HALCON 7.0 Virtual Frame Grabber Interface

This page provides the documentation of the HALCON virtual frame grabber interface which allows reading images from file(s) by using the regular operators of the HALCON frame grabber interface. Registered customers can download the latest revision of this interface from the MVTec WWW server.

Revision: 2.10

Introduction

The HALCON virtual frame grabber interface allows you to load images and image sequences from files by using the regular frame grabber operators open_framegrabber, grab_image, grab_image_async and close_framegrabber. Thus, you are able to test and debug your frame grabber application without having installed a real frame grabber board in your computer. All you have to do is to choose "File" in the parameter Name of open_framegrabber and to give the proper file name of the image(s) to be loaded in the parameter CameraType. The CameraType parameter can be either the name of a

• Single image: In this case every subsequent call of the operator grab_image or grab_image_async will load this image file. Note that the image name can either be given absolutely (e.g., "C:\\MyImages\\MyPicture") or relatively to your environment setting %HALCONIMAGES% (e.g., "MyPicture"). Furthermore, you can also choose to specify the full image name (e.g., "MyPicture.tif") or you can omit the file extension (e.g., "MyPicture"). In the latter case HALCON automatically appends the usual file extensions of the supported image formats (tiff, tif, jpg, jpeg, png, pbm, pnm, pgm, ppm, gif, bmp, pcx, ras, ima, xwd).
• Sequence file: A sequence file is a file which contains in each line the name of a single image file. In this case the first call of the operator grab_image or grab_image_async, respectively, will load the first image file, the second call will load the second one etc. In case of a failure loading an image an error will be returned and the next call will load the succeeding file. After the last entry in the sequence file has been reached the next grab will start with the first image file again (looping). Both the name of the sequence file as the image file names within the sequence file can either be given absolutely (e.g., "C:\\MyImages\\MySequence") or relatively to your environment setting %HALCONIMAGES%. Usually, the sequence file has the extension ".seq" (you can also omit to specify this file extension). Note that you can query the actual file name of the next image by calling get_framegrabber_param(...,'device',...).
• Directory name: If you specify a valid directory name in the parameter CameraType all files in this directory with one of the supported image file extensions (tiff, tif, jpg, jpeg, png, pbm, pnm, pgm, ppm, gif, bmp, pcx, ras, ima, xwd) are used one after the other in the following calls of grab_image or grab_image_async. In case of a failure loading an image an error will be returned and the next grab will load the succeeding file. After the grabbing of all available images the next grab will start with the first image file again (looping). Note that you can query the actual file name of the next image by calling get_framegrabber_param(...,'device',...).
• AVI file: Under Windows the virtual frame grabber interface also provides reading video streams in AVI file format. In this case the first call of the operator grab_image or grab_image_async respectively, will load the first image file, the second call will load the second one etc. After the last frame of the AVI file has been reached the next grab will start with the first frame again (looping). The name of the AVI file can either be given absolutely (e.g., "C:\\MyImages\\MyAVIFile") or relatively to your environment setting %HALCONIMAGES%. The AVI file has the extension ".avi" (you can also omit to specify this file extension).

System Requirements

• HALCON virtual frame grabber interface HFGFile.dll for Windows systems (or parHFGFile.dll for use with Parallel HALCON) or HFGFile.so for most UNIX systems, respectively. Depending on your system architecture, this file should reside either in bin\%ARCHITECTURE% (Windows) or in lib/$ARCHITECTURE (UNIX systems) within the HALCON base directory %HALCONROOT% you have chosen during the installation of HALCON.

Description

Parameters for open_framegrabber():

	Name	'File'	The name of the HALCON frame grabber interface.
	HorizontalResolution	---	Ignored.
	VerticalResolution	---	Ignored.
	ImageWidth	---	Ignored.
	ImageHeight	---	Ignored.
	StartRow	---	Ignored.
	StartColumn	---	Ignored.
	Field	---	Ignored.
	BitsPerChannel	---	Ignored.
	ColorSpace	---	Ignored.
	Gain	---	Ignored.
	ExternalTrigger	---	Ignored.
	CameraType	'filename'	The camera type parameter is used to specify the name of either a single image file, an AVI file (Windows only!), a sequence file containing the file names of a whole image sequence, or a directory (see introduction above). Default: 'fabrik'.
	Device	---	Ignored.
	Port	---	Ignored.
	LineIn	---	Ignored.

Parameters for set_framegrabber_param():

	'frame_number'		number		AVI format only. The parameter sets the number of the next frame to be grabbed by grab_image or grab_image_async.

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.

	'first_frame'		number		AVI format only. The parameter returns the number of the first frame of the AVI video stream.
	'last_frame'		number		AVI format only. The parameter returns the number of the last frame of the AVI video stream.
	'revision'		revision		Revision of the HALCON virtual frame grabber interface.

Release Notes

• Revision 2.10 (Dec 14, 2006):
  
  • Bugfix in opening and closing an avi file multiple times.
• Revision 2.9 (Aug 14, 2006):
  
  • Bugfix in get_framegrabber_param('frame_number') in case of the last frame of the AVI video stream (Windows only).
• Revision 2.8 (Jul 27, 2005):
  
  • Swapped search order for .avi and .seq files: If there is an .avi file as well as a .seq file with the same name, the .seq file is opened.
  • AVI files: Allow case insensitive file extensions.
  • AVI files: Support of bitmaps without color maps.
  • AVI files: Support of 16bit RGB bitmaps
• Revision 2.7 (Jun 24, 2004):
  
  • Reading all image files within specified directory.
  • Bugfix in accessing AVI files (Windows only).
• Revision 2.6 (Jun 5, 2003):
  
  • HALCON 7.0 version of the interface (included in HALCON 7.0 CD).
  • Bugfix in accessing the same file simultaneously.
• Revision 2.5 (Dec 9, 2002):
  
  • Attention: This revision requires at least HALCON 6.1.1.
  • New: support of PNG image format.
  • Improved timing behavior when reading from sequence files.
  • Improvement of AVI file error treatment (Windows only).
• Revision 2.4 (Apr 25, 2002):
  
  • HALCON 6.1 version of the interface (included in HALCON 6.1 CD).
  • Bugfix in correct handling of sequence files and file extensions.
• Revision 2.3 (Jun 22, 2001):
  
  • New: grabbing of '.ima' file types.
  • Grab calls step over load failures of images in sequence files.
• Revision 2.2 (Dec 15, 2000):
  
  • Bugfix in reading avi files with 24 bpp (Windows only).
• Revision 2.1 (Oct 26, 2000):
  
  • Support of AVI file format (Windows only).
  • New parameters 'frame_number', 'first_frame', and 'last_frame'.
• Revision 2.0 (Jul 4, 2000):
  
  • Adaptation to the HALCON 6.0 frame grabber interface.
  • Renaming from 'VirtualFG' into 'File'.
  • Support also of grab_image_async (same behaviour as grab_image).
  • Images within a image sequence are allowed to have different image sizes und bitdepths.
• Revision 1.27 (Mar 29, 1999):
  
  • HALCON 5.2 version of the interface (included in the HALCON 5.2 CD).
  • Automatic restart from the beginning in a sequence file when end is reached (looping).
• Revision 1.26 (Mar 28, 1999):
  
  • New parameter 'revision'.