find_aniso_shape_modelsT_find_aniso_shape_modelsFindAnisoShapeModelsFindAnisoShapeModelsfind_aniso_shape_models (Operator)

Name

find_aniso_shape_modelsT_find_aniso_shape_modelsFindAnisoShapeModelsFindAnisoShapeModelsfind_aniso_shape_models — Find the best matches of multiple anisotropically scaled shape models.

Signature

find_aniso_shape_models(Image : : ModelIDs, AngleStart, AngleExtent, ScaleRMin, ScaleRMax, ScaleCMin, ScaleCMax, MinScore, NumMatches, MaxOverlap, SubPixel, NumLevels, Greediness : Row, Column, Angle, ScaleR, ScaleC, Score, Model)

Herror T_find_aniso_shape_models(const Hobject Image, const Htuple ModelIDs, const Htuple AngleStart, const Htuple AngleExtent, const Htuple ScaleRMin, const Htuple ScaleRMax, const Htuple ScaleCMin, const Htuple ScaleCMax, const Htuple MinScore, const Htuple NumMatches, const Htuple MaxOverlap, const Htuple SubPixel, const Htuple NumLevels, const Htuple Greediness, Htuple* Row, Htuple* Column, Htuple* Angle, Htuple* ScaleR, Htuple* ScaleC, Htuple* Score, Htuple* Model)

void FindAnisoShapeModels(const HObject& Image, const HTuple& ModelIDs, const HTuple& AngleStart, const HTuple& AngleExtent, const HTuple& ScaleRMin, const HTuple& ScaleRMax, const HTuple& ScaleCMin, const HTuple& ScaleCMax, const HTuple& MinScore, const HTuple& NumMatches, const HTuple& MaxOverlap, const HTuple& SubPixel, const HTuple& NumLevels, const HTuple& Greediness, HTuple* Row, HTuple* Column, HTuple* Angle, HTuple* ScaleR, HTuple* ScaleC, HTuple* Score, HTuple* Model)

static void HShapeModel::FindAnisoShapeModels(const HImage& Image, const HShapeModelArray& ModelIDs, const HTuple& AngleStart, const HTuple& AngleExtent, const HTuple& ScaleRMin, const HTuple& ScaleRMax, const HTuple& ScaleCMin, const HTuple& ScaleCMax, const HTuple& MinScore, const HTuple& NumMatches, const HTuple& MaxOverlap, const HTuple& SubPixel, const HTuple& NumLevels, const HTuple& Greediness, HTuple* Row, HTuple* Column, HTuple* Angle, HTuple* ScaleR, HTuple* ScaleC, HTuple* Score, HTuple* Model)

void HShapeModel::FindAnisoShapeModels(const HImage& Image, double AngleStart, double AngleExtent, double ScaleRMin, double ScaleRMax, double ScaleCMin, double ScaleCMax, double MinScore, Hlong NumMatches, double MaxOverlap, const HString& SubPixel, Hlong NumLevels, double Greediness, HTuple* Row, HTuple* Column, HTuple* Angle, HTuple* ScaleR, HTuple* ScaleC, HTuple* Score, HTuple* Model) const

void HShapeModel::FindAnisoShapeModels(const HImage& Image, double AngleStart, double AngleExtent, double ScaleRMin, double ScaleRMax, double ScaleCMin, double ScaleCMax, double MinScore, Hlong NumMatches, double MaxOverlap, const char* SubPixel, Hlong NumLevels, double Greediness, HTuple* Row, HTuple* Column, HTuple* Angle, HTuple* ScaleR, HTuple* ScaleC, HTuple* Score, HTuple* Model) const

void HShapeModel::FindAnisoShapeModels(const HImage& Image, double AngleStart, double AngleExtent, double ScaleRMin, double ScaleRMax, double ScaleCMin, double ScaleCMax, double MinScore, Hlong NumMatches, double MaxOverlap, const wchar_t* SubPixel, Hlong NumLevels, double Greediness, HTuple* Row, HTuple* Column, HTuple* Angle, HTuple* ScaleR, HTuple* ScaleC, HTuple* Score, HTuple* Model) const   (Windows only)

void HImage::FindAnisoShapeModels(const HShapeModelArray& ModelIDs, const HTuple& AngleStart, const HTuple& AngleExtent, const HTuple& ScaleRMin, const HTuple& ScaleRMax, const HTuple& ScaleCMin, const HTuple& ScaleCMax, const HTuple& MinScore, const HTuple& NumMatches, const HTuple& MaxOverlap, const HTuple& SubPixel, const HTuple& NumLevels, const HTuple& Greediness, HTuple* Row, HTuple* Column, HTuple* Angle, HTuple* ScaleR, HTuple* ScaleC, HTuple* Score, HTuple* Model) const

void HImage::FindAnisoShapeModels(const HShapeModel& ModelIDs, double AngleStart, double AngleExtent, double ScaleRMin, double ScaleRMax, double ScaleCMin, double ScaleCMax, double MinScore, Hlong NumMatches, double MaxOverlap, const HString& SubPixel, Hlong NumLevels, double Greediness, HTuple* Row, HTuple* Column, HTuple* Angle, HTuple* ScaleR, HTuple* ScaleC, HTuple* Score, HTuple* Model) const

void HImage::FindAnisoShapeModels(const HShapeModel& ModelIDs, double AngleStart, double AngleExtent, double ScaleRMin, double ScaleRMax, double ScaleCMin, double ScaleCMax, double MinScore, Hlong NumMatches, double MaxOverlap, const char* SubPixel, Hlong NumLevels, double Greediness, HTuple* Row, HTuple* Column, HTuple* Angle, HTuple* ScaleR, HTuple* ScaleC, HTuple* Score, HTuple* Model) const

void HImage::FindAnisoShapeModels(const HShapeModel& ModelIDs, double AngleStart, double AngleExtent, double ScaleRMin, double ScaleRMax, double ScaleCMin, double ScaleCMax, double MinScore, Hlong NumMatches, double MaxOverlap, const wchar_t* SubPixel, Hlong NumLevels, double Greediness, HTuple* Row, HTuple* Column, HTuple* Angle, HTuple* ScaleR, HTuple* ScaleC, HTuple* Score, HTuple* Model) const   (Windows only)

static void HOperatorSet.FindAnisoShapeModels(HObject image, HTuple modelIDs, HTuple angleStart, HTuple angleExtent, HTuple scaleRMin, HTuple scaleRMax, HTuple scaleCMin, HTuple scaleCMax, HTuple minScore, HTuple numMatches, HTuple maxOverlap, HTuple subPixel, HTuple numLevels, HTuple greediness, out HTuple row, out HTuple column, out HTuple angle, out HTuple scaleR, out HTuple scaleC, out HTuple score, out HTuple model)

static void HShapeModel.FindAnisoShapeModels(HImage image, HShapeModel[] modelIDs, HTuple angleStart, HTuple angleExtent, HTuple scaleRMin, HTuple scaleRMax, HTuple scaleCMin, HTuple scaleCMax, HTuple minScore, HTuple numMatches, HTuple maxOverlap, HTuple subPixel, HTuple numLevels, HTuple greediness, out HTuple row, out HTuple column, out HTuple angle, out HTuple scaleR, out HTuple scaleC, out HTuple score, out HTuple model)

void HShapeModel.FindAnisoShapeModels(HImage image, double angleStart, double angleExtent, double scaleRMin, double scaleRMax, double scaleCMin, double scaleCMax, double minScore, int numMatches, double maxOverlap, string subPixel, int numLevels, double greediness, out HTuple row, out HTuple column, out HTuple angle, out HTuple scaleR, out HTuple scaleC, out HTuple score, out HTuple model)

void HImage.FindAnisoShapeModels(HShapeModel[] modelIDs, HTuple angleStart, HTuple angleExtent, HTuple scaleRMin, HTuple scaleRMax, HTuple scaleCMin, HTuple scaleCMax, HTuple minScore, HTuple numMatches, HTuple maxOverlap, HTuple subPixel, HTuple numLevels, HTuple greediness, out HTuple row, out HTuple column, out HTuple angle, out HTuple scaleR, out HTuple scaleC, out HTuple score, out HTuple model)

void HImage.FindAnisoShapeModels(HShapeModel modelIDs, double angleStart, double angleExtent, double scaleRMin, double scaleRMax, double scaleCMin, double scaleCMax, double minScore, int numMatches, double maxOverlap, string subPixel, int numLevels, double greediness, out HTuple row, out HTuple column, out HTuple angle, out HTuple scaleR, out HTuple scaleC, out HTuple score, out HTuple model)

def find_aniso_shape_models(image: HObject, model_ids: MaybeSequence[HHandle], angle_start: MaybeSequence[float], angle_extent: MaybeSequence[float], scale_rmin: MaybeSequence[float], scale_rmax: MaybeSequence[float], scale_cmin: MaybeSequence[float], scale_cmax: MaybeSequence[float], min_score: MaybeSequence[float], num_matches: MaybeSequence[int], max_overlap: MaybeSequence[float], sub_pixel: MaybeSequence[str], num_levels: MaybeSequence[int], greediness: MaybeSequence[float]) -> Tuple[Sequence[float], Sequence[float], Sequence[float], Sequence[float], Sequence[float], Sequence[float], Sequence[int]]

Description

The operator find_aniso_shape_modelsfind_aniso_shape_modelsFindAnisoShapeModelsFindAnisoShapeModelsFindAnisoShapeModelsfind_aniso_shape_models finds the best NumMatchesNumMatchesNumMatchesNumMatchesnumMatchesnum_matches instances of the anisotropically scaled shape models that are passed in ModelIDsModelIDsModelIDsModelIDsmodelIDsmodel_ids in the input image ImageImageImageImageimageimage. The models must have been created previously by calling create_aniso_shape_modelcreate_aniso_shape_modelCreateAnisoShapeModelCreateAnisoShapeModelCreateAnisoShapeModelcreate_aniso_shape_model or read_shape_modelread_shape_modelReadShapeModelReadShapeModelReadShapeModelread_shape_model. In contrast to find_aniso_shape_modelfind_aniso_shape_modelFindAnisoShapeModelFindAnisoShapeModelFindAnisoShapeModelfind_aniso_shape_model, multiple models can be searched in the same image in one call.

The position, rotation, and scale in the row and column direction of the found instances of the model are returned in RowRowRowRowrowrow, ColumnColumnColumnColumncolumncolumn, AngleAngleAngleAngleangleangle, ScaleRScaleRScaleRScaleRscaleRscale_r, and ScaleCScaleCScaleCScaleCscaleCscale_c. The score of each found instance is returned in ScoreScoreScoreScorescorescore. The type of the found instances of the models is returned in ModelModelModelModelmodelmodel. For details see respective sections below.

Characteristics of the parameter semantics

Compared to find_aniso_shape_modelfind_aniso_shape_modelFindAnisoShapeModelFindAnisoShapeModelFindAnisoShapeModelfind_aniso_shape_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 must contain the same number of elements as ModelIDsModelIDsModelIDsModelIDsmodelIDsmodel_ids, in which case each parameter element refers to the corresponding element in ModelIDsModelIDsModelIDsModelIDsmodelIDsmodel_ids. (NumLevelsNumLevelsNumLevelsNumLevelsnumLevelsnum_levels may also contain either two or twice the number of elements as ModelIDsModelIDsModelIDsModelIDsmodelIDsmodel_ids.) More details can be found below in the sections containing information for the respective parameters. Note that a call to find_aniso_shape_modelsfind_aniso_shape_modelsFindAnisoShapeModelsFindAnisoShapeModelsFindAnisoShapeModelsfind_aniso_shape_models with multiple values for ModelIDsModelIDsModelIDsModelIDsmodelIDsmodel_ids, NumMatchesNumMatchesNumMatchesNumMatchesnumMatchesnum_matches and MaxOverlapMaxOverlapMaxOverlapMaxOverlapmaxOverlapmax_overlap has the same effect as multiple independent calls to find_aniso_shape_modelfind_aniso_shape_modelFindAnisoShapeModelFindAnisoShapeModelFindAnisoShapeModelfind_aniso_shape_model with the respective parameters. However, a single call to find_aniso_shape_modelsfind_aniso_shape_modelsFindAnisoShapeModelsFindAnisoShapeModelsFindAnisoShapeModelsfind_aniso_shape_models is considerably more efficient.

Input parameters in detail

ImageImageImageImageimageimage and its domain:

The domain of the ImageImageImageImageimageimage 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 shape model with create_aniso_shape_modelcreate_aniso_shape_modelCreateAnisoShapeModelCreateAnisoShapeModelCreateAnisoShapeModelcreate_aniso_shape_model. A different origin set with set_shape_model_originset_shape_model_originSetShapeModelOriginSetShapeModelOriginSetShapeModelOriginset_shape_model_origin is not taken into account. 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 MinScoreMinScoreMinScoreMinScoreminScoremin_score (see below). Note that, if for a certain pyramid level the model touches the image border, it might not be found even if it lies completely within the original image. As a rule of thumb, the model might not be found if its distance to an image border falls below . This behavior can be changed with set_system('border_shape_models','true')set_system("border_shape_models","true")SetSystem("border_shape_models","true")SetSystem("border_shape_models","true")SetSystem("border_shape_models","true")set_system("border_shape_models","true") for all models or with set_shape_model_param(ModelID, 'border_shape_models','true')set_shape_model_param(ModelID, "border_shape_models","true")SetShapeModelParam(ModelID, "border_shape_models","true")SetShapeModelParam(ModelID, "border_shape_models","true")SetShapeModelParam(ModelID, "border_shape_models","true")set_shape_model_param(ModelID, "border_shape_models","true") for a specific model, which will cause models that extend beyond the image border to be found if they achieve a score greater than MinScoreMinScoreMinScoreMinScoreminScoremin_score. Here, points lying outside the image are regarded as being occluded, i.e., they lower the score. It should be noted that the runtime of the search will increase in this mode. Note further, that in rare cases, which occur typically only for artificial images, the model might not be found also if for certain pyramid levels the model touches the border of the reduced domain. Then, it may help to enlarge the reduced domain by using, e.g., dilation_circledilation_circleDilationCircleDilationCircleDilationCircledilation_circle.

As usual, the domain of the input ImageImageImageImageimageimage is used to restrict the search space for the reference point of the models ModelIDsModelIDsModelIDsModelIDsmodelIDsmodel_ids. Consistent with the above semantics, the input ImageImageImageImageimageimage can therefore contain a single image object or an image object tuple containing multiple image objects. If ImageImageImageImageimageimage contains a single image object, its domain is used as the region of interest for all models in ModelIDsModelIDsModelIDsModelIDsmodelIDsmodel_ids. If ImageImageImageImageimageimage contains multiple image objects, each domain is used as the region of interest for the corresponding model in ModelIDsModelIDsModelIDsModelIDsmodelIDsmodel_ids. In this case, the images have to be identical except for their domains, i.e., ImageImageImageImageimageimage cannot be constructed in an arbitrary manner using concat_objconcat_objConcatObjConcatObjConcatObjconcat_obj, but must be created from the same image using add_channelsadd_channelsAddChannelsAddChannelsAddChannelsadd_channels or equivalent calls. If this is not the case, an error message is returned.

AngleStartAngleStartAngleStartAngleStartangleStartangle_start, AngleExtentAngleExtentAngleExtentAngleExtentangleExtentangle_extent, ScaleRMinScaleRMinScaleRMinScaleRMinscaleRMinscale_rmin, ScaleRMaxScaleRMaxScaleRMaxScaleRMaxscaleRMaxscale_rmax, ScaleCMinScaleCMinScaleCMinScaleCMinscaleCMinscale_cmin, and ScaleCMaxScaleCMaxScaleCMaxScaleCMaxscaleCMaxscale_cmax:

The parameters AngleStartAngleStartAngleStartAngleStartangleStartangle_start and AngleExtentAngleExtentAngleExtentAngleExtentangleExtentangle_extent determine the range of rotations for which the model is searched. The parameters ScaleRMinScaleRMinScaleRMinScaleRMinscaleRMinscale_rmin, ScaleRMaxScaleRMaxScaleRMaxScaleRMaxscaleRMaxscale_rmax, ScaleCMinScaleCMinScaleCMinScaleCMinscaleCMinscale_cmin, and ScaleCMaxScaleCMaxScaleCMaxScaleCMaxscaleCMaxscale_cmax determine the range of scales in the row and column directions for which the model is searched. If necessary, both ranges are clipped to the range given when the model was created with create_aniso_shape_modelcreate_aniso_shape_modelCreateAnisoShapeModelCreateAnisoShapeModelCreateAnisoShapeModelcreate_aniso_shape_model. In particular, this means that the angle ranges of the model and the search must overlap.

If in ModelIDsModelIDsModelIDsModelIDsmodelIDsmodel_ids a model is passed that was created by using create_shape_modelcreate_shape_modelCreateShapeModelCreateShapeModelCreateShapeModelcreate_shape_model or create_scaled_shape_modelcreate_scaled_shape_modelCreateScaledShapeModelCreateScaledShapeModelCreateScaledShapeModelcreate_scaled_shape_model then the model is searched with an isotropic scaling of 1.0 or with an isotropic scaling within the range from ScaleRMinScaleRMinScaleRMinScaleRMinscaleRMinscale_rmin to ScaleRMaxScaleRMaxScaleRMaxScaleRMaxscaleRMaxscale_rmax, respectively. In this case, for ScaleRScaleRScaleRScaleRscaleRscale_r and ScaleCScaleCScaleCScaleCscaleCscale_c identical values are returned.

Note that in some cases instances with a rotation or scale that is slightly outside the specified range are found. This may happen if the specified range is smaller than the range given during the creation of the model. AngleStartAngleStartAngleStartAngleStartangleStartangle_start and AngleExtentAngleExtentAngleExtentAngleExtentangleExtentangle_extent as well as ScaleRMinScaleRMinScaleRMinScaleRMinscaleRMinscale_rmin/ScaleCMinScaleCMinScaleCMinScaleCMinscaleCMinscale_cmin and ScaleRMaxScaleRMaxScaleRMaxScaleRMaxscaleRMaxscale_rmax/ScaleCMaxScaleCMaxScaleCMaxScaleCMaxscaleCMaxscale_cmax are checked only at the highest pyramid level. Matches that are found on the highest pyramid level are refined to the lowest pyramid level. For performance reasons, however, during the refinement it is no longer checked whether the matches are still within the specified ranges.

MinScoreMinScoreMinScoreMinScoreminScoremin_score:

The parameter MinScoreMinScoreMinScoreMinScoreminScoremin_score determines what score a potential match must at least have to be regarded as an instance of the model in the image. The larger MinScoreMinScoreMinScoreMinScoreminScoremin_score is chosen, the faster the search is. If the model can be expected never to be occluded in the images, MinScoreMinScoreMinScoreMinScoreminScoremin_score may be set as high as 0.8 or even 0.9. If the matches are not tracked to the lowest pyramid level (see below) it might happen that instances with a score slightly below MinScoreMinScoreMinScoreMinScoreminScoremin_score are found.

If a single value is passed in MinScoreMinScoreMinScoreMinScoreminScoremin_score, this value is applied to found instances of all models. If, on the other hand, MinScoreMinScoreMinScoreMinScoreminScoremin_score contains multiple values, the values are applied separately for the respective model.

In case that the shape models have been extended by clutter parameters with set_shape_model_clutterset_shape_model_clutterSetShapeModelClutterSetShapeModelClutterSetShapeModelClutterset_shape_model_clutter and thus 'use_clutter'"use_clutter""use_clutter""use_clutter""use_clutter""use_clutter" is enabled, MinScoreMinScoreMinScoreMinScoreminScoremin_score expects for each minimum score an additional value which determines what clutter value a potential match must at most have to be regarded as an instance of the model in the image. The runtime using clutter parameters will be at least as high as the runtime without clutter parameters and NumMatchesNumMatchesNumMatchesNumMatchesnumMatchesnum_matches set to 0. Changing this second value does not influence the runtime. Note that the different shape models must have the same value for 'use_clutter'"use_clutter""use_clutter""use_clutter""use_clutter""use_clutter".

If the maximum clutter is specified separately for each model, which is needed if also the minimum score is set for each model individually, MinScoreMinScoreMinScoreMinScoreminScoremin_score must contain twice the number of elements as ModelIDs. In this case, the minimum score and the maximum clutter must be specified interleaved in MinScoreMinScoreMinScoreMinScoreminScoremin_score. If, for example, two models are specified in ModelIDs, the minimum score is 0.9 for the first model and 0.8 for the second model, and the maximum clutter is 0.1 for the first model and 0.2 for the second model, MinScoreMinScoreMinScoreMinScoreminScoremin_score = [0.9,0.1,0.8,0.2] must be selected.

NumMatchesNumMatchesNumMatchesNumMatchesnumMatchesnum_matches:

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

When tracking the matches through the image pyramid, on each level, some less promising matches are rejected based on NumMatchesNumMatchesNumMatchesNumMatchesnumMatchesnum_matches. Thus, it is possible that some matches are rejected that would have had a higher score on the lowest pyramid level. Due to this, for example, the found match for NumMatchesNumMatchesNumMatchesNumMatchesnumMatchesnum_matches set to 1 might be different from the match with the highest score returned when setting NumMatchesNumMatchesNumMatchesNumMatchesnumMatchesnum_matches to 0 or > 1.

If multiple objects with a similar score are expected, but only the one with the highest score should be returned, it might be preferable to raise NumMatchesNumMatchesNumMatchesNumMatchesnumMatchesnum_matches, and then select the match with the highest score.

In case that the shape models have been extended by clutter parameters using set_shape_model_clutterset_shape_model_clutterSetShapeModelClutterSetShapeModelClutterSetShapeModelClutterset_shape_model_clutter, NumMatchesNumMatchesNumMatchesNumMatchesnumMatchesnum_matches also considers the second value passed in MinScoreMinScoreMinScoreMinScoreminScoremin_score: If more than NumMatchesNumMatchesNumMatchesNumMatchesnumMatchesnum_matches instances with a score greater than the first entry of MinScoreMinScoreMinScoreMinScoreminScoremin_score and a clutter value smaller than the second entry of MinScoreMinScoreMinScoreMinScoreminScoremin_score are found in the image, only the best NumMatchesNumMatchesNumMatchesNumMatchesnumMatchesnum_matches instances with respect to clutter are returned. Still, MinScoreMinScoreMinScoreMinScoreminScoremin_score takes precedence over NumMatchesNumMatchesNumMatchesNumMatchesnumMatchesnum_matches and NumMatchesNumMatchesNumMatchesNumMatchesnumMatchesnum_matches must be set to 0 if all model instances fulfilling the conditions imposed by MinScoreMinScoreMinScoreMinScoreminScoremin_score should be found. Please note that using clutter parameters, when tracking the matches through the image pyramid, no matches are rejected. Thus the runtime using clutter parameters will be at least as high as the runtime without clutter parameters and NumMatchesNumMatchesNumMatchesNumMatchesnumMatchesnum_matches set to 0.

If NumMatchesNumMatchesNumMatchesNumMatchesnumMatchesnum_matches contains one element, find_aniso_shape_modelsfind_aniso_shape_modelsFindAnisoShapeModelsFindAnisoShapeModelsFindAnisoShapeModelsfind_aniso_shape_models returns the best NumMatchesNumMatchesNumMatchesNumMatchesnumMatchesnum_matches instances of the model irrespective of the type of the model. If, for example, two models are passed in ModelIDsModelIDsModelIDsModelIDsmodelIDsmodel_ids and NumMatchesNumMatchesNumMatchesNumMatchesnumMatchesnum_matches = 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, NumMatchesNumMatchesNumMatchesNumMatchesnumMatchesnum_matches contains multiple values, the number of instances returned of the different models corresponds to the number specified in the respective entry in NumMatchesNumMatchesNumMatchesNumMatchesnumMatchesnum_matches. If, for example, NumMatchesNumMatchesNumMatchesNumMatchesnumMatchesnum_matches = [1,1] is selected, one instance of the first model and one instance of the second model is returned.

MaxOverlapMaxOverlapMaxOverlapMaxOverlapmaxOverlapmax_overlap:

If the model exhibits symmetries it may happen that multiple instances with similar positions but different rotations are found in the image. The parameter MaxOverlapMaxOverlapMaxOverlapMaxOverlapmaxOverlapmax_overlap 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 MaxOverlapMaxOverlapMaxOverlapMaxOverlapmaxOverlapmax_overlap only the best instance is returned. The calculation of the overlap is based on the smallest enclosing rectangle of arbitrary orientation (see smallest_rectangle2smallest_rectangle2SmallestRectangle2SmallestRectangle2SmallestRectangle2smallest_rectangle2) of the found instances. If MaxOverlapMaxOverlapMaxOverlapMaxOverlapmaxOverlapmax_overlap=0, the found instances may not overlap at all, while for MaxOverlapMaxOverlapMaxOverlapMaxOverlapmaxOverlapmax_overlap=1 all instances are returned.

If a single value is passed in MaxOverlapMaxOverlapMaxOverlapMaxOverlapmaxOverlapmax_overlap, 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 in MaxOverlapMaxOverlapMaxOverlapMaxOverlapmaxOverlapmax_overlap, 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.

SubPixelSubPixelSubPixelSubPixelsubPixelsub_pixel:

The parameter SubPixelSubPixelSubPixelSubPixelsubPixelsub_pixel determines whether the instances should be extracted with subpixel accuracy. If SubPixelSubPixelSubPixelSubPixelsubPixelsub_pixel is set to 'none'"none""none""none""none""none" (or 'false'"false""false""false""false""false" for backwards compatibility) the model's pose is only determined with pixel accuracy and the angle and scale resolution that was specified with create_aniso_shape_modelcreate_aniso_shape_modelCreateAnisoShapeModelCreateAnisoShapeModelCreateAnisoShapeModelcreate_aniso_shape_model. If SubPixelSubPixelSubPixelSubPixelsubPixelsub_pixel is set to 'interpolation'"interpolation""interpolation""interpolation""interpolation""interpolation" (or 'true'"true""true""true""true""true") the position as well as the rotation and scale 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 an accuracy that is high enough for most applications. In some applications, however, the accuracy requirements are extremely high. In these cases, the model's pose can be determined through a least-squares adjustment, i.e., by minimizing the distances of the model points to their corresponding image points. In contrast to 'interpolation'"interpolation""interpolation""interpolation""interpolation""interpolation", this mode requires additional computation time. The different modes for least-squares adjustment ('least_squares'"least_squares""least_squares""least_squares""least_squares""least_squares", 'least_squares_high'"least_squares_high""least_squares_high""least_squares_high""least_squares_high""least_squares_high", and 'least_squares_very_high'"least_squares_very_high""least_squares_very_high""least_squares_very_high""least_squares_very_high""least_squares_very_high") can be used to determine the accuracy with which the minimum distance is being searched. The higher the accuracy is chosen, the longer the subpixel extraction will take, however. Usually, SubPixelSubPixelSubPixelSubPixelsubPixelsub_pixel should be set to 'interpolation'"interpolation""interpolation""interpolation""interpolation""interpolation". If least-squares adjustment is desired, 'least_squares'"least_squares""least_squares""least_squares""least_squares""least_squares" should be chosen because this results in the best trade-off between runtime and accuracy.

Objects that are slightly deformed with respect to the model, in some cases cannot be found or are found but only with a low accuracy. For such objects it is possible to additionally pass a maximal allowable object deformation in the parameter SubPixelSubPixelSubPixelSubPixelsubPixelsub_pixel. The deformation must be specified in pixels. This can be done by passing the optional parameter value 'max_deformation '"max_deformation ""max_deformation ""max_deformation ""max_deformation ""max_deformation " followed by an integer value between 0 and 32 (in the same string), which specifies the maximum deformation. For example, if the shape of the object may be deformed by up to 2 pixels with respect to the shape that is stored in the model, the value 'max_deformation 2'"max_deformation 2""max_deformation 2""max_deformation 2""max_deformation 2""max_deformation 2" must be passed in SubPixelSubPixelSubPixelSubPixelsubPixelsub_pixel in addition to the above described mode for the subpixel extraction, i.e., for example ['least_squares', 'max_deformation 2']["least_squares", "max_deformation 2"]["least_squares", "max_deformation 2"]["least_squares", "max_deformation 2"]["least_squares", "max_deformation 2"]["least_squares", "max_deformation 2"]. Passing the value 'max_deformation 0'"max_deformation 0""max_deformation 0""max_deformation 0""max_deformation 0""max_deformation 0" corresponds to a search without allowing deformations, i.e., the behavior is the same as if no 'max_deformation '"max_deformation ""max_deformation ""max_deformation ""max_deformation ""max_deformation " is passed. Note that higher values for the maximum deformation often result in an increased runtime. Furthermore, the higher the deformation value is chosen, the higher is the risk of finding wrong model instances. Both problems mainly arise when searching for small objects or for objects with fine structures. This is because such kinds of objects for higher deformations lose their characteristic shape, which is important for a robust search. Also note that for higher deformations the accuracy of partially occluded objects might decrease if clutter is present close to the object. Consequently, the maximum deformation should be chosen as small as possible and only as high as necessary. Approximately rotationally symmetric objects may not be found if 'max_deformation'"max_deformation""max_deformation""max_deformation""max_deformation""max_deformation" and AngleExtentAngleExtentAngleExtentAngleExtentangleExtentangle_extent are both set to a value greater than 0. In that case, ambiguities may occur that cannot be resolved, and the match is rejected as false. If this happens, try to set either 'max_deformation'"max_deformation""max_deformation""max_deformation""max_deformation""max_deformation" or AngleExtentAngleExtentAngleExtentAngleExtentangleExtentangle_extent to 0, or adjust the model such that symmetries are reduced. When specifying a deformation higher than 0 the computation of the score depends on the chosen value for the subpixel extraction. In most cases, the score of a match changes if 'least_squares'"least_squares""least_squares""least_squares""least_squares""least_squares", 'least_squares_high'"least_squares_high""least_squares_high""least_squares_high""least_squares_high""least_squares_high", or 'least_squares_very_high'"least_squares_very_high""least_squares_very_high""least_squares_very_high""least_squares_very_high""least_squares_very_high" (see above) is chosen for the subpixel extraction (in comparison to 'none'"none""none""none""none""none" or 'interpolation'"interpolation""interpolation""interpolation""interpolation""interpolation"). Furthermore, if one of the least-squares adjustments is selected the score might increase when increasing the maximum deformation because then for the model points more corresponding image points can be found. To get a meaningful score value and to avoid erroneous matches, we recommend to always combine the allowance of a deformation with a least-squares adjustment.

If the subpixel extraction and/or the maximum object deformation is specified separately for each model, for each model passed in ModelIDsModelIDsModelIDsModelIDsmodelIDsmodel_ids exactly one value for the subpixel extraction must be passed in SubPixelSubPixelSubPixelSubPixelsubPixelsub_pixel. After each value for the subpixel extraction optionally a second value can be passed, which describes the maximum object deformation of the corresponding mode. If for a certain model no value for the maximum object deformation is passed, the model is searched without taking deformations into account. For example, if two models are passed in ModelIDsModelIDsModelIDsModelIDsmodelIDsmodel_ids and for the first model the subpixel extraction is set to 'interpolation'"interpolation""interpolation""interpolation""interpolation""interpolation" and no object deformations are allowed and for the second model the subpixel extraction is set to 'least_squares'"least_squares""least_squares""least_squares""least_squares""least_squares" and a maximum object deformation of 3 pixels is allowed, then the tuple ['interpolation', 'least_squares', 'max_deformation 3']["interpolation", "least_squares", "max_deformation 3"]["interpolation", "least_squares", "max_deformation 3"]["interpolation", "least_squares", "max_deformation 3"]["interpolation", "least_squares", "max_deformation 3"]["interpolation", "least_squares", "max_deformation 3"] must be passed in SubPixelSubPixelSubPixelSubPixelsubPixelsub_pixel. Alternatively, the equivalent tuple ['interpolation', 'max_deformation 0', 'least_squares', 'max_deformation 3']["interpolation", "max_deformation 0", "least_squares", "max_deformation 3"]["interpolation", "max_deformation 0", "least_squares", "max_deformation 3"]["interpolation", "max_deformation 0", "least_squares", "max_deformation 3"]["interpolation", "max_deformation 0", "least_squares", "max_deformation 3"]["interpolation", "max_deformation 0", "least_squares", "max_deformation 3"] may be passed.

NumLevelsNumLevelsNumLevelsNumLevelsnumLevelsnum_levels:

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

In certain cases, the number of pyramid levels that was determined automatically with, for example, create_aniso_shape_modelcreate_aniso_shape_modelCreateAnisoShapeModelCreateAnisoShapeModelCreateAnisoShapeModelcreate_aniso_shape_model 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 MinScoreMinScoreMinScoreMinScoreminScoremin_score to a very low value to find all matches, it may be better to query the value of NumLevelsNumLevelsNumLevelsNumLevelsnumLevelsnum_levels with get_shape_model_paramsget_shape_model_paramsGetShapeModelParamsGetShapeModelParamsGetShapeModelParamsget_shape_model_params and then use a slightly lower value in find_aniso_shape_modelsfind_aniso_shape_modelsFindAnisoShapeModelsFindAnisoShapeModelsFindAnisoShapeModelsfind_aniso_shape_models. This approach is often better regarding the speed and robustness of the matching.

Optionally, NumLevelsNumLevelsNumLevelsNumLevelsnumLevelsnum_levels 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 NumLevelsNumLevelsNumLevelsNumLevelsnumLevelsnum_levels 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. Hence, if a high accuracy is desired, SubPixelSubPixelSubPixelSubPixelsubPixelsub_pixel should be set to at least 'least_squares'"least_squares""least_squares""least_squares""least_squares""least_squares". 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, NumLevelsNumLevelsNumLevelsNumLevelsnumLevelsnum_levels must contain twice the number of elements as ModelIDsModelIDsModelIDsModelIDsmodelIDsmodel_ids. In this case, the number of pyramid levels and the lowest pyramid level must be specified interleaved in NumLevelsNumLevelsNumLevelsNumLevelsnumLevelsnum_levels. If, for example, two models are specified in ModelIDsModelIDsModelIDsModelIDsmodelIDsmodel_ids, 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, NumLevelsNumLevelsNumLevelsNumLevelsnumLevelsnum_levels = [5,2,4,1] must be selected. If exactly two models are specified in ModelIDsModelIDsModelIDsModelIDsmodelIDsmodel_ids, 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 in NumLevelsNumLevelsNumLevelsNumLevelsnumLevelsnum_levels is interpreted as the explicit specification of the number of pyramid levels for the two models.

In input images of poor quality, i.e., in images that are, e.g., defocused, deformed, or noisy, often no instances of the shape model can be found on the lowest pyramid level. The reason for this behavior is the missing or deformed edge information which is a result of the poor image quality. Nevertheless, the edge information may be sufficient on higher pyramid levels. But keep in mind the above mentioned restrictions on accuracy and robustness if instances that were found on higher pyramid levels are used. The selection of the suitable pyramid level, i.e., the lowest pyramid level on which at least one instance of the shape model can be found, depends on the model and on the input image. This pyramid level may vary from image to image. To facilitate the matching on images of poor quality, the lowest pyramid level on which at least one instance of the model can be found can be determined automatically during the matching. To activate this mechanism, i.e., to use the so-called 'increased tolerance mode', the lowest pyramid level must be specified negatively in NumLevelsNumLevelsNumLevelsNumLevelsnumLevelsnum_levels. If, e.g., NumLevelsNumLevelsNumLevelsNumLevelsnumLevelsnum_levels is set to [5,2,4,-1], the lowest pyramid level for the first model is set to 2. If no instance of the first model can be found on this pyramid level, no result will be returned for this model. For the second shape model, the lowest pyramid level is set to -1. Therefore, an instance of the shape model is searched on the pyramid level 1. If no instance of the second model can be found on this pyramid level, the lowest pyramid level is determined on which at least one instance of the model can be found. The instances of this pyramid level will then be returned.

If a model was adapted with adapt_shape_model_high_noiseadapt_shape_model_high_noiseAdaptShapeModelHighNoiseAdaptShapeModelHighNoiseAdaptShapeModelHighNoiseadapt_shape_model_high_noise the estimated lowest pyramid level will be used by default. However, the user can override the estimated lowest pyramid level by providing explicitly the lowest pyramid level as described above.

GreedinessGreedinessGreedinessGreedinessgreedinessgreediness:

The parameter GreedinessGreedinessGreedinessGreedinessgreedinessgreediness determines how “greedily” the search should be carried out. If GreedinessGreedinessGreedinessGreedinessgreedinessgreediness=0, a safe search heuristic is used, which always finds the model if it is visible in the image and the other parameters are set appropriately. However, the search will be relatively time consuming in this case. If GreedinessGreedinessGreedinessGreedinessgreedinessgreediness=1, an unsafe search heuristic is used, which may cause the model not to be found in rare cases, even though it is visible in the image. For GreedinessGreedinessGreedinessGreedinessgreedinessgreediness=1, the maximum search speed is achieved. In almost all cases, the shape model will always be found for GreedinessGreedinessGreedinessGreedinessgreedinessgreediness=0.9.

Output parameters in detail

RowRowRowRowrowrow, ColumnColumnColumnColumncolumncolumn, AngleAngleAngleAngleangleangle, ScaleRScaleRScaleRScaleRscaleRscale_r, ScaleCScaleCScaleCScaleCscaleCscale_c:

The position, rotation, and scale in the row and column direction of the found instances of the model are returned in RowRowRowRowrowrow, ColumnColumnColumnColumncolumncolumn, AngleAngleAngleAngleangleangle, ScaleRScaleRScaleRScaleRscaleRscale_r, and ScaleCScaleCScaleCScaleCscaleCscale_c. The coordinates RowRowRowRowrowrow and ColumnColumnColumnColumncolumncolumn are the coordinates of the origin of the shape 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 shape model with create_aniso_shape_modelcreate_aniso_shape_modelCreateAnisoShapeModelCreateAnisoShapeModelCreateAnisoShapeModelcreate_aniso_shape_model. A different origin can be set with set_shape_model_originset_shape_model_originSetShapeModelOriginSetShapeModelOriginSetShapeModelOriginset_shape_model_origin.

Note that the coordinates RowRowRowRowrowrow and ColumnColumnColumnColumncolumncolumn do 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 for find_aniso_shape_modelfind_aniso_shape_modelFindAnisoShapeModelFindAnisoShapeModelFindAnisoShapeModelfind_aniso_shape_model shows how to create this matrix and use it to display the model at the found position in the search image.

Note also that for visualizing the model at the found position, also the procedure dev_display_shape_matching_results can be used.

ScoreScoreScoreScorescorescore:

The score of each found instance is returned in ScoreScoreScoreScorescorescore. The score is a number between 0 and 1, which is an approximate measure of how much of the model is visible in the image. If, for example, half of the model is occluded, the score cannot exceed 0.5.

In case that the shape models have been extended by clutter parameters using set_shape_model_clutterset_shape_model_clutterSetShapeModelClutterSetShapeModelClutterSetShapeModelClutterset_shape_model_clutter, following the above values ScoreScoreScoreScorescorescore also returns the clutter values of each found instance. If, for example, half of the clutter region is filled by clutter edges, the clutter value will equal 0.5. If, e.g., two instances are found, the score is 0.9 for the first instance and 0.8 for the second instance, and the clutter value is 0.2 for the first instance and 0.1 for the second instance, ScoreScoreScoreScorescorescore = [0.9,0.8,0.2,0.1] is returned. Please note that of all shape-based matching results, clutter values are affected the most when a variation of illumination occurs.

ModelModelModelModelmodelmodel:

The type of the found instances of the models is returned in ModelModelModelModelmodelmodel. The elements of ModelModelModelModelmodelmodel are indices into the tuple ModelIDsModelIDsModelIDsModelIDsmodelIDsmodel_ids, i.e., they can contain values from 0 to |ModelIDsModelIDsModelIDsModelIDsmodelIDsmodel_ids|-1. Hence, a value of 0 in an element of ModelModelModelModelmodelmodel corresponds to an instance of the first model in ModelIDsModelIDsModelIDsModelIDsmodelIDsmodel_ids.

Specifying a timeout

Using the operator set_shape_model_paramset_shape_model_paramSetShapeModelParamSetShapeModelParamSetShapeModelParamset_shape_model_param you can specify a 'timeout'"timeout""timeout""timeout""timeout""timeout" for find_aniso_shape_modelsfind_aniso_shape_modelsFindAnisoShapeModelsFindAnisoShapeModelsFindAnisoShapeModelsfind_aniso_shape_models. If the shape models referenced by ModelIDsModelIDsModelIDsModelIDsmodelIDsmodel_ids hold different values for 'timeout'"timeout""timeout""timeout""timeout""timeout", find_aniso_shape_modelsfind_aniso_shape_modelsFindAnisoShapeModelsFindAnisoShapeModelsFindAnisoShapeModelsfind_aniso_shape_models uses the smallest one. If find_aniso_shape_modelsfind_aniso_shape_modelsFindAnisoShapeModelsFindAnisoShapeModelsFindAnisoShapeModelsfind_aniso_shape_models reaches this 'timeout'"timeout""timeout""timeout""timeout""timeout", it terminates without results and returns the error code 9400 (H_ERR_TIMEOUT). Depending on the scaling ranges specified by ScaleRMinScaleRMinScaleRMinScaleRMinscaleRMinscale_rmin, ScaleRMaxScaleRMaxScaleRMaxScaleRMaxscaleRMaxscale_rmax, ScaleCMinScaleCMinScaleCMinScaleCMinscaleCMinscale_cmin and ScaleCMaxScaleCMaxScaleCMaxScaleCMaxscaleCMaxscale_cmax, find_aniso_shape_modelsfind_aniso_shape_modelsFindAnisoShapeModelsFindAnisoShapeModelsFindAnisoShapeModelsfind_aniso_shape_models needs a significant amount of time to free cached transformations if the shape model is not pregenerated. As this transformations have to be freed after a timeout occurs, the runtime of find_aniso_shape_modelsfind_aniso_shape_modelsFindAnisoShapeModelsFindAnisoShapeModelsFindAnisoShapeModelsfind_aniso_shape_models exceeds the value of the specified 'timeout'"timeout""timeout""timeout""timeout""timeout" by this time.

MinContrast with multiple models

Please note, that the different models that are given with the parameter ModelIDsModelIDsModelIDsModelIDsmodelIDsmodel_ids should have been created with the same value of MinContrastMinContrastMinContrastMinContrastminContrastmin_contrast. If they were created with different values for MinContrastMinContrastMinContrastMinContrastminContrastmin_contrast, find_aniso_shape_modelsfind_aniso_shape_modelsFindAnisoShapeModelsFindAnisoShapeModelsFindAnisoShapeModelsfind_aniso_shape_models will use the smallest of these values.

Visualization of the results

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

Further Information

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

Execution Information

This operator supports cancelling timeouts and interrupts.

Parameters

ImageImageImageImageimageimage (input_object)  (multichannel-)image(-array) objectHImageHObjectHImageHobject (byte / uint2)

Input image in which the models should be found.

ModelIDsModelIDsModelIDsModelIDsmodelIDsmodel_ids (input_control)  shape_model(-array) HShapeModel, HTupleMaybeSequence[HHandle]HTupleHtuple (handle) (IntPtr) (HHandle) (handle)

Handle of the models.

AngleStartAngleStartAngleStartAngleStartangleStartangle_start (input_control)  angle.rad(-array) HTupleMaybeSequence[float]HTupleHtuple (real) (double) (double) (double)

Smallest rotation of the models.

Default value: -0.39

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

AngleExtentAngleExtentAngleExtentAngleExtentangleExtentangle_extent (input_control)  angle.rad(-array) HTupleMaybeSequence[float]HTupleHtuple (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

ScaleRMinScaleRMinScaleRMinScaleRMinscaleRMinscale_rmin (input_control)  number(-array) HTupleMaybeSequence[float]HTupleHtuple (real) (double) (double) (double)

Minimum scale of the models in the row direction.

Default value: 0.9

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

Restriction: ScaleRMin > 0

ScaleRMaxScaleRMaxScaleRMaxScaleRMaxscaleRMaxscale_rmax (input_control)  number(-array) HTupleMaybeSequence[float]HTupleHtuple (real) (double) (double) (double)

Maximum scale of the models in the row direction.

Default value: 1.1

Suggested values: 1.0, 1.1, 1.2, 1.3, 1.4, 1.5

Restriction: ScaleRMax >= ScaleRMin

ScaleCMinScaleCMinScaleCMinScaleCMinscaleCMinscale_cmin (input_control)  number(-array) HTupleMaybeSequence[float]HTupleHtuple (real) (double) (double) (double)

Minimum scale of the models in the column direction.

Default value: 0.9

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

Restriction: ScaleCMin > 0

ScaleCMaxScaleCMaxScaleCMaxScaleCMaxscaleCMaxscale_cmax (input_control)  number(-array) HTupleMaybeSequence[float]HTupleHtuple (real) (double) (double) (double)

Maximum scale of the models in the column direction.

Default value: 1.1

Suggested values: 1.0, 1.1, 1.2, 1.3, 1.4, 1.5

Restriction: ScaleCMax >= ScaleCMin

MinScoreMinScoreMinScoreMinScoreminScoremin_score (input_control)  real(-array) HTupleMaybeSequence[float]HTupleHtuple (real) (double) (double) (double)

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

Default value: 0.5

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 min_score ≤ 1

Minimum increment: 0.01

Recommended increment: 0.05

NumMatchesNumMatchesNumMatchesNumMatchesnumMatchesnum_matches (input_control)  integer(-array) HTupleMaybeSequence[int]HTupleHtuple (integer) (int / long) (Hlong) (Hlong)

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

Default value: 1

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

MaxOverlapMaxOverlapMaxOverlapMaxOverlapmaxOverlapmax_overlap (input_control)  real(-array) HTupleMaybeSequence[float]HTupleHtuple (real) (double) (double) (double)

Maximum overlap of the instances of the models 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 max_overlap ≤ 1

Minimum increment: 0.01

Recommended increment: 0.05

SubPixelSubPixelSubPixelSubPixelsubPixelsub_pixel (input_control)  string(-array) HTupleMaybeSequence[str]HTupleHtuple (string) (string) (HString) (char*)

Subpixel accuracy if not equal to 'none'"none""none""none""none""none".

Default value: 'least_squares' "least_squares" "least_squares" "least_squares" "least_squares" "least_squares"

Suggested values: 'none'"none""none""none""none""none", 'interpolation'"interpolation""interpolation""interpolation""interpolation""interpolation", 'least_squares'"least_squares""least_squares""least_squares""least_squares""least_squares", 'least_squares_high'"least_squares_high""least_squares_high""least_squares_high""least_squares_high""least_squares_high", 'least_squares_very_high'"least_squares_very_high""least_squares_very_high""least_squares_very_high""least_squares_very_high""least_squares_very_high", 'max_deformation 1'"max_deformation 1""max_deformation 1""max_deformation 1""max_deformation 1""max_deformation 1", 'max_deformation 2'"max_deformation 2""max_deformation 2""max_deformation 2""max_deformation 2""max_deformation 2", 'max_deformation 3'"max_deformation 3""max_deformation 3""max_deformation 3""max_deformation 3""max_deformation 3", 'max_deformation 4'"max_deformation 4""max_deformation 4""max_deformation 4""max_deformation 4""max_deformation 4", 'max_deformation 5'"max_deformation 5""max_deformation 5""max_deformation 5""max_deformation 5""max_deformation 5", 'max_deformation 6'"max_deformation 6""max_deformation 6""max_deformation 6""max_deformation 6""max_deformation 6"

NumLevelsNumLevelsNumLevelsNumLevelsnumLevelsnum_levels (input_control)  integer(-array) HTupleMaybeSequence[int]HTupleHtuple (integer) (int / long) (Hlong) (Hlong)

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

Default value: 0

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

GreedinessGreedinessGreedinessGreedinessgreedinessgreediness (input_control)  real(-array) HTupleMaybeSequence[float]HTupleHtuple (real) (double) (double) (double)

“Greediness” of the search heuristic (0: safe but slow; 1: fast but matches may be missed).

Default value: 0.9

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 ≤ Greediness Greediness Greediness Greediness greediness greediness ≤ 1

Minimum increment: 0.01

Recommended increment: 0.05

RowRowRowRowrowrow (output_control)  point.y-array HTupleSequence[float]HTupleHtuple (real) (double) (double) (double)

Row coordinate of the found instances of the models.

ColumnColumnColumnColumncolumncolumn (output_control)  point.x-array HTupleSequence[float]HTupleHtuple (real) (double) (double) (double)

Column coordinate of the found instances of the models.

AngleAngleAngleAngleangleangle (output_control)  angle.rad-array HTupleSequence[float]HTupleHtuple (real) (double) (double) (double)

Rotation angle of the found instances of the models.

ScaleRScaleRScaleRScaleRscaleRscale_r (output_control)  number-array HTupleSequence[float]HTupleHtuple (real) (double) (double) (double)

Scale of the found instances of the models in the row direction.

ScaleCScaleCScaleCScaleCscaleCscale_c (output_control)  number-array HTupleSequence[float]HTupleHtuple (real) (double) (double) (double)

Scale of the found instances of the models in the column direction.

ScoreScoreScoreScorescorescore (output_control)  real-array HTupleSequence[float]HTupleHtuple (real) (double) (double) (double)

Score of the found instances of the models.

ModelModelModelModelmodelmodel (output_control)  integer-array HTupleSequence[int]HTupleHtuple (integer) (int / long) (Hlong) (Hlong)

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_aniso_shape_model (ImageReduced1,'auto', -0.39, 0.79, 'auto', 0.9, \
                          1.1, 'auto', 0.9, 1.1, 'auto', 'auto', \
                          'use_polarity', 'auto', 'auto', ModelID1)
create_aniso_shape_model (ImageReduced2,'auto', -0.39, 0.79, 'auto', 0.9, \
                          1.1, 'auto', 0.9, 1.1, 'auto', 'auto', \
                          'use_polarity', 'auto', 'auto', ModelID2)
ModelIDs:=[ModelID1, ModelID2]
find_aniso_shape_models(Image, ModelIDs, -0.39, 0.79, 0.9, 1.1, 0.9, 1.1, \
                        0.5, 1, 0.5, 'least_squares', 0, 0.9, Row, Column, \
                        Angle, ScaleR, ScaleC, Score, Model)
* Display results
dev_display_shape_matching_results (ModelIDs, 'red', Row, Column, Angle, \
                                    ScaleR, ScaleC, Model)

Result

If the parameter values are correct, the operator find_aniso_shape_modelsfind_aniso_shape_modelsFindAnisoShapeModelsFindAnisoShapeModelsFindAnisoShapeModelsfind_aniso_shape_models returns the value 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>)set_system("no_object_result",<Result>). If necessary, an exception is raised.

Possible Predecessors

add_channelsadd_channelsAddChannelsAddChannelsAddChannelsadd_channels, create_aniso_shape_modelcreate_aniso_shape_modelCreateAnisoShapeModelCreateAnisoShapeModelCreateAnisoShapeModelcreate_aniso_shape_model, read_shape_modelread_shape_modelReadShapeModelReadShapeModelReadShapeModelread_shape_model, set_shape_model_originset_shape_model_originSetShapeModelOriginSetShapeModelOriginSetShapeModelOriginset_shape_model_origin, set_shape_model_clutterset_shape_model_clutterSetShapeModelClutterSetShapeModelClutterSetShapeModelClutterset_shape_model_clutter

Possible Successors

clear_shape_modelclear_shape_modelClearShapeModelClearShapeModelClearShapeModelclear_shape_model

Alternatives

find_shape_modelsfind_shape_modelsFindShapeModelsFindShapeModelsFindShapeModelsfind_shape_models, find_scaled_shape_modelsfind_scaled_shape_modelsFindScaledShapeModelsFindScaledShapeModelsFindScaledShapeModelsfind_scaled_shape_models, find_shape_modelfind_shape_modelFindShapeModelFindShapeModelFindShapeModelfind_shape_model, find_scaled_shape_modelfind_scaled_shape_modelFindScaledShapeModelFindScaledShapeModelFindScaledShapeModelfind_scaled_shape_model, find_aniso_shape_modelfind_aniso_shape_modelFindAnisoShapeModelFindAnisoShapeModelFindAnisoShapeModelfind_aniso_shape_model, find_ncc_modelfind_ncc_modelFindNccModelFindNccModelFindNccModelfind_ncc_model, find_ncc_modelsfind_ncc_modelsFindNccModelsFindNccModelsFindNccModelsfind_ncc_models

See also

set_systemset_systemSetSystemSetSystemSetSystemset_system, get_systemget_systemGetSystemGetSystemGetSystemget_system, set_shape_model_paramset_shape_model_paramSetShapeModelParamSetShapeModelParamSetShapeModelParamset_shape_model_param

Module

Matching