Interface Documentation
Image Acquisition Interface for DirectShow File Reader
| Interface: | DirectFile |
| Revision: | 20.11.6 |
| Date: | 2023-08-08 |
- General
- System Requirements
- Interface Versioning
- Installation
- Limitations
- Parameters for info_framegrabber
- Parameters for open_framegrabber
- Parameters for set_framegrabber_param
- Parameters for get_framegrabber_param
- Operator set_framegrabber_lut
- Operator get_framegrabber_lut
- Operator set_framegrabber_callback
- Operator get_framegrabber_callback
- Operator grab_image_start
- Operator grab_image
- Operator grab_image_async
- Operator grab_data
- Operator grab_data_async
- Operator close_framegrabber
- HDevelop Examples
- Usage of third-party libraries
- Release Notes
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', ...).
Interface Versioning
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. 20.11.5. The first two numbers describe the minimum HALCON version the
interface is compatible with. For the example version 20.11.5 this means
that the interface is compatible with all HALCON versions since HALCON
20.11. The last number describes the revision of the interface, in this
example this is revision 5.
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:
|
| '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:
|
|
| '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 third-party libraries
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â.
Release Notes
- 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).