M3dmapControl

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

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

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

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

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

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

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.

Sets the speed and direction of the object being scanned, along the object's plane of motion. INQ

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

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

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

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

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.

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

Specifies how to perform the prealignment step. INQ

Sets the mode in which to fill gaps (missing data points) in depth maps obtained using M3dmapExtract(). INQ

Sets which boundary to use to fill sharp elevation gaps in depth maps obtained using M3dmapExtract(). INQ

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

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

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

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

Sets how to adjust the X and Y pixel sizes in M3dmapExtract() when M_EXTRACTION_SCALE_MODE is set to M_AUTO_SCALE. INQ

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

Sets the sign of the Z scale in M3dmapExtract() when M_EXTRACTION_SCALE_MODE is set to M_AUTO_SCALE. INQ

Sets the algorithm to use when calling M3dmapSetBox() with M_BOUNDING_BOX. INQ

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

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

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

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

Sets how to determine the gray level of a depth map pixel that corresponds to more than one 3D point. INQ

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

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.

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

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

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

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 18: 3D reconstruction using laser line profiling.

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