M3dimStat

Board	Supported
Host System	Yes
V4L2	Yes
Clarity UHD	Yes
Concord PoE	No
GenTL	Yes
GevIQ	Yes
GigE Vision	Yes
Indio	No
Iris GTX	Yes
Radient eV-CL	Yes
Rapixo CL	Yes
Rapixo CoF	Yes
Rapixo CXP	Yes
USB3 Vision	Yes

Compute a variety of statistics on a point cloud, depth map, or 3D geometry.

Syntax

void M3dimStat(
    AIL_ID    StatContext3dimId,                //in
    AIL_ID    AilObjectId,                      //in
    AIL_ID    StatResult3dimOrGeometry3dgeoId,  //out
    AIL_INT64 ControlFlag                       //in
)

Description

This function calculates a variety of statistics for the 3D points in a point cloud, for the real-world coordinates that correspond to pixels in a depth map, or for a 3D geometry. The specified statistics 3D image processing context establishes which statistics to calculate and how to calculate them. If you need to calculate one type of statistic and use default settings, you can use a predefined context; otherwise, use M3dimAlloc to set up a custom context that you can control using M3dimControl. For example, to calculate bounding box statistics for a point cloud or depth map, you can first enable the calculation (using M3dimControl with M_BOUNDING_BOX and M_ENABLE), and then have the algorithm compute the axis-aligned box that contains most of the points but rejects outliers (M_BOUNDING_BOX_ALGORITHM set to M_ROBUST). Note that, if you use the default M_STAT_CONTEXT_BOUNDING_BOX context, M3dimStat computes the bounding box of all valid points. Results are stored in the specified 3D statistics result buffer.

For a 3D geometry, you can calculate bounding box and centroid statistics only.

Note that, when you specify a destination 3D geometry, bounding box and centroid statistics are written directly to the specified 3D geometry object, which establishes the geometry as a 3D box or 3D point, respectively.

After calling M3dimStat, you can obtain the statistics from the result buffer using M3dimGetResult.

Note: Note that there must be a sufficient number of valid points in the source container or image buffer for the statistics to be calculated. This means that there must be at least 2 valid points for M_STAT_CONTEXT_DISTANCE_TO_NEAREST_NEIGHBOR calculations, and at least 1 valid point for all other statistics types. In the case of an insufficient number of valid points, the result is typically 0; however, PCA or fixturing matrices return the identity matrix, and PCA axes return an axis-aligned coordinate system with vector coordinates (1,0,0), (0,1,0), (0,0,1). Also note that, for moments, if the specified powers in X, Y, and Z are all 0, the result is 1; otherwise, the result is 0.

Parameters

StatContext3dimId (in, AIL_ID)

Specifies a previously allocated statistics 3D image processing context (used to evaluate multiple statistical calculations), or a predefined statistics 3D image processing context (used to evaluate a single statistical calculation).

For specifying the statistics context

Value	Description
M_STAT_CONTEXT_BOUNDING_BOX	Specifies a predefined statistics 3D image processing context with the M_BOUNDING_BOX control type (M3dimControl) set to M_ENABLE.

For a point cloud or depth map, use this predefined context to calculate bounding box statistics using the default setting (M_ALL_POINTS), which includes all valid points; no valid points exist outside the bounding box. To exclude outliers, use a custom context and compute a bounding box that contains most of the valid points instead of all of them, using M3dimControl with M_BOUNDING_BOX_ALGORITHM set to M_ROBUST.

Note that, if the destination object (StatResult3dimOrGeometry3dgeoId) is a 3D geometry, this setting writes the calculated bounding box into the specified 3D geometry object directly. | | M_STAT_CONTEXT_CENTROID | Specifies a predefined statistics 3D image processing context with the M_CENTROID control type (M3dimControl) set to M_ENABLE.

Use this predefined context to calculate centroid statistics. The centroid is the center of mass of a point cloud, depth map, or 3D geometry. Centroid statistics include the X-, Y-, and Z-coordinates of the centroid.

Note that, if the destination object (StatResult3dimOrGeometry3dgeoId) is a 3D geometry, this setting writes the calculated centroid into the specified 3D geometry object directly. | | M_STAT_CONTEXT_DISTANCE_TO_NEAREST_NEIGHBOR | Specifies a predefined statistics 3D image processing context with the M_DISTANCE_TO_NEAREST_NEIGHBOR control type (M3dimControl) set to M_ENABLE.

Use this predefined context to calculate distance-to-nearest-neighbor statistics, which include the average distance, the maximum distance, and the minimum distance of 3D points or real-world coordinates to their nearest neighbor.

Note: This predefined context is not available for 3D geometries. | | M_STAT_CONTEXT_NUMBER_OF_POINTS | Specifies a predefined statistics 3D image processing context with the M_NUMBER_OF_POINTS control type (M3dimControl) set to M_ENABLE.

Use this predefined context to calculate number-of-points statistics, which include the total number of points, the number of points that are missing data (invalid points), and the number of valid points.

Note: This predefined context is not available for 3D geometries. | | M_STAT_CONTEXT_PCA | Specifies a predefined statistics 3D image processing context with the M_PCA control type (M3dimControl) set to M_ENABLE.

Use this predefined context to calculate principle component analysis (PCA) statistics.

Note: This predefined context is not available for 3D geometries. | | M_STAT_CONTEXT_PCA_NORMALS | Specifies a predefined statistics 3D image processing context with the M_PCA control type set to M_ENABLE, the M_PCA_MODE control type set to M_ORDINARY, and the M_COMPONENT_OF_INTEREST control type set to M_COMPONENT_NORMALS_AIL (M3dimControl).

Use this predefined context to calculate principle component analysis (PCA) statistics on a point cloud's unit normal vectors.

Note: This predefined context is not available for depth maps or 3D geometries. | | M_STAT_CONTEXT_SEMI_ORIENTED_BOX | Specifies a predefined statistics 3D image processing context with the M_BOUNDING_BOX control type set to M_ENABLE and the M_BOX_ORIENTATION control type set to M_SEMI_ORIENTED (M3dimControl).

Use this predefined context to calculate semi-oriented bounding box statistics, whereby the minimum volume bounding box is axis-aligned in Z but not in X and Y. To change the axis with which the semi-oriented bounding box is aligned, use a custom context and specify the axis using M_BOX_SEMI_ORIENTED_ROTATION_AXIS. For a point cloud or depth map, specifying this predefined context calculates semi-oriented bounding box statistics using the default algorithm (M_ALL_POINTS), which includes all valid points; no valid points exist outside the semi-oriented bounding box. To exclude outliers, use a custom context and compute a semi-oriented bounding box that contains most of the valid points instead of all of them, using M3dimControl with M_BOUNDING_BOX_ALGORITHM set to M_ROBUST. | | M_STAT_CONTEXT_SURFACE_AREA | Specifies a predefined statistics 3D image processing context with the M_SURFACE_AREA control type (M3dimControl) set to M_ENABLE.

Use this predefined context to calculate the surface area of a mesh.

Note: This predefined context is only available for 3D-processable point cloud and depth map containers that have an M_COMPONENT_MESH_AIL component. | | Statistics 3D image processing context identifier | Specifies the identifier of a statistics 3D image processing context, previously allocated using M3dimAlloc with M_STATISTICS_CONTEXT.

Note: In this case, use M3dimControl to enable the statistics type(s) and specify additional control settings. |

AilObjectId (in, AIL_ID)

Specifies the identifier of the source container containing a 3D-processable point cloud or depth map, the identifier of the source depth map image buffer, or the identifier of the source 3D geometry object.

For specifying the source container, image buffer, or 3D geometry object identifier

Value	Description
Source 3D geometry object identifier	Specifies the identifier of the source 3D geometry object.

The 3D geometry object must have been previously allocated using M3dgeoAlloc withM_GEOMETRY, and must have been successfully defined. Supported 3D geometries include box, cylinder, line, point, and sphere. Note that infinite 3D geometries (such as an infinite cylinder, an infinite line, or a plane) are not supported. | | Source depth map container identifier | Specifies the identifier of the source depth map container.

The container must have been previously allocated using MbufAllocContainer with M_PROC, and must store data in a 3D-processable depth map format (that is, if you call MbufInquireContainer with M_3D_PROCESSABLE_DEPTH_MAP, the function returns M_TRUE). | | Source image buffer identifier | Specifies the identifier of the source image buffer.

The source image buffer must be a 1-band, 8-, 16-, or 32-bit unsigned buffer, and must be fully corrected (that is, if you call McalInquire with M_DEPTH_MAP, the function returns M_TRUE). The source image buffer can have a region of interest (ROI) associated with it, but it must be a raster region. Using an image buffer with a non-raster type of ROI will cause an error. | | Source point cloud container identifier | Specifies the identifier of the source point cloud container.

The container must be 3D-processable (that is, if you call MbufInquireContainer with M_3D_PROCESSABLE, the function returns M_PROCESSABLE), and must have been previously allocated using MbufAllocContainer with M_PROC. |

StatResult3dimOrGeometry3dgeoId (out, AIL_ID)

Specifies the identifier of the statistics 3D image processing result buffer, or the identifier of a 3D geometry object. The result buffer must have been allocated using M3dimAllocResult with M_STATISTICS_RESULT. The 3D geometry object must have been allocated using M3dgeoAlloc with M_GEOMETRY.

ControlFlag (in, AIL_INT64)

Reserved for future expansion and must be set to M_DEFAULT.