| MIL 10 Reference
| Customize Help
| Save Settings

McolMatch


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
McolMask
McolPreprocess
Synopsis
Match target areas with color-samples.
Syntax
void McolMatch(
MIL_ID ContextId, //in
MIL_ID TargetColorImageId, //in
MIL_ID TargetColorProfileId, //in
MIL_ID AreaIdentifierImageId, //in
MIL_ID ColorResultOrDestImageId, //in
MIL_INT64 ControlFlag //in
)
Description

This function matches the entire target image, or specific areas of the target image, with the color-samples defined in a color matching context. This function allows you to identify a target area's best-matched color-sample, or to determine the proportion of color in a target area, based on the color-samples provided.

To match multiple target areas, you must specify an area identifier image. Each unique, non-zero label in the area identifier image defines an independent target area. Touching target areas with different labels are considered distinct. If you use an area identifier image that does not contain any non-zero labels, the match is not performed, no resulting image is produced, and all results regarding target areas and color-samples are unavailable.

To retrieve the results of the match, you must set the ControlFlag parameter to M_DEFAULT and specify a result buffer using the ColorResultOrDestImageId parameter; you must then use this result buffer with McolGetResult(). In this case, to draw specific features of a color-sample or of a color matching result, use McolDraw().

You can also use McolMatch() to retrieve a single image result, by setting the ControlFlag parameter to a drawing operation (M_DRAW_...) and specifying an image buffer with the ColorResultOrDestImageId parameter. In this case, since you do not have a result buffer, you will not be able to use McolGetResult().

By default, a minimum distance operation is used to match the color of the target area with the color of the color-sample. To change the default operation mode, use McolSetMethod(). You can also use McolSetMethod() to change the default distance type of the match operation.

For color-samples defined from an image, MIL performs an estimation of the color. This estimate is based on color statistics, such as the mean; it is considered the color of the color-sample and is used in the match. The same kind of color estimation is also calculated for target areas, when matching with a minimum distance operation.

MIL assumes the color you are using is in the context's source color space (McolAlloc()). Therefore all color data that you provide must be consistent. For example, if you allocate an RGB context, bands 0, 1, and 2 are assumed to be red, green, and blue; you will therefore not receive an error if you try to match RGB target areas with HSL color-samples. Similarly, you will not receive an error if you try to match a 16-bit target area with an 8-bit color-sample. Even when the color data is inconsistent, MIL still processes it as is, which can produce misleading results.

You must set the color space encoding according to the actual dynamic range of your color data, using McolControl() with M_ENCODING. By default, the Color Analysis module assumes an 8-bit color space encoding (regardless of the buffer depth).

Certain modifications to the color matching context, such as adding or deleting color-samples, or changing some control settings, require you to preprocess the color matching context (McolPreprocess()) before any subsequent call to McolMatch(). To inquire whether you should preprocess, use McolInquire() with M_PREPROCESSED.

The function has been optimized for performance under the following conditions:

  • Buffers must be of the same type, as specified using McolControl() with M_ENCODING, preferably 8-bit or 16-bit.

  • The target image buffer must have a width greater than or equal to 8 pixels.

  • The area identifier image buffer must not be compressed (you cannot use MbufAllocColor() with M_COMPRESS).

  • When using multiple samples, an 8-bit target image buffer, and McolSetMethod() with either M_EUCLIDEAN or M_MAHALANOBIS, you should set the maximum tolerance for the color distance to a value less than 2 24/2 , using McolControl() with M_DISTANCE_TOLERANCE.

    Note that 2 24/2 is an internally established limit required for an optimal match process.

  • When using multiple samples, a 16-bit target image buffer, and McolSetMethod() with either M_EUCLIDEAN or M_MAHALANOBIS, you should set the maximum tolerance for the color distance to a value less than 2 53/2 , using McolControl() with M_DISTANCE_TOLERANCE.

    Note that 2 53/2 is an internally established limit required for an optimal match process.

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
ContextId

Specifies the identifier of the color matching context. The color matching context must have been previously allocated on the required system using McolAlloc() with M_COLOR_MATCHING.

TargetColorImageId

Specifies the identifier of the target image buffer with which to match the color-samples.

Target images must be 3-band 8- or 16-bit unsigned images. The target image and the color-sample must have the same color space encoding.

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.

TargetColorProfileId

Specifies the identifier of the target image's reference color space. This is the standard used to interpret the target's color data when performing an internal conversion before the match operation, using McolSetMethod() with the CIELAB conversion mode.

This parameter must be set to the following value:

function map For specifying the target image's color space profile
CollapseValue Description
Collapse M_DEFAULT

Specifies to use standard RGB specifications (sRGB), as defined by the International Electrotechnical Commission (IEC) Project Team 61966-2-1.
AreaIdentifierImageId

Specifies the identifier of the image buffer containing the target area labels. Area identifier images can be unsigned 1-band, packed binary, 8- or 16-bit grayscale images.

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.

To match the entire target image as one target area, set this parameter to M_NULL.

ColorResultOrDestImageId

Specifies the identifier of the image buffer or result buffer in which to write the results of the color matching operation.

If you specify the identifier of an image buffer, it must not have a region of interest (ROI) associated with it. Using an image buffer with an ROI will cause an error.

The bit depth of the image buffer must accommodate all the color-sample data drawn, including the background color, the outlier color, and the outlier label (when applicable).

The numerical value of the color-sample labels, the background pixels, and the outlier pixels and labels should be different so you can easily identify them if they are drawn (M_DRAW...). To modify these values, use McolControl() with M_SAMPLE_LABEL_VALUE, M_BACKGROUND_DRAW_COLOR, M_OUTLIER_DRAW_COLOR and M_OUTLIER_LABEL. Note that a pixel is considered background when it is outside the target areas, while outlier pixels are pixels inside a target area that did not match with any color-sample.

When the color of the color-sample is drawn, MIL uses either its triplet value (M_TRIPLET) or its estimated value (for example, the average color) taken from a source image (M_IMAGE), depending on how it was defined (McolDefine()).

If you specify the identifier of a result buffer, it must have been previously allocated on the required system, using McolAllocResult().

ControlFlag

Specifies the results to produce.

For specifying that results should be written in the result buffer, this parameter must be set to the following value. In this case, you must set the ColorResultOrDestImageId parameter to the identifier of a result buffer.

function map For specifying that results should be written in the result buffer
CollapseValue Description
Collapse M_DEFAULT

Calculates all possible results and writes them in the specified result buffer (ColorResultOrDestImageId).

For specifying that a specific image should be drawn in the image buffer, this parameter must be set to one the following values. In this case, you must set the ColorResultOrDestImageId parameter to the identifier of an image buffer. You can only draw one image at a time.

function map For specifying that a specific image result should be drawn in the image buffer
CollapseValue Description
Collapse M_DRAW_AREA_MATCH_USING_COLOR +

Draws, for each target area, the color of the best-matched color-sample. The background color and outlier color are also drawn; to modify these values, use McolControl() with M_BACKGROUND_DRAW_COLOR and M_OUTLIER_DRAW_COLOR, respectively.

For M_DRAW_AREA_MATCH_USING_COLOR, you must set the ColorResultOrDestImageId parameter to the identifier of a 3-band color image buffer.

(summarize)
Collapse M_DRAW_AREA_MATCH_USING_LABEL

Draws, for each target area, the label of the best-matched color-sample. The background color and outlier label are also drawn; to modify these values, use McolControl() with M_BACKGROUND_DRAW_COLOR and M_OUTLIER_LABEL, respectively.

For M_DRAW_AREA_MATCH_USING_LABEL, you must set the ColorResultOrDestImageId parameter to the identifier of a grayscale image buffer. To inquire the required buffer depth, use McolInquire() with M_SAMPLE_LABEL_SIZE_BIT.

(summarize)
Collapse M_DRAW_DISTANCE

Draws the distance between the estimated color (average color) of the target area (for an M_STAT_MIN_DIST operation mode) or the color of the target pixel (for an M_MIN_DIST_VOTE operation mode), and the color of its best-matched color-sample. Operation modes are set with McolSetMethod(). The background color and outlier color are also drawn; to modify these values, use McolControl() with M_BACKGROUND_DRAW_COLOR and M_OUTLIER_DRAW_COLOR, respectively.

For M_DRAW_DISTANCE, you must set the ColorResultOrDestImageId parameter to the identifier of a grayscale image buffer.

To draw normalized distances, use McolControl() with M_DISTANCE_IMAGE_NORMALIZE before drawing.

The outlier color, which is also drawn with M_DRAW_DISTANCE, can be difficult to identify if it is similar to the resulting distance. For example, if the outlier color is 0.0, you wouldn't be able to distinguish it if the resulting distance is also 0.0. In this case, you can use M_DRAW_..._USING_LABEL, which draws the outlier label.

M_DRAW_DISTANCE is not available if the operation mode is set to M_HISTOGRAM_MATCHING or M_HISTOGRAM_VOTE (McolSetMethod()).

(summarize)
Collapse M_DRAW_PIXEL_MATCH_USING_COLOR +

Draws, for each pixel in each target area, the color of the color-sample for which each pixel voted. The background color and outlier color are also drawn; to modify these values, use McolControl() with M_BACKGROUND_DRAW_COLOR and M_OUTLIER_DRAW_COLOR, respectively.

For M_DRAW_PIXEL_MATCH_USING_COLOR, you must set the ColorResultOrDestImageId parameter to the identifier of a 3-band color image buffer, and you must use McolSetMethod() with M_MIN_DIST_VOTE.

(summarize)
Collapse M_DRAW_PIXEL_MATCH_USING_LABEL

Draws, for each pixel in each target area, the label of the color-sample for which each pixel voted. The background color and outlier label are also drawn; to modify these values, use McolControl() with M_BACKGROUND_DRAW_COLOR and M_OUTLIER_LABEL, respectively.

For M_DRAW_PIXEL_MATCH_USING_LABEL, you must use McolSetMethod() with M_MIN_DIST_VOTE, and you must set the ColorResultOrDestImageId parameter to the identifier of a grayscale image buffer. To inquire the required buffer depth, use McolInquire() with M_SAMPLE_LABEL_SIZE_BIT.

(summarize)

You can add the following value to the above-mentioned values to specify whether to invert colors.

function map For specifying whether to invert colors
CollapseCombination value Description
Collapse M_INVERTED_COLORS

Inverts the color of the best-matched color-sample in the specified image.
Compilation information
Header Include mil.h.
Library Use mil.lib; milcolor.lib.
DLL Requires mil.dll; milcolor.dll.
UNSIGNED PROC NONE DEFAULT PROC NONE PROC NONE DEFAULT DRAW AREA MATCH USING COLOR DRAW AREA MATCH USING LABEL DRAW DISTANCE DRAW PIXEL MATCH USING COLOR DRAW PIXEL MATCH USING LABEL INVERTED COLORS