| Customize Help
| Save Settings

McolGetResult


Function Map
Syntax
Description
Parameters
- ResultId
- AreaLabel
Table: For specifying the target area's label
- ColorSampleIndexOrLabel
Table: For specifying the color-sample
- ResultType
- ResultArrayPtr
Parameter Associations
Table: For retrieving general results relating to the color matching context
Table: For retrieving general target area results
Table: For retrieving color-sample results
+ combination: For determining whether results are available
+ combination: For determining the required array size (number of elements) to store the returned values
+ combination: For specifying the data type
Compilation information
Synopsis
Get the specified type of results from a color matching result buffer.
Syntax
void McolGetResult(
MIL_ID ResultId, //in
MIL_INT AreaLabel, //in
MIL_INT ColorSampleIndexOrLabel, //in
MIL_INT64 ResultType, //in
void *ResultArrayPtr //out
)
Description

This function retrieves the results of the specified type from a color matching result buffer. Results are only available after calling McolMatch(), and are organized by target area labels and color-sample indices. You can get results obtained from a specific target area or for all target areas. Similarly, you can get results obtained from a specific color-sample or for all color-samples.

To determine the order of the results, use M_AREA_LABEL_VALUE, and set the AreaLabel parameter to M_ALL and the ColorSampleIndexOrLabel parameter to M_GENERAL.

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 which MIL system’s documentation you should use in its place and any possible differences.
Parameters
This function is not supported on the selected boards.
This function reference has not been updated for the selected MIL system. To show the content of this page, choose a second MIL system; refer to the MIL system's release note to see which MIL system’s documentation to choose and any possible differences.
Parameters
ResultId

Specifies the identifier of the color matching result buffer from which to get results.

AreaLabel

Specifies the label of the target area(s) for which to get results.

Target areas are specified using McolMatch() with the AreaIdentifierImageId parameter. If you set AreaIdentifierImageId to M_NULL, you must set the AreaLabel parameter to M_ALL or M_DEFAULT.

Set this parameter to one of the following values.

function map For specifying the target area's label
Click to summarizeValue Description
Click to summarize M_DEFAULT

Same as M_ALL.
Click to summarize M_ALL

Specifies to retrieve results for each target area.
Click to summarize M_GENERAL

Specifies to retrieve general results relating to the color matching context. This type of result is not specific to any one target area or color-sample.

(summarize)
Click to summarize Value > 0

Specifies a specific target area's label.
ColorSampleIndexOrLabel

Specifies the color-sample(s) for which to get results. Set this parameter to one of the following values.

function map For specifying the color-sample
Click to summarizeValue Description
Click to summarize

Specifies the index of a color-sample.

(summarize)
Parameters

Specifies an index value from 0 (inclusive) to the number of defined color-samples minus 1.
Click to summarize

Specifies the label of a color-sample.

(summarize)
Parameters

Specifies a label value greater than 0.
Click to summarize M_ALL

Specifies to retrieve results for each color-sample. Results are ordered according to the color-sample's index value, in increasing order.

(summarize)
Click to summarize M_GENERAL

Specifies to retrieve general results not specific to any one color-sample.
ResultType

Specifies the type of result to retrieve.

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

ResultArrayPtr
Accepts the address of one of the following (see the Parameter associations section for specifics on which is expected):
  • array of type MIL_DOUBLE [optionally, in C++: a reference to a std::vector<MIL_DOUBLE> ]
  • array of type MIL_FLOAT [optionally, in C++: a reference to a std::vector<MIL_FLOAT> ]
  • array of type MIL_ID [optionally, in C++: a reference to a std::vector<MIL_ID> ]
  • array of type MIL_INT [optionally, in C++: a reference to a std::vector<MIL_INT> ]
  • array of type MIL_INT16 [optionally, in C++: a reference to a std::vector<MIL_INT16> ]
  • array of type MIL_INT32 [optionally, in C++: a reference to a std::vector<MIL_INT32> ]
  • array of type MIL_INT64 [optionally, in C++: a reference to a std::vector<MIL_INT64> ]
  • MIL_DOUBLE
  • MIL_FLOAT
  • MIL_ID
  • MIL_INT
  • MIL_INT16
  • MIL_INT32
  • MIL_INT64

Specifies the address of the first element of the array in which to write the requested information.

This array must be large enough to hold all entries. For example, if you retrieve results for all target areas and color-samples, you must account for the following array size: NumberOfTargetAreas x NumberOfSamples.

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

Parameter associations

The tables below list possible values for the ResultType parameter and possible values returned to the ResultArrayPtr parameter.

To retrieve general results relating to the color matching context, the ResultType parameter can be set to one of the following values. In this case, you must set the AreaLabel and ColorSampleIndexOrLabel parameters to M_GENERAL.

function map For retrieving general results relating to the color matching context
Click to summarize
ResultType		 Description
ResultArrayPtr
- Possible values returned
Click to summarize M_AREA_IMAGE_SIGN +

Retrieves the data type required for the image buffer in which to draw the target area(s) of the area identifier image (McolDraw() with M_DRAW_AREA).

This result is available after you specify an area identifier image with McolMatch(), enable the McolControl() M_SAVE_AREA_IMAGE control type, and find a match.

(summarize)
Expand data type infoCollapse data type info ResultArrayPtr extra info
Data type info: Data type: address of a MIL_DOUBLE MORE
Click to summarize M_UNSIGNED

Specifies unsigned data.
Click to summarize M_AREA_IMAGE_SIZE_BAND +

Retrieves the number of surfaces (color bands) required for the image buffer in which to draw the target area(s) of the area identifier image (McolDraw() with M_DRAW_AREA).

This result is available after you specify an area identifier image with McolMatch(), enable the McolControl() M_SAVE_AREA_IMAGE control type, and find a match.

(summarize)
Expand data type infoCollapse data type info ResultArrayPtr extra info
Data type info: Data type: address of a MIL_DOUBLE MORE
Click to summarize 1

Specifies 1 color band.
Click to summarize M_AREA_IMAGE_SIZE_BIT +

Retrieves the depth per band required for the image buffer in which to draw the target area(s) of the area identifier image (McolDraw() with M_DRAW_AREA).

This result is available after you specify an area identifier image with McolMatch(), enable the McolControl() M_SAVE_AREA_IMAGE control type, and find a match.

(summarize)
Expand data type infoCollapse data type info ResultArrayPtr extra info
Data type info: Data type: address of a MIL_DOUBLE MORE
Click to summarize 1

Specifies 1-bit data depth per band.
Click to summarize 8

Specifies 8-bit data depth per band.
Click to summarize 16

Specifies 16-bit data depth per band.
Click to summarize M_AREA_IMAGE_SIZE_X +

Retrieves the width required for the image buffer in which to draw the target area(s) of the area identifier image (McolDraw() with M_DRAW_AREA).

This result is available after you specify an area identifier image with McolMatch(), enable the McolControl() M_SAVE_AREA_IMAGE control type, and find a match.

(summarize)
Expand data type infoCollapse data type info ResultArrayPtr extra info
Data type info: Data type: address of a MIL_DOUBLE MORE
Click to summarize Value

Specifies the width of the image buffer, in pixels.
Click to summarize M_AREA_IMAGE_SIZE_Y +

Retrieves the height required for the image buffer in which to draw the target area(s) of the area identifier image (McolDraw() with M_DRAW_AREA).

This result is available after you specify an area identifier image with McolMatch(), enable the McolControl() M_SAVE_AREA_IMAGE control type, and find a match.

(summarize)
Expand data type infoCollapse data type info ResultArrayPtr extra info
Data type info: Data type: address of a MIL_DOUBLE MORE
Click to summarize Value

Specifies the height of the image buffer, in pixels.
Click to summarize M_AREA_IMAGE_TYPE +

Retrieves the data type and depth required for the image buffer in which to draw the target area(s) of the area identifier image (McolDraw() with M_DRAW_AREA).

This result is available after you specify an area identifier image with McolMatch(), enable the McolControl() M_SAVE_AREA_IMAGE control type, and find a match.

(summarize)
Expand data type infoCollapse data type info ResultArrayPtr extra info
Data type info: Data type: address of a MIL_DOUBLE MORE
Click to summarize M_UNSIGNED + 1

Specifies 1-bit unsigned data.
Click to summarize M_UNSIGNED + 8

Specifies 8-bit unsigned data.
Click to summarize M_UNSIGNED + 16

Specifies 16-bit unsigned data.
Click to summarize M_AREA_MATCH_IMAGE_SIZE_X +

Retrieves the width required for the image buffer in which to draw (for each target area) the color or label of the best-matched color-sample (McolDraw() or McolMatch() with M_DRAW_AREA_MATCH_USING_COLOR or M_DRAW_AREA_MATCH_USING_LABEL).

This result is available after you enable the McolControl() M_SAVE_AREA_IMAGE control type (required for McolDraw()), and find a match.

(summarize)
Expand data type infoCollapse data type info ResultArrayPtr extra info
Data type info: Data type: address of a MIL_DOUBLE MORE
Click to summarize Value

Specifies the width of the image buffer, in pixels.
Click to summarize M_AREA_MATCH_IMAGE_SIZE_Y +

Retrieves the height required for the image buffer in which to draw (for each target area) the color or label of the best-matched color-sample (McolDraw() or McolMatch() with M_DRAW_AREA_MATCH_USING_COLOR or M_DRAW_AREA_MATCH_USING_LABEL).

This result is available after you enable the McolControl() M_SAVE_AREA_IMAGE control type (required for McolDraw()), and find a match.

(summarize)
Expand data type infoCollapse data type info ResultArrayPtr extra info
Data type info: Data type: address of a MIL_DOUBLE MORE
Click to summarize Value

Specifies the height of the image buffer, in pixels.
Click to summarize M_DISTANCE_IMAGE_SIGN +

Retrieves the data type required for the image buffer in which to draw the distance between the color of the target area (for an M_STAT_MIN_DIST operation mode) or target pixel (for an M_MIN_DIST_VOTE operation mode), and the color of its best-matched color-sample (McolDraw() or McolMatch() with M_DRAW_DISTANCE). Operation modes are set with McolSetMethod().

This result is available after you enable the McolControl() M_GENERATE_DISTANCE_IMAGE control type (required for McolDraw()), and find a match.

Note that if you have normalized distances by the maximum distance calculated, using McolControl() with M_DISTANCE_IMAGE_NORMALIZE set to M_MAX_NORMALIZE, you can draw the distance image in an unsigned image buffer.

This result is not available if the operation mode is set to M_HISTOGRAM_MATCHING or M_HISTOGRAM_VOTE (McolSetMethod()).

(summarize)
Expand data type infoCollapse data type info ResultArrayPtr extra info
Data type info: Data type: address of a MIL_DOUBLE MORE
Click to summarize M_FLOAT

Specifies floating-point data.
Click to summarize M_DISTANCE_IMAGE_SIZE_BAND +

Retrieves the number of surfaces (color bands) required for the image buffer in which to draw the distance between the color of the target area (for an M_STAT_MIN_DIST operation mode) or target pixel (for an M_MIN_DIST_VOTE operation mode), and the color of its best-matched color-sample (McolDraw() or McolMatch() with M_DRAW_DISTANCE). Operation modes are set with McolSetMethod().

This result is available after you enable the McolControl() M_GENERATE_DISTANCE_IMAGE control type (required for McolDraw()), and find a match.

This result is not available if the operation mode is set to M_HISTOGRAM_MATCHING or M_HISTOGRAM_VOTE (McolSetMethod()).

(summarize)
Expand data type infoCollapse data type info ResultArrayPtr extra info
Data type info: Data type: address of a MIL_DOUBLE MORE
Click to summarize 1

Specifies 1 color band.
Click to summarize M_DISTANCE_IMAGE_SIZE_BIT +

Retrieves the depth per band required for the image buffer in which to draw the distance between the color of the target area (for an M_STAT_MIN_DIST operation mode) or target pixel (for an M_MIN_DIST_VOTE operation mode), and the color of its best-matched color-sample (McolDraw() or McolMatch() with M_DRAW_DISTANCE). Operation modes are set with McolSetMethod().

This result is available after you enable the McolControl() M_GENERATE_DISTANCE_IMAGE control type (required for McolDraw()), and find a match.

This result is not available if the operation mode is set to M_HISTOGRAM_MATCHING or M_HISTOGRAM_VOTE (McolSetMethod()).

(summarize)
Expand data type infoCollapse data type info ResultArrayPtr extra info
Data type info: Data type: address of a MIL_DOUBLE MORE
Click to summarize 32

Specifies 32-bit data depth per band.
Click to summarize M_DISTANCE_IMAGE_SIZE_X +

Retrieves the width required for the image buffer in which to draw the distance between the color of the target area (for an M_STAT_MIN_DIST operation mode) or target pixel (for an M_MIN_DIST_VOTE operation mode), and the color of its best-matched color-sample (McolDraw() or McolMatch() with M_DRAW_DISTANCE). Operation modes are set with McolSetMethod().

This result is available after you enable the McolControl() M_GENERATE_DISTANCE_IMAGE control type (required for McolDraw()), and find a match.

This result is not available if the operation mode is set to M_HISTOGRAM_MATCHING or M_HISTOGRAM_VOTE (McolSetMethod()).

(summarize)
Expand data type infoCollapse data type info ResultArrayPtr extra info
Data type info: Data type: address of a MIL_DOUBLE MORE
Click to summarize Value

Specifies the width of the image buffer, in pixels.
Click to summarize M_DISTANCE_IMAGE_SIZE_Y +

Retrieves the height required for the image buffer in which to draw the distance between the color of the target area (for an M_STAT_MIN_DIST operation mode) or target pixel (for an M_MIN_DIST_VOTE operation mode), and the color of its best-matched color-sample (McolDraw() or McolMatch() with M_DRAW_DISTANCE). Operation modes are set with McolSetMethod().

This result is available after you enable the McolControl() M_GENERATE_DISTANCE_IMAGE control type (required for McolDraw()), and find a match.

This result is not available if the operation mode is set to M_HISTOGRAM_MATCHING or M_HISTOGRAM_VOTE (McolSetMethod()).

(summarize)
Expand data type infoCollapse data type info ResultArrayPtr extra info
Data type info: Data type: address of a MIL_DOUBLE MORE
Click to summarize Value

Specifies the height of the image buffer, in pixels.
Click to summarize M_DISTANCE_IMAGE_TYPE +

Retrieves the data type and depth required for the image buffer in which to draw the distance between the color of the target area (for an M_STAT_MIN_DIST operation mode) or target pixel (for an M_MIN_DIST_VOTE operation mode), and the color of its best-matched color-sample (McolDraw() or McolMatch() with M_DRAW_DISTANCE). Operation modes are set with McolSetMethod().

This result is available after you enable the McolControl() M_GENERATE_DISTANCE_IMAGE control type (required for McolDraw()), and find a match.

Note that if you have normalized distances by the maximum distance calculated, using McolControl() with M_DISTANCE_IMAGE_NORMALIZE set to M_MAX_NORMALIZE, you can draw the distance image in an unsigned image buffer.

This result is not available if the operation mode is set to M_HISTOGRAM_MATCHING or M_HISTOGRAM_VOTE (McolSetMethod()).

(summarize)
Expand data type infoCollapse data type info ResultArrayPtr extra info
Data type info: Data type: address of a MIL_DOUBLE MORE
Click to summarize M_FLOAT + 32

Specifies 32-bit floating-point data.
Click to summarize M_MAX_DISTANCE +

Retrieves the maximum (largest) color distance among all distances between the target area and all matching color-samples.

When the operation mode is M_STAT_MIN_DIST (McolSetMethod()), the largest color distance refers to the maximal distance among all areas that were matched with a color-sample.

When the operation mode is M_MIN_DIST_VOTE (McolSetMethod()), the largest color distance refers to the maximal distance among all the pixels that voted for a color-sample.

The maximum distance value is used internally when drawing the color distance of the area identifier image (McolDraw() or McolMatch() with M_DRAW_DISTANCE).

This result is not available if the operation mode is set to M_HISTOGRAM_MATCHING or M_HISTOGRAM_VOTE (McolSetMethod()).

(summarize)
Expand data type infoCollapse data type info ResultArrayPtr extra info
Data type info: Data type: address of a MIL_DOUBLE
Click to summarize M_NUMBER_OF_AREAS +

Retrieves the number of target areas in the area identifier image with which you performed the matching operation.

(summarize)
Expand data type infoCollapse data type info ResultArrayPtr extra info
Data type info: Data type: address of a MIL_DOUBLE MORE
Click to summarize M_NUMBER_OF_SAMPLES +

Retrieves the number of color-samples defined in the context.

(summarize)
Expand data type infoCollapse data type info ResultArrayPtr extra info
Data type info: Data type: address of a MIL_DOUBLE MORE
Click to summarize M_PIXEL_MATCH_IMAGE_SIZE_X +

Retrieves the width required for the image buffer in which to draw (for each pixel in each target area) the color or label of the color-sample for which each pixel voted (McolDraw() or McolMatch() with M_DRAW_PIXEL_MATCH_USING_COLOR or M_DRAW_PIXEL_MATCH_USING_LABEL).

This result is not available if the operation mode is set to M_HISTOGRAM_MATCHING (McolSetMethod()).

This result is available after you enable the McolControl() M_GENERATE_PIXEL_MATCH control type (required for McolDraw()), and find a match. You must also use McolSetMethod() with M_MIN_DIST_VOTE.

(summarize)
Expand data type infoCollapse data type info ResultArrayPtr extra info
Data type info: Data type: address of a MIL_DOUBLE MORE
Click to summarize Value

Specifies the width of the image buffer, in pixels.
Click to summarize M_PIXEL_MATCH_IMAGE_SIZE_Y +

Retrieves the height required for the image buffer in which to draw (for each pixel in each target area) the color or label of the color-sample for which each pixel voted (McolDraw() or McolMatch() with M_DRAW_PIXEL_MATCH_USING_COLOR or M_DRAW_PIXEL_MATCH_USING_LABEL).

This result is not available if the operation mode is set to M_HISTOGRAM_MATCHING (McolSetMethod()).

This result is available after you enable the McolControl() M_GENERATE_PIXEL_MATCH control type (required for McolDraw()), and find a match. You must also use McolSetMethod() with M_MIN_DIST_VOTE.

(summarize)
Expand data type infoCollapse data type info ResultArrayPtr extra info
Data type info: Data type: address of a MIL_DOUBLE MORE
Click to summarize Value

Specifies the height of the image buffer, in pixels.
Click to summarize M_SAMPLE_COLOR_SIGN +

Retrieves the data type required for the image buffer in which to draw (for each target area or for each pixel in each target area) the color of the best-matched color-sample or the color of the color-sample for which each pixel voted (McolDraw() or McolMatch() with M_DRAW_AREA_MATCH_USING_COLOR or M_DRAW_PIXEL_MATCH_USING_COLOR).

This result is available after you enable the McolControl() M_GENERATE_PIXEL_MATCH and M_GENERATE_SAMPLE_COLOR_LUT control types (required for McolDraw()), and find a match. You must also use McolSetMethod() with M_MIN_DIST_VOTE.

(summarize)
Expand data type infoCollapse data type info ResultArrayPtr extra info
Data type info: Data type: address of a MIL_DOUBLE MORE
Click to summarize M_SAMPLE_COLOR_SIZE_BAND +

Retrieves the number of surfaces (color bands) required for the image buffer in which to draw (for each target area or for each pixel in each target area) the color of the best-matched color-sample or the color of the color-sample for which each pixel voted (McolDraw() or McolMatch() with M_DRAW_AREA_MATCH_USING_COLOR or M_DRAW_PIXEL_MATCH_USING_COLOR).

This result is available after you enable the McolControl() M_GENERATE_PIXEL_MATCH and M_GENERATE_SAMPLE_COLOR_LUT control types (required for McolDraw()), and find a match. You must also use McolSetMethod() with M_MIN_DIST_VOTE.

(summarize)
Expand data type infoCollapse data type info ResultArrayPtr extra info
Data type info: Data type: address of a MIL_DOUBLE MORE
Click to summarize M_SAMPLE_COLOR_SIZE_BIT +

Retrieves the depth per band, in bits, required for the image buffer in which to draw (for each target area or for each pixel in each target area) the color of the best-matched color-sample or the color of the color-sample for which each pixel voted (McolDraw() or McolMatch() with M_DRAW_AREA_MATCH_USING_COLOR or M_DRAW_PIXEL_MATCH_USING_COLOR).

This result is available after you enable the McolControl() M_GENERATE_PIXEL_MATCH and M_GENERATE_SAMPLE_COLOR_LUT control types (required for McolDraw()), and find a match. You must also use McolSetMethod() with M_MIN_DIST_VOTE.

(summarize)
Expand data type infoCollapse data type info ResultArrayPtr extra info
Data type info: Data type: address of a MIL_DOUBLE MORE
Click to summarize M_SAMPLE_COLOR_TYPE +

Retrieves the data type and depth required for the image buffer in which to draw (for each target area or for each pixel in each target area) the color of the best-matched color-sample or the color of the color-sample for which each pixel voted (McolDraw() or McolMatch() with M_DRAW_AREA_MATCH_USING_COLOR or M_DRAW_PIXEL_MATCH_USING_COLOR).

This result is available after you enable the McolControl() M_GENERATE_PIXEL_MATCH and M_GENERATE_SAMPLE_COLOR_LUT control types (required for McolDraw()), and find a match. You must also use McolSetMethod() with M_MIN_DIST_VOTE.

(summarize)
Expand data type infoCollapse data type info ResultArrayPtr extra info
Data type info: Data type: address of a MIL_DOUBLE MORE
Click to summarize M_SAMPLE_LABEL_SIGN +

Retrieves the data type required for the image buffer in which to draw (for each target area or for each pixel in each target area) the label of the best-matched color-sample or the label of the color-sample for which each pixel voted (McolDraw() or McolMatch() with M_DRAW_AREA_MATCH_USING_LABEL or M_DRAW_PIXEL_MATCH_USING_LABEL).

(summarize)
Expand data type infoCollapse data type info ResultArrayPtr extra info
Data type info: Data type: address of a MIL_DOUBLE MORE
Click to summarize M_SAMPLE_LABEL_SIZE_BAND +

Retrieves the number of surfaces (color bands) required for the image buffer in which to draw (for each target area or for each pixel in each target area) the label of the best-matched color-sample or the label of the color-sample for which each pixel voted (McolDraw() or McolMatch() with M_DRAW_AREA_MATCH_USING_LABEL or M_DRAW_PIXEL_MATCH_USING_LABEL).

(summarize)
Expand data type infoCollapse data type info ResultArrayPtr extra info
Data type info: Data type: address of a MIL_DOUBLE MORE
Click to summarize M_SAMPLE_LABEL_SIZE_BIT +

Retrieves the depth per band, in bits, required for the image buffer in which to draw (for each target area or for each pixel in each target area) the label of the best-matched color-sample or the label of the color-sample for which each pixel voted (McolDraw() or McolMatch() with M_DRAW_AREA_MATCH_USING_LABEL or M_DRAW_PIXEL_MATCH_USING_LABEL).

(summarize)
Expand data type infoCollapse data type info ResultArrayPtr extra info
Data type info: Data type: address of a MIL_DOUBLE MORE
Click to summarize M_SAMPLE_LABEL_TYPE +

Retrieves the data type and depth required for the image buffer in which to draw (for each target area or for each pixel in each target area) the label of the best-matched color-sample or the label of the color-sample for which each pixel voted (McolDraw() or McolMatch() with M_DRAW_AREA_MATCH_USING_LABEL or M_DRAW_PIXEL_MATCH_USING_LABEL).

(summarize)
Expand data type infoCollapse data type info ResultArrayPtr extra info
Data type info: Data type: address of a MIL_DOUBLE MORE

To retrieve general results relating to a target area, the ResultType parameter can be set to one of the following values. In this case, you must set the AreaLabel parameter to a specific value (or M_ALL), and the ColorSampleIndexOrLabel parameter to M_GENERAL.

function map For retrieving general target area results
Click to summarize
ResultType		 Description
ResultArrayPtr
- Possible values returned
Click to summarize M_AREA_LABEL_VALUE +

Retrieves the label of the target areas you used to obtain results. If you do not specify an area identifier image with McolMatch(), the whole target image is labeled as target area 1.

(summarize)
Expand data type infoCollapse data type info ResultArrayPtr extra info
Data type info: Data type: array of type MIL_DOUBLE [optionally, in C++: a reference to a std::vector<MIL_DOUBLE> ]  |  address of a MIL_DOUBLE MORE
Click to summarize M_AREA_PIXEL_COUNT +

Retrieves the total number of pixels in the target area.

(summarize)
Expand data type infoCollapse data type info ResultArrayPtr extra info
Data type info: Data type: array of type MIL_DOUBLE [optionally, in C++: a reference to a std::vector<MIL_DOUBLE> ]  |  address of a MIL_DOUBLE MORE
Click to summarize M_BEST_MATCH_INDEX +

Retrieves the index of the target area's best-matched color-sample. If there is none, -1 is returned.

(summarize)
Expand data type infoCollapse data type info ResultArrayPtr extra info
Data type info: Data type: array of type MIL_DOUBLE [optionally, in C++: a reference to a std::vector<MIL_DOUBLE> ]  |  address of a MIL_DOUBLE MORE
Click to summarize M_BEST_MATCH_LABEL +

Retrieves the label of the target area's best-matched color-sample. If no color-samples are matched, the value you have set using McolControl() with M_OUTLIER_LABEL is returned.

(summarize)
Expand data type infoCollapse data type info ResultArrayPtr extra info
Data type info: Data type: array of type MIL_DOUBLE [optionally, in C++: a reference to a std::vector<MIL_DOUBLE> ]  |  address of a MIL_DOUBLE MORE
Click to summarize M_OUTLIER_COVERAGE +

Retrieves the outlier coverage, which is the percentage of the number of pixels in the target area that did not vote for any color-sample. Since this result is based on pixel votes, you must use McolSetMethod() with M_MIN_DIST_VOTE.

(summarize)
Expand data type infoCollapse data type info ResultArrayPtr extra info
Data type info: Data type: array of type MIL_DOUBLE [optionally, in C++: a reference to a std::vector<MIL_DOUBLE> ]  |  address of a MIL_DOUBLE MORE
Click to summarize M_SCORE_RELEVANCE +

Retrieves the relevance score of the target area, as a percentage. This value indicates the significance (relevance) of M_SCORE. In statistics, this is similar to the confidence level.

The target area's relevance score is based on the operation mode specified, using McolSetMethod():

  • M_STAT_MIN_DIST.

    RelevanceScore = (BestDistance)-1 / sum (Distance -1 ), where BestDistance is the distance of the best-matched color-sample, and the sum is over all color-samples that have been matched with the target area.

  • M_MIN_DIST_VOTE and M_HISTOGRAM_VOTE.

    RelevanceScore = sum(NumberOfVotes) / NumberOfPixelsInTheTargetArea , where sum(NumberOfVotes) refers to the total number of votes accumulated by all color-samples.

  • M_HISTOGRAM_MATCHING.

    RelevanceScore = (100.0 -BestScore)-1 / sum ((100.0 -Score)-1 ), where BestScore refers to the winning sample score, and the sum is over all color-samples.

(summarize)
Expand data type infoCollapse data type info ResultArrayPtr extra info
Data type info: Data type: array of type MIL_DOUBLE [optionally, in C++: a reference to a std::vector<MIL_DOUBLE> ]  |  address of a MIL_DOUBLE MORE
Click to summarize M_STATUS +

Retrieves the match status of the target area.

(summarize)
Expand data type infoCollapse data type info ResultArrayPtr extra info
Data type info: Data type: array of type MIL_DOUBLE [optionally, in C++: a reference to a std::vector<MIL_DOUBLE> ]  |  address of a MIL_DOUBLE MORE
Click to summarize M_FAILURE

Specifies that no color-samples have been matched.
Click to summarize M_SUCCESS

Specifies that at least one color-sample has been matched.

To retrieve results relating to a color-sample, the ResultType parameter can be set to one of the following values. In this case, you must set the AreaLabel parameter to a specific target area (or M_ALL) and the ColorSampleIndexOrLabel parameter to a specific color-sample (or M_ALL).

To retrieve color-sample results for all color-samples and all areas, set both the AreaLabel and ColorSampleIndexOrLabel parameter to M_ALL, and use M_NUMBER_OF_AREAS and M_NUMBER_OF_SAMPLES to set the size of the result array (NumberOfTargetAreas x NumberOfSamples). Note that to get a color-sample result, you must first refer to its target area.

function map For retrieving color-sample results
Click to summarize
ResultType		 Description
ResultArrayPtr
- Possible values returned
Click to summarize M_COLOR_DISTANCE +

Retrieves the color distance (difference) between the target area and the specified color-sample, when using McolSetMethod() with the M_STAT_MIN_DIST operation mode.

The significance of the distance value returned depends on the distance type that you have set, using McolSetMethod(). For example, a distance value of 1 when using an M_MAHALANOBIS distance type is not the same as when using an M_MANHATTAN distance type. Note that when matching in the CIELAB source color space, you will get distance results in the CIELAB native range.

(summarize)
Expand data type infoCollapse data type info ResultArrayPtr extra info
Data type info: Data type: array of type MIL_DOUBLE [optionally, in C++: a reference to a std::vector<MIL_DOUBLE> ]  |  address of a MIL_DOUBLE MORE
Click to summarize M_SAMPLE_COVERAGE +

Retrieves the proportion of pixels within the target area that voted for the color-sample, as a percentage. Since this result is based on pixel votes, you must use McolSetMethod() with M_MIN_DIST_VOTE.

(summarize)
Expand data type infoCollapse data type info ResultArrayPtr extra info
Data type info: Data type: array of type MIL_DOUBLE [optionally, in C++: a reference to a std::vector<MIL_DOUBLE> ]  |  address of a MIL_DOUBLE MORE
Click to summarize M_SAMPLE_LABEL_VALUE +

Retrieves the label of the color-sample corresponding to the specified index.

(summarize)
Expand data type infoCollapse data type info ResultArrayPtr extra info
Data type info: Data type: array of type MIL_DOUBLE [optionally, in C++: a reference to a std::vector<MIL_DOUBLE> ]  |  address of a MIL_DOUBLE MORE
Click to summarize M_SAMPLE_MATCH_STATUS +

Retrieves whether the specified color-sample fulfills the match conditions, with respect to the distance tolerance and acceptance. To determine if the color-sample is the best-matched color-sample, use M_BEST_MATCH_INDEX or M_BEST_MATCH_LABEL.

(summarize)
Expand data type infoCollapse data type info ResultArrayPtr extra info
Data type info: Data type: array of type MIL_DOUBLE [optionally, in C++: a reference to a std::vector<MIL_DOUBLE> ]  |  address of a MIL_DOUBLE MORE
Click to summarize M_MATCH

Specifies that the color-sample fulfills the match conditions.
Click to summarize M_NO_MATCH

Specifies that the color-sample does not fulfill the match conditions.
Click to summarize M_SAMPLE_PIXEL_COUNT +

Retrieves the number of pixels within the target area that voted for the color-sample, when using McolSetMethod() with M_MIN_DIST_VOTE.

(summarize)
Expand data type infoCollapse data type info ResultArrayPtr extra info
Data type info: Data type: array of type MIL_DOUBLE [optionally, in C++: a reference to a std::vector<MIL_DOUBLE> ]  |  address of a MIL_DOUBLE MORE
Click to summarize M_SCORE +

Retrieves the match score, as a percentage. This score indicates the similarity between the color of the color-sample and the color of the target area.

The color-sample's match score is based on the operation mode specified, using McolSetMethod():

  • M_STAT_MIN_DIST.

    MatchScore = [k / (k + Distance)] x [(MaxDistance - Distance) / MaxDistance], where Distance refers to the current color-sample distance and MaxDistance refers to the maximum distance possible (in the color space).

  • M_MIN_DIST_VOTE and M_HISTOGRAM_VOTE.

    MatchScore = NumberOfVotes / sum (NumberOfVotes), where NumberOfVotes refers to the current color-sample's number of votes, and the sum is over the number of votes for all color-samples.

  • M_HISTOGRAM_MATCHING.

    MatchScore refers to a measure of similarity between sample and target histograms.

(summarize)
Expand data type infoCollapse data type info ResultArrayPtr extra info
Data type info: Data type: array of type MIL_DOUBLE [optionally, in C++: a reference to a std::vector<MIL_DOUBLE> ]  |  address of a MIL_DOUBLE MORE
Combination value for the values listed in all the parameter association tables.

You can add the following value to the above-mentioned values to determine whether a result is available.

function map For determining whether results are available
Click to summarizeResultType Description
ResultArrayPtr
- Possible values returned
Click to summarize M_AVAILABLE

Retrieves whether a result is available to be returned.

(summarize)
Expand data type infoCollapse data type info ResultArrayPtr extra info
Data type info: Data type: address of a MIL_DOUBLE MORE
Click to summarize M_NULL

Specifies that the result is not available to be returned.
Click to summarize Value != 0

Specifies that the result is available to be returned.
Combination value for the values listed in For retrieving general target area results; the values listed in For retrieving color-sample results.

You can add the following value to the above-mentioned values to determine the required array size (number of elements) to store the returned values.

function map For determining the required array size (number of elements) to store the returned values
Click to summarizeResultType combination value Description
ResultArrayPtr
- Possible values returned
Click to summarize M_NB_ELEMENTS

Retrieves the required array size (number of elements) to store the returned values.

(summarize)
Expand data type infoCollapse data type info ResultArrayPtr extra info
Data type info: Data type: address of a MIL_DOUBLE MORE
Combination values for the values listed in all the parameter association tables.

You can add one of the following values to the above-mentioned values to cast the requested results to the required data type.

Some results might be altered if they do not fit numerically in the data type you specify. For example, if you cast a result value of 300 to a char, information will be lost. The default data type, double, will never result in lost information.

Note: In C++, when using a standard vector (std::vector) instead of an array, the values listed in this combination table must not be used. If you need to use a specific data type, instantiate the vector with the necessary data type.

function map For specifying the data type
Click to summarizeResultType Description
ResultArrayPtr
- Possible values returned
Click to summarize M_TYPE_MIL_DOUBLE

Casts the requested results to a MIL_DOUBLE.

(summarize)
Expand data type infoCollapse data type info ResultArrayPtr extra info
Data type info: Data type: array of type MIL_DOUBLE [optionally, in C++: a reference to a std::vector<MIL_DOUBLE> ]  |  address of a MIL_DOUBLE MORE
Click to summarize M_TYPE_MIL_FLOAT

Casts the requested results to a MIL_FLOAT.

(summarize)
Expand data type infoCollapse data type info ResultArrayPtr extra info
Data type info: Data type: array of type MIL_FLOAT [optionally, in C++: a reference to a std::vector<MIL_FLOAT> ]  |  address of a MIL_FLOAT MORE
Click to summarize M_TYPE_MIL_ID

Casts the requested results to a MIL_ID.

(summarize)
Expand data type infoCollapse data type info ResultArrayPtr extra info
Data type info: Data type: array of type MIL_ID [optionally, in C++: a reference to a std::vector<MIL_ID> ]  |  address of a MIL_ID MORE
Click to summarize M_TYPE_MIL_INT

Casts the requested results to a MIL_INT.

(summarize)
Expand data type infoCollapse data type info ResultArrayPtr extra info
Data type info: Data type: array of type MIL_INT [optionally, in C++: a reference to a std::vector<MIL_INT> ]  |  address of a MIL_INT MORE
Click to summarize M_TYPE_MIL_INT16

Casts the requested results to a MIL_INT16.

(summarize)
Expand data type infoCollapse data type info ResultArrayPtr extra info
Data type info: Data type: array of type MIL_INT16 [optionally, in C++: a reference to a std::vector<MIL_INT16> ]  |  address of a MIL_INT16 MORE
Click to summarize M_TYPE_MIL_INT32

Casts the requested results to a MIL_INT32.

(summarize)
Expand data type infoCollapse data type info ResultArrayPtr extra info
Data type info: Data type: array of type MIL_INT32 [optionally, in C++: a reference to a std::vector<MIL_INT32> ]  |  address of a MIL_INT32 MORE
Click to summarize M_TYPE_MIL_INT64

Casts the requested results to a MIL_INT64.

(summarize)
Expand data type infoCollapse data type info ResultArrayPtr extra info
Data type info: Data type: array of type MIL_INT64 [optionally, in C++: a reference to a std::vector<MIL_INT64> ]  |  address of a MIL_INT64 MORE
Compilation information
Header Include mil.h.
Library Use mil.lib; milcolor.lib.
DLL Requires mil.dll; milcolor.dll.
DEFAULT ALL GENERAL NUMBER OF SAMPLES ALL GENERAL AREA IMAGE SIGN UNSIGNED AREA IMAGE SIZE BAND AREA IMAGE SIZE BIT AREA IMAGE SIZE X AREA IMAGE SIZE Y AREA IMAGE TYPE UNSIGNED 1 UNSIGNED 8 UNSIGNED 16 AREA MATCH IMAGE SIZE X AREA MATCH IMAGE SIZE Y DISTANCE IMAGE SIGN FLOAT DISTANCE IMAGE SIZE BAND DISTANCE IMAGE SIZE BIT DISTANCE IMAGE SIZE X DISTANCE IMAGE SIZE Y DISTANCE IMAGE TYPE FLOAT 32 MAX DISTANCE NUMBER OF AREAS NUMBER OF SAMPLES PIXEL MATCH IMAGE SIZE X PIXEL MATCH IMAGE SIZE Y SAMPLE COLOR SIGN SAMPLE COLOR SIZE BAND SAMPLE COLOR SIZE BIT SAMPLE COLOR TYPE SAMPLE LABEL SIGN SAMPLE LABEL SIZE BAND SAMPLE LABEL SIZE BIT SAMPLE LABEL TYPE AREA LABEL VALUE AREA PIXEL COUNT BEST MATCH INDEX BEST MATCH LABEL OUTLIER COVERAGE SCORE RELEVANCE STATUS FAILURE SUCCESS COLOR DISTANCE SAMPLE COVERAGE SAMPLE LABEL VALUE SAMPLE MATCH STATUS MATCH NO MATCH SAMPLE PIXEL COUNT SCORE AVAILABLE NULL NB ELEMENTS TYPE MIL DOUBLE TYPE MIL FLOAT TYPE MIL ID TYPE MIL INT TYPE MIL INT16 TYPE MIL INT32 TYPE MIL INT64 GENERAL GENERAL GENERAL GENERAL GENERAL GENERAL ALL DEFAULT ALL DEFAULT ALL ALL