darvision 1.0.0__py3-none-any.whl

darvision/__init__.py

@@ -0,0 +1,10 @@
+"""
+DarVision — Real-time computer vision streaming framework.
+"""
+
+from darvision.host.host import Host
+from darvision.client.client import Client
+from darvision.plugins.base import DarVisionPlugin
+
+__version__ = "1.0.0"
+__all__ = ["Host", "Client", "DarVisionPlugin", "__version__"]

darvision/camera/__init__.py

@@ -0,0 +1,6 @@
+"""DarVision Camera package."""
+from darvision.camera.base import CameraSource
+from darvision.camera.webcam import WebcamSource
+from darvision.camera.queue import FrameQueue
+
+__all__ = ["CameraSource", "WebcamSource", "FrameQueue"]

darvision/camera/base.py

@@ -0,0 +1,59 @@
+"""
+Abstract camera source interface.
+All camera implementations must inherit from CameraSource.
+"""
+
+from abc import ABC, abstractmethod
+from typing import Optional
+
+import numpy as np
+
+
+class CameraSource(ABC):
+    """
+    Abstract base class for all DarVision camera sources.
+
+    Supported sources (v1: WebcamSource only):
+      - WebcamSource   — USB or built-in webcam via OpenCV
+      - VideoSource    — video file (future v1.1)
+      - RTSPSource     — IP/RTSP camera (future v1.1)
+    """
+
+    @abstractmethod
+    def open(self) -> None:
+        """Open and initialize the camera source. Raises CameraError on failure."""
+        pass
+
+    @abstractmethod
+    def read(self) -> Optional[np.ndarray]:
+        """
+        Read the next frame.
+        Returns a BGR numpy array, or None if no frame is available.
+        """
+        pass
+
+    @abstractmethod
+    def close(self) -> None:
+        """Release the camera source and any associated resources."""
+        pass
+
+    @property
+    @abstractmethod
+    def is_open(self) -> bool:
+        """True if the source is currently open and ready to read."""
+        pass
+
+    @property
+    @abstractmethod
+    def width(self) -> int:
+        pass
+
+    @property
+    @abstractmethod
+    def height(self) -> int:
+        pass
+
+    @property
+    @abstractmethod
+    def fps(self) -> float:
+        pass

darvision/camera/queue.py

@@ -0,0 +1,55 @@
+"""
+FrameQueue — thread-safe bounded queue connecting the camera thread
+to the plugin/network workers.
+
+Bounded so that if the network is slow, the oldest frames are dropped
+rather than letting memory grow without limit.
+"""
+
+import logging
+import queue
+from typing import Optional
+
+import numpy as np
+
+logger = logging.getLogger(__name__)
+
+
+class FrameQueue:
+    """
+    A thread-safe bounded queue for numpy frames.
+    When full, the oldest frame is discarded to make room (drop policy).
+    """
+
+    def __init__(self, maxsize: int = 4):
+        self._q: queue.Queue[np.ndarray] = queue.Queue(maxsize=maxsize)
+
+    def put(self, frame: np.ndarray) -> None:
+        """Add a frame; drop the oldest if the queue is full."""
+        if self._q.full():
+            try:
+                self._q.get_nowait()  # drop oldest
+            except queue.Empty:
+                pass
+        try:
+            self._q.put_nowait(frame)
+        except queue.Full:
+            pass  # race condition — silently ignore
+
+    def get(self, timeout: float = 0.1) -> Optional[np.ndarray]:
+        """Get the next frame, or None if none is available within timeout."""
+        try:
+            return self._q.get(timeout=timeout)
+        except queue.Empty:
+            return None
+
+    def qsize(self) -> int:
+        return self._q.qsize()
+
+    def clear(self) -> None:
+        """Drain all frames from the queue."""
+        while not self._q.empty():
+            try:
+                self._q.get_nowait()
+            except queue.Empty:
+                break

darvision/camera/webcam.py

@@ -0,0 +1,79 @@
+"""
+WebcamSource — captures frames from a USB or built-in webcam via OpenCV.
+"""
+
+import logging
+from typing import Optional
+
+import cv2
+import numpy as np
+
+from darvision.camera.base import CameraSource
+from darvision.exceptions import CameraError
+
+logger = logging.getLogger(__name__)
+
+
+class WebcamSource(CameraSource):
+    """
+    Captures frames from a local webcam using OpenCV VideoCapture.
+    """
+
+    def __init__(self, camera_id: int = 0, width: int = 640, height: int = 480, fps: int = 30):
+        self._camera_id = camera_id
+        self._width = width
+        self._height = height
+        self._fps = fps
+        self._cap: Optional[cv2.VideoCapture] = None
+
+    def open(self) -> None:
+        self._cap = cv2.VideoCapture(self._camera_id)
+        if not self._cap.isOpened():
+            raise CameraError(
+                f"Could not open camera {self._camera_id}. "
+                "Make sure a webcam is connected and not in use by another application."
+            )
+        self._cap.set(cv2.CAP_PROP_FRAME_WIDTH, self._width)
+        self._cap.set(cv2.CAP_PROP_FRAME_HEIGHT, self._height)
+        self._cap.set(cv2.CAP_PROP_FPS, self._fps)
+        logger.info(
+            f"Camera {self._camera_id} opened at "
+            f"{self._width}x{self._height} @ {self._fps}fps"
+        )
+
+    def read(self) -> Optional[np.ndarray]:
+        if not self.is_open:
+            return None
+        ret, frame = self._cap.read()
+        if not ret:
+            logger.warning("Failed to read frame from camera.")
+            return None
+        return frame
+
+    def close(self) -> None:
+        if self._cap and self._cap.isOpened():
+            self._cap.release()
+            logger.info(f"Camera {self._camera_id} closed.")
+        self._cap = None
+
+    @property
+    def is_open(self) -> bool:
+        return self._cap is not None and self._cap.isOpened()
+
+    @property
+    def width(self) -> int:
+        if self._cap:
+            return int(self._cap.get(cv2.CAP_PROP_FRAME_WIDTH))
+        return self._width
+
+    @property
+    def height(self) -> int:
+        if self._cap:
+            return int(self._cap.get(cv2.CAP_PROP_FRAME_HEIGHT))
+        return self._height
+
+    @property
+    def fps(self) -> float:
+        if self._cap:
+            return self._cap.get(cv2.CAP_PROP_FPS)
+        return float(self._fps)

darvision/cli.py

@@ -0,0 +1,161 @@
+"""
+DarVision CLI — built with click.
+
+Commands:
+    darvision host [--port] [--public] [--config]
+    darvision connect <address>
+    darvision doctor
+    darvision version
+"""
+
+from __future__ import annotations
+
+import sys
+
+import click
+
+from darvision import __version__
+from darvision.config import DarVisionConfig, setup_logging
+
+
+@click.group()
+@click.option("--log-level", default="INFO", show_default=True,
+              type=click.Choice(["DEBUG", "INFO", "WARNING", "ERROR"], case_sensitive=False),
+              help="Logging verbosity.")
+@click.pass_context
+def cli(ctx: click.Context, log_level: str) -> None:
+    """DarVision — real-time computer vision streaming framework."""
+    ctx.ensure_object(dict)
+    ctx.obj["log_level"] = log_level
+    setup_logging(log_level)
+
+
+# ---------------------------------------------------------------------------
+# darvision host
+# ---------------------------------------------------------------------------
+
+@cli.command()
+@click.option("--port", default=8765, show_default=True, help="WebSocket port to listen on.")
+@click.option("--public", is_flag=True, default=False,
+              help="Expose the host publicly via ngrok (requires pip install darvision[ngrok]).")
+@click.option("--preview", is_flag=True, default=False,
+              help="Open a local window showing what the host camera sees.")
+@click.option("--config", "config_file", default=None, type=click.Path(exists=True),
+              help="Path to a DarVision YAML config file.")
+@click.option("--camera", "camera_id", default=0, show_default=True,
+              help="Camera device index.")
+@click.pass_context
+def host(ctx: click.Context, port: int, public: bool, preview: bool, config_file: str | None, camera_id: int) -> None:
+    """Start the DarVision host and stream your webcam."""
+    from darvision.host.host import Host
+    from pathlib import Path
+
+    cfg = DarVisionConfig()
+    if config_file:
+        cfg = DarVisionConfig.from_yaml(Path(config_file))
+
+    cfg.network.port = port
+    cfg.camera.camera_id = camera_id
+
+    tunnel_provider = None
+    if public:
+        try:
+            from darvision.transport.tunnel.ngrok import NgrokTunnelProvider
+            tunnel_provider = NgrokTunnelProvider()
+        except ImportError:
+            click.secho(
+                "Error: pyngrok is not installed.\n"
+                "Install it with:  pip install darvision[ngrok]",
+                fg="red", err=True,
+            )
+            sys.exit(1)
+
+    h = Host(config=cfg, tunnel_provider=tunnel_provider)
+    h.start(preview=preview)
+
+
+# ---------------------------------------------------------------------------
+# darvision connect
+# ---------------------------------------------------------------------------
+
+@cli.command()
+@click.argument("address")
+@click.pass_context
+def connect(ctx: click.Context, address: str) -> None:
+    """Connect to a DarVision host and display the stream.
+
+    ADDRESS can be:
+      192.168.1.15:8765
+      ws://192.168.1.15:8765
+      wss://xxxx.ngrok-free.app
+    """
+    from darvision.client.client import Client
+    c = Client()
+    c.connect(address)
+
+
+# ---------------------------------------------------------------------------
+# darvision doctor
+# ---------------------------------------------------------------------------
+
+@cli.command()
+def doctor() -> None:
+    """Check system dependencies and camera availability."""
+    import importlib
+
+    ok = True
+
+    def check(label: str, fn):
+        nonlocal ok
+        try:
+            fn()
+            click.secho(f"  ✔  {label}", fg="green")
+        except Exception as exc:
+            click.secho(f"  ✗  {label}: {exc}", fg="red")
+            ok = False
+
+    click.echo("\nDarVision Doctor\n" + "─" * 40)
+
+    check("opencv-python",  lambda: __import__("cv2"))
+    check("numpy",          lambda: __import__("numpy"))
+    check("fastapi",        lambda: __import__("fastapi"))
+    check("uvicorn",        lambda: __import__("uvicorn"))
+    check("websockets",     lambda: __import__("websockets"))
+
+    # Optional
+    try:
+        import pyngrok
+        click.secho("  ✔  pyngrok (optional — ngrok tunneling)", fg="green")
+    except ImportError:
+        click.secho("  ℹ  pyngrok not installed (install with: pip install darvision[ngrok])", fg="yellow")
+
+    # Camera
+    def _camera_check():
+        import cv2
+        cap = cv2.VideoCapture(0)
+        if not cap.isOpened():
+            raise RuntimeError("Camera index 0 not available.")
+        cap.release()
+
+    check("Camera (index 0)", _camera_check)
+
+    click.echo("─" * 40)
+    if ok:
+        click.secho("  All checks passed!", fg="green", bold=True)
+    else:
+        click.secho("  Some checks failed. See above.", fg="red", bold=True)
+    click.echo()
+
+
+# ---------------------------------------------------------------------------
+# darvision version
+# ---------------------------------------------------------------------------
+
+@cli.command()
+def version() -> None:
+    """Show DarVision version."""
+    click.echo(f"DarVision v{__version__}")
+
+
+if __name__ == "__main__":
+    cli()

darvision/client/__init__.py

@@ -0,0 +1,4 @@
+"""DarVision Client package."""
+from darvision.client.client import Client
+
+__all__ = ["Client"]

darvision/client/client.py

@@ -0,0 +1,100 @@
+"""
+Client — the main DarVision client API.
+
+Usage:
+    from darvision import Client
+    client = Client()
+    client.connect("192.168.1.15:8765")
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from typing import Optional, Type
+
+from darvision.rendering.base import Renderer
+from darvision.rendering.opencv import OpenCVRenderer
+from darvision.serialization.decoder import FrameDecoder
+from darvision.transport.base import Transport
+from darvision.transport.websocket import WebSocketTransport
+from darvision.protocol.messages import MessageType
+
+logger = logging.getLogger(__name__)
+
+
+class Client:
+    """
+    DarVision client. Connects to a host and renders the incoming stream.
+    """
+
+    def __init__(
+        self,
+        renderer: Optional[Renderer] = None,
+        transport_class: Type[Transport] = WebSocketTransport,
+    ):
+        self._renderer = renderer or OpenCVRenderer()
+        self._transport = transport_class()
+        self._decoder = FrameDecoder()
+
+    async def _on_bytes(self, data: bytes) -> None:
+        """Handle an incoming binary FrameMessage."""
+        frame = self._decoder.decode(data)
+        if frame is not None:
+            self._renderer.update(frame, [])
+
+    async def _on_text(self, text: str) -> None:
+        """Handle incoming text messages (heartbeats, events — future use)."""
+        import json
+        try:
+            msg = json.loads(text)
+            if msg.get("type") == MessageType.HEARTBEAT:
+                logger.debug("Heartbeat received.")
+            elif msg.get("type") == MessageType.ERROR:
+                logger.warning(f"Host error: {msg.get('payload', {}).get('message')}")
+        except Exception:
+            pass
+
+    async def run(self, address: str) -> None:
+        """Connect to the host and block until the window is closed."""
+        # Normalize address
+        if not address.startswith(("ws://", "wss://")):
+            address = f"ws://{address}"
+
+        # Register callbacks
+        self._transport.on_bytes(self._on_bytes)
+        self._transport.on_text(self._on_text)
+
+        # Connect transport
+        await self._transport.connect(address)
+
+        # Start renderer
+        self._renderer.start()
+
+        print("\n" + "─" * 50)
+        print("  📺  DarVision Client connected")
+        print("─" * 50)
+        print(f"  Host   :  {address}")
+        print("  Press 'q' in the video window to stop.")
+        print("─" * 50 + "\n")
+
+        try:
+            while self._renderer.is_running:
+                await asyncio.sleep(0.05)
+        except asyncio.CancelledError:
+            pass
+        finally:
+            await self._disconnect()
+
+    async def _disconnect(self) -> None:
+        logger.info("Disconnecting DarVision Client...")
+        self._renderer.stop()
+        await self._transport.stop()
+        logger.info("Client disconnected.")
+
+    def connect(self, address: str) -> None:
+        """Convenience wrapper to run the client from non-async code."""
+        try:
+            asyncio.run(self.run(address))
+        except KeyboardInterrupt:
+            pass

darvision/config.py

@@ -0,0 +1,89 @@
+"""
+DarVision configuration.
+
+Supports three layers (highest priority first):
+  1. CLI arguments (passed programmatically)
+  2. Environment variables (DARVISION_*)
+  3. YAML configuration file (darvision.yaml)
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Optional
+
+import yaml
+
+
+@dataclass
+class CameraConfig:
+    camera_id: int = 0
+    width: int = 640
+    height: int = 480
+    fps: int = 30
+    queue_size: int = 4  # bounded queue, drops old frames under load
+
+
+@dataclass
+class NetworkConfig:
+    host: str = "0.0.0.0"
+    port: int = 8765
+    ping_interval: float = 20.0  # seconds between heartbeats
+
+
+@dataclass
+class DarVisionConfig:
+    camera: CameraConfig = field(default_factory=CameraConfig)
+    network: NetworkConfig = field(default_factory=NetworkConfig)
+    log_level: str = "INFO"
+
+    @classmethod
+    def from_yaml(cls, path: Path) -> "DarVisionConfig":
+        """Load config from a YAML file."""
+        with open(path) as f:
+            data = yaml.safe_load(f) or {}
+
+        cfg = cls()
+        if "camera" in data:
+            cam = data["camera"]
+            cfg.camera.camera_id = cam.get("camera_id", cfg.camera.camera_id)
+            cfg.camera.width = cam.get("width", cfg.camera.width)
+            cfg.camera.height = cam.get("height", cfg.camera.height)
+            cfg.camera.fps = cam.get("fps", cfg.camera.fps)
+            cfg.camera.queue_size = cam.get("queue_size", cfg.camera.queue_size)
+
+        if "network" in data:
+            net = data["network"]
+            cfg.network.host = net.get("host", cfg.network.host)
+            cfg.network.port = net.get("port", cfg.network.port)
+            cfg.network.ping_interval = net.get("ping_interval", cfg.network.ping_interval)
+
+        if "log_level" in data:
+            cfg.log_level = data["log_level"]
+
+        return cfg
+
+    @classmethod
+    def from_env(cls) -> "DarVisionConfig":
+        """Override defaults from DARVISION_* environment variables."""
+        cfg = cls()
+        cfg.camera.camera_id = int(os.getenv("DARVISION_CAMERA_ID", cfg.camera.camera_id))
+        cfg.camera.width = int(os.getenv("DARVISION_WIDTH", cfg.camera.width))
+        cfg.camera.height = int(os.getenv("DARVISION_HEIGHT", cfg.camera.height))
+        cfg.camera.fps = int(os.getenv("DARVISION_FPS", cfg.camera.fps))
+        cfg.network.port = int(os.getenv("DARVISION_PORT", cfg.network.port))
+        cfg.log_level = os.getenv("DARVISION_LOG_LEVEL", cfg.log_level)
+        return cfg
+
+
+def setup_logging(level: str = "INFO") -> None:
+    """Configure the root logger for DarVision."""
+    numeric = getattr(logging, level.upper(), logging.INFO)
+    logging.basicConfig(
+        level=numeric,
+        format="%(asctime)s [%(levelname)s] %(name)s: %(message)s",
+        datefmt="%H:%M:%S",
+    )

darvision/exceptions.py

@@ -0,0 +1,38 @@
+"""
+DarVision custom exceptions.
+"""
+
+
+class DarVisionError(Exception):
+    """Base exception for all DarVision errors."""
+    pass
+
+
+class CameraError(DarVisionError):
+    """Raised when a camera cannot be opened or fails during capture."""
+    pass
+
+
+class ConnectionError(DarVisionError):
+    """Raised when a network connection cannot be established or is lost."""
+    pass
+
+
+class SerializationError(DarVisionError):
+    """Raised when a frame or message cannot be encoded or decoded."""
+    pass
+
+
+class PluginError(DarVisionError):
+    """Raised when a plugin fails to initialize, process, or shut down."""
+    pass
+
+
+class TunnelError(DarVisionError):
+    """Raised when a tunnel provider fails to start or connect."""
+    pass
+
+
+class ConfigError(DarVisionError):
+    """Raised when configuration is invalid or missing required values."""
+    pass

darvision/host/__init__.py

@@ -0,0 +1,4 @@
+"""DarVision Host package."""
+from darvision.host.host import Host
+
+__all__ = ["Host"]