create_trained_component_modelT_create_trained_component_modelCreateTrainedComponentModelCreateTrainedComponentModelcreate_trained_component_model (Operator)

Name

create_trained_component_modelT_create_trained_component_modelCreateTrainedComponentModelCreateTrainedComponentModelcreate_trained_component_model — Prepare a component model for matching based on trained components.

Signature

create_trained_component_model( : : ComponentTrainingID, AngleStart, AngleExtent, MinContrastComp, MinScoreComp, NumLevelsComp, AngleStepComp, OptimizationComp, MetricComp, PregenerationComp : ComponentModelID, RootRanking)

Herror T_create_trained_component_model(const Htuple ComponentTrainingID, const Htuple AngleStart, const Htuple AngleExtent, const Htuple MinContrastComp, const Htuple MinScoreComp, const Htuple NumLevelsComp, const Htuple AngleStepComp, const Htuple OptimizationComp, const Htuple MetricComp, const Htuple PregenerationComp, Htuple* ComponentModelID, Htuple* RootRanking)

void CreateTrainedComponentModel(const HTuple& ComponentTrainingID, const HTuple& AngleStart, const HTuple& AngleExtent, const HTuple& MinContrastComp, const HTuple& MinScoreComp, const HTuple& NumLevelsComp, const HTuple& AngleStepComp, const HTuple& OptimizationComp, const HTuple& MetricComp, const HTuple& PregenerationComp, HTuple* ComponentModelID, HTuple* RootRanking)

HComponentModel HComponentTraining::CreateTrainedComponentModel(double AngleStart, double AngleExtent, const HTuple& MinContrastComp, const HTuple& MinScoreComp, const HTuple& NumLevelsComp, const HTuple& AngleStepComp, const HString& OptimizationComp, const HTuple& MetricComp, const HTuple& PregenerationComp, HTuple* RootRanking) const

HComponentModel HComponentTraining::CreateTrainedComponentModel(double AngleStart, double AngleExtent, Hlong MinContrastComp, double MinScoreComp, Hlong NumLevelsComp, double AngleStepComp, const HString& OptimizationComp, const HString& MetricComp, const HString& PregenerationComp, Hlong* RootRanking) const

HComponentModel HComponentTraining::CreateTrainedComponentModel(double AngleStart, double AngleExtent, Hlong MinContrastComp, double MinScoreComp, Hlong NumLevelsComp, double AngleStepComp, const char* OptimizationComp, const char* MetricComp, const char* PregenerationComp, Hlong* RootRanking) const

HComponentModel HComponentTraining::CreateTrainedComponentModel(double AngleStart, double AngleExtent, Hlong MinContrastComp, double MinScoreComp, Hlong NumLevelsComp, double AngleStepComp, const wchar_t* OptimizationComp, const wchar_t* MetricComp, const wchar_t* PregenerationComp, Hlong* RootRanking) const   (Windows only)

void HComponentModel::HComponentModel(const HComponentTraining& ComponentTrainingID, double AngleStart, double AngleExtent, const HTuple& MinContrastComp, const HTuple& MinScoreComp, const HTuple& NumLevelsComp, const HTuple& AngleStepComp, const HString& OptimizationComp, const HTuple& MetricComp, const HTuple& PregenerationComp, HTuple* RootRanking)

void HComponentModel::HComponentModel(const HComponentTraining& ComponentTrainingID, double AngleStart, double AngleExtent, Hlong MinContrastComp, double MinScoreComp, Hlong NumLevelsComp, double AngleStepComp, const HString& OptimizationComp, const HString& MetricComp, const HString& PregenerationComp, Hlong* RootRanking)

void HComponentModel::HComponentModel(const HComponentTraining& ComponentTrainingID, double AngleStart, double AngleExtent, Hlong MinContrastComp, double MinScoreComp, Hlong NumLevelsComp, double AngleStepComp, const char* OptimizationComp, const char* MetricComp, const char* PregenerationComp, Hlong* RootRanking)

void HComponentModel::HComponentModel(const HComponentTraining& ComponentTrainingID, double AngleStart, double AngleExtent, Hlong MinContrastComp, double MinScoreComp, Hlong NumLevelsComp, double AngleStepComp, const wchar_t* OptimizationComp, const wchar_t* MetricComp, const wchar_t* PregenerationComp, Hlong* RootRanking)   (Windows only)

HTuple HComponentModel::CreateTrainedComponentModel(const HComponentTraining& ComponentTrainingID, double AngleStart, double AngleExtent, const HTuple& MinContrastComp, const HTuple& MinScoreComp, const HTuple& NumLevelsComp, const HTuple& AngleStepComp, const HString& OptimizationComp, const HTuple& MetricComp, const HTuple& PregenerationComp)

Hlong HComponentModel::CreateTrainedComponentModel(const HComponentTraining& ComponentTrainingID, double AngleStart, double AngleExtent, Hlong MinContrastComp, double MinScoreComp, Hlong NumLevelsComp, double AngleStepComp, const HString& OptimizationComp, const HString& MetricComp, const HString& PregenerationComp)

Hlong HComponentModel::CreateTrainedComponentModel(const HComponentTraining& ComponentTrainingID, double AngleStart, double AngleExtent, Hlong MinContrastComp, double MinScoreComp, Hlong NumLevelsComp, double AngleStepComp, const char* OptimizationComp, const char* MetricComp, const char* PregenerationComp)

Hlong HComponentModel::CreateTrainedComponentModel(const HComponentTraining& ComponentTrainingID, double AngleStart, double AngleExtent, Hlong MinContrastComp, double MinScoreComp, Hlong NumLevelsComp, double AngleStepComp, const wchar_t* OptimizationComp, const wchar_t* MetricComp, const wchar_t* PregenerationComp)   (Windows only)

static void HOperatorSet.CreateTrainedComponentModel(HTuple componentTrainingID, HTuple angleStart, HTuple angleExtent, HTuple minContrastComp, HTuple minScoreComp, HTuple numLevelsComp, HTuple angleStepComp, HTuple optimizationComp, HTuple metricComp, HTuple pregenerationComp, out HTuple componentModelID, out HTuple rootRanking)

HComponentModel HComponentTraining.CreateTrainedComponentModel(double angleStart, double angleExtent, HTuple minContrastComp, HTuple minScoreComp, HTuple numLevelsComp, HTuple angleStepComp, string optimizationComp, HTuple metricComp, HTuple pregenerationComp, out HTuple rootRanking)

HComponentModel HComponentTraining.CreateTrainedComponentModel(double angleStart, double angleExtent, int minContrastComp, double minScoreComp, int numLevelsComp, double angleStepComp, string optimizationComp, string metricComp, string pregenerationComp, out int rootRanking)

public HComponentModel(HComponentTraining componentTrainingID, double angleStart, double angleExtent, HTuple minContrastComp, HTuple minScoreComp, HTuple numLevelsComp, HTuple angleStepComp, string optimizationComp, HTuple metricComp, HTuple pregenerationComp, out HTuple rootRanking)

public HComponentModel(HComponentTraining componentTrainingID, double angleStart, double angleExtent, int minContrastComp, double minScoreComp, int numLevelsComp, double angleStepComp, string optimizationComp, string metricComp, string pregenerationComp, out int rootRanking)

HTuple HComponentModel.CreateTrainedComponentModel(HComponentTraining componentTrainingID, double angleStart, double angleExtent, HTuple minContrastComp, HTuple minScoreComp, HTuple numLevelsComp, HTuple angleStepComp, string optimizationComp, HTuple metricComp, HTuple pregenerationComp)

int HComponentModel.CreateTrainedComponentModel(HComponentTraining componentTrainingID, double angleStart, double angleExtent, int minContrastComp, double minScoreComp, int numLevelsComp, double angleStepComp, string optimizationComp, string metricComp, string pregenerationComp)

def create_trained_component_model(component_training_id: HHandle, angle_start: float, angle_extent: float, min_contrast_comp: MaybeSequence[Union[int, str]], min_score_comp: MaybeSequence[float], num_levels_comp: MaybeSequence[Union[int, str]], angle_step_comp: MaybeSequence[Union[float, str]], optimization_comp: str, metric_comp: MaybeSequence[str], pregeneration_comp: MaybeSequence[str]) -> Tuple[HHandle, Sequence[int]]

def create_trained_component_model_s(component_training_id: HHandle, angle_start: float, angle_extent: float, min_contrast_comp: MaybeSequence[Union[int, str]], min_score_comp: MaybeSequence[float], num_levels_comp: MaybeSequence[Union[int, str]], angle_step_comp: MaybeSequence[Union[float, str]], optimization_comp: str, metric_comp: MaybeSequence[str], pregeneration_comp: MaybeSequence[str]) -> Tuple[HHandle, int]

Description

create_trained_component_modelcreate_trained_component_modelCreateTrainedComponentModelCreateTrainedComponentModelCreateTrainedComponentModelcreate_trained_component_model prepares the training result, which is passed in ComponentTrainingIDComponentTrainingIDComponentTrainingIDComponentTrainingIDcomponentTrainingIDcomponent_training_id, as a component model for matching. The output parameter ComponentModelIDComponentModelIDComponentModelIDComponentModelIDcomponentModelIDcomponent_model_id is a handle for this model, which is used in subsequent calls to find_component_modelfind_component_modelFindComponentModelFindComponentModelFindComponentModelfind_component_model. In contrast to create_component_modelcreate_component_modelCreateComponentModelCreateComponentModelCreateComponentModelcreate_component_model, the model components must have been previously trained using train_model_componentstrain_model_componentsTrainModelComponentsTrainModelComponentsTrainModelComponentstrain_model_components before calling create_trained_component_modelcreate_trained_component_modelCreateTrainedComponentModelCreateTrainedComponentModelCreateTrainedComponentModelcreate_trained_component_model.

The parameters AngleStartAngleStartAngleStartAngleStartangleStartangle_start and AngleExtentAngleExtentAngleExtentAngleExtentangleExtentangle_extent determine the range of possible rotations of the component model in an image.

Internally, a separate shape model is built for each model component (see create_shape_modelcreate_shape_modelCreateShapeModelCreateShapeModelCreateShapeModelcreate_shape_model). Therefore, the parameters MinContrastCompMinContrastCompMinContrastCompMinContrastCompminContrastCompmin_contrast_comp, MinScoreCompMinScoreCompMinScoreCompMinScoreCompminScoreCompmin_score_comp, NumLevelsCompNumLevelsCompNumLevelsCompNumLevelsCompnumLevelsCompnum_levels_comp, AngleStepCompAngleStepCompAngleStepCompAngleStepCompangleStepCompangle_step_comp, OptimizationCompOptimizationCompOptimizationCompOptimizationCompoptimizationCompoptimization_comp, MetricCompMetricCompMetricCompMetricCompmetricCompmetric_comp, and PregenerationCompPregenerationCompPregenerationCompPregenerationComppregenerationComppregeneration_comp correspond to the parameters of create_shape_modelcreate_shape_modelCreateShapeModelCreateShapeModelCreateShapeModelcreate_shape_model, with the following differences: First, the parameter OptimizationOptimizationOptimizationOptimizationoptimizationoptimization of create_shape_modelcreate_shape_modelCreateShapeModelCreateShapeModelCreateShapeModelcreate_shape_model provides the possibility to reduce the number of model points as well as the possibility to completely pregenerate the shape model. In contrast, the operator create_trained_component_modelcreate_trained_component_modelCreateTrainedComponentModelCreateTrainedComponentModelCreateTrainedComponentModelcreate_trained_component_model uses a separate parameter PregenerationCompPregenerationCompPregenerationCompPregenerationComppregenerationComppregeneration_comp in order to decide whether the shape models should be completely pregenerated or not. A second difference concerning the parameter MinScoreCompMinScoreCompMinScoreCompMinScoreCompminScoreCompmin_score_comp should be noted. When using the shape-based matching, this parameter needs not be passed when preparing the shape model using create_shape_modelcreate_shape_modelCreateShapeModelCreateShapeModelCreateShapeModelcreate_shape_model but only during the search using find_shape_modelfind_shape_modelFindShapeModelFindShapeModelFindShapeModelfind_shape_model. In contrast, when preparing the component model it is favorable to analyze rotational symmetries of the model components and similarities between the model components. However, this analysis only leads to meaningful results if the value for MinScoreCompMinScoreCompMinScoreCompMinScoreCompminScoreCompmin_score_comp that is used during the search (see find_component_modelfind_component_modelFindComponentModelFindComponentModelFindComponentModelfind_component_model) is already approximately known. After the search with find_component_modelfind_component_modelFindComponentModelFindComponentModelFindComponentModelfind_component_model the pose parameters of the components in a search image are returned. Note that the pose parameters refer to the reference points of the components. The reference point of a component is the center of gravity of its associated region that is returned in ModelComponentsModelComponentsModelComponentsModelComponentsmodelComponentsmodel_components of train_model_componentstrain_model_componentsTrainModelComponentsTrainModelComponentsTrainModelComponentstrain_model_components.

The parameters MinContrastCompMinContrastCompMinContrastCompMinContrastCompminContrastCompmin_contrast_comp, NumLevelsCompNumLevelsCompNumLevelsCompNumLevelsCompnumLevelsCompnum_levels_comp, AngleStepCompAngleStepCompAngleStepCompAngleStepCompangleStepCompangle_step_comp, and OptimizationCompOptimizationCompOptimizationCompOptimizationCompoptimizationCompoptimization_comp can be automatically determined by passing 'auto'"auto""auto""auto""auto""auto" for the respective parameters.

All component-specific input parameters (parameter names terminate with the suffix Comp) must either contain one element, in which case the parameter is used for all model components, or must contain the same number of elements as the number of model components contained in ComponentTrainingIDComponentTrainingIDComponentTrainingIDComponentTrainingIDcomponentTrainingIDcomponent_training_id, in which case each parameter element refers to the corresponding component in ComponentTrainingIDComponentTrainingIDComponentTrainingIDComponentTrainingIDcomponentTrainingIDcomponent_training_id.

In addition to the individual shape models, the component model also contains information about the way the single model components must be searched relative to each other using find_component_modelfind_component_modelFindComponentModelFindComponentModelFindComponentModelfind_component_model in order to minimize the computation time of the search. For this, the components are represented in a tree structure. First, the component that stands at the root of this search tree (root component) is searched. Then, the remaining components are searched relative to the pose of their predecessor in the search tree.

The root component can be passed as an input parameter of find_component_modelfind_component_modelFindComponentModelFindComponentModelFindComponentModelfind_component_model during the 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. Additionally, the computation time that is associated with the root component during the search can serve as a criterion. A ranking of the model components that is based on the latter criterion is returned in RootRankingRootRankingRootRankingRootRankingrootRankingroot_ranking. In this parameter the indices of the model components are sorted in descending order according to their associated computation time, i.e., RootRankingRootRankingRootRankingRootRankingrootRankingroot_ranking[0] contains the index of the model component that, chosen as root component, allows the fastest search. Note that the ranking returned in RootRankingRootRankingRootRankingRootRankingrootRankingroot_ranking represents only a coarse estimation. Furthermore, the calculation of the root ranking assumes that the image size as well as the value of the system parameter 'border_shape_models'"border_shape_models""border_shape_models""border_shape_models""border_shape_models""border_shape_models" are identical when calling create_trained_component_modelcreate_trained_component_modelCreateTrainedComponentModelCreateTrainedComponentModelCreateTrainedComponentModelcreate_trained_component_model and find_component_modelfind_component_modelFindComponentModelFindComponentModelFindComponentModelfind_component_model.

Execution Information

This operator returns a handle. Note that the state of an instance of this handle type may be changed by specific operators even though the handle is used as an input parameter by those operators.

Parameters

ComponentTrainingIDComponentTrainingIDComponentTrainingIDComponentTrainingIDcomponentTrainingIDcomponent_training_id (input_control)  component_training HComponentTraining, HTupleHHandleHTupleHtuple (handle) (IntPtr) (HHandle) (handle)

Handle of the training result.

AngleStartAngleStartAngleStartAngleStartangleStartangle_start (input_control)  angle.rad HTuplefloatHTupleHtuple (real) (double) (double) (double)

Smallest rotation of the component model.

Default value: -0.39

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

AngleExtentAngleExtentAngleExtentAngleExtentangleExtentangle_extent (input_control)  angle.rad HTuplefloatHTupleHtuple (real) (double) (double) (double)

Extent of the rotation of the component model.

Default value: 0.79

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

Restriction: AngleExtent >= 0

MinContrastCompMinContrastCompMinContrastCompMinContrastCompminContrastCompmin_contrast_comp (input_control)  integer(-array) HTupleMaybeSequence[Union[int, str]]HTupleHtuple (integer / string) (int / long / string) (Hlong / HString) (Hlong / char*)

Minimum contrast of the components in the search images.

Default value: 'auto' "auto" "auto" "auto" "auto" "auto"

Suggested values: 'auto'"auto""auto""auto""auto""auto", 10, 20, 20, 40

Restriction: MinContrastComp >= 0

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

NumLevelsCompNumLevelsCompNumLevelsCompNumLevelsCompnumLevelsCompnum_levels_comp (input_control)  integer(-array) HTupleMaybeSequence[Union[int, str]]HTupleHtuple (integer / string) (int / long / string) (Hlong / HString) (Hlong / char*)

Maximum number of pyramid levels for the components.

Default value: 'auto' "auto" "auto" "auto" "auto" "auto"

List of values: 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 'auto'"auto""auto""auto""auto""auto"

AngleStepCompAngleStepCompAngleStepCompAngleStepCompangleStepCompangle_step_comp (input_control)  angle.rad(-array) HTupleMaybeSequence[Union[float, str]]HTupleHtuple (real / string) (double / string) (double / HString) (double / char*)

Step length of the angles (resolution) for the components.

Default value: 'auto' "auto" "auto" "auto" "auto" "auto"

Suggested values: 'auto'"auto""auto""auto""auto""auto", 0.0175, 0.0349, 0.0524, 0.0698, 0.0873

Restriction: AngleStepComp >= 0

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

Kind of optimization for the components.

Default value: 'auto' "auto" "auto" "auto" "auto" "auto"

List of values: 'auto'"auto""auto""auto""auto""auto", 'none'"none""none""none""none""none", 'point_reduction_high'"point_reduction_high""point_reduction_high""point_reduction_high""point_reduction_high""point_reduction_high", 'point_reduction_low'"point_reduction_low""point_reduction_low""point_reduction_low""point_reduction_low""point_reduction_low", 'point_reduction_medium'"point_reduction_medium""point_reduction_medium""point_reduction_medium""point_reduction_medium""point_reduction_medium"

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

Match metric used for the components.

Default value: 'use_polarity' "use_polarity" "use_polarity" "use_polarity" "use_polarity" "use_polarity"

List of values: 'ignore_color_polarity'"ignore_color_polarity""ignore_color_polarity""ignore_color_polarity""ignore_color_polarity""ignore_color_polarity", 'ignore_global_polarity'"ignore_global_polarity""ignore_global_polarity""ignore_global_polarity""ignore_global_polarity""ignore_global_polarity", 'ignore_local_polarity'"ignore_local_polarity""ignore_local_polarity""ignore_local_polarity""ignore_local_polarity""ignore_local_polarity", 'use_polarity'"use_polarity""use_polarity""use_polarity""use_polarity""use_polarity"

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

Complete pregeneration of the shape models for the components if equal to 'true'"true""true""true""true""true".

Default value: 'false' "false" "false" "false" "false" "false"

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

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

Handle of the component model.

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

Ranking of the model components expressing the suitability to act as the root component.

Example (HDevelop)

* Get the model image.
read_image (ModelImage, 'model_image.tif')
* Define the regions for the initial components.
gen_rectangle2 (InitialComponentRegions, 212, 233, 0.62, 167, 29)
gen_rectangle2 (Rectangle2, 298, 363, 1.17, 162, 34)
gen_rectangle2 (Rectangle3, 63, 444, -0.26, 50, 27)
gen_rectangle2 (Rectangle4, 120, 473, 0, 33, 20)
concat_obj (InitialComponentRegions, Rectangle2, InitialComponentRegions)
concat_obj (InitialComponentRegions, Rectangle3, InitialComponentRegions)
concat_obj (InitialComponentRegions, Rectangle4, InitialComponentRegions)
* Get the training images.
gen_empty_obj (TrainingImages)
for i := 1 to 4 by 1
    read_image (TrainingImage, 'training_image-'+i+'.tif')
    concat_obj (TrainingImages, TrainingImage, TrainingImages)
endfor
* Extract the model components and train the relations.
train_model_components (ModelImage, InitialComponentRegions, \
                        TrainingImages, ModelComponents, 22, 60, 30, 0.65, \
                        0, 0, rad(60), 'speed', 'rigidity', 0.2, 0.4, \
                        ComponentTrainingID)
* Create the component model based on the training result.
create_trained_component_model (ComponentTrainingID, -rad(30), rad(60), 10, \
                                0.5, 'auto', 'auto', 'none', \
                                'use_polarity', 'false', ComponentModelID, \
                                RootRanking)
* Find the component model in a run-time image.
read_image (SearchImage, 'search_image.tif')
find_component_model (SearchImage, ComponentModelID, RootRanking, -rad(30), \
                      rad(60), 0.5, 0, 0.5, 'stop_search', 'prune_branch', \
                      'none', 0.55, 'least_squares', 0, 0.9, ModelStart, \
                      ModelEnd, Score, RowComp, ColumnComp, AngleComp, \
                      ScoreComp, ModelComp)

Result

If the parameters are valid, the operator create_trained_component_modelcreate_trained_component_modelCreateTrainedComponentModelCreateTrainedComponentModelCreateTrainedComponentModelcreate_trained_component_model returns the value TRUE. If necessary an exception is raised.

Possible Predecessors

train_model_componentstrain_model_componentsTrainModelComponentsTrainModelComponentsTrainModelComponentstrain_model_components, read_training_componentsread_training_componentsReadTrainingComponentsReadTrainingComponentsReadTrainingComponentsread_training_components

Possible Successors

find_component_modelfind_component_modelFindComponentModelFindComponentModelFindComponentModelfind_component_model

Alternatives

create_component_modelcreate_component_modelCreateComponentModelCreateComponentModelCreateComponentModelcreate_component_model

See also

create_shape_modelcreate_shape_modelCreateShapeModelCreateShapeModelCreateShapeModelcreate_shape_model, find_shape_modelfind_shape_modelFindShapeModelFindShapeModelFindShapeModelfind_shape_model

Module

Matching