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 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.

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

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.

`set_metrology_model_image_size`

2D Metrology

Operators |