MVTec HALCON 7.0: Frame Grabber Interface for DALSA Boards via Sapera LT library
This page provides the documentation of the HALCON SaperaLT interface for analog and digital frame grabber boards like X64-CL, X64-AN Quad, PC2-Vision, Viper, and Bandit-II from DALSA. Registered customers can download the latest revision of this interface from the MVTec WWW server.
Revision: 2.2
System Requirements
- Intel compatible PC with Windows NT/2000/XP.
- Successfully installed Sapera LT software library (version 5.2 or higher) as well as the camera configuration and demo executable CamExpert. Make sure that the environment variables %SAPERADIR% and %CAMEXPERTDIR% are set correctly to the particular installation directory. Note that for using the HALCON SaperaLT interface you need a valid .ccf file for your specific camera configuration which must be created using the DALSA CamExpert application!
- HALCON frame grabber interface HFGSaperaLT.dll or parHFGSaperaLT.dll, respectively. If you have properly installed the interface, both DLLs should reside in bin\i586-nt4 within the HALCON base directory %HALCONROOT% you have chosen during the installation of HALCON.
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 DALSA frame grabber boards.
- External trigger and asynchronous camera reset.
- Cropping of image parts.
- Support of images with height >32767 (split channel mode).
- Setting of lookup tables.
- Software bayer decoding.
- Software control of a wide range of configuration parameters.
Limitations
- grab_region and grab_region_async not supported.
Description
Parameters for open_framegrabber():
| Name | 'SaperaLT' | The name of the HALCON frame grabber interface. | |||
| HorizontalResolution | 1 | Ignored (the actual image resolution is set via the camera configuration file specified in the CameraType parameter!). Default: 1. | |||
| VerticalResolution | 1 | Ignored (the actual image resolution is set via the camera configuration file specified in the CameraType parameter!). Default: 1. | |||
| ImageWidth | 0, width | The width 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. Default: 0. | |||
| ImageHeight | 0, height | The 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. Default: 0. | |||
| StartRow | row | The row coordinate of the upper left pixel of the desired image part. Default: 0. | |||
| StartColumn | column | The column coordinate of the upper left pixel of the desired image part. Default: 0. | |||
| Field | --- | Ignored. | |||
| BitsPerChannel | --- | Ignored (the desired pixel depth will be set accordingly to the parameter settings in the camera configuration file). | |||
| ColorSpace | --- | Ignored (the desired pixel depth will be set accordingly to the parameter settings in the camera configuration file). | |||
| Gain | --- | Ignored. | |||
| ExternalTrigger | 'true', 'false' | Activate/deactivate external triggering. Note that the setting in the camera configuration file is ignored! Default: 'false'. | |||
| CameraType | 'default' | 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\DALSA Coreco\Sapera\CamFiles\User\myCameraConfig.ccf'). | |||
| Device | 'default', 'Bandit-II_CV_1', 'Bandit-II_MV_1', 'Bandit-II_RGB_1', 'PC2-Vision_1', 'PC2-CamLink_1' 'Viper_CamLink_1', 'Viper_Digital_1', 'Viper_Quad_1', 'Viper_RGB_1', 'X64-AN_Quad_1', 'X64_1', 'X64-CL_iPro_1', 'X64-CL_Dual_1', 'X64-LVDS_1', ... | The name of one of the desired DALSA frame grabber boards. If you have more than one board with the same name, the number at the end of the device name is counted upwards to access each board separately. If 'default' is specified, the interface will refer to the first device that can be found. Default: 'default'. | |||
| Port | -1, 0, 1, 2, 3, 4, 5 | Specifies the number of the desired camera port. If -1 is selected, the port will be selected from the configuration file. If this fails, the first active device found is selected (analog boards only). Default: -1. | |||
| LineIn | --- | Ignored. | |||
Parameters for set_framegrabber_param():
| 'bayer_hardware_decoder_method' | 1, 2, 3 | Sets the method for data conversion of the hardware bayer decoder. | |||
| 'bayer_software_decoder' | 'enable', 'disable' | Enables or disables the software bayer decoder. The setting takes effect with the next call of 'grab_image' or 'grab_image_async'. Note that you have to set all parameters starting with 'bayer_decoder' before the bayer conversion works. | |||
| 'bayer_software_decoder_alignment' | 'gb_rg', 'bg_gr', 'rg_gb', 'gr_bg' | Sets the alignment of the upper left 2x2 square of the camera`s bayer scheme. Default: 'gb_rg'. | |||
| 'bayer_software_decoder_format' | 'RGB888', 'RGB8888', 'RGB101010' | Sets the output buffer format of the software bayer decoder. 'RGB101010' is only available, if the input format is MONO16! Default: RGB888. | |||
| 'bayer_software_decoder_method' | 1, 2, 3 |
Sets the method for data conversion of the software bayer decoder.
|
|||
| 'bayer_software_decoder_whitebalance' | [wb.red, wb.green, wb.blue] | Sets the 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. Default: [1.0, 1.0, 1.0]. | |||
| 'bit_ordering' | 'std', '9_10', msb_10', 'msb_12', 'inv' |
The digital bit ordering of the camera.
|
|||
| 'brightness' | min...max | Specifies the brightness of the video signal. Represents the percentage of brightness to add or subtract to the composite video signal (analog only). | |||
| 'brightness_blue' | min...max | Specifies the brightness of the blue video signal. Represents the percentage of brightness to add or subtract to the blue video signal (analog only). | |||
| 'brightness_green' | min...max | Specifies the brightness of the green video signal. Represents the percentage of brightness to add or subtract to the green video signal (analog only). | |||
| 'brightness_red' | min...max | Specifies the brightness of the red video signal. Represents the percentage of brightness to add or subtract to the red video signal (analog only). | |||
| 'cam_reset' | 'enable', 'disable' | Enables or disables the reset pulse to the camera. You must have set the signal properties and the method first. | |||
| 'cam_reset_delay' | 0...max | Reset pulse delay (in µs). After receiving a trigger pulse, the acquisition device will wait this delay before generating the reset pulse. | |||
| 'cam_reset_duration' | 1...65535000 | Duration of the reset pulse. | |||
| 'cam_reset_signal' | 'active_low', 'active_high' | Defines the reset pulse signal. | |||
| 'cam_trigger_delay' | min...max | Represents the delay (in µs) the acquisition device will wait, before generating the trigger pulse (external, internal or software). | |||
| 'cam_trigger_duration' | min...max | The effect of this value differs addicted to the selected method. | |||
| 'cam_trigger' | 'enable', 'disable' | Enables or disables the frame trigger pulse to the camera (area scan only). | |||
| 'cam_trigger_method' | 1, 2 | Defines the trigger method of the camera, see Sapera LT documentation for more details. | |||
| 'cam_trigger_signal' | 'active_low', 'active_high' | Defines the camera trigger signal. | |||
| 'channel_height' | height | Specifies the channel height in the split channel mode. | |||
| 'contrast' | min...max | Specifies the 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' | min...max | Specifies the 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' | min...max | Specifies the 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' | min...max | Specifies the 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' | 0...max | Specifies the number of fields or frames to decimate per second. | |||
| 'decimate_method' | 'disable', 'field', 'frame', 'even', 'odd' | Defines the decimation method, see Sapera LT documentation for more details. | |||
| 'do_abort_grab' | --- | Aborts the current grab. | |||
| 'ext_frame_trigger' | 'enable', 'disable' | Enables or disables external frame trigger (line scan cameras only). You must have set the signal properties first. | |||
| 'ext_frame_trigger_level' | 'TTL', 'RS-422', 'LVDS' | Defines the external frame trigger level connected to the acquisition device (line scan cameras only). | |||
| 'ext_frame_trigger_signal' | 'active_low', 'active_high', 'falling', 'rising', 'double_rising', 'double_falling' | Defines the 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' | 0...max | Specifies the physical input source the external frame trigger is connected to on the acquisition device, in the case where the acquisition device has more than one input. Default: 0. | |||
| 'ext_line_trigger' | 'enable', 'disable' | Enables or disables external line trigger (line scan cameras only). You must have set the signal properties first. | |||
| 'ext_line_trigger_level' | 'TTL', 'RS-422', 'LVDS' | Defines the external line trigger level connected to the acquisition device (line scan cameras only). | |||
| 'ext_line_trigger_signal' | 'falling', 'rising' | Defines the external line trigger signal connected to the acquisition device (line scan cameras only). | |||
| 'ext_line_trigger_source' | 0...max | Specifies the 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. Default: 0. | |||
| 'external_trigger' | 'true', 'false' | Specifies if external triggering is used. Default: 'false'. | |||
| 'ext_trigger_delay' | 0 ... max | Represents the delay of the external trigger signal in units specified by 'ext_trigger_delay_time_base'. Default: 0. | |||
| 'ext_trigger_delay_time_base' | 0 ... max | Represents the granularity of units required to adjust the delay of the external trigger signal with 'ext_trigger_delay'. Default: 0. | |||
| 'ext_trigger_duration' | 0 ... max | Minimum external trigger pulse duration. For details please refer to the 'Sapera Acquisition Parameter' manual. Default: 0. | |||
| 'ext_trigger_level' | 'TTL', 'RS-422', 'LVDS' | Defines the external trigger level connected to the acquisition device. Default: 'TTL'. | |||
| 'ext_trigger_signal' | 'active_low', 'active_high', 'falling', 'rising' | Defines the external trigger signal connected to the acquisition device. Default: 'rising'. | |||
| 'ext_trigger_source' | 0, 1, 2 | Specifies the 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. Default: 0. | |||
| 'flat_field' | 'enable', 'disable' | Enable or disable the flat field resource. | |||
| 'flat_field_select' | 0...(n-1) | Select the active flat field. | |||
| 'frame_integration' | 'enable', 'disable' | 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 | Specifies the numer of frames to integrate. | |||
| 'frame_integration_method' | 1, 2 | Defines the frame integration method, see Sapera LT documentation for more details. | |||
| 'frame_integration_signal' | 'active_low', 'active_high' | Defines the frame integration signal. | |||
| 'grab_timeout' | msec | Specify the desired timeout (milliseconds passed as an integer) for aborting a pending grab. The value -1 means to never abort. Default: 5000. | |||
| 'hue' | min...max | Specifies the phase change in degrees applied to the hue control (analog composite or Y/C only). | |||
| 'image_part' | [row1,col1,row2,col2] | 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 has 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. | |||
| 'int_frame_trigger' | 'enable', 'disable' | Enables or disables internal frame trigger (area scan cameras only). You must have set the trigger frequency first. | |||
| 'int_frame_trigger_freq' | min...max | Defines the internal frame trigger frequency in milli-Hz (area scan cameras only). | |||
| 'lut' | 'enable', 'disable' | Enables or disables the lookup table. Default: disable. Caution: On some aquisition devices, the LUT can not be disabled. | |||
| 'port' | 0, 1, 2, 3, 4, 5 | Specifies the number of the desired camera port. | |||
| 'saturation' | min...max | Specifies the color saturation percentage control (analog composite only). | |||
| 'shaft_encoder' | 'enable', 'disable' | Enables or disables shaft encoder support of the acquisition device. | |||
| 'shaft_encoder_drop' | 0...max | Specifies the number of dropped signal edges using a shaft encoder. | |||
| 'shaft_encoder_level' | 'TTL', 'RS-422', 'LVDS' | Shaft encoder level fed to the acquisition device (line scan cameras only). | |||
| 'shaft_encoder_multiply' | min...max | Number of signal edges generated for each shaft encoder signal edge, when video acquisitions are controlled by an external shaft encoder trigger. | |||
| 'sharpness' | min...max | Specifies the sharpness control applied to the video signal (analog composite only). | |||
| 'start_async_after_grab_async' | 'enable', 'disable' | By default, at the end of grab_image_async a new asynchronous grab command is automatically given to the frame grabber board. If the parameter 'start_async_after_grab_async' is set to 'disable', this new grab command is omitted. This might be useful especially for switching between several connected cameras. Default: 'enable'. | |||
| 'strobe' | 'enable', 'disable' | Enables or disables the strobe pulse. You must have set the signal properties and the method first. | |||
| 'strobe_delay' | min...max | Specifies the strobe pulse delay 1 (in µs). | |||
| 'strobe_delay2' | min...max | Specifies the strobe pulse delay 2 (in µs). | |||
| 'strobe_duration' | min...max | Specifies the strobe pulse width (in µs). | |||
| 'strobe_level' | 'TTL', 'RS-422', 'LVDS' | Strobe signal level output by the acquisition device. | |||
| 'strobe_method' | 1, 2 | Selects the strobe pulse output method, see Sapera LT documentation for more details. | |||
| 'strobe_signal' | 'active_low', 'active_high' | Defines the strobe pulse signal. | |||
| 'time_integration' | 'enable', 'disable' | 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' | min...max | Time integration delay (in µs). After receiving a trigger pulse, the acquisition device will wait this delay before generating the time integration pulse(s). | |||
| 'time_integration_duration' | min...max | Specifies the time integration pulse width in µs (area scan cameras only). | |||
| 'time_integration_method' | 1, 2, 3, 4, 5, 6, 7, 8 | Defines the time integration method, see Sapera LT documentation for more details. | |||
| 'time_integration_pulse0_delay' | min...max | Time integration delay (in µs) of pulse 0. After receiving a trigger pulse, the acquisition device will wait this delay before generating the time integration pulse 0. | |||
| 'time_integration_pulse1_delay' | min...max | Time integration delay (in µs) of pulse 1. After receiving a trigger pulse, the acquisition device will wait this delay before generating the time integration pulse 1. | |||
| 'time_integration_pulse0_duration' | min...max | Specifies the time integration pulse 0 width (in µs). | |||
| 'time_integration_pulse1_duration' | min...max | Specifies the time integration pulse 1 width (in µs). | |||
| 'time_integration_pulse0_signal' | 'active_low', 'active_high' | Defines the time integration signal of pulse 0. | |||
| 'time_integration_pulse1_signal' | 'active_low', 'active_high' | Defines the time integration signal of pulse 1. | |||
| 'volatile' | 'enable', 'disable' | Grayscale only. In the volatile mode the frame grabber 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! Default: 'disable'. | |||
Parameters for get_framegrabber_param():
Additional parameters supported by get_framegrabber_param only. Note that all parameters supported by set_framegrabber_param except the ones with prefix 'do_' can also be accessed by get_framegrabber_param.
| 'acquisition_handle' | handle | Returns the handle of the current acquisition device to give the user the possibility to write his own functions, if they are not supported by the HALCON interface. | |||
| 'bayer_hardware_decoder' | status | 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! | |||
| 'brightness_range' | [min,max,step,default] | Possible range for brightness of the video signal. | |||
| 'brightness_blue_range' | [min,max,step,default] | Possible range for brightness of the blue video signal. | |||
| 'brightness_green_range' | [min,max,step,default] | Possible range for brightness of the green video signal. | |||
| 'brightness_red_range' | [min,max,step,default] | Possible range for brightness of the red video signal. | |||
| 'camera_model' | model | The name of the camera model. | |||
| 'camera_vendor' | vendor | The name of the camera vendor. | |||
| 'cam_reset_delay_range' | [min,max,step,default] | Possible range for the delay of the camera reset signal. | |||
| 'cam_trigger_delay_range' | [min,max,step,default] | Possible range for the delay of the camera trigger signal. | |||
| 'cam_trigger_method_range' | [min,max,step,default] | Possible range for the method of the camera trigger signal. | |||
| 'contrast_range' | [min,max,step,default] | Possible range for the contrast of the video signal. | |||
| 'contrast_blue_range' | [min,max,step,default] | Possible range for the contrast of the blue video signal. | |||
| 'contrast_green_range' | [min,max,step,default] | Possible range for the contrast of the green video signal. | |||
| 'contrast_red_range' | [min,max,step,default] | Possible range for the contrast of the red video signal. | |||
| 'ext_trigger_delay_range' | [min,max,step,default] | Possible range for the delay of the external trigger signal. | |||
| 'ext_trigger_duration_range' | [min,max,step,default] | Possible range for the duration of the external trigger signal. | |||
| 'ext_trigger_source_range' | [min,max,step,default] | Possible range for the source of the external trigger signal. | |||
| 'frame_integration_method_range' | [min,max,step,default] | Possible range for the method of the frame integration signal. | |||
| 'hue_range' | [min,max,step,default] | Possible range for brightness of the video signal. | |||
| 'image_available' | 0, 1 | Shows if a grabbed image is completely written and available. | |||
| 'int_frame_trigger_freq_range' | [min,max,step,default] | Possible range for the frequency of the internal frame trigger signal. | |||
| 'revision' | revision | The revision number of the HALCON SaperaLT interface. | |||
| 'saturation_range' | [min,max,step,default] | Possible range for saturation of the video signal. | |||
| 'shaft_encoder_drop_range' | [min,max,step,default] | Possible range for the number of signal edges dropped. | |||
| 'shaft_encoder_multiply_range' | [min,max,step,default] | Possible range for the number of signal edges generated for each shaft encoder signal edge. | |||
| 'sharpness_range' | [min,max,step,default] | Possible range for sharpness of the video signal. | |||
| 'strobe_delay_range' | [min,max,step,default] | Possible range for the delay of the strobe signal. | |||
| 'strobe_delay2_range' | [min,max,step,default] | Possible range for the delay2 of the strobe signal. | |||
| 'strobe_duration_range' | [min,max,step,default] | Possible range for the duration of the strobe signal. | |||
| 'strobe_method_range' | [min,max,step,default] | Possible range for the method of the strobe signal. | |||
| 'time_integration_delay_range' | [min,max,step,default] | Possible range for the delay of the time integration signal. | |||
| 'time_integration_duration_range' | [min,max,step,default] | Possible range for the duration of the external trigger signal. | |||
| 'time_integration_method_range' | [min,max,step,default] | Possible range for the method of the time integration signal. | |||
| 'time_integration_pulse0_delay_range' | [min,max,step,default] | Possible range for the delay of pulse0 of the time integration signal. | |||
| 'time_integration_pulse1_delay_range' | [min,max,step,default] | Possible range for the delay of pulse1 of the time integration signal. | |||
| 'time_integration_pulse0_duration_range' | [min,max,step,default] | Possible range for the duration of pulse0 of the time integration signal. | |||
| 'time_integration_pulse1_duration_range' | [min,max,step,default] | Possible range for the duration of pulse1 of the time integration signal. | |||
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.
Split channel mode:
The split channel mode allows the acquisition of images with more than 32767 lines, i.e., image height >32767. By default, an image with image height >32767 lines will automatically be returned as a multi-channel image, where each channel has the same height.With the parameter 'channel_height' you can change this behavior and set the desired number of lines per channel. For example, if the image height is 50000 and 'channel_height' is set to 30000, both channels of the returned image will have a height of 30000 lines, but in the second one only the first 20000 lines are filled with image data. The remaining lines are black.
Please note that the split channel mode works only with grayscale images. In combination with volatile mode, the image height must be a multiple of the channel height.
Since the split channel mode works with large images, please make sure that you have enough memory for the used image buffers!
Release Notes
- 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.
