| Customize Help
| Save Settings

M3dimCrop


Function Map
Syntax
Description
Parameters
- SrcContainerBufId
- DstContainerBufId
- ImageBufOrGeometry3dgeoId
Table: For specifying the mask
- Matrix3dgeoId
- OrganizationType
Table: For specifying the organization type
- ControlFlag
Table: For specifying which points to keep
Compilation information
Synopsis
Crop points in a point cloud based on a specified 3D geometry or calibrated mask image buffer.
Syntax
void M3dimCrop(
MIL_ID SrcContainerBufId, //in
MIL_ID DstContainerBufId, //in
MIL_ID ImageBufOrGeometry3dgeoId, //in
MIL_ID Matrix3dgeoId, //in
MIL_INT64 OrganizationType, //in
MIL_INT64 ControlFlag //in
)
Description

This function crops 3D points in the source container's point cloud, based on a specified 3D geometry or calibrated mask image buffer.

Source components are copied into the destination container where the destination's confidence component determines a point's viability after the crop operation. Specifically, rejected points (those cropped out) are assigned a 0 confidence value in the destination confidence component. Corresponding points in the destination range component are considered cropped out.

Note that normals and reflectance (or intensity) components are not required, but the crop operation is applied to these components if they are present in the source container.

If the crop is based on a 3D geometry, the default operation keeps points located inside the specified geometry, rejecting all others. If cropping with a mask image buffer, points are kept only if they are projected onto non-zero pixels in the mask; any points projected onto zero pixels are rejected. Note that you can specify to invert the crop operation (for example, to keep points located outside, instead of inside, the specified geometry).

You can specify how the destination container is organized (for example, as an unorganized point cloud).

If a mesh component exists in the source point cloud container, it is also affected by the crop operation. Any cropped points that correspond to the vertex of a triangular face result in that face's removal. This can result in a hole in the mesh.

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
SrcContainerBufId

Specifies the identifier of the source container containing a 3D-processable point cloud. The container must be 3D-processable (that is, if you call MbufInquireContainer() with M_3D_PROCESSABLE, the function returns M_PROCESSABLE).

The container must have been previously allocated using MbufAllocContainer() with M_PROC. The container must have the components M_COMPONENT_RANGE and M_COMPONENT_CONFIDENCE.

DstContainerBufId

Specifies the identifier of the destination container in which to store the resulting point cloud. The container must have been previously allocated using MbufAllocContainer() with M_PROC, and must not be a child container.

Note that, if the OrganizationType parameter is set to M_UNORGANIZED and there are no valid points remaining after the crop, the destination container's range component's dimensions are reduced to 1x1 and its corresponding confidence equals 0.

ImageBufOrGeometry3dgeoId

Specifies the identifier of the 3D geometry object or calibrated mask image buffer used to crop the points.

function map For specifying the mask
Click to summarizeValue Description
Click to summarize M_XY_PLANE

Specifies the XY (Z=0) plane.

Points are kept above this plane, unless M_INVERSE is specified; see the ControlFlag parameter.

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

Specifies the 3D geometry object identifier.

The 3D geometry object must have been previously allocated on the required system using M3dgeoAlloc() with M_GEOMETRY, and must have been successfully defined. Supported 3D geometries include box, cylinder, plane, and sphere.

(summarize)
Click to summarize MIL calibrated image buffer identifier

Specifies the calibrated mask image buffer. The calibrated mask must be a 1-band, 8-bit, 16-bit or 32-bit unsigned image buffer, and must not have a region of interest (ROI) associated with it. Using an image buffer with an ROI will cause an error.

When cropping using a calibrated mask image buffer, the point cloud's points are projected onto the mask image. A point is not kept if it is projected onto a zero pixel in the mask. Alternatively, to keep these points and crop out the others, set the ControlFlag parameter to M_INVERSE.

Note that, if the calibrated mask is uniformly calibrated, projection onto the mask image is orthogonal. That is, world coordinate values in the point cloud correspond linearly to pixel positions in the 2D mask image onto which the point cloud is projected. If the calibrated mask image is of type M_3D_CALIBRATION, point projection is not orthogonal, but instead follows the frustum of the camera's view, as represented by the associated camera calibration information. In either case, points that correspond to zero pixels in the calibrated mask image are cropped.

(summarize)
Matrix3dgeoId

Reserved for future expansion and must be set to M_NULL.

OrganizationType

Specifies how to organize the resulting point cloud.

function map For specifying the organization type
Click to summarizeValue Description
Click to summarize M_DEFAULT

Same as M_SAME.
Click to summarize M_SAME

Specifies to copy all the source container's components into the destination container; points set to 0 in the destination confidence component indicate cropped points.
Click to summarize M_SHRINK

Specifies to copy, from source to destination, the smallest region that holds all valid points (remaining after the crop operation) in all components; points set to 0 in the destination confidence component indicate cropped points.

Note that the region is a rectangular region within the bands of the 2D data buffers that hold point cloud data.

(summarize)
Click to summarize M_UNORGANIZED

Specifies to store results in an unorganized point cloud. Components in the destination container will store results of the crop operation in 1D, unorganized buffers.

(summarize)
ControlFlag

Specifies which points to keep, relative to the cropping object set with ImageBufOrGeometry3dgeoId.

function map For specifying which points to keep
Click to summarizeValue Description
Click to summarize M_DEFAULT

Specifies to keep points that are inside the specified 3D geometry object, above the specified plane, or not set to 0 in the specified calibrated mask, depending on the cropping object set with ImageBufOrGeometry3dgeoId.

Note that, for a plane geometry, above is in the direction of the plane normal vector. To inquire this vector, use M3dgeoInquire() with M_NORMAL_....

(summarize)
Click to summarize M_INVERSE

Specifies to keep points that are outside the specified 3D geometry object, below the specified plane, or set to 0 in the specified calibrated mask, depending on the cropping object set with ImageBufOrGeometry3dgeoId.

Note that, for a plane geometry, below is in the opposite direction of the plane normal vector. To inquire this vector, use M3dgeoInquire() with M_NORMAL_....

(summarize)
Compilation information
Header Include mil.h.
Library Use mil.lib; mil3dim.lib.
DLL Requires mil.dll; mil3dim.dll.
NOT PROCESSABLE PROC XY PLANE BOX CYLINDER PLANE SPHERE NULL UNSIGNED PROC NONE DEFAULT SAME SHRINK UNORGANIZED DEFAULT INVERSE