| Customize Help
| Save Settings

M3dmetVolume


Function Map
Syntax
Description
Parameters
- SrcContainerOrImageBufId
Table: For specifying the container or depth map
- Reference3dgeoOrImageBufId
Table: For specifying the reference MIL object
- Options
Table: For specifying the condition
- ControlFlag
- VolumePtr
- StatusPtr
Table: For retrieving the status of the volume operation
Return value
Compilation information
Synopsis
Computes the volume of a point cloud's mesh or of a depth map, delimited optionally by a specified reference object.
Syntax
MIL_DOUBLE M3dmetVolume(
MIL_ID SrcContainerOrImageBufId, //in
MIL_ID Reference3dgeoOrImageBufId, //in
MIL_INT64 Options, //in
MIL_INT64 ControlFlag, //in
MIL_DOUBLE *VolumePtr, //out
MIL_INT64 *StatusPtr //out
)
Description

This function calculates the volume of a point cloud's mesh or of a depth map, delimited optionally by a specified reference object.

If the source MIL object is not sufficient to define a closed volume, you must specify a reference object. This function extends the boundaries of the source MIL object (and for a mesh, its holes) onto the reference MIL object to define the closed 3D shape whose volume to calculate. How the boundaries extend onto the reference MIL object depends on the type of the source MIL object. If the boundaries of a mesh are extended, they will be extended perpendicular to the reference MIL object. If the boundaries of a depth map are extended, they will be extended in the Z-direction until they meet the reference MIL object.

Even if not required, you can specify a reference object to limit the volume to calculate. You can use the Options parameter to specify how the position of the reference MIL object, relative to enclosed shape, defines the volume calculation. For example, if you use a 3D plane geometry as the reference object of a mesh, you can specify whether to calculate the volume of the mesh above or below the plane.

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 point cloud or depth map for which to calculate the volume.

function map For specifying the container or depth map
Click to summarizeValue Description
Click to summarize Depth map image buffer identifier

Specifies the identifier of the depth map image buffer to use as the source MIL object. 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).

This image buffer can have a region of interest (ROI) associated with it, in raster format. Only points inside the ROI will be used in the volume calculation.

Any invalid points in the depth map are treated like holes, but you can use M3dimFillGaps() to fill them before using this function.

The function will compute the volume of the enclosed shape defined by the depth map, a reference object, and planes defined by the extension of the edges of the depth map to the reference MIL object in the Z-direction.

(summarize)
Click to summarize MIL meshed point cloud container identifier

Specifies the identifier of the container, containing a 3D-processable meshed point cloud, to use as the source MIL object.

The container must be 3D-processable (that is, if you call MbufInquireContainer() with M_3D_PROCESSABLE, the function returns M_PROCESSABLE).

The container must contain a mesh component. If the mesh does not contain any holes, the function computes the volume of the mesh, optionally delimited by the reference object. If the mesh contains holes, the function will compute the volume of the enclosed shape defined by the mesh, the reference object, and the planes defined by the extension of the edges of the mesh to the reference object at a perpendicular angle.

For more detailed information on how the volume is calculated for meshes with holes, see the Calculating a volume section of Chapter 33: 3D metrology.

(summarize)
Reference3dgeoOrImageBufId

Specifies the reference MIL object to use to define a closed 3D shape whose volume to calculate.

function map For specifying the reference MIL object
Click to summarizeValue Description
Click to summarize M_DEFAULT

Specifies to perform the default behavior.

If the source MIL object is a point cloud container, the default behavior is the same as M_NULL.

If the source MIL object is a depth map image buffer, the default behavior is the same as M_XY_PLANE.

(summarize)
Click to summarize M_NULL

Specifies to not use a reference MIL object for defining the volume to calculate.

M_NULL can only be specified when calculating the volume of meshes without any holes.

(summarize)
Click to summarize M_XY_PLANE

Specifies to use the XY (Z=0) plane as the reference MIL object.

If the source MIL object is a point cloud container, holes in the mesh are allowed, and the boundaries of the holes in the mesh are extended to the XY-plane at an angle perpendicular to the plane.

If the source MIL object is a depth map image buffer, the boundaries of the holes in the depth map are extended in the Z-direction to the XY-plane.

(summarize)
Click to summarize 3D plane geometry object identifier

Specifies the identifier of the 3D plane geometry object to use as the reference MIL object. The 3D plane geometry object must have been previously allocated using M3dgeoAlloc() with M_GEOMETRY, and defined as a plane.

If the source MIL object is a point cloud container, holes in the mesh are allowed, and the boundaries of the holes in the mesh are extended to the reference plane at an angle perpendicular to the plane.

If the source MIL object is a depth map image buffer, the boundaries of the holes in the depth map are extended in the Z-direction to the reference plane.

(summarize)
Click to summarize Depth map image buffer identifier

Specifies the identifier of the depth map image buffer to use as the reference MIL object. This is only usable with a depth map as the source MIL object.

When both source and reference MIL objects are depth map image buffers, their calibration information can vary in Z, but not in X and Y. That is, the image buffer specified with SrcContainerOrImageBufId must have the same camera calibration information for X and Y as the image buffer specified with Reference3dgeoOrImageBufId. 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)
Options

Specifies how to calculate the total volume, given the position of the source MIL object relative to the reference object. If you are calculating the volume of a point cloud without any reference MIL object, set this parameter to M_DEFAULT.

If the reference object is a plane, any volume on the same side as the plane's normal is considered to be above the plane.

If the reference object is a depth map, a given pixel in the source depth map (at a certain X- and Y-coordinate) is considered above a pixel (at the same X- and Y-coordinate) in the reference depth map if its Z-coordinate is greater.

function map For specifying the condition
Click to summarizeValue Description
Click to summarize M_DEFAULT

Same as M_TOTAL.
Click to summarize M_ABOVE

Specifies that the total volume is equal only to the volume above the reference MIL object. Any volume below the reference MIL object is ignored.

(summarize)
Click to summarize M_DIFFERENCE

Specifies that the total volume is calculated as the volume above the reference MIL object, minus the volume below the reference MIL object.
Click to summarize M_TOTAL

Specifies that the total volume is calculated as the sum of all volumes between the source and reference MIL objects, whether above or below the reference MIL object.
Click to summarize M_UNDER

Specifies that the total volume is equal only to the volume under the reference MIL object. Any volume above the reference MIL object is ignored.

(summarize)
ControlFlag

Reserved for future expansion and must be set to M_DEFAULT.

VolumePtr

Specifies the address of the variable in which to write the calculated volume. Since this function also returns the volume, this parameter can be set to M_NULL.

StatusPtr

Specifies the address of the variable in which to write the status of the volume calculation.

function map For retrieving the status of the volume operation
Click to summarizeValue Description
Click to summarize M_FAIL_GAPS

Specifies that the volume was not successfully computed, since the source MIL object was a mesh with gaps, and there was no reference MIL object.
Click to summarize M_FAIL_INVALID_MESH

Specifies that the volume was not successfully computed, since the mesh was not usable.
Click to summarize M_SUCCESS

Specifies that the volume was successfully computed.
Click to summarize M_WARNING_GAPS

Specifies that the volume was successfully computed, but there were gaps in the specified source depth map. The gaps were ignored in the volume calculation.

(summarize)
Return value
The returned value is the computed volume, if successful. If the volume calculation fails, M_NULL is returned.
Compilation information
Header Include mil.h.
Library Use mil.lib; mil3dmet.lib.
DLL Requires mil.dll; mil3dmet.dll.
UNSIGNED TRUE RASTER VECTOR AND RASTER PROC TRUE DEFAULT NULL XY PLANE PLANE UNSIGNED RASTER VECTOR AND RASTER DEFAULT ABOVE DIFFERENCE TOTAL UNDER FAIL GAPS FAIL INVALID MESH SUCCESS WARNING GAPS