plexus-python 0.5.2__py3-none-any.whl → 0.6.2__py3-none-any.whl

plexus/__init__.py

@@ -10,5 +10,5 @@ Plexus — thin Python SDK for sending telemetry to the Plexus gateway.
 from plexus.client import Plexus, read_mjpeg_frames
 from plexus.ws import WebSocketTransport
 
-__version__ = "0.5.2"
+__version__ = "0.6.2"
 __all__ = ["Plexus", "WebSocketTransport", "read_mjpeg_frames"]

plexus/cameras/__init__.py

@@ -0,0 +1,25 @@
+from plexus.cameras.thermal import (
+    NoCameraFound,
+    MLX90640Camera,
+    MLX90641Camera,
+    SimulatedThermalCamera,
+    ThermalCamera,
+    ThermalFrame,
+    ThermalSource,
+    USBThermalCamera,
+    build_thermal_frame,
+    encode_frame,
+)
+
+__all__ = [
+    "NoCameraFound",
+    "MLX90640Camera",
+    "MLX90641Camera",
+    "SimulatedThermalCamera",
+    "ThermalCamera",
+    "ThermalFrame",
+    "ThermalSource",
+    "USBThermalCamera",
+    "build_thermal_frame",
+    "encode_frame",
+]

plexus/cameras/thermal.py

@@ -0,0 +1,388 @@
+"""
+Thermal camera drivers for Plexus.
+
+Provides a hardware-agnostic interface over I2C sensors (MLX90640, MLX90641)
+and USB thermal cameras (Y16 pixel format). All drivers return a unified
+ThermalFrame containing a colorized JPEG image plus temperature metadata.
+
+Usage:
+    from plexus.cameras.thermal import ThermalSource
+
+    cam = ThermalSource.open()          # auto-detect
+    cam = ThermalSource.open("sim")     # simulated, no hardware
+
+    while True:
+        px.send_thermal_frame(cam.read_frame(), camera_id="thermal")
+        time.sleep(1 / 5)
+"""
+
+from __future__ import annotations
+
+import base64
+import time
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from typing import Any, Dict, Optional
+
+import cv2
+import numpy as np
+
+# Inferno is perceptually uniform and well-suited for thermal imaging.
+# Swap for cv2.COLORMAP_HOT or cv2.COLORMAP_JET if preferred.
+_COLORMAP = cv2.COLORMAP_INFERNO
+
+# Sensors at or below this pixel count include the full temps array in the
+# wire message. I2C sensors (32×24 = 768, 16×12 = 192) always qualify.
+# USB thermal cameras (256×192 = 49 152) do not.
+_TEMPS_INLINE_THRESHOLD = 4096
+
+# Upscale sensors whose shortest side is below this threshold.
+_MIN_DISPLAY_SIDE = 160
+
+
+class NoCameraFound(RuntimeError):
+    pass
+
+
+# ---------------------------------------------------------------------------
+# Abstract interface
+# ---------------------------------------------------------------------------
+
+
+class ThermalCamera(ABC):
+    """Hardware-agnostic thermal camera interface.
+
+    Subclass and implement read_frame() to support any sensor.
+    read_frame() must return a 2-D float32 array of temperatures in Celsius,
+    shaped (height, width).
+    """
+
+    @property
+    @abstractmethod
+    def width(self) -> int: ...
+
+    @property
+    @abstractmethod
+    def height(self) -> int: ...
+
+    @abstractmethod
+    def read_frame(self) -> np.ndarray: ...
+
+    def close(self) -> None:
+        pass
+
+
+# ---------------------------------------------------------------------------
+# Unified output
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class ThermalFrame:
+    """Encoded output from a ThermalCamera, ready to send to the gateway."""
+
+    image: np.ndarray        # uint8 BGR colorized image (display size)
+    width: int               # display width (may differ from sensor if upscaled)
+    height: int              # display height
+    sensor_width: int        # native sensor width
+    sensor_height: int       # native sensor height
+    temp_min: float
+    temp_max: float
+    temps: Optional[np.ndarray]  # native res; None when sensor > threshold
+    timestamp_ms: int
+
+    def to_message(
+        self, camera_id: str, source_id: Optional[str] = None, quality: int = 85
+    ) -> Dict[str, Any]:
+        """Build the gateway `video_frame` wire message for this frame."""
+        _, buf = cv2.imencode(".jpg", self.image, [cv2.IMWRITE_JPEG_QUALITY, quality])
+        b64 = base64.b64encode(buf.tobytes()).decode("ascii")
+
+        msg: Dict[str, Any] = {
+            "type": "video_frame",
+            "camera_id": camera_id,
+            "frame": b64,
+            "width": self.width,
+            "height": self.height,
+            "timestamp": self.timestamp_ms,
+            "video_type": "thermal",
+            "sensor_width": self.sensor_width,
+            "sensor_height": self.sensor_height,
+            "temp_min": self.temp_min,
+            "temp_max": self.temp_max,
+        }
+        if source_id is not None:
+            msg["source_id"] = source_id
+        if self.temps is not None:
+            msg["temps"] = self.temps.flatten().tolist()
+        return msg
+
+
+# ---------------------------------------------------------------------------
+# Encoding — single shared path used by both encode_frame() and the SDK's
+# Plexus.send_thermal_frame().
+# ---------------------------------------------------------------------------
+
+
+def _upscale_size(sw: int, sh: int) -> tuple[int, int]:
+    if sw >= _MIN_DISPLAY_SIDE and sh >= _MIN_DISPLAY_SIDE:
+        return sw, sh
+    scale = max(_MIN_DISPLAY_SIDE / sw, _MIN_DISPLAY_SIDE / sh)
+    return round(sw * scale), round(sh * scale)
+
+
+def build_thermal_frame(
+    temps: np.ndarray, timestamp_ms: Optional[int] = None
+) -> ThermalFrame:
+    """Colorize a temperature array into a ThermalFrame.
+
+    temps: 2-D float32 Celsius array, shape (height, width).
+    timestamp_ms: wire timestamp; defaults to current time.
+    """
+    sh, sw = temps.shape[:2]
+
+    temp_min = float(np.min(temps))
+    temp_max = float(np.max(temps))
+    span = temp_max - temp_min
+
+    normalized = (
+        np.zeros((sh, sw), dtype=np.uint8)
+        if span < 1e-6
+        else ((temps - temp_min) / span * 255).astype(np.uint8)
+    )
+
+    colored = cv2.applyColorMap(normalized, _COLORMAP)
+
+    dw, dh = _upscale_size(sw, sh)
+    if (dw, dh) != (sw, sh):
+        colored = cv2.resize(colored, (dw, dh), interpolation=cv2.INTER_CUBIC)
+
+    return ThermalFrame(
+        image=colored,
+        width=dw,
+        height=dh,
+        sensor_width=sw,
+        sensor_height=sh,
+        temp_min=round(temp_min, 2),
+        temp_max=round(temp_max, 2),
+        temps=temps if sw * sh <= _TEMPS_INLINE_THRESHOLD else None,
+        timestamp_ms=timestamp_ms if timestamp_ms is not None else int(time.time() * 1000),
+    )
+
+
+def encode_frame(cam: ThermalCamera) -> ThermalFrame:
+    """Read one frame from a camera and colorize it."""
+    return build_thermal_frame(cam.read_frame())
+
+
+# ---------------------------------------------------------------------------
+# Drivers
+# ---------------------------------------------------------------------------
+
+
+class SimulatedThermalCamera(ThermalCamera):
+    """Simulated thermal camera for testing without hardware.
+
+    Produces a moving warm blob over a noisy background at 32×24.
+    """
+
+    def __init__(self, width: int = 32, height: int = 24) -> None:
+        self._width = width
+        self._height = height
+        self._t = 0.0
+
+    @property
+    def width(self) -> int:
+        return self._width
+
+    @property
+    def height(self) -> int:
+        return self._height
+
+    def read_frame(self) -> np.ndarray:
+        self._t += 0.1
+        x = np.linspace(0, 2 * np.pi, self._width)
+        y = np.linspace(0, 2 * np.pi, self._height)
+        xx, yy = np.meshgrid(x, y)
+        base = 22.0 + 3.0 * np.sin(xx + self._t) * np.cos(yy + self._t * 0.7)
+        cx = int((np.sin(self._t * 0.5) * 0.4 + 0.5) * self._width)
+        cy = int((np.cos(self._t * 0.3) * 0.4 + 0.5) * self._height)
+        yg, xg = np.ogrid[: self._height, : self._width]
+        hotspot = 15.0 * np.exp(-((xg - cx) ** 2 + (yg - cy) ** 2) / 20.0)
+        return (base + hotspot).astype(np.float32)
+
+
+class USBThermalCamera(ThermalCamera):
+    """USB thermal camera via V4L2/UVC in Y16 pixel format.
+
+    Most USB thermal cameras (InfiRay, Topdon, Seek, some FLIR) present as
+    standard UVC video devices outputting Y16 frames where each uint16 pixel
+    encodes temperature as: celsius = (value / 100.0) - 273.15
+
+    Requires: pip install opencv-python
+    """
+
+    _KELVIN_SCALE = 100.0
+    _KELVIN_OFFSET = 273.15
+
+    def __init__(self, device_index: int = 0) -> None:
+        self._cap = cv2.VideoCapture(device_index)
+        if not self._cap.isOpened():
+            raise NoCameraFound(f"Cannot open video device {device_index}")
+        self._cap.set(cv2.CAP_PROP_FOURCC, cv2.VideoWriter_fourcc(*"Y16 "))
+        ret, frame = self._cap.read()
+        if not ret or frame is None:
+            self._cap.release()
+            raise NoCameraFound(
+                f"Device {device_index} opened but could not read a frame. "
+                "Check that it supports Y16 format."
+            )
+        self._width = int(self._cap.get(cv2.CAP_PROP_FRAME_WIDTH))
+        self._height = int(self._cap.get(cv2.CAP_PROP_FRAME_HEIGHT))
+
+    @property
+    def width(self) -> int:
+        return self._width
+
+    @property
+    def height(self) -> int:
+        return self._height
+
+    def read_frame(self) -> np.ndarray:
+        ret, raw = self._cap.read()
+        if not ret or raw is None:
+            raise RuntimeError("Failed to read frame from USB thermal camera")
+        u16 = raw.view(np.uint16).reshape(self._height, self._width)
+        return (u16.astype(np.float32) / self._KELVIN_SCALE) - self._KELVIN_OFFSET
+
+    def close(self) -> None:
+        self._cap.release()
+
+
+class MLX90640Camera(ThermalCamera):
+    """MLX90640 32×24 thermal array via I2C.
+
+    Requires: pip install adafruit-circuitpython-mlx90640
+    Wiring:   SCL → GPIO 3, SDA → GPIO 2, 3.3V power (Raspberry Pi).
+    """
+
+    def __init__(self) -> None:
+        import adafruit_mlx90640
+        import board
+        import busio
+
+        i2c = busio.I2C(board.SCL, board.SDA, frequency=800_000)
+        self._mlx = adafruit_mlx90640.MLX90640(i2c)
+        self._mlx.refresh_rate = adafruit_mlx90640.RefreshRate.REFRESH_4_HZ
+        self._buf = [0.0] * 768
+
+    @property
+    def width(self) -> int:
+        return 32
+
+    @property
+    def height(self) -> int:
+        return 24
+
+    def read_frame(self) -> np.ndarray:
+        self._mlx.getFrame(self._buf)
+        return np.array(self._buf, dtype=np.float32).reshape(24, 32)
+
+
+class MLX90641Camera(ThermalCamera):
+    """MLX90641 16×12 thermal array via I2C.
+
+    Requires: pip install adafruit-circuitpython-mlx90641
+    Wiring:   SCL → GPIO 3, SDA → GPIO 2, 3.3V power (Raspberry Pi).
+    """
+
+    def __init__(self) -> None:
+        import adafruit_mlx90641
+        import board
+        import busio
+
+        i2c = busio.I2C(board.SCL, board.SDA, frequency=400_000)
+        self._mlx = adafruit_mlx90641.MLX90641(i2c)
+        self._mlx.refresh_rate = adafruit_mlx90641.RefreshRate.REFRESH_4_HZ
+        self._buf = [0.0] * 192
+
+    @property
+    def width(self) -> int:
+        return 16
+
+    @property
+    def height(self) -> int:
+        return 12
+
+    def read_frame(self) -> np.ndarray:
+        self._mlx.getFrame(self._buf)
+        return np.array(self._buf, dtype=np.float32).reshape(12, 16)
+
+
+# ---------------------------------------------------------------------------
+# Auto-detection factory
+# ---------------------------------------------------------------------------
+
+
+class ThermalSource:
+    """Factory that opens the first available thermal camera.
+
+    Examples:
+        ThermalSource.open()             # auto-detect
+        ThermalSource.open("sim")        # simulated
+        ThermalSource.open("mlx90640")   # force I2C MLX90640
+        ThermalSource.open("mlx90641")   # force I2C MLX90641
+        ThermalSource.open("usb")        # USB thermal at index 0
+        ThermalSource.open(2)            # USB thermal at index 2
+    """
+
+    @staticmethod
+    def open(hint: str | int | None = None) -> ThermalCamera:
+        if hint == "sim":
+            return SimulatedThermalCamera()
+        if hint == "mlx90640":
+            return MLX90640Camera()
+        if hint == "mlx90641":
+            return MLX90641Camera()
+        if hint == "usb" or isinstance(hint, int):
+            return USBThermalCamera(0 if hint == "usb" else hint)
+        return ThermalSource._autodetect()
+
+    @staticmethod
+    def _autodetect() -> ThermalCamera:
+        cam = ThermalSource._try_i2c()
+        if cam:
+            return cam
+        cam = ThermalSource._try_usb()
+        if cam:
+            return cam
+        raise NoCameraFound(
+            "No thermal camera detected. Use ThermalSource.open('sim') to run without hardware."
+        )
+
+    @staticmethod
+    def _try_i2c() -> ThermalCamera | None:
+        try:
+            import board
+            import busio
+
+            i2c = busio.I2C(board.SCL, board.SDA)
+            i2c.try_lock()
+            addrs = i2c.scan()
+            i2c.unlock()
+            if 0x33 in addrs:
+                return MLX90640Camera()
+            if 0x60 in addrs:
+                return MLX90641Camera()
+        except Exception:
+            pass
+        return None
+
+    @staticmethod
+    def _try_usb() -> ThermalCamera | None:
+        for idx in range(10):
+            try:
+                return USBThermalCamera(idx)
+            except NoCameraFound:
+                continue
+        return None

plexus/client.py

@@ -483,8 +483,8 @@ class Plexus:
             except ImportError as e:
                 if required:
                     raise ImportError(
-                        "This frame type requires opencv-python. "
-                        "Install with: pip install opencv-python"
+                        "This frame type requires opencv-python-headless. "
+                        "Install with: pip install plexus-python[video]"
                     ) from e
         return self._cv2
 
@@ -590,6 +590,51 @@ class Plexus:
             self._normalize_ts_ms(timestamp),
         )
 
+    def send_thermal_frame(
+        self,
+        temps,
+        camera_id: str = "thermal:0",
+        quality: int = 85,
+        timestamp: Optional[float] = None,
+    ) -> bool:
+        """Send a thermal camera frame to Plexus (WebSocket transport only).
+
+        Args:
+            temps: 2-D float32 numpy array of temperatures in Celsius,
+                   shape (height, width). Obtained from ThermalCamera.read_frame().
+            camera_id: Logical camera identifier.
+            quality: JPEG quality for the colorized image, 1-100.
+            timestamp: Unix timestamp in seconds. Defaults to current time.
+
+        Returns:
+            True if the frame was sent successfully.
+
+        Raises:
+            PlexusError: If transport is not 'ws'.
+            ImportError: If opencv-python-headless is not installed.
+        """
+        if self.transport != "ws":
+            raise PlexusError("send_thermal_frame requires transport='ws'")
+
+        try:
+            from plexus.cameras.thermal import build_thermal_frame
+        except ImportError as e:
+            raise ImportError(
+                "send_thermal_frame requires opencv-python-headless. "
+                "Install with: pip install plexus-python[video]"
+            ) from e
+
+        frame = build_thermal_frame(temps, timestamp_ms=self._normalize_ts_ms(timestamp))
+        msg = frame.to_message(
+            camera_id=camera_id, source_id=self.source_id, quality=quality
+        )
+
+        ws = self._ensure_ws()
+        if not ws.is_authenticated:
+            ws.wait_authenticated(timeout=min(self.timeout, 5.0))
+
+        return ws.send_json_video_frame(msg)
+
     def stream_camera(
         self,
         url: str,

plexus/ws.py

@@ -209,6 +209,13 @@ class WebSocketTransport:
         except queue.Full:
             return False
 
+    def send_json_video_frame(self, msg: Dict[str, Any]) -> bool:
+        """Send a JSON video_frame message. Used for frames that carry extra
+        metadata (e.g. thermal cameras) that the binary format cannot express."""
+        if not self._authenticated.is_set():
+            return False
+        return self._send_frame(msg)
+
     # ------------------------------------------------------------------ thread
 
     def _run(self) -> None:

{plexus_python-0.5.2.dist-info → plexus_python-0.6.2.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: plexus-python
-Version: 0.5.2
+Version: 0.6.2
 Summary: Thin Python SDK for Plexus — send telemetry in one line
 Project-URL: Homepage, https://plexus.dev
 Project-URL: Documentation, https://docs.plexus.dev
@@ -23,11 +23,15 @@ Classifier: Topic :: System :: Hardware
 Requires-Python: >=3.10
 Requires-Dist: websocket-client>=1.7
 Provides-Extra: dev
+Requires-Dist: numpy>=1.24; extra == 'dev'
+Requires-Dist: opencv-python-headless>=4.8; extra == 'dev'
 Requires-Dist: pytest-cov; extra == 'dev'
 Requires-Dist: pytest>=9.0.3; extra == 'dev'
 Requires-Dist: ruff; extra == 'dev'
 Requires-Dist: websockets>=12; extra == 'dev'
 Provides-Extra: video
+Requires-Dist: numpy>=1.24; extra == 'video'
+Requires-Dist: opencv-python-headless>=4.8; extra == 'video'
 Requires-Dist: pillow>=12.2.0; extra == 'video'
 Description-Content-Type: text/markdown
 

plexus_python-0.6.2.dist-info/RECORD

@@ -0,0 +1,14 @@
+plexus/__init__.py,sha256=XFUsFY9sq7SzSuCP2D6NVAf8RxP0vsXROezHxPMY0ek,385
+plexus/_log.py,sha256=y1A9ahcPuCefTQ8xsZtOJTb6iT0pP9LAlkeP7U-yvGE,352
+plexus/buffer.py,sha256=3ykybqLs7yMXxQWFajAT8nGe3cs_lW8_6Xvn0vQ69dE,9262
+plexus/cli.py,sha256=-2wvHXQzobx3_tDGTXpaE2PlHv884y93Mu29kZE8qZE,14214
+plexus/client.py,sha256=1SzzqQDIx0B2zLDezO5cYpmwK8XeUrMd5jMdU7YB90M,36995
+plexus/config.py,sha256=wsG6lhNLmKe3JRlVycyRUKQeywnPUPPfrWkXFxYwELE,6179
+plexus/ws.py,sha256=_c--U-yySZbMXZsaj0fUaYKF_WesolHsrMDx4oWYfFQ,17428
+plexus/cameras/__init__.py,sha256=OvnU9KGKxkVtFLlk56H9x-ATa6UvpLI7PANa0HQO2cc,490
+plexus/cameras/thermal.py,sha256=-Ov8pgHGKtu5W-zyHRffVACDbsb50lpTmTGEbs_j4lg,12267
+plexus_python-0.6.2.dist-info/METADATA,sha256=kxGSad9N5G842Pjh_G4RvhJ6hdXrr9xEIjJHRhWXAr8,11739
+plexus_python-0.6.2.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+plexus_python-0.6.2.dist-info/entry_points.txt,sha256=YlkOtTn_7Q_IGuJaKdvpU-90dCeBSPx2p_UTGMAz5Zs,43
+plexus_python-0.6.2.dist-info/licenses/LICENSE,sha256=nm3qP1F-JAGcfLpRVtIX24L20LMnRpxmZ2oKZzFpLVo,10755
+plexus_python-0.6.2.dist-info/RECORD,,

plexus_python-0.5.2.dist-info/RECORD

@@ -1,12 +0,0 @@
-plexus/__init__.py,sha256=2Q3D7gMSFmMpFzcc_ywnCMH_1zgysy-PH6jW21bONgc,385
-plexus/_log.py,sha256=y1A9ahcPuCefTQ8xsZtOJTb6iT0pP9LAlkeP7U-yvGE,352
-plexus/buffer.py,sha256=3ykybqLs7yMXxQWFajAT8nGe3cs_lW8_6Xvn0vQ69dE,9262
-plexus/cli.py,sha256=-2wvHXQzobx3_tDGTXpaE2PlHv884y93Mu29kZE8qZE,14214
-plexus/client.py,sha256=S0AVpT73sKjMvDENZsWovk47ZuxZjT_vXQCAdNUVfG0,35338
-plexus/config.py,sha256=wsG6lhNLmKe3JRlVycyRUKQeywnPUPPfrWkXFxYwELE,6179
-plexus/ws.py,sha256=yTvxcloHOqiXkLtPQ4Vquv8KSrGoluOEkYIDp7MFImo,17095
-plexus_python-0.5.2.dist-info/METADATA,sha256=L87GlCwfwMIjXmetRak1E2vjkmdXyYj5v3nlzsFHtSU,11531
-plexus_python-0.5.2.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
-plexus_python-0.5.2.dist-info/entry_points.txt,sha256=YlkOtTn_7Q_IGuJaKdvpU-90dCeBSPx2p_UTGMAz5Zs,43
-plexus_python-0.5.2.dist-info/licenses/LICENSE,sha256=nm3qP1F-JAGcfLpRVtIX24L20LMnRpxmZ2oKZzFpLVo,10755
-plexus_python-0.5.2.dist-info/RECORD,,