Image Acquisition Interface for LinX GINGA digital-CLe and GINGA++Me Boards
Interface:
|
LinX
|
Revision:
|
13.0.2
|
Date:
|
2018-10-23
|
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 LinX driver
LinX.sys (LinX SDK version 5.90).
If you do not have this driver version, please contact LinX
or the vendor from which you bought the frame grabber board.
- HALCON image acquisition interface hAcqLinX.dll or
hAcqLinXxl.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
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.
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).
- Support of multiple digital cameras based on the LinX
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.
- Dynamically changing the frame size of the grabbed image.
- Support of start/stop trigger mode.
- 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.
Parameter |
Value List |
Type |
Kind |
Description |
'bits_per_channel' |
[8, 10, 12] |
integer |
pre-defined |
Values for bits per channel. |
'camera_type' |
['CAMFILE:', 'gdg;gpp', '<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' |
['GINGA:0', 'GINGA:1', 'GINGA:2', 'GINGA:3', 'default'] |
string |
pre-defined |
Pre-defined list of possible devices. |
'external_trigger' |
['false', 'true'] |
string |
pre-defined |
Values for the external trigger. |
'field' |
[] |
|
|
Unused. |
'general' |
[] |
string |
pre-defined |
Information about the HALCON LinX 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:default' |
string |
dynamic |
If a LinX board is found, the value is returned. Otherwise, an empty tuple is returned.
|
'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 |
Returns a pre-defined list of possible port numbers. |
'revision' |
'<revision>' |
string |
pre-defined |
Revision number of the LinX interface. |
'start_column' |
[] |
|
|
Unsupported query. |
'start_row' |
[] |
|
|
Unsupported query. |
'vertical_resolution' |
1 |
integer |
pre-defined |
Value list for vertical resolution. |
Parameter |
Values |
Default |
Type |
Description |
Name |
'LinX' |
|
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. 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 |
Camera configuration file. If you specify 'default' the first camera you have set with GingaSysReg
is used.
|
Device |
'<BoardType>:<nr>', 'default' |
'default' |
string |
The type ('GINGA') and the number ('0', '1', '2' ...) of the frame grabber board (passed as one string!), e.g., 'GINGA:0' or 'GINGA:1'. If you specify
'default' the interface automatically selects the first board.
|
Port |
<port> |
0 |
integer |
The number attached to the desired camera via the LinX configuration program GingaSysReg (starting with 0 for the first
camera). Only evaluated in case the CameraType parameter has been set to
'default'.
|
LineIn |
--- |
|
|
Ignored. |
Parameter |
Values |
Default |
Type |
Description |
'continuous_grabbing' |
'disable', 'enable' |
'disable' |
string |
Activate or deactivate 'continuous grabbing'. For details, please see the corresponding section below.
|
'dma_direction' |
'bottom-up', 'top-down' |
'top-down' |
string |
Read-out direction of the image. |
'do_abort_capture' |
--- |
|
|
Abort 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 |
The parameters for serial communication, separated by colons. The following parameters can be specified:
- timeout: timeout in milliseconds.
- baud_rate: baud rate. Valid baud rates are 9600, 19200, 38400,
57600, 115200, 230400.
- parity: parity to be used. N=No parity, E=Even parity,
O=Odd parity.
- data_bits: size of the data. 5="5" bit data, 6 = 6 bit data,
7 = 7 bit data, 8 = 8 bit data.
- stop_bits: number of stop bits. 1 = 1 stop bit, 15 = 1.5 stop bits,
2 = 2 stop bits
Example:
set_framegrabber_param(..., 'comm_param', 'baud_rate 9600:data_bits
8:parity N')
|
'do_comm_write' |
'<message>' |
|
string |
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 |
Specify the desired encoder divider value. |
'gport' |
[<out0>, ..., <out7>] |
|
integer |
Specify the desired state of all digital output lines. The tuple with all values must have 8 entries, where each value must be either 0 or 1.
|
'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 LinX 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 LinX
SDK Reference).
|
'lut' |
'disable', 'enable' |
'disable' |
string |
State of the lookup table. |
'num_buffers' |
2 - 1000 |
2 |
integer |
Number of buffers used for the image acquisition. |
'out:X' |
'high', 'low' |
depends on the board settings |
string |
State of one of the digital output lines (with X = 0, 1, 2, 3, 4, 5 or 6).
|
'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 LinX configuration program GingaSysReg - 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.
|
'resnap' |
'false', 'true' |
'false' |
string |
Specify 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.
|
'serial_baudrate' |
<baud> |
9600 |
integer |
Baud rate for serial communication. |
'serial_message' |
'<string>' |
|
string |
Send 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. |
'set_exposure_and_rate' |
['exp <value>: period <value>: trig_mod <string>: assert_high <string>: output <address>']
|
|
string |
Exposure and frame rate. Note that this parameter is a write-only parameter and, thus, cannot be queried by get_framegrabber_param.
- trig_mod: 'freerun', 'oneshot_trigger', 'oneshot_encoder'
- assert: 'high', 'low'
|
'shutter_speed' |
<shutter> |
|
integer |
Shutter speed. Note that this parameter is a write-only parameter and, thus, cannot be queried by get_framegrabber_param.
|
'software_trigger' |
'disable', 'enable' |
'disable' |
string |
Enable or disable 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> |
|
integer |
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' |
'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> |
|
integer |
Sets the timeout [ms] used by 'wait_frame_exposure'. |
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.
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' |
'<file>' |
'default' |
string |
pre-defined |
Current camera type. |
'color_space' |
'gray', 'rgb' |
'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 |
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 |
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_grabbing' |
'disable', 'enable' |
'disable' |
string |
pre-defined |
Activate or deactivate 'continuous grabbing'. For details, please see the corresponding section below.
|
'device' |
'<BoardType>:<nr>' |
'default' |
string |
pre-defined |
Current device. |
'dma_direction' |
'bottom-up', 'top-down' |
'top-down' |
string |
pre-defined |
Read-out direction of the image. |
'encoder_scan_step' |
0 ... 1023 |
|
integer |
dynamic |
Specify the desired 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. |
'generic' |
<default> |
-1 |
integer |
pre-defined |
The value is not used, so a default value is returned. |
'gport' |
[<out0>, ..., <out7>] |
|
integer |
dynamic |
Specify the desired state of all digital output lines. The tuple with all values must have 8 entries, where each value must be either 0 or 1.
|
'grab_timeout' |
<milliseconds> |
5000 |
integer |
pre-defined |
Current grab timeout in milliseconds. |
'hardware_exception_count' |
<number> |
|
integer |
dynamic |
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 |
State of one of the digital input lines (with X = 0, 1, 2, 3 or 4).
|
'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' |
'LinX' |
|
string |
pre-defined |
Name of the HALCON interface. |
'next_buffer_acquired' |
<buffer> |
|
integer |
dynamic |
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' |
<number> |
|
integer |
pre-defined |
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 |
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' |
<number> |
2 |
integer |
pre-defined |
Number of buffers used for the image acquisition. |
'num_free_buffers' |
<number> |
|
integer |
dynamic |
Number of free buffers in continuous grabbing mode. |
'out:X' |
'high', 'low' |
depends on the board settings |
string |
pre-defined |
State of one of the digital output lines (with X = 0, 1, 2, 3, 4, 5 or 6).
|
'overflow_count' |
<number> |
|
integer |
dynamic |
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.
|
'resnap' |
'false', 'true' |
'false' |
string |
pre-defined |
Re-snap mode. |
'revision' |
'<revision>' |
|
string |
pre-defined |
Revision number of the LinX interface. |
'serial_baudrate' |
<baud> |
9600 |
integer |
dynamic |
Baud rate for serial communication. |
'serial_message' |
'<string>' |
|
string |
dynamic |
Receive 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 |
Enable or disable 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> |
|
integer |
dynamic |
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).
|
'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' |
<status> |
|
integer |
dynamic |
Returns when 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> |
|
integer |
dynamic |
Sets the timeout [ms] used by 'wait_frame_exposure'. |
Not supported by this interface.
Not supported by this interface.
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
LinX 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 |
'transfer_end' |
Corresponds to the end of the image DMA. |
Not supported by this interface.
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.
Multiple Cameras (Port Switching)
It is possible to connect more than one camera to a LinX GINGA digital-CLe or GINGA++Me board. You will need specific camera
configuration files to do this, which have to be installed in your system
with the LinX configuration program
GingaSysReg (please
contact LinX for details). GingaSysReg 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
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
LinX).
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
linx_2ports you will find in
%HALCONROOT%\examples\hdevelop\Image\Acquisition.
Continuous Grabbing
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 loosing 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 most
safe 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
For this interface there are the following examples available:
- linx_2boards.hdev -
Example for the usage of two LinX frame grabber boards.
- linx_2ports.hdev -
Usage of two cameras ndport switching.
- linx_cont.hdev -
Shows parameterization of a LinX frame grabber
board (set up of 'continuous grabbing')
- linx.hdev -
Benchmark
- linx_simple.hdev -
A simple example to show the usage of the interface.
C++ Examples
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/.
C# Examples
Release Notes
- Revision 13.0.2 (Oct 23, 2018):
- The LinX SDK has been updated to 5.90.
- 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.
- Revision 13.0.1 (Oct 28, 2016):
- HALCON 13 version of the interface.
- Revision 6.1 (Sep 28, 2016):
- 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 'linx_2simultaneous' has been removed.
- Revision 6.0 (Oct 31, 2014):
- HALCON 12 version of the interface.
- Revision 5.3 (Sep 26, 2014):
- Withdraw to SDK 5.40. Removed all parameters and functions
which were added in the last revision.
- Revision 5.2 (Aug 28, 2013):
- Adapted to LinX 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.
- Add functionality to handle 'exposure_end' callbacks.
- 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 LinX 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 LinX 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).
- New parameters 'set_exposure_and_rate' and 'shutter_speed'.
- Bug fix in parameter 'do_comm_param'.
- Bug fix in get_framegrabber_param for the parameters
'overflow_thread' and 'hardware_exception_thread' to ensure
consistency with set_framegrabber_param.
- Revision 3.0 (Apr 22, 2008):