gen_initial_componentsgen_initial_componentsGenInitialComponentsGenInitialComponentsgen_initial_components (Operator)

Name

gen_initial_componentsgen_initial_componentsGenInitialComponentsGenInitialComponentsgen_initial_components — Extract the initial components of a component model.

Signature

gen_initial_components(ModelImage : InitialComponents : ContrastLow, ContrastHigh, MinSize, Mode, GenericName, GenericValue : )

Herror gen_initial_components(const Hobject ModelImage, Hobject* InitialComponents, const Hlong ContrastLow, const Hlong ContrastHigh, const Hlong MinSize, const char* Mode, const char* GenericName, double GenericValue)

Herror T_gen_initial_components(const Hobject ModelImage, Hobject* InitialComponents, const Htuple ContrastLow, const Htuple ContrastHigh, const Htuple MinSize, const Htuple Mode, const Htuple GenericName, const Htuple GenericValue)

void GenInitialComponents(const HObject& ModelImage, HObject* InitialComponents, const HTuple& ContrastLow, const HTuple& ContrastHigh, const HTuple& MinSize, const HTuple& Mode, const HTuple& GenericName, const HTuple& GenericValue)

HRegion HImage::GenInitialComponents(const HTuple& ContrastLow, const HTuple& ContrastHigh, const HTuple& MinSize, const HString& Mode, const HTuple& GenericName, const HTuple& GenericValue) const

HRegion HImage::GenInitialComponents(Hlong ContrastLow, Hlong ContrastHigh, Hlong MinSize, const HString& Mode, const HString& GenericName, double GenericValue) const

HRegion HImage::GenInitialComponents(Hlong ContrastLow, Hlong ContrastHigh, Hlong MinSize, const char* Mode, const char* GenericName, double GenericValue) const

HRegion HImage::GenInitialComponents(Hlong ContrastLow, Hlong ContrastHigh, Hlong MinSize, const wchar_t* Mode, const wchar_t* GenericName, double GenericValue) const   (Windows only)

static void HOperatorSet.GenInitialComponents(HObject modelImage, out HObject initialComponents, HTuple contrastLow, HTuple contrastHigh, HTuple minSize, HTuple mode, HTuple genericName, HTuple genericValue)

HRegion HImage.GenInitialComponents(HTuple contrastLow, HTuple contrastHigh, HTuple minSize, string mode, HTuple genericName, HTuple genericValue)

HRegion HImage.GenInitialComponents(int contrastLow, int contrastHigh, int minSize, string mode, string genericName, double genericValue)

def gen_initial_components(model_image: HObject, contrast_low: MaybeSequence[Union[int, str]], contrast_high: MaybeSequence[Union[int, str]], min_size: MaybeSequence[Union[int, str]], mode: str, generic_name: MaybeSequence[str], generic_value: MaybeSequence[Union[int, float]]) -> HObject

Description

In general, there are two possibilities to use gen_initial_componentsgen_initial_componentsGenInitialComponentsGenInitialComponentsGenInitialComponentsgen_initial_components. The first possibility should be chosen if the components of the component model are not known. Then gen_initial_componentsgen_initial_componentsGenInitialComponentsGenInitialComponentsGenInitialComponentsgen_initial_components automatically extracts the initial components of a component model from a model image. The second possibility can be chosen if the components of the component model are approximately known. Then gen_initial_componentsgen_initial_componentsGenInitialComponentsGenInitialComponentsGenInitialComponentsgen_initial_components can be used to find suitable parameter values for the model feature extraction in train_model_componentstrain_model_componentsTrainModelComponentsTrainModelComponentsTrainModelComponentstrain_model_components and create_component_modelcreate_component_modelCreateComponentModelCreateComponentModelCreateComponentModelcreate_component_model. Hence, the second possibility is comparable to the function of inspect_shape_modelinspect_shape_modelInspectShapeModelInspectShapeModelInspectShapeModelinspect_shape_model within the shape-based matching.

When using the first possibility, gen_initial_componentsgen_initial_componentsGenInitialComponentsGenInitialComponentsGenInitialComponentsgen_initial_components extracts the initial components of a component model from a model image ModelImageModelImageModelImageModelImagemodelImagemodel_image. As already mentioned, this is especially useful if the components of the component model are not known. In this case, the resulting initial components can be used to automatically train the component model with train_model_componentstrain_model_componentsTrainModelComponentsTrainModelComponentsTrainModelComponentstrain_model_components, which extracts the (final) model components and the relations between them. gen_initial_componentsgen_initial_componentsGenInitialComponentsGenInitialComponentsGenInitialComponentsgen_initial_components returns the initial components in a region object tuple InitialComponentsInitialComponentsInitialComponentsInitialComponentsinitialComponentsinitial_components that contains a representation for each initial component in form of contour regions.

For the automatic determination of the initial components, the domain of the model image ModelImageModelImageModelImageModelImagemodelImagemodel_image must contain the entire compound object including all components. ModeModeModeModemodemode specifies the method used for the automatic computation. Currently, only the mode 'connection'"connection""connection""connection""connection""connection" is available. In this mode the automatic computation is performed in two steps: In the first step, features are extracted using the parameters ContrastLowContrastLowContrastLowContrastLowcontrastLowcontrast_low, ContrastHighContrastHighContrastHighContrastHighcontrastHighcontrast_high, and MinSizeMinSizeMinSizeMinSizeminSizemin_size. These three parameters define the contours of which the initial components should consist and should be chosen such that only the significant features of the model image are contained in the initial components. ContrastLowContrastLowContrastLowContrastLowcontrastLowcontrast_low and ContrastHighContrastHighContrastHighContrastHighcontrastHighcontrast_high specify the gray value contrast of the points that should be contained in the initial components. The contrast is a measure for local gray value differences between the object and the background and between different parts of the object. The model image is segmented using a method similar to the hysteresis threshold method used in edges_imageedges_imageEdgesImageEdgesImageEdgesImageedges_image. Here, ContrastLowContrastLowContrastLowContrastLowcontrastLowcontrast_low determines the lower threshold, while ContrastHighContrastHighContrastHighContrastHighcontrastHighcontrast_high determines the upper threshold. If the same value is passed for ContrastLowContrastLowContrastLowContrastLowcontrastLowcontrast_low and ContrastHighContrastHighContrastHighContrastHighcontrastHighcontrast_high a simple thresholding operation is performed. For more information about the hysteresis threshold method, see hysteresis_thresholdhysteresis_thresholdHysteresisThresholdHysteresisThresholdHysteresisThresholdhysteresis_threshold. MinSizeMinSizeMinSizeMinSizeminSizemin_size can be used to select only significant features for the initial components based on the size of the connected contour regions, i.e., connected contour regions with fewer than MinSizeMinSizeMinSizeMinSizeminSizemin_size points are suppressed.

The resulting connected contour regions are iteratively merged in the second step. For this, two contour regions are merged if the distance between both regions is smaller than a certain threshold (see below). Finally, the merged regions are returned in InitialComponentsInitialComponentsInitialComponentsInitialComponentsinitialComponentsinitial_components and can be used to train the component model by passing them to train_model_componentstrain_model_componentsTrainModelComponentsTrainModelComponentsTrainModelComponentstrain_model_components.

To control the internal image processing, the parameters GenericNameGenericNameGenericNameGenericNamegenericNamegeneric_name and GenericValueGenericValueGenericValueGenericValuegenericValuegeneric_value are used. This is done by passing the names of the control parameters to be changed in GenericNameGenericNameGenericNameGenericNamegenericNamegeneric_name as a list of strings. In GenericValueGenericValueGenericValueGenericValuegenericValuegeneric_value the values are passed at the corresponding index positions.

Normally, none of the values needs to be changed. A change should only be applied in case of unsatisfying results of the automatic determination of the initial components. The two parameters that can be changed are 'merge_distance'"merge_distance""merge_distance""merge_distance""merge_distance""merge_distance" and 'merge_fraction'"merge_fraction""merge_fraction""merge_fraction""merge_fraction""merge_fraction"; both are used during the iterative merging of contour regions (see above). First, the fraction of contour pixels of one contour region that at most have a distance of 'merge_distance'"merge_distance""merge_distance""merge_distance""merge_distance""merge_distance" from another contour region is computed. If this fraction exceeds the value that is passed in 'merge_fraction'"merge_fraction""merge_fraction""merge_fraction""merge_fraction""merge_fraction" the two contour regions are merged. Consequently, the higher 'merge_distance'"merge_distance""merge_distance""merge_distance""merge_distance""merge_distance" and the lower 'merge_fraction'"merge_fraction""merge_fraction""merge_fraction""merge_fraction""merge_fraction" is chosen the more contour regions are merged. The default value of 'merge_distance'"merge_distance""merge_distance""merge_distance""merge_distance""merge_distance" is 5 and the default value of 'merge_fraction'"merge_fraction""merge_fraction""merge_fraction""merge_fraction""merge_fraction" is 0.5 (corresponds to 50 percent).

When using the second possibility, i.e., the components of the component model are approximately known, the training by using train_model_componentstrain_model_componentsTrainModelComponentsTrainModelComponentsTrainModelComponentstrain_model_components can be performed without previously executing gen_initial_componentsgen_initial_componentsGenInitialComponentsGenInitialComponentsGenInitialComponentsgen_initial_components. If this is desired, the initial components can be specified by the user and directly passed to train_model_componentstrain_model_componentsTrainModelComponentsTrainModelComponentsTrainModelComponentstrain_model_components. Furthermore, if the components as well as the relative movements (relations) of the components are known, gen_initial_componentsgen_initial_componentsGenInitialComponentsGenInitialComponentsGenInitialComponentsgen_initial_components as well as train_model_componentstrain_model_componentsTrainModelComponentsTrainModelComponentsTrainModelComponentstrain_model_components need not be executed. In fact, by immediately passing the components as well as the relations to create_component_modelcreate_component_modelCreateComponentModelCreateComponentModelCreateComponentModelcreate_component_model, the component model can be created without any training. In both cases, however, gen_initial_componentsgen_initial_componentsGenInitialComponentsGenInitialComponentsGenInitialComponentsgen_initial_components can be used to evaluate the effect of the feature extraction parameters ContrastLowContrastLowContrastLowContrastLowcontrastLowcontrast_low, ContrastHighContrastHighContrastHighContrastHighcontrastHighcontrast_high, and MinSizeMinSizeMinSizeMinSizeminSizemin_size of train_model_componentstrain_model_componentsTrainModelComponentsTrainModelComponentsTrainModelComponentstrain_model_components and create_component_modelcreate_component_modelCreateComponentModelCreateComponentModelCreateComponentModelcreate_component_model, and hence to find suitable parameter values for a certain application.

For this, the image regions for the (initial) components must be explicitly given, i.e., for each (initial) component a separate image from which the (initial) component should be created is passed. In this case, ModelImageModelImageModelImageModelImagemodelImagemodel_image contains multiple image objects. The domain of each image object is used as the region of interest for calculating the corresponding (initial) component. The image matrix of all image objects in the tuple must be identical, i.e., ModelImageModelImageModelImageModelImagemodelImagemodel_image 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. If the parameters ContrastLowContrastLowContrastLowContrastLowcontrastLowcontrast_low, ContrastHighContrastHighContrastHighContrastHighcontrastHighcontrast_high, or MinSizeMinSizeMinSizeMinSizeminSizemin_size only contain one element, this value is applied to the creation of all (initial) components. In contrast, if different values for different (initial) components should be used, tuples of values can be passed for these three parameters. In this case, the tuples must have a length that corresponds to the number of (initial) components, i.e., the number of image objects in ModelImageModelImageModelImageModelImagemodelImagemodel_image. The contour regions of the (initial) components are returned in InitialComponentsInitialComponentsInitialComponentsInitialComponentsinitialComponentsinitial_components.

Thus, the second possibility is equivalent to the function of inspect_shape_modelinspect_shape_modelInspectShapeModelInspectShapeModelInspectShapeModelinspect_shape_model within the shape-based matching. However, in contrast to inspect_shape_modelinspect_shape_modelInspectShapeModelInspectShapeModelInspectShapeModelinspect_shape_model, gen_initial_componentsgen_initial_componentsGenInitialComponentsGenInitialComponentsGenInitialComponentsgen_initial_components does not return the contour regions on multiple image pyramid levels. Therefore, if the number of pyramid levels to be used should be chosen manually, preferably inspect_shape_modelinspect_shape_modelInspectShapeModelInspectShapeModelInspectShapeModelinspect_shape_model should be called individually for each (initial) component.

For both described possibilities the parameters ContrastLowContrastLowContrastLowContrastLowcontrastLowcontrast_low, ContrastHighContrastHighContrastHighContrastHighcontrastHighcontrast_high, and MinSizeMinSizeMinSizeMinSizeminSizemin_size can be automatically determined. If both hysteresis threshold should be automatically determined, both ContrastLowContrastLowContrastLowContrastLowcontrastLowcontrast_low and ContrastHighContrastHighContrastHighContrastHighcontrastHighcontrast_high must be set to 'auto'"auto""auto""auto""auto""auto". In contrast, if only one threshold value should be determined, ContrastLowContrastLowContrastLowContrastLowcontrastLowcontrast_low must be set to 'auto'"auto""auto""auto""auto""auto" while ContrastHighContrastHighContrastHighContrastHighcontrastHighcontrast_high must be set to an arbitrary value different from 'auto'"auto""auto""auto""auto""auto".

If the input image ModelImageModelImageModelImageModelImagemodelImagemodel_image has one channel the representation of the model is created with the method that is used in create_component_modelcreate_component_modelCreateComponentModelCreateComponentModelCreateComponentModelcreate_component_model or create_trained_component_modelcreate_trained_component_modelCreateTrainedComponentModelCreateTrainedComponentModelCreateTrainedComponentModelcreate_trained_component_model for the metrics 'use_polarity'"use_polarity""use_polarity""use_polarity""use_polarity""use_polarity", 'ignore_global_polarity'"ignore_global_polarity""ignore_global_polarity""ignore_global_polarity""ignore_global_polarity""ignore_global_polarity", and 'ignore_local_polarity'"ignore_local_polarity""ignore_local_polarity""ignore_local_polarity""ignore_local_polarity""ignore_local_polarity". If the input image has more than one channel the representation is created with the method that is used for the metric 'ignore_color_polarity'"ignore_color_polarity""ignore_color_polarity""ignore_color_polarity""ignore_color_polarity""ignore_color_polarity".

Execution Information

Parameters

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

Input image from which the initial components should be extracted.

InitialComponentsInitialComponentsInitialComponentsInitialComponentsinitialComponentsinitial_components (output_object)  region-array objectHRegionHObjectHRegionHobject *

Contour regions of initial components.

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

Lower hysteresis threshold for the contrast of the initial components in the image.

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

Suggested values: 'auto'"auto""auto""auto""auto""auto", 10, 20, 30, 40, 60, 80, 100, 120, 140, 160

Restriction: ContrastLow > 0

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

Upper hysteresis threshold for the contrast of the initial components in the image.

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

Suggested values: 'auto'"auto""auto""auto""auto""auto", 10, 20, 30, 40, 60, 80, 100, 120, 140, 160

Restriction: ContrastHigh > 0 && ContrastHigh >= ContrastLow

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

Minimum size of the initial components.

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

Suggested values: 'auto'"auto""auto""auto""auto""auto", 0, 5, 10, 20, 30, 40

Restriction: MinSize >= 0

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

Type of automatic segmentation.

Default value: 'connection' "connection" "connection" "connection" "connection" "connection"

List of values: 'connection'"connection""connection""connection""connection""connection"

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

Names of optional control parameters.

Default value: []

List of values: 'merge_distance'"merge_distance""merge_distance""merge_distance""merge_distance""merge_distance", 'merge_fraction'"merge_fraction""merge_fraction""merge_fraction""merge_fraction""merge_fraction"

GenericValueGenericValueGenericValueGenericValuegenericValuegeneric_value (input_control)  number(-array) HTupleMaybeSequence[Union[int, float]]HTupleHtuple (real / integer) (double / int / long) (double / Hlong) (double / Hlong)

Values of optional control parameters.

Default value: []

Example (HDevelop)

* First example that shows the use of gen_initial_components to automatically
* extract the initial components from a model image.

* Get the model image.
read_image (Image, 'model_image.tif')
* Define the entire model region.
gen_rectangle1 (ModelRegion, 119, 106, 330, 537)
reduce_domain (Image, ModelRegion, ModelImage)
* Automatically generate the initial components.
gen_initial_components (ModelImage, InitialComponents, 40, 40, 20, \
                        'connection', [], [])
* Extract the model components and train the relations.
train_model_components (ModelImage, InitialComponents, TrainingImages, \
                        ModelComponents, 40, 40, 20, 0.85, 0, 0, rad(15), \
                        'speed', 'rigidity', 0.2, 0.5, ComponentTrainingID)
* Create the component model based on the training result.
create_trained_component_model (ComponentTrainingID, -rad(30), rad(60), 10, \
                                0.8, 'auto', 'auto', 'none', \
                                'use_polarity', 'false', ComponentModelID, \
                                RootRanking)

* Second example that shows the use of gen_initial_components to evaluate
* the effect of the feature extraction parameters.

* Get the model image.
read_image (ModelImage, 'model_image.tif')
* Define the regions for the components.
gen_rectangle2 (ComponentRegions, 318, 109, -1.62, 34, 19)
gen_rectangle2 (Rectangle2, 342, 238, -1.63, 32, 17)
gen_rectangle2 (Rectangle3, 355, 505, 1.41, 25, 17)
concat_obj (ComponentRegions, Rectangle2, ComponentRegions)
concat_obj (ComponentRegions, Rectangle3, ComponentRegions)
add_channels (ComponentRegions, ModelImage, ModelImageReduced)
gen_initial_components (ModelImageReduced, InitialComponents, 15, 40, 15, \
                        'connection', [], [])
* Create the component model by explicitly specifying the relations.
create_component_model (ModelImage, ComponentRegions, 20, 20, rad(25), 0, \
                        rad(360), 15, 40, 15, 10, 0.8, 'auto', 'auto', \
                        'none', 'use_polarity', 'false', ComponentModelID, \
                        RootRanking)

Result

If the parameter values are correct, the operator gen_initial_componentsgen_initial_componentsGenInitialComponentsGenInitialComponentsGenInitialComponentsgen_initial_components returns the value 2 (H_MSG_TRUE). If the input is empty (no input images are available) the behavior can be set via set_system('no_object_result',<Result>)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

draw_regiondraw_regionDrawRegionDrawRegionDrawRegiondraw_region, add_channelsadd_channelsAddChannelsAddChannelsAddChannelsadd_channels, reduce_domainreduce_domainReduceDomainReduceDomainReduceDomainreduce_domain

Possible Successors

train_model_componentstrain_model_componentsTrainModelComponentsTrainModelComponentsTrainModelComponentstrain_model_components

Alternatives

inspect_shape_modelinspect_shape_modelInspectShapeModelInspectShapeModelInspectShapeModelinspect_shape_model

Module

Matching