HALCON 6.1 Frame Grabber Interface for Unibrain Fire-i Boards

This page provides the documentation of the HALCON frame grabber interface HFGFire-i.dll for the Unibrain Fire-i API. With this interface you can acquire images from IEEE-1394 cameras which are connected to FireBoard400 or FireBoard400-OHCI boards. Registered customers can download the latest revision of this interface from the MVTec WWW server.

Revision: 2.4

• Intel compatible PC with Windows NT 4.0 (Service Pack 5), Windows 2000 or Windows XP.
• Successfully installed Unibrain ubCore software package version 2.0 or 2.1.
• Unibrain DLL firei.dll (version 2.0 or 2.1).
  This DLL must be within your search path %PATH%. If you do not have this DLL, please contact Unibrain or the vendor from which you bought the board.
• HALCON frame grabber interface HFGFire-i.dll or parHFGFire-i.dll, respectively.
  If you have properly installed the interface, both DLLs should reside in bin\i586-nt4 within the HALCON base directory %HALCONROOT% you have chosen during the installation of HALCON.

• Supports IEEE 1394-based digital camera specification 1.30.
• Supports multiple cameras connected to multiple adapter cards.
• Synchronous and asynchronous grabbing.
• External camera triggering.
• Provides color space transformation.
• Subsampling (by specifying the corresponding video mode).
• Software control of a variety of camera parameters.

• Bus reset is not supported.
• grab_region and grab_region_async not supported.
• No LUTs.
• No cropping of image parts (formats 6 and 7 are not supported).

Parameters for open_framegrabber():

	Name		'Fire-i'		The name of the HALCON frame grabber interface.
	HorizontalResolution		---		Ignored.
	VerticalResolution		---		Ignored.
	ImageWidth		---		Ignored.
	ImageHeight		---		Ignored.
	StartRow		---		Ignored.
	StartColumn		---		Ignored.
	Field		---		Ignored.
	BitsPerChannel		---		Ignored.
	ColorSpace		'gray', 'rgb', 'yuv', 'default'		Color space of the resulting HALCON image. 'default' means to adopt the supplied camera color space. Default: 'default'.
	Gain		---		Ignored.
	ExternalTrigger		'true', 'false'		Activate/deactivate external triggering. Default: 'false'.
	CameraType		'format:mode:fps', 'default'		Specify the desired video settings as a string consisting of the video format (0,1,2), 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. 'default' means to adopt the supplied video settings of the camera. Default: 'default'.
	Device		'1', '2', ... 'GUID'		Either the number of the FireBoard (passed as a string!) or the Global Unique Identifier (GUID) of a specific camera. The GUID addresses a specific camera on the available IEEE-1394 busses. The format of this ID is 'xxxxxx-xxxxxxxxxx' whereas x denotes a hexadecimal digit. You can obtain the GUIDs of all cameras linked to the busses by the 'info_boards' parameter of the info_framegrabber operator. If a board number is specified, the Port parameter of open_framegrabber is used to address a camera on the bus. Default: '1'.
	Port		1, 2, ...		The number of the camera found on the IEEE-1394 bus connected to a FireBoard specified by the Device parameter. This parameter is ignored if the Device parameter specifies a GUID. Default: 1 (searches for the first camera).
	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.

Many parameters (like 'exposure' and 'brightness') can be set by either a valid integer value or by specifying one of the following strings:

• 'auto' means that the camera controls the value automatically by itself
• 'manual' disables the automatic control mode
• '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
• 'on' enables the changing of the specified value

	'brightness'		min ... max, 'auto', 'manual', 'one_push', 'on', 'off'		Sets the brightness value of the camera. If the used camera does not support brightness adjustment, H_ERR_FGPARAM is returned (or an empty tuple in the corresponding call to get_framegrabber_param, respectively).
	'camera_type'		'format:mode:fps'		Specify the desired video settings as a string consisting of the video format (0,1,2), 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.
	'color_space'		'gray', 'rgb', 'yuv', 'default'		Color space of the resulting HALCON image. 'default' means, to adopt the supplied camera color space. Default: 'default'.
	'continuous_grabbing'		'enable', 'disable'		Start/stop of the isochronous transmission of video data: 'enable' starts the camera to yield a continuous video stream whereas 'disable' stops it. In contrast to single frame transmission, the isochronous transmission channel is initialized only once before the camera is set to run mode. This mode yields rate benefits while transmitting frame sequences. Notice that grab_image_start and grab_image_async take advantage of the isochronous transmission mode and start the camera by default, whereas grab_image stops it and transfers frames in single transmission mode. Default: 'disable'.
	'exposure'		min ... max, 'auto', 'manual', 'one_push', 'on', 'off'		Sets the auto exposure value of the camera. If the used camera does not support exposure adjustment, H_ERR_FGPARAM is returned (or an empty tuple in the corresponding call to get_framegrabber_param, respectively).
	'external_trigger'		'true', 'false'		Enables/disables the trigger mode. Be aware of the settings your camera supplies.
	'focus'		min ... max, 'auto', 'manual', 'one_push', 'on', 'off'		Sets the focus value of the camera. If the used camera does not support focus adjustment, H_ERR_FGPARAM is returned (or an empty tuple in the corresponding call to get_framegrabber_param, respectively).
	'frame_rate'		0, 1, 2, 3, 4, 5 1.875, 3.75, 7.5, 15.0, 30.0, 60.0		Sets the desired frame rate either as integer as determined in the IEEE 1394-based digital camera specification or as float in frames per second. Be aware of the settings your camera supplies. Default: the default camera setting.
	'gamma'		min ... max, 'auto', 'manual', 'one_push', 'on', 'off'		Sets the gamma value of the camera. If the used camera does not support gamma adjustment, H_ERR_FGPARAM is returned (or an empty tuple in the corresponding call to get_framegrabber_param, respectively).
	'grab_timeout'		msec		Specify the desired timeout (milliseconds passed as a long) for aborting a pending grab. -1 means to abort never. Default: 5000.
	'hue'		min ... max, 'auto', 'manual', 'one_push', 'on', 'off'		Sets the hue value of the camera. If the used camera does not support hue adjustment, H_ERR_FGPARAM is returned (or an empty tuple in the corresponding call to get_framegrabber_param, respectively).
	'iris'		min ... max, 'auto', 'manual', 'one_push', 'on', 'off'		Sets the iris value of the camera. If the used camera does not support iris adjustment, H_ERR_FGPARAM is returned (or an empty tuple in the corresponding call to get_framegrabber_param, respectively).
	'iso_speed'		100, 200, 400, 800, 1600, 3200		Sets the transmission speed in MBit/s. If not running, the isochronous channel and the camera are set when they are started the next time (e.g., with the next grab command).
	'num_buffers'		number		Specify the size of the internal ring buffer to which the frames are grabbed. The size has to be greater than 1! Default: 2.
	'saturation'		min ... max, 'auto', 'manual', 'one_push', 'on', 'off'		Sets the saturation value of the camera. If the used camera does not support saturation adjustment, H_ERR_FGPARAM is returned (or an empty tuple in the corresponding call to get_framegrabber_param, respectively).
	'sharpness'		min ... max, 'auto', 'manual', 'one_push', 'on', 'off'		Sets the sharpness value of the camera. If the used camera does not support sharpness adjustment, H_ERR_FGPARAM is returned (or an empty tuple in the corresponding call to get_framegrabber_param, respectively).
	'shutter'		min ... max, 'auto', 'manual', 'one_push', 'on', 'off'		Sets the shutter value of the camera. If the used camera does not support shutter adjustment, H_ERR_FGPARAM is returned (or an empty tuple in the corresponding call to get_framegrabber_param, respectively).
	'trigger_mode'		0, 1, 2, 3 'shutter', 'pulse_width', 'n_pulses', 'shutter_n_frames'		Sets the trigger mode either as integer as defined in the IEEE 1394-based digital camera specification or as corresponding string: 0, 'shutter': Integration time is described by shutter parameter. 1, 'pulse_width': Integration time is equal to the pulse width of the external trigger input. 2, 'n_pulses': Integration stops after n external trigger events, see also 'trigger_parameter'. 3, 'shutter_n_frames': Camera will issue trigger internally and cycle time is a multiple of the cycle time of the fastest frame rate (n>0!), 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 ('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_signal'		'rising', 'falling'		Sets the trigger polarity and distinguishes whereas the rising or falling edge triggers the camera. Be aware of the settings your camera supplies.
	'ub'		min ... max, 'auto', 'manual', 'one_push', 'on', 'off'		Sets the ub value of the camera. If the used camera does not support ub adjustment, H_ERR_FGPARAM is returned (or an empty tuple in the corresponding call to get_framegrabber_param, respectively).
	'video_format'		0 ... 2		Sets the desired video format determined in the IEEE 1394-based digital camera specification. Be aware of the settings your camera supplies. Default: the default camera setting.
	'video_gain'		min ... max, 'auto', 'manual', 'one_push', 'on', 'off'		Sets the gain value of the camera. If the used camera does not support gain adjustment, H_ERR_FGPARAM is returned (or an empty tuple in the corresponding call to get_framegrabber_param, respectively).
	'video_mode'		0 ... 7		Sets the desired video mode determined in the IEEE 1394-based digital camera specification. Be aware of the settings your camera supplies. Default: the default camera setting.
	'volatile'		'enable', 'disable'		Monochrome cameras only (the color space has to be set on 'default' or 'gray', and the camera has to deliver gray images. In the volatile mode the frame grabber interface 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 while calling grab_image or grab_image_async. Thus, you can only process one image while you grab another image. Older images are invalid! Default: 'disable'.
	'vr'		min ... max, 'auto', 'manual', 'one_push', 'on', 'off'		Sets the vr value of the camera. If the used camera does not support vr adjustment, H_ERR_FGPARAM is returned (or an empty tuple in the corresponding call to get_framegrabber_param, respectively).
	'zoom'		min ... max, 'auto', 'manual', 'one_push', 'on', 'off'		Sets the zoom value of the camera. If the used camera does not support zoom adjustment, H_ERR_FGPARAM is returned (or an empty tuple in the corresponding call to get_framegrabber_param, respectively).
	'do_reset_camera'		---		Resets the camera and puts its configurations to the manufacturer's default settings.
	'do_set_iso_channel_state'		'create', 'delete', 'start', 'stop'		Gives control to the state of the isochronous transmission channel (see also the 'iso_channel_state' parameter of the get_framegrabber_param operator): 'create' initializes the DMA engine and allocates the frame ring buffer on your host computer; 'delete' frees the engine and the buffer. 'start' initializes the isochronous channel (and the DMA engine, if closed) and reserves the necessary bandwidth on the IEEE-1394 bus; 'stop' frees the isochronous channel on the IEEE-1394 bus.

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.

	'brightness_range'		[min (long), max (long), step (long), default (long), <'auto'>, <'manual'>, <'on_off'>, <'one_push'>]		Possible range for brightness. If the used camera supports optional values like automatic brightness adjustment, these values are given in the return tuple starting with the fifth element; otherwise it contains only four elements. If the camera does not support brightness adjustment, an empty tuple is returned.
	'camera_model'		model_name (string)		Returns the name of the camera model.
	'camera_vendor'		vendor_name (string)		Returns the name of the camera vendor.
	'exposure_range'		[min (long), max (long), step (long), default (long), <'auto'>, <'manual'>, <'on_off'>, <'one_push'>]		Possible range for exposure. If the used camera supports optional values like automatic exposure adjustment, these values are given in the return tuple starting with the fifth element; otherwise it contains only four elements. If the camera does not support exposure adjustment, an empty tuple is returned.
	'focus_range'		[min (long), max (long), step (long), default (long), <'auto'>, <'manual'>, <'on_off'>, <'one_push'>]		Possible range for focus. If the used camera supports optional values like automatic focus adjustment, these values are given in the return tuple starting with the fifth element; otherwise it contains only four elements. If the camera does not support focus adjustment, an empty tuple is returned.
	'gamma_range'		[min (long), max (long), step (long), default (long), <'auto'>, <'manual'>, <'on_off'>, <'one_push'>]		Possible range for gamma. If the used camera supports optional values like automatic gamma adjustment, these values are given in the return tuple starting with the fifth element; otherwise it contains only four elements. If the camera does not support gamma adjustment, an empty tuple is returned.
	'hue_range'		[min (long), max (long), step (long), default (long), <'auto'>, <'manual'>, <'on_off'>, <'one_push'>]		Possible range for hue. If the used camera supports optional values like automatic hue adjustment, these values are given in the return tuple starting with the fifth element; otherwise it contains only four elements. If the camera does not support hue adjustment, an empty tuple is returned.
	'iris_range'		[min (long), max (long), step (long), default (long), <'auto'>, <'manual'>, <'on_off'>, <'one_push'>]		Possible range for iris. If the used camera supports optional values like automatic iris adjustment, these values are given in the return tuple starting with the fifth element; otherwise it contains only four elements. If the camera does not support iris adjustment, an empty tuple is returned.
	'iso_channel_state'		state (string)		Returns the state of the isochronous channel: The channel is 'running' if the isochronous channel on the IEEE-1394 bus is initialized; it is 'opened' if the DMA engine is initialized and the frame ring buffer allocated but if the channel is not running; else, the channel is 'closed'.
	'revision'		revision (string)		The revision number of the HALCON Fire-i interface.
	'saturation_range'		[min (long), max (long), step (long), default (long), <'auto'>, <'manual'>, <'on_off'>, <'one_push'>]		Possible range for saturation. If the used camera supports optional values like automatic saturation adjustment, these values are given in the return tuple starting with the fifth element; otherwise it contains only four elements. If the camera does not support saturation adjustment, an empty tuple is returned.
	'sharpness_range'		[min (long), max (long), step (long), default (long), <'auto'>, <'manual'>, <'on_off'>, <'one_push'>]		Possible range for sharpness. If the used camera supports optional values like automatic sharpness adjustment, these values are given in the return tuple starting with the fifth element; otherwise it contains only four elements. If the camera does not support sharpness adjustment, an empty tuple is returned.
	'shutter_range'		[min (long), max (long), step (long), default (long), <'auto'>, <'manual'>, <'on_off'>, <'one_push'>]		Possible range for shutter. If the used camera supports optional values like automatic shutter adjustment, these values are given in the return tuple starting with the fifth element; otherwise it contains only four elements. If the camera does not support shutter adjustment, an empty tuple is returned.
	'ub_range'		[min (long), max (long), step (long), default (long), <'auto'>, <'manual'>, <'on_off'>, <'one_push'>]		Possible range for ub. If the used camera supports optional values like automatic ub adjustment, these values are given in the return tuple starting with the fifth element; otherwise it contains only four elements. If the camera does not support ub adjustment, an empty tuple is returned.
	'unit_software_version'		number (string)		Returns the camera's software version.
	'video_gain_range'		[min (long), max (long), step (long), default (long), <'auto'>, <'manual'>, <'on_off'>, <'one_push'>]		Possible range for gain. If the used camera supports optional values like automatic gain adjustment, these values are given in the return tuple starting with the fifth element; otherwise it contains only four elements. If the camera does not support gain adjustment, an empty tuple is returned.
	'vr_range'		[min (long), max (long), step (long), default (long), <'auto'>, <'manual'>, <'on_off'>, <'one_push'>]		Possible range for vr. If the used camera supports optional values like automatic vr adjustment, these values are given in the return tuple starting with the fifth element; otherwise it contains only four elements. If the camera does not support vr adjustment, an empty tuple is returned.
	'zoom_range'		[min (long), max (long), step (long), default (long), <'auto'>, <'manual'>, <'on_off'>, <'one_push'>]		Possible range for zoom. If the used camera supports optional values like automatic zoom adjustment, these values are given in the return tuple starting with the fifth element; otherwise it contains only four elements. If the camera does not support zoom adjustment, an empty tuple is returned.

• Revision 2.4 (Oct 5, 2002):
  
  • Parameter 'gain' renamed into 'video_gain' due to the naming conflict with the standard gain parameter of the HALCON frame grabber integration interface.
  • New parameters with suffix '_range' added for get_framegrabber_param. These parameters are especially helpful when working with ActivVisionTools 2.1. The corresponding old '_min_value' and '_max_value' parameters are still usable for backward compatibility reasons.
  • get_framegrabber_param returns now an empty tuple as value if the requested parameter is not supported by the used camera.
  • get_framegrabber_param('trigger_mode') returns now the current trigger mode as a string instead of an integer.
  • get_framegrabber_param returns no longer the string values "auto" or "off" for the standard IEEE-1394 parameters like 'brightness'. Instead the actual integer value is given.
• Revision 2.3 (Jul 4, 2002):
  
  • Adaptation to Unibrain Fire-i API 2.0.
  • Support of FireBoard400-OHCI boards.
  • Support of multiple cameras and boards.
  • Specification of video format, video mode and frame rate via the CameraType parameter of open_framegrabber.
  • Addressing cameras on all available busses by their GUID using the Device parameter of open_framegrabber. The addressing via the CameraType parameter is still supported for backward compatibility reasons.
  • New parameters 'num_buffers', 'iso_speed', 'iso_channel_state' and 'do_set_iso_channel_state' for set/get_framegrabber_param.
  • Some parameter names for set/get_framegrabber_param have been renamed (the old names are still available for backward compatibility).
• Revision 2.2 (Jun 19, 2001):
  
  • Addressing cameras on the bus by their GUID using the CameraType parameter of open_framegrabber.
  • 'video_settings' parameter for set_framegrabber_param and get_framegrabber_param added.
  • HALCON 6.1 version of the interface (included in HALCON 6.1 CD).
• Revision 2.1 (Nov 8, 2000):
  
  • Query board information by info_framegrabber.
  • Color space transformation got faster.
• Revision 2.0 (Sep 10, 2000):
  
  • HALCON 6.0 version of the interface.
  • First official release.