segcam

Real-time semantic segmentation from any webcam.

A real-time instance segmentation application that processes video from any OpenCV-compatible camera, using YOLOv8-seg for segmentation with contour visualization.

Features

• Real-time YOLOv8-seg instance segmentation
• Works with any OpenCV-compatible camera
• Hardware-accelerated inference (MPS on Apple Silicon, CUDA on NVIDIA GPUs, CPU fallback)
• TOML-based configuration
• Interactive keyboard controls (toggle overlays)
• Structured JSON logging

Requirements

Software

• Python 3.13+
• uv package manager
• Any webcam recognized by OpenCV

Platform Support

Platform	Inference Acceleration	Camera Support
macOS (Apple Silicon)	MPS (Metal)	Any webcam, iPhone via Continuity Camera
Linux	CUDA (NVIDIA) or CPU	Any webcam
Windows	CUDA (NVIDIA) or CPU	Any webcam

Note: Camera enumeration with device names is currently macOS-only. On other platforms, cameras are selected by index.

Tested on: macOS only (MacBook Pro M1). Linux and Windows support is theoretical and untested.

Installation

git clone https://github.com/cverrier/segcam.git
cd segcam
uv sync

Usage

Run

uv run segcam
uv run segcam --config path/to/config.toml
uv run segcam --backend pytorch

Keyboard Controls

Key	Action
Q	Quit
O	Toggle segmentation overlay
D	Toggle debug overlay (FPS, inference time)

Configuration

Create a config.toml file to customize settings:

[capture]
resolution = [1280, 720]  # Width, height in pixels
fps = 30                   # Target frame rate

[model]
variant = "yolov8m-seg"       # YOLOv8 model variant (n/s/m/l/x)
confidence_threshold = 0.5    # Detection confidence threshold (0-1)
backend = "pytorch"           # Inference backend: "pytorch" or "tinygrad", "tinygrad" not implemented yet

[model.classes]
# Empty list = all 80 COCO classes; specify to filter
# Example: include = ["person", "car", "dog"]
include = []

[visualization]
line_thickness = 3       # Contour line thickness in pixels
overlay_enabled = true   # Show segmentation overlay on startup
debug_overlay = true     # Show debug info (FPS, inference time) on startup

[logging]
level = "INFO"           # Log level: DEBUG, INFO, WARNING, ERROR
file = "segcam.log"      # Log file path

Architecture

Module	Purpose
config.py	TOML configuration loading with validation
logging.py	Structured logging with JSON output
capture.py	Video capture with camera enumeration and selection
inference/base.py	Abstract inference backend interface
inference/pytorch_backend.py	PyTorch/ultralytics backend with MPS acceleration
visualization.py	Contour rendering and debug overlay
app.py	Main application loop
__main__.py	CLI entry point

Development

# Install dependencies (including dev)
uv sync

# Run tests
uv run pytest

# Run tests (quiet mode, concise failures)
uv run pytest -q --tb=short