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

rocket_welder_sdk/high_level/connection_strings.py

@@ -0,0 +1,330 @@
+"""
+Strongly-typed connection strings with parsing support.
+
+Connection string format: protocol://path?param1=value1&param2=value2
+
+Examples:
+    nng+push+ipc://tmp/keypoints?masterFrameInterval=300
+    nng+pub+tcp://localhost:5555
+    file://path/to/output.bin
+"""
+
+from __future__ import annotations
+
+import contextlib
+import os
+from dataclasses import dataclass, field
+from enum import Enum, auto
+from typing import Dict, Optional
+from urllib.parse import parse_qs
+
+from .transport_protocol import TransportProtocol
+
+
+class VideoSourceType(Enum):
+    """Type of video source."""
+
+    CAMERA = auto()
+    FILE = auto()
+    SHARED_MEMORY = auto()
+    RTSP = auto()
+    HTTP = auto()
+
+
+@dataclass(frozen=True)
+class VideoSourceConnectionString:
+    """
+    Strongly-typed connection string for video source input.
+
+    Supported formats:
+    - "0", "1", etc. - Camera device index
+    - file://path/to/video.mp4 - Video file
+    - shm://buffer_name - Shared memory buffer
+    - rtsp://host/stream - RTSP stream
+    """
+
+    value: str
+    source_type: VideoSourceType
+    camera_index: Optional[int] = None
+    path: Optional[str] = None
+    parameters: Dict[str, str] = field(default_factory=dict)
+
+    @classmethod
+    def default(cls) -> VideoSourceConnectionString:
+        """Default video source (camera 0)."""
+        return cls.parse("0")
+
+    @classmethod
+    def from_environment(cls, variable_name: str = "VIDEO_SOURCE") -> VideoSourceConnectionString:
+        """Create from environment variable or use default."""
+        value = os.environ.get(variable_name) or os.environ.get("CONNECTION_STRING")
+        return cls.parse(value) if value else cls.default()
+
+    @classmethod
+    def parse(cls, s: str) -> VideoSourceConnectionString:
+        """Parse a connection string."""
+        result = cls.try_parse(s)
+        if result is None:
+            raise ValueError(f"Invalid video source connection string: {s}")
+        return result
+
+    @classmethod
+    def try_parse(cls, s: str) -> Optional[VideoSourceConnectionString]:
+        """Try to parse a connection string."""
+        if not s or not s.strip():
+            return None
+
+        s = s.strip()
+        parameters: Dict[str, str] = {}
+
+        # Extract query parameters
+        if "?" in s:
+            base, query = s.split("?", 1)
+            for key, values in parse_qs(query).items():
+                parameters[key.lower()] = values[0] if values else ""
+            s = base
+
+        # Check for camera index first
+        if s.isdigit():
+            return cls(
+                value=s,
+                source_type=VideoSourceType.CAMERA,
+                camera_index=int(s),
+                parameters=parameters,
+            )
+
+        # Parse protocol
+        if s.startswith("file://"):
+            path = "/" + s[7:]  # Restore absolute path
+            return cls(
+                value=s,
+                source_type=VideoSourceType.FILE,
+                path=path,
+                parameters=parameters,
+            )
+        elif s.startswith("shm://"):
+            path = s[6:]
+            return cls(
+                value=s,
+                source_type=VideoSourceType.SHARED_MEMORY,
+                path=path,
+                parameters=parameters,
+            )
+        elif s.startswith("rtsp://"):
+            return cls(
+                value=s,
+                source_type=VideoSourceType.RTSP,
+                path=s,
+                parameters=parameters,
+            )
+        elif s.startswith("http://") or s.startswith("https://"):
+            return cls(
+                value=s,
+                source_type=VideoSourceType.HTTP,
+                path=s,
+                parameters=parameters,
+            )
+        elif "://" not in s:
+            # Assume file path
+            return cls(
+                value=s,
+                source_type=VideoSourceType.FILE,
+                path=s,
+                parameters=parameters,
+            )
+
+        return None
+
+    def __str__(self) -> str:
+        return self.value
+
+
+@dataclass(frozen=True)
+class KeyPointsConnectionString:
+    """
+    Strongly-typed connection string for KeyPoints output.
+
+    Supported protocols (composable with + operator):
+    - Transport.Nng + Transport.Push + Transport.Ipc → nng+push+ipc://tmp/keypoints
+    - Transport.Nng + Transport.Push + Transport.Tcp → nng+push+tcp://host:port
+    - file://path/to/file.bin - File output
+
+    Supported parameters:
+    - masterFrameInterval: Interval between master frames (default: 300)
+    """
+
+    value: str
+    protocol: Optional[TransportProtocol] = None
+    is_file: bool = False
+    address: str = ""
+    master_frame_interval: int = 300
+    parameters: Dict[str, str] = field(default_factory=dict)
+
+    @classmethod
+    def default(cls) -> KeyPointsConnectionString:
+        """Default connection string for KeyPoints."""
+        return cls.parse("nng+push+ipc://tmp/rocket-welder-keypoints?masterFrameInterval=300")
+
+    @classmethod
+    def from_environment(
+        cls, variable_name: str = "KEYPOINTS_CONNECTION_STRING"
+    ) -> KeyPointsConnectionString:
+        """Create from environment variable or use default."""
+        value = os.environ.get(variable_name)
+        return cls.parse(value) if value else cls.default()
+
+    @classmethod
+    def parse(cls, s: str) -> KeyPointsConnectionString:
+        """Parse a connection string."""
+        result = cls.try_parse(s)
+        if result is None:
+            raise ValueError(f"Invalid KeyPoints connection string: {s}")
+        return result
+
+    @classmethod
+    def try_parse(cls, s: str) -> Optional[KeyPointsConnectionString]:
+        """Try to parse a connection string."""
+        if not s or not s.strip():
+            return None
+
+        s = s.strip()
+        parameters: Dict[str, str] = {}
+
+        # Extract query parameters
+        endpoint_part = s
+        if "?" in s:
+            endpoint_part, query = s.split("?", 1)
+            for key, values in parse_qs(query).items():
+                parameters[key.lower()] = values[0] if values else ""
+
+        # Parse protocol and address
+        scheme_end = endpoint_part.find("://")
+        if scheme_end > 0:
+            protocol_str = endpoint_part[:scheme_end]
+            path_part = endpoint_part[scheme_end + 3 :]  # skip "://"
+
+            if protocol_str.lower() == "file":
+                address = "/" + path_part  # Restore absolute path
+                is_file = True
+                protocol = None
+            else:
+                protocol = TransportProtocol.try_parse(protocol_str)
+                if protocol is None:
+                    return None
+                address = protocol.create_nng_address(path_part)
+                is_file = False
+        elif s.startswith("/"):
+            # Assume absolute file path
+            address = s
+            is_file = True
+            protocol = None
+        else:
+            return None
+
+        # Parse masterFrameInterval
+        master_frame_interval = 300  # default
+        if "masterframeinterval" in parameters:
+            with contextlib.suppress(ValueError):
+                master_frame_interval = int(parameters["masterframeinterval"])
+
+        return cls(
+            value=s,
+            protocol=protocol,
+            is_file=is_file,
+            address=address,
+            master_frame_interval=master_frame_interval,
+            parameters=parameters,
+        )
+
+    def __str__(self) -> str:
+        return self.value
+
+
+@dataclass(frozen=True)
+class SegmentationConnectionString:
+    """
+    Strongly-typed connection string for Segmentation output.
+
+    Supported protocols (composable with + operator):
+    - Transport.Nng + Transport.Push + Transport.Ipc → nng+push+ipc://tmp/segmentation
+    - Transport.Nng + Transport.Push + Transport.Tcp → nng+push+tcp://host:port
+    - file://path/to/file.bin - File output
+    """
+
+    value: str
+    protocol: Optional[TransportProtocol] = None
+    is_file: bool = False
+    address: str = ""
+    parameters: Dict[str, str] = field(default_factory=dict)
+
+    @classmethod
+    def default(cls) -> SegmentationConnectionString:
+        """Default connection string for Segmentation."""
+        return cls.parse("nng+push+ipc://tmp/rocket-welder-segmentation")
+
+    @classmethod
+    def from_environment(
+        cls, variable_name: str = "SEGMENTATION_CONNECTION_STRING"
+    ) -> SegmentationConnectionString:
+        """Create from environment variable or use default."""
+        value = os.environ.get(variable_name)
+        return cls.parse(value) if value else cls.default()
+
+    @classmethod
+    def parse(cls, s: str) -> SegmentationConnectionString:
+        """Parse a connection string."""
+        result = cls.try_parse(s)
+        if result is None:
+            raise ValueError(f"Invalid Segmentation connection string: {s}")
+        return result
+
+    @classmethod
+    def try_parse(cls, s: str) -> Optional[SegmentationConnectionString]:
+        """Try to parse a connection string."""
+        if not s or not s.strip():
+            return None
+
+        s = s.strip()
+        parameters: Dict[str, str] = {}
+
+        # Extract query parameters
+        endpoint_part = s
+        if "?" in s:
+            endpoint_part, query = s.split("?", 1)
+            for key, values in parse_qs(query).items():
+                parameters[key.lower()] = values[0] if values else ""
+
+        # Parse protocol and address
+        scheme_end = endpoint_part.find("://")
+        if scheme_end > 0:
+            protocol_str = endpoint_part[:scheme_end]
+            path_part = endpoint_part[scheme_end + 3 :]  # skip "://"
+
+            if protocol_str.lower() == "file":
+                address = "/" + path_part  # Restore absolute path
+                is_file = True
+                protocol = None
+            else:
+                protocol = TransportProtocol.try_parse(protocol_str)
+                if protocol is None:
+                    return None
+                address = protocol.create_nng_address(path_part)
+                is_file = False
+        elif s.startswith("/"):
+            # Assume absolute file path
+            address = s
+            is_file = True
+            protocol = None
+        else:
+            return None
+
+        return cls(
+            value=s,
+            protocol=protocol,
+            is_file=is_file,
+            address=address,
+            parameters=parameters,
+        )
+
+    def __str__(self) -> str:
+        return self.value

rocket_welder_sdk/high_level/data_context.py

@@ -0,0 +1,163 @@
+"""
+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 KeyPoint, 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: KeyPoint, x: int, y: int, confidence: float) -> None:
+        """
+        Add a keypoint detection for this frame.
+
+        Args:
+            point: KeyPoint 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: KeyPoint, position: Point, confidence: float) -> None:
+        """
+        Add a keypoint detection using a Point tuple.
+
+        Args:
+            point: KeyPoint from schema definition
+            position: (x, y) tuple
+            confidence: Detection confidence (0.0 to 1.0)
+        """
+        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
+
+
+class KeyPointsDataContext(IKeyPointsDataContext):
+    """Implementation of keypoints data context."""
+
+    def __init__(
+        self,
+        frame_id: int,
+        writer: IKeyPointsWriter,
+    ) -> None:
+        from .schema import KeyPoint  # noqa: F401
+
+        self._frame_id = frame_id
+        self._writer = writer
+
+    @property
+    def frame_id(self) -> int:
+        return self._frame_id
+
+    def add(self, point: KeyPoint, 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: KeyPoint, 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:
+        from .schema import SegmentClass  # noqa: F401
+
+        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,180 @@
+"""
+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
+
+
+@dataclass(frozen=True)
+class KeyPoint:
+    """
+    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"KeyPoint({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) -> KeyPoint:
+        """
+        Define a new keypoint.
+
+        Args:
+            name: Human-readable name for the keypoint (e.g., "nose", "left_eye")
+
+        Returns:
+            KeyPoint handle for use with IKeyPointsDataContext.add()
+        """
+        pass
+
+    @property
+    @abstractmethod
+    def defined_points(self) -> List[KeyPoint]:
+        """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, KeyPoint] = {}
+        self._next_id = 0
+
+    def define_point(self, name: str) -> KeyPoint:
+        """Define a new keypoint."""
+        if name in self._points:
+            raise ValueError(f"Keypoint '{name}' already defined")
+
+        point = KeyPoint(id=self._next_id, name=name)
+        self._points[name] = point
+        self._next_id += 1
+        return point
+
+    @property
+    def defined_points(self) -> List[KeyPoint]:
+        """Get all defined keypoints."""
+        return list(self._points.values())
+
+    def get_metadata_json(self) -> str:
+        """Get JSON metadata for serialization."""
+        return json.dumps(
+            {
+                "version": "1.0",
+                "compute_module_name": "",
+                "points": {p.name: p.id for p in self._points.values()},
+            },
+            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."""
+        return json.dumps(
+            {
+                "version": "1.0",
+                "classes": {str(c.class_id): c.name for c in self._classes.values()},
+            },
+            indent=2,
+        )