| Customize Help
| Save Settings

M3dmetDistance


Function Map
Syntax
Description
Parameters
- SrcContainerOrImageBufId
Table: For specifying the point cloud container or depth map image buffer
- RefMilObjectId
Table: For specifying the reference MIL object identifier
- DstImageBufId
- DistanceType
- Param
Table: For specifying the maximum distance to calculate
- ControlFlag
Parameter Associations
Table: For specifying the type of distance measurement for the specified reference object
Compilation information
Synopsis
Calculates the distance between a point cloud or depth map, and a point cloud, depth map, or 3D geometry object.
Syntax
void M3dmetDistance(
MIL_ID SrcContainerOrImageBufId, //in
MIL_ID RefMilObjectId, //in
MIL_ID DstImageBufId, //in
MIL_INT64 DistanceType, //in
MIL_DOUBLE Param, //in
MIL_INT64 ControlFlag //in
)
Description

This function calculates various distance measurements between a point cloud or depth map, and a point cloud, depth map, or 3D geometry.

This function is similar to M3dmetStat(), but does not require allocating any 3D metrology contexts or result buffers, and does not calculate any statistical metrics based on the distance measurements.

Note that this function reference has not been updated for a MIL system added during a MIL update. Refer to the MIL system's release note to see which MIL system’s documentation you should use in its place and any possible differences.
Parameters
This function is not supported on the selected boards.
This function reference has not been updated for the selected MIL system. To show the content of this page, choose a second MIL system; refer to the MIL system's release note to see which MIL system’s documentation to choose and any possible differences.
Parameters
SrcContainerOrImageBufId

Specifies the source point cloud container or depth map image buffer.

function map For specifying the point cloud container or depth map image buffer
Click to summarizeValue Description
Click to summarize Depth map image buffer identifier

Specifies the identifier of a depth map image buffer.

The image buffer must be a 1-band, 8-bit, 16-bit, or 32-bit unsigned buffer. It must contain a fully corrected depth map (that is, if you call McalInquire() with M_DEPTH_MAP, the function returns M_TRUE).

The image buffer must not have a region of interest (ROI) associated with it.

(summarize)
Click to summarize Point cloud container identifier

Specifies the identifier of a point cloud container.

The container must be 3D-processable. You can use MbufInquireContainer() with M_3D_PROCESSABLE to ensure that the container contains a 3D-processable point cloud.

(summarize)
RefMilObjectId

Specifies the reference object with respect to which distances will be measured.

function map For specifying the reference MIL object identifier
Click to summarizeValue Description
Click to summarize M_XY_PLANE

Specifies the XY (Z=0) plane.

This is equivalent to passing a 3D plane geometry object, and can therefore be used with the same DistanceType parameter settings.

(summarize)
Click to summarize 3D geometry object identifier

Specifies the identifier of a 3D geometry object allocated using M3dgeoAlloc() and defined using M3dgeoBox(), M3dgeoCylinder(), M3dgeoLine(), M3dgeoSphere(), or M3dgeoPlane().
Click to summarize Depth map imague buffer identifier

Specifies the identifier of a depth map image buffer.

The image buffer must be a 1-band, 8-bit, 16-bit, or 32-bit unsigned buffer. It must contain a fully corrected depth map (that is, if you call McalInquire() with M_DEPTH_MAP, the function returns M_TRUE).

The image buffer is allocated using MbufAlloc2d(), and must not have a region of interest (ROI) associated with it.

(summarize)
Click to summarize Point cloud container identifier

Specifies the identifier of a point cloud container.

The container must be 3D-processable. You can use MbufInquireContainer() with M_3D_PROCESSABLE to ensure that the container contains a 3D-processable point cloud.

(summarize)

See the Parameter associations section for possible values that can be specified.

DstImageBufId

Specifies the identifier of the buffer in which to store the calculated distances.

The buffer must be a 1-band, 32-bit floating-point image buffer. The destination image buffer must be the same size as the source buffer (or, if the source is a container, the same size as the range component). You can inquire the size of the source object using MbufInquire() (or, for a container, MbufInquireContainer() with M_COMPONENT_RANGE) with M_SIZE_X and M_SIZE_Y. These values can then be used to allocate an image buffer of the correct size.

The image buffer must not have a region of interest (ROI) associated with it.

Note that, if the source object is an image buffer, its X and Y (but not Z) calibration information will be copied into the destination image buffer. Otherwise, the destination image buffer will be uncalibrated.

DistanceType

Specifies the type of distance to calculate.

See the Parameter associations section for possible values that can be specified.

Param

Specifies an optional maximum distance for which to complete calculations when the reference MIL object is a point cloud container. Specify a value if DistanceType is set to M_DISTANCE_TO_MESH or M_DISTANCE_TO_NEAREST_NEIGHBOR; otherwise, set this parameter to M_DEFAULT. Points determined to be further from the reference than this value are assigned a distance of MIL_FLOAT_MAX in the destination, instead of having their exact distances calculated.

function map For specifying the maximum distance to calculate
Click to summarizeValue Description
Click to summarize M_DEFAULT

Same as M_INFINITE.
Click to summarize M_INFINITE

Specifies that there is no maximum distance for which to complete calculations. All distance measurements will be fully calculated.

(summarize)
Click to summarize Value > 0.0

Specifies an optional maximum distance. All distance measurements greater than this limit are returned as MIL_FLOAT_MAX.

(summarize)
ControlFlag

Reserved for future expansion and must be set to M_DEFAULT.

Parameter associations

The table below lists possible values for the RefMilObjectId and DistanceType parameters.

To specify the type of distance measurement, the DistanceType parameter can be set to one of the following values, depending on the type of reference object (RefMilObjectId) being measured against.

function map For specifying the type of distance measurement for the specified reference object
Click to summarizeRefMilObjectId Description
DistanceType
Click to summarize 3D box geometry object identfier

Specifies a 3D box geometry object, allocated using M3dgeoAlloc() and defined using M3dgeoBox().

(summarize)
Click to summarize M_ABSOLUTE_DISTANCE_TO_SURFACE

Specifies to calculate the absolute distance to the surface of the box.

The returned value is always positive.

(summarize)
Click to summarize M_MANHATTAN_DISTANCE_TO_SURFACE

Specifies to calculate the Manhattan distance to the surface of the box.

Distance measurements are positive for points outside the box, and negative for points inside the box.

(summarize)
Click to summarize M_SIGNED_DISTANCE_TO_SURFACE

Specifies to calculate the signed distance to the surface of the box.

Distance measurements are positive for points outside the box, and negative for points inside the box.

(summarize)
Click to summarize 3D cylinder geometry object identifier

Specifies a 3D cylinder geometry object, allocated using M3dgeoAlloc() and defined using M3dgeoCylinder().

(summarize)
Click to summarize M_ABSOLUTE_DISTANCE_TO_SURFACE

Specifies to calculate the absolute distance to the surface of the cylinder.

The returned value is always positive.

(summarize)
Click to summarize M_DISTANCE_TO_CENTER_AXIS

Specifies to calculate the signed distance to the cylinder's central axis.

The axis extends infinitely in both directions, even if the cylinder has a finite size.

(summarize)
Click to summarize M_DISTANCE_TO_CENTER_AXIS_SQUARED

Specifies to calculate the square of the distance to the cylinder's central axis.

The axis extends infinitely in both directions, even if the cylinder has a finite size.

(summarize)
Click to summarize M_SIGNED_DISTANCE_TO_SURFACE

Specifies to calculate the signed distance to the surface of the cylinder.

Distance measurements are positive for points outside the cylinder, and negative for points inside the cylinder.

(summarize)
Click to summarize 3D line geometry object identifier

Specifies a 3D line geometry object, allocated using M3dgeoAlloc() and defined using M3dgeoLine().

(summarize)
Click to summarize M_DISTANCE_TO_LINE

Specifies to calculate the distance to the line.

The length of the line is respected; if the line is finite, it is not extended infinitely when calculating distances.

(summarize)
Click to summarize M_DISTANCE_TO_LINE_SQUARED

Specifies to calculate the square of the distance to the line.

The length of the line is respected; if the line is finite, it is not extended infinitely when calculating distances.

(summarize)
Click to summarize 3D plane geometry object identifier

Specifies a 3D plane geometry object, allocated using M3dgeoAlloc() and defined using M3dgeoPlane().

When the reference object is a 3D plane geometry object, calculations are quicker if the source object is a depth map rather than a point cloud.

(summarize)
Click to summarize M_ABSOLUTE_DISTANCE_TO_SURFACE

Specifies to calculate the absolute distance, perpendicular to the plane.

The returned value is always positive.

(summarize)
Click to summarize M_ABSOLUTE_DISTANCE_Z_TO_SURFACE

Specifies to calculate the absolute distance along the Z-axis to the plane.

The returned value is always positive.

(summarize)
Click to summarize M_SIGNED_DISTANCE_TO_SURFACE

Specifies to calculate the signed distance, perpendicular to the plane.

Distance measurements are positive for points on the same side as the plane's normal, and negative on the other side.

(summarize)
Click to summarize M_SIGNED_DISTANCE_Z_TO_SURFACE

Specifies to calculate the signed distance along the Z-axis to the plane.

Distance measurements are positive if the point is above the plane and negative below.

(summarize)
Click to summarize 3D sphere geometry object identifier

Specifies a 3D sphere geometry object, allocated using M3dgeoAlloc() and defined using M3dgeoSphere().

(summarize)
Click to summarize M_ABSOLUTE_DISTANCE_TO_SURFACE

Specifies to calculate the absolute distance to the surface of the sphere.

The returned value is always positive.

(summarize)
Click to summarize M_DISTANCE_TO_CENTER

Specifies to calculate the signed distance to the center of the sphere.
Click to summarize M_DISTANCE_TO_CENTER_SQUARED

Specifies to calculate the square of the distance to the center of the sphere.
Click to summarize M_SIGNED_DISTANCE_TO_SURFACE

Specifies to calculate the signed distance to the surface of the sphere.

Distance measurements are positive for points outside the sphere, and negative for points inside the sphere.

(summarize)
Click to summarize Depth map image buffer identifier

Specifies the identifier of a depth map image buffer.

The image buffer must be a 1-band, 8-bit, 16-bit, or 32-bit unsigned buffer. It must contain a fully corrected depth map (that is, if you call McalInquire() with M_DEPTH_MAP, the function returns M_TRUE).

The image buffer must not have a region of interest (ROI) associated with it.

When the source and reference MIL objects are depth maps, calculations are completed more quickly. The speed is further increased if both depth maps use the same calibration context.

(summarize)
Click to summarize M_ABSOLUTE_DISTANCE_Z_TO_SURFACE

Specifies to calculate the absolute distance to the position in the depth map that is directly above or below the source along the Z-axis.

The returned value is always positive.

If a point would be projected outside of the depth map, MIL_FLOAT_MAX is returned.

(summarize)
Click to summarize M_SIGNED_DISTANCE_Z_TO_SURFACE

Specifies to calculate the signed distance using the Z-coordinate of the corresponding pixel of the reference depth map. That is, the distance is calculated along the Z-axis.

Distance measurements are positive for points above the depth map, and negative for points below the depth map.

If a point would be projected outside of the depth map, MIL_FLOAT_MAX is returned.

(summarize)
Click to summarize Point cloud container identifier

Specifies a point cloud container, allocated with MbufAllocContainer() with M_PROC.

The function runs much slower when the reference MIL object is a point cloud container. If speed is an issue, you can specify a maximum for calculating distance measurements using the Param parameter. Any distance measurements greater than the maximum value are returned as MIL_FLOAT_MAX.

You can also project the reference point cloud into a fully corrected depth map first (using M3dimProject()), at the cost of precision.

(summarize)
Click to summarize M_DISTANCE_TO_MESH

Specifies to calculate the shortest distance to the reference object's mesh.

This calculation requires that the reference object have a mesh component.

(summarize)
Click to summarize M_DISTANCE_TO_NEAREST_NEIGHBOR

Specifies to calculate the distance to the nearest point in the reference point cloud.
Compilation information
Header Include mil.h.
Library Use mil.lib; mil3dmet.lib.
DLL Requires mil.dll; mil3dmet.dll.
UNSIGNED NONE PROC TRUE XY PLANE BOX CYLINDER LINE PLANE SPHERE UNSIGNED TRUE NONE PROC TRUE FLOAT NONE FLOAT NONE DEFAULT INFINITE BOX ABSOLUTE DISTANCE TO SURFACE MANHATTAN DISTANCE TO SURFACE SIGNED DISTANCE TO SURFACE CYLINDER ABSOLUTE DISTANCE TO SURFACE DISTANCE TO CENTER AXIS DISTANCE TO CENTER AXIS SQUARED SIGNED DISTANCE TO SURFACE LINE DISTANCE TO LINE DISTANCE TO LINE SQUARED PLANE ABSOLUTE DISTANCE TO SURFACE ABSOLUTE DISTANCE Z TO SURFACE SIGNED DISTANCE TO SURFACE SIGNED DISTANCE Z TO SURFACE SPHERE ABSOLUTE DISTANCE TO SURFACE DISTANCE TO CENTER DISTANCE TO CENTER SQUARED SIGNED DISTANCE TO SURFACE UNSIGNED NONE ABSOLUTE DISTANCE Z TO SURFACE SIGNED DISTANCE Z TO SURFACE DISTANCE TO MESH DISTANCE TO NEAREST NEIGHBOR