| MIL 10 Reference
| Customize Help
| Save Settings

M3dmapSetGeometry


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
M3dmapSetBox
M3dmapStat
Synopsis
Define a geometry object, either parametrically or by fitting it to a depth map.
Syntax
void M3dmapSetGeometry(
MIL_ID Geometry3dmapId, //in
MIL_INT64 GeometryType, //in
MIL_INT64 OperationType, //in
MIL_DOUBLE Param1, //in
MIL_DOUBLE Param2, //in
MIL_DOUBLE Param3, //in
MIL_DOUBLE Param4, //in
MIL_DOUBLE Param5 //in
)
Description

This function allows you to define a geometry object, either by letting the 3D Reconstruction module compute the geometry that best fits a depth map, or by explicitly specifying the coefficients of the geometry's equation in world units.

If performing a fit operation, it is possible to specify an image buffer that acts as a mask, where pixels set to 0 will not be used in the fit. For example, masking pixels that represent a scanned object in the depth map can be useful when using the fit operation to define a new reference plane. Note that missing data (gaps) in the depth map is also ignored when fitting.

When fitting, it is also possible to specify an outlier distance along the Z-axis, beyond which no input data is considered for the fit operation. When specifying an outlier distance, the fit operation is performed in two phases. A preliminary fit is performed on all points (except those ignored if passing an image mask). Afterwards, points that are beyond the outlier distance are excluded, and a second fit operation is performed on the remaining points.

After defining a geometry object, it is possible to inquire whether the operation was successful using M3dmapInquire() with M_STATUS. After performing a successful fit operation, you can inquire the root mean squared error of the operation using M3dmapInquire() with M_FIT_RMS_ERROR. You can also inquire the geometry type using M3dmapInquire() with M_GEOMETRY_TYPE, or inquire the coefficients of the geometry's equation using M3dmapInquire() with M_FIT_PARAM_Z0, M_FIT_PARAM_AX, or M_FIT_PARAM_AY.

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
Geometry3dmapId

Specifies the identifier of a geometry object. The geometry object must have been previously allocated on the required system using M3dmapAlloc().

GeometryType INQ

Specifies the type of geometry object to define.

See the Parameter associations section for possible values that can be specified.

OperationType INQ

Specifies whether to define the geometry object by explicitly providing the coefficients of the geometry's equation or by applying a best-fit geometry operation on the depth map.

See the Parameter associations section for possible values that can be specified.

Param1

Specifies information about the geometry object used for the operation. Its definition is dependent on the specified operation and the geometry object type.

If this parameter is not used it must be set to M_DEFAULT.

See the Parameter associations section for possible values that can be specified.

Param2

Specifies information about the geometry object used for the operation. Its definition is dependent on the specified operation and the geometry object type.

If this parameter is not used it must be set to M_DEFAULT.

See the Parameter associations section for possible values that can be specified.

Param3

Specifies information about the geometry object used for the operation. Its definition is dependent on the specified operation and the geometry object type.

If this parameter is not used it must be set to M_DEFAULT.

See the Parameter associations section for possible values that can be specified.

Param4

Reserved for future expansion and must be set to M_DEFAULT.

Param5

Reserved for future expansion and must be set to M_DEFAULT.

Parameter associations

The table below lists possible values for the GeometryType, OperationType, Param1, Param2, and Param3 parameters.

function map For defining the type of geometry object used for the operation
CollapseOperationType Description
GeometryType
Param1
Param2
Param3
Collapse M_FIT

Specifies that the geometry is defined from the specified depth map. The coefficients of the geometry's equation are computed using the least-squares method to best fit the geometry to the depth map.

(summarize)
Collapse M_HORIZONTAL_PLANE

Specifies a horizontal plane described by the equation z(x,y) = z0 .

Note that z(x, y) and z0 are expressed in world units in the relative coordinate system.

(summarize)
Collapse Param1

Specifies the identifier of the image buffer representing the depth map on which to fit the horizontal plane. The identifier is cast to a MIL_DOUBLE.

The image buffer must be a 1-band, 8-bit or 16-bit unsigned buffer, and must be 3D-corrected.

(summarize)
Collapse Param2

Specifies whether to use an image mask, and if so, the image buffer to use as the image mask.

(summarize)
Collapse M_NULL

Specifies that no image mask is used.
Collapse Mask image buffer identifier

Specifies the identifier of the image buffer to use as an image mask. The identifier is cast to a MIL_DOUBLE.

The image buffer must be a 1-band, binary, 8-bit or 16-bit buffer, and must have the same dimensions as the depth map specified using Param1.

(summarize)
Collapse Param3

Specifies the outlier distance, if needed.

(summarize)
Collapse M_DEFAULT

Same as M_INFINITE.
Collapse M_INFINITE

Specifies that no pixel will be excluded when performing the fit operation (except for pixels optionally excluded by means of an image mask).
Collapse Value >= 0

Specifies the outlier vertical distance to use, in world units.
Collapse M_PLANE

Specifies an arbitrary plane described by the equation z(x,y) = z0 + Ax*x + Ay*y .

Note that z(x, y), x, y, and z0 are expressed in world units in the relative coordinate system, while A x and A y are dimensionless coefficients.

(summarize)
Collapse Param1

Specifies the identifier of the image buffer representing the depth map on which to fit the plane. The identifier is cast to a MIL_DOUBLE.

The image buffer must be a 1-band, 8-bit or 16-bit unsigned buffer, and must be a fully corrected depth map. 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.

(summarize)
Collapse Param2

Specifies whether to use an image mask, and if so, the image buffer to use as the image mask.

(summarize)
Collapse M_NULL

Specifies that no image mask is used.
Collapse Mask image buffer identifier

Specifies the identifier of the image buffer to use as an image mask. The identifier is cast to a MIL_DOUBLE.

The image buffer must be a 1-band, binary, 8-bit or 16-bit buffer, and must have the same dimensions as the depth map specified using Param1.

(summarize)
Collapse Param3

Specifies the outlier distance, if needed.

(summarize)
Collapse M_DEFAULT

Same as M_INFINITE.
Collapse M_INFINITE

Specifies that no pixel will be excluded when performing the fit operation (except for pixels optionally excluded by means of an image mask).
Collapse Value >= 0

Specifies the outlier vertical distance to use, in world units.
Collapse M_PARAMETRIC

Specifies that the geometry is explicitly defined. You must specify the coefficient(s) of the geometry's equation.

(summarize)
Collapse M_HORIZONTAL_PLANE

Specifies a horizontal plane described by the equation z(x,y) =z0 .

Note that z(x, y) and z0 are expressed in world units in the relative coordinate system.

(summarize)
Collapse Param1

Specifies the value of the coefficient z0 (Z-intercept). INQ

(summarize)
Collapse M_PLANE

Specifies an arbitrary plane described by the equation z(x,y) = z0 + Ax*x + Ay*y .

Note that z(x, y), x, y, and z0 are expressed in world units in the relative coordinate system, while A x and A y are dimensionless coefficients.

(summarize)
Collapse Param1

Specifies the value of the coefficient z0 (Z-intercept). INQ

(summarize)
Collapse Param2

Specifies the value of the coefficient A x. INQ

(summarize)
Collapse Param3

Specifies the value of the coefficient A y. INQ

(summarize)
Compilation information
Header Include mil.h.
Library Use mil.lib; mil3dmap.lib.
DLL Requires mil.dll; mil3dmap.dll.
FIT HORIZONTAL PLANE UNSIGNED TRUE PROC NULL PROC DEFAULT INFINITE PLANE UNSIGNED TRUE PROC NULL PROC DEFAULT INFINITE PARAMETRIC HORIZONTAL PLANE PLANE