MVTec Software GmbH
  Building Vision For Business
Halcon

HALCON 8.0 1394IIDC Image Acquisition Interface for IEEE 1394 (FireWire) Cameras

This page provides the documentation of the HALCON 1394IIDC interface which is based on the libdc1394 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: 3.2

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.
  • Note that in order to avoid compatibility problems, this interface is statically linked with the latest versions of the system libraries libraw1394 (version 1.2.0) and libdc1394 (version 1.2.2). Thus, the interface does not use the actually installed versions of these libraries.
  • HALCON image acquisition interface hAcq1394IIDC.so.
    If you have properly installed the interface, the shared object file 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 SuSE Linux versions 9.3/10.0 and will probably not work with older Linux kernel versions.

Features

  • Supports all IEEE 1394 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.
  • Currently only 400 MBit/s transfer rates supported, i.e., no full support of IEEE 1394b cameras.
  • No LUTs.
  • No color formats in Format_7.
  • No software cropping of image parts.
  • Bus reset not supported.
  • No color conversion inside the interface, i.e., only the native color formats of the camera can be used.
  • 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():

Name '1394IIDC' The name of the HALCON image acquisition interface.
HorizontalResolution --- Ignored. Note that in Format_7 you can specify the actual image part dynamically by using the operator set_framegrabber_param with the parameter names 'horizontal_offset', 'horizontal_resolution', 'vertical_offset', and 'vertical_resolution'.
VerticalResolution --- Ignored. Note that in Format_7 you can specify the actual image part dynamically by using the operator set_framegrabber_param with the parameter names 'horizontal_offset', 'horizontal_resolution', 'vertical_offset', and 'vertical_resolution'.
ImageWidth --- Ignored. The actual value is specified by the parameter CameraType.
ImageHeight --- Ignored. The actual value is specified by the parameter CameraType.
StartRow --- Ignored.
StartColumn --- Ignored.
Field --- Ignored.
BitsPerChannel --- Ignored. The actual value is specified by the parameter CameraType.
ColorSpace --- Ignored. The actual value is specified by the parameter CameraType.
Generic --- Ignored.
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 partial 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: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
'default' means to adopt the current settings of the camera. Default: 'default'.
Device '-1', 'card.id', 'GUID'',
 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('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' disables the automatic control mode and enables manual setting by integer values
  • 'one_push' means that the camera controls the value automatically by itself only once and returns to manual control mode
  • 'off' fixes the specified value
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',...) .

'brightness' min ... max,
'auto', 'manual', 'one_push', 'off' 		Sets the brightness mode of the camera if a string value is passed. In case of an integer value 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.
'capture_quality' min ... max,
'auto', 'manual', 'one_push', 'off' 		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', 'one_push', 'off' 		Sets the capture_size mode of the camera if a string value is passed. In case of an integer value the capture_size mode is switched to 'manual' (if supported) and the capture_size value is set.
'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.
'do_bus_reset' --- Resets the 1394IIDC bus.
'do_free_resources' --- Frees the resources of the isochronous channel on the IEEE 1394 bus. The setting fails, e.g., if not enough bandwidth is available on the bus. Note that calling a grab_image_start, grab_image_async and grab_image operator allocates the resources automatically if freed before.
'do_reset_camera' --- Sets the factory defaults of the camera. The settings induced by this parameter call depend highly on the camera.
'exposure' min ... max,
'auto', 'manual', 'one_push', 'off' 		Sets the exposure mode of the camera if a string value is passed. In case of an integer value 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', 'one_push', 'off' 		Sets the focus mode of the camera if a string value is passed. In case of an integer value the focus mode is switched to 'manual' (if supported) and the focus value is set.
'gamma' min ... max,
'auto', 'manual', 'one_push', 'off' 		Sets the gamma mode of the camera if a string value is passed. In case of an integer value 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. -1 means to abort never. Default: 5000.
'horizontal_offset' min ... max The row coordinate of the upper left pixel of the desired image part if Format_7 is set. The passed value gets rounded to the next smaller value to fit the step width restriction of this parameter (which depends on the camera). max equals the maximum image height minus the step width. This parameter is only supported if no resources are allocated (see also 'do_free_resources').
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. This parameter is only supported if no resources are allocated (see also 'do_free_resources').
'hue' min ... max,
'auto', 'manual', 'one_push', 'off' 		Sets the hue mode of the camera if a string value is passed. In case of an integer value the hue mode is switched to 'manual' (if supported) and the hue value is set.
'iris' min ... max,
'auto', 'manual', 'one_push', 'off' 		Sets the iris mode of the camera if a string value is passed. In case of an integer value the iris mode is switched to 'manual' (if supported) and the iris value is set.
'num_buffers' number Sets the size of the DMA ring buffer (num_buffers > = 2). This parameter is only supported if no resources are allocated (see also 'do_free_resources').
Default: 2.
'optical_filter' min ... max,
'auto', 'manual', 'one_push', 'off' 		Sets the optical_filter mode of the camera if a string value is passed. In case of an integer value the optical_filter mode is switched to 'manual' (if supported) and the optical_filter value is set.
'packet_size' min ... max, -1 Specifies the size of the transferred packets in bytes. This parameter is only supported when no resources are currently allocated and Format_7 is set (see also 'do_free_resources' and 'camera_type'). 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. -1 specifies the maximal packet size.
'pan' min ... max,
'auto', 'manual', 'one_push', 'off' 		Sets the pan mode of the camera if a string value is passed. In case of an integer value the pan mode is switched to 'manual' (if supported) and the pan value is set.
'register_address' 'address' Sets the register address of the camera control register you want to manipulate directly. The register address must be assigned to the parameter value in the hexadecimal format and as a string.
'register_value' 'value' Manipulates the camera control register selected with the parameter 'register_address' to the value specified. The value you want to set must be assigned to the parameter value in the hexadecimal format and as a string.
Attention: this parameter manipulates any camera control register specified by 'register_address' directly! Undefined register manipulations can have bad side effects concerning the camera's functionality.
'saturation' min ... max,
'auto', 'manual', 'one_push', 'off' 		Sets the saturation mode of the camera if a string value is passed. In case of an integer value the saturation mode is switched to 'manual' (if supported) and the saturation value is set.
'sharpness' min ... max,
'auto', 'manual', 'one_push', 'off' 		Sets the sharpness mode of the camera if a string value is passed. In case of an integer value the sharpness mode is switched to 'manual' (if supported) and the sharpness value is set.
'shift_bits' number Some cameras deliver for mono16 and rgb16 images a lower number of relevant bits which are aligned to the least significant bit. Use the parameter 'shift_bits' to shift the relevant bits to the most significant bit. Default: 0.
'shutter' min ... max
'auto', 'manual', 'one_push', 'off' 		Sets the shutter mode of the camera if a string value is passed. In case of an integer value 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' Some cameras deliver the image data for mono16 and rgb16 in reverse byte order. Setting this parameter to 'true' inverts the received byte order such that you get the image you want.
Default: 'false'.
'temperature' min ... max,
'auto', 'manual', 'one_push', 'off' 		Sets the temperature mode of the camera if a string value is passed. In case of an integer value the temperature mode is switched to 'manual' (if supported) and the (target) temperature value is set.
'tilt' min ... max,
'auto', 'manual', 'one_push', 'off' 		Sets the tilt mode of the camera if a string value is passed. In case of an integer value the tilt mode is switched to 'manual' (if supported) and the tilt value is set.
'trigger_mode' 0, 1, 2, 3 Sets the trigger mode as defined in the IEEE 1394-based digital camera specification:
  • 0: Integration time is described by shutter parameter.
  • 1: Integration time is equal to the pulse width of the external trigger input.
  • 2: Integration stops after n external trigger events, see also 'trigger_parameter'.
  • 3: Camera will issue trigger internally and cycle time is a multiple of the cycle time of the fastest frame rate, see also 'trigger_parameter'. Integration time is described by shutter parameter.
'trigger_parameter' number Sets the trigger parameter needed by the trigger modes 2 and 3: In trigger mode 2 it specifies the number of trigger input events which define the integration time (n>2!). In trigger mode 3 it defines the cycle time as multiple of the cycle time of the fastest frame rate (n>1!). Refer to the IIDC 1394-based DCAM specification for further information.
'trigger_polarity' 0, 1 Sets the trigger polarity and distinguishes whereas the rising (1) or falling (0) edge triggers the camera. Be aware of the settings your camera supplies.
'ub' ub_value,
'auto', 'manual', 'one_push', 'off' 		Sets the white_balance mode of the camera if a string value is passed. In case of an integer value the white_balance mode is switched to 'manual' (if supported) and the ub value is set.
'vertical_offset' min ... max The column coordinate of the upper left pixel of the desired image part if Format_7 is set. The passed value gets rounded to the next smaller value to fit the step width restriction of this parameter (which depends on the camera). max equals the maximum image width minus the step width. This parameter is only supported if no resources are allocated (see also 'do_free_resources').
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. This parameter is only supported if no resources are allocated (see also 'do_free_resources').
'video_gain' min ... max
'auto', 'manual', 'one_push', 'off' 		Sets the gain mode of the camera if a string value is passed. In case of an integer value 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', 'one_push', 'off' 		Sets the white_balance mode of the camera if a string value is passed. In case of an integer value the white_balance mode is switched to 'manual' (if supported) and the vr value is set.
'white_shading' [r_value,g_value,b_value],
'auto', 'manual', 'one_push', 'off' 		Sets the white_shading mode of the camera if a string value is passed. In case of a 3-tuple value (type long) the white_shading mode is switched to 'manual' (if supported) and the r_value, g_value and b_value are set.
'zoom' min ... max,
'auto', 'manual', 'one_push', 'off' 		Sets the zoom mode of the camera if a string value is passed. In case of an integer value 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.

'camera_guid' guid (string) Returns the Global Unified Identifier (GUID) of the camera). The returned string fits the format '0x<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.
'dcam_version' version (string) Returns the version number of the underlying 1394-based digital camera specification.
'framerate' 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.
'revision' revision (string) The revision number of the HALCON 1394IIDC interface.
'trigger' [<'on/off capable'> (string),
<'polarity capable'> (string),
<'mode 0'> (string),
<'mode 1'> (string),
<'mode 2'> (string),
<'mode 3'> (string)] 		Returns general informations about the trigger support of the camera including the supported trigger modes.
'video_resolution' resolution (string) Returns the decoded video format and video mode setting within the string format '<width>x<height>, <color_code>' according to the 1394-based digital camera specification.

Release Notes

  • Revision 3.2 (Nov 28, 2008):
    • Format7 can be dynamically changed by parameter 'camera_type' now.
    • Bugfix in close_framegrabber, which led to an exception.
    • The values of the parameters 'horizontal_resolution' and 'vertical_resolution' are set correctly now.
  • Revision 3.1 (Sep 30, 2008):
    • Statically linked with latest versions of libdc1394_control.a and libraw1394.a.
    • Added support of Linux x86_64 systems.
    • Added missing documentation of the parameter 'start_async_after_grab_async'.
  • Revision 3.0 (May 15, 2007):
    • HALCON 8.0 version of the interface (included in HALCON 8.0 DVD).
    • Renamed parameter 'allocate_resources' into 'do_free_resources'.
  • Revision 2.0 (Nov 30, 2006):
    • First official release.


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






Last modified: Fri Nov 28 13:42:12 CET 2008