rocket-welder-sdk 1.1.0__py3-none-any.whl → 1.1.25__py3-none-any.whl

rocket_welder_sdk/__init__.py

@@ -4,6 +4,9 @@ RocketWelder SDK - Enterprise-grade Python client library for video streaming se
 High-performance video streaming using shared memory (ZeroBuffer) for zero-copy operations.
 """
 
+import logging
+import os
+
 from .bytes_size import BytesSize
 from .connection_string import ConnectionMode, ConnectionString, Protocol
 from .controllers import DuplexShmController, IController, OneWayShmController
@@ -15,6 +18,25 @@ Client = RocketWelderClient
 
 __version__ = "1.1.0"
 
+# Configure library logger with NullHandler (best practice for libraries)
+logging.getLogger(__name__).addHandler(logging.NullHandler())
+
+# Configure from environment variable and propagate to zerobuffer
+_log_level = os.environ.get("ROCKET_WELDER_LOG_LEVEL")
+if _log_level:
+    try:
+        # Set rocket-welder-sdk log level
+        logging.getLogger(__name__).setLevel(getattr(logging, _log_level.upper()))
+
+        # Propagate to zerobuffer if not already set
+        if not os.environ.get("ZEROBUFFER_LOG_LEVEL"):
+            os.environ["ZEROBUFFER_LOG_LEVEL"] = _log_level
+            # Also configure zerobuffer logger if already imported
+            zerobuffer_logger = logging.getLogger("zerobuffer")
+            zerobuffer_logger.setLevel(getattr(logging, _log_level.upper()))
+    except AttributeError:
+        pass  # Invalid log level, ignore
+
 __all__ = [
     # Core types
     "BytesSize",

rocket_welder_sdk/controllers.py

@@ -14,6 +14,7 @@ from typing import Any, Callable
 import numpy as np
 from zerobuffer import BufferConfig, Frame, Reader, Writer
 from zerobuffer.duplex import DuplexChannelFactory, IImmutableDuplexServer
+from zerobuffer.exceptions import WriterDeadException
 
 from .connection_string import ConnectionMode, ConnectionString, Protocol
 from .gst_metadata import GstCaps, GstMetadata
@@ -21,6 +22,9 @@ from .gst_metadata import GstCaps, GstMetadata
 # Type alias for OpenCV Mat
 Mat = np.ndarray[Any, Any]
 
+# Module logger
+logger = logging.getLogger(__name__)
+
 
 class IController(ABC):
     """Abstract base class for controllers."""
@@ -63,13 +67,12 @@ class OneWayShmController(IController):
     as a zerosink, allowing zero-copy frame reception.
     """
 
-    def __init__(self, connection: ConnectionString, logger: logging.Logger | None = None):
+    def __init__(self, connection: ConnectionString):
         """
         Initialize the one-way controller.
 
         Args:
             connection: Connection string configuration
-            logger: Optional logger instance
         """
         if connection.protocol != Protocol.SHM:
             raise ValueError(
@@ -77,8 +80,6 @@ class OneWayShmController(IController):
             )
 
         self._connection = connection
-        self._logger = logger or logging.getLogger(__name__)
-        self._reader_logger = logging.getLogger(f"{__name__}.Reader")
         self._reader: Reader | None = None
         self._gst_caps: GstCaps | None = None
         self._metadata: GstMetadata | None = None
@@ -108,9 +109,7 @@ class OneWayShmController(IController):
         if self._is_running:
             raise RuntimeError("Controller is already running")
 
-        self._logger.debug(
-            "Starting OneWayShmController for buffer '%s'", self._connection.buffer_name
-        )
+        logger.debug("Starting OneWayShmController for buffer '%s'", self._connection.buffer_name)
         self._is_running = True
         self._cancellation_token = cancellation_token
 
@@ -124,9 +123,9 @@ class OneWayShmController(IController):
         # Pass logger to Reader for better debugging
         if not self._connection.buffer_name:
             raise ValueError("Buffer name is required for shared memory connection")
-        self._reader = Reader(self._connection.buffer_name, config, logger=self._reader_logger)
+        self._reader = Reader(self._connection.buffer_name, config)
 
-        self._logger.info(
+        logger.info(
             "Created shared memory buffer '%s' with size %s and metadata %s",
             self._connection.buffer_name,
             self._connection.buffer_size,
@@ -146,7 +145,7 @@ class OneWayShmController(IController):
         if not self._is_running:
             return
 
-        self._logger.debug("Stopping controller for buffer '%s'", self._connection.buffer_name)
+        logger.debug("Stopping controller for buffer '%s'", self._connection.buffer_name)
         self._is_running = False
 
         # Wait for worker thread to finish
@@ -160,7 +159,7 @@ class OneWayShmController(IController):
             self._reader = None
 
         self._worker_thread = None
-        self._logger.info("Stopped controller for buffer '%s'", self._connection.buffer_name)
+        logger.info("Stopped controller for buffer '%s'", self._connection.buffer_name)
 
     def _process_frames(self, on_frame: Callable[[Mat], None]) -> None:
         """
@@ -193,35 +192,39 @@ class OneWayShmController(IController):
                         if mat is not None:
                             on_frame(mat)
 
+                except WriterDeadException:
+                    # Writer has disconnected gracefully
+                    logger.info(
+                        "Writer disconnected gracefully from buffer '%s'",
+                        self._connection.buffer_name,
+                    )
+                    self._is_running = False
+                    break
                 except Exception as e:
                     # Log specific error types like C#
                     error_type = type(e).__name__
-                    if "ReaderDead" in error_type or "WriterDead" in error_type:
-                        self._logger.info(
-                            "Writer disconnected from buffer '%s'", self._connection.buffer_name
+                    if "ReaderDead" in error_type:
+                        logger.info(
+                            "Reader disconnected from buffer '%s'", self._connection.buffer_name
                         )
                         self._is_running = False
                         break
                     elif "BufferFull" in error_type:
-                        self._logger.error(
-                            "Buffer full on '%s': %s", self._connection.buffer_name, e
-                        )
+                        logger.error("Buffer full on '%s': %s", self._connection.buffer_name, e)
                         if not self._is_running:
                             break
                     elif "FrameTooLarge" in error_type:
-                        self._logger.error(
-                            "Frame too large on '%s': %s", self._connection.buffer_name, e
-                        )
+                        logger.error("Frame too large on '%s': %s", self._connection.buffer_name, e)
                         if not self._is_running:
                             break
                     elif "ZeroBuffer" in error_type:
-                        self._logger.error(
+                        logger.error(
                             "ZeroBuffer error on '%s': %s", self._connection.buffer_name, e
                         )
                         if not self._is_running:
                             break
                     else:
-                        self._logger.error(
+                        logger.error(
                             "Unexpected error processing frame from buffer '%s': %s",
                             self._connection.buffer_name,
                             e,
@@ -230,7 +233,7 @@ class OneWayShmController(IController):
                             break
 
         except Exception as e:
-            self._logger.error("Fatal error in frame processing loop: %s", e)
+            logger.error("Fatal error in frame processing loop: %s", e)
             self._is_running = False
 
     def _on_first_frame(self, on_frame: Callable[[Mat], None]) -> None:
@@ -258,53 +261,53 @@ class OneWayShmController(IController):
                     if metadata_bytes:
                         try:
                             # Log raw metadata for debugging
-                            self._logger.debug(
+                            logger.debug(
                                 "Raw metadata: %d bytes, type=%s, first 100 bytes: %s",
                                 len(metadata_bytes),
                                 type(metadata_bytes),
-                                bytes(metadata_bytes[:min(100, len(metadata_bytes))]),
+                                bytes(metadata_bytes[: min(100, len(metadata_bytes))]),
                             )
-                            
+
                             # Convert memoryview to bytes if needed
                             if isinstance(metadata_bytes, memoryview):
                                 metadata_bytes = bytes(metadata_bytes)
-                            
+
                             # Decode UTF-8
                             metadata_str = metadata_bytes.decode("utf-8")
-                            
+
                             # Check if metadata is empty or all zeros
-                            if not metadata_str or metadata_str == '\x00' * len(metadata_str):
-                                self._logger.warning("Metadata is empty or all zeros, skipping")
+                            if not metadata_str or metadata_str == "\x00" * len(metadata_str):
+                                logger.warning("Metadata is empty or all zeros, skipping")
                                 continue
-                            
+
                             # Find the start of JSON (skip any null bytes at the beginning)
-                            json_start = metadata_str.find('{')
+                            json_start = metadata_str.find("{")
                             if json_start == -1:
-                                self._logger.warning("No JSON found in metadata: %r", metadata_str[:100])
+                                logger.warning("No JSON found in metadata: %r", metadata_str[:100])
                                 continue
-                            
+
                             if json_start > 0:
-                                self._logger.debug("Skipping %d bytes before JSON", json_start)
+                                logger.debug("Skipping %d bytes before JSON", json_start)
                                 metadata_str = metadata_str[json_start:]
-                            
+
                             # Find the end of JSON (handle null padding)
-                            json_end = metadata_str.rfind('}')
+                            json_end = metadata_str.rfind("}")
                             if json_end != -1 and json_end < len(metadata_str) - 1:
-                                metadata_str = metadata_str[:json_end + 1]
-                            
+                                metadata_str = metadata_str[: json_end + 1]
+
                             metadata_json = json.loads(metadata_str)
                             self._metadata = GstMetadata.from_json(metadata_json)
                             self._gst_caps = self._metadata.caps
-                            self._logger.info(
+                            logger.info(
                                 "Received metadata from buffer '%s': %s",
                                 self._connection.buffer_name,
                                 self._gst_caps,
                             )
                         except Exception as e:
-                            self._logger.error("Failed to parse metadata: %s", e)
+                            logger.error("Failed to parse metadata: %s", e)
                             # Log the actual metadata content for debugging
                             if metadata_bytes:
-                                self._logger.debug("Metadata content: %r", metadata_bytes[:200])
+                                logger.debug("Metadata content: %r", metadata_bytes[:200])
                             # Don't continue without metadata
                             continue
 
@@ -314,17 +317,24 @@ class OneWayShmController(IController):
                         on_frame(mat)
                         return  # Successfully processed first frame
 
+            except WriterDeadException:
+                self._is_running = False
+                logger.info(
+                    "Writer disconnected gracefully while waiting for first frame on buffer '%s'",
+                    self._connection.buffer_name,
+                )
+                raise
             except Exception as e:
                 error_type = type(e).__name__
-                if "ReaderDead" in error_type or "WriterDead" in error_type:
+                if "ReaderDead" in error_type:
                     self._is_running = False
-                    self._logger.info(
-                        "Writer disconnected while waiting for first frame on buffer '%s'",
+                    logger.info(
+                        "Reader disconnected while waiting for first frame on buffer '%s'",
                         self._connection.buffer_name,
                     )
                     raise
                 else:
-                    self._logger.error(
+                    logger.error(
                         "Error waiting for first frame on buffer '%s': %s",
                         self._connection.buffer_name,
                         e,
@@ -367,7 +377,7 @@ class OneWayShmController(IController):
                 # Check data size matches expected
                 expected_size = height * width * channels
                 if len(data) != expected_size:
-                    self._logger.error(
+                    logger.error(
                         "Data size mismatch. Expected %d bytes for %dx%d with %d channels, got %d",
                         expected_size,
                         width,
@@ -386,17 +396,48 @@ class OneWayShmController(IController):
                 elif channels == 4:
                     mat = data.reshape((height, width, 4))
                 else:
-                    self._logger.error("Unsupported channel count: %d", channels)
+                    logger.error("Unsupported channel count: %d", channels)
                     return None
 
                 return mat  # type: ignore[no-any-return]
 
-            # No caps available
-            self._logger.error("No GstCaps available for frame conversion")
+            # 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)
+            common_resolutions = [
+                (640, 480, 3),  # VGA RGB
+                (640, 480, 4),  # VGA RGBA
+                (1280, 720, 3),  # 720p RGB
+                (1920, 1080, 3),  # 1080p RGB
+                (640, 480, 1),  # VGA Grayscale
+            ]
+
+            for width, height, channels in common_resolutions:
+                if frame_size == width * height * channels:
+                    logger.info(f"Inferred resolution: {width}x{height} with {channels} channels")
+
+                    # Create caps for future use
+                    format_str = "RGB" if channels == 3 else "RGBA" if channels == 4 else "GRAY8"
+                    self._gst_caps = GstCaps.from_simple(
+                        width=width, height=height, format=format_str
+                    )
+
+                    # Create Mat
+                    data = np.frombuffer(frame.data, dtype=np.uint8)
+                    if channels == 3:
+                        return data.reshape((height, width, 3))  # type: ignore[no-any-return]
+                    elif channels == 1:
+                        return data.reshape((height, width))  # type: ignore[no-any-return]
+                    elif channels == 4:
+                        return data.reshape((height, width, 4))  # type: ignore[no-any-return]
+
+            logger.error(f"Could not infer resolution for frame size {frame_size}")
             return None
 
         except Exception as e:
-            self._logger.error("Failed to convert frame to Mat: %s", e)
+            logger.error("Failed to convert frame to Mat: %s", e)
             return None
 
     def _infer_caps_from_frame(self, mat: Mat) -> None:
@@ -412,12 +453,12 @@ class OneWayShmController(IController):
         shape = mat.shape
         if len(shape) == 2:
             # Grayscale
-            self._gst_caps = GstCaps(format="GRAY8", width=shape[1], height=shape[0])
+            self._gst_caps = GstCaps.from_simple(width=shape[1], height=shape[0], format="GRAY8")
         elif len(shape) == 3:
             # Color image
-            self._gst_caps = GstCaps(format="BGR", width=shape[1], height=shape[0])
+            self._gst_caps = GstCaps.from_simple(width=shape[1], height=shape[0], format="BGR")
 
-        self._logger.info("Inferred caps from frame: %s", self._gst_caps)
+        logger.info("Inferred caps from frame: %s", self._gst_caps)
 
 
 class DuplexShmController(IController):
@@ -428,13 +469,12 @@ class DuplexShmController(IController):
     sending processed frames to another buffer.
     """
 
-    def __init__(self, connection: ConnectionString, logger: logging.Logger | None = None):
+    def __init__(self, connection: ConnectionString):
         """
         Initialize the duplex controller.
 
         Args:
             connection: Connection string configuration
-            logger: Optional logger instance
         """
         if connection.protocol != Protocol.SHM:
             raise ValueError(
@@ -447,7 +487,6 @@ class DuplexShmController(IController):
             )
 
         self._connection = connection
-        self._logger = logger or logging.getLogger(__name__)
         self._duplex_server: IImmutableDuplexServer | None = None
         self._gst_caps: GstCaps | None = None
         self._metadata: GstMetadata | None = None
@@ -498,7 +537,7 @@ class DuplexShmController(IController):
             self._connection.buffer_name, config, timeout_seconds
         )
 
-        self._logger.info(
+        logger.info(
             "Starting duplex server for channel '%s' with size %s and metadata %s",
             self._connection.buffer_name,
             self._connection.buffer_size,
@@ -514,7 +553,7 @@ class DuplexShmController(IController):
         if not self._is_running:
             return
 
-        self._logger.info("Stopping DuplexShmController")
+        logger.info("Stopping DuplexShmController")
         self._is_running = False
 
         # Stop the duplex server
@@ -522,7 +561,7 @@ class DuplexShmController(IController):
             self._duplex_server.stop()
             self._duplex_server = None
 
-        self._logger.info("DuplexShmController stopped")
+        logger.info("DuplexShmController stopped")
 
     def _on_metadata(self, metadata_bytes: bytes | memoryview) -> None:
         """
@@ -531,18 +570,29 @@ class DuplexShmController(IController):
         Args:
             metadata_bytes: Raw metadata bytes or memoryview
         """
+        logger.debug(
+            "_on_metadata called with %d bytes", len(metadata_bytes) if metadata_bytes else 0
+        )
         try:
             # Convert memoryview to bytes if needed
             if isinstance(metadata_bytes, memoryview):
                 metadata_bytes = bytes(metadata_bytes)
-            
+
+            # Log raw bytes for debugging
+            logger.debug(
+                "Raw metadata bytes (first 100): %r",
+                metadata_bytes[: min(100, len(metadata_bytes))],
+            )
+
             metadata_str = metadata_bytes.decode("utf-8")
+            logger.debug("Decoded metadata string: %r", metadata_str[: min(200, len(metadata_str))])
+
             metadata_json = json.loads(metadata_str)
             self._metadata = GstMetadata.from_json(metadata_json)
             self._gst_caps = self._metadata.caps
-            self._logger.info("Received metadata: %s", self._metadata)
+            logger.info("Received metadata: %s", self._metadata)
         except Exception as e:
-            self._logger.warning("Failed to parse metadata: %s", e)
+            logger.error("Failed to parse metadata: %s", e, exc_info=True)
 
     def _process_duplex_frame(self, request_frame: Frame, response_writer: Writer) -> None:
         """
@@ -552,8 +602,14 @@ class DuplexShmController(IController):
             request_frame: Input frame from the request
             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
 
             self._frame_count += 1
@@ -561,6 +617,7 @@ class DuplexShmController(IController):
             # 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)
                 return
 
             # Get buffer for output frame - use context manager for RAII
@@ -585,7 +642,9 @@ class DuplexShmController(IController):
                         )
                 else:
                     # Use same shape as input
-                    output_mat = np.frombuffer(output_buffer, dtype=np.uint8).reshape(input_mat.shape)
+                    output_mat = np.frombuffer(output_buffer, dtype=np.uint8).reshape(
+                        input_mat.shape
+                    )
 
                 # Call user's processing function
                 self._on_frame_callback(input_mat, output_mat)
@@ -593,7 +652,7 @@ class DuplexShmController(IController):
             # Commit the response frame after buffer is released
             response_writer.commit_frame()
 
-            self._logger.debug(
+            logger.debug(
                 "Processed duplex frame %d (%dx%d)",
                 self._frame_count,
                 input_mat.shape[1],
@@ -601,7 +660,7 @@ class DuplexShmController(IController):
             )
 
         except Exception as e:
-            self._logger.error("Error processing duplex frame: %s", e)
+            logger.error("Error processing duplex frame: %s", e)
 
     def _frame_to_mat(self, frame: Frame) -> Mat | None:
         """Convert frame to OpenCV Mat (reuse from OneWayShmController)."""

rocket_welder_sdk/gst_metadata.py

@@ -6,9 +6,13 @@ Matches C# GstCaps and GstMetadata functionality.
 from __future__ import annotations
 
 import json
-from dataclasses import dataclass, field
+import re
+from dataclasses import dataclass
 from typing import Any
 
+import numpy as np
+import numpy.typing as npt
+
 
 @dataclass
 class GstCaps:
@@ -16,172 +20,312 @@ class GstCaps:
     GStreamer capabilities representation.
 
     Represents video format capabilities including format, dimensions, framerate, etc.
+    Matches the C# GstCaps implementation with proper parsing and numpy integration.
     """
 
-    format: str | None = None
-    width: int | None = None
-    height: int | None = None
-    framerate: str | None = None  # e.g., "30/1" or "25/1"
-    pixel_aspect_ratio: str | None = None  # e.g., "1/1"
-    interlace_mode: str | None = None  # e.g., "progressive"
+    width: int
+    height: int
+    format: str
+    depth_type: type[np.uint8] | type[np.uint16]
+    channels: int
+    bytes_per_pixel: int
+    framerate_num: int | None = None
+    framerate_den: int | None = None
+    interlace_mode: str | None = None
     colorimetry: str | None = None
-    chroma_site: str | None = None
+    caps_string: str | None = None
+
+    @property
+    def frame_size(self) -> int:
+        """Calculate the expected frame size in bytes."""
+        return self.width * self.height * self.bytes_per_pixel
 
-    # Additional fields can be stored here
-    extra_fields: dict[str, Any] = field(default_factory=dict)
+    @property
+    def framerate(self) -> float | None:
+        """Get framerate as double (FPS)."""
+        if (
+            self.framerate_num is not None
+            and self.framerate_den is not None
+            and self.framerate_den > 0
+        ):
+            return self.framerate_num / self.framerate_den
+        return None
 
     @classmethod
-    def from_dict(cls, data: dict[str, Any]) -> GstCaps:
+    def parse(cls, caps_string: str) -> GstCaps:
         """
-        Create GstCaps from dictionary.
+        Parse GStreamer caps string.
+        Example: "video/x-raw, format=(string)RGB, width=(int)640, height=(int)480, framerate=(fraction)30/1"
 
         Args:
-            data: Dictionary containing caps data
+            caps_string: GStreamer caps string
 
         Returns:
             GstCaps instance
+
+        Raises:
+            ValueError: If caps string is invalid
         """
-        # Extract known fields
-        caps = cls(
-            format=data.get("format"),
-            width=data.get("width"),
-            height=data.get("height"),
-            framerate=data.get("framerate"),
-            pixel_aspect_ratio=data.get("pixel-aspect-ratio"),
-            interlace_mode=data.get("interlace-mode"),
-            colorimetry=data.get("colorimetry"),
-            chroma_site=data.get("chroma-site"),
-        )
+        if not caps_string or not caps_string.strip():
+            raise ValueError("Empty caps string")
 
-        # Store any extra fields
-        known_fields = {
-            "format",
-            "width",
-            "height",
-            "framerate",
-            "pixel-aspect-ratio",
-            "interlace-mode",
-            "colorimetry",
-            "chroma-site",
-        }
+        caps_string = caps_string.strip()
 
-        for key, value in data.items():
-            if key not in known_fields:
-                caps.extra_fields[key] = value
+        # Check if it's a video caps
+        if not caps_string.startswith("video/x-raw"):
+            raise ValueError(f"Not a video/x-raw caps string: {caps_string}")
 
-        return caps
+        try:
+            # Parse width
+            width_match = re.search(r"width=\(int\)(\d+)", caps_string)
+            if not width_match:
+                raise ValueError("Missing width in caps string")
+            width = int(width_match.group(1))
+
+            # Parse height
+            height_match = re.search(r"height=\(int\)(\d+)", caps_string)
+            if not height_match:
+                raise ValueError("Missing height in caps string")
+            height = int(height_match.group(1))
+
+            # Parse format
+            format_match = re.search(r"format=\(string\)(\w+)", caps_string)
+            format_str = format_match.group(1) if format_match else "RGB"
+
+            # Parse framerate (optional)
+            framerate_num = None
+            framerate_den = None
+            framerate_match = re.search(r"framerate=\(fraction\)(\d+)/(\d+)", caps_string)
+            if framerate_match:
+                framerate_num = int(framerate_match.group(1))
+                framerate_den = int(framerate_match.group(2))
+
+            # Parse interlace mode (optional)
+            interlace_mode = None
+            interlace_match = re.search(r"interlace-mode=\(string\)(\w+)", caps_string)
+            if interlace_match:
+                interlace_mode = interlace_match.group(1)
+
+            # Parse colorimetry (optional)
+            colorimetry = None
+            colorimetry_match = re.search(r"colorimetry=\(string\)([\w:]+)", caps_string)
+            if colorimetry_match:
+                colorimetry = colorimetry_match.group(1)
+
+            # Map format to numpy dtype and get channel info
+            depth_type, channels, bytes_per_pixel = cls._map_gstreamer_format_to_numpy(format_str)
+
+            return cls(
+                width=width,
+                height=height,
+                format=format_str,
+                depth_type=depth_type,
+                channels=channels,
+                bytes_per_pixel=bytes_per_pixel,
+                framerate_num=framerate_num,
+                framerate_den=framerate_den,
+                interlace_mode=interlace_mode,
+                colorimetry=colorimetry,
+                caps_string=caps_string,
+            )
+        except Exception as e:
+            raise ValueError(f"Failed to parse caps string: {caps_string}") from e
 
     @classmethod
-    def from_string(cls, caps_string: str) -> GstCaps:
+    def from_simple(cls, width: int, height: int, format: str = "RGB") -> GstCaps:
         """
-        Parse GStreamer caps string.
+        Create GstCaps from simple parameters.
 
         Args:
-            caps_string: GStreamer caps string (e.g., "video/x-raw,format=RGB,width=640,height=480")
+            width: Frame width
+            height: Frame height
+            format: Pixel format (default: "RGB")
 
         Returns:
             GstCaps instance
         """
-        if not caps_string:
-            return cls()
+        depth_type, channels, bytes_per_pixel = cls._map_gstreamer_format_to_numpy(format)
+        return cls(
+            width=width,
+            height=height,
+            format=format,
+            depth_type=depth_type,
+            channels=channels,
+            bytes_per_pixel=bytes_per_pixel,
+        )
 
-        # Remove media type prefix if present
-        if "/" in caps_string and "," in caps_string:
-            # Has media type prefix (e.g., "video/x-raw,format=RGB")
-            _, params = caps_string.split(",", 1)
-        else:
-            # No media type prefix (e.g., "format=RGB,width=320")
-            params = caps_string
-
-        # Parse parameters
-        data: dict[str, Any] = {}
-        for param in params.split(","):
-            if "=" in param:
-                key, value = param.split("=", 1)
-                key = key.strip()
-                value_str = value.strip()
-
-                # Try to parse numeric values
-                if value_str.isdigit():
-                    data[key] = int(value_str)
-                elif key in ["width", "height"] and value_str.startswith("(int)"):
-                    data[key] = int(value_str[5:].strip())
-                else:
-                    data[key] = value_str
-
-        return cls.from_dict(data)
+    @staticmethod
+    def _map_gstreamer_format_to_numpy(
+        format: str,
+    ) -> tuple[type[np.uint8] | type[np.uint16], int, int]:
+        """
+        Map GStreamer format strings to numpy dtype.
+        Reference: https://gstreamer.freedesktop.org/documentation/video/video-format.html
 
-    def to_dict(self) -> dict[str, Any]:
-        """Convert to dictionary representation."""
-        result: dict[str, Any] = {}
-
-        if self.format is not None:
-            result["format"] = self.format
-        if self.width is not None:
-            result["width"] = self.width
-        if self.height is not None:
-            result["height"] = self.height
-        if self.framerate is not None:
-            result["framerate"] = self.framerate
-        if self.pixel_aspect_ratio is not None:
-            result["pixel-aspect-ratio"] = self.pixel_aspect_ratio
-        if self.interlace_mode is not None:
-            result["interlace-mode"] = self.interlace_mode
-        if self.colorimetry is not None:
-            result["colorimetry"] = self.colorimetry
-        if self.chroma_site is not None:
-            result["chroma-site"] = self.chroma_site
+        Args:
+            format: GStreamer format string
 
-        # Add extra fields
-        result.update(self.extra_fields)
+        Returns:
+            Tuple of (numpy dtype, channels, bytes_per_pixel)
+        """
+        format_upper = format.upper() if format else "RGB"
+
+        format_map = {
+            # RGB formats
+            "RGB": (np.uint8, 3, 3),
+            "BGR": (np.uint8, 3, 3),
+            "RGBA": (np.uint8, 4, 4),
+            "BGRA": (np.uint8, 4, 4),
+            "ARGB": (np.uint8, 4, 4),
+            "ABGR": (np.uint8, 4, 4),
+            "RGBX": (np.uint8, 4, 4),  # RGB with padding
+            "BGRX": (np.uint8, 4, 4),  # BGR with padding
+            "XRGB": (np.uint8, 4, 4),  # RGB with padding
+            "XBGR": (np.uint8, 4, 4),  # BGR with padding
+            # 16-bit RGB formats
+            "RGB16": (np.uint16, 3, 6),
+            "BGR16": (np.uint16, 3, 6),
+            # Grayscale formats
+            "GRAY8": (np.uint8, 1, 1),
+            "GRAY16_LE": (np.uint16, 1, 2),
+            "GRAY16_BE": (np.uint16, 1, 2),
+            # YUV planar formats (Y plane only for simplicity)
+            "I420": (np.uint8, 1, 1),
+            "YV12": (np.uint8, 1, 1),
+            "NV12": (np.uint8, 1, 1),
+            "NV21": (np.uint8, 1, 1),
+            # YUV packed formats
+            "YUY2": (np.uint8, 2, 2),
+            "UYVY": (np.uint8, 2, 2),
+            "YVYU": (np.uint8, 2, 2),
+            # Bayer formats (raw sensor data)
+            "BGGR": (np.uint8, 1, 1),
+            "RGGB": (np.uint8, 1, 1),
+            "GRBG": (np.uint8, 1, 1),
+            "GBRG": (np.uint8, 1, 1),
+        }
 
-        return result
+        # Default to RGB if unknown
+        return format_map.get(format_upper, (np.uint8, 3, 3))
 
-    def to_string(self) -> str:
-        """Convert to GStreamer caps string format."""
-        params = []
-
-        if self.format:
-            params.append(f"format={self.format}")
-        if self.width is not None:
-            params.append(f"width={self.width}")
-        if self.height is not None:
-            params.append(f"height={self.height}")
-        if self.framerate:
-            params.append(f"framerate={self.framerate}")
-        if self.pixel_aspect_ratio:
-            params.append(f"pixel-aspect-ratio={self.pixel_aspect_ratio}")
-        if self.interlace_mode:
-            params.append(f"interlace-mode={self.interlace_mode}")
+    def create_array(
+        self, data: bytes | memoryview | npt.NDArray[np.uint8] | npt.NDArray[np.uint16]
+    ) -> npt.NDArray[np.uint8] | npt.NDArray[np.uint16]:
+        """
+        Create numpy array with proper format from data.
+
+        Args:
+            data: Frame data as bytes, memoryview, or existing numpy array
+
+        Returns:
+            Numpy array with proper shape and dtype
+
+        Raises:
+            ValueError: If data size doesn't match expected frame size
+        """
+        # Convert memoryview to bytes if needed
+        if isinstance(data, memoryview):
+            data = bytes(data)
+
+        # If it's already a numpy array, check size and reshape if needed
+        if isinstance(data, np.ndarray):
+            if data.size * data.itemsize != self.frame_size:
+                raise ValueError(
+                    f"Data size mismatch. Expected {self.frame_size} bytes for "
+                    f"{self.width}x{self.height} {self.format}, got {data.size * data.itemsize}"
+                )
+            # Reshape if needed
+            if self.channels == 1:
+                return data.reshape((self.height, self.width))
+            else:
+                return data.reshape((self.height, self.width, self.channels))
+
+        # Check data size
+        if len(data) != self.frame_size:
+            raise ValueError(
+                f"Data size mismatch. Expected {self.frame_size} bytes for "
+                f"{self.width}x{self.height} {self.format}, got {len(data)}"
+            )
+
+        # Create array from bytes
+        arr = np.frombuffer(data, dtype=self.depth_type)
+
+        # Reshape based on channels
+        if self.channels == 1:
+            return arr.reshape((self.height, self.width))
+        else:
+            # For multi-channel images, reshape to (height, width, channels)
+            total_pixels = self.width * self.height * self.channels
+            if self.depth_type == np.uint16:
+                # For 16-bit formats, we need to account for the item size
+                arr = arr[:total_pixels]
+            return arr.reshape((self.height, self.width, self.channels))
+
+    def create_array_from_pointer(
+        self, ptr: int, copy: bool = False
+    ) -> npt.NDArray[np.uint8] | npt.NDArray[np.uint16]:
+        """
+        Create numpy array from memory pointer (zero-copy by default).
 
-        # Add extra fields
-        for key, value in self.extra_fields.items():
-            params.append(f"{key}={value}")
+        Args:
+            ptr: Memory pointer as integer
+            copy: If True, make a copy of the data; if False, create a view
 
-        if params:
-            return "video/x-raw," + ",".join(params)
+        Returns:
+            Numpy array with proper shape and dtype
+        """
+        # Calculate total elements based on depth type
+        if self.depth_type == np.uint16:
+            total_elements = self.width * self.height * self.channels
         else:
-            return "video/x-raw"
+            total_elements = self.frame_size
 
-    @property
-    def framerate_tuple(self) -> tuple[int, int] | None:
-        """Get framerate as a tuple of (numerator, denominator)."""
-        if not self.framerate or "/" not in self.framerate:
-            return None
+        # Create array from pointer using ctypes
+        import ctypes
 
-        try:
-            num, denom = self.framerate.split("/")
-            return (int(num), int(denom))
-        except (ValueError, AttributeError):
-            return None
+        # Create a buffer from the pointer
+        buffer_size = total_elements * self.depth_type.itemsize
+        c_buffer = (ctypes.c_byte * buffer_size).from_address(ptr)
+        arr = np.frombuffer(c_buffer, dtype=self.depth_type)
 
-    @property
-    def fps(self) -> float | None:
-        """Get framerate as floating-point FPS value."""
-        fr = self.framerate_tuple
-        if fr and fr[1] != 0:
-            return fr[0] / fr[1]
-        return None
+        # Reshape based on channels
+        if self.channels == 1:
+            shaped = arr.reshape((self.height, self.width))
+        else:
+            shaped = arr.reshape((self.height, self.width, self.channels))
+
+        return shaped.copy() if copy else shaped
+
+    def __str__(self) -> str:
+        """String representation."""
+        # If we have the original caps string, return it for perfect round-tripping
+        if self.caps_string:
+            return self.caps_string
+
+        # Otherwise build a simple display string
+        fps = f" @ {self.framerate:.2f}fps" if self.framerate else ""
+        return f"{self.width}x{self.height} {self.format}{fps}"
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to dictionary representation."""
+        result = {
+            "width": self.width,
+            "height": self.height,
+            "format": self.format,
+            "channels": self.channels,
+            "bytes_per_pixel": self.bytes_per_pixel,
+        }
+
+        if self.framerate_num is not None:
+            result["framerate_num"] = self.framerate_num
+        if self.framerate_den is not None:
+            result["framerate_den"] = self.framerate_den
+        if self.interlace_mode:
+            result["interlace_mode"] = self.interlace_mode
+        if self.colorimetry:
+            result["colorimetry"] = self.colorimetry
+
+        return result
 
 
 @dataclass
@@ -190,6 +334,7 @@ class GstMetadata:
     GStreamer metadata structure.
 
     Matches the JSON structure written by GStreamer plugins.
+    Compatible with C# GstMetadata record.
     """
 
     type: str
@@ -207,24 +352,46 @@ class GstMetadata:
 
         Returns:
             GstMetadata instance
+
+        Raises:
+            ValueError: If JSON is invalid or missing required fields
         """
-        data = json.loads(json_data) if isinstance(json_data, (str, bytes)) else json_data
+        # Parse JSON if needed
+        if isinstance(json_data, (str, bytes)):
+            if isinstance(json_data, bytes):
+                json_data = json_data.decode("utf-8")
+            try:
+                data = json.loads(json_data)
+            except json.JSONDecodeError as e:
+                raise ValueError(f"Invalid JSON: {e}") from e
+        else:
+            data = json_data
+
+        # Validate required fields
+        if not isinstance(data, dict):
+            raise ValueError("JSON must be an object/dictionary")
+
+        # Get required fields
+        type_str = data.get("type", "")
+        version = data.get("version", "")
+        element_name = data.get("element_name", "")
 
-        # Parse caps
-        caps_data = data.get("caps", {})
+        # Parse caps - it's a STRING in the JSON!
+        caps_data = data.get("caps")
         if isinstance(caps_data, str):
-            caps = GstCaps.from_string(caps_data)
+            # This is the normal case - caps is a string that needs parsing
+            caps = GstCaps.parse(caps_data)
         elif isinstance(caps_data, dict):
-            caps = GstCaps.from_dict(caps_data)
+            # Fallback for dict format (shouldn't happen with real GStreamer)
+            # Create a simple caps from dict
+            width = caps_data.get("width", 640)
+            height = caps_data.get("height", 480)
+            format_str = caps_data.get("format", "RGB")
+            caps = GstCaps.from_simple(width, height, format_str)
         else:
-            caps = GstCaps()
+            raise ValueError(f"Invalid caps data type: {type(caps_data)}")
 
-        return cls(
-            type=data.get("type", ""),
-            version=data.get("version", ""),
-            caps=caps,
-            element_name=data.get("element_name", ""),
-        )
+        return cls(type=type_str, version=version, caps=caps, element_name=element_name)
 
     def to_json(self) -> str:
         """Convert to JSON string."""
@@ -235,6 +402,10 @@ class GstMetadata:
         return {
             "type": self.type,
             "version": self.version,
-            "caps": self.caps.to_dict(),
+            "caps": str(self.caps),  # Caps as string for C# compatibility
             "element_name": self.element_name,
         }
+
+    def __str__(self) -> str:
+        """String representation."""
+        return f"GstMetadata(type={self.type}, element={self.element_name}, caps={self.caps})"

rocket_welder_sdk/rocket_welder_client.py

@@ -20,6 +20,9 @@ if TYPE_CHECKING:
 # Type alias for OpenCV Mat
 Mat = np.ndarray[Any, Any]
 
+# Module logger
+logger = logging.getLogger(__name__)
+
 
 class RocketWelderClient:
     """
@@ -28,20 +31,18 @@ class RocketWelderClient:
     Provides a unified interface for different connection types and protocols.
     """
 
-    def __init__(self, connection: str | ConnectionString, logger: logging.Logger | None = None):
+    def __init__(self, connection: str | ConnectionString):
         """
         Initialize the RocketWelder client.
 
         Args:
             connection: Connection string or ConnectionString object
-            logger: Optional logger instance
         """
         if isinstance(connection, str):
             self._connection = ConnectionString.parse(connection)
         else:
             self._connection = connection
 
-        self._logger = logger or logging.getLogger(__name__)
         self._controller: IController | None = None
         self._lock = threading.Lock()
 
@@ -93,15 +94,15 @@ class RocketWelderClient:
             # Create appropriate controller based on connection
             if self._connection.protocol == Protocol.SHM:
                 if self._connection.connection_mode == ConnectionMode.DUPLEX:
-                    self._controller = DuplexShmController(self._connection, self._logger)
+                    self._controller = DuplexShmController(self._connection)
                 else:
-                    self._controller = OneWayShmController(self._connection, self._logger)
+                    self._controller = OneWayShmController(self._connection)
             else:
                 raise ValueError(f"Unsupported protocol: {self._connection.protocol}")
 
             # Start the controller
             self._controller.start(on_frame, cancellation_token)  # type: ignore[arg-type]
-            self._logger.info("RocketWelder client started with %s", self._connection)
+            logger.info("RocketWelder client started with %s", self._connection)
 
     def stop(self) -> None:
         """Stop the client and clean up resources."""
@@ -109,7 +110,7 @@ class RocketWelderClient:
             if self._controller:
                 self._controller.stop()
                 self._controller = None
-                self._logger.info("RocketWelder client stopped")
+                logger.info("RocketWelder client stopped")
 
     def __enter__(self) -> RocketWelderClient:
         """Context manager entry."""
@@ -125,7 +126,6 @@ class RocketWelderClient:
         buffer_name: str,
         buffer_size: str = "256MB",
         metadata_size: str = "4KB",
-        logger: logging.Logger | None = None,
     ) -> RocketWelderClient:
         """
         Create a one-way shared memory client.
@@ -134,7 +134,6 @@ class RocketWelderClient:
             buffer_name: Name of the shared memory buffer
             buffer_size: Size of the buffer (e.g., "256MB")
             metadata_size: Size of metadata buffer (e.g., "4KB")
-            logger: Optional logger
 
         Returns:
             Configured RocketWelderClient instance
@@ -142,7 +141,7 @@ class RocketWelderClient:
         connection_str = (
             f"shm://{buffer_name}?size={buffer_size}&metadata={metadata_size}&mode=OneWay"
         )
-        return cls(connection_str, logger)
+        return cls(connection_str)
 
     @classmethod
     def create_duplex_shm(
@@ -150,7 +149,6 @@ class RocketWelderClient:
         buffer_name: str,
         buffer_size: str = "256MB",
         metadata_size: str = "4KB",
-        logger: logging.Logger | None = None,
     ) -> RocketWelderClient:
         """
         Create a duplex shared memory client.
@@ -159,7 +157,6 @@ class RocketWelderClient:
             buffer_name: Name of the shared memory buffer
             buffer_size: Size of the buffer (e.g., "256MB")
             metadata_size: Size of metadata buffer (e.g., "4KB")
-            logger: Optional logger
 
         Returns:
             Configured RocketWelderClient instance
@@ -167,4 +164,4 @@ class RocketWelderClient:
         connection_str = (
             f"shm://{buffer_name}?size={buffer_size}&metadata={metadata_size}&mode=Duplex"
         )
-        return cls(connection_str, logger)
+        return cls(connection_str)

{rocket_welder_sdk-1.1.0.dist-info → rocket_welder_sdk-1.1.25.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: rocket-welder-sdk
-Version: 1.1.0
+Version: 1.1.25
 Summary: High-performance video streaming SDK for RocketWelder services using ZeroBuffer IPC
 Home-page: https://github.com/modelingevolution/rocket-welder-sdk
 Author: ModelingEvolution
@@ -27,7 +27,8 @@ Requires-Python: >=3.8
 Description-Content-Type: text/markdown
 Requires-Dist: numpy>=1.20.0
 Requires-Dist: opencv-python>=4.5.0
-Requires-Dist: zerobuffer-ipc>=1.1.10
+Requires-Dist: zerobuffer-ipc>=1.1.17
+Requires-Dist: pydantic>=2.5.0
 Provides-Extra: dev
 Requires-Dist: pytest>=7.0; extra == "dev"
 Requires-Dist: pytest-cov>=4.0; extra == "dev"

rocket_welder_sdk-1.1.25.dist-info/RECORD

@@ -0,0 +1,11 @@
+rocket_welder_sdk/__init__.py,sha256=hv0U_UsvIjyLhZLsumjGwKrBJs8vzb1kczUzANilHug,1789
+rocket_welder_sdk/bytes_size.py,sha256=Myl29-wyWCIYdbMmgaxXebT8Dz8_Fwcr3fnfaNW81P0,7463
+rocket_welder_sdk/connection_string.py,sha256=msDgHD7525UXvrNPqKGpYgQJJtmOfS_XEnX3JA8LIz0,7731
+rocket_welder_sdk/controllers.py,sha256=IhPJfwVlk0pxOuTRPW_Xp_3H_BZG6AJXQfS7DCfBrhg,26177
+rocket_welder_sdk/gst_metadata.py,sha256=jEQvZX4BdR6OR3lqp12PV-HEXZhcxfiS010diA2CbMM,14213
+rocket_welder_sdk/py.typed,sha256=0cXFZXmes4Y-vnl4lO3HtyyyWaFNw85B7tJdFeCtHDc,67
+rocket_welder_sdk/rocket_welder_client.py,sha256=uvaAtog-xVCY9YldisgkCnCkbEWMHEgrJUUWJA1J3hg,5237
+rocket_welder_sdk-1.1.25.dist-info/METADATA,sha256=4FF40eEwgdMu0vxF0cwsHgdayWGHc7xQ-C9WJ0KY6To,14362
+rocket_welder_sdk-1.1.25.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+rocket_welder_sdk-1.1.25.dist-info/top_level.txt,sha256=2iZvBjnwVCUW-uDE23-eJld5PZ9-mlPI69QiXM5IrTA,18
+rocket_welder_sdk-1.1.25.dist-info/RECORD,,

rocket_welder_sdk-1.1.0.dist-info/RECORD

@@ -1,11 +0,0 @@
-rocket_welder_sdk/__init__.py,sha256=6lQUKg8w-qK_5DRFOiydCdirGAj9t-dcCBmDyuW9GNc,909
-rocket_welder_sdk/bytes_size.py,sha256=Myl29-wyWCIYdbMmgaxXebT8Dz8_Fwcr3fnfaNW81P0,7463
-rocket_welder_sdk/connection_string.py,sha256=msDgHD7525UXvrNPqKGpYgQJJtmOfS_XEnX3JA8LIz0,7731
-rocket_welder_sdk/controllers.py,sha256=acrGGBrFvHO2NUIwaj1wsX7bef0Pn3bgYJlcJJUn3bE,24032
-rocket_welder_sdk/gst_metadata.py,sha256=K0FByW-BiRPPmveTPLKl1G3A_f9Tog0i8wukiaaXnig,7201
-rocket_welder_sdk/py.typed,sha256=0cXFZXmes4Y-vnl4lO3HtyyyWaFNw85B7tJdFeCtHDc,67
-rocket_welder_sdk/rocket_welder_client.py,sha256=1-W1ofdMof9njmLOx4eV8vgxtU2xgk96h8V01Yey9wE,5547
-rocket_welder_sdk-1.1.0.dist-info/METADATA,sha256=3g0N-hAnSmhEddO1fl8ox3KkiRL9V6gyOL90Zqr9JAg,14330
-rocket_welder_sdk-1.1.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-rocket_welder_sdk-1.1.0.dist-info/top_level.txt,sha256=2iZvBjnwVCUW-uDE23-eJld5PZ9-mlPI69QiXM5IrTA,18
-rocket_welder_sdk-1.1.0.dist-info/RECORD,,