HALCON 9.0 Image Acquisition Interface for DirectShow File Reader

This page provides the documentation about the HALCON DirectFile interface for the Microsoft DirectShow File Reader application programming interface. Registered customers can download the latest revision of this interface from the MVTec WWW server.

Revision: 4.2

System Requirements

• Intel compatible PC with Windows 2000/XP/Vista/7 and DirectX 8.1 or later installed. You can check your installed DirectX version by running the dxdiag diagnosis program. Note that the HALCON DirectFile interface does not run under Windows NT 4.0.
• HALCON image acquisition interface hAcqDirectFile.dll or hAcqDirectFilexl.dll, respectively.
  If you have properly installed the interface, these DLLs should reside in bin\%HALCONARCH% within the HALCON base directory %HALCONROOT% you have chosen during the installation of HALCON. You don't need to register this DLL manually. Instead, upon the first call to open_framegrabber() the DLL performs the necessary steps itself. However, note that it causes no error if the registration fails (e.g., because the application does not have sufficient rights to write to the registry). Thus, it is possible to use hAcqDirectFilexl.dll with hAcqDirectFile.dll still registered, or vice versa, which might cause serious crashes! You can use the operator set_system('do_low_error', 'true') to show warnings in case the registration fails.

Limitations

In general, whether a file can be opened with the HALCON DirectFile interface or not strongly depends on the configuration of the system your application is running on. Typically, it is necessary that a suitable codec is installed. As a rule of thumb, when you can replay a file with the Windows Media Player it is most likely that you can also open it with the HALCON DirectFile interface.

• Only files that allow frame based positioning supported.
• Image scaling and cropping not supported.
• No LUTs.
• grab_data and grab_data_async not supported.

Description

Parameters for open_framegrabber():

	Name		'DirectFile'		The name of the HALCON image acquisition interface.
	HorizontalResolution		---		Ignored.
	VerticalResolution		---		Ignored.
	ImageWidth		---		Ignored.
	ImageHeight		---		Ignored.
	StartRow		---		Ignored.
	StartColumn		---		Ignored.
	Field		---		Ignored.
	BitsPerChannel		---		Ignored.
	ColorSpace		'gray', 'rgb'		Specify the desired color space and thus the number of image channels of the resulting HALCON image. Default: 'rgb'.
	Generic		---		Ignored.
	ExternalTrigger		---		Ignored.
	CameraType		'filename'		The camera type parameter is used to specify the name of the video file to be opened. The name of the video file can either be given absolutely (e.g., "C:\\MyImages\\MyAVIFile.avi") or relatively to your environment setting %HALCONIMAGES%.
	Device		---		Ignored.
	Port		---		Ignored.
	LineIn		---		Ignored.

Parameters for set_framegrabber_param():

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

	'first_frame'		number		The parameter returns the number of the first frame of the video stream.
	'last_frame'		number		The parameter returns the number of the last frame of the video stream.
	'revision'		revision		The revision number of the HALCON DirectFile interface.

Release Notes

• Revision 4.2 (Aug 20, 2010):
  • The image buffer size was calculated too large by a factor of 8. This bug has been fixed.
• Revision 4.1 (Sep 9, 2009):
  • Fixed bug in parameter 'frame_number' in case that multiple DirectFile acquisition handles are used simultaneously.
• Revision 4.0 (Dec 1, 2008):
  • HALCON 9.0 version of the interface (included in HALCON 9.0 DVD).
• Revision 3.1 (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.0 (May 15, 2007):
  • HALCON 8.0 version of the interface (included in HALCON 8.0 DVD).
• Revision 2.3 (Apr 27, 2007):
  • Bugfix regarding the padding of images with an odd image width.
• Revision 2.2 (Aug 14, 2006):
  • Bugfix in get_framegrabber_param('frame_number') in case of the last frame of the video stream.
• Revision 2.1 (Sep 12, 2005):
  • 64 bit Windows version available.
  • Manual registration of hAcqDirectFile.dll or parhAcqDirectFile.dll no longer necessary.
• Revision 2.0 (Sep 1, 2005):
  • First official release (included in HALCON 7.1 CD).