Go to the documentation of this file.
00001 Roboception GenICam Convenience Layer
00002 =====================================
00004 This package combines the Roboception convenience layer for images with the
00005 GenICam reference implementation and a GigE Vision transport layer. It is a
00006 self contained package that permits configuration and image streaming of
00007 GenICam / GigE Vision 2.0 compatible cameras like the Roboception rc_visard.
00008 The API is based on C++ 11 and can be compiled under Linux and Windows.
00010 This package also provides some tools that can be called from the command line
00011 for discovering cameras, changing their configuration and streaming images.
00012 Although the tools are meant to be useful when working in a shell or in a
00013 script, their main purpose is to serve as example on how to use the API for
00014 reading and setting parameters, streaming and synchronizing images.
00016 API changes in version 2.0.0
00017 ----------------------------
00019 Version 2.0.0 introduced some API changes that require minor changes of
00020 programs that use the classes Buffer, Image and ImageList.
00022 An object of class Buffer can now represents a single buffer as well as a
00023 multipart buffer, depending on the availability of multipart support in the
00024 used GenTL producer and the GigE vision device. Multipart buffers can contain
00025 more than one image. For simplicity of the interface, non-multipart buffers are
00026 now treated like multipart buffers with just one image.
00028 For writing code that is able to support multipart, after grabbing the buffer,
00029 the number of parts must be requested with the method
00030 Buffer::getNumberOfParts() and a loop must be added to cycle over all parts.
00031 All methods that access image specific data have been extended by a second
00032 parameter for providing the 0 based part index. The following existing
00033 methods have been changed:
00035 - void    *Buffer::getBase(std::uint32_t part) const;
00036 - size_t   Buffer::getSize(std::uint32_t part) const;
00037 - size_t   Buffer::getWidth(std::uint32_t part) const;
00038 - size_t   Buffer::getHeight(std::uint32_t part) const;
00039 - size_t   Buffer::getXOffset(std::uint32_t part) const;
00040 - size_t   Buffer::getYOffset(std::uint32_t part) const;
00041 - size_t   Buffer::getXPadding(std::uint32_t part) const;
00042 - bool     Buffer::getImagePresent(std::uint32_t part) const;
00043 - uint64_t Buffer::getPixelFormat(std::uint32_t part) const;
00044 - uint64_t Buffer::getPixelFormatNamespace(std::uint32_t part) const;
00045 - size_t   Buffer::getDeliveredImageHeight(std::uint32_t part) const;
00046 -          Image::Image(const Buffer *buffer, std::uint32_t part);
00047 - void     ImageList::add(const Buffer *buffer, size_t part);
00049 Another important change is to use the new method Buffer::getGlobalBase() for
00050 getting the address used to connect a buffer with the nodemap for accessing
00051 chunk parameters instead of Buffer::getBase(). Other, new methods include:
00053 - void    *Buffer::getGlobalBase() const;
00054 - size_t   Buffer::getGlobalSize() const;
00055 - size_t   Buffer::getPartDataType(uint32_t part) const;
00056 - uint64_t Buffer::getPartSourceID(std::uint32_t part) const;
00058 Compiling and Installing
00059 ------------------------
00061 ### Linux
00063 Building follows the standard cmake build flow. Please make sure to set the
00064 install path *before* compiling. Otherwise it can happen that the transport
00065 layer is not found when calling the tools.
00067     cd <main-directory>
00068     mkdir build
00069     cd build
00070     cmake -DCMAKE_INSTALL_PREFIX=<install-directory> ..
00071     make
00072     make install
00074 ### Windows and Visual Studio
00076 Building is based on cmake. Therefore, cmake must be downloaded and installed
00077 according to the operating system from After
00078 starting the cmake-gui, the path to the rc_genicam_api source code directory
00079 as well as the build directory must be specified. It is common to choose
00080 a sub-directory of the source code directory and name it 'build' for the
00081 the temporary files that are created during the build process. After setting
00082 both paths, the 'Configure' button must be pressed. In the up-coming dialog,
00083 it can be chosen for which version of Visual Studio and which platform (e.g.
00084 Win64) the project files should be generated. The dialog is closed by pressing
00085 'Finish'.
00087 After configuration, the value of the key with the name `CMAKE_INSTALL_PREFIX`
00088 may be changed to an install directory. By default, the install directory is
00089 set to a path like `C:/Program Files/rc_genicam_api`. The 'Generate' button
00090 leads to creating the project file. Visual Studio can be opened with this
00091 project by pressing the 'Open Project' button.
00093 By default, a 'Debug' version will be compiled. This can be changed to 'Release'
00094 for compiling an optimized version. The package can then be created, e.g. by
00095 pressing 'F7'. For installing the compiled package, the 'INSTALL' target can be
00096 *created* in the project explorer.
00098 After installation, the install directory will contain three sub-directories.
00099 The 'bin' directory contains the tools, DLLs and the default transport layer
00100 including configuration. The 'include' and 'lib' sub-directories contain the
00101 headers and libraries for using the API in own programs.
00103 NOTE: For using the libraries in own projects, define the symbol
00104 `GENICAM_NO_AUTO_IMPLIB` in your project file to avoid linker problems with the
00105 GenICam libraries.
00107 Tools
00108 -----
00110 The tools do not offer a graphical user interface. They are meant to be called
00111 from a shell (e.g. Power Shell under Windows) or script and controlled by
00112 command line parameters. Calling the tools without any parameters prints a help
00113 text on the standard output.
00115 NOTE: If any tool returns the error `No transport layers found in path ...`,
00116 then read the section 'Transport Layer' below.
00118 ### gc_info
00120 Lists all available systems (i.e. transport layers), interfaces and devices
00121 with some information. If a device ID is given on the command line, then the
00122 complete GenICam nodemap with all parameters and their current values are
00123 listed.
00125 ```
00126 gc_info -h | -l | ([-o <xml-output-file>] [<interface-id>:]<device-id>[?<node>] [<key>=<value>] ...)
00128 Provides information about GenICam transport layers, interfaces and devices.
00130 Options: 
00131 -h   Prints help information and exits
00132 -l   List all all available devices on all interfaces
00133 -o   Filename to store XML description from specified device
00135 Parameters:
00136 <interface-id> Optional GenICam ID of interface for connecting to the device
00137 <device-id>    GenICam device ID, serial number or user defined name of device
00138 <node>         Optional name of category or parameter to be reported
00139 <key>=<value>  Optional GenICam parameters to be changed in the given order before reporting
00140 ```
00142 ### gc_config
00144 Can be used to list network specific information of GenICam compatible GigE
00145 Vision 2 cameras. The network settings as well as all other parameters
00146 provided via GenICam can be changed.
00148 ```
00149 gc_config -h | -l | ([<interface-id>:]<device-id> <options> ...)
00151 Configuration of a GigE Vision device via GenICam.
00153 -h             Prints help information and exits
00154 -l             Lists all available GigE Vision devices
00156 Parameters:
00157 <interface-id> Optional GenICam ID of interface for connecting to the device
00158 <device-id>    GenICam device ID, serial number or user defined name of device
00160 Options:
00161 -n <id>        Set user defined id
00162 -d 1|0         Switch DHCP on or off
00163 -p 1|0         Switch persistent IP on or off
00164 -t 1|0         Switch precision time protocol (ptp) on or off
00165 -i <ip>        Set persistent IP address
00166 -s <ip>        Set subnet mask for persistent IP address
00167 -g <ip>        Set default gateway for persistent IP address
00168 --iponly       Show current IP of device instead of full summary
00169 <key>=<value>  Optional GenICam parameters to be changed in the given order
00170 ```
00172 ### gc_stream
00174 This tool shows how to configure and stream images from a camera. GenICam
00175 features can be configured directly from the command line. Images will be
00176 stored in PGM or PPM format, depending on the image format.
00178 Streams of the Roboception rc_visard can be enabled or disabled directly on
00179 the command line by setting the appropriate GenICam parameters. The following
00180 command enables intensity images, disables disparity images and stores 10
00181 images:
00183 ```
00184 gc_stream <ID> ComponentSelector=Intensity ComponentEnable=1 ComponentSelector=Disparity ComponentEnable=0 n=10
00185 ```
00187 NOTE: Many image viewers can display PGM and PPM format. The sv tool of cvkit
00188 ( can also be used.
00190 ```
00191 gc_stream -h | [-t] [<interface-id>:]<device-id> [n=<n>] [<key>=<value>] ...
00193 Stores images from the specified device after applying the given optional GenICam parameters.
00195 Options:
00196 -h   Prints help information and exits
00197 -t   Testmode, which does not store images and provides extended statistics
00199 Parameters:
00200 <interface-id> Optional GenICam ID of interface for connecting to the device
00201 <device-id>    GenICam device ID, serial number or user defined name of device
00202 n=<n>          Optional number of images to be received (default is 1)
00203 <key>=<value>  Optional GenICam parameters to be changed in the given order
00204 ```
00206 ### gc_pointcloud
00208 This tool streams the left image, disparity, confidence and error from a
00209 Roboception rc_visard sensor. It takes the first set of time synchronous
00210 images, computes a colored point cloud and stores it in PLY ASCII format.
00211 This tool demonstrates how to synchronize different images according to
00212 their timestamps.
00214 NOTE: PLY is a standard format for scanned 3D data that can be read by many
00215 programs. The plyv tool of cvkit ( can
00216 also be used for visualization.
00218 ```
00219 gc_pointcloud -h | [-o <output-filename>] [<interface-id>:]<device-id>
00221 Gets the first synchronized image set of the Roboception rc_visard, consisting
00222 of left, disparity, confidence and error image, creates a point cloud and
00223 stores it in ply ascii format.
00225 Options:
00226 -h        Prints help information and exits
00227 -o <file> Set name of output file (default is 'rc_visard_<timestamp>.ply')
00229 Parameters:
00230 <interface-id> Optional GenICam ID of interface for connecting to the device
00231 <device-id>    GenICam device ID, serial number or user defined name of device
00232 ```
00234 Device ID
00235 ---------
00237 There are multiple ways of specifying an ID to identify a device.
00239 1. The serial number of the device serves as ID.
00240    Example: `02911931`
00242 2. The given ID can also be a user defined name. The user defined name is set
00243    to `rc_visard` by default and can be changed with:
00245        gc_config <ID> -n <user-defined-name>
00247    This way of identifying a device can fail if there is more than one device
00248    with the same name. No device is returned in this case.
00250    If the user defined name contains one or more colons, it must be preceded by
00251    a colon (e.g. `:my:name`) or an interface ID (see below).
00253 3. The device ID of the GenTL producer (see `Transport Layer` section below)
00254    may also be used. This ID is unique, but not persistent as it depends on the
00255    implementation of the GenTL producer. Thus, it can change after software
00256    updates. It often encodes the MAC address of the sensor in some way.
00258    Example: `00_14_2d_2c_6e_bb`
00260 All three options can be seen in the output of `gc_config -l`.
00262 ### Optional Interface ID prefix
00264 If the given ID contains a colon (i.e. `:`), the part before the (first)
00265 colon is interpreted as interface ID and the part after the first colon is
00266 treated as device ID. This is the format that `gc_config -l` shows. A device
00267 with the given ID is only sought on the specified interface. This can be
00268 useful if there are several ways to reach a device from a host computer,
00269 e.g. via wireless and wired network connection, but a certain connection
00270 type (e.g. wired) is preferred due to higher bandwidth and lower latency.
00272 Examples: `eth0:00_14_2d_2c_6e_bb`, `eth1:02911931` or `wlan0:rc_visard`
00274 A colon at the beginning of the ID effectively defines an empty interface ID
00275 which triggers looking on all interfaces.
00277 If the given ID does not contain a colon, the ID is interpreted as the
00278 device ID itself and is sought throughout all interfaces as well.
00280 Transport Layer
00281 ---------------
00283 The communication to the device is done through a so called transport layer
00284 (i.e. GenTL producer version 1.5 or higher). This package provides and installs
00285 a default transport layer that implements the GigE Vision protocol for
00286 connecting to the Roboception rc_visard. According to the GenICam
00287 specification, the transport layer has the suffix '.cti'. The environment
00288 variable `GENICAM_GENTL32_PATH` (for 32 bit applications) or `GENICAM_GENTL64_PATH`
00289 (for 64 bit applications) must contain a list of paths that contain transport
00290 layers. All transport layers are provided as systems to the application.
00292 For convenience, if the environment variable is not defined or empty, it is
00293 internally defined with the install path of the provided transport layer (as
00294 known at compile time!). If the package is not installed, the install path is
00295 changed after compilation or the package is moved to another location after
00296 installation, then the transport layer may not be found. In this case, the
00297 tools shows an error like e.g.:
00299     'No transport layers found in path /usr/lib/rc_genicam_api'
00301 In this case, the corresponding environment variable (see above) must be set to
00302 the directory in which the transport layer (i.e. file with suffix '.cti')
00303 resides.
00305 Under Windows, as second fall back additionally to the install path, the
00306 directory of the executable is also added to the environment variable. Thus,
00307 the install directory can be moved, as long as the cti file stays in the same
00308 directory as the executable.
00310 Network Optimization under Linux
00311 --------------------------------
00313 When images are received at a lower rate than set/exepected the most
00314 likely problem is that this (user space) library cannot read the many UDP
00315 packets fast enough resulting in incomplete image buffers.
00317 ### Test Script
00319 The `` script performs some simple checks and should be run
00320 while or after streaming images via GigE Vision.
00322     ./ --help
00324 ### Jumbo Frames
00326 First of all increasing the UDP packet size (using jubo frames) is strongly
00327 recommended! Increase the MTU of your network interface to 9000, e.g.
00329     sudo ifconfig eth0 mtu 9000
00331 Also make sure that all network devices/switches between your host and the
00332 sensor support this.
00334 ### sysctl settings
00336 There are several Linux sysctl options that can be modified to increase
00337 performance for the GigE Vision usecase.
00339 These values can be changed during runtime with `sysctl` or written to
00340 `/etc/sysctl.conf` for persistence across reboots.
00342 #### rmem_max
00344 If the number of UDP RcvbufErrors increases while streaming, increasing the
00345 socket receive buffer size usually fixes the problem.
00347 Check the RcvbufErrors with `` or
00349     netstat -us | grep RcvbufErrors
00351 Increase max receive buffer size:
00353     sudo sysctl -w net.core.rmem_max=33554432
00355 #### softirq
00357 Changing these values is usually not necessary, but can help if the kernel
00358 is already dropping packets.
00360 Check with `` and increase the values if needed:
00362     sudo sysctl -w net.core.netdev_max_backlog=2000
00363     sudo sysctl -w net.core.netdev_budget=600

Author(s): Heiko Hirschmueller
autogenerated on Thu Jun 6 2019 18:42:47