HALCON 8.0 Image Acquisition Interface for Tattile TAG Cameras
This page provides the documentation of the HALCON TAG interface for the TAG camera family from Tattile s.r.l.. Registered customers can download the latest revision of this interface from the MVTec WWW server.
Revision: 3.2
System Requirements
- Intel compatible PC with Windows 2000/XP Professional.
- HALCON image acquisition interface hAcqTAG.dll or parhAcqTAG.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.
- Successfully installed Tattile TAG SDK including the Tattile TAG filter which must be bound to the used Gigabit ethernet adapter board. The two DLLs TAGFilterLib.dll (version 3.0.8.0) and TAGUtility.dll (version 1.7.4.8) should be copied into the %HALCONROOT%\bin\%HALCONARCH% directory. Note that you cannot connect to the camera via the HALCON TAG interface if the Tattile TAG filter is disabled.
- To obtain the IP addresses of both the ethernet adapter board and the connected TAG camera use the TAGSettings application which is part of the TAG SDK installation.
- Verify the correct IP settings by grabbing images with the TagUnlimitedDemo application. If an ITF_ERROR_MEMORY(5) error occurs during the connection to the camera, follow the instructions in the TAG/TAG2 camera user manual to enable the memory lock-down.
Features
- Support of all Tattile TAG cameras.
- Multiple cameras.
- Synchronous and asynchronous grabbing.
- External trigger.
- Cropping of image parts.
- Software control of strobe, trigger, and exposure settings.
- Software control of the digital input and output lines.
- Setting of LUTs.
Limitations
- grab_data and grab_data_async not supported.
- In case of multiple connected cameras, info_framegrabber(..,'info_boards',...) only returns the requested information from the first camera.
Description
Parameters for open_framegrabber():
| Name | 'TAG' | The name of the HALCON image acquisition interface. | |
| HorizontalResolution | 1, width | The desired image resolution. Use '1' for full resolution or the corresponding absolute value (depending on your camera). Note that the TAG has no hardware scaling, thus, only full resolution is allowed. Default: 1. | |
| VerticalResolution | 1, height | The desired image resolution. Use '1' for full resolution or the corresponding absolute value (depending on your camera). Note that the TAG has no hardware scaling, thus, only full resolution is allowed. 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. Note that the area of the specified image part must be a multiple of 1024 pixels. 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. Note that the area of the specified image part must be a multiple of 1024 pixels. Default: 0. | |
| StartRow | row | The row coordinate of the upper left pixel of the desired image part. Note that the area of the specified image part must be a multiple of 1024 pixels. Default: 0. | |
| StartColumn | column | The column coordinate of the upper left pixel of the desired image part. Note that the area of the specified image part must be a multiple of 1024 pixels. Default: 0. | |
| Field | --- | Ignored. | |
| BitsPerChannel | 5, 8 | The number of significant bits per channel in case of rgb images. Note that this parameter will be ignored if ColorSpace is set to 'default'. Default: 8. | |
| ColorSpace | 'default', 'bayer', 'gray', 'rgb' | The desired color space. Note that in case of 'rgb' the number of significant bits per channel is set by BitsPerChannel. 'default' means that the current camera default value is used. Default: 'default'. | |
| Generic | --- | Ignored. | |
| ExternalTrigger | 'true', 'false' | Activate/deactivate external triggering. Default: 'false'. | |
| CameraType | 'camera_ipaddr' | Specify the IP address of the TAG camera in the dotted form 'aaa.bbb.ccc.ddd'. Note that this IP address must be in the same subnet as the IP address of the ethernet adapter that is specified in the Device parameter. Default: '0.0.0.0'. | |
| Device | 'board_ipaddr' | Specify the IP address of the local Ethernet adapter board in the dotted form 'aaa.bbb.ccc.ddd'. Note that this IP address must be in the same subnet as the IP address of the TAG camera that is specified in the CameraType parameter. Default: '0.0.0.0'. | |
| Port | --- | Ignored. | |
| LineIn | --- | Ignored. | |
Parameters for set_framegrabber_param():
| 'bits_per_channel' | 5, 8 | The number of significant bits per channel in case of rgb images. Note that this parameter is considered only if the parameter 'color_space' is set to 'rgb'. The value 5 means that only 16 bits per pixel are transmitted from the camera: 5 bits for red and blue and 6 bits for green. The value 8 means that 24 bits per pixel are transmitted from the camera: 8 bits for each color. This parameter can be modified only if continuous grabbing is disabled. | |||
| 'color_space' | 'bayer', 'gray', 'rgb' | Color space of the resulting HALCON image. This parameter can be modified only if continuous grabbing is disabled. | |||
| 'continuous_grabbing' | 'enable', 'disable' | Activate or deactivate the free-running acquisition mode. If the continuous mode is enabled, the TAG camera continuously sends images to the host and the TAG filter DLL stores these images in the internal buffers. Note that in this mode both operators grab_image and grab_image_async always fetch the newest available image. Default: 'disable'. | |||
| 'digital_output_0' | 0, 1 | Status of the digital output 0. | |||
| 'digital_output_1' | 0, 1 | Status of the digital output 1. Since the second digital output is also used by the strobe you must disable the strobe usage by set_framegrabber_param(...,'strobe',...). | |||
| 'exposure_delay' | usec | Specify delay in µs between the trigger and the start of the image exposure. | |||
| 'exposure_mask' | 'enable', 'disable' | Enable/disable the exposure mask mode. Note that this mode only works in normal grab mode. This parameter can be modified only if continuous grabbing is disabled. | |||
| 'exposure_time' | 66...100000 | Exposure time in µs. | |||
| 'exposure_time_as_trigger' | 'enable', 'disable' | Enable/disable the trigger controlled exposure mode. In this mode the CCD exposure time is given by the duration of the trigger signal. For using this feature the trigger must be activated. This parameter can be modified only if continuous grabbing is disabled. | |||
| 'external_trigger' | 'true', 'false' | Activate/deactivate external triggering. To use external triggering it is mandatory to enable the continuous grabbing mode. This parameter can be modified only if continuous grabbing is disabled. | |||
| 'gain' | 0.0 ... 600.0 | Specify amplification factor for video amplifier. | |||
| 'gain_blue' | 0 ... 4095 | Specify blue gain of the color space converter. | |||
| 'gain_green' | 0 ... 4095 | Specify green gain of the color space converter. | |||
| 'gain_red' | 0 ... 4095 | Specify red gain of the color space converter. | |||
| 'grab_bandwidth' | 0, MB/s | Specify the maximum band width in MB/s (or 0 for full band width). This parameter is considered only if the parameter 'grab_mode' is set to 'bandwidth'. This parameter can be modified only if continuous grabbing is disabled. | |||
| 'grab_fps' | fps | Specify the maximum frame rate. This parameter is considered only if the parameter 'grab_mode' is set to 'fixed_fps'. This parameter can be modified only if continuous grabbing is disabled. | |||
| 'grab_mode' | 'normal', 'bandwidth', 'fixed_fps', 'trigger_delay', 'alternate', 'record', 'play' | Specify the desired grab mode. This parameter can be modified only if continuous grabbing is disabled. | |||
| 'grab_timeout' | msec | Specify the desired timeout (milliseconds passed as an integer) for aborting a pending grab. Default: 5000. | |||
| 'grab_trigger_delay' | msec | Specify the delay in msec between the trigger and the start of the frame transmission. This parameter can be modified only if continuous grabbing is disabled. | |||
| 'image_height' | -1, height | The height of the desired image part (or -1 for the maximum image height). | |||
| 'image_part' | [row1, col1, row2, col2] | Specifiy the upper left (row1, col1) and lower right (row2, col2) corner of the desired image part. Note that the area of the specified image part must be a multiple of 1024 pixels. | |||
| 'image_width' | -1, width | The width of the desired image part (or -1 for the maximum image width). | |||
| 'normalization' | 'enable', 'disable' | Enable/disable luminance normalization. The normalization image has to be sent to the camera by set_framegrabber_param(...,'do_send_normalization_image',...). This parameter can be modified only if continuous grabbing is disabled. | |||
| 'offset' | 0 ... 255 | Specify offset level of the ADC converter. | |||
| 'start_column' | column | The column coordinate of the upper left pixel of the desired image part. | |||
| 'start_row' | row | The row coordinate of the upper left pixel of the desired image part. | |||
| 'strobe' | 'enable', 'disable' | Enable/disable the strobe usage. The strobe must be disabled if the second output should be used as a normal digital output. | |||
| 'strobe_delay' | usec | Specify delay in µs between the trigger and the start of the strobe signal. | |||
| 'strobe_time' | usec | Specify time in µs of raising the strobe output during image exposure. | |||
| 'test_image' | 'enable', 'disable' | Enable/disable test image sending. | |||
| 'trigger_signal' | 'falling', 'rising' | Specify the trigger event type (slope) for external triggering. This parameter can be modified only if continuous grabbing is disabled. | |||
| 'volatile' | 'enable', 'disable' | Grayscale only. In the volatile mode the 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! Default: 'disable'. | |||
| 'white_balance' | 'enable', 'disable', 'enable_analog' | Enable/disable automatic white balancing. The white balance changes the red, green, and blue gain. | |||
| 'do_abort_grab' | --- | This action parameter forces a pending grab_image or grab_image_async operator to abort the current grab. Note that using this parameter is only possible in combination with Parallel HALCON. | |||
| 'do_send_normalization_image' | filename | File name of the normalization image which is sent to the camera. This image must be a gray level BMP file with the same resolution as the CCD of the used TAG camera. | |||
Parameters for get_framegrabber_param():
Additional parameters supported by get_framegrabber_param only. Note that all parameters supported by set_framegrabber_param except the ones with prefix 'do_' can also be accessed by get_framegrabber_param. Furthermore, corresponding to the parameters supported by set_framegrabber_param, there may exist additional read-only parameters with the following postfixes:
- '_description': These parameters provide the tooltip of the corresponding parameter as a string.
- '_range': These parameters provide the minimum, maximum, stepwidth, and default values for the corresponding integer or float parameter as a tuple with 4 elements, e.g., get_framegrabber_param(..,'exposure_range',..) will return the output tuple [min,max,step,default]. Optionally, this tuple can also contain additional valid string values like 'auto' or 'manual'.
- '_values': These parameters provide the valid value list for the corresponding parameter as a tuple, e.g., get_framegrabber_param(..,'volatile_values',..) will return the output tuple ['enable','disable'].
| 'digital_input_0' | 0, 1 (long) | Current status of the digital input 0. | |||
| 'digital_input_1' | 0, 1 (long) | Current status of the digital input 1. | |||
| 'revision' | revision (string) | The revision number of the HALCON TAG interface. | |||
| 'temperature' | temp (long) | Current temperature of the camera. | |||
Lookup Tables:
Lookup tables can be set using the operators set_framegrabber_lut. The TAG cameras use 256 entries per LUT, which has to be passed as three array of integers. Note that only the values for the green channel are actually used.
Release Notes
-
Revision 3.2 (Apr 23, 2008):
- Adaptation to new Tattile SDK (see specific DLL versions in the System Requirements section).
- Bugfix in open_framegrabber to avoid occasionally error messages regarding a wrong chosen image part.
- Bugfix in close_framegrabber to eliminate a memory leak when using multiple cameras.
- Added read-only parameters with postfix '_description', '_range', and '_values' to enable the easy parameterization via a generic graphical user interface.
-
Revision 3.1 (Sep 12, 2007):
- Adaptation to Tattile SDK 2.0 (see specific DLL versions in the System Requirements section).
- New parameter 'temperature'.
- Updated value lists for info_framegrabber queries.
-
Revision 3.0 (May 15, 2007):
- HALCON 8.0 version of the interface (included in HALCON 8.0 DVD).
-
Revision 2.0 (Aug 8, 2005):
- HALCON 7.1 version of the interface (included in HALCON 7.1 CD).
- First official release.
