HALCON 9.0 Image Acquisition Interface for LinX GINGA digital-CLe and GINGA++Me Boards

This page provides the documentation about the HALCON LinX interface for the LinX GINGA digital-CLe and GINGA++Me boards. Registered customers can download the latest revision of this interface from the MVTec WWW server or from the Support Area of the LinX WWW server. In case of installation problems please send an e-mail (techimage@linx.jp) or a fax (81-45-979-0732) to LinX technical support center.

Revision: 4.1

System Requirements

• Intel compatible PC with Windows 2000/XP/Vista or Windows XP/Vista x64 Edition.
• Windows 2000/XP/Vista: Successfully installed LinX driver LinX.sys (LinX SDK version 5.00).
  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.

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.
• Simultaneous grabbing from multiple synchronized cameras (see parameter 'num_simultaneous_cameras' in the corresponding section below).
• 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 or simultaneous grabbing).
• No subsampling or cropping of image parts through the HALCON interface. This feature is supported through the use of camera files.
• grab_data and grab_data_async not supported.
• No support for LUTs.

Description

Parameters for open_framegrabber():

	Name		'LinX'		The name of the HALCON image acquisition interface.
	HorizontalResolution		1, width		The desired image resolution. Use '1' for full resolution or the corresponding absolute value (depending on your camera). Default: 1.
	VerticalResolution		1, height		The desired image resolution. Use '1' for full resolution or the corresponding absolute value (depending on your camera). Default: 1.
	ImageWidth		0		The width of the desired image part ('0' stands for the complete image). Default: 0.
	ImageHeight		0		The height of the desired image part ('0' stands for the complete image). Default: 0.
	StartRow		0		The row coordinate of the upper left pixel within the desired image part ('0' obviously results in delivering the complete image). Default: 0.
	StartColumn		0		The column coordinate of the upper left pixel within the desired image part ('0' obviously results in delivering the complete image). Default: 0.
	Field		---		Ignored.
	BitsPerChannel		-1, 8, 10, 12		The number of bits per channel. By specifying the default '-1' the corresponding setting of the camera configuration file is used. Default: -1.
	ColorSpace		'gray', 'rgb'		The desired color space. If BitsPerChannel is set to -1, the value is ignored and overwritten by the settings of the camera configuration file. Default: 'gray'.
	Generic		---		Ignored.
	ExternalTrigger		'true', 'false'		Activate/deactivate external triggering. Note that this setting overrides the corresponding setup in the camera configuration file. Default: 'false'.
	CameraType		'file', 'default'		This parameter is used to specify the camera configuration file. If you specify 'default' the first camera you have set with GingaSysReg is used.
	Device		'<BoardType>:<nr>', 'default'		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		number		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'. Default: 0.
	LineIn		---		Ignored.

Parameters for set_framegrabber_param():

	'continuous_grabbing'		'enable', 'disable'		Activate or deactivate 'continuous grabbing'. For details, please see the corresponding section below. Default: 'disable'.
	'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		Sets 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(AcqHandle, 'comm_param', 'baud_rate 9600:data_bits 8:parity N')
	'do_comm_write'		message		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 NUL characters. Examples: set_framegrabber_param(AcqHandle, 'do_comm_write', 'TR="2"\r\n'), set_framegrabber_param(AcqHandle, '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		Specify the desired encoder divider value.
	'gport'		[out0,...,out7]		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		Specify the desired timeout (milliseconds passed as an integer) for aborting a pending grab (the default value is specified in the camera configuration file).
	'hardware_exception_thread'		'enable', 'disable'		Start/stop hardware exception thread to reset acquisition in continuous grabbing mode when there is a hardware exception. Default: 'disable'.
	'image_height'		height		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		Dynamically change the current image width of the grabbed image. This value has to be a multiple of 4 and is limitied to use with only free run camera files (see also the comments to CiAqFrameSize in the LinX SDK Reference).
	'num_buffers'		2 - 1000		Specify the number of frame buffers used by the interface. Default: 2.
	'num_simultaneous_cameras'		number		This parameter sets the number of cameras from which the board grabs images simultaneously (see corresponding section below). Default: 1.
	'out:X'		'high', 'low'		Specify the desired state of one of the digital output lines (with X = 0, 1, 2, 3, 4, 5 or 6). The default depends on the board settings.
	'overflow_thread'		'enable', 'disable'		Start/stop overflow thread to reset acquisition in continuous grabbing mode when there is an overflow exception. Default: 'disable'.
	'overwrite_method'		'abort', 'ignore'		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). Default: 'abort'.
	'port'		number		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		Sets the 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. Default: 0.
	'resnap'		'true', 'false'		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. Default: 'false'.
	'serial_baudrate'		baudrate		Set the baud rate for serial communication. Default: 9600.
	'serial_terminate_code'		0 ... 255		Set the 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. Default: LF(0x0A).
	'serial_timeout'		timeout		Set the timeout for serial communication (in milliseconds). Default: 1000.
	'serial_message'		string		Send the string via the serial interface, see also 'do_comm_write'.
	'serial_message_buf_size'		1 ... 32767		Specify the maximum buffer size for receive strings via 'serial_message'. Default: 1024.
	'set_exposure_and_rate'		'exp value: period value: trig_mod string: assert_high string: output address'		Set the desired exposure and frame rate. Note that this parameter is a write-only parameter and, thus, cannot be queried by get_framegrabber_param. Possible values for 'trig_mod': 'freerun', 'oneshot_trigger', 'oneshot_encoder'; possible values for 'assert: 'high', 'low'.
	'show_internal_errors'		'true', 'false'		Specify whether the image acquisition interface should pop up an alert box in case of an error or not. If you use your own error management, we recommend to switch off the internal error display. In this mode only the error code is returned by the image acquisition operators, but the interface itself is "silent" (important for inline applications etc.). Otherwise, the user has to click on one of the buttons in the error dialog. On the other side, activated internal error display will result in more detailed and specific error messages for trouble shooting. The two behaviors can also be reached by using the HALCON operator set_system('do_low_error','true') or set_system('do_low_error','false'), respectively. Default: 'false'.
	'shutter_speed'		shutter		Specify the desired shutter speed. Note that this parameter is a write-only parameter and, thus, cannot be queried by get_framegrabber_param.
	'software_trigger'		'enable', 'disable'		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. Default: 'disable'.
	'start_async_after_grab_async'		'enable', 'disable'		By default, at the end of grab_image_async a new asynchronous grab command is automatically given to the frame grabber board. If the parameter 'start_async_after_grab_async' is set to 'disable' this new grab command is omitted. This might be useful especially for switching between several connected cameras. Default: 'enable'.
	'trigger_timeout'		milliseconds		Specify the desired timeout (milliseconds passed as an integer) for aborting a pending grab when waiting for an external trigger (a default of 60 seconds is set during open_framegrabber()).
	'volatile'		'enable', 'disable'		Grayscale only. In the volatile mode the two 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! Default: 'disable'.

Parameters for get_framegrabber_param():

Additional parameters supported by get_framegrabber_param only. Note that all parameters supported by set_framegrabber_param except the ones with prefix 'do_' can also be accessed by get_framegrabber_param. Furthermore, corresponding to the parameters supported by set_framegrabber_param, there may exist additional read-only parameters with the following postfixes:

• '_description': These parameters provide the tooltip of the corresponding parameter as a string.
• '_range': These parameters provide the minimum, maximum, stepwidth, and default values for the corresponding integer or float parameter as a tuple with 4 elements, e.g., get_framegrabber_param(..,'exposure_range',..) will return the output tuple [min,max,step,default]. Optionally, this tuple can also contain additional valid string values like 'auto' or 'manual'.
• '_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'].

	'available_callback_types'		callback_type		Query all callback types which are supported by this interface.
	'camera_connected'		'true', 'false'		Query the presence of the connected camera.
	'do_comm_read_int'		[int1,...,intN]		Reads 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 NUL characters.
	'do_comm_read_str'		camera_response		Reads 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.
	'hardware_exception_count'		num		Query the number of hardware exceptions that have occurred.
	'in:X'		'high', 'low'		Query the desired state of one of the digital input lines (with X = 0, 1, 2, 3 or 4).
	'next_buffer_acquired'		buffer		Returns the index of the next acquired buffer in continuous grabbing mode.
	'next_buffer_returned'		buffer		Returns the buffer index that is being returned by the next call of grab_image or grab_image_async in continuous grabbing mode.
	'num_free_buffers'		num		Query the number of free buffers in continuous grabbing mode.
	'overflow_count'		num		Query the number of overflows that have occurred.
	'revision'		revision		The revision number of the HALCON LinX interface.
	'serial_message'		string		Receive a string via the serial interface, see also 'do_comm_read_str'.

Parameters for set_framegrabber_callback():

The following callback types are supported by this interface:

'transfer_end'

Corresponds to the end of the image DMA.

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.

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 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 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.dev 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(AcqHandle,'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.

Simultaneous Grabbing from Multiple Cameras

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

Note that simultaneous grabbing is not supported in 24 bit per pixel mode.

Release Notes

• 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'.
  • Bugfix in parameter 'do_comm_param'.
  • Bugfix 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):
  • First official release.