HALCON 8.0 Image Acquisition Interface for LinX Ginga Boards

This page provides the documentation about the HALCON Ginga image acquisition interface for the LinX Corporation frame grabber boards of the Ginga family. Registered customers can download the latest revision of this interface from the MVTec WWW server.

Revision: 3.2

System Requirements

• Intel compatible PC with Windows NT 4.0 (Service Pack 4), Windows 2000 or Windows XP.
• Successfully installed Ginga driver Flashbus.sys (version 3.30 or higher).
• LinX DLL Fbus32.dll (version 3.9 or higher).
  This DLL must be within your search path %PATH%. If you do not have this DLL, please contact LinX or the vendor from which you bought the frame grabber board.
• HALCON image acquistion interface hAcqGinga.dll or parhAcqGinga.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 with multiple cameras.
• Synchronous and asynchronous grabbing.
• Realtime grabbing (30 frames per second or 60 fields per second for NTSC).
• External trigger.
• Subsampling by a factor of 1, 2 or 4 in horizontal or vertical direction separatly.
• Cropping of image parts.
• Writing and reading LUTs.
• Software control of the video gain (composite and S-Video only).
• Sending or receiving TTL signals from the onboard pins.
• Programming the serial interface.
• Optional: automatic gain control.
• Software control of hue, saturation, and brightness.
• Software control of the intensity of the red-, green-, and blue- channel (for RGB-signal).
• Software control of contrast and sharpness.
• Optional: disable color decoding on a composite input.
• Adjustment of frame grabber specific parameters.
• Supporting strobe grabbing and asynchronous reset.

Limitations

• grab_data and grab_data_async not supported.

Description

Parameters for open_framegrabber():

	Name		'Ginga'		The name of the HALCON image acquisition interface.
	HorizontalResolution		1, 2, 4, width		The desired image resolution. Use '1' for full resolution, '2' for subsampling by factor 2, '4' for subsampling by factor 4, or the corresponding absolute values 640, 320, 160 (NTSC) or 768, 384, 192 (PAL). Default: 1.
	VerticalResolution		1, 2, 4, height		The desired image resolution. Use '1' for full resolution, '2' for subsampling by factor 2, '4' for subsampling by factor 4, or the corresponding absolute values 480, 240, 120 (NTSC) or 576, 288, 144 (PAL). Default: 1.
	ImageWidth		0, width		The width of the desired image part (use '0' for the complete image). Default: 0.
	ImageHeight		0, height		The height of the desired image part (use '0' for the complete image). Default: 0.
	StartRow		0, row		The row coordinate of the upper left pixel within the desired image part (use '0' for the complete image). Default: 0.
	StartColumn		0, column		The column coordinate of the upper left pixel within the desired image part (use '0' for the complete image). Default: 0.
	Field		'first', 'second', 'next', 'interlaced', 'progressive'		Specifies the alignment of the grabbed images ('first': grabbing starts with an even field, 'second': grabbing starts with an odd field, 'next': grabbing starts with the next available field). When subsampling by a factor of 2 or 4 a field grabbing is done (you can achieve full field rate grabbing in this case!). To avoid line jittering say 'first' or 'second' (in this case you only get even or odd fields when subsampling). If you use a progressive scan camera say 'progressive'. Default: 'next'.
	BitsPerChannel		5, 8		Number of bits per image channel which will be delivered by the board via the PCI bus. Specifying 5 bits per channel is only allowed in combination with ColorSpace='rgb' and enables the 5-6-5 bit encoded RGB raw data transfer (reduced PCI bus load!). You will get an 8-8-8 three channel RGB HALCON image in this case, too. Default: 8.
	ColorSpace		'gray', 'rgb'		Specify the desired color space and thus the number of image channels of the resulting HALCON image. Default: 'rgb'.
	Generic		---		Ignored.
	ExternalTrigger		'true', 'false'		Activate/deactivate external triggering. Default: 'false'.
	CameraType		'auto', 'ntsc', 'pal', 'pal-large', 's-ntsc', 's-pal', 's-pal-large', 'rgb-ntsc', 'rgb-pal', 'rgb-pal-large', 'rs170-ntsc', 'rs170-pal', 'rs170-pal-large'		Specify the desired video signal: 'ntsc', 'pal', or 'auto'. The latter will do an automatic analysis of the signal. The additional 's-' or 'rgb-' specifies an S-Video or RGB input. Without the prefix a composite signal is assumed. For the PAL norm the suffix '-large' leads to an image size of 768*576 pixels, whereas the normal size is assumed to be 760*570. Default: 'ntsc'.
	Device		'0', '1', '2', ...		The number of the frame grabber board (passed as a string!). Default: '0'.
	Port		0 - 5		The desired input port depends on the type of video signal you are using. The following ports are available for the different types: Composite: 0-5, S-Video: 0-2, RGB: 0, RS170: 0-1. Default: 1.
	LineIn		---		Ignored.

Parameters for set_framegrabber_param():

	'agc'		'enable', 'disable'		Enables or disables automatic gain control. Default: 'disable'.
	'bluebright'		0 - 63		Sets blue brightness value for RGB input. Default: 0.
	'brightness'		0 - 63		Sets value for brightness. Default: 34.
	'cameratype'		value		Specifies the camera type. Default: 0.
	'compmono'		'enable', 'disable'		Enable or disable color decoding on a composite input. Default: 'enable'.
	'contrast'		0 - 63		Sets value for contrast. Default: 35.
	'flash_fdelay'		nrfields		Number of fields to wait between firing the flash and grabbing the frame. Default: 0.
	'flash_ldelay'		nrlines		Number of video lines to wait between firing the flash and grabbing the frame. Default: 0.
	'flash_type'		flashtype		Specifies the type of flash control desired (see Ginga user manual for a detailed description). Default: 0.
	'gain'		0.0 - 63.0		Sets the gain (only valid for composite and S-Video inputs). AGC must be disabled! Default: 11.0.
	'grab_timeout'		timeout		Timeout for image acquisition in milliseconds. Default: 5000.
	'greenbright'		0 - 63		Sets green brightness value for RGB input. Default: 0.
	'hue'		0 - 63		Sets value for hue. Default: 0.
	'misc_param_##'		value		Sets other than the above parameters; replace ## by the number of the parameter you want to set. For a complete list of the available parameters see your documentation of your Ginga frame grabber board. Attention: When using 'misc_param_##' the according parameter is set on the board and is NOT stored per instance!
	'non_async_grab'		0, 1		Enable (1) or disable (0) the acquisition mode for strobe grabbing and asynchronous reset. Default: 0.
	'redbright'		0 - 63		Sets red brightness value for RGB input. Default: 0.
	'saturation'		0 - 63		Sets value for saturation. Default: 32.
	'serial'		string		Sends a string to the serial port of the frame grabber board.
	'serial_setup'		'nBaud:nData:nParity:nStop: nBytes:nTimeOut'		Configures the serial port of the frame grabber board. Possible values: nBaud: 50, 110, 134, 200, 300, 600, 1050, 1200, 2400, 4800, 7200, 9600, 38400 nData: 5, 6, 7, 8 nParity: 0 (none), 1 (odd), 2 (even) nStop: 1, 2 nBytes: >="0" nTimeOut: >="0" Default: '9600:8:0:1:16:10'.
	'sharpness'		0 - 7		Sets a sharpness filter. Default: 0.
	'switch_camera_delay'		1 - 32768		The number of vertical blanks after switching between cameras connected to different ports. Make sure that the time needed to wait for the specified number of vertical blanks is smaller than the timeout for video synchronization (set by 'wait_for_sync'). Default: 1.
	'syncmode'		0, 1		If syncmode is set to 1 the decoder changes its method of syncing to a video source (may produce better results with certain video equipment). Default: 0.
	'trigger_signal'		'rising', 'falling', 'levelhigh', 'levellow'		Defines the expected type of input trigger. 'rising' ('falling') requires the external trigger to go low (high) and high (low) again before the next image can be acquired; in case of 'levelhigh' ('levellow') an image can be acquired during the whole time the trigger is high (low).
	'ttlio'		dword		Sets TTL level of the onboard pins. The setting is passed as a 32 bit value. The upper 16 bits are used as a mask, the lower 16 bits contain the bit pattern to be set. Only 8 bits are used. The pattern is as follows: UUUUUUUUMMMMMMMMUUUUUUUUVVVVVVVV (U: unused / M: mask / V: value).
	'volatile'		'enable', 'disable'		Grayscale (8 bit) 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'.
	'wait_for_sync'		timeout		Timeout in ms to wait for video synchronization after switching ports. Make sure that this value is larger than the time needed by 'switch_camera_delay'. Default: 5000.

Parameters for get_framegrabber_param():

Additional parameters supported by get_framegrabber_param only. Note that all parameters supported by set_framegrabber_param can also be accessed by get_framegrabber_param. 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'].

	'libversion'		version		The version number of the Ginga library Fbus32.dll.
	'revision'		revision		The revision number of the HALCON Ginga interface.

Lookup Tables:

Lookup tables can be manipulated using the operator set_framegrabber_lut() and get_framegrabber_lut(). The Ginga frame grabber boards use 256 entries per LUT, which are passed as an array of integers with a value range from 0-255. When using RGB input, three arrays are needed, in case of composite input or the 'rs170...' camera type parameter only the red channel is used. Default: ramp with values from 0-255.

Release Notes

• Revision 3.2 (Mar 16, 2009):
  • Fixed bug in info_framegrabber for parameter revision.
• Revision 3.1 (Apr 22, 2008):
  • Added read-only parameters with postfix '_description', '_range', and '_values' to enable the easy parameterization via a generic graphical user interface.
• Revision 3.0 (Jun 28, 2007):
  • HALCON 8.0 version of the interface (legacy only).
• Revision 2.3 (Jul 27, 2005):
  • HALCON 7.1 version of the interface.
  • Speed-up for acquisition of RGB images (avoiding cache alignment failures when converting the interleaved image data into HALCON image objects).
• Revision 2.2 (Dec 10, 2004):
  • 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.1 (Nov 14, 2000):
  • HALCON 7.0 version of the interface (included in HALCON 7.0 CD).
  • HALCON 6.1 version of the interface (included in HALCON 6.1 CD).
  • Query board information via info_framegrabber.
• Revision 2.0 (Jul 25, 2000):
  • Adaptation to the HALCON 6.0 frame grabber integration interface.
  • Optional parameter 'camera_type' renamed to 'cameratype'.
• Revision 1.27 (Mar 30, 2000):
  • New parameter 'non_async_grab' to enable acquistion mode for strobe grabbing and asynchronous reset.
  • New parameters 'flash_type', 'flash_fdelay', and 'flash_ldelay' to specify the desired flash parameters.
  • Evaluation of the 'Field' parameter during open_framegrabber to enable correct field alignment when grabbing with interlaced cameras.
• Revision 1.26 (Jun 18, 1999):
  • New parameter 'grab_timeout'.
• Revision 1.21 (May 4, 1999):
  • New parameters 'switch_camera_delay' and 'wait_for_sync'.
• Revision 1.17 (Apr 23, 1999):
  • HALCON 5.2 version of the interface (included in the HALCON 5.2 CD).
  • Some bugfixes concerning the serial interface.
  • First official release.
• Revision 1.10 (Mar 22, 1999):
  • Prerelease of HALCON 5.2 version of the interface (included in the HALCON 5.2 prerelease CD).