ClassesClasses | | Operators

find_ncc_modelT_find_ncc_modelFindNccModelFindNccModel (Operator)

Name

find_ncc_modelT_find_ncc_modelFindNccModelFindNccModel — Find the best matches of an NCC model in an image.

Signature

find_ncc_model(Image : : ModelID, AngleStart, AngleExtent, MinScore, NumMatches, MaxOverlap, SubPixel, NumLevels : Row, Column, Angle, Score)

Herror T_find_ncc_model(const Hobject Image, const Htuple ModelID, const Htuple AngleStart, const Htuple AngleExtent, const Htuple MinScore, const Htuple NumMatches, const Htuple MaxOverlap, const Htuple SubPixel, const Htuple NumLevels, Htuple* Row, Htuple* Column, Htuple* Angle, Htuple* Score)

void FindNccModel(const HObject& Image, const HTuple& ModelID, const HTuple& AngleStart, const HTuple& AngleExtent, const HTuple& MinScore, const HTuple& NumMatches, const HTuple& MaxOverlap, const HTuple& SubPixel, const HTuple& NumLevels, HTuple* Row, HTuple* Column, HTuple* Angle, HTuple* Score)

void HNCCModel::FindNccModel(const HImage& Image, double AngleStart, double AngleExtent, double MinScore, Hlong NumMatches, double MaxOverlap, const HString& SubPixel, const HTuple& NumLevels, HTuple* Row, HTuple* Column, HTuple* Angle, HTuple* Score) const

void HNCCModel::FindNccModel(const HImage& Image, double AngleStart, double AngleExtent, double MinScore, Hlong NumMatches, double MaxOverlap, const HString& SubPixel, Hlong NumLevels, HTuple* Row, HTuple* Column, HTuple* Angle, HTuple* Score) const

void HNCCModel::FindNccModel(const HImage& Image, double AngleStart, double AngleExtent, double MinScore, Hlong NumMatches, double MaxOverlap, const char* SubPixel, Hlong NumLevels, HTuple* Row, HTuple* Column, HTuple* Angle, HTuple* Score) const

void HImage::FindNccModel(const HNCCModel& ModelID, double AngleStart, double AngleExtent, double MinScore, Hlong NumMatches, double MaxOverlap, const HString& SubPixel, const HTuple& NumLevels, HTuple* Row, HTuple* Column, HTuple* Angle, HTuple* Score) const

void HImage::FindNccModel(const HNCCModel& ModelID, double AngleStart, double AngleExtent, double MinScore, Hlong NumMatches, double MaxOverlap, const HString& SubPixel, Hlong NumLevels, HTuple* Row, HTuple* Column, HTuple* Angle, HTuple* Score) const

void HImage::FindNccModel(const HNCCModel& ModelID, double AngleStart, double AngleExtent, double MinScore, Hlong NumMatches, double MaxOverlap, const char* SubPixel, Hlong NumLevels, HTuple* Row, HTuple* Column, HTuple* Angle, HTuple* Score) const

static void HOperatorSet.FindNccModel(HObject image, HTuple modelID, HTuple angleStart, HTuple angleExtent, HTuple minScore, HTuple numMatches, HTuple maxOverlap, HTuple subPixel, HTuple numLevels, out HTuple row, out HTuple column, out HTuple angle, out HTuple score)

void HNCCModel.FindNccModel(HImage image, double angleStart, double angleExtent, double minScore, int numMatches, double maxOverlap, string subPixel, HTuple numLevels, out HTuple row, out HTuple column, out HTuple angle, out HTuple score)

void HNCCModel.FindNccModel(HImage image, double angleStart, double angleExtent, double minScore, int numMatches, double maxOverlap, string subPixel, int numLevels, out HTuple row, out HTuple column, out HTuple angle, out HTuple score)

void HImage.FindNccModel(HNCCModel modelID, double angleStart, double angleExtent, double minScore, int numMatches, double maxOverlap, string subPixel, HTuple numLevels, out HTuple row, out HTuple column, out HTuple angle, out HTuple score)

void HImage.FindNccModel(HNCCModel modelID, double angleStart, double angleExtent, double minScore, int numMatches, double maxOverlap, string subPixel, int numLevels, out HTuple row, out HTuple column, out HTuple angle, out HTuple score)

Description

The operator find_ncc_modelfind_ncc_modelFindNccModelFindNccModelFindNccModel finds the best NumMatchesNumMatchesNumMatchesNumMatchesnumMatches instances of the NCC model ModelIDModelIDModelIDModelIDmodelID in the input image ImageImageImageImageimage. The model must have been created previously by calling create_ncc_modelcreate_ncc_modelCreateNccModelCreateNccModelCreateNccModel or read_ncc_modelread_ncc_modelReadNccModelReadNccModelReadNccModel.

The position and rotation of the found instances of the model is returned in RowRowRowRowrow, ColumnColumnColumnColumncolumn, and AngleAngleAngleAngleangle. Additionally, the score of each found instance is returned in ScoreScoreScoreScorescore.

It should be noted that the NCC is very sensitive to occlusion and clutter as well as to nonlinear illumination changes in the image. If a model should be found in the presence of occlusion, clutter, or nonlinear illumination changes the search should be performed using the shape-based matching (see, e.g., create_shape_modelcreate_shape_modelCreateShapeModelCreateShapeModelCreateShapeModel).

Input parameters in detail

The image and its domain:

The domain of the image ImageImageImageImageimage determines the search space for the reference point of the model, i.e., for the center of gravity of the domain (region) of the image that was used to create the NCC model with create_ncc_modelcreate_ncc_modelCreateNccModelCreateNccModelCreateNccModel. A different origin set with set_ncc_model_originset_ncc_model_originSetNccModelOriginSetNccModelOriginSetNccModelOrigin is not taken into account here. The model is searched within those points of the domain of the image, in which the model lies completely within the image. This means that the model will not be found if it extends beyond the borders of the image, even if it would achieve a score greater than MinScoreMinScoreMinScoreMinScoreminScore (see below).

AngleStart and AngleExtent:

The parameters AngleStartAngleStartAngleStartAngleStartangleStart and AngleExtentAngleExtentAngleExtentAngleExtentangleExtent determine the range of rotations for which the model is searched. If necessary, the range of rotations is clipped to the range given when the model was created with create_ncc_modelcreate_ncc_modelCreateNccModelCreateNccModelCreateNccModel.

MinScore:

The parameter MinScoreMinScoreMinScoreMinScoreminScore determines what score a potential match must at least have to be regarded as an instance of the model in the image. The larger MinScoreMinScoreMinScoreMinScoreminScore is chosen, the faster the search is.

NumMatches:

The maximum number of instances to be found can be determined with NumMatchesNumMatchesNumMatchesNumMatchesnumMatches. If more than NumMatchesNumMatchesNumMatchesNumMatchesnumMatches instances with a score greater than MinScoreMinScoreMinScoreMinScoreminScore are found in the image, only the best NumMatchesNumMatchesNumMatchesNumMatchesnumMatches instances are returned. If fewer than NumMatchesNumMatchesNumMatchesNumMatchesnumMatches are found, only that number is returned, i.e., the parameter MinScoreMinScoreMinScoreMinScoreminScore takes precedence over NumMatchesNumMatchesNumMatchesNumMatchesnumMatches. If all model instances exceeding MinScoreMinScoreMinScoreMinScoreminScore in the image should be found, NumMatchesNumMatchesNumMatchesNumMatchesnumMatches must be set to 0.

MaxOverlap:

If the model exhibits symmetries it may happen that multiple instances with similar positions but different rotations are found in the image. If the model has repeating structures it may happen that multiple instances with identical rotations are found at similar positions in the image. The parameter MaxOverlapMaxOverlapMaxOverlapMaxOverlapmaxOverlap determines by what fraction (i.e., a number between 0 and 1) two instances may at most overlap in order to consider them as different instances, and hence to be returned separately. If two instances overlap each other by more than MaxOverlapMaxOverlapMaxOverlapMaxOverlapmaxOverlap only the best instance is returned. The calculation of the overlap is based on the smallest enclosing rectangle of arbitrary orientation (see smallest_rectangle2smallest_rectangle2SmallestRectangle2SmallestRectangle2SmallestRectangle2) of the found instances. If MaxOverlapMaxOverlapMaxOverlapMaxOverlapmaxOverlap=0, the found instances may not overlap at all, while for MaxOverlapMaxOverlapMaxOverlapMaxOverlapmaxOverlap=1 all instances are returned.

SubPixel:

The parameter SubPixelSubPixelSubPixelSubPixelsubPixel determines whether the instances should be extracted with subpixel accuracy. If SubPixelSubPixelSubPixelSubPixelsubPixel is set to 'false'"false""false""false""false", the model's pose is only determined with pixel accuracy and the angle resolution that was specified with create_ncc_modelcreate_ncc_modelCreateNccModelCreateNccModelCreateNccModel. If SubPixelSubPixelSubPixelSubPixelsubPixel is set to 'true'"true""true""true""true", the position as well as the rotation are determined with subpixel accuracy. In this mode, the model's pose is interpolated from the score function. This mode costs almost no computation time and achieves a high accuracy. Hence, SubPixelSubPixelSubPixelSubPixelsubPixel should usually be set to 'true'"true""true""true""true". Note that the subpixel accurate determination of the model's pose is only possible if the found instance lies at least 2 pixels away from the image border of the lowest used pyramid level. If the instance lies closer to the image border, its pose is only determined with pixel accuracy and the angle resolution that was specified with create_ncc_modelcreate_ncc_modelCreateNccModelCreateNccModelCreateNccModel, even if SubPixelSubPixelSubPixelSubPixelsubPixel is set to 'true'"true""true""true""true".

NumLevels:

The number of pyramid levels used during the search is determined with NumLevelsNumLevelsNumLevelsNumLevelsnumLevels. If necessary, the number of levels is clipped to the range given when the NCC model was created with create_ncc_modelcreate_ncc_modelCreateNccModelCreateNccModelCreateNccModel. If NumLevelsNumLevelsNumLevelsNumLevelsnumLevels is set to 0, the number of pyramid levels specified in create_ncc_modelcreate_ncc_modelCreateNccModelCreateNccModelCreateNccModel is used.

In certain cases, the number of pyramid levels that was determined automatically with, for example, create_ncc_modelcreate_ncc_modelCreateNccModelCreateNccModelCreateNccModel may be too high. The consequence may be that some matches that may have a high final score are rejected on the highest pyramid level and thus are not found. Instead of setting MinScoreMinScoreMinScoreMinScoreminScore to a very low value to find all matches, it may be better to query the value of NumLevelsNumLevelsNumLevelsNumLevelsnumLevels with get_ncc_model_paramsget_ncc_model_paramsGetNccModelParamsGetNccModelParamsGetNccModelParams and then use a slightly lower value in find_ncc_modelfind_ncc_modelFindNccModelFindNccModelFindNccModel. This approach is often better regarding the speed and robustness of the matching.

Optionally, NumLevelsNumLevelsNumLevelsNumLevelsnumLevels can contain a second value that determines the lowest pyramid level to which the found matches are tracked. Hence, a value of [4,2] for NumLevelsNumLevelsNumLevelsNumLevelsnumLevels means that the matching starts at the fourth pyramid level and tracks the matches to the second lowest pyramid level (the lowest pyramid level is denoted by a value of 1). This mechanism can be used to decrease the runtime of the matching. It should be noted, however, that in general the accuracy of the extracted pose parameters is lower in this mode than in the normal mode, in which the matches are tracked to the lowest pyramid level. If the lowest pyramid level to use is chosen too large, it may happen that the desired accuracy cannot be achieved, or that wrong instances of the model are found because the model is not specific enough on the higher pyramid levels to facilitate a reliable selection of the correct instance of the model. In this case, the lowest pyramid level to use must be set to a smaller value.

Output parameters in detail

Row, Column and Angle:

The position and rotation of the found instances of the model is returned in RowRowRowRowrow, ColumnColumnColumnColumncolumn, and AngleAngleAngleAngleangle. The coordinates RowRowRowRowrow and ColumnColumnColumnColumncolumn are related to the position of the origin of the model in the search image. However, RowRowRowRowrow and ColumnColumnColumnColumncolumn do not exactly correspond to this position. Instead, find_ncc_modelfind_ncc_modelFindNccModelFindNccModelFindNccModel returns slightly modified values that are optimized for creating a transformation matrix, that can be used for alignment or visualization of the model. (This has to do with the way HALCON transforms iconic objects, see affine_trans_pixelaffine_trans_pixelAffineTransPixelAffineTransPixelAffineTransPixel). The example below shows how to create the transformation matrix for alignment and how to calculate the exact coordinates of the found matches.

By default, the origin is the center of gravity of the domain (region) of the image that was used to create the NCC model with create_ncc_modelcreate_ncc_modelCreateNccModelCreateNccModelCreateNccModel. A different origin can be set with set_ncc_model_originset_ncc_model_originSetNccModelOriginSetNccModelOriginSetNccModelOrigin.

Score:

Additionally, the score of each found instance is returned in ScoreScoreScoreScorescore. The score is the normalized cross correlation of the template t(r,c) and the image i(r,c):

Here, n denotes the number of points in the template, R denotes the domain (ROI) of the template, is the mean gray value of the template
is the variance of the gray values of the template
is the mean gray value of the image at position (r,c) over all points of the template (i.e., the template points are shifted by (r,c))
and is the variance of the gray values of the image at position (r,c) over all points of the template

The NCC measures how well the template and image correspond at a particular point (r,c). It assumes values between -1 and 1. The larger the absolute value of the correlation, the larger the degree of correspondence between the template and image. A value of 1 means that the gray values in the image are a linear transformation of the gray values in the template:

i(r+u,c+v) = a * t(u,v) + b
where a > 0. Similarly, a value of -1 means that the gray values in the image are a linear transformation of the gray values in the template with a < 0. Hence, in this case the template occurs with a reversed polarity in the image. Because of the above property, the NCC is invariant to linear illumination changes.

The NCC as defined above is used if the NCC model has been created with Metric = 'use_polarity'"use_polarity""use_polarity""use_polarity""use_polarity". If the model has been created with Metric = 'ignore_global_polarity'"ignore_global_polarity""ignore_global_polarity""ignore_global_polarity""ignore_global_polarity", the absolute value of ncc(r,c) is used as the score.

Specifying a timeout

Using the operator set_ncc_model_paramset_ncc_model_paramSetNccModelParamSetNccModelParamSetNccModelParam you can specify a 'timeout'"timeout""timeout""timeout""timeout" for find_ncc_modelfind_ncc_modelFindNccModelFindNccModelFindNccModel. If find_ncc_modelfind_ncc_modelFindNccModelFindNccModelFindNccModel reaches this 'timeout'"timeout""timeout""timeout""timeout", it terminates without results and returns the error code 9400 (H_ERR_TIMEOUT).

Visualization of the results

To display the results found by correlation-based matching, we highly recommend the usage of the procedure dev_display_ncc_matching_results.

Further Information

For an explanation of the different 2D coordinate systems used in HALCON, see the introduction of chapter Transformations / 2D Transformations.

Attention

find_ncc_modelfind_ncc_modelFindNccModelFindNccModelFindNccModel can be partially executed on OpenCL devices that support the cl_khr_global_int32_base_atomics OpenCL extension. Only the initial search for the model in the topmost pyramid level is done on the OpenCL device, while the tracking of matches is done on the host CPU. If the domain of the image to search in is substantially smaller than the size of the image, use crop_domaincrop_domainCropDomainCropDomainCropDomain to reduce the amount of data that needs to be copied from the OpenCL device to the host CPU. Note that find_ncc_modelfind_ncc_modelFindNccModelFindNccModelFindNccModel using OpenCL may run either substantially faster or slower depending on a wide number of factors, so the only way to tell if using OpenCL is beneficial is by testing with images from the actual application.

Furthermore, note that the internally used memory increases with the number of used threads.

Execution Information

Parameters

ImageImageImageImageimage (input_object)  singlechannelimage objectHImageHImageHobject (byte* / uint2*) *allowed for compute devices

Input image in which the model should be found.

ModelIDModelIDModelIDModelIDmodelID (input_control)  ncc_model HNCCModel, HTupleHTupleHtuple (handle) (IntPtr) (HHandle) (handle)

Handle of the model.

AngleStartAngleStartAngleStartAngleStartangleStart (input_control)  angle.rad HTupleHTupleHtuple (real) (double) (double) (double)

Smallest rotation of the model.

Default value: -0.39

Suggested values: -3.14, -1.57, -0.79, -0.39, -0.20, 0.0

AngleExtentAngleExtentAngleExtentAngleExtentangleExtent (input_control)  angle.rad HTupleHTupleHtuple (real) (double) (double) (double)

Extent of the rotation angles.

Default value: 0.79

Suggested values: 6.29, 3.14, 1.57, 0.79, 0.39, 0.0

Restriction: AngleExtent >= 0

MinScoreMinScoreMinScoreMinScoreminScore (input_control)  real HTupleHTupleHtuple (real) (double) (double) (double)

Minimum score of the instances of the model to be found.

Default value: 0.8

Suggested values: 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9, 1.0

Typical range of values: 0 ≤ MinScore MinScore MinScore MinScore minScore ≤ 1

Minimum increment: 0.01

Recommended increment: 0.05

NumMatchesNumMatchesNumMatchesNumMatchesnumMatches (input_control)  integer HTupleHTupleHtuple (integer) (int / long) (Hlong) (Hlong)

Number of instances of the model to be found (or 0 for all matches).

Default value: 1

Suggested values: 0, 1, 2, 3, 4, 5, 10, 20

MaxOverlapMaxOverlapMaxOverlapMaxOverlapmaxOverlap (input_control)  real HTupleHTupleHtuple (real) (double) (double) (double)

Maximum overlap of the instances of the model to be found.

Default value: 0.5

Suggested values: 0.0, 0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9, 1.0

Typical range of values: 0 ≤ MaxOverlap MaxOverlap MaxOverlap MaxOverlap maxOverlap ≤ 1

Minimum increment: 0.01

Recommended increment: 0.05

SubPixelSubPixelSubPixelSubPixelsubPixel (input_control)  string HTupleHTupleHtuple (string) (string) (HString) (char*)

Subpixel accuracy.

Default value: 'true' "true" "true" "true" "true"

List of values: 'false'"false""false""false""false", 'true'"true""true""true""true"

NumLevelsNumLevelsNumLevelsNumLevelsnumLevels (input_control)  integer(-array) HTupleHTupleHtuple (integer) (int / long) (Hlong) (Hlong)

Number of pyramid levels used in the matching (and lowest pyramid level to use if |NumLevelsNumLevelsNumLevelsNumLevelsnumLevels| = 2).

Default value: 0

List of values: 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10

RowRowRowRowrow (output_control)  point.y-array HTupleHTupleHtuple (real) (double) (double) (double)

Row coordinate of the found instances of the model.

ColumnColumnColumnColumncolumn (output_control)  point.x-array HTupleHTupleHtuple (real) (double) (double) (double)

Column coordinate of the found instances of the model.

AngleAngleAngleAngleangle (output_control)  angle.rad-array HTupleHTupleHtuple (real) (double) (double) (double)

Rotation angle of the found instances of the model.

ScoreScoreScoreScorescore (output_control)  real-array HTupleHTupleHtuple (real) (double) (double) (double)

Score of the found instances of the model.

Example (HDevelop)

create_ncc_model (TemplateImage, 'auto', rad(-45), rad(90), 'auto', \
                  'use_polarity', ModelID)
find_ncc_model (SearchImage, ModelID, rad(-45), rad(90), 0.7, 1, \
                0.5, 'true', 0, Row, Column, Angle, Score)
* Create transformation matrix
vector_angle_to_rigid (0, 0, 0, Row, Column, Angle, HomMat2D)
* Calculate true position of the model origin in the search image
affine_trans_pixel (HomMat2D, 0, 0, RowObject, ColumnObject)
* display the results
dev_display_ncc_matching_results (ModelID, 'red', Row, Column, \
                                  Angle, 0)

Result

If the parameter values are correct, the operator find_ncc_modelfind_ncc_modelFindNccModelFindNccModelFindNccModel returns the value 2 (H_MSG_TRUE). If the input is empty (no input images are available) the behavior can be set via set_system('no_object_result',<Result>)set_system("no_object_result",<Result>)SetSystem("no_object_result",<Result>)SetSystem("no_object_result",<Result>)SetSystem("no_object_result",<Result>). If necessary, an exception is raised.

Possible Predecessors

create_ncc_modelcreate_ncc_modelCreateNccModelCreateNccModelCreateNccModel, read_ncc_modelread_ncc_modelReadNccModelReadNccModelReadNccModel, set_ncc_model_originset_ncc_model_originSetNccModelOriginSetNccModelOriginSetNccModelOrigin

Possible Successors

clear_ncc_modelclear_ncc_modelClearNccModelClearNccModelClearNccModel

Alternatives

find_shape_modelfind_shape_modelFindShapeModelFindShapeModelFindShapeModel, find_scaled_shape_modelfind_scaled_shape_modelFindScaledShapeModelFindScaledShapeModelFindScaledShapeModel, find_aniso_shape_modelfind_aniso_shape_modelFindAnisoShapeModelFindAnisoShapeModelFindAnisoShapeModel, find_shape_modelsfind_shape_modelsFindShapeModelsFindShapeModelsFindShapeModels, find_scaled_shape_modelsfind_scaled_shape_modelsFindScaledShapeModelsFindScaledShapeModelsFindScaledShapeModels, find_aniso_shape_modelsfind_aniso_shape_modelsFindAnisoShapeModelsFindAnisoShapeModelsFindAnisoShapeModels

Module

Matching


ClassesClasses | | Operators