get_component_relations — Return the relations between the model components that are contained in a training result.
get_component_relations returns the relations between model components after training them with train_model_components. With the parameter ReferenceComponent, you can select a reference component. get_component_relations then returns the relations between the reference component and all other components in the model image (if Image = 'model_image' or Image = 0) or in a training image (if Image >= 1). In order to obtain the relations in the ith training image, Image must be set to i. The result of the training returned by train_model_components must be passed in ComponentTrainingID. ReferenceComponent describes the index of the reference component and must be within the range of 0 and n-1, if n is the number of model components (see train_model_components).
The relations are returned in form of regions in Relations as well as in form of numerical values in Row, Column, Phi, Length1, Length2, AngleStart, and AngleExtent.
The region object tuple Relations is designed as follows. For each component a separate region is returned. Consequently, Relations contains n regions, where the order of the regions within the tuple is determined by the index of the corresponding components. The positions of all components in the image are represented by circles with a radius of 3 pixels. For each component other than the reference component ReferenceComponent, additionally the position relation and the orientation relation relative to the reference component are represented. The position relation is represented by a rectangle and the orientation relation is represend by a circle sector with a radius of 30 pixels. The center of the circle is placed at the mean relative position of the component. The rectangle describes the movement of the reference point of the respective component relative to the pose of the reference component, while the circle sector describes the variation of the relative orientation (see train_model_components). A relative orientation of 0 corresponds to the relative orientation of both components in the model image. If both components appear in the same relative orientation in all images, the circle sector consequently degenerates to a straight line.
In addition to the region object tuple Relations, the relations are also returned in form of numerical values in Row, Column, Phi, Length1, Length2, AngleStart, and AngleExtent. These parameters are tuples of length n and contain the relations of all components relative to the reference component, where the order of the values within the tuples is determined by the index of the corresponding component. The position relation is described by the parameters of the corresponding rectangle Row, Column, Phi, Length1, and Length2 (see gen_rectangle2). The orientation relation is described by the starting angle AngleStart and the angle extent AngleExtent. For the reference component only the position within the image is returned in Row and Column. All other values are set to 0.
If the reference component has not been found in the current image, an array of empty regions is returned and the corresponding parameter values are set to 0.
The operator get_component_relations is particularly useful in order to visualize the result of the training that was performed with train_model_components. With this, it is possible to evaluate the variations that are contained in the training images. Sometimes it might be reasonable to restart the training with train_model_components while using a different set of training images.
Region representation of the relations.
Handle of the training result.
Index of reference component.
Restriction: ReferenceComponent >= 0
Image for which the component relations are to be returned.
Default value: 'model_image'
Suggested values: 'model_image', 0, 1, 2, 3, 4, 5, 6, 7, 8
Row coordinate of the center of the rectangle representing the relation.
Column index of the center of the rectangle representing the relation.
Orientation of the rectangle representing the relation (radians).
Assertion: ((- pi / 2) < Phi) && (Phi <= (pi / 2))
First radius (half length) of the rectangle representing the relation.
Assertion: Length1 >= 0.0
Second radius (half width) of the rectangle representing the relation.
Assertion: (Length2 >= 0.0) && (Length2 <= Length1)
Smallest relative orientation angle.
Extent of the relative orientation angles.
If the handle of the training result is valid, the operator get_component_relations returns the value 2 (H_MSG_TRUE). If necessary an exception is raised.