Skip to content

HDevEngine in Python applications🔗

The Python interface of HDevEngine follows the same concepts as the C++ and .NET interfaces. Most concepts and functions have a one-to-one mapping, and the Python layer is mainly a convenience wrapper around the same engine model.

A first example🔗

This example shows the basic HDevEngine workflow in Python:

import os
import halcon as ha

if __name__ == '__main__':
    example_dir = ha.get_system_s('example_dir')
    procedure_path = os.path.join(example_dir, 'hdevengine', 'procedures')

    hdev_engine = ha.HDevEngine()
    hdev_engine.set_procedure_path(procedure_path)

    img = ha.read_image('fin2')

    procedure = ha.HDevProcedure.load_external('detect_fin')
    proc_call = ha.HDevProcedureCall(procedure)

    proc_call.set_input_iconic_param_by_name('Image', img)
    proc_call.execute()

    fin_area = proc_call.get_output_control_param_by_name('FinArea')[0]
    print(f'Fin Area: {fin_area}')

This is the standard HDevEngine workflow: create an engine, configure the procedure path, load the procedure, set the input values, execute it, and read the output values.

Creating applications with HDevEnginePython🔗

No HDevEngine-specific actions are required to add the Python package to an application. You only need a valid HALCON Python installation.

python -m venv .venv
source .venv/bin/activate
pip install mvtec-halcon==<major><minor><revision>

Then the application can use the HALCON Python module directly:

import halcon as ha
hdev_engine = ha.HDevEngine()

Global functionality🔗

Multiple Python instances of HDevEngine can exist, but they all share the same underlying engine implementation as a mutable singleton. This mostly affects configuration and procedure loading, while the individual program and procedure call objects are largely independent.

Procedure path🔗

hdev_engine = ha.HDevEngine()
hdev_engine.set_procedure_path(path)
hdev_engine.add_procedure_path(path)

These functions set or extend the list of directories searched to load procedures.

Attributes🔗

hdev_engine = ha.HDevEngine()
assert hdev_engine.get_attribute('ignore_invalid_results') == 1

hdev_engine.set_attribute('ignore_invalid_results', 0)
assert hdev_engine.get_attribute('ignore_invalid_results') == 0

These functions let you set specific attributes. By default, the attribute ignore_invalid_results is set to true. This means that an empty region object or an empty tuple is returned when a variable or parameter is queried that was not previously set by the program or procedure. Think of it like this: should accessing an uninitialized variable return a default value or raise an exception? For HDevEngine attributes, 0 maps to false, and 1 maps to true.

Debug server🔗

hdev_engine.start_debug_server()
hdev_engine.stop_debug_server()

These methods start and stop the debug server used for remote debugging from HDevelop. The port can be configured via the corresponding engine attribute.

Global metadata and variables🔗

procedure_names = hdev_engine.get_procedure_names()
loaded_names = hdev_engine.get_loaded_procedure_names()

hdev_engine.set_global_control_var('MyVar', 42)
value = hdev_engine.get_global_control_var('MyVar')

These functions let you query global metadata, such as which procedures are loaded and the vector dimensions of global variables. The following methods are available for this purpose:

hdev_engine.get_procedure_names()
hdev_engine.get_loaded_procedure_names()
hdev_engine.get_global_control_var_names()
hdev_engine.get_global_iconic_var_dimension(name)
hdev_engine.get_global_control_var_dimension(name)

hdev_engine.set_global_iconic_var(name, value)
hdev_engine.set_global_iconic_vector_var(name, value)
hdev_engine.set_global_control_var(name, value)
hdev_engine.set_global_tuple_vector_var(name, value)

hdev_engine.get_global_iconic_var(name)
hdev_engine.get_global_iconic_vector_var(name)
hdev_engine.get_global_control_var(name)
hdev_engine.get_global_tuple_vector_var(name)

This allows you to inspect the loaded procedures and to read or write global variables, both iconic and control-based.

Calling HDevelop procedures🔗

The general workflow behind procedure calls is:

  1. Load a procedure from the file system.
  2. Create a procedure call object.
  3. Set the input values.
  4. Execute the procedure.
  5. Read the output values.
procedure = ha.HDevProcedure.load_external('detect_fin')
proc_call = ha.HDevProcedureCall(procedure)

proc_call.set_input_iconic_param_by_name('Image', img)
proc_call.execute()

fin_area = proc_call.get_output_control_param_by_name('FinArea')[0]

Loading procedures🔗

external_proc = ha.HDevProcedure.load_external('detect_fin')
program = ha.HDevProgram('my_program.hdev')
local_proc = ha.HDevProcedure.load_local(program, 'count_nuts')

Procedure loading should be done via the recommended static factory methods. This ensures that the engine state is initialized consistently.

Unloading procedures🔗

hdev_engine.unload_procedure('detect_fin')
hdev_engine.unload_all_procedures()

This can be useful when memory pressure or procedure reuse requires reloading or cleanup.

Procedure metadata🔗

The Python procedure object provides a number of read-only properties and metadata methods:

procedure.name
procedure.short_description
procedure.loaded
procedure.input_iconic_param_names
procedure.output_iconic_param_names
procedure.input_control_param_names
procedure.output_control_param_names

The get_info, get_param_info, and related methods can be used to query additional metadata about parameters and their dimensions. In addition, you can inspect the used procedures and query the available parameter slots:

procedure.get_used_procedure_names()
procedure.get_info(slot)
procedure.get_param_info(name, slot)
procedure.get_input_iconic_param_info(idx, slot)
procedure.get_output_iconic_param_info(idx, slot)
procedure.get_input_control_param_info(idx, slot)
procedure.get_output_control_param_info(idx, slot)
procedure.query_slots()
procedure.query_param_slots()

JIT compilation🔗

compiled = procedure.compile_used_procedures()

This triggers JIT compilation for procedures that can be compiled. Procedures that cannot be compiled still run via the normal interpreter path.

Procedure call initialization🔗

proc_call = ha.HDevProcedureCall(procedure)

The only way to initialize an HDevProcedureCall instance is using a loaded HDevProcedure instance.

Setting input parameters🔗

proc_call.set_input_control_param_by_name('Threshold', 120)
proc_call.set_input_iconic_param_by_name('Image', image)
proc_call.set_input_tuple_vector_by_name('Values', [[1, 2], [3, 4]])

The following methods are available for setting input parameters:

proc_call.set_input_control_param_by_index(idx, value)
proc_call.set_input_tuple_vector_by_index(idx, value)
proc_call.set_input_control_param_by_name(name, value)
proc_call.set_input_tuple_vector_by_name(name, value)
proc_call.set_input_iconic_param_by_index(idx, value)
proc_call.set_input_iconic_vector_by_index(idx, value)
proc_call.set_input_iconic_param_by_name(name, value)
proc_call.set_input_iconic_vector_by_name(name, value)

We recommend setting all input parameters again every time you want to execute the procedure call. This makes the code more robust in the face of error conditions. Indices start at 1 instead of 0. This is an important compatibility detail of the HDevEngine Python API.

Execution🔗

proc_call.execute()

Use this function when all input parameters are set and the procedure should be executed.

Reading output parameters🔗

result = proc_call.get_output_control_param_by_name('Result')
region = proc_call.get_output_iconic_param_by_name('Region')

The following methods are available for reading output parameters:

proc_call.get_output_control_param_by_index(idx)
proc_call.get_output_tuple_vector_by_index(idx)
proc_call.get_output_control_param_by_name(name)
proc_call.get_output_tuple_vector_by_name(name)
proc_call.get_output_iconic_param_by_index(idx)
proc_call.get_output_iconic_vector_by_index(idx)
proc_call.get_output_iconic_param_by_name(name)
proc_call.get_output_iconic_vector_by_name(name)

Use these functions to read output parameters after execute has finished successfully. Indices here also start at 1 instead of 0.

Waiting for the debugger🔗

proc_call.wait_for_debug_connection()

Use this function in conjunction with start_debug_server to debug procedure execution.

Reset🔗

proc_call.reset()

This is mainly useful when you want to abort execution from another thread or free native resources while some instances are still alive.

Calling HDevelop programs🔗

The workflow for programs is similar to that for procedures:

  1. Create an HDevProgram instance.
  2. Create an HDevProgramCall.
  3. Execute the program.
  4. Read the variables.
example_dir = ha.get_system_s('example_dir')
program_path = os.path.join(example_dir, 'hdevelop', 'Transformations', 'Poses')

program = ha.HDevProgram(os.path.join(program_path, 'pose_compose.hdev'))
program_call = ha.HDevProgramCall(program)
program_call.execute()

pose = program_call.get_control_var_by_name('PoseComposeAlternative')
rounded_pose = [round(x, 8) for x in pose]

The program object exposes metadata accessors such as:

  • name
  • loaded
  • iconic_var_names
  • control_var_names
  • get_used_procedure_names()
  • get_local_procedure_names()

These values are useful when inspecting a loaded program and its dependencies.

Loading programs🔗

program = ha.HDevProgram(os.path.join(program_path, 'pose_compose.hdev'))

Programs are loaded via the initializer of HDevProgram, which expects a full path to an HDevelop program in the platform-specific format, including the file name.

Program metadata🔗

Access program metadata via these read-only member variables:

program.name
program.loaded
program.iconic_var_names
program.control_var_names
program.iconic_var_dimensions
program.control_var_dimensions

The get_used_procedure_names and get_local_procedure_names methods can be used to query additional metadata about the loaded program.

JIT compilation for programs🔗

compiled = program.compile_used_procedures()

Compile all procedures that are used by the program and that can be compiled with a just-in-time compiler. Procedures that could not be compiled are still called by the HDevEngine interpreter in the usual way.

Program call initialization🔗

program_call = ha.HDevProgramCall(program)

The only way to initialize an HDevProgramCall instance is using a valid HDevProgram instance.

Execution🔗

program_call.execute()

Use this function to execute the program.

Reading variables🔗

pose = program_call.get_control_var_by_name('PoseComposeAlternative')
region = program_call.get_iconic_var_by_name('Region')

Use these functions to read variables after execute has finished successfully. Indices start at 1 instead of 0.

Waiting for the debugger🔗

program_call.wait_for_debug_connection()

Use this function together with start_debug_server to debug program execution.

Reset🔗

program_call.reset()

This is mainly useful when you want to abort execution from another thread or free native resources while some instances are still alive.

Dev operators🔗

Inside HDevelop, dev_* operators are often used for convenience. When embedding an HDevelop program or procedure in an application, these calls have no straightforward mapping. In such cases, it may be desirable to map them to visualization logic in the application itself.

HDevEnginePython provides a base class that you can inherit from and override with logic appropriate for your application.

Take, for example, this simple HDevelop program:

read_image(Image, 'pcb')
dev_display(Image)

By default, this program does not open a window when used with HDevEnginePython. However, you can register your own logic for what should happen when dev_display is called.

class DevImpl(ha.HDevOperatorBase):
    @staticmethod
    def dev_display(object):
        print(object)

hdev_engine = ha.HDevEngine()
hdev_engine.set_hdev_operator_impl(DevImpl())

To get an overview of which dev_* operators are available and which signatures each of them expects, inspect the HDevOperatorBase implementation.

Only one implementation can be registered at a time. This applies to all current and future HDevEngine instances until you change it again.

By default, no implementation is registered. Once you have registered one, you can return to the default behavior by calling:

hdev_engine.unset_hdev_operator_impl()

Any function that was not overwritten by your implementation of HDevOperatorBase raises an exception if called.

It is safe to raise exceptions from within Python code implementing dev_* operators. However, only a generic HDevEngineError is raised, and the original exception traceback is logged to stderr. This is a technical limitation.

HALCON vectors🔗

HDevEnginePython maps HALCON vectors to nested Python lists. There are two separate and incompatible vector types: tuple_vector and iconic_vector. The following examples show the Python representations used to read and write HALCON vectors in HDevEnginePython:

empty_tuple_vector = ha.HDevEmptyVector(dimension=1)
1d_tuple_vector = [[23, 'a'], ['ec', 2.5, 77]]
2d_tuple_vector = [[[8], ['b', 'c']], [], [[]]]

empty_iconic_vector = ha.HDevEmptyVector(dimension=1)
1d_iconic_vector = [img1, img2, img3]
2d_iconic_vector = [[img1, img2], [img1, img3, img4], []]

For tuple_vector, the innermost list is treated as a HALCON tuple. All elements of a vector must have the same dimension.

[[234], [2, 5]]  # OK
[234, [2, 5]]    # NOT OK!

Multithreading🔗

Because HDevEngine is a mutable singleton-like runtime, some functionality affects the complete application:

  • global engine settings
  • procedure path configuration
  • loaded procedures and programs
  • registered dev_* operator implementations

A multithreaded application must therefore take care when working with shared mutable state. For example, you cannot safely load multiple procedures in parallel using the global procedure path if they require different path settings without synchronizing inside the application. Not applying the required care can lead to undefined behavior, including crashes.

To avoid these issues, configure HDevEngine and load procedures and programs before starting additional application threads. The individual call objects such as HDevProcedureCall and HDevProgramCall are independent from each other, but the shared global state is not.

This is the same general rule as in the C++ API: configure once and use per-call instances in parallel where possible.