用于 USB3 Vision 兼容相机的图像采集接口

本页提供通用 HALCON USB3Vision 接口的文档，用于访问所有符合 USB3 Vision 标准的相机。注册 客户可从 MVTec WWW 服务器 下载该接口的 最新版本 。

• 英特尔兼容电脑，安装 Windows 7（32 位或 64 位）或更新版本，以及 WoW64（在 64 位 Windows 上使用 32 位 HALCON）、内核为 3.5（或更高）的 Linux 或 OS X 10.8（或更高）。
• 计算机必须配备 USB 3.0 接口。确保使用 USB 3.0 主控制器的最新驱动程序。请注意，在 Windows 系统上，使用内置机制搜索通常是不够的，您需要在主控制器制造商的网站上查看最新版本。
• 确保采集接口可完全访问所连接的 USB3 Vision 设备：
  • Windows： 设备的复合父节点上的受支持驱动程序（WinUSB、libusb-win32 或 libusbk）之一。
  • Linux： 相应设备文件的读写访问权限。
  • macOS： 自动提供访问。
  • 更多详情，请参阅 USB3 Vision 设备访问 一节。
• GenICam GenApi。相应文件是 HALCON GigEVision2 软件包的一部分，位于 HALCON 基本目录 %HALCONROOT% 下的 genicam 目录中。有关详情，参见 GenICam GenApi 一节。
• Windows：HALCON 图像采集接口分别是 hAcqUSB3Vision.dll 或 hAcqUSB3Visionxl.dll。此外，您还需要 libusb-1.0-usan.dll 和 libwdi-usan.dll 第三方库以及 hAcqUSB3VisionElevate.exe 二进制文件。后者是在接口内正确分配驱动程序所必需的。如果您已正确安装了接口，所有这些文件都应位于您在安装 HALCON 时所选择的 HALCON 基本目录 %HALCONROOT% 内的 bin\%HALCONARCH% 中。
  
• Linux：HALCON 图像采集接口分别是 hAcqUSB3Vision.so 或 hAcqUSB3Visionxl.so。此外，您还需要 libusb-1.0-usan.so.0 第三方库和 hAcqUSB3VisionElevate SUID 二进制文件（s-bit 用于 root）。后者对于在没有权限向设备发送命令的情况下在接口内正确识别设备十分必要。如果正确安装了接口，共享对象应位于 lib/$HALCONARCH 中，第三方共享库应位于 lib/$HALCONARCH/thirdparty 中，二进制文件应位于 bin/$HALCONARCH 中，并位于安装 HALCON 时所选择的 HALCON 基本目录 $HALCONROOT 中。
  设备访问需要 libudev（特别是 libudev.so.1 或更高），参见 USB3 Vision 设备访问 一节。
  为了调整优先级和调度策略，需要管理员权限或 CAP_SYS_NICE 功能，我们建议通过 @video - rtprio 99 这样的条目将这些功能添加到视频组（使用提供的 udev 配置时为默认组），例如添加到 /etc/security/limits.d/video.conf 中（可能需要创建）。
• macOS：HALCON 图像采集接口分别是 hAcqUSB3Vision.dylib 或 hAcqUSB3Visionxl.dylib。此外，您还需要 libusb-1.0-usan.0.dylib 第三方库。如果正确安装了接口，共享对象应位于 Libraries 子目录中的 HALCON 框架 /Library/Frameworks/HALCON.framework 或 HALCON XL 框架 /Library/Frameworks/HALCONxl.framework。或者，也可以将环境变量 DYLD_LIBRARY_PATH 设置为指向相应目录。
  调整优先级和调度策略需要必要的权限。
• T默认采集模式假定计算机的速度足以处理来自相机的所有缓冲区。如果不是这种情况，它们就会被默默丢弃。

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

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

• 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 下的版本子目录

从 13.0.4 版开始，共享库 libusb-1.0-usan.so.0 不再位于 $HALCONROOT/lib/$HALCONARCH/ 目录中。相反，它被移至子目录 $HALCONROOT/lib/$HALCONARCH/thirdparty。如果您是从较早版本的接口升级，则需要手动从 $HALCONROOT/lib/$HALCONARCH/ 目录中移除该库。

接口可通过几个环境变量进行控制：

• HALCON_ACQUIRED_FILE_PAYLOAD_DIR 用于指定使用设备提供的文件名存储非图像有效载荷类型（通常是文件或 "原始" 数据）的目录。
• 使用 HALCON_GENICAM_WRITE_XMLFILE 和/或 HALCON_GENICAM_WRITE_RAW_XMLFILE 指定目录时，GenICam 描述文件（XML 和/或原始格式）将在使用 HALCON 时存储在该目录中。也可以通过设置接口参数 "do_write_configuration" 来存储这些文件。
• 如果要使用已安装的 GenApi 版本，而不是 HALCON 随附的版本，则必须设置环境变量 HALCON_USE_EXTERNAL_GENAPI。此外，在这种情况下还必须设置 GenApi 所需的所有环境变量。这仅适用于专家，另见 GenICam GenApi 一节。

• USB3 Vision 协议的用户空间实施。
• 从多个相机抓取。
• 灵活的设备查找和连接选项。
• 同步和异步抓取。
• 支持 GenDC 流（GenDC 容器传输模式）。
• 获取三维数据并创建三维对象模型。
• 使用 GenApi 对所有通用相机参数进行软件控制。
• 使用 GenApi 对控制接口 USB3 Vision 生产者的参数进行软件控制。
• 支持各种像素格式和灵活的色彩转换。
• 支持 "连续"、"多帧 "和 "单帧 "采集模式。
• 支持 GenICam 动作控制。
• 支持 GenICam 块数据。
• 支持 GenICam 事件数据。
• 支持 GenICam 功能持久性。
• 支持 GenICam 文件访问。
• 支持 GenICam 固件更新。
• 支持功能更改通知回调。
• 支持不可串流设备（可通过 GenICam 控制，但不串流任何图像（或其他）数据的设备）。
• 支持待确认功能，无需手动调整超时，即可等待设备对长时间指令的响应。

• 不完全支持具有多个 USB 配置的设备。
• 在 OS X 10.10.x 及更早版本中，停止或中止抓取图像会导致带有大尺寸传感器（500 万像素及以上）的相机挂起。作为一种解决方法，请使用通用参数 "num_buffers=2 "打开接口，并将参数"[Stream]StreamAuxiliaryBufferCount" 设置为 0。 Apple 在 OS X 10.11 "El Capitan" 中修复了这个问题。

• 该接口实现了 1.2 版 USB3 Vision 规范，涵盖其定义的所有三个基本协议：控制、图像/数据流和异步设备事件。
• 接口支持 GenDC 容器传输模式（目前不支持串行和并行流模式）——当设备支持时，接口默认选择 GenDC 模式，以实现最大的灵活性。

• 该接口使用 GenApi 3.4 版本，详情请访问 GenICam 主页 。相应文件是 HALCON 运行时安装的一部分，分别位于 HALCON 基本目录 %HALCONROOT% 或 $HALCONROOT 下的 genicam 目录中。该版本与本文撰写时的正式发布版本相同。
• HALCON USB3Vision 接口会自行设置所有必要的环境变量，默认情况下会忽略其他已安装的 GenICam 软件包。
  如果要使用其他 GenICam 软件包，则需要设置环境变量 HALCON_USE_EXTERNAL_GENAPI。这省略了在内部设置所有必要变量和路径的步骤，因此必须确保设置正确。请注意，不同接口可能无法同时使用不同的 GenApi 版本，您必须使用该接口所需的 GenApi 版本。
• 激活设备 XML 文件的缓存以加快处理速度，并根据 %TEMP%、%TMP%、$TMPDIR、/tmp 或 %HALCONROOT% 的可用性写入临时目录。
• 该接口的远程设备控制功能以及 USB3 Vision 生产者控制功能均通过 GenApi 控制。

HALCON USB3Vision 图像采集接口通过 libusb 1.x 兼容接口执行对 USB 总线和所连接 USB 设备的所有访问。为确保完全访问设备，必须满足以下先决条件：

一般情况：

• 设备必须与 USB 3.0 兼容，并在超高速传输模式下运行。
• USB 2.0（或更低）设备或通过 USB 2.0 集线器连接的设备将被接口发现，但它们将被标记为不可访问，接口将拒绝打开它们。
• 请注意，当使用不适当的电缆或电缆接头未完全插入时，设备可能看起来也是通过 USB 2.0 连接的。

Windows：

• 在 Windows 系统中，可通过以下驱动程序之一访问设备： WinUSB、libusb-win32 或 libusbk，我们目前推荐将 WinUSB 作为默认选项。
• 驱动程序必须连接到设备的复合父设备，而不仅仅是其中一个设备接口。
• 如果驱动程序未正确连接到设备，HALCON USB3Vision 采集接口会发现设备，但会将其标记为不可访问，并且无法打开。
• 如果您使用 HDevelop 图像采集助手，它会自动提示您添加正确的通用参数，以便在必要时安装驱动程序。如果要手动操作，您可以在 HDevelop 示例 部分找到示例。请注意，由于需要提升权限，提升后的用户可能无法使用网络驱动器，因此驱动程序安装可能会失败。如果出现此类问题，请在本地安装 HALCON。
• 如果使用其他图像采集接口或其他软件访问相机，可能需要使用与此接口分配的驱动程序不同的驱动程序。具体方法是以管理权限打开设备管理器。然后选择设备，右键单击并选择卸载驱动程序。请选择删除驱动程序，否则重新连接设备时会自动分配驱动程序。现在拔下设备并重新连接。它应该会安装其他驱动程序，如果没有，请按照其他软件或界面的说明进行操作。
• 如果接口根本无法检测到设备，则需要手动分配驱动程序。在此之前，请先将 USB 3.0 主机控制器驱动程序更新为制造商提供的最新版本，这在大多数情况下可以实现自动检测。
• 手动安装驱动程序的推荐方法是使用 Zadig 驱动程序安装程序（最新版本）。以管理员权限运行该工具，在选项菜单中勾选 "列出所有设备" 并取消勾选 "忽略集线器或复合父设备"。在下拉列表中选择设备（重要的是：其复合父设备），然后安装与设备一起使用的驱动程序（如 WinUSB）。

Linux：

• 在 Linux 上，设备的枚举和访问是通过 libudev（使用 usbfs 作为备用）建立的。至少需要 libudev.so.1。
• 应用程序需要有足够的权限才能以读写模式打开设备文件。如果没有读写访问权限，甚至可能无法正确枚举设备，因为无法查询与设备有关的 USB3 Vision 基本信息。
• 如果您使用 HDevelop 图像采集助手，它会自动提示您添加正确的通用参数，以便在必要时添加缺失的权限。
• 为使普通用户账户能够完全访问设备，应配置系统的 udev 子系统，以确保读写访问与可能连接到系统的任何 USB3 Vision 设备相对应的设备文件。实际的 udev 配置策略可能因系统而异，不过，USB3 Vision 采集接口随附了适用于大多数情况的默认解决方案。
• 您可以在 $HALCONROOT/misc/linux/udev/rules.d/59-usb3vision.rules 中找到推荐的 udev 配置规则。该规则将保证 "video" 用户组的所有成员以及以交互方式登录系统的用户都能读写访问 USB3 Vision 设备对应的设备文件。如果该配置符合您的期望，请将文件复制到 /etc/udev/rules.d 目录（在大多数发行版中都有效）。如果需要，可根据为系统定义的 udev 配置策略修改该文件。
• 作为最后的额外辅助工具，当 udev 规则配置无法提供帮助时（例如，由于其他软件包覆盖了该配置），USB3 Vision 采集接口将尝试在设备发现过程中使用实用程序 $HALCONROOT/bin/$HALCONARCH/hAcqUSB3VisionElevate。该实用程序的唯一目的是读取 USB3 Vision 设备的相关标识，以便进行完整的设备发现。不过，无论实际用户和 udev 配置如何，该工具都需要对 USB3 Vision 设备文件进行可靠的读写访问。因此，建议将文件所有者更改为 root 并设置 setuid 位。为此，您需要以 root 身份执行以下命令： chown root $HALCONROOT/bin/$HALCONARCH/hAcqUSB3VisionElevate chmod 2755 $HALCONROOT/bin/$HALCONARCH/hAcqUSB3VisionElevate
• Linux 内核将分配给 USB 传输的缓冲区大小限制为 16MB。对于具有大型传感器、多台相机、大量同步计划传输或类似情况的相机（另见 高级流引擎控制 ），这一限制是不够的，需要进行调整。为防止图像采集失败，有必要将此限制提高到能安全覆盖流缓冲区传输总大小的值，在任何时刻，所有打开的相机都可能同时计划进行流缓冲区传输，同时还要考虑到可能与您的应用程序共享 USB 子系统的其他可能组件或应用程序。该限制由 usbcore.usbfs_memory_mb 内核参数（以 MB 为单位）控制。例如，要将限制增加到 512MB，可以在启动时或引导加载程序中添加 usbcore.usbfs_memory_mb=512 这样的内核命令行参数。或者，你也可以通过执行 echo 512 > /sys/module/usbcore/parameters/usbfs_memory_mb 命令，以管理员权限即时调整。

macOS：

• 不需要做任何特殊操作，默认情况下您应该拥有完整的设备访问权限。

同时使用多台 USB3 Vision 相机时，在规划硬件设置时可能需要考虑一些带宽管理因素。尤其重要的是，要保证设备可能使用的总带宽不超过它们最终共享的 USB 总线拓扑段的带宽，或者，如果可能的话，保证设备通过独立路径连接到主机。

请注意，集线器等 USB 组件的实际性能可能大大低于 USB 3.0 总线的最大理论带宽。

根据实际使用情况，特定的设备属性，如设备帧缓冲区的存在和大小，也可能对整个系统的性能和可靠性产生影响。设备供应商通常会提供详细的设备带宽管理指南和配置选项。

与（采集）设备的连接通过 open_framegrabber 算子建立。算子提供一组参数，用于配置设备的基本属性以及 HALCON USB3Vision 接口的控制方式 - 参见 相应小节 。部分参数还可在运行时通过 set_framegrabber_param 进行修改。本节只讨论 open_framegrabber 的 "Device" 参数，该参数用于确定应打开的设备（通常是相机）。
与通过 USB3 Vision 接口访问的设备的连接是通过设备 ID 建立的，该 ID 保证每个 USB3 Vision 设备都是唯一的，并在多个会话中保持不变，且与设备连接到 USB 总线的位置无关。也可以使用用户定义的设备名称来代替唯一的设备 ID。最后，还可以使用设备的序列号。
在任何时候，都可以使用 info_framegrabber 参数 "device" 或 "info_boards" 来获取系统中当前可用的所有设备列表--参见 相应小节 。这两个参数都会返回设备列表，每个设备都使用上述实体指定，格式为 " | device:<device id> | ..." ，其中 "<device id>" 为唯一设备 ID 或用户自定义名称（"DeviceUserID"）（如果设备支持该名称）。如果设置为 "user_name:<user-defined name>" ，info_framegrabber 获得的字符串将包含 "user_name:<user-defined name>" 条目。为方便用户，如果用户自定义名称是唯一的，"device" 条目将反映该名称。如果同一用户定义名称分配给多个设备，则只有第一个设备会使用该名称，其他所有设备都将使用唯一名称。完整字符串（从 info_framegrabber 调用中获得）可直接用于 open_framegrabber 的 "Device" 参数，格式相同。如上图所示，它由 "token:value" 形式的条目组成，以" | "分隔。"device" 条目是最重要的条目。
或者，您也可以直接指定设备。为此，可以省略一个或多个条目（或指定为 "default" ）——这就像使用通配符一样，意味着不应考虑该实体的特定 ID（任何 ID 都能匹配）。对 open_framegrabber 而言，只有" | device:<device id>"字符串条目是重要的，其他条目会被忽略，也可以省略。除设备 ID 外，设备还可以通过其他标识符打开：用户自定义名称（使用格式为"user_name:<user_defined_name>"的字符串指定设备）或序列号（"device_sn:<device_serial_number>"）。
当使用不含 "token: "和分隔符" | "的纯字符串时，它将被直接解释为设备 ID。
如果事先知道设备 ID，就可以不使用 info_framegrabber 而自行创建字符串。如上图所示，它由 "token:value" 形式的条目组成，之间用" | "分隔。设备 "条目是最重要的条目。当使用不含 "token: "和分隔符" | "的纯字符串时，它将被直接解释为设备 ID。
作为一种特殊情况，可以使用字符串 "default"——在这种情况下，HALCON 采集接口将使用第一个可用设备（将跳过当前报告为不可访问的设备）。当再次使用相同的 "default" 字符串时，该设备将不再可访问，因此将打开下一个可访问的设备。这样，所有连接到系统的设备都可以在循环中轻松打开。

请注意，自 1.1 版起，USB3 Vision 规范支持具有多个图像流的设备。HALCON USB3Vision 接口目前只支持单一图像流，这也是绝大多数设备所提供的。在这种情况下，打开设备的格式将通过流条目进行扩展。当前的格式将打开第一个可用的流。
同样，将来设备字符串格式可能会扩展为一个条目，指定设备所连接的 "interface"（即计算机的 USB 3.0 总线）。在这种情况下，目前的格式仍然有效，但会搜索所有接口，而不仅仅是指定的接口。

设备或 USB3 Vision 生产者的功能由 GenICam 功能描述文件（XML 文件）描述，这些文件会自动解析并提供给用户。HALCON USB3Vision 图像采集接口可访问通过以下 GenICam 功能描述文件显示的功能：

• 连接设备（"远程设备"），通常是相机，其功能通常直接从连接设备加载。
• USB3 Vision 生产者的功能通过一组 GenICam 描述文件来展示，每个内部实体都有一个描述文件来控制设备树：
  • "系统"——代表采集接口的整体行为。
  • 用于将设备连接到系统的接口。
  • 设备的代理（称为 "本地设备"），控制设备的 GigE Vision 生产者视图。
  • 用于采集的数据流（如果设备提供任何数据流）。

在大多数情况下，GenICam 描述文件由设备和 USB3 Vision 生产者提供。可以使用参数 "do_write_configuration"（参见 set_framegrabber_param）来存储与打开的连接相对应的这些文件的副本。该命令将写入所有 GenICam 描述文件和一个 "ini" 文件（详见 set_framegrabber_param），其中包含各种信息，包括写入的 GenICam 描述文件的位置，格式如下：

 
RemoteFile=%PATH_TO_GENICAM_FILE_OF_THE_DEVICE% 
SystemFile=%PATH_TO_GENICAM_FILE_OF_THE_SYSTEM_MODULE% 
InterfaceFile=%PATH_TO_GENICAM_FILE_OF_THE_INTERFACE_MODULE% 
DeviceFile=%PATH_TO_GENICAM_FILE_OF_THE_LOCAL_DEVICE_MODULE% 
StreamFile=%PATH_TO_GENICAM_FILE_OF_THE_STREAM_MODULE% 

可重复使用相同的 ini 文件格式，强制 HALCON 采集接口为其中一个或多个实体加载替代 XML 文件。这在更新或故障排除等方面非常有用。ini 文件中列出的文件将用于给定实体，而不是原始文件。对于 ini 文件中排除的实体，将按常规方式搜索和加载 GenICam 描述文件。要应用 ini 文件，请在 "CameraType" 参数中将其完整路径传递给 open_framegrabber。

请注意，ini 文件也可重复用于其他目的，例如存储/恢复配置（如 参数– 持续设备状态 中所述）。请注意，指定持久化文件时，它们的优先级高于传递给 open_framegrabber 的其他显式设置。

有以下几组参数：

• MVTec GenTL 消费者本身（GenICamTL 采集接口）的内部参数。这些参数按照 "下划线 "命名方式命名，例如 color_space，并且全部小写。不过，MVTec EasyParams 均以 "[Consumer]" 作为前缀，例如，[Consumer]gain。
• 基于 GenICam 的设备（通常是相机）参数按惯例使用 "CamelCase" 样式，例如 ExposureTime。
• 基于 GenICam 的各个 USB3 Vision 生产者模块（系统、接口、设备和数据流）的参数按照惯例使用相同的样式，但前缀为方括号中的模块名称。请注意，系统和接口模块可能会被多个已打开的设备共享，因此更改它们的配置也可能会对其他连接产生副作用。使用以下前缀：
  • "[System]"，例如，[System]TLVendorName。
  • "[Interface]"，例如，[Interface]InterfaceType。
  • "[Device]"，例如，[Device]DeviceID。
  • "[Stream]"，例如，[Stream]StreamBufferHandlingMode。

属于 USB3 Vision 生产者的系统模块和接口模块的参数（即前缀为 "[System]" 和 "[Interface]" 的参数，参见 参数 - 命名规则 ）必须以特殊方式处理。
要了解它们的行为，必须明白它们并不描述或配置设备本身，因此并不完全属于已打开的设备实例。
接口模块参数属于发现给定设备的接口，并由该接口下打开的所有设备共享（另见 识别和打开设备 ）。系统模块参数属于整个 USB3 Vision 生产者，由该 USB3 Vision 生产者中所有打开的设备共享。
这将产生若干影响。特别是在通过多个设备实例访问系统或接口模块参数时，这些参数必须被视为共享资源。通过一个设备实例修改这些参数会影响通过其他设备实例看到的参数值（可能还会影响其他功能的参数值）。打开设备实例后，这些参数的初始值可能取决于先前打开的设备实例与这些功能的交互。

HALCON 本地参数类型有

• integer – 有符号整数，64 位平台为 64 位，32 位平台为 32 位
• real – 浮点型
• string – 经典字符串

访问基于 GenICam 的功能时，必须将 GenICam 数据类型映射到 HALCON 识别的参数类型。GenICam 提供以下类型：

• IInteger – 整数值，直接映射到 HALCON 的 整数 参数类型。它也接受 实数 参数。如果相关的 GenICam 功能有相关的表示法，可将其识别为 IPV4Address、MACAddress 或 HexNumber，则也将接受相应的字符串表示法。需要强调的是，在 32 位平台上运行 HALCON（其中 整数 参数为 32 位宽）并访问自然为 64 位的 GenICam 功能时，可能会出现问题。在这种情况下，应用程序将无法使用该功能的全部范围，其值可能会被截断。此外，参数的符号也可能被误解。为了解决这个问题，可以使用参数 "split_param_values_into_dwords"。这将 64 位整数值映射为两个 32 位整数值，反之亦然。
• IFloat – 浮点数值，直接映射到 HALCON 的 实数 参数类型。它也接受 整数 参数。
• IString – 字符串值，直接映射到 HALCON 的 字符串 参数类型。
• IBoolean – 布尔类型通过 HALCON 的 整数 参数处理，0表示逻辑假，其他值表示逻辑真。
• IEnumeration – 枚举是一种类型，允许从一组主要由名称标识的值中进行选择（这些值称为 "枚举项"）。枚举通过 HALCON 的 字符串 参数类型进行接口，而枚举项名称则用作参数值。
• ICommand – 命令类型允许 "execute" 操作。要执行命令，可使用 set_framegrabber_param，其中包含一个任意值的 整数 参数（该参数值将被忽略）。某些命令的执行可能需要较长的时间，命令执行完毕后会提供反馈。要查询状态，请使用该命令的 get_framegrabber_param。如果 "已完成"（命令执行完毕），则返回 整数 值 1；如果尚未完成，则返回整数值 0。需要注意的是，如果某些其他功能在设计上依赖于该命令，那么查询 "已完成 "状态对于在命令执行结束后立即使依赖的功能失效（并更新为新值）可能是至关重要的。
• IRegister – 寄存器数据类型用于无法映射到任何其他数据类型的普通内存块。它们通过 HALCON 的 字符串 参数类型进行接口，寄存器值是寄存器内存的十六进制字符串表示。

采集设备设置的当前状态（定义其工作状态的所有参数值）可能会在未进行采集时持续存在，即在 grab_image_start 或 grab_image_async 之前或 set_framegrabber_param(..., 'do_abort_grab', 1) 之后。这不仅适用于实际设备参数，也适用于配置 GigE Vision 的参数和 GigE Vision 图像采集接口的内部参数。设备参数通常保留到设备断电为止。GigE Vision 生产者模块和消费者参数会一直保留，直到调用 close_framegrabber。使用参数 "settings_selector" 可指示哪些参数需要持久化。持久化功能包括两个步骤，将当前配置存储到文件中，然后重新加载回设备。可以使用 "do_write_settings" 参数存储由 "settings_selector" 指示的选定模块设置，之后再使用 "do_load_settings" 参数重新加载，并在两种情况下都指定所需的持久化文件路径。要查询某个功能是否可以持久化，请使用后缀"_streamable"。

请注意，虽然文件格式有意采用人类可读格式，而且可以根据需要对文件进行手工修改，但此类修改应由熟悉 GenICam 持久功能内部结构和特定设备的人员谨慎完成。对文件的不当修改会导致使用时出错。

重要的是要知道，设备相关功能的持久性虽然由软件执行，但实际上是设备端的功能。如果设备不正确或不完整地执行了持久性支持，它将无法按预期运行--在这种情况下，制造商可以提供更多信息或帮助。

设备和/或 GigE Vision 生产者可能会根据当前状态阻止与持久性相关的操作，例如在采集正在进行时。

相同的持久性文件可应用于相同类型和固件版本的整套设备。将持久性文件应用于其他类型的设备或使用不同固件版本的设备，很可能会导致不一致，甚至完全失效——相应的设备制造商应为此类使用情况提供指导。

除了 "do_write_settings" 外，还将使用参数 "do_write_configuration" 与 GenICam 功能描述文件选择 一节中记录的 ini 文件一起写入特征持续文件。该命令将生成扩展版本的持续文件，不仅存储当前设备配置，还存储用户集和定序器集的内容（如果设备支持这些内容）。此外，它还将为所有 GigE Vision 生产者模块（系统、接口、设备和数据流）生成持久文件。ini 文件中的持久文件条目格式如下：

 
RemotePersistence=%PATH_TO_PERSISTENCE_FILE_OF_THE_DEVICE% 
SystemPersistence=%PATH_TO_PERSISTENCE_FILE_OF_THE_SYSTEM_MODULE% 
InterfacePersistence=%PATH_TO_PERSISTENCE_FILE_OF_THE_INTERFACE_MODULE% 
DevicePersistence=%PATH_TO_PERSISTENCE_FILE_OF_THE_LOCAL_DEVICE_MODULE% 
StreamPersistence=%PATH_TO_PERSISTENCE_FILE_OF_THE_STREAM_MODULE% 

如果特定设备不支持持久功能（或根本不支持），可使用 GenICam 的 UserSetSave/UserSetLoad 功能（如果设备支持）。这些功能允许在设备的非易失性存储器中存储/加载设备设置。

MVTec EasyParams 是一组基于设备常规 GenICam 功能的 MVTec GenTL 消费者参数。通过这些参数，可以轻松访问最常用的相机参数。
可通过调用 "available_easyparam_names" 获取 EasyParams 列表。请注意，"available_param_names" 不包括 EasyParams。MVTec EasyParams 以 [Consumer] 前缀开头，表示它们是 HALCON GenTL 消费者本身的内部参数。
自 HALCON 22.11 版起，这些参数可通过 HDevelop 图像采集助手中的独立选项卡使用。
如果您的设备不支持其中一个 EasyParam，查询其访问权限将返回 "ni"（not implemented，未执行）。如果返回的是 "na"（not available，不可用），则表示该 EasyParam 受支持但当前不可用，例如，它取决于另一个 EasyParam 的当前状态或一个或多个 GenICam 功能的访问，或者因为图像采集正在运行。在后一种情况下，请使用 set_framegrabber_param(..., 'do_abort_grab', ...) 停止采集。
MVTec EasyParams 列表：

• 一般设备信息：
  • [Consumer]info_general
• 曝光功能：
  • [Consumer]exposure_auto
  • [Consumer]exposure
• 增益功能：
  • [Consumer]gain_auto
  • [Consumer]gain
• 触发功能：
  • [Consumer]trigger
  • [Consumer]trigger_activation
  • [Consumer]trigger_delay
  • [Consumer]trigger_software

有关每个 MVTec EasyParam 的详细信息，请参阅 "获取图像采集卡参数" 和 "设置图像采集卡参数 " 一节。
另见 HDevelop 示例 usb3vision_easyparams.hdev。

图像采集可以是同步的（grab_image/grab_data），也可以是异步的（grab_image_start/grab_image_async/grab_data_async），参见算子的参考文档。
该接口可完全配置和控制相机的采集过程。请注意，当采集激活时，GenICam 可能会锁定相机或生产者的某些功能。
使用同步抓取（grab_image/grab_data）时，每张图像都会在内部开始新的采集，因此应用程序总能获得新的图像。在传送图像之前，采集会再次停止，因此在每次 grab_image/grab_data 调用之间，所有与采集相关的功能都不会被锁定。
通过 grab_image_start 显式启动或 grab_image_async/grab_data_async 隐式启动的异步抓取，接口会在内部保持抓取运行，收集更多图像，并通过未来的 grab_image_async/grab_data_async 调用进行传输。在使用 set_framegrabber_param(..., 'do_abort_grab', ...) 停止采集之前，采集相关的功能会被锁定。
HALCON 采集接口可正确识别设备上配置的 "连续"、"单帧" 和 "多帧" 采集模式，并相应调整采集控制逻辑。
此外，该接口还可独占访问对采集控制至关重要的几个远程设备功能（AcquisitionStart、AcquisitionStop、AcquisitionAbort、TLParamsLocked）。用户应用程序无法直接控制这些功能。
抓取算子的 "图像" 和 "数据" 版本之间的区别记录在 采集——抓取算子 中。

接口默认为采集引擎分配 4 个缓冲区（可通过 open_framegrabber 的 "Generic" 参数更改缓冲区数量）。
每当成功获取新图像并将其作为 HALCON 图像传递给应用程序时，接口都会锁定缓冲区（不会将其返回给获取引擎），直到应用程序调用新的抓取相关算子或使用 set_framegrabber_param(..., 'do_abort_grab', ...) 中止获取。在此期间，查询 "最后获取" 的缓冲区信息是完全安全的，例如通过 get_framegrabber_param 参数（如 "buffer_timestamp"、"buffer_is_incomplete"、"image_width" 和 "image_height"）查询缓冲区属性。这也适用于最终存在于缓冲区中的 块数据 ，并且也可在易失性模式下使用。
当应用程序调用新的抓取相关算子时，接口会将缓冲区返回给采集引擎，与缓冲区相关的查询不再有效。

可能出现的情况是，相机临时或持续获取数据的速度高于应用程序处理数据的速度。在这种情况下，USB3 Vision 生产者的流引擎会根据 "[Stream]StreamBufferHandlingMode" 参数决定如何处理获取的缓冲区。

请注意，可通过 高级流引擎控制 中描述的附加参数进一步控制流引擎行为。

对于现代通用图像采集接口，应用程序无法根据当前设置对来自设备的图像格式做出有效假设。例如，有些设备允许在采集过程中更改图像格式属性。
HALCON USB3Vision 图像采集接口完全支持这些用例。它会检查每个缓冲区的图像格式和其他重要属性，并生成与所采集图像格式和最终用户配置的输出格式参数（如 "color_space" 和 "bits_per_channel" ）相对应的 HALCON 图像。只有在缺少有关缓冲区的必要信息时，才会使用当前设置作为备用。

采集接口提供了两种从设备采集图像（或其他）数据的机制：grab_image/grab_image_async 和 grab_data/grab_data_async。这两种机制可能更适合不同的使用情况。从内部看，这两种机制的工作原理完全相同（尤其是如何从设备上获取和处理数据），它们的不同之处在于如何向应用程序提供输出。
"传统的" grab_image/grab_image_async 算子仍然适用于只从设备上获取单个二维图像的简单用例。目前，HDevelop 的图像采集助手也在使用这种方法。但是，如果设备正在流式传输更复杂的数据结构，如三维数据、多 AOI 或类似数据，grab_image/grab_image_async 就无法提供所有输出。在所有这些情况下，它只会提供在获取的数据中找到的第一个图像。
"扩展的" grab_data/grab_data_async 算子允许输出任意数量的 HALCON 图像和任意数量的控制数据。因此，它适用于需要输出不止一个 HALCON 图像的高级用例。一个重要的使用案例是通过三维设备（使用三维设备 ）进行采集，此时算子可以通过控制数据输出建立并输出三维对象模型。当设备为单次采集输出多个图像时，它还可用于其他（甚至可能是特定设备）情况。
可借助 "image_contents"、"data_contents"和相关参数查询所提供输出的结构。
grab_data/grab_data_async 也可用于简单的单图像用例——在这种情况下，它们只需提供单个 HALCON 图像和零控制数据输出。因此，它们可以完全替代传统的 grab_image/grab_image_async 算子。

采集接口完全支持 GenICam 标准三维设备模型，因此能够无缝集成符合该模型的三维设备。这尤其意味着应用程序无需关心特定设备的三维数据格式，采集接口将使用设备的信息生成三维数据。
如果收到指示（使用 "create_objectmodel3d" 参数），采集接口将根据从设备采集的坐标数据生成三维对象模型。HALCON 的三维对象模型相关算子可以直接使用该模型。
最终三维对象模型的完整性和准确性在很大程度上取决于实际坐标数据，特别是设备提供的三维配置信息。由于三维配置元数据通常是通过块数据机制（ 块数据 ）从设备中传递的，因此必须注意设备是否完全启用了块数据生成功能。
如果缺少某些重要的三维配置信息，采集接口会尝试使用合适的默认值，但三维对象模型的输出质量可能会降低。
三维对象模型的创建还可受到 "coordinate_transform_mode"、"confidence_mode"、"confidence_threshold"、"add_objectmodel3d_overlay_attrib"等附加参数的影响。
注意：对于不符合 GenICam 标准三维设备模型的设备，无法自动生成 HALCON 三维对象模型。
请注意，只有 grab_data/grab_data_async 算子支持三维对象模型输出，而不能使用 grab_image/grab_image_async 获取。除三维对象模型外，grab_data/grab_data_async 算子还以 HALCON 图像的形式输出实际原始坐标数据。可以借助 "image_contents"、"data_contents"和相关参数来识别各个输出。

HALCON USB3Vision 图像采集接口内置一个转换器，可将 GenICam 标准功能命名规则中描述的像素格式转换为所需的 HALCON 图像格式。参数 ColorSpace 和 BitsPerChannel（open_framegrabber，最终为 set_framegrabber_param）定义了生成的 HALCON 图像所需的格式。如果将这些参数设置为默认值，则会保留来自设备的原始像素格式。
为提供对自定义像素格式（即 PFNC 未定义或 HALCON 不支持的像素格式）的基本支持，可使用值 "raw"。在这种情况下，图像采集接口无需进行任何格式转换即可将缓冲区传送给应用程序。
请注意，在获取包含图像数据以外内容的缓冲区时，也要遵循同样的原则。此类缓冲区的例子可以是文件（如压缩图像）或原始数据（智能相机处理的结果）。此类缓冲区不是真正的 "图像"，但仍可作为 "原始" HALCON 图像传送给应用程序。应用程序有责任知道如何解释这些数据。
最后但并非最不重要的一点是，如果用户明确希望接收未经任何转换的原始输入数据，也可以使用 "原始" 。例如，在获取拜耳编码图像时，指定 "原始" 意味着接口不应尝试将其解码为 RGB 或单色格式，而是直接将数据传送给应用程序。
重要的是要知道，当接口没有关于图像格式（尺寸和像素格式）的完整信息时，它必须选择一种人工格式。在这种情况下，它总是提供尺寸与缓冲区大小（图像大小的平方根）相匹配的 8 位图像。最终，HALCON 图像未使用的尾部（如果该人工图像大于源缓冲区）将被填充为零。使用 "image_raw_buffer_type"（图像提取缓冲区类型）和 "image_raw_buffer_padding_bytes"（图像提取缓冲区填充字节）参数，可以查询最后获取的缓冲区是包含已知属性的图像，还是包含其他数据（因此必须使用人工 HALCON 图像大小）以及最终尾部填充的大小。

与 GenICam 兼容的相机可以在每幅图像中以所谓的 "块数据 "格式提供附加元数据。通常需要先使用 "ChunkModeActive" 和 "ChunkSelector"/"ChunkEnable" 功能启用单个元数据 "块" 的传输。
接口以透明方式对块数据进行解码，并将其与相应的相机特征进行匹配。
实际值可通过常规参数读取机制（即 get_framegrabber_param）读取。元数据的选择取决于设备。与块相关的功能名称通常以约定俗成的前缀 "Chunk" （ 例如 "ChunkExposureTime" 或 "ChunkGain" ）开头，不过，相机文档中应包含所支持的块及其相应功能名称的所有信息。
某些与 GenICam 兼容的设备可能会实现纯块模式，在这种模式下传输的是没有图像的元数据。这种模式与 grab_image 算子不兼容，但可与 grab_data 算子一起使用。
只有在 "最后获取的缓冲区" 有效的情况下，与块数据相关的功能才会提供有意义的值， 即从最后一幅图像的传送到下一次调用任何抓取相关算子（请参阅 "采集 - 缓冲区处理 " 一节）。

相机和 USB3 Vision 生产者通过 GenICam 接口显示的任何功能以及采集接口的内部参数发生变化时，都可能收到通知。
请注意，在各种情况下都可能发出通知，包括：

• 应用程序（您）明确更改了该功能。
• 另一项功能已更改，而被通知的功能 "依赖于 "已更改的功能（依赖关系在 GenICam 描述文件中定义）。
• 功能的访问模式或当前范围已更改。
• 在未缓存功能的情况下，这是定期 "轮询" 的结果。
• 如果功能与设备事件相关联，则该功能是设备事件交付的结果。
• 由于为与块数据相对应的功能提供了新的缓冲区。

请注意，每当功能被上述操作之一 "标记为脏"（其缓存失效）时，就会发出通知。这并不一定意味着其值真的发生了变化，这需要应用程序来检查。
可以使用 set_framegrabber_callback 为个别功能注册通知回调（参见 相应的算子文档 ）。此外，还可以使用消息队列接收事件通知。在这种情况下，必须先创建一个消息队列，然后再注册单个功能 - 参见 事件消息队列 。

与 GenICam 兼容的设备可以发送异步事件，这些事件可选择携带附加数据。通常需要先使用 "EventSelector"/"EventNotification" 功能启用个别事件类型的传送。对于符合 SFNC 标准的事件，如果启用了参数 "event_notification_helper"，则可自动完成这一操作。
事件数据的解码和与相应功能（包括潜在通知）的匹配由接口透明地执行。
实际值可通过常规参数读取机制，如 get_framegrabber_param，或者如果使用消息队列接收事件，则可通过 get_message_tuple 读取。要生成的事件类型取决于设备。与事件相关的功能名称通常以约定俗成的前缀 "Event" 开头（例如 "EventFrameTrigger" 和 "EventFrameTriggerTimestamp"），不过，设备文档应包含有关支持的事件及其相应功能名称的所有信息。
虽然在一般情况下可以随时读取与最后发送的事件相对应的数据，但在使用回调接收事件 时，强烈建议将事件数据的读取与相应事件功能的通知同步进行。只有在这种情况下，才能保证读取的数据与被通知的事件实例完全一致，而不是通过同一事件的新实例来修改功能值。请注意，通知是从事件处理/调度线程的上下文中发出的，因此在处理用户回调时，事件处理机制会暂停。如果多个数据项与同一事件相关联，只需为实际事件功能注册通知，并在回调期间读取所有数据即可。
如果使用消息队列接收事件，您可以决定添加其他数据，以便与相应的事件功能一起传送，参见 事件消息队列 。在这种情况下，接口将在事件生成后立即读取所有指定的事件特征，并将其添加到相应的消息中。这就保证了发送的信息与事件发生时的实际值一致。
除了实际设备生成的异步事件外，USB3 Vision 生产者的任何模块（系统、接口、设备和数据流）都能生成异步事件（可选包括附加数据）。上述关于处理设备事件的信息同样适用于 USB3 Vision 生产者事件，包括启用/禁用这些事件（通常使用特定模块提供的 "EventSelector"/"EventNotification" 功能，即在功能名称中带有相应的模块前缀）。对于符合 SFNC 标准的事件，如果启用了参数 "event_notification_helper"，则会自动启用。
接口将自动捕捉和解码事件，并将其与相应的 USB3 Vision 生产者功能相匹配。重要的是要明白，系统和接口模块有可能被多个已打开的设备共享（参见 参数 - 设备间共享 ），因此，这些共享模块产生的异步事件也是如此。

该接口支持通过消息队列发送功能更改通知。使用 set_framegrabber_param(..., 'event_selector', ...) 选择所需的目标特征。它是与 set_framegrabber_param 相同的普通功能名称（GenICam 功能或内部参数），包括一个可能的前缀，如 "[Device]"（请参阅 参数 - 命名规则 ）。
使用 create_message_queue 创建一个接收通知的消息队列，并使用 set_framegrabber_param(..., 'event_message_queue', QueueHandle) 将其分配给所选功能。
消息队列可为任何基于 GenICam 的功能注册，即设备和 USB3 Vision 生产者发布的功能或采集接口的内部功能。此外，还可以为采集接口中发生的内部事件注册通知，特别是 "event_new_buffer" 事件，该事件会在上次采集的缓冲区信息更新时触发（抓取新缓冲区或重启采集时上次缓冲区信息失效）。
可通过调用 get_framegrabber_param(..., 'available_event_names', ...) 来查询支持的目标列表。
功能更改回调的重要用例之一是设备事件传送机制，详情请参见事件数据 和 功能更改通知 一节。
每当给定功能可能发生变化（包括范围或访问模式等其他属性）时，就会向指定队列添加一条新消息。请注意，这并不一定总是意味着该功能实际上有了新值。调用 set_framegrabber_param(..., 'event_message_queue', 0) 会取消注册先前从指定事件中注册的消息队列。请注意，接口只为每个功能保留一个注册，如果您试图为一个已经注册了消息队列的功能注册一个新的消息队列，先前的注册将被新的注册所取代。
通过 dequeue_message 可以检索到事件的信息，其中至少包含三个元组。第一个元组（键 "id"）是事件所来自的采集实例的唯一标识符。它是一个字符串，由 "<接口>:<唯一名称>" 组成。第二个元组（键 "event_name" ）是之前由 "event_selector" 指定的相应功能的名称。第三个元组（键 "event_value"）包含相应功能的值，如果可用且可读的话。
如果您决定添加其他数据与相应的事件功能一起传送，请使用 set_framegrabber_param(..., 'event_data', ...) 添加感兴趣的功能。每个事件数据功能都将附加到事件消息中，键为其名称，元组为其值（如果可读）。注意，通过 "event_data" 指定的重复信息将被忽略。被通知的功能值本身（已在 "event_value" 中报告）也将被视为重复信息，不会再次报告。

流引擎在标准用例中运行良好。不过，在特定使用情况下，必须对行为进行微调。本节中描述的参数仅用于这种高级用途，应谨慎对待——错误的配置会严重影响性能。
由于流引擎和事件引擎共享相同的资源（如 CPU 时间和 USB 子系统），建议同时考虑它们（参见 高级事件引擎控制 ）。
特别是当相机的帧率超过应用程序处理图像的速率时，就有必要调整行为。如果可能，应通过在相机中设置适当的参数来避免这种使用情况，例如使用触发模式而不是自由运行采集模式。
在通过 USB 传输数据流时，为了获得最佳性能，通常需要确保始终有一个缓冲区准备接收数据，并且该缓冲区也 "计划" 通过 USB 传输到系统的 USB 子系统。在任何其他情况下，相机都可能决定丢弃图像、只传输部分图像（尤其是在相机没有帧缓冲区或帧缓冲区有限的情况下），甚至开始出现异常。
如 采集 – 缓冲区处理 所述，采集接口会分配一组缓冲区（"用户缓冲区"），用于将采集的数据传送给用户应用程序。如果应用程序无法处理相机的帧率，那么所有这些缓冲区都会被填满，并在输出队列中等待处理，因此无法为下一次采集临时安排用户缓冲区。因此，流引擎会分配 "[Stream]StreamAuxiliaryBufferCount" 辅助缓冲区（默认为 2）。如果默认数量太少，无法防止溢出，也可以进一步增加，但在这种情况下，最好还是安排更多的用户缓冲区。
可通过 "[Stream]StreamScheduledBuffersTarget" 来调整流引擎在任何时刻都尽量保持已调度缓冲区的最小数量。为了满足这一目标，当没有足够的用户缓冲区可用时，就会调度辅助缓冲区。特别是在快速相机的情况下，如果流线程有一段时间没有调度，调度的缓冲区可能会很快用完，因此需要增加默认值 2。
如果图像已被获取到辅助缓冲区，流引擎会检查在此期间是否有新的用户缓冲区可用。如果没有，引擎会检查 "[Stream]StreamBufferHandlingMode" 参数，看是否允许覆盖输出队列中等待处理的旧缓冲区。如果有可用的用户缓冲区，数据就会被复制到该缓冲区，否则就会被丢弃。因此，使用辅助缓冲区总是会产生额外的复制开销。
另一方面，参数 "[Stream]StreamScheduledBuffersMaximum" 可控制引擎每次尝试调度的缓冲区最大数量。默认值为 4，在大多数情况下运行良好。只有在使用相机以非常快的帧率流式传输小图像时，才有必要增加该值。需要注意的是，将该值设置得比实际采集缓冲区的数量（参见 open_framegrabber 的 "num_buffers" 通用参数）更高并无意义。

请注意，最初引入此最大限制参数是由于底层 libusb 库（Windows 下）的限制，该库无法处理超过 64 个并发 USB 传输，这反过来又会给多相机设置带来问题。现在这种限制已不复存在，但为了避免向后兼容问题，我们暂时保留了相同的默认设置（已知在大多数情况下都能可靠运行）。
另请参阅控制事件引擎行为的相关功能（ 高级事件引擎控制 ）。

能否及时调度缓冲区对流引擎的性能影响很大。流引擎线程相对于系统中其他线程的优先级对此影响很大。详情请参考参数 "[Stream]StreamThreadPriority"、"[Stream]StreamThreadSchedulingPolicy" 和 "[Stream]StreamThreadApplyPriority" 的文档。设备打开时，一般会选择合适的默认优先级。
最后，可以在打开设备时使用 "streaming_mode=0" 通用参数完全禁用流基础设施。

事件引擎在标准用例中运行良好。但是，在特定的使用情况下，必须对其行为进行微调。本节中描述的参数仅用于高级用途，应谨慎对待——错误的配置会严重影响性能。
微调事件引擎与调整流引擎非常相似。由于它们共享相同的资源（如 CPU 时间和 USB 子系统），因此同时考虑它们是合理的。因此，建议学习（高级流引擎控制）中的相应说明，本节将只列出相应的事件相关参数。
与流引擎不同，事件引擎只在内部使用所有缓冲区。引擎会尝试为传入事件安排尽可能多的传输，但不会超过 "[Device]DeviceScheduledEventsMaximum" 参数的指定值。该参数目前只能读取（默认值为 2），在接口的未来版本中可能会变成可写入参数，但目前默认值在所有使用情况下都能正常工作。
事件引擎线程优先级由参数 "[Device]DeviceEventsThreadPriority"、"[Device]DeviceEventsThreadSchedulingPolicy" 和 "[Device]DeviceEventsThreadApplyPriority" 控制。设备打开时，一般会选择合适的默认优先级。
在打开设备时，可使用 "device_event_handling=0" 通用参数完全禁用事件处理基础结构。

在使用 HDevelop 图像采集助手时，以下提示有助于避免出现问题：

• 某些参数取决于特殊条件，例如有效的缓冲区或已激活的另一个参数。打开相机后，这些条件可能尚未满足，因此不会显示相关参数。使用 "刷新" 按钮可以重新读取所有参数，如果条件满足，则会显示相关参数。
• 还有一些关于图像大小和有效载荷大小的参数，只有在不采集的情况下才能更改。最安全的方法是应用操作参数 "do_abort_grab" 。请注意，必须先禁用 "更新图像"。
• 允许在流媒体激活时更改参数的行为取决于设备的功能。有些相机可能允许您在流式传输时控制曝光时间等参数，而有些相机则不允许。

HALCON GigEVision2 接口支持在软件中执行内部色彩转换。当兼容 PFNC（像素格式命名规则）的相机提供的色彩格式与用户通过参数 "color_space" 设置的格式不同时，转换将自动应用于该相机。所使用的转换算法是最基本的，并对速度进行了优化。

支持从相机（另见 PFNC）到接口（另见本文档中的 "color_space" 参数）的以下转换：

• 拜尔模式至 "rgb"：
  

  Bayer_LMMN R G1 G2 B ⇾ [R,G,B] [R,G,B] [R,G,B] [R,G,B]

  Bayer_NMML B G1 G2 R ⇾ [R,G,B] [R,G,B] [R,G,B] [R,G,B]

• 其中 G = (G1 + G2) / 2。

• Y'CbCr 至 "rgb"（注：不考虑伽玛校正）：
  

  R = Y' + 1.4020 * (Cr- M)
G = Y' - 0.34414 * (Cb- M) -0.71414 * (Cr- M)
B = Y' + 1.7720 * (Cb - M)

• RGB 至 "yuv"（"yuv "对应 PFNC 的 Y'CbCr，注：不考虑伽玛校正）：
  

  Y' = 0.299 * R + 0.587 * G + 0.114 * B
Cb = -0.16874 * R - 0.33126 * G + 0.5 * B + M
Cr = 0.5 * R - 0.41869 * G - 0.08131 * B + M

• RGB 至 "灰度"：
  

  Y' = 0.299 * R + 0.587 * G + 0.114 * B

其中 M = 128 表示 8 位原始数据，和 M = 32768 表示 16 位原始数据。
由于 8 位（0...255）的内部 16.16 定点运算和 16 位原始数据的 24.8 定点运算，结果的准确性受到限制。

采集接口支持 GenICam 固件更新标准，允许以通用方式更新支持相同标准的设备上的固件。如果设备支持该标准，其供应商会以 GUF 文件（即扩展名为 .guf 的文件）的形式分发固件更新文件。
要应用固件更新，必须在特殊配置模式（称为 "安全模式"）下打开设备（open_framegrabber）。可通过 open_framegrabber 的 "通用" 参数选择该模式，该参数必须包含 "device_access=safe-mode"。
在安全模式下打开时，大部分常规参数（由 HALCON 采集接口、设备本身或 USB3 Vision 生产者提供）将不可用。取而代之的是与给定设备和接口技术相对应的配置参数，尤其是与固件更新相关的参数。
要更新设备，首先要在 "fwupdate_file_path" 中选择 GUF 文件，然后使用 "fwupdate_update_selector" 从文件中选择一个（可能是多个）更新，最后通过 "do_fwupdate_apply" 进行应用。这些参数的文档提供了更多详细信息。
请注意，更新程序可能包括一次或多次设备重置，重置后设备必须被采集接口重新发现。重置和重新发现所需的时间由设备供应商在 GUF 文件中指定。然而，在某些情况下（取决于设备本身、其连接技术和系统设置），重新发现超时时间不够，设备无法被安全地重新发现。在这种情况下，可以指定一个额外的超时时间，将其添加到 GUF 文件中指定的超时时间中，以便成功完成进程。该参数 "fwupdate_wait_after_reset" 指定了以毫秒为单位的额外超时。
另见 HDevelop 示例 usb3vision_fwupdate.hdev.

相机和 USB3 Vision 生产者的参数通过 GenICam 访问，并在相应相机或 USB3 Vision 生产者的 GenICam 描述文件中定义，因此每个产品的参数集都不同（不过参数命名应符合 SFNC 和 GenTL SFNC GenICam 标准）。调用 get_framegrabber_param(..., 'available_param_names', ...) 会返回一个元组，其中包含所连接相机和 USB3 Vision 生产者的所有可用参数。另见有关 参数命名规则 一节。
例如，要设置 AcqHandle 所指相机的当前增益（调用 open_framegrabber 之后），用户可以调用 set_framegrabber_param(AcqHandle, 'Gain', 6.0)。
请注意，只有当参数值有效时，接口才会设置该值。不符合给定功能允许范围的整数和浮点数值会与最接近的有效值对齐。其他功能类型的无效值将被拒绝。
除了相机和 USB3 Vision 生产者的 GenICam 参数外，set_framegrabber_param 还支持以下 HALCON 接口参数：

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

• '_access'：这些参数以字符串形式提供相应参数的访问权限。可能的值有 "ro"（只读）、"wo"（只写）和 "rw"（读/写）。
• '_category'：这些参数以字符串形式提供了相应参数的类别。
• '_description'：这些参数以字符串形式提供相应参数的工具提示。
• '_displayname'：这些参数以字符串形式提供相应参数的显示名称。
• '_longdescription'：这些参数以字符串形式提供相应参数的描述。
• '_range'：例如，get_framegrabber_param(.., 'Shutter_range', ..) 将返回输出元组 [min, max, step, current]。
• '_representation'：这些参数以字符串形式提供相应参数的 GenICam 表示。它们只适用于整数参数。可能的值包括 "Linear"、"Logarithmic"、"Boolean"、"PureNumber"、"HexNumber"、"IPV4Address" 和 "MACAddress"。该表示法的目的是帮助设计图形用户界面。
• '_streamable'：这些参数以整数形式提供相应参数的持久性。假值为 0，真值为 1。
• '_string'：这些参数提供根据"_representation" 后缀格式化为字符串的整数值。对于"_representation值 "IPV4Address"、"MACAddress" 和 "HexNumber" 尤其有用。
• '_type'：这些参数提供了相应参数的字符串类型。
• '_values'：这些参数以元组形式提供相应参数的有效值列表，例如，get_framegrabber_param(.., 'volatile_values', ..) 将返回输出元组 ['enable', 'disable']。
• '_visibility'：这些参数以字符串形式提供相应参数的可见性。可能的值有 "beginner"初学者、"expert"专家 和 "guru"大师。

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

此接口不支持。

此接口不支持。

该接口通过算子 set_framegrabber_callback 和 get_framegrabber_callback 支持功能更改回调。
回调可用于任何基于 GenICam 的功能，即设备和 USB3 Vision 生产者通过 GenICam 描述文件发布的功能，以及采集接口的内部参数。
可通过调用 get_framegrabber_param(..., 'available_callback_types', ...) 查询支持的回调目标列表。
设备事件传送机制是功能更改回调的重要用例之一，详情参见 事件数据 和 功能通知 一节。set_framegrabber_callback 的 "CallbackType" 参数定义了注册回调的功能。它是与 set_framegrabber_param 相同的纯功能名称，包括一个可能的前缀，如 "[Device]"（请参阅 参数命名规则 ）。
每当给定功能可能发生变化（包括范围或访问模式等其他属性）时，注册的回调函数就会被调用。请注意，这并不一定总是意味着该功能实际上有了新值。如果回调函数被设置为 NULL，相应的回调函数将被取消注册。请注意，接口只为每个特性保留一个注册，如果您试图为一个已注册回调函数的功能注册一个新的回调函数，先前的注册将被新的注册所取代。

回调函数的签名是 Herror (__stdcall *HAcqCallback)(void *AcqHandle, void *Context, void *UserContext) 并使用以下参数：

• AcqHandle： 相应图像采集实例的采集句柄。
• Context： 特定回调的可选上下文数据。到目前为止，该参数未被使用，即 Context 设置为 NULL。
• UserContext： 特定回调的可选上下文数据。到目前为止，该参数尚未使用，即 UserContext 设置为 NULL。

需要注意的是，用户专用回调函数的执行时间必须尽可能短，因为在回调函数执行期间，可能会阻塞对其他内部回调的处理。要做到这一点，可以将当前的处理工作从用户专用回调函数转移到一个单独的线程中，该线程通过信号或事件进行控制。回调函数在底层接口或驱动程序的上下文中执行。
同样重要的是要了解，回调可能会作为参数设置或抓取操作的副作用被触发，即可能会在各自的锁中被调用。用户有责任在回调处理程序中考虑到这一点，以避免死锁风险。

 

该接口通过算子 set_framegrabber_callback 和 get_framegrabber_callback 支持功能回调。更多信息参见 set_framegrabber_callback。

启动新的异步抓取。另见 grab_image_start 和有关采集控制一节 。请注意，此算子会启动 GigE Vision 生产者和设备上的采集，并锁定采集期间受保护的功能。如果 grab_image_start 被重复调用，则会在 GenTL 生产者和设备上重新开始采集。这意味着缓冲区队列和所有与流相关的统计参数（如 "buffer_frameid"）都会被重置。可以使用 set_framegrabber_param(..., 'do_abort_grab', ...) 停止采集（并解锁功能）。

grab_image 启动对单幅图像的新同步抓取。另见 grab_image、有关采集控制一节 和 有关抓取算子 。请注意，该接口会将获取的图像转换为由参数 "bits_per_channel" 和 "color_space" 指定的所需图像格式。

grab_image_async 返回单幅图像，并开始下一次异步抓取。另见 grab_image_async、有关采集控制一节 和 有关抓取算子 。请注意，该接口会将获取的图像转换为由参数 "bits_per_channel" 和 "color_space" 指定的所需图像格式。
HALCON GenICamTL 采集接口忽略了 grab_image_async 算子的 "MaxDelay" 参数，因为所有 USB3 Vision 生产者都无法可靠地支持该参数。如果需要，应用程序需要自行实现其他功能。

grab_data 启动一个新的同步抓取，根据输入和配置的不同，可能会产生输出图像元组和各种数据输出元组。另见 grab_data、有关采集控制一节 和 有关抓取算子 。请注意，该接口会将获取的图像转换为由参数 "bits_per_channel" 和 "color_space" 指定的所需图像格式。输出元组使用 "data_contents"、"image_contents" 及相关参数描述。

grab_data_async 返回获取的图像/数据，并开始下一次异步抓取。另见 grab_data_async、有关采集控制一节 和 有关抓取算子 。请注意，该接口会将获取的图像转换为由参数 "bits_per_channel" 和 "color_space" 指定的所需图像格式。输出元组使用 "data_contents"、"image_contents" 及相关参数描述。
HALCON GenICamTL 采集接口忽略了 grab_image_async 算子的 "MaxDelay" 参数，因为所有 GenTL 生产者都无法可靠地支持该参数。如果需要，应用程序需要自行实现其他功能。

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

该接口有以下示例：

• usb3vision_acquisition_events.hdev - 示例如何使用消息队列处理带有附加事件数据的事件。
• usb3vision_2cameras.hdev - 从两个相机抓取图像。
• usb3vision_doo_abort_grab.hdev - 终止正在进行的图像采集。
• usb3vision_easyparams.hdev - 处理 MVTec EasyParams。
• usb3vision_fileaccess.hdev - 从 GenICam 设备上传和下载文件的示例。
• usb3vision_frame_rate.hdev - 测量采集设备有效帧率的示例。
• usb3vision_fwupdate.hdev - 使用 GenICam 的固件更新模块应用固件更新的示例。
• usb3vision_information.hdev - 用于收集系统和相机配置信息的程序。请求支持时请附上生成的文件。
• usb3vision_install_driver.hdev - 为设备安装必要的驱动程序，然后将其打开。这与 HDevelop 图像采集助手用于此目的的机制相同。
• usb3vision_io_control.hdev - 控制设备 GPIOs 的示例。
• usb3vision_parameters.hdev - 列出设备的所有参数。
• usb3vision_parameter_persistence.hdev - 演示将参数值写入文件以及从文件中恢复参数值。
• usb3vision_simple.hdev - 一个显示接口用法的简单示例。
• usb3vision_software_trigger.hdev - 软件触发器的使用。

如果 HALCON USB3Vision 接口出现问题，以下提示可能有助于解决问题。

一般情况：

• 检查是否使用了 最新版本 的 HALCON USB3Vision 接口。
• 检查 系统要求。
• 检查设备是否有最新固件。
• 启用 HALCON 中的低级错误信息，以查询有关问题的更多信息（如果适用，请检查 HDevelop 中的输出控制台）。

GenICam:

• 查是否使用了正确的 GenICam 二进制文件。HALCON 在私人安装中使用官方二进制文件（HALCONROOT 目录中的 genicam 文件夹）。如果您的路径或某些系统路径中存在其他 GenICam 二进制文件（对于 Windows，例如 c:\Windows\System32\；对于 Linux，例如 /usr/lib 或类似目录），请将它们与 HALCON 安装中的二进制文件进行比较，以确保它们是官方二进制文件。使用非官方二进制文件可能会导致奇怪的问题。

如果仍有问题，请联系当地经销商。

您的支持请求需要以下信息，以避免不必要的查询。

• 使用的 HALCON 和采集接口版本。
• 使用 HALCON 架构（尤其是 32 或 64 位）。
• 低级错误信息（如果有）。
• 相机制造商、型号和固件版本。
• 所用 GenICam GenTL 生产者的详细信息（至少包括名称和版本）。
• 计算机系统的详细信息，如操作系统、内存和 CPU。
• 重现问题的最小示例代码（如 HDevelop 脚本）。
• 描述观察到的和预期的行为。

请运行 HDevelop 示例 usb3vision_information.hdev，收集有关系统和相机配置的信息，然后在请求支持时附上生成的文件。

该接口依赖于第三方库。有关版权和许可信息，参见 HALCON 基本目录中的文件 third_party_genicamtl.txt。除非文件中有明确说明，否则将不加修改地使用这些库。

您可以通过发送电子邮件至 info@mvtec.com 申请获得 GPL 或 LGPL 许可的第三方库的源代码，邮件主题为 "申请第三方库的源代码"。

• 修订 20.11.19（2023 年 4 月 5 日）：
  • 如果数值参数除了纯数值外还有其他特殊表示形式，现在可以使用后缀 "_representation" 来查询表示形式的类型。
  • 现在可以使用后缀 "_string" 查询参数值的字符串表示形式。
  • libCLAllSerial 共享对象已从 GenApi 3.4.0 的再分发中移除。
  • 新增了 HDevelop 示例 usb3vision_software_trigger.hdev，以演示如何结合 grab_image_async 使用软件触发器。
  • 重写了 usb3vision_doo_abort_grab.hdev 示例。
  • third_party_genicamtl.txt 现在包含指向相应软件位置的链接。参见 第三方库的使用 。
• 修订 18.11.18（2022 年 10 月 7 日）：
  • MVTec EasyParams 以简单易用的方式处理最常见的 GenICam 功能。
  • 新增参数 "available_easyparam_names"，用于返回 MVTec EasyParams 列表。
  • 添加了 HDevelop 示例 usb3vision_easyparams.hdev，以演示如何处理 MVTec EasyParams。
  • 在 Unix 系统上，加载包含 Windows 行结束符的 GenICam 持久文件失败。这一问题已得到解决。
• 修订 18.11.17（2022 年 7 月 1 日）：
  • 现在支持 1.2 版 USB3 Vision 规范。这包括三维设备等使用的 GenDC 流。
  • 在上一版本中，该接口无法在 macOS 上加载。该问题已得到修复。
• 修订 18.11.16（2022 年 5 月 11 日）：
  • 在 Unix 系统上，加载在 Windows 系统上编写的 Consumer persistence 或配置 ini 失败。这一问题已得到修复。此外，在 Windows 系统上写入消费者持久性文件或配置 ini 文件已改为使用 Unix 行结束符。
  • 现在可以使用序列号连接，参见 识别和打开设备 。
  • 底层 GenApi 版本已更新至最新的 3.4 正式版。这修复了当设备无法执行底层命令 "DeviceRegistersStreamingEnd" 时，在 "do_load_settings" 过程中出现的崩溃问题。
  • 现在可以对 "available_param_names" 列出的任何参数接收 功能更改通知。
  • 添加了一个新参数 "event_new_buffer"，该参数只能作为事件使用，参见 功能更改通知 及后续内容。
  • 通过 事件消息队列 机制传送的每条消息都存在内存泄漏问题。该问题已得到解决。
  • 事件中传入的消息 的标识符（关键字 "id"）并不总是唯一的。这一问题已得到解决。字符串": "中的设备名称现在与 info_framegrabber 中的 "unique_name" 相对应。
  • 从主机文件系统检索 GenICam XML 描述文件的功能被破坏。该问题已得到修复。
  • 将底层 libusb 版本更新至 1.0.24。这解决了在 Windows 系统中，控制、流和事件通道同时安排的 USB 传输数量限制为 64 的问题。因此，特别是在使用多相机的情况下，可能会出现困难。
  • HDevelop 脚本 usb3vision_information.hdev 现在可将输出数据保存到用户的文档文件夹中，以避免出现写入权限缺失的问题。此外，脚本现在可以处理设备唯一名称中的非字母数字字符。此外，还修复了一个与恢复原始触发器设置有关的问题。
• 修订 18.11.15（2021 年 10 月 22 日）：
  • 现在支持 GenICam 像素格式命名规范规定的打包拜尔格式。
  • 在上一版本中，设备无法在 macOS 上初始化。该问题已得到修复。
  • 消费者模块的读写参数是可流参数，即可以通过 "do_write_settings" 或 "do_write_configuration" 进行持久化。然而，对于这些后缀为"_streamable" 的参数，get_framegrabber_param 返回值为 0。该问题已得到修复。
  • 现在，该接口的发布包中包含了为 HDevelop 示例浏览器提供元信息的文件。
• 修订 18.11.14（2021 年 2 月 24 日）：
  • 实用程序 libusb-1.0-usan.dll 和 libwdi-usan.dll再次依赖于 Visual Studio 2013 运行时库。该问题已得到修复。
  • 底层 GenApi 版本已更新至最新的官方版本 3.3。
  • 由编码器控制的线扫三维设备组装 ObjectModel3D 的过程已大大加快。为了实现这种加速，设备必须按照 GenICam 标准功能命名规则 2.7 及更高版本的描述，通过其 ValueArrayCandidates 宣布 ChunkEncoderValue 和 ChunkScanLineSelector。
  • 对于以 "token:value" 形式提供设备字符串的 open_framegrabber，必须包含分隔符"|"。这一限制已被取消。
  • 除非设置了环境变量 TEMP、TMP 或 TMPDIR，否则 GenICam 缓存机制将不起作用。现在，/tmp 或 HALCONROOT 被用作备用。
  • 新增了 HDevelop 示例 usb3vision_frame_rate.hdev，用于测量采集设备的帧频。
  • HDevelop 示例 usb3vision_acquisition_events.hdev 在事件快速进入时会陷入死锁。该问题已得到修复。
  • 重构了 HDevelop 示例 usb3vision_information.hdev，现在它调用新的函数库 genicamtl_information.hdpl。此外，新版本关闭了触发模式，以便测试图像采集。
  • 改进了错误处理。现在可以使用算子 get_extended_error_info 查询有关错误原因的附加信息。对于 HALCON 语言接口（C# 和 C++），HALCON 异常类提供了访问附加错误信息的方法。
• 修订 18.11.13（2020 年 10 月 27 日）：
  • 此接口无法从 Linux 和 macOS 上的 .NET Core 应用程序中加载。该问题已得到修复。
  • 添加了对 "YCbCr411_8_CbYYCrYY"、"YCbCr422_8" 和 "YCbCr422_8_CbYCrY" 像素格式的支持。
• 修订 13.0.12（2020 年 9 月 18 日）：
  • Most file operations did not support UTF-8 file names. This problem has been fixed. However, some of the operations like 固件更新 are managed by GenICam GenApi which might not support them.
  • 在上一版本中，"do_write_configuration" 没有将生成 xml 文件的路径写入生成的 ini 文件。该问题已得到修复。
• 修订 13.0.11（2020 年 8 月 7 日）：
  • "do_write_configuration" 已被扩展用于为 GenTL 消费者生成持久文件（持久化 HALCON USB3Vision 图像采集接口本身的内部参数，如 "grab_timeout" ），参见 参数– 持续设备状态。
  • 现在，在设备已打开的情况下，可以为单个 GenTL 生产者模块或 GenTL 消费者模块写入和加载持久性文件。迄今为止，只有远程设备可以做到这一点。可通过参数 "settings_selector"（设置选择器）选择要写入或加载的持久化文件。
  • 使用 open_framegrabber 加载持久化文件时，部分持久化参数值被覆盖。该问题已得到修复。
  • 在 18.05 之前的 HALCON 版本中，get_framegrabber_param(..., 'event_message_queue', ...) 失败。该问题已得到修复。
  • 添加了 HDevelop 示例 usb3vision_information.hdev，用于收集系统和相机配置信息。
  • 添加了 HDevelop 示例 usb3vision_parameter_persistence.hdev，以演示向文件写入参数值和从文件恢复参数值。
  • 参数 "available_event_names" 被错误地写成了 "available_event_types"。该问题已得到修复。
• 修订 13.0.10（2019 年 12 月 10 日）：
  • 将底层 GenApi 版本更新至最新正式版本 v3.2。更新包括用户和序列器集持久性的错误修复以及其他小错误修复。
  • 参数 "num_buffers" 的任意最大值限制为 1023。这一限制已被取消。
  • 实用程序 hAcqUSB3VisionElevate.exe、libusb-1.0-usan.dll 和 libwdi-usan.dll依赖于 Visual Studio 2013 运行时库。此问题已得到修复。
• 修订 13.0.9（2019 年 7 月 22 日）：
  • 现在，您可以使用"_streamable" 后缀查询功能是否可以持久化。
  • 扩展了 HDevelop 示例 usb3vision_parameters.hdev，以检查参数是否可以持久化。
  • 此接口的分发包中已添加文件 third_party_usb3vision.txt。
  • 在 x64-linux 架构上，辅助实用程序 hAcqUSB3VisionElevate 因找不到 libusb-1.0-usan.so.0 而被破坏。该问题已得到修复。
• 修订 13.0.8（2019 年 5 月 2 日）：
  • 已添加对 "BiColorRGBG8" 和 "BiColorBGRG8" 像素格式的支持。
  • 从 grab_data 和 grab_data_async 中生成的三维对象模型现在可以使用二维映射。这大大加快了多个算子处理三维对象模型的速度。
  • 新增 HDevelop 示例 usb3vision_io_control.hdev，以演示如何控制设备的 GPIOs。
• 修订 13.0.7（2019 年 1 月 21 日）：
  • 从三维图像生成 HALCON ObjectModel3D 的机制已扩展到差分图像。此类图像需要包含 SFNC 2.4 中指定的以下块："ChunkScan3dFocalLength"、"ChunkScan3dBaseline"、"ChunkScan3dPrincipalPointU"、"ChunkScan3dPrincipalPointV"。
  • 当相机发送最近过期的 GenCP 确认时，图像采集失败。该问题已得到解决。
• 修订 13.0.6（2018 年 10 月 30 日）：
  • 将底层 GenApi 版本更新至最新正式版本 v3.1。请注意，您 HALCON 安装程序中的 genicam 目录也将随之更新。更新包括加速数学解析器、改进与序列器结合的持久性，以及修复相应功能不可用但数值可用的问题。
  • 现在支持 GenICam 的文件访问功能。请参见新参数 "fileaccess_file_path"、"fileaccess_remote_name"、"do_fileaccess_download"、"do_fileaccess_upload"、"do_fileaccess_delete"，以及新的 HDevelop 示例 usb3vision_fileaccess.hdev。
  • 现在支持 GenICam 的固件更新。参见 固件更新 和新的 HDevelop 示例 usb3vision_fwupdate.hdev。
  • 现在支持在消息队列中接收 GenICam 事件，参见 事件消息队列。到目前为止，GenICam 事件只能通过回调来支持，因此无法在 HDevelop 中使用。此外，还添加了一个新的 HDevelop 示例 usb3vision_acquisition_events.hdev，以显示此功能。
  • "do_write_configuration" 已被扩展，不仅能存储当前设备配置，还能为所有 USB3 Vision 生产者模块（系统、接口、设备和数据流）生成持久文件，参见 参数– 持续设备状态。
  • 添加了新参数 "buffer_timestamp_ns" 和 "device_timestamp_frequency"，以提高 "buffer_timestamp" 的可用性。
  • 传递给 open_framegrabber 的某些通用参数无法通过 get_framegrabber_param 获取。该问题已得到修复。
  • 长度超过 1024 个字符的字符串参数会被 get_framegrabber_param 静默裁剪。该问题已得到修复。
  • 当 "start_async_after_grab_async" 设置为 "禁用" 时，远程设备上的采集会在每帧后停止。该问题已得到修复。
• 修订 13.0.5（2018 年 4 月 27 日）：
  • libwdi-usan.dll 中包含的驱动程序安装程序依赖于 Microsoft Visual Studio 2010。该问题已得到修复。
  • 添加了对 "Mono4p" 像素格式的支持。
  • 添加了对 "YCbCr411_8" 像素格式的支持。
  • 如果不支持的像素格式与支持的 Mono 格式足够相似，现在会尝试以实际图像尺寸返回。之前，所有不支持的格式都以正方形图像返回（参见 原始输出格式 ）。
  • 当 "DeviceUserID" 设置为" "（单个空格）时，无法用于连接。该问题已得到修复。
  • 当尝试使用繁忙设备的 DeviceUserID 连接该设备时，会出现误导性低级错误。该问题已得到修复。
  • 在 Unix 系统上，HALCON 在未调用 close_framegrabber 的情况下结束时会崩溃。该问题已得到修复。
  • 将基础 libusb 版本从 1.0.16 更新至 1.0.21。
• 修订 13.0.4（2017 年 11 月 28 日）：
  • libusb-1.0-usan.so.0 has been moved to a subdirectory on Linux systems.
  • HALCON 库的技术依赖已被移除。
  • 已添加新参数 "event_notification_helper"，如果回调是在符合 SFNC 标准的事件上注册，该参数可让辅助程序在 set_framegrabber_callback 过程中自动设置 "EventNotification"。更多信息，参见 事件数据。
  • 添加了新参数 "buffer_frameid" 和 "image_pixel_format"。
  • 在未注册的回调上调用 get_framegrabber_callback 时，会返回错误信息。该问题已得到修复。
  • 对于某些相机，即使启用了 "start_async_after_grab_async"，在 "SingleFrame" 或 "MultiFrame" 模式下，grab_image_async 也不会启动新的采集。该问题已得到修复。
  • 通过多次更改相机参数达到 GenCP 请求 ID 的 16 位边界时，有一项设置失败。该问题已得到解决。
• 修订 13.0.3（2017 年 5 月 3 日）：
  • 将底层 GenApi 版本更新到最新正式版本 v3.0.2，其中包含一些小错误修复。
• 修订 13.0.2（2017 年 3 月 16 日）：
  • 在图像不完整的情况下，错误地返回错误代码 H_ERR_FGWR (#5307)。该问题已得到解决。现在，不完整的图像将被传送，参数 "buffer_is_incomplete" 将返回 true。
  • 系统要求已更新为 libudev.so.1 或更高版本。
  • 扩展了接口文档，现在包含了对 info_framegrabber(...,'info_boards',...) 所返回字符串的描述。
  • 添加了新的 HDevelop 示例 usb3vision_2cameras.hdev，该示例展示了如何通过两个相机使用 USB3 Vision 接口。
  • 添加了新的 HDevelop 示例 usb3vision_do_abort_grab.hdev，显示如何终止正在进行的图像采集。
• 修订 13.0.1（2016 年 10 月 28 日）：
  • HALCON 13 版本的接口。
  • 新增对 GenTL 1.5 的支持。这主要意味着支持三维 数据采集，参见 使用三维设备。
    因此，实现了 grab_data/grab_data_async 算子，参见 采集 – 抓取算子。
    为控制三维数据采集，引入了以下参数： image_contents、image_source_id、image_region_id、image_purpose_id、image_raw_buffer_type、image_raw_buffer_padding_bytes、data_contents、data_source_id、data_region_id、data_purpose_id、create_objectmodel3d、coordinate_transform_mode、confidence_mode、confidence_threshold、add_objectmodel3d_overlay_attrib。集成生成器 Usan 已相应更新至 1.0.7 版。
• 修订 6.7（2016 年 7 月 14 日）：
  • 将集成生成器 Usan 更新至 1.0.6 版。改进了不兼容 Usan 默认传输对齐方式的相机的流处理。
• 修订 6.6（2016 年 5 月 13 日）：
  • 将底层 GenApi 版本更新到最新的官方版本 v3.0.1。以前的版本无法打开某些特定的相机，在最糟糕的情况下，使用这些设备时应用程序也会崩溃。该问题已得到修复。请注意，HALCON 安装程序中的 genicam 目录也将随之更新。
  • 由于无法在一个以上的进程中同时使用 USB3 Vision 接口，因此将集成生成器 Usan 更新至 1.0.5 版。该问题已得到修复。
  • 在 Windows 环境下，如果环境变量 路径 为空，open_framegrabber 就会崩溃。该问题已得到修复。
• 修订 6.5（2016 年 2 月 15 日）：
  • 将底层 GenApi 版本更新至最新的官方版本 v3.0，这样打开设备的速度更快，所需的内存更少。请注意，HALCON 安装中的 genicam 目录也将随之更新。
  • 添加了对 "Mono10p" 和 "Mono12p" 像素格式的支持。
  • Added limitation for OS X.
  • 为本文档添加了 "使用内部色彩转换" 段落。
  • 将集成生成器 Usan 更新至 1.0.4 版。与某些设备结合使用时，无法以较小的 ROI 达到全帧率。该问题已得到修复。
  • 根据该文档，get_framegrabber_param(..., 'AnyParameter_range', ...) 返回的第四个值是默认值。实际上，它是当前值。因此，本文档已作相应调整。
• 修订 6.4（2015 年 10 月 30 日）：
  • 有关 Visual Studio C++ Redistributable 软件包的系统要求已更新。
  • 当抓取被中止时，抓取算子会返回错误代码 H_ERR_FGABORTED (#5336)，而不是之前的 H_ERR_FGF (#5306)。
  • 在设备不允许停止采集（例如由于连接中断）的情况下，调用参数 "do_abort_grab" 无法终止正在运行的抓取。这一问题已得到解决。请注意，在这种情况下，与设备的通信会中断，因此强烈建议重新初始化。
  • 更新了有关驱动程序要求和与其他接口或软件配合使用的文档。
  • 新增了对用户自定义名称的支持。因此，info_framegrabber(...'info_boards'...) 和 info_framegrabber(...'device'...) 返回的字符串已扩展至包括新条目 unique_name:<unique name> 和 user_name:<user-defined name>（与 UserDeviceID 相对应）。新的 unique_name 条目的内容与以前的设备条目的内容相同。open_framegrabber 现在也接受用户自定义名称。
• 修订 6.3（2015 年 6 月 10 日）：
  • 在 Windows 环境下，某些 GenICam 动态库无法正确加载/卸载，并会打印出低级错误。该问题已得到修复。
  • 如果在第一次抓取之前调用 do_abort_grab 会返回错误。该问题已得到修复。
  • 对于 "na"（not available，不可用）参数，既没有使用范围属性，也没有使用值属性。该问题已得到解决。
  • 参数 "grab_timeout" 和 "delay_after_stop" 缺少范围属性。该问题已得到修复。
  • 如果参数没有访问属性和可见性属性，它们会返回 "未定义"。现在，如果它们不可用，则会返回错误信息。
  • "available_param_names" 返回的不是所有已实现的参数。现在，除了 "ro"（只读）、"wo"（只写）和 "rw"（读写）参数外，它还会返回 "na"（不可用）参数，但仅限于可见性不是 "不可见" 的情况。请注意，参数的访问模式可能会在运行时发生变化。
  • "num_buffers" 的文档对内部使用额外缓冲区的必要性不够明确。文档已得到改进。
  • 参数 "buffer_is_incomplete"、"buffer_timestamp"、"raw_buffer_padding_bytes"、"raw_buffer_type" 的固定访问模式为 "ro"。在尚未抓取缓冲区的情况下，这是错误的，应为 "na"。该问题已得到修复。
  • The HDevelop example usb3vision_parameters.hdev has been improved.
• 修订 6.2（2015 年 2 月 26 日）：
  • 将基础 GenApi 版本更新至最新正式版本 v2.4.1，包括性能改进和若干小错误修复。请注意，HALCON 安装程序中的 genicam 目录也将随之更新。
  • 将集成生产者 Usan 更新至 1.0.3 版。
  • 修正了 Windows 下驱动程序安装程序的问题： Win32 缺少文件，Win64 需要调试运行时，驱动程序安装程序未签名。
  • 解决了 libusbx 在 Windows 下的局限性，提高了多相机的使用率。
  • 解决了在相机提供应用程序可使用的更高帧频情况下的性能问题。
  • 为高级流引擎控制和高级事件引擎控制添加了新参数和文档。
  • 添加了 GenICam 故障排除提示。
  • 已添加对缓冲区处理模式 "OldestFirstOverwrite" 和 "NewestOnly" 的支持。
  • 已添加通用参数 "device_event_handling=0"，以便在打开设备时明确忽略事件通道。
  • 使有关意外参数类型的警告更易于理解。
  • 改进了与使用 libusbK 的其他采集接口的兼容性。
• 修订 6.1（2014 年 10 月 31 日）：
  • HALCON 12 版本的接口。
  • 支持更多主机控制器在 Windows 上安装驱动程序。
  • 修正了 Windows 系统初始化过程中可能出现的死锁问题。
  • 修正了参数 "camera_type" 的文档。配置文件的 .xml 扩展选项丢失。
  • 改进了 set_framegrabber_param 在尝试设置参数而未指定值时返回的错误信息。
  • 添加了以下参数的缺失说明："buffer_reallocation_mode"、"do_load_settings" 和 "do_write_settings"。
• 修订 5.2（2014 年 3 月 20 日）：
  • 修正了以任意顺序使用多个图像采集接口（这些接口使用的 GenApi 版本不同）时出现的问题。
  • 修复了在使用基于 GenApi 的多个图像采集接口（这些接口使用相同的 GenApi 版本）时发生崩溃的问题。在这种情况下，当关闭其中一个接口的最后一个实例时，其余接口无法再使用 GenApi。此修复的副作用是 GenApi 无法再被卸载。
  • 改进了参数 "clear_buffer" 的描述。
  • 为 Linux 添加了 libudev 系统要求。
• 修订 5.1（2014 年 1 月 31 日）：
  • 添加了对 Linux 和 Mac OS X 的支持。
  • 修正了错误的设备速度检测，该检测在 Windows 8.1 上可能会失败。
  • 修正了在尝试执行不带参数的 GenICam 命令时崩溃的问题。
  • 新增参数 "register_<addr>_<len>"，用于直接存取寄存器。
  • 已添加对 PFNC 像素格式命名空间的支持。请注意，没有实施新的转换例程。
  • 更改示例程序，使其更方便用户使用。
• 修订 5.0（2013 年 10 月 28 日）：
  • 首次正式发布。