HALCON 8.0 Image Acquisition Interface for Basler BCAM 1394 Driver

This page provides the documentation of the HALCON BCAM1394 image acquisition interface 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: 3.1

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.9 only!).
• HALCON image acquisition interface HacqBcam1394.dll or parHacqBcam1394.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.

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_data and grab_data_async not supported.
• No shading correction.
• No LUTs.

Description

Parameters for open_framegrabber():

	Name		'BCAM1394'		The name of the HALCON image acquisition 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.
	Generic		---		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. 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'].

	'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_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.
	'revision'		revision (string)		The revision number of the HALCON BCAM1394 interface.
	'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.

Release Notes

• Revision 3.1 (Mar 10, 2009):
  • Added read-only parameters with postfix '_description', '_range', and '_values' to enable the easy parameterization via a generic graphical user interface.
• Revision 3.0 (Jun 28, 2007):
  • HALCON 8.0 version of the interface (legacy only).
• Revision 2.5 (Oct 20, 2006):
  • Adaptation to BCAM 1394 driver version 1.9.
• Revision 2.4 (Jul 27, 2005):
  • HALCON 7.1 version of the interface (included in HALCON 7.1 CD).
  • 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.