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

rocket_welder_sdk/__init__.py

@@ -15,6 +15,19 @@ from .connection_string import ConnectionMode, ConnectionString, Protocol
 from .controllers import DuplexShmController, IController, OneWayShmController
 from .delta_frame import DeltaFrame
 from .frame_metadata import FRAME_METADATA_SIZE, FrameMetadata, GstVideoFormat
+from .graphics import (
+    FrameType,
+    ILayerCanvas,
+    IStageSink,
+    IStageWriter,
+    LayerEncoder,
+    OpType,
+    PropertyId,
+    RgbColor,
+    StageSink,
+    StageWriter,
+    VectorGraphicsEncoder,
+)
 from .gst_metadata import GstCaps, GstMetadata
 from .keypoints_protocol import (
     IKeyPointsSink,
@@ -38,6 +51,7 @@ from .segmentation_result import (
 from .session_id import (
     # Explicit URL environment variable names (set by rocket-welder2)
     ACTIONS_SINK_URL_ENV,
+    GRAPHICS_SINK_URL_ENV,
     KEYPOINTS_SINK_URL_ENV,
     SEGMENTATION_SINK_URL_ENV,
     # SessionId parsing
@@ -72,6 +86,7 @@ if _log_level:
 __all__ = [
     "ACTIONS_SINK_URL_ENV",
     "FRAME_METADATA_SIZE",
+    "GRAPHICS_SINK_URL_ENV",
     "KEYPOINTS_SINK_URL_ENV",
     "SEGMENTATION_SINK_URL_ENV",
     "BinaryFrameReader",
@@ -84,28 +99,39 @@ __all__ = [
     "DeltaFrame",
     "DuplexShmController",
     "FrameMetadata",
+    "FrameType",
     "GstCaps",
     "GstMetadata",
     "GstVideoFormat",
     "IController",
     "IKeyPointsSink",
     "IKeyPointsWriter",
+    "ILayerCanvas",
     "ISegmentationResultSink",
     "ISegmentationResultSource",
     "ISegmentationResultWriter",
+    "IStageSink",
+    "IStageWriter",
     "KeyPointsSink",
     "KeyPointsWriter",
+    "LayerEncoder",
     "OneWayShmController",
+    "OpType",
     "OpenCvController",
     "PeriodicTimer",
     "PeriodicTimerSync",
+    "PropertyId",
     "Protocol",
+    "RgbColor",
     "RocketWelderClient",
     "SegmentationFrame",
     "SegmentationProtocol",
     "SegmentationResultSink",
     "SegmentationResultSource",
     "SegmentationResultWriter",
+    "StageSink",
+    "StageWriter",
+    "VectorGraphicsEncoder",
     "get_session_id_from_env",
     "parse_session_id",
 ]

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

rocket_welder_sdk/graphics/rgb_color.py

@@ -0,0 +1,109 @@
+"""
+RgbColor - RGBA color representation.
+
+Matches C# RgbColor readonly record struct from BlazorBlaze.VectorGraphics.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import ClassVar
+
+
+@dataclass(frozen=True)
+class RgbColor:
+    """
+    Represents an RGBA color with byte components.
+
+    This is a frozen dataclass matching the C# `readonly record struct RgbColor`.
+    Each component is a byte (0-255).
+
+    Attributes:
+        r: Red component (0-255)
+        g: Green component (0-255)
+        b: Blue component (0-255)
+        a: Alpha component (0-255), defaults to 255 (opaque)
+    """
+
+    r: int
+    g: int
+    b: int
+    a: int = 255
+
+    # Pre-defined colors (class variables)
+    Transparent: ClassVar[RgbColor]
+    White: ClassVar[RgbColor]
+    Black: ClassVar[RgbColor]
+    Red: ClassVar[RgbColor]
+    Blue: ClassVar[RgbColor]
+    Green: ClassVar[RgbColor]
+    Gray: ClassVar[RgbColor]
+
+    def __post_init__(self) -> None:
+        """Validate color components are in valid range."""
+        if not (0 <= self.r <= 255):
+            raise ValueError(f"Red component must be 0-255, got {self.r}")
+        if not (0 <= self.g <= 255):
+            raise ValueError(f"Green component must be 0-255, got {self.g}")
+        if not (0 <= self.b <= 255):
+            raise ValueError(f"Blue component must be 0-255, got {self.b}")
+        if not (0 <= self.a <= 255):
+            raise ValueError(f"Alpha component must be 0-255, got {self.a}")
+
+    def __str__(self) -> str:
+        """Returns hex representation (#RRGGBB or #RRGGBBAA)."""
+        if self.a == 255:
+            return f"#{self.r:02X}{self.g:02X}{self.b:02X}"
+        return f"#{self.r:02X}{self.g:02X}{self.b:02X}{self.a:02X}"
+
+    def __repr__(self) -> str:
+        """Returns debug representation."""
+        return f"RgbColor(r={self.r}, g={self.g}, b={self.b}, a={self.a})"
+
+    def to_bytes(self) -> bytes:
+        """Returns RGBA as 4 bytes."""
+        return bytes([self.r, self.g, self.b, self.a])
+
+    @classmethod
+    def from_bytes(cls, data: bytes, offset: int = 0) -> RgbColor:
+        """Creates RgbColor from 4 bytes (RGBA)."""
+        return cls(data[offset], data[offset + 1], data[offset + 2], data[offset + 3])
+
+    @classmethod
+    def from_hex(cls, hex_str: str) -> RgbColor:
+        """
+        Creates RgbColor from hex string.
+
+        Supports formats: #RGB, #RGBA, #RRGGBB, #RRGGBBAA
+        """
+        hex_str = hex_str.lstrip("#")
+        if len(hex_str) == 3:
+            # #RGB -> #RRGGBB
+            hex_str = "".join(c * 2 for c in hex_str)
+        elif len(hex_str) == 4:
+            # #RGBA -> #RRGGBBAA
+            hex_str = "".join(c * 2 for c in hex_str)
+
+        if len(hex_str) == 6:
+            r = int(hex_str[0:2], 16)
+            g = int(hex_str[2:4], 16)
+            b = int(hex_str[4:6], 16)
+            return cls(r, g, b)
+        elif len(hex_str) == 8:
+            r = int(hex_str[0:2], 16)
+            g = int(hex_str[2:4], 16)
+            b = int(hex_str[4:6], 16)
+            a = int(hex_str[6:8], 16)
+            return cls(r, g, b, a)
+        else:
+            raise ValueError(f"Invalid hex color format: #{hex_str}")
+
+
+# Initialize class-level color constants
+RgbColor.Transparent = RgbColor(0, 0, 0, 0)
+RgbColor.White = RgbColor(255, 255, 255)
+RgbColor.Black = RgbColor(0, 0, 0)
+RgbColor.Red = RgbColor(255, 0, 0)
+RgbColor.Blue = RgbColor(0, 0, 255)
+RgbColor.Green = RgbColor(0, 255, 0)
+RgbColor.Gray = RgbColor(128, 128, 128)