WIP Basler backend: resolution, FPS and capabilities

Refactor Basler camera backend to improve resolution/fps handling and provide capability metadata. Adds OPTIONS_KEY, explicit requested vs actual resolution/fps fields and accessors, and a static_capabilities() method. Resolution is now applied only if explicitly requested (legacy resolution or settings.width/height), otherwise the device default is preserved. Simplifies exposure/gain/fps error handling, captures actual camera width/height/fps on open/read for GUI use, and consolidates resolution configuration into _configure_resolution(). Miscellaneous logging and minor API cleanup to better surface device-reported settings.

Author: C-Achard

dlclivegui/cameras/backends/basler_backend.py

@@ -1,13 +1,15 @@
 """Basler camera backend implemented with :mod:`pypylon`."""
 
+# dlclivegui/cameras/backends/basler_backend.py
 from __future__ import annotations
 
 import logging
 import time
+from typing import ClassVar
 
 import numpy as np
 
-from ..base import CameraBackend, register_backend
+from ..base import CameraBackend, SupportLevel, register_backend
 
 LOG = logging.getLogger(__name__)
 
@@ -21,101 +23,110 @@
 class BaslerCameraBackend(CameraBackend):
     """Capture frames from Basler cameras using the Pylon SDK."""
 
+    OPTIONS_KEY: ClassVar[str] = "basler"
+
     def __init__(self, settings):
         super().__init__(settings)
+
+        props = settings.properties if isinstance(settings.properties, dict) else {}
+        ns = props.get(self.OPTIONS_KEY, {})
+        if not isinstance(ns, dict):
+            ns = {}
+
         self._camera: pylon.InstantCamera | None = None
         self._converter: pylon.ImageFormatConverter | None = None
-        # Parse resolution with defaults (720x540)
-        self._resolution: tuple[int, int] = self._parse_resolution(settings.properties.get("resolution"))
+
+        # Resolution request (None = device default)
+        self._requested_resolution: tuple[int, int] | None = self._get_requested_resolution_or_none()
+
+        # Actuals for GUI
+        self._actual_width: int | None = None
+        self._actual_height: int | None = None
+        self._actual_fps: float | None = None
+
+    @property
+    def actual_resolution(self) -> tuple[int, int] | None:
+        if self._actual_width and self._actual_height:
+            return (self._actual_width, self._actual_height)
+        return None
+
+    @property
+    def actual_fps(self) -> float | None:
+        return self._actual_fps
 
     @classmethod
     def is_available(cls) -> bool:
         return pylon is not None
 
+    @classmethod
+    def static_capabilities(cls) -> dict[str, SupportLevel]:
+        caps = super().static_capabilities()
+        caps.update(
+            {
+                "set_resolution": SupportLevel.SUPPORTED,
+                "set_fps": SupportLevel.SUPPORTED,
+                "set_exposure": SupportLevel.SUPPORTED,
+                "set_gain": SupportLevel.SUPPORTED,
+                "device_discovery": SupportLevel.BEST_EFFORT,
+                "stable_identity": SupportLevel.SUPPORTED,
+            }
+        )
+        return caps
+
     def open(self) -> None:
-        if pylon is None:  # pragma: no cover - optional dependency
+        if pylon is None:
             raise RuntimeError("pypylon is required for the Basler backend but is not installed")
+
         devices = self._enumerate_devices()
         if not devices:
             raise RuntimeError("No Basler cameras detected")
+
         device = self._select_device(devices)
         self._camera = pylon.InstantCamera(pylon.TlFactory.GetInstance().CreateDevice(device))
         self._camera.Open()
 
-        # Configure exposure
+        # Exposure
         exposure = self._settings_value("exposure", self.settings.properties)
         if exposure is not None:
             try:
                 self._camera.ExposureTime.SetValue(float(exposure))
-                actual = self._camera.ExposureTime.GetValue()
-                if abs(actual - float(exposure)) > 1.0:  # Allow 1μs tolerance
-                    LOG.warning(f"Exposure mismatch: requested {exposure}μs, got {actual}μs")
-                else:
-                    LOG.info(f"Exposure set to {actual}μs")
-            except Exception as e:
-                LOG.warning(f"Failed to set exposure to {exposure}μs: {e}")
-
-        # Configure gain
+            except Exception:
+                pass
+
+        # Gain
         gain = self._settings_value("gain", self.settings.properties)
         if gain is not None:
             try:
                 self._camera.Gain.SetValue(float(gain))
-                actual = self._camera.Gain.GetValue()
-                if abs(actual - float(gain)) > 0.1:  # Allow 0.1 tolerance
-                    LOG.warning(f"Gain mismatch: requested {gain}, got {actual}")
-                else:
-                    LOG.info(f"Gain set to {actual}")
-            except Exception as e:
-                LOG.warning(f"Failed to set gain to {gain}: {e}")
-
-        # Configure resolution
-        requested_width, requested_height = self._resolution
-        try:
-            self._camera.Width.SetValue(requested_width)
-            self._camera.Height.SetValue(requested_height)
-            actual_width = self._camera.Width.GetValue()
-            actual_height = self._camera.Height.GetValue()
-            if actual_width != requested_width or actual_height != requested_height:
-                LOG.warning(
-                    f"Resolution mismatch: requested {requested_width}x{requested_height}, "
-                    f"got {actual_width}x{actual_height}"
-                )
-            else:
-                LOG.info(f"Resolution set to {actual_width}x{actual_height}")
-        except Exception as e:
-            LOG.warning(f"Failed to set resolution to {requested_width}x{requested_height}: {e}")
+            except Exception:
+                pass
+
+        # Resolution (device default if None)
+        self._configure_resolution()
 
-        # Configure frame rate
+        # Frame rate
         fps = self._settings_value("fps", self.settings.properties, fallback=self.settings.fps)
         if fps is not None:
             try:
                 self._camera.AcquisitionFrameRateEnable.SetValue(True)
                 self._camera.AcquisitionFrameRate.SetValue(float(fps))
-                actual_fps = self._camera.AcquisitionFrameRate.GetValue()
-                if abs(actual_fps - float(fps)) > 0.1:
-                    LOG.warning(f"FPS mismatch: requested {fps:.2f}, got {actual_fps:.2f}")
-                else:
-                    LOG.info(f"Frame rate set to {actual_fps:.2f} FPS")
-            except Exception as e:
-                LOG.warning(f"Failed to set frame rate to {fps}: {e}")
+                self._actual_fps = float(self._camera.AcquisitionFrameRate.GetValue())
+            except Exception:
+                self._actual_fps = None
+
+        # Capture actual resolution even when using defaults
+        try:
+            self._actual_width = int(self._camera.Width.GetValue())
+            self._actual_height = int(self._camera.Height.GetValue())
+        except Exception:
+            pass
 
         self._camera.StartGrabbing(pylon.GrabStrategy_LatestImageOnly)
+
         self._converter = pylon.ImageFormatConverter()
         self._converter.OutputPixelFormat = pylon.PixelType_BGR8packed
         self._converter.OutputBitAlignment = pylon.OutputBitAlignment_MsbAligned
 
-        # Read back final settings
-        try:
-            self.settings.width = int(self._camera.Width.GetValue())
-            self.settings.height = int(self._camera.Height.GetValue())
-        except Exception:
-            pass
-        try:
-            self.settings.fps = float(self._camera.ResultingFrameRateAbs.GetValue())
-            LOG.info(f"Camera configured with resulting FPS: {self.settings.fps:.2f}")
-        except Exception:
-            pass
-
     def read(self) -> tuple[np.ndarray, float]:
         if self._camera is None or self._converter is None:
             raise RuntimeError("Basler camera not opened")
@@ -129,6 +140,12 @@ def read(self) -> tuple[np.ndarray, float]:
         image = self._converter.Convert(grab_result)
         frame = image.GetArray()
         grab_result.Release()
+
+        if self._actual_width is None or self._actual_height is None:
+            h, w = frame.shape[:2]
+            self._actual_width = int(w)
+            self._actual_height = int(h)
+
         rotate = self._settings_value("rotate", self.settings.properties)
         if rotate:
             frame = self._rotate(frame, float(rotate))
@@ -176,25 +193,61 @@ def _rotate(self, frame: np.ndarray, angle: float) -> np.ndarray:
             raise RuntimeError("Rotation requested for Basler camera but imutils is not installed") from exc
         return rotate_bound(frame, angle)
 
-    def _parse_resolution(self, resolution) -> tuple[int, int]:
-        """Parse resolution setting.
+    def _get_requested_resolution_or_none(self) -> tuple[int, int] | None:
+        """
+        Return (w, h) if user explicitly requested a resolution.
+        Return None to keep device defaults.
+        """
+        props = self.settings.properties if isinstance(self.settings.properties, dict) else {}
 
-        Args:
-            resolution: Can be a tuple/list [width, height], or None
+        legacy = props.get("resolution")
+        if isinstance(legacy, (list, tuple)) and len(legacy) == 2:
+            try:
+                w, h = int(legacy[0]), int(legacy[1])
+                if w > 0 and h > 0:
+                    return (w, h)
+            except Exception:
+                pass
 
-        Returns:
-            Tuple of (width, height), defaults to (720, 540)
+        try:
+            w = int(getattr(self.settings, "width", 0) or 0)
+            h = int(getattr(self.settings, "height", 0) or 0)
+            if w > 0 and h > 0:
+                return (w, h)
+        except Exception:
+            pass
+
+        return None
+
+    def _configure_resolution(self) -> None:
+        """
+        Apply width/height only if explicitly requested.
+        If None, keep device defaults.
         """
-        if resolution is None:
-            return (720, 540)  # Default resolution
+        if self._camera is None:
+            return
 
-        if isinstance(resolution, (list, tuple)) and len(resolution) == 2:
-            try:
-                return (int(resolution[0]), int(resolution[1]))
-            except (ValueError, TypeError):
-                return (720, 540)
+        req = self._requested_resolution
+        if req is None:
+            LOG.info("Resolution: using device default.")
+            return
+
+        req_w, req_h = req
+        try:
+            self._camera.Width.SetValue(int(req_w))
+            self._camera.Height.SetValue(int(req_h))
 
-        return (720, 540)
+            aw = int(self._camera.Width.GetValue())
+            ah = int(self._camera.Height.GetValue())
+            self._actual_width = aw
+            self._actual_height = ah
+
+            if (aw, ah) != (req_w, req_h):
+                LOG.warning(f"Resolution mismatch: requested {req_w}x{req_h}, got {aw}x{ah}")
+            else:
+                LOG.info(f"Resolution set to {aw}x{ah}")
+        except Exception as exc:
+            LOG.warning(f"Failed to set resolution to {req_w}x{req_h}: {exc}")
 
     @staticmethod
     def _settings_value(key: str, source: dict, fallback: float | None = None):