HALCON 6.0 Frame Grabber Interface for Leutron PicPort, PicPortPro, DigiPort and PicProdigy Boards

This document provides information about the HALCON interface HFGLeutron.dll (or HFGLeutron.so, respectively) for the Leutron Vision frame grabber boards. As the latest revision of this interface is part of the LV-SDS software from Leutron, registered customers can download it from the Support Area of the Leutron WWW server.

Revision: 2.18

• Intel compatible PC with either Windows NT 4.0 (Service Pack 4), Windows 2000, Windows XP or Linux.
• Leutron LV-SDS software package.
  Windows NT/2000/XP: The LVSDS_NT\bin directory must be within your search path %PATH% (typically, the LV-SDS software is installed to C:\LVSDS_NT). If you do not have the LV-SDS software, please contact Leutron or the vendor from which you bought the frame grabber board. Modify your path variable accordingly!
  Linux: Please follow carefully the instructions from Leutron for installing the LV-SDS software under Linux.
• Successfully installed Leutron driver lvppx.sys (Windows) or xlvppx.o (Linux), respectively.
  Typically, this file reside in the directory C:\Winnt\system32\drivers (Windows) or /usr/lib/lv (Linux) after installation of the LV-SDS software. If you do not have this driver, please contact Leutron or the vendor from which you bought the frame grabber board.
• HALCON frame grabber interface HFGLeutron.dll (or parHFGLeutron.dll, respectively) for Windows.
  After successful installation of the LV-SDS software, the HALCON Leutron interface is usually located in C:\LVSDS_NT\bin. If this directory is within your %PATH% you don't need to copy the files HFGLeutron.dll and parHFGLeutron.dll into the directory bin\i586-nt4 within the HALCON base directory %HALCONROOT% you have chosen during the installation of HALCON (see also the instructions in C:\LVSDS_NT\3rdParty\Halcon\readme.txt).
  Furthermore, we recommend to copy the current HTML documentation of this interface from C:\LVSDS_NT\3rdParty\Halcon\doc to the directory doc\html\manuals within the HALCON base directory %HALCONROOT%.
• HALCON frame grabber interface HFGLeutron.so for Linux.
  After successful installation of the LV-SDS software, the HALCON Leutron interface is usually located in /usr/LeutronVision/3rdParty/halcon/lib. You have to copy the file HFGLeutron.so into the directory lib/i586-linux2.2 within the HALCON base directory $HALCONROOT you have chosen during the installation of HALCON.
  Furthermore, we recommend to copy the current HTML documentation of this interface from /usr/LeutronVision/3rdParty/halcon/doc to the directory doc/html/manuals within the HALCON base directory $HALCONROOT.
• Attention using Windows: When opening the frame grabber, new micro code is compiled internally which is stored in the host CPU memory. If opening the board fails, make sure that RpsBuffer in the Windows registry (HKEY_LOCAL_MACHINE\SOFTWARE\Leutron Vision\PRVPH) is set to a value big enough to store this code (0x00000100 (=256)) or higher; contact Leutron for further information.

	PicPort Monochrome	Multiple cameras on multiple frame grabber boards. Serial and parallel (simultaneously from several cameras) grabbing. Synchronous and asynchronous grabbing. Different grabbing modes: external trigger, asynchronous reset, enhanced, flash, frame integration, frame integration with asynchronous reset. Subsampling. Software cropping of image parts. Support of color encoded cameras (Bayer array).
	PicPort Digital	Multiple cameras on multiple frame grabber boards. Serial and parallel (simultaneously from several cameras) grabbing. Synchronous and asynchronous grabbing. Different grabbing modes: external trigger, asynchronous reset, enhanced, flash, frame integration. Subsampling. Software cropping of image parts. Support of digital cameras with more than 8bpp. Support of color encoded cameras (Bayer array).
	PicPort Color	Multiple cameras on multiple frame grabber boards. Different grabbing modes: external trigger, enhanced, flash, frame integration. Serial and parallel (simultaneously from several cameras on more boards) grabbing. Subsampling. Software cropping of image parts.
	DigiPort	up to 32 optoisolated outputs. up to 32 optoisolated inputs.
	PicPortPro CL	CameraLink interface. Support for area scan and line scan cameras. Synchronous and asynchronous grabbing. Different grabbing modes: external trigger, asynchronous reset. Multiple cameras on Stereo boards. Software cropping of image parts. Support of cameras with more than 8bpp. Hardware support of color encoded cameras (Bayer array).
	PicProdigy Color	Multiple cameras on multiple frame grabber boards. Different grabbing modes: external trigger, enhanced. Subsampling. Software cropping of image parts.

If you are working with several cameras connected to several boards, you can access all cameras through a single handle. The connection of the cameras to the boards is specified in the device parameter in combination with the port parameter (see description below). In this case you get a multichannel image when grabbing an image; access the individual images by access_channel(). The images themselves are either grabbed in a sequence - one after the other - or in parallel (simultaneously) from all cameras at the same time (see parameter 'sequence_acquisition' below).

If you want to grab from each camera separately use open_framegrabber() once for each camera to get several handles.

• grab_region() and grab_region_async() not supported.
• No LUTs.
• Subsampling will not work for dual channel cameras and for parallel acquisition of two cameras on the same grabber.
• The asynchronous reset mode is not supported by the PicPort Color and PicProdigy Color boards.

Parameters for open_framegrabber():

	Name	'Leutron'	The name of the HALCON frame grabber interface.
	HorizontalResolution	1, 2, 4	The desired image resolution. Use '1' for full resolution, '2' for subsampling by factor 2, and '4' for subsampling by factor 4. Default: 1.
	VerticalResolution	1, 2, 4	The desired image resolution. Use '1' for full resolution, '2' for subsampling by factor 2, and '4' for subsampling by factor 4. Default: 1.
	ImageWidth	0, width	The width of the desired image part ('0' stands for the maximum image width). Default: 0.
	ImageHeight	0, height	The height of the desired image part ('0' stands for the maximum image height). Default: 0.
	StartRow	0, row	The row coordinate of the upper left pixel of the desired image part. If ImageHeight is set to 0, then both the first AND last StartRow rows of the image matrix are discarded. Default: 0.
	StartColumn	0, column	The column coordinate of the upper left pixel of the desired image part. If ImageWidth is set to 0, then both the first AND last StartColumn columns of the image matrix are discarded. Default: 0.
	Field	---	Ignored.
	BitsPerChannel	8, 9, ..., 16	Number of bits per channel: Gray scale (8 ... 16 bits) or color (8 bits). Values greater than 8 are only valid when using a PicPort Digital board together with a appropriate camera type. In this case the gray value range of the grabbed HALCON image objects will be adjusted (e.g., 0 ... 511 when using a 10bpp camera) if you specify the actual number of bits (corresponding to the specified camera type). Default: 8.
	ColorSpace	'gray','rgb'	The desired color space. Default: 'gray'.
	Gain	---	Ignored.
	ExternalTrigger	'true', 'false'	Activate/deactivate external triggering.
	CameraType	cameraname	This parameter is used to specify the camera connected to the frame grabber board. To define a camera use the camera editor delivered with the LV-SDS software. Default: 'BW_RS170'.
	Device	device	The device parameter is used to specify the board(s) used for grabbing. You have to specify the board name and the number(s) of the board(s) you want to use; one for each camera. The numbers have to be separated by a ':'. For example, if you want to use 2 (physical) boards together with one camera connected to the first and two cameras connected to the second board, you would say 'Picport Stereo H4-D:1:2:2'. For each board number there must be a digit in the port parameter (see below). The order of the (physical) board depends on your machine and is the order in which the driver finds the boards on the PCI bus. Default: 'Picport Stereo H4-S:1'.
	Port	[1-8]+	Specifies the port(s) the camera(s) is/are connected to. If you use more than one camera or more than one (physical) board, you have to specify one digit for each camera; each digit has to be in the range 1-8. For example, if you are using two (physical) boards together with 3 cameras - one connected to the second port of the first board, one to the first port of the second board and one to the third port of the second board - you would say 213 together with the combination GrabberName:1:2:2 in the device parameter. Default: 1.
	LineIn	---	Ignored.

Parameters for set_framegrabber_param():

	'volatile'	'enable', 'disable'	8bpp gray scale only. In the volatile mode the two frame grabber 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'.
	'grab_timeout'	milliseconds	The timeout value (> 0 in milliseconds) for the grabbing of images. Default: 5000.
	'acquisition_mode'	'default', 'async_reset', 'enhanced', 'flash', 'frame_integration', 'frame_integration_async_reset'	The acquisition mode you want to use for grabbing (e.g. frame integration, asynchronous reset, ...). The value string may be extended by optional additional parameters with the syntax described on the pages for the individual modules (e.g. 'async_reset:AR_ShutterTime 1000:AR_FlashEnable 1'). For a detailed description see the handbook LV-SDS from Leutron, chapter Sequencer DRAL configuration. Default: 'default' (no special module is used).
	'sequence_acquisition'	'serial', 'parallel'	The order or timing in which the images are grabbed from the different cameras connected to the boards (PicPort Monochrome, PicPort Digital, and PicPort Color only!). Serial means switching from one camera to the next, parallel means from all cameras simultaneously. Default: 'serial'.
	'boards_synchronized'	'enable', 'disable'	Enable or disable synchronization of several (physical) boards among each other (PicPort Monochrome, and PicPort Digital only!). Attention: the boards have to be connected with a special cable to the master grabber (the first one found on the PCI bus). 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 random switching between several connected cameras. Default: 'enable'.
	'suppress_timeout_beep'	'enable', 'disable'	When set to 'disable', a beep is produced every time a timeout occurs during a pending grabbing command. Default: 'disable'.
	'image_width'	0, width	The width of the desired image part ('0' stands for the maximum image width). This value has to be equal or smaller than the maximum image width.
	'image_height'	0, height	The height of the desired image part ('0' stands for the maximum image height). This value has to be equal or smaller than the maximum image height.
	'start_row'	0, row	The row coordinate of the upper left pixel of the desired image part. If ImageHeight is set to 0, then both the first AND last StartRow rows of the image matrix are discarded.
	'start_column'	0, column	The column coordinate of the upper left pixel of the desired image part. If ImageWidth is set to 0, then both the first AND last StartColumn columns of the image matrix are discarded.
	'optocoupler', 'buffered_optocoupler'	value	Sets the current state of the output optocouplers (PicPort Monochrome PMC, PicPort Digital PMC, and DigiPort only!). The value is a bitmask where each bit represents a single optocoupler. Each bit set to 1 means that the corresponding optocoupler output is set as active. The value can range from 0 to 0xFF for PicPort Monochrome PMC boards, or from 0 to 0xFFFF for DigiPort 16 boards or from 0 to 0xFFFFFFFF for DigiPort 32 boards. The optocoupler associated with bit 0 cannot be set through this function because it is internally used by the PicPort interface.
	'equalize_color_image'	'default', 'top:left:bottom:right'	Performs an image color balancing before decoding the next Bayer array image (in combination with color encoded cameras only!). This adjustment is only applied once! As parameter value can be specified either 'default' (full image is processed) or a specific rectangle as 'top:left:bottom:right', i.e. '0:0:100:100'.
	'external_trigger'	'true', 'false'	Activate/deactivate external triggering.
	'upperlevel'	0 ... 255	Define the upper level of the on-board ADCs (PicPort Monochrome only!).
	'lowerlevel'	0 ... 255	Define the lower level of the on-board ADCs (PicPort Monochrome only!).
	'brightness'	brightness	Define the brightness level of the onboard decoder (PicPort Color and PicProdigy Color only!). The value can range from -128 to 127 for PicPort Color boards, or from 0 to 255 for PicProdigy Color boards.
	'contrast'	contrast	Define the contrast level of the onboard decoder (PicPort Color and PicProdigy Color only!). The value can range from 0 to 511 for PicPort Color boards, or from 0 to 255 for PicProdigy Color boards.
	'hue'	-128 ... 127	Define the hue angle of the onboard decoder (PicPort Color and PicProdigy Color only!).
	'saturation'	saturation	Define the saturation level of the onboard decoder (PicPort Color and PicProdigy Color only!). The value can range from 0 to 511 for PicPort Color boards, or from 0 to 255 for PicProdigy Color boards.
	'opto_config'	'num:value ...'	Configure the optoisolated inputs (DigiPort only!). Each opto input (num=0..31) can be configured with one of the following values (either using the digit or the string): '0' or 'Disable': Never reported '1' or 'RaisingEdge': Reported when transacting from low to high '2' or 'FallingEdge': Reported transacting from high to low '3' or 'BothEdge': Reported on any transaction More opto inputs can be configured at the same time, each with its own settings. Furthermore, you can also configure all opto inputs with the same polarity using the 'All' string. Examples: set_framegrabber_param(FGHandle,'opto_config','1:RaisingEdge') set_framegrabber_param(FGHandle,'opto_config','1:2 2:0 3:0') set_framegrabber_param(FGHandle,'opto_config','All:BothEdge')
	'comm_param'	'name value ...'	Set the parameters for serial communication with the camera over the CameraLink interface (PicPortPro CL only!). Each parameter is specified with name value. More parameters can be set in the same set_framegrabber_param call separating them with the ':' character (e.g. 'BaudRate 9600:DataBit 8:Parity N'). The following parameters can be specified: 'Timeout': Timeout in milliseconds. The communication fails if the amount of milliseconds specified in Timeout expires without receiving any response from the camera. 'BaudRate': Baud rate. Numeric. This value must match that set in the camera. 'Parity': Parity to be used. N=No parity, E=Even parity, O=Odd parity 'DataBit': Size of the data. 7=7bit data, 8=8 bit data 'StopBit': Number of stop bits: 1=1 stop bit 2=2 stop bits
	'camera_cmd'	string	String command to send to the camera, including any control character (PicPortPro CL only!). The interface waits for response from the camera. The camera answer can be retrieved with get_framegrabber_param(FGHandle,'camera_response',...). Most cameras require a non-printable command termination character, usually a carriage return or line feed. For such characters, use the escape character representation, i.e. for CR use '\r', for LF use '\n'. set_framegrabber_param(FGHandle,'camera_cmd','TR=2\r\n') Please, note that binary protocols are not supported in this interface since, usually, they require run-time calculations on the ongoing binary packet, i.e. CRC calculation.
	'io_inconfig_0', 'io_inconfig_1', 'io_inconfig_2'	'name value ...'	Define up to three trigger sources with proper functionality. Each parameter is specified with name value. More parameters can be set in the same set_framegrabber_param call separating them with the ':' character (e.g. 'Function FrameTrigger : Type Opto : Index 1'). The following parameters can be specified: 'Function': Function of the input signal. The value can be 'None' or 'Nothing' (Disables the input), 'FrameTrigger' (When asserted, a frame is captured), 'FrameStopTrigger' (When asserted, the frame acquisition is aborted. For area scan cameras a full frame is anyway completed, for line scan cameras, the frame is aborted immediately.), or 'LineTrigger' (When asserted, a line is captured. Only for acquisition_mode 'async_reset'. 'Type': Type of signal. The value can be 'Opto' for an optocoupler, 'GpioTTL' for a single Gpio signal, or 'GpioLVDS' for a differential Gpio signal. 'Index': Index of the signal to be used. The value can range from 0 to 8. The maximum value depends on the used board. 'Pol': Activation polarity of the signal. The value can be 'ActiveHigh' (the signal is asserted when changing from low to high) or 'ActiveLow' (the signal is asserted when changing from high to low). 'TypeBack': Encoder. Type of signal of the backward encoder phase. The value can be 'Opto' for an optocoupler, 'GpioTTL' for a single Gpio signal, or 'GpioLVDS' for a differential Gpio signal. 'IndexBack': Encoder. Index of the signal of the backward encoder phase. The value can range from 0 to 8. The maximum value depends on the used board. 'PolBack': Encoder. Activation polarity of the backward encoder phase signal. The value can be 'ActiveHigh' (the signal is asserted when changing from low to high) or 'ActiveLow' (the signal is asserted when changing from high to low). 'Ratio': An acquisition trigger is issued every value physical triggers. Not always possible, depends on the configuration. Default: 1 (every event is processed).
	'io_extev_function'	'StartAcq', 'StartStopAcq', 'RestartAcq', 'EnableAcq'	Defines the overall functionality of the I/O inputs defined with io_inconfig_x. Note when 'FrameTrigger' is not set explicitly in any io_inconfig_x, it gets a default value (usually 'Opto 0'). 'StartAcq': Start an acquisition on the defined 'FrameTrigger' input activation. 'StartStopAcq': Start an acquisition on the defined 'FrameTrigger' input activation and stop the acquisition on the defined 'FrameStopTrigger' input activation. The 'FrameStopTrigger' input can be defined the same as 'FrameTrigger' input. 'RestartAcq': Restart an acquisition, meaning the actual acquisition is aborted and a new frame is captured, on the defined 'FrameTrigger' input activation. Meaningful for line scan cameras only. 'EnableAcq': Enable frame acquisitions while the defined 'FrameTrigger' input remains active. 'FrameTrigger' deactivation stops the acquisition.

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().