Interface Documentation
Image Acquisition Interface for IEEE 1394 (FireWire) Cameras
| Interface: | 1394IIDC |
| Revision: | 20.11.2 |
| Date: | 2023-08-01 |
1394IIDC: Legacy Interface
- General
- System Requirements
- Installation
- Features
- Limitations
- Using Scalable Image Format (Format_7)
- Using the generic parameter in open_framegrabber
- Data Transfer
- Selecting the desired video mode and frame rate
- Parameters for info_framegrabber
- Parameters for open_framegrabber
- Parameters for set_framegrabber_param
- Parameters for get_framegrabber_param
- Operator set_framegrabber_lut
- Operator get_framegrabber_lut
- Operator set_framegrabber_callback
- Operator get_framegrabber_callback
- Operator grab_image_start
- Operator grab_image
- Operator grab_image_async
- Operator grab_data
- Operator grab_data_async
- Operator close_framegrabber
- HDevelop Examples
- C++ Examples
- C# Examples
- Release Notes
General
This page provides the documentation of the HALCON 1394IIDC interface. With this interface you can acquire images from IEEE 1394 (FireWire)
cameras via any OHCI compliant IEEE 1394 adapter card.
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 with OHCI compliant IEEE 1394 adapter.
- Successfully installed FirePackage or FirePackage64 driver (version 2.33 or higher). Registered customers can download this 3rd party driver from the MVTec WWW server. Note that this driver replaces the standard IEEE 1394 driver of your system! For (de-)installation of the FirePackage driver please use the program svcInst.exe that is part of the FirePackage installation.
- FirePackage access DLL FGCamera.dll (version 2.7.0.4 or higher).
This DLL is part of the FirePackage installation and must be in your search path %PATH% (usually this file is located in C:\Windows\System32). - HALCON image acquisition interface hAcq1394IIDC.dll or
hAcq1394IIDCxl.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. - Important note: If you are using some of the viewing tools of the FirePackage installation like (e.g., GrabDemo.exe) please have in mind that you are only able to acquire up to 5000 images! As soon as you exceed this number of images an error message will occur unless you reload the driver, e.g., by restarting your system. However, all images that are grabbed by the HALCON 1394IIDC interface do not add to this image counter.
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
- Supports all IEEE 1394a and 1394b cameras that are compliant to the IIDC 1394-based Digital Camera Specification.
- Synchronous and asynchronous grabbing.
- Multiple cameras.
- External camera triggering.
- Support of scalable image formats (Format_7).
- Software control of all IIDC 1394 parameters.
- Software and hardware cropping of images.
- Support of user-specific callback functions.
Limitations
- The number of connectable cameras per IEEE 1394 adapter card is limited by the number of isochronous DMAs on the OHCI adapter. Typically, this number is four. For connecting to more cameras you have to use several IEEE 1394 adapter cards.
- Hot plugging (bus reset) is not supported.
- Format_6 not supported.
Using Scalable Image Format (Format_7)
Only if you are using the scalable image format (Format_7), you can crop images by changing the used camera sensor size with the
following parameters:
Note that because of the smaller used sensor size the frame rate will raise.
In contrast to the hardware image cropping parameters, the parameters for software image cropping 'image_height', 'image_width', 'start_column' and 'start_row' can be used together with any video format. Naturally, the frame rate will not change when using software image cropping.
- horizontal_offset
- horizontal_resolution (also in open_framegrabber)
- vertical_offset
- vertical_resolution (also in open_framegrabber)
Note that because of the smaller used sensor size the frame rate will raise.
In contrast to the hardware image cropping parameters, the parameters for software image cropping 'image_height', 'image_width', 'start_column' and 'start_row' can be used together with any video format. Naturally, the frame rate will not change when using software image cropping.
Using the generic parameter in open_framegrabber
- Isochronous Resource Manager (IRM)
The Isochronous Resource Manager (IRM) is a service of the IEEE 1394 bus, which manages among other things the bandwidth for each camera. Normally, the HALCON 1394IIDC interface uses the IRM, i.e., if a camera requests more bandwidth than available on the bus the operator open_framegrabber or set_framegrabber_param fails.
Since some applications like triggered image acquisition actually need less bandwidth than the IRM calculates, the IRM can be disabled by writing 'irm=0' as a string into the parameter Generic in open_framegrabber (recommended) or via set_framegrabber_param. Please note if you are using multiple cameras on the same IEEE 1394 bus, the setting of the IRM affects all cameras on this bus. Also note that each call of open_framegrabber without explicit disabling of the IRM activates it for the IEEE 1394 bus! - Number of Buffers
The desired number of buffers for the image acquisition can be set with the string 'num_buffers=<x>', where x must be a number greater or equal 1. We recommend to use at least two buffers, which is also the default setting. - Isochronous Transfer Speed
The Isochronous Transfer Speed denotes the real physical speed that is used to talk with the connected image device. In case that you don't want to use the maximum bandwidth of the IEEE 1394 bus, you can set the real physical speed via the parameter Generic in open_framegrabber. The desired speed is a string with the values 'phy_speed=100', 'phy_speed=200', 'phy_speed=400', and 'phy_speed=800'. Note: 'phy_speed=800' is only available for IEEE 1394b buses. - Bus/Card Reset
Before opening the image acquisition device, all available cards can be reset via the parameter 'do_bus_reset=<ms>', where ms is the time in milliseconds to wait for the cards to re-initialize. For most cards this value should be at least 300.
Data Transfer
IIDC 1394 uses isochronous data transfer for image acquisition from the connected camera to the PC. Each camera uses its own channel to send the data
packets to the corresponding DMA channel of the IEEE 1394 card.
The data transfer is already started after calling open_framegrabber, but some parameters can only be set, if no data is transfered. So, the 1394IIDC interface stops the data transfer, sets the parameter, and restarts the transfer automatically for the following parameters:
Please note that stopping and restarting the data transfer can have side-effects on other parameters, especially if Format 7 is used.
The data transfer is already started after calling open_framegrabber, but some parameters can only be set, if no data is transfered. So, the 1394IIDC interface stops the data transfer, sets the parameter, and restarts the transfer automatically for the following parameters:
- 'burst_count'
- 'camera_type'
- 'irm'
- 'horizontal_offset'
- 'horizontal_resolution'
- 'packet_size'
- 'vertical_offset'
- 'vertical_resolution'
Please note that stopping and restarting the data transfer can have side-effects on other parameters, especially if Format 7 is used.
Selecting the desired video mode and frame rate
Specify the desired video settings in IIDC 1394 notation as a string consisting of the video format (0, 1, 2, 7), the video mode
(0, 1, 2, 3, 4, 5, 6, 7), and the frame rate (0, 1, 2, 3, 4, 5), separated
by colons. Video format 7 is the partial image mode; here, the frame
rate depends on the chosen image size and the packet_size
parameter. For the supported modes and frame rates please see
the manual of your specific camera.
frame rate:
frame rate:
- 0 = 1.875 fps
- 1 = 3.75 fps
- 2 = 7.5 fps
- 3 = 15 fps
- 4 = 30 fps
- 5 = 60 fps
- 6 = 120 fps
- 7 = 240 fps
format 0
- mode 0 - 160 X 120 YUV(4:4:4) Mode (24bit/pixel) - frame rates 2, 3, 4, 5, 6, 7
- mode 1 - 320 X 240 YUV(4:2:2) Mode (16bit/pixel) - frame rates 0, 1, 2, 3, 4, 5, 6, 7
- mode 2 - 640 X 480 YUV(4:1:1) Mode (12bit/pixel) - frame rates 0, 1, 2, 3, 4, 5, 6, 7
- mode 3 - 640 X 480 YUV(4:2:2) Mode (16bit/pixel) - frame rates 0, 1, 2, 3, 4, 5, 6, 7
- mode 4 - 640 X 480 RGB Mode (24bit/pixel) - frame rates 0, 1, 2, 3, 4, 5, 6, 7
- mode 5 - 640 X 480 Y (Mono) Mode (8bit/pixel) - frame rates 0, 1, 2, 3, 4, 5, 6, 7
- mode 6 - 640 X 480 Y (Mono16) Mode (16bit/pixel) - frame rates 0, 1, 2, 3, 4, 5, 6, 7
format 1
- mode 0 - 800 X 600 YUV(4:2:2) Mode (16bit/pixel) - frame rates 1, 2, 3, 4, 5, 6, 7
- mode 1 - 800 X 600 RGB Mode (24bit/pixel) - frame rates 2, 3, 4, 5, 6
- mode 2 - 800 X 600 Y (Mono) Mode (8bit/pixel) - frame rates 2, 3, 4, 5, 6, 7
- mode 3 - 1024 X 768 YUV(4:2:2) Mode (16bit/pixel) - frame rates 0, 1, 2, 3, 4, 5, 6
- mode 4 - 1024 X 768 RGB Mode (24bit/pixel) - frame rates 0, 1, 2, 3, 4, 5
- mode 5 - 1024 X 768 Y (Mono) Mode (8bit/pixel) - frame rates 0, 1, 2, 3, 4, 5, 6, 7
- mode 6 - 800 X 600 Y (Mono16) Mode (16bit/pixel) - frame rates 1, 2, 3, 4, 5, 6, 7
- mode 7 - 1024 X 768 Y (Mono16) Mode (16bit/pixel) - frame rates 0, 1, 2, 3, 4, 5, 6
format 2
- mode 0 - 1280 X 960 YUV(4:2:2) Mode (16bit/pixel) - frame rates 0, 1, 2, 3, 4, 5
- mode 1 - 1280 X 960 RGB Mode (24bit/pixel) - frame rates 0, 1, 2, 3, 4, 5
- mode 2 - 1280 X 960 Y (Mono) Mode (8bit/pixel) - frame rates 0, 1, 2, 3, 4, 5, 6
- mode 3 - 1600 X 1200 YUV(4:2:2) Mode (16bit/pixel) - frame rates 0, 1, 2, 3, 4, 5
- mode 4 - 1600 X 1200 RGB Mode (24bit/pixel) - frame rates 0, 1, 2, 3, 4
- mode 5 - 1600 X 1200 Y (Mono) Mode (8bit/pixel) - frame rates 0, 1, 2, 3, 4, 5, 6
- mode 6 - 1280 X 960 Y (Mono16) Mode (16bit/pixel) - frame rates 0, 1, 2, 3, 4, 5
- mode 7 - 1600 X 1200 Y (Mono16) Mode (16bit/pixel) - frame rates 0, 1, 2, 3, 4, 5
format 7
- 7:0:0 - Y8
- 7:0:1 - YUV411
- 7:0:2 - YUV422
- 7:0:3 - YUV444
- 7:0:4 - RGB8
- 7:0:5 - Y16
- 7:0:6 - RGB16
- 7:0:7 - Signed Y16
- 7:0:8 - Signed RGB16
- 7:0:9 - RAW8
- 7:0:10 - RAW16
Alternatively, you can specify the video settings in FireGrab notation by
resolution (0-7), color mode (0-6), and frame rate (0-7), separated by
dots:
resolution:
- 0 (= 160 x 120)
- 1 (= 320 x 240)
- 2 (= 640 x 480)
- 3 (= 800 x 600)
- 4 (= 1024 x 768)
- 5 (= 1280 x 960)
- 6 (= 1600 x 1200)
- 7 (= scalable)
color mode:
- 0 (= Y8)
- 1 (= YUV411)
- 2 (= YUV422)
- 3 (= YUV444)
- 4 (= RGB8)
- 5 (= Y16)
- 6 (= RGB16)
- 7 (= Signed Y16)
- 8 (= Signed RGB16)
- 9 (= RAW8)
- 10 (= RAW16)
frame rate:
- 0 (= 1.875)
- 1 (= 3.75)
- 2 (= 7.5)
- 3 (= 15)
- 4 (= 30)
- 5 (= 60)
- 6 (= 120)
- 7 (= 240)
Parameters for info_framegrabber
| Parameter | Value List | Type | Kind | Description |
|---|---|---|---|---|
| 'bits_per_channel' | [-1, 8, 9, 10, 11, 12, 13, 14, 15, 16] | integer | pre-defined | Values for bits per channel. |
| 'camera_type' | ['<format:mode:fps>', '<resolution.color.fps>', 'default'] | string | pre-defined | Specify the desired video settings in IIDC 1394 notation or in FireGrab notation. For the supported modes and frame rates please see
the manual of your specific camera. A detailed list with all settings is
described here. 'default' means that proper video settings are chosen automatically: If the camera supports Format_7 the maximum image size is set, otherwise the maximum supported image format in combination with the minimum frame rate is selected. |
| 'color_space' | ['default', 'gray', 'raw', 'rgb', 'yuv'] | string | pre-defined | Values for color space. |
| 'defaults' | [1, 1, 0, 0, 0, 0, 'progressive', -1, 'default', -1.0, 'false', 'default', '-1', 0, 0] | mixed | pre-defined | Default values for open_framegrabber. |
| 'device' | [<device_id>] | string | dynamic | Returns a list of the available device IDs. |
| 'external_trigger' | ['false', 'true'] | string | pre-defined | Values for the external trigger. |
| 'field' | ['interlaced', 'progressive'] | string | pre-defined | Values for field. |
| 'general' | [] | string | pre-defined | Information about the HALCON 1394IIDC interface. |
| 'generic' | ['', 'do_bus_reset=<time>', 'irm=0', 'num_buffers=<num>', 'phy_speed=<speed>'] | string | pre-defined | Value list for the Generic parameter. |
| 'horizontal_resolution' | [1, 2] | integer | pre-defined | Value list for horizontal resolution. |
| 'image_height' | [] | Unsupported query. | ||
| 'image_width' | [] | Unsupported query. | ||
| 'info_boards' | ['device:<guid> card.id:<id>'] | string | dynamic | Returns a list of the available devices including the appendant card IDs. |
| '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' | [] | If no device has been opened already, a card reset for all cards with installed FirePackage driver is performed. | ||
| 'revision' | '<revision>' | string | pre-defined | Revision number of the 1394IIDC interface. |
| 'start_column' | [] | Unsupported query. | ||
| 'start_row' | [] | Unsupported query. | ||
| 'vertical_resolution' | [1, 2] | integer | pre-defined | Value list for vertical resolution. |
Parameters for open_framegrabber
| Parameter | Values | Default | Type | Description |
|---|---|---|---|---|
| Name | '1394IIDC' | string | Name of the HALCON interface. | |
| HorizontalResolution | 1, 2, <width> | 1 | integer | Horizontal resolution of the image sensor if CameraType is set to Format_7.
|
| VerticalResolution | 1, 2, <height> | 1 | integer | Vertical resolution of the image sensor if CameraType is set to Format_7.
|
| ImageWidth | 0, <width> | 0 | integer | Width of the desired image part. The passed value gets rounded to fit the step with restriction of this parameter (which depends on the camera). The value 0 stands for the complete image. |
| ImageHeight | 0, <height> | 0 | integer | Height of the desired image part. The passed value gets rounded to fit the step with restriction of this parameter (which depends on the camera). The value 0 stands for the complete image. |
| StartRow | 0, <row> | 0 | integer | Row coordinate of the upper left pixel of the desired image part. The passed value gets rounded to fit the step with restriction of this parameter (which depends on the camera). |
| StartColumn | 0, <column> | 0 | integer | Column coordinate of the upper left pixel of the desired image part. The passed value gets rounded to fit the step with restriction of this parameter (which depends on the camera). |
| Field | 'interlaced', 'progressive' | 'progressive' | string | Ignored. |
| BitsPerChannel | -1, 8, 9, 10, 11, 12, 13, 14, 15, 16 | -1 | integer | Number of significant bits per channel. -1 means to adopt the value 8 or 16 according to the specified CameraType. In case of Y16 or RGB16 image formats the pixel data will be shifted according to this parameter to ensure that the image data is right aligned. |
| ColorSpace | 'default', 'gray', 'raw', 'rgb', 'yuv' | 'default' | string | Desired color space of the resulting HALCON image. 'default' means to adopt the camera setting. |
| Generic | '', ['do_bus_reset=<time>', 'irm=0', 'num_buffers=<num>', 'phy_speed=<speed>'], -1 | -1 | mixed | Generic parameter, see description above. |
| ExternalTrigger | 'false', 'true' | 'false' | string | Status of the external trigger. |
| CameraType | '<format:mode:fps>', '<resolution.color.fps>', 'default' | 'default' | string | Specify the desired video settings in IIDC 1394 notation or in FireGrab notation. For the supported modes and frame rates please see
the manual of your specific camera. A detailed list with all settings is
described here. 'default' means that proper video settings are chosen automatically: If the camera supports Format_7 the maximum image size is set, otherwise the maximum supported image format in combination with the minimum frame rate is selected. |
| Device | '-1', 'card.id', 'guid' | '-1' | string | Select the desired camera device: You can either do this by specifying the indices of the used adapter card and id, or by the camera GUID. To query the actual installed cameras you can call info_framegrabber(..., 'info_boards', ...). '-1' selects the first available device. |
| Port | --- | Ignored. | ||
| LineIn | --- | Ignored. |
Parameters for set_framegrabber_param
| Parameter | Values | Default | Type | Description |
|---|---|---|---|---|
| 'bayer_pattern' | 'rg_gb', 'gb_rg', 'gr_bg', 'bg_gr' | 'rg_gb' | string | Alignment of the Bayer pattern. The values are set according to the first 2x2 pixel on the upper left of the image sensor. |
| 'bits_per_channel' | 8, 9, 10, 11, 12, 13, 14, 15, 16 | -1 | integer | Number of significant bits per channel. -1 means to adopt the value 8 or 16 according to the specified CameraType. In case of Y16 or RGB16 image formats the pixel data will be shifted according to this parameter to ensure that the image data is right aligned. |
| 'brightness' | <brightness>, 'auto', 'one_push', 'off' | mixed | Brightness mode of the camera if a string value is passed. Otherwise the brightness mode is switched to 'manual' and the brightness value is set. | |
| 'burst_count' | <burst_count> | 0 | integer | Burst count mode of the camera:
|
| 'busy_timeout' | <milliseconds> | 100 | integer | Time to wait in milliseconds after stopping data transfer. New commands are set to the camera if the time is expired. See also parameter 'register_value_stopped' and section Data Transfer. |
| 'camera_type' | '<format:mode:fps>', '<resolution.color.fps>' | 'default' | string | Specify the desired video settings in IIDC 1394 notation or in FireGrab notation. For the supported modes and frame rates please see
the manual of your specific camera. A detailed list with all settings is
described here. 'default' means that proper video settings are chosen automatically: If the camera supports Format_7 the maximum image size is set, otherwise the maximum supported image format in combination with the minimum frame rate is selected. |
| 'capture_quality' | <capture_quality>, 'auto', 'one_push', 'off' | mixed | Capture quality mode of the camera if a string value is passed. In case of an integer value the capture quality mode is switched to 'manual' (if supported) and the capture quality value is set. | |
| 'capture_size' | <capture_size>, 'auto', 'one_push', 'off' | mixed | Capture size mode of the camera if a string value is passed. Otherwise the capture size mode is switched to 'manual' (if supported) and the capture size value is set. | |
| 'color_space' | 'gray', 'raw', 'rgb', 'yuv' | string | Desired color space of the resulting HALCON image. | |
| 'do_abort_grab' | --- | Cancel current grab. | ||
| 'do_bustrigger' | --- | Activates the trigger of all cameras on the bus without acknowledgement and waiting for an answer. | ||
| 'do_fasttrigger' | --- | Activates the trigger of the camera without acknowledgement and waiting for an answer. | ||
| 'do_reset_camera' | --- | Resets the camera and puts its configuration to the manufacturer's default settings. | ||
| 'do_trigger' | --- | Activates the trigger of the camera. | ||
| 'exposure' | <exposure>, 'auto', 'one_push', 'off' | mixed | Exposure mode of the camera if a string value is passed. Otherwise the exposure mode is switched to 'manual' (if supported) and the exposure value is set. | |
| 'external_trigger' | 'false', 'true' | string | Enables/disables the trigger mode. | |
| 'focus' | <focus>, 'auto', 'one_push', 'off' | mixed | Focus mode of the camera if a string value is passed. Otherwise the focus mode is switched to 'manual' (if supported) and the focus value is set. | |
| 'gamma' | <gamma>, 'auto', 'one_push', 'off' | mixed | Gamma mode of the camera if a string value is passed. Otherwise the gamma mode is switched to 'manual' (if supported) and the gamma value is set. | |
| 'grab_timeout' | <milliseconds> | 5000 | integer | Desired timeout (milliseconds) for aborting a pending grab. If -1 is specified, the timeout is set to INFINITE. |
| 'horizontal_offset' | <offset> | integer | Horizontal offset of the image sensor. | |
| 'horizontal_resolution' | <resolution> | integer | Horizontal resolution of the image sensor. Note that this parameter can only be set, if CameraType is set to Format_7. | |
| 'hue' | <hue>, 'auto', 'one_push', 'off' | mixed | Hue mode of the camera if a string value is passed. Otherwise the hue mode is switched to 'manual' (if supported) and the hue value is set. | |
| 'image_height' | -1, <height> | integer | Height of the resulting HALCON image. -1 specifies the maximum image height. | |
| 'image_width' | -1, <width> | integer | Width of the resulting HALCON image. -1 specifies the maximum image width. | |
| 'iris' | <iris>, 'auto', 'one_push', 'off' | mixed | Iris mode of the camera if a string value is passed. Otherwise the iris mode is switched to 'manual' (if supported) and the iris value is set. | |
| 'irm' | 0, 1 | 1 | integer | State of the isochronous resource manager (IRM), see description above. To enable the IRM the value has to be set to 1. Please note that the IRM is a global setting of the bus, so will change the settings for all cameras on the IEEE 1394 bus! |
| 'optical_filter' | <optical_filter>, 'auto', 'one_push', 'off' | mixed | Optical_filter mode of the camera if a string value is passed. Otherwise the optical_filter mode is switched to 'manual' (if supported) and the optical_filter value is set. | |
| 'packet_size' | <packet_size> | integer | Specifies the size of the transferred packets (only supported in Format_7). The value specifies the bandwidth of the isochronuous channel and therefore influences the frame rate of the camera. Note that specifying a very small packet size may result in timeout errors while grabbing images. | |
| 'pan' | <pan>, 'auto', 'one_push', 'off' | integer | Pan mode of the camera if a string value is passed. Otherwise the pan mode is switched to 'manual' (if supported) and the pan value is set. | |
| 'register_address' | <0x00000000 ... 0xFFFFFFFF> | integer | Specify the address of the register that should be set directly, e.g., 0xF0F0060C. | |
| 'register_value' | <0x00000000 ... 0xFFFFFFFF> | integer | Specify the register value (as long) that is set directly in the register specified by the 'register_address' parameter, e.g., 0x01000000. The parameter 'register_address' must always set before using the parameter 'register_value'. | |
| 'register_value_stopped' | <0x00000000 ... 0xFFFFFFFF> | integer | Same usage as parameter 'register_value', but the camera is stopped before and restarted after writing the value to the register. The time to wait before writing the register value canbe set via parameter 'busy_timeout'. See also section Data Transfer. | |
| 'saturation' | <saturation>, 'auto', 'one_push', 'off' | mixed | Saturation mode of the camera if a string value is passed. Otherwise the saturation mode is switched to 'manual' (if supported) and the saturation value is set. | |
| 'sharpness' | <sharpness>, 'auto', 'one_push', 'off' | integer | Sharpness mode of the camera if a string value is passed. Otherwise the sharpness mode is switched to 'manual' (if supported) and the sharpness value is set. | |
| 'shutter' | <shutter>, 'auto', 'one_push', 'off' | mixed | Shutter mode of the camera if a string value is passed. Otherwise the shutter mode is switched to 'manual' (if supported) and the shutter value is set. | |
| '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. |
| 'start_column' | <column> | integer | Column coordinate of the upper left pixel within the desired image part. | |
| 'start_row' | <row> | integer | Row coordinate of the upper left pixel within the desired image part. | |
| 'swap_bytes' | 'false', 'true' | 'false' | string | Specifies whether the byte order within a pixel should be swapped in Y16 and RGB16 modes. |
| 'temperature' | <temperature>, 'auto', 'one_push', 'off' | mixed | Temperature mode of the camera if a string value is passed. Otherwise the temperature mode is switched to 'manual' (if supported) and the target temperature value is set. | |
| 'tilt' | <tilt>, 'auto', 'one_push', 'off' | mixed | Tilt mode of the camera if a string value is passed. Otherwise the tilt mode is switched to 'manual' (if supported) and the tilt value is set. | |
| 'trigger_delay' | <seconds> | mixed | Trigger delay value of the camera (in seconds). | |
| 'trigger_mode' | <number> | integer | Trigger mode either as integer as defined in the IIDC 1394-based digital camera specification.
|
|
| 'trigger_parameter' | <number> | integer | 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_polarity' | 0, 1 | integer | Trigger polarity and distinguishes whereas the rising or falling edge triggers the camera.
|
|
| 'trigger_source' | <source> | integer | Trigger source as defined in the IEEE 1394-based digital camera specification. Be aware of the settings your camera supplies. | |
| 'ub' | <ub>, 'auto', 'one_push', 'off' | mixed | White balance mode of the camera if a string value is passed. Otherwise the white balance mode is switched to 'manual' (if supported) and the ub value is set. | |
| 'vertical_offset' | <offset> | integer | Vertical offset of the image sensor. | |
| 'vertical_resolution' | <resolution> | integer | Vertical resolution of the image sensor. Note that this parameter can only be set, if CameraType is set to Format_7. | |
| 'video_gain' | <video_gain>, 'auto', 'one_push', 'off' | mixed | Video gain mode of the camera if a string value is passed. Otherwise the video gain mode is switched to 'manual' (if supported) and the video gain value is set. | |
| 'vr' | <vr>, 'auto', 'one_push', 'off' | mixed | White_balance mode of the camera if a string value is passed. Otherwise the white_balance mode is switched to 'manual' (if supported) and the vr value is set. | |
| 'white_shading' | <white_shading>, 'auto', 'one_push', 'off' | mixed | White_shading mode of the camera if a string value is passed. Otherwise the white shading mode is switched to 'manual' (if supported) and the white shading value is set. | |
| 'zoom' | <zoom>, 'auto', 'one_push', 'off' | mixed | Zoom mode of the camera if a string value is passed. Otherwise the zoom mode is switched to 'manual' (if supported) and the zoom value is set. |
Parameters for get_framegrabber_param
There may exist additional read-only parameters with the following postfixes:
- '_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'].
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. | |
| 'bayer_pattern' | 'rg_gb', 'gb_rg', 'gr_bg', 'bg_gr' | 'rg_gb' | string | pre-defined | Alignment of the Bayer pattern. The values are set according to the first 2x2 pixel on the upper left of the image sensor. |
| 'bits_per_channel' | -1, 8, 9, 10, 11, 12, 13, 14, 15, 16 | -1 | integer | pre-defined | Number of bits per channel of the resulting HALCON image. In case of -1 the current bit depth of the camera is used. By specifying a value greater than 8 the grabbed images are delivered as uint2 images. |
| 'brightness' | <brightness>, 'auto', 'one_push', 'off' | mixed | dynamic | If mode is not set to 'manual', the brightness mode of the camera is returned as a string. Otherwise you get the current brightness value. | |
| 'burst_count' | <burst_count> | 0 | integer | dynamic | Burst count mode of the camera. |
| 'busy_timeout' | <milliseconds> | 100 | integer | pre-defined | Time to wait in milliseconds after stopping data transfer. New commands are set to the camera if the time is expired. See also parameter 'register_value_stopped' and section Data Transfer. |
| 'camera_model' | <model_name> | string | dynamic | Name of the camera model. | |
| 'camera_type' | '<format:mode:fps>', '<resolution.color.fps>' | 'default' | string | pre-defined | Current camera type. |
| 'camera_vendor' | <vendor_name> | string | dynamic | Name of the camera vendor. | |
| 'capture_quality' | <capture_quality>, 'auto', 'one_push', 'off' | mixed | dynamic | If mode is not set to 'manual', the capture quality mode of the camera is returned as a string. Otherwise you get the current capture quality value. | |
| 'capture_size' | <capture_size>, 'auto', 'one_push', 'off' | mixed | dynamic | If mode is not set to 'manual', the capture size mode of the camera is returned as a string. Otherwise you get the current capture size value. | |
| 'card_list' | <card_ids> | string | dynamic | A list of all IEEE 1394 compliant cards of the PC with installed FirePackage driver. | |
| 'color_space' | 'gray', 'raw', 'rgb', 'yuv' | 'default' | string | pre-defined | Desired color space and thus the number of image channels of the resulting HALCON image. |
| 'device' | '<guid>' | '-1' | string | dynamic | Current device ID. |
| 'exposure' | <exposure>, 'auto', 'one_push', 'off' | mixed | dynamic | If mode is not set to 'manual', the exposure mode of the camera is returned as a string. Otherwise you get the current exposure value. | |
| 'external_trigger' | 'false', 'true' | 'false' | string | pre-defined | Status of the external trigger. |
| 'field' | '<default>' | 'progressive' | string | pre-defined | The value is not used, so a default value is returned. |
| 'focus' | <focus>, 'auto', 'one_push', 'off' | mixed | dynamic | If mode is not set to 'manual', the focus mode of the camera is returned as a string. Otherwise you get the current focus value. | |
| 'frame_rate' | <fps> | float | dynamic | Video frame rate of the camera. In case of Format_7 as used video format the frame rate is estimated from the image size in bytes and the size of the transferred bytes per packet. | |
| 'gamma' | <gamma>, 'auto', 'one_push', 'off' | mixed | dynamic | If mode is not set to 'manual', the gamma mode of the camera is returned as a string. Otherwise you get the current gamma value. | |
| 'generic' | '', ['do_bus_reset=<time>', 'irm=0', 'num_buffers=<num>', 'phy_speed=<speed>'], -1 | -1 | mixed | pre-defined | Values of the Generic parameter. |
| 'grab_timeout' | <milliseconds> | 5000 | integer | pre-defined | Current grab timeout in milliseconds. |
| 'horizontal_offset' | <offset> | integer | dynamic | Horizontal offset of the image sensor. | |
| 'horizontal_resolution' | 1, 2, 4 | 1 | integer | pre-defined | Current value of horizontal resolution. |
| 'hue' | <hue>, 'auto', 'one_push', 'off' | mixed | dynamic | If mode is not set to 'manual', the hue mode of the camera is returned as a string. Otherwise you get the current hue value. | |
| '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 | pre-defined | Height of the desired image part ('0' stands for the complete image). |
| 'image_width' | <width> | 0 | integer | pre-defined | Width of the desired image part ('0' stands for the complete image). |
| 'iris' | <iris>, 'auto', 'one_push', 'off' | mixed | dynamic | If mode is not set to 'manual', the iris mode of the camera is returned as a string. Otherwise you get the current iris value. | |
| 'irm' | 0, 1 | 1 | integer | pre-defined | State of the isochronous resource manager (IRM), see description above. To enable the IRM the value has to be set to 1. Please note that the IRM is a global setting of the bus, so will change the settings for all cameras on the IEEE 1394 bus! |
| 'line_in' | <default> | 0 | integer | pre-defined | The value is not used, so a default value is returned. |
| 'name' | '1394IIDC' | string | pre-defined | Name of the HALCON interface. | |
| 'num_buffers' | <number> | 2 | integer | pre-defined | Number of buffers used for the image acquisition. |
| 'optical_filter' | <optical_filter>, 'auto', 'one_push', 'off' | mixed | dynamic | If mode is not set to 'manual', the optical filter mode of the camera is returned as a string. Otherwise you get the current optical filter value. | |
| 'packet_size' | <packet_size> | integer | dynamic | Specifies the size of the transferred packets (only supported in Format_7). The value specifies the bandwidth of the isochronuous channel and therefore influences the frame rate of the camera. Note that specifying a very small packet size may result in timeout errors while grabbing images. | |
| 'pan' | <pan>, 'auto', 'one_push', 'off' | integer | dynamic | If mode is not set to 'manual', the pan mode of the camera is returned as a string. Otherwise you get the current pan value. | |
| 'phy_speed' | <speed> | string | pre-defined | Real physical speed that is used to talk with the connected image device, see also parameter Generic in open_framegrabber. | |
| 'port' | <default> | 0 | integer | pre-defined | The value is not used, so a default value is returned. |
| 'register_address' | <0x00000000 ... 0xFFFFFFFF> | integer | dynamic | Specify the address of the register that should be set directly, e.g., 0xF0F0060C. | |
| 'register_value' | <0x00000000 ... 0xFFFFFFFF> | integer | dynamic | Specify the register value (as long) that is set directly in the register specified by the 'register_address' parameter, e.g., 0x01000000. The parameter 'register_address' must always set before using the parameter 'register_value'. | |
| 'revision' | '<revision>' | string | pre-defined | Revision number of the 1394IIDC interface. | |
| 'saturation' | <saturation>, 'auto', 'one_push', 'off' | mixed | dynamic | If mode is not set to 'manual', the saturation mode of the camera is returned as a string. Otherwise you get the current saturation value. | |
| 'sharpness' | <sharpness>, 'auto', 'one_push', 'off' | integer | dynamic | If mode is not set to 'manual', the sharpness mode of the camera is returned as a string. Otherwise you get the current sharpness value. | |
| 'shutter' | <shutter>, 'auto', 'one_push', 'off' | mixed | dynamic | If mode is not set to 'manual', the shutter mode of the camera is returned as a string. Otherwise you get the current shutter value. | |
| '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. |
| 'swap_bytes' | 'false', 'true' | 'false' | string | pre-defined | Specifies whether the byte order within a pixel should be swapped in Y16 and RGB16 modes. |
| 'temperature' | <temperature>, 'auto', 'one_push', 'off' | mixed | dynamic | If mode is not set to 'manual', the temperature mode of the camera is returned as a string. Otherwise you get the current temperature value. | |
| 'tilt' | <tilt>, 'auto', 'one_push', 'off' | mixed | dynamic | If mode is not set to 'manual', the tilt mode of the camera is returned as a string. Otherwise you get the current tilt value. | |
| 'trigger_delay' | <seconds> | mixed | dynamic | Trigger delay value of the camera (in seconds). | |
| 'trigger_mode' | <number> | integer | dynamic | Current trigger mode. | |
| 'trigger_parameter' | <number> | integer | dynamic | 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_polarity' | 0, 1 | integer | dynamic | Trigger polarity and distinguishes whereas the rising or falling edge triggers the camera.
|
|
| 'trigger_source' | <source> | integer | dynamic | Trigger source as defined in the IEEE 1394-based digital camera specification. Be aware of the settings your camera supplies. | |
| 'ub' | <ub>, 'auto', 'one_push', 'off' | mixed | dynamic | If mode is not set to 'manual', the white balance mode of the camera is returned as a string. Otherwise you get the current ub value. | |
| 'vertical_offset' | <offset> | integer | dynamic | Vertical offset of the image sensor. | |
| 'vertical_resolution' | 1, 2, 4 | 1 | integer | pre-defined | Current value of vertical resolution. |
| 'video_gain' | <video_gain>, 'auto', 'one_push', 'off' | mixed | dynamic | If mode is not set to 'manual', the video gain mode of the camera is returned as a string. Otherwise you get the current video gain value. | |
| 'vr' | <vr>, 'auto', 'one_push', 'off' | mixed | dynamic | If mode is not set to 'manual', the white balance mode of the camera is returned as a string. Otherwise you get the current vr value. | |
| 'white_shading' | <white_shading>, 'auto', 'one_push', 'off' | mixed | dynamic | If mode is not set to 'manual', the white shading mode of the camera is returned as a string. Otherwise you get the current white shading value. | |
| 'zoom' | <zoom>, 'auto', 'one_push', 'off' | mixed | dynamic | If mode is not set to 'manual', the zoom mode of the camera is returned as a string. Otherwise you get the current zoom value. |
Operator set_framegrabber_lut
Not supported by this interface.
Operator get_framegrabber_lut
Not supported by this interface.
Operator set_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,
on every occurrence of the underlying event (e.g., the notification
that the exposure has finished) the specified callback function will be
called. If the callback function is set to NULL, the corresponding
callback will be unregistered.
The signature of the callback function is Herror (__stdcall *HAcqCallback)(void *AcqHandle, void *Context, void *UserContext) and uses the following parameters:
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.
The signature of the callback function is Herror (__stdcall *HAcqCallback)(void *AcqHandle, void *Context, void *UserContext) and uses the following parameters:
- AcqHandle Acquisition handle of the corresponding image acquisition instance.
- Context Optional context data of the specific callback. In the 1394IIDC 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.
| Type | Description |
|---|---|
| 'transfer_end' | Corresponds to the FRAME_READY callback provided by the FireGrab API. |
Operator get_framegrabber_callback
See section 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:
- 1394iidc.hdev - Benchmark
- 1394iidc_2cameras.hdev - Concurrent grabbing from two connected cameras
- 1394iidc_camera_types.hdev - Query and use all supported camera types
- 1394iidc_crop.hdev - Grabbing images using image cropping
- 1394iidc_format7.hdev - Image grabbing in format_7 with different frame rates
- 1394iidc_parameters.hdev - Lists all parameters of a device
- 1394iidc_simple.hdev - A simple example to show the usage of the interface
- 1394iidc_software_trigger.hdev - Grabbing images using a software trigger
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\.
Release Notes
- Revision 20.11.2 (Aug 1, 2023):
- The distribution package of this interface now contains files providing meta information for the HDevelop example browser.
- Revision 13.0.1 (Oct 28, 2016):
- HALCON 13 version of the interface.
- Revision 6.0 (Oct 31, 2014):
- HALCON 12 version of the interface.
- Added parameter 'busy_timeout' to allow different waiting times for parameter 'register_value_stopped'.
- Revision 5.1 (Nov 27, 2013):
- Added write-only parameter 'register_value_stopped'.
- Added section Data Transfer to this document.
- Revision 5.0 (May 15, 2012):
- HALCON 11 version of the interface (included in HALCON 11 DVD).
- Revision 4.9 (Apr 30, 2012):
- Fixed thread safety problem in grab_image and grab_image_async that could occur if a pending grab was aborted via the 'do_abort_grab' parameter of set_framegrabber_param.
- Corrected return value of grab_image and grab_image_async in case the grab was aborted via the 'do_abort_grab' parameter of set_framegrabber_param. The return value now is H_ERR_FGF ("Failed grabbing of an image") instead of H_ERR_FGTIMEOUT ("Timeout").
- Revision 4.8 (Jul 6, 2011):
- Fixed problem with grab_image in case of low frame rate.
- Revision 4.7 (Apr 7, 2011):
- Fixed wrong return value of get_framegrabber_param(..., 'packet_size', ...), if value has been changed indirectly (by another parameter setting).
- Revision 4.6 (Sep 7, 2010):
- Fixed bug with fast cameras and internal callback function of FireGrab API, which caused a crash while grabbing images.
- Added missing descriptions ('paramname__description') for parameters 'do_abort_grab', 'pan', 'temperature', and 'tilt'.
- HALCON 10 version of the interface (included in HALCON 10 DVD).
- Revision 4.5 (Jul 30, 2010):
- Adapted to FirePackage driver 2v33.
- Added support of a user-specific callback function to enable notification when a new image is available.
- Added Generic parameter 'do_bus_reset' in open_framegrabber to reset all IEEE 1394 cards with installed FirePackage driver.
- Added card reset for all IEEE 1394 cards with installed FirePackage driver via info_framegrabber('port', ...) in case that no camera has been opened before.
- Added parameter 'card_list', which shows all available IEEE 1394 cards with installed FirePackage driver.
- Fixed bug in the acquisition engine which prevented the use of the maximum frame rate.
- Revision 4.4 (Mar 17, 2010):
- Fixed memory leak in grab_image_start and grab_image_async in case that the parameter MaxDelay was explicitly set to a positive value and the grabbed image was actually "too old". Note that this fix changes the calculated age of the image compared to the previous interface revisions.
- Added implementation of info_framegrabber(.., 'generic', ...) to query all supported values for the Generic parameter in open_framegrabber.
- Revision 4.3 (Feb 3, 2010):
- Fixed Generic parameter handling in open_framegrabber with syntax 'irm=x', which didn't work.
- Fixed missing error message when input value of parameter 'external_trigger' was not a string.
- Read-only parameter 'irm' is now also writeable. The description about the IRM has been updated.
- Revision 4.2 (Jun 15, 2009):
- Querying the parameter ranges under Windows x64 via get_framegrabber_param(..., '<parameter_name>_range', ...) did not return the optional values 'auto' or 'one_push'. This problem has been fixed.
- Added missing read-only parameters with postfix '_description'.
- Fixed wrong visibility in HDevelop Image Acquisition Assistant under Windows x64, where no parameter was 'Beginner'.
- Added item in section Limitations of this documentation to clarify that the number of connectable cameras per IEEE 1394 adapter card is limited.
- Revision 4.1 (Mar 24, 2009):
- New Generic parameter 'num_buffers' in open_framegrabber to specify the desired number of image acquisition buffers.
- Added read-only parameter 'num_buffers'.
- Bug fix in Generic parameter evaluation in open_framegrabber.
- If the current value of a parameter is 'off', now the corresponding integer value is returned instead. This improves the behaviour of the HDevelop Image Acquisition Assistant.
- Revision 4.0 (Dec 1, 2008):
- HALCON 9.0 version of the interface (included in HALCON 9.0 DVD).
- Changed syntax of Generic parameter values in open_framegrabber. For backward compatibility the old syntax still works.
- Revision 3.3 (Apr 22, 2008):
- Added read-only parameters with postfix '_description', '_range', and '_values' to enable the easy parameterization via a generic graphical user interface.
- Revision 3.2 (Feb 27, 2008):
- In Revision 3.1, open_framegrabber might have crashed due to the access of uninitialized memory while evaluating the parameter Generic. This bug has been fixed.
- Support of interlaced gray-scale cameras via the parameter Field in open_framegrabber.
- Revision 3.1 (Oct 16, 2007):
- Added functionality for parameter 'Generic' to allow to reduce the isochronous transfer speed or to disable the IRM before opening the acquisition device.
- Added read-only parameter 'phy_speed' to return the isochronous transfer speed.
- Revision 3.0 (May 15, 2007):
- HALCON 8.0 version of the interface (included in HALCON 8.0 DVD).
- Revision 2.3 (Mar 29, 2007):
- Adaption to FirePackage driver 2v18.
- Added 'raw' to parameter 'color_space' to support the acquisition of RAW images.
- Added parameters 'capture_quality', 'capture_size', 'irm', and 'white_shading'.
- Revision 2.2 (Oct 16, 2006):
- Support of Windows XP x64 (using the FirePackage64 driver).
- Bug fix in YUV conversion.
- Bug fix for use with Parallel HALCON.
- Revision 2.1 (Jul 28, 2006):
- Adaptation to FirePackage driver 2v14.
- Support of RAW8 and RAW16 formats according to IIDC 1394-based digital camera specification 1.31.
- Fixed bug in parameters 'horizontal_resolution' and 'vertical_resolution'.
- Fixed memory leak in open_framegrabber/ close_framegrabber.
- Fixed bug in parameter 'color_space'.
- Corrected return value of get_framegrabber_param( ..., 'external_trigger', ...).
- Revision 2.0 (Jan 4, 2006):
- First official release.