HALCON 5.2 general purpose TWAIN interface

This document provides the documentation of the HALCON general purpose TWAIN interface HTwain.dll. With this interface you can acquire images from arbitrary image devices which support the TWAIN norm (e.g., scanners or frame grabbers). Registered customers can download the latest revision of this interface from the MVTec WWW server.

Revision: 1.5

• Intel compatible PC with Windows NT 4.0 (Service Pack 3).
• 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 (typically c:\Winnt) and are shipped together with the HALCON distribution (you can find them in the directory misc\i486-nt4 on the HALCON CD). Attention: Make sure that you donīt use an older version of the DLLs, because you might run into severe problems in that case.
• HALCON TWAIN interface HTwain.dll.
  If you have properly installed the interface, HTwain.dll should reside in bin\i486-nt4 within the HALCON base directory %HALCONROOT% you have chosen during the installation of HALCON.

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

Parameters for open_framegrabber():

	Name	'HTwain'	The name of the HALCON TWAIN interface.
	FGWidth	-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 generic 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 FGWidth / (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 generic parameter). E.g., using a scanner with 'inches' as generic and 200 as FGWidth, 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.
	FGHeight	-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 generic 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 FGHeight / (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 generic parameter). E.g., using a scanner with 'inches' as generic and 200 as FGWidth, 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.
	Width	-1, width	The width of the desired image part in pixels. Attention: The image part is only set if Width, Height, StartRow, and StartColumn are all different from -1. Use '-1' if you donīt want this value to be set. Default: -1.
	Height	-1, height	The height of the desired image part in pixels. Attention: The image part is only set if Width, Height, 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 Width, Height, 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 Width, Height, StartRow, and StartColumn are all different from -1. Use '-1' if you donīt want this value to be set. Default: -1.
	Field	--	Ignored.
	Bits	-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', 'none'	Sets the type of pixel data according to the TWAIN norm. Use 'none' if you donīt want this value to be set. Default: 'none'.
	Gain	---	Ignored.
	ExternalTrigger	---	Ignored.
	Generic	'interactive', 'interactive:inches', 'interactive:centimeters', 'interactive:picas', 'interactive:points', 'interactive:twips', 'interactive:pixels', 'inches', 'centimeters', 'picas', 'points', 'twips', 'pixels'	The generic parameter is used to specify whether the image is acquired interactively via the sourceīs user interface 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., framegrabbers). When saying 'interactive' or 'interactive:xxx' the source's user interface is displayed each time you acquire an image and the parameters are written back to fginst->width, fginst->height, ... in the 'interactive:xxx' case. If 'generic'=='inches', ... the sourceīs user interface is not displayed and the parameters are set manually to the values YOU provide (see FGWidth, FGHeight, ...). 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; in all other cases the interface will try to open a source with the specified name. Default: 'interactive'.
	Port	---	Ignored.
	LineIn	---	Ignored.

Parameters for set_framegrabber_param():

	'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.
	'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.
	'xscaling'	> 0.0	Scaling in x-direction. Corresponding TWAIN capability: ICAP_XSCALING.
	'yscaling'	> 0.0	Scaling in y-direction. Corresponding TWAIN capability: ICAP_YSCALING.
	'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.
	'xresolution'	> 0.0	X-axis resolution of the source (measured in units of pixels per unit). Corresponding TWAIN capability: ICAP_XRESOLUTION.
	'yresolution'	> 0.0	Y-axis resolution of the source (measured in units of pixels per) unit. Corresponding TWAIN capability: ICAP_YRESOLUTION.
	'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.
	'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.
	'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'.

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

	'revision'	revision	The revision number of the HALCON framegrabber interface HTwain.dll.
	'xfermech'	'native', 'file', 'memory'	Transfer mechanism of the source. Corresponding TWAIN capability: ICAP_XFERMECH.
	'physicalwidth'	physicalwidth	The maximum physical width (X-axis) the source can acquire (measured in units of ICAP_UNITS). Corresponding TWAIN capability: ICAP_PHYSICALWIDTH.
	'physicalheight'	physicalheight	The maximum physical height (Y-axis) the source can acquire (measured in units of ICAP_UNITS). Corresponding TWAIN capability: ICAP_PHYSICALHEIGHT.
	'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.

• Revision 1.5 (November 14, 2001):
  
  • Bugfix enables grabbing of single channel gray scale images.
• Revision 1.4 (March 25, 1999):
  
  • HALCON 5.2 version of the interface (included in the HALCON 5.2 CD).
  • First official release.