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

rocket_welder_sdk/periodic_timer.py

@@ -0,0 +1,303 @@
+"""
+PeriodicTimer implementation for Python, similar to .NET's System.Threading.PeriodicTimer.
+
+Provides an async periodic timer that enables waiting asynchronously for timer ticks.
+This is particularly useful for rendering and periodic frame updates.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import time
+from datetime import timedelta
+from typing import TYPE_CHECKING, Any, List, Optional, Union
+
+if TYPE_CHECKING:
+    from types import TracebackType
+else:
+    TracebackType = type
+
+
+class PeriodicTimer:
+    """
+    A periodic timer that enables waiting asynchronously for timer ticks.
+
+    Similar to .NET's PeriodicTimer, this class provides:
+    - Async-first design with wait_for_next_tick_async()
+    - Single consumer model (only one wait call at a time)
+    - Proper cancellation support
+    - No callback-based design (work is done in the calling scope)
+
+    Example:
+        async def render_loop():
+            timer = PeriodicTimer(timedelta(seconds=1/60))  # 60 FPS
+            try:
+                while await timer.wait_for_next_tick_async():
+                    # Render frame
+                    await render_frame()
+            finally:
+                timer.dispose()
+    """
+
+    def __init__(self, period: Union[timedelta, float]):
+        """
+        Initialize a new PeriodicTimer.
+
+        Args:
+            period: Time interval between ticks. Can be timedelta or float (seconds).
+
+        Raises:
+            ValueError: If period is negative or zero.
+        """
+        if isinstance(period, timedelta):
+            self._period_seconds = period.total_seconds()
+        else:
+            self._period_seconds = float(period)
+
+        if self._period_seconds <= 0:
+            raise ValueError("Period must be positive")
+
+        self._start_time = time.monotonic()
+        self._tick_count = 0
+        self._is_disposed = False
+        self._waiting = False
+        self._dispose_event = asyncio.Event()
+
+    @property
+    def period(self) -> timedelta:
+        """Get the current period as a timedelta."""
+        return timedelta(seconds=self._period_seconds)
+
+    @period.setter
+    def period(self, value: Union[timedelta, float]) -> None:
+        """
+        Set a new period (supported in .NET 8+).
+
+        Args:
+            value: New time interval between ticks.
+        """
+        new_period = value.total_seconds() if isinstance(value, timedelta) else float(value)
+
+        if new_period <= 0:
+            raise ValueError("Period must be positive")
+
+        self._period_seconds = new_period
+
+    async def wait_for_next_tick_async(
+        self, cancellation_token: Optional[asyncio.Event] = None
+    ) -> bool:
+        """
+        Wait asynchronously for the next timer tick.
+
+        Args:
+            cancellation_token: Optional cancellation token to stop waiting.
+
+        Returns:
+            True if the timer ticked successfully, False if canceled or disposed.
+
+        Raises:
+            RuntimeError: If multiple consumers try to wait simultaneously.
+
+        Note:
+            - Only one call to this method may be in flight at any time
+            - If a tick occurred while no one was waiting, the next call
+              will complete immediately
+            - The timer starts when the instance is created, not when first called
+        """
+        if self._is_disposed:
+            return False
+
+        if self._waiting:
+            raise RuntimeError("Only one consumer may wait on PeriodicTimer at a time")
+
+        self._waiting = True
+        try:
+            # Calculate next tick time
+            self._tick_count += 1
+            next_tick_time = self._start_time + (self._tick_count * self._period_seconds)
+
+            # Calculate wait time
+            current_time = time.monotonic()
+            wait_time = max(0, next_tick_time - current_time)
+
+            # If we're behind schedule, complete immediately
+            if wait_time == 0:
+                return not self._is_disposed
+
+            # Create tasks for waiting
+            tasks: List[asyncio.Task[Any]] = [asyncio.create_task(asyncio.sleep(wait_time))]
+
+            # Add dispose event task
+            dispose_task = asyncio.create_task(self._dispose_event.wait())
+            tasks.append(dispose_task)
+
+            # Add cancellation token if provided
+            if cancellation_token:
+                cancel_task = asyncio.create_task(cancellation_token.wait())
+                tasks.append(cancel_task)
+
+            # Wait for first task to complete
+            done, pending = await asyncio.wait(tasks, return_when=asyncio.FIRST_COMPLETED)
+
+            # Cancel pending tasks
+            for task in pending:
+                task.cancel()
+                with contextlib.suppress(asyncio.CancelledError):
+                    await task
+
+            # Check what completed
+            if dispose_task in done or self._is_disposed:
+                return False
+
+            return not (cancellation_token and cancel_task in done)
+
+        finally:
+            self._waiting = False
+
+    def dispose(self) -> None:
+        """
+        Dispose of the timer and release resources.
+
+        This will cause any pending wait_for_next_tick_async() calls to return False.
+        """
+        if not self._is_disposed:
+            self._is_disposed = True
+            self._dispose_event.set()
+
+    def __enter__(self) -> PeriodicTimer:
+        """Context manager entry."""
+        return self
+
+    def __exit__(
+        self,
+        exc_type: Optional[type],
+        exc_val: Optional[BaseException],
+        exc_tb: Optional[TracebackType],
+    ) -> None:
+        """Context manager exit - ensures disposal."""
+        self.dispose()
+
+    def __del__(self) -> None:
+        """Ensure timer is disposed when garbage collected."""
+        self.dispose()
+
+
+class PeriodicTimerSync:
+    """
+    Synchronous version of PeriodicTimer for non-async contexts.
+
+    Provides similar functionality but with blocking wait methods.
+    Useful when async is not available or desired.
+
+    Example:
+        timer = PeriodicTimerSync(1.0/60)  # 60 FPS
+        try:
+            while timer.wait_for_next_tick():
+                render_frame()
+        finally:
+            timer.dispose()
+    """
+
+    def __init__(self, period: Union[timedelta, float]):
+        """
+        Initialize a new synchronous PeriodicTimer.
+
+        Args:
+            period: Time interval between ticks. Can be timedelta or float (seconds).
+        """
+        if isinstance(period, timedelta):
+            self._period_seconds = period.total_seconds()
+        else:
+            self._period_seconds = float(period)
+
+        if self._period_seconds <= 0:
+            raise ValueError("Period must be positive")
+
+        self._start_time = time.monotonic()
+        self._tick_count = 0
+        self._is_disposed = False
+        self._waiting = False
+
+    @property
+    def period(self) -> timedelta:
+        """Get the current period as a timedelta."""
+        return timedelta(seconds=self._period_seconds)
+
+    @period.setter
+    def period(self, value: Union[timedelta, float]) -> None:
+        """Set a new period."""
+        new_period = value.total_seconds() if isinstance(value, timedelta) else float(value)
+
+        if new_period <= 0:
+            raise ValueError("Period must be positive")
+
+        self._period_seconds = new_period
+
+    def wait_for_next_tick(self, timeout: Optional[float] = None) -> bool:
+        """
+        Wait synchronously for the next timer tick.
+
+        Args:
+            timeout: Optional timeout in seconds. None means wait indefinitely.
+
+        Returns:
+            True if the timer ticked successfully, False if timed out or disposed.
+
+        Raises:
+            RuntimeError: If multiple consumers try to wait simultaneously.
+        """
+        if self._is_disposed:
+            return False
+
+        if self._waiting:
+            raise RuntimeError("Only one consumer may wait on PeriodicTimer at a time")
+
+        self._waiting = True
+        try:
+            # Calculate next tick time
+            self._tick_count += 1
+            next_tick_time = self._start_time + (self._tick_count * self._period_seconds)
+
+            # Calculate wait time
+            current_time = time.monotonic()
+            wait_time = max(0, next_tick_time - current_time)
+
+            # Apply timeout if specified
+            if timeout is not None:
+                wait_time = min(wait_time, timeout)
+
+            # If we need to wait, sleep
+            if wait_time > 0:
+                time.sleep(wait_time)
+
+            # Check if we're disposed or timed out
+            if self._is_disposed:
+                return False
+
+            if timeout is not None:
+                actual_time = time.monotonic()
+                if actual_time < next_tick_time:
+                    return False  # Timed out
+
+            return True
+
+        finally:
+            self._waiting = False
+
+    def dispose(self) -> None:
+        """Dispose of the timer."""
+        self._is_disposed = True
+
+    def __enter__(self) -> PeriodicTimerSync:
+        """Context manager entry."""
+        return self
+
+    def __exit__(
+        self,
+        exc_type: Optional[type],
+        exc_val: Optional[BaseException],
+        exc_tb: Optional[TracebackType],
+    ) -> None:
+        """Context manager exit."""
+        self.dispose()

rocket_welder_sdk/rocket_welder_client.py

@@ -6,19 +6,25 @@ Main entry point for the RocketWelder SDK.
 from __future__ import annotations
 
 import logging
+import queue
 import threading
-from typing import TYPE_CHECKING, Any, Callable
+from typing import TYPE_CHECKING, Any, Callable, List, Optional, Union
 
 import numpy as np
 
 from .connection_string import ConnectionMode, ConnectionString, Protocol
 from .controllers import DuplexShmController, IController, OneWayShmController
+from .opencv_controller import OpenCvController
 
 if TYPE_CHECKING:
+    import numpy.typing as npt
+
     from .gst_metadata import GstMetadata
 
-# Type alias for OpenCV Mat
-Mat = np.ndarray[Any, Any]
+    # Use numpy array type for Mat - OpenCV Mat is essentially a numpy array
+    Mat = npt.NDArray[np.uint8]
+else:
+    Mat = np.ndarray  # type: ignore[misc]
 
 # Module logger
 logger = logging.getLogger(__name__)
@@ -31,7 +37,7 @@ class RocketWelderClient:
     Provides a unified interface for different connection types and protocols.
     """
 
-    def __init__(self, connection: str | ConnectionString):
+    def __init__(self, connection: Union[str, ConnectionString]):
         """
         Initialize the RocketWelder client.
 
@@ -43,9 +49,17 @@ class RocketWelderClient:
         else:
             self._connection = connection
 
-        self._controller: IController | None = None
+        self._controller: Optional[IController] = None
         self._lock = threading.Lock()
 
+        # Preview support
+        self._preview_enabled = (
+            self._connection.parameters.get("preview", "false").lower() == "true"
+        )
+        self._preview_queue: queue.Queue[Optional[Mat]] = queue.Queue(maxsize=2)  # type: ignore[valid-type]  # Small buffer
+        self._preview_window_name = "RocketWelder Preview"
+        self._original_callback: Any = None
+
     @property
     def connection(self) -> ConnectionString:
         """Get the connection configuration."""
@@ -57,7 +71,7 @@ class RocketWelderClient:
         with self._lock:
             return self._controller is not None and self._controller.is_running
 
-    def get_metadata(self) -> GstMetadata | None:
+    def get_metadata(self) -> Optional[GstMetadata]:
         """
         Get the current GStreamer metadata.
 
@@ -71,8 +85,8 @@ class RocketWelderClient:
 
     def start(
         self,
-        on_frame: Callable[[Mat], None] | Callable[[Mat, Mat], None],
-        cancellation_token: threading.Event | None = None,
+        on_frame: Union[Callable[[Mat], None], Callable[[Mat, Mat], None]],  # type: ignore[valid-type]
+        cancellation_token: Optional[threading.Event] = None,
     ) -> None:
         """
         Start receiving/processing video frames.
@@ -97,11 +111,55 @@ class RocketWelderClient:
                     self._controller = DuplexShmController(self._connection)
                 else:
                     self._controller = OneWayShmController(self._connection)
+            elif self._connection.protocol in (Protocol.FILE, Protocol.MJPEG):
+                self._controller = OpenCvController(self._connection)
             else:
                 raise ValueError(f"Unsupported protocol: {self._connection.protocol}")
 
+            # If preview is enabled, wrap the callback to capture frames
+            if self._preview_enabled:
+                self._original_callback = on_frame
+
+                # Determine if duplex or one-way
+                if self._connection.connection_mode == ConnectionMode.DUPLEX:
+
+                    def preview_wrapper_duplex(input_frame: Mat, output_frame: Mat) -> None:  # type: ignore[valid-type]
+                        # Call original callback
+                        on_frame(input_frame, output_frame)  # type: ignore[call-arg]
+                        # Queue the OUTPUT frame for preview
+                        try:
+                            self._preview_queue.put_nowait(output_frame.copy())  # type: ignore[attr-defined]
+                        except queue.Full:
+                            # Drop oldest frame if queue is full
+                            try:
+                                self._preview_queue.get_nowait()
+                                self._preview_queue.put_nowait(output_frame.copy())  # type: ignore[attr-defined]
+                            except queue.Empty:
+                                pass
+
+                    actual_callback = preview_wrapper_duplex
+                else:
+
+                    def preview_wrapper_oneway(frame: Mat) -> None:  # type: ignore[valid-type]
+                        # Call original callback
+                        on_frame(frame)  # type: ignore[call-arg]
+                        # Queue frame for preview
+                        try:
+                            self._preview_queue.put_nowait(frame.copy())  # type: ignore[attr-defined]
+                        except queue.Full:
+                            # Drop oldest frame if queue is full
+                            try:
+                                self._preview_queue.get_nowait()
+                                self._preview_queue.put_nowait(frame.copy())  # type: ignore[attr-defined]
+                            except queue.Empty:
+                                pass
+
+                    actual_callback = preview_wrapper_oneway  # type: ignore[assignment]
+            else:
+                actual_callback = on_frame  # type: ignore[assignment]
+
             # Start the controller
-            self._controller.start(on_frame, cancellation_token)  # type: ignore[arg-type]
+            self._controller.start(actual_callback, cancellation_token)  # type: ignore[arg-type]
             logger.info("RocketWelder client started with %s", self._connection)
 
     def stop(self) -> None:
@@ -110,8 +168,83 @@ class RocketWelderClient:
             if self._controller:
                 self._controller.stop()
                 self._controller = None
+
+                # Signal preview to stop if enabled
+                if self._preview_enabled:
+                    self._preview_queue.put(None)  # Sentinel value
+
                 logger.info("RocketWelder client stopped")
 
+    def show(self, cancellation_token: Optional[threading.Event] = None) -> None:
+        """
+        Display preview frames in a window (main thread only).
+
+        This method should be called from the main thread after start().
+        - If preview=true: blocks and displays frames until stopped or 'q' pressed
+        - If preview=false or not set: returns immediately
+
+        Args:
+            cancellation_token: Optional cancellation token to stop preview
+
+        Example:
+            client = RocketWelderClient("file:///video.mp4?preview=true")
+            client.start(process_frame)
+            client.show()  # Blocks and shows preview
+            client.stop()
+        """
+        if not self._preview_enabled:
+            # No preview requested, return immediately
+            return
+
+        try:
+            import cv2
+        except ImportError:
+            logger.warning("OpenCV not available, cannot show preview")
+            return
+
+        logger.info("Starting preview display in main thread")
+
+        # Create window
+        cv2.namedWindow(self._preview_window_name, cv2.WINDOW_NORMAL)
+
+        try:
+            while True:
+                # Check for cancellation
+                if cancellation_token and cancellation_token.is_set():
+                    break
+
+                try:
+                    # Get frame with timeout
+                    frame = self._preview_queue.get(timeout=0.1)
+
+                    # Check for stop sentinel
+                    if frame is None:
+                        break
+
+                    # Display frame
+                    cv2.imshow(self._preview_window_name, frame)
+
+                    # Process window events and check for 'q' key
+                    key = cv2.waitKey(1) & 0xFF
+                    if key == ord("q"):
+                        logger.info("User pressed 'q', stopping preview")
+                        break
+
+                except queue.Empty:
+                    # No frame available, check if still running
+                    if not self.is_running:
+                        break
+                    # Process window events even without new frame
+                    if cv2.waitKey(1) & 0xFF == ord("q"):
+                        logger.info("User pressed 'q', stopping preview")
+                        break
+
+        finally:
+            # Clean up window
+            cv2.destroyWindow(self._preview_window_name)
+            cv2.waitKey(1)  # Process pending events
+            logger.info("Preview display stopped")
+
     def __enter__(self) -> RocketWelderClient:
         """Context manager entry."""
         return self
@@ -120,6 +253,110 @@ class RocketWelderClient:
         """Context manager exit."""
         self.stop()
 
+    @classmethod
+    def from_connection_string(cls, connection_string: str) -> RocketWelderClient:
+        """
+        Create a client from a connection string.
+
+        Args:
+            connection_string: Connection string (e.g., 'shm://buffer?mode=Duplex')
+
+        Returns:
+            Configured RocketWelderClient instance
+        """
+        return cls(connection_string)
+
+    @classmethod
+    def from_args(cls, args: List[str]) -> RocketWelderClient:
+        """
+        Create a client from command line arguments.
+
+        Checks in order:
+        1. First positional argument from args
+        2. CONNECTION_STRING environment variable
+
+        Args:
+            args: Command line arguments (typically sys.argv)
+
+        Returns:
+            Configured RocketWelderClient instance
+
+        Raises:
+            ValueError: If no connection string is found
+        """
+        import os
+
+        # Check for positional argument (skip script name if present)
+        connection_string = None
+        for arg in args[1:] if len(args) > 0 and args[0].endswith(".py") else args:
+            if not arg.startswith("-"):
+                connection_string = arg
+                break
+
+        # Fall back to environment variable
+        if not connection_string:
+            connection_string = os.environ.get("CONNECTION_STRING")
+
+        if not connection_string:
+            raise ValueError(
+                "No connection string provided. "
+                "Provide as argument or set CONNECTION_STRING environment variable"
+            )
+
+        return cls(connection_string)
+
+    @classmethod
+    def from_(cls, *args: Any, **kwargs: Any) -> RocketWelderClient:
+        """
+        Create a client with automatic configuration detection.
+
+        This is the most convenient factory method that:
+        1. Checks kwargs for 'args' parameter (command line arguments)
+        2. Checks args for command line arguments
+        3. Falls back to CONNECTION_STRING environment variable
+
+        Examples:
+            client = RocketWelderClient.from_()  # Uses env var
+            client = RocketWelderClient.from_(sys.argv)  # Uses command line
+            client = RocketWelderClient.from_(args=sys.argv)  # Named param
+
+        Returns:
+            Configured RocketWelderClient instance
+
+        Raises:
+            ValueError: If no connection string is found
+        """
+        import os
+
+        # Check kwargs first
+        argv = kwargs.get("args")
+
+        # Then check positional args
+        if not argv and args:
+            # If first arg looks like sys.argv (list), use it
+            if isinstance(args[0], list):
+                argv = args[0]
+            # If first arg is a string, treat it as connection string
+            elif isinstance(args[0], str):
+                return cls(args[0])
+
+        # Try to get from command line args if provided
+        if argv:
+            try:
+                return cls.from_args(argv)
+            except ValueError:
+                pass  # Fall through to env var check
+
+        # Fall back to environment variable
+        connection_string = os.environ.get("CONNECTION_STRING")
+        if connection_string:
+            return cls(connection_string)
+
+        raise ValueError(
+            "No connection string provided. "
+            "Provide as argument or set CONNECTION_STRING environment variable"
+        )
+
     @classmethod
     def create_oneway_shm(
         cls,