MVTec Software GmbH
 

Documentation

DirectFile / HALCON / MVTec Software GmbH

Image Acquisition Interface for DirectShow File Reader

Interface: DirectFile
Revision: 13.0.2
Date: 2018-08-13

General

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.

System Requirements

  • 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 0.7.87.0 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', ...).

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.

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

Parameters for info_framegrabber

Parameter Value List Type Kind Description
'bits_per_channel' [] Unused.
'camera_type' 'CAMFILE:' string pre-defined Syntax for camera configuration file.
'color_space' ['gray', 'rgb'] string pre-defined Values for color space.
'defaults' [1, 1, 0, 0, 0, 0, 'default', 8, 'rgb', -1.0, 'false', 'default', '0', -1, 1] mixed pre-defined Default values for open_framegrabber.
'device' [] Unused.
'external_trigger' [] Unused.
'field' [] Unused.
'general' [] string pre-defined Information about the HALCON DirectFile 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' 'filter:<filter> | merit:<merit> | file:<file> | type:<type> | subtype:<subtype>' string dynamic Info about installed DirectShow filters:
  • filter is the name of this DirectShow filter.
  • merit is a value that defines which filters are preferred to build the capture filter graph. Standard values are shown by their name.
  • file is the DLL that contains this filter.
  • type and subtype list the media types of all input pins of this filter. Known media types are shown by their name, others by their GUID.
'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 DirectFile 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 'DirectFile' string Name of the HALCON interface.
HorizontalResolution --- Ignored.
VerticalResolution --- Ignored.
ImageWidth --- Ignored.
ImageHeight --- Ignored.
StartRow --- Ignored.
StartColumn --- Ignored.
Field --- Ignored.
BitsPerChannel --- Ignored.
ColorSpace 'gray', 'rgb' 'rgb' string Desired color space and thus the number of image channels of the resulting HALCON image.
Generic --- Ignored.
ExternalTrigger --- Ignored.
CameraType '<filename>' 'default' string 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

Parameter Values Default Type Description
'frame_number' <number> integer Number of the next frame to be grabbed by grab_image or grab_image_async.
'grab_timeout' <milliseconds> 5000 integer Desired timeout (milliseconds) for aborting a pending grab. If -1 is specified, the timeout is set to INFINITE.

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>' 'default' string pre-defined Name of the camera configuration file.
'color_space' 'gray', 'rgb' 'rgb' string pre-defined Desired color space and thus the number of image channels of the resulting HALCON image.
'device' <default> '0' integer dynamic The value is not used, so a default value is returned.
'external_trigger' <default> 'false' string pre-defined The value is not used, so a default value is returned.
'field' '<default>' 'default' string pre-defined The value is not used, so a default value is returned.
'filter_graph' 'filter:<filter> | merit:<merit> | file:<file> | type:<type> | subtype:<subtype>' string dynamic Info about connected DirectShow filters:
  • filter is the name of this DirectShow filter.
  • merit is a value that defines which filters are preferred to build the capture filter graph. Standard values are shown by their name.
  • file is the DLL that contains this filter.
  • type and subtype list the media types of all input pins of this filter. Known media types are shown by their name, others by their GUID.
'first_frame' <number> integer dynamic Number of the first frame of the video stream.
'frame_number' <number> integer dynamic Number of the next frame to be grabbed by grab_image or grab_image_async.
'generic' <default> -1 mixed pre-defined The value is not used, so a default value is returned.
'grab_timeout' <milliseconds> 5000 integer pre-defined Current grab timeout in milliseconds.
'horizontal_resolution' <resolution> 1 integer pre-defined Current value of horizontal resolution.
'image_height' <default> 0 integer pre-defined The value is not used, so a default value is returned.
'image_width' <default> 0 integer pre-defined The value is not used, so a default value is returned.
'last_frame' <number> integer dynamic Number of the last frame of the video stream.
'line_in' <default> 1 integer pre-defined The value is not used, so a default value is returned.
'media_info' <media_info> string dynamic Info about the source file retrieved by the third-party library MediaInfo (see the System Requirements).
'name' 'DirectFile' 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 DirectFile interface.
'start_column' <column> 0 integer pre-defined Returns the current start column of the HALCON image.
'start_row' <row> 0 integer pre-defined Returns the current start row of the HALCON image.
'vertical_resolution' <resolution> 1 integer pre-defined Current value of vertical resolution.

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:
  • directfile.hdev - Benchmark

Usage of 3rd party libraries

This interface depends on the following 3rd party libraries. See the files third_party_copyrights.html and third_party_licenses.txt in the HALCON base directory for copyright and license information.

Release Notes

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