Python Programmer's Guide#

This section provides information specific to Basler Stereo ace cameras. It doesn't aim to give a comprehensive overview of the official Python language binding for Basler pylon.

The official Python language binding for Basler pylon is the pypylon project. pypylon is an open-source project hosted on GitHub. You need version 4.0 or above in order to use Basler Stereo ace cameras.

If you are new to pypylon, Basler recommends making yourself familiar with the pypylon API first by reading the pypylon documentation.

Python Programming Samples#

Prerequisites for Running the Samples#

Python 3.9 or above
pypylon library
NumPy library
OpenCV library
Open3D library (optional, used for visualization)

To install the required libraries, use the following command:

pip install pypylon numpy opencv-python open3d

Running the Samples#

The pylon Supplementary Package for Stereo ace includes some Python programming samples that illustrate how to access a Stereo ace camera using Python and pypylon.

WindowsUbuntuOther Linux Distributions

The Python samples are located in the C:\Program Files\Basler\pylon\Development\Samples\Stereo_ace\Python folder.

The Python samples are located in the /opt/pylon/share/pylon/Samples/Stereo_ace/Python folder.

情報

Before building the samples, copy the folder containing the samples to a location of your choice where you have write permissions.

To run a Python sample, navigate to the folder containing the sample and execute it using Python. Example:

python SimpleGrab.py

Check the Troubleshooting topic if you experience problems running the samples.

List of Samples#

SimpleGrab: Illustrates how to grab images from a Stereo ace camera and access intensity and disparity data.
ShowPointCloud: Illustrates how to calculate a point cloud from disparity data and visualize it using Open3D.
OpenDeviceByIpAddress: Demonstrates how to open a Stereo ace camera by one of its IP addresses.
TriggerLowLatency: Demonstrates how latency can be reduced by binning on the camera instead of on the host.
LeftAndRightIntensity: Demonstrates how to grab left and right intensity image from a Stereo ace camera.

Refer to the sample code in the Python samples directory for more details.

How to Use pypylon with Stereo ace Cameras#

Opening and Accessing Stereo ace Cameras#

The following example demonstrates how to open the first available Stereo ace camera using pypylon:

from pypylon import pylon

# Open the first available Stereo ace camera.
di = pylon.DeviceInfo()
di.SetDeviceClass("BaslerGTC/Basler/basler_xw")
camera = pylon.InstantCamera(pylon.TlFactory.GetInstance().CreateFirstDevice(di))
camera.Open()

print(f"Connected to camera: {camera.GetDeviceInfo().GetModelName()}")

# Close the camera
camera.Close()

To open a specific Stereo ace camera by serial number or user-defined name, modify the DeviceInfo object:

# Open a specific Stereo ace camera by serial number.
di.SetSerialNumber("12345678")

# Open a specific Stereo ace camera by user-defined name.
di.SetUserDefinedName("MyStereoAce")

Accessing Camera Parameters#

You can access and modify camera parameters using the camera object. For example:

# Set the exposure time.
camera.ExposureTime.Value = 5000  # in microseconds

# Set the illumination mode.
camera.BslIlluminationMode.Value = "AlternateActive"

# Print the current depth quality.
print(f"Depth Quality: {camera.BslDepthQuality.GetValue()}")

Acquiring Data#

The following example demonstrates how to grab intensity and disparity data from a Stereo ace camera:

import numpy as np
import cv2
from pypylon import pylon

# Open the first available Stereo ace camera.
di = pylon.DeviceInfo()
di.SetDeviceClass("BaslerGTC/Basler/basler_xw")
camera = pylon.InstantCamera(pylon.TlFactory.GetInstance().CreateFirstDevice(di))
camera.Open()

# Enable intensity and disparity components.
camera.ComponentSelector.Value = "Intensity"
camera.ComponentEnable.Value = True
camera.ComponentSelector.Value = "Disparity"
camera.ComponentEnable.Value = True

# Start grabbing
camera.StartGrabbing(pylon.GrabStrategy_LatestImageOnly)

while camera.IsGrabbing():
    grabResult = camera.RetrieveResult(20000, pylon.TimeoutHandling_ThrowException)

    if grabResult.GrabSucceeded():
        # Access intensity and disparity data.
        pylonDataContainer = grabResult.GetDataContainer()
        for componentIndex in range(pylonDataContainer.DataComponentCount):
            pylonDataComponent = pylonDataContainer.GetDataComponent(componentIndex)
            if pylonDataComponent.ComponentType == pylon.ComponentType_Intensity:
                intensity = pylonDataComponent.Array.reshape(pylonDataComponent.Height, pylonDataComponent.Width)
            elif pylonDataComponent.ComponentType == pylon.ComponentType_Disparity:
                disparity = pylonDataComponent.Array.reshape(pylonDataComponent.Height, pylonDataComponent.Width)

        # Display the images.
        cv2.imshow("Intensity", intensity)
        cv2.imshow("Disparity", disparity)

        # Break the loop on ESC key press.
        if cv2.waitKey(1) & 0xFF == 27:
            break

    grabResult.Release()

camera.StopGrabbing()
camera.Close()

Calculating Point Clouds#

Refer to the ShowPointCloud.py sample for an example of how to calculate and visualize point clouds using Open3D.

Debugging Applications#

If you encounter issues while using pypylon with Stereo ace cameras, check the Troubleshooting topic. from pypylon import pylon

#### Discovering and Opening Cameras

```python
# Create a Basler device support factory
tl_factory = pylon.TlFactory.GetInstance()

# Get all attached Stereo ace cameras
devices = tl_factory.EnumerateDevices()

if len(devices) == 0:
    raise RuntimeError("No Stereo ace cameras found!")

# Create a camera object
camera = pylon.CreateInstantCamera(pylon.CameraOptions(), devices[0])
camera.Open()

Accessing Camera Parameters#

# Access camera parameters
camera.OffsetX.Value = 0
camera.OffsetY.Value = 0

# Get parameter values
width = camera.Width.Value
height = camera.Height.Value
pixel_format = camera.PixelFormat.Value

Grabbing Images#

# Start image acquisition
camera.StartGrabbing(pylon.GrabStrategy_LatestImageOnly)

# Grab images
converter = pylon.ImageFormatConverter()
converter.OutputPixelFormat = pylon.PixelType_BGR8packed
converter.OutputBitAlignment = pylon.OutputBitAlignment_MsbAligned

while camera.IsGrabbing():
    grab_result = camera.RetrieveResult(5000, pylon.TimeoutHandling_ThrowException)

    if grab_result.GrabSucceeded():
        # Access the image data
        image = converter.Convert(grab_result)
        img = image.GetArray()
        # Process image

    grab_result.Release()

# Stop image acquisition
camera.StopGrabbing()
camera.Close()

Installing OpenCV for Python#

Windows and Linux:

Install OpenCV using pip:

pip install opencv-python

Or if you need the full OpenCV package with extra modules:

pip install opencv-contrib-python

Installing NumPy#

Install NumPy using pip:

pip install numpy