MVTec Software GmbH
 

Documentation

File / HALCON / MVTec Software GmbH

Virtual Image Acquisition Interface (File Interface)

Interface: File
Revision: 13.0.3
Date: 2018-11-30

General

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.

Introduction

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/.

System Requirements

  • 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.

Installation

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
    • The genicam folder to /Library/Frameworks/HALCON.framework/Libraries
    • The examples folder to the version subdirectory at /Users/Shared/Library/Application Support
    • The doc folder to the version subdirectory at /Library/Application Support

Parameters for info_framegrabber

Parameter Value List Type Kind Description
'bits_per_channel' [] Unused.
'camera_type' ['CAMFILE:', 'tif;tiff;gif;bmp;jpg;jpeg;jp2;png;pcx;pgm;ppm;pbm;xwd;avi;seq', '<example_dir>/images'] string pre-defined Syntax for file format and path.
'color_space' [] Unused.
'defaults' [1, 1, 0, 0, 0, 0, 'default', -1, 'default', -1.0, 'false', 'printer_chip/printer_chip_01', '', 1, 2] mixed pre-defined Default values for open_framegrabber.
'device' [] Unused.
'external_trigger' [] Unused.
'field' [] Unused.
'general' [] string pre-defined Information about the HALCON File interface.
'generic' [] Unsupported query.
'horizontal_resolution' 1 integer pre-defined Value list for horizontal resolution.
'image_height' [] Unsupported query.
'image_width' [] Unsupported query.
'info_boards' 'device:default' string pre-defined Pre-defined list for device.
'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 File 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 'File' string Name of the HALCON interface.
HorizontalResolution --- Ignored.
VerticalResolution --- Ignored.
ImageWidth --- Ignored.
ImageHeight --- Ignored.
StartRow --- Ignored.
StartColumn --- Ignored.
Field --- 'default' Ignored.
BitsPerChannel --- -1 Ignored.
ColorSpace --- Ignored.
Generic --- Ignored.
ExternalTrigger --- Ignored.
CameraType '<filename>' or '<directory>' 'printer_chip/printer_chip_01' string 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).
Device --- Ignored.
Port --- Ignored.
LineIn --- Ignored.

Parameters for set_framegrabber_param

Parameter Values Default Type Description
'frame_number' <number> integer Number of the next frame to be grabbed by grab_image or grab_image_async. AVI format only.

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
'bits_per_channel' <default> -1 integer pre-defined The value is not used, so a default value is returned.
'camera_type' '<filename>' 'printer_chip/printer_chip_01' string pre-defined Current camera type.
'color_space' ['gray', 'multichannel'] 'gray' string pre-defined 'gray' is used for 1-channel images, 'multichannel' otherwise.
'device' '<filename>' string dynamic Returns the file name of the next image.
'external_trigger' '<default>' 'false' string pre-defined The value is not used, so a default value is returned.
'field' '<default>' 'progressive' string pre-defined The value is not used, so a default value is returned.
'first_frame' <number> integer dynamic Number of the first frame of the AVI video stream. AVI format only.
'frame_number' <number> integer dynamic Number of the next frame to be grabbed by grab_image or grab_image_async. AVI format only.
'generic' <default> -1 mixed pre-defined The value is not used, so a default value is returned.
'horizontal_resolution' <default> 1 integer pre-defined The value is not used, so a default value is returned.
'image_height' <height> 0 integer pre-defined Height of the image in pixels.
'image_width' <width> 0 integer pre-defined Width of the image in pixels.
'last_frame' <number> integer dynamic Number of the last frame of the AVI video stream. AVI format only.
'line_in' <default> 2 integer pre-defined The value is not used, so a default value is returned.
'name' 'File' string pre-defined Name of the HALCON interface.
'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 File interface.
'start_column' <default> 0 integer pre-defined The value is not used, so a default value is returned.
'start_row' <default> 0 integer pre-defined The value is not used, so a default value is returned.
'vertical_resolution' <default> 1 integer pre-defined The value is not used, so a default value is returned.

Operator set_framegrabber_lut

Not supported by this interface.

Operator get_framegrabber_lut

Not supported by this interface.

Operator set_framegrabber_callback

Not supported by this interface.

Operator get_framegrabber_callback

Not supported by this interface.

Operator grab_image_start

Starts a new asynchronous grab. See also grab_image_start.

Operator grab_image

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

Operator grab_image_async

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

Operator grab_data

Not supported by this interface.

Operator grab_data_async

Not supported by this interface.

Operator close_framegrabber

This operator closes the device. See also close_framegrabber.

HDevelop Examples

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.

Release Notes

  • 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.
    • 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 (July 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.
  • 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'.