HDevGUI [HALCON Operator Reference / Version 18.11.0.0]

HDevGUI

HDevGUI Server Extension Package for HALCON

The HDevGUI Server Extension Package for HALCON is an extension package to enable development of GUI applications with HALCON. Currently, this Extension Package is available for HALCON 18.11, HALCON 20.11, HALCON 22.11, HALCON 24.11, and HALCON 25.11. It is available for x86/x64 Windows and x86/x64 Linux architectures.

Installation

Running the installer

Run the installer
install-hdevgui-x.x.x.exe . The following packages will be installed:
HDevGUI Server Extension Package .

Setting HALCONEXTENSIONS

After the installation, the HDevGUI Server Extension Package must be made known to the HALCON installation. This is done by setting the HALCONEXTENSIONS environment variable.

Example

Let's assume that your installation directory of HDevGUI is
C:\Program Files\Machine Vision Makers\HDevGUI
. Then the correct setting for HALCONEXTENSIONS is
C:\Program Files\Machine Vision Makers\HDevGUI\halcon-20.11-Progress\hdevgui_server_extpack .
Here the subdirectory halcon-20.11-Progress has to match the version of HALCON you will be using.

Open Windows Settings / Advanced system settings / Environment Variables... (or start typing environment in the Start menu). Then go to System variables / New... and create a variable with name HALCONEXTENSIONS and value C:\Program Files\Machine Vision Makers\HDevGUI\halcon-20.11-Progress\hdevgui_server_extpack. You can use Browse Directory... in the Edit System Variable dialog to find the directory. After a restart of HDevelop there are new operators available, for example mvm_gui_open_webserver .

Removing from HALCONEXTENSIONS

To disable the extension package remove the system environment variable HALCONEXTENSIONS: Open Windows Settings / Advanced system settings / Environment Variables... (or start typing environment in the Start menu). Then go to System variables and look for the environment variable named HALCONEXTENSIONS. Select it and press Delete.

Licensing Requirements

This extension package is subject to licensing terms, valid for a single HALCON USB dongle ID. Usage of the extension package is restricted to the specific USB dongle for which it is licensed. Upon purchase, customers are required to provide their HALCON dongle ID to enable the generation of the corresponding extension package license. Following purchase, customers will receive a file named similarly to "hdevgui_license_3-1234567.dat". This file must be placed adjacent to the corresponding "license*.dat" file within the existing installation of HALCON.
Alternatively, the license file may be situated at any location within the file system. In such cases, the environment variable HDEVGUI_LICENSE_FILE must be configured to encompass the complete path leading to the license file's location.

Example:

If HALCON is assumed to be installed at C:\Users\User\AppData\Local\Programs\MVTec\HALCON-22.11-Progress, you will probably have installed the corresponding license file at C:\Users\User\AppData\Local\Programs\MVTec\HALCON-22.11-Progress\license\license_3-1234567.dat . The extension package license file should then be installed as C:\Users\User\AppData\Local\Programs\MVTec\HALCON-22.11-Progress\license\hdevgui_license_3-1234567.dat.
The file structure now looks like the following:

  C:\Users\User\AppData\Local\Programs\MVTec\HALCON-22.11-Progress
  +---bin
  +---calib
  +---doc
  +---...
  \---license
          hdevgui_license_3-1234567.dat
          license_3-1234567.dat

The license file will serve as the means to authenticate the validity of the extension package license whenever any operator of this extension package is invoked.

Examples

The examples are by default located at
C:\Program Files\Machine Vision Makers\HDevGUI\examples\ . For example, examples\simple_hdevgui\simple_hdevgui.hdev is the HALCON script running the Image Processing together with the HDevGUI Server. Open examples\simple_hdevgui\simple_hdevgui.hdev in HDevelop and press Run (F5).

If you are running the HDevGUI Server Extension for the first time the Windows Firewall might ask for permission: Select 'Allow access'.

After reading the short introduction press Run (F5) again to start the local web server at port 9980. You can then connect to the HDevGUI by opening
http://localhost:9980
in the browser.

By setting
UseExternalBrowser := true
to
UseExternalBrowser := false
in the script an internal browser engine will be used instead of the browser. The HDevGUI will then look and behave more like an installed local application.

Within the directory examples\simple_hdevgui\client the HTML client code is located. The path to this is specified via the mvm_gui_open_webserver operator call in simple_hdevgui.hdev, i.e. the HTML code in this directory will then be served via the integrated web server together with JavaScript and CSS files.

To modify the existing examples it is recommend to copy the whole directory C:\Program Files\Machine Vision Makers\HDevGUI\examples\ to a convinient location where you have write access and as a starting point open and edit the existing .hdev example scripts and the corresponding web pages from there.

Server/Client architecture

One important functionality of the extension package is to provide a web server with specific features related to HALCON. The web server can serves web page resources like HTML, CSS, and JavaScript files. But the web server is also responsible to create a communication channel for images and tuples between HALCON and the web client. The web server can be opened using the mvm_gui_open_webserver. This operator call returns the handle ServerHandle which is passed in many subsequent operator calls (for example mvm_gui_send_tuple) to specify that messages are to be sent to the web client or received from the web client via this server.

Many operators also use the parameter ConnectionHandle to specify which client connection should be addressed. Multiple connections can be specified as tuple. A ConnectionHandle with the value 'all' means that the UI state of all connected clients is addressed. This is the default value. A value of 'first' addresses only the first connection. Additionally, an optional custom error handling can be specified in ConnectionHandle. For further explanations on connection handles and custom error handling, see the \ChapRef{MachineVisionMakers,HDevGUI} chapter documentation for this extension package. The parameter ConnectionHandle can also contain further string elements to set specific options for this operator call:

connection_error_ignore:

Ignore connection errors ¹.

connection_error_lowlevel:

Issue a low level warning to the Output console upon connection errors ¹.

connection_error_raise:

Raise a HDevelop exception upon connection errors ¹.

ack_error_ignore:

Ignore acknowledge errors ².

ack_error_lowlevel:

Issue a low level warning to the Output console upon acknowledge errors ².

ack_error_raise:

Raise a HDevelop exception upon acknowledge errors ².

¹ examples for connection errors are failure to send out data at all because of a closing or closed client connection or failure to receive acknowledge packages for example because the web client JavaScript code is currently stopped (during debugging)

² examples for acknowledge errors are using wrong identifiers which do not correspond to any listener on the client side. For example such an error happens if you there is an HTML element like
<input type="checkbox" data-bind="checkbox1">
but you are using
mvm_gui_send_tuple (ServerHandle, 'all', 'chckbx1', 1)
to send data to the (misstyped) data-bind identifier.

Please contact hdevgui@machine-vision-makers.com for assistance, purchasing, or bug reports.

Copyright Machine Vision Makers, http://www.machine-vision-makers.com

List of Operators

mvm_close_loggerMvmCloseLoggerMvmCloseLoggermvm_close_logger: Close a logger.

mvm_gui_close_consoleMvmGuiCloseConsoleMvmGuiCloseConsolemvm_gui_close_console: Close developer console.

mvm_gui_close_webclientMvmGuiCloseWebclientMvmGuiCloseWebclientmvm_gui_close_webclient: Close a webclient.

mvm_gui_close_webserverMvmGuiCloseWebserverMvmGuiCloseWebservermvm_gui_close_webserver: Close a webserver.

mvm_gui_errorMvmGuiErrorMvmGuiErrormvm_gui_error: Convert an error code of this extension package to a human-readable error message.

mvm_gui_get_infoMvmGuiGetInfoMvmGuiGetInfomvm_gui_get_info: Retrieve diagnostic information.

mvm_gui_get_messageMvmGuiGetMessageMvmGuiGetMessagemvm_gui_get_message: Receive a message from the message loop of a server.

mvm_gui_get_open_connectionsMvmGuiGetOpenConnectionsMvmGuiGetOpenConnectionsmvm_gui_get_open_connections: Get all client IDs that are connected to a given server.

mvm_gui_get_uiMvmGuiGetUiMvmGuiGetUimvm_gui_get_ui: Receive current data from the clients.

mvm_gui_get_webserver_optionsMvmGuiGetWebserverOptionsMvmGuiGetWebserverOptionsmvm_gui_get_webserver_options: Return current webserver options for a given server in JSON format.

mvm_gui_open_consoleMvmGuiOpenConsoleMvmGuiOpenConsolemvm_gui_open_console: Open developer console.

mvm_gui_open_webclientMvmGuiOpenWebclientMvmGuiOpenWebclientmvm_gui_open_webclient: Open a webclient using the internal browser engine.

mvm_gui_open_webserverMvmGuiOpenWebserverMvmGuiOpenWebservermvm_gui_open_webserver: Open a GUI webserver.

mvm_gui_send_imageMvmGuiSendImageMvmGuiSendImagemvm_gui_send_image: Send an image to a webclient.

mvm_gui_send_tupleMvmGuiSendTupleMvmGuiSendTuplemvm_gui_send_tuple: Send a tuple to a webclient.

mvm_gui_set_htmlMvmGuiSetHtmlMvmGuiSetHtmlmvm_gui_set_html: Set inner HTML of an HTML element.

mvm_gui_set_webserver_optionsMvmGuiSetWebserverOptionsMvmGuiSetWebserverOptionsmvm_gui_set_webserver_options: Set webserver options for a given server in JSON format.

mvm_gui_try_get_messageMvmGuiTryGetMessageMvmGuiTryGetMessagemvm_gui_try_get_message: Try to get a message from the message loop of a server.

mvm_log_lineMvmLogLineMvmLogLinemvm_log_line: Send a log message to a client.

mvm_log_rawMvmLogRawMvmLogRawmvm_log_raw: Send a raw log message to a client.

mvm_open_loggerMvmOpenLoggerMvmOpenLoggermvm_open_logger: Open a logger.

Operators