Skip to content

Working with HALCON Script Engineđź”—

As the name suggests, HALCON Script Engine allows you to execute whole HALCON Script programs or their individual procedures from a C++ application.

HALCON Script Engine can load HSCRIPT files dynamically, which means that you can modify the HALCON Script program or procedure without needing to compile and link the application. Therefore, you can easily update the machine vision part of an application by replacing individual HSCRIPT files.

Generally speaking, if your script already runs in HDevelopEVO, then it should also work in the HScriptEngine/C++ application.

Preview restrictions

  • While HALCON Script Engine is intended to have the same functionality and behavior as the execution in HDevelopEVO, the same limitations on language completeness apply.
  • The redirection of dev_* visualization operators is not yet implemented. The built-in behavior is to open free-floating windows.
  • 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.
  • Remote debugging is not yet implemented.
  • Resource use is not yet tracked at document level.
    To release loaded documents (or to force reload from disk) it is not sufficient to destroy a HScriptDocument instance. Instead, do the following:
    1. Create a new HScriptEngine instance to reload a file from disk.
    2. Destroy the old HScriptEngine instance (and all associated class instances) to release resources.

Command-line usageđź”—

Apart from creating a C++ application (see Creating an application with HALCON Script Engine), you can also run HALCON Script programs from the command line.

Currently, the command line tools hscriptengine.exe (Windows) and hscriptengine (Linux) allow you to do the following:

  • Execute programs from HSCRIPT files (if they are organized using a main procedure)
  • Execute arbitrary procedures from HSCRIPT files, passing input arguments from command line
  • Check HSCRIPT source files for errors and generate an error list similar to the one in HDevelopEVO (requires SDK license)

Important

Only procedures with public scope can be executed. This means, the procedures must be declared as public proc proc_name.
For more information, see Declaring and calling procedures.

For information on how to use the command line tool, run hscriptengine --help:

Options of the “hscriptengine” command line tool
%HALCONROOT%\bin> hscriptengine
Usage: hscriptengine [action] {options} [input file]
actions:
  run (default)           execute procedure from input *.hscript file
  check                   list all errors in input file or imported files [*]
options:
  --help                  show this screen
  --exec <proc_name>      the procedure to execute (default = 'main')
  --input <expr>|<stmt>   pass value (use once per input parameter)
      <expr>: HScript expression that evaluates to a value e.g "sin(1) + 4"
      <stmt>: Initialization code using the placeholder '#ARG'
examples:
 hscriptengine program.hscript
 hscriptengine --exec proc --input 42 --input 2.5 --input "'true'" lib.hscript
 hscriptengine --exec proc --input "[1, 2, 3]" lib.hscript
 hscriptengine --exec proc --input "read_image(#ARG, 'test.png')" lib.hscript
[*] Requires SDK license