rocket-welder-sdk 1.1.36.dev14__py3-none-any.whl

rocket_welder_sdk/high_level/connection_strings.py

@@ -0,0 +1,331 @@
+"""
+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
+    socket:///tmp/my.sock
+"""
+
+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:
+    - file:///path/to/file.bin - File output (absolute path)
+    - socket:///tmp/socket.sock - Unix domain socket
+    - nng+push+ipc://tmp/keypoints - NNG Push over IPC
+    - nng+push+tcp://host:port - NNG Push over TCP
+
+    Supported parameters:
+    - masterFrameInterval: Interval between master frames (default: 300)
+    """
+
+    value: str
+    protocol: TransportProtocol
+    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:
+            return None
+
+        schema_str = endpoint_part[:scheme_end]
+        path_part = endpoint_part[scheme_end + 3 :]  # skip "://"
+
+        protocol = TransportProtocol.try_parse(schema_str)
+        if protocol is None:
+            return None
+
+        # Build address based on protocol type
+        if protocol.is_file:
+            # file:///absolute/path -> /absolute/path
+            address = path_part if path_part.startswith("/") else "/" + path_part
+        elif protocol.is_socket:
+            # socket:///tmp/sock -> /tmp/sock
+            address = path_part if path_part.startswith("/") else "/" + path_part
+        elif protocol.is_nng:
+            # NNG protocols need proper address format
+            address = protocol.create_nng_address(path_part)
+        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,
+            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:
+    - file:///path/to/file.bin - File output (absolute path)
+    - socket:///tmp/socket.sock - Unix domain socket
+    - nng+push+ipc://tmp/segmentation - NNG Push over IPC
+    - nng+push+tcp://host:port - NNG Push over TCP
+    """
+
+    value: str
+    protocol: TransportProtocol
+    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:
+            return None
+
+        schema_str = endpoint_part[:scheme_end]
+        path_part = endpoint_part[scheme_end + 3 :]  # skip "://"
+
+        protocol = TransportProtocol.try_parse(schema_str)
+        if protocol is None:
+            return None
+
+        # Build address based on protocol type
+        if protocol.is_file:
+            # file:///absolute/path -> /absolute/path
+            address = path_part if path_part.startswith("/") else "/" + path_part
+        elif protocol.is_socket:
+            # socket:///tmp/sock -> /tmp/sock
+            address = path_part if path_part.startswith("/") else "/" + path_part
+        elif protocol.is_nng:
+            # NNG protocols need proper address format
+            address = protocol.create_nng_address(path_part)
+        else:
+            return None
+
+        return cls(
+            value=s,
+            protocol=protocol,
+            address=address,
+            parameters=parameters,
+        )
+
+    def __str__(self) -> str:
+        return self.value

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/frame_sink_factory.py

@@ -0,0 +1,118 @@
+"""
+Factory for creating IFrameSink instances from parsed protocol and address.
+
+Does NOT parse URLs - use SegmentationConnectionString or KeyPointsConnectionString for parsing.
+
+This mirrors the C# FrameSinkFactory class for API consistency.
+
+Usage:
+    from rocket_welder_sdk.high_level import FrameSinkFactory, SegmentationConnectionString
+
+    cs = SegmentationConnectionString.parse("socket:///tmp/seg.sock")
+    sink = FrameSinkFactory.create(cs.protocol, cs.address)
+
+    # For null sink (no output configured):
+    sink = FrameSinkFactory.create_null()
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING, Optional
+
+from .transport_protocol import TransportProtocol
+
+if TYPE_CHECKING:
+    from rocket_welder_sdk.transport.frame_sink import IFrameSink
+
+logger = logging.getLogger(__name__)
+
+
+class FrameSinkFactory:
+    """
+    Factory for creating IFrameSink instances from parsed protocol and address.
+
+    Does NOT parse URLs - use SegmentationConnectionString or KeyPointsConnectionString for parsing.
+
+    Mirrors C# RocketWelder.SDK.Transport.FrameSinkFactory.
+    """
+
+    @staticmethod
+    def create(
+        protocol: Optional[TransportProtocol],
+        address: str,
+        *,
+        logger_instance: Optional[logging.Logger] = None,
+    ) -> IFrameSink:
+        """
+        Create a frame sink from parsed protocol and address.
+
+        Returns NullFrameSink if protocol is None (no URL specified).
+
+        Args:
+            protocol: The transport protocol (from ConnectionString.protocol), or None
+            address: The address (file path, socket path, or NNG address)
+            logger_instance: Optional logger for diagnostics
+
+        Returns:
+            An IFrameSink connected to the specified address, or NullFrameSink if protocol is None
+
+        Raises:
+            ValueError: If protocol is not supported for sinks
+
+        Example:
+            cs = SegmentationConnectionString.parse("socket:///tmp/seg.sock")
+            sink = FrameSinkFactory.create(cs.protocol, cs.address)
+        """
+        from rocket_welder_sdk.transport import NngFrameSink, NullFrameSink
+        from rocket_welder_sdk.transport.stream_transport import StreamFrameSink
+        from rocket_welder_sdk.transport.unix_socket_transport import UnixSocketFrameSink
+
+        log = logger_instance or logger
+
+        # Handle None protocol - return null sink
+        if protocol is None:
+            log.debug("No protocol specified, using NullFrameSink")
+            return NullFrameSink.instance()
+
+        if not isinstance(protocol, TransportProtocol):
+            raise TypeError(f"Expected TransportProtocol, got {type(protocol).__name__}")
+
+        if protocol.is_file:
+            log.info("Creating file frame sink at: %s", address)
+            file_handle = open(address, "wb")  # noqa: SIM115
+            return StreamFrameSink(file_handle)
+
+        if protocol.is_socket:
+            log.info("Creating Unix socket frame sink at: %s", address)
+            return UnixSocketFrameSink.connect(address)
+
+        if protocol.is_nng:
+            log.info("Creating NNG frame sink (%s) at: %s", protocol.schema, address)
+
+            if protocol.is_pub:
+                return NngFrameSink.create_publisher(address)
+            if protocol.is_push:
+                return NngFrameSink.create_pusher(address)
+
+            raise ValueError(
+                f"NNG protocol '{protocol.schema}' is not supported for sinks "
+                "(only pub and push are supported)"
+            )
+
+        raise ValueError(f"Transport protocol '{protocol.schema}' is not supported for frame sinks")
+
+    @staticmethod
+    def create_null() -> IFrameSink:
+        """
+        Create a null frame sink that discards all data.
+
+        Use when no output URL is configured.
+        """
+        from rocket_welder_sdk.transport import NullFrameSink
+
+        return NullFrameSink.instance()
+
+
+# Re-export for convenience
+__all__ = ["FrameSinkFactory"]