@camera.ui/server 0.0.69 → 0.0.71-dev.0

package/dist/server/src/_camera_ui_tools/camera_ui_sdk/sensor/object.py

@@ -0,0 +1,210 @@
+from __future__ import annotations
+
+from abc import abstractmethod
+from collections.abc import Mapping
+from enum import Enum
+from typing import Any, Generic, Literal, Protocol, overload, runtime_checkable
+
+from typing_extensions import TypedDict, TypeVar
+
+from ..observable import Observable
+from .base import Sensor, SensorCategory, SensorLike, SensorType
+from .detection import Detection, DetectionLabel, VideoFrameData
+from .spec import ObjectModelSpec
+
+
+class ObjectProperty(str, Enum):
+    """Property names of an object detection sensor."""
+
+    Detected = "detected"  # Whether any object is currently detected
+    Detections = "detections"  # List of detected objects with labels and bounding boxes
+    Labels = "labels"  # Unique labels of the current detections (auto-derived when reporting detections)
+
+
+class TrackVelocity(TypedDict):
+    """Signed centroid velocity vector in normalized units per frame step.
+
+    Positive x = moving right, positive y = moving down. Consumers doing
+    motion prediction (PTZ autotrack, trajectory estimation) should use this
+    instead of deriving velocity from frame-to-frame position deltas.
+    """
+
+    x: float
+    y: float
+
+
+class TrackedDetection(Detection, total=False):
+    """Detection enriched with tracking metadata (stable IDs, velocity)."""
+
+    trackId: int  # Stable sequential ID for this object across frames
+    trackAge: int  # Number of frames this object has been continuously tracked
+    trackSpeed: float  # Velocity magnitude in normalized units per frame; 0 = stationary
+    trackVelocity: TrackVelocity  # Signed centroid velocity vector in normalized units per frame
+    trackLost: bool  # True if the object was not matched in the current frame
+
+
+class ObjectSensorProperties(TypedDict):
+    """Property shape carried by an ObjectSensor."""
+
+    detected: bool
+    detections: list[TrackedDetection]
+    labels: list[DetectionLabel]
+
+
+class ObjectPropertyChangeData(TypedDict):
+    """Property change payload emitted on ObjectSensorLike.onPropertyChanged."""
+
+    property: str  # ObjectProperty value
+    value: bool | list[Detection] | list[DetectionLabel]
+
+
+TStorage = TypeVar("TStorage", bound=Mapping[str, Any], default=dict[str, Any])
+
+
+@runtime_checkable
+class ObjectSensorLike(SensorLike, Protocol):
+    """Read-only proxy interface for an object detection sensor."""
+
+    @property
+    def type(self) -> SensorType:
+        return SensorType.Object
+
+    @overload
+    def getValue(self, property: Literal[ObjectProperty.Detected]) -> bool | None: ...
+    @overload
+    def getValue(self, property: Literal[ObjectProperty.Detections]) -> list[TrackedDetection] | None: ...
+    @overload
+    def getValue(self, property: Literal[ObjectProperty.Labels]) -> list[DetectionLabel] | None: ...
+    @overload
+    def getValue(self, property: str) -> object | None: ...
+
+    @property
+    def onPropertyChanged(self) -> Observable[ObjectPropertyChangeData]: ...
+
+
+class ObjectSensor(Sensor[ObjectSensorProperties, TStorage, str], Generic[TStorage]):
+    """Object detection sensor that reports detected objects (person, vehicle, animal, etc.).
+
+    Plugin authors call `reportDetections(list)` to push detection results.
+    `detected` and `labels` are auto-derived from the detection list.
+    """
+
+    _requires_frames = False
+
+    def __init__(self, name: str = "Object Sensor") -> None:
+        super().__init__(name)
+        self._write_state(
+            {
+                ObjectProperty.Detected.value: False,
+                ObjectProperty.Detections.value: [],
+                ObjectProperty.Labels.value: [],
+            }
+        )
+
+    @property
+    def type(self) -> SensorType:
+        return SensorType.Object
+
+    @property
+    def category(self) -> SensorCategory:
+        return SensorCategory.Sensor
+
+    @property
+    def detected(self) -> bool:
+        """Whether any object is currently detected."""
+        return bool(self.props.detected)
+
+    @property
+    def detections(self) -> list[TrackedDetection]:
+        """Current detection list."""
+        return self.props.detections or []
+
+    @property
+    def labels(self) -> list[DetectionLabel]:
+        """Unique labels of the current detections."""
+        return self.props.labels or []
+
+    def reportDetections(
+        self,
+        detected: bool,
+        detections: list[TrackedDetection] | None = None,
+    ) -> None:
+        """Report detected objects. Auto-derives ``detected`` and ``labels``
+        from the list.
+
+        - ``reportDetections(True)`` — something detected without specific data.
+          The SDK synthesizes a single full-frame ``'motion'`` detection as a
+          generic fallback.
+        - ``reportDetections(True, [...])`` — explicit detections (typical case).
+        - ``reportDetections(False)`` — clear.
+
+        Args:
+            detected: Whether any object is currently detected.
+            detections: Optional explicit object detections (with optional
+                tracking metadata).
+
+        Example:
+            ```python
+            sensor.reportDetections(
+                True,
+                [
+                    TrackedDetection(
+                        label="person",
+                        confidence=0.92,
+                        box=BoundingBox(x=0.1, y=0.2, width=0.3, height=0.4),
+                    )
+                ],
+            )
+            sensor.reportDetections(False)
+            ```
+        """
+        list_ = self._normalize_reported_detections(
+            detected,
+            detections,  # type: ignore[arg-type]
+            "motion",
+        )
+        labels = list(dict.fromkeys(d["label"] for d in list_))
+        self._write_state(
+            {
+                ObjectProperty.Detected.value: detected,
+                ObjectProperty.Detections.value: list_,
+                ObjectProperty.Labels.value: labels,
+            }
+        )
+
+    def clearDetections(self) -> None:
+        """Explicitly clear detection state (detected = False, detections = [], labels = [])."""
+        self.reportDetections(False)
+
+    async def updateValue(self, property: str, value: Any) -> None:
+        """Read-only sensor: external writes are ignored. State is reported via `reportDetections`."""
+        # No-op — object detection state is reported by the plugin, not set externally.
+
+
+class ObjectResult(TypedDict):
+    """Return type for ObjectDetectorSensor.detectObjects()."""
+
+    detected: bool  # Whether any object is detected in this frame
+    detections: list[TrackedDetection]  # Detections emitted for this frame
+
+
+class ObjectDetectorSensor(ObjectSensor[TStorage], Generic[TStorage]):
+    """Object detector that receives video frames from the backend pipeline.
+
+    Extend this class and implement ``detectObjects`` and ``modelSpec``. The
+    backend scales frames to match ``modelSpec.input`` dimensions before each
+    call.
+    """
+
+    _requires_frames = True
+
+    @property
+    @abstractmethod
+    def modelSpec(self) -> ObjectModelSpec:
+        """Declares the expected input dimensions. The backend scales frames to match."""
+        ...
+
+    @abstractmethod
+    async def detectObjects(self, frame: VideoFrameData) -> ObjectResult:
+        """Analyze a single video frame for objects. Called by the backend at the configured interval."""
+        ...

package/dist/server/src/_camera_ui_tools/camera_ui_sdk/sensor/occupancy.py

@@ -0,0 +1,88 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+from enum import Enum
+from typing import Any, Generic, Literal, Protocol, overload, runtime_checkable
+
+from typing_extensions import TypedDict, TypeVar
+
+from ..observable import Observable
+from .base import Sensor, SensorCategory, SensorLike, SensorType
+
+
+class OccupancyProperty(str, Enum):
+    """Properties for occupancy sensors."""
+
+    Detected = "detected"
+
+
+class OccupancySensorProperties(TypedDict):
+    """Property value map for occupancy sensors."""
+
+    detected: bool
+
+
+class OccupancyPropertyChangeData(TypedDict):
+    """Emitted on OccupancySensorLike.onPropertyChanged."""
+
+    property: str  # OccupancyProperty value
+    value: bool
+
+
+TStorage = TypeVar("TStorage", bound=Mapping[str, Any], default=dict[str, Any])
+
+
+@runtime_checkable
+class OccupancySensorLike(SensorLike, Protocol):
+    """Read-only proxy interface for an occupancy sensor."""
+
+    @property
+    def type(self) -> SensorType:
+        return SensorType.Occupancy
+
+    @overload
+    def getValue(self, property: Literal[OccupancyProperty.Detected]) -> bool | None: ...
+    @overload
+    def getValue(self, property: str) -> object | None: ...
+
+    @property
+    def onPropertyChanged(self) -> Observable[OccupancyPropertyChangeData]: ...
+
+
+class OccupancySensor(Sensor[OccupancySensorProperties, TStorage, str], Generic[TStorage]):
+    """Occupancy sensor for detecting presence in a room or area."""
+
+    _requires_frames = False
+
+    def __init__(self, name: str = "Occupancy Sensor") -> None:
+        super().__init__(name)
+        self._write_state({OccupancyProperty.Detected.value: False})
+
+    @property
+    def type(self) -> SensorType:
+        return SensorType.Occupancy
+
+    @property
+    def category(self) -> SensorCategory:
+        return SensorCategory.Sensor
+
+    @property
+    def detected(self) -> bool:
+        return bool(self.props.detected)
+
+    def setDetected(self, value: bool) -> None:
+        """Report occupancy state.
+
+        Args:
+            value: True when the area is currently occupied.
+
+        Example:
+            ```python
+            occupancy.setDetected(True)
+            ```
+        """
+        self._write_state({OccupancyProperty.Detected.value: value})
+
+    async def updateValue(self, property: str, value: Any) -> None:
+        """Read-only sensor: external writes are ignored."""
+        # No-op — occupancy state is reported by the plugin, not set externally.

package/dist/server/src/_camera_ui_tools/camera_ui_sdk/sensor/ptz.py

@@ -0,0 +1,256 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+from enum import Enum
+from typing import Any, Generic, Literal, NotRequired, Protocol, overload, runtime_checkable
+
+from typing_extensions import TypedDict, TypeVar
+
+from ..observable import Observable
+from .base import Sensor, SensorCategory, SensorLike, SensorType
+
+
+class PTZCapability(str, Enum):
+    """Optional capabilities for PTZ controls."""
+
+    Pan = "pan"
+    Tilt = "tilt"
+    Zoom = "zoom"
+    Presets = "presets"
+    Home = "home"
+
+
+class PTZProperty(str, Enum):
+    """Properties for PTZ controls."""
+
+    Position = "position"
+    Moving = "moving"
+    Presets = "presets"
+    Velocity = "velocity"
+    TargetPreset = "targetPreset"
+
+
+class PTZPosition(TypedDict):
+    """Absolute PTZ position."""
+
+    pan: float
+    tilt: float
+    zoom: float
+
+
+class PTZDirection(TypedDict):
+    """PTZ movement speed for continuous move commands.
+
+    Speeds are in normalized range ``[-1, 1]`` where:
+
+    - ``-1`` = maximum speed in negative direction
+    - ``0`` = stop movement
+    - ``1`` = maximum speed in positive direction
+
+    Conventions: positive ``panSpeed`` = right, positive ``tiltSpeed`` = up,
+    positive ``zoomSpeed`` = zoom in. Plugins should clamp values to ``[-1, 1]``
+    and map them to hardware-specific speeds.
+    """
+
+    panSpeed: float
+    tiltSpeed: float
+    zoomSpeed: float
+
+
+class PTZControlProperties(TypedDict):
+    """Property value map for PTZ controls."""
+
+    position: PTZPosition
+    moving: bool
+    presets: list[str]
+    velocity: NotRequired[PTZDirection | None]
+    targetPreset: NotRequired[str | None]
+
+
+class PTZPropertyChangeData(TypedDict):
+    """Emitted on PTZControlLike.onPropertyChanged."""
+
+    property: str  # PTZProperty value
+    value: PTZPosition | bool | list[str] | PTZDirection | str | None
+
+
+TStorage = TypeVar("TStorage", bound=Mapping[str, Any], default=dict[str, Any])
+
+
+@runtime_checkable
+class PTZControlLike(SensorLike, Protocol):
+    """Read-only proxy interface for a PTZ control."""
+
+    @property
+    def type(self) -> SensorType:
+        return SensorType.PTZ
+
+    @overload
+    def getValue(self, property: Literal[PTZProperty.Position]) -> PTZPosition | None: ...
+    @overload
+    def getValue(self, property: Literal[PTZProperty.Moving]) -> bool | None: ...
+    @overload
+    def getValue(self, property: Literal[PTZProperty.Presets]) -> list[str] | None: ...
+    @overload
+    def getValue(self, property: Literal[PTZProperty.Velocity]) -> PTZDirection | None: ...
+    @overload
+    def getValue(self, property: Literal[PTZProperty.TargetPreset]) -> str | None: ...
+    @overload
+    def getValue(self, property: str) -> object | None: ...
+
+    @property
+    def onPropertyChanged(self) -> Observable[PTZPropertyChangeData]: ...
+
+    @property
+    def onCapabilitiesChanged(self) -> Observable[list[PTZCapability]]: ...
+
+
+class PTZControl(Sensor[PTZControlProperties, TStorage, PTZCapability], Generic[TStorage]):
+    """Pan-tilt-zoom camera control.
+
+    Override `setPosition()` / `setVelocity()` / `setTargetPreset()` to drive
+    hardware, then call the corresponding `super().X()` method after success to
+    sync the SDK state. For hardware-pushed state updates (e.g. PTZ position
+    change events), call the super methods from your event handler — that
+    bypasses any plugin override and only syncs state.
+
+    Set `capabilities` to advertise supported axes and features. Use
+    `setPresets()` to publish the discovered preset list and `setMoving()` to
+    publish movement state.
+    """
+
+    _requires_frames = False
+
+    def __init__(self, name: str = "PTZ") -> None:
+        super().__init__(name)
+        self._write_state(
+            {
+                PTZProperty.Position.value: {"pan": 0, "tilt": 0, "zoom": 0},
+                PTZProperty.Moving.value: False,
+                PTZProperty.Presets.value: [],
+            }
+        )
+
+    @property
+    def type(self) -> SensorType:
+        return SensorType.PTZ
+
+    @property
+    def category(self) -> SensorCategory:
+        return SensorCategory.Control
+
+    @property
+    def position(self) -> PTZPosition:
+        return self.props.position  # type: ignore[no-any-return]
+
+    @property
+    def moving(self) -> bool:
+        return bool(self.props.moving)
+
+    @property
+    def presets(self) -> list[str]:
+        return self.props.presets or []
+
+    @property
+    def velocity(self) -> PTZDirection | None:
+        return self.props.velocity  # type: ignore[no-any-return]
+
+    @property
+    def targetPreset(self) -> str | None:
+        return self.props.targetPreset  # type: ignore[no-any-return]
+
+    async def setPosition(self, value: PTZPosition) -> None:
+        """Move to an absolute pan/tilt/zoom position. Override to drive hardware
+        and call `await super().setPosition(value)` after success to sync the SDK state.
+
+        Args:
+            value: Absolute pan/tilt/zoom target position.
+
+        Example:
+            ```python
+            await ptz.setPosition({"pan": 0.25, "tilt": -0.1, "zoom": 0.5})
+            ```
+        """
+        self._write_state({PTZProperty.Position.value: value})
+
+    async def setVelocity(self, value: PTZDirection | None) -> None:
+        """Continuous-move command. Override to drive hardware and call
+        `await super().setVelocity(value)` after success to sync the SDK state.
+
+        Args:
+            value: Per-axis speeds in ``[-1, 1]``, or ``None`` to stop.
+
+        Example:
+            ```python
+            await ptz.setVelocity({"panSpeed": 0.5, "tiltSpeed": 0, "zoomSpeed": 0})
+            await ptz.setVelocity(None)  # stop
+            ```
+        """
+        self._write_state({PTZProperty.Velocity.value: value})
+
+    async def setTargetPreset(self, value: str | None) -> None:
+        """Preset-move command. Override to drive hardware and call
+        `await super().setTargetPreset(value)` after success to sync the SDK state.
+
+        Args:
+            value: Preset name to move to, or ``None`` to clear.
+
+        Example:
+            ```python
+            await ptz.setTargetPreset("Driveway")
+            ```
+        """
+        self._write_state({PTZProperty.TargetPreset.value: value})
+
+    def setPresets(self, value: list[str]) -> None:
+        """Publish the discovered preset list (typically called once at startup).
+
+        Args:
+            value: List of preset names supported by the camera.
+
+        Example:
+            ```python
+            ptz.setPresets(["Home", "Driveway", "Backyard"])
+            ```
+        """
+        self._write_state({PTZProperty.Presets.value: value})
+
+    def setMoving(self, value: bool) -> None:
+        """Publish movement state (e.g. when continuous-move starts/stops).
+
+        Args:
+            value: True while the camera is moving.
+
+        Example:
+            ```python
+            ptz.setMoving(True)
+            ```
+        """
+        self._write_state({PTZProperty.Moving.value: value})
+
+    async def goHome(self) -> None:
+        """Move the camera to the home position (pan=0, tilt=0, zoom=0).
+
+        Example:
+            ```python
+            await ptz.goHome()
+            ```
+        """
+        await self.setPosition({"pan": 0, "tilt": 0, "zoom": 0})
+
+    async def updateValue(self, property: str, value: Any) -> None:
+        """Routes generic property writes to semantic methods.
+
+        `moving` and `presets` are observed/discovered state and not externally
+        writable; only `Position`, `Velocity`, and `TargetPreset` may be set.
+        """
+        if property == PTZProperty.Position.value:
+            await self.setPosition(value)
+            return
+        if property == PTZProperty.Velocity.value:
+            await self.setVelocity(value)
+            return
+        if property == PTZProperty.TargetPreset.value:
+            await self.setTargetPreset(value)
+            return
+        # Unknown / non-writable property (incl. moving, presets) — ignored.