M3dimProjectEx

Board	Supported
Host System	Yes
V4L2	Yes
Clarity UHD	Yes
Concord PoE	No
GenTL	Yes
GevIQ	Yes
GigE Vision	Yes
Indio	No
Iris GTX	Yes
Radient eV-CL	Yes
Rapixo CL	Yes
Rapixo CoF	Yes
Rapixo CXP	Yes
USB3 Vision	Yes

Project a point cloud or 3D geometry onto the XY (Z=0) plane to generate a fully corrected depth map according to the settings of the project 3D image processing context.

Syntax

void M3dimProjectEx(
    AIL_ID    ProjectContext3dimId,              //in
    AIL_ID    SrcContainerBufOrGeometry3dgeoId,  //in
    AIL_ID    AABox3dgeoId,                      //in
    AIL_ID    DstDepthMapBufId,                  //in
    AIL_INT64 Options,                           //in
    AIL_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. You can use M3dimControl to specify settings, such as the pixel aspect ratio and projection mode.

This function can be used instead of M3dimCalculateMapSize, M3dimCalibrateDepthMap, and M3dimProject. If you are projecting into a container, M3dimProjectEx can optionally allocate an M_COMPONENT_RANGE component or change the dimensions of a previously existing M_COMPONENT_RANGE component and assign the 3D properties required to produce natively calibrated coordinates before projecting. If you are projecting into an image buffer, M3dimProjectEx can be used instead of M3dimCalibrateDepthMap and M3dimProject to calibrate the destination image buffer and then project.

You can optionally specify a region of the point cloud to project using an axis-aligned 3D box geometry and M_FIT_BOX or M_USE_BOX_WORLD_SIZE.

Note that M3dimProjectEx can also project intensity values from the source container's M_COMPONENT_REFLECTANCE or M_COMPONENT_INTENSITY component, if one exists. Intensity values are projected into the destination container's M_COMPONENT_REFLECTANCE or M_COMPONENT_INTENSITY component (respectively), which is created if not previously existing in the destination container. If both components exist in the source container, only the reflectance component is considered.

M3dimProjectEx 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 M3dimProjectEx.

If you want to limit which points are considered for the projection, prior to calling M3dimProjectEx, 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 Regions of interest.

Parameters

ProjectContext3dimId (in, AIL_ID)

Specifies a project 3D image processing context.

For specifying the project 3D image processing context identifier

Value	Description
M_DEFAULT	Specifies the default project 3D image processing context of the current Aurora Imaging Library application.

Note: The operation will use default values for all project context control types (M3dimControl). | | Project 3D image processing context identifier | Specifies the identifier of a project 3D image processing context, previously allocated using M3dimAlloc with M_PROJECT_CONTEXT.

Note: If a project context is specified, the function applies the project control settings specified using M3dimControl. |

SrcContainerBufOrGeometry3dgeoId (in, AIL_ID)

Specifies a source container or 3D geometry object to project.

For specifying the source container or 3D geometry object identifier

Value	Description
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 withM_GEOMETRY, and must have been successfully defined. Supported 3D geometries include cylinder, line, plane, point, and sphere.
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. |

AABox3dgeoId (in, AIL_ID)

Specifies the identifier of the axis-aligned 3D box geometry object to use to limit the calculation to points within the box. For M_FIT_BOX and M_USE_BOX_WORLD_SIZE, the box is also used to define the calibration region. The 3D box geometry object must have been previously allocated using M3dgeoAlloc with M_GEOMETRY, and defined as a box.

DstDepthMapBufId (in, AIL_ID)

Specifies the identifier of the destination image buffer or container in which to store the depth map.

For specifying the depth map

Value	Description
Destination container identifier	Specifies the identifier of the destination container.

The destination container must have been previously allocated using MbufAllocContainer with M_PROC, and must not be a child container.

If you pass M_USE_DESTINATION to the Options parameter, the container must store data in a 3D-processable depth map format (that is, if you call MbufInquireContainer with M_3D_PROCESSABLE_DEPTH_MAP, the function returns M_TRUE). If you pass M_FIT_BOX or M_FIT_SRC_DATA to the Options parameter, an M_COMPONENT_RANGE component must exist in the container. | | Destination image buffer identifier | Specifies the identifier of the destination image buffer.

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

If you pass M_USE_DESTINATION to the Options parameter, the image buffer must contain a fully corrected depth map (that is, if you call McalInquire with M_DEPTH_MAP, the function returns M_TRUE). |

Options (in, AIL_INT64)

Specifies additional options for the destination.

For specifying the option

Value	Description
M_DEFAULT
M_AUTO (default)	Specifies to automatically choose the option.

If the source is a point cloud and the destination is a container, M_AUTO is the same as M_USE_SRC_DATA. If the source is a point cloud and the destination is an image buffer, or if the source is a finite geometry, M_AUTO is the same as M_FIT_SRC_DATA. If the source is an infinite geometry and an axis-aligned box is provided, M_AUTO is the same as M_FIT_BOX. If the source is an infinite geometry and no axis-aligned box is provided, M_AUTO is the same as M_USE_DESTINATION. | | M_FIT_BOX | Specifies to reuse the X-size and Y-size of the destination image buffer or container's range component and to choose the scales and offsets so that the axis-aligned box fits inside the destination depth map.

This option is not available when the AABox3dgeoId parameter is set to M_NULL or the destination is a container that does not have an M_COMPONENT_RANGE component. | | M_FIT_SRC_DATA | Specifies to reuse the X-size and Y-size of the destination image buffer or container's range component and to choose the scales and offsets so that the source data fits inside the destination depth map.

Note that if an axis-aligned box is provided, only points within the box are considered.

This option is not available when the source is an infinite geometry or the destination is a container that does not have an M_COMPONENT_RANGE component. | | M_USE_BOX_WORLD_SIZE | Specifies to use the axis-aligned box to determine the X-size, Y-size, scales, and offsets of the destination container's range component.

Note that the points within the box are used to determine the destination pixel sizes.

This option is not available when the AABox3dgeoId parameter is set to M_NULL, the source is a geometry, or the destination is an image buffer. | | M_USE_DESTINATION | Specifies to reuse the X-size, Y-size, and calibration information of the destination image buffer or 3D properties of the destination container's range component.

This option is only available when the destination is a fully corrected depth map image buffer or a 3D-processable depth map container. | | M_USE_SRC_DATA | Specifies to use the source data to determine the X-size, Y-size, scales, and offsets of the destination container's range component.

Note that if an axis-aligned box is provided, only points within the box are considered.

This option is not available when the source is a geometry or the destination is an image buffer. |

For accumulating data

Value	Description
M_ACCUMULATE	Specifies not to clear the previous contents of the destination depth map prior to projection. This is useful to project additional data.

ControlFlag (in, AIL_INT64)

Reserved for future expansion and must be set to M_DEFAULT.