| Customize Help
| Save Settings

M3dimCalibrateDepthMap


Function Map
Syntax
Description
Parameters
- SrcContainerBufOrGeometry3dgeoId
- DepthMapImageBufId
- IntensityMapImageBufId
- CalibrationMilObjectOrMatrix3dgeoId
- PixelSizeAspectRatio
Table: For specifying the pixel aspect ratio
- ZSign
Table: For specifying the Z-scale sign
- ControlFlag
Table: For specifying the control flag
Compilation information
Synopsis
Calibrate an image buffer based on the bounding box of a container's point cloud or an axis-aligned 3D box geometry, to prepare the buffer to hold a depth or intensity map.
Syntax
void M3dimCalibrateDepthMap(
MIL_ID SrcContainerBufOrGeometry3dgeoId, //in
MIL_ID DepthMapImageBufId, //in
MIL_ID IntensityMapImageBufId, //in
MIL_ID CalibrationMilObjectOrMatrix3dgeoId, //in
MIL_DOUBLE PixelSizeAspectRatio, //in
MIL_INT64 ZSign, //in
MIL_INT64 ControlFlag //in
)
Description

This function calibrates an image buffer based on the bounding box of a container's point cloud or an axis-aligned 3D box geometry. For a point cloud, the source container's M_COMPONENT_RANGE and M_COMPONENT_CONFIDENCE components are used to establish the bounding box. The calibration prepares the buffer to hold depth map or intensity map information. To generate a depth map from a point cloud or 3D geometry, or to generate an intensity map, use M3dimProject().

M3dimCalibrateDepthMap() sets the real-world to pixel unit scale for the image buffer, and sets the real-world to gray level scale (M_GRAY_LEVEL_SIZE_Z) for depth values.

You can set this function's PixelSizeAspectRatio to M_NULL to ensure an unconstrained pixel aspect ratio, so that source data fits completely into the depth map.

If the PixelSizeAspectRatio parameter is not set to M_NULL, there can be leftover, unused pixel rows or columns in the destination. You can specify where to place valid values in the destination image buffer with the ControlFlag parameter and M_DEFAULT or M_CENTER. In the M_DEFAULT case, the data aligns to the top left of the image buffer, and the function calculates a pixel size such that the data extends at least the breadth of one dimension, and no data is lost along the other dimension. In the M_CENTER case, valid data is centered in the image buffer and extends the full breadth of one dimension with no loss of data along the other dimension. M3dimProject() will set pixels in unused rows or columns to the invalid pixel value. Note that the calculated pixel size does not distort the world data and the overall aspect ratio of source information is maintained. Also note that a projected point retains its source coordinate values, regardless of whether the corresponding pixel is centered (M_CENTER) or not (M_DEFAULT). This means that the depth map's top-left pixel will have different world XY-coordinates, depending on the ControlFlag setting. See the Specifying data placement in the destination image buffer subsection of the Generating fully corrected depth and intensity maps section of Chapter 32: 3D image processing for more information.

By default, the relative coordinate system is set to the same location as the absolute coordinate system. You can optionally set the relative coordinate system to a different location by specifying (with CalibrationMilObjectOrMatrix3dgeoId) a calibration context, a calibrated MIL object, or a transformation matrix object. Note that the pixel-to-world mapping of the specified calibration context or calibrated MIL object is not used.

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
SrcContainerBufOrGeometry3dgeoId

Specifies the identifier of the source point cloud container or 3D geometry object.

The point cloud container must be 3D-processable (that is, if you call MbufInquireContainer() with M_3D_PROCESSABLE, the function returns M_PROCESSABLE). The container must have been previously allocated using MbufAllocContainer() with M_PROC.

The 3D geometry object must be an axis-aligned box, previously allocated using M3dgeoAlloc() with M_GEOMETRY, and defined as a box.

DepthMapImageBufId

Specifies the identifier of the destination image buffer with which to associate the calibration information for a depth map.

The destination image buffer must be a 1-band, 8-bit, 16-bit or 32-bit unsigned image buffer.

IntensityMapImageBufId

Specifies the identifier of the destination image buffer with which to associate the calibration information for an intensity map. This image buffer must have the same dimensions as the buffer specified for DepthMapImageBufId.

If an intensity map is not required, set this parameter to M_NULL.

CalibrationMilObjectOrMatrix3dgeoId

Specifies the identifier of the MIL object that defines the relationship between the relative and absolute coordinate systems in the depth map. The MIL object can be a camera calibration context, a 3D reconstruction context, a 3D reconstruction result buffer, or any object that has camera calibration information, such as an image or result buffer. It can also be a transformation matrix object, previously allocated using M3dgeoAlloc() with M_TRANSFORMATION_MATRIX. If no calibration context or object associated with a camera calibration context is required, set this parameter to M_NULL.

PixelSizeAspectRatio

Specifies how to adjust the X and Y pixel sizes.

function map For specifying the pixel aspect ratio
Click to summarizeValue Description
Click to summarize M_DEFAULT

Specifies the default value; the default value is 1.0.
Click to summarize M_NULL

Specifies to apply a pixel aspect ratio such that the source container's bounding box or the axis-aligned box fits exactly inside the dimensions of the destination image buffer.
Click to summarize Value > 0.0

Specifies an aspect ratio for the destination pixels. The pixel size is computed such that the pixel's length in X divided by its length in Y equals the specified PixelSizeAspectRatio value.

(summarize)
ZSign

Specifies the sign of the Z-scale. The sign applies to M_GRAY_LEVEL_SIZE_Z, which sets the length, in world units, of one gray level in a fully-corrected depth map.

function map For specifying the Z-scale sign
Click to summarizeValue Description
Click to summarize M_DEFAULT

Same as M_POSITIVE.
Click to summarize M_NEGATIVE

Specifies a negative value for M_GRAY_LEVEL_SIZE_Z. A negative value indicates that larger Z-values are represented by darker depth map pixels, and the smaller the Z-value the brighter the pixel.

(summarize)
Click to summarize M_POSITIVE

Specifies a positive value for M_GRAY_LEVEL_SIZE_Z. A positive value indicates that larger Z-values are represented by brighter depth map pixels, and the smaller the Z-value the darker the pixel.

(summarize)
ControlFlag

Specifies where to place valid values in the depth map. When PixelSizeAspectRatio is set to M_NULL, ControlFlag must be set to M_DEFAULT.

function map For specifying the control flag
Click to summarizeValue Description
Click to summarize M_DEFAULT

Specifies that, once M3dimProject() is called, the point cloud or 3D geometry data is projected onto the depth map image buffer such that it aligns to the top left of the image buffer, and the data extends at least the breadth of one dimension, leaving space at the bottom or right. M3dimProject() will set pixels in unused rows or columns to the invalid pixel value. The source data maintains its aspect ratio.

(summarize)
Click to summarize M_CENTER

Specifies that, once M3dimProject() is called, the point cloud data is projected onto the depth map image buffer such that it is centered horizontally or vertically in the image buffer. M3dimProject() will set pixels in unused rows or columns to the invalid pixel value. The source data maintains its aspect ratio.

(summarize)
Compilation information
Header Include mil.h.
Library Use mil.lib; mil3dim.lib.
DLL Requires mil.dll; mil3dim.dll.
TRUE BOX NOT PROCESSABLE UNSIGNED NULL DEFAULT NULL DEFAULT NEGATIVE POSITIVE DEFAULT CENTER