Calculating distance measurements and statistics

See also

User Guide:

Calculating statistics on a point cloud or depth map Color and display settings for 3D data

Reference:

M3dimStat M3dmetAlloc M3dmetAllocResult M3dmetControl M3dmetDistance M3dmetGetResult M3dmetStat

Availability

Not available in MIL-Lite

Available in MIL

The 3D Metrology module can calculate distance measurements between two MIL objects, and compute a variety of statistics (such as, the minimum, maximum and average distances) on those distance measurements.

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 the Calculating statistics on a point cloud or depth map section of Chapter 32: 3D image processing.

Steps to calculate distance measurements and statistics

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

Optionally, allocate a statistics 3D metrology context, using M3dmetAlloc() with M_STATISTICS_CONTEXT.

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.
Allocate a statistics 3D metrology result buffer, using M3dmetAllocResult() with M_STATISTICS_RESULT.
Control the settings of the statistics 3D metrology context using M3dmetControl(). These settings determine which distance measurements and statistics to calculate.
Call M3dmetStat() to calculate the distance measurements and evaluate their statistics.
Retrieve results from the statistics 3D metrology result buffer using M3dmetGetResult().

Note that you can calculate distance measurements without evaluating statistics 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 the Applying LUTs subsection of the Color and display settings for 3D data section of Chapter 37: 3D Display and graphics.

How distances are calculated

Depending on the type of reference object that you pass, and the setting of the DistanceType parameter, M3dmetStat() or M3dmetDistance() can 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).

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.

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, set DistanceType to M_DISTANCE_TO_NEAREST_NEIGHBOR.

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, set DistanceType to M_DISTANCE_TO_MESH.

For maximum performance, you can specify not to complete calculations for points in the source which are determined to be more than a certain distance from the reference point cloud. For M3dmetDistance(), this is specified by the Param parameter. For M3dmetStat(), this is specified using the Condition, CondHigh and CondLow parameters, 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, set DistanceType to M_ABSOLUTE_DISTANCE_Z_TO_SURFACE or M_SIGNED_DISTANCE_Z_TO_SURFACE.

If a point does not map to a position in the depth map, it is assigned a distance of MIL_FLOAT_MAX and 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, set DistanceType to M_ABSOLUTE_DISTANCE_TO_SURFACE, M_SIGNED_DISTANCE_TO_SURFACE, or M_MANHATTAN_DISTANCE_TO_SURFACE (for a 3D box geometry only).

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_SURFACE unless it is specifically required for your application.
For a cylinder 3D geometry object, you can choose to measure distances from each point in the source 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, set DistanceType to M_DISTANCE_TO_CENTER_AXIS or M_DISTANCE_TO_CENTER_AXIS_SQUARED.
For a line 3D geometry object, distances are measured from each point in the source 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, set DistanceType to M_DISTANCE_TO_LINE or M_DISTANCE_TO_LINE_SQUARED.
For a plane 3D geometry object, you can choose to measure distances from each point in the source 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, set DistanceType to M_ABSOLUTE_DISTANCE_Z_TO_SURFACE or M_SIGNED_DISTANCE_Z_TO_SURFACE.
For a sphere 3D geometry object, you can choose to measure distances from each point in the source to the center of the sphere. To calculate these distances, set DistanceType to M_DISTANCE_TO_CENTER or M_DISTANCE_TO_CENTER_SQUARED.

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 respectively). 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) that bypasses this step and instead stores the square of the distance in the result buffer.