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

rocket_welder_sdk/__init__.py

@@ -10,10 +10,30 @@ import os
 from .bytes_size import BytesSize
 from .connection_string import ConnectionMode, ConnectionString, Protocol
 from .controllers import DuplexShmController, IController, OneWayShmController
+from .frame_metadata import FRAME_METADATA_SIZE, FrameMetadata, GstVideoFormat
 from .gst_metadata import GstCaps, GstMetadata
 from .opencv_controller import OpenCvController
 from .periodic_timer import PeriodicTimer, PeriodicTimerSync
 from .rocket_welder_client import RocketWelderClient
+from .session_id import (
+    # Explicit URL functions (PREFERRED - set by rocket-welder2)
+    ACTIONS_SINK_URL_ENV,
+    KEYPOINTS_SINK_URL_ENV,
+    SEGMENTATION_SINK_URL_ENV,
+    # SessionId-derived URL functions (fallback for backwards compatibility)
+    get_actions_url,
+    get_actions_url_from_env,
+    get_configured_nng_urls,
+    get_keypoints_url,
+    get_keypoints_url_from_env,
+    get_nng_urls,
+    get_nng_urls_from_env,
+    get_segmentation_url,
+    get_segmentation_url_from_env,
+    get_session_id_from_env,
+    has_explicit_nng_urls,
+    parse_session_id,
+)
 
 # Alias for backward compatibility and README examples
 Client = RocketWelderClient
@@ -40,23 +60,36 @@ if _log_level:
         pass  # Invalid log level, ignore
 
 __all__ = [
-    # Core types
+    "ACTIONS_SINK_URL_ENV",
+    "FRAME_METADATA_SIZE",
+    "KEYPOINTS_SINK_URL_ENV",
+    "SEGMENTATION_SINK_URL_ENV",
     "BytesSize",
-    "Client",  # Backward compatibility
+    "Client",
     "ConnectionMode",
     "ConnectionString",
     "DuplexShmController",
-    # GStreamer metadata
+    "FrameMetadata",
     "GstCaps",
     "GstMetadata",
-    # Controllers
+    "GstVideoFormat",
     "IController",
     "OneWayShmController",
     "OpenCvController",
-    # Timers
     "PeriodicTimer",
     "PeriodicTimerSync",
     "Protocol",
-    # Main client
     "RocketWelderClient",
+    "get_actions_url",
+    "get_actions_url_from_env",
+    "get_configured_nng_urls",
+    "get_keypoints_url",
+    "get_keypoints_url_from_env",
+    "get_nng_urls",
+    "get_nng_urls_from_env",
+    "get_segmentation_url",
+    "get_segmentation_url_from_env",
+    "get_session_id_from_env",
+    "has_explicit_nng_urls",
+    "parse_session_id",
 ]

rocket_welder_sdk/controllers.py

@@ -17,6 +17,7 @@ from zerobuffer.duplex import DuplexChannelFactory
 from zerobuffer.exceptions import WriterDeadException
 
 from .connection_string import ConnectionMode, ConnectionString, Protocol
+from .frame_metadata import FRAME_METADATA_SIZE, FrameMetadata
 from .gst_metadata import GstCaps, GstMetadata
 
 if TYPE_CHECKING:
@@ -336,6 +337,9 @@ class OneWayShmController(IController):
         Create OpenCV Mat from frame data using GstCaps.
         Matches C# CreateMat behavior - creates Mat wrapping the data.
 
+        Frame data layout from GStreamer zerosink:
+        [FrameMetadata (16 bytes)][Pixel Data (WxHxC bytes)]
+
         Args:
             frame: ZeroBuffer frame
 
@@ -359,31 +363,40 @@ class OneWayShmController(IController):
                 else:
                     channels = 3  # Default to RGB
 
-                # Get frame data directly as numpy array (zero-copy view)
-                # Frame.data is already a memoryview/buffer that can be wrapped
-                data = np.frombuffer(frame.data, dtype=np.uint8)
+                # Frame data has 16-byte FrameMetadata prefix that must be stripped
+                # Layout: [FrameMetadata (16 bytes)][Pixel Data]
+                if frame.size < FRAME_METADATA_SIZE:
+                    logger.error(
+                        "Frame too small for FrameMetadata: %d bytes (need at least %d)",
+                        frame.size,
+                        FRAME_METADATA_SIZE,
+                    )
+                    return None
+
+                # Get pixel data (skip 16-byte FrameMetadata prefix)
+                pixel_data = np.frombuffer(frame.data[FRAME_METADATA_SIZE:], dtype=np.uint8)
 
-                # Check data size matches expected
+                # Check pixel data size matches expected
                 expected_size = height * width * channels
-                if len(data) != expected_size:
+                if len(pixel_data) != expected_size:
                     logger.error(
-                        "Data size mismatch. Expected %d bytes for %dx%d with %d channels, got %d",
+                        "Pixel data size mismatch. Expected %d bytes for %dx%d with %d channels, got %d",
                         expected_size,
                         width,
                         height,
                         channels,
-                        len(data),
+                        len(pixel_data),
                     )
                     return None
 
                 # Reshape to image dimensions - this is zero-copy, just changes the view
                 # This matches C#: new Mat(Height, Width, Depth, Channels, ptr, Width * Channels)
                 if channels == 3:
-                    mat = data.reshape((height, width, 3))
+                    mat = pixel_data.reshape((height, width, 3))
                 elif channels == 1:
-                    mat = data.reshape((height, width))
+                    mat = pixel_data.reshape((height, width))
                 elif channels == 4:
-                    mat = data.reshape((height, width, 4))
+                    mat = pixel_data.reshape((height, width, 4))
                 else:
                     logger.error("Unsupported channel count: %d", channels)
                     return None
@@ -393,41 +406,55 @@ class OneWayShmController(IController):
             # No caps available - try to infer from frame size
             logger.warning("No GstCaps available, attempting to infer from frame size")
 
-            # Try common resolutions
-            frame_size = len(frame.data)
+            # Frame data has 16-byte FrameMetadata prefix
+            if frame.size < FRAME_METADATA_SIZE:
+                logger.error(
+                    "Frame too small for FrameMetadata: %d bytes (need at least %d)",
+                    frame.size,
+                    FRAME_METADATA_SIZE,
+                )
+                return None
+
+            # Calculate pixel data size (frame size minus 16-byte metadata prefix)
+            pixel_data_size = frame.size - FRAME_METADATA_SIZE
 
             # First, check if it's a perfect square (square frame)
             import math
 
-            sqrt_size = math.sqrt(frame_size)
+            sqrt_size = math.sqrt(pixel_data_size)
             if sqrt_size == int(sqrt_size):
                 # Perfect square - assume square grayscale image
                 dimension = int(sqrt_size)
                 logger.info(
-                    f"Frame size {frame_size} is a perfect square, assuming {dimension}x{dimension} grayscale"
+                    f"Pixel data size {pixel_data_size} is a perfect square, "
+                    f"assuming {dimension}x{dimension} grayscale"
                 )
-                data = np.frombuffer(frame.data, dtype=np.uint8)
-                return data.reshape((dimension, dimension))  # type: ignore[no-any-return]
+                pixel_data = np.frombuffer(frame.data[FRAME_METADATA_SIZE:], dtype=np.uint8)
+                return pixel_data.reshape((dimension, dimension))  # type: ignore[no-any-return]
 
             # Also check for square RGB (size = width * height * 3)
-            if frame_size % 3 == 0:
-                pixels = frame_size // 3
+            if pixel_data_size % 3 == 0:
+                pixels = pixel_data_size // 3
                 sqrt_pixels = math.sqrt(pixels)
                 if sqrt_pixels == int(sqrt_pixels):
                     dimension = int(sqrt_pixels)
-                    logger.info(f"Frame size {frame_size} suggests {dimension}x{dimension} RGB")
-                    data = np.frombuffer(frame.data, dtype=np.uint8)
-                    return data.reshape((dimension, dimension, 3))  # type: ignore[no-any-return]
+                    logger.info(
+                        f"Pixel data size {pixel_data_size} suggests {dimension}x{dimension} RGB"
+                    )
+                    pixel_data = np.frombuffer(frame.data[FRAME_METADATA_SIZE:], dtype=np.uint8)
+                    return pixel_data.reshape((dimension, dimension, 3))  # type: ignore[no-any-return]
 
             # Check for square RGBA (size = width * height * 4)
-            if frame_size % 4 == 0:
-                pixels = frame_size // 4
+            if pixel_data_size % 4 == 0:
+                pixels = pixel_data_size // 4
                 sqrt_pixels = math.sqrt(pixels)
                 if sqrt_pixels == int(sqrt_pixels):
                     dimension = int(sqrt_pixels)
-                    logger.info(f"Frame size {frame_size} suggests {dimension}x{dimension} RGBA")
-                    data = np.frombuffer(frame.data, dtype=np.uint8)
-                    return data.reshape((dimension, dimension, 4))  # type: ignore[no-any-return]
+                    logger.info(
+                        f"Pixel data size {pixel_data_size} suggests {dimension}x{dimension} RGBA"
+                    )
+                    pixel_data = np.frombuffer(frame.data[FRAME_METADATA_SIZE:], dtype=np.uint8)
+                    return pixel_data.reshape((dimension, dimension, 4))  # type: ignore[no-any-return]
 
             common_resolutions = [
                 (640, 480, 3),  # VGA RGB
@@ -438,7 +465,7 @@ class OneWayShmController(IController):
             ]
 
             for width, height, channels in common_resolutions:
-                if frame_size == width * height * channels:
+                if pixel_data_size == width * height * channels:
                     logger.info(f"Inferred resolution: {width}x{height} with {channels} channels")
 
                     # Create caps for future use
@@ -447,16 +474,16 @@ class OneWayShmController(IController):
                         width=width, height=height, format=format_str
                     )
 
-                    # Create Mat
-                    data = np.frombuffer(frame.data, dtype=np.uint8)
+                    # Create Mat from pixel data (skip 16-byte FrameMetadata prefix)
+                    pixel_data = np.frombuffer(frame.data[FRAME_METADATA_SIZE:], dtype=np.uint8)
                     if channels == 3:
-                        return data.reshape((height, width, 3))  # type: ignore[no-any-return]
+                        return pixel_data.reshape((height, width, 3))  # type: ignore[no-any-return]
                     elif channels == 1:
-                        return data.reshape((height, width))  # type: ignore[no-any-return]
+                        return pixel_data.reshape((height, width))  # type: ignore[no-any-return]
                     elif channels == 4:
-                        return data.reshape((height, width, 4))  # type: ignore[no-any-return]
+                        return pixel_data.reshape((height, width, 4))  # type: ignore[no-any-return]
 
-            logger.error(f"Could not infer resolution for frame size {frame_size}")
+            logger.error(f"Could not infer resolution for pixel data size {pixel_data_size}")
             return None
 
         except Exception as e:
@@ -553,7 +580,7 @@ class DuplexShmController(IController):
         self._gst_caps: Optional[GstCaps] = None
         self._metadata: Optional[GstMetadata] = None
         self._is_running = False
-        self._on_frame_callback: Optional[Callable[[Mat, Mat], None]] = None  # type: ignore[valid-type]
+        self._on_frame_callback: Optional[Callable[[FrameMetadata, Mat, Mat], None]] = None  # type: ignore[valid-type]
         self._frame_count = 0
 
     @property
@@ -567,14 +594,18 @@ class DuplexShmController(IController):
 
     def start(
         self,
-        on_frame: Callable[[Mat, Mat], None],  # type: ignore[override,valid-type]
+        on_frame: Callable[[FrameMetadata, Mat, Mat], None],  # type: ignore[override,valid-type]
         cancellation_token: Optional[threading.Event] = None,
     ) -> None:
         """
-        Start duplex frame processing.
+        Start duplex frame processing with FrameMetadata.
+
+        The callback receives FrameMetadata (frame number, timestamp, dimensions),
+        input Mat, and output Mat. The 24-byte metadata prefix is stripped from
+        the frame data before creating the input Mat.
 
         Args:
-            on_frame: Callback that receives input frame and output frame to fill
+            on_frame: Callback that receives (FrameMetadata, input_mat, output_mat)
             cancellation_token: Optional cancellation token
         """
         if self._is_running:
@@ -590,7 +621,6 @@ class DuplexShmController(IController):
         )
 
         # Create duplex server using factory
-        # Convert timeout from milliseconds to seconds for Python API
         if not self._connection.buffer_name:
             raise ValueError("Buffer name is required for shared memory connection")
         timeout_seconds = self._connection.timeout_ms / 1000.0
@@ -698,91 +728,98 @@ class DuplexShmController(IController):
 
     def _process_duplex_frame(self, request_frame: Frame, response_writer: Writer) -> None:
         """
-        Process a frame in duplex mode.
+        Process a frame in duplex mode with FrameMetadata.
+
+        The frame data has a 24-byte FrameMetadata prefix that is stripped
+        before creating the input Mat.
 
         Args:
-            request_frame: Input frame from the request
+            request_frame: Input frame from the request (with metadata prefix)
             response_writer: Writer for the response frame
         """
-        logger.debug(
-            "_process_duplex_frame called, frame_count=%d, has_gst_caps=%s",
-            self._frame_count,
-            self._gst_caps is not None,
-        )
         try:
             if not self._on_frame_callback:
                 logger.warning("No frame callback set")
                 return
 
+            # Check frame size is sufficient for metadata
+            if request_frame.size < FRAME_METADATA_SIZE:
+                logger.warning("Frame too small for FrameMetadata: %d bytes", request_frame.size)
+                return
+
             self._frame_count += 1
 
-            # Try to read metadata if we don't have it yet
-            if (
-                self._metadata is None
-                and self._duplex_server
-                and self._duplex_server.request_reader
-            ):
-                try:
-                    metadata_bytes = self._duplex_server.request_reader.get_metadata()
-                    if metadata_bytes:
-                        # Use helper method to parse metadata
-                        metadata = self._parse_metadata_json(metadata_bytes)
-                        if metadata:
-                            self._metadata = metadata
-                            self._gst_caps = metadata.caps
-                            logger.info(
-                                "Successfully read metadata from buffer '%s': %s",
-                                self._connection.buffer_name,
-                                self._gst_caps,
-                            )
-                        else:
-                            logger.debug("Failed to parse metadata in frame processing")
-                except Exception as e:
-                    logger.debug("Failed to read metadata in frame processing: %s", e)
+            # Parse FrameMetadata from the beginning of the frame
+            frame_metadata = FrameMetadata.from_bytes(request_frame.data)
+
+            # Calculate pixel data offset and size
+            pixel_data_offset = FRAME_METADATA_SIZE
+            pixel_data_size = request_frame.size - FRAME_METADATA_SIZE
 
-            # Convert input frame to Mat
-            input_mat = self._frame_to_mat(request_frame)
-            if input_mat is None:
-                logger.error("Failed to convert frame to Mat, gst_caps=%s", self._gst_caps)
+            # GstCaps must be available for width/height/format
+            # (FrameMetadata no longer contains these - they're stream-level, not per-frame)
+            if not self._gst_caps:
+                logger.warning(
+                    "GstCaps not available, skipping frame %d", frame_metadata.frame_number
+                )
                 return
 
-            # Get buffer for output frame - use context manager for RAII
-            with response_writer.get_frame_buffer(request_frame.size) as output_buffer:
-                # Create output Mat from buffer (zero-copy)
-                if self._gst_caps:
-                    height = self._gst_caps.height or 480
-                    width = self._gst_caps.width or 640
+            width = self._gst_caps.width
+            height = self._gst_caps.height
+            format_str = self._gst_caps.format
+
+            # Determine channels from format
+            if format_str in ["RGB", "BGR"]:
+                channels = 3
+            elif format_str in ["RGBA", "BGRA", "ARGB", "ABGR"]:
+                channels = 4
+            elif format_str in ["GRAY8", "GRAY16_LE", "GRAY16_BE"]:
+                channels = 1
+            else:
+                channels = 3  # Default to RGB
+
+            # Create input Mat from pixel data (after metadata prefix)
+            pixel_data = np.frombuffer(request_frame.data[pixel_data_offset:], dtype=np.uint8)
+
+            expected_size = height * width * channels
+            if len(pixel_data) != expected_size:
+                logger.error(
+                    "Pixel data size mismatch. Expected %d bytes for %dx%d with %d channels, got %d",
+                    expected_size,
+                    width,
+                    height,
+                    channels,
+                    len(pixel_data),
+                )
+                return
 
-                    if self._gst_caps.format == "RGB" or self._gst_caps.format == "BGR":
-                        output_mat = np.frombuffer(output_buffer, dtype=np.uint8).reshape(
-                            (height, width, 3)
-                        )
-                    elif self._gst_caps.format == "GRAY8":
-                        output_mat = np.frombuffer(output_buffer, dtype=np.uint8).reshape(
-                            (height, width)
-                        )
-                    else:
-                        # Default to same shape as input
-                        output_mat = np.frombuffer(output_buffer, dtype=np.uint8).reshape(
-                            input_mat.shape
-                        )
+            # Reshape to image dimensions
+            if channels == 1:
+                input_mat = pixel_data.reshape((height, width))
+            else:
+                input_mat = pixel_data.reshape((height, width, channels))
+
+            # Response doesn't need metadata prefix - just pixel data
+            with response_writer.get_frame_buffer(pixel_data_size) as output_buffer:
+                # Create output Mat from buffer (zero-copy)
+                output_data = np.frombuffer(output_buffer, dtype=np.uint8)
+                if channels == 1:
+                    output_mat = output_data.reshape((height, width))
                 else:
-                    # Use same shape as input
-                    output_mat = np.frombuffer(output_buffer, dtype=np.uint8).reshape(
-                        input_mat.shape
-                    )
+                    output_mat = output_data.reshape((height, width, channels))
 
-                # Call user's processing function
-                self._on_frame_callback(input_mat, output_mat)
+                # Call user's processing function with metadata
+                self._on_frame_callback(frame_metadata, input_mat, output_mat)
 
             # Commit the response frame after buffer is released
             response_writer.commit_frame()
 
             logger.debug(
-                "Processed duplex frame %d (%dx%d)",
-                self._frame_count,
-                input_mat.shape[1],
-                input_mat.shape[0],
+                "Processed duplex frame %d (%dx%d %s)",
+                frame_metadata.frame_number,
+                width,
+                height,
+                format_str,
             )
 
         except Exception as e:

rocket_welder_sdk/frame_metadata.py

@@ -0,0 +1,138 @@
+"""
+Frame metadata structure prepended to each frame in zerobuffer shared memory.
+
+This module provides the FrameMetadata dataclass that matches the C++ struct
+defined in frame_metadata.h.
+
+Protocol Layout (16 bytes, 8-byte aligned):
+    [0-7]   frame_number    - Sequential frame index (0-based)
+    [8-15]  timestamp_ns    - GStreamer PTS in nanoseconds (UINT64_MAX if unavailable)
+
+Note: Width, height, and format are NOT included here because they are
+stream-level properties that never change per-frame. They are stored once
+in the ZeroBuffer metadata section as GstCaps (via GstMetadata).
+This avoids redundant data and follows single-source-of-truth principle.
+"""
+
+from __future__ import annotations
+
+import struct
+from dataclasses import dataclass
+from typing import ClassVar, Dict, Optional
+
+# Size of the FrameMetadata structure in bytes
+FRAME_METADATA_SIZE = 16
+
+# Value indicating timestamp is unavailable
+TIMESTAMP_UNAVAILABLE = 0xFFFFFFFFFFFFFFFF  # UINT64_MAX
+
+# Struct format: little-endian, 2 uint64
+# Q = unsigned long long (8 bytes)
+_FRAME_METADATA_FORMAT = "<QQ"
+
+
+@dataclass(frozen=True)
+class FrameMetadata:
+    """
+    Frame metadata prepended to each frame in zerobuffer shared memory.
+
+    Attributes:
+        frame_number: Sequential frame index (0-based, increments per frame)
+        timestamp_ns: GStreamer PTS in nanoseconds (TIMESTAMP_UNAVAILABLE if not set)
+
+    Note: Width, height, and format come from GstCaps in ZeroBuffer metadata section,
+    not from per-frame metadata. This avoids redundant data.
+    """
+
+    frame_number: int
+    timestamp_ns: int
+
+    @classmethod
+    def from_bytes(cls, data: bytes | memoryview) -> FrameMetadata:
+        """
+        Parse FrameMetadata from raw bytes.
+
+        Args:
+            data: At least 16 bytes of data
+
+        Returns:
+            FrameMetadata instance
+
+        Raises:
+            ValueError: If data is too short
+        """
+        if len(data) < FRAME_METADATA_SIZE:
+            raise ValueError(f"Data must be at least {FRAME_METADATA_SIZE} bytes, got {len(data)}")
+
+        # Unpack the struct
+        frame_number, timestamp_ns = struct.unpack(
+            _FRAME_METADATA_FORMAT, data[:FRAME_METADATA_SIZE]
+        )
+
+        return cls(
+            frame_number=frame_number,
+            timestamp_ns=timestamp_ns,
+        )
+
+    @property
+    def has_timestamp(self) -> bool:
+        """Check if timestamp is available."""
+        return self.timestamp_ns != TIMESTAMP_UNAVAILABLE
+
+    @property
+    def timestamp_ms(self) -> Optional[float]:
+        """Get timestamp in milliseconds, or None if unavailable."""
+        if self.has_timestamp:
+            return self.timestamp_ns / 1_000_000.0
+        return None
+
+    def __str__(self) -> str:
+        """Return string representation."""
+        timestamp = f"{self.timestamp_ns / 1_000_000.0:.3f}ms" if self.has_timestamp else "N/A"
+        return f"Frame {self.frame_number} @ {timestamp}"
+
+
+# Common GstVideoFormat values - kept for reference when working with GstCaps
+class GstVideoFormat:
+    """Common GStreamer video format values (for use with GstCaps)."""
+
+    UNKNOWN = 0
+    I420 = 2
+    YV12 = 3
+    YUY2 = 4
+    UYVY = 5
+    RGBA = 11
+    BGRA = 12
+    ARGB = 13
+    ABGR = 14
+    RGB = 15
+    BGR = 16
+    NV12 = 23
+    NV21 = 24
+    GRAY8 = 25
+    GRAY16_BE = 26
+    GRAY16_LE = 27
+
+    _FORMAT_NAMES: ClassVar[Dict[int, str]] = {
+        0: "UNKNOWN",
+        2: "I420",
+        3: "YV12",
+        4: "YUY2",
+        5: "UYVY",
+        11: "RGBA",
+        12: "BGRA",
+        13: "ARGB",
+        14: "ABGR",
+        15: "RGB",
+        16: "BGR",
+        23: "NV12",
+        24: "NV21",
+        25: "GRAY8",
+        26: "GRAY16_BE",
+        27: "GRAY16_LE",
+    }
+
+    @classmethod
+    def to_string(cls, format_value: int) -> str:
+        """Convert format value to string name."""
+        return cls._FORMAT_NAMES.get(format_value, f"FORMAT_{format_value}")

rocket_welder_sdk/high_level/__init__.py

@@ -0,0 +1,52 @@
+"""
+High-level API for RocketWelder SDK.
+
+Mirrors C# RocketWelder.SDK API for consistent developer experience.
+
+Example:
+    from rocket_welder_sdk.high_level import RocketWelderClient
+
+    with RocketWelderClient.from_environment() as client:
+        nose = client.keypoints.define_point("nose")
+        person = client.segmentation.define_class(1, "person")
+        client.start(process_frame)
+"""
+
+from .client import RocketWelderClient, RocketWelderClientOptions
+from .connection_strings import (
+    KeyPointsConnectionString,
+    SegmentationConnectionString,
+    VideoSourceConnectionString,
+    VideoSourceType,
+)
+from .data_context import (
+    IKeyPointsDataContext,
+    ISegmentationDataContext,
+)
+from .schema import (
+    IKeyPointsSchema,
+    ISegmentationSchema,
+    KeyPointDefinition,
+    SegmentClass,
+)
+from .transport_protocol import (
+    TransportKind,
+    TransportProtocol,
+)
+
+__all__ = [
+    "IKeyPointsDataContext",
+    "IKeyPointsSchema",
+    "ISegmentationDataContext",
+    "ISegmentationSchema",
+    "KeyPointDefinition",
+    "KeyPointsConnectionString",
+    "RocketWelderClient",
+    "RocketWelderClientOptions",
+    "SegmentClass",
+    "SegmentationConnectionString",
+    "TransportKind",
+    "TransportProtocol",
+    "VideoSourceConnectionString",
+    "VideoSourceType",
+]