rocket-welder-sdk 0.0.1__tar.gz → 1.0.0__tar.gz

rocket_welder_sdk-1.0.0/PKG-INFO

@@ -0,0 +1,410 @@
+Metadata-Version: 2.4
+Name: rocket-welder-sdk
+Version: 1.0.0
+Summary: Client library for RocketWelder video streaming services
+Home-page: https://github.com/modelingevolution/rocket-welder-sdk
+Author: RocketWelder
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Multimedia :: Video
+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
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: numpy>=1.20.0
+Requires-Dist: opencv-python>=4.5.0
+Requires-Dist: zerobuffer-ipc>=1.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: black>=22.0; extra == "dev"
+Requires-Dist: mypy>=1.0; extra == "dev"
+Dynamic: author
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: provides-extra
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+# Rocket Welder SDK
+
+Multi-language client libraries for interacting with RocketWelder video streaming services.
+
+## Overview
+
+The Rocket Welder SDK provides high-performance video streaming capabilities for containerized applications. It offers native client libraries in C++, C#, and Python, enabling seamless integration with RocketWelder video streaming pipelines.
+
+## Features
+
+- **High Performance**: Optimized for minimal latency and maximum throughput
+- **Multi-Language Support**: Native libraries for C++, C#, and Python  
+- **Protocol Flexibility**: Support for multiple streaming protocols via connection strings
+- **Container-Ready**: Designed for Docker/Kubernetes deployments
+- **Simple Integration**: Easy-to-use API with minimal configuration
+
+## Client Libraries
+
+| Language | Package Manager | Package Name |
+|----------|----------------|--------------|
+| C++ | vcpkg | rocket-welder-sdk |
+| C# | NuGet | RocketWelder.SDK |
+| Python | pip | rocket-welder-sdk |
+
+## Connection String Format
+
+The SDK uses URI-style connection strings to specify data sources and protocols:
+
+```
+protocol://[host[:port]]/[path][?param1=value1&param2=value2]
+```
+
+### Supported Protocols
+
+#### Shared Memory (High-Performance Local)
+```
+shm://<buffer_name>
+shm://<buffer_name>?buffer_size=10MB&metadata_size=1024KB
+shm://<buffer_name>?mode=duplex&buffer_size=10MB
+```
+
+**Optional Parameters:**
+- `mode`: Communication mode (`duplex` for bidirectional/mutable, `oneway` for one-way communication; default: `duplex`)
+- `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)
+
+#### MJPEG over HTTP
+```
+mjpeg+http://192.168.1.100:8080
+mjpeg+http://camera.local:8080
+```
+
+#### MJPEG over TCP
+```
+mjpeg+tcp://192.168.1.100:5000
+mjpeg+tcp://camera.local:5000
+```
+
+### Environment Variable
+
+When deployed in a Rocket Welder container, the connection string is provided via:
+```bash
+CONNECTION_STRING=shm://camera_feed?buffer_size=20MB&metadata_size=4KB
+```
+
+## Installation
+
+### C++ (vcpkg)
+
+```bash
+vcpkg install rocket-welder-sdk
+```
+
+### C# (NuGet)
+
+```bash
+dotnet add package RocketWelder.SDK
+```
+
+### Python (pip)
+
+```bash
+pip install rocket-welder-sdk
+```
+
+## Usage Examples
+
+### C++
+
+```cpp
+#include <rocket_welder/client.hpp>
+#include <opencv2/opencv.hpp>
+
+int main(int argc, char* argv[]) {
+    // Best practice: use from() which:
+    // 1. Checks environment variable (CONNECTION_STRING)
+    // 2. Overrides with command line args if provided
+    auto client = rocket_welder::Client::from(argc, argv);
+    
+    // Or specify connection string directly
+    auto client = rocket_welder::Client::from_connection_string(
+        "shm://camera_feed?buffer_size=20MB&metadata_size=4KB"
+    );
+    
+    // Process frames as OpenCV Mat (mutable by default)
+    client.on_frame([](cv::Mat& frame) {
+        // Add overlay text - zero copy!
+        cv::putText(frame, "Processing", cv::Point(10, 30),
+                    cv::FONT_HERSHEY_SIMPLEX, 1.0, cv::Scalar(0, 255, 0), 2);
+        
+        // Add timestamp overlay
+        auto now = std::chrono::system_clock::now();
+        auto time_t = std::chrono::system_clock::to_time_t(now);
+        cv::putText(frame, std::ctime(&time_t), cv::Point(10, 60),
+                    cv::FONT_HERSHEY_SIMPLEX, 0.5, cv::Scalar(255, 255, 255), 1);
+    });
+    
+    client.start();
+    return 0;
+}
+```
+
+### C#
+
+```csharp
+using RocketWelder.SDK;
+using OpenCvSharp;
+
+class Program
+{
+    static void Main(string[] args)
+    {
+        // Best practice: use From() which:
+        // 1. Checks environment variable (CONNECTION_STRING)
+        // 2. Overrides with command line args if provided
+        var client = RocketWelderClient.From(args);
+        
+        // Or specify connection string directly
+        var client = RocketWelderClient.FromConnectionString(
+            "shm://camera_feed?buffer_size=20MB&metadata_size=4KB"
+        );
+        
+        int frameCount = 0;
+        
+        // Process frames as OpenCV Mat
+        client.OnFrame((Mat frame) => 
+        {
+            // Add overlay text
+            Cv2.PutText(frame, "Processing", new Point(10, 30),
+                       HersheyFonts.HersheySimplex, 1.0, new Scalar(0, 255, 0), 2);
+            
+            // Add frame counter overlay
+            Cv2.PutText(frame, $"Frame: {frameCount++}", new Point(10, 60),
+                       HersheyFonts.HersheySimplex, 0.5, new Scalar(255, 255, 255), 1);
+        });
+        
+        client.Start();
+    }
+}
+```
+
+### Python
+
+```python
+import rocket_welder_sdk as rw
+import cv2
+import sys
+
+# Best practice: use from_args() which:
+# 1. Checks environment variable (CONNECTION_STRING)
+# 2. Overrides with command line args if provided
+client = rw.Client.from_args(sys.argv)
+
+# Or specify connection string directly
+client = rw.Client.from_connection_string("shm://camera_feed?buffer_size=20MB&metadata_size=4KB")
+
+# Process frames as numpy arrays (OpenCV compatible)
+@client.on_frame
+def process_frame(frame: np.ndarray):
+    # Add overlay text - zero copy!
+    cv2.putText(frame, "Processing", (10, 30),
+                cv2.FONT_HERSHEY_SIMPLEX, 1.0, (0, 255, 0), 2)
+    
+    # Add timestamp overlay
+    from datetime import datetime
+    timestamp = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
+    cv2.putText(frame, timestamp, (10, 60),
+                cv2.FONT_HERSHEY_SIMPLEX, 0.5, (255, 255, 255), 1)
+
+client.start()
+
+# Or use iterator pattern
+for frame in client.frames():
+    # Each frame is a numpy array
+    print(f"Received frame: {frame.shape}")
+```
+
+## Docker Integration
+
+### C++ Dockerfile
+
+```dockerfile
+FROM ubuntu:22.04 AS builder
+
+# Install build tools and OpenCV
+RUN apt-get update && apt-get install -y \
+    build-essential \
+    cmake \
+    libopencv-dev
+
+# Install Rocket Welder SDK via vcpkg
+RUN vcpkg install rocket-welder-sdk
+
+# Build your application
+WORKDIR /app
+COPY . .
+RUN cmake . && make
+
+FROM ubuntu:22.04
+RUN apt-get update && apt-get install -y libopencv-dev
+COPY --from=builder /app/my_app /usr/local/bin/
+CMD ["my_app"]
+```
+
+### C# Dockerfile
+
+```dockerfile
+FROM mcr.microsoft.com/dotnet/sdk:8.0 AS builder
+
+WORKDIR /app
+COPY *.csproj ./
+RUN dotnet restore
+
+COPY . ./
+RUN dotnet publish -c Release -o out
+
+FROM mcr.microsoft.com/dotnet/runtime:8.0
+WORKDIR /app
+COPY --from=builder /app/out .
+CMD ["dotnet", "MyApp.dll"]
+```
+
+### Python Dockerfile
+
+```dockerfile
+FROM python:3.11-slim
+
+# Install OpenCV and other dependencies
+RUN apt-get update && apt-get install -y \
+    python3-opencv \
+    && rm -rf /var/lib/apt/lists/*
+
+# Install Rocket Welder SDK and ML frameworks
+RUN pip install --no-cache-dir \
+    rocket-welder-sdk \
+    numpy \
+    ultralytics  # Example: YOLO
+
+WORKDIR /app
+COPY . .
+
+CMD ["python", "app.py"]
+```
+
+## Protocol Details
+
+### Shared Memory Protocol (shm://)
+
+High-performance local data transfer between processes:
+
+- **Performance**: Minimal latency, maximum throughput
+- **Use Cases**: Local processing, multi-container applications on same host
+
+### MJPEG over HTTP (mjpeg+http://)
+
+Motion JPEG streaming over HTTP:
+
+- **Performance**: Good balance of quality and bandwidth
+- **Advantages**: Wide compatibility, firewall-friendly, browser support
+- **Use Cases**: Network streaming, web applications, remote monitoring
+
+### MJPEG over TCP (mjpeg+tcp://)
+
+Motion JPEG streaming over raw TCP socket:
+
+- **Performance**: Lower latency than HTTP, less protocol overhead
+- **Advantages**: Direct socket connection, minimal overhead, suitable for local networks
+- **Use Cases**: Low-latency streaming, embedded systems, industrial applications
+
+## Building from Source
+
+### Prerequisites
+
+- CMake 3.20+
+- C++20 compiler
+- Python 3.8+ (for Python bindings)
+- .NET 6.0+ SDK (for C# bindings)
+- OpenCV 4.0+ (optional, for image processing)
+
+### Build Instructions
+
+```bash
+git clone https://github.com/modelingevolution/rocket-welder-sdk.git
+cd rocket-welder-sdk
+
+# Build all libraries
+mkdir build && cd build
+cmake ..
+make -j$(nproc)
+
+# Run tests
+ctest
+
+# Install
+sudo make install
+```
+
+## API Reference
+
+Detailed API documentation for each language:
+
+- [C++ API Reference](docs/cpp-api.md)
+- [C# API Reference](docs/csharp-api.md)
+- [Python API Reference](docs/python-api.md)
+
+## Examples
+
+See the [examples](examples/) directory for complete working examples:
+
+- [Simple Frame Reader](examples/simple-reader/)
+- [Frame Processor](examples/frame-processor/)
+- [Multi-Stream Handler](examples/multi-stream/)
+- [Performance Benchmark](examples/benchmark/)
+
+## Contributing
+
+Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## Support
+
+- **Issues**: [GitHub Issues](https://github.com/modelingevolution/rocket-welder-sdk/issues)
+- **Discussions**: [GitHub Discussions](https://github.com/modelingevolution/rocket-welder-sdk/discussions)
+- **Documentation**: [https://docs.rocket-welder.io](https://docs.rocket-welder.io)
+
+## Technical Details
+
+### GStreamer Integration
+
+The SDK integrates with GStreamer pipelines through specialized elements:
+- **zerosink**: Simple sink element for writing video frames
+- **zerobuffer**: Processing element with bidirectional communication using DuplexChannel
+
+### Zero-Copy Buffer Technology
+
+For shared memory protocol, the SDK uses:
+- **C++**: Zero-Copy-Buffer (via vcpkg) - Returns cv::Mat with zero-copy access
+- **C#**: ZeroBuffer (via NuGet) - Returns OpenCvSharp.Mat with zero-copy access
+- **Python**: zero-buffer (via pip) - Returns numpy arrays compatible with OpenCV
+
+The SDK leverages DuplexChannel for bidirectional communication, enabling:
+- Zero-copy frame access as OpenCV Mat objects
+- In-place frame processing without memory allocation
+- Direct memory mapping between producer and consumer
+- Efficient metadata passing alongside frame data
+
+This technology enables direct memory access without data duplication, providing maximum performance for local processing scenarios.
+
+## Acknowledgments
+
+- GStreamer Project for the multimedia framework
+- ZeroBuffer contributors for the zero-copy buffer implementation

rocket_welder_sdk-1.0.0/rocket_welder_sdk/__init__.py

@@ -0,0 +1,8 @@
+"""
+Rocket Welder SDK - Python client library for RocketWelder video streaming services.
+"""
+
+from .client import Client
+
+__version__ = "1.0.0"
+__all__ = ["Client"]

rocket_welder_sdk-1.0.0/rocket_welder_sdk/client.py

@@ -0,0 +1,183 @@
+"""
+RocketWelder client implementation.
+"""
+
+import os
+import sys
+import time
+import threading
+from typing import Optional, Callable, Dict, Any, Iterator
+import numpy as np
+import cv2
+
+
+class Client:
+    """Client for RocketWelder video streaming services."""
+    
+    def __init__(self, connection_string: str):
+        """
+        Initialize client with connection string.
+        
+        Args:
+            connection_string: Connection string (e.g., "shm://buffer_name")
+        """
+        self.connection_string = connection_string
+        self._callback: Optional[Callable[[np.ndarray], None]] = None
+        self._callback_with_metadata: Optional[Callable[[np.ndarray, Dict[str, Any]], None]] = None
+        self._running = False
+        self._thread: Optional[threading.Thread] = None
+        
+        # TODO: Parse connection string
+        # TODO: Initialize based on protocol (shm://, mjpeg+http://, etc.)
+    
+    @classmethod
+    def from_args(cls, argv: list) -> 'Client':
+        """
+        Create client from command line arguments and environment variables.
+        Environment variable CONNECTION_STRING is checked first, then overridden by args.
+        
+        Args:
+            argv: Command line arguments (typically sys.argv)
+        
+        Returns:
+            Client instance
+        """
+        # Check environment variable first
+        connection_string = os.environ.get('CONNECTION_STRING')
+        
+        # Override with command line args if present
+        if argv:
+            for arg in argv[1:]:  # Skip program name
+                if (arg.startswith('shm://') or 
+                    arg.startswith('mjpeg+http://') or 
+                    arg.startswith('mjpeg+tcp://')):
+                    connection_string = arg
+                    break
+        
+        return cls(connection_string or 'shm://default')
+    
+    @classmethod
+    def from_env(cls) -> 'Client':
+        """
+        Create client from environment variable CONNECTION_STRING.
+        
+        Returns:
+            Client instance
+        """
+        connection_string = os.environ.get('CONNECTION_STRING', 'shm://default')
+        return cls(connection_string)
+    
+    @classmethod
+    def from_connection_string(cls, connection_string: str) -> 'Client':
+        """
+        Create client from a specific connection string.
+        
+        Args:
+            connection_string: Connection string
+        
+        Returns:
+            Client instance
+        """
+        return cls(connection_string)
+    
+    def on_frame(self, callback: Callable) -> Callable:
+        """
+        Decorator/method to set frame processing callback.
+        
+        The callback can have one of these signatures:
+        - callback(frame: np.ndarray) -> None
+        - callback(frame: np.ndarray, metadata: dict) -> None
+        
+        Args:
+            callback: Function to process frames
+        
+        Returns:
+            The callback function (for decorator usage)
+        """
+        import inspect
+        sig = inspect.signature(callback)
+        param_count = len(sig.parameters)
+        
+        if param_count == 1:
+            self._callback = callback
+        elif param_count == 2:
+            self._callback_with_metadata = callback
+        else:
+            raise ValueError(f"Callback must have 1 or 2 parameters, got {param_count}")
+        
+        return callback
+    
+    def start(self):
+        """Start frame processing."""
+        if self._running:
+            return
+        
+        if not self._callback and not self._callback_with_metadata:
+            raise RuntimeError("Frame callback must be set before starting")
+        
+        self._running = True
+        self._thread = threading.Thread(target=self._process_frames)
+        self._thread.daemon = True
+        self._thread.start()
+    
+    def stop(self):
+        """Stop frame processing."""
+        if not self._running:
+            return
+        
+        self._running = False
+        if self._thread:
+            self._thread.join(timeout=5.0)
+            self._thread = None
+    
+    def is_running(self) -> bool:
+        """Check if client is running."""
+        return self._running
+    
+    def frames(self) -> Iterator[np.ndarray]:
+        """
+        Iterator interface for frame processing.
+        
+        Yields:
+            Frame as numpy array
+        """
+        # TODO: Implement actual frame reading
+        # For now, generate dummy frames for testing
+        while True:
+            # Create dummy frame
+            frame = np.zeros((480, 640, 3), dtype=np.uint8)
+            yield frame
+            time.sleep(0.033)  # ~30 FPS
+    
+    def _process_frames(self):
+        """Internal method to process frames in thread."""
+        # TODO: Implement actual frame processing
+        # For now, generate dummy frames for testing
+        while self._running:
+            # Create dummy frame
+            frame = np.zeros((480, 640, 3), dtype=np.uint8)
+            
+            # Create dummy metadata
+            metadata = {
+                'timestamp': time.time(),
+                'format': 'BGR',
+                'width': 640,
+                'height': 480
+            }
+            
+            # Call appropriate callback
+            if self._callback:
+                self._callback(frame)
+            elif self._callback_with_metadata:
+                self._callback_with_metadata(frame, metadata)
+            
+            time.sleep(0.033)  # ~30 FPS
+    
+    def __enter__(self):
+        """Context manager entry."""
+        self.start()
+        return self
+    
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        """Context manager exit."""
+        self.stop()