Click here to show toolbars of the Web Online Help System: show toolbars
 

| Customize Help
| Save Settings

M3dmapArith


Function Map
Syntax
Description
Parameters
- Src1ImageBufOrGeometry3dmapId
Table: For specifying the data source of the first operand
- Src2ImageBufOrGeometry3dmapId
Table: For specifying the data source of the second operand
- DstImageBufId
- MaskBufId
Table: For specifying the mask
- Operation
Table: For specifying the operation to perform
- ControlFlag
Table: For specifying how to handle camera calibration information
Compilation information
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 camera calibration information.

All operations are performed using 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 camera 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 camera calibration information. You can, however, specify to use the existing camera 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
Click to summarizeValue Description
Click to summarize 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)
Click to summarize 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
Click to summarizeValue Description
Click to summarize 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)
Click to summarize 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
Click to summarizeValue Description
Click to summarize M_NULL

Specifies that all pixels of the destination will be written to.
Click to summarize 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 parameter to one of the following possible values.

function map For specifying the operation to perform
Click to summarizeValue Description
Click to summarize

Calculates the absolute difference between the Z-coordinates of corresponding pixels of a depth map and an operand, considering the neighborhood pixels. Typically, this is performed when comparing two depth maps of highly similar objects or features, which are slightly misaligned. M_DIST_NN() compensates for the misalignment.

This is a more robust version of the M_SUB_ABS operation, which calculates the Z-coordinate difference without considering the neighborhood of pixels.

If either operand is missing data for a certain pixel, the corresponding destination pixel is set to the value for missing data (255 or 65535 for an 8- or 16-bit depth map, respectively). For information on the underlying algorithm, see the Using arithmetic for defect detection subsection of the Operations on depth maps section of Chapter 19: 3D Analysis.

(summarize)
Parameters

Specifies the size of the neighborhood.
0 <= Value <= 255

Specifies the size of the height and width of the neighborhood, in pixels, rounded up to the next odd number. Typically, this is a value between 3 and 7.

Specifying 2 or 3 will create a 3x3 neighborhood, specifying 4 or 5 will create a 5x5 neighborhood, specifying 6 or 7 will result in a 7x7 neighborhood. The larger the value, the longer the operation will take and the more robust it will be to misalignment. Note that very large values can return insignificant results.

Note that specifying 0 or 1 will create a 1x1 neighborhood, which is no neighborhood other than the pixel. This renders this macro equivalent to the M_SUB_ABS operation.
Click to summarize

Calculates the signed difference between the Z-coordinates of corresponding pixels of a depth map and an operand, considering the neighborhood pixels. Typically, this is performed when comparing two depth maps of highly similar objects or features, which are slightly misaligned. M_DIST_NN_SIGNED() compensates for the misalignment.

This is a more robust version of the M_SUB operation, which calculates the Z-coordinate difference without considering the neighborhood of pixels.

M_DIST_NN_SIGNED() is equivalent to M_DIST_NN(), except that it returns a signed distance. If operand 1 has a higher Z-coordinate than operand 2, the returned value is positive. Otherwise the returned value is negative.

If either operand is missing data for a certain pixel, the corresponding destination pixel is set to the value for missing data (255 or 65535 for an 8- or 16-bit depth map, respectively). For information on the underlying algorithm, see the Using arithmetic for defect detection subsection of the Operations on depth maps section of Chapter 19: 3D Analysis.

(summarize)
Parameters

Specifies the size of the neighborhood.
0 <= Value <= 255

Specifies the size of the height and width of the neighborhood, in pixels, rounded up to the next odd number. Typically, this is a value between 3 and 7.

Specifying 2 or 3 will create a 3x3 neighborhood, specifying 4 or 5 will create a 5x5 neighborhood, specifying 6 or 7 will result in a 7x7 neighborhood. The larger the value, the longer the operation will take and the more robust it will be to misalignment. Note that very large values can return insignificant results.

Note that specifying 0 or 1 will create a 1x1 neighborhood, which is no neighborhood other than the pixel. This renders this macro equivalent to the M_SUB operation.
Click to summarize 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)
Click to summarize 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)
Click to summarize 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)
Click to summarize 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)
Click to summarize 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)
Click to summarize M_VALIDITY_MAP

Returns an image corresponding to the validity of each pixel in the two operands.

Operand 1

Operand 2

Return value

Return value constant

M_INVALID_POINT

M_INVALID_POINT

0

M_NO_SRC_VALID_LABEL

Valid point

M_INVALID_POINT

85

M_ONLY_SRC1_VALID_LABEL

M_INVALID_POINT

Valid point

170

M_ONLY_SRC2_VALID_LABEL

Valid point

Valid point

255

M_BOTH_SRC_VALID_LABEL

(summarize)
ControlFlag

Specifies how to handle the camera 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 camera calibration information
Click to summarizeValue Description
Click to summarize M_DEFAULT

Same as M_FIT_SCALES.

This is the only possible value for M_VALIDITY_MAP.

(summarize)
Click to summarize M_FIT_SCALES

Specifies to choose the Z-scale and Z-offset so that the values can be represented in the destination image buffer without saturation. This mode depends only on the 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.

Note that in extreme cases, M_DIST_NN() and M_DIST_NN_SIGNED() can return saturated pixels because the Euclidean distance is calculated and not just the Z-coordinate distance.

(summarize)
Click to summarize 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)
Click to summarize M_USE_DESTINATION_SCALES

Specifies to use the camera 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 camera 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 camera 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 VALIDITY MAP DEFAULT FIT SCALES SET WORLD OFFSET Z USE DESTINATION SCALES