spec-fog.md 11 KB
主场景区地物距离雾规格
Status: ready-for-agent Label: ready-for-agent
本规格仅固化已收口的视距雾气的实现规格决策。原有 主场景区相机限位与进出状态机规格保持独立；本规格不替代其进出状态、相机限位和归位契约。
Problem Statement
值班人员进入沅陵县城主场景区后，拉近与旋转镜头需要保留清晰的地物，同时避免远方粗底图、影像边缘等瑕疵破坏沉浸感。此前仅靠 Cesium 默认雾无法稳定获得所需效果。维护者观看独立原型后认可 B 方案的地物距离雾颜色和距离，但进入演示中雾形成得太晚，矩形影像边缘先暴露。需要让可实施的雾气契约与进入/返回时的影像交接相容，并如实处理雾不可用、透明地表和性能风险。
Solution
在现有 Cesium 地图上增加一层仅作用于有有效几何深度地物的距离雾。维护者选定的首版默认参数为相机到片元的世界射线距离 18 km 开始起雾、42 km 达到完全遮蔽、雾色 #bdcdd6，中间平滑增浓；无有效深度的天空背景保留原色。该雾可以提前准备、进入主场景区时启用、返回全球时平滑退出；它提供能力、就绪、强度和故障信息供影像过渡使用，但不自行断言整幅画面已被遮住。
全球自转和引导阶段先隐藏精细叠加影像，雾先具备有效保护，再渐显精细层；返回时反向交接。具体交接时机、影像准备度、失败恢复及全程无矩形跳变的判定由低精度 → 高精度过渡的解法持有：维护者已基本验收实际场景原型方向，并要求正式实施将进出雾气变化稍调快、雾色校为不发绿的冷白灰、返回时让镜头高度与雾气模糊同步变化且影像始终受保护。本规格固化雾气端必须提供的能力，不把原型观感认可写成正式运行达标。雾无法运行时保留业务可用性并清楚提示降级。
User Stories
- 作为值班人员，我希望在主场景区观察近处街区时地物依然清晰，以便辨认监测点及周围环境。
- 作为值班人员，我希望远处地物平滑融入雾色，以便旋转镜头时看不到突兀的远景边缘。
- 作为值班人员，我希望雾色和当前认可的 B 原型接近，以便县城画面保持已确认的视觉基调。
- 作为值班人员，我希望天空保留本来的颜色，以便它不会被整片压成夜空或一块平涂背景。
- 作为值班人员，我希望从全球进入主场景区时精细影像不要早于遮挡保护出现，以便飞入过程不露出明显矩形。
- 作为值班人员，我希望返回全球途中精细影像在保护撤除前收起，以便镜头拉远时不再次露出矩形边缘。
- 作为值班人员，我希望在自由全球视角没有自建县城雾，以便继续观看完整地球。
- 作为值班人员，我希望连续进入、取消和返回时仅最新操作生效，以便旧淡出操作不会突然关掉新进入的雾。
- 作为值班人员，我希望在管线视图检查近处管线时保持可读，以便透明深度错位时可减弱或暂关雾。
- 作为值班人员，我希望远处三维设备特效随雾一起减弱，以便特效不会像贴在雾面之上。
- 作为值班人员，我希望面板中的报警文字和状态始终清晰，以便远景雾不会遮住业务判断依据。
- 作为值班人员，我希望雾无法运行时仍能查看可用近景和业务内容，以便单个视觉效果失效不会锁住工作流程。
- 作为维护者，我希望无深度能力、雾创建失败或因可读性禁用时界面如实提示，以便部署异常不被误判成遮缝已生效。
- 作为维护者，我希望复用已创建的雾处理级并在离开地图时释放，以便减少反复创建造成的切换开销。
- 作为维护者，我希望雾支持按条件启停与参数调整，以便完成现场视觉调校及性能降级。
- 作为测试人员，我希望对同一视角和加载状态比较开启与关闭雾的帧耗时，以便判断是否满足性能预算。
- 作为验收人员，我希望单独检查首次启用、进入、返回、归位、浅俯角和管线视图，以便稳定段数字不会掩盖切换卡顿或错误雾化。
- 作为验收人员，我希望明确知道“雾已就绪”和“矩形边缘确已遮住”的区别，以便不把引擎状态误当作视觉验收结果。
Implementation Decisions
- 在单一 Cesium 渲染器中增加一层自建深度后处理雾；采用经维护者选择的 B 方案，不引入第二套 Three.js 渲染器，也不复用原型 C 的天空染色或太阳方向暖色。
- 对有效几何深度重建相机到片元的世界空间射线距离，按 18,000 m 起雾、42,000 m 完全遮蔽的默认端点平滑增浓。
#bdcdd6为早期经维护者确认的原型默认初值；后续实际场景反馈进一步要求白灰偏冷、不得发绿，正式色值须在真实场景调校和复核，不把初值当最终色。距离端点未在这次反馈中变更。 - 无有效几何深度的背景保留原色；无深度值不能被直接当作真实无限距离，也不能当作可靠的天空对象分类。透明地表与特效可能已写颜色但未写自身深度，需把这一点纳入处理与验收。
- 雾支持提前准备、启用、调节当前强度、退出时淡出、取消过期操作、禁用及销毁。对外提供是否支持、是否可执行、当前强度、当前参数、失败/降级原因等可观测信息；不以 ready 或强度单项宣称整幅视野已有保护，也不提供未经验证的全局“已遮缝”布尔承诺。
- 延续主场景区的进出状态：稳定进入时自建雾生效，自由全球及引导态关闭。进入途中的早期高度渐变可以作为雾强度输入，但原型的 60/20 km 高度带已在人工演示中表现为遮挡过晚，不得作为揭示精细影像的充分条件。实际先后交接由过渡规格决定。
- 返回全球时原型采用 0.8 秒淡出，只是历史原型参数，不作为本次最终速度；维护者在真实场景反馈进入和返回雾气变化都应稍快，未指定新时长。返回时相机高度上升与雾气模糊减弱要同步，而精细影像必须在失去保护前安全收起；不允许等影像收完后画面停顿才起飞，也不允许提前露边。反向快速切换必须取消过期操作。优先复用处理级对象，离开地图时销毁；禁用不保证完全无 GPU 开销，也不保证下次启用毫无资源重建。
- 精细影像在全球/引导阶段先隐藏、保留粗底图；进入时先准备雾再渐显精细层，返回反向交接。这是确定的交接方向。具体交接阈值、瓦片准备度、是否继续请求隐藏层瓦片、失败与取消路径由下游过渡决策确定，不在雾气模块里复制一套影像状态机。
- 无深度支持或雾运行失效时整级禁用并如实提示；业务可用优先，继续提供可用近景与业务操作，不让精细影像永久等待不可能成立的雾就绪。降级时不能宣称完全遮缝；无雾时影像怎样交接由过渡规格决定。主场景区配置缺失时沿用既有配置失效口径。
- 管线视图出现透明对象错误雾化时，允许减弱或暂关自建雾，同时保留相机限位并提示。正常情况下不预先关闭所有管线视图雾效。
- 三维设备特效随远景雾衰减，不开穿雾例外；面板业务文字始终清楚。若特效采用后处理，按颜色串联先特效后雾，并让两者独立启停。顺序不保证透明特效有自身深度。
- 同机、同分辨率、同视角和相同加载条件下，正式交付的 P95 帧耗时增幅 ≤15%；首次启用与进出卡顿另行验收。超预算先优化，仍不达标时降低效果质量或关闭并提示；性能合格不能替代视觉和业务可读性验收。
Testing Decisions
- 好的测试检查外部可见行为：近景可读、远景平滑衰减、无深度背景不被整屏染色、能力失败有提示、进出时序有可观测状态，以及管线与设备特效在降级前后仍符合业务目标。不要通过内部变量名或“stage ready=true”代替视觉验收。
- 主要验证 seam：使用现有驾驶舱地图服务层的可观测状态与真实一张图做集成走查；雾处理级提供支持/强度/失败信息，过渡逻辑只消费这些信息。既有相机状态和地图服务读数可作为同一场景下的对照，避免另造第二套地图测试入口。
- 计算型补充 seam：用仓库既有纯逻辑相机和视图模式断言形式，验证 18/42 km 衰减端点、进入/退出强度推进、降级选择及过期操作取消；这些断言只能证明策略计算正确，不能证明 shader 观感或遮缝已达标。
- 人工视觉验收：对照已选 B 的原型检查归位视角、浅俯角多个方向、地平线、影像边缘、半透明管线、设备特效，以及进入与返回全过程。进入演示曾被维护者判为“雾太晚、矩形边缘先出现”；修正后必须重看，不能沿用前次通过结论。完整影像交接的验收归过渡决策与其实施票。
- 性能验收：在固定设备、分辨率、视角、图层及相同加载状态下，记录无原型基线和开启雾后的重复采样 P95 帧耗时，验证增幅不超过 15%，并单独检查首次启用和切换卡顿。原型里的渲染事件间隔仅供参考，不是 GPU 时间，也不能单独证明预算达标；低帧率基线本身也不因相对增幅合格而合格。
- 本仓已有相机契约、视图模式的纯逻辑验证，以及进入引导的走查记录，可复用其模式。依照项目规则，只有维护者明确要求时才运行 build/dev、浏览器走查或截图。
Out of Scope
- 主场景区的坐标、相机 range 上限、软回弹及“返回全球”状态机：已由现有相机规格与 ADR 定义，本规格只消费其结果。
- 精细影像渐显的具体时长、瓦片就绪判定、影像层级替换与边缘羽化算法、正反向交接原型：由「低精度 → 高精度过渡的解法」继续裁决。
- 第二套 Three.js 渲染器、跨引擎深度互通、大气散射 LUT 或通用后处理框架。
- 更改业务面板、报警状态、监测点与设备的数据契约。
- 把开发态可丢弃雾原型直接当成生产代码或性能合格证据。
Further Notes
- 早期独立雾原型选 B，维护者曾反馈颜色和距离基本没有问题，并确认其默认 18/42 km 与
#bdcdd6；当时进入演示明确失败：矩形边缘先于雾的有效遮挡出现。之后的实际场景影像交接原型已获维护者基本认可，同时补充冷白灰不发绿、雾变换稍快、返回高度与雾效同步的要求。前次失败记录不删除；决策通过不等于正式实现已修复该缺陷。 - 若雾不支持或管线视图因透明深度错位被迫降级，应提示远景保护减弱；具体无雾过渡路径由下一决策票明确。本票已按决策范围收口，不能让下游过渡票等待雾的生产性能数据再认领。
- 本规格与主场景区相机限位与进出状态机规格是并列文件；后者未被覆盖或改写。实现票仍依地图约定在 Cockpit 外壳执行索引中建立。