find_component_modelT_find_component_modelFindComponentModelFindComponentModelfind_component_model (Operator)

Name

find_component_modelT_find_component_modelFindComponentModelFindComponentModelfind_component_model — Find the best matches of a component model in an image.

Signature

find_component_model(Image : : ComponentModelID, RootComponent, AngleStartRoot, AngleExtentRoot, MinScore, NumMatches, MaxOverlap, IfRootNotFound, IfComponentNotFound, PosePrediction, MinScoreComp, SubPixelComp, NumLevelsComp, GreedinessComp : ModelStart, ModelEnd, Score, RowComp, ColumnComp, AngleComp, ScoreComp, ModelComp)

Herror T_find_component_model(const Hobject Image, const Htuple ComponentModelID, const Htuple RootComponent, const Htuple AngleStartRoot, const Htuple AngleExtentRoot, const Htuple MinScore, const Htuple NumMatches, const Htuple MaxOverlap, const Htuple IfRootNotFound, const Htuple IfComponentNotFound, const Htuple PosePrediction, const Htuple MinScoreComp, const Htuple SubPixelComp, const Htuple NumLevelsComp, const Htuple GreedinessComp, Htuple* ModelStart, Htuple* ModelEnd, Htuple* Score, Htuple* RowComp, Htuple* ColumnComp, Htuple* AngleComp, Htuple* ScoreComp, Htuple* ModelComp)

void FindComponentModel(const HObject& Image, const HTuple& ComponentModelID, const HTuple& RootComponent, const HTuple& AngleStartRoot, const HTuple& AngleExtentRoot, const HTuple& MinScore, const HTuple& NumMatches, const HTuple& MaxOverlap, const HTuple& IfRootNotFound, const HTuple& IfComponentNotFound, const HTuple& PosePrediction, const HTuple& MinScoreComp, const HTuple& SubPixelComp, const HTuple& NumLevelsComp, const HTuple& GreedinessComp, HTuple* ModelStart, HTuple* ModelEnd, HTuple* Score, HTuple* RowComp, HTuple* ColumnComp, HTuple* AngleComp, HTuple* ScoreComp, HTuple* ModelComp)

HTuple HComponentModel::FindComponentModel(const HImage& Image, const HTuple& RootComponent, const HTuple& AngleStartRoot, const HTuple& AngleExtentRoot, double MinScore, Hlong NumMatches, double MaxOverlap, const HString& IfRootNotFound, const HString& IfComponentNotFound, const HString& PosePrediction, const HTuple& MinScoreComp, const HTuple& SubPixelComp, const HTuple& NumLevelsComp, const HTuple& GreedinessComp, HTuple* ModelEnd, HTuple* Score, HTuple* RowComp, HTuple* ColumnComp, HTuple* AngleComp, HTuple* ScoreComp, HTuple* ModelComp) const

Hlong HComponentModel::FindComponentModel(const HImage& Image, Hlong RootComponent, double AngleStartRoot, double AngleExtentRoot, double MinScore, Hlong NumMatches, double MaxOverlap, const HString& IfRootNotFound, const HString& IfComponentNotFound, const HString& PosePrediction, double MinScoreComp, const HString& SubPixelComp, Hlong NumLevelsComp, double GreedinessComp, Hlong* ModelEnd, double* Score, double* RowComp, double* ColumnComp, double* AngleComp, double* ScoreComp, Hlong* ModelComp) const

Hlong HComponentModel::FindComponentModel(const HImage& Image, Hlong RootComponent, double AngleStartRoot, double AngleExtentRoot, double MinScore, Hlong NumMatches, double MaxOverlap, const char* IfRootNotFound, const char* IfComponentNotFound, const char* PosePrediction, double MinScoreComp, const char* SubPixelComp, Hlong NumLevelsComp, double GreedinessComp, Hlong* ModelEnd, double* Score, double* RowComp, double* ColumnComp, double* AngleComp, double* ScoreComp, Hlong* ModelComp) const

Hlong HComponentModel::FindComponentModel(const HImage& Image, Hlong RootComponent, double AngleStartRoot, double AngleExtentRoot, double MinScore, Hlong NumMatches, double MaxOverlap, const wchar_t* IfRootNotFound, const wchar_t* IfComponentNotFound, const wchar_t* PosePrediction, double MinScoreComp, const wchar_t* SubPixelComp, Hlong NumLevelsComp, double GreedinessComp, Hlong* ModelEnd, double* Score, double* RowComp, double* ColumnComp, double* AngleComp, double* ScoreComp, Hlong* ModelComp) const   (Windows only)

HTuple HImage::FindComponentModel(const HComponentModel& ComponentModelID, const HTuple& RootComponent, const HTuple& AngleStartRoot, const HTuple& AngleExtentRoot, double MinScore, Hlong NumMatches, double MaxOverlap, const HString& IfRootNotFound, const HString& IfComponentNotFound, const HString& PosePrediction, const HTuple& MinScoreComp, const HTuple& SubPixelComp, const HTuple& NumLevelsComp, const HTuple& GreedinessComp, HTuple* ModelEnd, HTuple* Score, HTuple* RowComp, HTuple* ColumnComp, HTuple* AngleComp, HTuple* ScoreComp, HTuple* ModelComp) const

Hlong HImage::FindComponentModel(const HComponentModel& ComponentModelID, Hlong RootComponent, double AngleStartRoot, double AngleExtentRoot, double MinScore, Hlong NumMatches, double MaxOverlap, const HString& IfRootNotFound, const HString& IfComponentNotFound, const HString& PosePrediction, double MinScoreComp, const HString& SubPixelComp, Hlong NumLevelsComp, double GreedinessComp, Hlong* ModelEnd, double* Score, double* RowComp, double* ColumnComp, double* AngleComp, double* ScoreComp, Hlong* ModelComp) const

Hlong HImage::FindComponentModel(const HComponentModel& ComponentModelID, Hlong RootComponent, double AngleStartRoot, double AngleExtentRoot, double MinScore, Hlong NumMatches, double MaxOverlap, const char* IfRootNotFound, const char* IfComponentNotFound, const char* PosePrediction, double MinScoreComp, const char* SubPixelComp, Hlong NumLevelsComp, double GreedinessComp, Hlong* ModelEnd, double* Score, double* RowComp, double* ColumnComp, double* AngleComp, double* ScoreComp, Hlong* ModelComp) const

Hlong HImage::FindComponentModel(const HComponentModel& ComponentModelID, Hlong RootComponent, double AngleStartRoot, double AngleExtentRoot, double MinScore, Hlong NumMatches, double MaxOverlap, const wchar_t* IfRootNotFound, const wchar_t* IfComponentNotFound, const wchar_t* PosePrediction, double MinScoreComp, const wchar_t* SubPixelComp, Hlong NumLevelsComp, double GreedinessComp, Hlong* ModelEnd, double* Score, double* RowComp, double* ColumnComp, double* AngleComp, double* ScoreComp, Hlong* ModelComp) const   (Windows only)

static void HOperatorSet.FindComponentModel(HObject image, HTuple componentModelID, HTuple rootComponent, HTuple angleStartRoot, HTuple angleExtentRoot, HTuple minScore, HTuple numMatches, HTuple maxOverlap, HTuple ifRootNotFound, HTuple ifComponentNotFound, HTuple posePrediction, HTuple minScoreComp, HTuple subPixelComp, HTuple numLevelsComp, HTuple greedinessComp, out HTuple modelStart, out HTuple modelEnd, out HTuple score, out HTuple rowComp, out HTuple columnComp, out HTuple angleComp, out HTuple scoreComp, out HTuple modelComp)

HTuple HComponentModel.FindComponentModel(HImage image, HTuple rootComponent, HTuple angleStartRoot, HTuple angleExtentRoot, double minScore, int numMatches, double maxOverlap, string ifRootNotFound, string ifComponentNotFound, string posePrediction, HTuple minScoreComp, HTuple subPixelComp, HTuple numLevelsComp, HTuple greedinessComp, out HTuple modelEnd, out HTuple score, out HTuple rowComp, out HTuple columnComp, out HTuple angleComp, out HTuple scoreComp, out HTuple modelComp)

int HComponentModel.FindComponentModel(HImage image, int rootComponent, double angleStartRoot, double angleExtentRoot, double minScore, int numMatches, double maxOverlap, string ifRootNotFound, string ifComponentNotFound, string posePrediction, double minScoreComp, string subPixelComp, int numLevelsComp, double greedinessComp, out int modelEnd, out double score, out double rowComp, out double columnComp, out double angleComp, out double scoreComp, out int modelComp)

HTuple HImage.FindComponentModel(HComponentModel componentModelID, HTuple rootComponent, HTuple angleStartRoot, HTuple angleExtentRoot, double minScore, int numMatches, double maxOverlap, string ifRootNotFound, string ifComponentNotFound, string posePrediction, HTuple minScoreComp, HTuple subPixelComp, HTuple numLevelsComp, HTuple greedinessComp, out HTuple modelEnd, out HTuple score, out HTuple rowComp, out HTuple columnComp, out HTuple angleComp, out HTuple scoreComp, out HTuple modelComp)

int HImage.FindComponentModel(HComponentModel componentModelID, int rootComponent, double angleStartRoot, double angleExtentRoot, double minScore, int numMatches, double maxOverlap, string ifRootNotFound, string ifComponentNotFound, string posePrediction, double minScoreComp, string subPixelComp, int numLevelsComp, double greedinessComp, out int modelEnd, out double score, out double rowComp, out double columnComp, out double angleComp, out double scoreComp, out int modelComp)

def find_component_model(image: HObject, component_model_id: HHandle, root_component: MaybeSequence[int], angle_start_root: MaybeSequence[float], angle_extent_root: MaybeSequence[float], min_score: float, num_matches: int, max_overlap: float, if_root_not_found: str, if_component_not_found: str, pose_prediction: str, min_score_comp: MaybeSequence[float], sub_pixel_comp: MaybeSequence[str], num_levels_comp: MaybeSequence[int], greediness_comp: MaybeSequence[float]) -> Tuple[Sequence[int], Sequence[int], Sequence[float], Sequence[float], Sequence[float], Sequence[float], Sequence[float], Sequence[int]]

def find_component_model_s(image: HObject, component_model_id: HHandle, root_component: MaybeSequence[int], angle_start_root: MaybeSequence[float], angle_extent_root: MaybeSequence[float], min_score: float, num_matches: int, max_overlap: float, if_root_not_found: str, if_component_not_found: str, pose_prediction: str, min_score_comp: MaybeSequence[float], sub_pixel_comp: MaybeSequence[str], num_levels_comp: MaybeSequence[int], greediness_comp: MaybeSequence[float]) -> Tuple[int, int, float, float, float, float, float, int]

Description

The operator find_component_modelfind_component_modelFindComponentModelFindComponentModelFindComponentModelfind_component_model finds the best NumMatchesNumMatchesNumMatchesNumMatchesnumMatchesnum_matches instances of the component model ComponentModelIDComponentModelIDComponentModelIDComponentModelIDcomponentModelIDcomponent_model_id in the input image ImageImageImageImageimageimage.

The result of the search can be visualized using get_found_component_modelget_found_component_modelGetFoundComponentModelGetFoundComponentModelGetFoundComponentModelget_found_component_model. Also the operator can be used to extract the component matches of a certain component model instance.

Further information about input parameters

ComponentModelIDComponentModelIDComponentModelIDComponentModelIDcomponentModelIDcomponent_model_id:

Handle of the component model.

The model must have been created previously by calling create_trained_component_modelcreate_trained_component_modelCreateTrainedComponentModelCreateTrainedComponentModelCreateTrainedComponentModelcreate_trained_component_model or create_component_modelcreate_component_modelCreateComponentModelCreateComponentModelCreateComponentModelcreate_component_model, or read in using read_component_modelread_component_modelReadComponentModelReadComponentModelReadComponentModelread_component_model.

RootComponentRootComponentRootComponentRootComponentrootComponentroot_component:

Index of the root component.

The components of the component model ComponentModelIDComponentModelIDComponentModelIDComponentModelIDcomponentModelIDcomponent_model_id are represented in in a tree structure. The component that stands at the root of this search tree is the root component.

The root component is searched within the full search space, i.e., at all allowed positions and in the allowed range of orientations (see below). In contrast, the remaining components are searched relative to the pose of their predecessor in the search tree within a restricted search space that is computed from the relations (recursive search).

To what extent a model component is suited to act as root component depends on several factors. In principle, a model component that can be found in the image with a high probability, should be chosen. Therefore, a component that is sometimes occluded to a high degree or that is missing in some cases is not well suited to act as root component. For the behavior in such cases, see the entry IfRootNotFoundIfRootNotFoundIfRootNotFoundIfRootNotFoundifRootNotFoundif_root_not_found below.

A different possible criterion is the computation time that is associated with the root component during the search. A ranking of the model components that is based on the latter criterion is returned in RootRankingRootRankingRootRankingRootRankingrootRankingroot_ranking of the operator create_trained_component_modelcreate_trained_component_modelCreateTrainedComponentModelCreateTrainedComponentModelCreateTrainedComponentModelcreate_trained_component_model or create_component_modelcreate_component_modelCreateComponentModelCreateComponentModelCreateComponentModelcreate_component_model, respectively. If the complete ranking is passed in RootComponentRootComponentRootComponentRootComponentrootComponentroot_component, the first value RootComponentRootComponentRootComponentRootComponentrootComponentroot_component[0] is automatically selected as the root component.

AngleStartRootAngleStartRootAngleStartRootAngleStartRootangleStartRootangle_start_root and AngleExtentRootAngleExtentRootAngleExtentRootAngleExtentRootangleExtentRootangle_extent_root:

Specify the allowed angle range (in [rad]) within which the root component is searched.

If necessary, the range of rotations is clipped to the range given when the component model was created with create_trained_component_modelcreate_trained_component_modelCreateTrainedComponentModelCreateTrainedComponentModelCreateTrainedComponentModelcreate_trained_component_model or create_component_modelcreate_component_modelCreateComponentModelCreateComponentModelCreateComponentModelcreate_component_model, respectively. The angle range for each component can be queried with get_shape_model_paramsget_shape_model_paramsGetShapeModelParamsGetShapeModelParamsGetShapeModelParamsget_shape_model_params. The necessary handle of the corresponding shape model can be obtained using get_component_model_paramsget_component_model_paramsGetComponentModelParamsGetComponentModelParamsGetComponentModelParamsget_component_model_params.

MinScoreMinScoreMinScoreMinScoreminScoremin_score:

Determines what score a potential match of the component model must at least have to be regarded as an instance.

If the component 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. The value of this parameter only slightly influences the computation time. An exception is the case of IfRootNotFoundIfRootNotFoundIfRootNotFoundIfRootNotFoundifRootNotFoundif_root_not_found set to 'select_new_root'"select_new_root""select_new_root""select_new_root""select_new_root""select_new_root" (see below).

NumMatchesNumMatchesNumMatchesNumMatchesnumMatchesnum_matches:

Determines the maximum number of returned instances.

If fewer than NumMatchesNumMatchesNumMatchesNumMatchesnumMatchesnum_matches are found, only that number is returned, i.e., the parameter MinScoreMinScoreMinScoreMinScoreminScoremin_score takes precedence over NumMatchesNumMatchesNumMatchesNumMatchesnumMatchesnum_matches. In case 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. However, if all model instances exceeding MinScoreMinScoreMinScoreMinScoreminScoremin_score in the image should be found, NumMatchesNumMatchesNumMatchesNumMatchesnumMatchesnum_matches must be set to 0.

MaxOverlapMaxOverlapMaxOverlapMaxOverlapmaxOverlapmax_overlap:

Determines by what fraction two instances may at most overlap, whereby this fraction is a number between 0 and 1.

In some cases, found instances only differ in the pose of one or a few components. If two instances overlap each other by more than MaxOverlapMaxOverlapMaxOverlapMaxOverlapmaxOverlapmax_overlap only the best instance is returned. This means, for MaxOverlapMaxOverlapMaxOverlapMaxOverlapmaxOverlapmax_overlap = 0, the found instances may not overlap at all, while for MaxOverlapMaxOverlapMaxOverlapMaxOverlapmaxOverlapmax_overlap = 1 no check for overlap is performed, and hence all instances are returned. The calculation of the overlap is based on the smallest enclosing rectangles of arbitrary orientation (see smallest_rectangle2smallest_rectangle2SmallestRectangle2SmallestRectangle2SmallestRectangle2smallest_rectangle2) of the found component instances.

IfRootNotFoundIfRootNotFoundIfRootNotFoundIfRootNotFoundifRootNotFoundif_root_not_found:

specifies the behavior of the operator when dealing with a missing or strongly occluded root component.

Possible values:

IfComponentNotFoundIfComponentNotFoundIfComponentNotFoundIfComponentNotFoundifComponentNotFoundif_component_not_found:

Specifies how components are searched when the predecessor component was not found (e.g., because she is missing or strongly occluded).

Possible values:

PosePredictionPosePredictionPosePredictionPosePredictionposePredictionpose_prediction:

Determines whether the pose of not found components should be estimated.

Possible values:

MinScoreCompMinScoreCompMinScoreCompMinScoreCompminScoreCompmin_score_comp:

Minimal necessary score of the components for the instances to be found.

This parameter has the same meaning as MinScoreMinScoreMinScoreMinScoreminScoremin_score in find_shape_modelfind_shape_modelFindShapeModelFindShapeModelFindShapeModelfind_shape_model.

Settable is either one element or the same number of elements as model components in ComponentModelIDComponentModelIDComponentModelIDComponentModelIDcomponentModelIDcomponent_model_id. In the first case the parameter is used for all components. In the second case, each parameter element refers to the corresponding component in ComponentModelIDComponentModelIDComponentModelIDComponentModelIDcomponentModelIDcomponent_model_id.

SubPixelCompSubPixelCompSubPixelCompSubPixelCompsubPixelCompsub_pixel_comp:

Determines whether the extraction shall be done subpixel precise and in the given case the maximal allowed object deformation in pixels.

This parameter has the same meaning as SubPixelSubPixelSubPixelSubPixelsubPixelsub_pixel in find_shape_modelfind_shape_modelFindShapeModelFindShapeModelFindShapeModelfind_shape_model. Therefore the maximal allowed object deformation has to be given as integer in the same string. Settable is either one element or the same number of elements as model components in ComponentModelIDComponentModelIDComponentModelIDComponentModelIDcomponentModelIDcomponent_model_id. In the first case the parameter is used for all components. In the second case, each parameter element refers to the corresponding component in ComponentModelIDComponentModelIDComponentModelIDComponentModelIDcomponentModelIDcomponent_model_id.

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"].

NumLevelsCompNumLevelsCompNumLevelsCompNumLevelsCompnumLevelsCompnum_levels_comp:

Determine the pyramid levels for the components used in the matching.

This parameter has the same meaning as NumLevelsNumLevelsNumLevelsNumLevelsnumLevelsnum_levels in find_shape_modelfind_shape_modelFindShapeModelFindShapeModelFindShapeModelfind_shape_model.

It determines the number of pyramid levels for the components to be used in the matching. Settable is either one element or the same number of elements as model components in ComponentModelIDComponentModelIDComponentModelIDComponentModelIDcomponentModelIDcomponent_model_id. In the first case the parameter is used for all components. In the second case, each parameter element refers to the corresponding component in ComponentModelIDComponentModelIDComponentModelIDComponentModelIDcomponentModelIDcomponent_model_id.

Optional, one can set value pairs for this parameter: In this case, the first value still determines the number of pyramid levels to be used. The second value specifies the lowest pyramid level, to which the found matches are tracked. In doing so, one can set either a single value pair or a value pair for each model component in ComponentModelIDComponentModelIDComponentModelIDComponentModelIDcomponentModelIDcomponent_model_id. If different value pairs should be used for different components, they must be specified in the same tuple. In case ComponentModelIDComponentModelIDComponentModelIDComponentModelIDcomponentModelIDcomponent_model_id contains exactly two components and in NumLevelsCompNumLevelsCompNumLevelsCompNumLevelsCompnumLevelsCompnum_levels_comp two values are set, these values are interpreted as different number of pyramid levels to be used and not as a value pair.

Example: ComponentModelIDComponentModelIDComponentModelIDComponentModelIDcomponentModelIDcomponent_model_id contains two components, for which different pyramid levels shall be considered. For the first component 5 levels up to the level 2 shall be used. For the second component 4 levels up to the level 1 shall be used. In this case is NumLevelsCompNumLevelsCompNumLevelsCompNumLevelsCompnumLevelsCompnum_levels_comp = [5,2,4,1].

GreedinessCompGreedinessCompGreedinessCompGreedinessCompgreedinessCompgreediness_comp:

“Greediness” of the search heuristic for the components: value from 0 to 1. Thereby 0 means: safe but slow, 1: fast but matches may be missed.

This parameter has the same meaning as GreedinessGreedinessGreedinessGreedinessgreedinessgreediness in find_shape_modelfind_shape_modelFindShapeModelFindShapeModelFindShapeModelfind_shape_model.

Settable is either one element or the same number of elements as model components in ComponentModelIDComponentModelIDComponentModelIDComponentModelIDcomponentModelIDcomponent_model_id. In the first case the parameter is used for all components. In the second case, each parameter element refers to the corresponding component in ComponentModelIDComponentModelIDComponentModelIDComponentModelIDcomponentModelIDcomponent_model_id.

Further information about output parameters

ModelStartModelStartModelStartModelStartmodelStartmodel_start and ModelEndModelEndModelEndModelEndmodelEndmodel_end:

Return the first and last index and therewith the index range of all component matches associated to the same instance of the component model.

The component matches corresponding to the first found instance of the component model are given by the interval of indices [ModelStartModelStartModelStartModelStartmodelStartmodel_start[0],ModelEndModelEndModelEndModelEndmodelEndmodel_end[0]]. Thereby the indices refer to the values of the parameters RowCompRowCompRowCompRowComprowComprow_comp, ColumnCompColumnCompColumnCompColumnCompcolumnCompcolumn_comp, AngleCompAngleCompAngleCompAngleCompangleCompangle_comp, ScoreCompScoreCompScoreCompScoreCompscoreCompscore_comp, and ModelCompModelCompModelCompModelCompmodelCompmodel_comp.

Example: The component model consists for three components. Two instances have been found on the image, where for one instance only two components (component 0 and component 2) could be found. Then the returned parameters could look like this:
RowCompRowCompRowCompRowComprowComprow_comp = [100,200,300,150,250] ModelStartModelStartModelStartModelStartmodelStartmodel_start = [0,3]
ColumnCompColumnCompColumnCompColumnCompcolumnCompcolumn_comp = [200,210,220,400,425] ModelEndModelEndModelEndModelEndmodelEndmodel_end = [2,4]
AngleCompAngleCompAngleCompAngleCompangleCompangle_comp = [0,0.1,-0.2,0.1,0.2] ModelCompModelCompModelCompModelCompmodelCompmodel_comp = [0,1,2,0,2]
ScoreCompScoreCompScoreCompScoreCompscoreCompscore_comp = [1,1,1,1,1] ScoreScoreScoreScorescorescore = [1,1]
From the right column it is visible, that in the left column:
ScoreScoreScoreScorescorescore:

Score of the found instances of the component model.

ScoreScoreScoreScorescorescore contains the weighted mean of the component scores, the values in ScoreCompScoreCompScoreCompScoreCompscoreCompscore_comp. The weighting is performed according to the number of model points within the respective component.

RowCompRowCompRowCompRowComprowComprow_comp, ColumnCompColumnCompColumnCompColumnCompcolumnCompcolumn_comp, and AngleCompAngleCompAngleCompAngleCompangleCompangle_comp:

The position (RowCompRowCompRowCompRowComprowComprow_comp, ColumnCompColumnCompColumnCompColumnCompcolumnCompcolumn_comp) and rotation (AngleCompAngleCompAngleCompAngleCompangleCompangle_comp) of the model components of all found component model instances.

The coordinates RowCompRowCompRowCompRowComprowComprow_comp and ColumnCompColumnCompColumnCompColumnCompcolumnCompcolumn_comp are the coordinates of the component origin (reference point) in the search image. The component origin depends on the model creation:

Since the relations between the components in ComponentModelIDComponentModelIDComponentModelIDComponentModelIDcomponentModelIDcomponent_model_id refer to this reference point, the origin of the components must not be modified by using set_shape_model_originset_shape_model_originSetShapeModelOriginSetShapeModelOriginSetShapeModelOriginset_shape_model_origin.

ScoreCompScoreCompScoreCompScoreCompscoreCompscore_comp:

Score of each found component instance.

The score is a number between 0 and 1, and is an approximate measure of how much of the component is visible in the image. If, for example, half of the component is occluded, the score cannot exceed 0.5.

ModelCompModelCompModelCompModelCompmodelCompmodel_comp:

Index of the found component.

The tuple contains the indices of the respective model components (see create_component_modelcreate_component_modelCreateComponentModelCreateComponentModelCreateComponentModelcreate_component_model and train_model_componentstrain_model_componentsTrainModelComponentsTrainModelComponentsTrainModelComponentstrain_model_components, respectively). By this the values in RowCompRowCompRowCompRowComprowComprow_comp, ColumnCompColumnCompColumnCompColumnCompcolumnCompcolumn_comp, AngleCompAngleCompAngleCompAngleCompangleCompangle_comp, and ScoreCompScoreCompScoreCompScoreCompscoreCompscore_comp can be associated to the different model components. See also the example given for ModelStartModelStartModelStartModelStartmodelStartmodel_start and ModelEndModelEndModelEndModelEndmodelEndmodel_end.

Information concerning the search

Internally, the shape-based matching is used for the component-based matching in order to search the individual components (see find_shape_modelfind_shape_modelFindShapeModelFindShapeModelFindShapeModelfind_shape_model).

The domain of the ImageImageImageImageimageimage determines the search space for the reference point, i.e., the allowed positions, of the root component.

Usually the component model is searched only within those points of the image domain in which the model fits completely into the image. This means that the components will not be found if they extend beyond the borders of the image, even if they would achieve a score greater than MinScoreCompMinScoreCompMinScoreCompMinScoreCompminScoreCompmin_score_comp (see above).

Note that, if for a certain pyramid level the component 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"), which will cause components that extend beyond the image border to be found if they achieve a score greater than MinScoreCompMinScoreCompMinScoreCompMinScoreCompminScoreCompmin_score_comp. Here, points lying outside the image are regarded as being occluded, i.e., they lower the score. It should be noted that this mode increases the runtime of the search.

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.

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.

Recommendations

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.

To get a meaningful score value and to avoid erroneous matches, we recommend to always combine the allowance of a deformation with a subpixel extraction that applies a least-squares adjustment. If the subpixel extraction and/or the maximum object deformation is specified separately for each component, for each component in ComponentModelIDComponentModelIDComponentModelIDComponentModelIDcomponentModelIDcomponent_model_id exactly one value for the subpixel extraction must be passed in SubPixelCompSubPixelCompSubPixelCompSubPixelCompsubPixelCompsub_pixel_comp. 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 component no value for the maximum object deformation is passed, the component is searched without taking deformations into account. Further details can be found in the documentation of find_shape_modelsfind_shape_modelsFindShapeModelsFindShapeModelsFindShapeModelsfind_shape_models.

Execution Information

Parameters

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

Input image in which the component model should be found.

ComponentModelIDComponentModelIDComponentModelIDComponentModelIDcomponentModelIDcomponent_model_id (input_control)  component_model HComponentModel, HTupleHHandleHTupleHtuple (handle) (IntPtr) (HHandle) (handle)

Handle of the component model.

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

Index of the root component.

Suggested values: 0, 1, 2, 3, 4, 5, 6, 7, 8

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

Smallest rotation of the root component

Default value: -0.39

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

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

Extent of the rotation of the root component.

Default value: 0.79

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

Restriction: AngleExtentRoot >= 0

MinScoreMinScoreMinScoreMinScoreminScoremin_score (input_control)  real HTuplefloatHTupleHtuple (real) (double) (double) (double)

Minimum score of the instances of the component model 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

Minimum increment: 0.01

Recommended increment: 0.05

Restriction: 0 <= MinScore && MinScore <= 1

NumMatchesNumMatchesNumMatchesNumMatchesnumMatchesnum_matches (input_control)  integer HTupleintHTupleHtuple (integer) (int / long) (Hlong) (Hlong)

Number of instances of the component model 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 HTuplefloatHTupleHtuple (real) (double) (double) (double)

Maximum overlap of the instances of the component 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

Minimum increment: 0.01

Recommended increment: 0.05

Restriction: 0 <= MaxOverlap && MaxOverlap <= 1

IfRootNotFoundIfRootNotFoundIfRootNotFoundIfRootNotFoundifRootNotFoundif_root_not_found (input_control)  string HTuplestrHTupleHtuple (string) (string) (HString) (char*)

Behavior if the root component is missing.

Default value: 'stop_search' "stop_search" "stop_search" "stop_search" "stop_search" "stop_search"

List of values: 'select_new_root'"select_new_root""select_new_root""select_new_root""select_new_root""select_new_root", 'stop_search'"stop_search""stop_search""stop_search""stop_search""stop_search"

IfComponentNotFoundIfComponentNotFoundIfComponentNotFoundIfComponentNotFoundifComponentNotFoundif_component_not_found (input_control)  string HTuplestrHTupleHtuple (string) (string) (HString) (char*)

Behavior if a component is missing.

Default value: 'prune_branch' "prune_branch" "prune_branch" "prune_branch" "prune_branch" "prune_branch"

List of values: 'prune_branch'"prune_branch""prune_branch""prune_branch""prune_branch""prune_branch", 'search_from_best'"search_from_best""search_from_best""search_from_best""search_from_best""search_from_best", 'search_from_upper'"search_from_upper""search_from_upper""search_from_upper""search_from_upper""search_from_upper"

PosePredictionPosePredictionPosePredictionPosePredictionposePredictionpose_prediction (input_control)  string HTuplestrHTupleHtuple (string) (string) (HString) (char*)

Pose prediction of components that are not found.

Default value: 'none' "none" "none" "none" "none" "none"

List of values: 'from_all'"from_all""from_all""from_all""from_all""from_all", 'from_neighbors'"from_neighbors""from_neighbors""from_neighbors""from_neighbors""from_neighbors", 'none'"none""none""none""none""none"

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

Minimum score of the instances of the components 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

Minimum increment: 0.01

Recommended increment: 0.05

Restriction: 0 <= MinScoreComp && MinScoreComp <= 1

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

Subpixel accuracy of the component poses 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"

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

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

Default value: 0

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

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

“Greediness” of the search heuristic for the components (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

Minimum increment: 0.01

Recommended increment: 0.05

Restriction: 0 <= GreedinessComp && GreedinessComp <= 1

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

Start index of each found instance of the component model in the tuples describing the component matches.

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

End index of each found instance of the component model in the tuples describing the component matches.

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

Score of the found instances of the component model.

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

Row coordinate of the found component matches.

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

Column coordinate of the found component matches.

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

Rotation angle of the found component matches.

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

Score of the found component matches.

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

Index of the found components.

Result

If the parameter values are correct, the operator find_component_modelfind_component_modelFindComponentModelFindComponentModelFindComponentModelfind_component_model returns the value TRUE. If the input is empty (no input image 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

create_trained_component_modelcreate_trained_component_modelCreateTrainedComponentModelCreateTrainedComponentModelCreateTrainedComponentModelcreate_trained_component_model, create_component_modelcreate_component_modelCreateComponentModelCreateComponentModelCreateComponentModelcreate_component_model, read_component_modelread_component_modelReadComponentModelReadComponentModelReadComponentModelread_component_model

Possible Successors

get_found_component_modelget_found_component_modelGetFoundComponentModelGetFoundComponentModelGetFoundComponentModelget_found_component_model

Alternatives

find_generic_shape_modelfind_generic_shape_modelFindGenericShapeModelFindGenericShapeModelFindGenericShapeModelfind_generic_shape_model

See also

find_shape_modelfind_shape_modelFindShapeModelFindShapeModelFindShapeModelfind_shape_model, find_shape_modelsfind_shape_modelsFindShapeModelsFindShapeModelsFindShapeModelsfind_shape_models, get_shape_model_paramsget_shape_model_paramsGetShapeModelParamsGetShapeModelParamsGetShapeModelParamsget_shape_model_params, get_component_model_paramsget_component_model_paramsGetComponentModelParamsGetComponentModelParamsGetComponentModelParamsget_component_model_params, train_model_componentstrain_model_componentsTrainModelComponentsTrainModelComponentsTrainModelComponentstrain_model_components, set_shape_model_originset_shape_model_originSetShapeModelOriginSetShapeModelOriginSetShapeModelOriginset_shape_model_origin, smallest_rectangle2smallest_rectangle2SmallestRectangle2SmallestRectangle2SmallestRectangle2smallest_rectangle2

Module

Matching