rocket-welder-sdk 1.1.32__tar.gz → 1.1.33__tar.gz

{rocket_welder_sdk-1.1.32 → rocket_welder_sdk-1.1.33}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: rocket-welder-sdk
-Version: 1.1.32
+Version: 1.1.33
 Summary: High-performance video streaming SDK for RocketWelder services using ZeroBuffer IPC
 Home-page: https://github.com/modelingevolution/rocket-welder-sdk
 Author: ModelingEvolution
@@ -31,6 +31,9 @@ Requires-Dist: opencv-python>=4.5.0
 Requires-Dist: zerobuffer-ipc>=1.1.17
 Requires-Dist: pydantic>=2.5.0
 Requires-Dist: py-micro-plumberd>=0.1.8
+Requires-Dist: typing-extensions>=4.0.0
+Provides-Extra: nng
+Requires-Dist: pynng>=0.7.2; extra == "nng"
 Provides-Extra: dev
 Requires-Dist: pytest>=7.0; extra == "dev"
 Requires-Dist: pytest-cov>=4.0; extra == "dev"
@@ -39,6 +42,7 @@ Requires-Dist: black>=22.0; extra == "dev"
 Requires-Dist: mypy>=1.0; extra == "dev"
 Requires-Dist: ruff>=0.1.0; extra == "dev"
 Requires-Dist: types-setuptools; extra == "dev"
+Requires-Dist: pynng>=0.7.2; extra == "dev"
 Dynamic: author
 Dynamic: home-page
 Dynamic: requires-python
@@ -169,7 +173,7 @@ Start by testing your container locally before deploying to Neuron:
 
 ```bash
 # Build your container
-docker build -t my-ai-app:v1 -f examples/python/Dockerfile .
+docker build -t my-ai-app:v1 -f python/examples/Dockerfile .
 
 # Test with a video file
 docker run --rm \
@@ -223,6 +227,15 @@ docker run --rm \
     my-ai-app:v1
 ```
 
+You can also see preview in your terminal. 
+```bash
+docker run --rm \
+    -e CONNECTION_STRING="mjpeg+tcp://<neuron-ip>:<tcp-server-sink-port>?preview=true" \
+    -e DISPLAY=$DISPLAY \
+    -v /tmp/.X11-unix:/tmp/.X11-unix \
+    --network host my-ai-app:v1
+```
+
 This allows you to:
 - Test your AI processing with real camera feeds
 - Debug frame processing logic

{rocket_welder_sdk-1.1.32 → rocket_welder_sdk-1.1.33}/README.md

@@ -124,7 +124,7 @@ Start by testing your container locally before deploying to Neuron:
 
 ```bash
 # Build your container
-docker build -t my-ai-app:v1 -f examples/python/Dockerfile .
+docker build -t my-ai-app:v1 -f python/examples/Dockerfile .
 
 # Test with a video file
 docker run --rm \
@@ -178,6 +178,15 @@ docker run --rm \
     my-ai-app:v1
 ```
 
+You can also see preview in your terminal. 
+```bash
+docker run --rm \
+    -e CONNECTION_STRING="mjpeg+tcp://<neuron-ip>:<tcp-server-sink-port>?preview=true" \
+    -e DISPLAY=$DISPLAY \
+    -v /tmp/.X11-unix:/tmp/.X11-unix \
+    --network host my-ai-app:v1
+```
+
 This allows you to:
 - Test your AI processing with real camera feeds
 - Debug frame processing logic

rocket_welder_sdk-1.1.33/VERSION

@@ -0,0 +1 @@
+1.1.33

{rocket_welder_sdk-1.1.32 → rocket_welder_sdk-1.1.33}/pyproject.toml

@@ -38,9 +38,13 @@ dependencies = [
     "zerobuffer-ipc>=1.1.17",
     "pydantic>=2.5.0",
     "py-micro-plumberd>=0.1.8",
+    "typing-extensions>=4.0.0",
 ]
 
 [project.optional-dependencies]
+nng = [
+    "pynng>=0.7.2",
+]
 dev = [
     "pytest>=7.0",
     "pytest-cov>=4.0",
@@ -49,6 +53,7 @@ dev = [
     "mypy>=1.0",
     "ruff>=0.1.0",
     "types-setuptools",
+    "pynng>=0.7.2",
 ]
 
 [project.urls]
@@ -76,6 +81,10 @@ namespace_packages = true
 show_error_codes = true
 show_column_numbers = true
 pretty = true
+exclude = [
+    "examples/05-traktorek",
+    "examples/rocket-welder-client-python-yolo",
+]
 
 [[tool.mypy.overrides]]
 module = [
@@ -88,6 +97,8 @@ module = [
     "py_micro_plumberd.*",
     "esdbclient",
     "esdbclient.*",
+    "pynng",
+    "pynng.*",
 ]
 ignore_missing_imports = true
 
@@ -95,10 +106,20 @@ ignore_missing_imports = true
 line-length = 100
 target-version = ['py38', 'py39', 'py310', 'py311', 'py312']
 include = '\.pyi?$'
+exclude = '''
+/(
+    examples/05-traktorek
+  | examples/rocket-welder-client-python-yolo
+)/
+'''
 
 [tool.ruff]
 line-length = 100
 target-version = "py38"
+exclude = [
+    "examples/05-traktorek",
+    "examples/rocket-welder-client-python-yolo",
+]
 
 [tool.ruff.lint]
 select = [

{rocket_welder_sdk-1.1.32 → rocket_welder_sdk-1.1.33}/rocket_welder_sdk/__init__.py

@@ -10,6 +10,7 @@ import os
 from .bytes_size import BytesSize
 from .connection_string import ConnectionMode, ConnectionString, Protocol
 from .controllers import DuplexShmController, IController, OneWayShmController
+from .frame_metadata import FRAME_METADATA_SIZE, FrameMetadata, GstVideoFormat
 from .gst_metadata import GstCaps, GstMetadata
 from .opencv_controller import OpenCvController
 from .periodic_timer import PeriodicTimer, PeriodicTimerSync
@@ -40,23 +41,21 @@ if _log_level:
         pass  # Invalid log level, ignore
 
 __all__ = [
-    # Core types
+    "FRAME_METADATA_SIZE",
     "BytesSize",
-    "Client",  # Backward compatibility
+    "Client",
     "ConnectionMode",
     "ConnectionString",
     "DuplexShmController",
-    # GStreamer metadata
+    "FrameMetadata",
     "GstCaps",
     "GstMetadata",
-    # Controllers
+    "GstVideoFormat",
     "IController",
     "OneWayShmController",
     "OpenCvController",
-    # Timers
     "PeriodicTimer",
     "PeriodicTimerSync",
     "Protocol",
-    # Main client
     "RocketWelderClient",
 ]

{rocket_welder_sdk-1.1.32 → rocket_welder_sdk-1.1.33}/rocket_welder_sdk/controllers.py

@@ -17,6 +17,7 @@ from zerobuffer.duplex import DuplexChannelFactory
 from zerobuffer.exceptions import WriterDeadException
 
 from .connection_string import ConnectionMode, ConnectionString, Protocol
+from .frame_metadata import FRAME_METADATA_SIZE, FrameMetadata
 from .gst_metadata import GstCaps, GstMetadata
 
 if TYPE_CHECKING:
@@ -336,6 +337,9 @@ class OneWayShmController(IController):
         Create OpenCV Mat from frame data using GstCaps.
         Matches C# CreateMat behavior - creates Mat wrapping the data.
 
+        Frame data layout from GStreamer zerosink:
+        [FrameMetadata (16 bytes)][Pixel Data (W×H×C bytes)]
+
         Args:
             frame: ZeroBuffer frame
 
@@ -359,31 +363,40 @@ class OneWayShmController(IController):
                 else:
                     channels = 3  # Default to RGB
 
-                # Get frame data directly as numpy array (zero-copy view)
-                # Frame.data is already a memoryview/buffer that can be wrapped
-                data = np.frombuffer(frame.data, dtype=np.uint8)
+                # Frame data has 16-byte FrameMetadata prefix that must be stripped
+                # Layout: [FrameMetadata (16 bytes)][Pixel Data]
+                if frame.size < FRAME_METADATA_SIZE:
+                    logger.error(
+                        "Frame too small for FrameMetadata: %d bytes (need at least %d)",
+                        frame.size,
+                        FRAME_METADATA_SIZE,
+                    )
+                    return None
+
+                # Get pixel data (skip 16-byte FrameMetadata prefix)
+                pixel_data = np.frombuffer(frame.data[FRAME_METADATA_SIZE:], dtype=np.uint8)
 
-                # Check data size matches expected
+                # Check pixel data size matches expected
                 expected_size = height * width * channels
-                if len(data) != expected_size:
+                if len(pixel_data) != expected_size:
                     logger.error(
-                        "Data size mismatch. Expected %d bytes for %dx%d with %d channels, got %d",
+                        "Pixel data size mismatch. Expected %d bytes for %dx%d with %d channels, got %d",
                         expected_size,
                         width,
                         height,
                         channels,
-                        len(data),
+                        len(pixel_data),
                     )
                     return None
 
                 # Reshape to image dimensions - this is zero-copy, just changes the view
                 # This matches C#: new Mat(Height, Width, Depth, Channels, ptr, Width * Channels)
                 if channels == 3:
-                    mat = data.reshape((height, width, 3))
+                    mat = pixel_data.reshape((height, width, 3))
                 elif channels == 1:
-                    mat = data.reshape((height, width))
+                    mat = pixel_data.reshape((height, width))
                 elif channels == 4:
-                    mat = data.reshape((height, width, 4))
+                    mat = pixel_data.reshape((height, width, 4))
                 else:
                     logger.error("Unsupported channel count: %d", channels)
                     return None
@@ -393,41 +406,51 @@ class OneWayShmController(IController):
             # 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)
+            # Frame data has 16-byte FrameMetadata prefix
+            if frame.size < FRAME_METADATA_SIZE:
+                logger.error(
+                    "Frame too small for FrameMetadata: %d bytes (need at least %d)",
+                    frame.size,
+                    FRAME_METADATA_SIZE,
+                )
+                return None
+
+            # Calculate pixel data size (frame size minus 16-byte metadata prefix)
+            pixel_data_size = frame.size - FRAME_METADATA_SIZE
 
             # First, check if it's a perfect square (square frame)
             import math
 
-            sqrt_size = math.sqrt(frame_size)
+            sqrt_size = math.sqrt(pixel_data_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"
+                    f"Pixel data size {pixel_data_size} is a perfect square, "
+                    f"assuming {dimension}x{dimension} grayscale"
                 )
-                data = np.frombuffer(frame.data, dtype=np.uint8)
-                return data.reshape((dimension, dimension))  # type: ignore[no-any-return]
+                pixel_data = np.frombuffer(frame.data[FRAME_METADATA_SIZE:], dtype=np.uint8)
+                return pixel_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
+            if pixel_data_size % 3 == 0:
+                pixels = pixel_data_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]
+                    logger.info(f"Pixel data size {pixel_data_size} suggests {dimension}x{dimension} RGB")
+                    pixel_data = np.frombuffer(frame.data[FRAME_METADATA_SIZE:], dtype=np.uint8)
+                    return pixel_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
+            if pixel_data_size % 4 == 0:
+                pixels = pixel_data_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]
+                    logger.info(f"Pixel data size {pixel_data_size} suggests {dimension}x{dimension} RGBA")
+                    pixel_data = np.frombuffer(frame.data[FRAME_METADATA_SIZE:], dtype=np.uint8)
+                    return pixel_data.reshape((dimension, dimension, 4))  # type: ignore[no-any-return]
 
             common_resolutions = [
                 (640, 480, 3),  # VGA RGB
@@ -438,7 +461,7 @@ class OneWayShmController(IController):
             ]
 
             for width, height, channels in common_resolutions:
-                if frame_size == width * height * channels:
+                if pixel_data_size == width * height * channels:
                     logger.info(f"Inferred resolution: {width}x{height} with {channels} channels")
 
                     # Create caps for future use
@@ -447,16 +470,16 @@ class OneWayShmController(IController):
                         width=width, height=height, format=format_str
                     )
 
-                    # Create Mat
-                    data = np.frombuffer(frame.data, dtype=np.uint8)
+                    # Create Mat from pixel data (skip 16-byte FrameMetadata prefix)
+                    pixel_data = np.frombuffer(frame.data[FRAME_METADATA_SIZE:], dtype=np.uint8)
                     if channels == 3:
-                        return data.reshape((height, width, 3))  # type: ignore[no-any-return]
+                        return pixel_data.reshape((height, width, 3))  # type: ignore[no-any-return]
                     elif channels == 1:
-                        return data.reshape((height, width))  # type: ignore[no-any-return]
+                        return pixel_data.reshape((height, width))  # type: ignore[no-any-return]
                     elif channels == 4:
-                        return data.reshape((height, width, 4))  # type: ignore[no-any-return]
+                        return pixel_data.reshape((height, width, 4))  # type: ignore[no-any-return]
 
-            logger.error(f"Could not infer resolution for frame size {frame_size}")
+            logger.error(f"Could not infer resolution for pixel data size {pixel_data_size}")
             return None
 
         except Exception as e:
@@ -553,7 +576,7 @@ class DuplexShmController(IController):
         self._gst_caps: Optional[GstCaps] = None
         self._metadata: Optional[GstMetadata] = None
         self._is_running = False
-        self._on_frame_callback: Optional[Callable[[Mat, Mat], None]] = None  # type: ignore[valid-type]
+        self._on_frame_callback: Optional[Callable[[FrameMetadata, Mat, Mat], None]] = None  # type: ignore[valid-type]
         self._frame_count = 0
 
     @property
@@ -567,14 +590,18 @@ class DuplexShmController(IController):
 
     def start(
         self,
-        on_frame: Callable[[Mat, Mat], None],  # type: ignore[override,valid-type]
+        on_frame: Callable[[FrameMetadata, Mat, Mat], None],  # type: ignore[override,valid-type]
         cancellation_token: Optional[threading.Event] = None,
     ) -> None:
         """
-        Start duplex frame processing.
+        Start duplex frame processing with FrameMetadata.
+
+        The callback receives FrameMetadata (frame number, timestamp, dimensions),
+        input Mat, and output Mat. The 24-byte metadata prefix is stripped from
+        the frame data before creating the input Mat.
 
         Args:
-            on_frame: Callback that receives input frame and output frame to fill
+            on_frame: Callback that receives (FrameMetadata, input_mat, output_mat)
             cancellation_token: Optional cancellation token
         """
         if self._is_running:
@@ -590,7 +617,6 @@ class DuplexShmController(IController):
         )
 
         # Create duplex server using factory
-        # Convert timeout from milliseconds to seconds for Python API
         if not self._connection.buffer_name:
             raise ValueError("Buffer name is required for shared memory connection")
         timeout_seconds = self._connection.timeout_ms / 1000.0
@@ -698,91 +724,98 @@ class DuplexShmController(IController):
 
     def _process_duplex_frame(self, request_frame: Frame, response_writer: Writer) -> None:
         """
-        Process a frame in duplex mode.
+        Process a frame in duplex mode with FrameMetadata.
+
+        The frame data has a 24-byte FrameMetadata prefix that is stripped
+        before creating the input Mat.
 
         Args:
-            request_frame: Input frame from the request
+            request_frame: Input frame from the request (with metadata prefix)
             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
 
+            # Check frame size is sufficient for metadata
+            if request_frame.size < FRAME_METADATA_SIZE:
+                logger.warning("Frame too small for FrameMetadata: %d bytes", request_frame.size)
+                return
+
             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)
+            # Parse FrameMetadata from the beginning of the frame
+            frame_metadata = FrameMetadata.from_bytes(request_frame.data)
 
-            # 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)
+            # Calculate pixel data offset and size
+            pixel_data_offset = FRAME_METADATA_SIZE
+            pixel_data_size = request_frame.size - FRAME_METADATA_SIZE
+
+            # GstCaps must be available for width/height/format
+            # (FrameMetadata no longer contains these - they're stream-level, not per-frame)
+            if not self._gst_caps:
+                logger.warning(
+                    "GstCaps not available, skipping frame %d", frame_metadata.frame_number
+                )
                 return
 
-            # Get buffer for output frame - use context manager for RAII
-            with response_writer.get_frame_buffer(request_frame.size) as output_buffer:
-                # Create output Mat from buffer (zero-copy)
-                if self._gst_caps:
-                    height = self._gst_caps.height or 480
-                    width = self._gst_caps.width or 640
+            width = self._gst_caps.width
+            height = self._gst_caps.height
+            format_str = self._gst_caps.format
+
+            # Determine channels from format
+            if format_str in ["RGB", "BGR"]:
+                channels = 3
+            elif format_str in ["RGBA", "BGRA", "ARGB", "ABGR"]:
+                channels = 4
+            elif format_str in ["GRAY8", "GRAY16_LE", "GRAY16_BE"]:
+                channels = 1
+            else:
+                channels = 3  # Default to RGB
+
+            # Create input Mat from pixel data (after metadata prefix)
+            pixel_data = np.frombuffer(request_frame.data[pixel_data_offset:], dtype=np.uint8)
+
+            expected_size = height * width * channels
+            if len(pixel_data) != expected_size:
+                logger.error(
+                    "Pixel data size mismatch. Expected %d bytes for %dx%d with %d channels, got %d",
+                    expected_size,
+                    width,
+                    height,
+                    channels,
+                    len(pixel_data),
+                )
+                return
 
-                    if self._gst_caps.format == "RGB" or self._gst_caps.format == "BGR":
-                        output_mat = np.frombuffer(output_buffer, dtype=np.uint8).reshape(
-                            (height, width, 3)
-                        )
-                    elif self._gst_caps.format == "GRAY8":
-                        output_mat = np.frombuffer(output_buffer, dtype=np.uint8).reshape(
-                            (height, width)
-                        )
-                    else:
-                        # Default to same shape as input
-                        output_mat = np.frombuffer(output_buffer, dtype=np.uint8).reshape(
-                            input_mat.shape
-                        )
+            # Reshape to image dimensions
+            if channels == 1:
+                input_mat = pixel_data.reshape((height, width))
+            else:
+                input_mat = pixel_data.reshape((height, width, channels))
+
+            # Response doesn't need metadata prefix - just pixel data
+            with response_writer.get_frame_buffer(pixel_data_size) as output_buffer:
+                # Create output Mat from buffer (zero-copy)
+                output_data = np.frombuffer(output_buffer, dtype=np.uint8)
+                if channels == 1:
+                    output_mat = output_data.reshape((height, width))
                 else:
-                    # Use same shape as input
-                    output_mat = np.frombuffer(output_buffer, dtype=np.uint8).reshape(
-                        input_mat.shape
-                    )
+                    output_mat = output_data.reshape((height, width, channels))
 
-                # Call user's processing function
-                self._on_frame_callback(input_mat, output_mat)
+                # Call user's processing function with metadata
+                self._on_frame_callback(frame_metadata, input_mat, output_mat)
 
             # Commit the response frame after buffer is released
             response_writer.commit_frame()
 
             logger.debug(
-                "Processed duplex frame %d (%dx%d)",
-                self._frame_count,
-                input_mat.shape[1],
-                input_mat.shape[0],
+                "Processed duplex frame %d (%dx%d %s)",
+                frame_metadata.frame_number,
+                width,
+                height,
+                format_str,
             )
 
         except Exception as e: