| MIL 10 Reference
| Customize Help
| Save Settings

McolDefine



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
Synopsis
Define or delete a color-sample or color element.
Syntax
void McolDefine(
MIL_ID ContextId, //in
MIL_ID SrcImageBufId, //in
MIL_INT UserLabelOrIndex, //in
MIL_INT64 ColorSampleType, //in
MIL_DOUBLE Param1, //in
MIL_DOUBLE Param2, //in
MIL_DOUBLE Param3, //in
MIL_DOUBLE Param4 //in
)
Description

This function allows you to add a color-sample to, or remove a color-sample from, a color matching or relative color calibration context. You can also use this function to add color elements to, or remove elements from, an existing color-sample. When defining a color-sample, you are, by default, defining the first color element of the color-sample. To define a color-sample (and consequently the first color element), you can use an image or three explicit color component values.

For a relative color calibration context, you must use this function to define or delete the reference color-sample. Information about color-samples applies to the reference color-sample unless otherwise specified.

A color matching or relative color calibration context must have one or more color-samples. A relative color calibration context must have one reference color-sample.

MIL uses color-samples to execute McolMatch() (color matching) and McolTransform() (relative color calibration). Before calling these functions, you must preprocess the context that holds the color-samples, using McolPreprocess(). Whenever you add, add to, delete, or delete from a color-sample, you must preprocess the context for these changes to take effect. You must add, or add to, color-samples one at a time; however, you can delete all color-samples at once.

When defining image type color-samples for a color matching context, MIL performs a color estimation, which is based on color statistics, such as the mean. The estimate is considered the color of the color-sample and is used in subsequent operations, such as McolMatch() and McolDraw(). When defining image type color-samples for a relative color calibration context, MIL does not typically perform a color estimation. MIL considers the color of the color-sample to be the color data of each individual pixel. This is what MIL uses in subsequent operations that require color-samples, such as McolTransform() and McolDraw(). In some cases, you can use the mean color of the color-sample instead (McolSetMethod()).

The size of color-samples does not usually affect the operations that use them.

Color-sample indices start at 0. Each subsequent color-sample you add to the context is given a sequential index number. If you delete a color-sample, MIL shifts all entries with higher indices down by one. This convention also applies when adding or deleting a color element to or from a color-sample. The reference color-sample does not have an index (there can only be one).

You can also assign a label to a color-sample. If you don't, MIL assigns one automatically. To change it afterward, use McolControl() with M_SAMPLE_LABEL_VALUE. Adding color elements to, or removing color elements from, a color-sample does not change its index or label. You cannot assign a label to the reference color-sample (there can be only one, to which MIL automatically assigns a label).

You can limit the McolMatch() or McolTransform() operation to a region of the image buffer, using a rectangular region of interest (ROI) set using MbufSetRegion().

MIL assumes all the color you are using is in the context's source color space (McolAlloc()). Therefore all color elements that you add 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-samples are inconsistent, MIL still processes them as is, which can produce misleading results. However, MIL will not allow you to add color elements of different types to the same color-sample. If you do, you will receive an error. For relative color calibration, all color data must be RGB. MIL processes it as RGB even if it is not.

Color space encoding must be set according to the actual dynamic range of your color elements. By default, MIL assumes an 8-bit color space encoding (regardless of the buffer's depth). For color matching, you can specify a different encoding, such as 16-bit, using McolControl() with M_ENCODING. For relative color calibration, MIL always assumes 8-bit. No other encoding can be set.

You can use McolMask() to mask regions of a color element in a specified color-sample.

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 context in which to add or delete a color-sample. The context must have been previously allocated on the required system using McolAlloc() with M_COLOR_MATCHING or M_COLOR_CALIBRATION_RELATIVE. If you are adding or deleting a color element from a color-sample, this parameter specifies the context in which the color-sample you wish to add or delete elements from is located.

SrcImageBufId

Specifies the identifier of the source image buffer to use to define or add elements to a color-sample. If you are defining or adding elements to a color-sample from three explicit color component values, or if you are deleting color-samples or color elements, set this parameter to M_NULL.

This image buffer can have a region of interest (ROI) defined using MbufSetRegion(). The region must be defined in raster format (M_RASTER or M_VECTOR_AND_RASTER). An error will be generated if the ROI is only in vector format (M_VECTOR).

If the source image buffer has an ROI, MIL ignores all pixels outside the ROI when defining an M_IMAGE color-sample. In this case, you must set Param1 to Param4 to M_DEFAULT.

UserLabelOrIndex

Specifies a color-sample. You can add the color-sample to, or delete the color-sample (or all color-samples) from, the specified context (ContextId). You can also add color elements to, or delete color elements from, the color-sample.

Set this parameter to one of the following values. Unless otherwise specified, values apply to both color matching and relative color calibration contexts.

function map For specifying a color-sample
CollapseValue Description
Collapse M_DEFAULT

Adds a color-sample to the context and automatically assigns it a label. The label is the next available numerical value following the highest label defined.

(summarize)
Collapse

Specifies the index of a color element (item), relative to the reference color-sample. Use M_REFERENCE_SAMPLE_ITEM() to delete a color element from the reference color-sample. M_REFERENCE_SAMPLE_ITEM() only applies to relative color calibration contexts.

(summarize)
Parameters

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

Collapse

Specifies the index of an existing color-sample. Use M_SAMPLE_INDEX() to delete a color-sample from the context, or to add a color element to a color-sample.

(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. Use M_SAMPLE_INDEX_ITEM() to delete a color element from a color-sample.

(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 new or an existing color-sample. Use M_SAMPLE_LABEL() to: add a new color-sample to the context, add a color element to an existing color-sample, or delete an existing color-sample from the context.

(summarize)
Parameters

Specifies a label value greater than 0. The label cannot use the last valid label value (2 12-1 ). It is reserved for the reference color-sample (M_REFERENCE_SAMPLE).

Collapse

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

(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. Use M_ALL to delete all color-samples from the context. For relative color calibration contexts, M_ALL also deletes the reference color-sample.

(summarize)
Collapse M_REFERENCE_SAMPLE

Specifies the reference color-sample. Use M_REFERENCE_SAMPLE to: add the reference color-sample to the context, delete the reference color-sample from the context, or add a color element to the reference color-sample. MIL automatically assigns the last possible label value (2 12-1 ) to M_REFERENCE_SAMPLE. M_REFERENCE_SAMPLE only applies to relative color calibration contexts.

(summarize)
ColorSampleType INQ

Specifies the type of the color-sample or color element.

See the Parameter associations section for possible values that can be specified.

Param1

Specifies an attribute of the color-sample or color element. Its definition is dependent on the color-sample or color element type chosen.

Set this parameter to M_DEFAULT if not used, or if the source image buffer has a region of interest (ROI), that was set using MbufSetRegion().

See the Parameter associations section for possible values that can be specified.

Param2

Specifies an attribute of the color-sample or color element. Its definition is dependent on the color-sample or color element type chosen.

Set this parameter to M_DEFAULT if not used, or if the source image buffer has a region of interest (ROI), that was set using MbufSetRegion().

See the Parameter associations section for possible values that can be specified.

Param3

Specifies an attribute of the color-sample or color element. Its definition is dependent on the color-sample or color element type chosen.

Set this parameter to M_DEFAULT if not used, or if the source image buffer has a region of interest (ROI), that was set using MbufSetRegion().

See the Parameter associations section for possible values that can be specified.

Param4

Specifies an attribute of the color-sample or color element. Its definition is dependent on the color-sample or color element type chosen.

Set this parameter to M_DEFAULT if not used, or if the source image buffer has a region of interest (ROI), that was set using MbufSetRegion().

See the Parameter associations section for possible values that can be specified.

The tables below list possible values for the ColorSampleType, Param1, Param2, Param3, and Param4 parameters.

Set all unused parameters to M_DEFAULT.

The following ColorSampleType parameter settings can be used to add a color-sample to the context, or a color element to the specified color-sample.

function map For adding a color-sample or color element
CollapseColorSampleType Description
Param1
Param2
Param3
Param4
Collapse M_IMAGE +

Specifies to add a color-sample or color element using the specified region of the source image. In this case, you must set the SrcImageBufId parameter to the identifier of an 8- or 16-bit color (3-band) unsigned image buffer, if you are using a color matching context. For a relative color calibration context, the buffer must be an 8-bit RGB color (3-band) image buffer.

(summarize)
Collapse Param1

Sets the X-offset of the origin of the color-sample or color element region from the source image.

(summarize)
Collapse M_DEFAULT

Specifies that the X-offset is equal to 0.

Collapse Value

Specifies the X-offset, in pixels.

Collapse Param2

Sets the Y-offset of the origin of the color-sample or color element region from the source image.

(summarize)
Collapse M_DEFAULT

Specifies that the Y-offset is equal to 0.

Collapse Value

Specifies the Y-offset, in pixels.

Collapse Param3

Sets the width (X-size) of the color-sample or color element region.

(summarize)
Collapse M_DEFAULT

Specifies that the width is from the origin of the color-sample or color element region to the end of the source image, in the X-direction.

Collapse Value

Specifies the width, in pixels.

Collapse Param4

Sets the height (Y-size) of the color-sample or color element region.

(summarize)
Collapse M_DEFAULT

Specifies that the height is from the origin of the color-sample or color element region to the end of the source image, in the Y-direction.

Collapse Value

Specifies the height, in pixels.

Collapse M_TRIPLET +

Specifies to add a color-sample or color element using three explicit values for the color components (RGB, HSL, or CIELAB). In this case, you must set the SrcImageBufId parameter to M_NULL.

(summarize)
Collapse Param1

Sets the value of the first color component. INQ

(summarize)
Collapse Param2

Sets the value of the second color component. INQ

(summarize)
Collapse Param3

Sets the value of the third color component. INQ

(summarize)
Combination constant for M_IMAGE; M_TRIPLET.

You can add the following value to the above-mentioned values to specify additional color elements to add to an already existing color-sample.

function map For adding elements to an already existing color-sample
CollapseCombination value Description
Collapse M_ADD_COLOR_TO_SAMPLE

Adds the specified color element to the specified color-sample. If the specified color-sample does not already exist, you will get an error. The color estimation that MIL performs for the color-sample uses the new elements as well as the existing element(s). MIL considers the resulting estimate the color of the color-sample and uses it in subsequent operations, such as color matching, relative color calibration, and drawing.

All color elements in a color-sample must have the same type. For example, if the existing color-sample type is M_IMAGE, its additional color element(s) must also be M_IMAGE. Similarly, if the color-sample is M_TRIPLET, the additional element(s) must be M_TRIPLET.

For M_IMAGE, you must ensure that the source image from which to define the additional color element(s) has the same format as the original source image used to define the existing color-sample.

(summarize)

The following ColorSampleType parameter setting can be used to remove color-samples from the context, or color elements from the specified color-sample. In this case, you must set the SrcImageBufId parameter to M_NULL, and Param1 to Param4 to M_DEFAULT.

function map For deleting color-samples from the context, or color elements from the specified color-sample
CollapseColorSampleType Description
Param1
Param2
Param3
Param4
Collapse M_DELETE

Specifies to delete one or all color-samples or color elements, depending on the UserLabelOrIndex parameter setting.

Note that deleting the last remaining color-sample element (item) from a color-sample is equivalent to deleting the color-sample itself.

(summarize)
Compilation information
Header Include mil.h.
Library Use mil.lib; milcolor.lib.
DLL Requires mil.dll; milcolor.dll.
PROC VECTOR DEFAULT ALL REFERENCE SAMPLE IMAGE DEFAULT DEFAULT DEFAULT DEFAULT TRIPLET ADD COLOR TO SAMPLE DELETE