MVTec Software GmbH
  Building Vision For Business
Halcon

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

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.

Revision: 4.9

System Requirements

  • Intel compatible PC with Windows XP/Vista/7 or Windows XP/Vista/7 x64 Edition 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.

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.
  • grab_data and grab_data_async not supported.
  • No LUTs.
  • 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 (also in open_framegrabber)
  • vertical_offset
  • vertical_resolution (also in open_framegrabber)

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

In contrast the these 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 busses.
  • 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.

Description

Parameters for open_framegrabber():

Name '1394IIDC' The name of the HALCON image acquisition interface.
HorizontalResolution 1, 2, width Set the horizontal resolution of the image sensor if CameraType is set to Format_7. The value 1 means to use the full sensor width. 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, height Set the vertical resolution of the image sensor if CameraType is set to Format_7. The value 1 means to use the full sensor height. 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 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. Default: 0.
ImageHeight 0, height Sets the 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. Default: 0.
StartRow 0, row The 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). Default: 0.
StartColumn 0, column The 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). Default: 0.
Field 'interlaced', 'progressive' Specifies the alignment of the grabbed images ('interlaced' for use in combination with specific interlaced cameras). Note that 'interlaced' is currently only supported in combination with ColorSpace set to 'gray'. Default: 'progressive'.
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 ['do_bus_reset=time', 'irm=0', 'num_buffers=num', 'phy_speed=speed'], -1 Generic parameter, see description above.
ExternalTrigger 'true', 'false' Activate/deactivate external triggering. Default: 'false'.
CameraType 'format:mode:fps', 'resolution.color.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
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)
'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. 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
  • 'one_push' means that the camera controls the value automatically by itself only once and returns to manual setting by integer values
  • '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',...) .

'bayer_pattern' 'rg_gb', 'gb_rg', 'gr_bg', 'bg_gr' The alignment of the bayer pattern. The values are set acording 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 The number of significant bits per channel. 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' min ... max,
'auto', '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 input and the brightness value is set. See get_framegrabber_param to yield min, max and the supported modes.
'burst_count' min ... max Sets the burst count mode of the camera: 0 stands for continuous shot mode, 1 stands for one shot mode, and values >1 specify multi shot mode. See get_framegrabber_param to yield min and max. Typically, this interface is operated in continuous shot mode; the other modes are only useful in specfic configurations, e.g., in case of software triggering.
'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 or 1.875,3.75,7.5,15.0,30.0,60.0, respectively), separated by colons. Note that this parameter also updates the parameter settings for the image part. When setting video format to Format_7 the frame rate parameter is ignored and the packet size for isochronuous transmission is maximized for the specified image size instead.
'capture_quality' min ... max,
'auto', 'one_push', 'off' 		Sets the desired capture quality for Format_6.
'capture_size' min ... max,
'auto', 'one_push', 'off' 		Set the desired capture size for Format_6.
'color_space' 'gray', 'raw', 'rgb', 'yuv' Sets the 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' min ... max,
'auto', 'one_push', 'off' 		Sets the exposure mode of the camera if a string value is passed. In case of an integer value the exposure value is set. See get_framegrabber_param to yield min, max and the supported modes.
'external_trigger' 'true', 'false' Enables/disables the trigger mode.
'focus' min ... max,
'auto', 'one_push', 'off' 		Sets the focus mode of the camera if a string value is passed. In case of an integer value the focus value is set. See get_framegrabber_param to yield min, max and the supported modes.
'gamma' min ... max,
'auto', 'one_push', 'off' 		Sets the gamma mode of the camera if a string value is passed. In case of an integer value the gamma value is set. See get_framegrabber_param to yield min, max and the supported modes.
'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' 0 ... max Sets the horizontal offset of the image sensor. See get_framegrabber_param to yield min, max.
'horizontal_resolution' 0 ... max Sets the horizontal resolution of the image sensor. See get_framegrabber_param to yield min, max.
'hue' min ... max,
'auto', 'one_push', 'off' 		Sets the hue mode of the camera if a string value is passed. In case of an integer value the hue value is set. See get_framegrabber_param to yield min, max and the supported modes.
'image_height' -1, min ... max Sets the height of the resulting HALCON image. -1 specifies the maximum image height.
'image_width' -1, min ... max Sets the width of the resulting HALCON image. -1 specifies the maximum image width.
'iris' min ... max,
'auto', 'one_push', 'off' 		Sets the iris mode of the camera if a string value is passed. In case of an integer value the iris value is set. See get_framegrabber_param to yield min, max and the supported modes.
'irm' 0, 1 (long) Sets the 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! Default: 1.
'optical_filter' min ... max,
'auto', '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 value is set. See get_framegrabber_param to yield min, max and the supported modes.
'packet_size' min ... max 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. See get_framegrabber_param to yield min, max. Note that specifying a very small packet size may result in timeout errors while grabbing images.
'pan' min ... max,
'auto', 'one_push', 'off' 		Sets the pan mode of the camera if a string value is passed. In case of an integer value the pan value is set. See get_framegrabber_param to yield min, max and the supported modes.
'register_address' 0x00000000 ... 0xFFFFFFFF
 Specify the address of the register that should be set directly (as long), e.g., 0xF0F0060C.
'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', 'one_push', 'off' 		Sets the saturation mode of the camera if a string value is passed. In case of an integer value the saturation value is set. See get_framegrabber_param to yield min, max and the supported modes.
'sharpness' min ... max Sets the sharpness mode of the camera if a string value is passed. In case of an integer value the sharpness value is set. See get_framegrabber_param to yield min, max.
'shutter' min ... max
'auto', 'one_push', 'off' 		Sets the shutter mode of the camera if a string value is passed. In case of an integer value the shutter value is set. See get_framegrabber_param to yield min, max and the supported modes.
'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'.
'start_column' 0 ... max Sets the column coordinate of the upper left corner of the resulting HALCON image part.
'start_row' 0 ... max Sets the row coordinate of the upper left corner of the resulting HALCON image part.
'swap_bytes' 'false', 'true' Specifies whether the byte order within a pixel should be swapped in Y16 and RGB16 modes. Default: 'false'.
'temperature' min ... max,
'auto', 'one_push', 'off' 		Sets the temperature mode of the camera if a string value is passed. In case of an integer value the target temperature value is set. See get_framegrabber_param to yield min, max and the supported modes.
'tilt' min ... max,
'auto', 'one_push', 'off' 		Sets the tilt mode of the camera if a string value is passed. In case of an integer value the tilt value is set. See get_framegrabber_param to yield min, max and the supported modes.
'trigger_delay' min ... max,
'auto', 'one_push', 'off' 		Sets the trigger_delay mode of the camera if a string value is passed. In case of an integer value the trigger_delay value is set. See get_framegrabber_param to yield min, max and the supported modes.
'trigger_mode' number Sets the 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.
See get_framegrabber_param to yield the supported modes.
'trigger_parameter' number Sets the trigger parameter needed by the trigger modes 2 and 3: In trigger mode 2 ('n_pulses') it specifies the number of trigger input events which define the integration time (n>1!). In trigger mode 3 ('shutter_n_frames') it defines the cycle time as multiple of the cycle time of the fastest frame rate (n>0!). See IEEE 1394-based digital camera specification for further information.
'trigger_polarity' number Sets the trigger polarity and distinguishes whereas the rising or falling edge triggers the camera.
  • 0: low active
  • 1: high active
'trigger_source' 0 ... max Sets the trigger source.
'ub' min ... max,
'auto', 'one_push', 'off' 		Sets the white balance mode of the camera if a string value is passed. In case of an integer value the ub component of the white balance is set. See get_framegrabber_param to yield min, max and the supported modes.
'vertical_offset' 0 ... max Sets the vertical offset of the image sensor. See get_framegrabber_param to yield min, max.
'vertical_resolution' 0 ... max Sets the vertical resolution of the image sensor. See get_framegrabber_param to yield min, max.
'video_gain' min ... max,
'auto', 'one_push', 'off' 		Sets the gain mode of the camera if a string value is passed. In case of an integer value the gain value is set. See get_framegrabber_param to yield min, max and the supported modes.
'vr' min ... max,
'auto', 'one_push', 'off' 		Sets the white balance mode of the camera if a string value is passed. In case of an integer value the vr component of the white balance is set. See get_framegrabber_param to yield min, max and the supported modes.
'white_shading' min ... max,
'auto', 'one_push', 'off' 		Set the white shading of the camera.
'zoom' min ... max,
'auto', 'one_push', 'off' 		Sets the zoom mode of the camera if a string value is passed. In case of an integer value the zoom value is set. See get_framegrabber_param to yield min, max and the supported modes.

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.

'available_callback_types' callback_type  Query all callback types which are supported by this interface.
'camera_model' model_name (string) Returns the name of the camera model.
'camera_vendor' vendor_name (string) Returns the name of the camera vendor.
'card_list' card_ids (string) Returns a list of all IEEE 1394 compliant cards of the PC with installed FirePackage driver.
'device' GUID (string) Returns the GUID of the camera.
'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.
'image_available' 0, 1 (long) Returns the 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.
'num_buffers' number (long) The number of buffers used for the image acquisition.
'phy_speed' speed (string) Returns the real physical speed that is used to talk with the connected image device, see also parameter Generic in open_framegrabber.
'revision' revision (long) The revision of the HALCON 1394IIDC interface.

Parameters for set_framegrabber_callback():

The following callback types are supported by this interface:

'transfer_end' Corresponds to the FRAME_READY callback provided by the FireGrab API.

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 actual processing from the user-specific callback function to a separate thread that is controlled via signals or events.

Release Notes

  • Revision 4.9 (Apr 30, 2012):
    • Fixed thread safety problem in grab_image and grab_image_async that could occur if a pending grab was aborted via the 'do_abort_grab' parameter of set_framegrabber_param.
    • Corrected return value of grab_image and grab_image_async in case the grab was aborted via the 'do_abort_grab' parameter of set_framegrabber_param. The return value now is H_ERR_FGF ("Failed grabbing of an image") instead of H_ERR_FGTIMEOUT ("Timeout").
  • Revision 4.8 (Jul 6, 2011):
    • Fixed problem with grab_image in case of low frame rate.
  • Revision 4.7 (Apr 7, 2011):
    • Fixed wrong return value of get_framegrabber_param(...,'packet_size',...), if value has been changed indirectly (by another parameter setting).
  • Revision 4.6 (Sep 7, 2010):
    • Fixed bug with fast cameras and internal callback function of FireGrab API, which caused a crash while grabbing images.
    • Added missing descriptions ('paramname__description') for parameters 'do_abort_grab', 'pan', 'temperature', and 'tilt'.
    • HALCON 10 version of the interface (included in HALCON 10 DVD).
  • Revision 4.5 (Jul 30, 2010):
    • Adapted to FirePackage driver 2v33.
    • Added support of a user-specific callback function to enable notification when a new image is available.
    • Added Generic parameter 'do_bus_reset' in open_framegrabber to reset all IEEE 1394 cards with installed FirePackage driver.
    • Added card reset for all IEEE 1394 cards with installed FirePackage driver via info_framegrabber('port',...) in case that no camera has been opened before.
    • Added parameter 'card_list', which shows all available IEEE 1394 cards with installed FirePackage driver.
    • Fixed bug in the acquisition engine which prevented the use of the maximum frame rate.
  • Revision 4.4 (Mar 17, 2010):
    • Fixed memory leak in grab_image_start and grab_image_async in case that the parameter MaxDelay was explicitly set to a positive value and the grabbed image was actually "too old". Note that this fix changes the calculated age of the image compared to the previous interface revisions.
    • Added implementation of info_framegrabber(..,'generic',...) to query all supported values for the Generic parameter in open_framegrabber.
  • Revision 4.3 (Feb 3, 2010):
    • Fixed Generic parameter handling in open_framegrabber with syntax 'irm=x', which didn't work.
    • Fixed missing error message when input value of parameter 'external_trigger' was not a string.
    • Read-only parameter 'irm' is now also writeable. The description about the IRM has been updated.
  • Revision 4.2 (Jun 15, 2009):
    • Querying the parameter ranges under Windows x64 via get_framegrabber_param(...,'<parameter_name>_range',...) did not return the optional values 'auto' or 'one_push'. This problem has been fixed.
    • Added missing read-only parameters with postfix '_description'.
    • Fixed wrong visibility in HDevelop Image Acquisition Assistant under Windows x64, where no parameter was 'Beginner'.
    • Added item in section Limitations of this documentation to clarify that the number of connectable cameras per IEEE 1394 adapter card is limited.
  • Revision 4.1 (Mar 24, 2009):
    • New Generic parameter 'num_buffers' in open_framegrabber to specify the desired number of image acquisition buffers.
    • Added read-only parameter 'num_buffers'.
    • Bugfix 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).
    • Bugfix in YUV conversion.
    • Bugfix 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.


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






Last modified: Mon Apr 30 12:03:10 CEST 2012