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.
Download the latest Python release from python.org, available at https://www.python.org/downloads/windows/.
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.
Install or update python3.7 with the packet manager of your distribution.
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 ()