# ExtractDirectionHistogram3D

The ExtractDirectionHistogram3D function is used to extract a 3D direction histogram. It provides functions to compute the distribution of directions in a 3D space, between the surface normals on the point cloud and a reference plane. The function returns a Histogram3D structure.

Inputs

The ExtractDirectionHistogram3D function has the following syntax:

ExtractDirectionHistogram3D(PointCloud,Fixture3D,ExternalFixture,Region3D,ExternalRegion,Plane3D,ExternalPlane,FixtureReference,BinSize,FeatureSize,MinTiltAngle,MaxTiltAngle,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.
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.
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.
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.
Bin Size | Specifies the size of the intervals in which the values are grouped. The value range is 1 to 180., and the default value is 1.
Feature Size | Specifies the sampling quality of point cloud points and patches used for computing surface normals. The quality has three levels: 0 = Large 1 = Medium (Default) 2 = Small Tip: Lower values (Large and Medium) increase vision tool performance, but result in less accurate normal estimations and noise data sensitivity. The Small value results in more accurate normal estimations and better noise data sensitivity, at the cost of performance.
Min. Tilt Angle | Specifies the minimum tilt angle. The value range is 0 to the configured value of the Max. Tilt Angle parameter, and the default value is 0.
Max. Tilt Angle | Specifies the maximum tilt angle. The value range is from the configured value of the Min. Tilt Angle parameter to 90, and the default value is 90.
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.

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)

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.