HALCON 6.0 Frame Grabber Interface for Opteon Boards

This page provides the documentation of the HALCON frame grabber interface HFGOpteon.dll for the Opteon boards distributed by VISICS. Registered customers can download the latest revision of this interface from the MVTec WWW server.

Revision: 2.5

• Intel compatible PC with Windows NT 4.0 (Service Pack 4), Windows 2000 or Windows XP.
• Successfully installed Opteon driver v3.0 (including the DLL depict.dll v3.0).
  This DLL must be within your search path %PATH%. If you do not have this DLL, please contact Opteon or the vendor from which you bought the board.
• HALCON frame grabber interface HFGOpteon.dll or parHFGOpteon.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 Opteon Classic, USB 2.0, and Ethernet cameras.
• Supports multiple boards and multiple camera types.
• Synchronous and asynchronous grabbing.
• Variable image period for synchronous grabs.
• External trigger.
• Cropping of image parts.
• Exposure, gain, and offset control.
• Supports Bayer pattern single-chip colour.
• Supports alternate queued acquisition mode (see description below).

• Currently only support of 8 bpp and Bayer-pattern colour cameras
• grab_region and grab_region_async not supported.

Parameters for open_framegrabber():

	Name	'Opteon'	The name of the HALCON frame grabber interface.
	HorizontalResolution	1	The desired image resolution. Use '1' for full resolution. Default: 1.
	VerticalResolution	1	The desired image resolution. Use '1' for full resolution. Default: 1.
	ImageWidth	0, width	The width of the desired image part ('0' stands for the complete image). Default: 0.
	ImageHeight	0, height	The height of the desired image part ('0' stands for the complete image). Default: 0.
	StartRow	0, row	The row coordinate of the upper left pixel within the desired image part ('0' obviously results in delivering the complete image). Default: 0.
	StartColumn	0, column	The column coordinate of the upper left pixel within the desired image part ('0' obviously results in delivering the complete image). Default: 0.
	Field	'progressive'	Fixed. Default: 'progressive'.
	BitsPerChannel	8	Fixed. Default: 8.
	ColorSpace	'gray', 'rgb'	Choosing 'rgb' indicates a Bayer pattern colour camera. Default: 'gray'.
	Gain	0.0 - 100.0	The desired video gain: A floating point number between 0.0 and 100.0. Default: 1.0.
	ExternalTrigger	'true', 'false'	Activate/deactivate external triggering. Default: 'false'.
	CameraType	'classic', 'usb', 'ethernet'	The Opteon camera platform to use. Default: 'classic'.
	Device	'0', '1', ... '9'	The board number on the specified platform (passed as a string!). For Classic cameras this value can be in the range ['0', '9']. For USB 2.0 cameras, it must be '0'. For Ethernet cameras it can be in the range ['0', '3']. Default: '0'.
	Port	num	The camera number on the given platform and board number. For Classic cameras num can be in the range [0, 3]. For USB 2.0 cameras, num can be in the range [0, 9]. For Ethernet cameras, num must be set to the camera's serial number. Default: 0.
	LineIn	---	Ignored.

Parameters for set_framegrabber_param():

	'image_width'	width	The width of the desired image part.
	'image_height'	height	The height of the desired image part.
	'start_row'	row	The start row of the desired image part.
	'start_column'	column	The start column of the desired image part.
	'gain'	0.0 - 100.0	The desired video gain: A floating point number between 0.0 and 100.0.
	'offset'	-255.0 ... 255.0	The desired video offset: A floating point number between -255.0 and 255.0.
	'exposure'	usec	Set the exposure time in microseconds for primary acquisition (see Opteon documentation for details).
	'timebase'	usec	Sets the period for synchronous acquisitions in 'timebase' trigger mode (see Opteon documentation for details).
	'pipelined'	'true', 'false'	Turns pipelined acquisitions on ('true') or off ('false') (see Opteon documentation for details).
	'external_trigger'	'true', 'false'	Activate/deactivate external triggering.
	'trigger_mode'	'externala', 'externalb', 'immediate', 'master', 'slave', 'timebase'	Set desired trigger mode.
	'trigger_signal'	'rising', 'falling'	Sets whether trigger occurs on a rising or falling edge.
	'grab_timeout'	msec	Sets the acquisition timeout. If an acquisition does not complete within the specified timeout period, the HALCON interface returns with an timeout error. Default: 5000.

Parameters for get_framegrabber_param():

Additional parameters supported by get_framegrabber_param only. Note that all parameters supported by set_framegrabber_param can also be accessed by get_framegrabber_param.

	'revision'	revision	The revision number of the HALCON Opteon interface.

Description of alternate 'Queued' acquisition mode:

In order to support the advanced capabilities of Opteon cameras and the Depict camera interface, the HALCON Opteon interface supports an alternate 'queued' acquisition mode. In this mode, each camera has an acquisition queue. Calls to the HALCON grab_image function place an acquisition with the current camera settings onto the camera's queue and then return immediately. Each queued acquisition has an associated 'Wait Object' with which the user can wait for the acquisition to complete. The Wait Object also stores a timestamp for the acquisition that can be compared to those for other acquisitions to determine precise relative timing. Image data is placed directly into the HALCON image returned from the grab_image call, so the user must wait for the acquisition to be complete before performing any operations on the image, see also the example HDevelop script opteon_queued.dev in %HALCONROOT%/examples/hdevelop/Image/Framegrabber.

Queued acquisitions are controlled through a set of frame grabber parameters accessed using the standard set_framegrabber_param and get_framegrabber_param HALCON calls. The names and uses of these parameters are documented below; they follow a different naming convention to differentiate them from standard parameters. Note that many of the parameters perform different operations depending on whether a set_framegrabber_param or a get_framegrabber_param operation is being performed.

The 'GrabWaitObject' and 'TriggerWaitObject' properties are particularly important. They control whether the standard HALCON grab functionality or the alternate grab mode is used. If both of these parameters are set to 0, standard HALCON grabs will be performed. If either is set to a non-zero Wait Object handle (see below), the alternate acquisition mode will be enabled.

	'WaitObjectFactory'	get	Creates a new Wait Object and returns an integer-valued object handle that addresses the object. This handle can then be passed to other parameters that require a Wait Object handle.
		set	Destroys the Wait Object associated with the handle passed in.
	'GrabWaitObject'	get / set	Handle of the Wait Object to be used as the 'acquisition complete' object for the acquisition queued by the next grab_image call. This object will become ready when the acquisition is complete. Either this parameter or the 'TriggerWaitObject' must be set to a value other than 0 to activate the queued acquisition mode. If both property values are 0, standard HALCON grab functionality will be used. It is important to note that every acquisition that is in the queue at the same time must have an unique Wait Object. Therefore, if five acquisitions are to be queued (with five successive grab_image calls made before any of the acquisitions completes), the user must have called 'WaitObjectFactory' five times beforehand, stored the unique object handles returned, and set this property with the appropriate handle value before calling grab_image to queue each acquisition.
	'TriggerWaitObject'	get / set	Handle of the Wait Object to be used as the 'acquisition triggered' object for the acquisition queued by the next grab_image call. This object will become ready when the acquisition is triggered and exposure begins. Either this parameter or the 'GrabWaitObject' must be set to a value other than 0 to activate the queued acquisition mode. If both property values are 0, standard HALCON grab functionality will be used.
	'WaitObjectWait'	set	Specifies the handle for a Wait Object to be used in a subsequent 'get' operation (see below).
		get	Waits on the Wait Object specified by a prior 'set' operation. If this Wait Object was used in the 'GrabWaitObject' parameter for an acquisition, it will be ready when the acquisition is complete. If it was used in the 'TriggerWaitObject' parameter for an acquisition, it will be ready when the acquisition is triggered. If the object is not ready within the time period specified by the 'WaitObjectTime' property, this parameter returns a string value of 'timeout'. If the object is ready within the time period, it returns a string value of 'success'.
	'WaitObjectTime'	get / set	Controls the length of time, in milliseconds, that the 'WaitObjectWait' property will wait (on a 'get' operation, see property description) before returning.
	'WaitObjectDiff'	set	Specifies the handle for a Wait Object to be used in a subsequent 'get' operation (see below).
		get	Returns the timestamp difference, in milliseconds, between the last two Wait Objects passed (by handle) to the 'set' operation for this parameter. If the second object's timestamp was later than the first, the difference is positive; otherwise it is negative. If the 'set' operation has been called less than twice, an error is generated.
	'ClearQueue'	set	When set to 'true', clears the camera's acquisition queue. This cancels any previously queued acquisitions, including any made using the standard HALCON functionality. This call would typically be used to cancel an externally triggered acquisition if a program detected that the trigger was not likely to arrive.
		get	Not defined.

• Revision 2.5 (March 10th, 2003):
  
  • Bugfix in accessing classic and ethernet camera systems.
• Revision 2.4 (January 28th, 2003):
  
  • Adaptation to latest Depict 3.0 driver: Internally the parameters 'gain' and 'offset' now are represented as floats and have different value ranges.
• Revision 2.3 (April 11th, 2002):
  
  • Added support for USB 2.0 and Ethernet cameras.
  • Adaptation to Depict 3.0 driver.
• Revision 2.2 (April 9th, 2002):
  
  • Added support for Bayer pattern colour cameras.
  • Added 'offset', 'timebase', 'pipelined', 'trigger_signal', 'grab_timeout', and 'ClearQueue' parameters.
  • Documented alternate 'Queued' acquisition mode.
  • Canceling pending asynchronous grabs when calling grab_image_start() or grab_image().
• Revision 2.1 (February 14th, 2001):
  
  • Bugfix in grab_image_async(): When called without preceeding grab_image_start(), wait for the first grabbed image.
  • Bugfix in grab_image_async(): Always copy image into HALCON image structure to ensure database persistence.
  • Evaluation of the Device parameter during open_framegrabber().
• Revision 2.0 (November 16th, 2000):
  
  • First official release (included in the HALCON 6.0 CD).