| MIL 10 Reference
| Customize Help
| Save Settings

M3dmapArith


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
M3dmapAllocResult
M3dmapCalibrate
Synopsis
Perform a point-to-point arithmetic operation on depth maps and geometry objects.
Syntax
void M3dmapArith(
MIL_ID Src1ImageBufOrGeometry3dmapId, //in
MIL_ID Src2ImageBufOrGeometry3dmapId, //in
MIL_ID DstImageBufId, //in
MIL_ID MaskBufId, //in
MIL_INT64 Operation, //in
MIL_INT64 ControlFlag //in
)
Description

This function performs the specified point-to-point arithmetic operation on two depth maps or one depth map and one geometry object, storing the resulting depth map in the specified destination image buffer. Note that M3dmapArith() cannot be called with two geometry object operands.

All image operands must be fully corrected depth maps for this operation. To determine if you have a fully corrected depth map, call McalInquire() with M_GRAY_LEVEL_SIZE_Z and ensure that it does not return M_INVALID_SCALE. Moreover, if the two operands are images, they must have the same calibration information.

All operations are performed on the Z-world coordinates corresponding to the gray levels of the image operands or the surface point of a geometry operand. The resulting Z-world coordinates are then converted back to gray levels, according to the calibration information of the destination buffer. If the Z-scale and Z-offset of the destination are such that the 3D point falls outside the vertical span of the destination buffer, the destination pixel will be saturated to either 0 or the maximum value of the buffer, minus 1 (since the maximum value of a depth map represents missing data).

Some pixels of the destination buffer can be left unchanged by providing a mask image buffer with the corresponding pixels set to 0.

By default, the destination buffer does not have to be calibrated before calling M3dmapArith(). The function will fill the destination buffer and associate it with the necessary calibration information. You can, however, specify to use the existing calibration information of the destination buffer, by passing M_USE_DESTINATION_SCALES to ControlFlag parameter.

If either or both operands contain missing data (represented using the maximum value of the depth map buffer), missing data might be written to the destination buffer, depending on the value passed to the Operation parameter.

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
Src1ImageBufOrGeometry3dmapId

Specifies the data source of the first operand.

function map For specifying the data source of the first operand
CollapseValue Description
Collapse Geometry object identifier

Specifies the first operand to be a geometry object.

The geometry object must have been previously allocated on the required system using M3dmapAlloc() and must have been successfully defined using M3dmapSetGeometry().

(summarize)
Collapse Image buffer identifier

Specifies the first operand to be an image buffer that contains a depth map.

The image buffer must be a 1-band, 8-bit or 16-bit unsigned buffer and must be 3D-corrected. It must also have the same dimensions and bit depth as the destination buffer (DstImageBufId).

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.

(summarize)
Src2ImageBufOrGeometry3dmapId

Specifies the data source of the second operand.

function map For specifying the data source of the second operand
CollapseValue Description
Collapse Geometry object identifier

Specifies the second operand to be a geometry object.

The geometry object must have been previously allocated on the required system using M3dmapAlloc() and must have been successfully defined using M3dmapSetGeometry().

(summarize)
Collapse Image buffer identifier

Specifies the second operand to be an image buffer that contains a depth map.

The image buffer must be a 1-band, 8-bit or 16-bit unsigned buffer and must be 3D-corrected. It must also have the same dimensions and bit depth as the destination buffer (DstImageBufId).

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.

(summarize)
DstImageBufId

Specifies the identifier of the destination image buffer in which to put the result of the arithmetic operation. The image buffer must be a 1-band, 8-bit or 16-bit unsigned buffer.

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.

MaskBufId

Specifies the identifier of the image buffer used as a mask.

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.

function map For specifying the mask
CollapseValue Description
Collapse M_NULL

Specifies that all pixels of the destination will be written to.
Collapse Image buffer identifier

Specifies the identifier of the image buffer used as a mask in the arithmetic operation. Pixels of the destination buffer, corresponding to pixels set to 0 in the mask buffer, will be left unchanged, while the other destination pixels will be the result of the arithmetic operation. The image buffer must be a 1-band, binary, 8-bit or 16-bit buffer, and must have the same dimensions as the destination buffer (DstImageBufId).

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.

(summarize)
Operation

Specifies the operation to perform.

You can set the Operation parameter to one of the following possible values.

function map For specifying the operation to perform
CollapseValue Description
Collapse M_ADD

Adds the Z-coordinate of the first operand to the Z-coordinate of the second operand.

Destination = (Operand 1 + Operand 2).

If either operand is missing data, the destination is set to the value for missing data.

(summarize)
Collapse M_MAX

Compares the Z-coordinate of the first operand with the Z-coordinate of the second operand, and takes the greater of the two.

Destination = max(Operand 1, Operand 2).

If both operands are missing data, the destination is set to the value for missing data. If a single operand is missing data, the destination is set to the value of the other operand.

(summarize)
Collapse M_MIN

Compares the Z-coordinate of the first operand with the Z-coordinate of the second operand, and takes the lesser of the two.

Destination = min(Operand 1, Operand 2).

If both operands are missing data, the destination is set to the value for missing data. If a single operand is missing data, the destination is set to the value of the other operand.

(summarize)
Collapse M_SUB

Subtracts the Z-coordinate of the second operand from the Z-coordinate of the first operand.

Destination = (Operand 1 - Operand 2).

If either operand is missing data, the destination is set to the value for missing data.

(summarize)
Collapse M_SUB_ABS

Subtracts the Z-coordinate of the second operand from the Z-coordinate of the first operand, and takes the absolute value of the result. This operation is equivalent to taking the absolute value of the M_SUB operation.

Destination = | Operand 1 - Operand 2|.

If either operand is missing data, the destination is set to the value for missing data.

(summarize)
ControlFlag

Specifies how to handle the calibration information of the destination buffer.

You can set the ControlFlag parameter to one of the following possible values.

function map For specifying how to handle calibration information
CollapseValue Description
Collapse M_DEFAULT

Same as M_FIT_SCALES.
Collapse M_FIT_SCALES

Specifies to choose the Z-scale and Z-offset so that all possible values can be represented in the destination image buffer without saturation. This mode depends only on the possible range of the data, and not on the actual source depth map contents.

Note that the Z-scale will have the same sign as the Z-scale of the source image(s), and the X- and Y-scales and offsets of the destination buffer will be set to the same values as those of the source image(s). After calling M3dmapArith(), the destination buffer will be 3D-corrected.

(summarize)
Collapse M_SET_WORLD_OFFSET_Z

Specifies to keep the same Z-scale as the source image(s) and set the Z-offset so that the destination buffer Z-range covers the center of the possible range of the data. Since the Z-scale remains unaltered, it is possible for saturation to occur.

The X- and Y-scales and offsets of the destination buffer will be set to the same values as those of the source image(s). After calling M3dmapArith(), the destination buffer will be 3D-corrected.

(summarize)
Collapse M_USE_DESTINATION_SCALES

Specifies to use the calibration information of the destination buffer. This means the destination must be 3D-corrected before calling M3dmapArith(), and have the same scales and offsets in X and Y as the source image(s). This can be done by copying the calibration information from another image using McalAssociate(), or by providing scales and offsets manually using McalUniform() and McalControl() with M_GRAY_LEVEL_SIZE_Z and M_WORLD_POS_Z. M3dmapArith() will leave the calibration information of the destination buffer unchanged.

(summarize)
Compilation information
Header Include mil.h.
Library Use mil.lib; mil3dmap.lib.
DLL Requires mil.dll; mil3dmap.dll.
UNSIGNED TRUE PROC NONE UNSIGNED TRUE PROC NONE UNSIGNED PROC NONE NULL PROC NONE ADD MAX MIN SUB SUB ABS DEFAULT FIT SCALES SET WORLD OFFSET Z USE DESTINATION SCALES