# FindPatMax3D

The FindPatMax3D function is used to find objects in the point cloud based on a trained PatMax3D pattern configured with the TrainPatMax3D function. The function returns a Patterns3D structure.

You can find an example on how to use FindPatMax3D here.

Inputs

The FindPatMax3D function has the following syntax:

FindPatMax3D(PointCloud, Fixture3D, ExternalFixture, Region3D, ExternalRegion, ExcludeBasePlane, Plane3D, ExternalPlane, Offset, Pattern, NumberToFind, AcceptThreshold, MaxInPlaneRotationAngle, 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.
Exclude Base Plane | When enabled, the function adds a separate planar region of interest (ROI), so that the surface plane can be excluded when training and/or finding a 3D pattern, improving the tool's performance. This setting is enabled by default, and Cognex recommends keeping it enabled if the pattern to train/find is a particular object.
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 available only if Exclude Base Plane is True and External Plane is 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 available only if Exclude Base Plane is True.
Offset | Specifies the signed distance to the offset base plane. The value range is -inf. to inf., and the default value is 1.
Model3D | Specifies a reference to a trained Model3D structure trained with the TrainPatMax3D function in another cell.
Num to Find | Specifies the number of pattern instances to find. The value range is 1 to inf., and the default value is 1.
Accept Threshold | Specifies the minimum percentage score that a result must have to be considered a found pattern. The value range is 0 to 100, and the default value is 50.
Max In-Plane Rotation Angle | Specifies the maximum in-plane rotation angle that a result can have to be considered a found pattern. The value range is 0 to 180 and the default value is 180.
Max Tilt Angle | Specifies the maximum tilt rotation angle that a result can have to be considered a found pattern. The value range is 0 to 180 and the default value is 90.
Sort Key | Specifies the logic by which the found objects are sorted. The available values are the following: None: No sorting logic will be applied. Use this setting if you simply want a count of the objects, or want to examine them without the need to order them. Score: Sort the objects by their score. This is the default setting. Pose Rotation In-Plane Rotation Angle Norm: Sort the objects by their pose rotation's norm in-plane rotation. Pose Rotation In-Plane Rotation Angle Abs: Sort the objects by their pose rotation's absolute in-plane rotation. Pose Rotation Tilt Direction Norm: Sort the objects by their pose rotation's norm tilt direction. Pose Rotation Tilt Direction Abs: Sort the objects by their pose rotation's absolute tilt direction. Pose Rotation Tilt Angle: Sort the objects by their pose rotation's tilt angle. Pose Translation X: Sort the objects by their pose translation's X-component. Pose Translation Y: Sort the objects by their pose translation's Y-component. Pose Translation Z: Sort the objects by their pose translation's Z-component. Pose Translation R: Sort the objects by their pose translation's Euclidean distance. Pose Translation Spoke Angle Norm: Sort the objects by their pose translation's normalized spoke angle. Pose Translation Spoke Angle Abs: Sort the objects by their pose translation's absolute spoke angle. Pose Translation Spoke Radius: Sort the objects by their pose translation's spoke radius. Pose Translation X then Y then Z: Sort the objects by their pose translation's Grid X then Y, and then Z. Pose Translation Y then X then Z: Sort the objects by their pose translation's Grid Y then X, and then Z.
Sort Order | Specifies whether to sort the results in ascending or descending order. Note: This parameter is disabled if Sort Key is set to None.
Sort Tolerance | Specifies a threshold to determine if 2 or more results are tied. If they are tied, they can be sorted by a subsequent sort. Only takes effect when multiple sorting rules are applied (such as grid sorting or appending a sort tool). Note: This parameter is disabled if Sort Key is set to None.
Sort Reference | Specifies the origin of the coordinate space in which the positional and rotational values are defined. The available values are the following: Camera: The coordinate space is based off the system in which the point cloud's points are defined. Region: The coordinate space is based off the coordinate system of the working region used in the job. Note: This parameter is disabled if: The Sort Key is set to None or Score. An External Region is configured.
Show | Selects the type of graphics to overlay on the image.
0 = hide all (default) | All graphics are hidden, except when the cell containing the function is highlighted in the spreadsheet.
1 = result graphics only | The result graphics of the function are displayed at all times.
2 = input and result graphics | The region of interest, the input data and the results are displayed at all times.

Outputs

Returns | A Patterns3D data structure containing the found patterns, 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.
| Num Found | Index | Score | Fixture | X | Y | Z | Rotation | Tilt | Tilt Direction
❒Patterns3D | GetNFound(FindPatMax3D) | 0 | GetScore(Patterns3D,0) | GetFixture(Patterns3D,0) | GetX(Fixture3D) | GetY(Fixture3D) | GetZ(Fixture3D) | GetRotation(Fixture3D) | GetTilt(Fixture3D) | GetTiltDirection(Fixture3D)
|  | 1 | GetScore(Patterns3D,1) | GetFixture(Patterns3D,1) | GetX(Fixture3D) | GetY(Fixture3D) | GetZ(Fixture3D) | GetRotation(Fixture3D) | GetTilt(Fixture3D) | GetTiltDirection(Fixture3D)
|  | ... | ... | ... | ... | ... | ... | ... | ... | ...
|  | N-1 | GetScore(Patterns3D,N-1) | GetFixture(Patterns3D,N-1) | GetX(Fixture3D) | GetY(Fixture3D) | GetZ(Fixture3D) | GetRotation(Fixture3D) | GetTilt(Fixture3D) | GetTiltDirection(Fixture3D)
N = min(10, NumToFind)

Vision Data Access functions

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

Function | Description
GetFixture(Patterns3D, index) | Returns the Fixture3D structure of the found pattern's fixture.
GetNFound(Patterns3D, index) | Returns the number of found patterns.
GetRotation(Fixture3D) | Returns the rotation of the Z-axis in degrees, also known as the in-plane rotation.
GetScore(Patterns3D, index) | Returns the score of the found pattern specified with the index, as a value between 0 – 100.
GetTilt(Fixture3D) | Returns the tilt angle of the Fixture3D structure in degrees on the Z-axis.
GetTiltDirection(Fixture3D) | Returns the tilt direction angle of the specified Fixture3D structure in degrees. The angle is measured in the X-Y plane of the original reference coordinate system, and specifies the direction for the projection of the tilted Z-axis onto that plane.
GetX(Fixture3D, index) | Returns the X-axis coordinate of the pattern fixture's center point.
GetY(Fixture3D, index) | Returns the Y-axis coordinate of the pattern fixture's center point.
GetZ(Fixture3D, index) | Returns the Z-axis coordinate of the pattern fixture's center point.