HALCON 7.0 Frame Grabber Interface for Basler BCAM 1394 Driver

This page provides the documentation of the HALCON frame grabber interface HFGBcam1394.dll for the Basler BCAM 1394 driver. With this interface you can acquire images from Basler's IEEE 1394 cameras via any OHCI compliant IEEE 1394 adapter cards. Registered customers can download the latest revision of this interface from the MVTec WWW server.

Revision: 2.4

System Requirements

• Intel compatible PC with Windows 2000 (Service Pack 3) or Windows XP (Service Pack 1) and OHCI compliant IEEE 1394 adapter.
• Successfully installed OHCI compliant IEEE 1394 driver.
• Successfully installed BCAM 1394 Driver (version 1.8 only!).
• HALCON frame grabber interface HFGBcam1394.dll or parHFGBcam1394.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.

Features

• Supports all DCAM-compatible Basler IEEE 1394 cameras.
• Synchronous and asynchronous grabbing.
• External camera triggering.
• Supports Format_7 to enable Basler-specific features like image cropping and binning.
• Software control of a variety of camera parameters.
• Test images.

Limitations

• Support of Basler IEEE 1394 cameras only.
• grab_region and grab_region_async not supported.
• No shading correction.
• No LUTs.

Description

Parameters for open_framegrabber():

	Name		'BCAM1394'		The name of the HALCON frame grabber interface.
	HorizontalResolution		---		Ignored.
	VerticalResolution		---		Ignored.
	ImageWidth		-1, 0, min ... max		Sets the width of the desired image part if Format_7 is specified in CameraType. The passed value gets rounded to fit the step with restriction of this parameter (which depends on the camera). min equals the step width whereas max equals the maximum image width. -1 means to adopt the camera setting, 0 means to specify the maximum image width. Default: -1.
	ImageHeight		-1, 0, min ... max		Sets the height of the desired image part if Format_7 is specified in CameraType. The passed value gets rounded to fit the step with restriction of this parameter (which depends on the camera). min equals the step width whereas max equals the maximum image height. -1 means to adopt the camera setting 0 means to specify the maximum image width. Default: -1.
	StartRow		-1, 0 ... 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 fit the step with restriction of this parameter (which depends on the camera). max equals the maximum image height minus the step width. -1 means to adopt the camera setting. Default: -1.
	StartColumn		-1, 0 ... max		The column coordinate of the upper left pixel of the desired image part if Format_7 is specified in CameraType. The passed value gets rounded to fit the step with restriction of this parameter (which depends on the camera). max equals the maximum image width minus the step width. -1 means to adopt the camera setting. Default: -1.
	Field		---		Ignored.
	BitsPerChannel		---		Ignored.
	ColorSpace		---		Ignored.
	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,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. 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. 'default' means to adopt the supplied video settings of the camera. Default: 'default'.
	Device		'device name', 'default'		The name of the camera device. You can obtain the device names of all available cameras by the 'info_boards' parameter of the info_framegrabber operator. If 'default' is specified the Port parameter is used to specify the desired camera. Default: 'default'.
	Port		0, 1, ...		The number of the camera as found on the IEEE 1394 bus if the parameter Device is set to 'default'. 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. 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

	'allocate_resources'		'true', 'false'		Allocates ('true') or frees ('false') the resources of the isochronuous 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 and grab_image frees them again after the image has been grabbed.
	'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' (if supported) and the brightness value is set. See get_framegrabber_param to yield min, max and the supported modes.
	'bytes_per_packet'		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 'allocate_resources' and 'camea_type'). The passed value gets rounded to fit the step width restriction of this parameter. The value specifies the bandwidth of the isochronuous channel and therefore influences the frame rate of the camera. -1 specifies the maximal bytes per packet.
	'camera_sync_mode'		'sync', 'async'		Sets the synchronization mode of the camera. This parameter is only supported if no resources are allocated (see also 'allocate_resources'). 'sync' sets the camera to free run mode with the next grab. Following image requests will be grabbed synchronously to the camera frame cycle. In contrast, 'async' stops the free running camera with the next grab and allows to grab the images independent of any camera cycle as known as asynchronous (software) trigger. Note: The 'sync' mode yields best performance as regards frame rate. Default: 'sync'.
	'camera_type'		'format:mode:fps'		Specify the desired video settings 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 or 1.875,3.75,7.5,15.0,30.0,60.0, respectively), separated by colons. When setting video format to Format_7 the frame rate parameter is ignored and the packet size for isochronuous transmission is maximized for the set image size instead.
	'external_trigger'		'true', 'false'		Enables/disables the trigger mode. Be aware of the settings your camera supplies.
	'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. 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. -1 means to abort never. Default: 5000.
	'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. See get_framegrabbe_param to yield min, max and the supported modes.
	'image_height'		-1, min ... max		Sets the height of the image. This parameter is only supported if no resources are allocated and Format_7 is set (see also 'allocate_resources' and 'camera_type'). The passed value gets rounded to fit the step width restriction of this parameter. min is equal to the step width value and max to the maximal image height. -1 specifies the maximal image height.
	'image_width'		-1, min ... max		Sets the width of the image. This parameter is only supported if no resources are allocated and Format_7 is set (see also 'allocate_resources' and 'camera_type'). The passed value gets rounded to fit the step width restriction of this parameter. min is equal to the step width value and max to the maximal image width. -1 specifies the maximal image width.
	'image_part'		[row1, col1, row2, col2]		Specifies the upper left (row1, col1) and lower right (row2, col2) corner of the rectangular image part. This parameter is only supported if no resources are allocated and Format_7 is set (see also 'allocate_resources' and 'camera_type'). The passed values get rounded due to the step widths of the 'start_row', 'start_column', 'image_width' and 'image_height' parameters. The range of the row1 and col1 values is identical to the value range of the 'start_row' and 'start_column' parameters. The range of the row2 and col2 values is similar to the value range of the 'image_height' and 'image_width' parameters but decremented by one. Passing -1 for row2 or col2 specifies the maximum possible image row/column.
	'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. See get_framegrabber_param to yield min, max and the supported modes.
	'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. See get_framegrabber_param to yield min, max and the supported modes.
	'start_column'		0 ... max		Sets the column coordinate of the upper left corner of the image part. This parameter is only supported if no resources are allocated and Format_7 is set (see also 'camera_type'). The passed value gets rounded to fit the step width restriction of this parameter. max is equal to the maximal image width minus the step width.
	'start_row'		0 ... max		Sets the row coordinate of the upper left corner of the image part. This parameter is only supported if no resources are allocated and Format_7 is set (see also 'camera_type'). The passed value gets rounded to fit the step width restriction of this parameter. max is equal to the maximal image height minus the step height.
	'test_image'		'disabled', 'mode_1', 'mode_2', ... 'mode_7'		Sets the test image mode of the Basler camera. 'disabled' disables the test image mode and enables normal image acquisition. 'mode_1' to 'mode_7' enable the desired Basler-specific test image mode and succeeding grabs will return the selected test image. The supported test mode values can be requested by the 'test_image_values' parameter of the get_framegrabber_param operator. For further information see also your camera manual.
	'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', '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 component of the white balance is set. See get_framegrabber_param to yield min, max and the supported modes.
	'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. See get_framegrabber_param to yield min, max and the supported modes.
	'volatile'		'enable', 'disable'		Grayscale 8bpp only! In the volatile mode the two 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'		min ... max, '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 component of the white balance 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.

	'brightness_range'		[min (long), max (long), step_width (long), current_value (long), <'auto'> (string), <'manual'> (string), <'one_push'> (string), <'off'> (string)]		Returns the supported values of the 'brightness' parameter. The first four elements contain the minimal and maximal brightness value, the step width, and the current gain value. Furthermore, the returned tuple contains the strings of the supported brightness modes.
	'bytes_per_packet_range'		[min (long), max (long), step_width (long), current_value (long)]		Returns the supported range of the 'bytes_per_packet' parameter. The four elements contain the minimal and maximal settable packet size, the step width, and the current value of the packet size.
	'camera_firmware_version'		version (string)		Returns the version number of the camera firmware.
	'camera_guid'		guid (string)		Returns the Global Unified Identifier (GUID) of the camera). The returned string fits the format '0x<hexadecimal vendor code>-<decimal camera number>'.
	'camera_model'		model_name (string)		Returns the name of the camera model.
	'camera_type_values'		[<list of supported types> (string)]		The supported values of the 'camera_type' parameter. The returned camera types specify all the video settings supported by the camera, containing video format, video mode, and frame rate. The returned type strings fit the format 'format:mode:fps'. In case of Format_7 the frame rate value is of no relevance and -1 is returned instead.
	'camera_vendor'		vendor_name (string)		Returns the name of the camera vendor.
	'dcam_version'		version (string)		Returns the version number of underlying 1394-based digital camera specification.
	'driver_version'		version (string)		Returns the version number of the software driver.
	'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.
	'gamma_range'		[min (long), max (long), step_width (long), current_value (long), <'auto'> (string), <'manual'> (string), <'one_push'> (string), <'off'> (string)]		Returns the supported values of the 'gamma' parameter. The first four elements contain the minimal and maximal gamma value, the step width, and the current gamma value. Furthermore, the returned tuple contains the strings of the supported gamma modes.
	'hue_range'		[min (long), max (long), step_width (long), current_value (long), <'auto'> (string), <'manual'> (string), <'one_push'> (string), <'off'> (string)]		Returns the supported values of the 'hue' parameter. The first four elements contain the minimal and maximal hue value, the step width, and the current hue value. Furthermore, the returned tuple contains the strings of the supported hue modes.
	'image_height_range'		[min (long), max (long), step_width (long), current_value (long)]		Returns the supported range of the 'image_height' parameter. The four elements contain the minimal and maximal settable image height, the step width, and the current image height value.
	'image_width_range'		[min (long), max (long), step_width (long), current_value (long)]		Returns the supported range of the 'image_width' parameter. The four elements contain the minimal and maximal settable image width, the step width, and the current image width value.
	'revision'		revision (string)		The revision number of the HALCON BCAM1394 interface.
	'saturation_range'		[min (long), max (long), step_width (long), current_value (long), <'auto'> (string), <'manual'> (string), <'one_push'> (string), <'off'> (string)]		Returns the supported values of the 'saturation' parameter. The first four elements contain the minimal and maximal saturation value, the step width, and the current saturation value. Furthermore, the returned tuple contains the strings of the supported saturation modes.
	'shutter_range'		[min (long), max (long), step_width (long), current_value (long), <'auto'> (string), <'manual'> (string), <'one_push'> (string), <'off'> (string)]		Returns the supported values of the 'shutter' parameter. The first four elements contain the minimal and maximal shutter value, the step width and the current shutter value. Furthermore, the returned tuple contains the strings of the supported shutter modes.
	'start_column_range'		[min (long), max (long), step_width (long), current_value (long)]		Returns the supported range of the 'start_column' parameter. The four elements contain the minimal and maximal settable value, the step width, and the current value of the start column of the image part.
	'start_row_range'		[min (long), max (long), step_width (long), current_value (long)]		Returns the supported range of the 'start_row' parameter. The four elements contain the minimal and maximal settable value, the step width and the current value of the start row of the image part.
	'trigger_mode_values'		[<list of supported modes> (string)]		The supported values of the 'trigger_mode' parameter. For the meaning of the returned strings of the supported trigger modes see the description of the 'trigger_mode' parameter.
	'test_image_values'		[<list of supported modes> (string)]		The supported values of the 'test_image' parameter. For the meaning of the returned strings of the supported test image modes see the description of the 'test_image' parameter.
	'ub_range'		[min (long), max (long), step_width (long), current_value (long), <'auto'> (string), <'manual'> (string), <'one_push'> (string), <'off'> (string)]		Returns the supported values of the 'ub' parameter, a component to control the white balance of a color camera. The first four elements contain the minimal and maximal ub value, the step width, and the current ub value. Furthermore, the returned tuple contains the strings of the supported white balance modes.
	'video_gain_range'		[min (long), max (long), step_width (long), current_value (long), <'auto'> (string), <'manual'> (string), <'one_push'> (string), <'off'> (string)]		Returns the supported values of the 'video_gain' parameter. The first four elements contain the minimal and maximal gain value, the step width, and the current gain value. Furthermore, the returned tuple contains a strings of the supported gain modes.
	'video_resolution'		resolution (string)		Returns the decoded video format and video mode setting within the string format '<width>x<height>, <color_mode>' according to Table 1.2.2 of the 1394-based digital camera specification.
	'vr_range'		[min (long), max (long), step_width (long), current_value (long), <'auto'> (string), <'manual'> (string), <'one_push'> (string), <'off'> (string)]		Returns the supported values of the 'vr' parameter, a component to control the white balance of a color camera. The first four elements contain the minimal and maximal vr value, the step width, and the current vr value. Furthermore, the returned tuple contains the strings of the supported white balance modes.

Release Notes

• Revision 2.4 (Jul 27, 2005):
  
  • Speed-up for acquisition of RGB images (avoiding cache alignment failures when converting the interleaved image data into HALCON image objects).
• Revision 2.3 (Dec 10, 2004):
  
  • The query types 'bits_per_channel', 'camera_type', 'color_space', 'device', 'external_trigger', 'field', and 'port' for info_framegrabber provide now specific value lists for the corresponding parameters in open_framegrabber.
  • Added missing description of parameter 'volatile'.
• Revision 2.2 (Sep 9, 2004):
  
  • Adaptation to BCAM 1394 driver version 1.8.
• Revision 2.1 (Nov 21, 2003):
  
  • HALCON 7.0 version of the interface (included in HALCON 7.0 CD).
  • Adaptation to BCAM 1394 driver version 1.7.
• Revision 2.0 (Mar 21, 2003):
  
  • First official release.