Fratres-X-AI/JamBoy
GitHub: Fratres-X-AI/JamBoy
JamBoy 是一个无人机 GPS 拒止环境下的视觉导航层，通过光流、离线地图地理配准与 EKF 融合实现无 GPS 定位。
Stars: 40 | Forks: 12
# JamBoy
[](https://github.com/Fratres-X-AI/JamBoy/actions/workflows/ci.yml)
[](LICENSE)
适用于消耗型无人机的**抗干扰无 GPS 导航**：光流 + 离线地图地理配准 + EKF 融合 + 气压高度。
JamBoy 是一个**导航层**，而不是瞄准或武器系统。它已通过合成数据在仿真中得到验证；它**尚未通过飞行认证**。
## 功能
在提供向下摄像头、预加载的 GeoTIFF 地图、IMU 角速率和气压计高度的情况下，JamBoy 可以在没有 GPS 的条件下估算本地位置和速度：
1. 带有陀螺仪去旋转的 Lucas–Kanade 光流 → 地面速度
2. ORB（可选 SIFT）+ RANSAC 单应性矩阵与分块地图匹配 → 绝对地理定位
3. 带有气压高度的状态数为 6 的 EKF 融合
4. 状态机：巡航 (Cruise) → 航位推算 (DeadReckon) → 终端 (Terminal) (存根) → 终止 (Abort)
5. MAVLink 输出：`VISION_POSITION_ESTIMATE`（首选）或位置重置降级方案
强烈推荐使用全局快门；卷帘快门在降级模式下也受支持。
## 安装（本地 / CI）
要求 Python 3.10+。
```
python -m venv .venv
# Windows: .venv\Scripts\activate
# Linux/macOS: source .venv/bin/activate
pip install -e ".[dev]"
```
仅 CPU 运行环境（无 CUDA wheels）：
```
pip install -r requirements.txt
pip install -e ".[dev]"
```
可选 GPU 加速（CuPy / PyTorch）：
```
pip install -r requirements-gpu.txt
# 或者：pip install -e ".[gpu,dev]"
```
## 快速仿真门控
```
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
```
一次性辅助脚本（如果可用则使用 CUDA，否则使用 CPU）：
```
bash scripts/run_sim_confident.sh
```
真实感 / 振动数据：
```
python scripts/generate_dummy_data.py --realism
python scripts/run_simulation.py --cpu --profile --realism
```
通过标准和指标：[`docs/REQUIREMENTS.md`](docs/REQUIREMENTS.md)、[`docs/SIM_TEST_GUIDE.md`](docs/SIM_TEST_GUIDE.md)。
## 硬件
| 方案 | 文档 |
|------|-----|
| 直接接入清单（任意 FC + 摄像头） | [`docs/HARDWARE_DEPLOY.md`](docs/HARDWARE_DEPLOY.md) |
| 约 250 美元的 COTS BOM（Pi 5 + IMX296 + Pixhawk） | [`docs/COTS_PROTOTYPE.md`](docs/COTS_PROTOTYPE.md) |
| 硬件权衡研究 | [`docs/HARDWARE_TRADE_STUDY.md`](docs/HARDWARE_TRADE_STUDY.md) |
```
python scripts/calibrate_camera_imu.py --camera 0
# 对于真实的 FC，设置 mavlink.sim_mode: false
python scripts/main_navigator.py --config config/pi5_pixhawk.yaml
```
## 架构
| 模块 | 作用 |
|--------|------|
| [`src/jamboy/optical_flow.py`](src/jamboy/optical_flow.py) | LK 光流 + 陀螺仪去旋转 |
| [`src/jamboy/geo_match.py`](src/jamboy/geo_match.py) | ORB/SIFT + FLANN/RANSAC 地图匹配 |
| [`src/jamboy/ekf.py`](src/jamboy/ekf.py) | 状态数为 6 的 EKF |
| [`src/jamboy/navigator.py`](src/jamboy/navigator.py) | 融合 + 状态机 |
| [`src/jamboy/mavlink_bridge.py`](src/jamboy/mavlink_bridge.py) | 仿真日志或 MAVLink SITL/硬件 |
| [`src/jamboy/gpu_backend.py`](src/jamboy/gpu_backend.py) | 可选 CUDA (CuPy) 匹配器 |
详情：[`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) · 路线图：[`docs/ROADMAP.md`](docs/ROADMAP.md)
## 可选云端 GPU
任何 CUDA 主机均可运行。请使用您自己的云服务商控制面板中的 SSH endpoint —— **请勿提交主机名、端口或密钥**。
```
ssh root@ -p -i ~/.ssh/
cd /workspace/JamBoy # or your clone path
source .venv/bin/activate
export PYTHONPATH=src CUDA_VISIBLE_DEVICES=0
pip install -e ".[gpu,dev]"
bash scripts/run_sim_confident.sh
```
## 免责声明
JamBoy 是用于无 GPS 导航实验的研究 / 仿真软件。它不提供瞄准、交战规则 (ROE) 或动力学自主功能。在飞行前，请在您自己的硬件上进行验证。请在符合适用法律和出口管制规定的情况下使用。
## 贡献
请参阅 [`CONTRIBUTING.md`](CONTRIBUTING.md)。安全报告：[`SECURITY.md`](SECURITY.md)。
## 许可证
[MIT](LICENSE) — 版权所有 (c) 2026 Fratres-X AI
标签：EKF融合, MAVLink, 光流定位, 凭据扫描, 地理配准, 无GPS环境导航, 无人机导航, 视觉里程计, 逆向工具