determine_shape_model_paramsT_determine_shape_model_paramsDetermineShapeModelParamsDetermineShapeModelParams (Operator)

Name

determine_shape_model_paramsT_determine_shape_model_paramsDetermineShapeModelParamsDetermineShapeModelParams — Determine the parameters of a shape model.

Signature

Description

determine_shape_model_paramsdetermine_shape_model_paramsDetermineShapeModelParamsDetermineShapeModelParamsDetermineShapeModelParams determines certain parameters of a shape model automatically from the model image TemplateTemplateTemplateTemplatetemplate. The parameters to be determined can be specified with ParametersParametersParametersParametersparameters. determine_shape_model_paramsdetermine_shape_model_paramsDetermineShapeModelParamsDetermineShapeModelParamsDetermineShapeModelParams can be used to determine the same parameters that are determined automatically when the respective parameter in create_shape_modelcreate_shape_modelCreateShapeModelCreateShapeModelCreateShapeModel, create_scaled_shape_modelcreate_scaled_shape_modelCreateScaledShapeModelCreateScaledShapeModelCreateScaledShapeModel, or create_aniso_shape_modelcreate_aniso_shape_modelCreateAnisoShapeModelCreateAnisoShapeModelCreateAnisoShapeModel is set to 'auto'"auto""auto""auto""auto": the number of pyramid levels (ParametersParametersParametersParametersparameters = 'num_levels'"num_levels""num_levels""num_levels""num_levels"), the angle step length (ParametersParametersParametersParametersparameters = 'angle_step'"angle_step""angle_step""angle_step""angle_step"), the scale step length (ParametersParametersParametersParametersparameters = 'scale_step'"scale_step""scale_step""scale_step""scale_step" for isotropic scaling and 'scale_r_step'"scale_r_step""scale_r_step""scale_r_step""scale_r_step" and/or 'scale_c_step'"scale_c_step""scale_c_step""scale_c_step""scale_c_step" for anisotropic scaling), the kind of optimization (ParametersParametersParametersParametersparameters = 'optimization'"optimization""optimization""optimization""optimization"), the threshold (ParametersParametersParametersParametersparameters = 'contrast'"contrast""contrast""contrast""contrast") or the hysteresis thresholds (ParametersParametersParametersParametersparameters = 'contrast_hyst'"contrast_hyst""contrast_hyst""contrast_hyst""contrast_hyst") for the contrast, the minimum size of the object parts (ParametersParametersParametersParametersparameters = 'min_size'"min_size""min_size""min_size""min_size"), and the minimum contrast (ParametersParametersParametersParametersparameters = 'min_contrast'"min_contrast""min_contrast""min_contrast""min_contrast"). By passing a tuple of the above values in ParametersParametersParametersParametersparameters, an arbitrary combination of these parameters can be determined. If all of the above parameters should be determined, the value 'all'"all""all""all""all" can be passed. In this case both hysteresis thresholds are determined, i.e., the operator behaves like passing 'contrast_hyst'"contrast_hyst""contrast_hyst""contrast_hyst""contrast_hyst" instead of 'contrast'"contrast""contrast""contrast""contrast".

determine_shape_model_paramsdetermine_shape_model_paramsDetermineShapeModelParamsDetermineShapeModelParamsDetermineShapeModelParams is mainly useful to determine the above parameters before creating the model, e.g., in an interactive system, which makes suggestions for these parameters to the user, but enables the user to modify the suggested values.

The automatically determined parameters are returned as a name-value pair in ParameterNameParameterNameParameterNameParameterNameparameterName and ParameterValueParameterValueParameterValueParameterValueparameterValue. The parameter names in ParameterNameParameterNameParameterNameParameterNameparameterName are identical to the names in ParametersParametersParametersParametersparameters, where, of course, the value 'all'"all""all""all""all" is replaced by the actual parameter names. An exception is the parameter 'contrast_hyst'"contrast_hyst""contrast_hyst""contrast_hyst""contrast_hyst", for which the two values 'contrast_low'"contrast_low""contrast_low""contrast_low""contrast_low" and 'contrast_high'"contrast_high""contrast_high""contrast_high""contrast_high" are returned.

The remaining parameters (NumLevelsNumLevelsNumLevelsNumLevelsnumLevels, AngleStartAngleStartAngleStartAngleStartangleStart, AngleExtentAngleExtentAngleExtentAngleExtentangleExtent, ScaleMinScaleMinScaleMinScaleMinscaleMin, ScaleMaxScaleMaxScaleMaxScaleMaxscaleMax, OptimizationOptimizationOptimizationOptimizationoptimization, MetricMetricMetricMetricmetric, ContrastContrastContrastContrastcontrast, and MinContrastMinContrastMinContrastMinContrastminContrast) have the same meaning as in create_shape_modelcreate_shape_modelCreateShapeModelCreateShapeModelCreateShapeModel, create_scaled_shape_modelcreate_scaled_shape_modelCreateScaledShapeModelCreateScaledShapeModelCreateScaledShapeModel, and create_aniso_shape_modelcreate_aniso_shape_modelCreateAnisoShapeModelCreateAnisoShapeModelCreateAnisoShapeModel. The description of these parameters can be looked up with these operators. These parameters are used by determine_shape_model_paramsdetermine_shape_model_paramsDetermineShapeModelParamsDetermineShapeModelParamsDetermineShapeModelParams to calculate the parameters to be determined in the same manner as in create_shape_modelcreate_shape_modelCreateShapeModelCreateShapeModelCreateShapeModel, create_scaled_shape_modelcreate_scaled_shape_modelCreateScaledShapeModelCreateScaledShapeModelCreateScaledShapeModel, and create_aniso_shape_modelcreate_aniso_shape_modelCreateAnisoShapeModelCreateAnisoShapeModelCreateAnisoShapeModel. It should be noted that if the parameters of a shape model with isotropic scaling should be determined, i.e., if ParametersParametersParametersParametersparameters contains 'scale_step'"scale_step""scale_step""scale_step""scale_step" either explicitly or implicitly via 'all'"all""all""all""all", the parameters ScaleMinScaleMinScaleMinScaleMinscaleMin and ScaleMaxScaleMaxScaleMaxScaleMaxscaleMax must contain one value each. If the parameters of a shape model with anisotropic scaling should be determined, i.e., if ParametersParametersParametersParametersparameters contains 'scale_r_step'"scale_r_step""scale_r_step""scale_r_step""scale_r_step" or 'scale_c_step'"scale_c_step""scale_c_step""scale_c_step""scale_c_step" either explicitly or implicitly, the parameters ScaleMinScaleMinScaleMinScaleMinscaleMin and ScaleMaxScaleMaxScaleMaxScaleMaxscaleMax must contain two values each. In this case, the first value of the respective parameter refers to the scaling in the row direction, while the second value refers to the scaling in the column direction.

Note that in determine_shape_model_paramsdetermine_shape_model_paramsDetermineShapeModelParamsDetermineShapeModelParamsDetermineShapeModelParams some parameters appear that can also be determined automatically (NumLevelsNumLevelsNumLevelsNumLevelsnumLevels, OptimizationOptimizationOptimizationOptimizationoptimization, ContrastContrastContrastContrastcontrast, MinContrastMinContrastMinContrastMinContrastminContrast). If these parameters should not be determined automatically, i.e., their name is not passed in ParametersParametersParametersParametersparameters, the corresponding parameters must contain valid values and must not be set to 'auto'"auto""auto""auto""auto". In contrast, if these parameters are to be determined automatically, their values are treated in the following way: If the optimization or the (hysteresis) contrast is to be determined automatically, i.e., ParametersParametersParametersParametersparameters contains the value 'optimization'"optimization""optimization""optimization""optimization" or 'contrast'"contrast""contrast""contrast""contrast" ('contrast_hyst'"contrast_hyst""contrast_hyst""contrast_hyst""contrast_hyst"), the values passed in OptimizationOptimizationOptimizationOptimizationoptimization and ContrastContrastContrastContrastcontrast are ignored. In contrast, if the maximum number of pyramid levels or the minimum contrast is to be determined automatically, i.e., ParametersParametersParametersParametersparameters contains the value 'num_levels'"num_levels""num_levels""num_levels""num_levels" or 'min_contrast'"min_contrast""min_contrast""min_contrast""min_contrast", you can let HALCON determine suitable values and at the same time specify an upper or lower boundary, respectively:

If the maximum number of pyramid levels should be specified in advance, NumLevelsNumLevelsNumLevelsNumLevelsnumLevels can be set to the particular value. If in this case ParametersParametersParametersParametersparameters contains the value 'num_levels'"num_levels""num_levels""num_levels""num_levels", the computed number of pyramid levels is at most NumLevelsNumLevelsNumLevelsNumLevelsnumLevels. If NumLevelsNumLevelsNumLevelsNumLevelsnumLevels is set to 'auto'"auto""auto""auto""auto" (or 0 for backwards compatibility), the number of pyramid levels is determined without restrictions as large as possible.

If the minimum contrast should be specified in advance, MinContrastMinContrastMinContrastMinContrastminContrast can be set to the particular value. If in this case ParametersParametersParametersParametersparameters contains the value 'min_contrast'"min_contrast""min_contrast""min_contrast""min_contrast", the computed minimum contrast is at least MinContrastMinContrastMinContrastMinContrastminContrast. If MinContrastMinContrastMinContrastMinContrastminContrast is set to 'auto'"auto""auto""auto""auto", the minimum contrast is determined without restrictions.

Attention

In some cases, the maximum number of pyramid levels that is returned by determine_shape_model_paramsdetermine_shape_model_paramsDetermineShapeModelParamsDetermineShapeModelParamsDetermineShapeModelParams is higher than the number of levels that are actually used in the shape model. The latter can be queried by using get_shape_model_paramsget_shape_model_paramsGetShapeModelParamsGetShapeModelParamsGetShapeModelParams after creating the model. This might happen if the model is created by using create_scaled_shape_modelcreate_scaled_shape_modelCreateScaledShapeModelCreateScaledShapeModelCreateScaledShapeModel or create_aniso_shape_modelcreate_aniso_shape_modelCreateAnisoShapeModelCreateAnisoShapeModelCreateAnisoShapeModel and ScaleMin, ScaleRMin, or ScaleCMin is below 1.0.

Execution Information

• Multithreading type: reentrant (runs in parallel with non-exclusive operators).
• Multithreading scope: global (may be called from any thread).
• Processed without parallelization.

Parameters

Result

If the parameters are valid, the operator determine_shape_model_paramsdetermine_shape_model_paramsDetermineShapeModelParamsDetermineShapeModelParamsDetermineShapeModelParams returns the value 2 (H_MSG_TRUE). If necessary an exception is raised. If the parameters NumLevelsNumLevelsNumLevelsNumLevelsnumLevels and ContrastContrastContrastContrastcontrast are chosen such that the model contains too few points, or the input image does not contain a sufficient number of significant features, the error 8510 is raised.

Possible Predecessors

draw_regiondraw_regionDrawRegionDrawRegionDrawRegion, reduce_domainreduce_domainReduceDomainReduceDomainReduceDomain, thresholdthresholdThresholdThresholdThreshold

Possible Successors

create_shape_modelcreate_shape_modelCreateShapeModelCreateShapeModelCreateShapeModel, create_scaled_shape_modelcreate_scaled_shape_modelCreateScaledShapeModelCreateScaledShapeModelCreateScaledShapeModel, create_aniso_shape_modelcreate_aniso_shape_modelCreateAnisoShapeModelCreateAnisoShapeModelCreateAnisoShapeModel

See also

find_shape_modelfind_shape_modelFindShapeModelFindShapeModelFindShapeModel, find_scaled_shape_modelfind_scaled_shape_modelFindScaledShapeModelFindScaledShapeModelFindScaledShapeModel, find_aniso_shape_modelfind_aniso_shape_modelFindAnisoShapeModelFindAnisoShapeModelFindAnisoShapeModel, find_shape_modelsfind_shape_modelsFindShapeModelsFindShapeModelsFindShapeModels, find_scaled_shape_modelsfind_scaled_shape_modelsFindScaledShapeModelsFindScaledShapeModelsFindScaledShapeModels, find_aniso_shape_modelsfind_aniso_shape_modelsFindAnisoShapeModelsFindAnisoShapeModelsFindAnisoShapeModels

Module

Matching