MimStatCalculate

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

Calculates and stores a variety of statistics from the specified source image(s).

Syntax

void MimStatCalculate(
    AIL_ID    StatContextImId,  //in
    AIL_ID    SrcImageBufId,    //in
    AIL_ID    StatResultImId,   //out
    AIL_INT64 ControlFlag       //in
)

Description

This function calculates a variety of statistics for the pixels in the source image(s). Results are stored in the specified statistics result buffer.

The specified image processing context establishes which statistics to calculate. This function can take statistics for the specified image (M_STATISTICS_CONTEXT context) or it can accumulate statistics for each pixel across multiple images (M_STATISTICS_CUMULATIVE_CONTEXT context). For an M_STATISTICS_CONTEXT context, you can specify a condition that a pixel must satisfy to be included in the calculation using M_CONDITION. Co-occurrence statistics (M_STAT_GLCM...) ignore any specified condition. If you need to calculate one type of single-image statistic and don't need to specify a condition, you can use a predefined context; otherwise, use MimAlloc to set up a custom context that you can control using MimControl.

You can read the statistics from the result buffer using MimGetResult or MimGetResult2d, depending on the statistical operation performed. You can also draw some statistical results, usingMimDraw.

Once the statistics image processing context is configured, preprocess the context and result buffer by calling MimStatCalculate with M_PREPROCESS. If the preprocess operation is not done explicitly (using M_PREPROCESS), it will be done when MimStatCalculate is first called. When explicitly preprocessing a cumulative statistics image processing context and result buffer, the source image buffer can be set to M_NULL if you set the size that the source buffer will be, using MimControl with M_SOURCE_SIZE_X and M_SOURCE_SIZE_Y. Note that providing the source image buffer better optimizes future calls.

When working with an M_STATISTICS_CUMULATIVE_CONTEXT context, you can remove the calculated statistics associated with a specified source image from the result buffer by calling MimStatCalculate with M_REMOVE. To reset the results generated from finding the extremes of each pixel's value (such as, M_STAT_MIN), use M_RESET_EXTREMES.

To reset all the results in the result buffer, free it using MimFree, and then allocate a new result buffer using MimAllocResult with M_STATISTICS_RESULT. These actions apply to either context (M_STATISTICS_CONTEXT or M_STATISTICS_CUMULATIVE_CONTEXT).

Note that when working with an M_STATISTICS_CUMULATIVE_CONTEXT context, your source images should have the same dimensions, so that statistics are calculated for the same pixel across the multiple images.

For an M_STATISTICS_CONTEXT, you can limit some of this function's results to a region of an image buffer using a region of interest (ROI) set using MbufSetRegion. The ROI must be defined in raster format (M_RASTER or M_VECTOR_AND_RASTER). An error is generated if the ROI is only in vector format (M_VECTOR). Not all statistical operations support ROIs; for a list of those that do, see MimControl. Note that the M_STATISTICS_CUMULATIVE_CONTEXT context does not support ROIs.

Parameters

StatContextImId (in, AIL_ID)

Specifies a statistics context, which determines the statistics to calculate. You can select the identifier of a previously allocated statistics context, or you can select a predefined statistics context to evaluate one type of single-image statistical calculation. The predefined statistics contexts do not need to be allocated.

For specifying the statistics context, or specific statistic to calculate

Value	Description
M_STAT_CONTEXT_MAX	Specifies a predefined single-image statistics image processing context with all control types set to their default except for M_STAT_MAX, which is set to M_ENABLE.

Use this predefined context to calculate the maximum pixel value of the source image. | | M_STAT_CONTEXT_MAX_ABS | Specifies a predefined single-image statistics image processing context with all control types set to their default except for M_STAT_MAX_ABS, which is set to M_ENABLE.

Use this predefined context to calculate the maximum absolute pixel value of the source image. | | M_STAT_CONTEXT_MEAN | Specifies a predefined single-image statistics image processing context with all control types set to their default except for M_STAT_MEAN, which is set to M_ENABLE.

Use this predefined context to calculate the mean pixel value of the source image. | | M_STAT_CONTEXT_MIN | Specifies a predefined single-image statistics image processing context with all control types set to their default except for M_STAT_MIN, which is set to M_ENABLE.

Use this predefined context to calculate the minimum pixel value of the source image. | | M_STAT_CONTEXT_MIN_ABS | Specifies a predefined single-image statistics image processing context with all control types set to their default except for M_STAT_MIN_ABS, which is set to M_ENABLE.

Use this predefined context to calculate the minimum absolute pixel value of the source image. | | M_STAT_CONTEXT_NUMBER | Specifies a predefined single-image statistics image processing context with all control types set to their default except for M_STAT_NUMBER, which is set to M_ENABLE.

Use this predefined context to calculate the number of valid pixels in the source image. This is mainly useful in the presence of a region. | | M_STAT_CONTEXT_STANDARD_DEVIATION | Specifies a predefined single-image statistics image processing context with all control types set to their default except for M_STAT_STANDARD_DEVIATION, which is set to M_ENABLE.

Use this predefined context to calculate the standard deviation of the pixel values of the source image. | | M_STAT_CONTEXT_SUM | Specifies a predefined single-image statistics image processing context with all control types set to their default except for M_STAT_SUM, which is set to M_ENABLE.

Use this predefined context to calculate the sum of the pixel values of the source image. | | M_STAT_CONTEXT_SUM_ABS | Specifies a predefined single-image statistics image processing context with all control types set to their default except for M_STAT_SUM_ABS, which is set to M_ENABLE.

Use this predefined context to calculate the sum of the absolute pixel values of the source image. | | M_STAT_CONTEXT_SUM_OF_SQUARES | Specifies a predefined single-image statistics image processing context with all control types set to their default except for M_STAT_SUM_OF_SQUARES, which is set to M_ENABLE.

Use this predefined context to calculate the sum of the squared pixel values of the source image. | | Statistics context identifier | Specifies a statistics context identifier, previously allocated using MimAlloc with M_STATISTICS_CONTEXT or M_STATISTICS_CUMULATIVE_CONTEXT.

You can specify which statistics calculations are evaluated using MimControl. |

SrcImageBufId (in, AIL_ID)

Specifies the identifier of the source image buffer. The buffer used must be a 1-band image buffer.

StatResultImId (out, AIL_ID)

Specifies the identifier of the result buffer. The buffer must have been allocated using MimAllocResult with M_STATISTICS_RESULT.

ControlFlag (in, AIL_INT64)

Specifies the operation to perform on the source image.

To specify the operation to perform

Value	Description
M_DEFAULT	Calculates the statistics specified using MimControl, or in a predefined statistics context. This is the only valid option for a predefined statistics context.
M_PREPROCESS	Preprocesses the specified image processing context and image processing result buffer. Note that, if not called explicitly, this operation will be performed automatically upon the first call to MimStatCalculate.

If the identifier of the source image buffer is not set to M_NULL, information about the source image buffer will be used in the preprocessing operation. | | M_REMOVE | Removes the results related to the specified source image. This removes the results of the calculations, performed on the specified source image, from the accumulated results in the result buffer.

To reset the minimum and maximum statistical results, use M_RESET_EXTREMES. The minimum and maximum statistical results cannot be removed.

Note: Note that this value only works when dealing with a cumulative statistics context (M_STATISTICS_CUMULATIVE_CONTEXT). | | M_RESET_EXTREMES | Resets the results generated from M_STAT_MIN, M_STAT_MIN_ABS, M_STAT_MAX, and M_STAT_MAX_ABS operations. Note that, when resetting the minimum and maximum results, the SrcImageBufId parameter is ignored.

Note: Note that this value only works when dealing with a cumulative statistics context (M_STATISTICS_CUMULATIVE_CONTEXT). |