JamBoy

Jam-proof GPS-denied navigation for attritable drones: optical flow + offline map geo-registration + EKF fusion + barometric altitude.

Name note: JamBoy = GPS jam + Game Boy-era pun. Nothing to do with historical golf caddie slang.

JamBoy is a navigation layer, not a targeting or weapons system. It is sim-validated on synthetic data; it is not flight-certified.

What it does

Given a downward camera, pre-loaded GeoTIFF maps, IMU rates, and barometer altitude, JamBoy estimates local position and velocity without GPS:

1. Lucas–Kanade optical flow with gyro de-rotation → ground velocity
2. ORB (optional SIFT) + RANSAC homography against tiled maps → absolute geo fix
3. 6-state EKF fusion with baro altitude
4. State machine: Cruise → DeadReckon → Terminal (stub) → Abort
5. MAVLink out: VISION_POSITION_ESTIMATE (preferred) or reposition fallback

Global shutter is strongly preferred; rolling shutter is supported with fallback modes.

Install (local / CI)

Requires Python 3.10+.

python -m venv .venv
# Windows: .venv\Scripts\activate
# Linux/macOS: source .venv/bin/activate
pip install -e ".[dev]"

CPU runtime only (no CUDA wheels):

pip install -r requirements.txt
pip install -e ".[dev]"

Optional GPU acceleration (CuPy / PyTorch):

pip install -r requirements-gpu.txt
# or: pip install -e ".[gpu,dev]"

Quick sim gate

export PYTHONPATH=src   # Windows: $env:PYTHONPATH = "src"
python scripts/generate_dummy_data.py
pytest -q
python scripts/run_simulation.py --cpu --profile
python scripts/validate_sim.py

One-shot helper (CUDA if available, else CPU):

bash scripts/run_sim_confident.sh

Realism / vibration data:

python scripts/generate_dummy_data.py --realism
python scripts/run_simulation.py --cpu --profile --realism

Pass criteria and metrics: docs/REQUIREMENTS.md, docs/SIM_TEST_GUIDE.md.

Hardware