Metadata-Version: 2.4
Name: traj-scorer
Version: 0.1.0
Summary: Token-level PDMS trajectory scoring utilities for HelloData.
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: numpy>=1.24
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: build>=1.2.0; extra == "dev"

# Trajectory Scorer

HelloData 轨迹的 token-level PDMS 评分与可视化工具。

当前流程一次评估一个 token/window。clip 只是帧数据来源；评测入口消费一个
`ScoringContext` window 和一条候选轨迹。

## 安装

在仓库根目录执行：

```bash
pip install .
```

开发模式安装（代码改动可立即生效）：

```bash
pip install -e ".[dev]"
```

## 仓库结构

- `traj_scorer/`：评分库代码。
- `traj_scorer/pdms.py`：`evaluate_context()` 和 PDMS 聚合逻辑。
- `traj_scorer/metric_*.py`：各个子指标实现。
- `traj_scorer/hellodata.py`：HelloDataImporter 适配层。
- `scripts/repair_token_level_clip_3_155.py`：当前 token-level 验证与 BEV 可视化入口。
- `tests/`：聚焦指标行为的回归测试。
- `docs/pdms_metrics.md`：子指标定义与聚合公式说明。

## 主 Token-Level 命令

示例：clip `3_155`、token `230`、随机 50 条轨迹库候选。

```bash
python scripts/repair_token_level_clip_3_155.py \
  --output-dir output/token_level_repair_3_155_token230 \
  --library-count 50 \
  --token-starts 230 \
  --token-length 40 \
  --random-seed 155
```

输出包括：

- `expert_sanity.json/csv/md`
- `library_perturbation_comparison.json/csv`
- `bev_by_metric/*.png`

BEV 图会在 token 起点自车坐标系下绘制 OCC freespace、LD、当前/未来 ego、
当前/未来 agents，以及按指标分数着色的候选轨迹。

## 指标

详细说明见 `docs/pdms_metrics.md`。

已实现：

- `NC`：无责碰撞。
- `DAC`：可行驶区域合规，优先使用 OCC freespace。
- `EP`：自车进度。
- `TTC`：短时投影碰撞检查。
- `LK`：基于当前自车中心线的车道保持。
- `HC`：历史舒适性。

暂时默认通过：

- `DDC`：行驶方向合规。
- `TLC`：红绿灯合规。

## 验证

运行：

```bash
python -m py_compile scripts/repair_token_level_clip_3_155.py traj_scorer/*.py
python -m pytest -q
```

当前测试覆盖 EP 进度排序和 LK 中心线行为，包括“相邻中心线不应掩盖偏离当前车道”的情况。

## 打包发布给他人

先构建 wheel/sdist：

```bash
python -m build
```

构建产物会在 `dist/` 下，别人可直接安装：

```bash
pip install dist/traj_scorer-0.1.0-py3-none-any.whl
```
