New in Version 2027

Custom inspections

Custom inspections always refer to a geometric target element, in most cases an actual element. Therefore the name of an inspection element is typically composed of the target element’s name and an abbreviation indicating the inspection purpose. For example, a radius inspection on the circle element ‘Circle 1’ could be named ‘Circle1.R’.

Note

In this How-to, the preferred prose term is “inspection”. In the API, the current technical class family is CustomInspection. ScriptedInspection is documented as a legacy alias.

Inspections can be applied to

  • Scalar element properties – e.g. a circle’s radius

  • Curves – e.g. deviation of a section curve’s points in z-direction

  • Surfaces – e.g. deviation of a surface curve’s points in z-direction

The inspection element computes the deviation between the reference element’s actual value(s) and its nominal value(s). The deviation value(s) can have a dimension (e.g. length).

Dialog definition

The dialog must contain

Caution

The element name widget object must be set to name in the Dialog Editor.

The dialog can optionally provide

Caution

The tolerances widget’s name must be set to tolerance in the Dialog Editor.

Both object names – name and tolerance – are reserved and case-sensitive.

Custom inspection Python script

All custom elements are based on the Extensions API. More specifically, a custom inspection class is inherited from the CustomInspection base class.

Use this How-to for implementation flow and practical patterns. For complete constructor and return-value specifications, refer to the inspections class references in the API documentation.

Custom_Scalar_Inspection.py – Minimal example – Custom scalar inspection
 1import gom
 2import gom.api.custom_checks_util
 3import gom.api.extensions.inspections
 4
 5from gom import apicontribution
 6
 7@apicontribution
 8class MinimalScalarInspection (gom.api.extensions.inspections.Scalar):
 9
10    def __init__ (self):
11        super ().__init__ (
12            id='examples.custom_scalar_inspection',
13            description='Custom Scalar Inspection',
14            dimension='length',
15            abbreviation='ScrSca'
16        )
17
18    def dialog (self, context, args):
19        dlg = gom.api.dialog.create (context, '/Custom_Scalar_Inspection.gdlg')
20        # -------------------------------------------------------------------------
21        dlg.slct_element.filter = gom.api.custom_checks_util.is_scalar_checkable
22        # -------------------------------------------------------------------------
23        self.initialize_dialog(context, dlg, args)
24
25        # Provide dialog handle in event()
26        self.dlg = dlg
27
28        return self.apply_dialog(dlg, gom.api.dialog.show(context, dlg))
29
30    def event(self, context, event_type, parameters):
31        """
32        Set custom inspection name: <target_element>.<abbreviation>
33        """
34        if event_type == 'dialog::initialized' or event_type == 'dialog::changed':
35            if parameters['values']['slct_element'] is not None:
36                self.dlg.name.value = self.dlg.slct_element.value.name + '.' + 'ScrSca'
37                return True
38
39        return False
40
41    def compute (self, context, values):
42        # ----------------------------------------------------
43        # --- insert your computation here -------------------
44        # ----------------------------------------------------
45        ACTUAL_RESULT = 1.0
46        NOMINAL_RESULT = 2.0
47        # ----------------------------------------------------
48        return {
49            "nominal": NOMINAL_RESULT,
50            "actual":  ACTUAL_RESULT,
51            "target_element": values['slct_element']
52        }
53
54gom.run_api ()
line 2…5:

Import custom inspection specific packages.

line 7…8:

The class MinimalScalarInspection is inherited from gom.api.extensions.inspections.Scalar. The decorator @apicontribution allows to register the class MinimalScalarInspection in the ZEISS INSPECT framework.

line 10…16:

The constructor calls the super class constructor while defining the inspection ID, description, dimension, and abbreviation. See the API reference for full signature details.

Note

The dimension argument selects a physical quantity from ZEISS INSPECT’s built-in dimension definitions and determines the unit expected by the scripting API. For example, dimension='length' means that computed values must be provided in millimeters. The unit used to display that dimension can be configured in the ZEISS INSPECT preferences, but this does not change the API unit; ZEISS INSPECT converts values to the configured display unit when needed. Use gom.api.customelements.get_dimension_definition() to inspect a dimension definition.

line 18…28:

The dialog() method applies an element filter (see Selection element widget) and copies the dialog handle to the member dlg for usage in event().

line 30…39:

The event() method sets the custom inspection element name.

line 41…53:

The compute() method uses constant actual and nominal values for demonstration purposes. The exact required result schema depends on the inspection type and is defined in the API reference.

line 55:

gom.run_api() is executed when the script is started as a service.

Caution

The custom inspection’s service must be running when an inspection is created, whether creation is initiated interactively or from Python code.

Create custom inspections interactively

Custom inspections can be created interactively from the I-Inspect menu when an element is selected. The custom inspection’s service must be running for the inspection to be available in the menu.

By default, a custom inspection is visible in the I-Inspect menu. Override is_visible_for_iinspect() to control whether the inspection is offered for the selected element. The method receives exactly one selected element and can use its type or properties to determine whether the inspection is applicable.

Restricting an inspection’s visibility in the I-Inspect menu
1def is_visible_for_iinspect(self, context, element):
2    return gom.api.custom_checks_util.is_scalar_checkable(element)

Return False when the inspection is intended to be created only by script:

Hiding an inspection from the I-Inspect menu
1def is_visible_for_iinspect(self, context, element):
2    return False

If is_visible_for_iinspect() raises an exception, the inspection is visible by default as a fail-safe behavior. The method should therefore return False explicitly when an inspection must not be offered through I-Inspect.

Element-specific filtering methods

Use an element-specific filter to restrict the elements that can be selected in the inspection dialog. The filter is assigned to the selection widget’s filter attribute. Use the corresponding helper from gom.api.custom_checks_util for scalar, curve, or surface inspections.

Filtering elements in a custom inspection dialog
 1def element_filter(self, element):
 2    try:
 3        return gom.api.custom_checks_util.is_scalar_checkable(element)
 4    except (AttributeError, TypeError):
 5        return False
 6
 7def dialog(self, context, args):
 8    dlg = gom.api.dialog.create(context, '/Custom_ScalarInspection.gdlg')
 9    dlg.checked_element.filter = self.element_filter
10    self.initialize_dialog(context, dlg, args)
11    return self.apply_dialog(dlg, gom.api.dialog.show(context, dlg))

Use is_curve_checkable() or is_surface_checkable() for curve or surface inspections, respectively. Return False when an element is unsupported or does not provide the properties required by the inspection. The filter attribute controls which elements can be selected in the dialog; is_visible_for_iinspect() controls whether the inspection is offered in the I-Inspect menu.

Create custom inspections from Python script

Create a custom inspection from a Python script by using the gom.script.customelements.create_inspection() function. The contribution value must match the inspection class ID defined in its constructor. The values dictionary is forwarded unchanged to the inspection’s compute() method.

Custom inspection creation from Python script – Custom scalar inspection
 1checked_element = gom.app.project.actual_elements['Cylinder 1']
 2
 3gom.script.customelements.create_inspection (
 4    """
 5    Create a custom scalar inspection
 6    """
 7    # Inspection ID as defined in the contribution class constructor
 8    contribution='examples.custom_scalar_inspection',
 9
10    # Optional: Set the inspection name explicitly, otherwise it is set automatically
11    name='Cylinder 1.CusSca',
12
13    # Values are forwarded to compute()
14    values={
15        'checked_element': checked_element,
16        'nominal': 4.82
17    },
18
19    # Optional: Set asymmetric lower and upper tolerance limits
20    tolerance={'lower': -0.1, 'upper': 0.1}
21)

The values entries depend on the inspection type and must match the parameters expected by its compute() method. The result returned by compute() must use the schema required by the corresponding inspection class:

  • A scalar inspection returns nominal, actual, and target_element.

  • A curve inspection returns actual_values, either a common nominal_value or matching nominal_values, and target_element.

  • A surface inspection returns deviation_values, nominal, and target_element.

Optional inspection result data

Additional inspection data can be persisted by returning a data dictionary from compute(). The data is stored with the inspection element, and each key becomes a token that can be accessed through the element later.

Persisting optional custom inspection data
 1def compute(self, context, values):
 2    element = values['checked_element']
 3    actual = float(element.diameter)
 4
 5    return {
 6        'nominal': float(values['nominal']),
 7        'actual': actual,
 8        'target_element': element,
 9        'data': {
10            'checked_element_name': element.name,
11            'calculation_source': 'diameter'
12        }
13    }

Read the persisted values as tokens on the inspection element:

Reading optional custom inspection data
1inspection = gom.app.project.inspection['Cylinder 1.CusSca']
2print(inspection.checked_element_name)
3print(inspection.calculation_source)

Choose unique, token-friendly keys. A custom data key must not collide with an existing attribute or token of the inspection element type.

Stage-dependent computation

Curve and surface inspections can compute values for the current stage by using context.stage. See the Custom Scalar Inspection, Custom Curve Inspection, and Custom Surface Inspection examples for complete implementations and tests.

Applying tolerances

To apply tolerances when creating an inspection from its dialog, add a Tolerances widget with the reserved name tolerance, then forward its value from the dialog result in apply_dialog().

Forwarding tolerance values in apply_dialog()
1def apply_dialog(self, dlg, result):
2    params = super().apply_dialog(dlg, result)
3    params['name'] = result['name']
4    params['tolerance'] = result['tolerance']
5    return params

The framework consumes name and tolerance automatically. The values dictionary is still forwarded unchanged to compute().

When creating an inspection from Python code, pass the tolerance directly to gom.script.customelements.create_inspection(), as shown in the previous example. The tolerance can be a symmetric value or a dictionary containing lower and upper limits, depending on the selected tolerance mode. See the Tolerances widget documentation for the supported modes and result formats.

Service definition and troubleshooting

For service definition details and troubleshooting guidance (including service startup issues), refer to the corresponding sections in Custom nominal/actual elements:

References