| MIL 10 Reference
| Customize Help
| Save Settings

McolDraw


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
McolDistance
McolFree
Synopsis
Draw specific features of a color-sample, color element, or color matching result.
Syntax
void McolDraw(
MIL_ID GraphContId, //in
MIL_ID ContextOrResultId, //in
MIL_ID DestImageBufId, //in
MIL_INT64 DrawOperation, //in
MIL_INT AreaLabel, //in
MIL_INT SampleIndexOrLabel, //in
MIL_INT64 ControlFlag //in
)
Description

This function draws specific features of a selected color-sample (defined in a specified color matching or relative color calibration context), color element (defined in a specified color-sample), or of a color matching result, in the destination image buffer. Drawing operations for color matching results are only available after calling McolMatch().

Color-samples or color elements are drawn using either their triplet values (M_TRIPLET) or their estimated values (for example, the average) taken from a source image (M_IMAGE), depending on how you defined them (McolDefine()).

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
GraphContId

Specifies the identifier of the graphics context to use when drawing. Set this parameter to one of the following values:

function map For specifying the graphics context
CollapseValue Description
Collapse M_DEFAULT

Specifies that the default graphics context of the current MIL application is used.

Note that there is a different default graphics context for each thread.

(summarize)
Collapse MIL graphics context identifier

Specifies a valid graphics context identifier, which you have allocated using MgraAlloc().
ContextOrResultId

Specifies the context or result buffer for which to perform the drawing operation. The context or result buffer must have been previously allocated on the system using McolAlloc() (with M_COLOR_MATCHING or M_COLOR_CALIBRATION_RELATIVE) or McolAllocResult(), respectively.

DestImageBufId

Specifies the identifier of the destination image buffer in which to draw. The buffer can be any supported MIL image buffer. By drawing into its display's overlay buffer, you can also annotate the image non-destructively.

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 required format and size of the destination image depends on the drawing operation. For a color element, you can retrieve the required format and size using McolInquire() (for example, M_SAMPLE_IMAGE_SIZE_X). For a color matching result, you can retrieve this information using McolGetResult() (for example, M_AREA_IMAGE_SIZE_X). When drawing the mosaic of all color elements within a color-sample, you can retrieve the required information using McolInquire() (for example, M_SAMPLE_MOSAIC_SIZE_X).

The bit depth of the image buffer must accommodate all the color-sample or color element 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.

For a color matching result, the background of the destination image is set to the background color (McolControl() with M_BACKGROUND_DRAW_COLOR) that is in effect when you call McolMatch(). If you set a transparent background, the image background remains untouched.

DrawOperation

Specifies the type of drawing operation to perform.

For a selected color-sample, set this parameter to one of the following values:

function map For drawing specific features of a color-sample
CollapseValue Description
Collapse M_DRAW_SAMPLE_MOSAIC

Draws the mosaic of all the color elements found in the specified color-sample. If there is only one color element in the sample, M_DRAW_SAMPLE_MOSAIC will essentially perform the same operation as M_DRAW_SAMPLE.

(summarize)
Collapse M_DRAW_SAMPLE_MOSAIC_DONT_CARE

Draws a mosaic mask of all "don't care" pixels in the specified color-sample. All non-zero destination pixels correspond to either a region in-between color data or to a color data mask. All destination pixels set to zero correspond to non-masked color data.

(summarize)

For a selected color element (of a selected color-sample), set this parameter to one of the following values:

function map For drawing specific features of a color element
CollapseValue Description
Collapse M_DRAW_SAMPLE

Draws the internal image of the specified color element in the destination image buffer. If you defined a triplet color element, M_DRAW_SAMPLE fills the destination image buffer with the color of the triplet. The triplet values are saturated according to the destination buffer depth.

If you do not specify the index or label of a specific color element, the first color element in the specified color-sample will be drawn.

(summarize)
Collapse M_DRAW_SAMPLE_MASK

Draws the mask image of the specified color element in the destination image buffer. You can only perform this operation on M_IMAGE color-samples masked with McolMask(). To inquire if a color-sample has a mask, use McolInquire() with M_SAMPLE_MASKED.

If you do not specify the index or label of a specific color element, the first color element in the specified color-sample will be drawn.

(summarize)

For a color matching result buffer, set this parameter to one of the following values.

function map For drawing specific features of a color matching result
CollapseValue Description
Collapse M_DRAW_AREA

Draws the specified area(s) (AreaLabel) of the area identifier image.

If you specify a single target area, the background of the destination image (DestImageBufId) is untouched; if you specify M_ALL, the whole area identifier image, including a 0 background, is copied to the destination image.

To perform this drawing operation, you must have first enabled McolControl() with M_SAVE_AREA_IMAGE, and called McolMatch().

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

To perform this drawing operation, you must have first enabled McolControl() with M_SAVE_AREA_IMAGE and M_GENERATE_SAMPLE_COLOR_LUT, and called McolMatch().

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

To perform this drawing operation, you must have first enabled McolControl() with M_SAVE_AREA_IMAGE, and called McolMatch().

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

To perform this drawing operation, you must have first enabled McolControl() with M_GENERATE_DISTANCE_IMAGE, and called McolMatch().

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.

To perform this drawing operation, you must have first enabled McolControl() with M_GENERATE_PIXEL_MATCH and M_GENERATE_SAMPLE_COLOR_LUT, and called McolMatch(). You must have also used 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.

To perform this drawing operation, you must have first enabled McolControl() with M_GENERATE_PIXEL_MATCH, and called McolMatch(). You must also use have used McolSetMethod() with M_MIN_DIST_VOTE.

(summarize)

For either a color matching context or color matching result, set this parameter to the following value:

function map For drawing specific features of either a color-sample or a color matching result (for color matching)
CollapseValue Description
Collapse M_DRAW_SAMPLE_COLOR_LUT +

Draws the 3-band color-sample label LUT, where the label value of each color-sample is associated with its average color.

The average colors are calculated using the color data that you provided when defining the color-sample (McolDefine()). The calculation takes into account all three bands, regardless of the setting of McolControl() with M_BAND_MODE.

To perform this operation for color matching results, you must have first enabled McolControl() with M_GENERATE_SAMPLE_COLOR_LUT, and called McolMatch().

M_DRAW_SAMPLE_COLOR_LUT requires that you set the SampleIndexOrLabel parameter to M_ALL or M_DEFAULT.

When using M_DRAW_SAMPLE_COLOR_LUT, the destination image buffer (DestImageBufId) must be a 3-band, 8-bit unsigned LUT buffer, with a size of N x 1, where N is equal to the M_SAMPLE_LUT_SIZE_X inquire type (McolInquire()). You can associate this color-sample label LUT to either a display using MdispLut(), or to an image buffer using MbufControl() with M_ASSOCIATED_LUT.

(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.
AreaLabel

Specifies the label of the target area for which to perform the drawing operation, for color matching contexts. For a relative color calibration context, there are no target areas; you must specify M_DEFAULT.

Set this parameter to one of the following values:

function map For specifying the target area's label or index (for color matching)
CollapseValue Description
Collapse M_DEFAULT

Specifies the default. For a color matching context, the default is the same as M_ALL. For a relative color calibration context, the default indicates that this information is not required.

(summarize)
Collapse M_ALL

Specifies all target areas. You should specify M_ALL if you did not use an area identifier image (M_NULL) with McolMatch(). This value is only available for color matching contexts.

(summarize)
Collapse Value > 0

Specifies the label of the target area, as it appears in the area identifier image.

When specifying a specific target area's label, you must use McolControl() with M_SAVE_AREA_IMAGE set to M_ENABLE. This value is only available for color matching contexts.

(summarize)
SampleIndexOrLabel

Specifies the color-sample or color element therein for which to perform the drawing operation. Unless otherwise specified, values apply to both color matching and relative color calibration contexts. Set this parameter to one of the following values:

function map For specifying the color-sample or color element
CollapseValue Description
Collapse M_DEFAULT

Same as M_ALL.
Collapse

Specifies the index of a color element (item), relative to the reference color-sample. This value only applies to relative color calibration contexts (ContextOrResultId).

(summarize)
Parameters

Specifies the index of a color element (item). The index value must be greater than or equal to 0.
Collapse

Specifies the color-sample's index, in a color context or result.

(summarize)
Parameters

Specifies an index value greater than or equal to 0.
Collapse

Specifies the index of a color element (item), relative to a color-sample index.

(summarize)
Parameters

Specifies the index of the color-sample that holds the color element (item). The index must be greater than or equal to 0.

Specifies the index of the color element (item). The index value must be greater than or equal to 0.
Collapse

Specifies the label of a color-sample.

To use this value, you must typically enable McolControl() with M_GENERATE_PIXEL_MATCH. However, you need not do this when performing an M_DRAW_AREA_MATCH_USING_LABEL or M_DRAW_AREA_MATCH_USING_COLOR drawing operation.

(summarize)
Parameters

Specifies a label value greater than 0.
Collapse

Specifies the index of a color element (item), relative to a color-sample label.

(summarize)
Parameters

Specifies the label of the color-sample that holds the color element (item). The label value must be greater than 0.

Specifies the index of the color element (item). The index value must be greater than or equal to 0.
Collapse M_ALL

Specifies all color-samples.

When specifying a color matching context, you can only use M_ALL with M_DRAW_SAMPLE_COLOR_LUT.

When specifying a specific color-sample (in either a color matching or relative color calibration context), you can only use M_ALL with M_DRAW_SAMPLE and M_DRAW_SAMPLE_MASK.

You can use M_ALL with any operation that a color matching result buffer supports.

(summarize)
Collapse M_REFERENCE_SAMPLE

Specifies the reference color-sample. This value only applies to relative color calibration contexts.

(summarize)
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.
DEFAULT PROC NONE DRAW SAMPLE MOSAIC DRAW SAMPLE MOSAIC DONT CARE DRAW SAMPLE DRAW SAMPLE MASK DRAW AREA DRAW AREA MATCH USING COLOR DRAW AREA MATCH USING LABEL DRAW DISTANCE DRAW PIXEL MATCH USING COLOR DRAW PIXEL MATCH USING LABEL DRAW SAMPLE COLOR LUT INVERTED COLORS DEFAULT ALL DEFAULT ALL REFERENCE SAMPLE