McolDistance

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.

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.

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.

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.

Reserved for future expansion and must be set to M_DEFAULT.

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_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...)

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...)

Reserved for future expansion and must be set to M_DEFAULT.