rocket-welder-sdk 1.1.27__py3-none-any.whl → 1.1.28__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,7 +9,7 @@ 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
@@ -19,8 +19,12 @@ 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 +40,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 +86,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 +169,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 +244,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.
@@ -342,7 +350,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.
@@ -440,7 +448,7 @@ 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 _infer_caps_from_frame(self, mat: Mat) -> None:  # type: ignore[valid-type]
         """
         Infer GStreamer caps from OpenCV Mat.
 
@@ -487,11 +495,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[IImmutableDuplexServer] = 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 +507,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.
@@ -662,7 +670,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]

rocket_welder_sdk/opencv_controller.py

@@ -0,0 +1,278 @@
+"""
+OpenCV-based controller for video file playback and network streams.
+Provides support for file:// and mjpeg:// protocols.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import threading
+import time
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, Callable
+
+import cv2
+import numpy as np
+import numpy.typing as npt
+
+from .connection_string import ConnectionMode, ConnectionString, Protocol
+from .controllers import IController
+from .gst_metadata import GstCaps, GstMetadata
+from .periodic_timer import PeriodicTimerSync
+
+if TYPE_CHECKING:
+    Mat = npt.NDArray[np.uint8]
+else:
+    Mat = np.ndarray  # type: ignore[misc]
+
+logger = logging.getLogger(__name__)
+
+
+class OpenCvController(IController):
+    """
+    Controller for video sources using OpenCV VideoCapture.
+
+    Supports:
+    - File playback with optional looping
+    - MJPEG network streams over HTTP/TCP
+    """
+
+    def __init__(self, connection: ConnectionString) -> None:
+        """
+        Initialize the OpenCV controller.
+
+        Args:
+            connection: Connection string configuration
+        """
+        if not (connection.protocol == Protocol.FILE or bool(connection.protocol & Protocol.MJPEG)):  # type: ignore[operator]
+            raise ValueError(
+                f"OpenCvController requires FILE or MJPEG protocol, got {connection.protocol}"
+            )
+
+        self._connection = connection
+        self._capture: cv2.VideoCapture | None = None
+        self._metadata: GstMetadata | None = None
+        self._is_running = False
+        self._worker_thread: threading.Thread | None = None
+        self._cancellation_token: threading.Event | None = None
+
+        # Parse parameters for file protocol
+        self._loop = (
+            connection.protocol == Protocol.FILE
+            and connection.parameters.get("loop", "false").lower() == "true"
+        )
+
+        # Note: Preview is now handled at the client level via show() method
+        # This avoids X11/WSL threading issues with OpenCV GUI functions
+
+    @property
+    def is_running(self) -> bool:
+        """Check if the controller is running."""
+        return self._is_running
+
+    def get_metadata(self) -> GstMetadata | None:
+        """Get the current video metadata."""
+        return self._metadata
+
+    def start(
+        self,
+        on_frame: (
+            Callable[[npt.NDArray[Any]], None]
+            | Callable[[npt.NDArray[Any], npt.NDArray[Any]], None]
+        ),
+        cancellation_token: threading.Event | None = None,
+    ) -> None:
+        """
+        Start processing video frames.
+
+        Args:
+            on_frame: Callback for frame processing
+            cancellation_token: Optional cancellation token
+        """
+        if self._is_running:
+            raise RuntimeError("Controller is already running")
+
+        self._is_running = True
+        self._cancellation_token = cancellation_token
+
+        # Get video source
+        source = self._get_source()
+        logger.info("Opening video source: %s (loop=%s)", source, self._loop)
+
+        # Create VideoCapture
+        self._capture = cv2.VideoCapture(source)
+
+        if not self._capture.isOpened():
+            self._capture.release()
+            self._capture = None
+            self._is_running = False
+            raise RuntimeError(f"Failed to open video source: {source}")
+
+        # Get video properties
+        width = int(self._capture.get(cv2.CAP_PROP_FRAME_WIDTH))
+        height = int(self._capture.get(cv2.CAP_PROP_FRAME_HEIGHT))
+        fps = self._capture.get(cv2.CAP_PROP_FPS)
+        frame_count = int(self._capture.get(cv2.CAP_PROP_FRAME_COUNT))
+
+        # Create metadata
+        caps = GstCaps.from_simple(width, height, "RGB")
+        self._metadata = GstMetadata(
+            type="video",
+            version="1.0",
+            caps=caps,
+            element_name=(
+                "file-capture" if self._connection.protocol == Protocol.FILE else "opencv-capture"
+            ),
+        )
+
+        logger.info(
+            "Video source opened: %dx%d @ %.1ffps, %d frames", width, height, fps, frame_count
+        )
+
+        # Determine callback type and start worker thread
+        if self._connection.connection_mode == ConnectionMode.DUPLEX:
+            # For duplex mode with file/mjpeg, we allocate output but process as one-way
+            def duplex_wrapper(frame: npt.NDArray[Any]) -> None:
+                output = np.empty_like(frame)
+                on_frame(frame, output)  # type: ignore[call-arg]
+
+            self._worker_thread = threading.Thread(
+                target=self._process_frames,
+                args=(duplex_wrapper, fps),
+                name=f"RocketWelder-OpenCV-{Path(source).stem}",
+            )
+        else:
+            self._worker_thread = threading.Thread(
+                target=self._process_frames,
+                args=(on_frame, fps),
+                name=f"RocketWelder-OpenCV-{Path(source).stem}",
+            )
+
+        self._worker_thread.start()
+
+    def stop(self) -> None:
+        """Stop the controller and clean up resources."""
+        if not self._is_running:
+            return
+
+        logger.debug("Stopping OpenCV controller")
+        self._is_running = False
+
+        # Wait for worker thread
+        if self._worker_thread and self._worker_thread.is_alive():
+            timeout_s = (self._connection.timeout_ms + 50) / 1000.0
+            self._worker_thread.join(timeout=timeout_s)
+
+        # Clean up capture
+        if self._capture:
+            self._capture.release()
+            self._capture = None
+
+        self._worker_thread = None
+        logger.info("Stopped OpenCV controller")
+
+    def _get_source(self) -> str:
+        """
+        Get the video source string for OpenCV.
+
+        Returns:
+            Source string for VideoCapture
+
+        Raises:
+            FileNotFoundError: If file doesn't exist
+            ValueError: If file path is missing
+        """
+        if self._connection.protocol == Protocol.FILE:
+            if not self._connection.file_path:
+                raise ValueError("File path is required for file protocol")
+
+            if not os.path.exists(self._connection.file_path):
+                raise FileNotFoundError(f"Video file not found: {self._connection.file_path}")
+
+            return self._connection.file_path
+
+        elif bool(self._connection.protocol & Protocol.MJPEG):  # type: ignore[operator]
+            # Construct URL from host:port (no path support yet)
+            if bool(self._connection.protocol & Protocol.HTTP):  # type: ignore[operator]
+                return f"http://{self._connection.host}:{self._connection.port}"
+            elif bool(self._connection.protocol & Protocol.TCP):  # type: ignore[operator]
+                return f"tcp://{self._connection.host}:{self._connection.port}"
+            else:
+                return f"http://{self._connection.host}:{self._connection.port}"
+
+        else:
+            raise ValueError(f"Unsupported protocol: {self._connection.protocol}")
+
+    def _process_frames(self, on_frame: Callable[[npt.NDArray[Any]], None], fps: float) -> None:
+        """
+        Process video frames in a loop.
+
+        Args:
+            on_frame: Callback for each frame
+            fps: Frames per second for timing
+        """
+        if not self._capture:
+            return
+
+        # Use PeriodicTimer for precise frame timing (especially important for file playback)
+        timer = None
+        if self._connection.protocol == Protocol.FILE and fps > 0:
+            # Create timer for file playback at specified FPS
+            timer = PeriodicTimerSync(1.0 / fps)
+            logger.debug("Using PeriodicTimer for file playback at %.1f FPS", fps)
+
+        try:
+            while self._is_running:
+                if self._cancellation_token and self._cancellation_token.is_set():
+                    break
+
+                try:
+                    # Read frame
+                    ret, frame = self._capture.read()
+
+                    if not ret:
+                        if self._connection.protocol == Protocol.FILE and self._loop:
+                            # Loop: Reset to beginning
+                            self._capture.set(cv2.CAP_PROP_POS_FRAMES, 0)
+                            logger.debug("Looping video from beginning")
+                            continue
+                        elif self._connection.protocol == Protocol.FILE:
+                            # File ended without loop
+                            logger.info("Video file ended")
+                            break
+                        else:
+                            # Network stream issue
+                            logger.warning("Failed to read frame from stream")
+                            time.sleep(0.01)
+                            continue
+
+                    if hasattr(frame, "size") and frame.size == 0:
+                        time.sleep(0.01)
+                        continue
+
+                    # Process frame
+                    on_frame(frame)
+
+                    # Control frame rate for file playback using PeriodicTimer
+                    if timer:
+                        # Wait for next tick - this provides precise timing
+                        if not timer.wait_for_next_tick():
+                            # Timer disposed or timed out
+                            break
+                    elif self._connection.protocol != Protocol.FILE:
+                        # For network streams, we process as fast as they arrive
+                        # No artificial delay needed
+                        pass
+
+                except Exception as e:
+                    logger.error("Error processing frame: %s", e)
+                    if not self._is_running:
+                        break
+                    time.sleep(0.1)
+
+        finally:
+            if timer:
+                timer.dispose()
+
+        self._is_running = False