rocket-welder-sdk 1.1.32__py3-none-any.whl → 1.1.34__py3-none-any.whl

rocket_welder_sdk/high_level/data_context.py

@@ -0,0 +1,169 @@
+"""
+Data context types for per-frame keypoints and segmentation data.
+
+Implements the Unit of Work pattern - contexts are created per-frame
+and auto-commit when the processing delegate returns.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import TYPE_CHECKING, Sequence, Tuple, Union
+
+import numpy as np
+import numpy.typing as npt
+
+if TYPE_CHECKING:
+    from rocket_welder_sdk.keypoints_protocol import IKeyPointsWriter
+    from rocket_welder_sdk.segmentation_result import SegmentationResultWriter
+
+    from .schema import KeyPointDefinition, SegmentClass
+
+# Type aliases
+Point = Tuple[int, int]
+
+
+class IKeyPointsDataContext(ABC):
+    """
+    Unit of Work for keypoints data, scoped to a single frame.
+
+    Auto-commits when the processing delegate returns.
+    """
+
+    @property
+    @abstractmethod
+    def frame_id(self) -> int:
+        """Current frame ID."""
+        pass
+
+    @abstractmethod
+    def add(self, point: KeyPointDefinition, x: int, y: int, confidence: float) -> None:
+        """
+        Add a keypoint detection for this frame.
+
+        Args:
+            point: KeyPointDefinition from schema definition
+            x: X coordinate in pixels
+            y: Y coordinate in pixels
+            confidence: Detection confidence (0.0 to 1.0)
+        """
+        pass
+
+    @abstractmethod
+    def add_point(self, point: KeyPointDefinition, position: Point, confidence: float) -> None:
+        """
+        Add a keypoint detection using a Point tuple.
+
+        Args:
+            point: KeyPointDefinition from schema definition
+            position: (x, y) tuple
+            confidence: Detection confidence (0.0 to 1.0)
+        """
+        pass
+
+    @abstractmethod
+    def commit(self) -> None:
+        """Commit the context (called automatically when delegate returns)."""
+        pass
+
+
+class ISegmentationDataContext(ABC):
+    """
+    Unit of Work for segmentation data, scoped to a single frame.
+
+    Auto-commits when the processing delegate returns.
+    """
+
+    @property
+    @abstractmethod
+    def frame_id(self) -> int:
+        """Current frame ID."""
+        pass
+
+    @abstractmethod
+    def add(
+        self,
+        segment_class: SegmentClass,
+        instance_id: int,
+        points: Union[Sequence[Point], npt.NDArray[np.int32]],
+    ) -> None:
+        """
+        Add a segmentation instance for this frame.
+
+        Args:
+            segment_class: SegmentClass from schema definition
+            instance_id: Instance ID (for multiple instances of same class, 0-255)
+            points: Contour points defining the instance boundary
+        """
+        pass
+
+    @abstractmethod
+    def commit(self) -> None:
+        """Commit the context (called automatically when delegate returns)."""
+        pass
+
+
+class KeyPointsDataContext(IKeyPointsDataContext):
+    """Implementation of keypoints data context."""
+
+    def __init__(
+        self,
+        frame_id: int,
+        writer: IKeyPointsWriter,
+    ) -> None:
+        self._frame_id = frame_id
+        self._writer = writer
+
+    @property
+    def frame_id(self) -> int:
+        return self._frame_id
+
+    def add(self, point: KeyPointDefinition, x: int, y: int, confidence: float) -> None:
+        """Add a keypoint detection for this frame."""
+        self._writer.append(point.id, x, y, confidence)
+
+    def add_point(self, point: KeyPointDefinition, position: Point, confidence: float) -> None:
+        """Add a keypoint detection using a Point tuple."""
+        self._writer.append_point(point.id, position, confidence)
+
+    def commit(self) -> None:
+        """Commit the context (called automatically when delegate returns)."""
+        self._writer.close()
+
+
+class SegmentationDataContext(ISegmentationDataContext):
+    """Implementation of segmentation data context."""
+
+    def __init__(
+        self,
+        frame_id: int,
+        writer: SegmentationResultWriter,
+    ) -> None:
+        self._frame_id = frame_id
+        self._writer = writer
+
+    @property
+    def frame_id(self) -> int:
+        return self._frame_id
+
+    def add(
+        self,
+        segment_class: SegmentClass,
+        instance_id: int,
+        points: Union[Sequence[Point], npt.NDArray[np.int32]],
+    ) -> None:
+        """Add a segmentation instance for this frame."""
+        if instance_id < 0 or instance_id > 255:
+            raise ValueError(f"instance_id must be 0-255, got {instance_id}")
+
+        # Convert to numpy array if needed
+        if isinstance(points, np.ndarray):
+            points_array = points
+        else:
+            points_array = np.array(points, dtype=np.int32)
+
+        self._writer.append(segment_class.class_id, instance_id, points_array)
+
+    def commit(self) -> None:
+        """Commit the context (called automatically when delegate returns)."""
+        self._writer.close()

rocket_welder_sdk/high_level/schema.py

@@ -0,0 +1,197 @@
+"""
+Schema types for KeyPoints and Segmentation.
+
+Provides type-safe definitions for keypoints and segmentation classes
+that are defined at initialization time and used during processing.
+"""
+
+from __future__ import annotations
+
+import json
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from typing import Dict, List, Any
+
+
+@dataclass(frozen=True)
+class KeyPointDefinition:
+    """
+    A keypoint definition with ID and name.
+
+    Created via IKeyPointsSchema.define_point().
+    Used as a type-safe handle when adding keypoints to data context.
+    """
+
+    id: int
+    name: str
+
+    def __str__(self) -> str:
+        return f"KeyPointDefinition({self.id}, '{self.name}')"
+
+
+@dataclass(frozen=True)
+class SegmentClass:
+    """
+    A segmentation class definition with class ID and name.
+
+    Created via ISegmentationSchema.define_class().
+    Used as a type-safe handle when adding instances to data context.
+    """
+
+    class_id: int
+    name: str
+
+    def __str__(self) -> str:
+        return f"SegmentClass({self.class_id}, '{self.name}')"
+
+
+class IKeyPointsSchema(ABC):
+    """
+    Interface for defining keypoints schema.
+
+    Keypoints are defined once at initialization and referenced by handle
+    when adding data to the context.
+    """
+
+    @abstractmethod
+    def define_point(self, name: str) -> KeyPointDefinition:
+        """
+        Define a new keypoint.
+
+        Args:
+            name: Human-readable name for the keypoint (e.g., "nose", "left_eye")
+
+        Returns:
+            KeyPointDefinition handle for use with IKeyPointsDataContext.add()
+        """
+        pass
+
+    @property
+    @abstractmethod
+    def defined_points(self) -> List[KeyPointDefinition]:
+        """Get all defined keypoints."""
+        pass
+
+    @abstractmethod
+    def get_metadata_json(self) -> str:
+        """Get JSON metadata for serialization."""
+        pass
+
+
+class ISegmentationSchema(ABC):
+    """
+    Interface for defining segmentation classes schema.
+
+    Classes are defined once at initialization and referenced by handle
+    when adding instances to the context.
+    """
+
+    @abstractmethod
+    def define_class(self, class_id: int, name: str) -> SegmentClass:
+        """
+        Define a new segmentation class.
+
+        Args:
+            class_id: Unique class identifier (0-255)
+            name: Human-readable name for the class (e.g., "person", "car")
+
+        Returns:
+            SegmentClass handle for use with ISegmentationDataContext.add()
+        """
+        pass
+
+    @property
+    @abstractmethod
+    def defined_classes(self) -> List[SegmentClass]:
+        """Get all defined classes."""
+        pass
+
+    @abstractmethod
+    def get_metadata_json(self) -> str:
+        """Get JSON metadata for serialization."""
+        pass
+
+
+class KeyPointsSchema(IKeyPointsSchema):
+    """Implementation of keypoints schema."""
+
+    def __init__(self) -> None:
+        self._points: Dict[str, KeyPointDefinition] = {}
+        self._next_id = 0
+
+    def define_point(self, name: str) -> KeyPointDefinition:
+        """Define a new keypoint."""
+        if name in self._points:
+            raise ValueError(f"Keypoint '{name}' already defined")
+
+        point = KeyPointDefinition(id=self._next_id, name=name)
+        self._points[name] = point
+        self._next_id += 1
+        return point
+
+    @property
+    def defined_points(self) -> List[KeyPointDefinition]:
+        """Get all defined keypoints."""
+        return list(self._points.values())
+
+    def get_metadata_json(self) -> str:
+        """
+        Get JSON metadata for serialization.
+
+        Format matches C# SDK:
+        {
+            "version": 1,
+            "type": "keypoints",
+            "points": [{"id": 0, "name": "nose"}, ...]
+        }
+        """
+        metadata: Dict[str, Any] = {
+            "version": 1,
+            "type": "keypoints",
+            "points": [{"id": p.id, "name": p.name} for p in self._points.values()],
+        }
+        return json.dumps(metadata, indent=2)
+
+
+class SegmentationSchema(ISegmentationSchema):
+    """Implementation of segmentation schema."""
+
+    def __init__(self) -> None:
+        self._classes: Dict[int, SegmentClass] = {}
+
+    def define_class(self, class_id: int, name: str) -> SegmentClass:
+        """Define a new segmentation class."""
+        if class_id < 0 or class_id > 255:
+            raise ValueError(f"class_id must be 0-255, got {class_id}")
+
+        if class_id in self._classes:
+            raise ValueError(f"Class ID {class_id} already defined")
+
+        segment_class = SegmentClass(class_id=class_id, name=name)
+        self._classes[class_id] = segment_class
+        return segment_class
+
+    @property
+    def defined_classes(self) -> List[SegmentClass]:
+        """Get all defined classes."""
+        return list(self._classes.values())
+
+    def get_metadata_json(self) -> str:
+        """
+        Get JSON metadata for serialization.
+
+        Format matches C# SDK:
+        {
+            "version": 1,
+            "type": "segmentation",
+            "classes": [{"classId": 1, "name": "person"}, ...]
+        }
+        """
+        metadata: Dict[str, Any] = {
+            "version": 1,
+            "type": "segmentation",
+            "classes": [
+                {"classId": c.class_id, "name": c.name} for c in self._classes.values()
+            ],
+        }
+        return json.dumps(metadata, indent=2)

rocket_welder_sdk/high_level/transport_protocol.py

@@ -0,0 +1,238 @@
+"""
+Unified transport protocol as a value type.
+
+Supports: file://, socket://, nng+push+ipc://, nng+push+tcp://, etc.
+
+Examples:
+    file:///home/user/output.bin   - absolute file path
+    socket:///tmp/my.sock          - Unix domain socket
+    nng+push+ipc://tmp/keypoints   - NNG Push over IPC
+    nng+push+tcp://host:5555       - NNG Push over TCP
+"""
+
+from __future__ import annotations
+
+from enum import Enum, auto
+from typing import ClassVar, Dict, Optional
+
+
+class TransportKind(Enum):
+    """Transport kind enumeration."""
+
+    FILE = auto()
+    """File output."""
+
+    SOCKET = auto()
+    """Unix domain socket (direct, no messaging library)."""
+
+    NNG_PUSH_IPC = auto()
+    """NNG Push over IPC."""
+
+    NNG_PUSH_TCP = auto()
+    """NNG Push over TCP."""
+
+    NNG_PULL_IPC = auto()
+    """NNG Pull over IPC."""
+
+    NNG_PULL_TCP = auto()
+    """NNG Pull over TCP."""
+
+    NNG_PUB_IPC = auto()
+    """NNG Pub over IPC."""
+
+    NNG_PUB_TCP = auto()
+    """NNG Pub over TCP."""
+
+    NNG_SUB_IPC = auto()
+    """NNG Sub over IPC."""
+
+    NNG_SUB_TCP = auto()
+    """NNG Sub over TCP."""
+
+
+class TransportProtocol:
+    """
+    Unified transport protocol specification as a value type.
+
+    Supports: file://, socket://, nng+push+ipc://, nng+push+tcp://, etc.
+    """
+
+    # Predefined protocols
+    File: TransportProtocol
+    Socket: TransportProtocol
+    NngPushIpc: TransportProtocol
+    NngPushTcp: TransportProtocol
+    NngPullIpc: TransportProtocol
+    NngPullTcp: TransportProtocol
+    NngPubIpc: TransportProtocol
+    NngPubTcp: TransportProtocol
+    NngSubIpc: TransportProtocol
+    NngSubTcp: TransportProtocol
+
+    _SCHEMA_MAP: ClassVar[Dict[str, TransportKind]] = {
+        "file": TransportKind.FILE,
+        "socket": TransportKind.SOCKET,
+        "nng+push+ipc": TransportKind.NNG_PUSH_IPC,
+        "nng+push+tcp": TransportKind.NNG_PUSH_TCP,
+        "nng+pull+ipc": TransportKind.NNG_PULL_IPC,
+        "nng+pull+tcp": TransportKind.NNG_PULL_TCP,
+        "nng+pub+ipc": TransportKind.NNG_PUB_IPC,
+        "nng+pub+tcp": TransportKind.NNG_PUB_TCP,
+        "nng+sub+ipc": TransportKind.NNG_SUB_IPC,
+        "nng+sub+tcp": TransportKind.NNG_SUB_TCP,
+    }
+
+    _KIND_TO_SCHEMA: ClassVar[Dict[TransportKind, str]] = {}
+
+    def __init__(self, kind: TransportKind, schema: str) -> None:
+        self._kind = kind
+        self._schema = schema
+
+    @property
+    def kind(self) -> TransportKind:
+        """The transport kind."""
+        return self._kind
+
+    @property
+    def schema(self) -> str:
+        """The schema string (e.g., 'file', 'socket', 'nng+push+ipc')."""
+        return self._schema
+
+    # Classification properties
+
+    @property
+    def is_file(self) -> bool:
+        """True if this is a file transport."""
+        return self._kind == TransportKind.FILE
+
+    @property
+    def is_socket(self) -> bool:
+        """True if this is a Unix socket transport."""
+        return self._kind == TransportKind.SOCKET
+
+    @property
+    def is_nng(self) -> bool:
+        """True if this is any NNG-based transport."""
+        return self._kind in {
+            TransportKind.NNG_PUSH_IPC,
+            TransportKind.NNG_PUSH_TCP,
+            TransportKind.NNG_PULL_IPC,
+            TransportKind.NNG_PULL_TCP,
+            TransportKind.NNG_PUB_IPC,
+            TransportKind.NNG_PUB_TCP,
+            TransportKind.NNG_SUB_IPC,
+            TransportKind.NNG_SUB_TCP,
+        }
+
+    @property
+    def is_push(self) -> bool:
+        """True if this is a Push pattern."""
+        return self._kind in {TransportKind.NNG_PUSH_IPC, TransportKind.NNG_PUSH_TCP}
+
+    @property
+    def is_pull(self) -> bool:
+        """True if this is a Pull pattern."""
+        return self._kind in {TransportKind.NNG_PULL_IPC, TransportKind.NNG_PULL_TCP}
+
+    @property
+    def is_pub(self) -> bool:
+        """True if this is a Pub pattern."""
+        return self._kind in {TransportKind.NNG_PUB_IPC, TransportKind.NNG_PUB_TCP}
+
+    @property
+    def is_sub(self) -> bool:
+        """True if this is a Sub pattern."""
+        return self._kind in {TransportKind.NNG_SUB_IPC, TransportKind.NNG_SUB_TCP}
+
+    @property
+    def is_ipc(self) -> bool:
+        """True if this uses IPC layer."""
+        return self._kind in {
+            TransportKind.NNG_PUSH_IPC,
+            TransportKind.NNG_PULL_IPC,
+            TransportKind.NNG_PUB_IPC,
+            TransportKind.NNG_SUB_IPC,
+        }
+
+    @property
+    def is_tcp(self) -> bool:
+        """True if this uses TCP layer."""
+        return self._kind in {
+            TransportKind.NNG_PUSH_TCP,
+            TransportKind.NNG_PULL_TCP,
+            TransportKind.NNG_PUB_TCP,
+            TransportKind.NNG_SUB_TCP,
+        }
+
+    def create_nng_address(self, path_or_host: str) -> str:
+        """
+        Create the NNG address from a path/host.
+
+        For IPC: ipc:///path
+        For TCP: tcp://host:port
+
+        Raises:
+            ValueError: If this is not an NNG protocol.
+        """
+        if not self.is_nng:
+            raise ValueError(f"Cannot create NNG address for {self._kind} transport")
+
+        if self.is_ipc:
+            # IPC paths need leading "/" for absolute paths
+            if not path_or_host.startswith("/"):
+                return f"ipc:///{path_or_host}"
+            return f"ipc://{path_or_host}"
+
+        # TCP
+        return f"tcp://{path_or_host}"
+
+    def __str__(self) -> str:
+        return self._schema
+
+    def __repr__(self) -> str:
+        return f"TransportProtocol({self._kind.name}, '{self._schema}')"
+
+    def __eq__(self, other: object) -> bool:
+        if isinstance(other, TransportProtocol):
+            return self._kind == other._kind
+        return False
+
+    def __hash__(self) -> int:
+        return hash(self._kind)
+
+    @classmethod
+    def parse(cls, s: str) -> TransportProtocol:
+        """Parse a protocol string (e.g., 'nng+push+ipc')."""
+        result = cls.try_parse(s)
+        if result is None:
+            raise ValueError(f"Invalid transport protocol: {s}")
+        return result
+
+    @classmethod
+    def try_parse(cls, s: Optional[str]) -> Optional[TransportProtocol]:
+        """Try to parse a protocol string."""
+        if not s:
+            return None
+
+        schema = s.lower().strip()
+        kind = cls._SCHEMA_MAP.get(schema)
+        if kind is None:
+            return None
+
+        return cls(kind, schema)
+
+
+# Initialize predefined protocols
+TransportProtocol.File = TransportProtocol(TransportKind.FILE, "file")
+TransportProtocol.Socket = TransportProtocol(TransportKind.SOCKET, "socket")
+TransportProtocol.NngPushIpc = TransportProtocol(TransportKind.NNG_PUSH_IPC, "nng+push+ipc")
+TransportProtocol.NngPushTcp = TransportProtocol(TransportKind.NNG_PUSH_TCP, "nng+push+tcp")
+TransportProtocol.NngPullIpc = TransportProtocol(TransportKind.NNG_PULL_IPC, "nng+pull+ipc")
+TransportProtocol.NngPullTcp = TransportProtocol(TransportKind.NNG_PULL_TCP, "nng+pull+tcp")
+TransportProtocol.NngPubIpc = TransportProtocol(TransportKind.NNG_PUB_IPC, "nng+pub+ipc")
+TransportProtocol.NngPubTcp = TransportProtocol(TransportKind.NNG_PUB_TCP, "nng+pub+tcp")
+TransportProtocol.NngSubIpc = TransportProtocol(TransportKind.NNG_SUB_IPC, "nng+sub+ipc")
+TransportProtocol.NngSubTcp = TransportProtocol(TransportKind.NNG_SUB_TCP, "nng+sub+tcp")
+
+# Initialize reverse lookup map
+TransportProtocol._KIND_TO_SCHEMA = {v: k for k, v in TransportProtocol._SCHEMA_MAP.items()}