# 规划算法测试

**Repository Path**: Rain-in-June/planning-algorithm-testing

## Basic Information

- **Project Name**: 规划算法测试
- **Description**: 简短介绍，，，，，，，，，，，，，
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: feat/cross-residual-single-pass
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-14
- **Last Updated**: 2026-08-21

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 星座任务规划算法验证平台

本项目用于在**同一场景、同一访问窗口、同一完整实体条带和同一评价口径**下，对多星任务规划算法进行可复现比较。默认场景为 `demo_small`：48 颗卫星、10 个点/面任务、48 小时时域；规划以覆盖优先，同时报告轨道/过境次数、条带重叠、残余碎片与约束违例。

> **使用边界：** 这是一个面向算法验证的工程原型。主路径使用 Skyfield/TLE 子星点和 UTC 时间，但地面条带、侧摆可达和面积仍采用小区域局部平面近似。当前结果适合固定场景下的算法相对比较，不能直接作为真实卫星业务下发计划。

## 1. 已实现的算法与公平口径

| 算法键 | 名称 | 主要作用 |
|---|---|---|
| `priority-pass` | 优先级过境生长 | 快速基线：航向聚类与贴边铺带。 |
| `priority-pass-v2` | 优先级过境生长 V2 | 覆盖优先，支持残余分量收尾与同次过境贯穿。 |
| `portfolio-pass` | 多目标组合规划 | 在覆盖、均衡、经济等小型策略组合中选解。 |
| `topsis-pass` | TOPSIS 多准则规划 | 用 TOPSIS 对同一真实访问窗口的候选排序。 |
| `neighborhood-repair-pass` | 邻域重建规划 | 对低质量任务执行有限邻域重建。 |

所有 `/api/evaluate` 调用会先**只生成一次**真实访问窗口，再把同一 `access_rows` 交给各算法。算法输出均以完整、连续、固定航向的实体条带进行统一覆盖、重叠和残余计算；不以裁剪后的剩余碎片充当成像条带。

## 2. 坐标、时间与约束口径

| 内容 | 当前统一定义 |
|---|---|
| 坐标 | 经度、纬度，十进制度；多边形顺序为 `[longitude, latitude]`。 |
| 时间 | `Scenario.epoch` 为 UTC；任务和计划时间均为相对该历元的秒。 |
| 轨道 | 默认使用场景 TLE 和 Skyfield 子星点；`simple` 仅用于快速近似验证。 |
| 访问采样 | 默认 30 秒；短窗口或业务级精度需在候选边界局部加密。 |
| 成像时段 | 同时夹紧于访问窗口、任务窗口和条带连续成像需求；不足最小时长则候选不可行。 |
| 同星冲突 | 任意两个不同动作须保留至少 2 秒间隔；规划器和评价器共用该口径。 |
| 覆盖率 | `coverage_rate` 是面任务面积覆盖率；点任务请结合 `coverage_completion_rate_99_5` 阅读。 |

### 原始 Cesium 页面采样兼容性

原始三维页面和评测接口将**访问窗口采样上限固定为 30 秒**。此前页面默认 120 秒；短过境在粗采样中可能只命中一个点，进而被表达为零持续时间访问窗口。P0 的时窗夹紧会正确拒绝这类无法证明连续成像可行性的窗口，因此会出现“0 覆盖、0/10 完成”的表象。现在即使旧客户端提交 `step_seconds=120`，后端也会自动使用 30 秒访问采样，并在响应中返回 `access_step_seconds` 说明实际口径。

这项修复不是放松约束，而是避免粗采样把物理可达过境错误离散为空时段。以原始 `priority-pass` 和 `demo_small` 复验时，修复前为 0 条带、0.00% 覆盖；修复后为 113 条完整条带、10/10 任务、96.92% 覆盖，且同星时序违例仍为 0。详见 `reports/cesium_zero_result_fix_20260819.md`。

## 3. 安装与启动

建议 Python 3.11+。安装依赖：

```bash
pip install -r requirements.txt
```

启动服务：

```bash
python app.py
```

浏览器入口：

| 地址 | 用途 |
|---|---|
| `http://127.0.0.1:8771/` | 原始 Cesium 三维核验页面：真实任务边界、轨迹与完整条带。 |
| `http://127.0.0.1:8771/eval/` | 统一算法评测页面：选择算法并查看相同口径的指标。 |
| `http://127.0.0.1:8771/docs` | FastAPI 接口文档。 |

`app.py` 默认关闭热重载；修改 Python 后需重启服务。前端修改后请刷新浏览器缓存。

## 4. API 与算法扩展

评测请求示例：

```bash
curl -X POST http://127.0.0.1:8771/api/evaluate \
  -H 'Content-Type: application/json' \
  -d '{"scenario_id":"demo_small","algorithms":["priority-pass-v2","topsis-pass","neighborhood-repair-pass"]}'
```

`PlanningRequest` 同时保留历史 `candidates` 字段，并增加实际规划使用的 `access_rows`。新算法应优先消费 `access_rows`，不可再次按自己的步长重新生成访问窗口。实现新算法后在 `core/registry.py` 注册，并确保返回 `PlanningResult`；所有覆盖与约束由 `core.metrics.evaluate()` 统一后评估。

## 5. 测试与真实验证

运行核心回归：

```bash
pytest -q tests/test_eval_core.py
```

测试覆盖算法注册、Skyfield 输入、访问窗口、航向聚类、时窗夹紧、2 秒间隔和统一指标。真实运行会生成：

```text
logs/plan-<场景>-<时间>.log
logs/latest.log
```

每份日志记录任务窗口、载荷、选定过境、航向、成像时段、覆盖率和未完成原因。建议在比较算法时固定：场景、TLE、访问提供器、采样步长、视场角、最大侧摆和评分权重。

## 6. 已核验的论文机制与项目取舍

本项目不将论文名称作为“算法先进性”的替代品，而是只迁移与当前**多星、时间窗、连续条带、覆盖优先**问题相容的机制；所有候选仍须先通过 Skyfield/TLE 访问、载荷、最大侧摆、任务时窗与同星 2 秒间隔检查。论文中的完整资源模型、随机算子学习或精确求解器没有被错误宣称为已复现。

| 资料 | 对项目有价值的机制 | 当前对应实现 | 不直接照搬的部分 |
|---|---|---|---|
| 多准则多星成像获取排程 [1] | 将覆盖/质量/优先级等偏好作为**已可行候选之间**的排序问题，并将物理约束留在独立可行性层。 | `topsis-pass` 对覆盖增益、完成度、轨道复用和侧摆代价排序。 | 文中的 BLP、内存、云量、立体成像和完整运营偏好尚未建模。 |
| 多敏捷卫星 ALNS [2] | 通过删除—插入—重排邻域改善已有可行计划，适合处理残余覆盖缺口。 | `neighborhood-repair-pass` 比较有限、确定性的修复预算，再按覆盖优先质量口径选解。 | 未实现自适应算子权重、随机多轮学习；因此称为“有限邻域重建”，不是完整 ALNS 复现。 |
| 主动成像敏捷卫星多条带调度 [3] | 明确了连续面任务的多条带选择、条带分组与多目标权衡不能简化为独立点任务。 | V2 及其派生规划器保留固定航向、连续实体条带和残余分量收尾。 | 该文的主动成像载荷模型和双目标记忆算法不适用于当前 SAR/光学简化载荷，未直接移植。 |
| EOS-Bench 开放评测基准 [4] | 用场景难度、完成率、运行时间等多维指标避免只看单一覆盖率。 | 本项目固定共同访问输入，并报告覆盖、轨迹、重叠、残余、时序违例和耗时。 | 尚未接入该基准的场景和数据；当前 `demo_small` 只适合作为项目内回归基准。 |

上述资料说明，下一项最有价值的工程投入不是再增加一个名称不同的启发式，而是补齐**姿态机动时间、能源/存储/下传、光学照明与云量**，并将当前统一评测扩展到多场景压力测试。这样才能区分“几何覆盖更高”和“可下发运营计划更好”。

## 7. 当前模型边界与后续优先级

本项目已修正任务时窗、2 秒间隔、统一访问输入和完整条带口径。下一阶段若面向业务级应用，应依次引入：椭球/局部 AEQD 投影、访问边界插值、真实侧摆地面交点、姿态机动、光学照明与云、SAR 模式、能源/存储/下传约束。详细审查见 `reports/algorithm_rigor_audit.md`。

## 8. 目录结构

```text
app.py                    FastAPI 入口与统一评测调度
config.json               场景、访问提供器、视场与采样配置
algorithms/               五个可替换规划器
core/                     访问窗口、几何、约束、指标、场景与日志
data/scenarios/           场景 JSON 与 TLE
web/                      原始 Cesium 三维核验页面
web_eval/                 统一指标审计页面
tests/                    pytest 回归测试
reports/                  实验、截图和严谨性审查报告
handoff/                  供后续 AI/开发者继续工作的项目交接说明
```

## 参考资料

[1]: https://www.mdpi.com/1424-8220/20/5/1242 "Multi Criteria Decision Making for the Multi-Satellite Image Acquisition Scheduling Problem"

[2]: https://www.sciencedirect.com/science/article/pii/S0305054818301722 "An improved adaptive large neighborhood search algorithm for multiple agile satellites scheduling"

[3]: https://link.springer.com/article/10.1007/s00521-023-08286-6 "Multi-strip observation scheduling problem for active-imaging agile earth observation satellites"

[4]: https://arxiv.org/abs/2604.25782 "EOS-Bench: A Comprehensive Benchmark for Earth Observation Satellite Scheduling"