M3dmetControl

See also

User Guide:

Calculating distance measurements and statistics Performing 3D fitting

Reference:

M3dgeoAlloc M3dmetAlloc M3dmetCopy M3dmetFit M3dmetGetResult M3dmetInquire M3dmetStat

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

Function Map

Parameter Associations

Table:	To control a statistics 3D metrology context
Table:	To control a fit 3D metrology context

Type-specific versions of the function when using a C compiler under 64-bit

Compilation information

Synopsis

Control a setting for a 3D metrology context.

Syntax

void M3dmetControl(

MIL_ID Context3dmetId,	//in
MIL_INT64 ControlType,	//in
MIL_DOUBLE ControlValue	//in

)

Description

This function allows you to control a setting of a 3D metrology context. These settings control the execution of M3dmetFit() and M3dmetStat(). You can typically inquire these settings using M3dmetInquire().

Note that when using a C compiler (not a C++ or other compiler) in 64-bit mode, M3dmetControl() internally calls the MIL_DOUBLE version of this function (M3dmetControlDouble()). If you need to pass integer values, call the MIL_INT64 version of this function (M3dmetControlInt64()).

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

Context3dmetId

Specifies the identifier of the fit 3D metrology context or statistics 3D metrology context to control. The 3D metrology context must have been previously allocated on the required system using M3dmetAlloc().

ControlType

Specifies the setting to control.

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

ControlValue

Specifies the value needed for the control.

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

Parameter associations

The tables below list possible values for the ControlType and ControlValue parameters.

To control a statistics 3D metrology context
To control a fit 3D metrology context

The following ControlType and ControlValue parameter settings can be specified for statistics 3D metrology contexts, and control which statistics M3dmetStat() calculates.

To control a statistics 3D metrology context
ControlType		Description
	ControlValue	Description
M_STAT_MAX		Sets whether to calculate the maximum distance between the point cloud or depth map, and the specified reference object. INQ (summarize) Sets whether to calculate the maximum distance between the point cloud or depth map, and the specified reference object. INQ (more details...)
	M_DEFAULT	Same as M_DISABLE.
	M_DISABLE	Specifies not to calculate the maximum distance.
	M_ENABLE	Specifies to calculate the maximum distance.
M_STAT_MAX_ABS		Sets whether to calculate the maximum absolute distance between the point cloud or depth map, and the specified reference object. INQ (summarize) Sets whether to calculate the maximum absolute distance between the point cloud or depth map, and the specified reference object. INQ (more details...)
	M_DEFAULT	Same as M_DISABLE.
	M_DISABLE	Specifies not to calculate the maximum absolute distance.
	M_ENABLE	Specifies to calculate the maximum absolute distance.
M_STAT_MEAN		Sets whether to calculate the average distance between the point cloud or depth map, and the specified reference object. INQ (summarize) Sets whether to calculate the average distance between the point cloud or depth map, and the specified reference object. INQ (more details...)
	M_DEFAULT	Same as M_DISABLE.
	M_DISABLE	Specifies not to calculate the average distance.
	M_ENABLE	Specifies to calculate the average distance.
M_STAT_MIN		Sets whether to calculate the minimum distance between the point cloud or depth map, and the specified reference object. INQ (summarize) Sets whether to calculate the minimum distance between the point cloud or depth map, and the specified reference object. INQ (more details...)
	M_DEFAULT	Same as M_DISABLE.
	M_DISABLE	Specifies not to calculate the minimum distance.
	M_ENABLE	Specifies to calculate the minimum distance.
M_STAT_MIN_ABS		Sets whether to calculate the minimum absolute distance between the point cloud or depth map, and the specified reference object. INQ (summarize) Sets whether to calculate the minimum absolute distance between the point cloud or depth map, and the specified reference object. INQ (more details...)
	M_DEFAULT	Same as M_DISABLE.
	M_DISABLE	Specifies not to calculate the minimum absolute distance.
	M_ENABLE	Specifies to calculate the minimum absolute distance.
M_STAT_NUMBER		Sets whether to record the number of points that meet the condition specified when calling M3dmetStat() (using the Condition, CondLow and CondHigh parameters). INQ (summarize) Sets whether to record the number of points that meet the condition specified when calling M3dmetStat() (using the Condition, CondLow and CondHigh parameters). INQ (more details...)
	M_DEFAULT	Same as M_DISABLE.
	M_DISABLE	Specifies not to record the number of points that meet the specified condition.
	M_ENABLE	Specifies to record the number of points that meet the specified condition.
M_STAT_RMS		Sets whether to calculate the root-mean-square (RMS) error between the point cloud or depth map, and the specified reference object. MIL calculates the RMS error using the following formula: INQ (summarize) Sets whether to calculate the root-mean-square (RMS) error between the point cloud or depth map, and the specified reference object. INQ (more details...)
	M_DEFAULT	Same as M_DISABLE.
	M_DISABLE	Specifies not to calculate the RMS error.
	M_ENABLE	Specifies to calculate the RMS error.
M_STAT_STANDARD_DEVIATION		Sets whether to calculate the standard deviation of all the distances calculated between the point cloud or depth map, and the specified reference object. MIL calculates the standard deviation using the following formula: INQ (summarize) Sets whether to calculate the standard deviation of all the distances calculated between the point cloud or depth map, and the specified reference object. INQ (more details...)
	M_DEFAULT	Same as M_DISABLE.
	M_DISABLE	Specifies not to calculate the standard deviation.
	M_ENABLE	Specifies to calculate the standard deviation.
M_STAT_SUM		Sets whether to calculate the sum of all the distances calculated between the point cloud or depth map, and the specified reference object. INQ (summarize) Sets whether to calculate the sum of all the distances calculated between the point cloud or depth map, and the specified reference object. INQ (more details...)
	M_DEFAULT	Same as M_DISABLE.
	M_DISABLE	Specifies not to calculate the sum of all the distances.
	M_ENABLE	Specifies to calculate the sum of all the distances.
M_STAT_SUM_ABS		Sets whether to calculate the sum of all the absolute distances calculated between the point cloud or depth map, and the specified reference object. INQ (summarize) Sets whether to calculate the sum of all the absolute distances calculated between the point cloud or depth map, and the specified reference object. INQ (more details...)
	M_DEFAULT	Same as M_DISABLE.
	M_DISABLE	Specifies not to calculate the sum of all absolute distances.
	M_ENABLE	Specifies to calculate the sum of all absolute distances.
M_STAT_SUM_OF_SQUARES		Sets whether to calculate the sum of squared distances between the point cloud or depth map, and the specified reference object. INQ (summarize) Sets whether to calculate the sum of squared distances between the point cloud or depth map, and the specified reference object. INQ (more details...)
	M_DEFAULT	Same as M_DISABLE.
	M_DISABLE	Specifies not to calculate the sum of squared distances.
	M_ENABLE	Specifies to calculate the sum of squared distances.

The following ControlType and ControlValue parameter settings can be specified for a fit 3D metrology context, and control how M3dmetFit() performs the fit operation.

To control a fit 3D metrology context
ControlType		Description
	ControlValue	Description
M_ESTIMATION_MODE		Sets how to compute an initial fit estimate between the point cloud or depth map, and the specified reference object. INQ (summarize) Sets how to compute an initial fit estimate between the point cloud or depth map, and the specified reference object. INQ (more details...)
	M_DEFAULT	Same as M_RANDOM_SAMPLING.
	M_FROM_GEOMETRY	Specifies that an initial fit estimate is determined using a geometry object that is copied into the fit 3D metrology context using M3dmetCopy() with M_ESTIMATE_GEOMETRY. The 3D geometry object must have been previously allocated using M3dgeoAlloc() with M_GEOMETRY, and must have been successfully defined. Supported 3D geometries include cylinder, line, plane, and sphere. Note that fitting a 3D box geometry is not supported. (summarize) Specifies that an initial fit estimate is determined using a geometry object that is copied into the fit 3D metrology context using M3dmetCopy() with M_ESTIMATE_GEOMETRY. (more details...)
	M_NO_SAMPLING	Specifies that an initial fit estimate is calculated using all available points in a point cloud or depth map. It is recommended that you only use this mode when there is a low percentage of outliers among the points of the point cloud or depth map. (summarize) Specifies that an initial fit estimate is calculated using all available points in a point cloud or depth map. (more details...)
	M_RANDOM_SAMPLING	Specifies that an initial fit estimate is determined using a random sampling consensus (RANSAC) algorithm. This mode tries to find the best fit of a 3D geometry object to a point cloud by trying to fit the reference object to several random samplings of the point cloud or depth map, and uses the best fit (with the lowest root-mean-squared (RMS) error) as the best initial approximation. Random sampling consensus assumes that the best fit of the MIL object will use the random sampling of points that contains the fewest outliers. Using an initial fit estimate that ignores outliers will prevent M3dmetFit() from fitting the MIL object incorrectly. To optimize the likelihood of a good initial fit estimate, you can specify a value for M_EXPECTED_OUTLIER_PERCENTAGE. (summarize) Specifies that an initial fit estimate is determined using a random sampling consensus (RANSAC) algorithm. (more details...)
M_EXPECTED_OUTLIER_PERCENTAGE		Sets the expected percentage of outliers among the points of the point cloud or depth map to be fitted. This setting is only applicable when M_ESTIMATION_MODE is M_RANDOM_SAMPLING. INQ (summarize) Sets the expected percentage of outliers among the points of the point cloud or depth map to be fitted. INQ (more details...)
	M_DEFAULT	Specifies the default value; the default value is 40.
	0.0 < Value < 100.0	Specifies the expected percentage of outliers among the points of the point cloud or depth map to be fitted.
M_FIT_ITERATIONS_MAX		Sets the maximum number of iterations to use during the fit operation. If this value is set to 0, M3dmetFit() returns the result of the initial fit estimate, as specified using M3dmetControl() with M_ESTIMATION_MODE. INQ (summarize) Sets the maximum number of iterations to use during the fit operation. INQ (more details...)
	M_DEFAULT	Specifies the default value; the default value is 5.
	Value >= 0	Specifies the maximum number of iterations to use during the fit operation.
M_INLIER_AMOUNT_THRESHOLD		Sets a minimum number of inliers required for the fit operation to end. After each iteration of the fit operation, the total number of inliers and the RMS error are calculated. If the number of inliers exceeds M_INLIER_AMOUNT_THRESHOLD, and the average RMS error is less than M_RMS_ERROR_THRESHOLD, the fit operation will stop. A point is considered an inlier when its distance from the reference geometry is less than the value passed to the OutlierDistance parameter when M3dmetFit() is called. The status of the fit operation can be retrieved using M3dmetGetResult() with M_STATUS. INQ (summarize) Sets a minimum number of inliers required for the fit operation to end. INQ (more details...)
	M_DEFAULT	Same as M_INFINITE.
	M_INFINITE	Specifies that there is no minimum number of inliers.
	Value >= 0	Specifies the minimum number of inliers.
M_RMS_ERROR_THRESHOLD		Sets the maximum RMS error required for the fit operation to end. After each iteration of the fit operation, the average RMS error is calculated. If the average RMS error is less than M_RMS_ERROR_THRESHOLD, and the number of inliers exceeds M_INLIER_AMOUNT_THRESHOLD, the fit operation will stop. INQ (summarize) Sets the maximum RMS error required for the fit operation to end. INQ (more details...)
	M_DEFAULT	Specifies the default value; the default value is 0.0.
	Value >= 0.0	Specifies the maximum RMS error.

Type-specific versions of the function when using a C compiler under 64-bit

void M3dmetControlInt64 (MIL_ID Context3dmetId, MIL_INT64 ControlType, MIL_INT64 ControlValue)

Details

Parameters

Context3dmetId

See Context3dmetId of the main function for a description.

ControlType

See ControlType of the main function for a description.

ControlValue

See ControlValue of the main function for a description.

void M3dmetControlDouble (MIL_ID Context3dmetId, MIL_INT64 ControlType, MIL_DOUBLE ControlValue)

Details

Parameters

Context3dmetId

See Context3dmetId of the main function for a description.

ControlType

See ControlType of the main function for a description.

ControlValue

See ControlValue of the main function for a description.

Compilation information

Header	Include mil.h.
Library	Use mil.lib; mil3dmet.lib.
DLL	Requires mil.dll; mil3dmet.dll.