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.

• Intel compatible PC with Windows 7 (32-bit or 64-bit) or newer and DirectX 8.1 or later installed. You can check your installed DirectX version by running the dxdiag diagnosis program.
• HALCON image acquisition interface hAcqDirectFile.dll or hAcqDirectFilexl.dll, respectively.
  If you have properly installed the interface, these DLLs should reside in %HALCONROOT%\bin\%HALCONARCH%. You don't need to register this DLL manually. Instead, the DLL checks the current registration and performs the necessary steps itself if necessary. If it does not have sufficient permissions to do this it will run regsvr32.exe with elevated privileges which will usually require user interaction.
• Third-party library MediaInfo.dll version 25.07 which should also reside in %HALCONROOT%\bin\%HALCONARCH% if you have properly installed the interface. Note that this DLL is not crucial for image acquisition, it is only required for calling get_framegrabber_param(..., 'media_info', ...).

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.

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 GraphEdit it is most likely that you can also open it with the HALCON DirectFile interface. On a 64 bit operating system the HALCON architecture (32 or 64 bit) must match the architecture of the codec. For detailed information about the codecs on your system, see the Technical Support Information at the About dialog of Windows Media Player.

• Only files that allow frame based positioning supported.
• Image scaling and cropping not supported.

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:

• directfile.hdev - Benchmark

This interface depends on third-party libraries. See the file third_party_directfile.txt in the HALCON base directory for copyright and license information. Libraries are used without modifications unless explicitly stated in the file.

You can request the source for those third-party libraries licensed under GPL or LGPL via email to info@mvtec.com with the subject "Request source code of third-party libraries".

• Revision 24.11.7 (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".
  • MediaInfo library has been updated to version 25.07.
• Revision 20.11.6 (Aug 8, 2023):
  • third_party_directfile.txt now contains links to the corresponding software location. See also Usage of third-party libraries.
• 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 (Feb 27, 2020):
  • The file third_party_directfile.txt has been added to the distribution package of this interface.
  • Querying the parameter 'media_info' could lead to a crash of HALCON with certain video files. This problem has been fixed.
• Revision 13.0.2 (Aug 13, 2018):
  • The technical dependency from the HALCON Library has been removed.
  • When calling the parameter 'media_info' if the information of the file contained UNICODE characters this was not handled correctly. This problem has been fixed.
• 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.3 (Aug 26, 2016):
  • info_framegrabber(..., 'info_boards', ...) now returns a list of all DirectShow filters installed on the system.
  • get_framegrabber_param(..., 'filter_graph', ...) now returns a list of the DirectShow filters used by the active filter graph.
  • get_framegrabber_param(..., 'media_info', ...) now returns information about the source file retrieved by the third-party library MediaInfo (see the System Requirements).
  • open_framegrabber now succeeds as soon as the source file has been loaded. If no working filter graph can be built, get_framegrabber_param(..., 'media_info', ...) can serve to query useful information about the file in order to find and install a suitable codec.
  • If open_framegrabber was called with a nonexistent file, it returned with H_ERR_FGNV (#5304) instead of H_ERR_FNF (#5200). This problem has been fixed.
  • File paths containing multi-byte characters could not be opened on Asian systems. This problem has been fixed.
  • Setting an empty value in set_framegrabber_param led to a crash. This problem has been fixed.
• Revision 6.2 (Jul 22, 2015):
  • First call of open_framegrabber failed. This problem has been fixed.
  • The call of info_framegrabber(..., 'general', ...) crashed if quartz.dll was available. This problem has been fixed.
• Revision 6.1 (Feb 23, 2015):
  • Fixed bug reading UTF8 encoded file names.
• Revision 6.0 (Oct 31, 2014):
  • HALCON 12 version of the interface.
  • Improved DLL registration process in case the interface is not already registered correctly.
• Revision 5.0 (May 15, 2012):
  • HALCON 11 version of the interface (included in HALCON 11 DVD).
• Revision 4.2 (Aug 20, 2010):
  • The image buffer size was calculated too large by a factor of 8. This bug has been fixed.
  • HALCON 10 version of the interface (included in HALCON 10 DVD).
• 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 (Nov 28, 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):
  • Bug fix regarding the padding of images with an odd image width.
• Revision 2.2 (Aug 14, 2006):
  • Bug fix 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).