Image Acquisition Interface for BitFlow Boards

This page provides the documentation of the HALCON BitFlow interface for the BitFlow frame grabber boards Alta-AN, Karbon-CL, Karbon-CXP, Cyton-CXP, Neon-CL, RoadRunner, RoadRunner-CL, R3, and R3-CL. Please note, that the RoadRunner-CL, R3, R3-CL boards are only supported by Windows 32-Bit. Although Raven, R64, and R64e-CL boards are still supported by this interface they are no more actively tested as they are out of production. Registered customers can download the latest revision of this interface from the MVTec WWW server.

• Intel compatible PC with Windows 7 (32-bit or 64-bit) or newer that is also supported by the vendor-specific SDK.
• Successfully installed BitFlow driver BitFlow.sys (BitFlow SDK version 6.30).
  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, Gn2.dll, CiD.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 image acquisition interface hAcqBitFlow.dll or hAcqBitFlowxl.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.

Only when installing or updating the interface manually follow these steps:

• Windows: Extract the archive containing the interface files to the HALCON base directory %HALCONROOT% (Note: Administrator privileges may be required for this step). Additionally, you have to move the interface examples to the directory %HALCONEXAMPLES% manually.

• 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 1000 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 analog and 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.
• Support of line scan cameras.
• Writing and reading of LUTs.
• Dynamically changing the frame size of the grabbed image.
• Support of start/stop trigger mode (for line scan cameras connected to RoadRunner or RoadRunner CL boards).
• Serial communication with Camera Link cameras.
• Support of user-specific callback function.

• Only one image acquisition 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.

There may exist additional read-only parameters with the following postfixes:

• '_description': These parameters provide the tool-tip of the corresponding parameter as a string.
• '_range': These parameters provide the minimum, maximum, step width, and default values for the corresponding integer or float parameter as a tuple with 4 elements, e.g., get_framegrabber_param(.., 'Shutter_range', ..) will return the output tuple [min, max, step, default].
• '_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'].

All these postfixed parameter names are not returned when calling info_framegrabber(.., 'parameters', ..) and are used to enable the easy parameterization via a generic graphical user interface, particularly the HDevelop Image Acquisition Assistant.

Set the lookup-table values if LUTs are supported by the used board. Note that also the number of 'bits_per_channel' is important for the number of input values.

Query the lookup-table values.

All actually supported callback types of a specific image acquisition device can be queried by calling get_framegrabber_param with the parameter 'available_callback_types'. Once the callback is registered, on every occurrence of the underlying event (e.g., the notification that the exposure has finished) the specified callback function will be called. If the callback function is set to NULL, the corresponding callback will be unregistered.

The signature of the callback function is Herror (__stdcall *HAcqCallback)(void *AcqHandle, void *Context, void *UserContext) and uses the following parameters:

• AcqHandle Acquisition handle of the corresponding image acquisition instance.
• Context Optional context data of the specific callback. In the BitFlow interface, this parameter is not used, i.e., Context is set to NULL.
• UserContext User context as set via set_framegrabber_callback.

Using user-callback functions
Note that the execution time of a user-specific callback function should always be as short as possible since during the execution of a callback function the handling of further internal callbacks might be blocked. This can be achieved by removing the current processing from the user-specific callback function to a separate thread that is controlled via signals or events.

This interface supports device specific events via the operators set_framegrabber_callback and get_framegrabber_callback. For more information see set_framegrabber_callback.

Starts a new asynchronous grab. See also grab_image_start.

grab_image starts a new synchronous grab. See also grab_image. Note that the interface converts the image from the device to the desired image format specified by the parameters 'image_width', 'image_height', 'start_row', 'start_column', 'bits_per_channel', and 'color_space'.

grab_image_async returns an image and starts the next asynchronous grab. See also grab_image_async. Note that the interface converts the image from the device to the desired image format specified by the parameters 'image_width', 'image_height', 'start_row', 'start_column', 'bits_per_channel', and 'color_space'.

Not supported by this interface.

Not supported by this interface.

This operator closes the device. See also close_framegrabber.

It is possible to connect more than one camera to a BitFlow 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 bitflow_2ports.dev you will find in %HALCONROOT%\examples\hdevelop\Image\Acquisition.

The continuous grabbing mode is used for completely asynchronous grabbing with or without external triggering: If you activate this mode via set_framegrabber_param(..., '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 losing a frame. This is, for example, very useful for the acquisition of images under specific lighting 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 1000 (as specified with the parameter 'num_buffers'). Note that you have to specify the desired number of buffers via set_framegrabber_param(...'num_buffers'...) before enabling the continuous grabbing mode!

In this continuous 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 safest method. The main user will be able to process any good buffers still in the system before an error is returned.
• '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.

For this interface there are the following examples available:

• bitflow_2boards.hdev - Grabbing images with two BitFlow frame grabber boards.
• bitflow_2ports.hdev - Shows the usage of two cameras and port switching.
• bitflow.hdev - Benchmark.
• bitflow_cont.hdev - Parameterization of a BitFlow frame grabber board.
• bitflow_change_size.hdev - Set different image sizes.
• bitflow_cl_serial_usage.hdev - Shows the usage of serial communication of a BitFlow frame grabber board.
• bitflow_cont_async_oneshot.hdev - Parameterization of a BitFlow frame grabber board.
• bitflow_cxp_register_poke_peek.hdev - Read/write registers of a CXP BitFlow frame grabber board.
• bitflow_lut.hdev - Setting a look-up table.
• bitflow_open_by_switch_connector.hdev - Opening the board by sitch and connector.
• bitflow_register_poke_peek.hdev - Read/write registers of a CL BitFlow frame grabber board.
• bitflow_simple.hdev - A simple example to show the usage of the interface.
• bitflow_simple_sw_trigger.hdev - Shows the usage of software trigger.
• bitflow_version.hdev - Shows all versions.

For this interface there is also a further C++ Visual Studio Project to demonstrate the usage of the operators get_framegrabber_callback and set_framegrabber_callback. Please check the directory %HALCONEXAMPLES%\cpp\console\vs2005\. If you prefer building the example via the console, please check the following folder %HALCONEXAMPLES%\cpp\console\. With a Linux OS please use $HALCONEXAMPLES/cpp/console/.

For this interface there is also a further C# Visual Studio Project to demonstrate the usage of the operators get_framegrabber_callback and set_framegrabber_callback. Please check the directory %HALCONEXAMPLES%\cpp\console\vs2005\.

• Revision 13.0.3 (Oct 23, 2018):
  • The BitFlow SDK has been updated to 6.30.
  • The technical dependency from the HALCON Library has been removed.
  • When querying the 'camera_type' parameter if the camera file path contained UNICODE characters it was not displayed correctly. This problem has been fixed.
  • The parameter 'ring_buffer_stop_margin' has been added.
• Revision 13.0.2 (Oct 20, 2017):
  • Renamed the parameter 'do_abort_capture' to 'do_abort_grab'. The parameter 'do_abort_capture' will continue to work for compatibility but should be avoided.
  • Information about the use of modes with Gen2 boards has been added to the CameraType parameter in open_framegrabber.
• Revision 13.0.1 (Oct 28, 2016):
  • HALCON 13 version of the interface.
• Revision 6.2 (Sep 28, 2016):
  • The BitFlow SDK has been updated to 6.20.
  • The parameter 'num_simultaneous_cameras' is no longer supported. For backward compatibility it is still available, but you get an error message, if you want to use it.
  • The parameters 'do_comm_read_int' and 'do_comm_read_str' have been renamed to 'comm_read_int' and 'comm_read_str'. For backward compatibility the old names still work.
  • Setting an empty value in set_framegrabber_param led to a crash. This problem has been fixed.
  • The example 'bitflow_2simultaneous' has been removed.
  • The examples 'bitflow_2boards' and 'bitflow_cont' have been adapted.
  • The examples 'bitflow_change_size', 'bitflow_cl_serial_usage', 'bitflow_cont_async_oneshot', 'bitflow_cxp_register_poke_peek', 'bitflow_open_by_switch_connector', 'bitflow_register_poke_peek', 'bitflow_simple_sw_trigger', and 'bitflow_version' have been added.
• Revision 6.1 (Oct 20, 2015):
  • The BitFlow SDK has been updated to 6.00.
  • New board types Karbon-CXP and Cyton-CXP were added.
  • New parameters 'num_buffers_overwritten', 'sdk_revision', 'sdk_build', 'firmware_file_name', 'firmware_directory' were added.
  • The use of the serial communication led to a crash. This problem has been fixed.
  • This documentation did not list all available callback types. This problem has been fixed.
  • The legacy Raven and R64 and R64e-CL frame grabber families has been removed from the documentation.
• Revision 6.0 (Oct 31, 2014):
  • HALCON 12 version of the interface.
• Revision 5.2 (Aug 28, 2013):
  • Adapted to BitFlow SDK 5.70.
  • Added parameters 'cc:x', 'continuous_grab_timeout', 'register_peek', 'register_poke', 'register_index_peek', 'register_index_poke', and 'register_index_get'.
  • Adapted implementation of the serial communication.
  • Added functionality to handle 'exposure_end' callbacks.
  • Added hint for support of older frame grabbers to section 'General' in this document.
• Revision 5.1 (Oct 29, 2012):
  • Fixed bug in grab_image_start that could lead to a deadlock situation in combination with succeeding asynchronous image acquisition operators.
• Revision 5.0 (May 15, 2012):
  • HALCON 11 version of the interface (included in HALCON 11 DVD).
  • Adapted to BitFlow SDK 5.60.
  • Add new parameters 'next_buffer_acquired_abs', 'wait_frame_exposure' and 'wait_frame_exposure_timeout'.
  • Fixed thread safety problem in grab_image and grab_image_async that could occur if a pending grab was aborted via the 'do_abort_grab' parameter of set_framegrabber_param.
• Revision 4.2 (Aug 27, 2010):
  • Adapted to BitFlow SDK 5.30.
  • Added parameters 'dma_direction', 'lut', 'serial_write_delay', 'start_column', and 'start_row'.
  • Improved internal thread handling.
  • Removed parameter 'show_internal_errors'; please use set_system('do_low_error', ...) instead.
  • HALCON 10 version of the interface (included in HALCON 10 DVD).
• Revision 4.1 (Jan 22, 2010):
  • Add functionality to handle 'transfer_end' callbacks.
• Revision 4.0 (Dec 1, 2008):
  • HALCON 9.0 version of the interface (included in HALCON 9.0 DVD).
  • Bug fix in parameters 'do_comm_param' and 'ctab_fill'.
  • Bug fix in get_framegrabber_param for the parameters 'overflow_thread' and 'hardware_exception_thread' to ensure consistency with set_framegrabber_param.
• Revision 3.3 (Apr 22, 2008):
  • Adaptation to BitFlow SDK 5.00 with support of the new Alta-AN, Karbon-CL, and Neon-CL boards.
  • New parameters 'start_async_after_grab_async', 'software_trigger', 'do_force_trigger', 'do_abort_capture', 'gport', 'encoder_scan_step', 'serial_timeout', 'serial_baudrate', 'serial_message', 'serial_terminate_code', 'serial_message_buf_size', 'ctab_fill', 'camera_connected', 'do_flush_buffers', and 'num_free_buffers'.
  • Default value of parameter 'overwrite_method' changed to 'abort'.
  • Default value of parameter 'show_internal_errors' changed to 'false'.
  • Added read-only parameters with postfix '_description', '_range', and '_values' to enable the easy parameterization via a generic graphical user interface.
• Revision 3.2 (Feb 27, 2008):
  • New parameter 'do_flush_buffers'.
• Revision 3.1 (Jan 30, 2008):
  • Bug fix concerning the general serial communication with Camera Link cameras (correct use of clserbit.lib instead of clallserial.lib).
• Revision 3.0 (May 15, 2007):
  • HALCON 8.0 version of the interface (included in HALCON 8.0 DVD).
  • Bug fix in parameter 'do_comm_param'.
• Revision 2.12 (Feb 02, 2007):
  • Support of Windows XP x64 for R64 and R64e boards (using BitFlow SDK version 4.80).
• Revision 2.11 (Aug 16, 2006):
  • Support of 3x 10bpp and 3x 12bpp RGB cameras.
  • Bug fix for 16bpp images.
• Revision 2.10 (Jan 18, 2006):
  • Adaptation to the new BitFlow SDK 4.50 with support of the new R64e boards.
  • New parameters 'next_buffer_acquired' and 'next_buffer_returned'.
  • Updated to Camera Link version 1.1 compliance.
• Revision 2.9 (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.8 (Nov 24, 2004):
  • The serial communication with Camera Link cameras now supports the reading and writing of NULL characters. Thus, the parameter 'do_comm_write' accepts also a tuple of integer values. Furthermore, the parameter 'do_comm_read' has been split into the two new parameters 'comm_read_str' and 'comm_read_int' to allow the reading of strings as well as the reading of integer tuples.
  • The maximum number of used frame buffers has been increased to 1000.
  • 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.
• Revision 2.7 (Aug 30, 2004):
  • New parameters 'overflow_thread', 'hardware_exception_thread', 'overflow_count', and 'hardware_exception_count' to reset acquisition in continuous grabbing mode when there is a hardware or overflow exception.
  • New parameters 'do_comm_param', 'do_comm_open', 'do_comm_close', 'do_comm_write', 'do_comm_read', 'do_comm_flush', and 'read_buf_size' to control the serial communication with Camera Link cameras.
• Revision 2.6 (Jul 25, 2003):
  • HALCON 7.0 version of the interface (included in HALCON 7.0 CD).
  • Adaptation to the new BitFlow SDK 4.00 with support of the new R64 boards.
• Revision 2.5 (Nov 19, 2002):
  • New parameter 'in:X' to query the state of the digital input lines (GPIN).
• Revision 2.4 (Jul 4, 2002):
  • Adaptation to the new BitFlow SDK 3.00 with support of the new R3 and R3-CL boards.
  • New parameter 'resnap' to enable a second grab in case of an overflow.
• Revision 2.3 (Aug 30, 2001):
  • HALCON 6.1 version of the interface (included in HALCON 6.1 CD).
  • Bug fix in open_framegrabber together with multi processor machines.
  • Bug fix forces correct LUT setting with model 11 RoadRunner boards.
• Revision 2.2 (Jun 8, 2001):
  • Adaptation to the new BitFlow SDK 2.50. Older revisions are no longer supported!
  • Support of start/stop trigger mode (for line scan cameras connected to RoadRunner or RoadRunner CL boards).
  • Dynamically changing the frame size of the grabbed image via set_framegrabber_param.
  • Default value of parameter 'overwrite_method' changed from 'abort' to 'holdoff'.
• Revision 2.1 (Nov 24, 2000):
  • Bug fix in overriding the BitsPerChannel parameter during open_framegrabber
  • Automatic enabling of GPOUT when set_framegrabber_param(...'out:X'...) is called (regardless of the settings in the camera file).
• Revision 2.0 (Nov 14, 2000):
  • Adaptation to the HALCON 6.0 image acquisition interface.
• Revision 1.2 (Nov 10, 2000):
  • Bug fix in masking the LUT when using a 10 bit camera.
  • Bug fix in continuous grabbing mode together with external triggering.
  • Bug fix in cleaning up after an unsuccessful call of open_framegrabber
  • Bug fix in switching between connected cameras.
• Revision 1.1 (Oct 27, 2000):
  • Adaptation to the new BitFlow SDK 2.10. Older revisions are no longer supported!
  • In contrast to the old HALCON RoadRunner and HALCON Raven interfaces the special long frame mode is no longer necessary. Therefore, the parameters 'long_frames', 'long_frame_size', and 'qtab_part' are no longer supported.