M3dmetStat

See also

User Guide:

Calculating distance measurements and statistics Calculating statistics on a point cloud or depth map

Reference:

M3dgeoAlloc M3dgeoBox M3dgeoCylinder M3dgeoInquire M3dgeoLine M3dgeoPlane M3dgeoSphere M3dimProject M3dmetAlloc M3dmetAllocResult M3dmetControl MbufAlloc2d MbufAllocContainer MbufInquire MbufInquireContainer McalInquire

Availability

Not available in MIL-Lite

Available in MIL

Available on Windows

Available on Linux

Not supported on:

Not supported on Matrox Indio (Update 53 or Update 68) (w)

Not supported on Matrox Concord PoE with ToE (Update 82) (z)

Fully supported on:

Fully supported on Host system (a)

Fully supported on Matrox GigE Vision driver (MIL 10, Update 25, Update 54, or Update 85)* (c)

Fully supported on Matrox Morphis (g)

Fully supported on Matrox Morphis QxT (h)

Fully supported on Matrox Orion HD (i)

Fully supported on Matrox Radient eCL (j)

Fully supported on Matrox Radient eV-CXP (MIL 10 or Update 29)* (k)

Fully supported on Matrox Solios eA/XA (l)

Fully supported on Matrox Solios ecl/xcl/ev-cl (m)

Fully supported on Matrox USB3 Vision driver (Update 19) (o)

Fully supported on Matrox RadientPro-CL (Update 7) (p)

Fully supported on Matrox Radient eV-CL (Update 27 or 74) (r)

Fully supported on Matrox Iris GTR (Update 28 or Update 68) (t)

Fully supported on Matrox Clarity UHD (Update 36 or 76) (u)

Fully supported on Matrox GenTL driver (Update 34) (v)

Fully supported on Matrox Rapixo CXP (Update 75 or Update 84) (y)

Fully supported on Matrox Rapixo CL Pro (Update 96) (aa)

* Refer to the MIL system-specific information
in the MIL Reference for the minimum update required.

For any information regarding a MIL system added during a MIL Update, see the MIL system’s release note

Available on Non-Matrox computer

Available on Matrox 4Sight-X

Available on Matrox 4Sight GP/GPm

Available on Matrox Supersight

Function map

Examples

3dplanarity.cpp
3dplanefit.cpp
blisterpackinspection.cpp
bottlecapinspection.cpp
caninspection.cpp
cookiedetection.cpp
simple3dbinpicking.cpp
simple3dstitching.cpp
sphereinspection.cpp

M3dmetSave

M3dmetStream

Synopsis

Compute a variety of statistics on the distances between a point cloud or depth map, and a point cloud, depth map, or 3D geometry.

Syntax

void M3dmetStat(

MIL_ID StatContext3dmetId,	//in
MIL_ID SrcContainerOrImageBufId,	//in
MIL_ID RefMilObjectId,	//in
MIL_ID StatResult3dmetId,	//in
MIL_INT64 DistanceType,	//in
MIL_INT64 Condition,	//in
MIL_DOUBLE CondLow,	//in
MIL_DOUBLE CondHigh,	//in
MIL_INT64 ControlFlag	//in

)

Description

This function calculates a variety of statistics on the distance measurements collected between a source and reference MIL object.

The specified statistics 3D metrology context establishes which statistics to compute, and the DistanceType and Condition parameters establish the type of distance measurements to use in computing the statistics. Note that you can use a predefined context to calculate a single statistic. In this case, the statistic is calculated using its default settings.

You can use this function to, for example, calculate the mean distance between all points in a point cloud and the center of a 3D sphere geometry object.

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

StatContext3dmetId

Specifies a previously allocated statistics 3D metrology context (used to evaluate multiple statistical calculations), or a predefined statistics 3D metrology context (used to evaluate a single statistical calculation).

For specifying the statistics 3D metrology context, or specific statistic to calculate
Value	Description
M_STAT_CONTEXT_MAX	Specifies a predefined statistics 3D metrology context with all the control types (M3dmetControl()) in the context set to their default, except for M_STAT_MAX which is set to M_ENABLE. Use this predefined context to calculate the maximum distance between the point cloud or depth map, and the specified reference object. (summarize) Specifies a predefined statistics 3D metrology context with all the control types (M3dmetControl()) in the context set to their default, except for M_STAT_MAX which is set to M_ENABLE. (more details...)
M_STAT_CONTEXT_MAX_ABS	Specifies a predefined statistics 3D metrology context with all the control types (M3dmetControl()) in the context set to their default, except for M_STAT_MAX_ABS which is set to M_ENABLE. Use this predefined context to calculate the maximum absolute distance between the point cloud or depth map, and the specified reference object. (summarize) Specifies a predefined statistics 3D metrology context with all the control types (M3dmetControl()) in the context set to their default, except for M_STAT_MAX_ABS which is set to M_ENABLE. (more details...)
M_STAT_CONTEXT_MEAN	Specifies a predefined statistics 3D metrology context with all the control types (M3dmetControl()) in the context set to their default, except for M_STAT_MEAN which is set to M_ENABLE. Use this predefined context to calculate the average distance between the point cloud or depth map, and the specified reference object. (summarize) Specifies a predefined statistics 3D metrology context with all the control types (M3dmetControl()) in the context set to their default, except for M_STAT_MEAN which is set to M_ENABLE. (more details...)
M_STAT_CONTEXT_MIN	Specifies a predefined statistics 3D metrology context with all the control types (M3dmetControl()) in the context set to their default, except for M_STAT_MIN which is set to M_ENABLE. Use this predefined context to calculate the minimum distance between the point cloud or depth map, and the specified reference object. (summarize) Specifies a predefined statistics 3D metrology context with all the control types (M3dmetControl()) in the context set to their default, except for M_STAT_MIN which is set to M_ENABLE. (more details...)
M_STAT_CONTEXT_MIN_ABS	Specifies a predefined statistics 3D metrology context with all the control types (M3dmetControl()) in the context set to their default, except for M_STAT_MIN_ABS which is set to M_ENABLE. Use this predefined context to calculate the minimum absolute distance between the point cloud or depth map, and the specified reference object. (summarize) Specifies a predefined statistics 3D metrology context with all the control types (M3dmetControl()) in the context set to their default, except for M_STAT_MIN_ABS which is set to M_ENABLE. (more details...)
M_STAT_CONTEXT_NUMBER	Specifies a predefined statistics 3D metrology context with all the control types (M3dmetControl()) in the context set to their default, except for M_STAT_NUMBER which is set to M_ENABLE. Use this predefined context to calculate the number of points that meet the condition specified using the Condition, CondLow and CondHigh parameters. (summarize) Specifies a predefined statistics 3D metrology context with all the control types (M3dmetControl()) in the context set to their default, except for M_STAT_NUMBER which is set to M_ENABLE. (more details...)
M_STAT_CONTEXT_RMS	Specifies a predefined statistics 3D metrology context with all the control types (M3dmetControl()) in the context set to their default, except for M_STAT_RMS which is set to M_ENABLE. Use this predefined context to calculate the root-mean-square (RMS) error of the point cloud or depth map, and the specified reference object. (summarize) Specifies a predefined statistics 3D metrology context with all the control types (M3dmetControl()) in the context set to their default, except for M_STAT_RMS which is set to M_ENABLE. (more details...)
M_STAT_CONTEXT_STANDARD_DEVIATION	Specifies a predefined statistics 3D metrology context with all the control types (M3dmetControl()) in the context set to their default, except for M_STAT_STANDARD_DEVIATION which is set to M_ENABLE. Use this predefined context to calculate the standard deviation of all the distances calculated between the point cloud or depth map, and the specified reference object. (summarize) Specifies a predefined statistics 3D metrology context with all the control types (M3dmetControl()) in the context set to their default, except for M_STAT_STANDARD_DEVIATION which is set to M_ENABLE. (more details...)
M_STAT_CONTEXT_SUM	Specifies a predefined statistics 3D metrology context with all the control types (M3dmetControl()) in the context set to their default, except for M_STAT_SUM which is set to M_ENABLE. Use this predefined context to calculate the sum of all the distances calculated between the point cloud or depth map, and the specified reference object. (summarize) Specifies a predefined statistics 3D metrology context with all the control types (M3dmetControl()) in the context set to their default, except for M_STAT_SUM which is set to M_ENABLE. (more details...)
M_STAT_CONTEXT_SUM_ABS	Specifies a predefined statistics 3D metrology context with all the control types (M3dmetControl()) in the context set to their default, except for M_STAT_SUM_ABS which is set to M_ENABLE. Use this predefined context to calculate the sum of all the absolute distances calculated between the point cloud or depth map, and the specified reference object. (summarize) Specifies a predefined statistics 3D metrology context with all the control types (M3dmetControl()) in the context set to their default, except for M_STAT_SUM_ABS which is set to M_ENABLE. (more details...)
M_STAT_CONTEXT_SUM_OF_SQUARES	Specifies a predefined statistics 3D metrology context with all the control types (M3dmetControl()) in the context set to their default, except for M_STAT_SUM_OF_SQUARES which is set to M_ENABLE. Use this predefined context to calculate the sum of squared distances between the point cloud or depth map, and the specified reference object. (summarize) Specifies a predefined statistics 3D metrology context with all the control types (M3dmetControl()) in the context set to their default, except for M_STAT_SUM_OF_SQUARES which is set to M_ENABLE. (more details...)
MIL statistics 3D metrology context identifier	Specifies a statistics 3D metrology context identifier, previously allocated using M3dmetAlloc() with M_STATISTICS_CONTEXT. You can specify which statistics calculations are evaluated using M3dmetControl(). (summarize) Specifies a statistics 3D metrology context identifier, previously allocated using M3dmetAlloc() with M_STATISTICS_CONTEXT. (more details...)

SrcContainerOrImageBufId

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

For specifying the point cloud container or depth map image buffer
Value	Description
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 can have region of interest (ROI) in raster format; only the values inside the ROI will be used in the statistics calculations. (summarize) Specifies the identifier of a depth map image buffer. (more details...)
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) Specifies the identifier of a point cloud container. (more details...)

RefMilObjectId

Specifies the identifier of the reference MIL object, with respect to which distances will be measured.

You can set the RefMilObjectId parameter to one of the following values:

For specifying the container, depth map or 3D geometry object
Value	Description
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) Specifies the XY (Z=0) plane. (more details...)
3D geometry object identifier	Specifies the identifier of a 3D geometry object to use as the reference MIL object. The geometry object must have been previously allocated on the required system using M3dgeoAlloc() and must have been successfully defined. Supported 3D geometries include box, cylinder, line, plane, and sphere. (summarize) Specifies the identifier of a 3D geometry object to use as the reference MIL object. (more details...)
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 is allocated using MbufAlloc2d(), and must not have a region of interest (ROI) associated with it. (summarize) Specifies the identifier of a depth map image buffer. (more details...)
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) Specifies the identifier of a point cloud container. (more details...)

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

StatResult3dmetId

Specifies the identifier of the statistics 3D metrology result buffer in which to store the results. The result buffer must have been allocated using M3dmetAllocResult() with M_STATISTICS_RESULT.

DistanceType

Specifies the type of distance to calculate.

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

Condition

Specifies the condition for which distance measurements will be used in statistics calculations.

For specifying the condition
Value	Description
M_ALL	Specifies to use all distance measurements.
M_GREATER	Specifies to use all distance measurements greater than CondLow.
M_GREATER_OR_EQUAL	Specifies to use all distance measurements greater than or equal to CondLow.
M_IN_RANGE	Specifies to use all distance measurements between CondLow and CondHigh (inclusive).
M_LESS	Specifies to use all distance measurements less than CondLow.
M_LESS_OR_EQUAL	Specifies to use all distance measurements less than or equal to CondLow.

CondLow

Specifies the lower limit of the selected condition.

For the lower limit of the selected condition
Value	Description
M_NULL	Specifies that this parameter is not applicable.
Value	Specifies the lower limit of the condition.

CondHigh

Specifies the upper limit of the selected condition.

For the upper limit of the selected condition
Value	Description
M_NULL	Specifies that this parameter is not applicable.
Value	Specifies the upper limit of the condition.

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.

For specifying the type of distance calculation for the specified reference object

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.

For specifying the type of distance calculation for the specified reference object
RefMilObjectId		Description
	DistanceType	Description
3D box geometry object identfier		Specifies a 3D box geometry object, allocated using M3dgeoAlloc() and defined using M3dgeoBox(). (summarize) Specifies a 3D box geometry object, allocated using M3dgeoAlloc() and defined using M3dgeoBox(). (more details...)
	M_ABSOLUTE_DISTANCE_TO_SURFACE	Specifies to calculate the absolute distance to the surface of the box. The returned value is always positive. (summarize) Specifies to calculate the absolute distance to the surface of the box. (more details...)
	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) Specifies to calculate the Manhattan distance to the surface of the box. (more details...)
	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) Specifies to calculate the signed distance to the surface of the box. (more details...)
3D cylinder geometry object identifier		Specifies a 3D cylinder geometry object, allocated using M3dgeoAlloc() and defined using M3dgeoCylinder(). (summarize) Specifies a 3D cylinder geometry object, allocated using M3dgeoAlloc() and defined using M3dgeoCylinder(). (more details...)
	M_ABSOLUTE_DISTANCE_TO_SURFACE	Specifies to calculate the absolute distance to the surface of the cylinder. The returned value is always positive. (summarize) Specifies to calculate the absolute distance to the surface of the cylinder. (more details...)
	M_DISTANCE_TO_CENTER_AXIS	Specifies to calculate the distance to the cylinder's central axis. The axis extends infinitely in both directions, even if the cylinder has a finite size. (summarize) Specifies to calculate the distance to the cylinder's central axis. (more details...)
	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) Specifies to calculate the square of the distance to the cylinder's central axis. (more details...)
	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) Specifies to calculate the signed distance to the surface of the cylinder. (more details...)
3D line geometry object identifier		Specifies a 3D line geometry object, allocated using M3dgeoAlloc() and defined using M3dgeoLine(). (summarize) Specifies a 3D line geometry object, allocated using M3dgeoAlloc() and defined using M3dgeoLine(). (more details...)
	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) Specifies to calculate the distance to the line. (more details...)
	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) Specifies to calculate the square of the distance to the line. (more details...)
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) Specifies a 3D plane geometry object, allocated using M3dgeoAlloc() and defined using M3dgeoPlane(). (more details...)
	M_ABSOLUTE_DISTANCE_TO_SURFACE	Specifies to calculate the absolute distance, perpendicular to the plane. The returned value is always positive. (summarize) Specifies to calculate the absolute distance, perpendicular to the plane. (more details...)
	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) Specifies to calculate the absolute distance along the Z-axis to the plane. (more details...)
	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) Specifies to calculate the signed distance, perpendicular to the plane. (more details...)
	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) Specifies to calculate the signed distance along the Z-axis to the plane. (more details...)
3D sphere geometry object identifier		Specifies a 3D sphere geometry object, allocated using M3dgeoAlloc() and defined using M3dgeoSphere(). (summarize) Specifies a 3D sphere geometry object, allocated using M3dgeoAlloc() and defined using M3dgeoSphere(). (more details...)
	M_ABSOLUTE_DISTANCE_TO_SURFACE	Specifies to calculate the absolute distance to the surface of the sphere. The returned value is always positive. (summarize) Specifies to calculate the absolute distance to the surface of the sphere. (more details...)
	M_DISTANCE_TO_CENTER	Specifies to calculate the signed distance to the center of the sphere.
	M_DISTANCE_TO_CENTER_SQUARED	Specifies to calculate the square of the distance to the center of the sphere.
	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) Specifies to calculate the signed distance to the surface of the sphere. (more details...)
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) Specifies the identifier of a depth map image buffer. (more details...)
	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, the point is not used in statistics calculations. (summarize) 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. (more details...)
	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, the point is not used in statistics calculations. (summarize) Specifies to calculate the signed distance using the Z-coordinate of the corresponding pixel of the reference depth map. (more details...)
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 range for calculating distance measurements using the Condition, CondHigh and CondLow parameters. Any distance measurements outside the specified range are not used in statistics calculations. You can also project the reference point cloud into a fully corrected depth map first (using M3dimProject()), at the cost of precision. (summarize) Specifies a point cloud container, allocated with MbufAllocContainer() with M_PROC. (more details...)
	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) Specifies to calculate the shortest distance to the reference object's mesh. (more details...)
	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.