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

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

(该 GigEVision2 接口取代了旧版的、已废弃的 HALCON 采集 GigEVision 接口。从以前的 GigEVision 采集接口转换到新版本 GigEVision2 的用户请注意强调 两个接口版本之间差异 的一节，以便轻松过渡）。

• 英特尔兼容电脑，安装 Windows 7（32 位或 64 位）或更新版本，以及 WoW64（在 64 位 Windows 上使用 32 位 HALCON）、内核为 2.6（或更高）的 Linux 或 macOS。
• 千兆以太网网络适配器。建议使用支持巨帧的 PCIe 网络适配器。请相应配置网络适配器，例如将 MTU 值设置为 9000，以减少中断次数。此外，相机应直接连接到网络适配器，以避免干扰其他网络流量。请注意，交换机等网络设备不一定支持巨帧。
• 如果您使用防火墙，请确保您的防火墙配置允许您的应用程序或 HDevelop 连接到相机并接收传入的图像，否则抓取将失败。支持穿越防火墙的相机可能会正常工作。
• 在 Windows x86、WoW64 或 Windows x64 下运行 MVTec GigE Vision 流过滤器：HALCON GigEVision2 接口会自动使用过滤器驱动程序来提高流式传输图像时的性能。安装 HALCON 时，如果您在安装过程中启用了相应的复选框，过滤器驱动程序将自动安装。
  请确保至少已安装驱动程序版本 v2.1.8.0（检查网络属性）。较旧的驱动程序版本将无法使用！要实现全部功能，需要驱动程序版本 v2.2.8.4。
• GenICam GenApi。相应文件是 HALCON GigEVision2 软件包的一部分，位于 HALCON 基本目录 %HALCONROOT% 下的 genicam 目录中。有关详情，参见 GenICam GenApi 一节。
• Windows： HALCON 图像采集接口分别是 hAcqGigEVision2.dll 或 hAcqGigEVision2xl.dll。如果正确安装了接口，所有这些 DLLs 都应位于安装 HALCON 时所选择的 HALCON 基本目录 %HALCONROOT% 下的 bin\%HALCONARCH% 中。
  Linux： HALCON 图像采集接口分别是 hAcqGigEVision2.so 或 hAcqGigEVision2xl.so。如果正确安装了接口，共享对象应位于安装 HALCON 时所选择的 HALCON 基本目录 $HALCONROOT 中的 lib\$HALCONARCH 中。
  macOS： HALCON 图像采集接口分别是 hAcqGigEVision2.dylib 或 hAcqGigEVision2xl.dylib。如果正确安装了接口，共享对象应位于库子目录中的 HALCON 框架 /Library/Frameworks/HALCON.framework 或 HALCON XL 框架 /Library/Frameworks/HALCONxl.framework 中。
• 默认采集模式假定计算机的速度足以处理来自相机的所有缓冲区。如果不是这种情况，它们就会被默默丢弃。

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

• 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 一节。

用于数字输入/输出和图像采集的 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 下的版本子目录

• GigE Vision 协议的用户空间实施。
  对于 Windows，MVTec GigE Vision 流过滤器 可用，安装后可提高性能。
• 支持 GigE Vision 1.0 至 2.2。
• 支持 GenDC 流。
• 从多个相机抓取。
• 同步和异步抓取。
• 获取三维数据并创建三维对象模型。
• 支持巨帧和自动优化数据包大小。
• 使用 GenApi 对所有通用相机参数进行软件控制。
• 传输层相关参数的软件控制
• 支持各种像素格式和灵活的色彩转换。
• 除安装过滤器驱动程序（和内部线程优先级控制）外，无需管理员或根权限。
• 支持强制 IP。
• 支持 "连续"、"单帧 "和 "多帧 "采集模式。
• 支持 GenICam 动作控制。
• 支持 GenICam 块数据。
• 支持 GenICam 事件数据。
• 支持 GenICam 功能持久性。
• 支持 GenICam 文件访问。
• 支持 GenICam 固件更新。
• 支持功能更改通知回调。
• 支持不可串流设备（可通过 GenICam 控制，但不串流任何图像（或其他）数据的设备）。
• 支持待确认功能，无需手动调整超时，即可等待设备对长时间指令的响应。

• MVTec GigE Vision 流过滤器仅在 Windows 下可用。有关详情，参见 MVTec GigE Vision 流过滤器 段落。
• 仅支持流通道 0。
• 不支持从只读访问模式的设备上获取数据。

• 该接口实现了 GigE Vision 规范 2.2 版，涵盖其定义的所有三个基本协议：控制、图像/数据流和异步设备事件。
• 该接口支持 3D 设备等使用的 GenDC 流。
• 该接口还与执行 GigE Vision 1.0、1.1 或 1.2 标准的旧款相机完全兼容。

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

为确保完全访问设备，必须满足以下前提条件：

一般情况：

• 如果系统中激活了防火墙，则必须对其进行配置，以便所有预期使用 GigE Vision 设备的应用程序（如 HDevelop，以及任何用户开发的应用程序）都能完全访问所连接的设备。无论如何，支持穿越防火墙的相机都可以工作。
• 如果可能，确保所使用的设备已正确配置，以匹配其所连接的网络接口的 IP 配置（通过设备的持久 IP 配置或 DHCP）。
• 如果设备的 IP 配置与设备所连接网络接口的 IP 配置不匹配，HALCON GigEVision2 采集接口将发现设备，但会将其标记为不可访问，并且无法打开。
• 如果您使用 HDevelop 图像采集助手，它会自动提示您添加正确的通用参数，以强制为设备设置合适的临时 IP 地址。请记住，该临时 IP 地址在设备电源循环后不会继续存在。最好还是对设备进行正确配置（持久 IP 或 DHCP），以便下次开机时以合适的 IP 配置启动。

Linux：

• 在 Linux 系统中，如果开启了 "反向路径过滤"，则可能无法发现配置错误（子网错误）的设备。反向路径过滤是一种安全选项，如果反向路径流量（到输入数据包源头的流量）不会在接口上路由，该接口就会丢弃输入数据包。在实践中，这意味着设备宣布自己的发现数据包将被丢弃。为了避免这种情况，我们建议在任何要发现 GigE Vision 设备的接口上关闭反向路径过滤选项（除非你确定设备永远不会被错误配置）。要暂时禁用 eth0 上的反向路径过滤，请执行
  sudo sysctl -w net.ipv4.conf.all.rp_filter=0
  sudo sysctl -w net.ipv4.conf.eth0.rp_filter=0
  要使更改永久有效，请在 sysctl 配置文件（如 /etc/sysctl.conf 或 /etc/sysctl.d 树）中调整这些选项：
  net.ipv4.conf.all.rp_filter=0
  net.ipv4.conf.eth0.rp_filter=0

• 对于 Windows x86 和 x64，可使用所谓的 "过滤器（筛选器）驱动程序"。如果已安装并激活，则会自动使用。该内核模式驱动程序可提高性能，应尽可能使用。
• 安装：
  安装 HALCON 时，如果您在安装过程中启用了相应的复选框，过滤器驱动程序将自动安装。
  过滤器驱动程序也可单独安装。必要的安装程序可在 %HALCONROOT%\misc 中找到。 如果您从 MVTec 网站单独下载了 GigEVision2 软件包，则可在软件包内的 misc 子文件夹中找到过滤器驱动程序安装程序。安装时，请关闭所有网络连接，并以管理员身份执行安装程序。它将在所有以太网接口上安装并启用过滤器。此外，驱动程序文件将放置在 %HALCONROOT%\...\GevStreamingFilter 中。
  要禁用特定接口的过滤器，可以在网络接口属性中取消选择 "MVTec GigE Vision 流过滤器"。过滤器驱动程序可以通过 %HALCONROOT%\...\GevStreamingFilter 中的卸载程序完全卸载。为此，请关闭所有网络连接，并以管理员身份执行卸载程序。
  请在安装驱动程序后重新启动，以确保可以使用。
• 更新安装：
  当更新 GigEVision2 接口并包含新版本的过滤器驱动程序时，也应更新驱动程序。检查软件包 misc 子文件夹中 "GevStreamingFilter "安装程序的版本号，并将其与网络接口属性中的版本号进行比较。如有必要，请先卸载旧版本，然后再安装新版本（参见上述说明）。请重新启动以确保使用新版本。
• 版本控制：
  过滤器驱动程序版本号有 4 位数字。前两位数表示支持的最高 GigE Vision 标准。第三位数字表示主要版本，GigEVision2 接口使用它来决定是否提供二进制兼容性（即是否可以使用过滤器驱动程序）。第四位数字为次要版本，表示对驱动程序进行了内部修改。
  例如：
  2.2.x.x = 驱动程序完全支持具有 GigE Vision 标准 2.2 功能的相机。旧版本的标准始终包含在内。
  x.x.8.1 = 主版本 8，次版本 1。如果 GigEVision2 接口期望使用主版本 8，则将使用该驱动程序。这反映在参数 [System]GevTLSubsystemInfo 中，例如显示 filter driver: 2020803/2010802 。这意味着 GigEVision2 接口的本地版本是 2.2.8.3，而系统上安装的驱动程序版本是 2.1.8.2，兼容性是因为 x.x.8.x == x.x.8.x。我们强烈建议始终更新过滤器驱动程序，使次要版本也能匹配。
• 请注意，过滤器驱动程序已通过 Microsoft Authenticode 正式签名，但未通过 WHQL 认证，即安装时可能会警告驱动程序未通过 Windows 徽标认证。可以放心地忽略此警告。
• 通用参数 "force_sockdrv" 可用于禁用特定设备的过滤器驱动程序。
• 可以查询参数 "[Stream]GevStreamActiveEngine" ，以检查特定设备是否使用了过滤器驱动程序。
• 虽然有足够的可用用户内存，但过滤器驱动程序可能会耗尽内核内存。在这种情况下，请减少通用参数 "num_buffers"。
• 如果不能使用过滤器驱动程序，底层 GVSP 流将由套接字驱动程序在用户空间执行，这将增加 CPU 负载。
• 使用 MVTec GigE Vision 流过滤器时，某些参数与文件中的插座驱动程序不同。

• 使用多台相机的推荐方法是将每台相机连接到各自的接口上。
• 如果相机共用一个接口，则需要计算由此产生的链路负载。如果将一幅图像的大小与帧率相乘，就可以大致计算出来。例如，VGA 灰度图像每像素深度为 8 位，帧率为 100 帧/秒：
  640*480*1 B*100/s = 3072000 B/s 或约 30 MB/s
  由于 GigE 链路的传输速率约为 120 MB/s，理论上一条链路可连接 4 台相机，但实际上可能仅限于 3 台相机。数量较少的原因是 GVSP 协议的开销以及可能需要的重发，而上述计算并没有考虑到这一点。此外，根据相机和网络接口的行为，帧的单个数据包（也称为数据块）是作为一个突发数据包发送，还是在一个帧时间内平均分配。
  此外，还需要考虑必要的网络设备（如交换机）的行为，这可能会导致使用小数据包，甚至丢失数据包。
  在这种情况下，可能需要调整网络相关参数，如设备的包间延迟，以提高性能。如有疑问，也请遵循相应设备制造商的性能相关建议。

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

请注意，当前版本的接口只支持单流设备，并且总是打开第一个可用的流。如果将来增加了对多图像流设备的支持，打开设备的格式可能会扩展为流条目。

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

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

在大多数情况下，GenICam 描述文件由设备和 GigE 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 的各个 GigE Vision 生产者模块（系统、接口、设备和数据流）的参数按照惯例使用相同的样式，但前缀为方括号中的模块名称。请注意，系统和接口模块可能会被多个已打开的设备共享，因此更改它们的配置也可能会对其他连接产生副作用。使用以下前缀：
  • "[System]"，例如，[System]TLVendorName。
  • "[Interface]"，例如，[Interface]InterfaceType。
  • "[Device]"，例如，[Device]DeviceID。
  • "[Stream]"，例如，[Stream]StreamBufferHandlingMode。

属于 GigE Vision 生产者的系统模块和接口模块的参数（即前缀为 "[System]" 和 "[Interface]" 的参数，参见 参数 - 命名规则 ）必须以特殊方式处理。
要了解它们的行为，必须明白它们并不描述或配置设备本身，因此并不完全属于已打开的设备实例。
接口模块参数属于发现给定设备的接口，并由该接口下打开的所有设备共享（另见 识别和打开设备 ）。系统模块参数属于整个 GigE Vision 生产者，由该 GigE 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 示例 gigevision2_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"）查询缓冲区属性。这也适用于最终存在于缓冲区中的 块数据 ，并且也可在易失性模式下使用。
当应用程序调用新的抓取相关算子时，接口会将缓冲区返回给采集引擎，与缓冲区相关的查询不再有效。

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

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

对于现代通用图像采集接口，应用程序无法根据当前设置对来自设备的图像格式做出有效假设。例如，有些设备允许在采集过程中更改图像格式属性。
HALCON GigEVision2 图像采集接口完全支持这些用例。它会检查每个缓冲区的图像格式和其他重要属性，并生成与所采集图像格式和最终用户配置的输出格式参数（如 "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 GigEVision2 图像采集接口内置一个转换器，可将 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 算子一起使用。
只有在 "最后获取的缓冲区" 有效的情况下，与块数据相关的功能才会提供有意义的值， 即从最后一幅图像的传送到下一次调用任何抓取相关算子（请参阅 "采集 - 缓冲区处理 " 一节）。

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

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

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

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

该接口支持通过消息队列发送功能更改通知。使用 set_framegrabber_param(..., 'event_selector', ...) 选择所需的目标特征。它是与 set_framegrabber_param 相同的普通功能名称（GenICam 功能或内部参数），包括一个可能的前缀，如 "[Device]"（请参阅 参数 - 命名规则 ）。
使用 create_message_queue 创建一个接收通知的消息队列，并使用 set_framegrabber_param(..., 'event_message_queue', QueueHandle) 将其分配给所选功能。
消息队列可为任何基于 GenICam 的功能注册，即设备和 GigE 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" 中报告）也将被视为重复信息，不会再次报告。

流引擎试图在所有标准使用情况下都能很好地工作。不过，为了达到最佳性能（无论从每个应用的角度来看这意味着什么），最好对某些参数进行微调，以满足特定设备类型和应用的需求。GigE Vision 流协议的一个重要方面是管理丢失数据包的重发请求（由于各种原因，特别是 CPU 负载过高，数据包可能会在设备和应用程序之间丢失）。重发请求的控制可能需要从应用角度（更倾向于低延迟、高吞吐量或高可靠性）和设备角度（固定的可预测数据包/块时序与不规则流的预期，如线扫描相机）来考虑。根据设备和系统的已知特性，重发请求最好既不要发出得太晚（设备可能不再存储这些数据包的副本），也不要发出得太早（可能导致重复发送数据包）。
因此，可以通过各种流参数对引擎进行配置，包括 "[Stream]GevStreamMaxPacketGaps"、"[Stream]GevStreamMaxBlockDuration" 或 "[Stream]GevStreamDeliverIncompleteBlocks" 。更改参数时，该参数将在最近的适当时间点（通常是在将缓冲区重新排序回引擎时）传递给数据包处理引擎，并应用于后续的缓冲区获取。
某些参数，特别是 "[Stream]GevStreamRingBufferSize" 或 "[Stream]GevStreamReceiveSocketSize" ，在调整超高速设备（不使用过滤器驱动程序时）的接口性能时会产生重大影响。它们的使用可能与系统密切相关，应根据实际目标系统的测试经验，与实际网卡驱动程序的配置一起进行调整。
另一方面，该引擎提供的各种统计数据可能有助于观察其性能和行为，并有助于微调输入参数。这些统计数据包括 "[Stream]GevStreamLostPacketCount"、"[Stream]GevStreamResendCommandCount" 或 "[Stream]GevStreamIncompleteBlockCount" 等。统计信息会定期更新，并在每次采集启动时重置。
有关流参数的完整列表和详细信息，请参阅流参数文档。
如果不使用流过滤驱动程序，处理传入数据的能力会严重影响流引擎的性能。流引擎线程相对于系统中其他线程的优先级对此影响很大。详情请参考参数 "[Stream]StreamThreadPriority"、"[Stream]StreamThreadSchedulingPolicy" 和 "[Stream]StreamThreadApplyPriority" 的文档。设备打开时，一般会选择合适的默认优先级。
最后，可以在打开设备时使用 "streaming_mode=0" 通用参数完全禁用流基础设施。

事件引擎在标准用例中运行良好。但是，在特定的使用情况下，必须对其行为进行微调。本节中描述的参数仅用于高级用途，应谨慎对待——错误的配置会严重影响性能。
事件引擎线程优先级由参数 "[Device]DeviceEventsThreadPriority"、"[Device]DeviceEventsThreadSchedulingPolicy" 和 "[Device]DeviceEventsThreadApplyPriority" 控制。设备打开时，一般会选择合适的默认优先级。
在打开设备时，可使用 "device_event_handling=0" 通用参数完全禁用事件处理基础结构。

在调试使用 GigE Vision 设备的应用程序时，必须知道 GigE Vision 协议的核心概念是使用常规 "心跳" 数据包保持与设备的连接。当应用程序停止保持心跳时，设备就会断开连接。HALCON GigEVision2 可以完全透明地处理心跳控制，但有一种特殊情况它不能这样做，即应用程序正在调试并遇到断点时。在这种情况下，所有线程通常都会停止，包括负责心跳维护的线程。
为防止调试时失去与设备的连接，可以大幅延长心跳超时时间或完全禁用设备上的心跳控制。详情请参阅参数 "[Device]DeviceLinkHeartbeatTimeout" 和 "[Device]DeviceLinkHeartbeatMode" 的描述。

在使用 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 采集接口、设备本身或 Gige Vision 生产者提供）将不可用。取而代之的是与给定设备和接口技术相对应的配置参数，尤其是与固件更新相关的参数。
要更新设备，首先要在 "fwupdate_file_path" 中选择 GUF 文件，然后使用 "fwupdate_update_selector" 从文件中选择一个（可能是多个）更新，最后通过 "do_fwupdate_apply" 进行应用。这些参数的文档提供了更多详细信息。
请注意，更新程序可能包括一次或多次设备重置，重置后设备必须被采集接口重新发现。重置和重新发现所需的时间由设备供应商在 GUF 文件中指定。然而，在某些情况下（取决于设备本身、其连接技术和系统设置），重新发现超时时间不够，设备无法被安全地重新发现。在这种情况下，可以指定一个额外的超时时间，将其添加到 GUF 文件中指定的超时时间中，以便成功完成进程。该参数 "fwupdate_wait_after_reset" 指定了以毫秒为单位的额外超时。
另见 HDevelop 示例 gigevision2_fwupdate.hdev.

相机和 GigE Vision 生产者的参数通过 GenICam 访问，并在相应相机或 GigE Vision 生产者的 GenICam 描述文件中定义，因此每个产品的参数集都不同（不过参数命名应符合 SFNC 和 GenTL SFNC GenICam 标准）。调用 get_framegrabber_param(..., 'available_param_names', ...) 会返回一个元组，其中包含所连接相机和 GigE Vision 生产者的所有可用参数。另见有关 参数命名规则 一节。
例如，要设置 AcqHandle 所指相机的当前增益（调用 open_framegrabber 之后），用户可以调用 set_framegrabber_param(AcqHandle, 'Gain', 6.0)。
请注意，只有当参数值有效时，接口才会设置该值。不符合给定功能允许范围的整数和浮点数值会与最接近的有效值对齐。其他功能类型的无效值将被拒绝。
除了相机和 GigE 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 的功能，即设备和 GigE 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 被重复调用，则会在 GigE Vision 生产者和设备上重新开始采集。这意味着缓冲区队列和所有与流相关的统计参数（如 "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" 参数，因为所有 GigE 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。

该接口有以下示例：

• gigevision2.hdev - 基准测试。
• gigevision2_2cameras.hdev - 从两个相机抓取图像。
• gigevision2_acquisition_events.hdev - 示例如何使用消息队列处理带有附加事件数据的事件。
• gigevision2_action_control.hdev - 使用动作控制功能。
• gigevision2_automation_technology_c4_objectmodel3d.hdev - Automation Technology C4 传感器三维数据的采集和可视化。
• gigevision2_chunkdata.hdev - 使用 GigE Vision 块数据。
• gigevision2_crop.hdev - 通过软件和硬件图像裁剪抓取图像的示例。
• gigevision2_devicelost_event.hdev - 使用消息队列处理 DeviceLost 事件的示例。
• gigevision2_doo_abort_grab.hdev - 终止正在进行的图像采集。
• gigevision2_easyparams.hdev - 处理 MVTec EasyParams。
• gigevision2_fileaccess.hdev - 从 GenICam 设备上传和下载文件的示例。
• gigevision2_flir_ax5.hdev - 从 FLIR AX5 红外热像仪采集数据，使用铁查找表和温度报警检测进行可视化。
• gigevision2_forceip.hdev - 使用 ForceIP 正确配置配置错误的 GigE Vision 设备。
• gigevision2_frame_rate.hdev - 测量采集设备有效帧率的示例。
• gigevision2_fwupdate.hdev - 如何通过 GenICam 固件更新应用固件更新的示例。
• gigevision2_information.hdev - 用于收集系统和相机配置信息的程序。请求支持时请附上生成的文件。
• gigevision2_interpacket_delay.hdev - 调整包间延迟，以便使用通过单个交换机连接到一个网络接口的两台相机。
• gigevision2_io_control.hdev - 控制设备 GPIOs 的示例。
• gigevision2_ip_address_handling.hdev - 读取 IPv4 地址并静态分配 IPv4 地址。
• gigevision2_link_aggregation.hdev - 结合静态链路聚合 (LAG) 显示使用情况。
• gigevision2_multiframe.hdev - 显示多帧模式的使用情况。
• gigevision2_parameters.hdev - 列出设备的所有参数。
• gigevision2_parameter_persistence.hdev - 演示将参数值写入文件以及从文件中恢复参数值。
• gigevision2_photonfocus3d_objectmodel3d.hdev - Photonfocus 三维传感器三维数据的采集与可视化。
• gigevision2_roboception_rcvisard_objectmodel3d.hdev - Roboception rc_visard 传感器三维数据的采集与可视化。
• gigevision2_scheduled_action_command_ptp_ieee1588.hdev - 利用 GigE Vision 功能 "计划动作命令" 同步触发多台相机。
• gigevision2_sick_ranger3_objectmodel3d.hdev - Sick Ranger3 传感器三维数据的采集和可视化。
• gigevision2_simple.hdev - 一个展示接口用法的简单示例。
• gigevision2_software_trigger.hdev - 软件触发器的使用。
• gigevision2_wenglor_shapedrive_objectmodel3d.hdev - wenglor ShapeDrive 传感器三维数据的采集和可视化。
• gigevision2_wenglor_wecat3d_objectmodel3d.hdev - wenglor weCat3D 传感器三维数据的采集和可视化。

本章旨在帮助用户从旧版本（GigEVision）转换到新版的采集接口（GigEVision2）。直接基于 GigEVision2 接口启动新应用程序的用户可以完全忽略本章内容。

GigEVision2 接口是对以前接口的重大改写，其目标是支持 GigE Vision 2 规范，与 GenICam 标准系列的现代版本完全兼容，并在所有基于 GenICam 的 HALCON 采集接口（特别是 GigEVision2、USB3Vision 和 GenICamTL）中实现相似的用户体验。因此，不可能与该接口的前一版本保持完全向后兼容。

GigEVision2 引入的最重要的新功能：

• 支持 2.x 版 GigE Vision 规范。
• 与当前版本的 GenICam 标准紧密兼容。
• 完全支持 GigE Vision 块数据和事件数据。
• 支持多部分数据，特别是本地支持三维设备（使用三维设备）。
• 引入了 grab_data 和 grab_data_async 算子（采集 – 抓取算子）的支持。

目前存在的限制，将在今后的接口更新中加以解决：

• 流过滤器可同时与两个版本的采集接口一起使用。其当前版本尚未实现 GigEVision2 接口的所有流引擎参数（流控制和统计）。所有这些差异将在 获取图像采集卡参数 和 设置图像采集卡参数 的小节中明确指出。

与打开设备有关的更改（open_framegrabber 和 info_framegrabber）：

• 采集接口本身的名称已经更改（GigEVision2 取代了 GigEVision），而这两个版本目前同时存在。
• 标识设备的字符串格式和标识设备的选项集已发生变化，参见 标识和打开设备 中有关当前格式的详细信息。同样的更改也反映在 info_framegrabber 算子中的 device 和 info_boards 查询中。
• 以下参数在 open_framegrabber 算子中被忽略： ImageWidth、ImageHeight、StartRow、StartColumn、Field、ExternalTrigger、Port、LineIn。相应功能应通过设置每个相应设备的 GenICam 功能来配置。
• 检测配置错误的设备（IP 子网与设备连接的网络接口不匹配）的功能，以及在打开设备时强制向设备提供新的临时 IP 地址的选项仍然存在，但请求新 IP 地址的字符串格式已发生变化，以便与新的底层设备发现架构相匹配。请参考 open_framegraber 中的 force_ip 通用参数（取代使用不同内部格式的旧版 GtlForceIP 通用参数）。
• open_framegrabber 中的下列通用参数有了新名称：
  • force_sockdrv 代替 GtlForceSocketDriver
  • num_buffers 代替 GtlNumBuffers
    请注意，接口内部锁定 1 个缓冲区（参见 采集缓冲区处理 ），因此如果您的应用程序需要 n 个缓冲区，"num_buffers" 必须设置为 n+1。
• 不支持通用参数 GtlGVCPRetries 和 GtlGVCPTimeout，它们的功能可通过 set_framegrabber_param 参数 [Device]LinkCommandRetryCount 和 [Device]LinkCommandTimeout 新增访问。
• 目前完全不支持通用参数 GtlUseCameraPacketSize 和 GtlDisableAutomaticTestPackets。

在 GigEVision2 接口版本中，配置采集接口和所连接设备的各种参数发生了变化或被移除。这反映了内部架构的重大变化，现在所有基于 GenICam 的 HALCON 采集接口都采用了 GenICam GenTL 架构模型。参见 获取帧捕获器参数 和 设置帧捕获器参数 中的详细信息。

• 以 Gtl 前缀开头的参数已不复存在（请参阅下文了解哪些参数被名称不同的类似参数取代）。
• 以 Gev 前缀开头的参数已不复存在（根据实际连接的设备，如果设备本身提供这些参数，其中一些参数可能仍然可用）。
• 不再支持以下附加参数
  • do_flush_buffers
  • do_flush_callback_queue, max_num_queued_callbacks, num_queued_callbacks, callback_timeout
  • do_write_xml_file
  • DeviceID, DeviceModelName, DeviceVendorName (与带 Gev 前缀的参数类似，如果设备本身支持这些参数，则这些参数可能可用）。
  • parameters_hidden
  • GenApiCNodeMapRefPtr

• 上面列出的一些缺失参数被新名称（括号内为参数的旧名称）的相同或相似目的参数所取代：
  • [Device]DeviceID (DeviceID)
  • [Device]DeviceVendorName (DeviceVendorName)
  • [Device]DeviceModelName (DeviceModelName)
  • [Device]DeviceSerialNumber (GtlSerialNumber)
  • [Device]GevDeviceIPAddress (GtlCurrentIPAddress)
  • [Device]GevDeviceMACAddress (GtlDeviceMACAddress)
  • [Device]LinkCommandRetryCount/[Device]LinkCommandTimeout (GtlGVCPRetries/GtlGVCPTimeout)
  • [Stream]StreamBufferHandlingMode (GtlBufferHandlingMode) -请参阅新参数的文档，支持的值列表有所不同
  • [Stream]GevStreamDeliverIncompleteBlocks (GtlGVSPDiscardIncompleteBuffers) - 小心标志的反向逻辑
  • [Stream]GevStreamMaxBlockDuration (GtlBlockTimeout) - 新功能支持指定 "无限" 持续时间，详情请参考功能文档
  • [Stream]GevStreamActiveEngine (GtlAcquisitionEngine) - 小心不同的输出字符串
  • [Stream]GevStreamIncompleteBlockCount (GtlIncompleteBuffers)
  • [Stream]GevStreamPacketOrderDelay (GtlGVSPResendWait)
  • [Interface]InterfaceID (GtlInterfaceID) - 小心不同的输出字符串
  • GevSCPD (GtlGVSPInterpacketDelay) - 请注意，这是一项设备功能，并非强制性的
  • buffer_is_incomplete (GtlBufferIncomplete)
  • buffer_timestamp (GtlBufferTimestamp)
  • buffer_frameid (GtlBlockID)
  • do_write_configuration (do_write_xml_file) - 新参数不仅取代了旧参数，还扩展了更广泛的功能
  • 我们建议您参阅 获取图像采集卡参数 和 设置图像采集卡参数 中所有当前可用参数的文档。

目前不支持以下回调（set_framegrabber_callback）：

• callback_queue_overflow

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

一般情况：

• 检查是否使用了 最新版本 的 HALCON GigEVision2 接口。
• 检查 系统要求。
• 检查设备是否有最新固件。
• 启用 HALCON 中的低级错误信息，以查询有关问题的更多信息（如果适用，请检查 HDevelop 中的输出控制台）。
• 如果系统中激活了防火墙，则必须对其进行配置，以便所有预期使用 GigE Vision 设备的应用程序（如 HDevelop，以及任何用户开发的应用程序）都能完全访问所连接的设备。
• 如果发现随机采集超时，可能是网络设置中的数据包丢失率过高。请确认所有网络组件都能跟上相机发送的数据速率。使用 "[Stream]GevStreamResendPacketCount" 检查数据包丢失的频率。然后尝试为您的设置设置重发机制的参数，例如增加"[Stream]GevStreamMaxPacketGaps" 或使用 "[Stream]GevStreamMaxBlockDuration" 。

过滤器驱动器（MVTec GigE Vision 流过滤器）：

• 如果过滤器驱动程序激活时出现流问题，通常无法捕获网络数据包跟踪来分析问题。从第 2.1.8.0 版开始，过滤器驱动程序可以设置环境变量 ESEN_FILTER_PASSTHROUGH=1，让其他过滤器（如 Wireshark 的 pcap）访问数据包。

GenICam：

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

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

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

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

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

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

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

• 修订 20.11.16（2023 年 4 月 6 日）：
  • 如果数值参数除了纯数值外还有其他特殊表示形式，现在可以使用后缀 "_representation" 来查询表示形式的类型。
  • 现在可以使用后缀 "_string" 查询参数值的字符串表示形式。
  • 当接收有效载荷类型为 Chunk Data 的数据时，grab_data 和 grab_data_async 出现故障。该问题已得到修复。另见 块数据。
  • libCLAllSerial 共享对象已从 GenApi 3.4.0 的再分发中移除。
  • 重写了 gigevision2_doo_abort_grab.hdev 示例。
  • 重写了 gigevision2_software_trigger.hdev 示例。
  • 新增了 HDevelop 示例 gigevision2_scheduled_action_command_ptp_ieee1588.hdev，用于演示使用 GigE Vision 功能 "预定动作命令" 同步触发多台相机。
  • third_party_genicamtl.txt 现在包含指向相应软件位置的链接。参见 第三方库的使用 。
• 修订 18.11.15（2022 年 10 月 7 日）：
  • 当 MVTec GigE Vision 流过滤器 安装程序的文件位置包含非 ASCII 字符时，安装程序会失败。该问题已得到修复。
  • MVTec EasyParams 以简单易用的方式处理最常见的 GenICam 功能。
  • 新增参数 "available_easyparam_names"，用于返回 MVTec EasyParams 列表。
  • 新增了 HDevelop 示例 gigevision2_easyparams.hdev，以演示如何处理 MVTec EasyParams。
  • 在 Unix 系统上，加载包含 Windows 行结束符的 GenICam 持久文件失败。这一问题已得到解决。
• 修订 18.11.14（2022 年 5 月 11 日）：
  • 在某些情况下，info_framegrabber 的 "info_boards" 查询无法检测到配置错误设备的可用 IP 地址。这一问题已得到修复。
  • 在 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 描述文件的功能被破坏。该问题已得到修复。
  • 在使用线扫描设备生成视差数据时，B (Y) 坐标的计算不正确。该问题已得到修复。
  • 当启用 "add_objectmodel3d_overlay_attrib" 但 ObjectModel3D 不包含点时，grab_data 和 grab_data_async 失败。该问题已得到修复。
  • HDevelop 脚本 gigevision2_information.hdev 现在可将输出数据保存到用户的文档文件夹中，以避免出现写入权限缺失的问题。此外，脚本现在还能处理设备唯一名称中的非字母数字字符。此外，还修复了一个与恢复原始触发器设置有关的问题。
• 修订 18.11.13（2021 年 10 月 20 日）：
  • 现在可以解码 GigE Vision 和 GenICam GenDC 标准规定的 JPEG 有效载荷。
  • 现在支持 GigE Vision 标准和 GenICam 像素格式命名规则规定的打包拜尔格式。
  • 现在支持 "Coord3D_AC32f"、"Coord3D_AC16" 和 "Coord3D_AC8" 像素格式。
  • 消费者模块的读写参数是可流参数，即可以通过 "do_write_settings" 或 "do_write_configuration" 进行持久化。然而，对于这些后缀为"_streamable" 的参数，get_framegrabber_param 返回值为 0。该问题已得到修复。
  • 在执行 open_framegrabber 时，HALCON 在极少数情况下会因连接丢失而崩溃。该问题已得到修复。
  • 在设备发现后不久调用强制 IP 的 open_framegrabber 时，即使强制 IP 命令实际上已成功执行，也可能会失败。这一问题已得到修复。
  • HDevelop 示例 gigevision2_information.hdev 现在包含接收端配置的 MTU 信息。
  • 对 HDevelop 示例 gigevision2_roboception_rcvisard_objectmodel3d.hdev 进行了扩展，以支持 Roboception 的 GenTL 生产者。此外，DepthDispRange 现在可以隐式计算，ObjectModel3D 的颜色叠加问题也得到了修复。
  • 现在，该接口的发布包中包含了为 HDevelop 示例浏览器提供元信息的文件。
• 修订 18.11.12（2021 年 2 月 15 日）：
  • 修改了 Socket 驱动程序的性能，包括两个新参数"[Stream]GevStreamRingBufferSize" 和 "[Stream]GevStreamReceiveSocketSize"，另见 高级流引擎控制。
  • 已添加参数 [Stream]EventTransferEndUndeliverabilityReason，以便与 [Stream]EventTransferEnd 结合使用。
  • MVTec GigE Vision 流过滤器（滤波器驱动程序）已更新至 2.2.8.4 版，其中包含以下更改：
    • 使用流过滤器时，EventTransferEnd 只对成功接收的数据块触发，而对无法发送的数据块不触发。这一问题已得到修复。
    • 在极少数情况下，当应用程序在流传输过程中没有优雅地关闭时，流过滤器的自动卸载可能会导致操作系统崩溃。这一问题已得到修复。
  • 底层 GenApi 版本已更新至最新的官方版本 3.3。
  • 由编码器控制的线扫三维设备组装 ObjectModel3D 的过程已大大加快。为了实现这种加速，设备必须按照 GenICam 标准功能命名规则 2.7 及更高版本的描述，通过其 ValueArrayCandidates 宣布 ChunkEncoderValue 和 ChunkScanLineSelector。
  • 对于以 "token:value" 形式提供设备字符串的 open_framegrabber，必须包含分隔符"|"。这一限制已被取消。
  • 除非设置了环境变量 TEMP、TMP 或 TMPDIR，否则 GenICam 缓存机制将不起作用。现在，/tmp 或 HALCONROOT 被用作备用。
  • 对 HDevelop 示例 gigevision2_frame_rate.hdev 进行了优化。
  • HDevelop 示例 gigevision2_acquisition_events.hdev 在事件快速进入时会陷入死锁。该问题已得到修复。
  • 从以前的 GigEVision 接口实现转换 一节已扩展了更多旧参数及其新对应关系。
  • 重构了 HDevelop 示例 gigevision2_information.hdev，现在它调用新的过程库 genicamtl_information.hdpl。此外，新版本关闭了触发模式，以便测试图像采集，并在图像采集失败时记录更多细节。
  • 改进了错误处理。现在可以使用算子 get_extended_error_info 查询有关错误原因的附加信息。对于 HALCON 语言接口（C# 和 C++），HALCON 异常类提供了访问附加错误信息的方法。
• 修订 18.11.11（2020 年 10 月 27 日）：
  • 此接口无法从 Linux 和 macOS 上的 .NET Core 应用程序中加载。该问题已得到修复。
  • 添加了对 "YCbCr411_8_CbYYCrYY"、"YCbCr422_8" 和 "YCbCr422_8_CbYCrY" 像素格式的支持。
• 修订 13.0.10（2020 年 9 月 18 日）：
  • 大多数文件操作不支持 UTF-8 文件名。这个问题已经解决。不过，某些操作（如 固件更新）由 GenICam GenApi 管理，而 GenICam GenApi 可能不支持这些操作。
  • 在上一版本中，"do_write_configuration" 没有将生成 xml 文件的路径写入生成的 ini 文件。该问题已得到修复。
• 修订 13.0.9（2020 年 8 月 7 日）：
  • "do_write_configuration" 已被扩展用于为 GenTL 消费者生成持久文件（持久保存 HALCON GigEVision2 图像采集接口本身的内部参数，如 "grab_timeout" ），请参阅 参数– 持续设备状态。
  • 现在，在设备已打开的情况下，可以为单个 GenTL 生产者模块或 GenTL 消费者模块写入和加载持久性文件。迄今为止，只有远程设备可以做到这一点。可通过参数 "settings_selector"（设置选择器）选择要写入或加载的持久化文件。
  • 使用 open_framegrabber 加载持久化文件时，部分持久化参数值被覆盖。该问题已得到修复。
  • 新增了"[Interface]GevInterfaceGatewaySelector" 和 "[Interface]GevInterfaceGateway" 功能。请注意，它们目前尚未在 macOS 上实现。
  • 新增了 HDevelop 示例 gigevision2_parameter_persistence.hdev，以演示向文件写入参数值和从文件恢复参数值。
  • 参数 "available_event_names" 被错误地写成了 "available_event_types"。该问题已得到修复。
• 修订 13.0.8（2020 年 4 月 24 日）：
  • 现在支持 GigE Vision 规范 2.2 版。这包括三维设备等使用的 GenDC 流。
  • 在 18.05 之前的 HALCON 版本中，get_framegrabber_param(..., 'event_message_queue', ...) 失败。该问题已得到修复。
  • MVTec GigE Vision 流过滤器（过滤器驱动程序）已更新至 2.2.8.3 版，其中包含以下更改：
  • 在多个网卡上使用"[Stream]EventTransferEnd "时，过滤器驱动程序会偶尔停止传输事件。这一问题已得到修复。
  • get_framegrabber_param (..., 'num_buffers_underrun', ...) 在过滤器驱动程序中不可用。该问题已得到修复。
• 修订 13.0.7（2020 年 2 月 19 日）：
  • 从缓冲队列中获取缓冲区的时间随缓冲区索引的增加而线性增加。这在使用较大的 "num_buffers" 时最为明显。该问题已得到修复。
  • HDevelop 示例 gigevision2_action_control.hdev 不再依赖于可选的设备功能 GevCurrentIPAddress。
• 修订 13.0.6（2019 年 12 月 10 日）：
  • 将底层 GenApi 版本更新至最新正式版本 v3.2。更新包括用户和序列器集持久性的错误修复以及其他小错误修复。
  • 参数 "num_buffers" 的任意最大值限制为 1023。这一限制已被取消。
  • 强制 IP 请求的默认超时时间已增加，以便允许设备根据 RFC 5227 对请求的 IP 进行验证。此外，还添加了新参数"[Interface]GevDeviceForceIPTimeout" 和"[Interface]GevDeviceLastForceIPSuccess"，以便更好地控制操作。
  • 传递给 open_framegrabber 的通用参数 "direct_connection" 既未在 info_framegrabber (..., 'generic', ...) 中列出，也无法从 get_framegrabber_param 中获取。该问题已得到修复。
  • MVTec GigE Vision 流过滤器（过滤器驱动程序）在网卡超过 24 个的系统上不起作用。该问题已得到修复。
  • 对 HDevelop 示例 gigevision2_link_aggregation.hdev 进行了扩展，以便与套接字驱动程序配合使用。
  • HDevelop 示例 gigevision2_link_aggregation.hdev 不完整。该问题已得到修复。现在，"[Stream]GevStreamPacketOrderDelay" 会根据具体设置进行调整。
  • 对 HDevelop 示例 gigevision2_roboception_rcvisard_objectmodel3d.hdev 进行了调整，以丢弃不完整的缓冲区。
  • 添加了新的 HDevelop 示例 gigevision2_sick_ranger3_objectmodel3d.hdev，展示了如何使用 Sick Ranger3 传感器获取三维数据并将其可视化。
• 修订 13.0.5（2019 年 7 月 22 日）：
  • 现在可以使用 IP 地址快速直接连接，参见 识别和打开设备 。
  • 现在，您可以使用"_streamable" 后缀查询功能是否可以持久化。
  • 对 HDevelop 示例 gigevision2_parameters.hdev 进行了扩展，以检查参数是否可以持久化。
  • 对 HDevelop 示例 gigevision2_information.hdev 进行了扩展，以检查相机是否支持防火墙穿越。
  • "add_objectmodel3d_overlay_attrib" 机制根据 SFNC 2.5 进行了扩展，规定了如何映射与三维数据分辨率不同的覆盖数据。
  • 相应简化了 HDevelop 示例 gigevision2_roboception_rcvisard_objectmodel3d.hdev。
  • 此接口的分发包中已添加文件 third_party_gigevision2.txt。
• 修订 13.0.4 增补（2019 年 5 月 2 日）：
  • 新增 HDevelop 示例 gigevision2_io_control.hdev，演示如何控制设备的 GPIOs。
  • 在 HDevelop 示例 gigevision2_roboception_rcvisard_objectmodel3d.hdev 中，"DepthMaxDepth" 已降至 5 米，以减少不需要的背景数据。
• 修订 13.0.4（2019 年 3 月 5 日）：
  • 已添加对 "BiColorRGBG8" 和 "BiColorBGRG8" 像素格式的支持。
  • 从 grab_data 和 grab_data_async 中生成的三维对象模型现在可以使用二维映射。这大大加快了多个算子处理三维对象模型的速度。
  • 从三维图像生成 HALCON ObjectModel3D 的机制已扩展到差分图像。此类图像需要包含 SFNC 2.4 中指定的以下块："ChunkScan3dFocalLength"、"ChunkScan3dBaseline"、"ChunkScan3dPrincipalPointU"、"ChunkScan3dPrincipalPointV"。
  • 在 Linux 系统上，"do_abort_grab" 可能会耗时过长。该问题已得到修复。
  • 此外，还引入了参数"[Stream]GevStreamAbortCheckPeriod"，用于配置 "do_abort_grab" 的检查周期。
  • MVTec GigE Vision 流过滤器（过滤器驱动程序）已更新至 2.1.8.2 版，其中包含以下更改：
  • 使用过滤器驱动程序时，"[Stream]EventTransferEnd" 及其相关事件数据现在也可用了。
  • 过滤器驱动程序中缺少使用 get_framegrabber_param 提供的下列统计信息，但现在已经实现： GevStreamDeliveredPacketCount"、"[Stream]GevStreamDuplicatePacketCount"、"[Stream]GevStreamLostPacketCount"、"[Stream]GevStreamOversizedBlockCount"、"[Stream]GevStreamResendCommandCount"、"[Stream]GevStreamSkippedBlockCount"。
  • 添加了新的 HDevelop 示例 gigevision2_roboception_rcvisard_objectmodel3d.hdev，展示了如何使用 Roboception rc_visard 传感器获取三维数据并将其可视化。
  • 添加了新的 HDevelop 示例 gigevision2_wenglor_shapedrive_objectmodel3d.hdev，展示了如何从 wenglor ShapeDrive 传感器获取三维数据并将其可视化。
• 修订 13.0.3（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 示例 gigevision2_fileaccess.hdev。
  • 现在支持 GenICam 的固件更新。参见 固件更新和新的 HDevelop 示例 gigevision2_fwupdate.hdev。
  • 现在支持在消息队列中接收 GenICam 事件，参见 事件消息队列。到目前为止，GenICam 事件只能通过回调来支持，因此无法在 HDevelop 中使用。此外，我们还添加了两个新的 HDevelop 示例来展示这一功能 gigevision2_acquisition_events.hdev 和 gigevision2_devicelost_event.hdev。
  • GigE Vision 生产者现在支持 GenICam 动作控制。有关详细信息，请参阅新的 HDevelop 示例 gigevision2_action_control.hdev。
  • GigE Vision 生产者现在支持待确认功能，无需手动调整超时即可等待设备对长时间指令的响应。
  • "do_write_configuration" 已被扩展，不仅能存储当前设备配置，还能为所有 GigE Vision 生产者模块（系统、接口、设备和数据流）生成持久文件，参见 参数– 持续设备状态 。
  • 添加了新参数 "buffer_timestamp_ns" 和 "device_timestamp_frequency"，以提高 "buffer_timestamp" 的可用性。
  • 传递给 open_framegrabber 的某些通用参数无法通过 get_framegrabber_param 获取。这一问题已得到修复。
  • 长度超过 1024 个字符的字符串参数会被 get_framegrabber_param 静默裁剪。该问题已得到修复。
  • 当 "start_async_after_grab_async" 设置为 "禁用" 时，远程设备上的采集会在每帧后停止。该问题已得到修复。
  • 当更改"[Interface]DeviceSelector "时，某些取决于"[Interface]DeviceSelector" 的参数（如"[Interface]DeviceTLVersionMajor"）不会更新。这一问题已得到修复。
  • 为保持一致，示例 gigevision2_atc4_objectmodel3d 已更名为 gigevision2_automation_technology_c4_objectmodel3d.hdev。
• 修订 13.0.2（2018 年 4 月 27 日）：
  • 添加了对 "Mono4p" 像素格式的支持。
  • 添加了对 "YCbCr411_8" 像素格式的支持。
  • 如果不支持的像素格式与支持的 Mono 格式足够相似，现在会尝试以实际图像尺寸返回。之前，所有不支持的格式都以正方形图像返回（参见 原始输出格式 ）。
  • 在 Unix 系统上，HALCON 在未调用 close_framegrabber 的情况下结束时会崩溃。该问题已得到修复。
  • 当 "DeviceUserID" 设置为" "（单个空格）时，无法用于连接。该问题已得到修复。
  • 当尝试使用繁忙设备的 "DeviceUserID" 连接该设备时，会出现误导性低级错误。该问题已得到修复。
  • 现在，每个网络接口的设备发现都是并行进行的。
  • 如果相机支持信息通道源端口 (MCSP) 和流通道源端口 (SCSPx) 寄存器，现在可以穿越 Windows 防火墙。可以使用新参数 "[Device]DeviceMessageChannelKeepAliveTimeout" 和 "[Stream]DeviceStreamChannelKeepAliveTimeout" 配置穿越。
  • 参数"[Device]LinkCommandTimeout" 的默认值已从 400000 微秒更改为 200000 微秒。
  • 根据 GigE Vision 规范修订了数据包大小协商算法。为使其更加透明和可配置，引入了以下参数："[Interface]GevInterfaceMTU"、"[Stream]DeviceStreamChannelPacketSize"、"[Stream]DeviceStreamChannelPacketSizeMin"、"[Stream]DeviceStreamChannelPacketSizeMax"、"[Stream]DeviceStreamChannelPacketSizeInc"、"[Stream]DeviceStreamChannelNegotiatePacketSize"。
  • 动态更改 "GevSCPSPacketSize" 时，可能会获取损坏或根本没有图像。这一问题已得到修复。
  • 流过滤器现在可以在 WiFi 接口上运行。在此之前，通过 WiFi 接口连接的设备只能使用插座驱动程序。
  • 流过滤器在使用巨型帧的 Killer 网络接口卡上不起作用。该问题已得到修复。
  • 套接字驱动程序可能无法请求重新发送丢失的块拖车。该问题已得到修复。
  • 改进了流过滤器的内部锁定功能，以提高性能和稳定性，尤其是对于多台相机而言。
  • 对流过滤器的重发策略进行了修改和优化，以实现低延迟流。
  • 参数"[Stream]GevStreamMaxBlockDuration" 对流过滤器没有影响，而是被固定为 200 毫秒。该问题已得到修复。
  • 以下套接字驱动程序参数已调整或引入到流过滤器中： GevStreamUnavailablePacketCount"、"[Stream]GevStreamMaxPacketGaps"、"[Stream]GevStreamMaxBlockDuration"、"[Stream]GevStreamDeliverIncompleteBlocks"、"[Stream]GevStreamFullBlockTerminatesPrev"、"[Stream]GevStreamEngineUnderrunCount"。
  • 添加了使用 GigE Vision 块数据的示例。
• 修订 13.0.1（2017 年 11 月 28 日）：
  • 首次正式发布。