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

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

@@ -0,0 +1,186 @@
+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, VideoFrameData
+from .spec import ModelSpec
+
+
+class LicensePlateProperty(str, Enum):
+    """Property names of a license plate detection sensor."""
+
+    Detected = "detected"  # Whether any license plate is currently detected
+    Detections = "detections"  # List of detected plates with OCR text
+
+
+class LicensePlateDetection(Detection):
+    """A license plate detection result, extending Detection with OCR fields."""
+
+    attribute: Literal["license_plate"]  # type: ignore[misc]  # Sub-detection attribute, fixed to "license_plate"
+    plateText: str  # Recognized plate text (e.g. "ABC 1234")
+
+
+class LicensePlateSensorProperties(TypedDict):
+    """Property shape carried by a LicensePlateSensor."""
+
+    detected: bool
+    detections: list[LicensePlateDetection]
+
+
+class LicensePlatePropertyChangeData(TypedDict):
+    """Property change payload emitted on LicensePlateSensorLike.onPropertyChanged."""
+
+    property: str  # LicensePlateProperty value
+    value: bool | list[LicensePlateDetection]
+
+
+TStorage = TypeVar("TStorage", bound=Mapping[str, Any], default=dict[str, Any])
+
+
+@runtime_checkable
+class LicensePlateSensorLike(SensorLike, Protocol):
+    """Read-only proxy interface for a license plate sensor."""
+
+    @property
+    def type(self) -> SensorType:
+        return SensorType.LicensePlate
+
+    @overload
+    def getValue(self, property: Literal[LicensePlateProperty.Detected]) -> bool | None: ...
+    @overload
+    def getValue(
+        self, property: Literal[LicensePlateProperty.Detections]
+    ) -> list[LicensePlateDetection] | None: ...
+    @overload
+    def getValue(self, property: str) -> object | None: ...
+
+    @property
+    def onPropertyChanged(self) -> Observable[LicensePlatePropertyChangeData]: ...
+
+
+class LicensePlateSensor(Sensor[LicensePlateSensorProperties, TStorage, str], Generic[TStorage]):
+    """License plate sensor that reports detected plates with OCR text.
+
+    Plugin authors call `reportDetections(list)` to push detected plates.
+    `detected` is auto-derived from the detection list.
+    """
+
+    _requires_frames = False
+
+    def __init__(self, name: str = "License Plate Sensor") -> None:
+        super().__init__(name)
+        self._write_state(
+            {
+                LicensePlateProperty.Detected.value: False,
+                LicensePlateProperty.Detections.value: [],
+            }
+        )
+
+    @property
+    def type(self) -> SensorType:
+        return SensorType.LicensePlate
+
+    @property
+    def category(self) -> SensorCategory:
+        return SensorCategory.Sensor
+
+    @property
+    def detected(self) -> bool:
+        """Whether any license plate is currently detected."""
+        return bool(self.props.detected)
+
+    @property
+    def detections(self) -> list[LicensePlateDetection]:
+        """Current detection list."""
+        return self.props.detections or []
+
+    def reportDetections(
+        self,
+        detected: bool,
+        detections: list[LicensePlateDetection] | None = None,
+    ) -> None:
+        """Report detected license plates.
+
+        - ``reportDetections(True)`` — plate detected without specifics. The SDK
+          synthesizes a single full-frame detection with empty plateText.
+        - ``reportDetections(True, [...])`` — explicit plate detections with OCR text.
+        - ``reportDetections(False)`` — clear.
+
+        Args:
+            detected: Whether any license plate is currently detected.
+            detections: Optional explicit plate detections to publish.
+
+        Example:
+            ```python
+            sensor.reportDetections(
+                True,
+                [
+                    LicensePlateDetection(
+                        label="vehicle",
+                        confidence=0.93,
+                        box=BoundingBox(x=0.2, y=0.5, width=0.2, height=0.08),
+                        attribute="license_plate",
+                        plateText="ABC 1234",
+                    )
+                ],
+            )
+            sensor.reportDetections(False)
+            ```
+        """
+        list_ = self._normalize_reported_detections(
+            detected,
+            detections,  # type: ignore[arg-type]
+            "vehicle",
+            {"attribute": "license_plate", "plateText": ""},
+        )
+        self._write_state(
+            {
+                LicensePlateProperty.Detected.value: detected,
+                LicensePlateProperty.Detections.value: list_,
+            }
+        )
+
+    def clearDetections(self) -> None:
+        """Explicitly clear license plate state (detected = False, detections = [])."""
+        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 — license plate state is reported by the plugin, not set externally.
+
+
+class LicensePlateResult(TypedDict):
+    """Return type for LicensePlateDetectorSensor.detectLicensePlates()."""
+
+    detected: bool  # Whether any license plate is detected in this frame
+    detections: list[LicensePlateDetection]  # Detections emitted for this frame
+
+
+class LicensePlateDetectorSensor(LicensePlateSensor[TStorage], Generic[TStorage]):
+    """License plate detector that receives video frames from the backend pipeline.
+
+    Extend this class and implement ``detectLicensePlates`` for plate detection
+    and OCR.
+    """
+
+    _requires_frames = True
+
+    @property
+    @abstractmethod
+    def modelSpec(self) -> ModelSpec:
+        """Declares the expected input dimensions and trigger labels. The backend scales frames to match."""
+        ...
+
+    @abstractmethod
+    async def detectLicensePlates(self, frames: list[VideoFrameData]) -> list[LicensePlateResult]:
+        """Detect license plates in batch. Each frame is a pre-cropped, pre-scaled vehicle region
+        produced by the upstream object detector. Must return exactly one LicensePlateResult per
+        input frame, in the same order."""
+        ...

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

@@ -0,0 +1,157 @@
+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 LightCapability(str, Enum):
+    """Optional capabilities for light controls."""
+
+    Brightness = "brightness"
+    """Light supports brightness adjustment (0–100)."""
+
+
+class LightProperty(str, Enum):
+    """Properties for light controls."""
+
+    On = "on"
+    Brightness = "brightness"
+
+
+class LightControlProperties(TypedDict):
+    """Property value map for light controls."""
+
+    on: bool
+    brightness: int
+
+
+class LightPropertyChangeData(TypedDict):
+    """Emitted on LightControlLike.onPropertyChanged."""
+
+    property: str  # LightProperty value
+    value: bool | int
+
+
+TStorage = TypeVar("TStorage", bound=Mapping[str, Any], default=dict[str, Any])
+
+
+@runtime_checkable
+class LightControlLike(SensorLike, Protocol):
+    """Read-only proxy interface for a light control."""
+
+    @property
+    def type(self) -> SensorType:
+        return SensorType.Light
+
+    @overload
+    def getValue(self, property: Literal[LightProperty.On]) -> bool | None: ...
+    @overload
+    def getValue(self, property: Literal[LightProperty.Brightness]) -> int | None: ...
+    @overload
+    def getValue(self, property: str) -> object | None: ...
+
+    @property
+    def onPropertyChanged(self) -> Observable[LightPropertyChangeData]: ...
+
+    @property
+    def onCapabilitiesChanged(self) -> Observable[list[LightCapability]]: ...
+
+
+class LightControl(Sensor[LightControlProperties, TStorage, LightCapability], Generic[TStorage]):
+    """Light control sensor. Override ``setOn()``/``setOff()`` to drive your
+    hardware, then ``await super().setOn()`` / ``await super().setOff()`` to
+    sync the SDK state.
+
+    Plugins that have no hardware-action use case can leave the methods
+    unoverridden — the base implementation just updates the state.
+
+    For hardware-pushed updates (someone manually flipped the switch), call
+    ``super().setOn()`` / ``super().setOff()`` from your event handler — that
+    bypasses any plugin override and only syncs state.
+    """
+
+    _requires_frames = False
+
+    def __init__(self, name: str = "Light") -> None:
+        super().__init__(name)
+        self._write_state(
+            {
+                LightProperty.On.value: False,
+                LightProperty.Brightness.value: 100,
+            }
+        )
+
+    @property
+    def type(self) -> SensorType:
+        return SensorType.Light
+
+    @property
+    def category(self) -> SensorCategory:
+        return SensorCategory.Control
+
+    @property
+    def on(self) -> bool:
+        return bool(self.props.on)
+
+    @property
+    def brightness(self) -> int:
+        value = self.props.brightness
+        return int(value) if value is not None else 0
+
+    async def setOn(self) -> None:
+        """Turn the light on. Override to drive hardware and call
+        ``await super().setOn()`` after the hardware call succeeds to sync the
+        SDK state.
+
+        Example:
+            ```python
+            await light.setOn()
+            ```
+        """
+        self._write_state({LightProperty.On.value: True})
+
+    async def setOff(self) -> None:
+        """Turn the light off. Override to drive hardware and call
+        ``await super().setOff()`` after the hardware call succeeds to sync the
+        SDK state.
+
+        Example:
+            ```python
+            await light.setOff()
+            ```
+        """
+        self._write_state({LightProperty.On.value: False})
+
+    async def setBrightness(self, value: int) -> None:
+        """Set brightness. Override to drive hardware and call
+        ``await super().setBrightness(value)`` after the hardware call
+        succeeds. The default implementation clamps the value to [0, 100].
+
+        Args:
+            value: Brightness level in the range 0–100.
+
+        Example:
+            ```python
+            await light.setBrightness(75)
+            ```
+        """
+        self._write_state({LightProperty.Brightness.value: max(0, min(100, value))})
+
+    async def updateValue(self, property: str, value: Any) -> None:
+        """Routes generic property writes to semantic methods."""
+        if property == LightProperty.On.value:
+            if value:
+                await self.setOn()
+            else:
+                await self.setOff()
+            return
+        if property == LightProperty.Brightness.value:
+            await self.setBrightness(int(value))
+            return
+        # Unknown / non-writable property — ignored.

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

@@ -0,0 +1,149 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+from enum import Enum, IntEnum
+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 LockState(IntEnum):
+    """Lock states (HomeKit-compatible values)."""
+
+    Secured = 0
+    Unsecured = 1
+    Unknown = 2
+
+
+class LockProperty(str, Enum):
+    """Properties for lock controls."""
+
+    CurrentState = "currentState"
+    TargetState = "targetState"
+
+
+class LockControlProperties(TypedDict):
+    """Property value map for lock controls."""
+
+    currentState: int
+    targetState: int
+
+
+class LockPropertyChangeData(TypedDict):
+    """Emitted on LockControlLike.onPropertyChanged."""
+
+    property: str  # LockProperty value
+    value: LockState
+
+
+TStorage = TypeVar("TStorage", bound=Mapping[str, Any], default=dict[str, Any])
+
+
+@runtime_checkable
+class LockControlLike(SensorLike, Protocol):
+    """Read-only proxy interface for a lock control."""
+
+    @property
+    def type(self) -> SensorType:
+        return SensorType.Lock
+
+    @overload
+    def getValue(self, property: Literal[LockProperty.CurrentState]) -> LockState | None: ...
+    @overload
+    def getValue(self, property: Literal[LockProperty.TargetState]) -> LockState | None: ...
+    @overload
+    def getValue(self, property: str) -> object | None: ...
+
+    @property
+    def onPropertyChanged(self) -> Observable[LockPropertyChangeData]: ...
+
+
+class LockControl(Sensor[LockControlProperties, TStorage, str], Generic[TStorage]):
+    """Lock control.
+
+    Override `setTargetState()` to drive hardware and call
+    `await super().setTargetState(value)` once the hardware confirms — the base
+    implementation updates both `targetState` and `currentState` to the new value.
+
+    For asymmetric flows (long-running unlock with intermediate state) override
+    `setTargetState` and write `currentState` separately when transitions complete.
+    """
+
+    _requires_frames = False
+
+    def __init__(self, name: str = "Lock") -> None:
+        super().__init__(name)
+        self._write_state(
+            {
+                LockProperty.CurrentState.value: int(LockState.Secured),
+                LockProperty.TargetState.value: int(LockState.Secured),
+            }
+        )
+
+    @property
+    def type(self) -> SensorType:
+        return SensorType.Lock
+
+    @property
+    def category(self) -> SensorCategory:
+        return SensorCategory.Control
+
+    @property
+    def currentState(self) -> LockState:
+        value = self.props.currentState
+        return LockState(value) if value is not None else LockState.Secured
+
+    @property
+    def targetState(self) -> LockState:
+        value = self.props.targetState
+        return LockState(value) if value is not None else LockState.Secured
+
+    async def setTargetState(self, value: LockState) -> None:
+        """Set the target state. Override to drive hardware and call
+        `await super().setTargetState(value)` after success — the base implementation
+        syncs both `targetState` and `currentState` to the new value.
+
+        Args:
+            value: Desired lock state from the ``LockState`` enum.
+
+        Example:
+            ```python
+            from camera_ui_sdk import LockState
+
+            await lock.setTargetState(LockState.Secured)
+            ```
+        """
+        self._write_state(
+            {
+                LockProperty.TargetState.value: int(value),
+                LockProperty.CurrentState.value: int(value),
+            }
+        )
+
+    def setCurrentState(self, value: LockState) -> None:
+        """Publish the actual lock state. Use this to drive transitions where
+        the physical state diverges from the user-requested target — e.g.
+        motorized smart locks that take time to rotate (publish ``Unknown``
+        while moving), or hardware reporting an out-of-band state change.
+        Read-only from cross-process consumers (``updateValue`` ignores it).
+
+        Args:
+            value: Current physical lock state from the ``LockState`` enum.
+
+        Example:
+            ```python
+            from camera_ui_sdk import LockState
+
+            lock.setCurrentState(LockState.Unknown)
+            ```
+        """
+        self._write_state({LockProperty.CurrentState.value: int(value)})
+
+    async def updateValue(self, property: str, value: Any) -> None:
+        """Routes generic property writes to semantic methods."""
+        if property == LockProperty.TargetState.value:
+            await self.setTargetState(LockState(value))
+        # Unknown / non-writable property (incl. currentState) — ignored.

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

@@ -0,0 +1,203 @@
+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_ATTRIBUTES,
+    DETECTION_LABELS,
+    BoundingBox,
+    Detection,
+    DetectionAttribute,
+    DetectionLabel,
+    VideoFrameData,
+)
+
+# Re-exports kept for backward compatibility — original public surface of this module.
+__all__ = [
+    "BoundingBox",
+    "DETECTION_ATTRIBUTES",
+    "DETECTION_LABELS",
+    "Detection",
+    "DetectionAttribute",
+    "DetectionLabel",
+    "MotionDetectorSensor",
+    "MotionProperty",
+    "MotionPropertyChangeData",
+    "MotionResult",
+    "MotionSensor",
+    "MotionSensorLike",
+    "MotionSensorProperties",
+    "VideoFrameData",
+]
+
+
+class MotionProperty(str, Enum):
+    """Property names of a motion sensor."""
+
+    Detected = "detected"  # Whether motion is currently detected
+    Detections = "detections"  # List of detection results with bounding boxes
+    Blocked = "blocked"  # When true, detection updates are suppressed (set by the backend dwell logic)
+    LastTriggered = (
+        "lastTriggered"  # Timestamp in milliseconds of the last detection trigger, set by the backend
+    )
+
+
+class MotionSensorProperties(TypedDict):
+    """Property shape carried by a MotionSensor."""
+
+    detected: bool
+    detections: list[Detection]
+    blocked: bool
+
+
+class MotionPropertyChangeData(TypedDict):
+    """Property change payload emitted on MotionSensorLike.onPropertyChanged."""
+
+    property: str  # MotionProperty value
+    value: bool | list[Detection]
+
+
+TStorage = TypeVar("TStorage", bound=Mapping[str, Any], default=dict[str, Any])
+
+
+@runtime_checkable
+class MotionSensorLike(SensorLike, Protocol):
+    """Read-only proxy interface for a motion sensor."""
+
+    @property
+    def type(self) -> SensorType:
+        return SensorType.Motion
+
+    @overload
+    def getValue(self, property: Literal[MotionProperty.Detected]) -> bool | None: ...
+    @overload
+    def getValue(self, property: Literal[MotionProperty.Detections]) -> list[Detection] | None: ...
+    @overload
+    def getValue(self, property: Literal[MotionProperty.Blocked]) -> bool | None: ...
+    @overload
+    def getValue(self, property: str) -> object | None: ...
+
+    @property
+    def onPropertyChanged(self) -> Observable[MotionPropertyChangeData]: ...
+
+
+class MotionSensor(Sensor[MotionSensorProperties, TStorage, str], Generic[TStorage]):
+    """Motion sensor that reports motion state and detection results.
+
+    Plugin authors call `reportDetections(list)` to push detection results.
+    `detected` is auto-derived from the detection list. `blocked` is read-only
+    and is set by the backend (dwell logic) — `reportDetections()` becomes a
+    no-op while the sensor is blocked.
+    """
+
+    _requires_frames = False
+
+    def __init__(self, name: str = "Motion Sensor") -> None:
+        super().__init__(name)
+        self._write_state(
+            {
+                MotionProperty.Detected.value: False,
+                MotionProperty.Detections.value: [],
+                MotionProperty.Blocked.value: False,
+            }
+        )
+
+    @property
+    def type(self) -> SensorType:
+        return SensorType.Motion
+
+    @property
+    def category(self) -> SensorCategory:
+        return SensorCategory.Sensor
+
+    @property
+    def detected(self) -> bool:
+        """Whether motion is currently detected."""
+        return bool(self.props.detected)
+
+    @property
+    def detections(self) -> list[Detection]:
+        """Current detection list."""
+        return self.props.detections or []
+
+    @property
+    def blocked(self) -> bool:
+        """Whether the sensor is currently blocked. Read-only — set by the backend dwell logic, not by plugin code."""
+        return bool(self.props.blocked)
+
+    def reportDetections(self, detected: bool, detections: list[Detection] | None = None) -> None:
+        """Report a motion detection result.
+
+        - ``reportDetections(True)`` — motion detected without bbox (e.g. Ring camera).
+          The SDK synthesizes a single full-frame ``'motion'`` detection.
+        - ``reportDetections(True, [...])`` — motion detected with explicit detections.
+        - ``reportDetections(False)`` — no motion (clears detections).
+
+        No-op while the sensor is blocked by backend dwell logic.
+
+        Args:
+            detected: Whether motion is currently detected.
+            detections: Optional explicit detections produced for this frame.
+
+        Example:
+            ```python
+            sensor.reportDetections(
+                True,
+                [
+                    Detection(
+                        label="motion",
+                        confidence=0.85,
+                        box=BoundingBox(x=0.1, y=0.2, width=0.3, height=0.4),
+                    )
+                ],
+            )
+            sensor.reportDetections(False)
+            ```
+        """
+        if self.blocked:
+            return
+        list_ = self._normalize_reported_detections(detected, detections, "motion")  # type: ignore[arg-type]
+        self._write_state(
+            {
+                MotionProperty.Detected.value: detected,
+                MotionProperty.Detections.value: list_,
+            }
+        )
+
+    def clearDetections(self) -> None:
+        """Explicitly clear motion state (detected = False, detections = [])."""
+        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 — motion state is reported by the plugin, not set externally.
+
+
+class MotionResult(TypedDict):
+    """Return type for MotionDetectorSensor.detectMotion()."""
+
+    detected: bool  # Whether motion is detected in this frame
+    detections: list[Detection]  # Detections emitted for this frame
+
+
+class MotionDetectorSensor(MotionSensor[TStorage], Generic[TStorage]):
+    """Motion detector that receives video frames from the backend pipeline.
+
+    Extend this class and implement ``detectMotion`` to analyze frames for
+    motion. The backend calls ``detectMotion`` at the configured frame
+    interval and applies the returned result to the sensor.
+    """
+
+    _requires_frames = True
+
+    @abstractmethod
+    async def detectMotion(self, frame: VideoFrameData) -> MotionResult:
+        """Analyze a single video frame for motion. Called by the backend at the configured interval."""
+        ...