Dokumentation
Image Acquisition Interface for BitFlow Boards
Interface: | BitFlow |
Revision: | 13.0.3 |
Date: | 2018-10-23 |
- General
- System Requirements
- Installation
- Features
- Limitations
- Parameters for info_framegrabber
- Parameters for open_framegrabber
- Parameters for set_framegrabber_param
- Parameters for get_framegrabber_param
- Operator set_framegrabber_lut
- Operator get_framegrabber_lut
- Operator set_framegrabber_callback
- Operator get_framegrabber_callback
- Operator grab_image_start
- Operator grab_image
- Operator grab_image_async
- Operator grab_data
- Operator grab_data_async
- Operator close_framegrabber
- Multiple Cameras (Port Switching)
- Continuous Grabbing
- HDevelop Examples
- C++ Examples
- C# Examples
- Release Notes
General
System Requirements
- 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.
Installation
- 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.
Features
- 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.
Limitations
- 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.
Parameters for info_framegrabber
Parameter | Value List | Type | Kind | Description |
---|---|---|---|---|
'bits_per_channel' | [8, 10, 12] | integer | pre-defined | Values for bits per channel. |
'camera_type' | ['CAMFILE:', 'cam;r64;rcl;rvc;anlg;bfml;kcxp', '<camera_path>', 'default'] | string | pre-defined | Syntax for camera configuration file and default value. |
'color_space' | ['gray', 'rgb'] | string | pre-defined | Values for color space. |
'defaults' | [1, 1, 0, 0, 0, 0, 'progressive', -1, 'gray', -1.0, 'false', 'default', 'default', 0, 1] | mixed | pre-defined | Default values for open_framegrabber. |
'device' | ['RoadRunner:0', 'RoadRunner:1', 'RoadRunner:2', 'RoadRunner:3', 'Gn2:0', 'Gn2:1', 'Gn2:2', 'Gn2:3', 'default'] | string | dynamic | Pre-defined list of possible device IDs. |
'external_trigger' | ['false', 'true'] | string | pre-defined | Values for the external trigger. |
'field' | [] | Unused. | ||
'general' | [] | string | pre-defined | Information about the HALCON BitFlow interface. |
'generic' | [] | Unsupported query. | ||
'horizontal_resolution' | 1 | integer | pre-defined | Value list for horizontal resolution. |
'image_height' | [] | Unsupported query. | ||
'image_width' | [] | Unsupported query. | ||
'info_boards' | ['device:<device_id>'] | string | dynamic | Returns a list of installed BitFlow boards. |
'parameters' | ['<parameters>'] | string | pre-defined | Pre-defined parameters of the HALCON interface. |
'parameters_readonly' | ['<parameters>'] | string | pre-defined | Pre-defined read-only parameters of the HALCON interface. |
'parameters_writeonly' | ['<parameters>'] | string | pre-defined | Pre-defined write-only parameters of the HALCON interface. |
'port' | [0, 1, 2, 3] | integer | pre-defined | Pre-defined list of possible port numbers. |
'revision' | '<revision>' | string | pre-defined | Revision number of the BitFlow interface. |
'start_column' | [] | Unsupported query. | ||
'start_row' | [] | Unsupported query. | ||
'vertical_resolution' | 1 | integer | pre-defined | Value list for vertical resolution. |
Parameters for open_framegrabber
Parameter | Values | Default | Type | Description |
---|---|---|---|---|
Name | 'BitFlow' | string | Name of the HALCON interface. | |
HorizontalResolution | 1, <width> | 1 | integer | Desired image resolution. Use '1' for full resolution or the corresponding absolute value (depending on your camera). |
VerticalResolution | 1, <height> | 1 | integer | Desired image resolution. Use '1' for full resolution or the corresponding absolute value (depending on your camera). |
ImageWidth | 0 | 0 | integer | Width of the desired image part ('0' stands for the complete image). |
ImageHeight | 0 | 0 | integer | Height of the desired image part ('0' stands for the complete image). |
StartRow | 0 | 0 | integer | Row coordinate of the upper left pixel within the desired image part. |
StartColumn | 0 | 0 | integer | Column coordinate of the upper left pixel within the desired image part. |
Field | --- | Ignored. | ||
BitsPerChannel | -1, 8, 10, 12 | -1 | integer | Number of bits per channel. By specifying the default '-1' the corresponding setting of the camera configuration file is used. |
ColorSpace | 'gray', 'rgb' | 'gray' | string | Desired color space of the HALCON image. If BitsPerChannel is set to -1, the value is ignored and overwritten by the settings of the camera configuration file. |
Generic | --- | Ignored. | ||
ExternalTrigger | 'false', 'true' | 'false' | string | Status of the external trigger. |
CameraType | '<file>', 'default' | 'default' | string | This parameter is used to specify the camera configuration file (e.g., 'BfSynth256E1.cam' (RoadRunner) or 'Generic-Synthetic-1024x1024-1T.r64' (Neon) for a synthetic test image). If you specify 'default' the first camera you have set with SysReg is used. For Gen2 boards you can also provide a mode when passing the configuration file using 'mode@camfile.bfml' where 'mode' is one of the modes from the BFML file. If a mode is not provided with the configuration file then the default mode will be used. |
Device | '<BoardType>:<nr>', 'default' | 'default' | string | Type ('Gen2' or 'RoadRunner') and number ('0', '1', '2' ...) of the frame grabber board (passed as one string!), e.g.,
'RoadRunner:1' or 'Gn2:0'. Note that R3 boards are treated in the way as RoadRunner boards and that Alta, Karbon and Neon boards are treated in the way as the legacy R64 boards. If you specify 'default' the interface automatically selects the first board. |
Port | <port> | 0 | integer | 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 CameraType parameter has been set to 'default'. |
LineIn | --- | Ignored. |
Parameters for set_framegrabber_param
Parameter | Values | Default | Type | Description |
---|---|---|---|---|
'cc:X' | <command> | integer | Low CPU usage write to the CCx_CON register | |
'continuous_grab_timeout' | <milliseconds> | 5000 | integer | Specifies the desired timeout (milliseconds) for aborting an acquisition when in continuous grabbing mode. This timeout is used only by the internal grabbing thread, it must see an image within this amount of time. If not, it will abort acquisition. This timeout is not used by the grab_image() functions. If -1 is specified, the timeout is set to INFINITE. |
'continuous_grabbing' | 'disable', 'enable' | 'disable' | string | Activates or deactivates 'continuous grabbing'. For details, please see the corresponding section below. |
'ctab_fill' | ['index <index>: num_entries <num>: mask <mask>: value <value>'] | string | Ctab_fill parameter writes a masked CTAB fill value to the Camera Control Table. The following parameters must be specified:
Note that this parameter is a write-only parameter! Example: set_framegrabber_param(..., 'ctab_fill', 'index 0:num_entries 256:mask 0xffff:value 0x0000') |
|
'dma_direction' | 'bottom-up', 'top-down' | 'top-down' | string | Read-out direction of the image. |
'do_abort_grab' | --- | Aborts the current image acquisition. | ||
'do_comm_close' | --- | Closes the comm port. | ||
'do_comm_flush' | --- | Discards any bytes that are available in the input buffer of the comm port. | ||
'do_comm_open' | --- | Opens and initializes the comm port for use on the board. The comm port will always be opened with 9600 baud, 8 data bits, no parity, and 1 stop bit. The default timeout is 1 second. | ||
'do_comm_param' | '<string>' | string | Parameters for serial communication, separated by colons. The following parameters can be specified:
|
|
'do_comm_write' | <message> | mixed | Writes message to comm port. Note that message can either be a string value or a tuple of integers. The latter case also allows the writing of NULL characters. Examples: set_framegrabber_param(..., 'do_comm_write', 'TR="2"\r\n'), set_framegrabber_param(..., 'do_comm_write', [0, 127, 128]) | |
'do_flush_buffers' | --- | Discards all image buffers in the output buffer queue in continuous grabbing mode. | ||
'do_force_trigger' | --- | Generate a software trigger signal for the camera. | ||
'encoder_scan_step' | 0 ... 1023 | integer | Encoder divider value. | |
'grab_timeout' | <milliseconds> | 5000 | integer | Desired timeout (milliseconds) for aborting a pending grab. If -1 is specified, the timeout is set to INFINITE. |
'hardware_exception_thread' | 'disable', 'enable' | 'disable' | string | Start/stop hardware exception thread to reset acquisition in continuous grabbing mode when there is a hardware exception. |
'image_height' | <height> | integer | Dynamically change the current image height of the grabbed image. This feature is limited to use with only free run camera files (see also the comments to CiAqFrameSize in the BitFlow SDK Reference). | |
'image_width' | <width> | integer | Dynamically change the current image width of the grabbed image. This value has to be a multiple of 4 and is limited to use with only free run camera files (see also the comments to CiAqFrameSize in the BitFlow SDK Reference). | |
'lut' | 'disable', 'enable' | 'disable' | string | State of the lookup table. |
'out:X' | 'high', 'low' | string | State of one of the digital output lines (with X = 0, 1, or 2 for RoadRunner/R3-DIF family; RoadRunner/R3 CL family). The default depends on the board settings. | |
'overflow_thread' | 'disable', 'enable' | 'disable' | string | Start/stop overflow thread to reset acquisition in continuous grabbing mode when there is an overflow exception. |
'overwrite_method' | 'abort', 'ignore' | 'abort' | string | Specify how the interface should handle situations where the external trigger is received faster than the images are read by the application in continuous grabbing mode (see also the corresponding section below). |
'port' | <port> | integer | 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 frame grabber board (see below). | |
'read_buf_size' | 0...32768 | 0 | integer | Number of bytes to read from the read buffer of an open comm port. This will most likely be set before each read, unless the message from the camera is always the same size. |
'register_index_poke:xx' | <value> | integer | Writes the given value of to register or bitfield index. The index is obtained by calling register_index_get. This function uses very little CPU and can be used during CPU intensive operations | |
'register_poke:xx' | <value> | integer | Writes the given value to a register or bitfield. The bitfield names and the purpose are described in the hardware reference manual for the frame grabber being used. Note that this function is somewhat CPU intensive and should not be used during intensive processing. | |
'resnap' | 'false', 'true' | 'false' | string | Specifies whether to reset the DMA engine and to try a second snap in case of an overflow. Note that in continuous grabbing mode you can use the parameter 'overflow_thread' to reset acquisition when there is an overflow exception. |
'ring_buffer_stop_margin' | 1 | integer | This parameter controls the 'protection zone' used to look ahead when a buffer is about to be overwritten. When 'continuous_grabbing' is enable, the frame grabber acquires automatically into a circular set of buffers. There is a thread that watches acquisition and makes sure that buffers which have not yet been processed by the user's program are not overwritten by new images. If a buffers is about to be overwritten, acquisition is aborted. If the frame rate is high and/or the CPU is very busy, the thread might not get serviced in time to protect unprocessed buffers. By increasing the size, the overwrite protection can still be maintained under these conditions. This parameters only is used with 'continuous_grabbing' is enabled. | |
'serial_baudrate' | <baud> | 9600 | integer | Baud rate for serial communication. |
'serial_message' | '<string>' | string | Sends the string via the serial interface, see also 'do_comm_write'. | |
'serial_message_buf_size' | 1 ... 32767 | 1024 | integer | Maximum buffer size for receive strings via 'serial_message'. |
'serial_terminate_code' | 0...255 | LF(0x0A) | integer | Termination character of the receive string. If you call get_framegrabber_param with the parameter 'serial_message', the receive process is finished by receiving this character. |
'serial_timeout' | <milliseconds> | 1000 | integer | Timeout for serial communication (in milliseconds). |
'serial_write_delay' | <milliseconds> | 0 | integer | Timeout in milliseconds for serial write operations. |
'software_trigger' | 'disable', 'enable' | 'disable' | string | Enables or disables the software trigger mode (shot grabbing). Note that the software trigger mode can only be used with a one shot camera file. |
'start_async_after_grab_async' | 'disable', 'enable' | 'enable' | string | By default a new asynchronous grab command is automatically given to the acquisition device at the end of grab_image_async. If the parameter 'start_async_after_grab_async' is set to 'disable', this new grab command is omitted. |
'start_column' | 0 ... <max> | integer | Column coordinate of the upper left pixel within the desired image part. | |
'start_row' | 0 ... <max> | integer | Row coordinate of the upper left pixel within the desired image part. | |
'trigger_timeout' | <milliseconds> | 60000 | integer | Timeout (milliseconds passed as an integer) for aborting a pending grab when waiting for an external trigger. |
'volatile' | 'disable', 'enable' | 'disable' | string | Grayscale only. In the volatile mode the two image acquisition 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! |
'wait_frame_exposure_timeout' | <milliseconds> | 1000 | integer | Sets the timeout [ms] used by 'wait_frame_exposure'. |
Parameters for get_framegrabber_param
- '_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.
Parameter | Values | Default | Type | Kind | Description |
---|---|---|---|---|---|
'available_callback_types' | ['<callback_type>'] | string | dynamic | Query all callback types which are supported by this interface. | |
'bits_per_channel' | -1, 8, 10, 12 | -1 | integer | pre-defined | Number of bits per channel of the resulting HALCON image. In case of -1 the current bit depth of the camera is used. By specifying a value greater than 8 the grabbed images are delivered as uint2 images. |
'camera_connected' | 'false', 'true' | string | pre-defined | Query the presence of the connected camera. | |
'camera_type' | '<default>' | 'default' | string | pre-defined | Name of the camera configuration file. |
'color_space' | '<color_space>' | 'gray' | string | pre-defined | Desired color space and thus the number of image channels of the resulting HALCON image. |
'comm_read_int' | [<int1>, ..., <intN>] | integer | dynamic | Returns the N number of bytes set by read_buf_size from an open comm port. This command will return when the read_buf_size of bytes are available or when the serial timeout period has passed. Upon success, read_buf_size number of bytes will be returned as a tuple of N integer values. In an error case, no data is returned. Note that this parameter allows also the reading of NULL characters. | |
'comm_read_str' | <camera_response> | integer | dynamic | Returns the number of bytes set by read_buf_size from an open comm port. This command will return when the read_buf_size of bytes are available or when the serial timeout period has passed. Upon success, read_buf_size number of bytes will be returned as a string. In an error case, no data is returned. | |
'continuous_grab_timeout' | <milliseconds> | 5000 | integer | pre-defined | Returns the current continuous grabbing timeout value in milliseconds. |
'continuous_grabbing' | 'disable', 'enable' | 'disable' | string | pre-defined | Activates or deactivates 'continuous grabbing'. For details, please see the corresponding section below. |
'device' | '<device_id>' | 'default' | string | dynamic | Current device ID. |
'dma_direction' | 'bottom-up', 'top-down' | 'top-down' | string | pre-defined | Read-out direction of the image. |
'encoder_scan_step' | 0 ... 1023 | integer | dynamic | Encoder divider value. | |
'external_trigger' | 'false', 'true' | 'false' | string | pre-defined | Status of the external trigger. |
'field' | '<default>' | 'progressive' | string | pre-defined | The value is not used, so a default value is returned. |
'firmware_directory' | <value> | string | dynamic | Returns the path of the default firmware directory. | |
'firmware_file_name' | <value> | string | dynamic | Returns the file name of the used firmware. | |
'generic' | <default> | -1 | integer | pre-defined | The value is not used, so a default value is returned. |
'grab_timeout' | <milliseconds> | 5000 | integer | pre-defined | Current grab timeout in milliseconds. |
'hardware_exception_count' | <num> | integer | dynamic | Returns the number of hardware exceptions that have occurred. | |
'hardware_exception_thread' | 'disable', 'enable' | 'disable' | string | pre-defined | Start/stop hardware exception thread to reset acquisition in continuous grabbing mode when there is a hardware exception. |
'horizontal_resolution' | <resolution> | 1 | integer | pre-defined | Current value of horizontal resolution. |
'image_height' | <height> | 0 | integer | pre-defined | Height of the desired image part ('0' stands for the complete image). |
'image_width' | <width> | 0 | integer | pre-defined | Width of the desired image part ('0' stands for the complete image). |
'in:X' | 'high', 'low' | string | pre-defined | Returns the desired state of one of the digital input lines (with X = 0 for a RoadRunner, X = 1 or 2 for a RoadRunner CL). | |
'line_in' | <default> | 1 | integer | pre-defined | The value is not used, so a default value is returned. |
'lut' | 'disable', 'enable' | 'disable' | string | pre-defined | State of the lookup table. |
'name' | 'BitFlow' | string | pre-defined | Name of the HALCON interface. | |
'next_buffer_acquired' | <buffer> | integer | dyanmic | Returns the index of the next acquired buffer in continuous grabbing mode. The buffer number is between 0 and the number of allocated buffers. | |
'next_buffer_acquired_abs' | <num> | integer | dynamic | Returns the buffer index that is being returned by the next call of grab_image or grab_image_async in continuous grabbing mode. The incrementation is done continuously. The returned buffer number will be between 0 and 2^32. | |
'next_buffer_returned' | <buffer> | integer | dynamic | Returns the buffer index that is being returned by the next call of grab_image or grab_image_async in continuous grabbing mode. The buffer number is between 0 and the number of allocated buffers. | |
'num_buffers' | 2 - 1000 | 2 | integer | pre-defined | Number of buffers used for the image acquisition. |
'num_buffers_overwritten' | <value> | integer | dynamic | Returns the number of overwritten buffers. Only active, if the overwrite method is set. | |
'num_free_buffers' | <num> | integer | dynamic | Returns the number of free buffers in continuous grabbing mode. | |
'out:X' | 'high', 'low' | string | pre-defined | State of one of the digital output lines (with X = 0, 1, or 2 for RoadRunner/R3-DIF family; RoadRunner/R3 CL family). The default depends on the board settings. | |
'overflow_count' | <num> | integer | dynamic | Returns the number of overflows that have occurred. | |
'overflow_thread' | 'disable', 'enable' | 'disable' | string | pre-defined | Start/stop overflow thread to reset acquisition in continuous grabbing mode when there is an overflow exception. |
'overwrite_method' | 'abort', 'ignore' | 'abort' | string | pre-defined | Specify how the interface should handle situations where the external trigger is received faster than the images are read by the application in continuous grabbing mode (see also the corresponding section below). |
'port' | <port> | 0 | integer | pre-defined | Current port number. |
'read_buf_size' | 0...32768 | 0 | integer | dynamic | Number of bytes to read from the read buffer of an open comm port. This will most likely be set before each read, unless the message from the camera is always the same size. |
'register_index_get:xx' | <value> | integer | dynamic | Returns a register which can be used for quick access (i.e. with low CPU usage) to registers. The index returned from this function can be used with both register_index_poke and register_index_peek. The bitfield names and the purpose are described in the hardware reference manual for the frame grabber being used. Note that this function is somewhat CPU intensive and should not be used during intensive processing. | |
'register_index_peek:xx' | <value> | integer | dynamic | Returns the current value of a register or bitfield index. The index is obtained by calling register_index_get. This function uses very little CPU and can be used during CPU intensive operations | |
'register_peek:xx' | <value> | integer | dynamic | Returns the current value of a register or bitfield. The bitfield names and the purpose are described in the hardware reference manual for the frame grabber being used. Note that this function is somewhat CPU intensive and should not be used during intensive processing. | |
'resnap' | 'false', 'true' | 'false' | string | pre-defined | Specifies whether to reset the DMA engine and to try a second snap in case of an overflow. Note that in continuous grabbing mode you can use the parameter 'overflow_thread' to reset acquisition when there is an overflow exception. |
'revision' | '<revision>' | string | pre-defined | Revision number of the BitFlow interface. Further the build date of the interface will be listed. | |
'ring_buffer_stop_margin' | 1 | integer | pre-defined | This parameter controls the 'protection zone' used to look ahead when a buffer is about to be overwritten. When 'continuous_grabbing' is enable, the frame grabber acquires automatically into a circular set of buffers. There is a thread that watches acquisition and makes sure that buffers which have not yet been processed by the user's program are not overwritten by new images. If a buffers is about to be overwritten, acquisition is aborted. If the frame rate is high and/or the CPU is very busy, the thread might not get serviced in time to protect unprocessed buffers. By increasing the size, the overwrite protection can still be maintained under these conditions. This parameters only is used with 'continuous_grabbing' is enabled. | |
'sdk_build' | <value> | string | dynamic | Returns the build version. | |
'sdk_revision' | <value> | string | dynamic | Returns the version number of the SDK. | |
'serial_baudrate' | <baud> | 9600 | integer | dynamic | Baud rate for serial communication. |
'serial_message' | '<string>' | string | dynamic | Receives a string via the serial interface, see also 'comm_read_str'. | |
'serial_message_buf_size' | 1 ... 32767 | 1024 | integer | dynamic | Maximum buffer size for receive strings via 'serial_message'. |
'serial_terminate_code' | 0...255 | LF(0x0A) | integer | dynamic | Termination character of the receive string. If you call get_framegrabber_param with the parameter 'serial_message', the receive process is finished by receiving this character. |
'serial_timeout' | <milliseconds> | 1000 | integer | dynamic | Timeout for serial communication (in milliseconds). |
'serial_write_delay' | <milliseconds> | 0 | integer | dynamic | Timeout in milliseconds for serial write operations. |
'software_trigger' | 'disable', 'enable' | 'disable' | string | pre-defined | Enables or disables the software trigger mode (shot grabbing). Note that the software trigger mode can only be used with a one shot camera file. |
'start_async_after_grab_async' | 'disable', 'enable' | 'enable' | string | pre-defined | Status of 'start_async_after_grab_async'. |
'start_column' | <column> | 0 | integer | pre-defined | Returns the current start column of the HALCON image. |
'start_row' | <row> | 0 | integer | pre-defined | Returns the current start row of the HALCON image. |
'trigger_timeout' | <milliseconds> | 60000 | integer | dynamic | Timeout (milliseconds passed as an integer) for aborting a pending grab when waiting for an external trigger. |
'vertical_resolution' | <resolution> | 1 | integer | pre-defined | Current value of vertical resolution. |
'volatile' | 'disable', 'enable' | 'disable' | string | pre-defined | Grayscale only. In the volatile mode the two image acquisition 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! |
'wait_frame_exposure' | <num> | integer | dynamic | Returns if the exposure of the camera has finished. If the value 0 is returned, an error occurred. The return value 1 indicates, that a timeout was reached (see 'wait_frame_exposure_timeout). In case of success, the value 2 is returned. | |
'wait_frame_exposure_timeout' | <milliseconds> | 1000 | integer | dynamic | Sets the timeout [ms] used by 'wait_frame_exposure'. |
Operator set_framegrabber_lut
Operator get_framegrabber_lut
Operator set_framegrabber_callback
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.
Type | Description |
---|---|
'exposure_end' | Corresponds to the end of the exposure. |
'transfer_end' | Corresponds to the end of the image DMA. |
Operator get_framegrabber_callback
Operator grab_image_start
Operator grab_image
Operator grab_image_async
Operator grab_data
Operator grab_data_async
Operator close_framegrabber
Multiple Cameras (Port Switching)
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.
Continuous Grabbing
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.
HDevelop Examples
- 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.
C++ Examples
C# Examples
Release Notes
- 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.