About the main classes and methods of HALCON Script Engine

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

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.

C++.NET

HScriptEngine engine;

HScriptEngine engine = new HScriptEngine();

Methods

C++.NET

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 LoadDocument(string file_name)

Loads an HScript document from a file

HScriptDocument CreateDocumentFromString(string text, string virtual_file_name = null)

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

C++.NET

HScriptDocument doc = engine.LoadDocument(hscript_file);

HScriptDocument doc = engine.LoadDocument(hscript_file);

Methods

C++.NET

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 document:

• procedures: tuple of dictionaries with procedure information

For more information, see also Procedure and file documentation.

HScriptEngine GetEngine()

Retrieves the parent engine context

HScriptProcedure GetProcedure(string name)

Retrieves a specific procedure from the document

HalconDotNet.HDict GetDocumentInfo()

Returns dictionary providing information about the document:

• procedures: tuple of dictionaries with procedure information

For more information, see also Procedure and file documentation.

HScriptProcedure class

Represents a single procedure.

C++.NET

HScriptProcedure proc = doc.GetProcedure(proc_name);

HScriptProcedure proc = doc.GetProcedure(proc_name);

Note

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

Methods

C++.NET

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'

For more information, see also Procedure and file documentation.

HScriptDocument GetDocument()

Retrieves the parent document

HScriptProcedureCall CreateCall()

Creates a new execution instance for the procedure

HalconDotNet.HDict GetProcedureInfo()

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'

For more information, see also Procedure and file documentation.

HScriptProcedureCall class

Represents a procedure execution from a single thread.

C++.NET

HScriptProcedureCall call = proc.CreateCall();

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

C++.NET

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

HScriptProcedure GetProcedure()

Retrieves the associated procedure definition

HalconDotNet.HDict InputParamDict

The input parameter dictionary

HalconDotNet.HDict OutputParamDict

The output parameter dictionary

Important

This dictionary is only populated after calling Execute().

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:

C++.NET

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"];

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:

C++.NET

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

HalconDotNet.HDict Execute(HalconDotNet.HDict input_dict)

HScriptEngineException class

Expected exception type for all HScriptEngine API calls

Methods

C++.NET

Hlong GetErrorCode() const;

Retrieves the numeric error code

const char* GetErrorMessage() const;

Retrieves a human-readable error message

int GetErrorCode()

Retrieves the numeric error code

string GetErrorMessage()

Retrieves a human-readable error message