用于 GenICam GenTL 兼容相机的图像采集接口

本页提供通用 HALCON GenICamTL 接口的文档，用于访问所有兼容 GenICam GenTL 的相机。注册 客户可从 MVTec WWW 服务器 下载该接口的 最新版本 。

• 英特尔兼容电脑，安装所使用的 GenTL 生产者也支持的 Windows 7（32 位或 64 位）或更新版本、XP SP1/Vista/7/8、Windows XP/Vista/7/8 x64、WoW64（在 64 位 Windows 上使用 32 位 HALCON）、内核为 2.6（或更高）的 Linux 或 macOS。
• 成功安装 GenICam GenTL 生产者。相应的 .cti 文件必须位于环境变量 GENICAM_GENTL32_PATH 或 GENICAM_GENTL64_PATH 分别指定的目录中。否则，必须在打开设备时指定 GenTL 生产者的完整路径。
• 根据所使用的传输层，确保您可以访问设备。遵循各 GenTL 生产者规定的所有要求和建议，以确保完美有效地访问设备。特别是对于（千兆）以太网，必须检查以下几点：
  • 建议使用支持巨帧的 PCIe 网络适配器。请相应配置网络适配器，例如 MTU 值为 9000。此外，相机应直接连接到网络适配器，以避免干扰其他网络流量。请注意，交换机等网络设备不一定支持巨帧。
  • 如果使用防火墙，请确保防火墙设置允许与相机进行发现、控制和流媒体通信，具体取决于所使用的传输层。对于 Windows，最简单的方法是在防火墙上允许应用程序（如 HDevelop 或您编译的应用程序）。
• GenICam GenApi。相应文件是 HALCON GenICamTL 软件包的一部分，位于 HALCON 基本目录 %HALCONROOT% 下的 genicam 目录中。详情参见 GenICam GenApi 一节。
• Windows: HALCON 图像采集接口分别是 hAcqGenICamTL.dll 或 hAcqGenICamTLxl.dll。如果正确安装了接口，所有这些 DLLs 都应位于安装 HALCON 时选择的 HALCON 基本目录 %HALCONROOT% 下的 bin\%HALCONARCH% 中。
  Linux: HALCON 图像采集接口分别是 hAcqGenICamTL.so 或 hAcqGenICamTLxl.so。如果正确安装了接口，共享对象应位于 HALCON 基本目录 $HALCONROOT 中的 lib/$HALCONARCH 中。
  macOS: HALCON 图像采集接口分别是 hAcqGenICamTL.dylib 或 hAcqGenICamTLxl.dylib。如果正确安装了接口，共享对象应位于库子目录中的 HALCON 框架 /Library/Frameworks/HALCON.framework 或 HALCON XL 框架 /Library/Frameworks/HALCONxl.framework 中。
• 默认采集模式假定计算机的速度足以处理来自相机的所有缓冲区。如果不是这种情况，（GenTL 生产者）就会默默地丢弃这些缓冲区。

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

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

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

• 目前还无法从同一设备的多个数据流中同时获取数据。
• 不支持从只读访问模式的设备上采集数据。
• 对具有多重 ROI 功能的设备支持有限。

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

• GenTL 是 GenICam 标准 的一部分，允许 GenTL 消费者（如独立于特定传输层和硬件的 HALCON GenICamTL 采集接口）和一个或多个实现对特定设备硬件（通常是相机）访问的 GenTL 生产者之间进行通用通信。
• GenTL 生产者通常由设备制造商提供。它们实现与设备在控制和数据流（图像）方面的通信，并以统一的方式呈现给 GenTL 消费者。消费者使用 GenApi 访问和控制设备功能。
• 可用的 GenICam GenTL 生产者将分别在环境变量 GENICAM_GENTL32_PATH 或 GENICAM_GENTL64_PATH 设定的路径内搜索。如果未设置这些变量，则必须指定 GenTL 生产者的完整路径（参见 识别和打开设备 ）。

通过 GenTL 接口访问的设备通常被描述为由四个实体组成的集合，其中的名称由特定的 GenTL 生产者给出。

• 'producer' - 用于访问设备的 GenTL 生产者的名称。
• 'interface' - 设备连接的（逻辑）接口名称。例如，在有多个网卡的系统上运行的基于以太网的 GenTL 生产者可能会将设备连接的网卡的 IP 或 MAC 地址作为接口名称。
• 'device'- 设备（通常是相机）的名称。请注意，一个设备可能可以通过多个生产者或接口访问，因此也可能以不同（希望相似）的名称显示。
• 'stream' - 设备每个数据流的名称。目前只完全支持无数据流（外设）或单一（图像）数据流的设备，因此尚未使用。

设备列表可通过 info_framegrabber 获取，参数为 "info_boards"（所有可检测设备）或 "device"（仅可用设备）。每个条目都由 "token:value"（上面列出的实体，通常还有其他实体）形式的条目组成，并用" | "（空格 - 管道 - 空格）序列分隔。
info_framegrabber 的结果可直接传递给 open_framegrabber。或者，也可以直接指定设备。为此，可以省略一个或多个条目（或指定为 "默认"）——这就像使用通配符，意味着不应考虑该实体的特定 ID（任何 ID 都能匹配）。HALCON 采集接口将遍历 GenTL 设备树（生产者 -> 接口 -> 设备 -> 数据流），直到找到所有非默认项的完全匹配项。
对于 open_framegrabber，各个条目的评估值如下：

• 'producer'：该值被解释为 GenTL 生产者的文件名（总是以 .cti 为扩展名的文件）。如果使用完整路径指定，则直接打开。如果只指定文件名而不指定路径，则会搜索 GenTL 安装目录（分别通过 GENICAM_GENTL32_PATH 和 GENICAM_GENTL64_PATH 指定）。如果条目为 "默认" 或省略，则将匹配在 GenTL 安装目录中找到的任何 GenTL 生产者。
• 'interface'：该值被解释为 GenTL 接口 ID（由 GenTL 生产者分配给接口的字符串标识符）。"默认" 或省略时，任何接口都会匹配。
• 'device'：GenTL 设备 ID（由 GenTL 生产者分配的字符串标识符）。当 "默认" 或省略时，任何设备都会匹配，但只有 GenTL 生产者当前报告为可访问的设备才会匹配，不可访问的设备将被跳过。
• 'stream'：GenTL 数据流 ID。"默认" 或省略时，将使用给定设备报告的第一个数据流。

当使用不含 "token: "和分隔符" | "的纯字符串时，假定生产者、接口和流均为 "默认"，它将被直接解释为 GenTL 设备 ID。

替代 IDs：

• 除了 GenTL 设备 ID 外，如果设备支持用户自定义名称（'DeviceUserID'），还可以通过用户自定义名称打开设备。如果设置了，info_framegrabber 获得的字符串将包含 "user_name:<user-defined name>" 条目。为方便用户，如果用户自定义名称是唯一的，"device" 条目将反映该名称。如果同一用户定义名称分配给多个设备，则只有第一个设备会使用该名称，其他所有设备都将使用唯一名称。
• 有些设备可能（可选）允许使用 GenTL ID 以外的其他字符串来识别接口和/或设备。例如，设备的 MAC 或 IP 地址、序列号或类似信息。如果 GenTL 生产者支持此功能，则在打开设备时也可使用其他 ID。
• GenICamTL 接口必须对已打开的生产者、接口和设备进行参考计数。这需要以 GenTL IDs 为基础；如果使用其他 IDs，可能会导致参考计数无法正常工作。因此，我们建议始终使用 GenTL IDs 或始终使用替代 IDs。

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

• 连接设备（在 GenTL 术语中为 "远程设备"）的功能，一般是相机，通常直接从连接设备加载。
• GenTL 生产者的功能，每个（所谓的）GenTL 模块都可能有一个功能，这些功能与连接设备的 GenTL 设备树中的节点相对应：
  • 用 GenTL 术语来说，"系统" 代表 GenTL 生产者本身的整体行为。
  • 用于将设备（逻辑上）连接到系统的 "接口"。
  • "设备"（也称 "本地设备"），它是一种代理设备，控制着 GenTL 生产者对设备的查看。
  • 用于采集的 "数据流"（如果设备提供任何数据流）。

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

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

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) 之后。这不仅适用于实际设备参数，也适用于配置 GenTL 的参数和 GenICamTL 图像采集接口的内部参数。设备参数通常保留到设备断电为止。GenTL 生产者模块和消费者参数会一直保留，直到调用 close_framegrabber。使用参数 "settings_selector" 可指示哪些参数需要持久化。持久化功能包括两个步骤，将当前配置存储到文件中，然后重新加载回设备。可以使用 "do_write_settings" 参数存储由 "settings_selector" 指示的选定模块设置，之后再使用 "do_load_settings" 参数重新加载，并在两种情况下都指定所需的持久化文件路径。要查询某个功能是否可以持久化，请使用后缀"_streamable"。

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

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

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

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

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

 
RemotePersistence=%PATH_TO_PERSISTENCE_FILE_OF_THE_DEVICE% 
SystemPersistence=%PATH_TO_PERSISTENCE_FILE_OF_GENTL_SYSTEM_MODULE% 
InterfacePersistence=%PATH_TO_PERSISTENCE_FILE_OF_GENTL_INTERFACE_MODULE% 
DevicePersistence=%PATH_TO_PERSISTENCE_FILE_OF_GENTL_DEVICE_MODULE% 
StreamPersistence=%PATH_TO_PERSISTENCE_FILE_OF_GENTL_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 示例 genicamtl_easyparams.hdev。

图像采集可以是同步的（grab_image/grab_data），也可以是异步的（grab_image_start/grab_image_async/grab_data_async），参见算子的参考文档。
该接口可完全配置和控制相机和 GenTL 生产者的采集过程。请注意，当采集激活时，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"）查询缓冲区属性。这也适用于最终存在于缓冲区中的 块数据 ，并且也可在易失性模式下使用。
当应用程序调用新的抓取相关算子时，接口会将缓冲区返回给采集引擎，与缓冲区相关的查询不再有效。

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

采集接口提供了两种从设备采集图像（或其他）数据的机制：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 GenICamTL 图像采集接口内置一个转换器，可将 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 算子一起使用。
只有在 "最后获取的缓冲区" 有效的情况下，与块数据相关的功能才会提供有意义的值， 即从最后一幅图像的传送到下一次调用任何抓取相关算子（请参阅 "采集 - 缓冲区处理 " 一节）。

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

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

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

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

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

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

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

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

相机和 GenTL 生产者的参数通过 GenICam 访问，并在相应相机或 GenTL 生产者的 GenICam 描述文件中定义，因此每个产品的参数集都不同（不过参数命名应符合 SFNC 和 GenTL SFNC GenICam 标准）。调用 get_framegrabber_param(..., 'available_param_names', ...) 会返回一个元组，其中包含所连接相机和 GenTL 生产者的所有可用参数。另见有关 参数命名规则 一节。
例如，要设置 AcqHandle 所指相机的当前增益（调用 open_framegrabber 之后），用户可以调用 set_framegrabber_param(AcqHandle, 'Gain', 6.0)。
请注意，只有当参数值有效时，接口才会设置该值。不符合给定功能允许范围的整数和浮点数值会与最接近的有效值对齐。其他功能类型的无效值将被拒绝。
除了相机和 GenTL 生产者的 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 的功能，即设备和 GenTL 生产者通过 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 和有关采集控制一节 。请注意，此算子会启动 GenTL 生产者和设备上的采集，并锁定采集期间受保护的功能。如果 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" 参数，因为所有 GenTL 生产者都无法可靠地支持该参数。如果需要，应用程序需要自行实现其他功能。

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。

该接口有以下示例：

• genicamtl.hdev - 基准测试。
• genicamtl_acquisition_events.hdev - 示例如何使用消息队列处理带有附加事件数据的事件。
• genicamtl_basler_blaze_objectmodel3d.hdev - Basler Blaze TOF 传感器的使用示例。
• genicamtl_devicelost_event.hdev - 使用消息队列处理 DeviceLost 事件的示例。
• genicamtl_do_abort_grab.hdev - 终止正在进行的图像采集。
• genicamtl_easyparams.hdev - 处理 MVTec EasyParams。
• genicamtl_fileaccess.hdev - 举例说明如何从 GenICam 设备上传和下载文件。
• genicamtl_frame_rate.hdev - 测量采集设备有效帧频的示例。
• genicamtl_fwupdate.hdev - 如何使用 GenICam 的固件更新模块应用固件更新的示例。
• genicamtl_information.hdev - 用于收集系统和相机配置信息的程序。请求支持时请附上生成的文件。
• genicamtl_io_control.hdev - 如何控制设备 GPIOs 的示例。
• genicamtl_lmi_gocator_objectmodel3d.hdev - 使用 LMI Gocator 校准三维传感器的示例。
• genicamtl_parameters.hdev - 列出设备的所有参数。
• genicamtl_parameter_persistence.hdev - 演示将参数值写入文件和从文件中恢复参数值。
• genicamtl_simple.hdev - 一个简单的示例来说明接口的使用方法。
• genicamtl_smartray_ecco_objectmodel3d.hdev - SmartRay ECCO 三维传感器使用示例。
• genicamtl_software_trigger.hdev - 使用软件触发器。
• genicamtl_vrmagic_areascan3d_objectmodel3d.hdev - VRmagic AreaScan3D 已校准三维面积传感器的使用示例。
• genicamtl_zivid_one_objectmodel3d.hdev - 使用 Zivid One 三维传感器的示例。

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

一般情况：

• 检查是否使用了 最新版本 的 HALCON GenICamTL 接口。
• 检查 系统要求。
• 检查所用 GenICam GenTL 生产者的更新版本。
• 检查设备是否有最新固件。
• 启用 HALCON 中的低级错误信息，以查询有关问题的更多信息（如果适用，请检查 HDevelop 中的输出控制台）。
• 如果设备通过以太网连接，且系统中的防火墙处于激活状态，则必须对防火墙进行配置，以便所有预期使用设备的应用程序（如 HDevelop，以及任何用户开发的应用程序）都能完全访问所连接的设备。

GenICam：

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

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

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

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

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

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

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

• 修订 20.11.16（2023 年 4 月 5 日）：
  • 如果数值参数除了纯数值外还有其他特殊表示形式，现在可以使用后缀 "_representation" 来查询表示形式的类型。
  • 现在可以使用后缀 "_string" 查询参数值的字符串表示形式。
  • libCLAllSerial 共享对象已从 GenApi 3.4.0 的再分发中移除。
  • 新增了 HDevelop 示例 genicamtl_software_trigger.hdev，以演示如何结合 grab_image_async 使用软件触发器。
  • 新增了 HDevelop 示例 genicamtl_do_abort_grab.hdev，以演示如何中断抓取算子并停止采集引擎。
  • 改进了 HDevelop 示例 genicamtl_basler_blaze_objectmodel3d.hdev，以处理生产者名称的更改。
  • third_party_genicamtl.txt 现在包含指向相应软件位置的链接。参见 第三方库的使用 。
• 修订 18.11.15（2022 年 10 月 7 日）：
  • MVTec EasyParams 以简单易用的方式处理最常见的 GenICam 功能。
  • 新增参数 "available_easyparam_names" ，用于返回 MVTec EasyParams 列表。
  • 新增了 HDevelop 示例 genicamtl_easyparams.hdev，以演示如何处理 MVTec EasyParams。
  • 在 Unix 系统上，加载包含 Windows 行结束符的 GenICam 持久文件失败。这一问题已得到解决。
• 修订 18.11.14（2022 年 5 月 11 日）：
  • 底层 GenApi 版本已更新至最新的 3.4 正式版。这修复了当设备无法执行底层命令 "DeviceRegistersStreamingEnd" 时，在 "do_load_settings" 过程中出现的崩溃问题。
  • 在 Unix 系统上，加载在 Windows 系统上编写的 Consumer persistence 或配置 ini 失败。这一问题已得到修复。此外，在 Windows 系统上写入消费者持久性文件或配置 ini 文件已改为使用 Unix 行结束符。
  • 现在可以对 "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 脚本 genicamtl_information.hdev 现在可将输出数据保存到用户的文档文件夹中，以避免出现写入权限缺失的问题。此外，脚本现在还能处理设备唯一名称中的非字母数字字符。此外，还修复了一个与恢复原始触发器设置有关的问题。
• 修订 18.11.13（2021 年 10 月 20 日）：
  • 现在可以解码 GenICam GenTL 和 GenDC 标准规定的 JPEG 有效载荷。
  • 现在支持 GigE Vision 标准和 GenICam 像素格式命名规则规定的打包拜尔格式。
  • 现在支持 "Coord3D_AC32f"、"Coord3D_AC16" 和 "Coord3D_AC8" 像素格式。
  • 消费者模块的读写参数是可流参数，即可以通过 "do_write_settings" 或 "do_write_configuration" 进行持久化。然而，对于这些后缀为"_streamable" 的参数，get_framegrabber_param 返回值为 0。该问题已得到修复。
  • 现在，该接口的发布包中包含了为 HDevelop 示例浏览器提供元信息的文件。
• 修订 18.11.12（2021 年 2 月 15 日）：
  • 底层 GenApi 版本已更新至最新的官方版本 3.3。
  • 由编码器控制的线扫三维设备组装 ObjectModel3D 的过程已大大加快。为了实现这种加速，设备必须按照 GenICam 标准功能命名规则 2.7 及更高版本的描述，通过其 ValueArrayCandidates 宣布 ChunkEncoderValue 和 ChunkScanLineSelector。
  • 对于以 "token:value "形式提供设备字符串的 open_framegrabber，必须包含分隔符"|"。这一限制已被取消。
  • 除非设置了环境变量 TEMP、TMP 或 TMPDIR，否则 GenICam 缓存机制将不起作用。现在，/tmp 或 HALCONROOT 被用作备用。
  • 新增了 HDevelop 示例 genicamtl_frame_rate.hdev，用于测量采集设备的帧频。
  • HDevelop 示例 genicamtl_acquisition_events.hdev 在事件快速进入时陷入死锁。该问题已得到修复。
  • 已对 HDevelop 示例 genicamtl_basler_blaze_objectmodel3d.hdev 进行调整，以便在较新固件版本下运行。
  • 重构了 HDevelop 示例 genicamtl_information.hdev，现在它调用新的函数库 genicamtl_information.hdpl。此外，新版本关闭了触发模式（TriggerMode），以便测试图像采集。
  • 改进了错误处理。现在可以使用算子 get_extended_error_info 查询有关错误原因的附加信息。对于 HALCON 语言接口（C# 和 C++），HALCON 异常类提供了访问附加错误信息的方法。
  • 更新了 HDevelop 示例 genicamtl_zivid_one_objectmodel3d.hdev，使其与 Zivid SDK 2.0 或更高版本兼容。
• 修订 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 GenICamTL 图像采集接口本身的内部参数，如 "grab_timeout" ），参见 参数– 持续设备状态。
  • 现在，在设备已打开的情况下，可以为单个 GenTL 生产者模块或 GenTL 消费者模块写入和加载持久性文件。迄今为止，只有远程设备可以做到这一点。可通过参数 "settings_selector"（设置选择器）选择要写入或加载的持久化文件。
  • 使用 open_framegrabber 加载持久化文件时，部分持久化参数值被覆盖。该问题已得到修复。
  • 在 Windows 系统中，需要额外依赖项的 GenTL 生产者（这些依赖项位于同一位置，但不在 路径 中）在某些情况下无法正确加载。这一问题已得到修复。
  • 在 18.05 之前的 HALCON 版本中，get_framegrabber_param(..., 'event_message_queue', ...) 失败。该问题已得到修复。
  • HDevelop 示例 genicamtl_zivid_one_objectmodel3d.hdev 曾经打开找到的第一个 GenICam 设备。现在，该示例已改进为只打开 Zivid 设备。
  • 新增了 HDevelop 示例 genicamtl_parameter_persistence.hdev，以演示向文件写入参数值和从文件恢复参数值。
  • HDevelop 示例 genicamtl_basler_tof_objectmodel3d.hdev 已被新示例 genicamtl_basler_blaze_objectmodel3d.hdev 所取代。
  • 参数 "available_event_names" 被错误地写成了 "available_event_types"。该问题已得到修复。
• 修订 13.0.8（2019 年 12 月 10 日）：
  • 将底层 GenApi 版本更新至最新正式版本 v3.2。更新包括用户和序列器集持久性的错误修复以及其他小错误修复。
  • 参数 "num_buffers" 的任意最大值限制为 1023。这一限制已被取消。
  • 新增了 HDevelop 示例 genicamtl_information.hdev，用于收集系统和相机配置的相关信息。
  • 在 HDevelop 示例 genicamtl_lmi_gocator_objectmodel3d.hdev 中，返回的分辨率和偏移量的单位取决于设备，因此在示例中添加了变量 "Units"。
• 修订 13.0.7（2019 年 7 月 22 日）：
  • 新增了一个 HDevelop 示例，演示从 Zivid One 3D 传感器获取图像和 HALCON ObjectModel3D。
  • 现在，您可以使用"_streamable" 后缀查询功能是否可以持久化。
  • 对 HDevelop 示例 genicamtl_parameters.hdev 进行了扩展，以检查参数是否可以持久化。
  • 该接口的分发包中已添加了 third_party_genicamtl.txt 文件。
• 修订 13.0.6（2019 年 5 月 2 日）：
  • 已添加对 "BiColorRGBG8" 和 "BiColorBGRG8" 像素格式的支持。
  • 从 grab_data 和 grab_data_async 中生成的三维对象模型现在可以使用二维映射。这大大加快了多个算子处理三维对象模型的速度。
  • 从三维图像生成 HALCON ObjectModel3D 的机制已扩展到视差图像。此类图像需要包含 SFNC 2.4 中指定的以下块："ChunkScan3dFocalLength"、"ChunkScan3dBaseline"、"ChunkScan3dPrincipalPointU"、"ChunkScan3dPrincipalPointV"。
  • 新增 HDevelop 示例 genicamtl_io_control.hdev，演示如何控制设备的 GPIOs。
• 修订 13.0.5（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 示例 genicamtl_fileaccess.hdev。
  • 现在支持 GenICam 的固件更新。参见 固件更新 和新的 HDevelop 示例 genicamtl_fwupdate.hdev。
  • 现在支持在消息队列中接收 GenICam 事件，参见 事件消息队列。到目前为止，GenICam 事件只能通过回调来支持，因此无法在 HDevelop 中使用。此外，我们还添加了两个新的 HDevelop 示例来展示这一功能 genicamtl_acquisition_events.hdev 和 genicamtl_devicelost_event.hdev。
  • "do_write_configuration" 已被扩展，不仅能存储当前设备配置，还能为所有 GenTL 生产者模块（系统、接口、设备和数据流）生成持久文件，参见 参数– 持续设备状态。
  • 添加了新参数 "buffer_timestamp_ns" 和 "device_timestamp_frequency"，以提高 "buffer_timestamp" 的可用性。
  • 如果 GenTL 生产者没有实现立即停止采集引擎（ACQ_STOP_FLAGS_KILL），则停止引擎（如 close_framegrabber）可能会导致死锁。这一问题已得到修复。
  • 在 Windows 系统中，需要额外依赖项的 GenTL 生产者无法正确加载，这些依赖项位于同一位置，但不在 路径 中。该问题已得到修复。
  • 在 aarch64-linux 上，GenTL 生产者在 GENICAM_GENTL32_PATH 而非 GENICAM_GENTL64_PATH 中搜索。该问题已得到修复。
  • 传递给 open_framegrabber 的某些通用参数无法通过 get_framegrabber_param 获取。该问题已得到修复。
  • 长度超过 1024 个字符的字符串参数会被 get_framegrabber_param 静默裁剪。该问题已得到修复。
  • 当 "start_async_after_grab_async" 设置为 "禁用" 时，远程设备上的采集会在每帧后停止。该问题已得到修复。
  • 为保持一致，以下示例已重命名：genicamtl_areascan3d_objectmodel3d.hdev 为 genicamtl_vrmagic_areascan3d_objectmodel3d.hdev，genicamtl_gocator_objectmodel3d. hdev 改为 genicamtl_lmi_gocator_objectmodel3d.hdev，以及 genicamtl_smartray_3dsensor_objectmodel3d.hdev 改为 genicamtl_smartray_eco_objectmodel3d.hdev。
• 修订 13.0.4（2018 年 4 月 27 日）：
  • 添加了对 "Mono4p" 像素格式的支持。
  • 添加了对 "YCbCr411_8" 像素格式的支持。
  • 如果不支持的像素格式与支持的 Mono 格式足够相似，现在会尝试以实际图像尺寸返回。之前，所有不支持的格式都以正方形图像返回（参见 原始输出格式 ）。
  • 在 Unix 系统上，HALCON 在未调用 close_framegrabber 的情况下结束时会崩溃。该问题已得到修复。
  • 当 "DeviceUserID" 设置为" "（单个空格）时，无法用于连接。该问题已得到修复。
  • 当尝试使用繁忙设备的 DeviceUserID 连接该设备时，会出现误导性低级错误。该问题已得到修复。
• 修订 13.0.3（2017 年 11 月 28 日）：
  • HALCON 库的技术依赖已被移除。
  • 新增了对 GenTL 模块事件的支持。它们与设备事件一样使用，但包括模块的方括号前缀。因此，您可以通过查询以所需模块为前缀的 "EventSelector_values" 来查询可用的模块事件。更多信息，参见 事件数据。
  • 已添加新参数 "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 也不会启动新的采集。该问题已得到修复。
  • 新增了一个 HDevelop 示例，演示从 SmartRay 三维传感器获取图像和 HALCON ObjectModel3D。
• 修订 13.0.2（2017 年 5 月 3 日）：
  • 将底层 GenApi 版本更新到最新正式版本 v3.0.2，其中包含一些小错误修复。
  • 不支持不提供 "AcquisitionStart" 和 "AcquisitionStop" 命令的设备。这个问题已经解决。对于 Camera Link 设备，缺失的功能将被自动容忍。
  • 新增了一个 HDevelop 示例，演示从 Basler TOF 传感器获取图像和 HALCON ObjectModel3D。
  • 扩展了接口文档，现在包含了对 info_framegrabber(...,'info_boards',...) 所返回字符串的描述。
• 修订 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。
• 修订 6.5 （2016 年 5 月 13 日）：
  • 将底层 GenApi 版本更新到最新的官方版本 v3.0.1。以前的版本无法打开某些特定的相机，在最糟糕的情况下，使用这些设备时应用程序也会崩溃。该问题已得到修复。请注意，HALCON 安装程序中的 genicam 目录也将随之更新。
  • 在 Windows 环境下，如果环境变量 路径 为空，open_framegrabber 就会崩溃。该问题已得到修复。
  • 改进了对线扫相机的支持，首先查询缓冲区的交付图像高度（如果可用）。这也使得无法正确更新缓冲区高度的线扫相机可以使用生产者。
• 修订 6.4 （2016 年 2 月 15 日）：
  • 将底层 GenApi 版本更新至最新的官方版本 v3.0，这样打开设备的速度更快，所需的内存更少。请注意，HALCON 安装中的 genicam 目录也将随之更新。
  • 添加了对 "Mono10p" 和 "Mono12p" 像素格式的支持。
  • 为本文档添加了 "使用内部色彩转换" 段落。
  • 根据该文档，get_framegrabber_param(..., 'AnyParameter_range', ...) 返回的第四个值是默认值。实际上，它是当前值。因此，本文档已作相应调整。
• 修订 6.3 （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.2 （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"。该问题已得到修复。
  • 改进了 HDevelop 示例 genicamtl_parameters.hdev。
  • HDevelop 示例 genicamtl_gocator_objectmodel3d.hdev 已适应 Gocator GenTL 驱动程序 4.x 版。现在 X-Y-Z 偏移量和 X-Y-Z 分辨率均以纳米为单位。此外，现在还能正确解释 TransformationZOffset。
• 修订 6.1 （2015 年 2 月 26 日）：
  • 将基础 GenApi 版本更新至最新正式版本 v2.4.1，包括性能改进和若干小错误修复。请注意，HALCON 安装程序中的 genicam 目录也将随之更新。
  • 消费者与 GenTL v1.4 规范保持一致。
  • 已添加对缓冲区处理模式 "OldestFirstOverwrite" 和 "NewestOnly" 的支持，这需要生产者的支持。
  • 已添加通用参数 "device_event_handling=0"，以便在打开设备时明确忽略事件通道。
  • 使有关意外参数类型的警告更易于理解。
• 修订 5.8 （2014 年 3 月 20 日）：
  • 修正了以任意顺序使用多个图像采集接口（这些接口使用的 GenApi 版本不同）时出现的问题。
  • 修复了在使用基于 GenApi 的多个图像采集接口（这些接口使用相同的 GenApi 版本）时发生崩溃的问题。在这种情况下，当关闭其中一个接口的最后一个实例时，其余接口无法再使用 GenApi。此修复的副作用是 GenApi 无法再被卸载。
  • 改进了参数 "clear_buffer" 的描述。
• 修订 5.7 （2014 年 1 月 31 日）：
  • 修正了在尝试执行不带参数的 GenICam 命令时崩溃的问题。
  • 修复了尝试使用易失性模式时的崩溃问题。
  • 通过对更多调用进行异常处理，提高了稳健性。
  • 已添加对 PFNC 像素格式命名空间的支持。请注意，没有实施额外的转换例程。
  • 新增参数 "register_<addr>_<len>"，用于直接存取寄存器。
  • 添加了参数 "do_write_settings" 和 "do_load_settings"，以写入和载入 GenICam 持久设置。参数 "do_write_configuration" 和 "do_load_configuration" 现在也支持 GenICam 持久化设置。
  • 切换 "color_space" 参数值现在可立即生效。
  • 扩展了 "streaming_mode" 和 "clear_buffer" 参数的文档。
  • 重新命名环境变量：
    HALCON_GENTL_WRITE_XMLFILE -> HALCON_GENICAM_WRITE_XMLFILE
    HALCON_GENTL_WRITE_RAW_XMLFILE -> HALCON_GENICAM_WRITE_RAW_XMLFILE
    HALCON_GENTL_FILE_PAYLOAD_DIR -> HALCON_ACQUIRED_FILE_PAYLOAD_DIR
• 修订 5.6 （2013 年 5 月 24 日）：
  • 通用参数 "streaming_mode=0" 现在可用于不提供 AcquisitionStart/Stop/Mode（开始/停止/模式）功能的设备。
  • 对于杀死事件时可能出现的竞赛条件，内部事件处理现在更加稳健。
  • 修正了调用 info_framegrabber(..., 'info_boards', ...) 或 info_framegrabber(..., 'device', ...) 时未检测到设备而导致崩溃的问题。
• 修订 5.5 （2013 年 3 月 25 日）：
  • 全面修订了整个接口的实现。请注意，并非在所有情况下都能完全保持向后兼容性，特别是有些参数已不再支持。
  • 改进了生产者和设备检测，增加了更灵活的设备打开选项。
  • 支持与来自相同和/或不同 GenTL 生产者的设备并行开放连接。
  • 广泛支持 GenICam，包括 IRegister 等高级功能和参数类型。现在 32 位系统也支持 GenICam 64 位整数。
  • 通过 get_framegrabber_param 支持 GenICam 块数据，移除了 grab_data(_async)（过去对块的支持有限）。新的实现会在运行时保留抓取的缓冲区，直到下一次抓取。
  • 通过回调支持 GenICam 事件和 GenICam 事件数据。
  • 通过回调支持 GenICam 功能更改通知。
  • 添加了 "do_write_configuration" 参数。
  • 移除了 "callback_timeout" 参数。
  • 支持在运行时更改基本图像属性的设备以及修改图像的 GenTL 生产者。
  • 支持非图像有效载荷类型。
  • 改进了对未知图像格式原始数据的支持。
  • 改进了对 GenICam 配置（XML）文件的读写支持。
  • 支持存在已知回调问题的设备。
  • 改编文件。
  • 改进了 LMI Gocator 示例 genicamtl_gocator_objectmodel3d.hdev。现在 Z 坐标已正确转换为 HALCON 相机坐标系，示例还显示了如何加载配置文件。
  • 修正了 "generic" 参数的文档。
• 修订 5.4 （2012 年 11 月 16 日）：
  • 移除了对 HALCONROOT 环境变量的所有依赖。
  • 修正了 XML 加载，即使没有清单，也能打开设备。
• 修订 5.3 （2012 年 10 月 22 日）：
  • 使用清单中具有最高模式和版本号的 XML。
  • 修正了 CLProtocol URLs 的处理方式。
  • 修正了某些调用生产者的 DSInfo 时错误的数据大小。
  • 修正了出错时的 cancel_mutex 锁定。
  • 移除了注册 GenApi 内部回调时的警告信息。
  • 添加了新示例 genicamtl_gocator_objectmodel3d.hdev，用于使用 LMI Gocator 校准三维传感器。
• 修订 5.2 （2012 年 9 月 28 日）：
  • 修正了一个问题，该问题在解析参数时打开某些设备可能导致崩溃。
• 修订 5.1 （2012 年 7 月 11 日）：
  • 将 GenApi 更新至 v2.3.1。请注意，HALCON 安装中的 genicam 目录也将随之更新。
  • 修正了因 GenApi 内部回调处理不当而导致的自动更新参数宽度、高度、有效载荷大小和采集模式的问题。
  • 添加了使用 VRmagic AreaScan3D 校准三维面积传感器的 HDevelop 示例程序。
• 修订 5.0 （2012 年 5 月 15 日）：
  • HALCON 11 版本的接口（包含在 HALCON 11 DVD 中）。
  • 增加了同时支持多个生产者的功能。
  • 添加了端口访问模式缓存。
  • 修正了 URL 解析。
  • 添加了缺失错误检查，但也放宽了过于严格的检查。
  • 添加了更多警告信息并修改了文本。
  • 宽松的 GenApi 回调注册码。
  • 添加了对 Mac OS X 10.7 的支持。
  • 使用 GenApi v2.3。
• 修订 4.4 （2011 年 11 月 21 日）：
  • 修正了参数 "buffer_timestamp" 中错误的返回值，并将类型从整数改为字符串。
  • 修正了每次调用 open_framegrabber 时在 路径 环境变量中添加 GenICam 路径的问题。
  • 修正了使用多个名称相同但接口不同的设备时出现的问题。
  • 修正了每次调用 grab_image 或 grab_image_async 时启动流的问题。
  • 通过算子 grab_data 和 grab_data_async 增加了对块数据的支持。在本文档中还添加了一个小节。
  • 通过用户特定的回调，添加了在发生任何可用设备特定事件时获取通知的功能。
  • 为抓取图像添加了互斥保护。
  • 添加了参数 "available_callback_types" 和 "callback_timeout"。
  • 已添加参数 "clear_buffer" 和 "verify_value"。
  • 添加了通用参数 "device_access" 和 "streaming_mode"。
  • 将 info_framegrabber(..'general'..) 改为静态列表。
  • 如果设备的采集模式为 "Continuous"，则更改了 grab_image 的行为。现在应始终返回新图像。
  • 更改了参数 "do_write_xml_file" 的行为。现在不仅会写入远程设备的 XML 文件，还会写入 GenTL 生产者模块的 XML 文件（包括所用 GenTL 生产者的名称）。
  • 修改了内部颜色转换，使其依赖于当前缓冲区提供的信息。目前，如果 BUFFER_INFO_PIXELFORMAT_NAMESPACE 或 BUFFER_INFO_PIXELFORMAT 返回的值不支持，接口将使用设备的像素格式。在这种情况下，将返回一条低级错误信息。
  • 移除了 open_framegrabber 中的外部触发器设置。
• 修订 4.3 （2010 年 12 月 13 日）：
  • 将 open_framegrabber 中水平/垂直分辨率的默认设置从 1 改为 0。
  • 修正了在 Linux 下多次打开相机时 XML 文件的解析问题。
  • 更改图像尺寸并使用软件触发时的固定超时。
  • 修正了模块参数设置问题，该问题在某些情况下会导致错误。
  • 修正了发现多个 GenTL 生产者但其中一个无法加载时的错误。现在会跳过坏掉的那个，其他的都能正确加载。
  • 改进了 YUV 像素格式的色彩转换。
  • 已添加对表示标记的支持，以正确显示十六进制数字。
  • 添加了低级错误信息，以改进错误处理。
  • 已添加辅助函数，用于纠正超出参数有效边界的值。
• 修订 4.2 （2010 年 9 月 30 日）：
  • 更改了启动采集的顺序： 现在，在启动 GenTL 生产者采集后才开始采集远程设备。
  • 修正了在使用参数 "info_boards"、"device" 或 "general" 后多次调用 info_framegrabber 时出现的错误。
• 修订 4.1（2010 年 9 月 10 日）：
  • 修正了在设备已打开的情况下调用 info_framegrabber(..., 'info_boards', ...) 时防止 HDevelop 崩溃的错误。
  • 修正了防止重复调用 "StartAcquisition" 的错误，该错误会导致某些设备出现问题。
  • 可同时使用多个设备。
  • 修复了内存泄漏。
  • 修正了一个错误，即使所使用的 GenTL 生产者中没有模块参数，也能打开设备。
  • 模块参数名现在以相应模块层的前缀开头，以确保所有参数名的唯一性。如果没有前缀，这些参数的返回值和类别可能会出错。
  • 如果 GenICam 的环境变量未正确设置，则接口会出现 H_ERR_DLOPEN 故障。现在启用了 GenICam 库的延迟加载功能，因此可以自动设置环境变量。
  • 已添加参数 "buffer_is_incomplete"、"buffer_timestamp"、"do_write_xml_file"、"num_buffers_await_delivery"、"num_buffers_underrun"、"tl_displayname"、"tl_filename"、"tl_id"、"tl_model" 和 "tl_pathname"。
  • 在本文档中添加了 "GenICam GenTL "和 "参数命名" 段落。
  • HALCON 10 version of the interface (included in HALCON 10 DVD).
• 修订 4.0 （2010 年 7 月 30 日）：
  • 首次正式发行。