rocket-welder-sdk 1.1.43__py3-none-any.whl → 1.1.44__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/high_level/__init__.py

@@ -12,7 +12,12 @@ Example:
         client.start(process_frame)
 """
 
-from .client import RocketWelderClient, RocketWelderClientOptions
+from .client import (
+    IRocketWelderClient,
+    RocketWelderClient,
+    RocketWelderClientFactory,
+    RocketWelderClientOptions,
+)
 from .connection_strings import (
     KeyPointsConnectionString,
     SegmentationConnectionString,
@@ -39,11 +44,13 @@ __all__ = [
     "FrameSinkFactory",
     "IKeyPointsDataContext",
     "IKeyPointsSchema",
+    "IRocketWelderClient",
     "ISegmentationDataContext",
     "ISegmentationSchema",
     "KeyPointDefinition",
     "KeyPointsConnectionString",
     "RocketWelderClient",
+    "RocketWelderClientFactory",
     "RocketWelderClientOptions",
     "SegmentClass",
     "SegmentationConnectionString",

rocket_welder_sdk/high_level/client.py

@@ -2,18 +2,24 @@
 RocketWelderClient - High-level API matching C# RocketWelder.SDK.
 
 Usage:
-    with RocketWelderClient.from_environment() as client:
+    with RocketWelderClientFactory.from_environment() as client:
         # Define schema
         nose = client.keypoints.define_point("nose")
         person = client.segmentation.define_class(1, "person")
 
         # Start processing
         client.start(process_frame)
+
+Alternatively:
+    # Using class methods directly
+    with RocketWelderClient.from_environment() as client:
+        ...
 """
 
 from __future__ import annotations
 
 import logging
+from abc import ABC, abstractmethod
 from dataclasses import dataclass, field
 from typing import TYPE_CHECKING, Any, Callable, Optional
 
@@ -50,6 +56,73 @@ Mat: TypeAlias = npt.NDArray[np.uint8]
 logger = logging.getLogger(__name__)
 
 
+class IRocketWelderClient(ABC):
+    """
+    Main entry point for RocketWelder SDK high-level API.
+
+    Provides schema definitions and frame processing loop.
+    Matches C# IRocketWelderClient interface.
+    """
+
+    @property
+    @abstractmethod
+    def keypoints(self) -> IKeyPointsSchema:
+        """Schema for defining keypoints."""
+        pass
+
+    @property
+    @abstractmethod
+    def segmentation(self) -> ISegmentationSchema:
+        """Schema for defining segmentation classes."""
+        pass
+
+    @abstractmethod
+    def start(
+        self,
+        process_frame: Callable[[Mat, ISegmentationDataContext, IKeyPointsDataContext, Mat], None],
+    ) -> None:
+        """
+        Start the processing loop with full context (keypoints + segmentation).
+
+        Args:
+            process_frame: Callback for each frame with:
+                - input_frame: Source video frame (Mat)
+                - segmentation: Segmentation data context
+                - keypoints: KeyPoints data context
+                - output_frame: Output frame for visualization (Mat)
+        """
+        pass
+
+    @abstractmethod
+    def start_keypoints(
+        self,
+        process_frame: Callable[[Mat, IKeyPointsDataContext, Mat], None],
+    ) -> None:
+        """Start the processing loop (keypoints only)."""
+        pass
+
+    @abstractmethod
+    def start_segmentation(
+        self,
+        process_frame: Callable[[Mat, ISegmentationDataContext, Mat], None],
+    ) -> None:
+        """Start the processing loop (segmentation only)."""
+        pass
+
+    @abstractmethod
+    def close(self) -> None:
+        """Release resources."""
+        pass
+
+    def __enter__(self) -> IRocketWelderClient:
+        """Context manager entry."""
+        return self
+
+    def __exit__(self, *args: object) -> None:
+        """Context manager exit."""
+        self.close()
+
+
 @dataclass
 class RocketWelderClientOptions:
     """Configuration options for RocketWelderClient."""
@@ -72,11 +145,12 @@ class RocketWelderClientOptions:
         )
 
 
-class RocketWelderClient:
+class RocketWelderClient(IRocketWelderClient):
     """
     High-level client for RocketWelder SDK.
 
-    Mirrors C# RocketWelder.SDK.IRocketWelderClient interface.
+    Implements IRocketWelderClient interface.
+    Mirrors C# RocketWelder.SDK.RocketWelderClientImpl.
     """
 
     def __init__(self, options: RocketWelderClientOptions) -> None:
@@ -233,3 +307,40 @@ class RocketWelderClient:
 
     def __exit__(self, *args: object) -> None:
         self.close()
+
+
+class RocketWelderClientFactory:
+    """
+    Factory for creating RocketWelderClient instances.
+
+    Matches C# RocketWelderClientFactory static class.
+    """
+
+    @staticmethod
+    def from_environment() -> IRocketWelderClient:
+        """
+        Creates a client configured from environment variables.
+
+        Environment variables:
+        - VIDEO_SOURCE or CONNECTION_STRING: Video input
+        - KEYPOINTS_CONNECTION_STRING: KeyPoints output
+        - SEGMENTATION_CONNECTION_STRING: Segmentation output
+
+        Returns:
+            IRocketWelderClient configured from environment.
+        """
+        options = RocketWelderClientOptions.from_environment()
+        return RocketWelderClient(options)
+
+    @staticmethod
+    def create(options: Optional[RocketWelderClientOptions] = None) -> IRocketWelderClient:
+        """
+        Creates a client with explicit configuration.
+
+        Args:
+            options: Configuration options. If None, uses defaults.
+
+        Returns:
+            IRocketWelderClient with the specified configuration.
+        """
+        return RocketWelderClient(options or RocketWelderClientOptions())

rocket_welder_sdk/high_level/connection_strings.py

@@ -4,10 +4,8 @@ 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
+    socket:///tmp/my.sock?masterFrameInterval=300
 """
 
 from __future__ import annotations
@@ -148,8 +146,6 @@ class KeyPointsConnectionString:
     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)
@@ -164,7 +160,7 @@ class KeyPointsConnectionString:
     @classmethod
     def default(cls) -> KeyPointsConnectionString:
         """Default connection string for KeyPoints."""
-        return cls.parse("nng+push+ipc://tmp/rocket-welder-keypoints?masterFrameInterval=300")
+        return cls.parse("socket:///tmp/rocket-welder-keypoints.sock?masterFrameInterval=300")
 
     @classmethod
     def from_environment(
@@ -217,9 +213,6 @@ class KeyPointsConnectionString:
         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
 
@@ -249,8 +242,6 @@ class SegmentationConnectionString:
     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
@@ -261,7 +252,7 @@ class SegmentationConnectionString:
     @classmethod
     def default(cls) -> SegmentationConnectionString:
         """Default connection string for Segmentation."""
-        return cls.parse("nng+push+ipc://tmp/rocket-welder-segmentation")
+        return cls.parse("socket:///tmp/rocket-welder-segmentation.sock")
 
     @classmethod
     def from_environment(
@@ -314,9 +305,6 @@ class SegmentationConnectionString:
         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
 

rocket_welder_sdk/high_level/frame_sink_factory.py

@@ -51,7 +51,7 @@ class FrameSinkFactory:
 
         Args:
             protocol: The transport protocol (from ConnectionString.protocol), or None
-            address: The address (file path, socket path, or NNG address)
+            address: The address (file path or socket path)
             logger_instance: Optional logger for diagnostics
 
         Returns:
@@ -64,7 +64,7 @@ class FrameSinkFactory:
             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 import NullFrameSink
         from rocket_welder_sdk.transport.stream_transport import StreamFrameSink
         from rocket_welder_sdk.transport.unix_socket_transport import UnixSocketFrameSink
 
@@ -87,19 +87,6 @@ class FrameSinkFactory:
             log.info("Creating Unix socket frame sink (server/bind) at: %s", address)
             return UnixSocketFrameSink.bind(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