| MIL 10 Reference
| Customize Help
| Save Settings

McolProject


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
McolPreprocess
McolRestore
Synopsis
Perform a color projection.
Syntax
void McolProject(
MIL_ID Src1ImageId, //in
MIL_ID Src2ImageOrArrayId, //in
MIL_ID DestImageOrArrayId, //in
MIL_ID DestMaskImageId, //in
MIL_INT64 Operation, //in
MIL_INT64 ControlFlag, //in
MIL_INT *StatusPtr //out
)
Description

This function performs a color projection (transformation) of the source image, or returns a color projection matrix, which you can then apply to transform other images, using MimConvert(). McolProject() allows you to separate a selected color from a rejected one, or to convert color images to grayscale with minimal loss of information. You can also use this function to perform analytical tasks, such as calculating an image's covariance matrix or the principal components of an image's color information.

The calculated projection results are written in the specified destination buffer (DestImageOrArrayId). If the calculated projection results create an image, you can restrict the area to which results are written in the destination buffer using a mask image (DestMaskImageId).

Color projection is an operation that requires data defined in a Cartesian coordinate system (for example, RGB or CIELAB). A projection with HSL data would provide incoherent results.

This function is optimized for images with a width (X-size) greater than seven pixels.

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
Src1ImageId

Specifies the identifier of the source image buffer on which to perform the projection transformation. This must be a 3-band 8- or 16-bit unsigned image. Source images are interpreted per band, independently of the MIL buffer format.

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.

When separating colors (M_COLOR_SEPARATION) and using a MIL array buffer to specify the separation colors (Src2ImageOrArrayId), set this parameter to M_NULL. In this case, the destination buffer will contain the resulting projection matrix, rather than the transformed image.

Src2ImageOrArrayId

Specifies the identifier of an image buffer or MIL array buffer that controls how the source pixels are interpreted.

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

DestImageOrArrayId

Specifies the identifier of the destination buffer in which to write the color projection (transformation) results. The destination buffer can be either an image or a MIL array buffer.

Note that when the result is a matrix, you must set this parameter to a MIL array buffer, allocated using MbufAlloc...() with M_ARRAY.

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

DestMaskImageId

Specifies the identifier of the destination mask image. The mask image must be monochrome. You can only specify a mask if the destination buffer is an image. If you do not require a mask, set this parameter to M_NULL.

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 destination mask determines where to write the result of the projection operation. Only masked pixels (non-zero) will be written to, in the destination image. The destination mask does not affect calculations.

Operation

Specifies the color projection operation.

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

ControlFlag

Specifies the dynamic range on which the resulting projection is mapped. This is only applicable for M_PRINCIPAL_COMPONENT_PROJECTION.

Set this parameter to M_DEFAULT if not used.

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

StatusPtr

Specifies the address of the variable in which to write the status of the color projection operation. If you do not require this information, set this parameter to M_NULL.

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

Parameter associations

The table below lists possible values for the Src2ImageOrArrayId, DestImageOrArrayId, Operation, and ControlFlag parameters and possible values returned to the StatusPtr parameter.

Note that you should set any unused parameters to M_DEFAULT.

function map For implementing the color projection
CollapseOperation Description
Src2ImageOrArrayId
DestImageOrArrayId
ControlFlag
StatusPtr
- Possible values returned
Collapse M_COLOR_SEPARATION

Removes a color from the source image. In this case, you must identify the background, selected, and rejected colors. The rejected color indicates the color to remove.

(summarize)
Collapse Src2ImageOrArrayId

Specifies the identifier of the buffer identifying the background, selected, and rejected pixel colors with which to perform the color separation.

If Src1ImageId is set to M_NULL, you must set Src2ImageOrArrayId to a MIL array buffer. In this case, the destination buffer will contain the resulting projection matrix for the specified background, selected, and rejected pixels colors, rather than the transformed source image.

(summarize)
Collapse Array buffer identifier

Specifies the identifier of a 3x3 MIL array buffer, where each row defines, in the following order, the background, the selected, and the rejected colors, to use to compute the projection matrix.
Collapse Image buffer identifier

Specifies the identifier of a data identification image buffer. This image determines which areas of the source image (Src1ImageId) have the background, selected, and rejected colors; these colors are then used to calculate the projection matrix. To identify the source image colors, you must set the corresponding pixels in the data identification image to one of the label values below.

Label value

Definition

M_BACKGROUND_LABEL

Identifies a background-color pixel.

M_REJECTED_LABEL

Identifies a rejected-color pixel.

M_SELECTED_LABEL

Identifies a selected-color pixel.

The calculation uses the average color value of all the pixels in the source image identified as background, selected, and rejected. You must assign at least one pixel in the data identification image to each of these values. Pixels in the source image that do not correspond to one of these values are ignored in the calculation. If the data identification image is smaller than the source image, the outlying source image pixels are ignored.

The data identification buffer must be a 1-band 8-bit unsigned image buffer and must not have a region of interest (ROI) associated with it. Using an image buffer with an ROI will cause an error.

(summarize)
Collapse DestImageOrArrayId

Specifies the identifier of the destination buffer in which to write the color separation results.

If Src1ImageId is set to M_NULL, you must set DestImageOrArrayId to a MIL array buffer.

(summarize)
Collapse Array buffer identifier

Specifies the identifier of a 4x3 MIL array buffer, of type float, to store the resulting projection matrix.

You can use this matrix with MimConvert() to separate colors in any 3-band color image. Be certain that the color distribution of all source images that use this matrix is similar, otherwise unpredictable results can occur.

(summarize)
Collapse Image buffer identifier

Specifies the identifier of a 3-band color image buffer, to store the transformed (color separated) source image.

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.

(summarize)
Collapse StatusPtr

Returns the resulting status of the M_COLOR_SEPARATION operation.

(summarize)
Collapse M_3_COLORS_COLLINEAR

Specifies an unsatisfactory status, indicating that the selected, rejected, and background colors are collinear.

If DestImageOrArrayId specifies an image buffer, it is a copy of the source image. If DestImageOrArrayId specifies an array buffer, it is filled with the identity matrix such that, using this array with MimConvert() copies the source image into the destination image.

(summarize)
Collapse M_NO_BACKGROUND_DEFINED

Specifies an unsatisfactory status, indicating that no background color was defined with the Src2ImageOrArrayId parameter.

If DestImageOrArrayId specifies an image buffer, it is a copy of the source image. If DestImageOrArrayId specifies an array buffer, it is filled with the identity matrix such that, using this array with MimConvert() copies the source image into the destination image.

(summarize)
Collapse M_NO_REJECTED_DEFINED

Specifies an unsatisfactory status, indicating that no rejected color was defined with the Src2ImageOrArrayId parameter.

If DestImageOrArrayId specifies an image buffer, it is a copy of the source image. If DestImageOrArrayId specifies an array buffer, it is filled with the identity matrix such that, using this array with MimConvert() copies the source image into the destination image.

(summarize)
Collapse M_NO_SELECTED_DEFINED

Specifies an unsatisfactory status, indicating that no selected color was defined with the Src2ImageOrArrayId parameter.

If DestImageOrArrayId specifies an image buffer, it is a copy of the source image. If DestImageOrArrayId specifies an array buffer, it is filled with the identity matrix such that, using this array with MimConvert() copies the source image into the destination image.

(summarize)
Collapse M_REJECTED_EQUAL_BACKGROUND

Specifies an unsatisfactory status, indicating that the rejected color equals the background color.

If DestImageOrArrayId specifies an image buffer, it is a copy of the source image. If DestImageOrArrayId specifies an array buffer, it is filled with the identity matrix such that, using this array with MimConvert() copies the source image into the destination image.

(summarize)
Collapse M_REJECTED_EQUAL_SELECTED

Specifies an unsatisfactory status, indicating that the rejected color equals the selected color.

If DestImageOrArrayId specifies an image buffer, it is a copy of the source image. If DestImageOrArrayId specifies an array buffer, it is filled with the identity matrix such that, using this array with MimConvert() copies the source image into the destination image.

(summarize)
Collapse M_SELECTED_EQUAL_BACKGROUND

Specifies an unsatisfactory status, indicating that the selected color equals the background color. In this case, although the operation was performed, MIL internally used, as the selected color, a color that is perpendicular to the rejected color.

(summarize)
Collapse M_SUCCESS

Specifies a successful operation.
Collapse M_COVARIANCE

Calculates the covariance matrix of the source image's color information. This is a measure of the color variation.

(summarize)
Collapse Src2ImageOrArrayId

Specifies the identifier of the buffer that controls how the source pixels are interpreted when performing the covariance calculation.

(summarize)
Collapse M_NULL

Specifies to use the entire source image to compute the covariance matrix.
Collapse Image buffer identifier

Specifies the identifier of a data identification image buffer. This image determines which areas of the source image (Src1ImageId) to use to compute the covariance matrix. To specify an area, you must set the corresponding pixels in the data identification image to M_SOURCE_LABEL.

You must assign at least one pixel in the data identification image to M_SOURCE_LABEL. Pixels in the source image that do not correspond to M_SOURCE_LABEL are ignored in the calculation. If the data identification image is smaller than the source image, the outlying source image pixels are ignored.

The data identification buffer must be a 1-band 8-bit unsigned image buffer and must not have a region of interest (ROI) associated with it. Using an image buffer with an ROI will cause an error.

(summarize)
Collapse DestImageOrArrayId

Specifies the identifier of a 3x3 or 4x3 MIL array buffer, of type float, to store the resulting covariance matrix. The data returned depends on the array's dimensions:

  • 3x3.

    The covariance matrix elements are returned columnwise.

  • 4x3.

    In addition to the 3x3 array results, the mean color of the source image areas (M_SOURCE_LABEL) is returned in the fourth column.

(summarize)
Collapse StatusPtr

Returns the resulting status of the M_COVARIANCE operation.

(summarize)
Collapse M_NO_SOURCE_DEFINED

Specifies an unsatisfactory status, indicating that there was no pixel in the data identification image that was set to M_SOURCE_LABEL.

The resulting matrix (DestImageOrArrayId) is filled with zeros.

(summarize)
Collapse M_SUCCESS

Specifies a successful operation.
Collapse M_PRINCIPAL_COMPONENT_PROJECTION

Performs a principal component projection of the source image. This converts each color pixel to a grayscale value with a point-to-point projection of the source image, onto its first principal component, using a grayscale LUT. The projection is a mathematically optimal color-to-grayscale transformation, which uses the distribution of the source image's color data to calculate the best grayscale conversion possible, minimizing the loss of information.

MIL performs a principal component analysis (PCA) to calculate the color image's principal components. The strongest is the first principal component. If no principal component is the strongest, one is arbitrarily considered the first principal component.

(summarize)
Collapse Src2ImageOrArrayId

Specifies the identifier of the buffer that controls how the source pixels are interpreted to calculate the first principal component, which is used to perform the principal component projection.

(summarize)
Collapse M_NULL

Specifies to use the entire source image to perform the principal component projection.
Collapse Image buffer identifier

Specifies the identifier of a data identification image buffer. This image determines which areas of the source image (Src1ImageId) to use to calculate the first principal component, which is used to perform the principal component projection. To specify an area, you must set the corresponding pixels in the data identification image to M_SOURCE_LABEL.

If there is ambiguity between which colors should be designated as light and dark, set some pixels in the data identification image to M_BRIGHT_LABEL and M_DARK_LABEL. M_BRIGHT_LABEL identifies source pixels that represent the color to project on the brightest side of the grayscale palette, while M_DARK_LABEL identifies source pixels that represent the color to project on the darkest side. These labels are optional and pixels designated as bright or dark are not used in the principal component projection for anything other than determining which colors are light and dark. Therefore, use as few pixels as necessary for this purpose. MIL uses the mean color of the bright or dark pixels if you set multiple pixels to bright or dark.

You must assign at least one pixel in the data identification image to M_SOURCE_LABEL. Pixels in the source image that do not correspond to M_SOURCE_LABEL are ignored in the calculation. If the data identification image is smaller than the source image, the outlying source image pixels are ignored.

The data identification image must be a 1-band 8-bit unsigned image buffer and must not have a region of interest (ROI) associated with it. Using an image buffer with an ROI will cause an error.

(summarize)
Collapse DestImageOrArrayId

Specifies the identifier of the destination buffer in which to write the principal component results.

(summarize)
Collapse Array buffer identifier

Specifies the identifier of a 4x1 MIL array buffer, of type float, to store the resulting projection matrix.

You can use this matrix with MimConvert() to perform a color-to-grayscale transformation of any 3-band color image. Be certain that the color distribution of all source images that use this matrix is similar, otherwise unpredictable results can occur.

(summarize)
Collapse Image buffer identifier

Specifies the identifier of a 1-band image buffer, to store the transformed source image.

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.

(summarize)
Collapse ControlFlag

Specifies whether MIL should perform the projection according to the dynamic range (minimum and maximum pixel values) established from all the pixels in the source image, or according to the dynamic range established from only the specified source image pixels (M_SOURCE_LABEL) identified with the data identification image.

(summarize)
Collapse M_DEFAULT

Performs the projection according to the dynamic range of all the pixels in the source image.
Collapse M_MASK_CONTRAST_ENHANCEMENT

Performs the projection according to the dynamic range of the pixels identified with the data identification image. The result is similar to increasing the contrast. When using M_MASK_CONTRAST_ENHANCEMENT, MIL saturates the projected unidentified source image colors that are outside the dynamic range of the identified source image pixels' color; that is, MIL maps those colors to either the minimum or maximum allowable grayscale value. In this case, the projection result can contain sections that have lost a certain degree of contrast information.

(summarize)
Collapse StatusPtr

Returns the resulting status of the M_PRINCIPAL_COMPONENT_PROJECTION operation.

(summarize)
Collapse M_NO_SOURCE_DEFINED

Specifies an unsatisfactory status, indicating that there was no pixel in the data identification image that was set to M_SOURCE_LABEL.

If DestImageOrArrayId specifies an image buffer, it is a copy of the source image. If DestImageOrArrayId specifies an array buffer, it is filled with the identity matrix such that, using this array with MimConvert() copies the source image into the destination image.

(summarize)
Collapse M_SUCCESS

Specifies a successful operation.
Collapse M_UNSTABLE_POLARITY

Specifies an unsatisfactory status, indicating that the polarity of the projection is unstable. In this case, although the operation was performed, it was not possible to confidently determine, in a consistent and repeatable way, which pixels should be projected to the brightest/darkest side of the grayscale palette.

(summarize)
Collapse M_PRINCIPAL_COMPONENTS

Calculates the principal components of the source image's color information. The principal components correspond to the three eigenvectors of the image's covariance matrix. With M_PRINCIPAL_COMPONENTS, you can also retrieve each eigenvector's eigenvalue and the source image's average color.

To calculate the principal components, MIL performs a principal component analysis (PCA).

(summarize)
Collapse Src2ImageOrArrayId

Specifies the identifier of the buffer that controls how the source pixels are interpreted to perform the principal component calculation.

(summarize)
Collapse M_NULL

Specifies to use the entire source image to calculate the principal components.
Collapse Image buffer identifier

Specifies the identifier of a data identification image buffer. This image determines which areas of the source image (Src1ImageId) to use to calculate the principal components. To specify an area, you must set the appropriate pixels in the data identification image to M_SOURCE_LABEL.

You must assign at least one pixel in the data identification image to M_SOURCE_LABEL. Pixels in the source image that do not correspond to M_SOURCE_LABEL are ignored in the calculation. If the data identification image is smaller than the source image, the outlying source image pixels are ignored.

The data identification image must be a 1-band 8-bit unsigned image buffer and must not have a region of interest (ROI) associated with it. Using an image buffer with an ROI will cause an error.

(summarize)
Collapse DestImageOrArrayId

Specifies the identifier of the destination buffer in which to write the resulting data for each of the three principal components.

(summarize)
Collapse Array buffer identifier

Specifies the identifier of a 3x3, 4x3, or 5x3 MIL array buffer, of type float, to store the resulting data. The data returned depends on the array's dimensions:

  • 3x3.

    The three eigenvectors are returned columnwise in decreasing order of strength.

  • 4x3.

    In addition to the 3x3 array results, each eigenvectors's eigenvalue is returned in the fourth column. The eigenvalue corresponds to the eigenvector's strength.

  • 5x3.

    In addition to the 4x3 array results, the mean color of the source image areas (M_SOURCE_LABEL) is returned in the fifth column, band-by-band: SourceMeanValueBand0, SourceMeanValueBand1, and SourceMeanValueBand2.

(summarize)
Collapse StatusPtr

Returns the resulting status of the M_PRINCIPAL_COMPONENTS operation.

(summarize)
Collapse M_NO_SOURCE_DEFINED

Specifies an unsatisfactory status, indicating that there was no pixel in the data identification image that was set to M_SOURCE_LABEL.

The resulting matrix (DestImageOrArrayId) is filled with zeros.

(summarize)
Collapse M_SUCCESS

Specifies a successful operation.
Collapse M_UNSTABLE_POLARITY

Specifies an unsatisfactory status, indicating that the direction of the first principal component is unstable. In this case, although the operation was performed, it was not possible to align the first principal component, in a consistent and repeatable way, with the gray axis (from black to white).

(summarize)
Collapse M_UNSTABLE_PRINCIPAL_COMPONENT_2

Specifies an unsatisfactory status, indicating that the direction of the third principal component (least important) is unstable. Although the operation was performed, this status result typically means that there were small variances along the color component's direction.

(summarize)
Collapse M_UNSTABLE_PRINCIPAL_COMPONENTS_12

Specifies an unsatisfactory status, indicating that the direction of the second and third principal components are unstable. Although the operation was performed, this status result typically means that there were small variances along the color component's direction.

(summarize)
Collapse M_UNSTABLE_PRINCIPAL_COMPONENTS_012

Specifies an unsatisfactory status, indicating that the direction of all principal components are unstable.

The resulting matrix (DestImageOrArrayId) is filled with zeros.

(summarize)
Compilation information
Header Include mil.h.
Library Use mil.lib; milcolor.lib.
DLL Requires mil.dll; milcolor.dll.
UNSIGNED PROC NONE PROC PROC PROC NONE COLOR SEPARATION UNSIGNED PROC NONE FLOAT NONE 3 COLORS COLLINEAR NO BACKGROUND DEFINED NO REJECTED DEFINED NO SELECTED DEFINED REJECTED EQUAL BACKGROUND REJECTED EQUAL SELECTED SELECTED EQUAL BACKGROUND SUCCESS COVARIANCE NULL UNSIGNED PROC NONE NO SOURCE DEFINED SUCCESS PRINCIPAL COMPONENT PROJECTION NULL UNSIGNED PROC NONE FLOAT PROC NONE DEFAULT MASK CONTRAST ENHANCEMENT NO SOURCE DEFINED SUCCESS UNSTABLE POLARITY PRINCIPAL COMPONENTS NULL UNSIGNED PROC NONE FLOAT NO SOURCE DEFINED SUCCESS UNSTABLE POLARITY UNSTABLE PRINCIPAL COMPONENT 2 UNSTABLE PRINCIPAL COMPONENTS 12 UNSTABLE PRINCIPAL COMPONENTS 012