McolDefine

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.