Skip to content

About the main classes and methods of HALCON Script Engine🔗

HALCON Script Engine (HScriptEngine/C++) is provided as a C++ class library providing the classes mentioned below.

HScriptEngine class🔗

Represents a context for loading HSCRIPT documents and executing programs and procedures.
This context may include configuration settings, global variables, as well as special states like the active window for dev_* operators. It is possible to create multiple contexts for loading and executing procedures. However, even independent engine contexts share some process-wide states such as settings controlled by the set_system operator.

HScriptEngine engine;

Methods🔗

HScriptDocument LoadDocument(const char* file_name);
Loads an HScript document from a file
HScriptDocument CreateDocumentFromString(const char* text, const char* virtual_file_name = 0);
Creates an HSCRIPT document from a string, optionally assigning a virtual file name

HScriptDocument class🔗

Represents a single .hscript document.
Loading or holding this document may implicitly load or keep alive other documents in the associated engine context (for example, via import statements). 

HScriptDocument doc = engine.LoadDocument(hscript_file);

Methods🔗

HScriptEngine GetEngine() const;
Retrieves the parent engine context
HScriptProcedure GetProcedure(const char* name) const;
Retrieves a specific procedure from the document
HalconCpp::HDict GetDocumentInfo() const;

Returns dictionary providing information about the procedure:

  • procedures: tuple of dictionaries with procedure information

HScriptProcedure class🔗

Represents a single procedure.

HScriptProcedure proc = doc.GetProcedure(proc_name);

Note

There is no corresponding entity to represent a program. Instead, just reference the main procedure.

Methods🔗

HScriptDocument GetDocument() const;
Retrieves the parent document
HScriptProcedureCall CreateCall() const;
Creates a new execution instance for the procedure
HalconCpp::HDict GetProcedureInfo() const;

Returns dictionary providing information about the procedure:

  • name: procedure name
  • source: HSCRIPT source file name
  • parameters: tuple of parameter dictionaries with:
    • name: parameter name
    • type: 'tuple' or 'object'
    • output: 'true' or 'false'

HScriptProcedureCall class🔗

Represents a procedure execution from a single thread.

HScriptProcedureCall call = proc.CreateCall();

Preview restriction

Parallel execution of procedures is not yet implemented within a single instance of HScriptEngine. One execution will wait for the other to finish. However, you can execute procedures in parallel from multiple application threads when each procedure is loaded in its own instance of HScriptEngine. In particular, to execute the same procedure twice in parallel, you have to load the same document twice in different engine instances.

Methods🔗

HScriptProcedure GetProcedure() const;
Retrieves the associated procedure definition
HalconCpp::HDict GetInputParamDict();
Retrieves the input parameter dictionary
HalconCpp::HDict GetOutputParamDict() const;

Retrieves the output parameter dictionary

Important

This dictionary is only populated after calling Execute().

While this method is marked as const to indicate intent, technically both GetInputParamDict and GetOutputParamDict are equally mutable and can be queried at any time.
The procedure call owns two dictionaries: input and output. During execution, the call looks into the input dictionary to find the required parameters and writes the results to the output dictionary. Before and after the call, you are free to modify both dictionaries – the execution does not care about “additional” content.

void Execute();
Executes the procedure with current input parameters

Convenience notations🔗

To store parameters in the input dictionary or read them from the output dictionary, you can also use this compact notation:

my_call["image"] = my_input_object;
my_call["x"]     = my_input_tuple;
my_call.Execute();
HObject region   = my_call["region"];
HTuple  result   = my_call["y"];

When the caller already holds an input dictionary, you can also use this notation:

HalconCpp::HDict Execute(const HalconCpp::HDict& input_dict);

HScriptEngineException class🔗

Expected exception type for all HScriptEngine API calls

Methods🔗

Hlong GetErrorCode() const;
Retrieves the numeric error code
const char* GetErrorMessage() const;
Retrieves a human-readable error message