find_ncc_models🔗
Short description🔗
find_ncc_models — Find the best matches of multiple NCC models.
Signature🔗
find_ncc_models( image Image, ncc_model ModelIDs, angle.rad AngleStart, angle.rad AngleExtent, real MinScore, integer NumMatches, real MaxOverlap, string SubPixel, integer NumLevels, out point.y Row, out point.x Column, out angle.rad Angle, out real Score, out integer Model )
Description🔗
The operator find_ncc_models finds the best
NumMatches instances of the NCC models that are passed in
the tuple ModelIDs in the input Image. The
models must have been created previously by calling
create_ncc_model or read_ncc_model.
In contrast to find_ncc_model, multiple models can
be searched in the same image in one call.
If NCC finds no suitable match or the matching scores are to low,
the search should be performed using a different matching method
(see, e.g., “Solution Guide II-B - Matching”).
Characteristics of the parameter semantics🔗
Compared to find_ncc_model, the
semantics of all input parameters have changed to some extent.
All input parameters must either contain one element, in which case the
parameter is used for all models, or they must contain the same number of
elements as ModelIDs, in which case each parameter element
refers to the corresponding element in ModelIDs.
(NumLevels may also contain either two or twice the number
of elements as ModelIDs). More details can be found below
in the sections containing information for the respective parameters.
Note that a call to
find_ncc_models with multiple
values for ModelIDs, NumMatches and
MaxOverlap has the same effect as multiple independent
calls to find_ncc_model with the respective parameters.
However, a single call to find_ncc_models is considerably
more efficient.
Input parameters in detail🔗
-
Imageand its domain: The domain of the imageImagedetermines 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 withcreate_ncc_model. A different origin set withset_ncc_model_originis not taken into account. The model has to lie 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 thanMinScore(see below). Note that rounding effects can cause matches to lie up to \(0.5 * 2^{\textrm{NumLevels} - 1}\) pixels outside the image.The input
Imagecan contain a single image object or an image object array containing multiple image objects. IfImagecontains a single image object, its domain is used as the region of interest for all models inModelIDs. IfImagecontains multiple image objects, each domain is used as the region of interest for the corresponding model inModelIDs. In this case, the images have to be identical except for their domains, i.e.,Imagecannot be constructed in an arbitrary manner usingconcat_obj, but must be created from the same image usingadd_channelsor equivalent calls. If this is not the case, an error message is returned. -
AngleStartandAngleExtent: The parametersAngleStartandAngleExtentdetermine 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 withcreate_ncc_model.Furthermore, it should be noted that in some cases instances with a rotation that is slightly outside the specified range of rotations are found. This may happen if the specified range of rotations is smaller than the range given when the model was created.
-
MinScore: The parameterMinScoredetermines what score a potential match must at least have to be regarded as an instance of the model in the image. The largerMinScoreis chosen, the faster the search is. If the model can be expected never to be occluded in the images,MinScoremay be set as high as 0.8 or even 0.9. If the matches are not tracked to the lowest pyramid level (seeNumLevels), it might happen that instances with a score slightly belowMinScoreare found. -
NumMatches: The maximum number of instances to be found can be determined withNumMatches. If more thanNumMatchesinstances with a score greater thanMinScoreare found in the image, only the bestNumMatchesinstances are returned. If fewer thanNumMatchesare found, only that number is returned, i.e., the parameterMinScoretakes precedence overNumMatches. If all model instances exceedingMinScorein the image should be found,NumMatchesmust be set to 0.If
NumMatchescontains one element,find_ncc_modelsreturns the bestNumMatchesinstances of the model irrespective of the type of the model. If, for example, two models are passed inModelIDsand \(\textrm{NumMatches} = 2\) is selected, it can happen that two instances of the first model and no instances of the second model, one instance of the first model and one instance of the second model, or no instances of the first model and two instances of the second model are returned. If, on the other hand,NumMatchescontains multiple values, the number of instances returned of the different models corresponds to the number specified in the respective entry inNumMatches. If, for example, \(\textrm{NumMatches} = [1,1]\) is selected, one instance of the first model and one instance of the second model is returned. -
MaxOverlap: If the model exhibits symmetries it may happen that multiple instances with similar positions but different rotations are found in the image. The parameterMaxOverlapdetermines 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 thanMaxOverlap, only the best instance is returned. The calculation of the overlap is based on the smallest enclosing rectangle of arbitrary orientation (seesmallest_rectangle2) of the found instances. If \(\textrm{MaxOverlap}=0\), the found instances may not overlap at all, while for \(\textrm{MaxOverlap}=1\) all instances are returned.If a single value is passed in
MaxOverlap, the overlap is computed for all found instances of the different models, irrespective of the model type, i.e., instances of the same or of different models that overlap too much are eliminated. If, on the other hand, multiple values are passed inMaxOverlap, the overlap is only computed for found instances of the model that have the same model type, i.e., only instances of the same model that overlap too much are eliminated. In this mode, models of different types may overlap completely. -
SubPixel: The parameterSubPixeldetermines whether the instances should be extracted with subpixel accuracy. IfSubPixelis set to 'false' the model’s pose is only determined with pixel accuracy and the angle resolution that was specified withcreate_ncc_model. IfSubPixelis set to '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. -
NumLevels: The number of pyramid levels used during the search is determined withNumLevels. If necessary, the number of levels is clipped to the range given when the NCC model was created withcreate_ncc_model. IfNumLevelsis set to 0, the number of pyramid levels specified increate_ncc_modelis used.In certain cases, the number of pyramid levels that was determined automatically with, for example,
create_ncc_modelmay 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 settingMinScoreto a very low value to find all matches, it may be better to query the value ofNumLevelswithget_ncc_model_paramsand then use a slightly lower value infind_ncc_models. This approach is often better regarding the speed and robustness of the matching.Optionally,
NumLevelscan contain a second value that determines the lowest pyramid level to which the found matches are tracked. Hence, a value of [4, 2] forNumLevelsmeans 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.If the lowest pyramid level is specified separately for each model,
NumLevelsmust contain twice the number of elements asModelIDs. In this case, the number of pyramid levels and the lowest pyramid level must be specified interleaved inNumLevels. If, for example, two models are specified inModelIDs, the number of pyramid levels is 5 for the first model and 4 for the second model, and the lowest pyramid level is 2 for the first model and 1 for the second model, \(\textrm{NumLevels} = \textit{[5, 2, 4, 1]}\) must be selected. If exactly two models are specified inModelIDs, a special case occurs. If in this case the lowest pyramid level is to be specified, the number of pyramid levels and the lowest pyramid level must be specified explicitly for both models, even if they are identical, because specifying two values inNumLevelsis interpreted as the explicit specification of the number of pyramid levels for the two models.
Output parameters in detail🔗
-
Row,ColumnandAngle: The position and rotation of the found instances of the model is returned inRow,Column, andAngle. The coordinatesRowandColumnare the coordinates of the origin of the NCC model in the search image. By default, the origin is the center of gravity of the domain (region) of the image that was used to create the NCC model withcreate_ncc_model. A different origin can be set withset_ncc_model_origin.Note that the coordinates
RowandColumndo not exactly correspond to the position of the model in the search image. Thus, you cannot directly use them. Instead, the values are optimized for creating the transformation matrix with which you can use the results of the matching for various tasks, e.g., to align ROIs for other processing steps. The example given forfind_ncc_modelshows how to create this matrix and use it to display the model at the found position in the search image and to calculate the exact coordinates.Note also that for visualizing the model at the found position, also the procedure
dev_display_ncc_matching_resultscan be used. -
Score: Additionally, the score of each found instance is returned inScore. -
Model: The type of the found instances of the models is returned inModel. The elements ofModelare indices into the tupleModelIDs, i.e., they can contain values from 0 to \(|\textrm{ModelIDs}|-1\). Hence, a value of 0 in an element ofModelcorresponds to an instance of the first model inModelIDs.
Specifying a timeout🔗
Using the operator set_ncc_model_param you can specify a
'timeout' for find_ncc_models. If the NCC models
referenced by ModelIDs hold different values for 'timeout',
find_ncc_models uses the smallest one.
If find_ncc_models reaches this '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🔗
Note that the internally used memory increases with the number of used threads.
Execution information🔗
Execution information
-
Supports OpenCL compute devices.
-
Multithreading type: reentrant (runs in parallel with non-exclusive operators).
-
Multithreading scope: global (may be called from any thread).
-
Automatically parallelized on internal data level.
Parameters🔗
Image (input_object) (multichannel-)image(-array) → object (byte* / uint2*) *allowed for compute devices
Input image in which the model should be found.
ModelIDs (input_control) ncc_model(-array) → (handle)
Handle of the models.
AngleStart (input_control) angle.rad(-array) → (real)
Smallest rotation of the models.
Default: -0.39
Suggested values: -3.14, -1.57, -0.79, -0.39, -0.20, 0.0
AngleExtent (input_control) angle.rad(-array) → (real)
Extent of the rotation angles.
Default: 0.79
Suggested values: 6.29, 3.14, 1.57, 0.79, 0.39, 0.0
Restriction: AngleExtent >= 0
MinScore (input_control) real(-array) → (real)
Minimum score of the instances of the models to be found.
Default: 0.8
Suggested values: 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9, 1.0
Value range: 0 ≤ MinScore ≤ 1
Minimum increment: 0.01
Recommended increment: 0.05
NumMatches (input_control) integer(-array) → (integer)
Number of instances of the models to be found (or 0 for all matches).
Default: 1
Suggested values: 0, 1, 2, 3, 4, 5, 10, 20
MaxOverlap (input_control) real(-array) → (real)
Maximum overlap of the instances of the models to be found.
Default: 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
Value range: 0 ≤ MaxOverlap ≤ 1
Minimum increment: 0.01
Recommended increment: 0.05
SubPixel (input_control) string(-array) → (string)
Subpixel accuracy if not equal to 'none'.
Default: 'true'
List of values: 'false', 'true'
NumLevels (input_control) integer(-array) → (integer)
Number of pyramid levels used in the matching (and lowest pyramid level to use if \(|\textrm{NumLevels}| = 2\)).
Default: 0
List of values: 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10
Row (output_control) point.y-array → (real)
Row coordinate of the found instances of the models.
Column (output_control) point.x-array → (real)
Column coordinate of the found instances of the models.
Angle (output_control) angle.rad-array → (real)
Rotation angle of the found instances of the models.
Score (output_control) real-array → (real)
Score of the found instances of the models.
Model (output_control) integer-array → (integer)
Index of the found instances of the models.
Example🔗
(HDevelop)
read_image (Image, 'pcb_focus/pcb_focus_telecentric_061')
gen_rectangle1 (ROI_0, 236, 241, 313, 321)
gen_circle (ROI_1, 281, 653, 41)
reduce_domain (Image, ROI_0, ImageReduced1)
reduce_domain (Image, ROI_1, ImageReduced2)
create_ncc_model (ImageReduced1, 'auto', rad(-45), rad(90), 'auto', \
'use_polarity', ModelID1)
create_ncc_model (ImageReduced2, 'auto', rad(-45), rad(90), 'auto', \
'use_polarity', ModelID2)
ModelIDs:=[ModelID1, ModelID2]
find_ncc_models (Image, ModelIDs, rad(-45), rad(90), 0.7, [1,1], 0.5, \
'true', 0, Row, Column, Angle, Score, Model)
dev_display_ncc_matching_results (ModelIDs, 'red', Row, Column, \
Angle, Model)
Result🔗
If the parameter values are correct, the operator
find_ncc_models 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>). If necessary, an
exception is raised.
Combinations with other operators🔗
Combinations
Possible predecessors
create_ncc_model, read_ncc_model, set_ncc_model_origin
Possible successors
Alternatives
Module🔗
Matching