{"id":34830003,"url":"https://github.com/modelingevolution/rocket-welder-sdk","last_synced_at":"2026-06-13T23:05:19.440Z","repository":{"id":315091008,"uuid":"1036733533","full_name":"modelingevolution/rocket-welder-sdk","owner":"modelingevolution","description":"Client-Libraries for C++/C#/Python for RocketWelder","archived":false,"fork":false,"pushed_at":"2026-05-29T08:33:06.000Z","size":7648,"stargazers_count":1,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-05-29T10:15:44.285Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"C#","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/modelingevolution.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-08-12T14:01:27.000Z","updated_at":"2026-05-29T08:29:36.000Z","dependencies_parsed_at":"2025-09-16T18:01:51.763Z","dependency_job_id":"df2983bb-dd3f-43b9-8190-c2eafe4ff744","html_url":"https://github.com/modelingevolution/rocket-welder-sdk","commit_stats":null,"previous_names":["modelingevolution/rocket-welder-sdk"],"tags_count":110,"template":false,"template_full_name":null,"purl":"pkg:github/modelingevolution/rocket-welder-sdk","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/modelingevolution%2Frocket-welder-sdk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/modelingevolution%2Frocket-welder-sdk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/modelingevolution%2Frocket-welder-sdk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/modelingevolution%2Frocket-welder-sdk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/modelingevolution","download_url":"https://codeload.github.com/modelingevolution/rocket-welder-sdk/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/modelingevolution%2Frocket-welder-sdk/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33858578,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-03T02:00:06.370Z","response_time":59,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-12-25T15:47:20.080Z","updated_at":"2026-06-03T10:00:28.601Z","avatar_url":"https://github.com/modelingevolution.png","language":"C#","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Rocket Welder SDK\n\n[![NuGet](https://img.shields.io/nuget/v/RocketWelder.SDK.svg)](https://www.nuget.org/packages/RocketWelder.SDK/)\n[![PyPI](https://img.shields.io/pypi/v/rocket-welder-sdk.svg)](https://pypi.org/project/rocket-welder-sdk/)\n[![vcpkg](https://img.shields.io/badge/vcpkg-rocket--welder--sdk-blue)](https://github.com/modelingevolution/rocket-welder-sdk-vcpkg-registry)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\n**Client libraries for building custom AI/ML video processing containers that integrate with RocketWelder (Neuron) devices.**\n\n## Overview\n\nThe Rocket Welder SDK enables AI/ML developers to build custom video processing containers for Neuron industrial vision devices. It provides high-performance, **zero-copy** frame access via shared memory, supporting real-time computer vision, object detection, and AI inference workloads.\n\n**Target Audience**: AI/ML developers building containerized applications for:\n- Real-time object detection (YOLO, custom models)\n- Computer vision processing\n- AI inference on video streams\n- Industrial vision applications\n\n## Table of Contents\n\n- [Quick Start](#quick-start)\n- [Your First AI Processing Container](#your-first-ai-processing-container)\n- [Development Workflow](#development-workflow)\n- [Deploying to Neuron Device](#deploying-to-neuron-device)\n- [RocketWelder Integration](#rocketwelder-integration)\n- [API Reference](#api-reference)\n- [Production Best Practices](#production-best-practices)\n\n## Quick Start\n\n### Installation\n\n| Language | Package Manager | Package Name |\n|----------|----------------|--------------|\n| C++ | vcpkg | rocket-welder-sdk |\n| C# | NuGet | RocketWelder.SDK |\n| Python | pip | rocket-welder-sdk |\n\n#### Python\n```bash\npip install rocket-welder-sdk\n```\n\n#### C#\n```bash\ndotnet add package RocketWelder.SDK\n```\n\n#### C++\n```bash\nvcpkg install rocket-welder-sdk\n```\n\n## Your First AI Processing Container\n\n### Starting with Examples\n\nThe SDK includes ready-to-use examples in the `/examples` directory:\n\n```\nexamples/\n├── python/\n│   ├── simple_client.py       # Timestamp overlay example\n│   ├── integration_client.py  # Testing with --exit-after\n│   └── Dockerfile             # Ready-to-build container\n├── csharp/\n│   └── SimpleClient/\n│       ├── Program.cs          # Full example with UI controls\n│       └── Dockerfile          # Ready-to-build container\n└── cpp/\n    ├── simple_client.cpp\n    └── CMakeLists.txt\n```\n\n### Python Example - Simple Timestamp Overlay\n\n```python\n#!/usr/bin/env python3\nimport sys\nimport cv2\nimport numpy as np\nfrom datetime import datetime\nimport rocket_welder_sdk as rw\n\n# Create client - reads CONNECTION_STRING from environment or args\nclient = rw.Client.from_(sys.argv)\n\ndef process_frame(frame: np.ndarray) -\u003e None:\n    \"\"\"Add timestamp overlay to frame - zero copy!\"\"\"\n    timestamp = datetime.now().strftime(\"%H:%M:%S\")\n    cv2.putText(frame, timestamp, (10, 30),\n                cv2.FONT_HERSHEY_SIMPLEX, 0.7, (255, 255, 255), 2)\n\n# Start processing\nclient.start(process_frame)\n\n# Keep running\nwhile client.is_running:\n    time.sleep(0.1)\n```\n\n### Building Your Container\n\n```bash\n# Navigate to examples directory\ncd python/examples\n\n# Build Docker image\ndocker build -t my-ai-app:v1 -f Dockerfile ..\n\n# Test locally with file\ndocker run --rm \\\n    -e CONNECTION_STRING=\"file:///data/test.mp4?loop=true\" \\\n    -v /path/to/video.mp4:/data/test.mp4:ro \\\n    my-ai-app:v1\n```\n\n## Development Workflow\n\n### Step 1: Test Locally with Video File\n\nStart by testing your container locally before deploying to Neuron:\n\n```bash\n# Build your container\ndocker build -t my-ai-app:v1 -f python/examples/Dockerfile .\n\n# Test with a video file\ndocker run --rm \\\n    -e CONNECTION_STRING=\"file:///data/test.mp4?loop=true\u0026preview=false\" \\\n    -v $(pwd)/examples/test_stream.mp4:/data/test.mp4:ro \\\n    my-ai-app:v1\n```\n\nYou can also see preview in your terminal. \n\n```bash\n# Install x11-apps\nsudo apt install x11-apps\n\n# Test with a video file\ndocker run --rm \\\n    -e CONNECTION_STRING=\"file:///data/test.mp4?loop=true\u0026preview=true\" \\\n    -e DISPLAY=$DISPLAY \\\n    -v /path/to/your/file.mp4:/data/test.mp4:ro -v /tmp/.X11-unix:/tmp/.X11-unix     my-ai-app:v1\n```\n\n### Step 2: Test with Live Stream from Neuron\n\nOnce your container works locally, test it with a live stream from your Neuron device:\n\n#### Configure RocketWelder Pipeline for Streaming\n\n1. Access RocketWelder UI on your Neuron device (usually `http://neuron-ip:8080`)\n2. Open **Pipeline Designer**\n3. Click **\"Add Element\"**\n4. Choose your video source (e.g., `pylonsrc` for Basler cameras)\n5. Add **caps filter** to specify format: `video/x-raw,width=1920,height=1080,format=GRAY8`\n6. Add **jpegenc** element\n7. Add **tcpserversink** element with properties:\n   - `host`: `0.0.0.0`\n   - `port`: `5000`\n8. Start the pipeline\n\nExample pipeline:\n```\npylonsrc → video/x-raw,width=1920,height=1080,format=GRAY8 → queue max-buffers-size=1, Leaky=Upstream → jpegenc → tcpserversink host=0.0.0.0 port=5000 sync=false\n```\n\n#### Connect from Your Dev Laptop\n\n```bash\n# On your laptop - connect to Neuron's TCP stream\ndocker run --rm \\\n    -e CONNECTION_STRING=\"mjpeg+tcp://neuron-ip:5000\" \\\n    --network host \\\n    my-ai-app:v1\n```\n\nYou can also see preview in your terminal. \n```bash\ndocker run --rm \\\n    -e CONNECTION_STRING=\"mjpeg+tcp://\u003cneuron-ip\u003e:\u003ctcp-server-sink-port\u003e?preview=true\" \\\n    -e DISPLAY=$DISPLAY \\\n    -v /tmp/.X11-unix:/tmp/.X11-unix \\\n    --network host my-ai-app:v1\n```\n\nThis allows you to:\n- Test your AI processing with real camera feeds\n- Debug frame processing logic\n- Measure performance with actual hardware\n\n## Deploying to Neuron Device\n\n### Option 1: Local Docker Registry (Recommended for Development)\n\nThis is the fastest workflow for iterative development:\n\n#### Setup Registry on Your Laptop (One-time)\n\n```bash\n# Start a local Docker registry\ndocker run -d \\\n    -p 5000:5000 \\\n    --restart=always \\\n    --name registry \\\n    registry:2\n\n# Verify it's running\ncurl http://localhost:5000/v2/_catalog\n```\n\n#### Configure Neuron to Use Your Laptop Registry (One-time)\n\n```bash\n# SSH to Neuron device\nssh user@neuron-ip\n\n# Edit Docker daemon config\nsudo nano /etc/docker/daemon.json\n\n# Add your laptop's IP to insecure registries:\n{\n  \"insecure-registries\": [\"laptop-ip:5000\"]\n}\n\n# Restart Docker\nsudo systemctl restart docker\n```\n\n**Note**: Replace `laptop-ip` with your laptop's actual IP address (e.g., `192.168.1.100`).\nTo find it: `ip addr show` or `ifconfig`\n\n#### Push Image to Your Registry\n\n```bash\n# On your laptop - tag for local registry\ndocker tag my-ai-app:v1 localhost:5000/my-ai-app:v1\n\n# Push to registry\ndocker push localhost:5000/my-ai-app:v1\n\n# Verify push\ncurl http://localhost:5000/v2/my-ai-app/tags/list\n```\n\n#### Pull on Neuron Device\n\n```bash\n# SSH to Neuron\nssh user@neuron-ip\n\n# Pull from laptop registry\ndocker pull laptop-ip:5000/my-ai-app:v1\n\n# Verify image\ndocker images | grep my-ai-app\n```\n\n#### Workflow Summary\n\n```bash\n# Iterative development loop:\n1. Edit code on laptop\n2. docker build -t localhost:5000/my-ai-app:v1 .\n3. docker push localhost:5000/my-ai-app:v1\n4. Configure in RocketWelder UI (once)\n5. RocketWelder pulls and runs your container\n```\n\n### Option 2: Export/Import (For One-off Transfers)\n\nUseful when you don't want to set up a registry:\n\n```bash\n# On your laptop - save image to tar\ndocker save my-ai-app:v1 | gzip \u003e my-ai-app-v1.tar.gz\n\n# Transfer to Neuron\nscp my-ai-app-v1.tar.gz user@neuron-ip:/tmp/\n\n# SSH to Neuron and load\nssh user@neuron-ip\ndocker load \u003c /tmp/my-ai-app-v1.tar.gz\n\n# Verify\ndocker images | grep my-ai-app\n```\n\n### Option 3: Azure Container Registry (Production)\n\nFor production deployments:\n\n```bash\n# Login to ACR (Azure Container Registry)\naz acr login --name your-registry\n\n# Tag and push\ndocker tag my-ai-app:v1 your-registry.azurecr.io/my-ai-app:v1\ndocker push your-registry.azurecr.io/my-ai-app:v1\n\n# Configure Neuron to use ACR (credentials required)\n```\n\n## RocketWelder Integration\n\n### Understanding zerosink vs zerofilter\n\nRocketWelder provides two GStreamer elements for container integration:\n\n| Element | Mode | Use Case |\n|---------|------|----------|\n| **zerosink** | One-way | RocketWelder → Your Container\u003cbr/\u003eRead frames, process, log results |\n| **zerofilter** | Duplex | RocketWelder ↔ Your Container\u003cbr/\u003eRead frames, modify them, return modified frames |\n\n**Most AI use cases use `zerosink`** (one-way mode):\n- Object detection (draw bounding boxes)\n- Classification (overlay labels)\n- Analytics (count objects, log events)\n\n**Use `zerofilter`** (duplex mode) when:\n- You need to modify frames and return them to the pipeline\n- Real-time visual effects/filters\n- Frame enhancement before encoding\n\n### Configuring Your Container in RocketWelder\n\n#### Step-by-Step UI Configuration\n\n1. **Access RocketWelder UI**\n   - Navigate to `http://neuron-ip:8080`\n   - Log in to your Neuron device\n\n2. **Open Pipeline Designer**\n   - Go to **Pipelines** section\n   - Create new pipeline or edit existing\n\n3. **Add Video Source**\n   - Click **\"Add Element\"**\n   - Choose your camera source (e.g., `pylonsrc`, `aravissrc`)\n   - Configure camera properties\n\n4. **Add Format** \n   - Add caps filter: `video/x-raw,format=RGB`\n\n5. **Add queueue**\n   - max-num-buffers: 1\n   - leaky: upstream\n\n5. **Add ZeroBuffer Element**\n   - Click **\"Add Element\"**\n   - Select **\"zerosink\"** (or **\"zerofilter\"** for duplex mode)\n   - Scroll down in properties panel on the right\n\n6. **Configure Consumer**\n   - Toggle **\"Enable ZeroBuffer Consumer\"** ✓\n   - Select **\"Consumer Mode\"** dropdown\n   - Choose **\"Docker Container\"** (not Process)\n\n7. **Configure Docker Settings**\n   - **Image**: Enter your image name\n     - Local registry: `laptop-ip:5000/my-ai-app`\n     - ACR: `your-registry.azurecr.io/my-ai-app`\n     - Loaded image: `my-ai-app`\n   - **Tag**: `v1` (or your version tag)\n   - **Environment Variables**: (optional) Add custom env vars if needed\n   - **Auto-remove**: ✓ (recommended - cleans up container on stop)\n\n8. **Save Pipeline Configuration**\n\n9. **Start Pipeline**\n   - Click **\"Start\"** button\n   - RocketWelder will automatically:\n     - Pull your Docker image (if not present)\n     - Create shared memory buffer\n     - Launch your container with `CONNECTION_STRING` env var\n     - Start streaming frames\n\n### Automatic Environment Variables\n\nWhen RocketWelder launches your container, it automatically sets:\n\n```bash\nCONNECTION_STRING=shm://zerobuffer-abc123-456?size=20MB\u0026metadata=4KB\u0026mode=oneway\nSessionId=def789-012                    # For UI controls (if enabled)\nEventStore=esdb://host.docker.internal:2113?tls=false  # For external controls\n```\n\nYour SDK code simply reads `CONNECTION_STRING`:\n\n```python\n# Python - automatically reads CONNECTION_STRING from environment\nclient = rw.Client.from_(sys.argv)\n```\n\n```csharp\n// C# - automatically reads CONNECTION_STRING\nvar client = RocketWelderClient.From(args);\n```\n\n### Example Pipeline Configurations\n\n#### AI Object Detection Pipeline\n\n```\npylonsrc\n  → video/x-raw,width=1920,height=1080,format=Gray8\n  → videoconvert\n  → zerosink\n     └─ Docker: laptop-ip:5000/yolo-detector:v1\n```\n\nYour YOLO container receives frames, detects objects, draws bounding boxes.\n\n#### Dual Output: AI Processing\n\n```\npylonsrc\n  → video/x-raw,width=1920,height=1080,format=Gray8\n  → tee name=t\n      t. → queue → jpegenc → tcpserversink\n      t. → queue → zerofilter → queue → jpegenc → tcpserversink\n           └─ Docker: laptop-ip:5000/my-ai-app:v1\n```\n\n#### Real-time Frame Enhancement with Live Preview (Duplex Mode)\n\n```\n  → pylonsrc hdr-sequence=\"5000,5500\" hdr-sequence2=\"19,150\" hdr-profile=0\n  → video/x-raw,width=1920,height=1080,format=Gray8\n  → queue max-num-buffers=1 leaky=upstream\n  → hdr mode=burst num-frames=2\n  → sortingbuffer \n  → queue max-num-buffers=1 leaky=upstream\n  → zerofilter\n     └─ Docker: laptop-ip:5000/frame-enhancer:v1\n  → queue max-num-buffers=1 leaky=upstream\n  → jpegenc\n  → multipartmux enable-html=true\n  → tcpserversink host=0.0.0.0 port=5000 sync=false\n```\n\nIn duplex mode with `zerofilter`, your container:\n1. Receives input frames via shared memory (automatically configured by RocketWelder)\n2. Processes them in real-time (e.g., AI enhancement, object detection, overlays)\n3. Writes modified frames back to shared memory\n4. Modified frames flow back into RocketWelder pipeline for streaming/display\n\n**Pipeline elements explained:**\n- `pylonsrc hdr-sequence=\"5000,5500\"`: Configures HDR Profile 0 with 5000μs and 5500μs exposures (cycles automatically via camera sequencer)\n- `hdr-sequence2=\"19,150\"`: Configures HDR Profile 1 with 2 exposures for runtime switching\n- `hdr-profile=0`: Starts with Profile 0 (can be changed at runtime to switch between lighting conditions), requires a branch with histogram, dre and pylontarget.\n- `hdr processing-mode=burst num-frames=2`: HDR blending element - combines multiple exposures into single HDR frame\n- `sortingbuffer skip-behaviour=hdr`: Reorders out-of-order frames from Pylon camera using HDR metadata (MasterSequence, ExposureSequenceIndex) - automatically detects frame order using `image_number` from Pylon metadata \n- `zerofilter`: Bidirectional shared memory connection to your Docker container\n- `jpegenc`: JPEG compression for network streaming\n- `multipartmux enable-html=true`: Creates MJPEG stream with CORS headers for browser viewing\n- `tcpserversink`: Streams to RocketWelder UI at `http://neuron-ip:5000`\n\n**View live preview:**\nOpen in browser: `http://neuron-ip:5000` to see the processed video stream with your AI enhancements in real-time!\n\n**HDR Profile Switching:**\nThe dual-profile system allows runtime switching between lighting conditions:\n- Profile 0 (2 exposures): Fast cycling for normal conditions\n- Profile 1 (2 exposures): More exposures for challenging lighting\n- Switch dynamically via `hdr-profile` property without stopping the pipeline (requires another branch, histogram, dre, pylon-target)\n\n**Use case examples:**\n- **AI object detection**: Draw bounding boxes that appear in RocketWelder preview\n- **Real-time enhancement**: AI super-resolution, denoising, stabilization\n- **Visual feedback**: Add crosshairs, tracking overlays, status indicators\n- **Quality control**: Highlight defects or areas of interest in industrial inspection\n\n## Connection String Format\n\nThe SDK uses URI-style connection strings:\n\n```\nprotocol://[host[:port]]/[path][?param1=value1\u0026param2=value2]\n```\n\n### Supported Protocols\n\n#### Shared Memory (Production - Automatic)\n```\nshm://buffer-name?size=20MB\u0026metadata=4KB\u0026mode=oneway\n```\n\nWhen deployed with RocketWelder, this is set automatically via `CONNECTION_STRING` environment variable.\n\n**Parameters:**\n- `size`: Buffer size (default: 20MB, supports: B, KB, MB, GB)\n- `metadata`: Metadata size (default: 4KB)\n- `mode`: `oneway` (zerosink) or `duplex` (zerofilter)\n\n#### File Protocol (Local Testing)\n```\nfile:///path/to/video.mp4?loop=true\u0026preview=false\n```\n\n**Parameters:**\n- `loop`: Loop playback (`true`/`false`, default: `false`)\n- `preview`: Show preview window (`true`/`false`, default: `false`)\n\n#### MJPEG over TCP (Development/Testing)\n```\nmjpeg+tcp://neuron-ip:5000\n```\n\nConnect to RocketWelder's `tcpserversink` for development testing.\n\n#### MJPEG over HTTP\n```\nmjpeg+http://camera-ip:8080\n```\n\nFor network cameras or HTTP streamers.\n\n## API Reference\n\n### Python API\n\n```python\nimport rocket_welder_sdk as rw\n\n# Create client (reads CONNECTION_STRING from env or args)\nclient = rw.Client.from_(sys.argv)\n\n# Or specify connection string directly\nclient = rw.Client.from_connection_string(\"shm://buffer-name?size=20MB\")\n\n# Process frames - one-way mode\n@client.on_frame\ndef process_frame(frame: np.ndarray) -\u003e None:\n    # frame is a numpy array (height, width, channels)\n    # Modify in-place for zero-copy performance\n    cv2.putText(frame, \"AI Processing\", (10, 30),\n                cv2.FONT_HERSHEY_SIMPLEX, 1.0, (0, 255, 0), 2)\n\n# Process frames - duplex mode\ndef process_frame_duplex(input_frame: np.ndarray, output_frame: np.ndarray) -\u003e None:\n    # Copy input to output and modify\n    np.copyto(output_frame, input_frame)\n    # Add AI overlay to output_frame\n    cv2.putText(output_frame, \"Processed\", (10, 30),\n                cv2.FONT_HERSHEY_SIMPLEX, 1.0, (0, 255, 0), 2)\n\n# Start processing\nclient.start(process_frame)  # or process_frame_duplex for duplex mode\n\n# Keep running\nwhile client.is_running:\n    time.sleep(0.1)\n\n# Stop\nclient.stop()\n```\n\n### C# API\n\n```csharp\nusing RocketWelder.SDK;\nusing Emgu.CV;\n\n// Create client (reads CONNECTION_STRING from env or config)\nvar client = RocketWelderClient.From(args);\n\n// Or specify connection string directly\nvar client = RocketWelderClient.FromConnectionString(\"shm://buffer-name?size=20MB\");\n\n// Process frames - one-way mode\nclient.Start((Mat frame) =\u003e\n{\n    // frame is an Emgu.CV.Mat (zero-copy)\n    CvInvoke.PutText(frame, \"AI Processing\", new Point(10, 30),\n                     FontFace.HersheySimplex, 1.0, new MCvScalar(0, 255, 0), 2);\n});\n\n// Process frames - duplex mode\nclient.Start((Mat input, Mat output) =\u003e\n{\n    input.CopyTo(output);\n    CvInvoke.PutText(output, \"Processed\", new Point(10, 30),\n                     FontFace.HersheySimplex, 1.0, new MCvScalar(0, 255, 0), 2);\n});\n```\n\n### C++ API\n\n```cpp\n#include \u003crocket_welder/client.hpp\u003e\n#include \u003copencv2/opencv.hpp\u003e\n\n// Create client (reads CONNECTION_STRING from env or args)\nauto client = rocket_welder::Client::from(argc, argv);\n\n// Or specify connection string directly\nauto client = rocket_welder::Client::from_connection_string(\"shm://buffer-name?size=20MB\");\n\n// Process frames - one-way mode\nclient.on_frame([](cv::Mat\u0026 frame) {\n    // frame is a cv::Mat reference (zero-copy)\n    cv::putText(frame, \"AI Processing\", cv::Point(10, 30),\n                cv::FONT_HERSHEY_SIMPLEX, 1.0, cv::Scalar(0, 255, 0), 2);\n});\n\n// Process frames - duplex mode\nclient.on_frame([](const cv::Mat\u0026 input, cv::Mat\u0026 output) {\n    input.copyTo(output);\n    cv::putText(output, \"Processed\", cv::Point(10, 30),\n                cv::FONT_HERSHEY_SIMPLEX, 1.0, cv::Scalar(0, 255, 0), 2);\n});\n\n// Start processing\nclient.start();\n```\n\n## Production Best Practices\n\n### Performance Optimization\n\n1. **Zero-Copy Processing**\n   - Modify frames in-place when possible\n   - Avoid unnecessary memory allocations in the frame processing loop\n   - Use OpenCV operations that work directly on the frame buffer\n\n2. **Frame Rate Management**\n   ```python\n   # Process every Nth frame for expensive AI operations\n   frame_count = 0\n\n   def process_frame(frame):\n       global frame_count\n       frame_count += 1\n       if frame_count % 5 == 0:  # Process every 5th frame\n           run_expensive_ai_model(frame)\n   ```\n\n3. **Logging**\n   - Use structured logging with appropriate levels\n   - Avoid logging in the frame processing loop for production\n   - Log only important events (errors, detections, etc.)\n\n### Error Handling\n\n```python\nimport logging\nimport rocket_welder_sdk as rw\n\nlogger = logging.getLogger(__name__)\n\nclient = rw.Client.from_(sys.argv)\n\ndef on_error(sender, error):\n    logger.error(f\"Client error: {error.Exception}\")\n    # Implement recovery logic or graceful shutdown\n\nclient.OnError += on_error\n```\n\n### Monitoring\n\n```python\nimport time\nfrom datetime import datetime\n\nclass FrameStats:\n    def __init__(self):\n        self.frame_count = 0\n        self.start_time = time.time()\n\n    def update(self):\n        self.frame_count += 1\n        if self.frame_count % 100 == 0:\n            elapsed = time.time() - self.start_time\n            fps = self.frame_count / elapsed\n            logger.info(f\"Processed {self.frame_count} frames, {fps:.1f} FPS\")\n\nstats = FrameStats()\n\ndef process_frame(frame):\n    stats.update()\n    # Your processing logic\n```\n\n### Docker Best Practices\n\n1. **Use Multi-stage Builds**\n   ```dockerfile\n   FROM python:3.12-slim as builder\n   # Build dependencies\n\n   FROM python:3.12-slim\n   # Copy only runtime artifacts\n   ```\n\n2. **Minimize Image Size**\n   - Use slim base images\n   - Remove build tools in final stage\n   - Clean apt cache: `rm -rf /var/lib/apt/lists/*`\n\n3. **Health Checks**\n   ```dockerfile\n   HEALTHCHECK --interval=30s --timeout=3s \\\n       CMD pgrep -f my_app.py || exit 1\n   ```\n\n4. **Resource Limits** (in RocketWelder docker-compose or deployment)\n   ```yaml\n   deploy:\n     resources:\n       limits:\n         cpus: '2.0'\n         memory: 2G\n   ```\n\n## Examples\n\nThe `examples/` directory contains complete working examples:\n\n- **python/simple_client.py** - Minimal timestamp overlay\n- **python/integration_client.py** - Testing with --exit-after flag\n- **python/advanced_client.py** - Full-featured with UI controls\n- **csharp/SimpleClient/** - Complete C# example with crosshair controls\n- **cpp/simple_client.cpp** - C++ example\n\n## Troubleshooting\n\n### Container Doesn't Start\n\n**Check Docker logs:**\n```bash\ndocker ps -a | grep my-ai-app\ndocker logs \u003ccontainer-id\u003e\n```\n\n**Common issues:**\n- Image not found (check `docker images`)\n- Insecure registry not configured on Neuron\n\n### Cannot Pull from Laptop Registry\n\n```bash\n# On Neuron - test connectivity\nping laptop-ip\n\n# Test registry access\ncurl http://laptop-ip:5000/v2/_catalog\n\n# Check Docker daemon config\ncat /etc/docker/daemon.json\n\n# Restart Docker after config change\nsudo systemctl restart docker\n```\n\n### SDK Connection Timeout\n\n**Check shared memory buffer exists:**\n```bash\n# On Neuron device\nls -lh /dev/shm/\n\n# Should see zerobuffer-* files\n```\n\n**Check RocketWelder pipeline status:**\n- Is pipeline running?\n- Is zerosink element configured correctly?\n- Check RocketWelder logs for errors\n\n### Low Frame Rate / Performance\n\n1. **Check CPU usage:** `htop` or `docker stats`\n2. **Reduce AI model complexity** or process every Nth frame\n3. **Profile your code** to find bottlenecks\n4. **Use GPU acceleration** if available (NVIDIA runtime)\n\n## Support\n\n- **Issues**: [GitHub Issues](https://github.com/modelingevolution/rocket-welder-sdk/issues)\n- **Discussions**: [GitHub Discussions](https://github.com/modelingevolution/rocket-welder-sdk/discussions)\n- **Documentation**: [https://docs.rocket-welder.io](https://docs.rocket-welder.io)\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Acknowledgments\n\n- GStreamer Project for the multimedia framework\n- ZeroBuffer contributors for the zero-copy buffer implementation\n- OpenCV community for computer vision tools\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmodelingevolution%2Frocket-welder-sdk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmodelingevolution%2Frocket-welder-sdk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmodelingevolution%2Frocket-welder-sdk/lists"}