HALCON 7.1 Frame Grabber Interface for Basler eXcite
This page provides the documentation of the HALCON eXcite frame grabber interface for the eXcite smart camera from Basler Vision Technologies. Registered customers can download the latest revision of this interface from the MVTec WWW server.
Revision: 2.4
Operation modes
There are three ways to use the eXcite smart camera:
- Remote mode with Linux OS.
- Remote mode with Windows OS.
- Local mode with Linux OS (MIPS processor).
Attention using remote mode:
- Before grabbing images remote from the camera make sure that the gxbaslercam service is running on the camera.
- There can occur timeouts (black images), if the network load is too high.
- Many users can connect to the camera, but only one user is able to grab images.
- If you are using Windows XP with Service Pack 2, please make sure that your firewall settings allow to connect to the camera, otherwise the grabbing fails (timeouts).
- All modes: The user (usually excite) accessing the camera either when starting gxbaslercam for remote access or when using the camera locally must have read and write access to the necessary device files /dev/ttycci0, /dev/xcam/xicap0 and /dev/watchdog.
System Requirements
-
Basler eXcite software package:
Linux (local): Successfully installed Linux operating system and camera driver on the eXcite.
Windows (remote): The eXcite\bin directory and the successfully installed eXcite camera library gttrans.dll must be within your search path %PATH%. If you do not have this library, please contact Basler or the vendor from which you bought the camera.
Linux (remote): The eXcite\bin directory and the successfully installed eXcite camera library libbaslercam.so and libgxcam.so must be in the search path of your system. If you do not have these libraries, please contact Basler or the vendor from which you bought the camera. - Linux (local): HALCON frame grabber interface HFGeXcite.so for Linux. If you have properly installed the interface, this shared object should reside in lib\mips64-basler-linux2.6 within the HALCON base directory %HALCONROOT% you have chosen during the installation of HALCON.
-
Windows (remote):
HALCON frame grabber interface HFGeXcite.dll or
parHFGeXcite.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. - Linux (remote): HALCON frame grabber interface HFGeXcite.so for Linux. If you have properly installed the interface, this shared object should reside in lib\i586-linux2.2-gcc33 within the HALCON base directory %HALCONROOT% you have chosen during the installation of HALCON.
Features
- Synchronous and asynchronous grabbing.
- External trigger.
- Software control of shutter time.
- Software control of gain and brightness.
- Software control of the digital input and output lines.
Limitations
- grab_region and grab_region_async not supported.
- No LUTs.
- YUV 4:2:2 not supported yet.
- Strobe not supported yet.
Description
Parameters for open_framegrabber():
| Name | 'eXcite' | The name of the HALCON frame grabber interface. | |||
| HorizontalResolution | --- | Ignored. | |||
| VerticalResolution | --- | Ignored. | |||
| ImageWidth | 0, width | The width of the desired image part ('0' stands for the complete image). Default: 0. | |||
| ImageHeight | 0, height | The height of the desired image part ('0' stands for the complete image). Default: 0. | |||
| StartRow | 0, row | The row coordinate of the upper left pixel within the desired image part. Default: 0. | |||
| StartColumn | 0, column | The column coordinate of the upper left pixel within the desired image part. Default: 0. | |||
| Field | --- | Ignored. | |||
| BitsPerChannel | 8, 10, 12 | Number of bits per image channel. Default: 8. | |||
| ColorSpace | 'gray', 'bayer' | Specify the desired color space and thus the number of image channels of the resulting HALCON image. Default: 'gray'. | |||
| Gain | --- | Ignored. | |||
| ExternalTrigger | 'true', 'false' | Activate/deactivate external triggering. Default: 'false'. | |||
| CameraType | --- | Ignored. | |||
| Device | '0', 'ip_address' | Select the camera to connect. '0' selects the first detected camera. With the IP address any available camera in the network can be selected. Default: '0'. | |||
| Port | --- | Ignored. | |||
| LineIn | --- | Ignored. | |||
Parameters for set_framegrabber_param():
| 'brightness' | brightness | Sets the brightness of the camera. | |||
| 'digital_output' | [port0 (long), port1 (long), port2 (long), port3 (long)] | Sets the values of the digital output ports. The value could be either 0 or 1. | |||
| 'do_abort_grab' | --- | Aborts the current grab. | |||
| 'external_trigger' | 'true', 'false' | Enables/disables the trigger mode. Be aware of the settings your camera supplies. | |||
| 'grab_timeout' | 100 ... 327680 | Specifies the desired timeout (milliseconds passed as an integer) for aborting a pending grab. Default: 500. | |||
| 'image_height' | height (long) | Specifies the height of the grabbed image. If the value is not divisible by two, it will be rounded to next valid value. | |||
| 'image_width' | width (long) | Specifies the width of the grabbed image. If the value is not divisible by two, it will be rounded to next valid value. | |||
| 'shutter' | shutter | Specifies the desired exposure time of the camera. The exposure time is 20 microseconds multiplied with the shutter value. | |||
| 'start_async_after_grab_async' | 'enable', 'disable' | By default, at the end of grab_image_async a new request for an asynchronous grab command is automatically given to the camera. If the parameter 'start_async_after_grab_async' is set to 'disable' this new grab command is omitted. Default: 'enable'. | |||
| 'start_async_after_timeout' | 'enable', 'disable' | If this parameter is enabled, the buffer is flushed after a timeout occurred. Otherwise, you get the last image acquired before the timeout. | |||
| 'start_column' | column (long) | Specifies the start column of the grabbed image. If the value is not divisible by two, it will be rounded to next valid value. Please note that you can only change the 'start_column' value if you have reduced the image width. | |||
| 'start_row' | row (long) | Specifies the start row of the grabbed image. If the value is not divisible by two, it will be rounded to next valid value. Please note that you can only change the 'start_row' value if you have reduced the image height. | |||
| 'trigger_mode' | 0, 1, 2, 3 | Specifies the desired trigger mode. 0 is the 'Programmable Mode', which means that the exposure time is determined by the shutter. 1 is the 'Level Controlled Exposure Mode', which means that the duration of the specified trigger signal determines the exposure time. | |||
| 'trigger_signal' | 'falling', 'rising' | Specifies the desired type of trigger signal. | |||
| 'trigger_source' | 0, 1, 2, 3 | Sets the physical input ports for the trigger. | |||
| 'video_gain' | video gain | Sets the video gain of the camera. | |||
| '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 can also be accessed by get_framegrabber_param.
| 'brightness_range' |
[min (long), max (long), step_width (long), current_value (long)] |
Returns the supported values of the 'brightness' parameter. The four elements contain the minimal and maximal gain value, the step width, and the current brightness value. | |||
| 'digital_input' | [port0 (long), port1 (long), port2 (long), port3 (long)] | Gets the values of the digital input ports. | |||
| 'image_available' | 0, 1 | Returns the status of the last asynchronous grab command. The value 1 means that the image is already acquired and thus can be fetched by grab_image_async without delay. Note that this parameter is especially useful in combination with external triggering. | |||
| 'image_height_range' | [min (long), max (long), step (long), default (long)] | Returns the supported range of the 'image_height' parameter. The four elements contain the minimal and maximal settable value, the step width, and the current value of the image height. | |||
| 'image_width_range' | [min (long), max (long), step (long), default (long)] | Returns the supported range of the 'image_width' parameter. The four elements contain the minimal and maximal settable value, the step width, and the current value of the image width. | |||
| 'revision' | revision | The revision number of the HALCON eXcite interface. | |||
| 'shutter_range' |
[min (long), max (long), step_width (long), current_value (long)] |
Returns the supported range of the 'shutter' parameter. The four elements contain the minimal and maximal settable value, the step width, and the current value of the shutter. | |||
| 'start_async_after_grab_async_values' | values | Returns the supported values for the parameter 'start_async_after_grab_async'. | |||
| 'start_async_after_timeout_values' | values | Returns the supported values for the parameter 'start_async_after_timeout'. | |||
| 'start_row_range' | [min (long), max (long), step (long), default (long)] | Returns the supported range of the 'start_row' parameter. The four elements contain the minimal and maximal settable value, the step width, and the current value of the start row. | |||
| 'start_column_range' | [min (long), max (long), step (long), default (long)] | Returns the supported range of the 'start_column' parameter. The four elements contain the minimal and maximal settable value, the step width, and the current value of the start column. | |||
| 'trigger_mode_range' |
[min (long), max (long), step_width (long), current_value (long)] |
Returns the supported range of the 'trigger_mode' parameter. The four elements contain the minimal and maximal settable value, the step width, and the current value of the trigger mode. | |||
| 'trigger_source_range' | [<list of supported trigger sources> (string)] | Returns the supported range of the 'trigger_source' parameter. The four elements contain the minimal and maximal settable value, the step width, and the current value of the trigger source. | |||
| 'video_gain_range' |
[min (long), max (long), step_width (long), current_value (long)] |
Returns the supported values of the 'video_gain' parameter. The four elements contain the minimal and maximal gain value, the step width, and the current gain value. |
Release Notes
-
Revision 2.4 (Oct 18, 2007):
- Bugfix in grab_image after a timeout occurred.
- Added parameters 'start_async_after_grab_async', 'start_async_after_grab_async_values', 'start_async_after_timeout', and 'start_async_after_timeout_values'.
-
Revision 2.3 (Sep 20, 2007):
- Fixed bug in grab_image after a timeout occurred.
-
Revision 2.2 (Dec 7, 2006):
- Fixed bug in grab_image_async in combination with external trigger.
-
Revision 2.1 (Jun 6, 2006):
- Fixed bug in external trigger settings.
- Fixed bug in buffer handling (old images in grab_image_async).
- Removed the parameters 'continuous_grabbing' and 'software_trigger'.
- Changed 'ColorSpace' parameter 'raw' to 'bayer'.
- Enhanced error handling in remote mode.
- Added support for 12 bpp cameras.
- Several small bugfixes.
-
Revision 2.0 (Apr 19, 2006):
- First official release.
