Halcon driver User's Guide

Documentation of the LV-SDS interface for Halcon and ActivVisionTools packages from MVTec Software GmbH

Leutron Vision

Revision: 1.0. Leutron Vision documentation set.

All Information in this document is subject to change without notice and does not represent a commitment on the part of Leutron Vision. The software products described in this document are furnished under a license agreement or nondisclosure agreement. The software may be used or copied only in accordance with the terms of agreement.

It is against the law to copy the software on any medium except as specifically allowed in the license or nondisclosure agreement. The licensee may make one copy of the software for backup purposes. No part of this manual may be reproduced or transmitted in any form or by any means, electronic or mechanical, including photocopying, recording, or information storage and retrieval systems, for any purpose other than the licensee’s personal use, without the express written permission of Leutron Vision.

Product names mentioned in this manual may be trademarks or registered trademarks of their respective companies and are hereby acknowledged.

04 July 2009

General information

Scope of the manual

This manual provides a complete description of the LV-SDS interface to Halcon and ActivVisionTools image processing libraries from MVTec Software GmbH. It explains how to connect to our cameras and frame grabbers from these libraries and it lists all functions and acquisition parameters supported by the interface.

1. Introduction

The LV-SDS Halcon driver is an interface layer between regular LV-SDS API and Halcon/ActivVisionTools libraries of MVTec Software GmbH. This interface allows to acquire images and image sequences using all types of Leutron Vision hardware products from Halcon and ActivVisionTools applications. The interface provides access to most of the hardware functionality.

1.1. System requirements

The LV-SDS Halcon driver is currently available in versions for Windows and Linux operating system. It can be used under all flavors of these operating systems that are supported by both the LV-SDS and Halcon. Check also the architectures and environments (especially compiler versions) supported by LV-SDS and Halcon. Detailed information about LV-SDS system requirements is provided in Installation and configuration guide. System requirements for the Halcon and ActivVisionTools libraries are listed on the MVTec Software GmbH website.

The LV-SDS Halcon driver is available for all Halcon versions from 5.2 and higher. It is however recommended to use the latest Halcon version whenever possible.

1.2. Installation

The LV-SDS Halcon driver is installed as a part of regular LV-SDS installation, which is described in Installation and configuration guide.

1.2.1. Windows

Under Windows, it is necessary to explicitly check the “Halcon support” option during the LV-SDS setup.

The corresponding .dll files are installed in the LVSDSHOME\bin, where LVSDSHOME is LV-SDS installation directory, C:\LVSDS by default. The bin directory is added to the system path as required, so that the Halcon loader can find the libraries. The files are named HFGLeutron.dll (interface for Halcon versions 6 and higher), respectively parHFGLeutron.dll (the same for Parallel Halcon). Other .dll file names (100% compatible) might also be available to keep backward compatibility with older applications.

Additionally, the Halcon driver libraries (Leutron.dll and others) for Halcon version 5.2 are installed in LVSDSHOME\3rdParty\Halcon\5.2\bin directory. Please copy them manually to LVSDSHOME\bin if you are actually using Halcon 5.2.

1.2.2. Linux

Under Linux, the Halcon driver is always installed automatically.

The corresponding .so files are installed in the /usr/lib/lvsds directory and links to them are additionally created in /usr/lib as required, so that the Halcon loader can find the libraries. The files are named HFGLeutron.so (interface for Halcon versions 6 and higher), respectively Leutron.so (interface for Halcon version 5.2). Other .so file names (100% compatible) might also be available to keep backward compatibility with older applications.

It is important to remember, that Linux LV-SDS (and thus also its Halcon driver) is available in variants for multiple versions of the gcc compiler (that are not mutually binary compatible). You can notice multiple .so file versions installed. The basic .so file names (such as HFGLeutron.so) are always links pointing to the actual version of the Halcon driver library compatible with gcc compiler version that was “default” at the time of LV-SDS installation (the version is determined by calling gcc --version).

This version, however, might not be actually supported by Halcon itself. The links might also become out of date when you update the gcc compiler version on your system. Whenever one of these cases apply or if you need to use a particular (“non-default”) gcc version, please update manually the library links used by your Halcon application (usually HFGLeutron.so) so that they point to the library compatible with the compiler.

See more information about the supported gcc versions in Installation and configuration guide.

1.3. Feature overview

The LV-SDS Halcon driver supports image acquisition from all kinds of Leutron Vision hardware, namely from all families of the frame grabber such as PicPort®-CameraLink or PicPort®-Elite and from our “bus” cameras, such as PicSight®-GigE cameras with Ethernet interface and PicSight®-USB cameras with USB interface. Most of the functionality of these products can be controlled from the Halcon interface. The main features include:

Support for all types of Leutron Vision hardware using a common programming interface
Halcon synchronous (grab_image()) and asynchronous (grab_image_async()) grabbing with multiple buffers per grabber to guarantee maximum throughput
Various acquisition modes supporting different functionality:
- basic mode for simple image acquisition with a “free running” camera (without triggers)
- asynchronous reset mode supporting flexible acquisition and shutter time control using external hardware triggers or software triggers
- more
Advanced settings and control over the hardware's general purpose I/O and optocouplers
Bayer decoding by means of hardware (when supported by the given model) or software
Access to additional hardware preprocessing capabilities such as color correction, white balance etc.
Control of image properties: shutter time, gain, software image cropping etc.
Serial communication with Camera Link cameras
Automatic mode adjustment for PicSight®-GigE and PicSight®-USB cameras

1.3.1. Limitations

The Halcon driver implements all Halcon's frame grabber related operators with exception of grab_region(), grab_region_async(), set_framegrabber_lut() and get_framegrabber_lut(). Preprocessing functions of Leutron Vision hardware products, equivalent to the LUT usage, are however implemented by other means, through more elaborate parameter settings.

It might happen that some of the very latest LV-SDS features are not always immediately supported by the Halcon driver. In most cases, however, the important features are soon implemented in the Halcon driver interface as well. In case you feel some important functionality is missing, please contact Leutron Vision for the latest information.

1.4. Underlying LV-SDS implementation

For users familiar with LV-SDS programming it might be useful to know that the Halcon driver is fully implemented using the Sequencer DRAL API. This might help understanding the functionality of its interface, Halcon driver just allows to access the standard Sequencer DRAL features using Halcon interface. It also might help with troubleshooting – when something does not work as expected, it can be a good idea to verify (for example using one of our test programs), if the same functionality works well with the pure Sequencer DRAL interface.

It is also important to understand that the Halcon driver is kind of “bridge” between the Sequencer DRAL API and Halcon frame grabber integration API. Linking these two distinct interfaces led necessarily to some compromises. For example to obtain a Halcon frame grabber handle, you use the open_framegrabber() operator, which allows to specify some basic parameters, such as grabber and camera names or connector number. On the other side, to fully initialize a Sequencer DRAL application, it might be necessary to supply many more parameters, which is not possible through the simple open_framegrabber() call. For example to change the acquisition mode to “asynchronous reset” or to adjust the I/O configuration, you need to use additional calls to the set_framegrabber_param() operator. Because these parameters are essential for the Sequencer DRAL library, they must be specified before application initialization and not freely at runtime. When setting them from Halcon, the internal Sequencer DRAL object needs to be re-initialized, which in turn can take a while (notably longer than setting some simple runtime parameters such as shutter time). It is thus advisable to adjust all the basic application parameters in the beginning of the application. Otherwise you need to be ready for certain delays.

Nevertheless, these limitations affect only the initialization procedure. The runtime performance of the Halcon driver is well optimized and does not introduce any unnecessary delays or bottlenecks.

1.5. Distributed sample code

Lots of samples showing how to use various functionality of the Leutron Vision hardware and software from Halcon applications are installed in LVSDSHOME/3rdParty/halcon/scripts. All the samples are actually a simple HDevelop scripts, each usually demonstrating one particular feature or usage of one particular type of hardware (frame grabber or camera). Every script includes also a brief comment describing its purpose.

When searching for a sample showing usage of a particular feature or parameter setting, please search across all the scripts in the directory for the name of the given parameter. The set of scripts is ever growing and thus we do not maintain list of the samples in this document.

We provide no C/C++ samples for Halcon, they would be identical to the HDevelop scripts. HDevelop is also more suitable for testing and experimenting with the new functionality in an interactive way.

1.6. Troubleshooting

When solving any issues with your Halcon applications using Leutron Vision hardware, please try to determine, whether your problem is related to the Halcon library itself and its use or whether it is related to the hardware interface. For issues related directly to the Halcon, please contact MVTec Software GmbH. When solving issues related to the Leutron Vision hardware and its Halcon driver interface, please follow the steps suggested below:

Enable the Halcon do_low_error system parameter through the set_system() operator so that additional low level diagnostics can be output. Save those messages to send them with other log files to our support team.
```
set_system ('do_low_error', 'true')
```
Enable logging of the LV-SDS Halcon driver.
```
[Halcon]
EnableLog=1
```
The log messages will be sent to the LV-SDS core log file, prvphlib.log. Send the log file generated during the problematic session away to be sent later to our support team.
Create the minimal HDevelop script demonstrating the problem. It will help us to reproduce the problem quickly and easily.
When working under Windows, try to reproduce the problem using the PicPort® and PicProdigy® demo program delivered with LV-SDS. Use its interface for real-time tasks (based on Sequencer DRAL) and use, if possible, the same configuration as when accessing the hardware from Halcon. The user interface of PicPort® and PicProdigy® demo is intuitive and it should not be a problem to jump in using it immediately. Reproducing the problem in PicPort® and PicProdigy® demo can help as a confirmation that the problem is in our interface rather than in your code.
Follow all the additional general purpose troubleshooting guidelines listed in Support and troubleshooting guide, collect the required log files, then contact our support team.

2. Interface description


	The brief examples given in the text below use the HDevelop syntax. If a string parameter does not fit well to a single line, its first part is ended with a backslash character (“`\`”) to indicate that the string continues on the next line. To get more complete examples of use of the individual parameters, search the Halcon samples distributed with LV-SDS.

2.1. Opening the grabber handle

The grabber handle is in Halcon opened using the open_framegrabber() operator. Very similar rules apply, no matter whether you are working with a camera connected to Leutron Vision frame grabber board, such as PicPort®-CameraLink or PicPort®-Elite, or whether you are acquiring directly from one of the “bus” camera types, such as PicSight®-GigE or PicSight®-USB.

All the parameters accepted by the open_framegrabber() operator are discussed below with information how to use them with different hardware models. For detailed description of the open_framegrabber() operator, please refer to the Halcon documentation.

Name

Use 'Leutron'for 32bit Windows and 'Leutron64' for 64bit Windows. Other names are also recognized for backward compatibility, but we recommend to use always 'Leutron' / 'Leutron64'

HorizontalResolution

Use the default value: 1.

It is possible to use also values 2 or 4 in which case the image will be hardware cropped to half or quarter horizontal resolution. Note that this operation is cropping the image, not scaling.

VerticalResolution

Use the default value: 1.

It is possible to use also values 2 or 4 in which case the image will be hardware cropped to half or quarter vertical resolution. Note that this operation is cropping the image, not scaling.

ImageWidth

Use the default value: 0.

This parameter is currently not used with the new Leutron Vision hardware products. However, similar goal can be achieved (by means of software image cropping) using the image_width parameter passed to the set_framegrabber_param() Halcon operator.

ImageHeight

Use the default value: 0.

This parameter is currently not used with the new Leutron Vision hardware products. However, similar goal can be achieved (by means of software image cropping) using the image_height parameter passed to the set_framegrabber_param() Halcon operator.

StartRow

Use the default value: 0.

This parameter is currently not used with the new Leutron Vision hardware products. However, similar goal can be achieved (by means of software image cropping) using the start_row parameter passed to the set_framegrabber_param() Halcon operator.

StartColumn

Use the default value: 0.

This parameter is currently not used with the new Leutron Vision hardware products. However, similar goal can be achieved (by means of software image cropping) using the start_column parameter passed to the set_framegrabber_param() Halcon operator.

Field

Ignored.

BitsPerChannel

Number of bits per channel for the acquired image. Possible values are 8 to 16 for monochrome images (ColorSpace is 'gray'), and 8/10/12 for color images (ColorSpace is 'rgb'). For color images the BitsPerChannel parameter specifies number of bits fore every color (R/G/B) channel. Default is 8.

Note that not all image output formats are supported on all hardware models and their firmware versions. For example to use the 3×10-bit or 3×12-bit color (RGB) image acquisition, you need a frame grabber board with the “RGB split” functionality that can deliver the image data in separate color planes. You can learn more about this topic in the Daisy manual.

For monochrome acquisition, the result image depends on both the BitsPerChannel parameter value and the original bit depth used by the camera. More information about how these two values are combined together when producing the final output image can again be found in the Daisy manual.

ColorSpace

Use 'gray' or 'raw' to acquire monochrome or 'rgb' to acquire RGB color image into the Halcon image object(s). Default is 'gray'.

When using Bayer encoded cameras, selecting 'rgb' switches on the software Bayer decoding. Selecting 'raw' does not switch it on and the raw non-decoded image is delivered to Halcon. Selecting 'gray' switches the decoding on, but the decoded image is then converted back to monochrome format (but now fine-interpolated, without the Bayer mosaic artifacts).

When using a hardware model (frame grabber or camera) with hardware Bayer decoding capability, the image is decoded by means of hardware in any case. Selecting 'gray' or 'raw' then converts this decoded image to monochrome format.

For other than Bayer encoded cameras, 'gray' and 'raw' have always same meaning.

Gain

Ignored.

ExternalTrigger

Use 'true' or 'false' to activate or deactivate the use of external triggers. Default is 'false'. This setting can be later changed through the external_trigger parameter passed to the set_framegrabber_param() Halcon operator.

CameraType

Name of the LV-SDS camera definition that should be used for the acquisition. This must be a valid name of a camera definition from LV-SDS camera database maintained by the Camera Editor application. The definition can be either one delivered with LV-SDS or a user defined one. There is no reasonable default value possible, user has always select the camera type explicitly.

Device

A string describing the LV-SDS “grabber” user for acquisition. The string consists of two parts, the name of the “grabber” recognized by LV-SDS and its order (starting with 1) to distinguish possibly multiple grabbers of the same name located in the system. Both parts, the grabber name and its order number, are compulsory and they have to be separated by a colon. An example of the Device parameter string value can thus be 'PicPortExpress CL Stereo:1'.

Note that the “grabber” in LV-SDS is an abstraction for an acquisition device, a device controlling the acquisition. This can refer either to an actual frame grabber board or to a “bus” camera (PicSight®-GigE or PicSight®-USB). See more info about LV-SDS grabbers, cameras and connectors in the Daisy manual. It provides also a section with advice about the LV-SDS grabber naming conventions

and how to find out the proper grabber name recognized by LV-SDS.

When using frame grabber boards, multiple grabbers of the same name can be installed in the system. The order in which they are discovered in the system by LV-SDS is guaranteed to be the same unless you change the hardware configuration (plug them to different PCI slots). They are discovered in the order in which they appear on the PCI bus. To distinguish between them, you should use the grabber order number, for example 'PicPortX Elite 16:1' and 'PicPortX Elite 16:2'.
When using the “bus” cameras, PicSight®-GigE or PicSight®-USB, you should assign every camera a unique nickname and use the grabber name based on the nickname, such as 'PicSight Nickname:1', where Nickname should be replaced with the real nickname assigned to the camera. Refer to the PicSight®-GigE getting started resp. PicSight®-USB getting started manuals to learn how to assign a nickname to the camera. If you enter device name properly and you have not all of the PicSight®-GigE / PicSight®-USB cameras named with the same name, is possible to enter 'auto' in the CameraName field — when entered 'auto' the proper camera will be selected by looking all of the connected cameras for the entered Nickname and the first one will be used.
Contrary to the frame grabber boards, with the “bus” cameras there is no guarantee in which order they will be discovered in the system by LV-SDS. You should thus always use a unique nickname for every camera and the grabber order number should be always 1.
You should always avoid using the generic grabber names 'GigE:1' and 'USB:1' because there would be no way to distinguish between multiple cameras of the same type using the port number, because of the unknown order of the cameras in the system. This attitude can only be safely used when just a single camera of the same type is always connected to the system.

Port

Number of connector on the “grabber” where the camera is connected (starting with 1). Default is 1.

For a PicSight®-GigE or PicSight®-USB camera the port number should be always 1.
For camera connected to a PicPort®-CameraLink frame grabber the port number can be 1 or 2 (for board types featuring two Camera Link inputs). For medium Camera Link cameras it is always 1.
For camera connected to a PicPort®-Elite frame grabber the port number can be from 1 to 16 (starting from the first input on “connector A” to the last input on “connector B”).

LineIn

Ignored.

FGHandle

Variable that will hold the opened grabber handle upon successful finish of the open_framegrabber() call.

2.2. Controlling acquisition parameters

Having a valid Halcon grabber handle, you can access additional parameters controlling all the different aspects of image acquisition. These parameters can be accessed through set_framegrabber_param() and get_framegrabber_param() Halcon operators. If not explicitly stated otherwise, the parameters can be used with both functions, i.e. they can be both written and read. If not explicitly stated otherwise, the parameters are available for all types of Leutron Vision image acquisition hardware.

Just a single parameter can be written/read using the Halcon set_framegrabber_param() and get_framegrabber_param() operators. Because in some cases it is useful (for performance reasons and for clarity) to pass multiple values through a single set_framegrabber_param() call, those multiple values need to be “encoded” in a single string parameter. The string is composed from a colon-separated tokens, one for each parameter value. The tokens usually consist of the value name followed by a space and the value itself. An example of such string could be “BaudRate 9600:DataBit 8:Parity N”.

Because the Leutron Vision Halcon driver is just a wrapper on top of the lower level LV-SDS libraries, its functionality is actually a subset of the full LV-SDS functionality. If description of some of the parameters seems to brief, incomplete or not clear enough, you can search for more details in documentation for the low level LV-SDS libraries, especially in the Daisy manual and in the Sequencer DRAL manual.

2.2.1. Acquisition mode

There are two main acquisition modes supported, the “default” mode, when the camera itself is not triggered (it runs in so called “free running” mode) and the “asynchronous reset” mode, when the camera is controlled using the hardware triggers. In both modes it is still possible to synchronize the acquisition with external devices. This section describes the acquisition_mode parameter allowing to change the basic acquisition mode as well as other related parameters allowing to further refine the acquisition mode properties.


	Some other acquisition modes were used with our legacy hardware models (especially older analog frame grabbers). These modes make sense with the current hardware and they are now obsolete.

acquisition_mode

The acquisition mode you want to use for grabbing. Possible values are 'default' (for applications with free running camera) and 'async_reset' (for applications using a camera working in a triggered mode). To learn more details about the asynchronous reset mode, please refer to the Sequencer DRAL manual.

In case of the asynchronous reset mode, the value string may be optionally extended by additional parameters, separated by colons, for example

set_framegrabber_param (FGHandle,
          'acquisition_mode',
          'async_reset:ShutterType Mode_1:AR_ShutterTime 1000')

The possible additional parameters for the asynchronous reset mode are:

ShutterType

Asynchronous reset mode of the camera that should be used for the acquisition. The value might be one of the eight strings, 'Mode_0' to 'Mode_7', referring to corresponding modes defined in the LV-SDS Camera Editor database. Default is 'Mode_0'. Refer to the Camera Editor manual if you need more information about LV-SDS camera definitions and their asynchronous reset modes.

Remember, that you might still need to adjust the camera to proper working mode corresponding with the mode selected through the ShutterType parameter. This applies especially to the Camera Link cameras, that can be adjusted by sending proper commands over the serial communication interface using the camera_cmd parameter. The PicSight®-GigE and PicSight®-USB cameras are adjusted automatically.

AR_ShutterTime

Shutter time in microseconds. Please note this parameter is effective only if the camera is working in a programmable shutter mode, e.g. in pulse width mode, where the shutter time is controlled by the trigger duration.

In other modes, the shutter time has to be set by different means, depending on the camera time (e.g. by sending a camera specific command string to a Camera Link camera using camera_cmd parameter or by adjusting a PicSight®-GigE/PicSight®-USB camera using the exposure_time parameter.

AR_FlashEnable

Value of 1 enables the flash (strobe) output, value of 0 disables it. The flash output can be configured using the io_outconfig_x parameter with the 'DralOutput' output function.

AR_CamRstDelay

Delay between the “logical” acquisition start and the effective acquisition trigger used by the camera. Note that the flash output is not delayed, just the camera acquisition. The parameter can be thus used in situations when the flash device is too slow and when the image would be acquired before the flash light goes off. Delaying the camera acquisition can put the camera and flash in sync.

The delay should be specified in number of lines for area scan cameras and in microseconds for line scan cameras.

external_trigger

Activate or deactivate external triggering. Possible values are 'true' and 'false', the default is 'false'.

When switched off, no external triggers are considered, the acquisition is controlled purely by software triggers. When switched on, the acquisition is synchronized to an external trigger (which can be configured through the io_inconfig_x parameters). In this case, the request for the new image using grab_image() or similar function sets the hardware in a status waiting for an external trigger. The real acquisition starts when the trigger arrives.

ar_runtime_param

Allows to control some runtime parameters available in the 'async_reset' acquisition mode. Some of them might be also controlled directly within the acquisition_mode parameter. However, that parameter is intended only for changing acquisition mode and it can be time consuming. Using the ar_runtime_param is fast and it can be used frequently during the sequence acquisition.

The individual parameters can be passed as usual in a colon-separated string. Currently supported parameters are:

AR_ShutterTime

grab_timeout

The timeout value in milliseconds for image grabbing. When new image is requested by the application using the grab_image() or grab_image_async() function and when it does not arrive within the specified timeout, the function stops waiting and returns an error. Note that this timeout might occur because of a problem with acquisition (camera not connected or not acquiring properly) or also because an external trigger (if used) did not arrived in time and thus the camera could never start acquiring.

The value must be greater than zero. The default value is 5000. The INFINITE waiting is not possible to set (is possible to set the MAX_INT value, it is 2.147.483.647 )


	Do not confuse this parameter with the `MaxDelay` parameter of the Halcon `grab_image_async()` function. That parameter has different meaning, it sets the maximum acceptable age of an image acquired asynchronously before. See Halcon documentation.

start_async_after_grab_async

By default, at the end of the grab_image_async() function a new asynchronous grab is automatically started, as suggested by Halcon documentation. If the parameter start_async_after_grab_async is set to 'disable' this new grab command is omitted and a new asynchronous grab should be explicitly started using grab_image_start().

Possible values are 'enable' and 'disable', the default is 'enable'.

2.2.2. Image properties

Parameters in this section allow to control various image properties, such as the image geometry (using software image cropping) or analog controls (gain or exposure time).

image_width

The width of the desired image part in pixels (0 stands for the maximum image width). This value has to be equal or smaller than the maximum image width available from the currently opened grabber handle (the maximum width depends on the camera used and on additional parameters set in open_framegrabber() call). The resulting image delivered to Halcon is software-cropped (clipped) to get the desired width.

image_height

The height of the desired image part in pixels (0 stands for the maximum image height). This value has to be equal or smaller than the maximum image height available from the currently opened grabber handle (the maximum height depends on the camera used and on additional parameters set in open_framegrabber() call). The resulting image delivered to Halcon is software-cropped (clipped) to get the desired height.

start_column

The column coordinate of the upper left pixel of the desired image part. The parameter is used together with image_width to software-crop (clip) the acquired image.

If the image_width parameter is set to 0, then both the number of columns specified in start_column will clipped away from both left and right side of the image.

start_row

The row coordinate of the upper left pixel of the desired image part. The parameter is used together with image_height to software-crop (clip) the acquired image.

If the image_height parameter is set to 0, then both the number of rows specified in start_row will clipped away from both top and bottom side of the image.

exposure_time