| Customize Help

Calculating statistics on a point cloud or depth map


You can extract a variety of statistical information from a point cloud or depth map. Using M3dimStat(), you can calculate:

If you require statistics from distance measurements between a point cloud or depth map and a reference object, use M3dmetStat(). See the Calculating distance measurements and statistics section of Chapter 33: 3D metrology for more information.

Except when otherwise mentioned, everything in this section that refers to point clouds also includes depth maps.

Steps to performing a statistics calculation

The following steps provide a basic methodology for calculating statistics using the 3D Image Processing module.

  1. Optionally, allocate a custom statistics 3D image processing context using M3dimAlloc() with M_STATISTICS_CONTEXT. With a custom context, you can enable and calculate multiple statistics.

    Note that if you want to evaluate a single statistics calculation, you can call M3dimStat() with a predefined statistics 3D image processing context, without having to allocate a statistics 3D image processing context beforehand. M3dimStat() will calculate the required statistics using default settings.

  2. Allocate a statistics 3D image processing result buffer using M3dimAllocResult() with M_STATISTICS_RESULT.

  3. If required, use M3dimControl() to enable the required statistics calculation (for example, to enable bounding box statistics, set M_BOUNDING_BOX to M_ENABLE). This step is necessary if you are using a custom statistics 3D image processing context.

  4. Call M3dimStat() with an appropriate statistics context (custom or predefined), a statistics result buffer, and the point cloud container or depth map image buffer for which to calculate the required statistics.

  5. Retrieve results using M3dimGetResult() and M3dimCopyResult().

Determining the bounding box of a point cloud

The bounding box of a point cloud is the smallest axis-aligned box that contains, by default, all the valid points in a point cloud. To calculate the bounding box, specify the M_STAT_CONTEXT_BOUNDING_BOX predefined context or use a custom context with M_BOUNDING_BOX enabled. You can compute the bounding box's dimensions, as well as its minimum and maximum coordinate points.

The default setting (M3dimControl() with M_ALL_POINTS) calculates a bounding box that includes all valid points. Note that you can refine your bounding box, typically to limit outliers, using M3dimControl() with M_BOUNDING_BOX_ALGORITHM set to M_ROBUST. In this case, you must specify the outlier ratio with M_BOUNDING_BOX_OUTLIER_RATIO_X, M_BOUNDING_BOX_OUTLIER_RATIO_Y, and M_BOUNDING_BOX_OUTLIER_RATIO_Z. The outlier ratio is the fraction of the total number of points whose coordinates place the points in outlier positions, and therefore outside of the bounding box. For example, if you set all M_BOUNDING_BOX_OUTLIER_RATIO_... values to 0.01, the calculation rejects the furthest 1 percent of points.

You can copy the bounding box to a 3D box geometry using M3dimCopyResult() with M_BOUNDING_BOX. Whereas, you can use M3dimGetResult() to retrieve the coordinates of the center of the bounding box (M_BOX_CENTER_X, M_BOX_CENTER_Y, and M_BOX_CENTER_Z), the bounding box's dimensions (M_SIZE_X, M_SIZE_Y, and M_SIZE_Z), and the minimum/maximum coordinates of the bounding box (M_MIN_... or M_MAX_...).

Determining the centroid

The centroid of a point cloud is the center of mass of the point cloud. To calculate the centroid, specify the M_STAT_CONTEXT_CENTROID predefined context or use a custom context with M_CENTROID enabled. Centroid statistics include the X-, Y-, and Z-coordinates of the point cloud's centroid. To retrieve these results, use M3dimGetResult() with M_CENTROID_X, M_CENTROID_Y, and M_CENTROID_Z.

Determining distances between points

To compute distance-to-nearest-neighbor statistics, specify the M_STAT_CONTEXT_DISTANCE_TO_NEAREST_NEIGHBOR predefined context or use a custom context with M_DISTANCE_TO_NEAREST_NEIGHBOR enabled. You can calculate the average distance, the maximum distance, and the minimum distance of 3D points to their nearest neighbor. To retrieve these results, use M3dimGetResult() with M_AVG_DISTANCE_TO_NEAREST_NEIGHBOR, M_MAX_DISTANCE_TO_NEAREST_NEIGHBOR, or M_MIN_DISTANCE_TO_NEAREST_NEIGHBOR.

Determining numbers of points

To compute number-of-points statistics, specify the M_STAT_CONTEXT_NUMBER_OF_POINTS predefined context or use a custom context with M_DISTANCE_TO_NEAREST_NEIGHBOR enabled. You can calculate the total number of points, the number of points that are missing data (invalid points), and the number of valid points. Note that the sum of valid and invalid points equals the total number of points. To retrieve these results, use M3dimGetResult() with M_NUMBER_OF_POINTS_TOTAL, M_NUMBER_OF_POINTS_MISSING_DATA, or M_NUMBER_OF_POINTS_VALID.