Virtual Image Acquisition Interface (File Interface)

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

The HALCON virtual image acquisition interface allows you to load images and image sequences from files by using the regular image acquisition operators open_framegrabber, grab_image, grab_image_async and close_framegrabber. Thus, you are able to test and debug your image acquisition application without having installed a real frame grabber board or camera 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 image search path (e.g., "MyPicture", see also 'image_dir' in set_system). 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 image search path (see 'image_dir' in set_system). Usually, the sequence file has the extension ".seq" (you can also omit to specify this file extension). When the image file paths contain non-ASCII characters and the HALCON virtual image acquisition interface is used with HALCON 18.11 or newer, the sequence file should use UTF-8 for string encoding. This guarantees best interchangeability between different systems and locales. Sequence files that are not valid UTF-8 are assumed to use the local-8-bit encoding. 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. The directory name can either be given absolutely (e.g., "C:\\MyImages") or relatively to your image search path (see 'image_dir' in set_system). 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 image acquisition 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 image search path (see 'image_dir' in set_system). The AVI file has the extension ".avi" (you can also omit to specify this file extension).
  Please note that the ability of reading AVI files via the HALCON File Interface is based on the quite old Video for Windows (VfW) API. Thus, for reading AVI files you will need a VfW compatible codec. If you have trouble reading a specific AVI file we recommend to try the HALCON DirectFile Interface instead which is based on the DirectShow API.

Examples for using the HALCON virtual image acquisition interface can be found in the directory %HALCONEXAMPLES%/hdevelop/Image/Acquisition. An example for a sequence file can be found in %HALCONEXAMPLES%/images/pendulum/.

• Intel compatible PC with Windows 7 (32-bit or 64-bit) or newer, also WoW64 (using 32-bit HALCON on 64-bit Windows), Linux with kernel 2.6 (or higher) , or macOS.
• Windows: HALCON image acquisition interface hAcqFile.dll or hAcqFilexl.dll, respectively. If you have properly installed the interface, all these DLLs should reside in bin\%HALCONARCH% within the HALCON base directory %HALCONROOT% you have chosen during the installation of HALCON.
  Linux: HALCON image acquisition interface hAcqFile.so or hAcqFilexl.so, respectively. If you have properly installed the interface, the shared objects should reside in lib/$HALCONARCH within the HALCON base directory $HALCONROOT you have chosen during the installation of HALCON.
  macOS: HALCON image acquisition interface hAcqFile.dylib or hAcqFilexl.dylib, respectively. If you have properly installed the interface, the shared objects should reside in the HALCON framework /Library/Frameworks/HALCON.framework or the HALCON XL framework /Library/Frameworks/HALCONxl.framework in the Libraries subdirectory.

MVTec interfaces for digital I/O and image acquisition are always compatible to a range of HALCON versions. Therefore, the versioning scheme both describes the compatibility of the interface and also the revision of the interface itself. An interface version always consists of three numbers, separated by dots, i.e. 24.11.5. The first two numbers describe the minimum HALCON version the interface is compatible with. For the example version 24.11.5 this means that the interface is compatible with all HALCON versions since HALCON 24.11. The last number describes the revision of the interface, in this example this is revision 5.

Only when installing or updating the interface manually follow these steps:

• Windows: Extract the archive containing the interface files to the HALCON base directory %HALCONROOT% (Note: Administrator privileges may be required for this step). Additionally, you have to move the interface examples to the directory %HALCONEXAMPLES% manually.
• Linux: Extract the archive containing the interface files to the HALCON base directory $HALCONROOT.
• OS X: Extract the archive. Manually move the following files:
  • The .dylib files located in lib/x64-macosx to /Library/Frameworks/HALCON.framework/Libraries or /Library/Frameworks/HALCONxl.framework/Libraries repectively.
  • The genicam folder to /Library/Frameworks/HALCON.framework/Libraries or /Library/Frameworks/HALCONxl.framework/Libraries respectively.
  • The examples folder to the version subdirectory at /Users/Shared/Library/Application Support
  • The doc folder to the version subdirectory at /Library/Application Support

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.

Not supported by this interface.

Not supported by this interface.

Not supported by this interface.

Not supported by this interface.

Starts a new asynchronous grab. See also grab_image_start.

grab_image starts a new synchronous grab. See also grab_image. Note that the interface converts the image from the device to the desired image format specified by the parameters 'image_width', 'image_height', 'start_row', 'start_column', 'bits_per_channel', and 'color_space'.

grab_image_async returns an image and starts the next asynchronous grab. See also grab_image_async. Note that the interface converts the image from the device to the desired image format specified by the parameters 'image_width', 'image_height', 'start_row', 'start_column', 'bits_per_channel', and 'color_space'.

Not supported by this interface.

Not supported by this interface.

This operator closes the device. See also close_framegrabber.

For this interface there are the following examples available:

• file.hdev - Benchmark
• file_directory.hdev - Example for reading all images from the specified directory.
• file_sequence.hdev - Shows the usage of the virtual frame grabber with an image sequence.

• Revision 24.11.8 (Mar 6, 2026):
  • Reading avi files and calling close_framegrabber from a different thread than the one calling open_framegrabber, corrupted Windows copy-and-past functionality. This problem has been fixed.
• Revision 24.11.7 (Dec 3, 2025):
  • Opening a directory that contained unreadable files could lead to abnormal program termination. This problem has been fixed.
  • Grabbing images too large for non-XL HALCON threw error 6007 (Memory management: wrong memory type allocated). This problem has been fixed. Now, error 5504 (Image too large for this HALCON Version) is thrown.
• Revision 24.11.6 (Oct 8, 2025):
  • A Software Bill of Materials (SBOM) in the System Package Data Exchange (SPDX) format has been added next to each binary file with the same name extended by ".spdx.json".
• Revision 18.11.5 (Oct 20, 2021):
  • The distribution package of this interface now contains files providing meta information for the HDevelop example browser.
• Revision 18.11.4 (Oct 27, 2020):
  • This interface couldn't be loaded from .NET Core applications on Linux and macOS. This problem has been fixed.
• Revision 13.0.3 (Nov 30, 2018):
  • Sequence files, which list the paths of the images that has to be read one after the other, have to be encoded in UTF-8 if the interface is used with HALCON 18.11 or newer. Old sequence files, which use the current local-8-bit encoding and do not yield only strings which would also be valid UTF-8 strings, are still supported and will automatically be detected and correctly converted.
• Revision 13.0.2 (Nov 28, 2017):
  • The technical dependency from the HALCON Library has been removed.
• Revision 13.0.1 (Oct 28, 2016):
  • HALCON 13 version of the interface.
  • On Windows systems the maximum length for a path was limited to 260 characters. This problem has been fixed. Now, the maximum total path length on Windows systems is 32,767 characters.
• Revision 6.1 (Mar 13, 2015):
  • Fixed crash when grabbing files with more than four channels.
• Revision 6.0 (Oct 31, 2014):
  • HALCON 12 version of the interface.
• Revision 5.5 (Nov 27, 2013):
  • Fixed crash when reading an avi file (an undefined image format was used erroneously).
• Revision 5.4 (Sep 6, 2013):
  • Fixed crash when grabbing files with multiple channels which have different image formats.
  • Corrected documentation for parameters 'color_space', 'image_width' and 'image_height'.
• Revision 5.3 (Jun 13, 2013):
  • Bug fix in case of reading TIFF files with an alpha channel. Now an image with the proper number of channels is returned. This bug fix takes only effect in combination with HALCON 11.0.2 or higher.
  • Corrected documentation of the 'generic' parameter.
  • Improvement in open_framegrabber: Now a directory name relatively to the search path (see 'image_dir' in set_system) can be specified in parameter 'CameraType'.
• Revision 5.2 (Nov 15, 2012):
  • Corrected default search path for images in return value of info_framegrabber 'camera_type' query.
• Revision 5.1 (Jul 11, 2012):
  • Bug fix in case of reading TIFF files with an alpha channel.
• Revision 5.0 (May 15, 2012):
  • HALCON 11 version of the interface (included in HALCON 11 DVD).
  • Added support for Mac OS X 10.7.
• Revision 4.1 (Jun 16, 2009):
  • Bug fix in case of trying to read a non-existing or corrupt TIFF file.
  • HALCON 10 version of the interface (included in HALCON 10 DVD).
• Revision 4.0 (Nov 28, 2008):
  • HALCON 9.0 version of the interface (included in HALCON 9.0 DVD).
• Revision 3.1 (Aug 3, 2007):
  • Bug fix in reading all files from a directory in case that besides the specified directory name there exists a single image file with the same name.
• Revision 3.0 (May 15, 2007):
  • HALCON 8.0 version of the interface (included in HALCON 8.0 DVD).
• Revision 2.10 (Dec 14, 2006):
  • Bug fix in opening and closing an avi file multiple times.
• Revision 2.9 (Aug 14, 2006):
  • Bug fix 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):
  • HALCON 7.1 version of the interface (included in HALCON 7.1 CD).
  • Reading all image files within specified directory.
  • Bug fix 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).
  • Bug fix 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).
  • Bug fix 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):
  • Bug fix 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 integration 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 bit depths.