4.5 KiB
4.5 KiB
自动匹配 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
- AC1:当前南台子湖区域重新生成后,普通直线路段的巡航点位于匹配 Driving lane 的几何中心,允许误差不超过
0.10 m。 - AC2:测试 fixture 覆盖至少
3.0 m、3.5 m两种车道宽度,输出中心偏移分别随实际车道数据变化,不存在1.3 m或1.5 m全局常量依赖。 - AC3:测试 fixture 覆盖双向单车道、同向多车道、
oneway=yes和正反方向,验证目标车道选择及偏移方向正确。 - AC4:连续路段车道宽度变化或车道数变化时,路线在衔接区连续;相邻采样点不得出现由偏移切换导致的异常横跳。
- AC5:路线 JSON 能追溯每段匹配到的
osm_way_ids、方向、lane index、width、center offset 和数据来源。 - AC6:既有 preview asset tests、路线闭环测试和区域质量门通过,信号灯停车与车辆朝向行为不回归。
- 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 输入错误,单个路段无法可靠匹配则跳过并写诊断。