HALCON 6.0 General Purpose TWAIN Interface

This page provides the documentation of the HALCON general purpose TWAIN interface HFGTwain.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: 2.2

• Intel compatible PC with Windows NT 4.0 (Service Pack 4), Windows 2000 or Windows XP.
• 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\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 HFGTwain.dll or parHFGTwain.dll, respectively.
  If you have properly installed the interface, both DLLs should reside in bin\i586-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() 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	'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', '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.
	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 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., frame grabbers). 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 the corresponding HALCON variables in the 'interactive:xxx' case. If CameraType=='inches', ... the source's user interface 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; 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 interface HFGTwain.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 2.2 (October 30, 2003):
  
  • Bugfix in canceling a grab.
• Revision 2.1 (November 14, 2001):
  
  • Bugfix enables grabbing of single channel gray scale images.
• Revision 2.0 (September 5, 2000):
  
  • Adaptation to the HALCON 6.0 frame grabber interface.
• Revision 1.4 (March 25, 1999):
  
  • HALCON 5.2 version of the interface (included in the HALCON 5.2 CD).
  • First official release.