| MIL 10 Reference
| Customize Help
| Save Settings

M3dmapStat


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
M3dmapSetGeometry
M3dmapStream
Synopsis
Compute a variety of statistics on a depth map.
Syntax
void M3dmapStat(
MIL_ID ImageBufId, //in
MIL_ID ImageBufOrGeometry3dmapId, //in
MIL_ID MaskBufId, //in
MIL_ID Result3dmapId, //in
MIL_INT64 StatType, //in
MIL_DOUBLE OutlierDistanceWorld, //in
MIL_INT64 ControlFlag, //in
MIL_DOUBLE *StatValuePtr //out
)
Description

This function calculates a variety of statistics for the pixels that satisfy the specified condition in a depth map. Results are stored in the specified statistic result buffer.

By default, statistics are computed using the XY world plane (Z=0) as the reference level. Alternatively, you can specify a fully corrected depth map or geometry object to use as a reference level for the calculations.

You can specify a mask image using MaskBufId. Pixels set to 0 in the mask image are excluded from the statistics computation.

Any pixel that is set to the missing data value, either in the source depth map or the reference depth map (if provided) will be excluded from the statistics computation. This could have an impact, for example, when computing the volume of an object. Prior to calling M3dmapStat(), you can fill missing data using M3dmapExtract() with M_FILL_MISSING_DATA_ONLY.

After calling M3dmapStat(), results can be obtained using M3dmapGetResult() on the result buffer.

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
ImageBufId

Specifies the image buffer identifier of the depth map on which to compute statistics. The image buffer must be a 1-band, 8-bit or 16-bit unsigned buffer and must be 3D-corrected.

This image buffer must not have a region of interest (ROI) associated with it. Using an image buffer with an ROI will cause an error.

ImageBufOrGeometry3dmapId

Specifies what will be used as reference level for statistics computation.

You can set the ImageBufOrGeometry3dmapId parameter to one of the following values.

function map For specifying the reference level
CollapseValue Description
Collapse M_NULL

Specifies that the XY world plane (Z=0) will be used as the reference level.
Collapse Geometry object identifier

Specifies the identifier of the geometry object to use as the reference level. The geometry object must have been previously allocated on the required system using M3dmapAlloc() and must have been successfully defined using M3dmapSetGeometry().

(summarize)
Collapse Image buffer identifier

Specifies the image buffer identifier of the depth map to use as the reference level. The image buffer must be a 1-band, 8-bit or 16-bit unsigned buffer and must be 3D-corrected. It must also have the same dimensions and the same calibration information as the image buffer specified using ImageBufId.

This image buffer must not have a region of interest (ROI) associated with it. Using an image buffer with an ROI will cause an error.

(summarize)
MaskBufId

Specifies the identifier of the image buffer to use as a mask, if needed.

You can set the MaskBufId parameter to one of the following values.

function map For specifying the mask
CollapseValue Description
Collapse M_NULL

Specifies to consider all pixels of the source depth map; no mask will be used.
Collapse Image buffer identifier

Specifies the identifier of the image buffer to use as a mask while computing statistics. Pixels of the source depth map corresponding to pixels set to 0 in the mask buffer will not be considered in the statistics.

The image buffer must be a 1-band, binary, 8-bit or 16-bit buffer, and must have the same dimensions as the image buffer given in ImageBufId.

This image buffer must not have a region of interest (ROI) associated with it. Using an image buffer with an ROI will cause an error.

(summarize)
Result3dmapId

Specifies the result buffer identifier, if needed.

You can set the Result3dmapId parameter to one of the following values.

function map For specifying the result buffer
CollapseValue Description
Collapse M_NULL

Specifies that no result buffer is needed. In that case, the StatValuePtr parameter must not be M_NULL and the StatType parameter must not be M_DEFAULT.

(summarize)
Collapse 3D reconstruction statistics result buffer
identifier

Specifies the identifier of an M_STAT_RESULT 3D reconstruction result buffer. The result buffer must have been previously allocated on the required system using M3dmapAllocResult() with M_STAT_RESULT.

(summarize)
StatType

Specifies what statistics to compute. When using a result buffer to hold the results, all statistics are computed and this parameter must be set to M_DEFAULT. If a single statistic is needed, StatType specifies which one. In that case, it is not necessary to allocate a result buffer; the result is returned directly at the address given to StatValuePtr.

You can set the StatType parameter to one of the following values.

function map For specifying the statistics to compute
CollapseValue Description
Collapse M_DEFAULT

Specifies to compute all possible statistics. In this case, you must pass Result3dmapId a valid result buffer identifier.

(summarize)
Collapse M_DEVIATION_MAX +

Specifies to calculate the maximum height between depth map and reference level (always positive).
Collapse M_DEVIATION_MEAN +

Specifies to calculate the average height between depth map and reference level.
Collapse M_NUMBER_OF_PIXELS_MISSING_DATA

Specifies to determine the number of pixels that were not taken into account while computing statistics because they were set to the missing data value, either in the depth map or the reference level.
Collapse M_NUMBER_OF_PIXELS_OUTLIER +

Specifies to determine the number of pixels that were not taken into account while computing statistics because the distance between the depth map and the reference level at those coordinates was beyond the outlier threshold.
Collapse M_NUMBER_OF_PIXELS_TOTAL

Specifies to determine the total number of pixels that were considered while computing statistics. This number corresponds to the number of pixels in the depth map, or the number of pixels that are not 0 in the mask buffer if it was provided. This value is also the sum of M_NUMBER_OF_PIXELS_VALID, M_NUMBER_OF_PIXELS_OUTLIER, and M_NUMBER_OF_PIXELS_MISSING_DATA.

(summarize)
Collapse M_NUMBER_OF_PIXELS_VALID +

Specifies to determine the number of pixels that were taken into account while computing statistics.
Collapse M_VOLUME +

Specifies to calculate the volume contained between the depth map and the reference level.

You can add one of the following values to the above-mentioned values to specify which pixels to take into account.

function map For specifying which pixels to take into account
CollapseCombination value Description
Collapse M_STAT_ABS

Specifies to take into account all valid pixels, treating all vertical distances as positive.

Note that this value can only be used with M_DEVIATION_MEAN and M_VOLUME.

(summarize)
Collapse M_STAT_ALL

Specifies to take into account all valid pixels. This is the default behavior if no combination value is added.

(summarize)
Collapse M_STAT_NEGATIVE

Specifies to take into account only the pixels for which going from the reference level to the depth map is in the negative Z-direction. Statistics will be measured in the negative Z-direction, so they will all be positive.

(summarize)
Collapse M_STAT_POSITIVE

Specifies to take into account only the pixels for which going from the reference level to the depth map is in the positive Z-direction.
OutlierDistanceWorld

Specifies the outlier distance to use to exclude pixels from the statistics.

You can set the OutlierDistanceWorld parameter to one of the following values.

function map For specifying the outlier distance
CollapseValue Description
Collapse M_DEFAULT

Same as M_INFINITE.
Collapse M_INFINITE

Specifies an infinite outlier distance; no depth map points will be excluded from the statistics calculation based on their distance from the reference level.
Collapse Value >= 0

Specifies the outlier vertical distance to use, in world units. All 3D points of the source depth map which are farther than this distance from the reference level will not be considered in the statistics. When ImageBufOrGeometry3dmapId is set to M_NULL, the XY world plane (Z=0) is considered as the reference level.

(summarize)
ControlFlag

Reserved for future expansion and must be set to M_DEFAULT.

StatValuePtr

Specifies where to write the results, if needed.

You can set the StatValuePtr parameter to one of the following values.

function map For specifying where to write the results
CollapseValue Description
Collapse M_NULL

Specifies to use the result buffer to hold all computed statistics. In this case, Result3dmapId must not be M_NULL and StatType must be set to M_DEFAULT. You can retrieve results from the result buffer using M3dmapGetResult().

(summarize)
Collapse Address of a MIL_DOUBLE

Specifies to compute the statistic specified using StatType, and write the result at this address. In this case, Result3dmapId must be set to M_NULL.

(summarize)
Compilation information
Header Include mil.h.
Library Use mil.lib; mil3dmap.lib.
DLL Requires mil.dll; mil3dmap.dll.
UNSIGNED TRUE PROC NONE NULL UNSIGNED TRUE PROC NONE NULL PROC NONE NULL DEFAULT DEVIATION MAX DEVIATION MEAN NUMBER OF PIXELS MISSING DATA NUMBER OF PIXELS OUTLIER NUMBER OF PIXELS TOTAL NUMBER OF PIXELS VALID VOLUME STAT ABS STAT ALL STAT NEGATIVE STAT POSITIVE DEFAULT INFINITE NULL