| Customize Help
| Save Settings

M3dimProject


Function Map
Syntax
Description
Parameters
- SrcContainerBufOrGeometry3dgeoId
Table: For specifying the source container or 3D geometry object identifier
- DepthMapImageBufId
- IntensityMapImageBufId
- ProjectionMode
Table: For specifying the projection mode
- OverlapMode
Table: For specifying the overlap mode
- Options
Table: For specifying the option
- ControlFlag
Compilation information
Synopsis
Project a point cloud or 3D geometry onto the XY (Z=0) plane to generate a fully corrected depth map.
Syntax
void M3dimProject(
MIL_ID SrcContainerBufOrGeometry3dgeoId, //in
MIL_ID DepthMapImageBufId, //in
MIL_ID IntensityMapImageBufId, //in
MIL_INT64 ProjectionMode, //in
MIL_INT64 OverlapMode, //in
MIL_INT64 Options, //in
MIL_INT64 ControlFlag //in
)
Description

This function projects a point cloud or a 3D geometry onto the XY (Z=0) plane, generating a fully corrected depth map. A depth map pixel's gray level indicates depth. M3dimProject() can also generate an intensity map image from the source container, if an appropriate component is available (M_COMPONENT_REFLECTANCE and/or M_COMPONENT_INTENSITY). An intensity map pixel's gray level indicates the luminosity of the original scene at the location represented by the corresponding pixel in the depth map.

M3dimProject() projects the points of the point cloud on the XY (Z=0) plane of its working coordinate system. To change the resulting depth map, use M3dimRotate() or M3dimMatrixTransform() to rotate or transform (respectively) the 3D points before calling M3dimProject().

To define the region of the point cloud or 3D geometry to project, the destination image buffer's size and camera calibration information are used to establish a bounding box. You can use M3dimCalculateMapSize() to establish the required destination depth map image buffer size in X and Y, and M3dimCalibrateDepthMap() to calibrate the image buffer(s).

If you want to limit which points are considered for the projection, prior to calling M3dimProject(), you can crop or mask the point cloud (using M3dimCrop() or changing the data in the source container's confidence component). For more information, see the Regions of interest subsection of the Working with 3D section of Chapter 2: Building an application.

Note that, when generating an intensity map, the source container's reflectance or intensity component provides the color or intensity for pixels in the destination image. If both components exist, only the reflectance component is considered. You cannot generate an intensity map when projecting a 3D geometry.

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 a source container or 3D geometry object.

function map For specifying the source container or 3D geometry object identifier
Click to summarizeValue Description
Click to summarize Source 3D geometry object identifier

Specifies the identifier of a 3D geometry object, except that of a box geometry object. 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.

(summarize)
Click to summarize Source container identifier

Specifies the identifier of the source container.

The 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 container must have the 2 components M_COMPONENT_RANGE and M_COMPONENT_CONFIDENCE.

(summarize)
DepthMapImageBufId

Specifies the identifier of the destination depth map image buffer, previously allocated using MbufAlloc2d(). To establish the required destination depth map image buffer size in X and Y, use M3dimCalculateMapSize().

The destination image buffer must be fully corrected (that is, if you call McalInquire() with M_DEPTH_MAP, the function returns M_TRUE). This means that the buffer must be associated with a calibration context and have a constant pixel size in X and Y; it must also have a valid Z-scale. To establish the required calibration, use M3dimCalibrateDepthMap(). Note that, depending on the Z-scale and offset of the destination image buffer, a point's Z-value can place it outside the buffer's range of possible values. By default, the point is ignored, but saturation to either 0 or the buffer's maximum value (minus 1) is possible with the Options parameter set to M_SATURATION.

The destination image buffer must be an 8-bit, 16-bit or 32-bit unsigned buffer.

IntensityMapImageBufId

Specifies the identifier of the destination intensity map image buffer. The image buffer must have the same dimensions as the buffer specified for DepthMapImageBufId. In addition, the image buffer must be an 8-bit or 16-bit unsigned, 1-band or 3-band buffer. The number of bands must be equal to that of the component M_COMPONENT_REFLECTANCE or M_COMPONENT_INTENSITY. If the container has neither M_COMPONENT_REFLECTANCE nor M_COMPONENT_INTENSITY components, or if projecting a 3D geometry, this parameter must be set to M_NULL.

ProjectionMode

Specifies the projection mode.

You must set this parameter to M_DEFAULT if the source is a 3D geometry object.

function map For specifying the projection mode
Click to summarizeValue Description
Click to summarize M_DEFAULT

Same as M_POINT_BASED.
Click to summarize M_MESH_BASED

Specifies to consider the source container's mesh component when extracting 3D points for projection into the depth map. For a meshed point cloud, each triangular face has 3 vertices, and a vertex's Z-value determines the gray level of its corresponding pixel in the depth map. The remaining pixels (in the depth map) are assigned interpolated gray levels, since they correspond to the triangular faces between the vertices (in the point cloud's mesh). The container must have an M_COMPONENT_MESH_MIL component before using the M_MESH_BASED mode.

(summarize)
Click to summarize M_POINT_BASED

Specifies to project the 3D points directly into the depth map.
OverlapMode

Specifies the overlap mode, which determines a pixel's gray level when multiple points correspond to the same destination depth map pixel.

function map For specifying the overlap mode
Click to summarizeValue Description
Click to summarize M_DEFAULT

Same as M_MAX_Z.
Click to summarize M_AVERAGE

Specifies to use the average gray level of all the 3D points projected on a single depth map pixel.
Click to summarize M_MAX_Z

Specifies to use the gray level of the 3D point with the largest Z-value, of all the 3D points projected on a single depth map pixel. Note that this value can be bright or dark, depending on whether the Z-scale is positive or negative (M3dimCalibrateDepthMap() with ZSign set to M_POSITIVE or M_NEGATIVE).

(summarize)
Click to summarize M_MIN_Z

Specifies to use the gray level of the 3D point with the smallest Z-value, of all the 3D points projected on a single depth map pixel. Note that this value can be dark or bright, depending on whether the Z-scale is positive or negative (M3dimCalibrateDepthMap() with ZSign set to M_POSITIVE or M_NEGATIVE).

(summarize)
Click to summarize M_OVERWRITE

Specifies to use the last gray level of all the 3D points projected on a single depth map pixel. This mode continually overwrites the previous gray value for the pixel. M_OVERWRITE can be marginally faster than the other overlap modes.

(summarize)
Options

Specifies additional options.

Note that you can combine the 2 values M_ACCUMULATE and M_SATURATION (that is, you can set the Options parameter to M_ACCUMULATE + M_SATURATION).

function map For specifying the option
Click to summarizeValue Description
Click to summarize M_DEFAULT

Specifies no saturation; points falling outside the depth map image buffer's grayscale range are ignored.
Click to summarize M_ACCUMULATE

Specifies not to clear the previous contents of the depth map image buffer prior to projection.
Click to summarize M_SATURATION

Specifies saturation. Note that saturation can occur, depending on the Z-scale and offset of the destination depth map image buffer. If, for a given pixel of the destination buffer, the corresponding gray level of the 3D geometry or point of the point cloud falls outside the buffer's grayscale range, the pixel will be saturated to either 0 or the buffer's maximum value, minus 1 (the maximum value is reserved to represent missing data).

(summarize)
ControlFlag

Reserved for future expansion and must be set to M_DEFAULT.

Compilation information
Header Include mil.h.
Library Use mil.lib; mil3dim.lib.
DLL Requires mil.dll; mil3dim.dll.
BOX NOT INITIALIZED NOT PROCESSABLE UNSIGNED TRUE PROC UNSIGNED PROC DEFAULT MESH BASED POINT BASED DEFAULT AVERAGE MAX Z MIN Z OVERWRITE DEFAULT ACCUMULATE SATURATION