interfaces mvtec

Interface Documentation

Image Acquisition Interface for Teledyne DALSA Boards, Genie, and Spyder3 Cameras via Sapera LT library

Interface: SaperaLT
Revision: 13.0.5
Date: 2018-21-12

General

This page provides the documentation of the HALCON SaperaLT interface for digital frame grabber boards like Xtium, Xcelera, and X64-CL, and also the Genie and Spyder3 GigE Vision camera series from Teledyne DALSA. Registered customers can download the latest revision of this interface from the MVTec WWW server.

System Requirements

  • Intel compatible PC with Windows 7 (32-bit or 64-bit) or newer that is also supported by the vendor-specific SDK.
  • Successfully installed Sapera LT software library (version 8.0 or higher) as well as the camera configuration and demo executable CamExpert. Make sure that the environment variable %SAPERADIR% is set correctly to the particular installation directory.
  • For using the HALCON SaperaLT interface you need a valid .ccf file for your specific framegrabber configuration, which must be created using the Teledyne DALSA CamExpert application. If you are using multiple cameras connected to the same framegrabber a configuration file for each camera must be provided when open, using the same file is not allowed. Note: The configuration file is a text file in DALSA's format and must not be edited. You can then modify the device settings using the interface once it is open.
  • HALCON image acquisition interface hAcqSaperaLT.dll or hAcqSaperaLTxl.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.
  • Genie cameras: Successfully installed Genie Framework (version 1.60 or higher) or Genie TS Framework (version 1.10 or higher) for SaperaLT and Sapera Network Imaging Package (version 1.82 or higher).
  • Spyder3 cameras: Successfully installed Genie TS Framework (version 1.10 or higher) for SaperaLT and Sapera Network Imaging Package (versions 1.10 or higher).

Installation

Only when installing or updating the interface manually follow these steps:
  • Windows: Extract the archive containing the interface files to the HALCON base directory %HALCONROOT% (Note: Administrator privileges may be required for this step). Additionally, you have to move the interface examples to the directory %HALCONEXAMPLES% manually.

Features

  • Synchronous and asynchronous grabbing.
  • Support of multiple cameras and multiple boards.
  • Support of a wide range of area and line scan cameras varying among the different models of Teledyne DALSA frame grabber boards.
  • External trigger and asynchronous camera reset.
  • Cropping of image parts.
  • Setting of lookup tables.
  • Software Bayer decoding.
  • Software control of a wide range of configuration parameters.
  • Support of user-specific callback function.
  • Support of general I/Os.
  • TurboDrive.
  • Support of firmware that allows multiple cameras connected to the same board.

Limitations

  • Genie Framework doesn't support parameter 'num_buffers'.
  • Support of YUV format only with Genie TS Framework and GigE Vision camera.
  • GigE Vision cameras: No support of BayerXXPacked, BGRXXPlanar, and RGBXXPlanar pixel formats yet.
  • No support of GenCP.

Lookup tables

Lookup tables can be set using the operator set_framegrabber_lut. The SaperaLT interface uses at least 256 entries per LUT, which have to be passed as three arrays of integers. The LUT is automatically enabled, if set_framegrabber_lut is called.

Genie/Spyder3 GigE Vision cameras

With this interface Teledyne DALSA Genie and Spyder3 GigE Vision cameras can be used. All GenICam compliant devices contain a XML file, which describes the features of the device. The Standard Features Naming Convention (available here) lists all features a device must or can have. Because every device provides different parameters, we don't list them here. To get a list of supported parameters of your device call get_framegrabber_param(..., 'available_param_names', ...).

We strongly recommend not to use the following parameters, because they are handled internally: 'AcquisitionStart', 'AcquisitionStop', and 'TLParamsLocked'.
Please note that maybe not all features, e.g., Chunk Data, are supported. If you want a better support of special or newer GigE Vision features, please use the HALCON GigEVision interface.

General Input/Output (GIO)

Some Teledyne DALSA boards support General Input/Output pins, which can be configured by the Sapera LT GIO module. Since revision 5.5 the SaperaLT interface supports GIO.
The GIO pins are assembled in blocks. The number of available blocks can be queried by get_framegrabber_param(...'gio_count', ...). To choose a block of pins use set_framegrabber_param(...'do_set_gio_handle', ...). Per default all blocks are set as input. To query if the selected block can be set as output use get_framegrabber_param(..., 'gio_dir_output_range', ...) or as tri-state get_framegrabber_param(..., 'gio_dir_state_range', ...). An block can then be set to output via set_framegrabber_param(..., 'gio_dir_output', 0xF). With the parameters 'gio_state_mask' and 'gio_state' the pins can be set to HIGH or LOW. Therefore both parameters need to be set. If you want to set pins 1 and 2 to HIGH, for example, you have to call set_framegrabber_param(..., 'gio_state_mask', 0x3) and set_framegrabber_param(..., 'gio_state', 0x3). For easier use you can set the state mask to 0xF to prepare all pins.
You can also have a look at the HDevelop example saperalt_gio.hdev. If using a board with firmware that supports multiple cameras, the GIO pins are shared between the acquisition handles. If two applications threads call functions in the same module (e.g. Gio), then these calls are serialized in the Sapera LT API. However, it is the responsibility of the application to make sure that calling Sapera LT functions from different threads follows a logical order.

Parameters for info_framegrabber

Parameter Value List Type Kind Description
'bits_per_channel' [] Unused.
'camera_type' ['CAMFILE:', 'ccf', '<path>'] string pre-defined Syntax for camera configuration file.
'color_space' ['default', 'gray', 'raw', 'rgb', 'rgbx', 'yuv'] string pre-defined Values for color space.
'defaults' [1, 1, 0, 0, 0, 0, 'default', 8, 'default', -1.0, 'false', '', '0', -1, -1] mixed pre-defined Default values for open_framegrabber.
'device' ['<device_id>'] string dynamic Device names of the available devices.
'field' [] Unused.
'general' [] string pre-defined Information about the HALCON SaperaLT interface.
'generic' ['','num_buffers=<num>', 'cam_params=0'] string pre-defined Value list for the Generic parameter.
'horizontal_resolution' 1, 2, 4 integer pre-defined Value list for horizontal resolution.
'image_height' [] Unsupported query.
'image_width' [] Unsupported query.
'info_boards' ['device:<device_id>'] string dynamic A list of the available devices.
'parameters' ['<parameters>'] string pre-defined Pre-defined parameters of the HALCON interface.
'parameters_readonly' ['<parameters>'] string pre-defined Pre-defined read-only parameters of the HALCON interface.
'parameters_writeonly' ['<parameters>'] string pre-defined Pre-defined write-only parameters of the HALCON interface.
'port' [-1, 0, 1, 2, 3, 4, 5] integer pre-defined Pre-defined list of possible port numbers.
'revision' '<revision>' string pre-defined Revision number of the SaperaLT interface.
'start_column' [] Unsupported query.
'start_row' [] Unsupported query.
'vertical_resolution' 1, 2, 4 integer pre-defined Value list for vertical resolution.

Parameters for open_framegrabber

Parameter Values Default Type Description
Name 'SaperaLT' string Name of the HALCON interface.
HorizontalResolution 1, 2, 4 1 integer Desired horizontal resolution of the camera image:
  • 1: Use full resolution.
  • 2: Use half resolution.
  • 4: Use quarter resolution.
If you want to use other values for the image resolution, set it via the camera configuration file specified in the CameraType parameter. Please note that in case of an image width smaller than 8 this parameter is ignored. Also note that the value of 'ImageWidth' overwrites the value of 'HorizontalResolution', if no configuration file is set.
VerticalResolution 1, 2, 4 1 integer Desired vertical resolution of the camera image:
  • 1: Use full resolution.
  • 2: Use half resolution.
  • 4: Use quarter resolution.
If you want to use other values for the image resolution, set it via the camera configuration file specified in the CameraType parameter. Please note that in case of an image height smaller than 8 this parameter is ignored. Also note that the value of 'ImageHeight' overwrites the value of 'VerticalResolution', if no configuration file is set.
ImageWidth 0, <width> 0 integer Width of the desired image part ('0' stands for the maximum image width). This value has to be equal or smaller than the maximum image width. Note that this parameter will be ignored, if a ccf file is set as 'CameraType' parameter.
ImageHeight 0, <height> 0 integer Height of the desired image part ('0' stands for the maximum image height). This value has to be equal or smaller than the maximum image height. If the current buffer height is smaller than this parameter value the resulting HALCON image will be resized to the current buffer height. Note that this parameter will be ignored, if a ccf file is set as 'CameraType' parameter.
StartRow <row> 0 integer Row coordinate of the upper left pixel within the desired image part.
StartColumn <column> 0 integer Column coordinate of the upper left pixel within the desired image part.
Field --- Ignored.
BitsPerChannel --- Ignored (the desired pixel depth will be set accordingly to the parameter settings in the camera configuration file).
ColorSpace 'default', 'gray', 'raw', 'rgb', 'rgbx', 'yuv' 'default' string Using a frame grabber board: If not set to 'rgbx', the parameter is ignored and the desired pixel depth will be set accordingly to the parameter settings in the camera configuration file. Otherwise, a 4-channel image will be created, see also the parameter 'pixel_arrangement'. Please note that a 4-channel RGB image looks like a gray value image in HDevelop as by default only the first image channel will be displayed.
Using a GigE Vision camera: The color space for the resulting HALCON image will be automatically set. Only with Genie TS Framework the selected color space value will be set. The value 'rgbx' is only possible for frame grabber boards.
Generic ['','num_buffers=<num>', 'cam_params=0'] -1 mixed 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: Number of buffers used for the image acquisition. Note that with default buffer cycle mode one buffer is used as trash, so the effective number of available buffers for images is num_buffers - 1.
  • cam_params: Flag to enable access to the GenICam parameters of the connected framegrabber camera if available. Framegrabbers are not aware of any changes on the camera configuration at runtime because of this the following limitation need to be consider:
    • The parameters 'Width', 'Height', 'OffsetX' and 'OffsetY' are always mark as read only. Please use 'image_part' instead.
    • When changing the pixel format of the camera, the buffers are not recreated. A correct configuration file for the framegrabber must be provided, otherwise a incorrect images might be acquired. Note:It is possible that changing some of the parameters can stop the interface and the framegrabber from working correctly. Use at your own risk!
CameraType '<configuration_file>', '' '' string Specify the name (including the full path name) of the desired camera configuration file, i.e., the .ccf file. A camera configuration file can be created with the help of the camera configuration tool CamExpert; using that tool you can test and save an appropriate configuration for your camera and pass the complete file name (e.g., 'C:\Program Files\Teledyne DALSA\Sapera\CamFiles\User\myCameraConfig.ccf'). The configuration file is needed to connect to the camera and receive all basic parameters like width/height or pixel format of the image.

For GigE Vision cameras it is not necessary to use a camera configuration file (leave empty string ''). Then the needed values are queried directly from the camera and the current settings are used.
Note that the value of the parameters 'HorizontalResolution', 'VerticalResolution', 'ImageWidth', or 'ImageHeight' may overwrite the current settings of the camera, if no configuration file is set.

Device 'default', 'Genie_C640_1', 'Genie_C640-S3_1', 'Genie_M640_1', 'Genie_M640-S3_1', 'Genie_HM_640_1', 'Genie_C1024_1', 'Genie_M1024_1', 'Genie_HM1024_1', 'Genie_C1400_1', 'Genie_C1400-S3_1', 'Genie_M1400_1', 'Genie_M1400-S3_1', 'Genie_HM1400_1', 'Genie_TS-M2500', 'PC2-CamLink_1', 'Spyder_GigE_Colour_Camera_1', 'X64_1', 'X64-CL_iPro_1', 'X64-CL_Dual_1', 'X64-LVDS_1', 'Xcelera-CL_PX4_1', 'Xtium-CL_PX4',... '0' string The name of one of the desired Teledyne DALSA image acquisition device. If you have more than one device with the same name, the number at the end of the device name is counted upwards to access each device separately. If 'default' is specified, the interface will refer to the first device that can be found. A list of available devices can be queried by calling info_framegrabber(.., 'device', ...).

Please note that in case of using a GigE Vision camera without setting a camera configuration file in parameter 'camera_type' the value 'default' cannot be used as device name. A specific device name has to be set.

Port -1, 0, 1, 2, 3, 4, 5 -1 integer Specifies the number of the desired camera port (analog boards only). If -1 is selected, the port will be selected from the configuration file. In case of GigE Vision cameras this parameter will be ignored. In case of digital frame grabbers, the correct port has to be set in the camera configuration file (CCF). Note that the parameter 'port' corresponds to the Camera Selector (or parameter CORACQ_CAMSEL) of Sapera LT. When using a digital board this is not equal to the physical connector index.
LineIn --- Ignored.

Parameters for set_framegrabber_param

Parameters for Teledyne DALSA boards and Genie cameras. Please note that the Genie cameras have additional parameters, which depend on the camera model and are not listed in this manual. A list of all available parameters is returned by get_framegrabber_param(..., 'available_param_names', ...).
Parameter Values Default Type Description
'buffer_cycle_mode' 'asynchronous', 'next_empty', 'off', 'synchronous', 'synchronous_next_empty_with_trash', 'synchronous_with_trash' 'synchronous_next_empty_with_trash' string Allows you to select the used mode for buffer cycling. As default a mode with a trash buffer is used, which means that the number of image buffers is num_buffers - 1. If another cycle mode is set, acquisition is stopped and re-started. Note that an Xfer must exist to change the buffer cycle mode, which means that you have to call grab_image_start, grab_image, grab_image_async, or enable continuous_grabbing. The following modes can be set, but not every hardware supports all modes:
cycle mode description
asynchronous Always transfer to the next buffer regardless of its state.
synchronous If next buffer is empty, then transfer to next buffer, otherwise, transfer to current buffer.
synchronous_with_trash If next buffer is empty, then transfer to the next buffer, otherwise, transfer to the trash buffer. Repeat transferring to the trash buffer as long as the next buffer is full.
off Always transfer to the current buffer.
next_empty If next buffer is empty, then transfer to next buffer, otherwise, transfer to next empty buffer in the list. If all buffers are full, then transfer to current buffer.
synchronous_next_empty_with_trash If next buffer is empty, then transfer to next buffer, otherwise, transfer to next empty buffer in the list. If all buffers are full, then transfer to trash buffer. Repeat transferring to the trash buffer as long as there is no empty buffer in the list.
CorXferGetPrm -> CORXFER_PRM_CYCLE_MODE
'continuous_grabbing' 'disable', 'enable' 'disable' string If the continuous grabbing mode is enabled, the camera grabs all the time. In this mode the operator grab_image does not grab synchronously, but behaves similar to grab_image_async. Using this mode you can achieve full frame rate. If the continuous grabbing mode is disabled, the camera is set to single frame capture.
'do_abort_grab' --- Aborts the current grab.
'do_clear_buffers' -1 integer Acquisition is stopped and all queued buffers set to black and marked as empty to be available for the next grab.
'grab_timeout' <milliseconds> 5000 integer Specify the desired timeout (milliseconds) for aborting a pending grab. If -1 is specified, the timeout is set to INFINITE. Please note that in case of aborting a pending grab (when setting some parameters) or closing the device, the timeout for CorXferWait is set to 5 seconds, if an infinite timeout is set.
'image_part' [<row1, col1, row2, col2>] integer Allows you to crop a defined part of the image. In order to define a rectangular region for image acquisition, the point on the left top and the point on the right bottom have to be entered. If -1 is passed to every value, the values will be set to their default values. If a value exceeds the image size, it is set to the maximum allowable value.
'line_number' 0, 1, ... <image_height> 0 integer Allows you to select the line for the line_end callback to be signaled. This parameter has to be set before activating the callback.
'multiple_image_num' 1, 2, 3 1 integer Enables a special grabbing mode for line scan cameras. If this parameter is set to a value x (bigger than 1), grab_image splits the image in x parts. In the camera configuration file the full height has to be set. With every call of grab_image or grab_image_async the next part is returned. The next image is acquired, if all parts are returned. The parameter 'continuous_grabbing' has to be disabled to use this mode.
'num_buffers' <number> 3 integer Number of buffers used for the image acquisition. Note that with default buffer cycle mode one buffer is used as trash, so the effective number of available buffers for images is num_buffers - 1.
'start_async_after_grab_async' 'disable', 'enable' 'enable' string By default a new asynchronous grab command is automatically given to the acquisition device at the end of grab_image_async. If the parameter 'start_async_after_grab_async' is set to 'disable', this new grab command is omitted.
'volatile' 'disable', 'enable' 'disable' string Grayscale only. In the volatile mode the two image acquisition interface 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!

Parameters for get_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 tool-tip 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].
  • '_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.

Parameter Values Default Type Kind Description
'available_callback_types' ['<callback_type>'] string dynamic Query all callback types which are supported by this interface.
'available_param_names' ['<parameters>'] string dynamic In case of a Genie GigEVision camera the available parameters supported by this camera are returned. If a framegrabber board is used a list of all the available static parameters is returned and if the connected camera supports GenICam and 'cam_params' is set to 1 the interface will try to query the available parameters from the camera also.
Note: If using multiple cameras connected to the same board, the list of available parameters will correspond only to the open camera.
'bits_per_channel' '<default>' 8 integer pre-defined The value is not used, so a default value is returned.
'buffer_cycle_mode' 'asynchronous', 'next_empty', 'off', 'synchronous', 'synchronous_next_empty_with_trash', 'synchronous_with_trash' 'synchronous_next_empty_with_trash' string dynamic Allows you to select the used mode for buffer cycling. As default a mode with a trash buffer is used, which means that the number of image buffers is num_buffers - 1. If another cycle mode is set, acquisition is stopped and re-started. Note that an Xfer must exist to change the buffer cycle mode, which means that you have to call grab_image_start, grab_image, grab_image_async, or enable continuous_grabbing. The following modes can be set, but not every hardware supports all modes:
cycle mode description
asynchronous Always transfer to the next buffer regardless of its state.
synchronous If next buffer is empty, then transfer to next buffer, otherwise, transfer to current buffer.
synchronous_with_trash If next buffer is empty, then transfer to the next buffer, otherwise, transfer to the trash buffer. Repeat transferring to the trash buffer as long as the next buffer is full.
off Always transfer to the current buffer.
next_empty If next buffer is empty, then transfer to next buffer, otherwise, transfer to next empty buffer in the list. If all buffers are full, then transfer to current buffer.
synchronous_next_empty_with_trash If next buffer is empty, then transfer to next buffer, otherwise, transfer to next empty buffer in the list. If all buffers are full, then transfer to trash buffer. Repeat transferring to the trash buffer as long as there is no empty buffer in the list.
CorXferGetPrm -> CORXFER_PRM_CYCLE_MODE
'buffer_time_stamp' 0 integer dynamic Internal time stamp of the current SaperaLT buffer. CorBufferGetPrm -> CORBUFFER_PRM_COUNTER_STAMP
'cam_params' 0, 1 integer Flag to enable access to the GenICam parameters of the connected framegrabber camera if available. Framegrabbers are not aware of any changes on the camera configuration at runtime because of this the following limitation need to be consider:
  • The parameters 'Width', 'Height', 'OffsetX' and 'OffsetY' are always mark as read only. Please use 'image_part' instead.
  • When changing the pixel format of the camera, the buffers are not recreated. A correct configuration file for the framegrabber must be provided, otherwise an incorrect images might be acquired. Note:It is possible that changing some other parameters will stop the interface and the framegrabber of working correctly. Use at your own risk!
'camera_type' '<configuration_file>', '' '' string pre-defined Current camera type.
'color_space' 'gray', 'raw', 'rgb', 'rgbx', 'yuv' 'gray' string pre-defined Desired color space and thus the number of image channels of the resulting HALCON image.
'continuous_grabbing' 'disable', 'enable' 'disable' string pre-defined If the continuous grabbing mode is enabled, the camera grabs all the time. In this mode the operator grab_image does not grab synchronously, but behaves similar to grab_image_async. Using this mode you can achieve full frame rate. If the continuous grabbing mode is disabled, the camera is set to single frame capture.
'device' '<device_id>' '0' string dynamic Current device.
'field' '<default>' 'default' string pre-defined The value is not used, so a default value is returned.
'generic' ['','num_buffers=<num>', 'cam_params=0'] -1 mixed pre-defined Values of the Generic parameter.
'grab_timeout' <milliseconds> 5000 integer pre-defined Current grab timeout in milliseconds.
'horizontal_resolution' <resolution> 1 integer pre-defined Current value of horizontal resolution.
'image_available' 0, 1 integer dynamic 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.
'image_height' <height> 0 integer dynamic Height of the image.
'image_part' [<row1, col1, row2, col2>] integer dynamic Allows you to crop a defined part of the image. In order to define a rectangular region for image acquisition, the point on the left top and the point on the right bottom have to be entered. If -1 is passed to every value, the values will be set to their default values. If a value exceeds the image size, it is set to the maximum allowable value.
'image_width' <width> 0 integer dynamic Width of the image.
'internal_device_pointer' '<handle>' string dynamic Returns the internal SDK handle of the current acquisition device which enables direct device access. Use at your own risk!
'line_in' <default> -1 integer pre-defined The value is not used, so a default value is returned.
'line_number' 0, 1, ... <image_height> 0 integer dynamic Allows you to select the line for the line_end callback to be signaled. This parameter has to be set before activating the callback.
'multiple_image_num' 1, 2, 3 1 integer pre-defined Special grabbing mode for line scan cameras.
'name' 'SaperaLT' string pre-defined Name of the HALCON interface.
'num_buffers' <number> 3 integer pre-defined Number of buffers used for the image acquisition. Note that with default buffer cycle mode one buffer is used as trash, so the effective number of available buffers for images is num_buffers - 1.
'port' -1, 0, 1, 2, 3, 4, 5 integer pre-defined Current port number.
'revision' '<revision>' string pre-defined Revision number of the SaperaLT interface.
'start_async_after_grab_async' 'disable', 'enable' 'enable' string pre-defined Status of 'start_async_after_grab_async'.
'start_column' <column> 0 integer pre-defined Returns the current start column of the HALCON image.
'start_row' <row> 0 integer pre-defined Returns the current start row of the HALCON image.
'trash_counter' 0, 1, 2, ... integer dynamic Number of images, which could not be fetched (boards only).
'vertical_resolution' <resolution> 1 integer pre-defined Current value of vertical resolution.
'volatile' 'disable', 'enable' 'disable' string pre-defined Grayscale only. In the volatile mode the two image acquisition interface 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!

Additional parameters for set_framegrabber_param.

The parameters below are only for Teledyne DALSA frame grabber boards.
Parameter Values Default Type Description
'bayer_hardware_decoder_method' 1, 2, 3, 4, 5, 7 integer Method for data conversion of the hardware Bayer decoder.
'bayer_software_decoder' 'disable', 'enable' string Enables or disables the software Bayer decoder. The setting takes effect with the next call of 'grab_image' or 'grab_image_async'.
'bayer_software_decoder_alignment' 'bg_gr', 'gb_rg', 'gr_bg', 'rg_gb' 'gb_rg' string Alignment of the upper left 2x2 square of the camera`s Bayer scheme.
'bayer_software_decoder_format' 'RGB888', 'RGB8888', 'RGB101010' 'RGB888' string Output buffer format of the software Bayer decoder. 'RGB101010' is only available, if the input format is MONO16!
'bayer_software_decoder_method' 1, 2, 3 1 integer Method for data conversion of the software Bayer decoder.
  • method 1: Fast, based on bilinear interpolation.
  • method 2: Advanced, preserves image edges. Works only well, if the image has a strong green content.
  • method 3: Advanced, preserves image edges, independent of image green content.
'bayer_software_decoder_whitebalance' [<wb_red, wb_green, wb_blue>] [1.0, 1.0, 1.0] integer White balance gain for each color channel. You always have to set all three values (floating point). If all values are set to 1.0, no white balance is used for the software Bayer conversion.
'bit_ordering' '9_10', 'inv', 'msb_10', 'msb_12', 'std' string Digital bit ordering of the camera.
  • 9_10: Video data bits 9 and 10 are swapped with bits 0 and 1 (required by some 10-bit digital cameras).
  • inv: The video data bits are inverted (logical NOT).
  • msb_10: Video data bits 0-7 connect to the acquisition device input bits 2-9 (required by some 8-bit digital cameras).
  • msb_12: Video data bits 4-11 are directed to the input bits 0-7 of the acquisition device (required by some 12-bit digital cameras).
  • std: Standard digital bit ordering.
'brightness' <brightness> integer Brightness of the video signal. Represents the percentage of brightness to add or subtract to the composite video signal (analog only).
'brightness_blue' <brightness_blue> integer Brightness of the blue video signal. Represents the percentage of brightness to add or subtract to the blue video signal (analog only).
'brightness_green' <brightness_green> integer Brightness of the green video signal. Represents the percentage of brightness to add or subtract to the green video signal (analog only).
'brightness_red' <brightness_red> integer Brightness of the red video signal. Represents the percentage of brightness to add or subtract to the red video signal (analog only).
'cam_reset' 'disable', 'enable' string Enables or disables the reset pulse to the camera. You must have set the signal properties and the method first.
'cam_reset_delay' <microseconds> integer Reset pulse delay (in microseconds). After receiving a trigger pulse, the acquisition device will wait this delay before generating the reset pulse.
'cam_reset_duration' 1...65535000 integer Duration of the reset pulse.
'cam_reset_signal' 'active_high', 'active_low' string Defines the reset pulse signal.
'cam_trigger' 'disable', 'enable' string Enables or disables the frame trigger pulse to the camera (area scan only).
'cam_trigger_delay' <microseconds> integer Represents the delay (in microseconds) the acquisition device will wait, before generating the trigger pulse (external, internal or software).
'cam_trigger_duration' <duration> integer The effect of this value differs addicted to the selected method.
'cam_trigger_method' 1, 2 integer Trigger method of the camera, see Sapera LT documentation for more details.
'cam_trigger_signal' 'active_low', 'active_high' string Camera trigger signal.
'contrast' <contrast> integer Contrast of the video signal. Represents the percentage of contrast to be applied to the composite video signal (analog only). Step: 1000 (1%).
'contrast_blue' <contrast_blue> integer Contrast of the blue video signal. Represents the percentage of contrast to be applied to the blue video signal (analog only). Step: 1000 (1%).
'contrast_green' <contrast_green> integer Contrast of the green video signal. Represents the percentage of contrast to be applied to the green video signal (analog only). Step: 1000 (1%).
'contrast_red' <contrast_red> integer Contrast of the red video signal. Represents the percentage of contrast to be applied to the red video signal (analog only). Step: 1000 (1%).
'decimate_count' <count> integer Number of fields or frames to decimate per second.
'decimate_method' 'disable', 'even', 'field', 'frame', 'odd' string Decimation method, see Sapera LT documentation for more details.
'do_force_trigger' --- Sends a software trigger.
'do_release_gio_handle' --- Releases the actual GIO handle. Note that the actual GIO will also be released by close_framegrabber or if another GIO is opened by the parameter 'do_set_gio_handle'.
'do_reset_gio' --- Resets the actual GIO.
'do_set_gio_handle' <device_id> 0 integer Opens a GIO input or output port with the used device id.
'ext_frame_trigger' 'disable', 'enable' string Enables or disables external frame trigger (line scan cameras only). You must have set the signal properties first.
'ext_frame_trigger_level' '12 Volts', '24 Volts', 'LVDS', 'LVTTL', 'OPTO', 'RS-422', 'TTL' string External frame trigger level connected to the acquisition device (line scan cameras only).
'ext_frame_trigger_signal' 'active_high', 'active_low', 'double_falling', 'double_rising', 'falling', 'rising' string External frame trigger signal connected to the acquisition device (line scan cameras only). 'double_rising/falling' means to start the acquisition on the rising/falling edge of trigger 1 and to end on the rising/falling edge of trigger 2.
'ext_frame_trigger_source' <source> 0 integer Physical input source the external line trigger is connected to on the acquisition device, in the case where the acquisition device has more than one input.
'ext_line_trigger' 'disable', 'enable' string Enables or disables external line trigger (line scan cameras only). You must have set the signal properties first.
'ext_line_trigger_level' '12 Volts', '24 Volts', 'LVDS', 'LVTTL', 'OPTO', 'RS-422', 'TTL' string External line trigger level connected to the acquisition device (line scan cameras only).
'ext_line_trigger_signal' 'falling', 'rising' string External line trigger signal connected to the acquisition device (line scan cameras only).
'ext_line_trigger_source' <source> 0 integer Physical input source the external line trigger is connected to on the acquisition device, in the case where the acquisition device has more than one input.
'ext_trigger_delay' <delay> 0 integer Delay of the external trigger signal in units specified by 'ext_trigger_delay_time_base'.
'ext_trigger_delay_time_base' <time_base> 0 integer Granularity of units required to adjust the delay of the external trigger signal with 'ext_trigger_delay'.
'ext_trigger_duration' <duration> 0 integer Minimum external trigger pulse duration. For details please refer to the 'Sapera Acquisition Parameter' manual.
'ext_trigger_level' '12 Volts', '24 Volts', 'LVDS', 'LVTTL', 'OPTO', 'RS-422', 'TTL' 'TTL' string External trigger level connected to the acquisition device.
'ext_trigger_signal' 'active_high', 'active_low', 'falling', 'rising' 'rising' string External trigger signal connected to the acquisition device.
'ext_trigger_source' 0, 1, 2 0 integer Physical input source the external trigger is connected to on the acquisition device, in the case where the acquisition device has more than one input.
'frame_integration' 'disable', 'enable' string Enables or disables the frame integration control (area scan cameras only). You must have set the signal properties and the method first.
'frame_integration_count' 1...(2^32)-1 integer Number of frames to integrate.
'frame_integration_method' 1, 2 integer Frame integration method, see Sapera LT documentation for more details.
'frame_integration_signal' 'active_high', 'active_low' string Frame integration signal.
'gio_callback_mask' <mask> integer If a interrupt callback for the I/Os has to be set, this parameter sets a mask, which pins will cause the callback to be called. To active a pin, the value of the mask has to be 1 for it. See also set_framegrabber_callback.
'gio_connector' <number> integer Connector number of the I/O block. Only supported by XIO boards.
'gio_dir_output' <io> integer Specifies which I/O blocks are set as output. If a block is set to 1, it is used as output. Otherwise it is an input.
'gio_dir_tristate' <io> integer Specifies which I/O blocks are set as tristate. If a block is set to 1, it is tri-stated.
'gio_input_level' '12 Volts', '24 Volts', '422', 'LVDS', 'LVTTL', 'OPTO', 'TTL' string Input level of the I/O device. Note that this parameter is only available if the I/O block is set as input.
'gio_output_type' 'led', 'npn', 'opto', 'pnp', 'ttl', 'lvttl' string Output type of the I/O block.
'gio_state' 0, 1 integer State of the general I/O pins. If a pin is set to 1, it will be set to TRUE, otherwise FALSE. To set the mask for the pins to set use the parameter 'gio_state_mask'. Note that you have to set ALL pins you want to set additionally to the mask, which means, e.g., to activate pins 1 and 3, the mask and the state has to be set to 0x5. This parameter is not supported by all boards.
'gio_state_mask' <mask> integer Mask for setting the state of the general I/O pins. If a pin is set to 1, it can be set via the value of the parameter 'gio_state'.
'hue' <hue> integer Phase change in degrees applied to the hue control (analog composite or Y/C only).
'int_frame_trigger' 'disable', 'enable' string Enables or disables internal frame trigger (area scan cameras only). You must have set the trigger frequency first.
'int_frame_trigger_freq' <mHz> integer Internal frame trigger frequency in milli-Hz (area scan cameras only).
'int_line_trigger' 'disable', 'enable' string Enables or disables internal line trigger. You must have set the trigger frequency first.
'int_line_trigger_freq' <Hz> integer Internal line trigger frequency in Hz.
'line_integration' 'disable', 'enable' string Enables or disables the line integration signal pulse to the camera (line scan cameras only). You have to set the signal properties and the method first.
'line_integration_duration' <microseconds> integer Specifies the line integration pulse width in microseconds (line scan cameras only).
'line_integration_method' 1, 2, 3, 4, 7 integer Line integration method, see Sapera LT documentation for more details (line scan cameras only).
'line_integration_pulse0_delay' <microseconds> integer Line integration delay (in microseconds) of pulse 0. After receiving a trigger pulse, the acquisition device will wait this delay before generating the line integration pulse 0 (line scan cameras only).
'line_integration_pulse0_duration' <microseconds> integer Line integration pulse 0 width (in microseconds) (line scan cameras only).
'line_integration_pulse0_signal' 'active_high', 'active_low' string Line integration signal of pulse 0 (line scan cameras only).
'line_integration_pulse1_delay' <microseconds> integer Line integration delay (in microseconds) of pulse 1. After receiving a trigger pulse, the acquisition device will wait this delay before generating the line integration pulse 1 (line scan cameras only).
'line_integration_pulse1_duration' <microseconds> integer Line integration pulse 1 width (in microseconds) (line scan cameras only).
'line_integration_pulse1_signal' 'active_high', 'active_low' string Line integration signal of pulse 1 (line scan cameras only).
'line_integration_time_base' 'ns', 'pixel_clk' string Time base of line integration signal (line scan cameras only).
'line_trigger' 'disable', 'enable' string Enables or disables the line trigger signal pulse to the camera (line scan cameras only). Note that this parameter cannot be enabled if 'line_integration' is enabled and vice versa.
'line_trigger_delay' <delay> integer Delay of the line trigger pulse in units specified by 'line_integration_time_base' (line scan cameras only).
'line_trigger_duration' <duration> integer Duration of the line trigger pulse in units specified by 'line_integration_time_base' (line scan cameras only).
'line_trigger_method' 1, 2 integer Output method of the line trigger signal pulse (line scan cameras only).
'linescan_direction' 'disable', 'enable', 'camera' string Enables or disables the line scan direction (line scan cameras only). If the framegrabber does not support this feature, but the camera does, it is possible to attempt to enable direction change directly into the camera by setting the value 'camera'. However, notice that this may not work on all devices. If you are successful the parameter 'linescan_direction_source' becomes available and the parameter 'linescan_direction_output' can be used normally.
'linescan_direction_output' 'forward', 'reverse' string Linescan direction (line scan cameras only). The value can only be changed if the parameter 'linescan_direction' has been successfully set to 'enable' or 'camera'. If the 'camera' value was set on the parameter 'linescan_direction', then the parameter 'linescan_direction_source' must be set to 'internal' in order to enable the direction change.
'linescan_direction_signal' 'active_high', 'active_low' string Signal of the line scan direction (line scan cameras only).
'linescan_direction_source' 'internal', 'external' string The linescan direction source (line scan cameras only) is the source from where the trigger for the direction change can be set. The source must be set to 'internal' in order to enable the direction change using the parameter 'linescan_direction_output'.
'lut' 'disable', 'enable' 'disable' string Enables or disables the lookup table. Caution: On some acquisition devices, the LUT can not be disabled.
'pixel_arrangement' 'line_interleaved', 'pixel_interleaved' 'pixel_interleaved' string In case of 4-channel images this parameter is used to set the pixel arrangement, if the output format differs from an RGB format.
'pixel_clock_detection' 'falling', 'rising' string Type of pixel clock detection of the video source.
'pixel_clock_ext' <Hz> integer External pixel clock frequency in Hz. Note that this parameter is valid only if parameter 'pixel_clock_source' specifies that an external pixel clock is needed.
'pixel_clock_int' <Hz> integer Internal pixel clock frequency in Hz. Note that this parameter is valid only if parameter 'pixel_clock_source' specifies that an internal pixel clock is needed.
'pixel_clock_source' 'ext', 'ext_int', 'int' string Source of the acquisition device pixel clock. 'ext_int' means that the external pixel clock is used while the acquisition device simultaneously outputs its own internal pixel clock for other use.
'port' 0, 1, 2, 3, 4, 5 integer Number of the desired camera port.
'saturation' <saturation> integer Color saturation percentage control (analog composite only).
'shaft_encoder' 'disable', 'enable' string Enables or disables shaft encoder support of the acquisition device.
'shaft_encoder_drop' <number> integer Number of dropped signal edges using a shaft encoder.
'shaft_encoder_level' '12 Volts', '24 Volts', 'LVDS', 'LVTTL', 'OPTO', 'RS-422', 'TTL' string Shaft encoder level fed to the acquisition device (line scan cameras only).
'shaft_encoder_multiply' <number> integer Number of signal edges generated for each shaft encoder signal edge, when video acquisitions are controlled by an external shaft encoder trigger.
'sharpness' <sharpness> integer Sharpness control applied to the video signal (analog composite only).
'strobe' 'disable', 'enable' string Enables or disables the strobe pulse. You must have set the signal properties and the method first.
'strobe_delay' <microseconds> integer Strobe pulse delay 1 (in microseconds).
'strobe_delay2' <microseconds> integer Strobe pulse delay 2 (in microseconds).
'strobe_duration' <microseconds> integer Strobe pulse width (in microseconds).
'strobe_level' '12 Volts', '24 Volts', 'LVDS', 'LVTTL', 'OPTO', 'RS-422', 'TTL' string Strobe signal level output by the acquisition device.
'strobe_method' 1, 2 integer Strobe pulse output method, see Sapera LT documentation for more details.
'strobe_signal' 'active_high', 'active_low' string Strobe pulse signal.
'time_integration' 'disable', 'enable' string Enables or disables the time integration signal pulse to the camera (area scan cameras only). You have to set the signal properties and the method first.
'time_integration_delay' <microseconds> integer Time integration delay (in microseconds). After receiving a trigger pulse, the acquisition device will wait this delay before generating the time integration pulse(s).
'time_integration_duration' <microseconds> integer Time integration pulse width in microseconds (area scan cameras only).
'time_integration_method' 1, 2, 3, 4, 5, 6, 7, 8, 10, 11, 12 integer Time integration method, see Sapera LT documentation for more details.
'time_integration_pulse0_delay' <microseconds> integer Time integration delay (in microseconds) of pulse 0. After receiving a trigger pulse, the acquisition device will wait this delay before generating the time integration pulse 0.
'time_integration_pulse0_duration' <microseconds> integer Specifies the time integration pulse 0 width (in microseconds).
'time_integration_pulse0_signal' 'active_high', 'active_low' string Time integration signal of pulse 0.
'time_integration_pulse1_delay' <microseconds> integer Time integration delay (in microseconds) of pulse 1. After receiving a pulse, the acquisition device will wait this delay before generating the time integration pulse 1.
'time_integration_pulse1_duration' <microseconds> integer Specifies the time integration pulse 1 width (in microseconds).
'time_integration_pulse1_signal' 'active_high', 'active_low' string Time integration signal of pulse 1.

Additional parameters for get_framegrabber_param.

The parameters below are only for Teledyne DALSA frame grabber boards.
Parameter Values Default Type Kind Description
'bayer_hardware_decoder' 'disable', 'enable' string dynamic Gets the status of the hardware Bayer decoder of the acquisition device. When present and enabled, the Bayer video data is converted into the specified output format (from the camera configuration file). Note that this feature is not supported by all board types!
'bayer_hardware_decoder_method' 1, 2, 3, 4, 5, 7 integer dynamic Method for data conversion of the hardware Bayer decoder.
'bayer_software_decoder' 'disable', 'enable' string dynamic Enables or disables the software Bayer decoder. The setting takes effect with the next call of 'grab_image' or 'grab_image_async'.
'bayer_software_decoder_alignment' 'bg_gr', 'gb_rg', 'gr_bg', 'rg_gb' 'gb_rg' string pre-defined Alignment of the upper left 2x2 square of the camera`s Bayer scheme.
'bayer_software_decoder_format' 'RGB888', 'RGB8888', 'RGB101010' 'RGB888' string pre-defined Output buffer format of the software Bayer decoder. 'RGB101010' is only available, if the input format is MONO16!
'bayer_software_decoder_method' 1, 2, 3 1 integer pre-defined Method for data conversion of the software Bayer decoder.
  • method 1: Fast, based on bilinear interpolation.
  • method 2: Advanced, preserves image edges. Works only well, if the image has a strong green content.
  • method 3: Advanced, preserves image edges, independent of image green content.
'bayer_software_decoder_whitebalance' [<wb_red, wb_green, wb_blue>] [1.0, 1.0, 1.0] integer pre-defined White balance gain for each color channel. You always have to set all three values (floating point). If all values are set to 1.0, no white balance is used for the software Bayer conversion.
'bit_ordering' '9_10', 'inv', 'msb_10', 'msb_12', 'std' string dynamic Digital bit ordering of the camera.
  • 9_10: Video data bits 9 and 10 are swapped with bits 0 and 1 (required by some 10-bit digital cameras).
  • inv: The video data bits are inverted (logical NOT).
  • msb_10: Video data bits 0-7 connect to the acquisition device input bits 2-9 (required by some 8-bit digital cameras).
  • msb_12: Video data bits 4-11 are directed to the input bits 0-7 of the acquisition device (required by some 12-bit digital cameras).
  • std: Standard digital bit ordering.
'brightness' <brightness> integer dynamic Brightness of the video signal. Represents the percentage of brightness to add or subtract to the composite video signal (analog only).
'brightness_blue' <brightness_blue> integer dynamic Brightness of the blue video signal. Represents the percentage of brightness to add or subtract to the blue video signal (analog only).
'brightness_green' <brightness_green> integer dynamic Brightness of the green video signal. Represents the percentage of brightness to add or subtract to the green video signal (analog only).
'brightness_red' <brightness_red> integer dynamic Brightness of the red video signal. Represents the percentage of brightness to add or subtract to the red video signal (analog only).
'cam_reset' 'disable', 'enable' string dynamic Enables or disables the reset pulse to the camera. You must have set the signal properties and the method first.
'cam_reset_delay' <microseconds> integer dynamic Reset pulse delay (in microseconds). After receiving a trigger pulse, the acquisition device will wait this delay before generating the reset pulse.
'cam_reset_duration' 1...65535000 integer dynamic Duration of the reset pulse.
'cam_reset_signal' 'active_high', 'active_low' string dynamic Defines the reset pulse signal.
'cam_trigger' 'disable', 'enable' string dynamic Enables or disables the frame trigger pulse to the camera (area scan only).
'cam_trigger_delay' <microseconds> integer dynamic Represents the delay (in microseconds) the acquisition device will wait, before generating the trigger pulse (external, internal or software).
'cam_trigger_duration' <duration> integer dynamic The effect of this value differs addicted to the selected method.
'cam_trigger_method' 1, 2 integer dynamic Trigger method of the camera, see Sapera LT documentation for more details.
'cam_trigger_signal' 'active_low', 'active_high' string dynamic Camera trigger signal.
'camera_model' '<model>' string dynamic Name of the camera model.
'camera_vendor' '<vendor>' string dynamic Name of the camera vendor.
'contrast' <contrast> integer dynamic Contrast of the video signal. Represents the percentage of contrast to be applied to the composite video signal (analog only). Step: 1000 (1%).
'contrast_blue' <contrast_blue> integer dynamic Contrast of the blue video signal. Represents the percentage of contrast to be applied to the blue video signal (analog only). Step: 1000 (1%).
'contrast_green' <contrast_green> integer dynamic Contrast of the green video signal. Represents the percentage of contrast to be applied to the green video signal (analog only). Step: 1000 (1%).
'contrast_red' <contrast_red> integer dynamic Contrast of the red video signal. Represents the percentage of contrast to be applied to the red video signal (analog only). Step: 1000 (1%).
'decimate_count' <count> integer dynamic Number of fields or frames to decimate per second.
'decimate_method' 'disable', 'even', 'field', 'frame', 'odd' string dynamic Decimation method, see Sapera LT documentation for more details.
'ext_frame_trigger' 'disable', 'enable' string dynamic Enables or disables external frame trigger (line scan cameras only). You must have set the signal properties first.
'ext_frame_trigger_level' '12 Volts', '24 Volts', 'LVDS', 'LVTTL', 'OPTO', 'RS-422', 'TTL' string dynamic External frame trigger level connected to the acquisition device (line scan cameras only).
'ext_frame_trigger_signal' 'active_high', 'active_low', 'double_falling', 'double_rising', 'falling', 'rising' string dynamic External frame trigger signal connected to the acquisition device (line scan cameras only). 'double_rising/falling' means to start the acquisition on the rising/falling edge of trigger 1 and to end on the rising/falling edge of trigger 2.
'ext_frame_trigger_source' <source> 0 integer dynamic Physical input source the external line trigger is connected to on the acquisition device, in the case where the acquisition device has more than one input.
'ext_line_trigger' 'disable', 'enable' string dynamic Enables or disables external line trigger (line scan cameras only). You must have set the signal properties first.
'ext_line_trigger_level' '12 Volts', '24 Volts', 'LVDS', 'LVTTL', 'OPTO', 'RS-422', 'TTL' string dynamic External line trigger level connected to the acquisition device (line scan cameras only).
'ext_line_trigger_signal' 'falling', 'rising' string dynamic External line trigger signal connected to the acquisition device (line scan cameras only).
'ext_line_trigger_source' <source> 0 integer dynamic Physical input source the external line trigger is connected to on the acquisition device, in the case where the acquisition device has more than one input.
'ext_trigger_delay' <delay> 0 integer dynamic Delay of the external trigger signal in units specified by 'ext_trigger_delay_time_base'.
'ext_trigger_delay_time_base' <time_base> 0 integer dynamic Granularity of units required to adjust the delay of the external trigger signal with 'ext_trigger_delay'.
'ext_trigger_duration' <duration> 0 integer dynamic Minimum external trigger pulse duration. For details please refer to the 'Sapera Acquisition Parameter' manual.
'ext_trigger_level' '12 Volts', '24 Volts', 'LVDS', 'LVTTL', 'OPTO', 'RS-422', 'TTL' 'TTL' string pre-defined External trigger level connected to the acquisition device.
'ext_trigger_signal' 'active_high', 'active_low', 'falling', 'rising' 'rising' string pre-defined External trigger signal connected to the acquisition device.
'ext_trigger_source' 0, 1, 2 0 integer pre-defined Physical input source the external trigger is connected to on the acquisition device, in the case where the acquisition device has more than one input.
'frame_integration' 'disable', 'enable' string dynamic Enables or disables the frame integration control (area scan cameras only). You must have set the signal properties and the method first.
'frame_integration_count' 1...(2^32)-1 integer dynamic Number of frames to integrate.
'frame_integration_method' 1, 2 integer dynamic Frame integration method, see Sapera LT documentation for more details.
'frame_integration_signal' 'active_high', 'active_low' string dynamic Frame integration signal.
'gio_callback_mask' <mask> integer dynamic If a interrupt callback for the I/Os has to be set, this parameter sets a mask, which pins will cause the callback to be called. To active a pin, the value of the mask has to be 1 for it. See also set_framegrabber_callback.
'gio_connector' <number> integer dynamic Connector number of the I/O block. Only supported by XIO boards.
'gio_count' <num> integer dynamic Number of available I/O blocks.
'gio_device_id' <id> integer dynamic Device id of the actual I/O block.
'gio_dir_output' <io> integer dynamic Specifies which I/O blocks are set as output. If a block is set to 1, it is used as output. Otherwise it is an input.
'gio_dir_tristate' <io> integer dynamic Specifies which I/O blocks are set as tristate. If a block is set to 1, it is tri-stated.
'gio_event_count_falling_edge' <event_count> integer dynamic Number of events for the falling edge of the interrupt callback for the I/Os. This parameter only returns values, if the corresponding event has been registered by the callback.
'gio_event_count_rising_edge' <event_count> integer dynamic Number of events for the rising edge of the interrupt callback for the I/Os. This parameter only returns values, if the corresponding event has been registered by the callback.
'gio_input_level' '12 Volts', '24 Volts', '422', 'LVDS', 'LVTTL', 'OPTO', 'TTL' string dynamic Input level of the I/O device. Note that this parameter is only available if the I/O block is set as input.
'gio_label' '<label>' string dynamic Name of the actual I/O.
'gio_output_type' 'led', 'npn', 'opto', 'pnp', 'ttl', 'lvttl' string dynamic Output type of the I/O block.
'gio_state' 0, 1 integer dynamic State of the general I/O pins. If a pin is set to 1, it will be set to TRUE, otherwise FALSE. To set the mask for the pins to set use the parameter 'gio_state_mask'. Note that you have to set ALL pins you want to set additionally to the mask, which means, e.g., to activate pins 1 and 3, the mask and the state has to be set to 0x5. This parameter is not supported by all boards.
'gio_state_mask' <mask> integer dynamic Mask for setting the state of the general I/O pins. If a pin is set to 1, it can be set via the value of the parameter 'gio_state'.
'hue' <hue> integer dynamic Phase change in degrees applied to the hue control (analog composite or Y/C only).
'int_frame_trigger' 'disable', 'enable' string dynamic Enables or disables internal frame trigger (area scan cameras only). You must have set the trigger frequency first.
'int_frame_trigger_freq' <mHz> integer dynamic Internal frame trigger frequency in milli-Hz (area scan cameras only).
'int_line_trigger' 'disable', 'enable' string dynamic Enables or disables internal line trigger. You must have set the trigger frequency first.
'int_line_trigger_freq' <Hz> integer dynamic Internal line trigger frequency in Hz.
'line_integration' 'disable', 'enable' string dynamic Enables or disables the line integration signal pulse to the camera (line scan cameras only). You have to set the signal properties and the method first.
'line_integration_duration' <microseconds> integer dynamic Specifies the line integration pulse width in microseconds (line scan cameras only).
'line_integration_method' 1, 2, 3, 4, 7 integer dynamic Line integration method, see Sapera LT documentation for more details (line scan cameras only).
'line_integration_pulse0_delay' <microseconds> integer dynamic Line integration delay (in microseconds) of pulse 0. After receiving a trigger pulse, the acquisition device will wait this delay before generating the line integration pulse 0 (line scan cameras only).
'line_integration_pulse0_duration' <microseconds> integer dynamic Line integration pulse 0 width (in microseconds) (line scan cameras only).
'line_integration_pulse0_signal' 'active_high', 'active_low' string dynamic Line integration signal of pulse 0 (line scan cameras only).
'line_integration_pulse1_delay' <microseconds> integer dynamic Line integration delay (in microseconds) of pulse 1. After receiving a trigger pulse, the acquisition device will wait this delay before generating the line integration pulse 1 (line scan cameras only).
'line_integration_pulse1_duration' <microseconds> integer dynamic Line integration pulse 1 width (in microseconds) (line scan cameras only).
'line_integration_pulse1_signal' 'active_high', 'active_low' string dynamic Line integration signal of pulse 1 (line scan cameras only).
'line_integration_time_base' 'ns', 'pixel_clk' string dynamic Time base of line integration signal (line scan cameras only).
'line_trigger' 'disable', 'enable' string dynamic Enables or disables the line trigger signal pulse to the camera (line scan cameras only). Note that this parameter cannot be enabled if 'line_integration' is enabled and vice versa.
'line_trigger_delay' <delay> integer dynamic Delay of the line trigger pulse in units specified by 'line_integration_time_base' (line scan cameras only).
'line_trigger_duration' <duration> integer dynamic Duration of the line trigger pulse in units specified by 'line_integration_time_base' (line scan cameras only).
'line_trigger_method' 1, 2 integer dynamic Output method of the line trigger signal pulse (line scan cameras only).
'linescan_direction' 'disable', 'enable', 'camera' string dynamic Enables or disables the line scan direction (line scan cameras only). If the framegrabber does not support this feature, but the camera does, it is possible to attempt to enable direction change directly into the camera by setting the value 'camera'. However, notice that this may not work on all devices. If you are successful the parameter 'linescan_direction_source' becomes available and the parameter 'linescan_direction_output' can be used normally.
'linescan_direction_output' 'forward', 'reverse' string dynamic Linescan direction (line scan cameras only). The value can only be changed if the parameter 'linescan_direction' has been successfully set to 'enable' or 'camera'. If the 'camera' value was set on the parameter 'linescan_direction', then the parameter 'linescan_direction_source' must be set to 'internal' in order to enable the direction change.
'linescan_direction_signal' 'active_high', 'active_low' string dynamic Signal of the line scan direction (line scan cameras only).
'linescan_direction_source' 'internal', 'external' string dynamic The linescan direction source (line scan cameras only) is the source from where the trigger for the direction change can be set. The source must be set to 'internal' in order to enable the direction change using the parameter 'linescan_direction_output'.
'lut' 'disable', 'enable' 'disable' string pre-defined Enables or disables the lookup table. Caution: On some acquisition devices, the LUT can not be disabled.
'pixel_arrangement' 'line_interleaved', 'pixel_interleaved' 'pixel_interleaved' string pre-defined In case of 4-channel images this parameter is used to set the pixel arrangement, if the output format differs from an RGB format.
'pixel_clock_11' <Hz> integer dynamic Pixel clock frequency in Hz, so that the camera image has a 1:1 aspect ratio.
'pixel_clock_detection' 'falling', 'rising' string dynamic Type of pixel clock detection of the video source.
'pixel_clock_ext' <Hz> integer dynamic External pixel clock frequency in Hz. Note that this parameter is valid only if parameter 'pixel_clock_source' specifies that an external pixel clock is needed.
'pixel_clock_int' <Hz> integer dynamic Internal pixel clock frequency in Hz. Note that this parameter is valid only if parameter 'pixel_clock_source' specifies that an internal pixel clock is needed.
'pixel_clock_source' 'ext', 'ext_int', 'int' string dynamic Source of the acquisition device pixel clock. 'ext_int' means that the external pixel clock is used while the acquisition device simultaneously outputs its own internal pixel clock for other use.
'saturation' <saturation> integer dynamic Color saturation percentage control (analog composite only).
'shaft_encoder' 'disable', 'enable' string dynamic Enables or disables shaft encoder support of the acquisition device.
'shaft_encoder_drop' <number> integer dynamic Number of dropped signal edges using a shaft encoder.
'shaft_encoder_level' '12 Volts', '24 Volts', 'LVDS', 'LVTTL', 'OPTO', 'RS-422', 'TTL' string dynamic Shaft encoder level fed to the acquisition device (line scan cameras only).
'shaft_encoder_multiply' <number> integer dynamic Number of signal edges generated for each shaft encoder signal edge, when video acquisitions are controlled by an external shaft encoder trigger.
'sharpness' <sharpness> integer dynamic Sharpness control applied to the video signal (analog composite only).
'signal_status' <status> integer dynamic Current signal status of the camera.
'strobe' 'disable', 'enable' string dynamic Enables or disables the strobe pulse. You must have set the signal properties and the method first.
'strobe_delay' <microseconds> integer dynamic Strobe pulse delay 1 (in microseconds).
'strobe_delay2' <microseconds> integer dynamic Strobe pulse delay 2 (in microseconds).
'strobe_duration' <microseconds> integer dynamic Strobe pulse width (in microseconds).
'strobe_level' '12 Volts', '24 Volts', 'LVDS', 'LVTTL', 'OPTO', 'RS-422', 'TTL' string dynamic Strobe signal level output by the acquisition device.
'strobe_method' 1, 2 integer dynamic Strobe pulse output method, see Sapera LT documentation for more details.
'strobe_signal' 'active_high', 'active_low' string dynamic Strobe pulse signal.
'time_integration' 'disable', 'enable' string dynamic Enables or disables the time integration signal pulse to the camera (area scan cameras only). You have to set the signal properties and the method first.
'time_integration_delay' <microseconds> integer dynamic Time integration delay (in microseconds). After receiving a trigger pulse, the acquisition device will wait this delay before generating the time integration pulse(s).
'time_integration_duration' <microseconds> integer dynamic Time integration pulse width in microseconds (area scan cameras only).
'time_integration_method' 1, 2, 3, 4, 5, 6, 7, 8, 10, 11, 12 integer dynamic Time integration method, see Sapera LT documentation for more details.
'time_integration_pulse0_delay' <microseconds> integer dynamic Time integration delay (in microseconds) of pulse 0. After receiving a trigger pulse, the acquisition device will wait this delay before generating the time integration pulse 0.
'time_integration_pulse0_duration' <microseconds> integer dynamic Specifies the time integration pulse 0 width (in microseconds).
'time_integration_pulse0_signal' 'active_high', 'active_low' string dynamic Time integration signal of pulse 0.
'time_integration_pulse1_delay' <microseconds> integer dynamic Time integration delay (in microseconds) of pulse 1. After receiving a pulse, the acquisition device will wait this delay before generating the time integration pulse 1.
'time_integration_pulse1_duration' <microseconds> integer dynamic Specifies the time integration pulse 1 width (in microseconds).
'time_integration_pulse1_signal' 'active_high', 'active_low' string dynamic Time integration signal of pulse 1.

Operator set_framegrabber_lut

Lookup tables can be set using the operator set_framegrabber_lut or can be enabled/disabled by set_framegrabber_param(...,'lut','enable'/'disable'). Note that not all boards and cameras support LUTs. The number of values to pass depends on the current color space. This operator creates a normal (linear) LUT. Reading a LUT from file is not supported.
Also have a look at the HDevelop example saperalt_lut.

Operator get_framegrabber_lut

Get the current lookup table.

Operator set_framegrabber_callback

This interface supports device specific events via the operators set_framegrabber_callback and get_framegrabber_callback.

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 the specified callback function will be called. If the callback function is set to NULL, the corresponding callback will be unregistered. In addition to our HALCON defined callbacks this interface supports Acquisition and AcqDevice events callbacks. For cameras AcqDevice events the name of the available callbacks will be displayed as a provided by querying the device. For framegrabbers Acquisition the events CORACQ_VAL_EVENT_TYPE_END_OF_LINE, CORACQ_VAL_EVENT_TYPE_END_OF_NLINES, CORACQ_VAL_EVENT_TYPE_LINK_LOCK and CORACQ_VAL_EVENT_TYPE_LINK_UNLOCK are not available. The signature of the callback function is Herror (__stdcall *HAcqCallback)(void *AcqHandle, void *Context, void *UserContext) for Windows operating systems. All other operating systems use their native calling convention instead of __stdcall.
The callback function uses the following parameters:
  • AcqHandle Acquisition handle of the corresponding image acquisition instance.
  • Context Optional context data of the specific callback. In the SaperaLT interface, 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 should always be as short as possible since during the execution of a callback function the handling of further internal callbacks might be blocked. This can be achieved by removing the current processing from the user-specific callback function to a separate thread that is controlled via signals or events.
If you want to know which I/O pin has signaled the callback, a callback function has to be registered for each pin.
Please also note that not all cameras support all callbacks.

Type Description
'external_trigger' The 'external_trigger' callback corresponds with the CORACQ_VAL_EVENT_TYPE_EXTERNAL_TRIGGER and is only available for framegrabbers that support it.
'gio_falling_edge' If a frame grabber supports general I/Os, a callback can be registered, which will be called if an I/O generates an interrupt. With the parameter 'gio_callback_mask' the I/O pins, which will call the callback, can be set. The parameter 'gio_event_count_falling_edge' returns the number of occurred events. This callback is not supported by GigE Vision cameras.
'gio_rising_edge' If a frame grabber supports general I/Os, a callback can be registered, which will be called if an I/O generates an interrupt. With the parameter 'gio_callback_mask' the I/O pins, which will call the callback, can be set. The parameter 'gio_event_count_rising_edge' returns the number of occurred events. This callback is not supported by GigE Vision cameras.
'line_end' The 'line_end' callback corresponds to the CorXferRegisterCallback(..., CORXFER_VAL_EVENT_TYPE_END_OF_LINE, ...) command. The callback will be signaled after the line data is written into the local PC buffer. The parameter 'line_number' has to be set before activating this callback to specify the desired line at which the callback will be signaled.

'readout_end' Since the callback corresponds to the CorAcqDeviceRegister(..., 'End of Readout', ...) (or 'ReadoutEnd' with Genie TS Framework) command, it is only available for GigE Vision cameras. Note that the callback will be signaled after the image data is written into the local camera buffer but not yet finally transferred to the PC.
'transfer_end' The 'transfer_end' callback corresponds to the CorXferRegisterCallback(..., CORXFER_VAL_EVENT_TYPE_END_OF_TRANSFER, ...) command. The callback will be signaled after the image data is written into the local PC buffer.

'data_overflow' The 'data_overflow' callback corresponds with the CORACQ_VAL_EVENT_TYPE_DATA_OVERFLOW and is only available for framegrabbers that support it.
'end_of_even' The 'end_of_even' callback corresponds with the CORACQ_VAL_EVENT_TYPE_END_OF_EVEN and is only available for framegrabbers that support it.
'end_of_field' The 'end_of_field' callback corresponds with the CORACQ_VAL_EVENT_TYPE_END_OF_FIELD and is only available for framegrabbers that support it.
'end_of_frame' The 'end_of_frame' callback corresponds with the CORACQ_VAL_EVENT_TYPE_END_OF_FRAME and is only available for framegrabbers that support it.
'end_of_odd' The 'end_of_odd' callback corresponds with the CORACQ_VAL_EVENT_TYPE_END_OF_ODD and is only available for framegrabbers that support it.
'external_trigger_ignored' The 'external_trigger_ignored' callback corresponds with the CORACQ_VAL_EVENT_TYPE_EXTERNAL_TRIGGER_IGNORED and is only available for framegrabbers that support it.
'external_trigger_too_slow' The 'external_trigger_too_slow' callback corresponds with the CORACQ_VAL_EVENT_TYPE_EXT_LINE_TRIGGER_TOO_SLOW and is only available for framegrabbers that support it.
'frame_lost' The 'frame_lost' callback corresponds with the CORACQ_VAL_EVENT_TYPE_FRAME_LOST and is only available for framegrabbers that support it.
'horizontal_sync_lock' The 'horizontal_sync_lock' callback corresponds with the CORACQ_VAL_EVENT_TYPE_HSYNC_LOCK and is only available for framegrabbers that support it.
'horizontal_sync_unlock' The 'horizontal_sync_unlock' callback corresponds with the CORACQ_VAL_EVENT_TYPE_HSYNC_UNLOCK and is only available for framegrabbers that support it.
'line_trigger_too_fast' The 'line_trigger_too_fast' callback corresponds with the CORACQ_VAL_EVENT_TYPE_LINE_TRIGGER_TOO_FAST and is only available for framegrabbers that support it.
'link_error' The 'link_error' callback corresponds with the CORACQ_VAL_EVENT_TYPE_LINK_ERROR and is only available for framegrabbers that support it.
'no_horizontal_sync' The 'no_horizontal_sync' callback corresponds with the CORACQ_VAL_EVENT_TYPE_NO_HSYNC and is only available for framegrabbers that support it.
'no_pixel_clock' The 'no_pixel_clock' callback corresponds with the CORACQ_VAL_EVENT_TYPE_NO_PIXEL_CLK and is only available for framegrabbers that support it.
'no_vertical_sync' The 'no_vertical_sync' callback corresponds with the CORACQ_VAL_EVENT_TYPE_NO_VSYNC and is only available for framegrabbers that support it.
'pixel_clock' The 'pixel_clock' callback corresponds with the CORACQ_VAL_EVENT_TYPE_PIXEL_CLK and is only available for framegrabbers that support it.
'shaft_encoder_reverse_count_overflow' The 'shaft_encoder_reverse_count_overflow' callback corresponds with the CORACQ_VAL_EVENT_TYPE_SHAFT_ENCODER_REVERSE_COUNT_OVERFLOW and is only available for framegrabbers that support it.
'start_of_even' The 'start_of_even' callback corresponds with the CORACQ_VAL_EVENT_TYPE_START_OF_EVEN and is only available for framegrabbers that support it.
'start_of_field' The 'start_of_field' callback corresponds with the CORACQ_VAL_EVENT_TYPE_START_OF_FIELD and is only available for framegrabbers that support it.
'start_of_frame' The 'start_of_frame' callback corresponds with the CORACQ_VAL_EVENT_TYPE_START_OF_FRAME and is only available for framegrabbers that support it.
'start_of_odd' The 'start_of_odd' callback corresponds with the CORACQ_VAL_EVENT_TYPE_START_OF_ODD and is only available for framegrabbers that support it.
'user_define' The 'user_define' callback corresponds with the CORACQ_VAL_EVENT_TYPE_USER_DEFINE and is only available for framegrabbers that support it.
'vertical_sync' The 'vertical_sync' callback corresponds with the CORACQ_VAL_EVENT_TYPE_VERTICAL_SYNC and is only available for framegrabbers that support it.
'vertical_timeout' The 'vertical_timeout' callback corresponds with the CORACQ_VAL_EVENT_TYPE_VERTICAL_TIMEOUT and is only available for framegrabbers that support it.

Operator get_framegrabber_callback

This interface supports device specific events via the operators set_framegrabber_callback and get_framegrabber_callback. For more information see set_framegrabber_callback.

Operator grab_image_start

Starts a new asynchronous grab. See also grab_image_start.

Operator grab_image

grab_image starts a new synchronous grab. See also grab_image. Note that the interface converts the image from the device to the desired image format specified by the parameters 'image_width', 'image_height', 'start_row', 'start_column', 'bits_per_channel', and 'color_space'.

Operator grab_image_async

grab_image_async returns an image and starts the next asynchronous grab. See also grab_image_async. Note that the interface converts the image from the device to the desired image format specified by the parameters 'image_width', 'image_height', 'start_row', 'start_column', 'bits_per_channel', and 'color_space'.

Operator grab_data

Not supported by this interface.

Operator grab_data_async

Not supported by this interface.

Operator close_framegrabber

This operator closes the device. See also close_framegrabber.

HDevelop Examples

For this interface there are the following examples available:
  • saperalt_2boards.hdev - Example for the usage of two Teledyne DALSA frame grabber boards.
  • saperalt_2cameras.hdev - Shows concurrent grabbing from two connected cameras.
  • saperalt_crop.hdev - Example for grabbing images with image cropping.
  • saperalt.hdev - Benchmark.
  • saperalt_gio.hdev - Shows the usage of general input/output pins.
  • saperalt_lut.hdev - Shows the usage of a look-up table.
  • saperalt_parameters.hdev - Lists all parameters of a device.
  • saperalt_simple.hdev - A simple example to show the usage of the interface.
  • saperalt_turbodrive.hdev - Shows the usage of the TurboDrive feature.

C++ Examples

For this interface there is also a further C++ Visual Studio Project to demonstrate the usage of the operators get_framegrabber_callback and set_framegrabber_callback. Please check the directory %HALCONEXAMPLES%\cpp\console\vs2005\. If you prefer building the example via the console, please check the following folder %HALCONEXAMPLES%\cpp\console\. With a Linux OS please use $HALCONEXAMPLES/cpp/console/.

C# Examples

For this interface there is also a further C# Visual Studio Project to demonstrate the usage of the operators get_framegrabber_callback and set_framegrabber_callback. Please check the directory %HALCONEXAMPLES%\cpp\console\vs2005\.

Known Issues

  • Using Hardware Bayer decoder on X64 Xcelera PX4
    If you are using a X64 Xcelera PX4 frame grabber with Hardware Bayer decoder and a driver version smaller than 1.5x, it could be that you cannot grab images with HALCON (an error message occurs). The solution is to contact Teledyne DALSA and ask for a driver update for your frame grabber board. After installing the new driver everything should work correctly.

Release Notes

  • Revision 13.0.5 (Dec 21, 2018):
    • There was a problem when reading the image size during open_framegrabber which led to incorrect images. This problem has been fixed.
  • Revision 13.0.4 (Nov 30, 2018):
    • Added support to enable querying the '_access' on GenICam features which the access mode is not-implemented ('ni') and not-enable ('na').
    • Added support for querying '_type' on GenICam features.
    • Added support for framegrabber firmware that allow use of multiple cameras. It is now possible to get an acquisition handle to each of the cameras and grab images.
    • Added support to read and write the GenICam parameters of the connected camera if this functionality is supported by the framegrabbers firmware. To enable this functionality the generic parameter 'cam_params' must be set to 1.
    • The GIO of a framegrabber board are now share between all instances of the same device. This includes all relevant parameter values like the 'gio_state_mask', 'gio_state', etc.
  • Revision 13.0.3 (May 29, 2018):
    • Added support for the 'YCbCr411_8' pixel format.
    • Allocating buffers led to a crash in HALCON, if there was not enough available memory. This problem has been fixed.
    • Opening a GigE Vision device was not possible, if ROI parameters like 'OffsetX', 'OffsetY', 'Width', or 'Height' were not writable. This problem has been fixed.
    • Opening a GigE Vision device crashed if you tried setting 'OffsetX' and/or 'OffsetY' to values different than zero. This problem has been fixed.
    • When using a configuration file for a GigE Vision camera the parameters 'OffsetX' and 'OffsetY' were not set correctly. This problem has been fixed.
    • The buffer type scatter gather is now the first option used when trying to allocate the acquisition buffers.
    • When acquiring very large images HALCON sometimes crashed. This problem has been fixed.
  • Revision 13.0.2 (Jan 10, 2018):
    • The technical dependency from the HALCON Library has been removed.
    • Added support for the 'Mono4p' pixel format.
    • Setting 'line_end' callback if the capability was not available on the device generated a crash. This problem has been fixed.
    • The operator grab_image_start failed (H_ERR_FGSETPAR) after changing the 'buffer_cycle_mode' parameter. This problem has been fixed.
    • When opening the framegrabber if the scatter and scatter physical buffer types were not available the operator failed. This problem has been fixed by additionally trying to set a contiguous buffer as a third and last option.
    • The Acquisition (framegrabbers) and AcqDevice (cameras) event callbacks are now supported.
    • The HDevelop example saperalt_turbodrive.hdev has been improved by using the 'transferQueueCurrentBlockCount' parameter.
    • In case of failure the interface can now provide additional information by returning the SaperaLT status codes as extended error messages when available.
    • The value 'camera' has been added to the parameter 'linescan_direction'.
    • The parameter 'linescan_direction_source' has been added.
    • The 'image_part' parameter sometimes failed to crop the image to the specified values. This problem has been fixed.
  • Revision 13.0.1 Addendum (Jul 14, 2017):
    • TurboDrive has been added to the features list.
    • The HDevelop example saperalt_turbodrive.hdev has been added to show the usage of the TurboDrive feature.
  • Revision 13.0.1 (Oct 28, 2016):
    • HALCON 13 version of the interface.
    • On Windows systems the maximum length for a path was limited to 260 characters. This problem has been fixed. Now, the maximum total path length on Windows systems is 32,767 characters.
  • Revision 6.7 (Jun 24, 2016):
    • Adapted to Sapera LT SDK 8.0.
    • When getting an timeout error a mutex wasn't unlocked, so a call of close_framegrabber led to a crash. This problem has been fixed.
    • Switching between grab_image and grab_image_async or a double call of grab_image_start could lead to a state that no more image could be grabbed. This problem in the internal buffer queue has been fixed.
    • After a timeout sometimes no new image could be grabbed. This problem has been fixed.
    • The parameters 'line_integration_time_base', 'line_trigger', 'line_trigger_delay', 'line_trigger_duration', and 'line_trigger_method' have been added.
    • The values '12 Volts', '24 Volts', 'LVTTL', and 'OPTO' have been added to the parameters 'ext_frame_trigger_level', 'ext_line_trigger_level', 'ext_trigger_level', 'shaft_encoder_level', and 'strobe_level'.
    • The values '12 Volts', 'LVTTL', and 'OPTO' have been added to the parameter 'gio_input_level'.
    • The parameter 'bayer_hardware_decoder_method' has been extended by method 7.
    • The parameter 'time_integration_method' has been extended by methods 10, 11, and 12.
    • The values 'lvttl' and 'ttl' have been added to the parameter 'gio_output_type'.
  • Revision 6.6 (Feb 15, 2016):
    • Using the parameter 'hardware_bayer_decoder_method' led to a crash in some cases. This problem has been fixed.
    • Using the output formats RGB888 or RGB101010 led to wrong color format in HALCON. This problem has been fixed.
    • Added support for the 'Mono10p' and 'Mono12p' pixel formats.
  • Revision 6.5 (Dec 10, 2015):
    • Grabbing images with a Xtium board led sporadically to error messages. This problem has been fixed.
    • The callback type of the user-specific callback 'transfer_end' has changed from CORXFER_VAL_EVENT_TYPE_END_OF_FRAME to CORXFER_VAL_EVENT_TYPE_END_OF_TRANSFER.
    • The parameter 'buffer_cycle_mode_values' returned a static list. Now it queries the available modes of the board. Note that it works only, if a Xfer is connected, which means that the buffers are allocated.
    • Added missing description of operators get_framegrabber_lut and set_framegrabber_lut.
    • Added hint how to save the ccf file via CamExpert in section System Requirements.
  • Revision 6.4 (Oct 20, 2015):
    • When using a GEV linescan camera with a ccf file the settings of the ccf file were ignored and the maximum height set. This problem has been fixed.
    • In some cases a previous error during open_framegrabber prevented a successful connection to a GEV camera. This problem has been fixed.
    • Not all parameters of the ccf file were set to a CL camera. This problem has been fixed.
    • The parameters 'horizontal_resolution' and 'vertical_resolution' of info_framegrabber didn't return all possible values. This problem has been fixed.
    • The description of the parameters 'HorizontalResolution', 'ImageHeight', 'ImageWidth', 'VerticalResolution', and 'CameraType' has been updated.
  • Revision 6.3 (Aug 24, 2015):
    • grab_image_start didn't work anymore, if no image was grabbed before. This problem has been fixed.
    • Some parameters for Camera Link cameras returned wrong values when called via get_framegrabber_param. This problem has been fixed.
    • For GigE Vision cameras no camera configuration file is needed anymore, so the description of the parameters 'camera_type' and 'device' have been adapted.
    • The description of the parameter 'continuous_grabbing' didn't contain all necessary information. The missing information has been added.
    • The section 'Known Issues' has been added to this documentation.
  • Revision 6.2 (Jun 26, 2015):
    • Aborting grab_image or grab_image_async by the parameter 'do_abort_grab' didn't work in all cases. This problem has been fixed. Now additionally the H_ERR_FGABORTED error (5336) will be returned.
    • If variable image height was used, the resulting HALCON image could contain black lines. This problem has been fixed. Now the images are reduced to the used image height.
    • De-registering transfer_end callback, without grabbing any images before set_framegrabber_callback, crashed. This problem has been fixed.
    • The read-only parameter 'buffer_time_stamp' has been added.
    • Sometimes after setting a parameter a wrong image has been returned by grab_image or grab_image_async. This problem has been fixed. Now a protected internal buffer index queue has been added.
    • The parameter 'bayer_hardware_decoder_method' has been extended by method 4 and 5.
    • The parameter 'bayer_hardware_decoder_method_range' has been changed into 'bayer_hardware_decoder_method_values'. Now only the supported values are returned.
    • The description of the parameters 'grab_timeout' and 'image_height' in this documentation has been updated.
  • Revision 6.1 (Feb 26, 2015):
    • Fixed wrong value of parameter 'image_available', which was never 1.
    • Fixed bug in parameter 'do_abort_grab', which did not work in all cases.
    • Fixed bug in parameter 'decimate_method', which did query the wrong capability.
    • Added parameters 'buffer_cycle_mode' and 'line_number'.
    • Added parameter 'do_clear_buffers' to manually set all queued buffers to black.
    • Added 'line_end' callback to user-specific callbacks.
    • Added missing parameter 'num_buffers' to the documentation of 'set_framegrabber_param'.
    • Added missing parameter 'shaft_encoder' to 'available_param_names'.
    • Added hint of trash buffer to description of parameter 'num_buffers'.
    • Corrected default of parameter 'num_buffers'.
    • Corrected bug in the strings of the low-level error messages.
    • Adapted description of parameter 'external_trigger'.
    • Moved parameter 'trash_counter' from section 'Additional parameters' to section get_framegrabber_param.
    • Revised section about SFNC parameters in this document.
    • Removed outdated note of particular treatment for 'do_abort_grab' in 'grab_timeout' parameter description.
  • Revision 6.0 (Oct 31, 2014):
    • HALCON 12 version of the interface.
  • Revision 5.7 (Sep 12, 2014):
    • Fixed memory leak when grabbing images via grab_image_async or grab_image.
    • Improved function to show low-level error messages.
    • Moved parameters 'image_height', 'image_width', and 'signal_status' to read-only parameters in the HDevelop Image Acquisition Assistant and added them to the info_framegrabber(.., 'parameters_readonly', ...) list.
    • Removed legacy devices from this documentation.
  • Revision 5.6 (Jul 21, 2014):
    • Fixed problem with old images when switching between grab_image and grab_image_async or external trigger.
    • Fixed crash in grab_image and grab_image_async after a timeout occurred.
    • Fixed crash in case of trying to open a device twice.
    • Fixed timeouts in continuous grabbing mode after using external trigger.
    • Fixed bug in set_framegrabber_param when trying to set a parameter without specifying a value.
    • Added support of Genie TS Framework to allow also usage of the Teledyne DALSA Spyder3 GigE Vision camera family.
    • Added user-specific callback 'readout_end' for area scan GigE Vision cameras.
    • Added read-only parameter 'trash_counter' to show number of frames, which could not be fetched. Note that this parameter works only with frame grabber boards.
    • Added read-only parameters 'bits_per_channel' and 'color_space'.
    • Added category 'HALCON Interface'.
    • Added paragraph "General Input/Output" to this document.
    • Added HDevelop example 'saperalt_gio' to show the usage of general input/output pins.
    • Improved documentation of the 'Port' parameter in open_framegrabber (digital boards case).
    • Improved color conversion for GigE Vision cameras.
    • Changed cycle mode of the buffers from CORXFER_VAL_CYCLE_MODE_ASYNCHRONOUS to CORXFER_VAL_CYCLE_MODE_SYNCHRONOUS_NEXT_EMPTY_WITH_TRASH.
    • Changed default for parameter 'ColorSpace' in open_framegrabber to 'default'.
    • Changed user-specific callback 'transfer_end' for GigE Vision cameras from CorAcqDeviceRegister(..., 'End of Readout', ...) to CorXferRegisterCallback(..., CORXFER_VAL_EVENT_TYPE_END_OF_FRAME, ...) since it did not work with line scan cameras.
    • Removed extended waiting time. Now the time to wait is always the current grab_timeout value.
    • Removed frame grabber specific parameters from info_framegrabber(.., 'parameters_readonly', ..) and info_framegrabber(.., 'parameters_writeonly', ..).
  • Revision 5.5 (Oct 11, 2013):
    • Added support of general I/Os via the following parameters: 'do_set_gio_handle', 'do_reset_gio', 'do_release_gio_handle', 'gio_device_id', 'gio_count', 'gio_connector', 'gio_dir_output', 'gio_dir_tristate', 'gio_input_level', 'gio_label', 'gio_output_type', 'gio_state', 'gio_state_mask', 'gio_event_count_falling_edge', 'gio_event_count_rising_edge', and 'gio_callback_mask'.
    • Added callback types 'gio_falling_edge' and 'gio_rising_edge' for general I/Os.
    • Added missing default value to additional get_framegrabber_param entries in this documentation.
    • Added alphabetical sorting for additional parameters in this documentation.
    • Changed displayed error message of Sapera LT low-level error. The new format is "<level>:<module>-<id> (<info>)", where "info" is only shown, if there is some information.
    • Removed parameters 'external_trigger', 'image_height', and 'image_width' from section 'Additional parameters'. They are still described by the standard parameter section.
  • Revision 5.4 (Jun 13, 2013):
    • If the allocation of a buffer via Sapera LT fails, a low-level error is returned and the allocation will be done again with the type CORBUFFER_VAL_TYPE_SCATTER_GATHER only. This can happen in case of large buffers with an amount of > 16GB.
    • Corrected error messages for memory allocation and CorXfer.
    • Removed setting of 'external_trigger' from open_framegrabber for GigE Vision cameras. It still can be set afterwards via set_framegrabber_param.
    • Fixed problem with reading/writing parameters with floating point values.
    • Removed split channel mode, parameter 'channel_height', and HDevelop example program saperalt_split_channel_mode.hdev. For large images HALCON XL has to be used.
    • Added parameters 'bits_per_channel' and 'color_space' as read-only parameters.
    • Added section 'Genie GigE Vision cameras' to this document.
  • Revision 5.3 (Apr 26, 2013):
    • Removed value range check in set_framegrabber_param to avoid problems with specific board types, e.g. Xcelera boards.
    • Added new '_range' parameters. Note that in case of Xcelera boards, some '_range' parameters are not accessible.
    • Updated example programs saperalt_2boards.hdev and saperalt_2cameras.hdev to use the operators dev_set_window and dev_display.
  • Revision 5.2 (Jan 8, 2013):
    • Fixed problem in open_framegrabber if the image height or image width parameters in open_framegrabber were set to a value smaller than 8 (also when such a value was set indirectly via the camera configuration file).
  • Revision 5.1 (Aug 28, 2012):
    • Fixed bug if parameter 'multiple_image_num' was set to a value higher than 4.
    • Fixed return value in set_framegrabber_param: In case of a Camera Link device and an unsupported parameter input value, no error was returned.
  • Revision 5.0 (May 15, 2012):
    • HALCON 11 version of the interface (included in HALCON 11 DVD).
  • Revision 4.11 (Nov 28, 2011):
    • Fixed problem with delay and duration parameters with some frame grabber boards, where valid values could not be set.
    • Corrected return values of parameter 'color_space' in info_framegrabber.
    • Added section 'Waiting time after special functions' to this document.
  • Revision 4.10 (Oct 18, 2011):
    • Added description for parameter 'available_callback_types'.
    • Reduced needed memory in case of using a frame grabber.
    • Removed obsolete parameters 'flat_field' and 'flat_field_select'.
  • Revision 4.9 (Jul 27, 2011):
    • Adapted to Sapera LT 7.0.
    • Fixed problem grabbing images on computers with 64-bit operating system and more than 4GB RAM.
    • Fixed performance problem with Genie cameras, so that the full frame rate can be reached, if 'continuous_grabbing' is enabled.
    • Fixed error message under Windows 7 (H_ERR_FGWP), if a Camera Link camera is used.
    • Fixed wrong return values of parameter 'image_available'.
    • Fixed timeout error when setting parameter 'grab_timeout' to -1.
    • Fixed problem with parameter 'internal_device_pointer' on 64-bit systems with more than 4 GB RAM. Now, the value is returned as a string.
    • Fixed error in open_framegrabber on Windows 7 to prevent timing problems when detecting the camera port on frame grabber boards.
    • Improved internal buffer handling.
    • Improved search path for camera configuration file.
    • Added parameter 'multiple_image_num' to split a buffer in multiple images.
    • Added parameter 'num_buffers' to change the number of used buffers.
    • Added parameters 'line_integration', 'line_integration_duration', 'line_integration_method', 'line_integration_pulse0_delay', 'line_integration_pulse1_delay', 'line_integration_pulse0_duration', 'line_integration_pulse1_duration', 'line_integration_pulse0_signal', and 'line_integration_pulse1_signal' for line scan cameras.
    • Added parameters 'pixel_clock_11', 'pixel_clock_detection', 'pixel_clock_ext', 'pixel_clock_int, and 'pixel_clock_source' to control the pixel clock values.
    • Added 'transfer_end' callback functionality.
    • Added description of the parameter 'bayer_hardware_decoder' to this document.
  • Revision 4.8 (Oct 27, 2010):
    • Fixed timeout error when setting parameter 'grab_timeout' to -1.
  • Revision 4.7 (Sep 10, 2010):
    • Fixed problem with parameter 'continuous_grabbing', which can now be set even if no Xfer has been started. Internally, the buffers will be allocated before the transfer starts.
    • Fixed problem when setting parameters 'TriggerEnable' or 'continuous_grabbing'.
    • HALCON 10 version of the interface (included in HALCON 10 DVD).
  • Revision 4.6 (Jul 30, 2010):
    • Added support of 4-channel RGB images. Therefor it is now possible to specify 'rgbx' in open_framegrabber as a value for ColorSpace. If the output format of the ccf file is no RGB format, the parameter 'pixel_arrangement' has to be set accordingly.
    • Added parameters 'int_line_trigger', 'int_line_trigger_freq', and 'signal_status'.
    • Fixed problem with image transfer connection when using the parameter 'image_part'.
  • Revision 4.5 (May 17, 2010):
    • Fixed crash of HDevelop, when using the Image Acquisition Assistant together with Teledyne DALSA Genie cameras.
    • Fixed image acquisition problem when using PixelFormat 'Bayer Raw10' or color_space 'yuv'.
    • Fixed problem in grab_image_start when using Teledyne DALSA Genie cameras.
    • Separated parameters for Teledyne DALSA Genie cameras and frame grabber boards in get_framegrabber_param and set_framegrabber_param.
    • Fixed problem when setting parameter 'external_trigger' after an image has already been acquired.
    • The dynamic setting of 'Height', 'PixelFormat', 'OffsetX', 'OffsetY' and 'Width' has been improved.
    • The allocation of the image buffers is now done, when a grab is requested and not in open_framegrabber anymore.
    • Changed return value of info_framegrabber(..., 'info_boards', ..).
    • info_framegrabber(..., 'device', ..) now returns the currently available devices instead of a statical list.
    • Moved parameter 'bayer_software_decoder_whitebalance' to hidden parameters for the HDevelop Image Acquisition Assistant.
    • Updated example programs.
  • Revision 4.4 (Mar 16, 2010):
    • The internal memory for the Sapera LT server names was not released in close_framegrabber. This problem has been fixed.
    • Added read-only parameters 'image_height' and 'image_width' for Teledyne DALSA boards.
    • Renamed parameter 'acquisition_handle' to 'internal_device_pointer' to avoid confusion with the parameter AcqusitionHandle in open_framegrabber. For backward compatibility the old parameter name still works.
  • Revision 4.3 (Jan 14, 2010):
    • Fixed bug in open_framegrabber to ensure the proper use of multiple cameras, if device parameter is set to 'default'.
    • Added parameter 'do_force_trigger' to allow software triggering.
  • Revision 4.2 (Nov 10, 2009):
    • Fixed bugs in open_framegrabber, grab_image, and grab_image_async to ensure the proper use of multiple Genie cameras in one application.
    • Fixed bug in general parameter handling to enable the use of all parameters in the HDevelop Image Acquisition Assistant.
    • Added support for RGB161616 color format.
    • Corrected transformation of BGR101010 pixel data to ensure the correct alignment of the pixel values.
  • Revision 4.1 (Mar 5, 2009):
    • Added parameters 'linescan_direction', 'linescan_direction_output', and 'linescan_direction_signal'.
  • Revision 4.0 (Dec 1, 2008):
    • HALCON 9.0 version of the interface (included in HALCON 9.0 DVD). Note that the split channel mode is no more necessary in combination with HALCON XL.
  • Revision 3.4 (Jul 15, 2008):
    • Bug fix in grab_image and grab_image_async in case of an error. Now the next grab returns always the correct image.
    • The HDevelop Image Acquisition Assistant now shows also the HALCON specific parameters in case of Genie cameras.
    • Added buffer rotation mode 'NEXT_EMPTY' with fallback to 'ASYNCHRONOUS'.
  • Revision 3.3 (May 28, 2008):
    • Added support of Windows x64 Edition.
    • Bug fix regarding sporadic timeouts.
    • Added automatic rotation of Sapera LT buffers.
    • Bug fix regarding parameterization of Genie cameras via the HDevelop Image Acquisition Assistant.
  • Revision 3.2 (Apr 22, 2008):
    • Bug fix in registering/unregistering the end-of-frame callback.
    • Bug fix in parameter 'external_trigger'.
    • Added read-only parameters with postfix '_description', '_range', and '_values' to enable the easy parameterization via a generic graphical user interface.
  • Revision 3.1 (Oct 16, 2007):
    • Adapted to SaperaLT 6.0.
    • Added support for Teledyne DALSA Genie GigE Vision camera series.
    • Bug fix in buffer handling.
    • Added parameters 'available_param_descriptions', 'available_param_names', and 'available_param_types'.
    • Added parameters 'continuous_grabbing', 'continuous_grabbing_values', 'start_async_after_grab_async_values', and 'volatile_values'.
  • 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 support for acquiring images with more than 32767 lines by using the so-called split channel mode.
    • Added software Bayer encoder.
    • Added the following parameters: 'bayer_software_decoder_alignment', 'bayer_software_decoder_format', 'bayer_software_decoder_whitebalance', 'bayer_software_decoder', 'bayer_software_decoder_method', and 'channel_height'.
    • Changed name of the parameter 'bayer_decoding' and 'bayer_decoder_method' to 'bayer_hardware_decoder' and 'bayer_hardware_decoder_method'.
    • Fixed bug in ring buffer handling.
    • Fixed bugs in parameters 'do_abort_grab', 'flat_field_select', and 'image_available'.
  • Revision 2.1 (Nov 28, 2005):
    • Added support of LUTs.
    • Added the following parameters: 'acquisition_handle', 'do_abort_grab', 'image_available', and 'lut'.
    • Fixed bug in RGB8888 output format.
  • Revision 2.0 (Oct 26, 2005):
    • First official release.