Balluff - BVS CA-SF Technical Documentation
Working with GStreamer - The Impact Acquire GenICam GStreamer Plugin

About the Impact Acquire GenICam GStreamer Plugin

Balluff provides a Impact Acquire GenICam GStreamer plugin that enables machine vision applications to use GenICam compliant devices with the GStreamer pipeline framework. It leverages the Impact Acquire C API and the open-source project gst-plugins-vision. The source code can be obtained by contacting the Balluff support.

Building the Impact Acquire GenICam GStreamer Plugin

Prerequisites

  • Install the Impact Acquire framework by following the instructions for Linux and for Windows respectively.
  • Contact Balluff support to obtain the gst-plugins-vision project with the Impact Acquire GenICam GStreamer plugin extension.
  • Install GStreamer 1.2.x or newer.
  • Install CMake
  • (For Linux) Set or add the path /usr/lib/gstreamer-1.0/ to the environment variable GST_PLUGIN_PATH or GST_PLUGIN_SYSTEM_PATH.

Compilation And Installation

Extract the downloaded source of the gst-plugins-vision project with the Impact Acquire GenICam GStreamer plugin. Depending on the host OS, follow the steps below for Linux und Windows respectively.

Linux

Open a terminal and execute the following commands to compile and install the gstimpactacquire plugin: 

$ sudo apt-get install libgstreamer-plugins-base1.0-dev liborc-0.4-dev
$ cd gst-plugins-vision
$ mkdir -p build
$ cd build
$ cmake ..
$ sudo make install gstimpactacquire
Note
When built successfully, the libgstimpactacquire.so will be installed under /usr/lib/gstreamer-1.0/ by default.

Windows

Open a PowerShell terminal and execute the following commands to configure the build environment, e.g. Visual Studio project (Visual Studio 2019 in this documentation): 

cd gst-plugins-vision
mkdir build
cd build
cmake -G "Visual Studio 16 2019" ..
Note
  • Make sure that CMake has been added to the system's PATH variable before compiling.
  • The cmake generator doesn't have to be Visual Studio 16 2019 as shown in the instruction above, it should be selected to match the compiler on your system (see cmake-generators(7)).

Once the project has been generated, open gst-plugins-vision.sln. Inside the solution:

  • Right click on the project gstimpactacquire and select Build
  • Right click on the project INSTALL and select Build
Note
When built successfully, the libgstimpactacquire.dll will be installed under %GSTREAMER_1_0_ROOT_MSVC_X86_64%\lib\gstreamer-1.0 (when using GStreamer for MSVC 64-bit) by default, which will be automatically used by GStreamer to scan its plugins.

Using the Impact Acquire GenICam GStreamer Plugin

Plugin Inspection

Once the Impact Acquire GenICam GStreamer plugin has been built, all information regarding the plugin (including capabilities and read/write parameters) can be inspected via: 

$ gst-inspect-1.0 impactacquiresrc

A Simple Pipeline To Test

A simple pipeline using the Impact Acquire GenICam GStreamer plugin can be constructed like this: 

$ gst-launch-1.0 impactacquiresrc serial="xxxxxx" ! autovideosink
Note
  • If a specific GenICam compliant device is to be used, replace the xxxxxx with the serial number of that device. Wildcards can be used for the serial parameter, so with e.g. serial="GX001*" the Impact Acquire GenICam GStreamer plugin will use the first device with a serial number starting with GX001.
  • If the serial parameter is not given, the Impact Acquire GenICam GStreamer plugin will use the first GenICam compliant device detected by the Impact Acquire framework.

Supported Pixel Formats

The following pixel formats are supported by the Impact Acquire GenICam GStreamer plugin:

  • GRAY8 (Mono8): 
    $ gst-launch-1.0 impactacquiresrc serial="xxxxxx" ! 'video/x-raw, format=GRAY8' ! queue ! autovideosink
  • GRAY16_LE (Mono16): 
    $ gst-launch-1.0 impactacquiresrc serial="xxxxxx" ! 'video/x-raw, format=GRAY16_LE' ! queue ! autovideosink
  • rggb (BayerRG8): 
    $ gst-launch-1.0 impactacquiresrc serial="xxxxxx" ! 'video/x-bayer, format=rggb' ! bayer2rgb ! queue ! autovideosink
  • grbg (BayerGR8): 
    $ gst-launch-1.0 impactacquiresrc serial="xxxxxx" ! 'video/x-bayer, format=grbg' ! bayer2rgb ! queue ! autovideosink
  • rggb16 (BayerRG16): 
    $ gst-launch-1.0 impactacquiresrc serial="xxxxxx" ! 'video/x-bayer, format=rggb16' ! bayer2gray ! queue ! autovideosink
  • grbg16 (BayerGR16): 
    $ gst-launch-1.0 impactacquiresrc serial="xxxxxx" ! 'video/x-bayer, format=grbg16' ! bayer2gray ! queue ! autovideosink
  • RGB: 
    $ gst-launch-1.0 impactacquiresrc serial="xxxxxx" ! 'video/x-raw, format=RGB' ! queue ! autovideosink
  • BGRA: 
    $ gst-launch-1.0 impactacquiresrc serial="xxxxxx" ! 'video/x-raw, format=BGRA' ! queue ! autovideosink
  • BGRx: 
    $ gst-launch-1.0 impactacquiresrc serial="xxxxxx" ! 'video/x-raw, format=BGRx' ! queue ! autovideosink
  • UYVY: 
    $ gst-launch-1.0 impactacquiresrc serial="xxxxxx" ! 'video/x-raw, format=UYVY' ! queue ! autovideosink
  • IYU2: 
    $ gst-launch-1.0 impactacquiresrc serial="xxxxxx" ! 'video/x-raw, format=IYU2' ! queue ! autovideosink
Note
  • If a Bayer format is given to the pipeline (i.e. rggb, grbg, rggb16, or grbg16) but the device doesn't support it, an error "Internal data stream error" will be displayed when starting the pipeline. In this case, please choose a different format.
  • If the device does support a debayered format (e.g. BGRx) but you'd prefer the debayering to be handled by the driver on the host in order to achieve a higher frame rate, use the parameter 'debayer-on-host' and set it to 'Yes' (case insensitive): $ gst-launch-1.0 impactacquiresrc serial="xxxxxx" debayer-on-host=Yes ! 'video/x-raw, format=BGRx' ! queue ! autovideosink
  • When using the queue plugin on a slow system, the streaming pipeline might shutdown automatically followed by the error "internal data flow error: Subclass GstImpactAcquireSrc neither returned a buffer nor submitted a buffer list from its create function". This is because the image buffers might be filled faster by the Impact Acquire framework than being released by the pipeline on such system and the Impact Acquire framework will eventually run out of buffers. Therefore, it is recommended to set the max-size-buffers property of the queue plugin to < 10 , which is the default amount of image buffers in the Impact Acquire framework.

Examples For Using Other Parameters

The following examples demonstrate how to use some of the Impact Acquire GenICam GStreamer plugin's parameters. To retrieve a list of all parameters please refer to Plugin Inspection

  • Setting gain and exposure time: 
    $ gst-launch-1.0 impactacquiresrc serial="xxxxxx" gain=6.0 exposuretime=40000 ! 'video/x-raw, format=(string)UYVY' ! autovideosink
  • Defining an AOI (Area Of Interest): 
    $ gst-launch-1.0 impactacquiresrc serial="xxxxxx" width=1024 height=1024 offsetx=128 offsety=128 ! 'video/x-raw, format=(string)UYVY' ! autovideosink
  • Turning on AEC (Auto Exposure Control) and AGC (Auto Gain Control): 
    $ gst-launch-1.0 impactacquiresrc serial="xxxxxx" autogain="Continuous" autoexposure="Continuous" ! 'video/x-raw, format=(string)UYVY' ! autovideosink

Setting Many Parameters At Once

In case of setting many parameters at the same time, it might be more convenient to pass a configuration file to the plugin, instead of entering these parameters one by one in the pipeline. This XML configuration file of a device can be generated in ImpactControlCenter (see Storing Settings). Users can either configure these parameters first in ImpactControlCenter and then save the current device settings to an XML file, or save the default settings first and then edit these parameters in the XML file.

Once the XML configuration file has been created, use the configurationfile parameter to pass the file to the Impact Acquire GenICam GStreamer plugin: 

$ gst-launch-1.0 impactacquiresrc serial="xxxxxx" configurationfile="myConfig.xml" ! 'video/x-raw, format=(string)UYVY' ! autovideosink