Calculating distance measurements and statistics

The 3D Metrology module can calculate distance measurements between a source and reference Aurora Imaging Library object, and compute a variety of statistics (such as, the minimum, maximum and average distances) on those distance measurements.

You can calculate distance measurements between two Aurora Imaging Library objects, using M3dmetDistanceEx or M3dmetDistance. You can also calculate distances and perform statistics, using M3dmetStat. Note that M3dmetDistanceEx uses a distance 3D metrology context and stores the result of the distance operation in a result buffer. M3dmetStat uses a statistics 3D metrology context and stores the result of the statistics operation in a result buffer. M3dmetDistance does not require a context or result buffer and returns the calculated distance directly.

Note: To calculate distances and statistics for a single point cloud or depth map (such as, the bounding box or the distances between the points), use the 3D image processing module (M3dimStat) instead. For more information, see Calculating statistics on a point cloud, depth map, or 3D geometry.

Steps to calculate distance measurements and statistics

The following steps provide a basic methodology for calculating distance measurements and statistics:

1. Optionally, allocate a statistics 3D metrology context, using M3dmetAlloc with M_STATISTICS_CONTEXT or, allocate a distance 3D metrology context with M_DISTANCE_CONTEXT.

   Note: Note that if you want to evaluate a single statistics calculation, you can call M3dmetStat with a predefined statistics 3D metrology context, without having to allocate a statistics 3D metrology context beforehand.

2. Allocate a statistics 3D metrology result buffer, using M3dmetAllocResult with M_STATISTICS_RESULT or, allocate a calculate 3D metrology result buffer with M_CALCULATE_RESULT.
3. Control the settings of the statistics or distance 3D metrology context using M3dmetControl. These settings determine which distance measurements and statistics to calculate.
4. Call M3dmetStat to calculate the distance measurements and evaluate their statistics, or call M3dmetDistanceEx to calculate the distance measurements without evaluating their statistics.
5. Retrieve results from the statistics or distance 3D metrology result buffer, using M3dmetGetResult.

Note that you can calculate distance measurements without evaluating statistics or allocating a 3D metrology context or result buffer using M3dmetDistance. This function creates a distance map which is useful, for example, to highlight defects using a LUT in a 2D or 3D display. For more information about showing point clouds in a 3D display using a LUT, see Applying LUTs. You must use M3dmetDistanceEx if you want to save the paired reference facets, pixels, and points (M_SAVE_PAIRED_REFERENCE_...).

How distances are calculated

Depending on the type of reference object that you pass, and the setting of the DistanceType parameter, M3dmetStat and M3dmetDistance can both calculate different distances for each point in the source. You must specify the distance type to be calculated, even if only one option is available (for example, when the reference is a point cloud without a mesh). To use M3dmetDistanceEx, allocate a distance 3D metrology context (M3dmetAlloc) and use M3dmetControl with M_PAIRING_TYPE, M_PAIRING_DISTANCE_METRIC, and M_DISTANCE_METRIC_OPERATOR to specify the distance to calculate. Alternatively, use M3dmetDistanceEx with a predefined distance 3D metrology context (M_DISTANCE_CONTEXT_...).

Note: When a depth map is passed as a source to these functions, it is typically internally converted to a point cloud. When referring to the source object in this section, the term point can refer to either a point in a point cloud, or the position in 3D space represented by a pixel of a depth map. This does not apply to the reference object; when passed as a reference, depth maps and point clouds are treated differently.

Only some combinations of reference object, M_PAIRING_TYPE, M_PAIRING_DISTANCE_METRIC, and M_DISTANCE_METRIC_OPERATOR are accepted when using M3dmetDistanceEx. The following table lists all of the possible combinations of these values:

M_PAIRING_TYPE	Reference object	M_PAIRING_DISTANCE_METRIC	M_DISTANCE_METRIC_OPERATOR
M_DISTANCE_TO_REFERENCE	3D point, 3D sphere, 3D cylinder, or 3D line geometry	M_EUCLIDEAN	M_ABSOLUTE or M_SQUARED
M_DISTANCE_TO_SURFACE	3D sphere geometry	M_EUCLIDEAN	M_ABSOLUTE or M_SIGNED
3D plane geometry	M_EUCLIDEAN	M_ABSOLUTE or M_SQUARED
3D plane geometry	M_DIRECTION_Z	M_ABSOLUTE or M_SIGNED
3D box geometry	M_EUCLIDEAN	M_ABSOLUTE or M_SIGNED
3D box geometry	M_MANHATTAN	M_ABSOLUTE
3D cylinder	M_EUCLIDEAN	M_ABSOLUTE or M_SIGNED
Meshed point cloud	M_EUCLIDEAN or M_DIRECTION_NORMAL	M_ABSOLUTE
M_DISTANCE_TO_NEIGHBOR	Point cloud	M_EUCLIDEAN or M_DIRECTION_NORMAL	M_ABSOLUTE
Depth map	M_DIRECTION_Z	M_ABSOLUTE or M_SIGNED

In the case that only one setting is available, and you specify an unavailable setting, it will be ignored and the appropriate setting will be used instead. When more than one setting is available, and an unavailable setting is specified, an error is generated.

Point cloud as a reference

When the reference is a point cloud without a mesh, distances are measured from each point in the source to the nearest point in the reference. To calculate these distances using M3dmetStat orM3dmetDistance, setDistanceType to M_DISTANCE_TO_NEAREST_NEIGHBOR. When using M3dmetDistanceEx, use M3dmetControl with M_PAIRING_TYPE set to M_DISTANCE_TO_NEIGHBOR for the same result. You can also find the nearest neighbor of the source points in the direction of their normals with M3dmetDistanceEx, using M3dmetControl withM_PAIRING_DISTANCE_METRIC set to M_DIRECTION_NORMAL. To compute the normal distance between the paired source and reference points, you must enable M_DISTANCE_NORMAL. The normal distance is defined as the dot product between the paired source point's normal and the reference point's normal.

When the reference is a meshed point cloud, you can choose to instead measure distances from each point in the source to the nearest position on the surface of the mesh. To calculate these distances using M3dmetStat orM3dmetDistance, setDistanceType to M_DISTANCE_TO_MESH. When using M3dmetDistanceEx, use M3dmetControl with M_PAIRING_TYPE set to M_DISTANCE_TO_SURFACE for the same result. You can also find the nearest position on the surface of the mesh to the source points in the direction of their normals with M3dmetDistanceEx, using M3dmetControl with M_PAIRING_DISTANCE_METRIC set to M_DIRECTION_NORMAL.

Note: For maximum performance, you can specify not to complete calculations for source points that are more than a certain distance from the reference point cloud. For M3dmetDistance, specify this distance using the Paramparameter. For M3dmetDistanceEx, specify this distance using M3dmetControl with M_PAIRING_DISTANCE_METRIC and M_PAIRING_DISTANCE_MAX. In the case that the reference object is a point cloud and M_PAIRING_TYPE is set to M_DISTANCE_TO_NEIGHBOR, use M_PAIRING_PERPENDICULAR_DISTANCE_MAX and M_PAIRING_PERPENDICULAR_DISTANCE_MAX_MODE. For M3dmetStat, specify this distance using the Condition, CondHighand CondLowparameters, which also determine whether a given distance is used when calculating statistics.

Depth map as a reference

When the reference is a fully corrected depth map, distances are measured from each point in the source to the position in the depth map that is directly above or below the source point along the Z-axis. To calculate these distances, using M3dmetStat orM3dmetDistance, setDistanceType toM_ABSOLUTE_DISTANCE_Z_TO_SURFACEor M_SIGNED_DISTANCE_Z_TO_SURFACE. For the same result when using M3dmetDistanceEx, use M3dmetControl with M_DISTANCE_METRIC_OPERATOR set to M_ABSOLUTE or M_SIGNED.

Note: If a point does not map to a position in the depth map, it is assigned a distance ofAIL_FLOAT_MAXand is ignored for statistics calculations.

3D geometry as a reference

When the reference is a 3D geometry object, you can choose to measure distances in several ways depending on the type of the 3D geometry:

• For all types of 3D geometry objects (except lines), you can choose to measure distances from each point to the nearest position on the surface of the 3D geometry. To calculate these distances using M3dmetStat orM3dmetDistance, setDistanceType to M_ABSOLUTE_DISTANCE_TO_SURFACE, M_SIGNED_DISTANCE_TO_SURFACE, or M_MANHATTAN_DISTANCE_TO_SURFACE(for a 3D box geometry only). For M3dmetDistanceEx, use M3dmetControl with M_PAIRING_TYPE set to M_DISTANCE_TO_SURFACE for the same result. To compute the normal distance between the paired source and reference points, you must enable M_DISTANCE_NORMAL.

  Note: The Manhattan distance is the combined distance in all 3 axes between two positions, as opposed to the length of the shortest path between the two positions. For example, the shortest distance from (0,0,0) to (1,1,1) is ~1.73, but the Manhattan distance is 3 (1 + 1 + 1). Typically, you should not use M_MANHATTAN_DISTANCE_TO_SURFACEunless it is specifically required for your application.

• For a cylinder 3D geometry object, you can choose to measure distances from each source point to the nearest position on the central axis of the cylinder. The central axis is extended infinitely, even if the cylinder is finite. To calculate these distances using M3dmetStat orM3dmetDistance, setDistanceType to M_DISTANCE_TO_CENTER_AXISor M_DISTANCE_TO_CENTER_AXIS_SQUARED. For M3dmetDistanceEx, useM3dmetControl with M_PAIRING_TYPE set to M_DISTANCE_TO_REFERENCE, and M3dmetControl with M_DISTANCE_METRIC_OPERATOR set to M_ABSOLUTE or M_SQUARED for the same result.
• For a line 3D geometry object, distances are measured from each source point to the nearest position on the line. Unlike the central axis of a cylinder, a finite line is not extended infinitely for this calculation. To calculate these distances using M3dmetStat orM3dmetDistance, setDistanceType toM_DISTANCE_TO_LINEor M_DISTANCE_TO_LINE_SQUARED. For M3dmetDistanceEx, use M3dmetControl with M_PAIRING_TYPE set to M_DISTANCE_TO_REFERENCE, and use M3dmetControl with M_DISTANCE_METRIC_OPERATOR set to M_ABSOLUTE or M_SQUARED for the same result.
• For a plane 3D geometry object, you can choose to measure distances from each source point to the position on the surface of the plane that is directly above or below the point along the Z-axis. To calculate these distances using M3dmetStat orM3dmetDistance, setDistanceType to M_ABSOLUTE_DISTANCE_Z_TO_SURFACEor M_SIGNED_DISTANCE_Z_TO_SURFACE. For M3dmetDistanceEx, use M3dmetControl with M_PAIRING_TYPE set to M_DISTANCE_TO_SURFACE, and use M3dmetControl with M_DISTANCE_METRIC_OPERATOR set to M_ABSOLUTE or M_SIGNED for the same result.
• For a sphere 3D geometry object, you can choose to measure distances from each source to the center of the sphere. To calculate these distances using M3dmetStat orM3dmetDistance, setDistanceType toM_DISTANCE_TO_CENTERor M_DISTANCE_TO_CENTER_SQUARED. For M3dmetDistanceEx, use M3dmetControl with M_PAIRING_TYPE set to M_DISTANCE_TO_REFERENCE, and use M3dmetControl with M_DISTANCE_METRIC_OPERATOR set to M_ABSOLUTE or M_SIGNED for the same result.

When calculating distances to the surface of a 3D geometry object, you can specify to have distances returned as either absolute or signed values (for example, using M_ABSOLUTE_DISTANCE_TO_SURFACE or M_SIGNED_DISTANCE_TO_SURFACE with M3dmetDistance, respectively; for M3dmetDistanceEx, useM3dmetControl withM_DISTANCE_METRIC_OPERATOR set to M_ABSOLUTE or M_SIGNED for the same result). When you specify to return signed values, the sign indicates whether the point is above or below the surface of the reference object.

Some types of distance calculations with 3D geometries (such as M_DISTANCE_TO_CENTER) include a square root operation to determine the distance for each point in the source. You can improve the performance of these types of distance calculations by specifying an alternate version (such as, M_DISTANCE_TO_CENTER_SQUARED; for M3dmetDistanceEx, useM3dmetControl withM_DISTANCE_METRIC_OPERATOR set to M_ABSOLUTE or M_SIGNED for the same result) that bypasses this step and instead stores the square of the distance in the result buffer.