# SetHeightColorRange

The SetHeightColorRange function allows you to set the height color range used in the 3D view. It returns a HeightColor3D structure containing the minimum and maximum height (dimension Z) of the color range.

If you are not using a SetHeightColorRange function, height color range is automatically computed based on the acquired detection zone for each point cloud. For old point clouds where this information was not stored, a predefined range is used instead.

Note: This function can use the Box3D orientation to determine the gradient direction using the Directional mode.

To use the SetHeightColorRange function:

1. Drag and drop the SetHeightColorRange function to the Spreadsheet.

2. In the property sheet that pops up, choose a Height color mode:

   - Directional Mode: Use a Box3D to define the height of the color range and direction. Double-click the Box3D parameter to open the interactive display. Adjust the ROI shape on the display. Alternatively, you can expand the Box3D settings and define the parameters manually.

     The Z range is relative to the Box3D, so the minimum value of the range is always 0 and the highest value is equal to the box SizeZ. The dimensions X and Y have no effect on the result.

     Note: You can use boxes produced by other 3D tools, such as ExtractBlob3D, to automatically adjust the color based on the computed box from one acquisition to the next.

   - Z Range Mode: Define the height color range with the Minimum Z and Maximum Z parameters.

3. Click OK to finalize the settings.

Input

Parameter | Description
--- | ---
PointCloud | Reference to a cell containing a point cloud. The default value is $A$0.
Height color mode | Selects the height color mode:
Directional | Applies the height color using a Box3D. The range is equal to SizeZ of the Box3D. The local +Z axis of the Box3D defines the gradient direction. The color bar in the 3D viewer shows "Z Box (mm)" and the range is from 0 to the height of the box.
Z Range | Applies the height color based on the Z range that you define with the Minimum Z and the Maximum Z parameters in the Property Sheet. The +Z world axis defines the gradient direction. The color bar shows "Z world (mm)" and the range is from Minimum Z to Maximum Z.
Note: You can only use one mode at a time. If you choose Directional mode, the Z Range mode properties are disabled. The same happens if you choose Z Range mode.
Fixture3D | Specifies the point cloud coordinate system in which the 3D fixture is defined. It is offset from the PointCloud origin in the following format with the following arguments: {X, Y, Z, Rotation, Tilt, TiltDirection}
X | Offset on the X-axis from the PointCloud origin.
Y | Offset on the Y-axis from the PointCloud origin.
Z | Offset on the Z-axis from the PointCloud origin.
Rotation | Specifies the in-plane rotation in degrees around the PointCloud Z-axis. The value range is -180 to 180. The tool normalizes external references with values outside the allowed range to the allowed range.
Tilt | Specifies the tilt angle in degrees from the PointCloud Z-axis after rotation. The value range is 0-180. External references with values outside the allowed range result in an error.
Tilt Direction | Specifies the direction of tilt in degrees from the rotated PointCloud X-axis of the tool, around the PointCloud Z-axis of the tool. The value range is -180 to 180. The tool normalizes external references with values outside the allowed range to the allowed range.
Note: The Fixture3D parameter is only available if you set External Fixture to 0. Note: This parameter is available only in Directional mode.
External Fixture | Specifies a reference to a Fixture3D structure defined in another cell. The function uses the referenced cell as the fixture of the function. Set to 0 (OFF) to use the internal fixture of the function instead. Note: This parameter is available only in Directional mode.
Box3D | Specifies the dimensions, offset and angle for the 3D rectangle of the function. It is offset from the PointCloud origin in the following format with the following arguments: {SizeX, SizeY, X, Y, Z, Rotation, Tilt, TiltDirection}
SizeX | The size of the box along the X-axis of the PointCloud. The value range is 0.001 to inf., and the default value is 100.
SizeY | The size of the box along the Y-axis of the PointCloud. The value range is 0.001 to inf., and the default value is 100.
SizeZ | The size of the box along the Z-axis of the PointCloud. The value range is 0.001 to inf., and the default value is 100.
X | Offset on the X-axis from the PointCloud origin. The value range is -inf. to inf., and the default value is 0.
Y | Offset on the Y-axis from the PointCloud origin. The value range is -inf. to inf., and the default value is 0.
Z | Offset on the Z-axis from the PointCloud origin. The value range is -inf. to inf., and the default value is 0.
Rotation | Specifies the in-plane rotation of the box (in degrees) about the PointCloud Z-axis of the tool. The value range is -360 to 360. External references with values outside the allowed range will be normalized to the allowed range.
Tilt | Specifies the tilt angle of the box (in degrees) from the PointCloud Z-axis of the tool. The value range is 0 - 180. External references with values outside the allowed range will result in an error.
Tilt Direction | Specifies the tilt direction of the box (in degrees) from the rotated PointCloud X-axis of the tool, about the PointCloud Z-axis of the tool. The value range is -360 to 360. External references with values outside the allowed range will be normalized to the allowed range.
Note: This parameter is available only if External Box is set to 0. Note: This parameter is available only in Directional mode.
External Box | Specifies a reference to a Box3D structure defined in another cell of the spreadsheet to be used for plotting. Set to 0 (OFF) to use the function's internal Box3D structure. Note: This parameter is available only in Directional mode.
Minimum Z | Specifies the minimum value of the height color range in Z Range mode. Note: This parameter is available only in Z Range mode.
Maximum Z | Specifies the maximum value of the height color range in Z Range mode. Note: This parameter is available only in Z Range mode.
Show | Selects the type of graphics to overlay on the image.
0 = hide all (default) | All graphics will be hidden, except when the cell containing the function is highlighted in the spreadsheet.
2 = input graphics only | The input data will be displayed at all times.

Output

The function returns different getters depending on the selected height color mode.

## Directional Mode Outputs

Returns | A HeightColor3D structure containing the minimum and maximum height (dimension Z) of the color range.
Results | When inserted into a cell, the following functions are automatically inserted into the spreadsheet.
| Start | End
HeightColor3D | GetHeightColorStart(HeightColor3D) | GetHeightColorEnd(HeightColor3D)

## Z Range Mode Outputs

Returns | A HeightColor3D structure containing the minimum and maximum height (dimension Z) of the color range.
Results | When inserted into a cell, the following functions are automatically inserted into the spreadsheet.
| MinZ | MaxZ
HeightColor3D | GetMinZ(HeightColor3D) | GetMaxZ(HeightColor3D)