MVTec Software GmbH
  Building Vision For Business
Halcon

HALCON 9.0: Image Acquisition Interface for Basler GigE Vision and IEEE 1394 cameras via pylon library

This page provides the documentation of the HALCON pylon interface. Currently, the Basler ace, aviator, pilot, runner, and scout GigE Vision and IEEE 1394a/b cameras are supported by this interface. Registered customers can download the latest revision of this interface from the MVTec WWW server.

Revision: 4.14

System Requirements

  • Intel compatible PC with Windows XP/Vista/7 or Windows XP x64/Vista x64/7 x64.
  • Successfully installed pylon SDK (version 3.0).
  • GigE Vision: Successfully installed pylon GigE Vision Streaming Filter or High Performance driver.
    IEEE 1394a/b: Successfully installed pylon 1394 driver.
    Camera Link: Successfully installed pylon Camera Link driver.
  • HALCON image acquisition interface hAcqpylon.dll or hAcqpylonxl.dll, respectively. If you have properly installed the interface, both DLLs should reside in bin\%HALCONARCH% within the HALCON base directory %HALCONROOT% you have chosen during the installation of HALCON.
  • If you are using a firewall, e.g., Windows XP with Service Pack 2, please make sure that your firewall settings allow to connect to the camera, otherwise the grabbing fails.

Features

  • Multiple device support.
  • Generic parameter access.
  • Synchronous and asynchronous grabbing.
  • Cropping of image parts.
  • Decimation.
  • External trigger.
  • Software control of all acquisition parameters directly from the HALCON application.
  • Support of user-specific callback functions.
  • Support of ace and aviator cameras over Camera Link (no grabbing!).

Limitations

  • No LUTs.
  • grab_data and grab_data_async not supported.

AcquisitionMode

'AcquisitionMode' is one of the mandatory parameters of GigE Vision cameras. The HALCON pylon interface reads the current value of the camera in open_framegrabber. If you need high frame rates it is recommended to set 'AcquisitionMode' to 'Continuous'.

Description

Parameters for open_framegrabber():

Note that in case of a IEEE 1394 camera, the parameter 'PacketSize' is set to the maximum value during open_framegrabber.


Name
'pylon'
The name of the HALCON interface.
HorizontalResolution 1, 2, 4, width The desired horizontal image resolution. Use '1' for full resolution, '2' for decimation by factor 2, and '4' for decimation by factor 4. Set the horizontal resolution of the camera sensor, if no decimation is used. Default: 1.
VerticalResolution 1, 2, 4, height The desired vertical image resolution. Use '1' for full resolution, '2' for decimation by factor 2, and '4' for decimation by factor 4. Set the vertical resolution of the camera sensor, if no decimation is used. Default: 1.
ImageWidth 0, width The width of the desired HALCON image part (software cropping). '0' stands for the complete image. Default: 0.
ImageHeight 0, height The height of the desired HALCON image part (software cropping). '0' stands for the complete image. Default: 0.
StartRow 0, row The row coordinate of the upper left pixel within the desired HALCON image part. Default: 0.
StartColumn 0, column The column coordinate of the upper left pixel within the desired HALCON image part. Default: 0.
Field --- Ignored.
BitsPerChannel -1, 8, 10, 12, 16 The number of significant bits per channel. Default: 8.
ColorSpace 'gray', 'yuv', 'raw', 'rgb' Specify the desired color space and thus the number of image channels of the resulting HALCON image. Default: 'gray'.
Generic ['num_buffers=number', 'tl_type=type', -1] With the Generic parameter some important values can be set before the camera is initialized. Note that the parameter names including the values must be strings, e.g., 'num_buffers=5' sets the number of buffers to 5.
The following parameters are available:
  • num_buffers: To set the maximum number of buffers used in the HALCON acquisition interface a value greater than 1 has to be used. Note that depending on the image size of the used camera a high number of buffers can exceed the available memory size of your computer. We recommend to use at least 2 buffers. Default: 2.
  • tl_type: With this parameter the type of the desired Transport Layer can be set. Valid values are 'gev' for GigE Vision, 'iidc' for 1394IIDC, and 'cl' for Camera Link. Note: If 'tl_type' is set to another value than 'cl', open_framegrabber can be accelerated in contrast to the case that it is not set at all. If a device index is used as device name, the value of tl_type is ignored and the index is used with the list over all available devices.
Default: -1.
ExternalTrigger --- Ignored. The external trigger can be activated by  set_framegrabber_param via the parameter 'TriggerMode'.
CameraType --- Ignored.
Device UniqueDeviceID, IP address, DeviceUserID, SerialNumber, Index To open a specific camera the device name as shown in info_framegrabber(..,'device',..) has to be set. Alternatively, the IP address, the DeviceUserID or the serial number can be used. These values can be queried by calling 'info_framegrabber(..,'info_boards',..)'. Another possibility is the increasing device index, e.g., the first camera is specified by '0', the second camera by '1', etc. Default: '0'.
Port --- Ignored.
LineIn --- Ignored.

Parameters for set_framegrabber_param():

The parameters of all cameras are based on the GenApi, so they can be different for each camera. A call of info_framegrabber('parameters', InfoParameters, AvailableParameters) returns a tuple containing all available parameters of the connected camera.
To read e.g. the current gain of the camera AcqHandle refers to (after calling open_framegrabber), the user can call get_framegrabber_param(AcqHandle, 'GainRaw', Gain)
Apart from that the user can query additional information about the properties. Some might define limits like min, max or step width. These values can be queried as a list by by postfixing the parameters name with '_range' . So, to query the limits of the gain parameter the user can call get_framegrabber_param(AcqHandle, 'GainRaw_range', Gain). This might e.g. result in a list like this: [ 0, 30, 1, 5 ]. The first value indicates the minimum value for this parameter, the second value is the maximum value for this parameter, the third value is the step width and the last value is the current value.
Other parameters like the trigger source can only be set to certain values. To find out which values are valid for a certain parameter the user has to postfix it with '_values'. So to find out which values are allowed for the trigger source parameter the user has to call get_framegrabber_param(AcqHandle, 'TriggerSource_values', TriggerSources). Afterwards the variable TriggerSources will contain a list of strings defining the allowed trigger sources for this device. This list might look like this: [ 'Line1', 'Line2', 'Line3', 'Line4', 'Software' ].
Additionally to the GenApi parameters of the camera the following HALCON parameters are supported:


'bits_per_channel'
8, 10, 12, 14, 16
Specify the desired bits per channel of the HALCON image. Default: 8.
'color_space' 'gray', 'raw', 'rgb', 'yuv' Specify the desired color space of the image. You can also adapt this setting with the generic parameter 'PixelFormat'. Default: 'gray'.
'do_abort_grab' --- Abort the current image acquisition.
'do_unlock_parameters' --- After grabbing an image the parameters regarding the image size and position are locked. This parameter unlocks them.
'grab_timeout' msec Specify the desired timeout (milliseconds) for aborting a pending grab. Default: 5000.
'image_height' height The height of the HALCON image (software cropping). Please note that the value of this parameter is overwritten, if 'Height' is set afterwards.
'image_width' width The width of the HALCON image (software cropping). Please note that the value of this parameter is overwritten, if 'Width' is set afterwards.
'start_async_after_grab_async' 'disable', 'enable' By default, at the end of grab_image_async a new asynchronous grab command is automatically given to the acquisition device. If the parameter 'start_async_after_grab_async' is set to 'disable' this new grab command is omitted. Default: 'enable'.
'start_column' column The upper left pixel of the HALCON image.
'start_row' row The upper left pixel of the HALCON image.
'volatile' 'enable', 'disable' Grayscale only. In the volatile mode the two image buffers are used directly to store HALCON images. This is the fastest mode avoiding to copy raw images in memory. However, be aware that older images are overwritten again and again as a side-effect. Thus, you can only process one image while you grab another image. Older images are invalid! Default: 'disable'.

Parameters for get_framegrabber_param():

Additional parameters supported by get_framegrabber_param only. Note that all parameters supported by set_framegrabber_param except the ones with prefix 'do_' can also be accessed by get_framegrabber_param. Furthermore, corresponding to the parameters supported by set_framegrabber_param, there may exist additional read-only parameters with the following postfixes:

  • '_access': These parameters provide the access permissions of the corresponding parameter as a string. Possible values are 'ro' (read-only), 'wo' (write-only), and 'rw' (read/write).
  • '_category': These parameters provide the category of the corresponding parameter as a string.
  • '_description': These parameters provide the tooltip of the corresponding parameter as a string.
  • '_range': These parameters provide the minimum, maximum, step width, and default values for the corresponding integer or float parameter as a tuple with 4 elements, e.g., get_framegrabber_param(..,'Shutter_range',..) will return the output tuple [min,max,step,default]. Optionally, this tuple can also contain additional valid string values like 'auto' or 'manual'.
  • '_values': These parameters provide the valid value list for the corresponding parameter as a tuple, e.g., get_framegrabber_param(..,'volatile_values',..) will return the output tuple ['enable','disable'].
  • '_visibility': These parameters provide the visibility of the corresponding parameter as a string. Possible values are 'beginner', 'expert', and 'guru'.
All these postfixed parameter names are not returned when calling info_framegrabber(..,'parameters',..) and are used to enable the easy parameterization via a generic graphical user interface, particularly the HDevelop Image Acquisition Assistant.


'available_callback_types'
callback_type (string)
Returns a list containing the device-specific callback types.
'available_param_descriptions' descriptions (string) Returns a list containing additional information about all parameters. The order of the entries is equal to the order of the parameter names returned by 'available_param_names'.
'available_param_names' parameters (string) Returns a list containing the names of all available parameters.
'image_available' 0, 1 (integer) Returns the status of the last asynchronous grab command. The value 1 means that the image is already acquired and thus can be fetched by grab_image_async without delay. Note that this parameter is especially useful in combination with external triggering.
'num_buffers' number (integer) The number of buffers used in HALCON.
'revision' revision (integer) The revision number of the HALCON pylon interface.
'tl_type' type (string) The used Transport Layer of the device:
  • 'gev': GigE Vision TL
  • 'iidc': 1394IIDC TL
  • 'cl': Camera Link TL

Parameters for set_framegrabber_callback():

The following callback types are supported by this interface:

'device_removal' Corresponds to the device removal notification as described in the pylon documentation.
'exposure_end' Corresponds to the 'ExposureEndEventTimestamp' GenApi node. If this GenApi node is updated the user-specific function will be called. Note that calling grab_image or grab_image_async is not allowed inside the user-specific function. Please create a seperate thread to actually acquire the images, otherwise a dead-lock situation will occur.

Attention:To activate or deactivate the device-specific callbacks, the corresponding device-specific event has to enabled or disabled, too. This can be done by setting the GenApi parameter 'EventSelector' to the specific event type, and the 'EventNotification' parameter to 'GenICamEvent'.

All actually supported callback types of a specific image acquisition device can be queried by calling get_framegrabber_param with the parameter 'available_callback_types'. Once the callback is registered and the underlying event is activated, on every occurrence of the event (e.g., the notification that the exposure has finished) the specified callback function will be called. If the callback function is set to NULL, the corresponding callback will be unregistered. Please remember to deactivate the underlying event first.

The signature of the callback function is Herror (__stdcall *HAcqCallback)(void *AcqHandle, void *Context, void *UserContext) and uses the following parameters:
AcqHandle Acquisition handle of the corresponding image acquisition instance.
Context Optional context data of the specific callback. In case of the 'device_removal' callback, this parameter returns a device-specific string to identify the device that has been lost. In case of the 'exposure_end' callback, this parameter is not used, i.e., Context is set to NULL.
UserContext User context as set via set_framegrabber_callback.

Using user-callback functions

Note that the execution time of a user-specific callback function must always be as short as possible since during the execution of a callback function the handling of further internal callbacks might be blocked or ignored. This can be achieved by removing the actual processing from the user-specific callback function to a separate thread that is controlled via signals or events. The callback function is executed in the context of the underlying interface or driver.

Release Notes

  • Revision 4.14 (Apr 30, 2012):
    • Adapted to pylon SDK 3.0.
    • Improved error handling in cleaning up the acquisition callbacks.
  • Revision 4.13 (Feb 6, 2012):
    • Fixed bug in grab_image_async. The wrong image was returned, if the grabbed image was too old regarding the parameter MaxDelay (maximum tolerated delay between the start of the asynchronous grab and the delivery of the image).
  • Revision 4.12 (Nov 29, 2011):
    • Added Generic parameter 'tl_type' to accelerate open_framegrabber, if no Camera Link device is used.
    • Added read-only parameter 'tl_type'.
  • Revision 4.11 (Nov 11, 2011):
    • Fixed problem in close_framegrabber if the 'expsoure_end' callback function was registered.
    • Fixed overwritten memory in open_framegrabber if the device was opened with a serial number.
    • Fixed problem when trying to open a device via a device number.
    • Fixed color conversion of >8 bit/pixel Bayer formats, which could also lead to a crash.
  • Revision 4.10 (Sep 12, 2011):
    • Added support for Basler Camera Link cameras. Please note that it is not possible to grab images, just the configuration of the camera parameters is supported.
    • Removed setting of external trigger parameters in open_framegrabber.
  • Revision 4.9 (Jul 25, 2011):
    • Added functionality to handle 'device_removal' and 'exposure_end' callbacks.
    • Fixed wrong return value of parameter 'image_available'.
    • Fixed bug when changing the AOI of the camera by setting the 'Width' and 'Height' parameters. If the size was set to a larger value the size of the returned HALCON image remained small.
    • Fixed problem when trying to open a IEEE 1394 camera with its full name.
    • Changed behavior of the Horizontal/VerticalResolution parameters in open_framegrabber. Now, the maximum of the parameter 'Width'/'Height' is also queried for determining the maximum image size.
  • Revision 4.8 (Apr 14, 2011):
    • Fixed crash in open_framegrabber with pylon SDK 2.3.3 which occurred if a Camera Link board was installed.
    • Added possibility to open a device via its IP address, DeviceUserID or serial number. In this context the returned output parameters of info_framegrabber(...,'info_boards',...) and info_framegrabber(...,'device',...) have been adapted accordingly.
    • Added missing read-only parameters with postfix '_description' to query the tooltip for each parameter.
    • Improved software cropping via parameters 'image_width' and 'image_height'.
  • Revision 4.7 (Mar 15, 2011):
    • Fixed general problem when reading TransportLayer or StreamGrabber parameters.
    • Added version check for correct pylon version.
    • Improved color conversion for YUV pixel formats.
  • Revision 4.6 (Oct 25, 2010):
    • Adapted to pylon SDK 2.3.
    • Fixed crash of application if an error occurs when trying to grab an image.
    • Fixed problem regarding querying the parameter descriptions, in particular to ensure the correct display of parameter tooltips in the HDevelop Image Acquisition Assistant.
    • Added access to non-integer parameters for the TransportLayer and StreamGrabber node map.
  • Revision 4.5 (Sep 10, 2010):
    • Fixed problem when changing image size after setting parameter 'do_unlock_parameters', which in some cases caused a crash.
    • Added support for parameter 'UserSetLoad'.
    • Added parameter 'num_buffers'.
    • Improved re-allocating of the image buffers, which is now only done if necessary.
    • Changed behavior regarding the parameter 'AcquisitionMode'. In older versions, open_framegrabber set this value to 'SingleFrame'. Now the current value of the camera is used instead.
  • Revision 4.4 (Apr 28, 2010):
    • Adapted to pylon SDK 2.2.
    • Fixed problem with setting the parameter 'AcquisitionMode' to 'SingleFrame', when this mode was already set.
    • If acquisition mode was set to 'SingleFrame', grab_image and grab_image_async returned old images. This problem has been solved.
    • Added implementation of info_framegrabber(..,'generic',...) to query all supported values for the Generic parameter in open_framegrabber.
  • Revision 4.3 (Feb 12, 2010):
    • Fixed crashes caused by wrong device names.
    • When using an external trigger in continuous grabbing mode, the first call of grab_image or grab_image_async always returned an image even if there was no trigger signal. This bug has been fixed.
  • Revision 4.2 (May 25, 2009):
    • Adapted to pylon SDK 2.1.
    • Added additional parameters with postfixes '_access', '_category', and '_visibility' to query access mode, category name, and visibility of a specific parameter.
  • Revision 4.1 (Mar 5, 2009):
    • Bug fix in Generic parameter 'num_buffers'.
    • Bug fix regarding mutex and parameter 'do_abort_grab', which could have caused a deadlock. Furthermore, the parameter now also works, if no image was grabbed before.
    • Bug fix in parameter 'volatile' in case of enabling it twice.
    • Adapted set_framegrabber_param to allow also integer values for parameters with float values and vice versa.
  • Revision 4.0 (Dec 10, 2008):
    • HALCON 9.0 version of the interface (included in HALCON 9.0 DVD).
    • Support of Windows XP x64.
    • Bug fix in grab_image and grab_image_async for multiple camera configurations. Furthermore, the error message "Wrong color space" now only appears, if there is no valid color space conversion available.
    • Bugfix in grab_image and grab_image_async in case of errors during the image acquisition (not in all cases the buffer was re-queued correctly).
    • Added a mutex to protect the buffer queue during image acquisition in multithread applications.
  • Revision 3.7 (Jul 15, 2008):
    • Bug fix in open_framegrabber regarding the device names.
    • Bug fix using multiple devices.
    • Added parameter 'bits_per_channel'.
  • Revision 3.6 (May 30, 2008):
    • Bug fix in color transformation.
    • Bug fix in open_framegrabber. Now the device name can also be the full name of the device.
    • Bug fix in close_framegrabber. Now the device is also closed correctly when no image was acquired so far.
    • Bug fix in info_framegrabber. If using multiple Basler cameras, the HDevelop Image Acquisition Assistant now lists all of them.
    • Bug fix regarding GenICam enumeration values. Now only the actually supported values are listed.
    • Added software cropping functionality. Thus, the behavior of the parameters 'image_width', 'image_height', 'start_row', and 'start_column' in open_framegrabber changed. These parameters now are only used for specifying the size and position of the resulting HALCON image and can also be used dynamically via set_framegrabber_param or get_framegrabber_param.
    • Removed parameter 'available_param_types'.
    • Added categories for the generic parameters.
  • Revision 3.5 (Apr 22, 2008):
    • Adapted to pylon SDK 2.0.
    • Added color transformation functionality, i.e., depending on the parameter ColorType the resulting HALCON image of each grab is converted accordingly.
    • Bug fix in continuous grabbing mode.
  • Revision 3.4 (Oct 15, 2007):
    • Bug fix in grab_image_start and grab_image.
  • Revision 3.3 (Sep 20, 2007):
    • Bug fix in grab_image and grab_image_async.
    • Bug fix in software trigger function.
    • Bug fix in 'raw' color space.
  • Revision 3.2 (Sep 5, 2007):
    • Bug fix in first usage of grab_image_start.
    • Improved buffer handling for external triggering.
  • Revision 3.1 (Jul 27, 2007):
    • Adapted to pylon SDK 1.0.
    • Bug fix in grab_image/grab_image_async in case of incomplete images.
    • Bug fix in open_framegrabber regarding external triggering and maximum image size.
    • Removed setting of the parameter 'ExposureTimeRaw' during open_framegrabber.
  • Revision 3.0 (May 15, 2007):
    • HALCON 8.0 version of the interface (included in HALCON 8.0 DVD).
  • Revision 2.2 (Mar 28, 2007):
    • Added access to the parameters of the TransportLayer and StreamGrabber node map.
    • Added string prefix 'device:' to info_framegrabber(...,'info_boards',...).
    • Added parameter 'start_async_after_grab_async'.
  • Revision 2.1 (Feb 21, 2007):
    • Adapted to pylon SDK 0.9.
    • Added support of the scout IEEE 1394a/b cameras.
    • Added support of color images.
    • Added parameters 'color_space', 'color_space_values', and 'volatile_values'.
    • Fixed bug in info_framegrabber and open_framegrabber which led to problems if a device was closed and reopened again.
    • Fixed bug in grab_image(_async) which caused a black image after changing image-specific parameters.
  • Revision 2.0 (Nov 3, 2006):
    • First official release.


© Copyright 2012, MVTec Software GmbH, corporate/legal/privacy information






Last modified: Mon Apr 30 12:03:10 CEST 2012