|
Common Vision Blox 15.0
|
|
|
Common Vision Blox 15.0
|
Common Vision Blox Tool
 C-Style |  C++ |  .Net API (C#, VB, F#) |  Python |
| CVGevServer.dll | Cvb::GevServer | Stemmer.Cvb.GevServer | cvb.gevserver |
The Common Vision Blox GigE Vision Server (CVB GEV Server) presents any CVB image source, like a frame grabber or Firewire camera, as a GigE Vision camera.
It utilizes the CVB Filter Driver which is also used for acquiring images for high performance image streaming within the GenICam.vin. Using the CVB GEV Server can be as simple as assigning an image source and starting it. The tool takes care of the rest. But if you wish, you also have the possibility to fine-tune its behavior from being able to do image preprocessing up to defining your custom GenICamTM GenApi features.
With the latter you can easily remote control the PC and hardware on which the CVB GEV Server runs. This is done programmatically – there is no need to learn XML or the GenICamTM GenApi description format as the features are generated automatically. CVB uses the GenICam.vin in conjunction with the high performance Filter Driver which is also used for all other GigE Vision cameras. As with all other CVB tools the CVB GEV Server needs the Image Manager to be installed and licensed. Two different licenses for the CVB GEV Server exist:
If no license is provided the CVB GEV Server runs in demo mode. The demo mode resembles a Multicast License limited to a total transfer volume of 5000 frames.
GEVServer applications are installed in %CVB%Tutorial/GEVServer.
First of all the terms and definitions are shortly introduced along with links for further reading. After that three large sections about
follow.
First a few words about the names and acronyms used in this documentation.
As the name of this tool implies, the CVB GigE Vision™ Server is a server. The naming comes from networks where a server provides a service. The service in this case is image transfer and device/camera control. A client connects to a server to consume the service. So the client here would be the software receiving the image data and controlling the CVB GEV Server. The CVB GEV Server needs a network interface (NIC) to work on.
A physical NIC is normally one network card. One NIC is identified by its unique Media Access Control (MAC) address. A NIC needs to have at least one Internet Protocol (IP) address to be assigned to it with which the CVB GEV Server can be associated with. Every interface has a subnet mask assigned to it. This mask defines which IP addresses form one logical network.
By default only devices in the logical subnet can see each other. Especially the automatic GigE Vision™ device discovery only works in one subnet. To identify a service or an application based on an IP address a port number is used. Ports are managed by the CVB GEV Server library. When using the CVB GEV Server library the local endpoint which is the local IP address/port combination refers to the IP address/port of the server. The remote endpoint refers to a connected client.
GigE Vision™ is based on the User Datagram Protocol (UDP) which makes fast image data transfer possible. UDP itself is a connectionless protocol, but the GEV protocol adds connection state via a heart beat (timeout of the connection after a certain time without communication), access control (Control Channel Privilege) and data reliability (Resend-mechanism) without impairing the high transfer rates. For more information about the GigE Vision™ protocol and supported software and devices visit the Association for Advancing Automation website.
GigE Vision™ itself describes only the way data is transferred and the transfer and connection related camera controls. For the high level description of the camera's features and general camera control the GenICam™ standard is referenced. The aim of the GenICam™ standard is to provide a generic interface to multiple transport technologies.
Every GEV camera must describe its features via an XML description which is then used by the GenICam™ GenApi to provide a high level feature interface. For more information about GenICam™ and its modules see https://www.genicam.org. The CVB GEV Server takes care of both the GEV protocol handling and the GenICam™ GenApi description and feature handling.
A logical interface for the server is an IP address. One physical network interface card (NIC) can have multiple IP addresses assigned to it. To be compliant to the GigE Vision protocol there can be only one CVB GEV Server instance per IP address.
If more than one instance is needed on one NIC, assign multiple IP addresses to it. See your operating system manual for a description on how to assign IP addresses to a NIC. To make the enumeration of the available logical interfaces easier in your application the CVB GEV Server library provides InterfaceList functions which provide IP addresses, subnet masks and MAC addresses of the available interfaces the CVB GEV Server can use.
A CVB GEV Server instance acts as one GEV camera using one NIC. One instance can send one image stream. Meaning that one server can acquire data from one image source and send it via the network. Following are sections explaining several aspects of the CVB GEV Server from setup to acquisition. Adding or modifying GenICam™ GenApi Features is explained in the chapter GenICam™ Features.
On the client side the CVB GEV Server will identify itself as the STEMMERIMAGING CVB GEV Server.
The Device ID format is as follows:
S{dongle-number}:{IP address}
(The term in curly brackets is replaced by the value as a hexadecimal number.)
For example for a server on 192.168.1.128/CVB dongle number 999 the Device ID is: “S3E7:C0A80180”
Normally GigE Vision™ devices use the MAC address as their Device ID to uniquely identify themselves. This is not possible on PC based systems as there can be multiple IP address assigned to one network interface. Thus in this case different CVB GEV Server instances would use the same ID which would lead to errors in opening/managing the devices. Therefore the device ID is a combination of the used dongle number (unique for the system except development/test systems) and the used IP address.
After starting the server the configuration can not be changed until the server is stopped again. This means that the image dimensions (width, height and color format) and available GenICam™ Features are fixed. What that means for the GenICam™ Features is explained in detail in the GenICam™ Features chapter. The server which is now in the Open Connection state is waiting for a connection.
As soon as a client connects the server goes to the Connected state. There is always only one controlling client to which the acquisition control is transferred to. As long as the connection exists no other client can connect to the server. Normally that means that other clients do not have read or write access. Depending on the access mode (GEV control channel privilege – CCP) other clients may have read access to the server which is very helpful for multicast scenarios. But there is always only one controlling client which has write access. When the client starts the acquisition the server state changes to Acquiring.
Depending on the acquisition mode the server then delivers images via the GEV stream to the client. This is done until the acquisition is stopped. If a client disconnects while an acquisition is running, first the acquisition state is revoked and then the connected state. A server can not be in acquisition state while being disconnected. As the acquisition and connection control is transferred to the client from the point on where the server is started, the server application is notified about the state changes by callback functions (C interface) or events (.NET interface).
The transfer driver is referred to as the driver type in the CVB GEV Server interface. It defines which driver is used to stream images to the client. The two possibilities are:
Filter Driver
This is the default driver to be used. It yields the best performance and lower CPU load for transfers to a remote PC.
Socket Driver
If you want to use the CVB GEV Server on the same PC where your client application is running you can not use the Filter Driver, because the operating system redirects the packets in the IP stack before they reach the Filter Driver.
To be able to acquire images, use the Socket Driver both in the server and the client application.
If installed, the CVB GEV Server uses the Filter Driver by default. If not, it automatically falls back to the Socket Driver. The driver type is specified when the server instance is created and can not be changed afterwards.
Depending on the image source provided and the level of control which is needed a different acquisition mode is used. The acquisition mode defines whether the CVB GEV Server library or the server application handles the image acquisition.
In this acquisition mode the server application needs to do no extra work.
The acquisition/grab is handled completely by the CVB GEV Server library. This mode is only available (and is set automatically) if an image source with any grabber interface is set to the server. In this mode a separate grab thread is started as soon as the client starts the acquisition. On each newly acquired image a callback (C interface)/event (.NET interface) is fired which enables the application to do image preprocessing before the image is sent.
All kinds of preprocessing can be done as long as the image dimensions (width, height and color format) are preserved. Only CVB images from the image source set in the configuration phase can be sent this way, but in place preprocessing can be done as described above. The Send functions do not work in this mode.
When this acquisition mode is set the server application decides when an image is sent to the client.
This mode is available for all image objects set to the server. It is set automatically if an image source without a grab interface is set to the server. This mode is useful if the server needs to control the timing for sending images or if images from multiple sources are to be streamed over one CVB GEV Server connection. The images sent via the connection need to be compatible with the image set to the server in the configuration phase. Compatible means that they have the same dimensions (width, height and color format) as the configured image.
This acquisition mode is set when the server instance is created and no image is set.
Even though it is possible to start the server with no image assigned this mode is not GigE Vision™ compliant. A compliant device needs to have at least one stream channel. Thus many compliant clients will refuse to communicate with such a server instance. If a server is started in this mode only the connection related features are available, but no streaming related features. Of course any other GenICam™ Feature can be added and used to create a simple remote control application.
Most setups will use a unicast connection between one client PC which acquires images and one server PC which sends images. The server gets its images either from disk or from another source like a IEEE 1394 camera.
In this scenario there is a one-to-one relationship between server and client. The client controls the server and receives the image data. Normally the Control Channel Privileges in this topology are set to exclusive, which means that only the controlling client has read and write access to the server. With GigE Vision™ there is always only one controlling client. That means that even in a multicast scenario there is only one client PC which holds the control connection. For the next paragraphs a basic knowledge of multicast technologies is needed.
In the graphic we have one controlling client which controls the server and two other clients, called display clients, which only receive the data. Each client has at least to set-up the image acquisition logic and join a multicast group. The group handling and transfer is handled by a multicast capable switch in the network. The clients join a multicast group to receive image data and the controlling client sets the multicast group IP address in the server. Normally the display clients also have a read-only control connection to the server to be able to read e.g. the image format. Therefore the Control Channel Privilege is set to “Control” which enables the controlling client to have full read/write access and other clients to have read-only access. The CVB GenICam.vin supports from these multicast scenarios the read-only control flavor. For additional information on multicast scenarios regarding recommended hardware and hardware/software setup please contact your local Common Vision Blox distributor.
The CVB GEV Server provides an interface to create and modify GenICam™ GenApi Features presented to the client. This chapter gives an instruction how to work with these features and how they can be accessed by an application using the CVB GigE Vision Server library.
A device like a camera or this server can make all its features known and accessible via the GenICam™ GenApi. Each device provides an XML description which maps high level features like a shutter time to a register space representation. The register space can be visualized as linear memory. Each logical register has an address and a size. For GigE Vision™ the register access is four byte aligned. That means that a register is at least four bytes in size and all memory access has to be aligned to four bytes (address and size). A read of three bytes from address 0002 would be rejected by the protocol. A read of four bytes from address 0008 would be valid. The content of the memory is interpreted by the GenApi.
On the client side a GenApi implementation like the CVGenApi from CVB reads that XML description and makes the described features accessible. Instead of writing an arbitrary value to some register address an application can query the shutter value and set its value in a predefined unit, e.g. in microseconds. In the GenApi terminology features, like gain or shutter, are represented as nodes in a node map. The node map makes all nodes accessible via a unique node name – meaning that a feature node can be obtained from the map by using a qualified node name.
Not all nodes are meant to be publicly accessible as features but are only there as helper or transformation nodes. Every node has at least one specific interface like IInteger which defines its data type and available properties. Some nodes have multiple interfaces like the IntReg node which is derived from IInteger and IRegister. A feature node for the public interface can be for example the Gain feature or the ModelName. A helper node might calculate the maximal possible width of an AOI depending on the sensor size and the current offset.
Features in the CVB GenApi Grid:
But feature nodes do not only have values, they also have properties which give more information about the feature like a descriptive text or value ranges:
Some nodes are directly linked to the memory of the register map and contain the name Reg or Register in their interface name. Other nodes are floating, meaning that they are constants or helper nodes without a value in the device. These floating nodes may be linked to other nodes by references in order to refine other values. References can be set for example for the value itself or the valid maximal value. A detailed description of the features can be found in the Available Feature Types section. Features which are not directly linked to a register (non-register nodes) are called floating nodes. In this document nodes that also do not reference a register node for its value are called fully floating. A reference does not need to be direct. Multiple compatible nodes might be in between. Fully floating nodes act as constants or calculation nodes for e.g. selectors/arrays.
Every node has a common set of attributes and most nodes have special attributes. This section describes important attributes which are necessary for understanding the following sections. A complete listing and explanations can be found in the Feature Interfaces section.
Every node has an access mode. A node can be:
| Not Implemented (NI) | This means that the XML description is designed for a family of devices, but this device does not support that feature. As long as this device is used this feature will never be available. Thus every read and write operation on a feature will result in an error. Generally user interfaces do not display these features. |
| Not Available (NA) | These features are implemented in a device, but currently not available because of the device state. The StartAcquisition command is for example not available when the acquisition is running. Every read and write operation on a feature will result in an error. User interfaces show this feature but will disable it. |
| Write Only (WO) | Mostly used with commands which do not have auto-reset behavior. The StartAcquisition command is write only as the operation normally is manually stopped by the client. A one-push white-balance for example can also be made readable to enable the client to wait until the operation has finished. Read operations on a write only feature will result in an error. |
| Read Only (RO) | Read only features may be status information or currently not writable because of the device state. If a camera is acquiring and sending image date the payload size, which is the overall size of the transferred data per frame, must not change. Thus features like color format are then read only. Write operations on a read only feature will result in an error. |
| Readable and Writeable (RW) | Provides full access on a feature which will change the state or an attribute in the device. |
The access modes that can be set directly to a node are RW, RO and WO. Only register nodes have an access mode. All nodes referencing these nodes will inherit the access right of that node. If a node wants to limit the access on a feature it can use the imposed access mode. For dynamic changes of the access mode to Not Available (IsAvailable node) or Not Implemented (IsImplemented node) references can be set to other nodes.
To reduce the load on the transfer medium and to improve the response time GenApi libraries cache values.
Caching takes into account that some values are only set by the client and need not be reread every time. Caching is only available on register nodes. Caching modes are:
| No | No cache is used and every read will request the information from the remote device. |
| WriteThrough | Means that every write will update the cache and the next read will be returned from the cache. |
| WriteAround | In this case a write will invalidate the cache and the next read operation will fill it. Subsequent reads will read from the cache until the next write operation. This is useful for registers which have a irregular stepping or where the value is adjusted on each write. If the cache of a node needs to be invalidated due to a change in another node, this can be expressed by the Invalidator list. Every value change of one of the listed features will invalidate the cache of the node holding the list. |
All nodes reside in a namespace.
The GenApi defines the standard and the custom namespace. The CVB GEV Server adds another namespace: private. They are used as follows:
| Standard | Only features described in the GenICam™ Standard Features Naming Convention (SFNC) document reside in this namespace. The standard document describes the data types and behavior of the features and can be found on the http://www.GenICam.org web site. All features in that namespace must comply with this document. |
| Custom | Only features described in the GenICam™ Standard Features Naming Convention (SFNC) document reside in this namespace. The standard document describes the data types and behavior of the features and can be found on the http://www.GenICam.org web site. All features in that namespace must comply with this document. |
| Private (CVB GEV Server only) | Private nodes are not put into the XML description. Private nodes are useful for register representations which are e.g. accessed via Selectors (see below) and have variable base addresses which need to be backed by physical storage. Also features used to store internal information which is not publicly visible can reside here. |
Integer and Enumeration nodes can play a special role: they can act as selectors.
Selectors enable indexed access on other features to use them e.g. as arrays. The selector node holds a list of features they 'select'. The selected feature's value depends on the selector. An example would be a LUT where the selector would be the LUT index and the selected node would be the LUT value for that index. Depending on the LUT index a different value in the LUT would be accessed by the LUT value. Often IntSwissKnife nodes are used for the selected nodes register addresses to map the value to different points in the register map.
Features can be very simple like adjusting the shutter time or so complex that wrong settings will block other camera features.
To reflect the complexity of a feature the visibility is used. Every node has a specific visibility defined as follows:
| Beginner | A simple feature which can be used easily. |
| Expert | More complex features which require more in-depth knowledge of the camera or transport technology. |
| Guru | Very complex features which require exact knowledge about that specific device or transport technology. Wrong settings can impair the functionality of the device. |
| Invisible | Helper node which should not be used directly. |
To provide complete coverage of the necessary GenApi Features for a GigE Vision™ TM device over 150 feature nodes are needed.
Also a lot of inter-node connections and dependencies have to be taken care of. And of course the register layout has to be maintained where the features' memory is located in to match the XML description. Thus a device designer has to keep his register layout in sync with the XML description. Luckily all this work is done by the CVB GEV Server library automatically. Everything that is needed to connect to the CVB GEV Server and to stream image data is provided. So only the application specific custom features need to be provided. If desired the CVB GEV Server automatically assigns register addresses to new features.
After all needed features are added the CVB GEV Server library dynamically generates the GenApi XML description and makes it accessible to the client via the GEV protocol. In addition to the normal interface of the GenApi libraries like the CVGenApi library of CVB the CVB GEV Server provides functions to configure the GenApi nodes. Configurations range from setting the help text via the Description property up to connecting the value of a feature with another node. Normally GenApi libraries cache some of the values to reduce the load on the network.
As the feature access is local for the server no values are cached and the application has access to the actual values. Also the access rights like read-only are not checked to enable full control on all the register values for the device. For the client the access rights are of course checked to guarantee the integrity of your feature values. It is recommended to only change the values of the nodes which you created and leave the management of the acquisition and GEV related nodes to the server. To be able to react to client access on the nodes, callback functions (C interface)/events (.NET interface) inform about read and write access. In these events the value may be modified if needed.
Depending on the cache mode and the GenApi library used in the client not every read operation might be visible in the server. Only access to the local register map will result in a read notification. When a new node is created it is not associated with a server. This allows a more flexible implementation especially if you use multiple server instances in one application. But as long as it is not added to a server's node map no reference to other nodes or actual values can be set. Only local properties like the description or display name are settable. For most purposes it is good practice to add a node to a server as soon as it is created. All attributes and values of the nodes can be modified through the public interface of the CVB GEV Server library.
Depending on the state, configuration or running, some restrictions apply. For example when the server is running no changes in the node attributes can be made as this information can not be transferred to the clients because this is done when a client connects to the server. Also no value set access is allowed on fully floating nodes as changes to these nodes can not be communicated to the clients. Value changes on fully floating nodes before the server is started set the initial value which is written in the XML description. With that mechanism constants or specific startup values can be defined.
Currently the following node types are available in the CVB GEV Server.
For a detailed description on the interfaces and dependencies see the Feature Interfaces section.
Boolean nodes are floating value nodes which can reference an IInteger node for its value.
The Boolean node has an OnValue and an OffValue. When the Value is set to true the OnValue is written; if set to false the OffValue is written. All values of the referenced IInteger that differ from the OffValue are treated as true in a get operation. These nodes present a simple Boolean interface and are useful for mapping arbitrary values to true and false. In contrast to a Command node Boolean nodes represent a state and do not normally start an action.
The interface of this node is the IBoolean interface.
A Category node is useful to group features and is normally only used in user interfaces.
A Category node does not have a value of its own and is thus fully floating. But it holds a list of nodes which form the members of the category. Any node can be a member of a category; even other categories. With that hierarchies of sub-categories can be formed. Every feature that should be visible in a graphical user interface must be member of a special category called Root. It is recommended that the direct children of the Root category are also categories. If possible these first level sub-categories should follow the main categories of the GenICam Standard Features Naming Convention document.
The interface of this node is the ICategory interface.
For submitting commands the floating Command value nodes are used.
A Command node can reference other IInteger nodes for the command's execute value and the value to write. In contrast to the Boolean nodes commands are used for prolonged actions that are executed asynchronously.
Every time the command is executed the CommandValue is written to a referenced IInteger node.
If the command action automatically terminates, like a one-push white-balance, Command nodes are also readable.
The current status can then be queried with the IsDone property.
This property returns true as soon as the referenced IInteger value is unequal to the CommandValue which is the signal that the operation has finished (called auto-reset or self-clearing commands). Commands which are not self-clearing normally are write-only like the AcquisitionStart command.
The interface of this node is the ICommand interface.
If a predefined set of symbolic (string) values is needed which are mapped to an integer number Enumeration nodes are used.
The Enumeration is a floating node which can reference an IInteger node for the indexed value. Also EnumEntry nodes are needed to map a symbolic value to an integer value. An Enumeration node holds a list of all possible EnumEntry nodes. Every time the value is set in an Enumeration the corresponding index value is written to the referenced IInteger value node. A read from the referenced IInteger is translated to the EnumEntry accordingly. If the value can not be mapped to an EnumEntry an error is returned. Although an Enumeration node accepts integer and symbolic values for its value it is recommended to only use the symbolic values. The symbolics are defined in the product's documentation or in the GenICam Standard Features Naming Convention document where the numeric indices may vary from device to device or vendor to vendor.
The interfaces of these nodes are IEnumeration and IEnumEntry.
The Integer value nodes provide access to 64 bit signed integer variables.
The Integer node is a floating node with definable maximum, minimum and increment (stepping or granularity) parameters. IntReg nodes are registers which are interpreted as integer values with a maximum and minimum based on the register size. Integer nodes can reference other IInteger nodes for their value, maximum, minimum and increment. IntReg nodes can have no reference for these attributes but map their value directly to the register map. IntReg nodes though can be signed or unsigned to limit their value range accordingly. 64 bit unsigned integers are problematic though as the GenApi library interfaces uses signed 64 bit integers. If a restriction on the value range is needed on an IntReg node an Integer node can be used with the configured range limitation referencing the IntReg node as its value.
The interfaces of these nodes are IIntegerNode and IIntReg.
To perform mathematical computations on the client side SwissKnife nodes are used.
The floating IntSwissKnife value node uses 64 bit signed integer arithmetic meaning that after each computation in a formula a floor operation is done which removes all digits after the decimal point. The computation 2 * (3 / 2) results in 2 not 3!
A SwissKnife node holds a number of variables which are references to other nodes. In case of the IntSwissKnife node these are IInteger nodes. As soon as the value is read from a SwissKnife node the Formula is evaluated and the referenced variables are read. SwissKnife nodes only perform computations and thus are read-only. IntSwissKnife support decimal and hexadecimal numbers in their formulas. Hexadecimal numbers are prefixed with 0x. 42 is the decimal 42; 0x42 would evaluate to the decimal number 66. For logical operations everything that is not 0 is treated as true. IntSwissKnife nodes support the following operations in their formulae:
| (, ) | brackets for grouping/overriding operator precedence: 3 * (2 + 3) = 15 |
| +, -, *, / | addition, subtraction, multiplication, division |
| % | remainder: 7 4 = 3 |
| ** | power: 2 ** 3 = 8 |
| &, |, ^, ~ | bitwise AND, OR, XOR, NOT: 2 | 1 = 3 |
| &&, || | logical AND, OR |
| <>, =, >, <, <=, >= | logical UNEQUAL, EQUAL, GREATER, LESS, LESS OR EQUAL, GREATER OR EQUAL: 3 >= 2 = 1 or 1 <> 1 = 0 |
| <<, >> | shift left, shift right: 1 << 2 = 4 |
| ? : | conditional operator <condition> ? <true> : <false>: (2 > 3) ? 1 : 2 = 2 |
| SGN | Signum function (-1 if value < 0; 0 if value = 0; 1 if value > 0): SGN(42) = 1 |
| NEG | Negative function: NEG(-42) = 42 |
SwissKnife nodes are often used to calculate base addresses of selected (see Selector nodes) nodes or to determine dynamic range limitations (e.g. on AOIs). An IntSwissKnife node, although supporting the IInteger interface, can not act as a selector as it is always read-only.
The interface of this node is the IIntSwissKnife interface.
ASCII strings are represented by StringReg nodes. The GenApi standard 1.0 does not define floating String nodes. All strings are backed in the register map. GigE Vision™ restricts the string length to be a multiple of four and strings must be saved zero-terminated. That means that in a StringReg node with the length of eight bytes up to seven ASCII characters can be stored (seven characters plus the zero-termination).
The interface of this node is the IStringReg interface.
Every node implements one or several interfaces. If one interface inherits from another it adds its new functionality to the functionality of its parent(s).
The description of the interfaces is for the CVB GEV Server library. This is not a pure GenICam GenApi library interface as additional operations are necessary to configure the nodes. Thus the presented interfaces vary from the ones introduced in the standard and new ones are added. The interfaces defined below are written in pseudo code. How the attributes and operations are accessed depends on the programming language being used. Attributes or properties are presented in the following form:
{name} : {data type} (possible access get and/or set)
Operations or functions use the following form:
{name}({parameter name} : {Parameter Type}, ...) : {return data type}
A data type in angular brackets is a choice and thus may only contain one of the entries:
<{data type} | ...>
A data type with square brackets means a list of that type. A list provides indexed access, add (tail) and remove operations:
{data type}[]
Represents a Boolean value (true or false). This node implements the following interfaces:
The following attributes are available:
| Attribute/Operation | Description |
|---|---|
| OffValue : int64 (get/set) | Numeric value set to the ValueConfig choice if false is set to Value. Default value is an int64 variable with the value 0. Set operation is only possible as long as the server is not running. |
| OnValue : int64 (get/set) | Numeric value set to the ValueConfig choice if true is set to Value. Default value is an int64 variable with the value 1. Set operation is only possible as long as the server is not running. |
| Value : boolean (get/set) | Value access. If set, the OnValue (true) or OffValue (false) is assigned to the ValueConfig choice. If read all values of the ValueConfig except OffValue are true. Set operations result in an error if the server is running and this node is fully floating. |
| ValueConfig : <IInteger | int64> (get/set) | Defines whether this is a fully floating node and an int64 variable is used or the Value access is referenced to the set IInteger node. By default an int64 variable is set with the value 0. Set operation is only possible as long as the server is not running. |
Categories group other nodes. A category implements the following interface(s):
Only one attribute is available:
| Attribute/Operation | Description |
|---|---|
| Nodes : INode[] (get) | Contains all the nodes which are grouped by the category. Default value is an empty list. List modification is only possible as long as the server is not running. |
Command executes an action and provides the following interface(s):
The following attributes and operations are available:
| Attribute/Operation | Description |
|---|---|
| Execute() : void | Executes the command by writing the CommandValueConfig value to the ValueConfig choice. Set operations will result in an error if the server is running and this is a fully floating node |
| CommandValueConfig : <IInteger | int64> (get/set) | The value to write on Execute() calls and to compare against in IsDone reads. Can be either an IInteger node whose value is read for each operation or a constant. By default an int64 variable is set with the value 0. Set operation is only possible as long as the server is not running. |
| IsDone : boolean (get) | Checks whether the operation is done by comparing the current ValueConfig value against CommandValueConfig. If both are different this attribute is true. |
| PollingTime : int64 (get/set) | Hint for the client application in which time interval (ms) the IsDone attribute is to be reread. A negative value indicates that no polling is to be done. Make sure that if polling is used that the caching mode of the used registers is set to No. By default the polling time is -1. Set operation is only possible as long as the server is not running. |
| ValueConfig : <IInteger | int64> (get/set) | Defines whether this is a fully floating node and an int64 variable is used or the Execute() and IsDone access is referenced to the set IInteger node. By default an int64 variable is set with the value 0. Set operation is only possible as long as the server is not running. |
Enumeration entries are only used in conjunctions with IEnumeration nodes and map a symbolic string to an integer index. It implements the following interface(s):
The following attributes are available:
| Attribute/Operation | Description |
|---|---|
| Symbolic : string (get/set) | Symbolic string representation of the entry. The symbolic may consist of letters (A-Z and a-z) and numbers (0-9) and must start with a letter. By default the symbolic is empty, but must be set for valid behavior. Set operation is only possible as long as the server is not running. |
| Value : int64 (get/set) | Numeric value of the entry. By default it is 0. Set operation is only possible as long as the server is not running. |
If symbolic names are needed enumeration nodes are used. The following interfaces are available:
The following attributes can be accessed:
| Attribute/Operation | Description |
|---|---|
| Entries : IEnumEntry[] (get) | Contains all the enumeration entry nodes which are available in this enumeration. Default value is an empty list, but it needs to be filled for correct behavior. List modification is only possible as long as the server is not running. |
| Value : <string | int64> (get/set) | The value can either be the symbolic (string) or the numerical (int64) value. Though both are possible it is recommended to only use the symbolic value as only this one is normally standardized or documented. If the server is running and this is a fully floating node set operations will result in an error. |
| ValueConfig : <IInteger | int64> (get/set) | Defines whether this is a fully floating node and an int64 variable is used or the Value access is referenced to the set IInteger node.By default an int64 variable is set with the value 0. Set operation is only possible as long as the server is not running. |
Base interface of all nodes that are treated as integers. The following interfaces are provided:
This interface is special as it does not represent a node but a family of nodes. The actual integer node is represented by the IIntegerNode interface. The following attributes are available:
| Attribute/Operation | Description |
|---|---|
| MaxValue : int64 (get) | Gets the maximal allowed value for this integer. |
| MinValue : int64 (get) | Gets the minimal allowed value for this integer. |
| Increment : int64 (get) | Gets the increment which defines the stepping of the Value. |
| Representation : enumeration (get/set) | Gets the representation for a graphical user interface. Possible values are:
|
| Value : int64 (get/set) | Gets or sets the current value of this node as an integer. If the server is running and this is a fully floating node, set operations will result in an error. |
Integer nodes represent integer values and implement the following interfaces:
Additionally to the attributes of the inherited interfaces the following attributes are available:
| Attribute/Operation | Description |
|---|---|
| MaxConfig : <IInteger | int64> (get/set) | The value to be used as maximum. Can be an integer variable or an IInteger node which will be queried for its value. By default an int64 variable is set with the value 2^63-1 (signed int64). |
| MinConfig : <IInteger | int64> (get/set) | The value to be used as minimum. Can be an integer variable or an IInteger node which will be queried for its value. By default an int64 variable is set with the value -2^63 (signed int64). |
| IncrementConfig : <IInteger | int64> (get/set) | The value to be used as the increment. Can be an integer variable or an IInteger node which will be queried for its value. By default an int64 variable is set with the value 1. |
| ValueConfig : <IInteger | int64> (get/set) | Defines whether this is a fully floating node and an int64 variable is used or the Value access is referenced to the set IInteger node. By default an int64 variable is set with the value 0. Set operation is only possible as long as the server is not running. |
Integer registers are backed directly in the register map. These nodes implement the following interfaces:
The following attribute is provided additionally:
| Attribute/Operation | Description |
|---|---|
| Signed : boolean (get/set) | Defines whether this register represents a signed integer (true) or an unsigned one (false). The default is signed. Set operation is only possible as long as the server is not running. |
If calculations are needed SwissKnife nodes are used. It implements the following interface(s):
As SwissKnife nodes are always read-only Value write operations always will report an error. Max and Min are default.
| Attribute/Operation | Description |
|---|---|
| Formula : string (get/set) | The formula to be evaluated on each Value query. Set all needed Variables prior to setting the formula as it will be validated for correctness. Missing variable declarations are treated as errors. Set operation is only possible as long as the server is not running. |
| Variables : string-IInteger-pair[] (get) | List containing variable name/IInteger pairs. On each formula evaluation all variable values are queried and then inserted. List modification is only possible as long as the server is not running. |
This is the top-level interface for all GenICam GenApi Feature nodes. All nodes present the following attributes:
| Attribute/Operation | Description |
|---|---|
| Alias : INode (get/set) | Optional reference to a node that represents the value of this node in a different manner. A graphical user interface could for instance display the alias node of Category node if the member nodes are hidden. If none is set, which is the default, no alias is available. Set operation is only possible as long as the server is not running. |
| Description : string (get/set) | A longer descriptive text (compared to the ToolTip) explaining the feature and the possible values in detail. Empty by default. Set operation is only possible as long as the server is not running. |
| DisplayName : string (get/set) | Generally the unique feature Name especially in conjunction with the Namespace is not easy to read in a graphical user interface. To have a human readable name even with spaces the display name can be used. If empty, which is the default, the Namespace abbreviation (Std or Cust), a double colon and the Name are used: e.g. Std::AcqStart. Set operation is only possible as long as the server is not running. |
| ImposedAccessMode : enumeration(get/set) | Normally only register nodes have an access mode. If the inherited access mode should be restricted this attribute can be used. Possible values are:
|
| IsAvailable : IInteger (get/set) | Optional reference to an IInteger node that defines whether this node is available or not. If the referenced IInteger value is unequal zero the configured access mode is used. If it is zero the access mode is set to not available (NA) and thus no read or write operations are allowed. If no node is referenced, which is the default, this node is always available. Set operation is only possible as long as the server is not running. |
| IsImplemented : IInteger (get/set) | Optional reference to an IInteger node that defines whether this node is implemented or not. If the referenced IInteger value is unequal zero the configured access mode is used. If it is zero the access mode is set to not implemented (NI) and thus no read or write operations are allowed. The value of the referenced IInteger should not change as long as the client is connected. If no node is referenced, which is the default, this node is always implemented. Set operation is only possible as long as the server is not running. |
| IsLocked : IInteger (get/set) | Optional reference to an IInteger node that defines whether this node is currently locked (read-only) or not. If the referenced IInteger value is unequal zero the configured access mode is used. If it is zero the access mode is set to read-only (RO) for RW nodes or not available (NA) for WO nodes. If no node is referenced, which is the default, this node is never locked. Set operation is only possible as long as the server is not running. |
| Name : string (get) | Unique name of the feature. A name may consist of letters (A-Z and a-z), the underscore '_' and numbers (0-9) and must start with a letter. The server uses this name to uniquely identify a feature and not the namespace/name combination. The name is given when a node is created. |
| Namespace : enumeration (get) | The namespace defines whether the feature is described in the GenICam Standard Features Naming Convention document (SFNC) or is a vendor’s custom feature. Possible values are:
|
| ToolTip : string (get/set) | A short descriptive text giving an overview about the feature. Empty by default. Set operation is only possible as long as the server is not running. |
| Visibility : enumeration (get/set) | Defines the complexity of the feature or if this is just a helper node which is not to be displayed. Possible values are:
|
Registers are directly backed by the register map and do not reference other value nodes. The implemented interfaces are:
Available attributes are:
| Attribute/Operation | Description |
|---|---|
| AccessMode : enumeration (get/set) | Defines the read and write access capability. Possible values are:
|
| Address : int64 (get) | Resulting address based on the sum of the constant from creating the register and the members of the AddressNodes list. GigE Vision™ uses a 32 bit address space and thus the 64 bit signed integer GenApi address space is sufficient. |
| AddressNodes : IInteger[] (get) | Additional IInteger nodes used for calculating dynamic addresses. When using dynamic addresses no address auto-assignment is supported. Also the registers will not create an actual memory representation in the register map. Use other registers in the Private namespace to create the memory representation. List modification is only possible as long as the server is not running. |
| CachingMode : enumeration (get/set) | Defines whether read access on the register will be cached and how it is cached if yes. Possible values are:
|
| InvalidatorNodes : INode[] (get) | List containing all nodes which, when changed, will invalidate the cache of this node. List modification is only possible as long as the server is not running. |
| Length : int64 (get) | The length of the register in bytes. This value is set when the register is created. |
| PollingTime : int64 (get/set) | Hint for the client application in which time interval (ms) the value is to be reread. A negative value indicates that no polling is to be done. Make sure that if polling is used that the CachingMode is set to No. By default the polling time is -1. Set operation is only possible as long as the server is not running. |
Selectors are value nodes which are used as the index of an array. The following interfaces are inherited:
The ISelector interface itself is not a node but is used by the Enumeration and Integer nodes.
Each selector provides the following attribute:
| Attribute/Operation | Description |
|---|---|
| SelectedNodes : INode[] (get) | List containing all nodes whose value depends on this nodes value. List modification is only possible as long as the server is not running. |
Represents a register map string. The following interfaces are inherited:
Each string register provides the following attribute:
| Attribute/Operation | Description |
|---|---|
| Value : string (get/set) | Value of the register as a string. |
Generic interface for all feature nodes which represent a value. The inherited interface is:
IValue interface is inherited by all nodes which have a gettable/settable value of any data type.
The following operations are provided:
| Attribute/Operation | Description |
|---|---|
| RegisterEvent(type : enumeration) : int64 | Registers a Read or Written event. The return value is the event ID used for unregistering the event. Multiple events can be registered on each node. The Read event is called before the answer is sent to the remote client to be able to update values on each read. The order in which multiple registered events are called is not defined. The Written event is called after the value has been written to the feature but before the acknowledge is sent. This enable notification on changes with the ability to modify the written value. |
| UnregisterEvent(type : enumeration, id : int64) : void | Unregisters a Read or Written event identified by the given ID. |
Every node map regardless of transport technology used has three mandatory nodes. Depending on the associated device there can be more mandatory nodes.
The Root category is the first node for a graphical user interface to access.
With this node it queries which nodes are available. Thus every node that should be publicly accessible must be in this category. Also it is recommended to only have Category nodes as the direct children of the Root category which resemble the names of the GenICam Standard Features Naming Convention document.
This integer node is used by the transport layer to lock all features which have an effect on the payload size.
The payload size is the overall frame size transferred by the camera. This is necessary to make sure that the preallocated buffers stay valid as long as streaming is in progress. Thus if you have a feature which must not be changed when the server is sending image data you can use the TLParamsLocked node in the IsLocked property. Locked features which are readable and writable become read-only. Write-only features become not available (e.g. Command nodes).
This node is listed here just for the sake of completeness as there is only limited access to it from the CVB GEV Server library.
A Port node is the link between a register node and the transport layer and thus the device. The Port node's interface provides the register map access. All the register/port handling is done automatically by the CVB GEV Server library.
Regarding the GenICam™ Feature interface it is very important to manage the versions of the device (CVB GEV Server) and the XML description correctly.
If this is not done properly it can happen that a software reads or writes the wrong memory in the register map because of mixed up descriptions. The main identification of the CVB GEV Server is the vendor and model name. To distinguish between different versions or instances of the tool the Device Version field is used. If you do not add your own custom features you do not need to change anything. Otherwise carry out the versioning as described in the next sections.
By default the CVB GEV Server uses as its device version its DLL version (e.g. 1.0.0.0). This is sufficient as long as the user does not add custom features. If custom features are added it is recommended to enter an additional user version which makes this instance with its feature set uniquely identifiable. If connection to instances with different feature sets of the CVB GEV Server are used different user versions must be assigned! Otherwise a read/write error will occur because of inconsistent register maps.
The user version can be set on the CVB GEV Server object either with the UserVersion property (.NET interface) or the GSSetInfoAsString function (C interface). The GenICam™ Registry, which stores XML description files in a data base on the client side, saves different XML sets for each device revision. Device revisions are identified by their version. The resulting version for the CVB GEV Server is the DLL version plus the user version, e.g. 1.0.0.0a or 1.0.0.0_BlobAnalyzer. Thus for the GenICam™ Registry these two CVB GEV Servers would be still the same device type but with independent and potentially different feature sets.
Dependent on the complete device version described in the previous section the XML version defines the state of the description itself.
For a certain family of CVB GEV Servers which is identified by the device version the versioning of the XML description can be done independently. That means that the XML version 1.0.0 for the device version 1.0.0.0 is different from the XML version 1.0.0 of the device version 1.0.0.0_BlobAnalyzer. The versions for the XML are to be given in a certain way:
| Major Version | A change in the major version indicates a change that is not backward compatible. If a change is necessary also define a new User Version for the CVB GEV Server instance to distinguish the incompatible instances. Use another version identifier in the User Version. '_BlobAnalyzerV2' for example. |
| Minor Version | Adds new features, but overall the XML description file is backward compatible. New features need to have a properly set IsImplemented node. |
| Sub-Minor Version | Bug fix change only without any changes in the public feature set. |
The CVB GEV Server library stores its configuration data and persistent state in the CVB GEV Server.cfg file.
This file is located in the Common Applications Data folder of your operating system:
{AllUsersProfile}\STEMMER IMAGING\Common Vision Blox
or simply the {CVBDATA} environment variable pointing to:
C:\ProgramData\STEMMER IMAGING\Common Vision Blox
The CVB GEV Server library supports monochrome images with up to 16 bits per pixel and RGB images with up to 8 bits per pixel.
Although the CVB GEV Server can work on every memory layout supported by CVB, certain layouts need to be converted internally. The transfer buffer expects the pixel data in a linear fashion pixel after pixel without gaps. For e.g. RGB images this would be RGBRGBRG... If the image data to be transferred does not resemble that format it has to be copied into that format by the CVB GEV Server. All this is done automatically but is paid with a sleight performance loss.
If possible use the filter driver as it minimizes the overhead of the normal Windows IP stack and reduces the CPU load significantly. Only use the Socket Driver if for example loopback transfer is needed.
On the receiving side larger packet sizes reduce the CPU load.
The same is true for the sender and thus the server side. The larger the packets the fewer packets need to be sent. This reduces the number of events to be processed and it improves the net transfer rate as fewer header data needs to be sent.
Applications using the CVB GEV Server library need at least full access rights in a firewall for the entire application.
Ports are requested dynamically from the system for streaming data and therefore a simple port rule would not be sufficient. Per application settings for a local firewall also introduce a significant performance penalty as the firewall still has to touch all the packets to check which is the sending/receiving application. It is recommended to use a dedicated network card for the image data transfer and disable the firewall for the whole interface. This imaging network should be physically separated from the normal company or communications network for security and performance reasons.
The CVB GEV Server.cfg file is an XML file. Near the top of the file is the Log element which contains the LogLevel and LogTarget elements. Possible log levels are:
| 0 | No Logging (default) |
| 1 | Log everything (information, warnings and errors) |
| 2 | Log only warnings and errors |
| 4 | Log only errors |
Possible log targets are:
| 0 | Console window (default) |
| 1 | File: The generated file will be located in the same directory as the CVB GEV Server.cfg and is named CVB GEV Server.log. New logs are appended to this file. |
To make the identification of several CVB GEV Server instances easier the User ID feature is implemented. The GigE Vision™ standard states that the value of this feature must be written to persistent memory. The persistent storage for the CVB GEV Server library is the hard disk. All settings specific to a CVB GEV Server instance are saved under its Device ID. If later an instance with the same device ID is opened the stored values are restored automatically.
It is recommended to use an Intel® PRO/1000 chipset.
As with the GenICam.vin installation several steps are necessary to optimize the send performance. It is recommended to use the latest driver for the network interface card (see your manufacturer's web-site).
1) Open your Network Properties Dialog (Start->Control Panel->Network Connections) and right click on the network connection used by the CVB GEV Server. Click the “Properties” entry from the context menu to get to the network configuration dialog (shown here: Windows XP).
2) Click on the “Configure” button to go to the hardware properties.
3) As an example a Intel® PRO/1000 network card is being used. Here select the “Advanced” tab on the property page. Increase the “Jumbo Frames” entry to the highest possible value.
4) Set the “Interrupt Moderation Rate” to “Extreme”.
5) Set the “Transmit Buffers” to the highest possible value.
This section provides answers to commonly asked questions and short examples on how to use certain aspects of the CVB GEV Server.
Additionally an MFC C++ example showing the C interface handling, a C# and VB.NET Windows™ Forms example showing the .NET interface are shipped with the CVB GigE Vision Server development resources. Generally use of the .NET interface is encouraged as it is object oriented and thus easier to work with. With the C interface the life-time management has to be done manually (CVB ref-counted objects which is significantly more error prone). If you debug an application using a running CVB GEV Server some topics deserve extra attention:
The GEV protocol uses a heartbeat mechanism to determine whether both parties are still connected and alive. By default the protocol's timeout is set to three seconds. In case a break point is hit the debugger will suspend all threads in the currently running process. As the CVB GEV Server library is loaded into this process its threads will also be suspended. This means that the server is not responding as long as the debugger waits for user input. The server will also not be able to answer the heartbeat packets and the connection will time out (the server becomes disconnected). To alleviate this problem increase the heartbeat timeout on the client side. With the CVB GenICam.vin this can be done in the ini-file. The drawback on that solution is that if one of the applications is stopped or not responding anymore the other side needs a longer time to adjust to the new state or also needs to be stopped.
As described in the Driver Type section of the Theory of Operation chapter loopback image transfer is only possible with the Socket Driver as the operating system redirects the network packets before they reach the Filter Driver.
If connections to different CVB GEV Servers with different feature sets is needed on one client PC different device versions must be used to properly separate the different versions.
See Device and XML Description Versions.
It is possible to stream image data from multiple image sources. These can be different grabbers or different preprocessing stages. This is possible as long as the image dimensions are compatible (same color format, width and height). To be able to use the different sources, assign the main vin-driver or create a dummy image via CreateGenericImage/CreateGenericImageDT. Then set the acquisition mode to manual. As soon as a client is connected and started the acquisition you can send arbitrary compatible images via the SendImage function.
If a GenICam Feature is to be used to update a client the polling time can be used. The easiest solution would be:
It is also possible to have readable and writeable nodes with pollable values. If you need to limit the value range you need to use a floating node for that. In that case many graphical user interfaces do not properly report the feature's poll status. Updates happen nonetheless.
When a node's value is read or written, it's access mode is not checked from the server's interface. The error for the value and attribute access is dependent on the state the CVB GEV Server is in:
Certain values need a node associated with a server's node map. If a value of a floating or register node needs to be set a connected register map is required. This requires a server node map which handles these connections and provides the memory. Also checks are done for reference assignments to make sure that both nodes reside in the same server. Changes that only affect the XML descriptions can be done even when the node is not assigned to a server. This includes the description, representation etc.
As soon as the server is running an XML description has been created so that clients are able to query and access the available features. Thus every feature configuration which would alter the XML description is not possible. That includes value changes of fully floating nodes as well as changes to the feature properties like descriptions or references. Register backed (non-floating) values can be changed though.
Check the caching mode. If this is not set to No the client will only query the cached value. If the polled register is referenced by a floating node many graphical user interfaces do not state that a value is polled. Updates should happen nonetheless.
If you want to use the CVB GEV Server on the same PC where your client application is running, you can not use the Filter Driver, because the operating system redirects the packets in the IP stack before they reach the Filter Driver. To be able to acquire images, use the Socket Driver both in the server and the client application.
1) Determine the NIC to be used:
2) Configure the Server with selecting the NIC and using the Socket Driver (loopback).
3) Open an Image Source (for example an *.emu file). Press Start.
4) Open a Client (e.g. GenICam Browser), search for available devices and select the CVGevServer Socket Driver.
5) Then, press the Grab button.
