McolMask

This function allows you to apply masks to specific color elements of the specified color-sample in the color matching or relative color calibration context. To apply a mask to a color-sample with only one element, you must have added the color-sample to the context using McolDefine() with M_IMAGE. To apply a mask to a specific color element of the specified color-sample, you must have added the color element to a color-sample using McolDefine() with M_ADD_COLOR_TO_SAMPLE.

With each mask, you can set pixels in the specified color element to a "don't care" state. MIL does not consider "don't care" pixels in color-samples when you call McolPreprocess(), McolMatch(), or McolTransform().

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 context in which the color-sample containing the color element to be masked is located. You must first allocate the color matching or relative color calibration context on the system using McolAlloc() with M_COLOR_MATCHING or M_COLOR_CALIBRATION_RELATIVE.

ColorSampleIndexOrLabel

Specifies the color element for which to create a mask. Unless otherwise specified, values apply to color matching and relative color calibration contexts. This parameter can be set to one of the following values:

For specifying the color element
Value	Description
M_REFERENCE_SAMPLE_ITEM( MIL_INT ElementIndex )	Specifies the index of a color element (item), relative to the reference color-sample. This value only applies to relative color calibration contexts (ContextId). (summarize) Specifies the index of a color element (item), relative to the reference color-sample. (more details...)
		Parameters
		ElementIndex Specifies the index of a color element (item). The index value must be greater than or equal to 0.
M_SAMPLE_INDEX( MIL_INT SampleIndex )	Specifies the index of a color-sample that has one color element. If the color-sample has multiple color elements, use M_SAMPLE_INDEX_ITEM() or M_SAMPLE_LABEL_ITEM(). (summarize) Specifies the index of a color-sample that has one color element. (more details...)
		Parameters
		SampleIndex Specifies an index value greater than or equal to 0.
M_SAMPLE_INDEX_ITEM( MIL_INT SampleIndex, MIL_INT ElementIndex )	Specifies the index of a color element (item), relative to a color-sample index. (summarize) Specifies the index of a color element (item), relative to a color-sample index. (more details...)
		Parameters
		SampleIndex Specifies the index of the color-sample that holds the color element (item). The index must be greater than or equal to 0.
		ElementIndex Specifies the index of the color element (item). The index value must be greater than or equal to 0.
M_SAMPLE_LABEL( MIL_INT SampleLabel )	Specifies the label of a color-sample that has one color element. If the color-sample has multiple color elements, use M_SAMPLE_INDEX_ITEM() or M_SAMPLE_LABEL_ITEM(). (summarize) Specifies the label of a color-sample that has one color element. (more details...)
		Parameters
		SampleLabel Specifies a label value greater than 0.
M_SAMPLE_LABEL_ITEM( MIL_INT SampleLabel, MIL_INT ElementIndex )	Specifies the index of a color element (item), relative to a color-sample label. (summarize) Specifies the index of a color element (item), relative to a color-sample label. (more details...)
		Parameters
		SampleLabel Specifies the label of the color-sample that holds the color element (item). The label value must be greater than 0.
		ElementIndex Specifies the index of the color element (item). The index value must be greater than or equal to 0.
M_REFERENCE_SAMPLE	Specifies the reference color-sample. This value only applies to relative color calibration contexts (ContextId). (summarize) Specifies the reference color-sample. (more details...)

MaskBufferId

Specifies the identifier of the buffer to use to identify the masked (non-zero) pixels in the color element. This buffer must be a 1-band 8-bit unsigned image buffer.

If the mask is not the same size as the color element, the masking operation considers only the common region between both images. A common origin at the top-left corner of the mask image is assumed. If the mask is smaller than the color element, the color element region exceeding the mask is considered unmasked. If the mask is greater than the color element, the mask is clipped. An error is generated if the color-sample is entirely masked.

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 remove the mask, set the MaskBufferId parameter to M_NULL. An error is generated if you try removing a mask that does not exist.

MaskType

Specifies the type of mask to employ. Set this parameter to the following value:

For specifying the type of mask
Value	Description
M_DONT_CARE	Specifies that MIL ignores non-zero pixels in the color element's masked region. For example, masked pixels do not affect any of the resulting scores, when preforming color matching. Masked pixels also do not affect the mapping MIL establishes between each color-sample and the relevant color-sample, when transforming colors using relative color calibration. (summarize) Specifies that MIL ignores non-zero pixels in the color element's masked region. (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.