| Operators |
gen_initial_components — Extract the initial components of a component model.
gen_initial_components(ModelImage : InitialComponents : ContrastLow, ContrastHigh, MinSize, Mode, GenericName, GenericValue : )
In general, there are two possibilities to use gen_initial_components. The first possibility should be chosen if the components of the component model are not known. Then gen_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_components can be used to find suitable parameter values for the model feature extraction in train_model_components and create_component_model. Hence, the second possibility is comparable to the function of inspect_shape_model within the shape-based matching.
When using the first possibility, gen_initial_components extracts the initial components of a component model from a model image ModelImage. 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_components, which extracts the (final) model components and the relations between them. gen_initial_components returns the initial components in a region object tuple InitialComponents 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 ModelImage must contain the entire compound object including all components. Mode specifies the method used for the automatic computation. Currently, only the mode 'connection' is available. In this mode the automatic computation is performed in two steps: In the first step, features are extracted using the parameters ContrastLow, ContrastHigh, and MinSize. 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. ContrastLow and ContrastHigh 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_image. Here, ContrastLow determines the lower threshold, while ContrastHigh determines the upper threshold. If the same value is passed for ContrastLow and ContrastHigh a simple thresholding operation is performed. For more information about the hysteresis threshold method, see hysteresis_threshold. MinSize 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 MinSize 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 InitialComponents and can be used to train the component model by passing them to train_model_components.
To control the internal image processing, the parameters GenericName and GenericValue are used. This is done by passing the names of the control parameters to be changed in GenericName as a list of strings. In GenericValue 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' and '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' from another contour region is computed. If this fraction exceeds the value that is passed in 'merge_fraction' the two contour regions are merged. Consequently, the higher 'merge_distance' and the lower 'merge_fraction' is chosen the more contour regions are merged. The default value of 'merge_distance' is 5 and the default value of '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_components can be performed without previously executing gen_initial_components. If this is desired, the initial components can be specified by the user and directly passed to train_model_components. Furthermore, if the components as well as the relative movements (relations) of the components are known, gen_initial_components as well as train_model_components need not be executed. In fact, by immediately passing the components as well as the relations to create_component_model, the component model can be created without any training. In both cases, however, gen_initial_components can be used to evaluate the effect of the feature extraction parameters ContrastLow, ContrastHigh, and MinSize of train_model_components and create_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, ModelImage 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., ModelImage cannot be constructed in an arbitrary manner using concat_obj, but must be created from the same image using add_channels or equivalent calls. If this is not the case, an error message is returned. If the parameters ContrastLow, ContrastHigh, or MinSize 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 ModelImage. The contour regions of the (initial) components are returned in InitialComponents.
Thus, the second possibility is equivalent to the function of inspect_shape_model within the shape-based matching. However, in contrast to inspect_shape_model, gen_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_model should be called individually for each (initial) component.
For both described possibilities the parameters ContrastLow, ContrastHigh, and MinSize can be automatically determined. If both hysteresis threshold should be automatically determined, both ContrastLow and ContrastHigh must be set to 'auto'. In contrast, if only one threshold value should be determined, ContrastLow must be set to 'auto' while ContrastHigh must be set to an arbitrary value different from 'auto'.
If the input image ModelImage has one channel the representation of the model is created with the method that is used in create_component_model or create_trained_component_model for the metrics 'use_polarity', 'ignore_global_polarity', and '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'.
Input image from which the initial components should be extracted.
Contour regions of initial components.
Lower hysteresis threshold for the contrast of the initial components in the image.
Default value: 'auto'
Suggested values: 'auto', 10, 20, 30, 40, 60, 80, 100, 120, 140, 160
Restriction: ContrastLow > 0
Upper hysteresis threshold for the contrast of the initial components in the image.
Default value: 'auto'
Suggested values: 'auto', 10, 20, 30, 40, 60, 80, 100, 120, 140, 160
Restriction: ContrastHigh > 0 && ContrastHigh >= ContrastLow
Minimum size of the initial components.
Default value: 'auto'
Suggested values: 'auto', 0, 5, 10, 20, 30, 40
Restriction: MinSize >= 0
Type of automatic segmentation.
Default value: 'connection'
List of values: 'connection'
Names of optional control parameters.
Default value: []
List of values: 'merge_distance', 'merge_fraction'
Values of optional control parameters.
Default value: []
* 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)
If the parameter values are correct, the operator gen_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>). If necessary, an exception is raised.
draw_region, add_channels, reduce_domain
Matching
| Operators |