MVTec Software GmbH
  Building Vision For Business
MVTec at Automatica 2014
Follow us on YouTube  Subscribe our RSS feed
Halcon

HALCON 9.0 1394IIDC-2 Image Acquisition Interface for IEEE 1394 (FireWire) Cameras

This page provides the documentation of the HALCON 1394IIDC-2 interface which is based on the libdc1394 v2 library via any OHCI compliant IEEE 1394 adapter cards. With this interface you can acquire images from all IEEE 1394 (FireWire) cameras that are compliant to the IIDC 1394 standard. Registered customers can download the latest revision of this interface from the MVTec WWW server.

Revision: 4.0

System Requirements

  • Intel compatible PC with Linux x86 or x86_64 operating system and OHCI compliant IEEE 1394 adapter.
  • The following kernel modules must be loaded: ohci1394, ieee1394, raw1394, video1394.
  • Read/write access to the following devices: /dev/raw1394 and /dev/video1394.
  • Installed system libraries libraw1394 (version 1.2.0) and libdc1394 (version 2.1).
  • HALCON image acquisition interface hAcq1394IIDC-2.so or hAcq1394IIDC-2xl.so, respectively.
    If you have properly installed the interface, the shared object files should reside in lib/$HALCONARCH within the HALCON base directory $HALCONROOT you have chosen during the installation of HALCON.
  • Please note that this interface has been tested on kernel version 2.6.13 (or higher) and will probably not work with older Linux kernel versions.

Features

  • Supports all IEEE 1394a and IEEE 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.

Limitations

  • grab_data and grab_data_async not supported.
  • No LUTs.
  • Bus reset 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:

  • horizontal_offset
  • horizontal_resolution
  • vertical_offset
  • vertical_resolution

Note that because of the smaller used sensor size the frame rate will raise.

Description

Parameters for open_framegrabber():

The number of used buffers can be set. We recommend to use at least two buffers. Default: 2.
Name '1394IIDC-2' The name of the HALCON image acquisition interface.
HorizontalResolution 1, 2, 4, width Set the horizontal resolution of the image sensor if CameraType is set to Format_7. The passed value gets rounded to fit the step with restriction of this parameter (which depends on the camera). The value 1 means to use the full sensor width (2 = half, 4 = quarter). 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. Default: 1.
VerticalResolution 1, 2, 4, height Set the vertical resolution of the image sensor if CameraType is set to Format_7. The passed value gets rounded to fit the step with restriction of this parameter (which depends on the camera). The value 1 means to use the full sensor height (2 = half, 4 = quarter). 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. Default: 1.
ImageWidth 0, width Sets the width of the HALCON image. The value 0 stands for the complete image. Default: 0.
ImageHeight 0, height Sets the height of the HALCON image. The value 0 stands for the complete image. Default: 0.
StartRow 0, row The row coordinate of the upper left pixel of the HALCON image. Default: 0.
StartColumn 0, column The column coordinate of the upper left pixel of the HALCON image. Default: 0.
Field --- Ignored.
BitsPerChannel -1, 8, 9, 10, 11, 12, 13, 14, 15, 16 The 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. Default: -1.
ColorSpace 'default', 'gray', 'raw', 'rgb', 'yuv' Sets the desired color space of the resulting HALCON image. 'default' means to adopt the camera setting. Default: 'default'.
Generic 'num_buffers=num', -1 With the Generic parameter 'num_buffers' the actual number of image buffers used in the HALCON acquisition interface can be set before the camera is initialized. Note that the parameter must be specified as a string, e.g., 'num_buffers=5'. Note that depending on the image size of the used camera a large number of buffers can exceed the available memory size of your computer. Default: 2.
ExternalTrigger 'true', 'false' Activate/deactivate external triggering (if supported by the camera). Default: 'false'.
CameraType 'format:mode:fps', 'default' 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 scalable image mode; here, the frame rate depends from 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:X:0 Y8
7:X:1 YUV411
7:X:2 YUV422
7:X:3 YUV444
7:X:4 RGB8
7:X:5 Y16
7:X:6 RGB16
7:X:7 Signed Y16
7:X:8 Signed RGB16
7:X:9 RAW8
7:X:10 RAW16
Please note that 'X' is a number, which depends of the supported formats of the camera. Possible values: 0...7.
'default' means to adopt the current settings of the camera. Default: 'default'.
Device '-1', 'GUID' Select the desired camera device by the camera GUID. To query the actual installed cameras you can call info_framegrabber('1394IIDC','info_boards',...). '-1' selects the first available device. Default: '-1'.
Port --- Ignored.
LineIn --- Ignored.

Parameters for set_framegrabber_param():

Note that most of the following parameters (and also the valid parameter values!) depend on the capabilities of the used camera. Additionally, the default values of these parameters depend on the current camera settings.

For many camera features the corresponding parameter (like 'shutter' and 'brightness') allows to set the operation mode of this feature by a string value:

  • 'auto' means that the camera controls the value automatically by itself.
  • 'manual' activates a feature, which is off.
  • 'off' fixes the specified value. In the HDevelop Image Acquisition Assistant you can enable a feature, which is off, by setting it to 'manual'.
  • 'one_push' means that the camera controls the value automatically by itself only once and returns to manual setting by integer values.
You can request the valid minimal and maximal integer values and the step width required for the manual setting as well as the supported modes of these parameters by calling get_framegrabber_param(...,'<parameter_name>_range',...) .
Other parameters like 'camera_type or 'trigger_mode' support a camera-specific set of values. This set of values can be requested by calling get_framegrabber_param(...,'<parameter_name>_values',...) .

'bayer_pattern' 'bg_gr', 'gb_rg', 'gr_bg', 'rg_gb' Sets the bayer pattern of the camera. Default: 'rg_gb'.
'brightness' min ... max,
'auto', 'manual', 'off', 'one_push'
Sets the 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' 0, 1 Setting this parameter to 1 causes the camera to use the one shot mode for grabbing images. Setting this parameter to 0 causes the camera to use the continuous shot mode for grabbing images. Not all cameras support the one shot mode. Default: 0.
'camera_type' 'format:mode:fps' Specify the desired video settings as a string consisting of the video format (0,1,2,6,7), the video mode (0,1,2,3,4,5,6,7), and the frame rate (0,1,2,3,4,5,6,7), separated by colons. When setting video format to Format_7 the last parameter value is the color_coding.
With get_framegrabber_param(...,'camera_type_values',...) all supported camera type values can be queried.
'capture_quality' min ... max,
'auto', 'manual', 'off', 'one_push'
Sets the 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' min ... max,
'auto', 'manual', 'off', 'one_push'
Sets the 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' 'default', 'gray', 'raw', 'rgb', 'yuv' Sets the desired color space of the resulting HALCON image. 'default' means to adopt the camera setting.
'do_abort_grab' --- Cancel current grab.
'do_reset_camera' --- Sets the factory defaults of the camera. The settings induced by this parameter call depend highly on the camera.
'do_software_trigger' --- Forces a trigger pulse. Note that this parameter only works, if trigger source is 'software'.
'exposure' min ... max,
'auto', 'manual', 'off', 'one_push'
Sets the 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' 'true', 'false' Enables/disables the external trigger mode. Be aware of the settings your camera supplies.
'focus' min ... max,
'auto', 'manual', 'off', 'one_push'
Sets the 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' min ... max,
'auto', 'manual', 'off', 'one_push'
Sets the 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' msec Specify the desired timeout (milliseconds passed as a long) for aborting a pending grab. If -1 is specified, the timeout is set to infinite. Default: 5000.
'horizontal_offset' min ... max Sets the row coordinate of the upper left pixel of the desired image part if Format_7 is specified.
horizontal_resolution min ... max Sets the horizontal resolution of the desired image part if Format_7 is specified. The passed value gets rounded to the next smaller value to fit the step width restriction of this parameter (which depends on the camera). min equals the step width whereas max equals the maximum image width.
'hue' min ... max,
'auto', 'manual', 'off', 'one_push'
Sets the 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.
'iris' min ... max,
'auto', 'manual', 'off', 'one_push'
Sets the 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.
'optical_filter' min ... max,
'auto', 'manual', 'off', 'one_push'
Sets the 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' min ... max Specifies the size of the transferred packets (only supported in Format_7 mode). The passed value gets rounded to the next smaller value to fit the step width restriction of this parameter. The value specifies the bandwidth of the isochronous channel and therefore influences the frame rate of the camera. By default, the packet size is set automatically to the maximum possible value.
'pan' min ... max,
'auto', 'manual', 'off', 'one_push'
Sets the 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
Specify the address of the register that should be set directly (as long) via the offset, e.g., 0x00000520.
'register_value' 0x00000000 ... 0xFFFFFFFF
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'.
'saturation' min ... max,
'auto', 'manual', 'off', 'one_push'
Sets the 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' min ... max,
'auto', 'manual', 'off', 'one_push'
Sets the 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' min ... max
'auto', 'manual', 'off', 'one_push'
Sets the 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' 'enable', 'disable' By default, at the end of grab_image_async a new request for an asynchronous grab command is automatically given to the camera. If the parameter 'start_async_after_grab_async' is set to 'disable' this new grab command is omitted. Default: 'enable'.
'swap_bytes' 'false', 'true' In case of images with a bit depth of more than 8 bit per pixel this parameter swaps the bytes. Default: 'true'.
'target_temperature' min ... max,
'auto', 'manual', 'off', 'one_push'
Sets the 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' min ... max,
'auto', 'manual', 'off', 'one_push'
Sets the 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' min ... max Sets the trigger delay value of the camera (in seconds).
'trigger_mode' 'mode_0', 'mode_1', 'mode_2', 'mode_3', 'mode_4', 'mode_5', 'mode_14', 'mode_15' Sets the trigger mode as defined in the IEEE 1394-based digital camera specification:
  • mode_0: Integration time is described by shutter parameter.
  • mode_1: Integration time is equal to the pulse width of the external trigger input.
  • mode_2: Integration stops after n external trigger events.
  • mode_3: Camera will issue trigger internally and cycle time is a multiple of the cycle time of the fastest frame rate Integration time is described by shutter parameter.
  • mode_4: Multiple shutter present mode. After the n-th external trigger event integration stops. Integration time is controlled by the shutter parameter.
  • mode_5: Multiple shutter pulse width mode. After the n-th external trigger event integration stops. Integration time is controlled by the trigger duration.
  • mode_14 and mode_15 are vendor specific trigger modes.
  • n is controlled via the parameter 'trigger_parameter'. Be aware of the settings your camera supplies.
'trigger_parameter' number Sets the trigger parameter needed by the trigger modes 2 to 5: In trigger mode 2 it specifies the number of trigger input events which define the integration time (n>1!). In trigger mode 3 it defines the cycle time as multiple of the cycle time of the fastest frame rate (n>0!). In trigger mode 4 and 5 it defines the number of exposures (n>0!). See IEEE 1394-based digital camera specification for further information.
'trigger_signal' 'low_active', 'high_active' Sets the trigger polarity and distinguishes whereas the rising or falling edge triggers the camera. Be aware of the settings your camera supplies.
'trigger_source' 'line_0', 'line_1', 'line_2', 'line_3', 'software' Sets the trigger source as defined in the IEEE 1394-based digital camera specification. Be aware of the settings your camera supplies.
'ub' ub_value,
'auto', 'manual', 'off', 'one_push'
Sets the 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' min ... max Sets the column coordinate of the upper left pixel of the desired image part if Format_7 is specified.
vertical_resolution min ... max Sets the vertical resolution of the desired image part if Format_7 is specified. The passed value gets rounded to the next smaller value to fit the step width restriction of this parameter (which depends on the camera). min equals the step width whereas max equals the maximum image height.
'video_gain' min ... max
'auto', 'manual', 'off', 'one_push'
Sets the video gain mode of the camera if a string value is passed. Otherwise the gain mode is switched to 'manual' (if supported) and the gain value is set.
'volatile' 'enable', 'disable' Grayscale 8bpp and 16bpp only! In the volatile mode the image buffers are used directly to store HALCON images. This is the fastest mode avoiding to copy raw images in memory. However, be aware that older images are overwritten again and again as a side-effect. Thus, you can only process one image while you grab another image. Older images are invalid!
'vr' vr_value,
'auto', 'manual', 'off', 'one_push'
Sets the 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_b' b_value,
'auto', 'manual', 'off', 'one_push'
Sets the 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 b_value is set.
'white_shading_g' g_value,
'auto', 'manual', 'off', 'one_push'
Sets the 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 g_value is set.
'white_shading_r' r_value,
'auto', 'manual', 'off', 'one_push'
Sets the 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 r_value is set.
'zoom' min ... max,
'auto', 'manual', 'off', 'one_push'
Sets the 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():

Additional parameters supported by get_framegrabber_param only. Note that all parameters supported by set_framegrabber_param except the ones with prefix 'do_' can also be accessed by get_framegrabber_param. Note that all parameters of get_framegrabber_param return an empty tuple if they are not supported by the used camera. Furthermore, corresponding to the parameters supported by set_framegrabber_param, there may exist additional read-only parameters with the following postfixes:

  • '_description': These parameters provide the tooltip of the corresponding parameter as a string.
  • '_range': These parameters provide the minimum, maximum, stepwidth, and default values for the corresponding integer or float parameter as a tuple with 4 elements, e.g., get_framegrabber_param(..,'exposure_range',..) will return the output tuple [min,max,step,default]. Optionally, this tuple can also contain additional valid string values like 'auto' or 'manual'.
  • '_values': These parameters provide the valid value list for the corresponding parameter as a tuple, e.g., get_framegrabber_param(..,'volatile_values',..) will return the output tuple ['enable','disable'].
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.

'bits_per_channel' bits (long) The number of significant bits per channel.
'camera_guid' guid (string) Returns the Global Unified Identifier (GUID) of the camera). The returned string fits the format '<hexadecimal vendor code>'.
'camera_model' model_name (string) Returns the name of the camera model.
'camera_vendor' vendor_name (string) Returns the name of the camera vendor.
'frame_rate' fps (float) The 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 and serves as a upper reachable bound.
'image_height' height (long) Returns the height of the resulting HALCON image.
'image_width' width (long) Returns the width of the resulting HALCON image.
'num_buffers' number (long) The number of buffers used for the image acquisition.
'revision' revision (string) The revision number of the HALCON 1394IIDC-2 interface.
'temperature' temperature (long) Returns the current temperature value.
'used_bandwidth' bandwidth (long) Shows the current bandwidth usage of the 1394 IIDC bus in percent.

Release Notes

  • Revision 4.0 (March 17, 2010):
    • First official release.


© Copyright 2014, MVTec Software GmbH, corporate/legal/privacy information