McolDistance

MIL_ID Src1Id,	//in
MIL_ID Src2Id,	//in
MIL_ID DestId,	//in
MIL_ID MaskId,	//in
MIL_ID DistanceAttributesArrayId,	//in
MIL_INT64 DistType,	//in
MIL_DOUBLE NormalizeValue,	//in
MIL_INT64 ControlFlag	//in

)

Description

This function calculates the point-to-point distance between colors in two images. You can also calculate the point-to-point distance between the color in one image and: a color constant, a covariance matrix, or the covariance of a specified image. The calculated distance (for each pixel) is written in the specified destination image (DestId parameter). To ignore unwanted pixels in the distance calculation, you can apply a mask.

The color distance is typically calculated only for pixels within the intersection of the source (Src1Id and Src2Id), destination (DestId), and mask (MaskId) images, with the assumption of a common origin at the top-left corner.

The Color Analysis module assumes that the color of the images you use with McolDistance() is consistent. For example, you will not receive an error if you try to calculate the distance between an RGB and an HSL image, or a 16-bit and an 8-bit image. Even when color data is inconsistent, it is still processed as is, which can produce misleading results.

You can also obtain distance results after calling McolMatch(), which unlike McolDistance(), considers the color matching context's color space. For more information on how distances differ between these two functions, see the Distance between colors section of Chapter 19: Color processing and analysis.

This function is optimized for planar buffers or for packed 32-bit BGR buffers with a width (X-size) greater than seven pixels (MbufAllocColor()). It is recommended to avoid providing both planar and packed buffers, since this requires some internal compensation.

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 which MIL system’s documentation you should use in its place and any possible differences.

Parameters

This function is not supported on the selected boards.

This function reference has not been updated for the selected MIL system. To show the content of this page, choose a second MIL system; refer to the MIL system's release note to see which MIL system’s documentation to choose and any possible differences.

Parameters

Src1Id

Specifies the identifier of the first source image buffer. The buffer must be an 8- or 16-bit color (3-band) unsigned image buffer.

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.

Src2Id

Specifies the identifier of the second source buffer, which can be either an image or a MIL array buffer.

For an image, the buffer must be an 8- or 16-bit color (3-band) unsigned image buffer. For an array, the content and size depends on the type of distance operation chosen (DistType).

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.

Note that when setting this parameter to an array buffer, this function will achieve maximal speed performance if the buffer's data type is the same as the data type of the first source image. For example, you will achieve maximal speed if the first source image buffer and second source array buffer are both 8-bit unsigned buffers.

DestId

Specifies the identifier of the destination image buffer in which to write the results of the distance calculation. The destination buffer must be a 1-band buffer; its type is not restricted.

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.

Since distance results are numerical values containing decimals, if you specify the destination buffer as type integer, the fractional part of the value will be truncated. For example, a distance of 50.25 will truncate to 50.

Distance results are clipped if they are greater than the destination buffer's maximal possible value. For example, when using an 8-bit unsigned destination buffer, distances higher than 255 will be written as 255. Note that if you specify a destination buffer of type floating-point, distance results would almost never be greater than the buffer's maximal possible value, since its limit is extremely high.

To normalize distance results, use the NormalizeValue parameter.

MaskId

Specifies the identifier of the image buffer used to identify the masked (non-zero) pixels. This must be a 1- or 8-bit (1-band) unsigned buffer. To not apply a mask, set this parameter to M_NULL.

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.

The color distance is calculated only for masked (non-zero) pixels within the intersection of the source, destination, and mask images, with the assumption of a common origin at the top-left corner. Set unmasked pixels to 0; unmasked pixels are ignored in the distance calculation.

DistanceAttributesArrayId

Reserved for future expansion and must be set to M_DEFAULT.

DistType

Specifies the type of distance operation to perform. This parameter must be set to one of the following values:

For specifying the distance type
Value	Description
M_DELTA_E	Specifies to use a Delta-E color distance, as defined by the International Commission on Illumination (CIE). A Delta-E color distance is the same as a Euclidean color distance (M_EUCLIDEAN), but specialized for the LAB (CIELAB) color space. That is, MIL converts the color data to the native LAB range before performing a Euclidean-type color distance. (summarize) Specifies to use a Delta-E color distance, as defined by the International Commission on Illumination (CIE). (more details...)
M_EUCLIDEAN	Specifies to use a Euclidean color distance. A Euclidean distance is the square root of the sum of the squared differences between the color of each pixel in the first source image buffer (Src1Id) and either the color of each pixel in the second source image buffer, or a color constant (Src2Id). For a color constant, you must use a 3x1, one-dimensional MIL array buffer. This buffer's type is unrestricted, and must contain three color component values (for example, RGB). (summarize) Specifies to use a Euclidean color distance. (more details...)
M_MAHALANOBIS	Specifies to use a Mahalanobis color distance. A Mahalanobis distance is calculated between the color of each pixel in the image specified in the first source image buffer (Src1Id) and, typically, either the covariance of the image specified in the second source image buffer, or a covariance matrix (Src2Id). This distance, between a color and a distribution of colors, is similar to a Euclidean distance between the mean of the two colors, but weighted by the inverse of the covariance of the distribution. This implies that the more a color distribution varies in a direction within the color space, the less important is the distance in that direction. Since the covariance matrix of the second source is used, the second source should usually be a distribution of colors, such as an image, and not a single solid color (a color constant). However, if you provide a color constant as the second source, Mahalanobis behaves very much like Euclidean and will yield similar results. For a covariance matrix, you must use a 4x3, two-dimensional MIL array buffer. (summarize) Specifies to use a Mahalanobis color distance. (more details...)
M_MANHATTAN	Specifies to use a Manhattan color distance. A Manhattan distance is the sum of the absolute value of the differences between the color of each pixel in the image specified in the first source image buffer (Src1Id) and either the color of each pixel in the second source image buffer, or a color constant (Src2Id). Note that in HSL the color's hue is stored as a separate component (H) represented as an angular position on a circular color disk. Therefore the distance between colors is equal to the smallest angular difference, rather than the absolute value of the difference. For a color constant, you must use a 3x1, one-dimensional MIL array buffer. The buffer's type is unrestricted, and must contain three color component values (for example, RGB). (summarize) Specifies to use a Manhattan color distance. (more details...)

NormalizeValue

Specifies the factor with which to normalize the resulting distances. The normalized distance that is written to the destination buffer must respect this buffer's limits (DestId).

This parameter should be set to one of the following values:

For specifying the normalization of distances
Value	Description
M_DEFAULT	Same as M_NO_NORMALIZE.
M_MAX_NORMALIZE	Specifies to normalize distance values according to the greatest calculated distance. This value corresponds to the result M_MAX_DISTANCE (McolGetResult()). The normalization performed is: (Distance/GreatestCalculatedDistance) x MaximumPossibleValueOfDestBuf (for destination buffer's of type integer). (Distance/GreatestCalculatedDistance) (for destination buffer's of type floating-point). Note that if the destination buffer is of type floating-point, you would typically not normalize the distance results, since all this will do is return a value between 0.0 and 1.0. (summarize) Specifies to normalize distance values according to the greatest calculated distance. (more details...)
M_NO_NORMALIZE	Specifies no normalization. For destination buffers of type integer, distance values are truncated (no decimals). For destination buffers of type floating-point, distance values are complete (with decimals). (summarize) Specifies no normalization. (more details...)
Value > 0.0	Specifies to normalize distance values according to the specified normalization value. The normalization performed is: (Distance/NormalizationValue) x MaximumPossibleValueOfDestBuf (for destination buffer's of type integer). (Distance/NormalizationValue) (for destination buffer's of type floating-point). Note that if the destination buffer is of type floating-point, you would typically not normalize the distance results, since all this will do is return a value between 0.0 and 1.0. (summarize) Specifies to normalize distance values according to the specified normalization value. (more details...)

ControlFlag

Reserved for future expansion and must be set to M_DEFAULT.

Compilation information

Header	Include mil.h.
Library	Use mil.lib; milcolor.lib.
DLL	Requires mil.dll; milcolor.dll.