Dokumentation

Image Acquisition Interface for TWAIN compatible devices

Interface:	TWAIN
Revision:	13.0.1
Date:	2016-10-28
HALCON Version:	13.0

General

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.

System Requirements

Intel compatible PC with Windows 7 (32-bit) or newer that is also supported by the vendor-specific SDK, also WoW64 (using 32-bit HALCON on 64-bit Windows).
Windows x86/x64: TWAIN DLLs TWAIN_32.DLL and TWAIN.DLL (version 1.6.0.3 or higher).
These DLLs should reside in the Windows directory.
HALCON TWAIN interface hAcqTwain.dll or hAcqTwainxl.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. See the twain_manual.hdev HDevelop example for further information.
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.
Automatic Document Feeder: this functionality can be enabled using the parameter 'automatic_document_feeder'. See also the parameters: 'xfercount', 'duplexenabled' and 'feederloaded'. Notice that WIA drivers may not work for scanners that have automatic document feeders, therefore you should install and use your scanner vendor's TWAIN driver for best results. For further information, see the twain_automatic_document_feeder.hdev HDevelop example.

Attention: To run your device in the 'interactive:xxx' or manual mode the device's TWAIN driver has to support several features required by the HALCON interface. Unfortunately, nearly all drivers deliver meaningless values very often. The HALCON interface will give you an error message in these cases. If you run into problems you should contact the vendor of your TWAIN device, too.

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.

Parameters for info_framegrabber

Parameter	Value List	Type	Kind	Description
'bits_per_channel'	[-1, 1, 8]	integer	pre-defined	Values for bits per channel.
'camera_type'	['interactive', 'interactive:inches', 'interactive:centimeters', 'interactive:picas', 'interactive:points', 'interactive:twips', 'interactive:pixels', 'inches', 'centimeters', 'picas', 'points', 'twips', 'pixels']	string	pre-defined	Pre-defined list with possible values for camera type.
'color_space'	['none', 'bw', 'gray', 'rgb', 'palette', 'cmy', 'cmyk', 'yuv', 'yuvk', 'ciexyz']	string	pre-defined	Values for color space.
'defaults'	[-1, -1, 0, 0, 0, 0, 'interlaced', -1, 'rgb', -1.0, 'false', 'interactive', 'interactive', 1, -1]	mixed	pre-defined	Default values for open_framegrabber.
'device'	['interactive', 'automatic']	string	pre-defined	Pre-defined list of possible device IDs.
'external_trigger'	[]			Unused.
'field'	[]			Unused.
'general'	[]	string	pre-defined	Information about the HALCON TWAIN interface.
'generic'	['', 'layout_mode=<mode>']	string	pre-defined	Value list for the Generic parameter.
'horizontal_resolution'	1	integer	pre-defined	Value list for horizontal resolution.
'image_height'	[]			Unsupported query.
'image_width'	[]			Unsupported query.
'info_boards'	['device:<device_id>']	string	dynamic	A list of the available devices.
'parameters'	['<parameters>']	string	pre-defined	Pre-defined parameters of the HALCON interface.
'parameters_readonly'	['<parameters>']	string	pre-defined	Pre-defined read-only parameters of the HALCON interface.
'parameters_writeonly'	['<parameters>']	string	pre-defined	Pre-defined write-only parameters of the HALCON interface.
'port'	[]			Unused.
'revision'	'<revision>'	string	pre-defined	Revision number of the TWAIN interface.
'start_column'	[]			Unsupported query.
'start_row'	[]			Unsupported query.
'vertical_resolution'	1	integer	pre-defined	Value list for vertical resolution.

Parameters for open_framegrabber

Parameter	Values	Default	Type	Description
Name	'TWAIN'		string	Name of the HALCON interface.
HorizontalResolution	-1, <resolution/scaling>	-1	integer	Desired image x-resolution/scaling. This value is only evaluated if you set '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.
VerticalResolution	-1, <resolution/scaling>	-1	integer	Desired image y-resolution/scaling. This value is only evaluated if you set '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.
ImageWidth	-1/0, <width>	-1/0	integer	Width of the desired image part in pixels. Attention: The image part is only set if ImageWidth and ImageHeight are bigger than 0 and StartRow and StartColumn are bigger than -1. Use '-1' or '0' if you don't want this value to be set.
ImageHeight	-1/0, <height>	-1/0	integer	Height of the desired image part in pixels. Attention: The image part is only set if ImageWidth and ImageHeight are bigger than 0 and StartRow and StartColumn are bigger than -1. Use '-1' or '0' if you don't want this value to be set.
StartRow	-1, <row>	-1/0	integer	Row coordinate of the upper left pixel of the desired image part. Notice that some device drivers do not support setting a value different from 0. Attention: The image part is only set if ImageWidth and ImageHeight are bigger than 0 and StartRow and StartColumn are bigger than -1. Use '-1' or '0' if you don't want this value to be set.
StartColumn	-1, <column>	-1/0	integer	Column coordinate of the upper left pixel of the desired image part. Notice that some device drivers do not support setting a value different from 0. Attention: The image part is only set if ImageWidth and ImageHeight are bigger than 0 and StartRow and StartColumn are bigger than -1. Use '-1' or '0' if you don't want this value to be set.
Field	---			Ignored.
BitsPerChannel	-1, <bits>	-1	integer	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.
ColorSpace	'none', 'bw', 'ciexyz', 'cmy', 'cmyk', 'gray', 'palette', 'rgb', 'yuv', 'yuvk'	'rgb'	string	Type of pixel data according to the TWAIN norm.
Generic	'', 'layout_mode=<mode>', -1	-1	mixed	Generic parameters: layout_mode: This setting makes it possible to work with some device drivers that define the TWAIN frame layout as the top-left coordinate and the size (width and height) of the image part, instead of the top-left coordinate and the bottom-right coordinate of the image part. Valid values are: 'size': to indicate that the frame layout is defined as the top-left coordinate and the size (width and height) of the image part. Please, enable this value if you notice that the image part cannot be consistently set in open_framegrabber. 'coordinate': default value. The frame layout is defined as the top-left coordinate and the bottom-right coordinate of the image part.
ExternalTrigger	---			Ignored.
CameraType	'interactive', 'interactive:inches', 'interactive:centimeters', 'interactive:picas', 'interactive:points', 'interactive:twips', 'interactive:pixels', 'inches', 'centimeters', 'picas', 'points', 'twips', 'pixels'	'interactive'	string	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, ...).
Device	'interactive', 'automatic', '<device>'	'interactive'	string	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`(...'info_boards'...)` returns a list of available devices.
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.

Parameter	Values	Default	Type	Description
'automatic_document_feeder'	'enable', 'disable'	'disable'	string	Enables the 'Automatic Document Feeder' functionality. If enabled CAP_XFERCOUNT is set to -1 (multiple images are fed and scanned). If you wish to feed and scan only 1 image in each grab_image, set 'xfercount' to 1 after enabling the 'automatic_document_feeder'. For further information, see twain_automatic_document_feeder.hdev. Set/GetCapValue->CAP_FEEDERENABLED, CAP_AUTOSCAN, CAP_XFERCOUNT
'bitdepth'	1, 2, ...		integer	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). Set/GetCapValue->ICAP_BITDEPTH
'brightness'	-1000.0 - 1000.0		float	Brightness value of the source. Set/GetCapValue->ICAP_BRIGHTNESS
'contrast'	-1000.0 - 1000.0		float	Contrast value of the source. Set/GetCapValue->ICAP_CONTRAST
'duplexenabled'	'enable', 'disable'	'disable'	string	If enabled, the scanner scans both sides of a paper; otherwise, the scanner will scan only one side of the image. Notice that in case of using the double-sided scan mode, 'xfercount' has to be set to 2 or -1. Set/GetCapValue->CAP_DUPLEXENABLED
'gamma'	<gamma>		float	Gamma correction value for the image data. Set/GetCapValue->ICAP_GAMMA
'highlight'	0.0 - 255.0		float	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. Set/GetCapValue->ICAP_HIGHLIGHT
'lightpath'	'reflective', 'transmissive'	'reflective'	string	If your scanner provides a light source for transmitted light scanning (e.g., a film scanner) you can select 'transmissive' mode for transparent material. Set/GetCapValue->ICAP_LIGHTPATH
'pixeltype'	'gray', 'rgb', 'palette', 'cmy', 'cmyk', 'yuv', 'yuvk', 'ciexyz'		string	Type of pixel data that a source is capable of acquiring. Set/GetCapValue->ICAP_PIXELTYPE
'shadow'	0.0 - 255.0		float	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. Set/GetCapValue->ICAP_SHADOW
'units'	'centimeters', 'inches', 'picas', 'pixels', 'points', 'twips'		string	Unless a quantity is dimensionless or uses a specified unit of measure, units determines the unit of measure for all quantities. Set/GetCapValue->ICAP_UNITS
'userinterface'	'hide', 'show'	'show'	string	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.
'xfercount'	-1, 1, 2, ...	-1	integer	Number of images to be transferred per session if the 'Automatic Document Feeder' functionality is used. If set to -1, the application is willing to transfer multiple images. See also 'automatic_document_feeder'. Notice that in case of using the double-sided scan mode ('duplexenabled'), 'xfercount' has to be set to 2 or -1. Set/GetCapValue-> CAP_XFERCOUNT
'xfermech'	'file', 'memory', 'native'		string	Specifies the transfer mechanism from the source to the interface. 'native': the entire image will be transferred. 'memory': the image will be delivered in parts of the size preferred by the source. 'file': 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. Set/GetCapValue->ICAP_XFERMECH
'xresolution'	>0		float	X-axis resolution of the source (measured in units of pixels per unit). Set/GetCapValue->ICAP_XRESOLUTION
'xscaling'	>0		float	Scaling in x-direction. Set/GetCapValue->ICAP_XSCALING
'yresolution'	>0		float	Y-axis resolution of the source (measured in units of pixels per) unit. Set/GetCapValue->ICAP_YRESOLUTION
'yscaling'	>0		float	Scaling in y-direction. Set/GetCapValue->ICAP_YSCALING

Parameters for get_framegrabber_param

There may exist additional read-only parameters with the following postfixes:

'_description': These parameters provide the tool-tip of the corresponding parameter as a string.
'_range': These parameters provide the minimum, maximum, step width, and default values for the corresponding integer or float parameter as a tuple with 4 elements, e.g., get_framegrabber_param(.., 'Shutter_range', ..) will return the output tuple [min, max, step, default].
'_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'].

All these postfixed parameter names are not returned when calling info_framegrabber(.., 'parameters', ..) and are used to enable the easy parameterization via a generic graphical user interface, particularly the HDevelop Image Acquisition Assistant.

Parameter	Values	Default	Type	Kind	Description
'automatic_document_feeder'	'enable', 'disable'	'disable'	string	pre-defined	Enables the 'Automatic Document Feeder' functionality. If enabled CAP_XFERCOUNT is set to -1 (multiple images are fed and scanned). If you wish to feed and scan only 1 image in each grab_image, set 'xfercount' to 1 after enabling the 'automatic_document_feeder'. For further information, see twain_automatic_document_feeder.hdev. Set/GetCapValue->CAP_FEEDERENABLED, CAP_AUTOSCAN, CAP_XFERCOUNT
'bitdepth'	1, 2, ...		integer	pre-defined	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). Set/GetCapValue->ICAP_BITDEPTH
'bits_per_channel'	-1, 1, 8	-1	integer	pre-defined	Number of bits per channel of the resulting HALCON image. In case of -1 the current bit depth of the camera is used. By specifying a value greater than 8 the grabbed images are delivered as uint2 images.
'brightness'	-1000.0 - 1000.0		float	dynamic	Brightness value of the source. Set/GetCapValue->ICAP_BRIGHTNESS
'camera_type'	'<camera_type>'	'interactive'	string	pre-defined	Current camera type.
'color_space'	'none', 'bw', 'ciexyz', 'cmy', 'cmyk', 'gray', 'palette', 'rgb', 'yuv', 'yuvk'	'rgb'	string	pre-defined	Desired color space and thus the number of image channels of the resulting HALCON image.
'contrast'	-1000.0 - 1000.0		float	dynamic	Contrast value of the source. Set/GetCapValue->ICAP_CONTRAST
'device'	'interactive', 'automatic', '<device>'	'interactive'	string	pre-defined	Current device ID.
'duplexenabled'	'enable', 'disable'	'disable'	string	pre-defined	If enabled, the scanner scans both sides of a paper; otherwise, the scanner will scan only one side of the image. Notice that in case of using the double-sided scan mode, 'xfercount' has to be set to 2 or -1. Set/GetCapValue->CAP_DUPLEXENABLED
'external_trigger'	<default>	'false'	string	pre-defined	The value is not used, so a default value is returned.
'feederloaded'	1, 0		integer	pre-defined	Reflects whether there are documents loaded in the Source's feeder. GetCapValue->CAP_FEEDERLOADED
'field'	'<default>'	'interlaced'	string	pre-defined	The value is not used, so a default value is returned.
'gamma'	<gamma>		float	dynamic	Gamma correction value for the image data. Set/GetCapValue->ICAP_GAMMA
'generic'	'', 'layout_mode=<mode>', -1	-1	mixed	pre-defined	Values of the Generic parameter.
'highlight'	0.0 - 255.0		float	dynamic	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. Set/GetCapValue->ICAP_HIGHLIGHT
'horizontal_resolution'	<resolution>	-1	integer	pre-defined	Current value of horizontal resolution.
'image_height'	<height>	-1/0	integer	pre-defined	Current height of the HALCON image.
'image_width'	<width>	-1/0	integer	pre-defined	Current width of the HALCON image.
'layout_mode'	'coordinate', 'size'	'coordinate'	string	pre-defined	Value of the layout_mode generic parameter specified in open_framegrabber.
'lightpath'	'reflective', 'transmissive'	'reflective'	string	pre-defined	If your scanner provides a light source for transmitted light scanning (e.g., a film scanner) you can select 'transmissive' mode for transparent material. Set/GetCapValue->ICAP_LIGHTPATH
'line_in'	<default>	-1	integer	pre-defined	The value is not used, so a default value is returned.
'name'	'TWAIN'		string	pre-defined	Name of the HALCON interface.
'physicalheight'	<physicalheight>		float	dynamic	Maximum physical height (Y-axis) the source can acquire (measured in units of ICAP_UNITS). GetCapValue->ICAP_PHYSICALHEIGHT
'physicalwidth'	<physicalwidth>		float	dynamic	The maximum physical width (X-axis) the source can acquire (measured in units of ICAP_UNITS). GetCapValue->ICAP_PHYSICALWIDTH
'pixeltype'	'gray', 'rgb', 'palette', 'cmy', 'cmyk', 'yuv', 'yuvk', 'ciexyz'		string	dynamic	Type of pixel data that a source is capable of acquiring. Set/GetCapValue->ICAP_PIXELTYPE
'port'	<default>	1	integer	pre-defined	The value is not used, so a default value is returned.
'revision'	'<revision>'		string	pre-defined	Revision number of the TWAIN interface.
'shadow'	0.0 - 255.0		float	dynamic	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. Set/GetCapValue->ICAP_SHADOW
'start_column'	<column>	-1/0	integer	pre-defined	Returns the current start column of the HALCON image.
'start_row'	<row>	-1/0	integer	pre-defined	Returns the current start row of the HALCON image.
'units'	'centimeters', 'inches', 'picas', 'pixels', 'points', 'twips'		string	dynamic	Unless a quantity is dimensionless or uses a specified unit of measure, units determines the unit of measure for all quantities. Set/GetCapValue->ICAP_UNITS
'userinterface'	'hide', 'show'	'show'	string	pre-defined	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.
'vertical_resolution'	<resolution>	-1	integer	pre-defined	Current value of vertical resolution.
'xfercount'	-1, 1, 2, ...	-1	integer	pre-defined	Number of images to be transferred per session if the 'Automatic Document Feeder' functionality is used. If set to -1, the application is willing to transfer multiple images. See also 'automatic_document_feeder'. Notice that in case of using the double-sided scan mode ('duplexenabled'), 'xfercount' has to be set to 2 or -1. Set/GetCapValue-> CAP_XFERCOUNT
'xfermech'	'file', 'memory', 'native'		string	dynamic	Specifies the transfer mechanism from the source to the interface. 'native': the entire image will be transferred. 'memory': the image will be delivered in parts of the size preferred by the source. 'file': 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. Set/GetCapValue->ICAP_XFERMECH
'xnativeresolution'	<xnativeresolution>		float	dynamic	Native optical resolution along the X-axis of the device being controlled by the source. GetCapValue->ICAP_XNATIVERESOLUTION
'xresolution'	>0		float	dynamic	X-axis resolution of the source (measured in units of pixels per unit). Set/GetCapValue->ICAP_XRESOLUTION
'xscaling'	>0		float	dynamic	Scaling in x-direction. Set/GetCapValue->ICAP_XSCALING
'ynativeresolution'	<ynativeresolution>		float	dynamic	Native optical resolution along the Y-axis of the device being controlled by the source. GetCapValue->ICAP_YNATIVERESOLUTION
'yresolution'	>0		float	dynamic	Y-axis resolution of the source (measured in units of pixels per) unit. Set/GetCapValue->ICAP_YRESOLUTION
'yscaling'	>0		float	dynamic	Scaling in y-direction. Set/GetCapValue->ICAP_YSCALING