rocket-welder-sdk 1.1.27__tar.gz → 1.1.28__tar.gz

{rocket_welder_sdk-1.1.27 → rocket_welder_sdk-1.1.28}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: rocket-welder-sdk
-Version: 1.1.27
+Version: 1.1.28
 Summary: High-performance video streaming SDK for RocketWelder services using ZeroBuffer IPC
 Home-page: https://github.com/modelingevolution/rocket-welder-sdk
 Author: ModelingEvolution
@@ -17,6 +17,7 @@ Classifier: Topic :: Multimedia :: Video
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
 Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
@@ -93,6 +94,18 @@ shm://<buffer_name>?mode=duplex&buffer_size=10MB
 - `buffer_size`: Size of the data buffer (default: 20MB, supports units: B, KB, MB, GB)
 - `metadata_size`: Size of the metadata buffer (default: 4KB, supports units: B, KB, MB)
 
+#### File (Video File Playback)
+```
+file:///path/to/video.mp4
+file:///path/to/video.mp4?loop=true
+file:///path/to/video.mp4?preview=true
+file:///path/to/video.mp4?loop=true&preview=true
+```
+
+**Optional Parameters:**
+- `loop`: Loop video playback when end is reached (`true` or `false`; default: `false`)
+- `preview`: Enable preview window display (`true` or `false`; default: `false`)
+
 #### MJPEG over HTTP
 ```
 mjpeg+http://192.168.1.100:8080
@@ -318,6 +331,44 @@ for frame in client.frames():
     print(f"Received frame: {frame.shape}")
 ```
 
+## Preview Display
+
+When using the `file://` protocol with `preview=true` parameter, you can display frames in a window. The `Show()` method must be called from the main thread:
+
+### C# Preview
+```csharp
+var client = RocketWelderClient.FromConnectionString(
+    "file:///path/to/video.mp4?preview=true&loop=true"
+);
+
+// Start processing in background
+client.Start(frame => {
+    // Process frame
+});
+
+// Show preview window in main thread (blocks until 'q' pressed)
+client.Show();
+```
+
+### Python Preview
+```python
+client = rw.Client.from_connection_string(
+    "file:///path/to/video.mp4?preview=true&loop=true"
+)
+
+# Start processing in background
+client.start(lambda frame: process_frame(frame))
+
+# Show preview window in main thread (blocks until 'q' pressed)
+client.show()
+```
+
+**Note**: The `Show()` method:
+- Blocks when `preview=true` is set in the connection string
+- Returns immediately when `preview` is not set or `false`
+- Must be called from the main thread (X11/GUI requirement)
+- Stops when 'q' key is pressed in the preview window
+
 ## Docker Integration
 
 ### C++ Dockerfile
@@ -385,6 +436,75 @@ COPY . .
 CMD ["python", "app.py"]
 ```
 
+### Running Docker with X11 Display Support (Preview)
+
+When using the `preview=true` parameter with file protocol, you need to enable X11 forwarding for Docker containers to display the preview window.
+
+#### Linux
+
+```bash
+# Allow X server connections from Docker
+xhost +local:docker
+
+# Run container with display support
+docker run --rm \
+    -e DISPLAY=$DISPLAY \
+    -e CONNECTION_STRING="file:///data/video.mp4?preview=true&loop=true" \
+    -v /tmp/.X11-unix:/tmp/.X11-unix:rw \
+    -v /path/to/video.mp4:/data/video.mp4:ro \
+    --network host \
+    your-image:latest
+
+# Restore X server security after running
+xhost -local:docker
+```
+
+#### Windows WSL2
+
+WSL2 includes WSLg which provides automatic X11 support:
+
+```bash
+# WSLg sets DISPLAY automatically, just verify it's set
+echo $DISPLAY  # Should show :0 or similar
+
+# Allow X server connections
+xhost +local:docker 2>/dev/null || xhost +local: 2>/dev/null
+
+# Run container with display support (same as Linux)
+docker run --rm \
+    -e DISPLAY=$DISPLAY \
+    -e CONNECTION_STRING="file:///data/video.mp4?preview=true&loop=true" \
+    -v /tmp/.X11-unix:/tmp/.X11-unix:rw \
+    -v /mnt/c/path/to/video.mp4:/data/video.mp4:ro \
+    --network host \
+    your-image:latest
+
+# Restore X server security
+xhost -local:docker 2>/dev/null || xhost -local: 2>/dev/null
+```
+
+#### Helper Scripts
+
+The SDK includes helper scripts for easy testing:
+
+```bash
+# Build Docker images with sample clients
+./build_docker_samples.sh
+
+# Test Python client with preview
+./run_docker_x11.sh python
+
+# Test C# client with preview
+./run_docker_x11.sh csharp
+```
+
+These scripts automatically:
+- Configure X11 display forwarding
+- Use a test video from the repository's data folder
+- Mount the video into the container
+- Set up the connection string with preview enabled
+- Clean up X server permissions after running
+
 ## Protocol Details
 
 ### Shared Memory Protocol (shm://)
@@ -394,6 +514,15 @@ High-performance local data transfer between processes:
 - **Performance**: Minimal latency, maximum throughput
 - **Use Cases**: Local processing, multi-container applications on same host
 
+### File Protocol (file://)
+
+Local video file playback with OpenCV:
+
+- **Performance**: Controlled playback speed based on video FPS
+- **Features**: Loop playback, preview window, frame-accurate timing
+- **Use Cases**: Testing, development, offline processing, demos
+- **Supported Formats**: All formats supported by OpenCV (MP4, AVI, MOV, etc.)
+
 ### MJPEG over HTTP (mjpeg+http://)
 
 Motion JPEG streaming over HTTP:

{rocket_welder_sdk-1.1.27 → rocket_welder_sdk-1.1.28}/README.md

@@ -49,6 +49,18 @@ shm://<buffer_name>?mode=duplex&buffer_size=10MB
 - `buffer_size`: Size of the data buffer (default: 20MB, supports units: B, KB, MB, GB)
 - `metadata_size`: Size of the metadata buffer (default: 4KB, supports units: B, KB, MB)
 
+#### File (Video File Playback)
+```
+file:///path/to/video.mp4
+file:///path/to/video.mp4?loop=true
+file:///path/to/video.mp4?preview=true
+file:///path/to/video.mp4?loop=true&preview=true
+```
+
+**Optional Parameters:**
+- `loop`: Loop video playback when end is reached (`true` or `false`; default: `false`)
+- `preview`: Enable preview window display (`true` or `false`; default: `false`)
+
 #### MJPEG over HTTP
 ```
 mjpeg+http://192.168.1.100:8080
@@ -274,6 +286,44 @@ for frame in client.frames():
     print(f"Received frame: {frame.shape}")
 ```
 
+## Preview Display
+
+When using the `file://` protocol with `preview=true` parameter, you can display frames in a window. The `Show()` method must be called from the main thread:
+
+### C# Preview
+```csharp
+var client = RocketWelderClient.FromConnectionString(
+    "file:///path/to/video.mp4?preview=true&loop=true"
+);
+
+// Start processing in background
+client.Start(frame => {
+    // Process frame
+});
+
+// Show preview window in main thread (blocks until 'q' pressed)
+client.Show();
+```
+
+### Python Preview
+```python
+client = rw.Client.from_connection_string(
+    "file:///path/to/video.mp4?preview=true&loop=true"
+)
+
+# Start processing in background
+client.start(lambda frame: process_frame(frame))
+
+# Show preview window in main thread (blocks until 'q' pressed)
+client.show()
+```
+
+**Note**: The `Show()` method:
+- Blocks when `preview=true` is set in the connection string
+- Returns immediately when `preview` is not set or `false`
+- Must be called from the main thread (X11/GUI requirement)
+- Stops when 'q' key is pressed in the preview window
+
 ## Docker Integration
 
 ### C++ Dockerfile
@@ -341,6 +391,75 @@ COPY . .
 CMD ["python", "app.py"]
 ```
 
+### Running Docker with X11 Display Support (Preview)
+
+When using the `preview=true` parameter with file protocol, you need to enable X11 forwarding for Docker containers to display the preview window.
+
+#### Linux
+
+```bash
+# Allow X server connections from Docker
+xhost +local:docker
+
+# Run container with display support
+docker run --rm \
+    -e DISPLAY=$DISPLAY \
+    -e CONNECTION_STRING="file:///data/video.mp4?preview=true&loop=true" \
+    -v /tmp/.X11-unix:/tmp/.X11-unix:rw \
+    -v /path/to/video.mp4:/data/video.mp4:ro \
+    --network host \
+    your-image:latest
+
+# Restore X server security after running
+xhost -local:docker
+```
+
+#### Windows WSL2
+
+WSL2 includes WSLg which provides automatic X11 support:
+
+```bash
+# WSLg sets DISPLAY automatically, just verify it's set
+echo $DISPLAY  # Should show :0 or similar
+
+# Allow X server connections
+xhost +local:docker 2>/dev/null || xhost +local: 2>/dev/null
+
+# Run container with display support (same as Linux)
+docker run --rm \
+    -e DISPLAY=$DISPLAY \
+    -e CONNECTION_STRING="file:///data/video.mp4?preview=true&loop=true" \
+    -v /tmp/.X11-unix:/tmp/.X11-unix:rw \
+    -v /mnt/c/path/to/video.mp4:/data/video.mp4:ro \
+    --network host \
+    your-image:latest
+
+# Restore X server security
+xhost -local:docker 2>/dev/null || xhost -local: 2>/dev/null
+```
+
+#### Helper Scripts
+
+The SDK includes helper scripts for easy testing:
+
+```bash
+# Build Docker images with sample clients
+./build_docker_samples.sh
+
+# Test Python client with preview
+./run_docker_x11.sh python
+
+# Test C# client with preview
+./run_docker_x11.sh csharp
+```
+
+These scripts automatically:
+- Configure X11 display forwarding
+- Use a test video from the repository's data folder
+- Mount the video into the container
+- Set up the connection string with preview enabled
+- Clean up X server permissions after running
+
 ## Protocol Details
 
 ### Shared Memory Protocol (shm://)
@@ -350,6 +469,15 @@ High-performance local data transfer between processes:
 - **Performance**: Minimal latency, maximum throughput
 - **Use Cases**: Local processing, multi-container applications on same host
 
+### File Protocol (file://)
+
+Local video file playback with OpenCV:
+
+- **Performance**: Controlled playback speed based on video FPS
+- **Features**: Loop playback, preview window, frame-accurate timing
+- **Use Cases**: Testing, development, offline processing, demos
+- **Supported Formats**: All formats supported by OpenCV (MP4, AVI, MOV, etc.)
+
 ### MJPEG over HTTP (mjpeg+http://)
 
 Motion JPEG streaming over HTTP:

rocket_welder_sdk-1.1.28/VERSION

@@ -0,0 +1 @@
+1.1.28

{rocket_welder_sdk-1.1.27 → rocket_welder_sdk-1.1.28}/pyproject.toml

@@ -7,7 +7,7 @@ name = "rocket-welder-sdk"
 dynamic = ["version"]
 description = "High-performance video streaming SDK for RocketWelder services using ZeroBuffer IPC"
 readme = "README.md"
-requires-python = ">=3.9"
+requires-python = ">=3.8.10"
 license = {text = "MIT"}
 authors = [
     {name = "ModelingEvolution", email = "info@modelingevolution.com"}
@@ -23,6 +23,7 @@ classifiers = [
     "Topic :: Software Development :: Libraries :: Python Modules",
     "License :: OSI Approved :: MIT License",
     "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.8",
     "Programming Language :: Python :: 3.9",
     "Programming Language :: Python :: 3.10",
     "Programming Language :: Python :: 3.11",
@@ -66,7 +67,7 @@ include = ["rocket_welder_sdk*"]
 rocket_welder_sdk = ["py.typed"]
 
 [tool.mypy]
-python_version = "3.9"
+python_version = "3.9"  # mypy 1.0+ requires 3.9, but code supports 3.8
 strict = true
 warn_return_any = true
 warn_unused_configs = true
@@ -80,6 +81,7 @@ pretty = true
 module = [
     "cv2",
     "cv2.*",
+    "cv2.typing",
     "zerobuffer",
     "zerobuffer.*",
     "py_micro_plumberd",
@@ -91,12 +93,12 @@ ignore_missing_imports = true
 
 [tool.black]
 line-length = 100
-target-version = ['py39', 'py310', 'py311', 'py312']
+target-version = ['py38', 'py39', 'py310', 'py311', 'py312']
 include = '\.pyi?$'
 
 [tool.ruff]
 line-length = 100
-target-version = "py39"
+target-version = "py38"
 
 [tool.ruff.lint]
 select = [
@@ -116,6 +118,9 @@ select = [
 ignore = [
     "E501",  # line too long (handled by black)
     "B008",  # do not perform function calls in argument defaults
+    "UP006", # Keep List[X] for Python 3.8 compatibility
+    "UP007", # Keep Union[X, Y] for Python 3.8 compatibility
+    "UP045", # Keep Optional[X] for Python 3.8 compatibility
     "C901",  # too complex
 ]
 

{rocket_welder_sdk-1.1.27 → rocket_welder_sdk-1.1.28}/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-1.1.27 → rocket_welder_sdk-1.1.28}/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-1.1.27 → rocket_welder_sdk-1.1.28}/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]