Basler backend

Basler backend#

The Basler backend provides support for Basler cameras using the official pylon SDK through the pypylon Python bindings.

Download the official pylon SDK from Basler and install the pypylon Python package to use this backend.

Note

This backend requires the optional pypylon dependency. If pypylon is not installed, the backend will be unavailable.

Features & design#

  • Native Basler camera support via pypylon (Pylon SDK bindings).

  • Best-effort device discovery without opening cameras (enumerates DeviceInfo entries).

  • Stable camera identity via serial number (device_id) with automatic index rebinding.

  • Configurable exposure, gain, frame rate, and resolution.

  • Frames are converted to BGR (8-bit) for consistency with other GUI backends.

Installation#

Important

For up to date installation instructions, please refer to the official pypylon documentation and the Basler pylon software installation guide.

1) Install Basler pylon SDK#

Basler recommends installing pylon first (strongly recommended even if you install pypylon via pip).

Basler provides pylon for Linux as Debian packages and .tar.gz archives (x86_64 and ARM variants).

  • Download the matching pylon installer from Basler and follow the included INSTALL instructions.

  • Install the Basler pylon Camera Software Suite (includes drivers and tooling).

  • Install the Basler pylon package for macOS (Intel/ARM supported, depending on Basler release). Basler lists macOS as a supported system for pypylon usage.

2) Install pypylon#

Install into the same Python environment as your GUI:

pip install pypylon # OR uv pip install pypylon

pypylon is the official Python wrapper for the Basler pylon Camera Software Suite

Basic configuration#

Select the Basler backend in the GUI or via configuration:

{
  "camera": {
    "backend": "basler",
    "index": 0,
    "fps": 30.0,
    "exposure": 8000,
    "gain": 5.0
  }
}

Camera selection#

By index (default)#

{
  "camera": {
    "backend": "basler",
    "index": 0
  }
}

Full properties and advanced configuration#

Basler-specific options live under the properties.basler namespace.

Basler namespace options#

These settings live under the properties.basler entry.

  • device_id (string): preferred stable identity (camera serial number).

  • fast_start (bool, default: false): probe-mode hint.

    • When true, the backend will open the camera but will not start grabbing and will not create the pixel format converter.

    • This is intended for fast capability probing; it is not suitable for normal capture.

  • resolution ([w, h]): optional override resolution pair.

    • Used only if width/height are not set.

Auto-populated Basler metadata#

After a successful open, the backend may populate the following read-only convenience fields in properties.basler:

  • device_name: a friendly device name (if provided by the SDK).

  • (Optionally) device_path: a full identifier string (depending on SDK/device).

These fields are managed automatically and are not required to configure the backend.

Exposure and gain#

Behavior:

  • If exposure > 0, the backend attempts to disable ExposureAuto (if present) and sets ExposureTime in microseconds.

  • If gain > 0, the backend attempts to disable GainAuto (if present) and sets Gain.

  • If exposure <= 0 or gain <= 0, the backend leaves the camera’s auto/manual mode unchanged.

Example:

{
  "camera": {
    "backend": "basler",
    "exposure": 10000,
    "gain": 6.0
  }
}

Frame rate (FPS)#

  • FPS is only applied when fps > 0.

  • The backend attempts to enable AcquisitionFrameRateEnable when available, then sets AcquisitionFrameRate.

  • The backend reads back the actual FPS (if available) and exposes it via telemetry.

Resolution handling#

Resolution is only changed when explicitly requested.

Priority order for requesting a resolution:

  1. width + height (GUI fields)

  2. properties.basler.resolution (namespaced override)

If no resolution is provided (or if width/height are 0), the backend preserves the camera’s default configuration.

Increment and range constraints:

  • Many Basler cameras restrict Width/Height to specific increments.

  • The backend snaps requested values down to the nearest valid increment (best-effort) and clamps to min/max.

  • A warning is logged if the requested and applied resolutions differ.

Pixel format and color conversion#

To provide a consistent frame format across backends, the Basler backend converts frames to:

  • BGR8 packed (8-bit BGR)

Internally, it uses a pypylon ImageFormatConverter configured for PixelType_BGR8packed.

Device discovery#

The backend can enumerate devices without opening them and returns (best-effort):

  • index: current device list index

  • label: human-readable label (vendor/model + serial if available)

  • device_id: serial number (stable identity)

  • path: full name string (if available)

Note that availability and richness of fields depend on camera transport and SDK support.

Troubleshooting#

Backend not available / import error#

  • Ensure pypylon is installed:

    python -c "import pypylon"

  • Install it if missing:

    pip install pypylon

No cameras detected#

  • Verify the Basler pylon runtime is installed and your camera is visible in Basler tooling.

  • On Linux, ensure you installed pylon using the Basler-provided packages/archives and followed the included INSTALL guide.

Resolution mismatch warnings#

If you request a resolution that violates camera constraints (min/max or increment), the backend will snap/clamp to valid values and log a warning.

Example configuration#

{
  "camera": {
    "backend": "basler",
    "index": 0,
    "fps": 60.0,
    "exposure": 8000,
    "gain": 10.0,
    "width": 1920,
    "height": 1080,
    "properties": {
      "basler": {
        "device_id": "40312345"
      }
    }
  }
}

Resources#

Contents