vision2constellation

# Clone the repository
git clone https://github.com/Constellation-Overwatch/vision2constellation.git
cd vision2constellation

# Install dependencies
uv sync

# Copy and configure environment
cp .env.example .env
# Edit .env with your CONSTELLATION_ORG_ID and CONSTELLATION_ENTITY_ID

# Run with default model (YOLOE C4ISR)
uv run overwatch.py

# Run with specific model
uv run overwatch.py --model rtdetr

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows (PowerShell)
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

# Homebrew
brew install uv

# Auto-detect camera (default)
uv run overwatch.py

# Specific camera by index
uv run overwatch.py --camera 0

# Skip built-in cameras (use external)
uv run overwatch.py --skip-native

# RTSP stream
uv run overwatch.py --rtsp rtsp://192.168.50.2:8554/live/stream

# HTTP stream
uv run overwatch.py --http http://192.168.1.100:8080/stream.mjpg

# Device path (Linux)
uv run overwatch.py --device /dev/video4

# List available devices
uv run overwatch.py --list-devices

# Camera diagnostics (macOS)
uv run utils/camera_diagnostics.py

# YOLOE C4ISR (default) - Threat detection
uv run overwatch.py --conf 0.15 --min-frames 1
uv run overwatch.py --custom-threats "drone" "robot"

# RT-DETR - High-speed production
uv run overwatch.py --model rtdetr --conf 0.4

# YOLOE - Custom object detection
uv run overwatch.py --model yoloe --min-frames 3 --tracker botsort.yaml

# SAM2 - Segmentation
uv run overwatch.py --model sam2 --conf 0.3 --imgsz 1024

# Moondream - Vision-language
uv run overwatch.py --model moondream --prompt "vehicles and people"

# List all available models
uv run overwatch.py --list-models

cp .env.example .env

constellation.events.isr.{organization_id}.{entity_id}
                    └── Detection events, bootsequence, shutdown

constellation.video.{entity_id}
                    └── Video frame stream (raw JPEG bytes)

import nats
from nats.js.api import ConsumerConfig, DeliverPolicy, AckPolicy

async def consume_video_frames():
    nc = await nats.connect("nats://localhost:4222", token="your-token")
    js = nc.jetstream()

    entity_id = "your-entity-id"

    # Subscribe to live frames (ephemeral consumer)
    sub = await js.subscribe(
        f"constellation.video.{entity_id}",
        stream="CONSTELLATION_VIDEO_FRAMES",
        config=ConsumerConfig(
            deliver_policy=DeliverPolicy.NEW,
            ack_policy=AckPolicy.NONE,
        ),
    )

    async for msg in sub.messages:
        frame_bytes = msg.data  # Raw JPEG bytes (starts with FF D8 FF)
        frame_num = msg.headers.get("Frame-Number")
        detection_count = msg.headers.get("Detection-Count")
        # Process frame - e.g., save to file, forward to WebSocket, etc.

{
  "timestamp": "2025-11-21T13:18:19.912559+00:00",
  "event_type": "detection",
  "entity_id": "1048bff5-5b97-4fa8-a0f1-061662b32163",
  "device_id": "b546cd5c6dc0b878",
  "detection": {
    "track_id": "clx7y3k2r0000qzrm8n7qh3k1",
    "model_type": "yoloe-c4isr-threat-detection",
    "label": "person",
    "confidence": 0.96,
    "bbox": { "x_min": 0.189, "y_min": 0.179, "x_max": 0.837, "y_max": 0.997 },
    "metadata": { "native_id": 1, "threat_level": "LOW_THREAT" }
  }
}

vision2constellation/
├── src/
│   ├── overwatch.py            # Main orchestrator entry point
│   ├── config/                 # Model configurations and threat definitions
│   │   ├── models.py           # DetectionMode enum and model configs
│   │   ├── threats.py          # C4ISR threat classification
│   │   └── defaults.py         # Default configuration values
│   ├── services/               # Core service layer
│   │   ├── detection/          # Model-specific detection implementations
│   │   │   ├── base.py         # BaseDetector abstract class
│   │   │   ├── factory.py      # DetectorFactory for model creation
│   │   │   ├── yoloe_c4isr.py  # C4ISR threat detection (default)
│   │   │   ├── rtdetr.py       # RT-DETR high-speed detection
│   │   │   ├── yoloe.py        # Open-vocabulary detection
│   │   │   ├── sam2.py         # Segmentation model
│   │   │   └── moondream.py    # Vision-language model
│   │   ├── tracking/           # Object tracking and state
│   │   │   ├── state.py        # TrackingState, C4ISRTrackingState
│   │   │   └── service.py      # TrackingService coordinator
│   │   ├── communication/      # NATS/JetStream messaging
│   │   │   ├── service.py      # OverwatchCommunication
│   │   │   └── publisher.py    # ConstellationPublisher
│   │   └── video/              # Video capture and display
│   │       └── service.py      # VideoService
│   └── utils/                  # Utilities
│       ├── args.py             # CLI argument parsing
│       ├── device.py           # Device fingerprinting
│       ├── constellation.py    # Constellation ID management
│       ├── frame_encoder.py    # Video frame encoding for streaming
│       └── signals.py          # Signal handlers
├── docs/                       # Documentation
├── models/                     # Downloaded ML models (auto-generated)
├── utils/                      # Diagnostic utilities
├── pyproject.toml              # Python project configuration
└── .env.example                # Example configuration