| Customize Help
| Save Settings

MbufConvert3d


Function Map
Syntax
Description
Parameters
- SrcContainerOrImageBufId
Table: For specifying the source container or fully corrected depth map image buffer
- DstContainerOrImageBufId
Table: For specifying the destination container or image buffer
- ExternalYArrayBufId
- DstOptions
Table: For specifying operations to apply to the data
- ControlFlag
Table: For specifying the control flag
Compilation information
Synopsis
Converts 3D data to a format that is 3D-processable and/or 3D-displayable.
Syntax
void MbufConvert3d(
MIL_ID SrcContainerOrImageBufId, //in
MIL_ID DstContainerOrImageBufId, //in
MIL_ID ExternalYArrayBufId, //in
MIL_INT64 DstOptions, //in
MIL_INT64 ControlFlag //in
)
Description

This function converts the 3D data in the specified source container or fully-corrected depth map image buffer, and stores it in the specified destination container or image buffer. If the destination is a container, the source data is converted to a point cloud format that is 3D-processable and/or 3D-displayable (depending on whether the destination container has the M_DISP or M_PROC attribute). If the destination is an image buffer and the range component of the source container stores a depth map, the source is converted to a fully corrected depth map.

You can only use an image buffer as a destination if the source is a container with a single range component, and the component has its M_3D_REPRESENTATION set to M_CALIBRATED_Z_UNIFORM_XY.

If the source and destination are both containers, all components of the source container that do not affect whether the container is 3D-processable or 3D-displayable will be copied to the destination.

In some cases, if you have container that stores incomplete or ambiguous 3D data, you can still convert it by specifying the M_COMPENSATE flag. When M_COMPENSATE is specified, MIL will try to convert the data by making assumptions about the missing or ambiguous information. For example, if the source container has a range component with the M_3D_REPRESENTATION set to M_UNCALIBRATED_Z, it will instead be treated as though it were M_CALIBRATED_Z_UNIFORM_XY. Typically, compensation should only be used for display purposes, because it can result in incorrectly calibrated 3D data in the destination container or image buffer.

If the source container has a range or disparity component with an M_3D_REPRESENTATION setting that specifies an external Y array, you must either set ExternalYArrayBufId to the MIL identifier of a buffer with an M_ARRAY attribute, or use M_COMPENSATE. Typically, this is only used when the 3D sensor, used to generate the range or disparity component, stores the position of a rotary/linear encoder to identify the position of the conveyor belt when scanning each line. In most cases, these 3D sensors transmit this information as GenICam chunk data, in which case you will need to manually extract the values immediately after the 3D data is grabbed. You can retrieve this data individually for each line using MdigControlFeature() with the feature name "ChunkScanLineSelector" and MdigInquireFeature() with the feature name "ChunkEncoderValue".

To convert the rotary encoder position values retrieved from the 3D sensor to calibrated Y-coordinates, you will need to set M_3D_SCALE_Y of the range or disparity component to a factor based on the displacement of the conveyor belt for each increment of the encoder. Your 3D sensor might be configured to set this value automatically during acquisition.

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
SrcContainerOrImageBufId

Specifies the identifier of the source container or fully corrected depth map image buffer to convert.

function map For specifying the source container or fully corrected depth map image buffer
Click to summarizeValue Description
Click to summarize MIL buffer ID

Specifies the MIL identifier of a fully corrected depth map image buffer.

The image buffer must be a 1-band, 8-bit, 16-bit, or 32-bit unsigned buffer and must store a fully-corrected depth map (that is, if you call McalInquire() with M_DEPTH_MAP, the function returns M_TRUE).

You can mark invalid data in the image buffer by associating the buffer with a region of interest (ROI) using MbufSetRegion(). Each pixel outside the ROI will be given a confidence value of 0 in the destination container. The ROI must be defined in raster format (M_RASTER or M_VECTOR_AND_RASTER). An error is generated if the ROI is only in vector format (M_VECTOR).

(summarize)
Click to summarize MIL container ID

Specifies the MIL identifier of a container to convert.

To be convertible, the source container must have exactly one component with either the component type M_COMPONENT_RANGE or M_COMPONENT_DISPARITY; the container can have other components, but it must not have more than one range or disparity component (if necessary, you can use a child container, created using MbufChildContainer(), to meet this restriction). If the container has a range component, it must have M_3D_COORDINATE_SYSTEM_TYPE set to M_CARTESIAN. The range or disparity component must also meet certain requirements, depending upon its M_3D_REPRESENTATION setting:

3D representation

Requirements

M_CALIBRATED_XYZ

A 3-band range component.

M_CALIBRATED_XYZ_UNORGANIZED

A 3-band range component with an M_SIZE_Y of 1.

M_CALIBRATED_XZ_EXTERNAL_Y

A 3-band range component, with Y values provided by passing a MIL array buffer to ExternalYArrayBufId. The Y-axis band of the range component will be ignored.

M_CALIBRATED_XZ_UNIFORM_Y

A 3-band range component, with Y values identified by multiplying the row index of each point by the range component's M_3D_SCALE_Y setting. The Y-axis band of the range component will be ignored.

M_CALIBRATED_Z

A 1-band range component.

The ControlFlag parameter must be set to M_COMPENSATE.

M_CALIBRATED_Z_EXTERNAL_Y

A 1-band range component, with Y values provided by passing a MIL array buffer to ExternalYArrayBufId.

The ControlFlag parameter must be set to M_COMPENSATE.

M_CALIBRATED_Z_UNIFORM_X_EXTERNAL_Y

A 1-band range component, with X values identified by multiplying the column index of each point by the range component's M_3D_SCALE_X setting and Y values provided by passing a MIL array buffer to ExternalYArrayBufId.

M_CALIBRATED_Z_UNIFORM_XY

A 1-band range component, with X and Y values identified by multiplying the column and row index of each point by the range component's M_3D_SCALE_X and M_3D_SCALE_Y settings, respectively.

M_UNCALIBRATED_Z

A 1-band range component.

The ControlFlag parameter must be set to M_COMPENSATE.

M_DISPARITY

A 1-band disparity component.

Typically, this setting should only be used with disparity components that have been generated using areascan stereoscopic cameras.

M_DISPARITY_EXTERNAL_Y

A 1-band disparity component, with Y values provided by passing a MIL array buffer to ExternalYArrayBufId.

Typically, this setting should only be used with disparity components that have been generated using linescan stereoscopic cameras.

M_DISPARITY_UNIFORM_Y

A 1-band disparity component, with Y values identified by multiplying the row index of each pixel by the disparity component's M_3D_SCALE_Y setting.

Typically, this setting should only be used with disparity components that have been generated using linescan stereoscopic cameras.

This function uses the 3D settings of the range or disparity component during conversion. For example, all Z-coordinates in the source container's range or disparity component will be offset by the value of M_3D_OFFSET_Z in the destination container or depth map image buffer. In the destination container, the range component will then have the M_3D_OFFSET_Z setting reset to the default value of 0.

If your 3D sensor transmits these 3D settings, they will be set automatically during acquisition. If not, you must modify the 3D settings of components directly using MbufControlContainer() with settings from the table For specifying settings useful with components that store 3D data.

Note that the M_3D_DISTANCE_UNIT setting of the range or disparity component will be copied to the range component of the destination, but will not be used during conversion.

(summarize)
DstContainerOrImageBufId

Specifies the identifier of the destination container or image buffer in which to store the converted data.

function map For specifying the destination container or image buffer
Click to summarizeValue Description
Click to summarize MIL buffer ID

Specifies the MIL identifier of a 1-band, 8-bit, 16-bit, or 32-bit unsigned image buffer. In this case, the source must be a container with a range component that stores a depth map. The depth map in the source container will be converted to a fully corrected depth map and stored in the destination image buffer. The image buffer must have been allocated with the same SizeX and SizeY settings as the range component of the source container.

This image buffer must not have a region of interest (ROI) associated with it. Using an image buffer with an ROI will cause an error.

You can only use an image buffer as a destination if the source is a container with a single range component and the component has its M_3D_REPRESENTATION setting set to M_CALIBRATED_Z_UNIFORM_XY. If ControlFlag is set to M_COMPENSATE, M_3D_REPRESENTATION can also be set to any 3D representation setting that can be interpreted as a depth map.

(summarize)
Click to summarize MIL container ID

Specifies the MIL identifier of a container that is not a child container, and has an M_DISP and/or M_PROC attribute.

To make the destination container 3D-processable and/or 3D-displayable, existing components in the destination container with the following component types might be freed, reallocated, or filled with new data:

If MbufConvert3d() reallocates existing components in the destination container, their MIL identifiers will change. You can determine the current MIL identifier of a component with a specific component type, using MbufInquireContainer() with M_COMPONENT_ID.

(summarize)
ExternalYArrayBufId

Specifies the identifier of a 1-band, 1D M_ARRAY buffer containing the Y-axis value for each row of coordinates stored in the range or disparity component of the source container. The array buffer must store one value per row in the range or disparity component of the source container.

This parameter is only used if the source range or disparity component has an M_3D_REPRESENTATION setting that requires an external Y array. Set this parameter to M_NULL if not used.

DstOptions

Specifies which operations to apply to the data during conversion.

function map For specifying operations to apply to the data
Click to summarizeValue Description
Click to summarize M_DEFAULT

Specifies to convert the data without performing extra operations.
Click to summarize M_REMOVE_NON_FINITE

Specifies to mark all non-finite 3D data in the source container as invalid during conversion. Non-finite 3D data is that which has a value of infinity, negative infinity, or NaN in the range or disparity component. This setting is only available when the source is a container.

If the destination is a container, all non-finite points are given a confidence value of 0. If the destination is an image buffer, all non-finite points are set to the maximum possible finite value, which marks them as missing or invalid.

(summarize)
ControlFlag

Specifies whether to generate an error when there is missing or ambiguous information in the source, or to compensate by making assumptions about the missing information.

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

Specifies to generate an error if conversion requires information that is missing or ambiguous in the source.
Click to summarize M_COMPENSATE

Specifies to compensate for missing or ambiguous information in the source. The following assumptions are used when compensating:

  • The coordinates in the source depth map or point cloud are uniformly spaced for any missing axes. For example, a range component with M_3D_REPRESENTATION set to M_CALIBRATED_Z_EXTERNAL_Y will be treated as though it were set to M_CALIBRATED_Z_UNIFORM_X_EXTERNAL_Y.

  • If the source is a container with no confidence information, all coordinates in the source are considered valid.

  • If the source is a container, all coordinates in the source are considered natively calibrated.

  • If M_SIZE_Y of the range component is larger than 1, then the point cloud in the container is considered organized.

  • Any components in the source container that have the same component type are not copied.

  • Any confidence, intensity, reflectance, mesh, or normals component in the source container that is not correctly formatted should be ignored.

(summarize)
Compilation information
Header Include mil.h.
Library Use mil.lib; mil3d.lib.
DLL Requires mil.dll; mil3d.dll.
UNSIGNED TRUE VECTOR CONVERTIBLE CONVERTIBLE WITH COMPENSATION UNSIGNED NONE PROC DISP DEFAULT REMOVE NON FINITE DEFAULT COMPENSATE CALIBRATED Z UNIFORM XY