interfaces mvtec

Interface Documentation

Image Acquisition Interface for IEEE 1394 (FireWire) Cameras

Interface: 1394IIDC
Revision: 20.11.2
Date: 2023-08-01
1394IIDC: Legacy Interface

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.

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:
  • 'burst_count'
  • 'camera_type'
  • 'irm'
  • 'horizontal_offset'
  • 'horizontal_resolution'
  • 'packet_size'
  • 'vertical_offset'
  • 'vertical_resolution'
If you want to set a special register value, which also needs a stopped data transfer, the parameter 'register_value_stopped' has to be used instead of the parameter 'register_value'. The parameter 'busy_timeout' defines the time to wait before the next command is send to the camera.
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:
  • 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.
  • 1: full horizontal resolution
  • 2: subsampling by factor 2
    The horizontal offset can be set by calling set_framegrabber_param(.., 'horizontal_offset', ..). If CameraType is set to a standard format this parameter will be ignored.
VerticalResolution 1, 2, <height> 1 integer Vertical resolution of the image sensor if CameraType is set to Format_7.
  • 1: full horizontal resolution
  • 2: subsampling by factor 2
    The vertical offset can be set by calling set_framegrabber_param(.., 'vertical_offset', ..). If CameraType is set to a standard format this parameter will be ignored.
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:
  • 0: continuous shot mode
  • 1: one shot mode
  • >1: specify multi shot mode
Typically, this interface is operated in continuous shot mode; the other modes are only useful in specific configurations, e.g., in case of software triggering.
'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.
  • 0: Mode shutter. Integration time is described by shutter parameter.
  • 1: Mode pulse_with. Integration time is equal to the pulse width of the external trigger input.
  • 2: Mode n_pulses. Integration stops after n external trigger events.
  • 3: Mode shutter_n_frames. Camera will issue trigger internally and cycle time is a multiple of the fastest frame rate.
'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.
  • 0: low active
  • 1: high active Be aware of the settings your camera supplies.
'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.
  • 0: low active
  • 1: high active Be aware of the settings your camera supplies.
'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:
  • 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

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):
  • 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.