系列文章目录

GenICam标准（一）
GenICam标准（二）
GenICam标准（三）
GenICam标准（四）
GenICam标准（五）
GenICam标准（六）

---

---

1、简介

    GenApi 模块解决如何去配置相机的问题。主要的思路是，让相机生产厂商为他们的相机提供机器可以识别的产品说明。这些相机描述文件（camera description files）包含所有需要的信息，用以自动地把相机的属性（features）和其寄存器（registers）相对应。

    相机的 Gain 属性是一个典型的例子，假设用户想令 Gain=42 ，利用 GenICam ，通用的软件可以读相机的描述文件并发现，要把 Gain 属性设成 42 意味着向地址为 0x0815 的寄存器写入值 0x2A 。其他要做的工作可能是检查相机是否提供 Gain 属性，并检查要写入的值是否在 Gain 的允许范围内。

    请注意，给相机添加新的属性仅仅意味着扩展相机的描述文件，就可以对所有符合 GenICam 标准的程序立即生效。

    图 2 显示了配置照相机所涉及的图层。

    请注意，本文档中的 GenApi 部分只处理照相机描述文件。它旨在帮助 GenICam 用户理解 GenApi 模块背后的关键思想，并使人们能够编写他们自己的相机描述文件。GenApi 参考实现附带了一个参考手册，展示了最终用户如何使用 GenApi 模块，即使不深入了解本节中介绍的概念。

2、照相机描述文件的基本结构

    该摄像机是通过在一个包含一组节点的 XML 文件上进行描述的，每个节点都有一个类型和一个唯一的名称。节点可以相互链接，每个连接都起着一定的作用。图 3 显示了一个非常简单的图形符号示例。节点显示为标记为 “type::name” 的气泡标签，链接显示为标记为角色名称的箭头。

    有两个特殊的节点：

• 根节点，可以遍历节点图
• 设备节点，提供到传输层连接。

图 3 由一个简单的配置文件构造而成的图的拓扑结构

    图 3 中的增益节点（Gain）为 IntReg 类型，它允许从寄存器中提取一个整数。从根节点上看，这是照相机的一个特性。因此，根节点包含一个名为 pFeature 的链接，它引用了增益节点（Gain）。要读取和写入增益寄存器，增益节点需要访问照相机端口，因此它包含一个到设备节点的链接。该链接被命名为 pPort ，并引用了设备节点。

    增益节点（Gain）包含在大端模式下提取两个字节无符号整数所需的所有信息。完整的相机描述文件如下：

<?xml version="1.0" encoding="utf-8"?>
<RegisterDescription 
	ModelName="Example01" 
	VendorName="Test" 
	ToolTip="Example 01 from the GenApi standard" 
	StandardNameSpace="None" 
	SchemaMajorVersion="1" 
	SchemaMinorVersion="1" 
	SchemaSubMinorVersion="0" 
	MajorVersion="1" 
	MinorVersion="0" 
	SubMinorVersion="0" 
	ProductGuid="1F3C6A72-7842-4edd-9130-E2E90A2058BA" 
	VersionGuid="7645D2A1-A41E-4ac6-B486-1531FB7BECE6" 
	xmlns="http://www.genicam.org/GenApi/Version_1_1" 
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
	xsi:schemaLocation="http://www.genicam.org/GenApi/Version_1_1
	 http://www.genicam.org/GenApi/GenApiSchema_Version_1_1.xsd">
	 
	<Category Name="Root">
		<ToolTip>Entry for traversing the node graph</ToolTip>
		<pFeature>Gain</pFeature>
	</Category>
	
	<IntReg Name="Gain">
		<ToolTip>Access node for the camera's Gain feature</ToolTip>
		<Address>0x0815</Address>
		<Length>2</Length>
		<AccessMode>RW</AccessMode>
		<pPort>Device</pPort>
		<Sign>Unsigned</Sign>
		<Endianess>BigEndian</Endianess>
	</IntReg>
	
	<Port Name="Device">
		<ToolTip> Port node giving access to the camera</ToolTip>
	</Port>
</RegisterDescription>

    <?xml> 节点是一个处理元素，提供有关文件编码的提示，并且总是这样的。

    <RegisterDescription> 元素是封装摄像机所有节点的最外层括号。相机由模型名称（ModelName）和 VenderName 属性标识标识。

    每个节点都有一个可选的 <ToolTip> 元素，其中包含一个简短的描述。增益节点（Gain）有一些依赖于其 IntReg 类型的附加元素，并告诉我们，例如，寄存器的地址或它的长度。其默认值为空字符串。

    通常，一个实现将为每个节点创建一个软件对象，并根据 XML 文件中描述的逻辑链接将这些对象链接在一起。这些节点既可以通过它们的（唯一的）名称来检索，也可以通过从根节点开始遍历节点图来找到。一旦用户有了一个指向节点的指针，他就可以通过节点对象的编程接口访问该特性。

    XML 文件的语法是在由模式位置属性给出的 XML 模式中定义的。该模式是该标准的一部分。本文解释了 GenICam 的思想和总体结构。模式及其嵌入的参考文档描述了正式的细节。如果有疑问，模式的内容将覆盖此文本的内容。

    文件位置 http://www.genicam.org/GenApi/GenApiSchema_Version_1_1.xsd 对于相机配置文件是必需的，但可以在运行时被重写。

3、节点、接口和抽象特征

Nodes, Interfaces, and Abstract Features

    相机描述文件中的每个节点只描述一个项目。基于项目的自然性，节点有一个特定的类型（node type）和一个特定的接口（interface）。目前可用的接口（interfaces）如下（每个接口有一个控件用于映射到 GUI）：

• IInteger —— 映射到一个带有 value、min、max 和 increment 的滑动条（slider）

• IFloat —— 映射到一个带有 value、min、max 和一个物理单位的滑动条（slider）

• IString —— 映射到一个显示字符串的编辑框

• IEnumeration —— 映射到一个下拉框

• ICommand —— 映射到一个命令按钮

• IBoolean —— 映射到一个复选框（check box）

• IRegister —— 映射到一个显示 16 进制字符串的编辑框

• ICategory —— 映射到一个可以反映相机属性结构的树控件

• IPort —— 映射到一个相机端口，通常不用图形显示

    第 2.9 节给出了接口特性的更多细节。可用的节点类型在第 2.8 节中说明。可能有多种节点类型实现同样的接口类型。例如，IInteger 接口，被下列（不是全部）节点类型实现：

• IntReg —— 根据字节边界，从寄存器取出一个整数

• MaskedIntReg —— 从寄存器的一段取出一个整数，例如，从第 8 位到第 12 位

• Integer —— 从不同的节点得到 value、min、max 和 increment 属性，合并在一起

    每个节点类型从不同的源，用不同的方法取出一个整数值。对于需要输入一个整数值的连接，所有这些节点的输出值都可以用作类型安全的输入。

    抽象特征（Abstract features）总是用接口类型（interface type）、名称（name）和含义（meaning）来描述。例如，相机的 Gain（名称）可以被定义为 IInteger（接口类型），并且可以描述相机内的增益（含义）。注意，其它的定义也可能存在，例如，Gain 可以被定义为一个 IEnumeration 或一个 IFloat 。

4、获取和设置值

Getting and Setting Values

    当用户读或写一个节点的值，节点会触发节点图内一系列的读写操作。为了说明这一点，图 4 显示了 Gain 属性的一个更复杂的例子。Gain 属性可以抽象成一个 IInteger 接口，通过这个接口，用户可以设置 Value 并且可以读（或其它操作）Min 和 Max 值。图 4 的例子假定相机有 3 个寄存器，一个是 Gain 的 Value ，另两个是 Min 和 Max 。利用 IntReg 节点可以从每个寄存器取出相应的值。名字为 Gain 的 Integer 节点收集并合并这些数据，再通过 IInteger 接口把结果传递出来。

图 4：获取和设置功能时的控制流示例

...
	 
	<Category Name="Root">
		<ToolTip>Entry for traversing the node graph</ToolTip>
		<pFeature>Gain</pFeature>
	</Category>
	
	<IntReg Name="Gain">
		<ToolTip>Access node for the camera's Gain feature</ToolTip>
		<Address>0x0815</Address>
		<Length>2</Length>
		<AccessMode>RW</AccessMode>
		<pPort>Device</pPort>
		<Sign>Unsigned</Sign>
		<Endianess>BigEndian</Endianess>
		<pValue>GainValue</pValue>
	    <pMin>GainMin</pMin>
	    <pMax>GainMax</pMax>
	</IntReg>
	
	<Port Name="Device">
		<ToolTip> Port node giving access to the camera</ToolTip>
	</Port>
...

    如果用户读取 Gain 节点的值，调用会被分派到 GainValue 节点，而 GainValue 节点会通过 IPort 接口向 Device 节点查询正确的寄存器。

    如果用户试图设置 Gain 节点的值，实现程序可能首先会从 GainMin 和 GainMax 节点读出 Min 和 Max 值以检查范围。如果输入值在允许的范围内，Gain 节点会通过 GainValue 节点和 Device 节点把值写入相机。注意，根据相应 IntReg 节点的 Cacheable 属性，实现程序可能会把 Min 和 Max 值放入缓存。

5、访问模式

Access Mode

每个节点都有一个下表定义的访问模式：

Readable	Writable	Implemented	Access Mode
＊	＊	0	NI – 未实现
0	0	1	NA – 不可用
0	1	1	WO – 只写
1	0	1	RO – 只读
1	1	1	RW – 读写

    1 = yes, 0 = no, ＊ = don’t care

    属性可能已经被相机实现，但暂时不可用。如果可用，则根据定义，属性被实现并且可以读和/或写。

    有些节点由某些元素来控制访问权限，例如寄存器节点（参见 2.8.3）。另外，GenICam 还提供 3 种在运行时改变访问权限的机制。

• 根据另一个节点的值，属性可能暂时被锁定（locked）。属性在锁定的状态下不可写。根据上面的表格，写标志位暂时强制为 0 。

• 根据另一个节点的值，属性可能暂时不可用（not available）。根据上面的表格，写标志位和读标志位暂时强制为 0 。

• 根据另一个节点的值，属性可能没有实现（not implemented）。根据上面的表格，实现标志位始终强制为 0 。

    “可用” 和 “已实现” 是不同的，因为 GUI 可能想用不同的方法来处理这两种情况。未实现的属性不会显示给用户；而暂时不可用的项目只是灰色的并且值会被替换，例如替换成 “—” ；暂时被锁定的属性是灰色的，但是属性的值仍然会显示。

    以硬件 Trigger 为例来说明让一个属性暂时不可用（temporarily not available）的情况，硬件 Trigger 的值可以为 On 或 Off 。如果 Trigger 是 On ，另外一个属性 TriggerPolarity（触发极性） 变得可用，TriggerPolarity 属性指示硬件信号是 ActiveHigh 还是 ActiveLow 。如果 Trigger 是 Off，则 TriggerPolarity 属性是无意义的，应该被置为灰色。

    图 5 显示了这个信息在相机描述文件中如何处理，Trigger 和 TriggerPolarity 属性用 Enumeration 类型的节点来实现，这种类型把一组枚举型的入口映射到整数值。例如，Trigger 属性的入口是 On=1 和 Off=0 。利用 IntReg 类型的节点把整数值映射到寄存器。

    图 5 控制一个特性是否可访问

    TriggerPolarity 节点有个叫 pIsAvailable 的连接，这个连接需要指向一个提供 IInteger 接口的节点。如果这个被指向的节点的值为 0 ，那么 TriggerPolarity 节点暂时不可访问。

    在这个例子中，pIsAvailable 可以直接指向 TriggerReg，因为 Trigger=On 被映射为 1，Trigger=Off 被映射为 0 。如果不是这样的话，一个类型为 IntSwissKnife 的节点会很有用，它能根据数学公式计算其他整数节点的值，并得到一个整数的结果。在 XML 文件中，节点看起来像这个样子：

<IntSwissKnife Name="TriggerEnabled">
	<ToolTip>Determines if the Trigger feature is switched on</ToolTip>
	<pVariable Name="TRIGGER">TriggerReg</pVariable>
	<Formula>TRIGGER==1</Formula>
</IntSwissKnife>

    <Formula> 入口的数学公式被计算，得到节点的计算结果。在计算之前，变量的符号名称被对应节点的整数值替换。在本例中，只有一个 <pVariable> 入口指向 TriggerReg 节点，符号名称是 TRIGGER 。这个名称在公式 “TRIGGER==1” 中也有。

    如果 GUI 升级了，就会去查看 TriggerPolarity 节点是否可用。而 TriggerPolarity 节点会去检查 IntSwissKnife，而 IntSwissKnife 又会根据 TriggerReg 节点的值去计算结果。

    兼容 DCAM 的 1394 相机的 BytesPerPacket 属性是 “暂时锁定属性”（ temporarily locked）的一个典型例子。用户可以改变相机的这个参数，仅当 PC 适配器的 DMA 未被设定为采集图像的时候。设定 DMA 的意思是，传输层查询相机的 BytesPerPacket 参数，并把这个参数设置到 DMA 。这个工作完成后，直到传输层释放 DMA 之后才能改变 BytesPerPacket 。在这之前，相机的这个参数必须被锁定。

    注意，相机本身没有办法知道 DMA 是否设置。因此，相机描述文件中 “普通的” 节点不能被用来控制 BytesPerPacket 的锁定状态。

    图 6 正在锁定一个特征

    GenApi 内的解决方案是提供一个浮动的 Boolean 型节点 TLParamsLocked（参见图 6）。BytesPerPacket 通过 pIsLocked 连接到这个节点。传输层（TL）需要通过更新 TLParasLocked 节点的值来反映其 DMA 状态。在设定 DMA 之前，它会通过令 TLParamsLocked 为 true 的方式来锁定相机参数（例如 BytesPerPacket ），在采集图像完成之后，它会把 TLParamsLocked 设置回 false 。改变 TLParamsLocked 节点会更新所有关联节点的锁定状态，例如 BytesPerPacket 节点。

    注意，为保证这种方式正常工作，TLParamsLocked 必须是标准的节点名，并且传输层必须有访问相机的 GenApi 接口的权限。另外，相机描述文件的设计者必须注意哪个参数要被传输层锁定。这个信息包含在传输层标准之中，例如 DCAM 规范，这个规范规定，在采集数据的时候每桢的包数和每个包的大小必须固定。

    “属性没有被实现”（ not implemented）的一个典型的例子是，同一个家族的某些相机有 Gamma 属性而有些则没有。如果相机有一个查询位（inquiry bit）来标识是否实现了 Gamma 属性，就可以为这个家族的所有相机维护一个相机描述文件。

    图 7 显示了 GenICam 如何处理这种情况。Gamma 属性节点有一个叫 pIsImplemented 的连接指向 GammaInq 节点，GammaInq 节点映射相机的查询位。通常把多个查询位合并到一个寄存器里。为了取得这些位，要使用 MaskedIntReg 节点类型。这个类型有点像 IntReg 节点，但是，你可以像查询整数一样取查询想要的一个或一组连续的位。

图 7 检查是否实现了一个功能

参考

GenIcam标准（一）
GenIcam标准（二）
GenIcam标准（三）
GenIcam标准（四）
GenIcam标准（五）
GenIcam标准（六）

GenIcam标准介绍

---

GenIcam标准（一）
GenIcam标准（二）
GenIcam标准（三）
GenIcam标准（四）
GenIcam标准（五）
GenIcam标准（六）

   
 

☆