skycam

Camera-agnostic fisheye image projection library for ground-based sky observation

---

✨ Features

Feature	Description
⚡ Numba JIT	~100x faster projection via compiled bilinear interpolation
💾 Coordinate Cache	Sub-100ms init after first calibration load
🛫 Aircraft Projection	Vectorized lon/lat/alt → pixel conversion with Shapely support
🏛️ Hexagonal Architecture	Clean separation of domain, adapters, and config
✅ Pydantic v2	Validated settings with environment variable support
🔬 Scientific Accuracy	WGS84 geodesic calculations via GeographicLib

🚀 Installation

uv add skycam

Or with pip:

pip install skycam

📖 Quick Start

from pathlib import Path

from skycam.adapters import JP2CalibrationLoader, load_jp2
from skycam.domain.models import ProjectionSettings
from skycam.domain.projection import ProjectionService

# Load calibration and create projector
loader = JP2CalibrationLoader(Path("calibration"))
calibration = loader.load("visible")
projector = ProjectionService(
    calibration=calibration,
    settings=ProjectionSettings(),
)

# Project fisheye → regular grid
projected = projector.project(load_jp2(Path("input.jp2")))

🏗️ Architecture

flowchart LR
    subgraph Adapters["Adapters"]
        CAL[JP2 Calibration]
        IMG[Image I/O]
    end
    
    subgraph Domain["Domain"]
        PROJ[ProjectionService]
        INTERP[Numba Bilinear]
    end
    
    subgraph Config["Config"]
        SETTINGS[SkycamSettings]
    end
    
    CAL --> PROJ
    IMG --> PROJ
    SETTINGS --> PROJ
    PROJ --> INTERP

Loading

⚙️ Configuration

Environment variables (prefix: SKYCAM_):

Variable	Default	Description
SKYCAM_CALIBRATION_DIR	calibration	JP2 calibration files directory
SKYCAM_CATEGORY	visible	Camera category (visible, infrarouge)
SKYCAM_DATA_DIR	data	Input/output data directory

🛠️ Development

git clone https://github.com/eurocontrol-asu/skycam.git
cd skycam
make install  # uv sync --all-groups
make check    # lint + audit + test

📚 Documentation

eurocontrol-asu.github.io/skycam

• 🚀 Tutorial — Project your first image in 5 minutes
• 🛠️ Guides — How-to recipes for common tasks
• 🧠 Concepts — Architecture and algorithm deep-dive
• 📚 Reference — Complete API documentation

🤝 Contributing

See CONTRIBUTING.md for guidelines.

📄 License

EUPL-1.2 — See LICENSE for details.