Skip to content

Python API#

The Python API wraps the native C++ interface via SWIG. A convenience module (vl.vl) provides a Camera class and Observer base class for easy camera access from Python.

For the full API reference, see the C++ API — all camera methods are available through the Python wrapper with identical names.

Sample applications are available here.

Installation#

The vl wheel is published to the project's public package registry — see Installation for details:

pip install vl \
  --extra-index-url https://git.3dvisionlabs.com/api/v4/projects/3dvisionlabs%2Fsoftware%2Fecm%2Fvl/packages/pypi/simple

The wheel is built for linux_aarch64 and bundles the native libraries, so no separate C++ installation is required.

Quick Start — Single Image#

from vl.vl import Camera, vlImageToNPArray
import cv2

c = Camera()
c.start()

# Grab a single image (synchronous)
frame = c.grabImage()

# Convert to NumPy array
nparray = vlImageToNPArray(frame.image())
cv2.imwrite("capture.jpg", nparray)

c.stop()

Note

vlImageToNPArray() requires the image to use Host memory. When using ImageSettings, set memory = MemoryType_Host.

Warning

MemoryType_CudaManaged buffers must not be read directly from the application — access has to be serialised against the GPU pipeline, which requires the C++-only vl::cudaMemoryAccess() (see Accessing CudaManaged Memory). From Python, use MemoryType_Host.

For continuous capture, use the observer pattern. The Observer base class provides FPS tracking via fps():

from vl.vl import Camera, Observer, vlImageToNPArray

class MyObserver(Observer):
    def onFrameReceived(self, frame):
        if not frame.valid():
            return
        print(f"Frame: {frame.image().width()}x{frame.image().height()}, "
              f"FPS: {self.fps():.1f}")

obs = MyObserver(callback=lambda frame: None)
c = Camera()
c.addStream(obs)
c.start()

input("Press Enter to stop...")
c.stop()

Tip

The Observer constructor takes a callback function that receives the frame. You can either pass a callback or subclass Observer and override onFrameReceived.

Camera Configuration#

All ICamera methods from the C++ API are available:

from vl import camera as vlcam

c = Camera()

# Exposure
c.setAutoExposureMode(vlcam.AutoControlMode_Off)
c.setExposure(15000)  # 15 ms

# Trigger
c.setTriggerMode(vlcam.TriggerMode_Software)
c.start()
c.trigger()

# Image format and scaling
settings = vlcam.ImageSettings()
settings.format = vlcam.ImageFormat_Gray8
settings.scale = 0.5

Settings Persistence#

c.saveSettings("/path/to/config.json")
c.loadSettings("/path/to/config.json")
c.resetToDefaults()

Setup and Run (Docker)#

git clone https://git.3dvisionlabs.com/3dvisionlabs/software/ecm/vl-samples.git
cd vl-samples/python
./run.sh