# ExtractDistanceHistogram3D

The ExtractDistanceHistogram3D function is used to extract a 3D distance histogram. It provides functions to compute the distribution of distances from the points in a point cloud to:

- The center of the mass of the points in the configured Region of Interest (ROI).
- A specific point in space.
- A specific line.

The function returns a Histogram3D structure.

## ExtractDistanceHistogram3D Inputs

The ExtractDistanceHistogram3D function has the following syntax:

ExtractDistanceHistogram3D(PointCloud,Fixture3D,ExternalFixture, Region3D,ExternalRegion,Mode,Point3D,ExternalPoint,Plane3D,ExternalPlane,Line3D,ExternalLine,FixtureReference,BinSize,MinValue,MaxValue,Show)

See the table for a description of the available parameters.

Parameter | Description
PointCloud | Reference to a cell containing a point cloud. The default value is $A$0.
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.
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.
Region3D | Specifies the dimensions, offset and angle for 3D region of interest (ROI) of the function. It is offset from the Fixture3D origin in the following format with the following arguments: {SizeX, SizeY, SizeZ, X, Y, Z, Rotation, Tilt, TiltDirection}
SizeX | The size of the ROI along the Fixture3D X-axis.
SizeY | The size of the ROI along the Fixture3D Y-axis.
SizeZ | The size of the ROI along the Fixture3D Z-axis.
X | Offset on the X-axis from the Fixture3D origin.
Y | Offset on the Y-axis from the Fixture3D origin.
Z | Offset on the Z-axis from the Fixture3D origin.
Rotation | Specifies the in-plane rotation in degrees around the Fixture3D Z-axis of the tool. The value range is -360 to 360. The tool normalizes external references with values outside the allowed range to the allowed range.
Tilt | Specifies the tilt angle in degrees from the Fixture3D Z-axis of the tool 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 Fixture3D X-axis of the tool, around the Fixture3D Z-axis of the tool . The value range is -360 to 360. The tool normalizes external references with values outside the allowed range to the allowed range.
Note: This setting is only available if you set External Region to 0.
External Region | Specifies a reference to a 3D region defined in another cell. The function uses the referenced cell as the Region of Interest of the function. Set to 0 (OFF) to use the internal Box3D structure of the function as the ROI.
Mode | Specifies the mode of operation: 0 = Center of Mass: Calculates the center of mass of all points in the ROI. Then, it fills the histogram with absolute distances from the center of mass to each point in the point cloud. This is the default setting. 1 = Point: Fills the histogram with absolute distances from a specific point, provided by a caller to each point in the point cloud. 2 = Plane: Fills the histogram with signed distances from a specific plane, provided by a caller to each point in the point cloud. 3 = Line: Fills the histogram with absolute distances from a specific line, provided by a caller to each point in the point cloud.
Point3D | Specifies the offset of the 3D point to use. It is offset from the PointCloud (or Fixture3D, if Fixture Reference is enabled) origin in the following format with the following arguments: {X, Y, Z}
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.
Note: This parameter is available only if External Point is set to 0. Note: This parameter is only available if the Mode is set to Point, and External Point is not 0.
External Point | Specifies a reference to a Point3D structure defined in another cell to be used by the function. Set to 0 (OFF) to use the function's internal Point3D structure. Note: This parameter is only available if the Mode is set to Point.
Plane3D | Specifies the offset and the angle of the plane to use. It is offset from the PointCloud origin in the following format with the following arguments: {X, Y, Z, 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.
Tilt | Specifies the tilt angle (in degrees) from the PointCloud Z-axis. The value range is 0-180. External references with values outside the allowed range will result in an error.
Tilt Direction | Specifies the direction of tilt (in degrees) from the plane's rotated PointCloud X-axis, about the tool's PointCloud Z-axis. The value range is -360 - 360. External references with values outside the allowed range will be normalized to the allowed range.
Note: This parameter is available only if External Plane is set to 0. Note: This parameter is only available if the Mode is set to Plane, and External Plane is not 0.
External Plane | Specifies a reference to a Rectangle3D or Circle3D structure defined in another cell to be used by the function. Set to 0 (OFF) to use the function's internal Plane3D structure instead. Note: This parameter is only available if the Mode is set to Plane.
Line3D | Specifies the offsets of the 3D line structure to use. It is offset from the PointCloud origin in the following format with the following arguments: {X0, Y0, Z0, X1, Y1, Z1}
X0 | Offset of the 3D line's starting point on the X-axis from the PointCloud origin.
Y0 | Offset of the 3D line's starting point on the Y-axis from the PointCloud origin.
Z0 | Offset of the 3D line's starting point on the Z-axis from the PointCloud origin.
X1 | Offset of the 3D line's ending point on the X-axis from the PointCloud origin.
Y1 | Offset of the 3D line's ending point on the Y-axis from the PointCloud origin.
Z1 | Offset of the 3D line's ending point on the Z-axis from the PointCloud origin.
Note: This parameter is available only if External Line is set to 0. Note: This parameter is only available if the Mode is set to Line, and External Line is not 0.
External Line | Specifies a reference to the Line3D structure defined in another cell to be used by the function. Set to 0 (OFF) to use the function's internal Line3D structure instead. Note: This parameter is only available if the Mode is set to Line.
Fixture Reference | Specifies whether to fixture the reference plane. Consider the following when using this setting: If you define the reference plane relative to a point cloud part, it will be fixtured using the same fixture as the tool's Region of Interest. If the Plane3D structure used for the function is extracted with an Extract function (such as ExtractPlane3D), then the plane is already fixtured, and this parameter can be disabled. This parameter is enabled by default. Note: This parameter is only available if the Mode parameter is set to Point or Plane.
Bin Size | Specifies the size of the intervals in which the values are grouped.
Min. Value | Specifies the minimum value of distances to compute in the histogram. The value range is -inf. to the configured value of the Max. Value parameter, and the default value is -10000.
Max. Value | Specifies the maximum value of distances to compute in the histogram. The value range is from the configured value of the Min. Value parameter to inf., and the default value is 10000.
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 region of interest and the reference plane will be displayed at all times.
3 = input and chart | The region of interest, the reference plane and the histogram chart will be displayed at all times.

## ExtractDistanceHistogram3D Outputs

Returns | A Histogram3D data structure containing the direction histogram extracted from the point cloud, or #ERR if any of the input parameters are invalid.
Results | When initially inserted into a cell, the following functions are automatically inserted into the spreadsheet to create a result table.
| Thresh | Low Count | High Count | Mean | Std Dev
❒Histogram3D | GetThreshold(Histogram3D) | GetSumOfFrequencies(Histogram3D, -999999, Thresh) | GetSumOfFrequencies(Histogram3D, Thresh, 999999) | GetMean(Histogram3D) | GetStandardDeviation(Histogram3D)

## ExtractDistanceHistogram3D Vision Data Access functions

The following Histogram3D Vision Data Access functions are automatically inserted into the spreadsheet to create the result table:

Function | Description
GetSumOfFrequencies(Histogram3D, [Low], [High]) | Returns the number of 3D points within the specified threshold range. In the Low Count column, it returns the number of 3D points below the threshold (returned by the GetThreshold function). In the High Count column, it returns the number of 3D points above the threshold (returned by the GetThreshold function).
GetThreshold(Histogram3D) | Computes an optimum histogram threshold that does a binary segmentation of all the histogram data. That way, GetThreshold specifies a threshold level that maximizes similarity between the histogram function's 3D region of interest and all possible binary re-quantization.
GetMean(Histogram3D) | Returns the mean value of the 3D points by summing up the values for all points in the function's 3D region of interest and then dividing by the count of 3D points in the same range.
GetStandardDeviation(Histogram3D) | Returns the standard deviation of the 3D points within the function's 3D region of interest.