Operators |

`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 the major axis
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
object. The measure direction for the detection of the edges within
each measure region is from the inside to the outside of the object
for objects of type circle, ellipse, and rectangle, and from
left to right for objects of type line (seen from the line's
start point to its end point). 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. The fitting of the geometric shape to the
found edge positions is performed using a RANSAC algorithm.

In the following, the individual steps needed for such a measurement are described:

**Providing approximate values**

For an efficient measurement, after creating the metrology model with
`create_metrology_model`, the image size for the image in which
the measurements will be performed should be specified with
`set_metrology_model_image_size`. 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 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 parameters that control the measurement comprise, e.g.,
parameters that specify the half lengths of the measure regions and the
distance between them. To visually inspect the measure regions, you can
access the XLD contours of their boundaries with the operator
`get_metrology_object_measures`. Furthermore, several
generic parameters can be adjusted for each metrology object.

**Modifying 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`. For example, if a
camera calibration has been performed, the camera parameters and the
pose of the world coordinate system (WCS) can be added to the metrology
objects using `set_metrology_object_param`. Then, the result of
the measurements will be returned in world coordinates. Additionally,
the metrology model or metrology objects can be copied with
`copy_metrology_model` or `copy_metrology_object`,
respectively. For an alignment, the metrology objects can be
transformed using `transform_metrology_object`. 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`.

**Applying the measurement**

If all metrology objects were added to the metrology model and all
parameters are finally set, the measurement in the image is applied
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. If more than one
instance of the returned object shape is needed, 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 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 the located edges can be accessed
with `get_metrology_object_measures`. 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.

A metrology model *'MetrologyHandle'* cannot be shared between
two or more user's threads. Different metrology models can be used
independently and safely in different threads.

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

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', \ 'param', Rectangle) gen_rectangle2_contour_xld (ContRect, Rectangle[0], Rectangle[1], \ Rectangle[2], Rectangle[3], Rectangle[4]) 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.

`set_metrology_model_image_size`

2D Metrology

Operators |