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 26.06 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#

• pylon 26.06 or above
• Python 3.9 or above
• pypylon 26.06 or above

Each sample has a requirements.txt file. Depending on the sample, it contains pypylon and optional dependencies such as NumPy, OpenCV, or Open3D.

To install the required libraries, navigate to the Python samples directory and install the requirements for the sample you want to run:

python3 -m pip install -r SimpleGrab/requirements.txt
python3 -m pip install -r OpenDeviceByIpAddress/requirements.txt
python3 -m pip install -r LeftAndRightIntensity/requirements.txt
python3 -m pip install -r TriggerLowLatency/requirements.txt
python3 -m pip install -r ShowPointCloud/requirements.txt

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.

From the Python samples directory, run one sample at a time using Python. For example:

python3 SimpleGrab/SimpleGrab.py
python3 OpenDeviceByIpAddress/OpenDeviceByIpAddress.py <ip-address>
python3 LeftAndRightIntensity/LeftAndRightIntensity.py
python3 TriggerLowLatency/TriggerLowLatency.py
python3 ShowPointCloud/ShowPointCloud.py

Replace <ip-address> with one of the Stereo ace camera's IP addresses.

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 setting the intensity and depth resolutions to High (2x2 binning) on the camera.
• 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"

# Set the output resolutions.
camera.BslDepthResolution.Value = "High"
camera.BslIntensityResolution.Value = "Full"

# Print the current depth resolution.
print(f"Depth Resolution: {camera.BslDepthResolution.Value}")

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()
        intensityComponent = pylonDataContainer.GetFirstImageDataComponent(pylon.ComponentType_Intensity, 0, False)
        disparityComponent = pylonDataContainer.GetFirstImageDataComponent(pylon.ComponentType_Disparity, 0, False)
        if not intensityComponent.IsValid() or not disparityComponent.IsValid():
            print("Missing intensity or disparity component in buffer.")
            grabResult.Release()
            continue

        intensity = intensityComponent.Array.reshape(intensityComponent.Height, intensityComponent.Width)
        disparity = disparityComponent.Array.reshape(disparityComponent.Height, disparityComponent.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.