| MIL 10 Reference
| Customize Help
| Save Settings

M3dmapSetBox


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
Available on Matrox Supersight
function map Function map
Examples
M3dmapSave
M3dmapSetGeometry
Synopsis
Set the extraction box used for depth map extraction.
Syntax
void M3dmapSetBox(
MIL_ID Result3dmapId, //in
MIL_INT64 BoxType, //in
MIL_INT64 BoxDefinitionType, //in
MIL_DOUBLE XPos1OrSource, //in
MIL_DOUBLE YPos1, //in
MIL_DOUBLE ZPos1, //in
MIL_DOUBLE XPos2OrLength, //in
MIL_DOUBLE YPos2OrLength, //in
MIL_DOUBLE ZPos2OrLength //in
)
Description

This function sets the extraction box used when generating a depth map. This function must be called prior to calling M3dmapExtract().

All coordinates are expressed in the relative coordinate system of the specified 3D reconstruction result buffer.

The edges of the extraction box are inclusive, which means that points in the point cloud that touch the extraction box are included in the depth map. If one or more of the dimensions of the extraction box are specified as zero, this creates a two-dimensional or one-dimensional extraction box. In this case, only those points that touch the extraction box exactly are included in the depth map. Consequently, to create a depth map representing a single slice or a single line of the point cloud, it is typically preferable to specify very small widths, rather than a zero width.

When setting the extraction box, it is important to take into account the results displacement mode, which specifies whether on-going conveyor movement is included in an object's coordinates. If conveyor displacement is included (M3dmapControl() with M_RESULTS_DISPLACEMENT_MODE set to M_CURRENT), you typically place the extraction box ahead of the laser plane, so that the object has at least partially passed through the laser plane before entering the box. The generated depth map will include whatever portions of objects are in the extraction box at the moment that you call M3dmapExtract(). For more information, see the Specifying the extraction box when including Y-axis displacement subsection of the Generating fully corrected depth and intensity maps section of Chapter 18: 3D reconstruction using laser line profiling.

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
Result3dmapId

Specifies the identifier of the 3D reconstruction result buffer for which to specify the extraction box. The 3D reconstruction result buffer must be a point cloud container, which means it must have been allocated on the required system using M3dmapAllocResult() with M_POINT_CLOUD_CONTAINER.

BoxType

Specifies the type of box to set.

function map For specifying the type of box
CollapseValue Description
Collapse M_DEFAULT

Same as M_EXTRACTION_BOX.
Collapse M_EXTRACTION_BOX

Specifies to set the extraction box used when generating a depth map of the point clouds in the specified result buffer.
BoxDefinitionType

Specifies how the extraction box is defined.

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

XPos1OrSource

Specifies the X-coordinate of the first point used to define the extraction box, or specifies a MIL identifier used to define the extraction box.

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

YPos1

Specifies the Y-coordinate of the first point used to define the extraction box. When not in use, set this parameter to M_DEFAULT.

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

ZPos1

Specifies the Z-coordinate of the first point used to define the extraction box. When not in use, set this parameter to M_DEFAULT.

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

XPos2OrLength

Specifies the X-coordinate of the second point used to define the extraction box, or the length of the extraction box along the X-axis. When not in use, set this parameter to M_DEFAULT.

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

YPos2OrLength

Specifies the Y-coordinate of the second point used to define the extraction box, or the length of the extraction box along the Y-axis. When not in use, set this parameter to M_DEFAULT.

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

ZPos2OrLength

Specifies the Z-coordinate of the second point used to define the extraction box, or the length of the extraction box along the Z-axis. When not in use, set this parameter to M_DEFAULT.

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

Parameter associations

The table below lists possible values for the BoxDefinitionType, XPos1OrSource, YPos1, ZPos1, XPos2OrLength, YPos2OrLength, and ZPos2OrLength parameters.

function map For specifying the box world coordinates
CollapseBoxDefinitionType Description
XPos1OrSource
YPos1
ZPos1
XPos2OrLength
YPos2OrLength
ZPos2OrLength
Collapse M_BOTH_CORNERS

Specifies to define the extraction box using any two opposite corners.

(summarize)
Collapse XPos1OrSource

Specifies the X-coordinate of one corner of the extraction box.
Collapse YPos1

Specifies the Y-coordinate of one corner of the extraction box.
Collapse ZPos1

Specifies the Z-coordinate of one corner of the extraction box.
Collapse XPos2OrLength

Specifies the X-coordinate of the second corner of the extraction box, opposite to the first corner.
Collapse YPos2OrLength

Specifies the Y-coordinate of the second corner of the extraction box, opposite to the first corner.
Collapse ZPos2OrLength

Specifies the Z-coordinate of the second corner of the extraction box, opposite to the first corner.
Collapse M_BOUNDING_BOX

Specifies that the extraction box is defined by computing the axis-aligned bounding box of the specified point cloud(s) in the result buffer. The axis-aligned bounding box is the extraction box that contains all the points in the point cloud, where the axes of the extraction box are aligned with the axes of the relative coordinate system.

To limit any outlying points in the bounding box, use M3dmapControl() with M_BOUNDING_BOX_ALGORITHM specifying the 3D reconstruction result buffer.

Note that if all the points of the specified point clouds are set to M_INVALID_POINT, the box will be reset to its undefined state.

(summarize)
Collapse XPos1OrSource

Specifies the point cloud(s) within the result buffer around which to define the bounding box.

(summarize)
Collapse

Specifies to compute the bounding box of the point cloud with the given index.

(summarize)
Parameters

Specifies the array index of an existing point cloud.
Collapse

Specifies to compute the bounding box of the point cloud with the given label.

(summarize)
Parameters

Specifies the label of an existing point cloud.
Collapse M_ALL

Specifies to compute the bounding box around all the points in all the point clouds in the result buffer.
Collapse M_CENTER_AND_DIMENSION

Specifies that the extraction box is defined by its center point and its length along each axis.

Note that you can determine the coordinates of the corners of the extraction box by taking a coordinate from the center point and adding or subtracting half the box's length, along the coordinate's axis. For example, the Y-coordinates of the corners of the extraction box are YPos1 ± (YPos2OrLength /2).

(summarize)
Collapse XPos1OrSource

Specifies the X-coordinate of the center of the extraction box.
Collapse YPos1

Specifies the Y-coordinate of the center of the extraction box.
Collapse ZPos1

Specifies the Z-coordinate of the center of the extraction box.
Collapse XPos2OrLength

Specifies the length of the extraction box along the X-axis.
Collapse YPos2OrLength

Specifies the length of the extraction box along the Y-axis.
Collapse ZPos2OrLength

Specifies the length of the extraction box along the Z-axis.
Collapse M_CORNER_AND_DIMENSION

Specifies that the extraction box is defined by one of its corners and its length (or negative length) along each axis.

A positive value for length extends the extraction box in the direction of the positive axis, starting from the specified corner point. A negative value extends the extraction box in the direction of the negative axis, starting at the specified corner point. For example, if the specified corner is (1, 1, 1) and the value of the X, Y, and Z lengths are all positive 3 (a cube), the coordinates of the corner opposite the specified corner would be (4, 4, 4). If the X length were -3, while the other two lengths remained positive 3 (still a cube), the coordinates of the corner opposite the specified corner would be (-2, 4, 4).

(summarize)
Collapse XPos1OrSource

Specifies the X-coordinate of one corner of the extraction box.
Collapse YPos1

Specifies the Y-coordinate of one corner of the extraction box.
Collapse ZPos1

Specifies the Z-coordinate of one corner of the extraction box.
Collapse XPos2OrLength

Specifies the length of the extraction box along the X-axis.
Collapse YPos2OrLength

Specifies the length of the extraction box along the Y-axis.
Collapse ZPos2OrLength

Specifies the length of the extraction box along the Z-axis.
Collapse M_DEPTH_MAP

Specifies to use an extraction box derived from the depth map in the specified image buffer.

By specifying M_DEPTH_MAP, you automatically set the value of M3dmapControl() with M_EXTRACTION_SCALE_MODE to M_USER_DEFINED. This also automatically sets the values of M_PIXEL_SIZE_X, M_PIXEL_SIZE_Y, and M_GRAY_LEVEL_SIZE_Z to the values used to generate the depth map in the specified image buffer.

(summarize)
Collapse XPos1OrSource

Specifies the depth map whose calibration information will be used to define the extraction box and set the world-to-pixel scale.

(summarize)
Collapse MIL 3D depth map image buffer identifier

Specifies the identifier of a depth map image buffer.
Compilation information
Header Include mil.h.
Library Use mil.lib; mil3dmap.lib.
DLL Requires mil.dll; mil3dmap.dll.
DEFAULT EXTRACTION BOX BOTH CORNERS BOUNDING BOX ALL CENTER AND DIMENSION CORNER AND DIMENSION DEPTH MAP TRUE