rocket-welder-sdk 1.1.43__py3-none-any.whl → 1.1.45__py3-none-any.whl

rocket_welder_sdk/confidence.py

@@ -0,0 +1,206 @@
+"""
+Confidence value type for ML detection results.
+Matches C# Confidence struct from RocketWelder.SDK.Protocols.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import ClassVar, Optional, Union
+
+
+@dataclass(frozen=True)
+class Confidence:
+    """
+    Represents a confidence score for ML detection results.
+
+    Internally stored as ushort (0-65535) for full precision.
+    Provides normalized float (0.0-1.0) for easy usage.
+
+    Examples:
+        >>> # Create from float (0.0-1.0)
+        >>> c1 = Confidence.from_float(0.95)
+        >>>
+        >>> # Create from raw ushort (0-65535)
+        >>> c2 = Confidence(raw=65535)
+        >>>
+        >>> # Get normalized float
+        >>> normalized = c1.normalized  # 0.95
+        >>>
+        >>> # Compare with float
+        >>> if c1 > 0.9:
+        ...     print("High confidence")
+        >>>
+        >>> # Get raw ushort value
+        >>> raw_value = c1.raw
+    """
+
+    MAX_RAW: ClassVar[int] = 65535  # ushort.MaxValue
+
+    raw: int
+    """The raw ushort value (0-65535)."""
+
+    def __post_init__(self) -> None:
+        """Validate raw value is in valid range."""
+        if not 0 <= self.raw <= Confidence.MAX_RAW:
+            raise ValueError(
+                f"Raw value must be between 0 and {Confidence.MAX_RAW}, got {self.raw}"
+            )
+
+    @property
+    def normalized(self) -> float:
+        """Get the normalized float value (0.0-1.0)."""
+        return self.raw / Confidence.MAX_RAW
+
+    @classmethod
+    def from_float(cls, value: float) -> Confidence:
+        """
+        Create Confidence from a float value (0.0-1.0).
+
+        The value is clamped to [0.0, 1.0] range before conversion.
+
+        Args:
+            value: Float value in range 0.0 to 1.0
+
+        Returns:
+            Confidence instance
+        """
+        clamped = max(0.0, min(1.0, value))
+        raw = int(clamped * cls.MAX_RAW)
+        return cls(raw=raw)
+
+    @classmethod
+    def full(cls) -> Confidence:
+        """Full confidence (1.0)."""
+        return cls(raw=cls.MAX_RAW)
+
+    @classmethod
+    def zero(cls) -> Confidence:
+        """Zero confidence (0.0)."""
+        return cls(raw=0)
+
+    @classmethod
+    def parse(cls, value: Union[str, int, float, Confidence]) -> Confidence:
+        """
+        Parse a string, number, or Confidence into a Confidence object.
+
+        Equivalent to C# IParsable<Confidence>.Parse().
+
+        Args:
+            value: Value to parse (e.g., "0.95", 0.95, 65535)
+
+        Returns:
+            Confidence instance
+
+        Raises:
+            ValueError: If the value cannot be parsed
+        """
+        if isinstance(value, Confidence):
+            return value
+
+        if isinstance(value, int):
+            if 0 <= value <= cls.MAX_RAW:
+                return cls(raw=value)
+            raise ValueError(f"Integer value must be between 0 and {cls.MAX_RAW}, got {value}")
+
+        if isinstance(value, float):
+            return cls.from_float(value)
+
+        if isinstance(value, str):
+            value = value.strip()
+            if not value:
+                raise ValueError("Cannot parse empty string as Confidence")
+
+            # Try parsing as percentage (e.g., "95.0%")
+            if value.endswith("%"):
+                try:
+                    percent = float(value[:-1])
+                    return cls.from_float(percent / 100.0)
+                except ValueError as e:
+                    raise ValueError(f"Invalid percentage format: '{value}'") from e
+
+            # Try parsing as float (0.0-1.0)
+            try:
+                float_val = float(value)
+                if 0.0 <= float_val <= 1.0:
+                    return cls.from_float(float_val)
+                # If > 1.0, treat as raw ushort value
+                if float_val == int(float_val) and 0 <= float_val <= cls.MAX_RAW:
+                    return cls(raw=int(float_val))
+                raise ValueError(
+                    f"Float value must be 0.0-1.0 or integer 0-{cls.MAX_RAW}, got {float_val}"
+                )
+            except ValueError:
+                raise ValueError(f"Invalid Confidence format: '{value}'") from None
+
+        raise ValueError(f"Cannot parse {type(value).__name__} as Confidence")
+
+    @classmethod
+    def try_parse(cls, value: Union[str, int, float, Confidence]) -> Optional[Confidence]:
+        """
+        Try to parse a value into Confidence, returning None on failure.
+
+        Args:
+            value: Value to parse
+
+        Returns:
+            Confidence instance or None if parsing failed
+        """
+        try:
+            return cls.parse(value)
+        except (ValueError, TypeError):
+            return None
+
+    def __float__(self) -> float:
+        """Convert to float (normalized value)."""
+        return self.normalized
+
+    def __int__(self) -> int:
+        """Convert to int (raw value)."""
+        return self.raw
+
+    def __str__(self) -> str:
+        """Return the normalized value as a percentage string (e.g., '95.0%')."""
+        return f"{self.normalized:.1%}"
+
+    def __repr__(self) -> str:
+        """Developer-friendly representation."""
+        return f"Confidence(raw={self.raw}, normalized={self.normalized:.4f})"
+
+    # Comparison operators with float
+    def __lt__(self, other: object) -> bool:
+        """Less than comparison."""
+        if isinstance(other, Confidence):
+            return self.raw < other.raw
+        if isinstance(other, (int, float)):
+            return self.normalized < other
+        return NotImplemented
+
+    def __le__(self, other: object) -> bool:
+        """Less than or equal comparison."""
+        if isinstance(other, Confidence):
+            return self.raw <= other.raw
+        if isinstance(other, (int, float)):
+            return self.normalized <= other
+        return NotImplemented
+
+    def __gt__(self, other: object) -> bool:
+        """Greater than comparison."""
+        if isinstance(other, Confidence):
+            return self.raw > other.raw
+        if isinstance(other, (int, float)):
+            return self.normalized > other
+        return NotImplemented
+
+    def __ge__(self, other: object) -> bool:
+        """Greater than or equal comparison."""
+        if isinstance(other, Confidence):
+            return self.raw >= other.raw
+        if isinstance(other, (int, float)):
+            return self.normalized >= other
+        return NotImplemented
+
+
+# Convenience constants matching C# static properties
+FULL = Confidence.full()
+ZERO = Confidence.zero()

rocket_welder_sdk/delta_frame.py

@@ -0,0 +1,150 @@
+"""
+DeltaFrame generic container for delta-encoded streaming data.
+Matches C# DeltaFrame<T> struct from RocketWelder.SDK.Protocols.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Generic, Iterator, Sequence, TypeVar
+
+# TypeVar for the item type (equivalent to C# struct constraint)
+T = TypeVar("T")
+
+
+@dataclass(frozen=True)
+class DeltaFrame(Generic[T]):
+    """
+    Generic container for delta-encoded streaming data.
+
+    Used by Reader/Source classes where IsDelta is needed for decoding.
+    When IsDelta is True, the items contain delta-encoded values relative
+    to the previous frame, otherwise they contain absolute values.
+
+    Type Parameters:
+        T: The item type (e.g., KeyPoint, SegmentationInstance)
+
+    Attributes:
+        frame_id: The frame identifier (ulong equivalent).
+        is_delta: True if this frame contains delta-encoded values relative to previous frame.
+        items: The items in this frame. Caller owns the backing memory.
+
+    Examples:
+        >>> from dataclasses import dataclass
+        >>> @dataclass(frozen=True)
+        ... class KeyPoint:
+        ...     x: int
+        ...     y: int
+        ...
+        >>> # Create a master frame (absolute values)
+        >>> master = DeltaFrame[KeyPoint](
+        ...     frame_id=1,
+        ...     is_delta=False,
+        ...     items=[KeyPoint(100, 200), KeyPoint(150, 250)]
+        ... )
+        >>>
+        >>> # Create a delta frame (relative values)
+        >>> delta = DeltaFrame[KeyPoint](
+        ...     frame_id=2,
+        ...     is_delta=True,
+        ...     items=[KeyPoint(5, -3), KeyPoint(-2, 1)]
+        ... )
+        >>>
+        >>> # Check if it's a master frame
+        >>> if not delta.is_delta:
+        ...     print("Master frame")
+    """
+
+    frame_id: int
+    """The frame identifier (ulong equivalent, 0 to 2^64-1)."""
+
+    is_delta: bool
+    """True if this frame contains delta-encoded values relative to previous frame."""
+
+    items: Sequence[T]
+    """The items in this frame. Caller owns the backing memory."""
+
+    def __post_init__(self) -> None:
+        """Validate frame_id is non-negative."""
+        if self.frame_id < 0:
+            raise ValueError(f"frame_id must be non-negative, got {self.frame_id}")
+
+    @property
+    def is_master(self) -> bool:
+        """True if this is a master frame (not delta-encoded)."""
+        return not self.is_delta
+
+    @property
+    def count(self) -> int:
+        """Number of items in this frame."""
+        return len(self.items)
+
+    def __len__(self) -> int:
+        """Return the number of items in this frame."""
+        return len(self.items)
+
+    def __bool__(self) -> bool:
+        """Return True if the frame has items."""
+        return len(self.items) > 0
+
+    def __iter__(self) -> Iterator[T]:
+        """Iterate over items in this frame."""
+        return iter(self.items)
+
+    def __getitem__(self, index: int) -> T:
+        """Get item by index."""
+        return self.items[index]
+
+    @classmethod
+    def master(cls, frame_id: int, items: Sequence[T]) -> DeltaFrame[T]:
+        """
+        Create a master frame (absolute values, not delta-encoded).
+
+        Args:
+            frame_id: The frame identifier
+            items: The items with absolute values
+
+        Returns:
+            DeltaFrame with is_delta=False
+        """
+        return cls(frame_id=frame_id, is_delta=False, items=items)
+
+    @classmethod
+    def delta(cls, frame_id: int, items: Sequence[T]) -> DeltaFrame[T]:
+        """
+        Create a delta frame (values relative to previous frame).
+
+        Args:
+            frame_id: The frame identifier
+            items: The items with delta-encoded values
+
+        Returns:
+            DeltaFrame with is_delta=True
+        """
+        return cls(frame_id=frame_id, is_delta=True, items=items)
+
+    @classmethod
+    def empty_master(cls, frame_id: int) -> DeltaFrame[T]:
+        """
+        Create an empty master frame.
+
+        Args:
+            frame_id: The frame identifier
+
+        Returns:
+            DeltaFrame with no items and is_delta=False
+        """
+        return cls(frame_id=frame_id, is_delta=False, items=[])
+
+    @classmethod
+    def empty_delta(cls, frame_id: int) -> DeltaFrame[T]:
+        """
+        Create an empty delta frame.
+
+        Args:
+            frame_id: The frame identifier
+
+        Returns:
+            DeltaFrame with no items and is_delta=True
+        """
+        return cls(frame_id=frame_id, is_delta=True, items=[])

rocket_welder_sdk/graphics/__init__.py

@@ -0,0 +1,42 @@
+"""
+VectorGraphics module for streaming graphics overlays.
+
+This module provides classes for encoding and streaming vector graphics
+to the browser using Protocol V2.
+
+Example:
+    from rocket_welder_sdk.graphics import StageSink, RgbColor
+    from rocket_welder_sdk.transport import UnixSocketFrameSink
+
+    # Create transport and sink
+    sink = UnixSocketFrameSink("/tmp/graphics.sock")
+    stage = StageSink(sink)
+
+    # Draw graphics for each frame
+    with stage.create_writer(frame_id) as writer:
+        writer[0].set_stroke(RgbColor.Red)
+        writer[0].draw_polygon([(0, 0), (100, 0), (100, 100)])
+        writer[1].draw_text("Hello", 10, 20)
+"""
+
+from .layer_canvas import ILayerCanvas
+from .protocol import END_MARKER_BYTE1, END_MARKER_BYTE2, FrameType, OpType, PropertyId
+from .rgb_color import RgbColor
+from .stage import IStageSink, IStageWriter, LayerEncoder, StageSink, StageWriter
+from .vector_graphics_encoder import VectorGraphicsEncoder
+
+__all__ = [
+    "END_MARKER_BYTE1",
+    "END_MARKER_BYTE2",
+    "FrameType",
+    "ILayerCanvas",
+    "IStageSink",
+    "IStageWriter",
+    "LayerEncoder",
+    "OpType",
+    "PropertyId",
+    "RgbColor",
+    "StageSink",
+    "StageWriter",
+    "VectorGraphicsEncoder",
+]

rocket_welder_sdk/graphics/layer_canvas.py

@@ -0,0 +1,157 @@
+"""
+ILayerCanvas protocol - per-layer drawing interface.
+
+Matches C# ILayerCanvas interface from BlazorBlaze.Server.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Protocol, Sequence, Tuple, runtime_checkable
+
+if TYPE_CHECKING:
+    from .rgb_color import RgbColor
+
+
+@runtime_checkable
+class ILayerCanvas(Protocol):
+    """
+    Represents a single rendering layer with stateful context management.
+
+    Mirrors SkiaSharp's canvas API for familiar usage patterns.
+    This is a Protocol class (interface) matching C# ILayerCanvas.
+    """
+
+    @property
+    def layer_id(self) -> int:
+        """The layer ID (z-order index)."""
+        ...
+
+    # ============== Layer Frame Type ==============
+
+    def master(self) -> None:
+        """
+        Sets this layer to Master mode - clears and redraws with operations that follow.
+
+        This is the default mode when drawing operations are added.
+        """
+        ...
+
+    def remain(self) -> None:
+        """
+        Sets this layer to Remain mode - keeps previous content unchanged.
+
+        No operations are sent for this layer, saving bandwidth.
+        """
+        ...
+
+    def clear(self) -> None:
+        """
+        Sets this layer to Clear mode - clears to transparent with no redraw.
+
+        Use when you want to hide a layer without drawing new content.
+        """
+        ...
+
+    # ============== Context State - Styling ==============
+
+    def set_stroke(self, color: RgbColor) -> None:
+        """Sets the stroke color for subsequent draw operations."""
+        ...
+
+    def set_fill(self, color: RgbColor) -> None:
+        """Sets the fill color for subsequent draw operations."""
+        ...
+
+    def set_thickness(self, width: int) -> None:
+        """Sets the stroke thickness in pixels."""
+        ...
+
+    def set_font_size(self, size: int) -> None:
+        """Sets the font size in pixels."""
+        ...
+
+    def set_font_color(self, color: RgbColor) -> None:
+        """Sets the font color for text operations."""
+        ...
+
+    # ============== Context State - Transforms ==============
+
+    def translate(self, dx: float, dy: float) -> None:
+        """Sets the translation offset for subsequent draw operations."""
+        ...
+
+    def rotate(self, degrees: float) -> None:
+        """Sets the rotation in degrees for subsequent draw operations."""
+        ...
+
+    def scale(self, sx: float, sy: float) -> None:
+        """Sets the scale factors for subsequent draw operations."""
+        ...
+
+    def skew(self, kx: float, ky: float) -> None:
+        """Sets the skew factors for subsequent draw operations."""
+        ...
+
+    def set_matrix(
+        self,
+        scale_x: float,
+        skew_x: float,
+        trans_x: float,
+        skew_y: float,
+        scale_y: float,
+        trans_y: float,
+    ) -> None:
+        """
+        Sets a full transformation matrix for subsequent draw operations.
+
+        Takes precedence over individual transform properties.
+
+        Matrix layout matches SKMatrix:
+        | ScaleX  SkewX   TransX |
+        | SkewY   ScaleY  TransY |
+        """
+        ...
+
+    # ============== Context Stack ==============
+
+    def save(self) -> None:
+        """
+        Pushes the current context state onto a stack.
+
+        Use with restore() for hierarchical transforms.
+        """
+        ...
+
+    def restore(self) -> None:
+        """Pops and restores the most recently saved context state."""
+        ...
+
+    def reset_context(self) -> None:
+        """Resets the context to default values (black stroke, identity transform)."""
+        ...
+
+    # ============== Draw Operations ==============
+
+    def draw_polygon(self, points: Sequence[Tuple[float, float]]) -> None:
+        """Draws a polygon using the current context state."""
+        ...
+
+    def draw_text(self, text: str, x: int, y: int) -> None:
+        """Draws text at the specified position using the current context state."""
+        ...
+
+    def draw_circle(self, center_x: int, center_y: int, radius: int) -> None:
+        """Draws a circle using the current context state."""
+        ...
+
+    def draw_rectangle(self, x: int, y: int, width: int, height: int) -> None:
+        """Draws a rectangle using the current context state."""
+        ...
+
+    def draw_line(self, x1: int, y1: int, x2: int, y2: int) -> None:
+        """Draws a line using the current context state."""
+        ...
+
+    def draw_jpeg(self, jpeg_data: bytes, x: int, y: int, width: int, height: int) -> None:
+        """Draws a JPEG image at the specified position and size."""
+        ...

rocket_welder_sdk/graphics/protocol.py

@@ -0,0 +1,72 @@
+"""
+Protocol V2 enums and constants for VectorGraphics encoding.
+
+Matches C# ProtocolV2 from BlazorBlaze.VectorGraphics.Protocol.
+"""
+
+from __future__ import annotations
+
+from enum import IntEnum
+
+
+class FrameType(IntEnum):
+    """
+    Frame type for layer updates.
+
+    Matches C# FrameType enum.
+    """
+
+    MASTER = 0x00  # Clear and redraw with operations
+    REMAIN = 0x01  # Keep previous content unchanged
+    CLEAR = 0x02  # Clear to transparent with no redraw
+
+
+class OpType(IntEnum):
+    """
+    Operation type codes.
+
+    Matches C# OpType enum.
+    """
+
+    # Draw operations (0x01-0x0F)
+    DRAW_POLYGON = 0x01
+    DRAW_TEXT = 0x02
+    DRAW_CIRCLE = 0x03
+    DRAW_RECT = 0x04
+    DRAW_LINE = 0x05
+    DRAW_JPEG = 0x07
+
+    # Context operations (0x10-0x1F)
+    SET_CONTEXT = 0x10
+    SAVE_CONTEXT = 0x11
+    RESTORE_CONTEXT = 0x12
+    RESET_CONTEXT = 0x13
+
+
+class PropertyId(IntEnum):
+    """
+    Property IDs for SetContext operation.
+
+    Matches C# PropertyId enum.
+    """
+
+    # Styling properties (0x01-0x0F)
+    STROKE = 0x01
+    FILL = 0x02
+    THICKNESS = 0x03
+    FONT_SIZE = 0x04
+    FONT_COLOR = 0x05
+
+    # Transform properties (0x10-0x1F)
+    OFFSET = 0x10
+    ROTATION = 0x11
+    SCALE = 0x12
+    SKEW = 0x13
+
+    # Matrix (0x20)
+    MATRIX = 0x20
+
+
+# Protocol constants
+END_MARKER_BYTE1: int = 0xFF
+END_MARKER_BYTE2: int = 0xFF