HALCON 8.0 General Purpose TWAIN Interface

This page provides the documentation of the HALCON TWAIN interface. Using this interface you can acquire images from arbitrary image devices which support the TWAIN standard, e.g., scanners. Registered customers can download the latest revision of this interface from the MVTec WWW server.

Revision: 3.3

System Requirements

• Intel compatible PC with Windows NT/2000/XP/Vista.
• TWAIN DLLs TWAIN_32.DLL, TWAIN.DLL (version 1.6.0.3 or higher), TWUNK_32.EXE, and TWUNK_16.EXE (version 1.6.0.1 or higher).
  These DLLs should reside in the Windows directory and are shipped together with the HALCON distribution (you can find them in the directory misc\i586-nt4 on the HALCON CD). Attention: Make sure that you donīt use an older version of these DLLs, because you might run into severe problems in that case.
• HALCON TWAIN interface hAcqTwain.dll or parhAcqTwain.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

• Interactive mode: The source's user interface will pop up each time you acquire an image. The parameters of the acquired image (width, height, ...) are written back to the corresponding HALCON variables in the 'interactive:xxx' modes; requesting these values with get_framegrabber_param() gives you the possibility to open the device again in manual mode.
• Manual mode for stand-alone applications: The source's user interface is not displayed. Instead of this the values specified in open_framegrabber are taken to initialize the device accordingly. You can selectively choose the parameters you want to set. All other values remain unchanged (the source's default values are taken instead).
• Manipulation of several device parameters according to the TWAIN norm.

Limitations

• There's a maximum of 3 image channels that the interface will extract from colored pixel data, even in the case of a scanner model that provides 'CMYK' or 'YUVK' color data.
• Asynchronous grabbing is not supported. Thus, the call of grab_image_async is equal to grab_image; the operator grab_image_start is not supported.

Description

Parameters for open_framegrabber():

	Name		'TWAIN'		The name of the HALCON TWAIN interface.
	HorizontalResolution		-1, resolution/scaling		The desired image x-resolution/scaling. This value is only evaluated if you say 'inches', 'centimeters', 'picas', 'points', 'twips' or 'pixels' in the cameratype parameter. In case of 'pixels' this parameter is used to scale the acquired image in the x-direction. The scaling factor is determined by evaluating the term HorizontalResolution / (maximum image width). E.g., if you have an NTSC camera and you say 320, the scaling factor will be 1/2 and you get an image of width 320 pixels. In the other cases this parameter is interpreted as resolution (#pixels/units with units specified in the cameratype parameter). E.g., using a scanner with 'inches' as CameraType and 200 as HorizontalResolution, you will get an image with an x-resolution of 200 dpi. For your information: 1 point = 1/72 inch; 1 pica = 1/6 inch = 12 points; 1 twip = 1/20 point = 1/1440 inch. Use '-1' if you don't want this value to be set. Default: -1.
	VerticalResolution		-1, resolution/scaling		The desired image y-resolution/scaling. This value is only evaluated if you say 'inches', 'centimeters', 'picas', 'points', 'twips' or 'pixels' in the cameratype parameter. In case of 'pixels' this parameter is used to scale the acquired image in the y-direction. The scaling factor is determined by evaluating the term VerticalResolution / (maximum image height). E.g., if you have an NTSC camera and you say 240, the scaling factor will be 1/2 and you get an image of height 240 pixels. In the other cases this parameter is interpreted as resolution (#pixels/units with units specified in the cameratype parameter). E.g., using a scanner with 'inches' as CameraType and 200 as VerticalResolution, you will get an image with an y-resolution of 200 dpi. For your information: 1 point = 1/72 inch; 1 pica = 1/6 inch = 12 points; 1 twip = 1/20 point = 1/1440 inch. Use '-1' if you don't want this value to be set. Default: -1.
	ImageWidth		-1, width		The width of the desired image part in pixels. Attention: The image part is only set if ImageWidth, ImageHeight, StartRow, and StartColumn are all different from -1. Use '-1' if you don't want this value to be set. Default: -1.
	ImageHeight		-1, height		The height of the desired image part in pixels. Attention: The image part is only set if ImageWidth, ImageHeight, StartRow, and StartColumn are all different from -1. Use '-1' if you don't want this value to be set. Default: -1.
	StartRow		-1, row		The row coordinate of the upper left pixel of the desired image part. Attention: The image part is only set if ImageWidth, ImageHeight, StartRow, and StartColumn are all different from -1. Use '-1' if you don't want this value to be set. Default: -1.
	StartColumn		-1, column		The column coordinate of the upper left pixel of the desired image part. Attention: The image part is only set if ImageWidth, ImageHeight, StartRow, and StartColumn are all different from -1. Use '-1' if you don't want this value to be set. Default: -1.
	Field		---		Ignored.
	BitsPerChannel		-1, bits		Bit depth of the image per channel. This depth is applied to all the data channels (for instance, the R, G, and B channels will all have this same bit depth for RGB data). Use '-1' if you don't want this value to be set. Default: -1.
	ColorSpace		'bw', 'gray', 'rgb', 'palette', 'cmy', 'cmyk', 'yuv', 'yuvk', 'ciexyz'		Sets the type of pixel data according to the TWAIN norm. Default: 'rgb'.
	Generic		---		Ignored.
	ExternalTrigger		---		Ignored.
	CameraType		'interactive', 'interactive:inches', 'interactive:centimeters', 'interactive:picas', 'interactive:points', 'interactive:twips', 'interactive:pixels', 'inches', 'centimeters', 'picas', 'points', 'twips', 'pixels'		The cameratype parameter is used to specify whether the image is acquired interactively via the user interface of the source or if the TWAIN parameters are set manually. You have to determine if your device uses units (e.g., scanners) or if you have a dimensionless device (e.g., frame grabbers). When saying 'interactive' or 'interactive:xxx' the user interface of the source is displayed each time you acquire an image and the parameters are written back to the corresponding HALCON variables in the 'interactive:xxx' case. If CameraType=='inches', ... the user interface of the source is not displayed and the parameters are set manually to the values you provide (see HorizontalResolution, VerticalResolution, ...). Default: 'interactive'.
	Device		'interactive', 'automatic', 'device'		Desired TWAIN source. When typing 'interactive' the source manager's dialog box will pop up and you can determine the desired TWAIN source interactively; when saying 'automatic' the source manager's default device will be selected. To open a device directly a call of info_framegrabber('TWAIN','info_boards', ... , ...) returns a list of available devices. Default: 'interactive'.
	Port		---		Ignored.
	LineIn		---		Ignored.

Parameters for set_framegrabber_param():

With the set_framegrabber command several parameters of the source can be adjusted manually. These parameters must be in accordance with the TWAIN norm. At the end of each description the according TWAIN capability is listed which will be manipulated by the specific parameter.

	'bitdepth'		1, 2, ...		Specifies the pixel bit depth for the current value of pixeltype. This value is applied to all data channels (for instance, the R, G, and B channels will all have this same bit depth for RGB data). Corresponding TWAIN capability: ICAP_BITDEPTH.
	'brightness'		-1000.0 - 1000.0		Brightness value of the source. Corresponding TWAIN capability: ICAP_BRIGHTNESS.
	'contrast'		-1000.0 - 1000.0		Contrast value of the source. Corresponding TWAIN capability: ICAP_CONTRAST.
	'gamma'		gamma (float)		Gamma correction value for the image data. Corresponding TWAIN capability: ICAP_GAMMA.
	'highlight'		0.0 - 255.0		Specifies which value in an image should be interpreted as the lightest "highlight". All values lighter than this value will be clipped to this value. Corresponding TWAIN capability: ICAP_HIGHLIGHT.
	'lightpath'		'reflective', 'transmissive'		If your scanner provides a light source for transmitted light scanning (e.g., a film scanner) you can select 'transmissive' mode for transparent material. Corresponding TWAIN capability: ICAP_LIGHTPATH. Default: 'reflective'.
	'pixeltype'		'gray', 'rgb', 'palette', 'cmy', 'cmyk', 'yuv', 'yuvk', 'ciexyz'		The type of pixel data that a source is capable of acquiring. Corresponding TWAIN capability: ICAP_PIXELTYPE.
	'shadow'		0.0 - 255.0		Specifies which value in an image should be interpreted as the darkest "shadow". All values darker than this value will be clipped to this value. Corresponding TWAIN capability: ICAP_SHADOW.
	'units'		'inches', 'centimeters', 'picas', 'points', 'twips', 'pixels'		Unless a quantity is dimensionless or uses a specified unit of measure, units determines the unit of measure for all quantities. Corresponding TWAIN capability: ICAP_UNITS.
	'userinterface'		'show', 'hide'		When set to 'show' the source's user interface is displayed each time an image is acquired. In this case you can specify the image parameters interactively. Default: 'show'.
	'xfermech'		'native', 'file', 'memory'		Transfer mechanism of the source. Specifies the transfer mechanism from the source to the interface. If set to native mode the entire image will be transferred, in memory mode the image will be delivered in parts of the size preferred by the source, in file mode the image is transferred via the harddisk. Note: Different scanner models might come up with different default transfer mechanisms; on the other hand, not all of the transfer modes might be supported by a specific scanner driver. Corresponding TWAIN capability: ICAP_XFERMECH.
	'xresolution'		> 0.0		X-axis resolution of the source (measured in units of pixels per unit). Corresponding TWAIN capability: ICAP_XRESOLUTION.
	'xscaling'		> 0.0		Scaling in x-direction. Corresponding TWAIN capability: ICAP_XSCALING.
	'yresolution'		> 0.0		Y-axis resolution of the source (measured in units of pixels per) unit. Corresponding TWAIN capability: ICAP_YRESOLUTION.
	'yscaling'		> 0.0		Scaling in y-direction. Corresponding TWAIN capability: ICAP_YSCALING.

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'].

	'physicalheight'		physicalheight		The maximum physical height (Y-axis) the source can acquire (measured in units of ICAP_UNITS). Corresponding TWAIN capability: ICAP_PHYSICALHEIGHT.
	'physicalwidth'		physicalwidth		The maximum physical width (X-axis) the source can acquire (measured in units of ICAP_UNITS). Corresponding TWAIN capability: ICAP_PHYSICALWIDTH.
	'revision'		revision		The revision number of the HALCON TWAIN interface.
	'xnativeresolution'		xnativeresolution		The native optical resolution along the X-axis of the device being controlled by the source. Corresponding TWAIN capability: ICAP_XNATIVERESOLUTION.
	'ynativeresolution'		ynativeresolution		The native optical resolution along the Y-axis of the device being controlled by the source. Corresponding TWAIN capability: ICAP_YNATIVERESOLUTION.

Release Notes

• Revision 3.3 (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.2 (Jul 27, 2007):
  • Bugfix to allow the call of info_framegrabber(..., 'info_boards', ..., ...) even if the device is already open.
• Revision 3.1 (Jun 29, 2007):
  • Bugfix in info_framegrabber(..., 'info_boards', ..., ...) to prevent a crash in case of device names with a length of a multitude of 16.
• Revision 3.0 (May 15, 2007):
  • HALCON 8.0 version of the interface (included in HALCON 8.0 DVD).
• Revision 2.6 (Dec 15, 2006):
  • Bugfix in open_framegrabber to enable the interface to work also in console applications.
  • info_framegrabber returns all available device names now.
• Revision 2.5 (Apr 18, 2006):
  • Bugfix in opening the source manager's dialog box.
• Revision 2.4 (Mar 31, 2005):
  • HALCON 7.1 version of the interface (included in HALCON 7.1 CD).
  • Support of 16 bit gray scale and 48 bit color images.
  • Support of the file and memory transfer modes. Thus, the parameter 'xfermech' is now adjustable via set_framegrabber_param.
  • New parameter 'lightpath'.
  • Bugfix of possible incorrect pixel order after acquisition of a black and white image.
• Revision 2.3 (Dec 16, 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.2 (Oct 30, 2003):
  • HALCON 7.0 version of the interface (included in HALCON 7.0 CD).
  • Bugfix in canceling a grab.
• Revision 2.1 (Nov 14, 2001):
  • HALCON 6.1 version of the interface (included in HALCON 6.1 CD).
  • Bugfix enables grabbing of single channel gray scale images.
• Revision 2.0 (Sep 5, 2000):
  • Adaptation to the HALCON 6.0 frame grabber integration interface.
• Revision 1.4 (Mar 25, 1999):
  • HALCON 5.2 version of the interface (included in the HALCON 5.2 CD).
  • First official release.