Getting Started with CVB Python

Table of Contents

• Prerequisites
• Installing the CVB Python Wheel
• Python API Concept
• Image Display with Qt/QML
• Next Steps and Further Reading

The CVB Python wrapper allows you to seamlessly integrate Common Vision Blox functionality into your Python applications. It provides easy access to image acquisition, processing, and device management features, making it ideal for rapid prototyping and automation in machine vision projects.

To ensure long-term reliability and compatibility, CVB is built on a stable and well-defined core interface:

The CVB C-API maintains a stable application binary interface (ABI), ensuring that applications built against a specific version continue to work with newer CVB versions without requiring recompilation, as long as the interface contract remains unchanged.

Note

While the C++, .NET, and Python wrappers are not strictly bound to API stability, they are designed with a strong focus on API consistency and backward compatibility. Therefore, even in these higher-level APIs, changes are introduced carefully and in a controlled manner to maintain a stable development experience.

Prerequisites

Before you begin, the following requirements are met:

• a stable Python version
• Pip (for installation)
• NumPy: python -m pip install numpy
• PySide2 and PySide6: python -m pip install pyside6 (optional, only needed if you want to use Qt/QML for image display)

Installing the CVB Python Wheel

The CVB Python wrappers can be installed using pip. Running the install script also sets up code completion for your IDE (e.g., Visual Studio Code). The Python wheel is included with your CVB installation at %CVB%%/Lib/Python (Windows) or /opt/cvb/python (Linux).

Install command on Windows:

python -m pip install cvbpy-2.0.0-py3-none-any.whl

and on Linux:

python3 -m pip install cvbpy-2.0.0-py3-none-any.whl

Note

When uninstalling CVB, the Python wheel is not removed automatically. It's recommended to uninstall it manually using: python -m pip uninstall cvb.

For users of Anaconda, additional information is available in the following CVB User Forum post: Getting Started with CVBPy.

Python API Concept

The CVB Python wrapper is located in your CVB installation directory under %CVB%\Lib\Python\cvb. All classes and functions are part of the cvb module. Additional modules and classes are used for specific functionality.

To use the wrapper, simply import the corresponding cvb module and call its functions as shown below:

import cvb
 
devices = cvb.DeviceFactory.discover_from_root(cvb.DiscoverFlags.IgnoreVins)

Lifetime Management

Proper management of object lifetimes is essential when working with resource-intensive entities. We recommend using Python’s with statement for objects that manage critical resources — such as devices and images — to guarantee timely and safe release of those resources.

Enum Values

Python does not treat enums as a distinct type like C/C++. However, since the CVB low-level API makes extensive use of enums, CVBpy provides equivalent representations using global classes. These classes contain static, read-only integer properties that correspond to the original enum values.

Implicit Casting

CVBpy automatically performs implicit conversions between int and float where appropriate. When a floating-point value is converted to an integer, the value is rounded mathematically. If the conversion would result in overflow or is otherwise undefined, the result is unspecified and may or may not raise an error.

Image Display with Qt/QML

To display images with CVB, you can use the Qt framework. For more details, refer to Python - Image Display Using Qt/QML.

Next Steps and Further Reading

Python Example Programs in CVB Installation
Code Examples
Python API Documentation

Python - Image Display Using Qt/QML
CVB Development Workflow Overview