Python API Manual

Introduction to the API

Vimba’s Python API is a Python wrapper around the Vimba C API. It provides all functions from the Vimba C API, but enables you to program Allied Vision cameras with less lines of code.

We recommend using the Vimba Python API for: - Quick prototyping - Getting started with programming machine vision or embedded vision applications - Easy interfacing with deep learning frameworks and libraries such as OpenCV via NumPy arrays

Is this the best API for you?

Vimba provides four APIs:

  • The Vimba Python API is ideal for quick prototyping. We also recommend this API for an easy start with machine vision or embedded vision applications. For best performance and deterministic behavior, the C and C++ APIs are a better choice.

  • The Vimba C API is easy-to-use, but requires more lines of code than the Python API. It can also be used as API for C++ applications.

  • The Vimba C++ API has an elaborate class architecture. It is designed as a highly efficient and sophisticated API for advanced object-oriented programming including the STL (standard template library), shared pointers, and interface classes. If you prefer an API with less design patterns, we recommend the Vimba C API.

  • The Vimba .NET API supports all .NET languages. Its general concept is similar to the C++ API.

All Vimba APIs cover the following functions:

  • Listing currently connected cameras

  • Controlling camera features

  • Receiving images from the camera

  • Getting notifications about camera connections and disconnections

Compatibility

Supported operating systems and cameras are listed in the Release Notes for your operating system.

Compatible Python version: Python 3.7.x or higher. For 64-bit operating systems, we recommend using a 64-bit Python interpreter.

Prerequisites

Note

Python is not provided with the Vimba SDK. To use Vimba Python, install Python version 3.7 or higher as described below.

Note

Updating Vimba to a higher version does not automatically update any installed VimbaPython site packages. Please perform the installation as described below again manually, especially if the error “Invalid VimbaC Version” occurs.

Installing Python - Windows

If your system requires multiple, coexisting Python versions, consider using pyenv-win, available at https://github.com/pyenv-win/pyenv-win to install and maintain multiple Python installations.

  1. Download the latest Python release from python.org, available at https://www.python.org/downloads/windows/.

  2. Execute the downloaded installer and ensure that the latest pip version is installed.

If you don’t have admin privileges for all directories, read the instructions for all operating systems below.

To verify the installation, open the command prompt and enter:

python --version
python -m pip --version

Please ensure that the Python version is 3.7 or higher and pip uses this Python version. Optionally, install NumPy and OpenCV.

Installing Python - Linux

On Linux systems, the Python installation process depends heavily on the distribution. If python3.7 is not available for your distribution or your system requires multiple python versions to coexist, use pyenv, available at https://realpython.com/intro-to-pyenv/ instead.

If you don’t have admin privileges for all directories, read the instructions for all operating systems below.

  1. Install or update python3.7 with the packet manager of your distribution.

  2. Install or update pip with the packet manager of your distribution.

To verify the installation, open a console and enter:

python --version
python -m pip --version

Helper scripts for Linux

For Linux systems, helper scripts named Install.sh and Uninstall.sh to install and uninstall VimbaPython are provided. They automatically detect if there is a currently active virtual environment. To install or uninstall VimbaPython for one of the system wide Python installations, admin rights are required (use sudo). To get further details on why the scripts do not offer your desired Python installation or to troubleshoot problems, a debug flag is provided (for example ./Install.sh -d).

ARM users only: If installation of “opencv-export” fails, pip is not able to install “opencv-python” for ARM boards. This is a known issue on ARM boards. If you are affected by this, install VimbaPython without optional dependencies and try to install OpenCV in a different way (for example, with your operating system’s packet manager). The OpenCV installation can be verified by running the example asychronous_ grab_ opencv.py.

All operating systems

Open a terminal and navigate to the VimbaPython installation directory. Users who want to change the API’s sources can find them in the Vimba examples directory that you have admin/write privileges for, such as C:\Users\Public\Documents\Allied Vision\Vimba_x_x\VimbaPython_Source. Please note that Allied Vision can offer only limited support if an application uses a modified version of the API.

Troubleshooting pip behavior

If you don’t have admin rights for the above-mentioned directories, download VimbaPython (in the correct version needed for your Vimba installation) from https://github.com/alliedvision/VimbaPython and install it from that directory.

Or downgrade pip to a version less than 2.3 with, for example:

python -m pip install --upgrade pip==21.1.2

After the VimbaPython installation is complete, you can upgrade pip again to the latest version.

For a basic Python installation, execute:

python -m pip install .
Installation with optional NumPy and OpenCV export:
python -m pip install .[numpy-export,opencv-export]

General aspects of the API

Entry point

The entry point of VimbaPython is the Vimba singleton representing the underlying Vimba System.

Entity documentation

All entities of the Vimba Python API are documented via docstring.

Context manager

The Vimba singleton implements a context manager. The context entry initializes:

  • System features discovery

  • Interface detection

  • Camera detection

The context entry always handles:

  • Vimba API startup and shutdown

  • Opening and closing cameras, interfaces, and ancillary data

  • Feature discovery for the opened entity

Always call all methods for Camera, Feature, and Interface within the scope of a with statement:

from vimba import *
with Vimba.get_instance () as vimba:
cams = vimba.get_all_cameras ()

Classes

Camera

The Camera class implements a context manager. On entering the Camera’s context, all camera features are detected and can be accessed only within the with statement. Additionally to getting and setting camera features, the Camera class handles the camera access mode (default: Full Access).

Note

For changing the pixel format, always use the convenience functions instead of the camera feature, see section Changing the pixel format.

Frame

The Frame class stores raw image data and metadata of a single frame. The Frame class implements deepcopy semantics. Additionally, it provides methods for pixel format conversion and ancillary data access. Like all objects containing Features, AncillaryData implements a context manager that must be entered before features can be accessed. The Frame class offers methods for NumPy and OpenCV export.

The following code snippet shows how to:

  • Acquire a single frame

  • Convert the pixel format to Mono8

  • Store it using opencv-python

import cv2
from vimba import *

with Vimba.get_instance () as vimba:
cams = vimba.get_all_cameras ()
with cams [0] as cam:
    frame = cam.get_frame ()
    frame.convert_pixel_format(PixelFormat.Mono8)
    cv2.imwrite('frame.jpg', frame.as_opencv_image ())

Interface

The Interface class contains all data of detected hardware interfaces cameras are connected to. An Interface has associated features and implements a context manager as well. On context entry, all features are detected and can be accessed within the with statement scope. The following code snippet prints all features of the first detected Interface.

from vimba import *

with Vimba.get_instance () as vimba:
    inters = vimba.get_all_interfaces ()
    with inters [0] as interface:
        for feat in interface.get_all_features ():
            print(feat)

API usage

See also

For a quick start, we recommend using the code examples.

Listing cameras

See also

To list available cameras, see the list_ cameras.py example

Cameras are detected automatically on context entry of the Vimba instance. The order in which detected cameras are listed is determined by the order of camera discovery and therefore not deterministic. The discovery of GigE cameras may take several seconds. Before opening cameras, camera objects contain all static details of a physical camera that do not change throughout the object’s lifetime such as the camera ID and the camera model.

Plug and play

Cameras and hardware interfaces such as USB can be detected at runtime by registering a callback at the Vimba instance. The following code snippet registers a callable, creating a log message as soon as a camera or an interface is connected or disconnected. It runs for 10 seconds waiting for changes of the connected hardware.

Note

The Camera Link and MIPI CSI-2 specifications don’t support plug and play. In this case, changes to the camera list cannot be detected while Vimba is running.

from time import sleep
from vimba import *

@ScopedLogEnable(LOG_CONFIG_INFO_CONSOLE_ONLY)
def print_device_id(dev , state ):
    msg = 'Device: {}, State: {}'.format(str(dev), str(state ))
    Log.get_instance (). info(msg)

vimba = Vimba.get_instance ()
vimba.register_camera_change_handler(print_device_id)
vimba.register_interface_change_handler(print_device_id)

with vimba:
    sleep (10)

Listing features

See also

To list the features of a camera and its physical interface, see the list_ features.py example.

Accessing features

As an example for reading and writing a feature, the following code snippet reads the current exposure time and increases it. Depending on your camera model and camera firmware, feature naming may be different.

from vimba import *

with Vimba.get_instance () as vimba:
    cams = vimba.get_all_cameras ()
    with cams [0] as cam:
        exposure_time = cam.ExposureTime

        time = exposure_time.get()
        inc = exposure_time.get_increment ()

        exposure_time.set(time + inc)

Acquiring images

The Camera class supports synchronous and asynchronous image acquisition. For high performance, acquire frames asynchronously and keep the registered callable as short as possible.

See also

The SDK Manual, section Synchronous and asynchronous image acquisition, provides background knowledge. The Vimba C API Manual, section Image Capture vs. Image Acquisition, provides detailed information about functions of the underlying C API.

To activate “alloc and announce” (optional): Use the optional parameter /x to overwrite allocation_ mode, see the AsynchronousGrab example.

# Synchronous grab
from vimba import *

with Vimba.get_instance () as vimba:
    cams = vimba.get_all_cameras ()
    with cams [0] as cam:
        # Aquire single frame synchronously
        frame = cam.get_frame ()

        # Aquire 10 frames synchronously
        for frame in cam.get_frame_generator(limit =10):
            pass

Acquire frames asychronously by registering a callable being executed with each incoming frame:

# Asynchronous grab
import time
from vimba import*

def frame_handler(cam , frame ):
    cam.queue_frame(frame)

with Vimba.get_instance () as vimba:
    cams = vimba.get_all_cameras ()
    with cams [0] as cam:
        cam.start_streaming(frame_handler)
        time.sleep (5)
        cam.stop_streaming ()

The asynchronous_ grab.py example shows how to grab images and prints information about the acquired frames to the console.

The asynchronous_ grab_ opencv.py example shows how to grab images. It runs for 5 seconds and displays the images via OpenCV.

Changing the pixel format

Note

Always use the convenience functions instead of the PixelFormat feature of the Camera.

Convenience functions

To easily change the pixel format with Vimba Python API, always use the convenience functions instead of the PixelFormat feature of the Camera. The convenience function set_pixel_format(fmt) changes the Camera pixel format by passing the desired member of the PixelFormat enum. When using the PixelFormat feature (not recommended), a correctly pre-formatted string has to be used instead.

Getting and setting pixel formats

Before image acquisition is started, you can get and set pixel formats within the Camera class:

# Camera class methods for getting and setting pixel formats
# Apply these methods before starting image acquisition

get_pixel_formats () # returns a tuple of all pixel formats supported by the camera
get_pixel_format () # returns the current pixel format
set_pixel_format(fmt) # enables you to set a new pixel format

Note

The pixel format cannot be changed while the camera is acquiring images.

Converting a pixel format

After image acquisition in the camera, the Frame contains the pixel format of the camera. Now you can convert the pixel format with the convert_ pixel_ format() method. The following code snippet shows how to query a pixel format and apply it to the camera:

from vimba import *

with Vimba.get_instance () as vimba:
    cams = vimba.get_all_cameras ()
    with cams [0] as cam:

    # Get pixel formats available in the camera
    fmts = cam.get_pixel_formats ()

    # In this case , we want a format that supports colors
    fmts = intersect_pixel_formats(fmts , COLOR_PIXEL_FORMATS)

    # In this case , we want a format that is compatible with OpenCV
    fmts = intersect_pixel_formats(fmts , OPENCV_PIXEL_FORMATS)

    if fmts:
        cam.set_pixel_format(fmts [0])

    else:
        print('Abort. No valid pixel format found.')

The following code snippet shows how to:

  • Acquire a single frame

  • Convert the pixel format to Mono with 8-bit depth

  • Save the frame as JPG using opencv-python

import cv2
from vimba import *

with Vimba.get_instance () as vimba:
    cams = vimba.get_all_cameras ()
    with cams [0] as cam:
        frame = cam.get_frame ()
        frame.convert_pixel_format(PixelFormat.Mono8)
        cv2.imwrite('frame.jpg', frame.as_opencv_image ())

Listing ancillary data

See also

The list_ ancillary_ data.py example shows how to list ancillary data such as the frame count or feature values such as the exposure time.

Loading and saving user sets

See also

To save the camera settings as a user set in the camera and load it, use the user_ set.py example.

Loading and saving settings

Additionally to the user sets stored in the camera, you can save the feature values as an XML file to your host PC. For example, you can configure your camera with Vimba Viewer, save the settings, and load them with any Vimba API.

See also

See the load_ save_ settings.py example.

Handling events

See also

To get notifications about feature changes, use the event_ handling.py example (for GigE cameras only).

Software trigger

Software trigger commands are supported by all Allied Vision cameras. To get started with triggering and explore the possibilities, you can use Vimba Viewer. To program a software trigger application, use the following code snippet.

# Software trigger for continuous image acquisition

import time
from vimba import *

def handler(cam , frame ):
    print('Frame acquired: {}'.format(frame), flush=True)
    cam.queue_frame(frame)

def main ():
    with Vimba.get_instance () as vimba:

    cam = vimba.get_all_cameras ()[0]

    with cam:
        cam.TriggerSource.set('Software ')
        cam.TriggerSelector.set('FrameStart ')
        cam.TriggerMode.set('On')
        cam.AcquisitionMode.set('Continuous ')

        try:
            cam.start_streaming(handler)

            time.sleep (1)
            cam.TriggerSoftware.run()

            time.sleep (1)
            cam.TriggerSoftware.run()

            time.sleep (1)
            cam.TriggerSoftware.run()

        finally:
            cam.stop_streaming ()

if __name__ == '__main__ ':
    main()

Trigger over Ethernet - Action Commands

You can broadcast a trigger signal simultaneously to multiple GigE cameras via GigE cable. Action Commands must be set first to the camera(s) and then to the API, which sends the Action Commands to the camera(s).

See also

For a quick start, see the ActionCommands example.

See also

Find more details in the application note: Trigger over Ethernet (ToE) - Action Commands

Multithreading

To get started with multithreading, use the multithreading_opencv.py example. You can use the example with one or multiple cameras. The FrameConsumer thread displays images of the first detected camera via OpenCV in a window of 480 x 480 pixels, independent of the camera’s image size. The example automatically constructs, starts, and stops FrameProducer threads for each connected or disconnected camera.

Migrating to the Vimba C or C++ API

The Vimba Python API is optimized for quick and easy prototyping. To migrate to the Vimba C API, we recommend using Vimba Python’s extensive logging capabilities. In the log file, the order of operations is the same as in the Vimba C API. Migrating to the Vimba C++ API is eased by similar names of the functions.

Troubleshooting

Frequent questions:

  • To use the Vimba Python API, the installation of a compatible Vimba C version and Vimba Image Transform version is required. To check the versions, use vimba.get_ version().

  • Error: “Invalid VimbaC Version” although the correct C API version is installed: Updating Vimba does not automatically update any installed VimbaPython site packages. Please perform the installation again manually.

  • For changing the pixel format, always use the convenience functions instead of the camera feature, see section Changing the pixel format.

  • For general issues, see Troubleshooting.

Logging

You can enable and configure logging to:

  • Create error reports

  • Prepare the migration to the Vimba C API or the Vimba C++ API

Tip

If you want to send a log file to our Technical Support team, always use logging level Trace.

Logging levels

The Vimba Python API offers several logging levels. The following code snippet shows how to enable logging with level Warning. All messages are printed to the console.

from vimba import *

vimba = Vimba.get_instance ()
vimba.enable_log(LOG_CONFIG_WARNING_CONSOLE_ONLY)

log = Log.get_instance ()
log.critical('Critical , visible ')
log.error('Error , visible ')
log.warning('Warning , visible ')
log.info('Info , invisible ')
log.trace('Trace , invisible ')

vimba.disable_log ()

Tracing

The logging level Trace enables the most detailed reports. Additionally, you can use it to prepare the migration to the Vimba C API or the Vimba C++ API. Trace is always used with the TraceEnable() decorator. The decorator adds a log entry of level Trace as soon as the decorated function is called. In addition, a log message is added on function exit. This log message shows if the function exit occurred as expected or with an exception.

See also

To create a trace log file, use the create_ trace_ log.py example.

Avoiding large log files

All previous examples enable and disable logging globally via the Vimba object. For more complex applications, this may cause large log files. The ScopedLogEnable() decorator allows enabling and disabling logging on function entry and exit. The following code snippet shows how to use TraceEnable() and ScopedLogEnable().

from vimba import *

@TraceEnable ()
def traced_function ():
   Log.get_instance (). info('Within Traced Function ')

@ScopedLogEnable(LOG_CONFIG_TRACE_CONSOLE_ONLY)
def logged_function ():
   traced_function ()

logged_function ()