M3dimArith

MIL_ID Src1ImageBufOrGeometry3dgeoId,	//in
MIL_ID Src2ImageBufOrGeometry3dgeoId,	//in
MIL_ID DstImageBufId,	//in
MIL_ID MaskBufId,	//in
MIL_INT64 Operation,	//in
MIL_INT64 SignMode,	//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 3D geometry, storing the resulting depth map in the specified destination image buffer. Note that M3dimArith() cannot be called with two 3D geometry operands.

Note that 3D geometries of type M_BOX are not supported for this function.

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_DEPTH_MAP and ensure that it returns M_TRUE. Note that if the two operands are images, their respective camera calibration information can vary in Z, but not in X or Y.

All operations are performed using the Z-world coordinates corresponding to the gray levels of the image operands or the surface point of a 3D 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 M3dimArith(). 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 the 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

Src1ImageBufOrGeometry3dgeoId

Specifies the first source image buffer or 3D geometry object.

For specifying the first source image buffer or 3D geometry object identifier
Value	Description
M_XY_PLANE	Specifies the first operand to be the XY (Z=0) plane.
3D geometry object identifier	Specifies the first operand to be a 3D geometry object. The 3D geometry object must have been previously allocated on the required system using M3dgeoAlloc() and must have been successfully defined. Note that 3D geometries of type M_BOX are not supported for this function. (summarize) Specifies the first operand to be a 3D geometry object. (more details...)
Image buffer identifier	Specifies the first operand to be an image buffer that contains a fully corrected depth map. The image buffer must be a 1-band, 8-bit, 16-bit, or 32-bit unsigned buffer and must contain a fully corrected depth map (that is, if you call McalInquire() with M_DEPTH_MAP, the function returns M_TRUE). 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) Specifies the first operand to be an image buffer that contains a fully corrected depth map. (more details...)

Src2ImageBufOrGeometry3dgeoId

Specifies the second source image buffer or 3D geometry object.

For specifying the second source image buffer or 3D geometry object identifier
Value	Description
M_XY_PLANE	Specifies the second operand to be the XY (Z=0) plane.
3D geometry object identifier	Specifies the second operand to be a 3D geometry object. The 3D geometry object must have been previously allocated on the required system using M3dgeoAlloc() and must have been successfully defined. Note that 3D geometries of type M_BOX are not supported for this function. (summarize) Specifies the second operand to be a 3D geometry object. (more details...)
Image buffer identifier	Specifies the second operand to be an image buffer that contains a fully corrected depth map. The image buffer must be a 1-band, 8-bit, 16-bit, or 32-bit unsigned buffer and must contain a fully corrected depth map (that is, if you call McalInquire() with M_DEPTH_MAP, the function returns M_TRUE). 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. When both operands are depth map image buffers, their calibration information can vary in Z, but not in X and Y. That is, the Src2ImageBufOrGeometry3dgeoId parameter must have the same camera calibration information for X and Y as the image buffer specified with Src1ImageBufOrGeometry3dgeoId. The operation is performed point-to-point; therefore, each respective pixel must represent the same area in the real world in X and Y. (summarize) Specifies the second operand to be an image buffer that contains a fully corrected depth map. (more details...)

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, 16-bit, or 32-bit unsigned buffer. The 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 to use as a mask, if needed.

For specifying the mask identifier
Value	Description
M_NULL	Specifies to write to all pixels in the destination image buffer; no mask will be used.
Image buffer identifier	Specifies the identifier of the image buffer to use as a mask in the arithmetic operation. Pixels in the destination image buffer corresponding to pixels set to 0 in the mask buffer are 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) Specifies the identifier of the image buffer to use as a mask in the arithmetic operation. (more details...)

Operation

Specifies the operation to perform.

For specifying the operation to perform

Value

Description

M_DIST_NN(

MIL_INT NeighborhoodSize

)

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, 65535, or 4294967295 for an 8-, 16-, or 32-bit depth map, respectively).

(summarize)

Calculates the absolute difference between the Z-coordinates of corresponding pixels of a depth map and an operand, considering the neighborhood pixels.

(more details...)

Parameters

NeighborhoodSize

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.

M_DIST_NN_SIGNED(

MIL_INT NeighborhoodSize

)

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.

(summarize)

Calculates the signed difference between the Z-coordinates of corresponding pixels of a depth map and an operand, considering the neighborhood pixels.

(more details...)

Parameters

NeighborhoodSize

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.

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.

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)

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

(more details...)

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)

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

(more details...)

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)

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

(more details...)

M_REPLACE_MISSING_DATA

Returns an image that is the same as the first source depth map, except that any missing values are replaced by their corresponding values from the second source.

This operation is available only when the first source is a depth map.

(summarize)

Returns an image that is the same as the first source depth map, except that any missing values are replaced by their corresponding values from the second source.

(more details...)

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)

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

(more details...)

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)

Subtracts the Z-coordinate of the second operand from the Z-coordinate of the first operand, and takes the absolute value of the result.

(more details...)

M_VALIDITY_MAP

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

Pixel in operand 1	Pixel in operand 2	Returned to corresponding pixel in the destination
Pixel in operand 1	Pixel in operand 2	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)

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

(more details...)

SignMode

Specifies which Z-coordinate to select for geometries with more than 1 Z-coordinate for a given pair of X- and Y-coordinates. When the two sources are depth maps, the SignMode parameter must be set to M_DEFAULT.

For specifying the sign mode
Value	Description
M_DEFAULT	Same as M_MAX_Z.
M_MAX_Z	Specifies to use the surface point with the largest Z-coordinate value.
M_MIN_Z	Specifies to use the surface point with the smallest Z-coordinate value.

ControlFlag

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

For specifying how to handle the camera calibration information of the destination image buffer
Value	Description
M_DEFAULT	Same as M_FIT_SCALES. This is the only possible value for M_VALIDITY_MAP. (summarize) Same as M_FIT_SCALES. (more details...)
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 possible range of the data, and not on the actual source depth map contents. Note that the X- and Y-scales and offsets of the destination image buffer will be set to the same values as those of the source image(s). After calling M3dimArith(), the destination image buffer will be fully 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) Specifies to choose the Z-scale and Z-offset so that the values can be represented in the destination image buffer without saturation. (more details...)
M_SET_WORLD_OFFSET_Z	Specifies to keep the same Z-scale as the first source image and to set the Z-offset so that the destination image 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 image buffer will be set to the same values as those of the source image(s). After calling M3dimArith(), the destination image buffer will be fully corrected. (summarize) Specifies to keep the same Z-scale as the first source image and to set the Z-offset so that the destination image buffer Z-range covers the center of the possible range of the data. (more details...)
M_USE_DESTINATION_SCALES	Specifies to use the camera calibration information of the destination image buffer. This means the destination must be fully corrected before calling M3dimArith(), 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() or using McalControl() with M_GRAY_LEVEL_SIZE_Z and M_WORLD_POS_Z. M3dimArith() will leave the camera calibration information of the destination image buffer unchanged. (summarize) Specifies to use the camera calibration information of the destination image buffer. (more details...)
M_USE_SOURCE1_SCALES	Specifies to use the calibration information of the first source. This option is not available when the Src1ImageBufOrGeometry3dgeoId parameter is set to M_XY_PLANE. (summarize) Specifies to use the calibration information of the first source. (more details...)
M_USE_SOURCE2_SCALES	Specifies to use the calibration information of the second source. This option is not available when the Src2ImageBufOrGeometry3dgeoId parameter is set to M_XY_PLANE. (summarize) Specifies to use the calibration information of the second source. (more details...)

Compilation information

Header	Include mil.h.
Library	Use mil.lib; mil3dim.lib.
DLL	Requires mil.dll; mil3dim.dll.