HALCON 6.0 Frame Grabber Interface for Allied Vision Technologies/Intek FirePackage Driver

This page provides the documentation of the HALCON frame grabber interface HFGFirePackage.dll for the Allied Vision Technologies/Intek FirePackage driver. With this interface you can acquire images from IEEE1394 cameras via any IEEE1394 adapter cards (PCILynx or OHCI). Registered customers can download the latest revision of this interface from the MVTec WWW server.

Revision: 2.2

• Intel compatible PC with Windows NT 4.0 (Service Pack 5), Windows 2000 or Windows XP and IEEE1394 adapter card (PCILynx or OHCI).
• Successfully installed intek Fireview driver (version 0,5,0,0 or higher). The corresponding demo executable FireView.exe should be at least version 1.3b.
• FIREPACKAGE DLL Firectrl.dll (version 1,8,0,1 or higher).
  This DLL (and an appropriate license file in the same directory!) must be within your search path %PATH%. If you do not have this DLL, please contact Allied Vision Technologies or the vendor from which you bought the FirePackage driver.
• HALCON frame grabber interface HFGFirePackage.dll or parHFGFirePackage.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 all DCAM-compatible webcams and industrial cameras, such as SONY DFW-V300, DFW-V500, DFW-VL500, DFW-X700, DFW-SX900, XCD-X700, and XCD-SX900, or Basler A302 and others.
• 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.

• Supports up to three cameras per board and up to four boards.
• Bus reset is not supported.
• grab_region and grab_region_async not supported.
• No LUTs.
• No cropping of image parts.

Parameters for open_framegrabber():

	Name	'FirePackage'	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	'0', '1', ...	The number of the used IEEE1394 adapter card (passed as a string!). Default: '0'.
	Port	0, 1, ...	The number of the camera found on the IEEE1394 bus. Default: 0 (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 video settings of the camera. 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. Note that you have to call set_framegrabber_param(...,'do_set_video_settings',...) before the new settings take effect.
	'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).
	'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. Note that you have to call set_framegrabber_param(...,'do_set_video_settings',...) before the new settings take effect.
	'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. Note that you have to call set_framegrabber_param(...,'do_set_video_settings',...) before the new settings take effect.
	'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_load_from_memory_channel'	0 ... 15	Loads camera settings from the specified memory channel (1 - 15) or reloads factory settings (0). Be aware of the settings your camera supplies.
	'do_reset_camera'	---	Resets the camera and puts its configurations to the manufacturer's default settings.
	'do_save_to_memory_channel'	1 ... 15	Stores the current camera settings to the specified memory channel. Be aware of the settings your camera supplies.
	'do_set_video_settings'	---	Calculates payload and number of iso-packets, and reconfigures the FirePackage driver. Has to be called after changing 'video_format', 'video_mode' and 'frame_rate'.

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.
	'revision'	revision (string)	The revision number of the HALCON FirePackage 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.
	'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.2 (Oct 7, 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.
  • set_framegrabber_param returns now an error (H_ERR_FGPARAM) if the selected parameter is not supported by the used camera.
  • 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.
• Revision 2.1 (Aug 19, 2002):
  
  • Support of OHCI IEEE-1394 adapter cards.
  • Support of up to 8 isochronous channels and 4 cameras per board.
• Revision 2.0 (Feb 25, 2002):
  
  • First official release.