M3dmapControl

Filters
See also

Availability

Not available in MIL-Lite

Available in MIL

Available on Windows

Available on Linux

Available on Non-Matrox computer

Available on Matrox 4Sight-X

Available on Matrox 4Sight GP/GPm

Available on Matrox Supersight

Function map

Examples

3dmodelheightdefect.cpp
3dplanarity.cpp
3dprofilemetrology.cpp
cameralasercalibration.cpp
depthmapgenerator.cpp
examplemanagerfor3d.cpp
lmigocator3110.cpp
m3dmap.cpp
m3dmap.cs
m3dmap.vb
matroxgatoreye.cpp
pfocus.cpp
sickrangerc.cpp
sickrangere.cpp
simple3dbinpicking.cpp
simple3dstitching.cpp

Function Map

- ContextOrResult3dmapId

- LabelOrIndex

Table:

For specifying the point cloud(s) or point cloud container

- ControlType

- ControlValue

Parameter Associations

Table:	For a 3D reconstruction context
Table:	For a 3D reconstruction context in M_CALIBRATED_CAMERA_LINEAR_MOTION 3D reconstruction mode
Table:	For a pairwise 3D alignment context
+ combination:	To specify the model or scene normals
Table:	For a 3D reconstruction result buffer set to M_POINT_CLOUD_CONTAINER, M_DEPTH_CORRECTED_DATA, or M_LASER_CALIBRATION_DATA
Table:	For a 3D reconstruction result buffer set to M_POINT_CLOUD_CONTAINER

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

Compilation information

Synopsis

Control a 3D reconstruction context or result buffer.

Syntax

void M3dmapControl(

MIL_ID ContextOrResult3dmapId,	//in
MIL_INT LabelOrIndex,	//in
MIL_INT64 ControlType,	//in
MIL_DOUBLE ControlValue	//in

)

Description

This function allows you to control a specified setting of a 3D reconstruction context or a 3D reconstruction result buffer.

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

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 if there is complementary information.

Parameters

This function is not supported on the selected boards.

Parameters

ContextOrResult3dmapId

Specifies the identifier of the 3D reconstruction context or the result buffer to control.

LabelOrIndex

Specifies the point cloud(s) in the specified 3D reconstruction result buffer, or the entire result buffer itself, to control. Only 3D reconstruction result buffers allocated using M_POINT_CLOUD_CONTAINER have point clouds that can be specified using this parameter. For all other types of 3D reconstruction contexts and result buffers, set this parameter to M_DEFAULT.

For specifying the point cloud(s) or point cloud container
Value	Description
M_POINT_CLOUD_INDEX( MIL_INT PointCloudIndex )	Specifies the array index of a point cloud in the specified 3D reconstruction result buffer. (summarize) Specifies the array index of a point cloud in the specified 3D reconstruction result buffer. (more details...)
		Parameters
		PointCloudIndex Specifies the index of an existing point cloud.
M_POINT_CLOUD_LABEL( MIL_INT PointCloudLabel )	Specifies the label for a point cloud in the specified 3D reconstruction result buffer. (summarize) Specifies the label for a point cloud in the specified 3D reconstruction result buffer. (more details...)
		Parameters
		PointCloudLabel Specifies the label of an existing point cloud.
M_ALL	Specifies to apply the control to all point clouds in the specified 3D reconstruction result buffer.
M_GENERAL	Specifies to control the specified 3D reconstruction result buffer (point cloud container) allocated using M_POINT_CLOUD_CONTAINER.

ControlType

Specifies the type of setting to control.

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

ControlValue

Specifies the required value for the setting.

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.

For a 3D reconstruction context
For a 3D reconstruction context in M_CALIBRATED_CAMERA_LINEAR_MOTION 3D reconstruction mode
For a pairwise 3D alignment context
For a 3D reconstruction result buffer set to M_POINT_CLOUD_CONTAINER, M_DEPTH_CORRECTED_DATA, or M_LASER_CALIBRATION_DATA
For a 3D reconstruction result buffer set to M_POINT_CLOUD_CONTAINER

The following ControlType and corresponding ControlValue settings are available for any kind of 3D reconstruction context:

For a 3D reconstruction context
ControlType		Description
	ControlValue	Description
M_CORRECTED_DEPTH		Specifies the Z-coordinate in world units (for point clouds) or gray level (for partially corrected depth maps) used to represent the height of the next reference plane (the next call to M3dmapAddScan()), during 3D reconstruction calibration for depth. If ContextOrResult3dmapId is a 3D reconstruction context allocated with M_CALIBRATED_CAMERA_LINEAR_MOTION, this value must be specified in world units. The specified Z-coordinate is the actual height of the reference plane in the next calibration image. If ContextOrResult3dmapId is a 3D reconstruction context allocated with M_DEPTH_CORRECTION, this value must be specified in gray levels. The specified gray level is paired with the position of the laser line over a reference plane in the calibration image. Note that a partially corrected depth map has no coordinate system, and so their is no actual height involved. INQ (summarize) Specifies the Z-coordinate in world units (for point clouds) or gray level (for partially corrected depth maps) used to represent the height of the next reference plane (the next call to M3dmapAddScan()), during 3D reconstruction calibration for depth. INQ (more details...)
	M_DEFAULT	Specifies the default value; the default value is 0.
	0 <= GrayValue <= 254	Specifies the gray level that will be used to represent the height of the next reference plane, when M3dmapAlloc() is set to M_DEPTH_CORRECTION. For 8-bit depth maps, the range is 0 to 254. Note that 255 is used to indicate an invalid value (no data). (summarize) Specifies the gray level that will be used to represent the height of the next reference plane, when M3dmapAlloc() is set to M_DEPTH_CORRECTION. (more details...)
	0 <= GrayValue <= 65534	Specifies the gray level that will be used to represent the height of the next reference plane, when M3dmapAlloc() is set to M_DEPTH_CORRECTION. For 16-bit depth maps, the range is 0 to 65534. Note that 65535 is used to indicate an invalid value (no data). (summarize) Specifies the gray level that will be used to represent the height of the next reference plane, when M3dmapAlloc() is set to M_DEPTH_CORRECTION. (more details...)
	ZCoordinateValue	Specifies the Z-coordinate (in world units) of the next reference plane. Generally, this value will be negative, since the Z-axis typically points downwards and has its origin on the conveyor. (summarize) Specifies the Z-coordinate (in world units) of the next reference plane. (more details...)
M_EXTRACTION_FIXED_POINT		Sets the number of binary digits used for the fractional part of the gray level values in uncorrected depth maps, when using M3dmapAddScan() with M_LINE_ALREADY_EXTRACTED. INQ (summarize) Sets the number of binary digits used for the fractional part of the gray level values in uncorrected depth maps, when using M3dmapAddScan() with M_LINE_ALREADY_EXTRACTED. INQ (more details...)
	M_DEFAULT	Specifies the default value; the default value is 0.
	0 <= Value <= 7	Specifies the number of binary digits used for the fractional part of gray level values.

The following ControlType and ControlValue settings are available only for a 3D reconstruction context in M_CALIBRATED_CAMERA_LINEAR_MOTION 3D reconstruction mode:

For a 3D reconstruction context in M_CALIBRATED_CAMERA_LINEAR_MOTION 3D reconstruction mode
ControlType		Description
	ControlValue	Description
M_EXTRACTION_CHILD_OFFSET_X		Sets the X-offset that M3dmapAddScan() assumes the laser line image buffer to have relative to the top-left pixel of the image buffer used during camera calibration. If you supply M3dmapAddScan() with a child buffer so that it processes only a subset of the grabbed laser line image, and you are generating a fully corrected depth map, you must specify the X- and Y-offsets of that child buffer, relative to the top-left pixel of the image buffer used during camera calibration. If you know, for example, that the laser line will appear only at certain heights in the grabbed laser line image, using a child buffer can be useful to narrow down the search region and reduce processing time. INQ (summarize) Sets the X-offset that M3dmapAddScan() assumes the laser line image buffer to have relative to the top-left pixel of the image buffer used during camera calibration. INQ (more details...)
	M_DEFAULT	Specifies the default value; the default value is 0.
	Value > 0	Specifies the X-offset, in pixels.
M_EXTRACTION_CHILD_OFFSET_Y		Sets the Y-offset that M3dmapAddScan() assumes the laser line image buffer to have relative to the top-left pixel of the image buffer used during camera calibration. If you supply M3dmapAddScan() with a child buffer so that it processes only a subset of the grabbed laser line image, and you are generating a fully corrected depth map, you must specify the X- and Y-offsets of that child buffer, relative to the top-left pixel of the image buffer used during camera calibration. If you know, for example, that the laser line will appear only at certain heights in the grabbed laser line image, using a child buffer can be useful to narrow down the search region and reduce processing time. INQ (summarize) Sets the Y-offset that M3dmapAddScan() assumes the laser line image buffer to have relative to the top-left pixel of the image buffer used during camera calibration. INQ (more details...)
	M_DEFAULT	Specifies the default value; the default value is 0.
	Value > 0	Specifies the Y-offset, in pixels.
M_EXTRACTION_RANGE_Z		Sets the mode that helps determine the range of valid Z-coordinates for extracted points when using M3dmapAddScan(). An extracted point that has a Z-coordinate outside of this range is set to M_INVALID_POINT. INQ (summarize) Sets the mode that helps determine the range of valid Z-coordinates for extracted points when using M3dmapAddScan(). INQ (more details...)
	M_GREATER	Specifies that the Z-axis range is defined by a lower limit corresponding to M_EXTRACTION_RANGE_Z_LIMIT1. All points having a Z coordinate greater than M_EXTRACTION_RANGE_Z_LIMIT1 are kept. (summarize) Specifies that the Z-axis range is defined by a lower limit corresponding to M_EXTRACTION_RANGE_Z_LIMIT1. (more details...)
	M_IN_RANGE	Specifies that the Z-axis range is defined by the inside range of a lower limit and a upper limit corresponding to M_EXTRACTION_RANGE_Z_LIMIT1 and M_EXTRACTION_RANGE_Z_LIMIT2. All points having a Z coordinate greater than or equal to the lower limit and less than or equal to the upper limit are kept. M_EXTRACTION_RANGE_Z_LIMIT1 is the lower limit of the Z-coordinate extraction range when it is lower than M_EXTRACTION_RANGE_Z_LIMIT2. M_EXTRACTION_RANGE_Z_LIMIT1 is the upper limit of the Z-coordinate extraction range when it is higher than M_EXTRACTION_RANGE_Z_LIMIT2. (summarize) Specifies that the Z-axis range is defined by the inside range of a lower limit and a upper limit corresponding to M_EXTRACTION_RANGE_Z_LIMIT1 and M_EXTRACTION_RANGE_Z_LIMIT2. (more details...)
	M_INFINITE	Specifies that the range covers the entire Z-axis, so all points are kept. This is the default value. (summarize) Specifies that the range covers the entire Z-axis, so all points are kept. (more details...)
	M_LESS	Specifies that the Z-axis range is defined by a upper limit corresponding to M_EXTRACTION_RANGE_Z_LIMIT1. All points having a Z coordinate less than M_EXTRACTION_RANGE_Z_LIMIT1 are kept. (summarize) Specifies that the Z-axis range is defined by a upper limit corresponding to M_EXTRACTION_RANGE_Z_LIMIT1. (more details...)
	M_OUT_RANGE	Specifies that the Z-axis range is defined by the outside range of a lower limit and a upper limit corresponding to M_EXTRACTION_RANGE_Z_LIMIT1 and M_EXTRACTION_RANGE_Z_LIMIT2. M_EXTRACTION_RANGE_Z_LIMIT1 is the lower limit of the Z-coordinate extraction range when it is lower than M_EXTRACTION_RANGE_Z_LIMIT2. M_EXTRACTION_RANGE_Z_LIMIT1 is the upper limit of the Z-coordinate extraction range when it is higher than M_EXTRACTION_RANGE_Z_LIMIT2. (summarize) Specifies that the Z-axis range is defined by the outside range of a lower limit and a upper limit corresponding to M_EXTRACTION_RANGE_Z_LIMIT1 and M_EXTRACTION_RANGE_Z_LIMIT2. (more details...)
M_EXTRACTION_RANGE_Z_LIMIT1		Sets the first limit value that determines the range of valid Z-coordinates for extracted points. This value is ignored when M_EXTRACTION_RANGE_Z is set to M_INFINITE. INQ (summarize) Sets the first limit value that determines the range of valid Z-coordinates for extracted points. INQ (more details...)
	Value	Specifies the first limit value, which can be either the lower limit or upper limit. The default value is 0. (summarize) Specifies the first limit value, which can be either the lower limit or upper limit. (more details...)
M_EXTRACTION_RANGE_Z_LIMIT2		Sets the second limit value that determines the range of valid Z-coordinates for extracted points. Note that when M_EXTRACTION_RANGE_Z is set to M_INFINITE, M_GREATER, or M_LESS, this value is ignored. INQ (summarize) Sets the second limit value that determines the range of valid Z-coordinates for extracted points. INQ (more details...)
	Value	Specifies the second limit value, which can be either the lower limit or upper limit. The default value is 0. (summarize) Specifies the second limit value, which can be either the lower limit or upper limit. (more details...)
M_SCAN_SPEED		Sets the speed and direction of the object being scanned, along the object's plane of motion. INQ (summarize) Sets the speed and direction of the object being scanned, along the object's plane of motion. INQ (more details...)
	M_DEFAULT	Specifies the default value; the default value is 1.0.
	Value	Specifies the speed, in world units per frame. Note that if the object is moving in the negative Y-axis, specify a negative value. (summarize) Specifies the speed, in world units per frame. (more details...)

The following ControlType and ControlValue settings are available only for a pairwise 3D alignment context allocated using M3dmapAlloc() with M_PAIRWISE_ALIGNMENT_CONTEXT:

For a pairwise 3D alignment context
ControlType		Description
	ControlValue	Description
M_ALIGN_RMS_ERROR_RELATIVE_THRESHOLD		Specifies the stop condition for the pairwise 3D alignment iterative process that tests the percentile change of the RMS error of successive iterations. The RMS error is calculated from the distance between paired points of the two point clouds being aligned in 3D. If the percentage change in the RMS error from the previous iteration to the current iteration goes under or equals the specified value, the 3D alignment process stops. This is typically considered a correct alignment. INQ (summarize) Specifies the stop condition for the pairwise 3D alignment iterative process that tests the percentile change of the RMS error of successive iterations. INQ (more details...)
	M_DEFAULT	Specifies the default value; the default value is 0.1.
	Value >= 0.0	Specifies the RMS relative threshold. This value is expressed as a percentage, so a value of 0.1 is 0.1%, not 10%. (summarize) Specifies the RMS relative threshold. (more details...)
M_ALIGN_RMS_ERROR_THRESHOLD		Specifies the stop condition for the pairwise 3D alignment iterative process that tests the RMS error of successive iterations. The RMS error is calculated from the distance between paired points of the two point clouds being aligned in 3D. If the RMS error goes under or equals the specified value, the 3D alignment process stops. This is typically considered a correct alignment. INQ (summarize) Specifies the stop condition for the pairwise 3D alignment iterative process that tests the RMS error of successive iterations. INQ (more details...)
	M_DEFAULT	Specifies the default value; the default value is 0.0.
	Value >= 0.0	Specifies the RMS threshold.
M_DECIMATION_STEP_MODEL		Specifies the decimation level applied to the model point cloud during the pairwise 3D alignment process. The number of points used during the pairwise 3D alignment process is reduced by a factor of the square of the specified value. For example, on a point cloud with 10,000 points, if you specify a decimation step of 2, the pairwise 3D alignment process would only use 2,500 points (10,000/2 ² ). If you specify a decimation step of 10, the process would only use 100 points of the original 10,000. Decimating the point cloud makes the pairwise 3D alignment process significantly faster, but reduces the accuracy of the results. INQ (summarize) Specifies the decimation level applied to the model point cloud during the pairwise 3D alignment process. INQ (more details...)
	M_DEFAULT	Specifies the default value; the default value is 1.
	Value > 0	Specifies the decimation level.
M_DECIMATION_STEP_SCENE		Specifies the decimation level applied to the scene point cloud during the pairwise 3D alignment process. The number of points used during the pairwise 3D alignment process is reduced by a factor of the square of the specified value. For example, on a point cloud with 10,000 points, if you specify a decimation step of 2, the pairwise 3D alignment process would only use 2,500 points (10,000/2 ² ). If you specify a decimation step of 10, the process would only use 100 points of the original 10,000. Decimating the point cloud makes the pairwise 3D alignment process significantly faster, but reduces the accuracy of the results. INQ (summarize) Specifies the decimation level applied to the scene point cloud during the pairwise 3D alignment process. INQ (more details...)
	M_DEFAULT	Specifies the default value; the default value is 1.
	Value > 0	Specifies the decimation level.
M_ERROR_MINIMIZATION_METRIC		Specifies the technique that the alignment algorithm uses to minimize the RMS error. INQ (summarize) Specifies the technique that the alignment algorithm uses to minimize the RMS error. INQ (more details...)
	M_POINT_TO_PLANE +	Specifies that the technique minimizes the distance between the points in one point cloud and the surface of the tangent planes of the other point cloud. You specify whether to use the tangent planes of the scene or model point cloud using M_USE_SCENE_NORMALS and M_USE_MODEL_NORMALS. M_POINT_TO_PLANE tends to be better suited for objects with a wide range of surface directions and for organized point clouds, such as of type M_LASER_SCAN. Compared to M_POINT_TO_POINT, the M_POINT_TO_PLANE technique tends to have faster convergence and is less sensitive to differences of sampling between the model and scene point clouds. This is the default value. You must specify a combination value from the following table: To specify whether to use the normals of the model or scene point cloud (summarize) Specifies that the technique minimizes the distance between the points in one point cloud and the surface of the tangent planes of the other point cloud. (more details...)
	M_POINT_TO_POINT	Specifies that the technique minimizes the Euclidean distance between the points in the model and scene point clouds, with no special consideration to the normals to the surface of the point clouds. M_POINT_TO_POINT tends to be more robust for objects with planar surfaces and for point clouds of type M_UNORGANIZED. Compared to M_POINT_TO_PLANE, the M_POINT_TO_POINT technique tends to have slower convergence and is more sensitive to differences of sampling between the model and scene point clouds. (summarize) Specifies that the technique minimizes the Euclidean distance between the points in the model and scene point clouds, with no special consideration to the normals to the surface of the point clouds. (more details...)
M_EXTRACTION_BOX_MODEL		Specifies whether to use the model point cloud's extraction box to limit the points used during pairwise 3D alignment. INQ (summarize) Specifies whether to use the model point cloud's extraction box to limit the points used during pairwise 3D alignment. INQ (more details...)
	M_IGNORE	Specifies to ignore the extraction box and use all points in the model point cloud. This is the default value. (summarize) Specifies to ignore the extraction box and use all points in the model point cloud. (more details...)
	M_USE	Specifies to use the model point cloud's extraction box to limit the points used during pairwise 3D alignment.
M_EXTRACTION_BOX_SCENE		Specifies whether to use the scene point cloud's extraction box to limit the points used during pairwise 3D alignment. INQ (summarize) Specifies whether to use the scene point cloud's extraction box to limit the points used during pairwise 3D alignment. INQ (more details...)
	M_IGNORE	Specifies to ignore the extraction box and use all points in the scene point cloud. This is the default value. (summarize) Specifies to ignore the extraction box and use all points in the scene point cloud. (more details...)
	M_USE	Specifies to use the scene point cloud's extraction box to limit the points used during pairwise 3D alignment.
M_MAX_ITERATIONS		Specifies the stop condition for the pairwise 3D alignment iterative process that tests the total number of iterations performed. If the maximum number of iterations is reached, the 3D alignment process stops. Note that the prealignment step is systematically considered as the first iteration. INQ (summarize) Specifies the stop condition for the pairwise 3D alignment iterative process that tests the total number of iterations performed. INQ (more details...)
	M_DEFAULT	Specifies the default value; the default value is 20.
	Value > 0	Specifies the maximum number of iterations.
M_MODEL_OVERLAP		Specifies the percentage of model points paired with scene points during each iteration of the alignment process. For instance, if 80% of the model points in the model point cloud are used in the alignment process, during each iteration, the top 80% of model point pairings are used to generate an RMS error and are used to calculate a transformation. This excludes the 20% worst point pairings, which are often the outliers in the scene point cloud typically caused by image noise, object deformity, or misalignment. Typically, if there are fewer scene points than model points (the scene is only a portion of the entire model), you should set this control type to the approximate ratio of the scene to the model. If the density of points is the same in the model and the scene point clouds, this ratio could be set to the exact ratio between the two. For instance, if there are 100,000 points in the scene point cloud, 200,000 points in the model point cloud, and they both have the same density of points, you should set this value to 50%. This can occur because of occlusion of the object while generating the scene point cloud. If there are more scene points than model points, you should set this value a little lower than 100%. In this case, you should use as much of the model points as possible, while still allowing for some outliers. INQ (summarize) Specifies the percentage of model points paired with scene points during each iteration of the alignment process. INQ (more details...)
	M_DEFAULT	Specifies the default value; the default value is 80.0.
	0.0 < Value <= 100.0	Specifies the percentage of points in the model point cloud that are paired with points in the scene point cloud during each iteration.
M_PREALIGNMENT_MODE		Specifies how to perform the prealignment step. INQ (summarize) Specifies how to perform the prealignment step. INQ (more details...)
	M_CENTROID	Specifies to automatically align the centroids (center of mass) of the two point clouds. By default, this alignment is a translation only and does not include any rotation. However, if a prealignment transformation matrix is passed to M3dmapAlign() and this control value is set, the prealignment iteration performs the translation required to align the centroids and the rotation specified by the prealignment transformation matrix. The translation specified by the prealignment transformation matrix is ignored. (summarize) Specifies to automatically align the centroids (center of mass) of the two point clouds. (more details...)
	M_USER_DEFINED	Specifies that the prealignment iteration performs the transformation defined by the prealignment transformation matrix passed to M3dmapAlign(). This is the default value. (summarize) Specifies that the prealignment iteration performs the transformation defined by the prealignment transformation matrix passed to M3dmapAlign(). (more details...)

Combination values for M_POINT_TO_PLANE (when ControlType=M_ERROR_MINIMIZATION_METRIC and ControlValue=M_POINT_TO_PLANE).

You must add one of the following values to the above-mentioned value to specify whether to use the normals of the model or scene point cloud.

To specify the model or scene normals
Combination value	Description
M_USE_MODEL_NORMALS	Specifies to measure the distance between the tangent planes of the surface of the model point cloud (calculated from the model normals) and the points of the scene point cloud. It can be beneficial to use the normals of the model point cloud when the model point cloud has fewer points than the scene point cloud, because fewer normals need to be calculated. This potential gain must be weighed against the additional processing time needed to calculate a temporary organizing structure for the model point cloud, if the model point cloud does not already have a recognized organizational structure. (summarize) Specifies to measure the distance between the tangent planes of the surface of the model point cloud (calculated from the model normals) and the points of the scene point cloud. (more details...)
M_USE_SCENE_NORMALS	Specifies to measure the distance between the tangent planes of the surface of the scene point cloud (calculated from the scene normals) and the points of the model point cloud. Note that the scene point cloud will always have either an implicit or a temporary organizing structure, so no additional processing time is spent calculating the temporary organizational structure needed to calculate the surface normals and tangents. This is the default value. (summarize) Specifies to measure the distance between the tangent planes of the surface of the scene point cloud (calculated from the scene normals) and the points of the model point cloud. (more details...)

The following ControlType and ControlValue settings are available only for a 3D reconstruction result buffer set to M_POINT_CLOUD_CONTAINER, M_DEPTH_CORRECTED_DATA, or M_LASER_CALIBRATION_DATA:

For a 3D reconstruction result buffer set to M_POINT_CLOUD_CONTAINER, M_DEPTH_CORRECTED_DATA, or M_LASER_CALIBRATION_DATA
ControlType		Description
	ControlValue	Description
M_FILL_MODE		Sets the mode in which to fill gaps (missing data points) in depth maps obtained using M3dmapExtract(). INQ (summarize) Sets the mode in which to fill gaps (missing data points) in depth maps obtained using M3dmapExtract(). INQ (more details...)
	M_DEFAULT	Same as M_DISABLE.
	M_DISABLE	Specifies not to fill gaps (missing data points).
	M_X_THEN_Y	Specifies that each depth map row is analyzed so that missing data points in each row are filled, and then each column is analyzed to fill the remaining missing data points. The filling operation used depends on the M_FILL_SHARP_ELEVATION_DEPTH and M_FILL_SHARP_ELEVATION control types. Gaps whose boundaries touch the border of the image will not be filled. (summarize) Specifies that each depth map row is analyzed so that missing data points in each row are filled, and then each column is analyzed to fill the remaining missing data points. (more details...)
	M_Y_THEN_X	Specifies that each depth map column is analyzed so that missing data points in each column are filled, and then each row is analyzed to fill the remaining missing data points. The filling operation used depends on the M_FILL_SHARP_ELEVATION_DEPTH and M_FILL_SHARP_ELEVATION control types. Gaps whose boundaries touch the border of the image will not be filled. (summarize) Specifies that each depth map column is analyzed so that missing data points in each column are filled, and then each row is analyzed to fill the remaining missing data points. (more details...)
M_FILL_SHARP_ELEVATION		Sets which boundary to use to fill sharp elevation gaps in depth maps obtained using M3dmapExtract(). INQ (summarize) Sets which boundary to use to fill sharp elevation gaps in depth maps obtained using M3dmapExtract(). INQ (more details...)
	M_DEFAULT	Same as M_DISABLE.
	M_DISABLE	Specifies not to fill sharp elevation gaps.
	M_MAX	Specifies that the destination pixel will be set to the maximum value of the two pixels on either side of the gap.
	M_MIN	Specifies that the destination pixel will be set to the minimum value of the two pixels on either side of the gap.
M_FILL_SHARP_ELEVATION_DEPTH		Sets the threshold used to differentiate between gradual elevation gaps and sharp elevation gaps in the depth map. If the difference between a gap's boundary values is less than the specified threshold, the gap is considered a gradual elevation gap, otherwise it is considered a sharp elevation gap. Gradual elevation gaps are filled using linear interpolation; sharp elevation gaps are either filled by propagating the value of one of the boundaries or are left unfilled, depending on the M_FILL_SHARP_ELEVATION control type. It is often better to fill gradual elevation gaps using linear interpolation since the underlying surface of such a gap is considered to be part of the same surface as its boundaries. Whereas for sharp elevation gaps, the underlying surface is considered to be discontinuous at least at one of its boundaries, so propagating the value of one of the boundaries is recommended. INQ (summarize) Sets the threshold used to differentiate between gradual elevation gaps and sharp elevation gaps in the depth map. INQ (more details...)
	M_DEFAULT	Same as M_INFINITE.
	M_INFINITE	Specifies that the threshold is infinite. When M_INFINITE is specified, all gaps are considered gradual elevation gaps, so linear interpolation is always used and M_FILL_SHARP_ELEVATION is ignored. (summarize) Specifies that the threshold is infinite. (more details...)
	Value >= 0.0	Specifies the threshold, in world units specified using M_GRAY_LEVEL_SIZE_Z. When the threshold is set to 0.0, all gaps are considered sharp elevation gaps, so linear interpolation is never used and all gaps are filled according to M_FILL_SHARP_ELEVATION. (summarize) Specifies the threshold, in world units specified using M_GRAY_LEVEL_SIZE_Z. (more details...)
M_FILL_THRESHOLD_X		Sets the maximum X-size of gaps that will be filled when you call M3dmapExtract(). Gaps that have an X-size equal to or smaller than M_FILL_THRESHOLD_X, or that have a Y-size equal to or smaller than M_FILL_THRESHOLD_Y, will be filled. INQ (summarize) Sets the maximum X-size of gaps that will be filled when you call M3dmapExtract(). INQ (more details...)
	M_DEFAULT	Same as M_INFINITE.
	M_INFINITE	Specifies no maximum in the X-direction.
	Value >= 0.0	Specifies the maximum X-size. If you are using a partially corrected depth map, you must specify this value in pixel units. If you are using a fully corrected depth map, you must specify this value in world units. (summarize) Specifies the maximum X-size. (more details...)
M_FILL_THRESHOLD_Y		Sets the maximum Y-size of gaps that will be filled when you call M3dmapExtract(). Gaps that have an X-size equal to or smaller than M_FILL_THRESHOLD_X, or that have a Y-size equal to or smaller than M_FILL_THRESHOLD_Y, will be filled. INQ (summarize) Sets the maximum Y-size of gaps that will be filled when you call M3dmapExtract(). INQ (more details...)
	M_DEFAULT	Same as M_INFINITE.
	M_INFINITE	Specifies no maximum in the Y-direction.
	Value >= 0.0	Specifies the maximum Y-size. If you are using a partially corrected depth map, you must specify this value in pixel units. If you are using a fully corrected depth map, you must specify this value in world units. (summarize) Specifies the maximum Y-size. (more details...)
M_MAX_FRAMES		Sets the maximum number of scanned laser lines that the result buffer should keep internally. Note that, if the value of this control type is changed after it has already been set, laser lines can be lost. When you specify a point cloud (result buffer of type M_POINT_CLOUD_CONTAINER with LabelOrIndex not set to M_GENERAL), this control applies to point clouds of type M_LASER_SCAN only. When you specify a point cloud container (result buffer of type M_POINT_CLOUD_CONTAINER with LabelOrIndex set to M_GENERAL), this control will set the maximum number of scanned laser lines kept by each subsequent point cloud of type M_LASER_SCAN generated in this point cloud container. INQ (summarize) Sets the maximum number of scanned laser lines that the result buffer should keep internally. INQ (more details...)
	M_DEFAULT	Specifies the default value; the default value is 1024.
	Value > 0	Specifies the maximum number of scanned laser lines to keep.

The following controls apply to M_POINT_CLOUD_CONTAINER 3D reconstruction result buffers, when LabelOrIndex is set to M_GENERAL.

For a 3D reconstruction result buffer set to M_POINT_CLOUD_CONTAINER
ControlType		Description
	ControlValue	Description
M_AUTO_SCALE_ASPECT_RATIO		Sets how to adjust the X and Y pixel sizes in M3dmapExtract() when M_EXTRACTION_SCALE_MODE is set to M_AUTO_SCALE. INQ (summarize) Sets how to adjust the X and Y pixel sizes in M3dmapExtract() when M_EXTRACTION_SCALE_MODE is set to M_AUTO_SCALE. INQ (more details...)
	M_DEFAULT	Specifies the default value; the default value is 1.0.
	M_UNCONSTRAINED	Specifies that pixel sizes are chosen independently so that the extraction box fits exactly inside the depth map image buffer.
	Value > 0.0	Specifies to choose pixel sizes such that M_PIXEL_SIZE_X / M_PIXEL_SIZE_Y equals the given aspect ratio.
M_AUTO_SCALE_XY		Sets how to adjust the X and Y pixel sizes in M3dmapExtract() when M_EXTRACTION_SCALE_MODE is set to M_AUTO_SCALE and M_AUTO_SCALE_ASPECT_RATIO is not set to M_UNCONSTRAINED. INQ (summarize) Sets how to adjust the X and Y pixel sizes in M3dmapExtract() when M_EXTRACTION_SCALE_MODE is set to M_AUTO_SCALE and M_AUTO_SCALE_ASPECT_RATIO is not set to M_UNCONSTRAINED. INQ (more details...)
	M_DEFAULT	Same as M_FIT.
	M_CLIP	Specifies pixel sizes such that all depth map pixels are inside the extraction box. This will clip those points that exist outside of the extraction box, if any. (summarize) Specifies pixel sizes such that all depth map pixels are inside the extraction box. (more details...)
	M_FIT	Specifies pixel sizes such that the extraction box fits completely inside the depth map. This might cause some depth map pixels to be missing data. (summarize) Specifies pixel sizes such that the extraction box fits completely inside the depth map. (more details...)
M_AUTO_SCALE_Z		Sets the sign of the Z scale in M3dmapExtract() when M_EXTRACTION_SCALE_MODE is set to M_AUTO_SCALE. INQ (summarize) Sets the sign of the Z scale in M3dmapExtract() when M_EXTRACTION_SCALE_MODE is set to M_AUTO_SCALE. INQ (more details...)
	M_DEFAULT	Same as M_NEGATIVE.
	M_NEGATIVE	Specifies a negative value for M_GRAY_LEVEL_SIZE_Z. Usually, negative Z values generate depth maps where higher objects appear lighter. (summarize) Specifies a negative value for M_GRAY_LEVEL_SIZE_Z. (more details...)
	M_POSITIVE	Specifies a positive value for M_GRAY_LEVEL_SIZE_Z. Usually, positive Z values generate depth maps where higher objects appear darker. (summarize) Specifies a positive value for M_GRAY_LEVEL_SIZE_Z. (more details...)
M_BOUNDING_BOX_ALGORITHM		Sets the algorithm to use when calling M3dmapSetBox() with M_BOUNDING_BOX. INQ (summarize) Sets the algorithm to use when calling M3dmapSetBox() with M_BOUNDING_BOX. INQ (more details...)
	M_DEFAULT	Same as M_ALL_POINTS.
	M_ALL_POINTS	Specifies to compute the axis-aligned bounding box, which contains all the points.
	M_ROBUST	Specifies to compute an axis-aligned box that contains most of the points, but rejects outliers.
M_BOUNDING_BOX_OUTLIER_RATIO_X		Sets the maximum ratio of the container points whose X coordinates can be considered outliers. Used when calling M3dmapSetBox() with M_BOUNDING_BOX and M_BOUNDING_BOX_ALGORITHM is set to M_ROBUST. INQ (summarize) Sets the maximum ratio of the container points whose X coordinates can be considered outliers. INQ (more details...)
	M_DEFAULT	Specifies the default value; the default value is 0.002.
	0.0 <= Value < 1.0	Specifies the ratio.
M_BOUNDING_BOX_OUTLIER_RATIO_Y		Sets the maximum ratio of the container points whose Y coordinates can be considered outliers. Used when calling M3dmapSetBox() with M_BOUNDING_BOX and M_BOUNDING_BOX_ALGORITHM is set to M_ROBUST. INQ (summarize) Sets the maximum ratio of the container points whose Y coordinates can be considered outliers. INQ (more details...)
	M_DEFAULT	Specifies the default value; the default value is 0.002.
	0.0 <= Value < 1.0	Specifies the ratio.
M_BOUNDING_BOX_OUTLIER_RATIO_Z		Sets the maximum ratio of the container points whose Z coordinates can be considered outliers. Used when calling M3dmapSetBox() with M_BOUNDING_BOX and M_BOUNDING_BOX_ALGORITHM is set to M_ROBUST. INQ (summarize) Sets the maximum ratio of the container points whose Z coordinates can be considered outliers. INQ (more details...)
	M_DEFAULT	Specifies the default value; the default value is 0.01.
	0.0 <= Value < 1.0	Specifies the ratio.
M_EXTRACTION_CUMULATIVE		Sets whether to accumulate points in the destination image with successive calls to M3dmapExtract() or to assume that all points are extracted in a single call. INQ (summarize) Sets whether to accumulate points in the destination image with successive calls to M3dmapExtract() or to assume that all points are extracted in a single call. INQ (more details...)
	M_DEFAULT	Same as M_DISABLE.
	M_DISABLE	Specifies to clear the image buffer before data is extracted for each call to M3dmapExtract().
	M_ENABLE	Specifies to accumulate data with each successive call to M3dmapExtract() without clearing the image buffer. You must call MbufClear() with the maximum value of the buffer (the value of a missing data point) before the first call to M3dmapExtract(). Note that during cumulative extraction, gap filling is disabled; instead, it must be performed with a separate call to M3dmapExtract() with M_FILL_MISSING_DATA_ONLY. (summarize) Specifies to accumulate data with each successive call to M3dmapExtract() without clearing the image buffer. (more details...)
M_EXTRACTION_OVERLAP		Sets how to determine the gray level of a depth map pixel that corresponds to more than one 3D point. INQ (summarize) Sets how to determine the gray level of a depth map pixel that corresponds to more than one 3D point. INQ (more details...)
	M_DEFAULT	Same as M_OVERWRITE.
	M_MAX	Specifies to use the largest gray level of all the 3D points projected on a single depth map pixel.
	M_MIN	Specifies to use the smallest gray level of all the 3D points projected on a single depth map pixel.
	M_OVERWRITE	Specifies to use the last gray level of all the 3D points projected on a single depth map pixel. This continually overwrites the previous gray value for the pixel, which can have unpredictable results. This can be marginally faster. (summarize) Specifies to use the last gray level of all the 3D points projected on a single depth map pixel. (more details...)
M_EXTRACTION_SATURATION		Sets how to determine a pixel's gray value when the point it represents cannot be represented by a gray value. There are two reasons why a point cannot be represented by a gray value: when the point is above or below the extraction box, and when the point is outside the depth map grayscale range. A point can be outside the grayscale range when you manually set the grayscale of the Z-axis (M_GRAY_LEVEL_SIZE_Z). For instance, if the Z-axis scale is 0.04 cm/gray level in an 8-bit image, a point that is 1 cm high has a gray value of 25. At about 10 cm, the gray value reaches its maximum for the bit depth, 254. A point higher than 10 cm is outside the grayscale range. Points can be out of the grayscale range of the depth map and still be in the extraction box. In the above example, if the extraction box is 20 cm high, a point that is 15 cm high is in the extraction box, but out of the grayscale range of the depth map. INQ (summarize) Sets how to determine a pixel's gray value when the point it represents cannot be represented by a gray value. INQ (more details...)
	M_DEFAULT	Same as M_DISABLE.
	M_DISABLE	Specifies to disable saturation. By disabling saturation, points above the extraction box or out of the depth map grayscale range are ignored and not included in the calculation of the depth map pixel's gray value. If there are other points that project onto this pixel, they are used to calculate the gray value. Otherwise, the pixel is rendered as invalid, and set to either 255 or 65535, depending on the bit-depth. (summarize) Specifies to disable saturation. (more details...)
	M_ENABLE	Specifies to enable saturation. By saturating the point, the pixel will either have the maximum possible gray value (254 or 65534 when the highest point is rendered white) or the minimum possible value (0 when the highest point is rendered black). The maximum value for a depth map can also be limited by a combination of the height of the extraction box and the depth map grayscale range. For instance, if the extraction box is 5 cm high, the highest possible point included in the depth map has a height of 5 cm. If the depth map grayscale range is 0.04 cm/gray level in an 8-bit depth map, the gray level of the highest possible point in the depth map is 125 (5 cm/0.04). A saturated pixel that is representing a point above the 5 cm extraction box limit takes the maximum possible gray value, which in this case is 125. (summarize) Specifies to enable saturation. (more details...)
M_EXTRACTION_SCALE_MODE		Sets how the scales of the X-, Y-, and Z-axes are selected before generating the depth map image. Note that in a depth map image, the Z-axis is represented using intensity rather than location, which is how the X- and Y- axes are represented. INQ (summarize) Sets how the scales of the X-, Y-, and Z-axes are selected before generating the depth map image. INQ (more details...)
	M_DEFAULT	Same as M_AUTO_SCALE.
	M_AUTO_SCALE	Specifies to automatically determine the scales during M3dmapExtract() so that the current extraction box fits the destination image buffer. The behavior can be further altered using M_AUTO_SCALE_ASPECT_RATIO, M_AUTO_SCALE_XY, and M_AUTO_SCALE_Z. (summarize) Specifies to automatically determine the scales during M3dmapExtract() so that the current extraction box fits the destination image buffer. (more details...)
	M_USE_DESTINATION_CALIBRATION	Specifies to use the scales stored in the depth map, previously set with an earlier call to M3dmapExtract(), or using McalUniform() and McalControl(). During M3dmapExtract(), the point cloud container's extraction box is ignored. (summarize) Specifies to use the scales stored in the depth map, previously set with an earlier call to M3dmapExtract(), or using McalUniform() and McalControl(). (more details...)
	M_USER_DEFINED	Specifies to use the values of M_PIXEL_SIZE_X, M_PIXEL_SIZE_Y, and M_GRAY_LEVEL_SIZE_Z.
M_GRAY_LEVEL_SIZE_Z		Sets the length of one gray level, in the Z-direction. This control type only affects how M3dmapExtract() generates and draws the depth map in the specified image buffer. INQ (summarize) Sets the length of one gray level, in the Z-direction. INQ (more details...)
	M_DEFAULT	Specifies the default value; the default value is 1.0.
	Value < 0.0	Specifies the length of one gray level, in world units. A negative value indicates that higher points in the object's height are represented by brighter depth map pixels, while the lower the height the darker the pixel. (summarize) Specifies the length of one gray level, in world units. (more details...)
	Value > 0.0	Specifies the length of one gray level, in world units. A positive value indicates that higher points in the object's height are represented by darker depth map pixels, and the lower the height the brighter the pixel. (summarize) Specifies the length of one gray level, in world units. (more details...)
M_PIXEL_SIZE_X		Sets the length, in world units, of one pixel, in the X-direction. This control type only affects how M3dmapExtract() generates and draws the depth map in the specified image buffer. In M_DEPTH_CORRECTION 3D reconstruction mode, this control type must be set to M_DEFAULT. INQ (summarize) Sets the length, in world units, of one pixel, in the X-direction. INQ (more details...)
	M_DEFAULT	Specifies the default value; the default value is 1.0.
	Value > 0.0	Specifies the length of one pixel, in world units.
M_PIXEL_SIZE_Y		Sets the length, in world units, of one pixel, in the Y-direction. This control type only affects how M3dmapExtract() generates and draws the depth map in the specified image buffer. INQ (summarize) Sets the length, in world units, of one pixel, in the Y-direction. INQ (more details...)
	M_DEFAULT	Specifies the default value; the default value is 1.0.
	Value > 0.0	Specifies the length of one pixel, in world units.
M_RESULTS_DISPLACEMENT_MODE		Sets the displacement mode, which determines whether the coordinates of scanned objects include the movement (displacement) of the conveyor. By default, the coordinates of scanned objects are stored as though the objects are fixed at their initial position when the first call to M3dmapAddScan() was made, despite the ongoing movement of the conveyor. When the coordinates are used (for instance, when returning the coordinates or generating a depth map), the displacement mode specifies whether to include the distance that the conveyor moved since the first call to M3dmapAddScan(). When you include this distance, you are getting the real-time coordinates of the objects at the moment the coordinates are returned or the depth map is generated. You can retrieve this conveyor displacement (Y-axis displacement) using M3dmapGetResult() with M_TOTAL_DISPLACEMENT_Y. In some circumstances, such as when manually defining the extraction box when generating a depth map, you might have to keep in mind whether an object's coordinates will include displacement when used. For more information, see the Results displacement mode subsection of the 3D coordinate systems and the coordinates of a point cloud section of Chapter 20: 3D reconstruction using laser line profiling. INQ (summarize) Sets the displacement mode, which determines whether the coordinates of scanned objects include the movement (displacement) of the conveyor. INQ (more details...)
	M_DEFAULT	Same as M_FIXED.
	M_CURRENT	Specifies that the results include the ongoing Y-axis displacement. The results return the current position of the object on the conveyor. Specifically, the results will reflect the 3D coordinates at the last call of M3dmapAddScan(). (summarize) Specifies that the results include the ongoing Y-axis displacement. (more details...)
	M_FIXED	Specifies that the results do not include the ongoing Y-axis displacement. The resulting coordinates are those of the object as if it were still at the original position on the conveyor, just prior to being scanned. In this mode, you can use M_RESULTS_DISPLACEMENT_Y to add a displacement offset to the 3D coordinates. (summarize) Specifies that the results do not include the ongoing Y-axis displacement. (more details...)
M_RESULTS_DISPLACEMENT_Y		Sets the Y-axis displacement to add to the resulting 3D coordinates of an object when M_RESULTS_DISPLACEMENT_MODE is set to M_FIXED. INQ (summarize) Sets the Y-axis displacement to add to the resulting 3D coordinates of an object when M_RESULTS_DISPLACEMENT_MODE is set to M_FIXED. INQ (more details...)
	M_DEFAULT	Specifies the default value; the default value is 0.0.
	Value	Specifies the Y-axis displacement. Note that total displacement can be negative depending on the direction of the conveyor. (summarize) Specifies the Y-axis displacement. (more details...)

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

void M3dmapControlInt64 (MIL_ID ContextOrResult3dmapId, MIL_INT LabelOrIndex, MIL_INT64 ControlType, MIL_INT64 ControlValue)

Details

Parameters

ContextOrResult3dmapId

See ContextOrResult3dmapId of the main function for a description.

LabelOrIndex

See LabelOrIndex 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 M3dmapControlDouble (MIL_ID ContextOrResult3dmapId, MIL_INT LabelOrIndex, MIL_INT64 ControlType, MIL_DOUBLE ControlValue)

Details

Parameters

ContextOrResult3dmapId

See ContextOrResult3dmapId of the main function for a description.

LabelOrIndex

See LabelOrIndex 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; mil3dmap.lib.
DLL	Requires mil.dll; mil3dmap.dll.