create_metrology_model — Create the data structure that is needed to measure geometric shapes.
create_metrology_model( : : : MetrologyHandle)
create_metrology_model creates a metrology model, i.e., the data structure that is needed to measure objects with a specific geometric shape (metrology object) via 2D metrology, and returns it in the handle MetrologyHandle.
Basic principle of 2D metrology
Generally, for 2D metrology approximate values for the positions, orientations and geometric shapes of the objects to measure must be provided. Within the image that shows the objects, the boundaries of these approximate objects are used to locate the real edges of the objects to adapt the parameters of the geometric shapes so that they fit optimally to the image data. The results of the measurements are the optimized parameters. The metrology model is used to store all necessary information like the initial parameters for the positions and geometric shapes of the metrology objects, parameters that control the measurement, and the results of the measurements. The geometric shapes that can be measured via 2D metrology comprise circles, ellipses, rectangles, and lines.
The edges of the object in the image are located within so-called measure regions. These are rectangular regions that are arranged perpendicular to the boundaries of the approximate objects so that their centers lie on the boundary. Parameters that adjust the dimension and distribution of the measure regions are specified together with the approximate shape parameters for each metrology object.
When the measurement is applied, the edge positions inside all measure regions are determined and fitted to geometric shapes using a RANSAC algorithm.
In the following, the individual steps needed for such a measurement are described:
Creating the metrology model data structure
First, create a metrology model data structure with create_metrology_model, which is used as a container for one or more metrology objects. After that, the image size for the image in which the measurements will be performed should be specified with set_metrology_model_image_size for an efficient measurement.
Providing approximate values
Then, metrology objects are added to the metrology model. Each metrology object consists of the approximate shape parameters for the corresponding object in the image and of the parameters that control the measurement. The parameters that control the measurement comprise, e.g., parameters that specify the half lengths of the measure regions and the distance between them. Furthermore, several generic parameters can be adjusted for each metrology object. The metrology objects are specified with the operator add_metrology_object_circle_measure for metrology objects of type circle, add_metrology_object_ellipse_measure for metrology objects of type ellipse, add_metrology_object_rectangle2_measure for metrology objects of type rectangle, and add_metrology_object_line_measure for metrology objects of type line. The operator add_metrology_object_generic allows to create metrology objects of different geometric shape types (e.g. ellipse, circle, etc.) using one operator. To visually inspect the defined metrology objects, you can access the XLD contours of their boundaries with the operator get_metrology_object_model_contour. To visually inspect the created measure regions, you can access the XLD contours of their boundaries with the operator get_metrology_object_measures.
Modifying model parameters
If a camera calibration has been performed, the camera parameters and the pose of the measurement plane are valid for all metrology objects and are added to the metrology model using set_metrology_model_param. Then, the result of the measurements returned by get_metrology_object_result will be in world coordinates. The reference coordinate system in which the metrology objects are defined can be changed using set_metrology_model_param.
Modifying object parameters
Many parameters can be set when adding the metrology objects to the metrology model. Some of them can also be modified afterwards using the operator set_metrology_object_param. The metrology model can be copied with copy_metrology_model. To write a metrology model to file, the operator write_metrology_model is available. The model can be read from file again using read_metrology_model. The indices of the metrology objects can be queried with get_metrology_object_indices.
Aligning the metrology model
align_metrology_model is used to translate and rotate the metrology model before the next measurement is performed, so that it matches its current occurrence in an image. An alignment is temporary and is replaced by the next alignment. The metrology model itself is not changed. If a shape model and find_shape_model shall be used to obtain the alignment parameters, consult align_metrology_model for more details.
Applying the measurement
Once all metrology objects were added to the metrology model, all parameters are set, and possibly an alignment has occurred, the measurement in the image is performed with apply_metrology_model. The operator locates the edges within the measure regions and fits the specified geometric shape to the edge positions using a RANSAC algorithm. The edges are located internally using the operator measure_pos or fuzzy_measure_pos. The latter uses fuzzy methods and is used only if at least one fuzzy function was set via set_metrology_object_fuzzy_param before applying the measurement. If more than one instance of the returned object shape is needed (compare image above), the generic parameter 'num_instances' must be set to the number of instances that should be returned. The parameter can be set when adding the individual metrology objects or afterwards with the operator set_metrology_object_param.
Accessing the results
After the measurement, the results can be accessed. The parameters of the adapted geometric shapes of the objects are queried with the operator get_metrology_object_result. Note that if more than one instance of an object is returned, the sequence of the returned instances is arbitrary, i.e., it is no measure for the quality of the fitting. The row and column coordinates of all located edges can be accessed with get_metrology_object_measures. Querying only the edges used for the returned result and their amplitude is also done using get_metrology_object_result. A visualization of the adapted geometric shapes as XLD contours is provided by get_metrology_object_result_contour.
Clean up memory
When the metrology model is not needed anymore, it should be destroyed with clear_metrology_model.
Note, that after calling the operator create_metrology_model the operator set_metrology_model_image_size should be called for efficiency reasons.
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.
Handle of the metrology model.
read_image (Image, 'fabrik') create_metrology_model (MetrologyHandle) get_image_size (Image, Width, Height) set_metrology_model_image_size (MetrologyHandle, Width, Height) add_metrology_object_rectangle2_measure (MetrologyHandle, 270, 230, 0, 30, \ 25, 10, 2, 1, 30, , , Index) apply_metrology_model (Image, MetrologyHandle) get_metrology_object_result (MetrologyHandle, Index, 'all', 'result_type', \ 'all_param', Rectangle) get_metrology_object_result_contour (Contour, MetrologyHandle, \ Index, 'all', 1.5) clear_metrology_model (MetrologyHandle)
If the parameters are valid, the operator create_metrology_model returns the value 2 (H_MSG_TRUE). If necessary, an exception is raised.