Python API

Note

new in 2.0.0: The python API was introduced in version 2.0.0 first

The python API is derived directly from the C++ interfaces via SWIG. In itself, the python/C++ interface does introduce only minimal new logic to the API. For the most part, it maps the C++ native data types correctly. In the python module "vl", the C++ classes, memory ownership and the python GIL are handled in a wrapper on top of the plain SWIG interface, thus data handover does work uncomplicated.

As the SWIG compiler creates the interface descriptions, currently we do not offer a dedicated python API documentation, other than the hints below. Please refer to our sample applications (publicly available here) and C++ API for details.

Also, please do not hesitate to contact us for further assistance.

Tip

new in 2.0.0: zero-copy memory management from C++ to C#

Danger

Image Lock: For python, the images (memory) must be actively managed through locking and unlocking mechanisms - this avoids that the C++ library "replaces" the raw image data while python is accessing it (zero copy mechanics). The camera instance provides the respective methods to be called.

python Example

The following minimal example shows how to use the python Camera and FrameObserver to configure the camera hardware device and attach to a camera stream. Setup and bring up should be done in a docker environment, the sample in the repository comes with ready-to-use docker files.

Setup and run

Download the python wheel of the desired libvl version here, and make sure to set the correct VERSION in run.sh. Log into the camera (see OS section for details) and issue the following commands:

## clone the git sample repository from 3dvl gitlab server
git clone https://git.3dvisionlabs.com/3dvisionlabs/software/ecm/vl-samples.git
## enter c# sample folder
cd vl-samples/python

## download correct wheel (replace url)
wget https://git.3dvisionlabs.com/3dvisionlabs/software/ecm/vl/-/package_files/5229/download

## edit run.sh to match wheel version as VERSION variable
vi run.sh

## build docker image; build c# executable and run in docker context
./run.sh

Python code

The main program handles setup and configuration of the camera instance as well as the "outer logic", e.g. waiting for user-input before stopping the application. Be aware, the following sample mainly demonstrates the locking mechanism. For production, the "streaming mode", as outlined in the (stream.py) sample, is the recommended way of handling the camera - asynchronously waiting for new camera images in the FrameObserver, and keeping the camera handle and config "idle" in the main tread, e.g. for handling new configurations.

from vl.vl import Camera
import cv2

# initialize and start the camera
c = Camera()
c.start()

# grab an single (synchronous) image from the camera
frame = c.grabImage()

# lock c++ managed memory and convert image into numpy array
nparray = c.lock(frame)

# do something with the image
cv2.imwrite("test.jpg", nparray)

# unlock managed memory (can be recycled by C++, dont use the image after unlocking)
c.unlock()

# stop the camera
c.stop()