HALCON 5.2 frame grabber interface for BitFlow RoadRunner boards

This document provides some information about the HALCON frame grabber interface RoadRunner.dll for the BitFlow frame grabber board RoadRunner. Registered customers can download the latest revision of this interface from the MVTec WWW server.

Revision: 1.14

• Intel compatible PC with Windows NT 4.0 (Service Pack 4).
• Successfully installed RoadRunner driver BitFlow.sys (BitFlow SDK version 2.50). If you do not have this driver version, please contact BitFlow or the vendor from which you bought the frame grabber board.
• BitFlow DLLs R2D.dll and BFD.dll.
  These DLLs must be in your search path %PATH%. If you do not have these DLLs, please contact BitFlow or the vendor from which you bought the frame grabber board.
• HALCON frame grabber interface RoadRunner.dll (revision 1.14 or higher).
  If you have properly installed the interface, RoadRunner.dll should reside in bin\i486-nt4 within the HALCON base directory %HALCONROOT% you have chosen during the installation of HALCON.

• Multiple frame grabber boards.
• Multiple compatible cameras per board (port switching).
• Synchronous and asynchronous grabbing.
• External trigger (with software override of the camera configuration file).
• Up to 40 frame buffers (e.g., for volatile and/or continuous grabbing).
• Completely asynchronous grabbing of up to 40 images (with or without external triggering; see parameter 'continuous_grabbing' and the corresponding section below).
• Support of multiple digital cameras based on the BitFlow camera configuration files.
• (Partial) software control of the number of bits per pixel (with software override of the camera configuration file).
• Support of the digital output lines of the RoadRunner board.
• Special 'long_frames' mode designed for supporting line scan cameras.
• Simultaneous grabbing from multiple synchronized cameras (see parameter 'num_simultaneous_cameras' the corresponding section below).
• Writing and reading of LUTs.

• Only one frame grabber instance per frame grabber board (however, multiple compatible cameras can be accessed using port switching).
• No subsampling or cropping of image parts through the HALCON interface. This feature is supported through the use of camera files.
• grab_region and grab_region_async not supported.

Parameters for open_framegrabber():

	Name	'RoadRunner'	The name of the HALCON frame grabber interface.
	FGWidth	1, width	The desired image resolution. Use '1' for full resolution or the corresponding absolute value (depending on your camera). Default: 1.
	FGHeight	1, height	The desired image resolution. Use '1' for full resolution or the corresponding absolute value (depending on your camera). Default: 1.
	Width	0	The width of the desired image part ('0' stands for the complete image). Default: 0.
	Height	0	The height of the desired image part ('0' stands for the complete image). Default: 0.
	StartRow	0	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	The column coordinate of the upper left pixel within the desired image part ('0' obviously results in delivering the complete image). Default: 0.
	Field	---	Ignored.
	Bits	-1, 8, 10, 12, 24	The number of bits per pixel. By specifying the default '-1' the corresponding setting of the camera configuration file is used. Default: -1.
	ColorSpace	---	Ignored.
	Gain	---	Ignored.
	ExternalTrigger	'true', 'false'	Activate/deactivate external triggering. Note that this setting overrides the corresponding setup in the camera configuration file. Default: 'false'.
	Generic	'default', 'file'	The generic parameter is used to specify the camera configuration file (e.g., 'BfSynth256E1.cam' for the synthetic test image). If you specify 'default' the first camera you have set with SysReg is used.
	Device	'0', '1', '2', ...	The number of the frame grabber board (passed as a string!). Default: '0'.
	Port	number	The number attached to the desired camera via the BitFlow configuration program SysReg (starting with 0 for the first camera). Only evaluated in case the Generic parameter has been set to 'default'. Default: 0.
	LineIn	---	Ignored.

Parameters for set_framegrabber_param():

	'continuous_grabbing'	'enable', 'disable'	Activate or deactivate 'continuous grabbing'. For details, please see the corresponding section below. Default: 'disable'.
	'grab_timeout'	milliseconds	Specify the desired timeout (milliseconds passed as an integer) for aborting a pending grab (the default value is specified in the camera configuration file).
	'num_buffers'	2 - 40	Specify the number of frame buffers used by the interface. Default: 2.
	'out:X'	'high', 'low'	Specify the desired state of one of the digital output lines (with X = 0, 1, or 3). The default depends on the board settings.
	'overwrite_method'	'abort', 'holdoff', 'ignore'	Specify how the interface should handle siutuations where the external trigger is received faster than the images are read by the application in continuos grabbing mode (see also the corresponding section below). Default: 'abort'.
	'port'	number	Switch to the camera with the specified number (attached via the BitFlow configuration program SysReg - starting with 0 for the first camera). Using this port switching you can access multiple cameras with one RoadRunner board (see below).
	'show_internal_errors'	'true', 'false'	Specify whether the frame grabber interface should pop up an alert box in case of an error or not. If you use your own error management, we recommend to switch off the internal error display. In this mode only the error code is returned by the frame grabber operators, but the interface itself is "silent" (important for inline applications etc.). Otherwise, the user has to click on one of the buttons in the error dialog. On the other side, activated internal error display will result in more detailed and specific error messages for trouble shooting. Default: 'true'.
	'trigger_timeout'	milliseconds	Specify the desired timeout (milliseconds passed as an integer) for aborting a pending grab when waiting for an external trigger (a default of 60 seconds is set during open_framegrabber()).
	'volatile'	'enable', 'disable'	Grayscale only. In the volatile mode the two 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 and again as a side-effect. Thus, you can only process one image while you grab another image. Older images are invalid! Default: 'false'.
	'long_frames'	'enable', 'disable'	Activate/deactivate the grabbing of long frames (see corresponding section below). Note: long frame mode cannot be used in conjunction with continuous or simultaneous grabbing. Default: 'disable'.
	'long_frame_size'	nrlines	The total number of lines that should be acquired in long frame mode (see corresponding section below). You should not be grabbing an image when you call this operator. Note: this parameter must be set before long frame mode is enabled.
	'qtab_part'	number	In long frame mode only, this parameter defines the number of parts in which QTABs are downloaded to the RoadRunner board (see corresponding section below). Default: 20.
	'num_simultaneous_cameras'	number	This parameter sets the number of cameras from which the board grabs images simultaneously (see corresponding section below). Default: 1.

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 frame grabber interface RoadRunner.dll.

It is possible to connect more than one camera to a RoadRunner board. You will need specific camera configuration files to do this, which have to be installed in your system with the BitFlow configuration program SysReg (please contact BitFlow for details). SysReg attaches a number to each camera (starting with 0). This number is used as port parameter in the HALCON interface. To access a specific camera, you have to specify the corresponding port. This setting can be changed dynamically using the operator set_framegrabber_param() (port switching). However, in this case the used cameras must be compatible, that is of the same type or with similar features (if in doubt please contact your local vendor or BitFlow).

With this mechanism you can access multiple cameras with one frame grabber handle. Note that a pending asynchronous job is aborted when changing the port. Therefore, it does not make much sense to use grab_image_async() in combination with port switching. Please note further the simple HDevelop example program roadrunner_2ports.dev you will find in %HALCONROOT%\examples\hdevelop\Image\Framegrabber.

The continuous grabbing mode is used for completely asynchronous grabbing with or without external triggering: If you activate this mode via set_framegrabber_param(FGHandle,'continuous_grabbing','enable') images will be acquired (with each trigger if triggering is enabled) and stored in N buffers in a cyclic way without any additional explicit software trigger like grab_image(). Thus, your HALCON application can process other data without loosing a frame. This is, for example, very useful for the acquisition of images under specific lightning conditions which are triggered by a sequence controller with a fixed timing. In continuous grabbing mode both grab_image() and grab_image_async() simply will return the next frame (or wait if it has not been acquired so far). Note that with the standard asynchronous grabbing there can only be one grab job pending. Thus, you can only acquire one frame in parallel to processing, e.g., the previous frame. Now you can acquire N frames in parallel with N between 2 and 40 (as specified with the parameter 'num_buffers').

In this continuos grabbing mode you might encounter situations where the images are acquired at a faster rate than they are read by your application. Thus, the N buffers will fill up and finally you will encounter a buffer that was not read so far, but should be overwritten by the next frame. You can decide what to do in this situation via the parameter 'overwrite_method':

• 'abort': Before overwriting any frame, abort the acquisition. This is the most safe method. The main user will be able to process any good buffers still in the system before an error is returned.
• 'holdoff': Hold off acquisition until a buffer is free. This will result in loosing one or more frames, but allows the processing and acquisition to continue.
• 'ignore': Ignore the problem and overwrite the buffer. Thus, some of the older frames that already have been acquired (but not processed so far) will be lost.

Note that it is not possible to use both the long frame mode and the continuous grabbing mode at the same time.

Long frame mode is used to grab images with a line scan camera that are larger than the QTAB hardware on the RoadRunner board allows, e.g., 5000x6000 images. To do so, the image is broken up vertically into chunks that fit into the QTABs, e.g., 5000x1000 chunks. The number of chunks must be an even number, e.g., 6 in the above example. To use long frame mode, you will need a special camera file for your line scan camera. First, YSIZE in the camera file must be equal to the chunk size (1000 in the above example). Furthermore, the CTAB entries VSTART and VEND (=VSTOP) must be set for the long frame size. For the image of height 6000 in the above example, segment 1 of VSTART must be 1 with a size of 1, while segment 2 of VSTART and segment 1 of VEND must be set to 6001 (=0x1771) with size 1. If you have set up the camera file correctly, you must first tell the HALCON interface the height of the long frames by calling set_framegrabber_param(FGHandle,'long_frame_size', nrlines), where nrlines is 6000 in the above example. Then, long frame mode must be enabled by calling set_framegrabber_param(FGHandle,'long_frames','enable'). After these calls, you can grab long frames in the usual manner with grab_image() or grab_image_async().

On some systems, PCI transfer from the RoadRunner board may interfere with the downloads of the QTABs (which are necessary for every chunk of the long frame). This may lead to `garbled' images or failed grabs. In this case, the parameter 'qtab_part' can be used to eliminate these problems. On slower PCs, this parameter should be set to higher values while on faster PCs it can be set to lower values than the default value of 20.

It is possible to grab images simultaneously from multiple (up to 4) synchronized cameras. To do so, you will need a special camera file that sets up the board to transfer the n images to memory as one big image with the individual images stacked atop each other. For example, if you want to grab two images of size 640x480 simultaneously, your camera file must be set up to transfer an image of size 640x960 to memory, where the image of the first camera is contained in the first 480 lines of the large image and the image of the second camera is contained in the second 480 lines of the large image. In your application, you need to call set_framegrabber_param(FGHandle,'num_simultaneous_cameras', n), where n is the number of simultaneous cameras, e.g., 2 in the above example. With this, the HALCON interface will return a multi-channel image with each grab, e.g., a two-channel image in the above example. The individual images can be obtained by calling decompose2(), decompose3(), or decompose4(), depending on how many images are grabbed simultanously.

Note that it is not possible to use both the long frame mode and the simultaneous grabbing mode at the same time. Furthermore, simultaneous grabbing is not supported in 24 bit per pixel mode.

• Revision 1.14 (October 15, 2001):
  
  • Adaptation to the new BitFlow SDK 2.50.
• Revision 1.13 (December 5, 1999):
  
  • Adaptation to the new BitFlow SDK 1.263. Older revisions are no longer supported.
  • Support of simultaneous grabbing from multiple synchronized cameras (not combinable with long frame mode and 24 bits per pixel).
  • Support of writing and reading of LUTs.
  • Support of continuous grabbing without external triggers.
• Revision 1.12 (August 12, 1999):
  
  • Adaptation to the new BitFlow SDK 1.261. Older revisions (especially 1.20 and 1.26) are no longer supported.
  • Bugfix in query 'parameter' in info_framegrabber().
  • Improvements in handling color images and long frames.
• Revision 1.10 (March 25, 1999):
  
  • HALCON 5.2 version of the interface (included in the HALCON 5.2 CD).
  • Up to 40 frame buffers in the interface ('num_buffers').
  • Support of long frames (new parameters 'long_frame_size' and 'long_frames').
• Revision 1.9 (September 10, 1998):
  
  • Port switching (to access multiple cameras).
  • Elimination of timing problems that caused timeouts or stalled the acquisition occasionally.
• Revision 1.8 (July 20, 1998):
  
  • Continuous grabbing mode ('continuous_grabbing', 'overwrite_method').
  • Up to 20 frame buffers in the interface ('num_buffers').
  • Parameter 'trigger_timeout'.
  • First release of the DEC Alpha version.
• Revision 1.7 (June 1998):
  
  • Control of digital output lines (see parameter 'out:X').
• Revision 1.6 (May 28, 1998):
  
  • External triggering (independent of the setting in the camera configuration file).
  • Adjustable timeout (see parameter 'grab_timeout').
  • Support of 24 bit color images.
  • Overriding of the original bit depth specified in the camera configuration file (if possible).
• Revision 1.5 (May 1998):
  
  • Elimination of the 10 and 12 bit grabbing and visualization problem.
  • Elimination of the asynchronous grabbing error.
  • Improvement of the error messages.
• Revision 1.4 (April 1998):
  
  • Performance boost by a factor of 200.
• Revision 1.1 (March 1998):
  
  • HALCON 5.1 version of the interface.