50 lines
4.5 KiB
Markdown
50 lines
4.5 KiB
Markdown
# 自动匹配 Cesium 巡航车道中心
|
||
|
||
## Goal
|
||
|
||
Cesium 预览巡航路线应根据实际车道数据自动落在所选行车道中心，消除固定横向偏移带来的位置误差，为后续车辆仿真提供可靠的几何基础。
|
||
|
||
## Background
|
||
|
||
- `scripts/lib/vehicle-route.js:9` 当前使用固定 `LANE_OFFSET_METERS = 1.3`，并在 `makeRoute()` 中对整条平滑后的道路中心线统一向右偏移。
|
||
- 当前区域的 `lane_polygons.geojson` 中 Driving lane 宽度为 `3.0 m`，单车道中心距道路中心线应为 `1.5 m`，现有路线存在约 `0.2 m` 横向误差。
|
||
- `lane_polygons.geojson` 已包含 `direction`、`width`、`index`、`osm_way_ids` 和车道 polygon；这些数据与最终渲染道路来自同一 osm2streets 中间产物。
|
||
- OSM 输入包含 `lanes`、`lanes:forward`、`lanes:backward` 和 `turn:lanes:*`，但不保证包含明确的 `width`，不能单独作为所有区域的精确宽度来源。
|
||
- 历史提交 `30846b6` 引入连续巡航路线时沿用了实验阶段的 `1.3 m` 固定值，没有建立路线与 osm2streets 车道几何之间的契约。
|
||
|
||
## Requirements
|
||
|
||
- R1：路线生成以 osm2streets 实际 Driving lane 数据为主事实源，不再使用全局固定偏移常量。
|
||
- R2：按 OSM way、行驶方向和车道顺序匹配目标车道，并根据各路段的真实宽度及横向位置计算车道中心。
|
||
- R3：不同宽度、不同车道数或不同方向配置的连续道路必须逐路段计算偏移，路口连接处保持连续且不产生横向跳变。
|
||
- R4：多车道路段必须选择一条明确的目标车道；车道选择和转向可行性应使用 `direction`、`index`、`allowed_turns` / `turn:lanes:*` 数据，而不是只看总车道数。
|
||
- R4.1：同向多车道按下一次 maneuver 选择兼容车道；左转/掉头优先最左侧兼容车道，右转优先最右侧兼容车道，直行默认最右侧兼容车道。没有兼容车道时跳过该候选路线并记录诊断。
|
||
- R5：每条输出路线记录所用车道、宽度/偏移来源及诊断信息，使下游能够识别精确匹配、次级推导和跳过的路段。
|
||
- R5.1：缺少、歧义或无法验证车道数据的路段必须跳过并输出结构化诊断；禁止回退到固定偏移或默认车道宽度。
|
||
- R6：保留现有 `routes`、兼容别名 `segments`、闭环路线、信号灯停车和 Cesium 动画消费契约。
|
||
- R7：preview stage manifest 将参与路线计算的车道数据列为输入，使车道几何变化能够正确判定预览产物 stale。
|
||
- R8：不得修改 Blender/GLB 主资产；本任务只修正预览巡航路线及其生成契约。
|
||
|
||
## Acceptance Criteria
|
||
|
||
- [x] AC1：当前南台子湖区域重新生成后，普通直线路段的巡航点位于匹配 Driving lane 的几何中心，允许误差不超过 `0.10 m`。
|
||
- [x] AC2：测试 fixture 覆盖至少 `3.0 m`、`3.5 m` 两种车道宽度，输出中心偏移分别随实际车道数据变化，不存在 `1.3 m` 或 `1.5 m` 全局常量依赖。
|
||
- [x] AC3：测试 fixture 覆盖双向单车道、同向多车道、`oneway=yes` 和正反方向，验证目标车道选择及偏移方向正确。
|
||
- [x] AC4：连续路段车道宽度变化或车道数变化时，路线在衔接区连续；相邻采样点不得出现由偏移切换导致的异常横跳。
|
||
- [x] AC5：路线 JSON 能追溯每段匹配到的 `osm_way_ids`、方向、lane index、width、center offset 和数据来源。
|
||
- [ ] AC6：既有 preview asset tests、路线闭环测试和区域质量门通过，信号灯停车与车辆朝向行为不回归。
|
||
- [x] AC7：preview manifest 记录车道数据文件；该文件改变后诊断能够将 preview 标记为 stale。
|
||
|
||
## Out of Scope
|
||
|
||
- 车辆在运行时动态换道、超车或避障。
|
||
- 交通流量、车辆间距和碰撞模型。
|
||
- 修改 osm2streets 生成的车道 polygon 或 Blender 道路网格。
|
||
- 将实验性预览巡航升级为通用交通仿真引擎。
|
||
|
||
## Technical Constraints
|
||
|
||
- 本任务涉及 OSM、osm2streets GeoJSON、stage manifest 和 Cesium route JSON 的跨层契约，按复杂任务处理；规划收敛后需要 `design.md` 和 `implement.md`。
|
||
- Driving lane polygon 的相对两边中点算法已在 `scripts/lib/turn-lane-arrows.js:265` 验证；巡航路线应复用同一纯几何实现，不维护第二份 polygon 解析逻辑。
|
||
- `preview` 保持可独立执行，但现在明确依赖已有 `lane_polygons.geojson`；车道文件整体缺失或格式无效属于 stage 输入错误，单个路段无法可靠匹配则跳过并写诊断。
|