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 |
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.
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.
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.
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.
![]() |
|||||||||||||||||||||||||||||||||||||||
![]() ![]() |
Description | ||||||||||||||||||||||||||||||||||||||
![]() ![]() |
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)Adds a color-sample to the context and automatically assigns it a label. (more details...) |
||||||||||||||||||||||||||||||||||||||
![]() ![]() |
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)Specifies the index of a color element (item), relative to the reference color-sample. (more details...) |
||||||||||||||||||||||||||||||||||||||
Parameters | |||||||||||||||||||||||||||||||||||||||
Specifies the index of the color element (item). The index value must be greater than or equal to 0. |
|||||||||||||||||||||||||||||||||||||||
![]() ![]() |
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)Specifies the index of an existing color-sample. (more details...) |
||||||||||||||||||||||||||||||||||||||
Parameters | |||||||||||||||||||||||||||||||||||||||
Specifies an index value greater than or equal to 0. |
|||||||||||||||||||||||||||||||||||||||
![]() ![]() |
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)Specifies the index of a color element (item), relative to a color-sample index. (more details...) |
||||||||||||||||||||||||||||||||||||||
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. |
|||||||||||||||||||||||||||||||||||||||
![]() ![]() |
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)Specifies the label of a new or an existing color-sample. (more details...) |
||||||||||||||||||||||||||||||||||||||
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). |
|||||||||||||||||||||||||||||||||||||||
![]() ![]() |
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)Specifies the index of a color element (item), relative to a color-sample label. (more details...) |
||||||||||||||||||||||||||||||||||||||
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. |
|||||||||||||||||||||||||||||||||||||||
![]() ![]() |
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)Specifies all color-samples. (more details...) |
||||||||||||||||||||||||||||||||||||||
![]() ![]() |
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)Specifies the reference color-sample. (more details...) |
Specifies the type of the color-sample or color element.
See the Parameter associations section for possible values that can be specified.
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.
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.
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.
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.
![]() |
|||||||||||||||||||||||||||||||||||||||
![]() ![]() |
Description | ||||||||||||||||||||||||||||||||||||||
Param1 | |||||||||||||||||||||||||||||||||||||||
Param2 | |||||||||||||||||||||||||||||||||||||||
Param3 | |||||||||||||||||||||||||||||||||||||||
Param4 | |||||||||||||||||||||||||||||||||||||||
![]() ![]() |
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)Specifies to add a color-sample or color element using the specified region of the source image. (more details...) |
||||||||||||||||||||||||||||||||||||||
![]() ![]() |
Sets the X-offset of the origin of the color-sample or color element region from the source image. (summarize)Sets the X-offset of the origin of the color-sample or color element region from the source image. (more details...) |
||||||||||||||||||||||||||||||||||||||
![]() ![]() |
Specifies that the X-offset is equal to 0. |
||||||||||||||||||||||||||||||||||||||
![]() ![]() |
Specifies the X-offset, in pixels. |
||||||||||||||||||||||||||||||||||||||
![]() ![]() |
Sets the Y-offset of the origin of the color-sample or color element region from the source image. (summarize)Sets the Y-offset of the origin of the color-sample or color element region from the source image. (more details...) |
||||||||||||||||||||||||||||||||||||||
![]() ![]() |
Specifies that the Y-offset is equal to 0. |
||||||||||||||||||||||||||||||||||||||
![]() ![]() |
Specifies the Y-offset, in pixels. |
||||||||||||||||||||||||||||||||||||||
![]() ![]() |
Sets the width (X-size) of the color-sample or color element region. (summarize)Sets the width (X-size) of the color-sample or color element region. (more details...) |
||||||||||||||||||||||||||||||||||||||
![]() ![]() |
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. |
||||||||||||||||||||||||||||||||||||||
![]() ![]() |
Specifies the width, in pixels. |
||||||||||||||||||||||||||||||||||||||
![]() ![]() |
Sets the height (Y-size) of the color-sample or color element region. (summarize)Sets the height (Y-size) of the color-sample or color element region. (more details...) |
||||||||||||||||||||||||||||||||||||||
![]() ![]() |
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. |
||||||||||||||||||||||||||||||||||||||
![]() ![]() |
Specifies the height, in pixels. |
||||||||||||||||||||||||||||||||||||||
![]() ![]() |
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)Specifies to add a color-sample or color element using three explicit values for the color components (RGB, HSL, or CIELAB). (more details...) |
||||||||||||||||||||||||||||||||||||||
![]() ![]() |
Sets the value of the first color component. INQ (summarize)Sets the value of the first color component. INQ (more details...) |
||||||||||||||||||||||||||||||||||||||
![]() ![]() |
Sets the value of the second color component. INQ (summarize)Sets the value of the second color component. INQ (more details...) |
||||||||||||||||||||||||||||||||||||||
![]() ![]() |
Sets the value of the third color component. INQ (summarize)Sets the value of the third color component. INQ (more details...) |
You can add the following value to the above-mentioned values to specify additional color elements to add to an already existing color-sample.
![]() |
|||||||||||||||||||||||||||||||||||||||
![]() ![]() |
Description | ||||||||||||||||||||||||||||||||||||||
![]() ![]() |
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)Adds the specified color element to the specified color-sample. (more details...) |
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.
![]() |
|||||||||||||||||||||||||||||||||||||||
![]() ![]() |
Description | ||||||||||||||||||||||||||||||||||||||
Param1 | |||||||||||||||||||||||||||||||||||||||
Param2 | |||||||||||||||||||||||||||||||||||||||
Param3 | |||||||||||||||||||||||||||||||||||||||
Param4 | |||||||||||||||||||||||||||||||||||||||
![]() ![]() |
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)Specifies to delete one or all color-samples or color elements, depending on the UserLabelOrIndex parameter setting. (more details...) |
Header | Include mil.h. |
Library | Use mil.lib; milcolor.lib. |
DLL | Requires mil.dll; milcolor.dll. |