用于 DirectShow 文件阅读器的图像采集接口

本页提供有关 Microsoft DirectShow 文件阅读器应用程序编程接口的 HALCON DirectFile 接口的文档。注册 客户可从 MVTec WWW 服务器下载该接口的最新版本。

• 英特尔兼容电脑，装有 Windows 7（32 位或 64 位）或更新版本，并安装了 DirectX 8.1 或更高版本。您可以运行 dxdiag 诊断程序检查所安装的 DirectX 版本。
• HALCON 图像采集接口分别是 hAcqDirectFile.dll 或 hAcqDirectFilexl.dll。
  如果正确安装了接口，这些 DLL 应位于 %HALCONROOT%\bin\%HALCONARCH% 中。你不需要手动注册这个 DLL。相反，该 DLL 会检查当前的注册情况，并在必要时自行执行必要的步骤。如果没有足够的权限，它将以提升的权限运行 regsvr32.exe，这通常需要用户交互。
• 第三方库 MediaInfo.dll 0.7.87.0 版本，如果已正确安装接口，该库也应位于 %HALCONROOT%\bin\%HALCONARCH%。请注意，该 DLL 对于图像采集并不重要，只有在调用 get_framegrabber_param(..., 'media_info', ...) 时才需要它。

用于数字输入/输出和图像采集的 MVTec 接口始终与一系列 HALCON 版本兼容。因此，版本控制方案既说明了接口的兼容性，也说明了接口本身的版本。接口版本总是由三个数字组成，中间用点隔开，即 18.11.5。前两个数字描述了接口兼容的最小 HALCON 版本。以 18.11.5 版本为例，这意味着接口兼容 HALCON 18.11 之后的所有 HALCON 版本。最后一个数字说明接口的修订版本，在本例中为修订版本 5。

只有在手动安装或更新接口时，才能按照这些步骤操作：

• Windows： 将包含接口文件的压缩包解压缩到 HALCON 基本目录 %HALCONROOT%（注意：此步骤可能需要管理员权限）。此外，还必须手动将接口示例移至 %HALCONEXAMPLES% 目录。

一般来说，能否使用 HALCON DirectFile 接口打开文件主要取决于应用程序所运行系统的配置。通常情况下，需要安装合适的编解码器。根据经验，如果可以使用 GraphEdit 重放文件，则很有可能也可以使用 HALCON DirectFile 接口打开文件。在 64 位操作系统上，HALCON 架构（32 或 64 位）必须与编解码器的架构相匹配。有关系统中编解码器的详细信息，请参阅 Windows Media Player 关于对话框的技术支持信息。

• 只支持允许基于帧定位的文件。
• 不支持图像缩放和裁剪。

可能还存在以下后缀的其他只读参数：

• '_description'： 这些参数以字符串形式提供相应参数的工具提示。
• '_range'： 这些参数以 4 个元素的元组形式提供了相应整数或浮点数参数的最小值、最大值、步宽和默认值， 例如 get_framegrabber_param(.., 'Shutter_range', ..) 将返回输出元组 [min, max, step, default].
• '_values'： 这些参数以元组形式提供相应参数的有效值列表，例如 get_framegrabber_param(.., 'volatile_values', ..) 将返回输出元组 ['enable', 'disable'].

在调用 info_framegrabber(.., 'parameters', ..) 时，所有这些后置固定参数名都不会返回，而是用于通过通用图形用户界面，特别是 HDevelop 图像采集助手，方便地进行参数设置。

此接口不支持。

此接口不支持。

此接口不支持。

此接口不支持。

开始新的异步抓取。另见 grab_image_start。

grab_image 启动新的同步抓取。另见 grab_image。请注意，该接口会将来自设备的图像转换为由参数 "image_width"、"image_height"、"start_row"、"start_column"、"bits_per_channel" 和 "color_space" 指定的所需图像格式。

grab_image_async 返回图像并开始下一次异步抓取。另请参阅 grab_image_async。请注意，该接口会将来自设备的图像转换为由参数 "image_width"、"image_height"、"start_row"、"start_column"、"bits_per_channel" 和 "color_space" 指定的所需图像格式。

此接口不支持。

此接口不支持。

此算子关闭设备。另见 close_framegrabber。

该接口有以下示例：

• directfile.hdev - 基准

该接口依赖于以下第三方库。有关版权和许可证信息，参见 HALCON 基本目录中的文件 third_party_directfile.txt。

• MediaInfo - 未经修改使用

• 修订 18.11.5（2021 年 10 月 20 日）：
  • 现在，该接口的发布包中包含了为 HDevelop 示例浏览器提供元信息的文件。
• 修订 18.11.4（2020 年 10 月 27 日）：
  • 此接口无法从 Linux 和 macOS 上的 .NET Core 应用程序中加载。该问题已得到修复。
• 修订 13.0.3（2020 年 2 月 27 日）：
  • 该接口的分发包中已添加了 third_party_directfile.txt 文件。
  • 查询参数 "media_info" 可能导致 HALCON 在处理某些视频文件时崩溃。该问题已得到修复。
• 修订 13.0.2（2018 年 8 月 13 日）：
  • HALCON 库的技术依赖已被移除。
  • 在调用参数 "media_info" 时，如果文件信息包含 UNICODE 字符，则无法正确处理。该问题已得到修复。
• 修订 13.0.1（2016 年 10 月 28 日）：
  • HALCON 13 版本的接口。
  • 在 Windows 系统上，路径的最大长度限制为 260 个字符。这个问题已经解决。现在，Windows 系统上的最大路径总长度为 32,767 个字符。
• 修订 6.3（2016 年 8 月 26 日）：
  • info_framegrabber(..., 'info_boards', ...) 现在会返回系统中安装的所有 DirectShow 过滤器的列表。
  • get_framegrabber_param(..., 'filter_graph', ...) 现在会返回活动过滤图使用的 DirectShow 过滤器列表。
  • get_framegrabber_param(..., 'media_info', ...) 现在可返回通过第三方库 MediaInfo 检索到的源文件信息（参见 系统要求 ）。
  • open_framegrabber 现在可以在加载源文件后立即成功。如果无法构建工作过滤图，get_framegrabber_param(..., 'media_info', ...) 可以查询文件的有用信息，以便找到并安装合适的编解码器。
  • 如果调用 open_framegrabber 时文件不存在，则返回 H_ERR_FGNV (#5304) 而不是 H_ERR_FNF (#5200)。这一问题已得到修复。
  • 在亚洲系统上无法打开包含多字节字符的文件路径。该问题已得到修复。
  • 在 set_framegrabber_param 中设置空值会导致崩溃。该问题已得到修复。
• 修订 6.2（2015 年 7 月 22 日）：
  • 首次调用 open_framegrabber 失败。该问题已得到解决。
  • 如果 quartz.dll 可用，调用 iinfo_framegrabber(..., 'general', ...) 时会崩溃。该问题已得到修复。
• 修订 6.1（2015 年 2 月 23 日）：
  • 修正了读取 UTF8 编码文件名的错误。
• 修订 6.0（2014 年 10 月 31 日）：
  • HALCON 12 版本的接口。
  • 改进了 DLL 注册流程，以防接口尚未正确注册。
• 修订 5.0（2012 年 5 月 15 日）：
  • HALCON 11 版本的接口（包含在 HALCON 11 DVD 中）。
• 修订 4.2（2010 年 8 月 20 日）：
  • 图像缓冲区大小计算超出了 8 倍。该问题已得到修复。
  • HALCON 10 版本的接口（包含在 HALCON 10 DVD 中）。
• 修订 4.1（2009 年 9 月 9 日）：
  • 修正了在同时使用多个 DirectFile 获取句柄时参数 "frame_number" 的错误。
• 修订 4.0（2008 年 11 月 28 日）：
  • HALCON 9.0 版本的接口（包含在 HALCON 9.0 DVD 中）。
• 修订 3.1（2008 年 4 月 22 日）：
  • 添加了后缀为"_description"、"_range" 和"_values" 的只读参数，以便通过通用图形用户界面轻松设置参数。
• 修订 3.0（2007 年 5 月 15 日）：
  • HALCON 8.0 版本的接口（包含在 HALCON 8.0 DVD 中）。
• 修订 2.3（2007 年 4 月 27 日）：
  • 修复了关于图像宽度为奇数的图像填充的错误。
• 修订 2.2（2006 年 8 月 14 日）：
  • 修复了 get_framegrabber_param(..., 'frame_number', ...) 中视频流最后一帧的错误。
• 修订 2.1（2005 年 9 月 12 日）：
  • 提供 64 位 Windows 版本。
  • 不再需要手动注册 hAcqDirectFile.dll 或 parhAcqDirectFile.dll。
• 修订 2.0（2005 年 9 月 1 日）：
  • 首次正式发行（包含在 HALCON 7.1 CD 中）。