rocket-welder-sdk 1.1.27__py3-none-any.whl → 1.1.29__py3-none-any.whl

rocket_welder_sdk/__init__.py

@@ -11,9 +11,11 @@ from .bytes_size import BytesSize
 from .connection_string import ConnectionMode, ConnectionString, Protocol
 from .controllers import DuplexShmController, IController, OneWayShmController
 from .gst_metadata import GstCaps, GstMetadata
+from .opencv_controller import OpenCvController
+from .periodic_timer import PeriodicTimer, PeriodicTimerSync
 from .rocket_welder_client import RocketWelderClient
 
-# Alias for backward compatibility
+# Alias for backward compatibility and README examples
 Client = RocketWelderClient
 
 __version__ = "1.1.0"
@@ -50,6 +52,10 @@ __all__ = [
     # Controllers
     "IController",
     "OneWayShmController",
+    "OpenCvController",
+    # Timers
+    "PeriodicTimer",
+    "PeriodicTimerSync",
     "Protocol",
     # Main client
     "RocketWelderClient",

rocket_welder_sdk/connection_string.py

@@ -21,6 +21,7 @@ class Protocol(Flag):
     MJPEG = auto()  # Motion JPEG
     HTTP = auto()  # HTTP protocol
     TCP = auto()  # TCP protocol
+    FILE = auto()  # File protocol
 
 
 class ConnectionMode(Enum):
@@ -43,12 +44,15 @@ class ConnectionString:
     - shm://buffer_name?size=256MB&metadata=4KB&mode=Duplex
     - mjpeg://192.168.1.100:8080
     - mjpeg+http://camera.local:80
+    - file:///path/to/video.mp4?loop=true
     """
 
     protocol: Protocol
     host: str | None = None
     port: int | None = None
     buffer_name: str | None = None
+    file_path: str | None = None
+    parameters: dict[str, str] = field(default_factory=dict)
     buffer_size: BytesSize = field(default_factory=lambda: BytesSize.parse("256MB"))
     metadata_size: BytesSize = field(default_factory=lambda: BytesSize.parse("4KB"))
     connection_mode: ConnectionMode = ConnectionMode.ONE_WAY
@@ -82,6 +86,8 @@ class ConnectionString:
         # Parse based on protocol type
         if protocol == Protocol.SHM:
             return cls._parse_shm(protocol, remainder)
+        elif protocol == Protocol.FILE:
+            return cls._parse_file(protocol, remainder)
         elif bool(protocol & Protocol.MJPEG):  # type: ignore[operator]
             return cls._parse_mjpeg(protocol, remainder)
         else:
@@ -110,6 +116,7 @@ class ConnectionString:
             "mjpeg": Protocol.MJPEG,
             "http": Protocol.HTTP,
             "tcp": Protocol.TCP,
+            "file": Protocol.FILE,
         }
 
         protocol = protocol_map.get(protocol_str, Protocol.NONE)
@@ -157,6 +164,43 @@ class ConnectionString:
             timeout_ms=timeout_ms,
         )
 
+    @classmethod
+    def _parse_file(cls, protocol: Protocol, remainder: str) -> ConnectionString:
+        """Parse file protocol connection string."""
+        # Split file path and query parameters
+        if "?" in remainder:
+            file_path, query_string = remainder.split("?", 1)
+            params = cls._parse_query_params(query_string)
+        else:
+            file_path = remainder
+            params = {}
+
+        # Handle file:///absolute/path and file://relative/path
+        if not file_path.startswith("/"):
+            file_path = "/" + file_path
+
+        # Parse common parameters
+        connection_mode = ConnectionMode.ONE_WAY
+        timeout_ms = 5000
+
+        if "mode" in params:
+            mode_str = params["mode"].upper()
+            if mode_str == "DUPLEX":
+                connection_mode = ConnectionMode.DUPLEX
+            elif mode_str in ("ONEWAY", "ONE_WAY"):
+                connection_mode = ConnectionMode.ONE_WAY
+        if "timeout" in params:
+            with contextlib.suppress(ValueError):
+                timeout_ms = int(params["timeout"])
+
+        return cls(
+            protocol=protocol,
+            file_path=file_path,
+            parameters=params,
+            connection_mode=connection_mode,
+            timeout_ms=timeout_ms,
+        )
+
     @classmethod
     def _parse_mjpeg(cls, protocol: Protocol, remainder: str) -> ConnectionString:
         """Parse MJPEG connection string."""
@@ -195,6 +239,8 @@ class ConnectionString:
         protocol_parts = []
         if self.protocol & Protocol.SHM:
             protocol_parts.append("shm")
+        if self.protocol & Protocol.FILE:
+            protocol_parts.append("file")
         if self.protocol & Protocol.MJPEG:
             protocol_parts.append("mjpeg")
         if self.protocol & Protocol.HTTP:
@@ -215,6 +261,11 @@ class ConnectionString:
                 params.append(f"timeout={self.timeout_ms}")
 
             return f"{protocol_str}://{self.buffer_name}?{'&'.join(params)}"
+        elif self.protocol == Protocol.FILE:
+            query_string = ""
+            if self.parameters:
+                query_string = "?" + "&".join(f"{k}={v}" for k, v in self.parameters.items())
+            return f"{protocol_str}://{self.file_path}{query_string}"
         else:
             return f"{protocol_str}://{self.host}:{self.port}"
 

rocket_welder_sdk/controllers.py

@@ -9,18 +9,23 @@ import json
 import logging
 import threading
 from abc import ABC, abstractmethod
-from typing import Any, Callable
+from typing import TYPE_CHECKING, Callable, Optional
 
 import numpy as np
 from zerobuffer import BufferConfig, Frame, Reader, Writer
 from zerobuffer.duplex import DuplexChannelFactory, IImmutableDuplexServer
+from zerobuffer.duplex.server import ImmutableDuplexServer
 from zerobuffer.exceptions import WriterDeadException
 
 from .connection_string import ConnectionMode, ConnectionString, Protocol
 from .gst_metadata import GstCaps, GstMetadata
 
-# Type alias for OpenCV Mat
-Mat = np.ndarray[Any, Any]
+if TYPE_CHECKING:
+    import numpy.typing as npt
+
+    Mat = npt.NDArray[np.uint8]
+else:
+    Mat = np.ndarray  # type: ignore[misc]
 
 # Module logger
 logger = logging.getLogger(__name__)
@@ -36,13 +41,15 @@ class IController(ABC):
         ...
 
     @abstractmethod
-    def get_metadata(self) -> GstMetadata | None:
+    def get_metadata(self) -> Optional[GstMetadata]:
         """Get the current GStreamer metadata."""
         ...
 
     @abstractmethod
     def start(
-        self, on_frame: Callable[[Mat], None], cancellation_token: threading.Event | None = None
+        self,
+        on_frame: Callable[[Mat], None],  # type: ignore[valid-type]
+        cancellation_token: Optional[threading.Event] = None,
     ) -> None:
         """
         Start the controller with a frame callback.
@@ -80,24 +87,26 @@ class OneWayShmController(IController):
             )
 
         self._connection = connection
-        self._reader: Reader | None = None
-        self._gst_caps: GstCaps | None = None
-        self._metadata: GstMetadata | None = None
+        self._reader: Optional[Reader] = None
+        self._gst_caps: Optional[GstCaps] = None
+        self._metadata: Optional[GstMetadata] = None
         self._is_running = False
-        self._worker_thread: threading.Thread | None = None
-        self._cancellation_token: threading.Event | None = None
+        self._worker_thread: Optional[threading.Thread] = None
+        self._cancellation_token: Optional[threading.Event] = None
 
     @property
     def is_running(self) -> bool:
         """Check if the controller is running."""
         return self._is_running
 
-    def get_metadata(self) -> GstMetadata | None:
+    def get_metadata(self) -> Optional[GstMetadata]:
         """Get the current GStreamer metadata."""
         return self._metadata
 
     def start(
-        self, on_frame: Callable[[Mat], None], cancellation_token: threading.Event | None = None
+        self,
+        on_frame: Callable[[Mat], None],  # type: ignore[valid-type]
+        cancellation_token: Optional[threading.Event] = None,
     ) -> None:
         """
         Start receiving frames from shared memory.
@@ -161,7 +170,7 @@ class OneWayShmController(IController):
         self._worker_thread = None
         logger.info("Stopped controller for buffer '%s'", self._connection.buffer_name)
 
-    def _process_frames(self, on_frame: Callable[[Mat], None]) -> None:
+    def _process_frames(self, on_frame: Callable[[Mat], None]) -> None:  # type: ignore[valid-type]
         """
         Process frames from shared memory.
 
@@ -236,7 +245,7 @@ class OneWayShmController(IController):
             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:
+    def _on_first_frame(self, on_frame: Callable[[Mat], None]) -> None:  # type: ignore[valid-type]
         """
         Process the first frame and extract metadata.
         Matches C# OnFirstFrame behavior - loops until valid frame received.
@@ -268,36 +277,14 @@ class OneWayShmController(IController):
                                 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):
-                                logger.warning("Metadata is empty or all zeros, skipping")
+                            # Use helper method to parse metadata
+                            metadata = self._parse_metadata_json(metadata_bytes)
+                            if not metadata:
+                                logger.warning("Failed to parse metadata, skipping")
                                 continue
 
-                            # Find the start of JSON (skip any null bytes at the beginning)
-                            json_start = metadata_str.find("{")
-                            if json_start == -1:
-                                logger.warning("No JSON found in metadata: %r", metadata_str[:100])
-                                continue
-
-                            if json_start > 0:
-                                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("}")
-                            if json_end != -1 and json_end < len(metadata_str) - 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._metadata = metadata
+                            self._gst_caps = metadata.caps
                             logger.info(
                                 "Received metadata from buffer '%s': %s",
                                 self._connection.buffer_name,
@@ -342,7 +329,7 @@ class OneWayShmController(IController):
                     if not self._is_running:
                         break
 
-    def _create_mat_from_frame(self, frame: Frame) -> Mat | None:
+    def _create_mat_from_frame(self, frame: Frame) -> Optional[Mat]:  # type: ignore[valid-type]
         """
         Create OpenCV Mat from frame data using GstCaps.
         Matches C# CreateMat behavior - creates Mat wrapping the data.
@@ -406,6 +393,40 @@ class OneWayShmController(IController):
 
             # Try common resolutions
             frame_size = len(frame.data)
+
+            # First, check if it's a perfect square (square frame)
+            import math
+
+            sqrt_size = math.sqrt(frame_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"
+                )
+                data = np.frombuffer(frame.data, dtype=np.uint8)
+                return 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
+                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]
+
+            # Check for square RGBA (size = width * height * 4)
+            if frame_size % 4 == 0:
+                pixels = frame_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]
+
             common_resolutions = [
                 (640, 480, 3),  # VGA RGB
                 (640, 480, 4),  # VGA RGBA
@@ -440,7 +461,46 @@ class OneWayShmController(IController):
             logger.error("Failed to convert frame to Mat: %s", e)
             return None
 
-    def _infer_caps_from_frame(self, mat: Mat) -> None:
+    def _parse_metadata_json(self, metadata_bytes: bytes | memoryview) -> GstMetadata | None:
+        """
+        Parse metadata JSON from bytes, handling null padding and boundaries.
+
+        Args:
+            metadata_bytes: Raw metadata bytes or memoryview
+
+        Returns:
+            GstMetadata object or None if parsing fails
+        """
+        try:
+            # Convert to string
+            if isinstance(metadata_bytes, memoryview):
+                metadata_bytes = bytes(metadata_bytes)
+            metadata_str = metadata_bytes.decode("utf-8")
+
+            # Find JSON boundaries (handle null padding)
+            json_start = metadata_str.find("{")
+            if json_start < 0:
+                logger.debug("No JSON found in metadata")
+                return None
+
+            json_end = metadata_str.rfind("}")
+            if json_end <= json_start:
+                logger.debug("Invalid JSON boundaries in metadata")
+                return None
+
+            # Extract JSON
+            metadata_str = metadata_str[json_start : json_end + 1]
+
+            # Parse JSON
+            metadata_json = json.loads(metadata_str)
+            metadata = GstMetadata.from_json(metadata_json)
+            return metadata
+
+        except Exception as e:
+            logger.debug("Failed to parse metadata JSON: %s", e)
+            return None
+
+    def _infer_caps_from_frame(self, mat: Mat) -> None:  # type: ignore[valid-type]
         """
         Infer GStreamer caps from OpenCV Mat.
 
@@ -487,11 +547,11 @@ class DuplexShmController(IController):
             )
 
         self._connection = connection
-        self._duplex_server: IImmutableDuplexServer | None = None
-        self._gst_caps: GstCaps | None = None
-        self._metadata: GstMetadata | None = None
+        self._duplex_server: Optional[ImmutableDuplexServer] = None
+        self._gst_caps: Optional[GstCaps] = None
+        self._metadata: Optional[GstMetadata] = None
         self._is_running = False
-        self._on_frame_callback: Callable[[Mat, Mat], None] | None = None
+        self._on_frame_callback: Optional[Callable[[Mat, Mat], None]] = None  # type: ignore[valid-type]
         self._frame_count = 0
 
     @property
@@ -499,14 +559,14 @@ class DuplexShmController(IController):
         """Check if the controller is running."""
         return self._is_running
 
-    def get_metadata(self) -> GstMetadata | None:
+    def get_metadata(self) -> Optional[GstMetadata]:
         """Get the current GStreamer metadata."""
         return self._metadata
 
     def start(
         self,
-        on_frame: Callable[[Mat, Mat], None],  # type: ignore[override]
-        cancellation_token: threading.Event | None = None,
+        on_frame: Callable[[Mat, Mat], None],  # type: ignore[override,valid-type]
+        cancellation_token: Optional[threading.Event] = None,
     ) -> None:
         """
         Start duplex frame processing.
@@ -532,6 +592,11 @@ class DuplexShmController(IController):
         if not self._connection.buffer_name:
             raise ValueError("Buffer name is required for shared memory connection")
         timeout_seconds = self._connection.timeout_ms / 1000.0
+        logger.debug(
+            "Creating duplex server with timeout: %d ms (%.1f seconds)",
+            self._connection.timeout_ms,
+            timeout_seconds,
+        )
         factory = DuplexChannelFactory()
         self._duplex_server = factory.create_immutable_server(
             self._connection.buffer_name, config, timeout_seconds
@@ -563,6 +628,44 @@ class DuplexShmController(IController):
 
         logger.info("DuplexShmController stopped")
 
+    def _parse_metadata_json(self, metadata_bytes: bytes | memoryview) -> GstMetadata | None:
+        """
+        Parse metadata JSON from bytes, handling null padding and boundaries.
+
+        Args:
+            metadata_bytes: Raw metadata bytes or memoryview
+
+        Returns:
+            GstMetadata object or None if parsing fails
+        """
+        try:
+            # Convert to string
+            if isinstance(metadata_bytes, memoryview):
+                metadata_bytes = bytes(metadata_bytes)
+            metadata_str = metadata_bytes.decode("utf-8")
+
+            # Find JSON boundaries (handle null padding)
+            json_start = metadata_str.find("{")
+            if json_start < 0:
+                logger.debug("No JSON found in metadata")
+                return None
+
+            json_end = metadata_str.rfind("}")
+            if json_end <= json_start:
+                logger.debug("Invalid JSON boundaries in metadata")
+                return None
+
+            # Extract JSON
+            metadata_str = metadata_str[json_start : json_end + 1]
+
+            # Parse JSON
+            metadata_json = json.loads(metadata_str)
+            metadata = GstMetadata.from_json(metadata_json)
+            return metadata
+        except Exception as e:
+            logger.debug("Failed to parse metadata JSON: %s", e)
+            return None
+
     def _on_metadata(self, metadata_bytes: bytes | memoryview) -> None:
         """
         Handle metadata from duplex channel.
@@ -574,23 +677,20 @@ class DuplexShmController(IController):
             "_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
-            logger.info("Received metadata: %s", self._metadata)
+            # 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("Received metadata: %s", self._metadata)
+            else:
+                logger.warning("Failed to parse metadata from buffer initialization")
         except Exception as e:
             logger.error("Failed to parse metadata: %s", e, exc_info=True)
 
@@ -614,6 +714,30 @@ class DuplexShmController(IController):
 
             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)
+
             # Convert input frame to Mat
             input_mat = self._frame_to_mat(request_frame)
             if input_mat is None:
@@ -662,7 +786,7 @@ class DuplexShmController(IController):
         except Exception as e:
             logger.error("Error processing duplex frame: %s", e)
 
-    def _frame_to_mat(self, frame: Frame) -> Mat | None:
+    def _frame_to_mat(self, frame: Frame) -> Optional[Mat]:  # type: ignore[valid-type]
         """Convert frame to OpenCV Mat (reuse from OneWayShmController)."""
         # Implementation is same as OneWayShmController
         return OneWayShmController._create_mat_from_frame(self, frame)  # type: ignore[arg-type]