虚拟图像采集接口（文件接口）

• 单张图片： 在这种情况下，算子 grab_image 或 grab_image_async 的每次后续调用都将加载该图像文件。请注意，图像名称可以是绝对的（例如 "C:\MyImages\MyPicture"），也可以是相对于图像搜索路径的（例如 "MyPicture"，参见 set_system 中的 "image_dir"）。此外，您还可以选择指定完整的图像名称（例如 "MyPicture.tif"）或省略文件扩展名（例如 "MyPicture"）。在后一种情况下，HALCON 会自动添加所支持图像格式（tiff、tif、jpg、jpeg、png、ppm、ppnm、ppm、pppm、gif、bmp、pcx、ras、ima、xwd）的常用文件扩展名。
• 序列文件： 序列文件是一种每行包含一个图像文件名的文件。在这种情况下，算子 grab_image 或 grab_image_async 的第一次调用将分别加载第一个图像文件，第二次调用将加载第二个图像文件等。如果加载图像失败，将返回错误信息，下一次调用将加载后续文件。在序列文件的最后一个条目结束后，下一次抓取将再次从第一个图像文件开始（循环）。序列文件名和序列文件中的图像文件名既可以是绝对的（如 "C:\MyImages\MySequence"），也可以是相对于图像搜索路径的（参见 set_system 中的 "image_dir"）。通常，序列文件的扩展名为".seq"（也可以省略指定此文件扩展名）。当图像文件路径包含非 ASCII 字符且 HALCON 虚拟图像采集接口使用 HALCON 18.11 或更新版本时，序列文件应使用 UTF-8 作为字符串编码。这样可以保证不同系统和本地之间的最佳互换性。序列文件如果不是有效的 UTF-8，则会被假定为使用本地 8 位编码。请注意，您可以通过调用 get_framegrabber_param(..., 'device', ...) 来查询下一幅图像的实际文件名。
• 目录名称： 如果在 CameraType 参数中指定了一个有效的目录名，那么在接下来的 grab_image 或 grab_image_async 调用中，该目录中所有带有支持的图像文件扩展名（tiff、tif、jpg、jpeg、png、ppm、ppnm、ppgm、ppm、gif、bmp、pcx、ras、ima、xwd）的文件都会相继被使用。目录名可以是绝对的（例如 "C:\\MyImages"），（参见 set_system 中的 "image_dir"）。如果加载图像失败，将返回错误信息，下一次抓取将加载后续文件。抓取完所有可用图像后，下一次抓取将从第一个图像文件开始（循环）。请注意，您可以通过调用 get_framegrabber_param(..., 'device', ...) 来查询下一幅图像的实际文件名。
• AVI 文件： 在 Windows 下，虚拟图像采集接口还提供读取 AVI 文件格式视频流的功能。在这种情况下，算子 grab_image 或 grab_image_async 的第一次调用将分别加载第一个图像文件，第二次调用将加载第二个图像文件，等等。到达 AVI 文件的最后一帧后，下一次抓取将从第一帧开始（循环）。AVI 文件的名称可以是绝对的（例如 "C:\\MyImages\MyAVIFile"），也可以是相对于图像搜索路径的（参见 set_system 中的 "image_dir"）。AVI 文件的扩展名为".avi"（也可以省略指定此文件扩展名）。
  请注意，通过 HALCON 文件接口读取 AVI 文件的功能是基于相当古老的 Windows 视频 (VfW) API。因此，要读取 AVI 文件，您需要使用与 VfW 兼容的编解码器。如果您在读取特定的 AVI 文件时遇到困难，我们建议您尝试使用基于 DirectShow API 的 HALCON DirectFile 接口。

使用 HALCON 虚拟图像采集接口的示例可在 %HALCONEXAMPLES%/hdevelop/Image/Acquisition 目录中找到。序列文件示例可在 %HALCONEXAMPLES%/images/pendulum/ 目录中找到。

• 英特尔兼容电脑，安装 Windows 7（32 位或 64 位）或更新版本，以及 WoW64（在 64 位 Windows 上使用 32 位 HALCON）、内核为 2.6（或更高）的 Linux 或 macOS。
• Windows： HALCON 图像采集接口分别是 hAcqFile.dll 或 hAcqFilexl.dll。如果正确安装了接口，所有这些 DLLs 都应位于安装 HALCON 时所选择的 HALCON 基本目录 %HALCONROOT% 下的 bin\%HALCONARCH% 中。
  Linux： HALCON 图像采集接口分别是 hAcqFile.so 或 hAcqFilexl.so。如果正确安装了接口，共享对象应位于 HALCON 基本目录 $HALCONROOT 中的 lib/$HALCONARCH 中。
  macOS： HALCON 图像采集接口分别是 hAcqFile.dylib 或 hAcqFilexl.dylib。如果正确安装了接口，共享对象应位于库子目录中的 HALCON 框架 /Library/Frameworks/HALCON.framework 或 HALCON XL 框架 /Library/Frameworks/HALCONxl.framework 中。

• Windows： 将包含接口文件的压缩包解压缩到 HALCON 基本目录 %HALCONROOT%（注意：此步骤可能需要管理员权限）。此外，还必须手动将接口示例移至 %HALCONEXAMPLES% 目录。
• Linux： 将包含接口文件的压缩包解压缩到 HALCON 基本目录 $HALCONROOT。
• OS X： 解压压缩包。手动移动以下文件：
  • 将位于 lib/x64-macosx 中的 .dylib 文件移至 /Library/Frameworks/HALCON.framework/Libraries
  • 将 genicam 文件夹移至 /Library/Frameworks/HALCON.framework/Libraries
  • 将示例文件夹移至 /Users/Shared/Library/Application Support 下的版本子目录
  • 将 doc 文件夹移至 /Library/Application Support 下的版本子目录

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

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

• file.hdev - 基准
• file_directory.hdev - 从指定目录读取所有图像的示例。
• file_sequence.hdev - 显示虚拟图像采集卡在图像序列中的使用情况。

• 修订 18.11.5（2021 年 10 月 20 日）：
  • 现在，该接口的发布包中包含了为 HDevelop 示例浏览器提供元信息的文件。
• 修订 18.11.4（2020 年 10 月 27 日）：
  • 此接口无法从 Linux 和 macOS 上的 .NET Core 应用程序中加载。该问题已得到修复。
• 修订 13.0.3（2018 年 11 月 30 日）：
  • 如果接口使用的是 HALCON 18.11 或更新版本，则必须使用 UTF-8 编码的序列文件（其中列出了必须逐个读取的图像路径）。对于使用当前本地 8 位编码的旧序列文件，如果其生成的字符串不是有效的 UTF-8 字符串，则仍可支持，并会自动检测和正确转换。
• 修订 13.0.2（2017 年 11 月 28 日）：
  • HALCON 库的技术依赖已被移除。
• 修订 13.0.1（2016 年 10 月 28 日）：
  • HALCON 13 版本的接口。
  • 在 Windows 系统上，路径的最大长度限制为 260 个字符。这个问题已经解决。现在，Windows 系统上的最大路径总长度为 32,767 个字符。
• 修订 6.1（2015 年 3 月 13 日）：
  • 修复了抓取超过四个通道的文件时崩溃的问题。
• 修订 6.0（2014 年 10 月 31 日）：
  • HALCON 12 版本的接口。
• 修订 5.5（2013 年 11 月 27 日）：
  • 修复了读取 avi 文件时崩溃的问题（错误地使用了未定义的图像格式）。
• 修订 5.4（2013 年 9 月 6 日）：
  • 修复了抓取具有不同图像格式的多通道文件时的崩溃问题。
  • 更正了参数 "color_space"、"image_width" 和 "image_height" 的文档。
• 修订 5.3（2013 年 6 月 13 日）：
  • 修复了在读取带有 Alpha 通道的 TIFF 文件时出现的错误。现在会返回具有适当通道数的图像。
  • 更正了 "generic" 参数的文档。
  • 改进 open_framegrabber：现在可在参数 "CameraType" 中指定与搜索路径（参见 set_system 中的 "image_dir"）相对应的目录名称。
• 修订 5.2（2012 年 11 月 15 日）：
  • 更正了 info_framegrabber 'camera_type' 查询返回值中的图像默认搜索路径。
• 修订 5.1（2012 年 7 月 11 日）：
  • 修复了在读取带有 alpha 通道的 TIFF 文件时出现的错误。
• 修订 5.0（2012 年 5 月 15 日）：
  • HALCON 11 版本的接口（包含在 HALCON 11 DVD 中）。
  • 添加了对 Mac OS X 10.7 的支持。
• 修订 4.1（2009 年 6 月 16 日）：
  • 修正了在尝试读取不存在或损坏的 TIFF 文件时出现的错误。
  • HALCON 10 版本的接口（包含在 HALCON 10 DVD 中）。
• 修订 4.0（2008 年 11 月 28 日）：
  • HALCON 9.0 版本的接口（包含在 HALCON 9.0 DVD 中）。
• 修订 3.1（2007 年 8 月 3 日）：
  • 修正了在指定目录名之外存在同名图像文件的情况下读取目录中所有文件的错误。
• 修订 3.0（2007 年 5 月 15 日）：
  • HALCON 8.0 版本的接口（包含在 HALCON 8.0 DVD 中）。
• 修订 2.10（2006 年 12 月 14 日）：
  • 修复多次打开和关闭 avi 文件的错误。
• 修订 2.9（2006 年 8 月 14 日）：
  • 修正了 get_framegrabber_param(...'frame_number'...) 中 AVI 视频流最后一帧的错误（仅限 Windows）。
• 修订 2.8（2005 年 7 月 27 日）：
  • 交换 .avi 和 .seq 文件的搜索顺序： 如果存在同名的 .avi 文件和 .seq 文件，则打开 .seq 文件。
  • AVI 文件： 允许不区分大小写的文件扩展名。
  • AVI 文件： 支持无彩色映射的位图
  • AVI 文件： 支持 16 位 RGB 位图
• 修订 2.7（2004 年 6 月 24 日）：
  • HALCON 7.1 版本的接口（包含在 HALCON 7.1 CD 中）。
  • 读取指定目录下的所有图像文件。
  • 访问 AVI 文件的错误修正（仅限 Windows）。
• 修订 2.6（2003 年 6 月 5 日）：
  • HALCON 7.0 版本接口（包含在 HALCON 7.0 CD 中）。
  • 修复了同时访问同一文件的错误。
• 修订 2.5（2002 年 12 月 9 日）：
  • 请注意： 该版本至少需要 HALCON 6.1.1。
  • 新功能：支持 PNG 图像格式。
  • 改进了从序列文件读取数据时的定时行为。
  • 改进 AVI 文件错误处理（仅限 Windows）。
• 修订 2.4（2002 年 4 月 25 日）：
  • HALCON 6.1 版本接口（包含在 HALCON 6.1 CD 中）。
  • 修正了正确处理序列文件和文件扩展名的错误。
• 修订 2.3（2001 年 6 月 22 日）：
  • 新功能：抓取".ima" 文件类型。
  • 抓取调用序列文件中的图像，以克服加载失败的问题。
• 修订 2.2（2000 年 12 月 15 日）：
  • 修复读取 24 bpp avi 文件时的错误（仅限 Windows）。
• 修订 2.1（2000 年 10 月 26 日）：
  • 支持 AVI 文件格式（仅限 Windows）。
  • 新增参数 "frame_number"、"first_frame" 和 "last_frame"。
• 修订 2.0（2000 年 7 月 4 日）：
  • 适应 HALCON 6.0 帧采集器集成接口。
  • 将 "VirtualFG "重命名为 "File"。
  • 还支持 grab_image_async（与 grab_image 行为相同）。
  • 图像序列中的图像可以有不同的图像大小和比特深度。
• 修订 1.27（1999 年 3 月 29 日）：
  • HALCON 5.2 版本的接口（包含在 HALCON 5.2 CD 中）。
  • 当到达终点时，自动从序列文件的起点重新开始（循环）。
• 修订 1.26（1999 年 3 月 28 日）：
  • 新参数 "revision" 。