HALCON 8.0 Image Acquisition Interface for Allied Vision Technologies/intek FirePackage Driver
This page provides the documentation of the HALCON FirePackage interface for the Allied Vision Technologies/intek FirePackage driver. With this interface you can acquire images from IEEE 1394 cameras via any IEEE 1394 adapter cards (PCILynx or OHCI). Registered customers can download the latest revision of this interface from the MVTec WWW server.
Note that the HALCON FirePackage interface is no more recommended. Please use the new universal HALCON 1394IIDC interface instead which supports all IEEE 1394 (a and b) cameras that are compliant to the IIDC 1394 (DCAM) standard, e.g., from Allied Vision, Basler, NET, Point Grey, Prosilica, Sony, The Imaging Source, or Toshiba Teli. This new interface is also based on the high-performance FirePackage driver, but uses the new FireGrab API.
Revision: 3.1
System Requirements
- Intel compatible PC with Windows NT 4.0 (Service Pack 5), Windows 2000 or Windows XP and IEEE 1394 adapter card (PCILynx or OHCI).
-
HALCON image acquisition interface hAcqFirePackage.dll or
parhAcqFirePackage.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 FireDrv.sys driver (version 1.0.2.1 or higher). If you do not have this file, you can download the FirePackage driver from http://www.alliedvisiontec.com.
-
Wrapper DLL FireCtrl.dll (version 1.8.0.9 or higher).
This DLL together with an appropriate license file License.txt
must be located together in one directory within the system
path %PATH%, e.g., C:\Windows\System32.
In order to access IEEE 1394 cameras from Allied Vision Technologies
properly, the file License.txt must contain the key 1EEAF9B450220075!
Note that after the installation of the FirePackage driver the files FireCtrl.dll and License.txt files can be found in the directory [Legacy\]FireCtrl\Lib within the FirePackage directory.
Features
- Supports IEEE 1394-based digital camera compliant to the IIDC 1.30, such as the Dolphin, Marlin, and Oscar camera series from Allied Vision Technologies.
- Synchronous and asynchronous grabbing.
- External camera triggering.
- Provides color space transformation.
- Subsampling (by specifying the corresponding video mode).
- Support of video format 7 (partial scan).
- Software control of a variety of camera parameters.
- Simultanuous acquisition triggered by a software-driven broadcast command to all cameras.
- Listen-only functionality to use the deferred transport capability of AVT cameras.
Limitations
- Supports up to three cameras per board and up to four boards.
- Hot plugging is not supported. Be aware that due to a bus reset the same camera can appear with another number respectively at another port in the image acquisition interface!
- grab_data and grab_data_async not supported.
- No LUTs.
- No support of IEEE 1394b cameras.
Description
Parameters for open_framegrabber():
| Name | 'FirePackage' | The name of the HALCON image acquisition interface. | |||
| HorizontalResolution | --- | Ignored. | |||
| VerticalResolution | --- | Ignored. | |||
| ImageWidth | -1, 0, min ... max | Sets the width of the desired image part if Format_7 is specified in the parameter CameraType. The passed value gets rounded to fit the step width restriction of this parameter (which depends on the camera). min equals the step width whereas max equals the maximum image width. -1 means to adopt the camera setting, 0 means to specify the maximum image width. Default: -1. | |||
| ImageHeight | -1, 0, min ... max | Sets the height of the desired image part if Format_7 is specified in the parameter CameraType. The passed value gets rounded to fit the step width restriction of this parameter (which depends on the camera). min equals the step width whereas max equals the maximum image height. -1 means to adopt the camera setting, 0 means to specify the maximum image height. Default: -1. | |||
| StartRow | -1, 0 ... max | The row coordinate of the upper left pixel of the desired image part if Format_7 is set. The passed value gets rounded to fit the step width restriction of this parameter (which depends on the camera). max equals the maximum image height minus the step width; -1 means to adopt the camera setting. Default: -1. | |||
| StartColumn | -1, 0 ... max | The column coordinate of the upper left pixel of the desired image part if Format_7 is set. The passed value gets rounded to fit the step width restriction of this parameter (which depends on the camera). max equals the maximum image width minus the step width; -1 means to adopt the camera setting. Default: -1. Ignored. | |||
| Field | --- | Ignored. | |||
| BitsPerChannel | --- | Ignored. | |||
| ColorSpace | 'gray', 'rgb', 'yuv', 'default' | Color space of the resulting HALCON image. 'default' means to adopt the supplied camera color space. Default: 'default'. | |||
| Generic | --- | Ignored. | |||
| ExternalTrigger | 'true', 'false' | Activate/deactivate external triggering. Default: 'false'. | |||
| CameraType |
'format:mode:fps[:iso_control]', '7:mode:busload_percentage[:iso_control]', 'default' |
Specify the desired video settings as a string consisting
of the video format (0,1,2 or 7), the video mode (0,1,2,3,4,5,6,7),
and the frame rate (0,1,2,3,4,5 or 1.875,3.75,7.5,15.0,30.0,60.0,
respectively), separated by colons. If video format is set to 7,
the third parameter specifies not the frame rate, but the busload
in percent (of 4096 bytes per packet). 'default' means to
adopt the supplied video settings of the camera and the
ISO transfer will be enabled. Default: 'default'. Optionally, a fourth parameter can be appended specifythe type of image acquisition (one_shot, multi_shot, continuous_shot or listen_only). |
|||
| Device | 'card_number[:speed]' |
The number of the used IEEE 1394 adapter card
(passed as a string!). Default: '0'. An optional parameter separated by colons can be used to adjust the speed (100, 200 or 400) of the IEEE 1394 interface for the device opening (e.g., '0:200'). This speed can differ between cameras on the same card depending on the physical interface which is used. |
|||
| Port | 0, 1, ... | The number of the camera found on the IEEE 1394 bus. Default: 0 (searches for the first camera). | |||
| LineIn | -1, 0, 1, ... | Number of ISO channel used for transmission. -1 means the ISO channel number equals the port number. Default: -1. | |||
Parameters for set_framegrabber_param():
Note that most of the following parameters (and also the valid parameter values!) depend on the capabilities of the used camera.
Many parameters (like 'exposure' and 'brightness') can be set by either a valid integer value or by specifying one of the following strings:
- 'auto' means that the camera controls the value automatically by itself
- 'manual' disables the automatic control mode
- 'one_push' means that the camera controls the value automatically by itself only once and returns to manual control mode
- 'off' fixes the specified value
- 'on' enables the changing of the specified value
| 'acquisition_mode' | 'continuous_shot', 'one_shot', 'multi_shot', 'listen_only' |
Defines the way the camera is requested to acquire images:
|
|||
| 'async_speed' | 100, 200, 400 | Speed for asynchronous communication of the IEEE 1394 interface. | |||
| 'brightness' |
min ... max, 'auto', 'manual', 'one_push', 'on', 'off' |
Sets the brightness value of the camera. If the used camera does not support brightness adjustment, H_ERR_FGPARAM is returned (or an empty tuple in the corresponding call to get_framegrabber_param, respectively). | |||
| 'camera_type' | 'format:mode:fps' | Specify the desired video settings as a string consisting of the video format (0,1,2), the video mode (0,1,2,3,4,5,6,7), and the frame rate (0,1,2,3,4,5 or 1.875,3.75,7.5,15.0,30.0,60.0, respectively), separated by colons. | |||
| 'ccr_offset' | offset | Offset to the base address of the camera register space 0xFFFF F0000000. Note that while setting this parameter the value can also be specified as a string parameter. | |||
| 'ccr_quadlet' | 0x000000000 ... 0x7FFFFFFFF | Quadlet which will be sent or received to/from the address given by the 'ccr_offset' parameter. Note that while setting this parameter the value can also be specified as a string parameter, thus, enabling values greater than 0x7FFFFFFF. | |||
| 'color_space' | 'gray', 'rgb', 'yuv', 'default' | Color space of the resulting HALCON image. 'default' means to adopt the supplied video settings of the camera. Default: 'default'. | |||
| 'continuous_grabbing' | 'enable', 'disable' |
Start/stop of the isochronous transmission of video data:
'enable' starts the camera to yield a continuous video stream
whereas 'disable' stops it. In contrast to single frame transmission,
the isochronous transmission channel is initialized only once
before the camera is set to run mode. This mode yields rate benefits
while transmitting frame sequences. Notice that
grab_image_start and
grab_image_async take advantage of the isochronous transmission mode and start the
camera by default, whereas
grab_image stops it
and transfers frames in single transmission mode. Default: 'disable'. |
|||
| 'exposure' |
min ... max, 'auto', 'manual', 'one_push', 'on', 'off' |
Sets the auto exposure value of the camera. If the used camera does not support exposure adjustment, H_ERR_FGPARAM is returned (or an empty tuple in the corresponding call to get_framegrabber_param, respectively). | |||
| 'external_trigger' | 'true', 'false' | Enables/disables the trigger mode. Be aware of the settings your camera supplies. | |||
| 'focus' |
min ... max, 'auto', 'manual', 'one_push', 'on', 'off' |
Sets the focus value of the camera. If the used camera does not support focus adjustment, H_ERR_FGPARAM is returned (or an empty tuple in the corresponding call to get_framegrabber_param, respectively). | |||
| 'frame_rate' |
0, 1, 2, 3, 4, 5 1.875, 3.75, 7.5, 15.0, 30.0, 60.0 |
Sets the desired frame rate either as integer as determined in the IEEE 1394-based digital camera specification or as float in frames per second. Be aware of the settings your camera supplies. Note that you have to call set_framegrabber_param(...,'do_set_video_settings',...) before the new settings take effect. | |||
| 'gamma' |
min ... max, 'auto', 'manual', 'one_push', 'on', 'off' |
Sets the gamma value of the camera. If the used camera does not support gamma adjustment, H_ERR_FGPARAM is returned (or an empty tuple in the corresponding call to get_framegrabber_param, respectively). | |||
| 'grab_timeout' | msec | Specify the desired timeout (milliseconds passed as a long) for aborting a pending grab. -1 means to abort never. Default: 5000. | |||
| 'hue' |
min ... max, 'auto', 'manual', 'one_push', 'on', 'off' |
Sets the hue value of the camera. If the used camera does not support hue adjustment, H_ERR_FGPARAM is returned (or an empty tuple in the corresponding call to get_framegrabber_param, respectively). | |||
| 'image_height' | -1, height | Sets the height of the image when operating in Format_7. -1 specifies the maximal image height. | |||
| 'image_width' | -1, width | Sets the width of the image when operating in Format_7. -1 specifies the maximal image width. | |||
| 'iris' |
min ... max, 'auto', 'manual', 'one_push', 'on', 'off' |
Sets the iris value of the camera. If the used camera does not support iris adjustment, H_ERR_FGPARAM is returned (or an empty tuple in the corresponding call to get_framegrabber_param, respectively). | |||
| 'num_buffers' | 1 ... 32767 | Number of buffers used for image acquisition. Default: 5. | |||
| 'num_multi_shot' | 1 ... 65535 | Number of images that will be acquired by multi shot acquisition. | |||
| 'saturation' |
min ... max, 'auto', 'manual', 'one_push', 'on', 'off' |
Sets the saturation value of the camera. If the used camera does not support saturation adjustment, H_ERR_FGPARAM is returned (or an empty tuple in the corresponding call to get_framegrabber_param, respectively). | |||
| 'sharpness' |
min ... max, 'auto', 'manual', 'one_push', 'on', 'off' |
Sets the sharpness value of the camera. If the used camera does not support sharpness adjustment, H_ERR_FGPARAM is returned (or an empty tuple in the corresponding call to get_framegrabber_param, respectively). | |||
| 'shutter' |
min ... max, 'auto', 'manual', 'one_push', 'on', 'off' |
Sets the shutter value of the camera. If the used camera does not support shutter adjustment, H_ERR_FGPARAM is returned (or an empty tuple in the corresponding call to get_framegrabber_param, respectively). | |||
| 'start_column' | column | Sets the column coordinate of the upper left corner of the image part when operating in Format_7. | |||
| 'start_row' | row | Sets the row coordinate of the upper left corner of the image part when operating in Format_7. | |||
| 'trigger_mode' |
0, 1, 2, 3 'shutter', 'pulse_width', 'n_pulses', 'shutter_n_frames' |
Sets the trigger mode either as integer as defined in the
IEEE 1394-based digital camera specification or as corresponding
string:
|
|||
| 'trigger_parameter' | number | Sets the trigger parameter needed by the trigger modes 2 and 3: In trigger mode 2 ('n_pulses') it specifies the number of trigger input events which define the integration time (n>1!). In trigger mode 3 ('shutter_n_frames') it defines the cycle time as multiple of the cycle time of the fastest frame rate (n>0!). See IEEE 1394-based digital camera specification for further information. | |||
| 'trigger_signal' | 'rising', 'falling' | Sets the trigger polarity and distinguishes whereas the rising or falling edge triggers the camera. Be aware of the settings your camera supplies. | |||
| 'ub' |
min ... max, 'auto', 'manual', 'one_push', 'on', 'off' |
Sets the ub value of the camera. If the used camera does not support ub adjustment, H_ERR_FGPARAM is returned (or an empty tuple in the corresponding call to get_framegrabber_param, respectively). | |||
| 'video_format' | 0 ... 2 | Sets the desired video format determined in the IEEE 1394-based digital camera specification. Be aware of the settings your camera supplies. Note that you have to call set_framegrabber_param(...,'do_set_video_settings',...) before the new settings take effect. | |||
| 'video_gain' |
min ... max, 'auto', 'manual', 'one_push', 'on', 'off' |
Sets the gain value of the camera. If the used camera does not support gain adjustment, H_ERR_FGPARAM is returned (or an empty tuple in the corresponding call to get_framegrabber_param, respectively). | |||
| 'video_mode' | 0 ... 7 | Sets the desired video mode determined in the IEEE 1394-based digital camera specification. Be aware of the settings your camera supplies. Note that you have to call set_framegrabber_param(...,'do_set_video_settings',...) before the new settings take effect. | |||
| 'vr' |
min ... max, 'auto', 'manual', 'one_push', 'on', 'off' |
Sets the vr value of the camera. If the used camera does not support vr adjustment, H_ERR_FGPARAM is returned (or an empty tuple in the corresponding call to get_framegrabber_param, respectively). | |||
| 'zoom' |
min ... max, 'auto', 'manual', 'one_push', 'on', 'off' |
Sets the zoom value of the camera. If the used camera does not support zoom adjustment, H_ERR_FGPARAM is returned (or an empty tuple in the corresponding call to get_framegrabber_param, respectively). | |||
| 'do_load_from_memory_channel' | 0 ... 15 | Loads camera settings from the specified memory channel (1 - 15) or reloads factory settings (0). Be aware of the settings your camera supplies. | |||
| 'do_multi_shot' | 'this_camera', 'all_cameras' | By specifying 'this_camera' the associated camera performs an acquisition using the multi shot capability. 'all_cameras' sends the multi shot command to all cameras on this bus. | |||
| 'do_one_shot' | 'this_camera', 'all_cameras' | By specifying 'this_camera' the associated camera performs an acquisition using the one shot capability. 'all_cameras' sends the one shot command to all cameras on this bus. | |||
| 'do_reset_camera' | --- | Resets the camera and puts its configurations to the manufacturer's default settings. | |||
| 'do_save_to_memory_channel' | 1 ... 15 | Stores the current camera settings to the specified memory channel. Be aware of the settings your camera supplies. | |||
| 'do_set_video_settings' | --- | Calculates payload and number of ISO packets, and reconfigures the FirePackage driver. Has to be called after changing 'video_format', 'video_mode' and 'frame_rate'. | |||
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'].
| 'camera_capabilities' | [format,mode,fps,width,height,colorformat, ...] | Returns a tuple of numbers that contains information about the available standard settings of this camera. A section of six numbers holds the VideoFormat, VideoMode, FrameRate, Width, Height, and Camera color format. | |||
| 'camera_model' | model_name (string) | Returns the name of the camera model. | |||
| 'camera_vendor' | vendor_name (string) | Returns the name of the camera vendor. | |||
| 'revision' | revision (string) | The revision number of the HALCON FirePackage interface. | |||
Release Notes
-
Revision 3.1 (Mar 10, 2009):
- Added read-only parameters with postfix '_description', '_range', and '_values' to enable the easy parameterization via a generic graphical user interface.
-
Revision 3.0 (Jun 28, 2007):
- HALCON 8.0 version of the interface (legacy only).
-
Revision 2.4 (Jul 10, 2005):
- HALCON 7.1 version of the interface (included in HALCON 7.1 CD).
- New parameters 'num_multi_shot' and 'do_multi_shot' for configuring and triggering of the multishot functionality. The existing parameter 'num_shots' has been renamed into 'num_buffers' to avoid confusion with the parameter 'num_multi_shot'. The documentation of 'num_buffers' has been clarified.
- Allow setting of offset and register values in string notation.
- New parameters 'image_height', 'image_width', 'start_column', and 'start_row' to change the image part in Format_7 dynamically.
- Speed-up for acquisition of RGB images (avoiding cache alignment failures when converting the interleaved image data into HALCON image objects).
- Bugfix in handling grab timeout parameter (when calling grab_image_start the value was reset to 5000).
-
Revision 2.3 (Apr 4, 2005):
- Support of video format 7 (partial scan).
- Support of pre-licensed AVT cameras (FirePackage 1.5.1 or higher).
- Acquisition from basic parameter of configuration ROM is corrected for all (camera) implementations
- Faulty packet count acquisition is fixed.
- Device/camera enumeration corrected.
- Check of DLL compatibility gives detailed low-level error message.
- info_framegrabber with 'info_boards' now returns information about the actually found camera (device, port, camera vendor and model, SN).
- An optional value within the CameraType parameter in open_framegrabber allows configuration of the camera acquisition setting (one_shot/multi_shot/continuous_shot) and in addition a 'listen_only' mode. This enables the frame grabber to listen asynchronously for images at a specified ISO channel.
- New parameters 'acquisition_mode', 'num_shots', and 'do_one_shot'.
- New parameters 'ccr_offset' and 'ccr_quadlet' to access the camera register space.
- The speed of the IEEE 1394 interface can be specified either in the Device parameter of open_framegrabber or with the parameter 'async_speed'.
- New parameters 'image_width_range', 'image_height_range', 'camera_type_values', and 'camera_capabilities'.
- Support of 16 bit image formats.
- The interface is now multi-host capable: More than one host computer on the same IEEE 1394 bus can access the cameras in a shared manner.
-
Revision 2.2 (Oct 7, 2002):
- HALCON 7.0 version of the interface (included in HALCON 7.0 CD).
- Parameter 'gain' renamed into 'video_gain' due to the naming conflict with the standard gain parameter of the HALCON image aquisition integration interface.
- New parameters with suffix '_range' added for get_framegrabber_param. These parameters are especially helpful when working with ActivVisionTools 2.1. The corresponding old '_min_value' and '_max_value' parameters are still usable for backward compatibility reasons.
- set_framegrabber_param returns now an error (H_ERR_FGPARAM) if the selected parameter is not supported by the used camera.
- get_framegrabber_param returns now an empty tuple as value if the requested parameter is not supported by the used camera.
- get_framegrabber_param('trigger_mode') returns now the current trigger mode as a string instead of an integer.
-
Revision 2.1 (Aug 19, 2002):
- Support of OHCI IEEE-1394 adapter cards.
- Support of up to 8 isochronous channels and 4 cameras per board.
-
Revision 2.0 (Feb 25, 2002):
- HALCON 6.1 version of the interface (included in HALCON 6.1 CD).
- First official release.
