# 主场景区限位、视距与过渡（决策地图）

Status: resolved
Labels: wayfinder:map

本 effort 只产出决策，不实现功能（Q6=(a)）。实现票在本图收口后接进 `.scratch/cockpit-shell-panel-layout/issues/` 的 30 之后。

## Destination

把「进入沅陵县城主场景区之后」的三件事锁成可实现契约，让 agent 不必再发明语义：

1. **区域限位**：弹簧臂/相机按主场景区限位 —— 中心点约束 + 相机离地高度上下限 + range 上限（Q2=C）。
2. **视距雾气**：机制、曲线、门控与配色（Q4 / Q9 / Q11）。
3. **低精度 → 高精度过渡**：从全球飞到县城视角的全过程不出现肉眼可辨的方形色块跳变（Q5=B）。

目的地达成的判据：每张子票都有明确答案，且答案之间的数值互相自洽 —— 限位数值、雾气门控、过渡曲线引用**同一个**主场景区定义与**同一套**视距基准。

## Notes

- Domain：城市生命线 Web 驾驶舱 `/cockpit`。词汇以 `CONTEXT.md` 为准。
- 每次会话先读：`CONTEXT.md`、`docs/adr/0001`–`0008`、`src/modules/cockpit/domain/camera.js`、`domain/viewPresets.js`、`domain/viewModes.js`、`domain/mapLayers.js`、`services/cesiumEngine.js`、`services/cameraControl.js`、`public/cockpit/config.json`，以及 `.scratch/cockpit-shell-panel-layout/issues/21`、`30`。
- 引擎现状：`cesium@1.145.0`；唯一 `import 'cesium'` 在 `services/cesiumEngine.js`；目前**零**自定义 shader、**零** post-process 级、**零** fog/atmosphere 配置 —— 但 `scene.fog` 默认 `enabled: true`（默认密度在县城尺度几乎不可见）。
- 本图只产出决策，不实现功能。实现票去向：`.scratch/cockpit-shell-panel-layout/issues/` 30 之后（Q6=(a)+(c)）。
- 技能：grilling、domain-modeling、research、prototype。
- 决策票状态词是 wayfinder 自己的 `open`/`claimed`/`resolved`，**不套 triage 五标签**。
- 新增 ADR 0009 记录本图结论（Q7）。
- 验收＝可计算部分走纯逻辑断言，观感部分由维护者目视走查（Q8）。按 `AGENTS.md`，改代码后不自动跑 build/dev。
- 阻塞关系以 `Blocked by:` 字段行为准。

### 已锁定的甲方裁定（2026-09-18 澄清）

1. 主场景区用**新配置字段**显式给出（Q1=C）。本部署取甲方框定的沅陵县城范围 `[110.328749941417, 28.3917230659234, 110.465779226663, 28.4913038992907]`（`[west, south, east, north]`，13.4 km × 11.0 km，147.6 km²）。**01 已 resolved（2026-09-18）**：兜底改为「部署期准备候选值＋运行时未配置则关闭」；候选值公式＝影像 bounds ∩ DEM `valid_bounds` 的 B，围绕 `map.home` 经纬度（＝进入系统默认位置＝归位位置）每边折半。原“内置兜底自动得到 B 收紧 50%”不再适用，详见 [01 的 Answer](issues/01-primary-area-config-contract.md#answer)。
2. 限位为**三量同夹**：中心点、相机离地高度、range（Q2=C）。最低仍须能贴近看设备。**02 已 resolved（2026-09-18）：数值口径见 Decisions so far。**
3. 进区后**锁定**，另给显式「返回全球」（Q3=C）。
4. 雾气定位＝**氛围 + 遮缝**，不承担"限制用户能看多远"的职责 —— 限距由第 1 条的限位承担（Q4）。
5. 过渡判据＝从全球飞到县城视角的**全过程**无肉眼可辨的方形色块跳变；允许边界羽化/渐变遮罩这类**碰 shader** 的手段（Q5=B）。
6. 本图只产决策；实现票接在 `cockpit-shell-panel-layout` 的 30 之后（Q6=(a)+(c)）。
7. 新增 ADR 0009（Q7）。
8. 验收＝纯逻辑断言 + 维护者目视走查（Q8）。
9. 雾气走**自建 Cesium depth 后处理级（路线 B）**，参考 Three.js 增强管线的 shader 写法以提升观感、降低开销（Q9=B）。
10. 早期「垂直视野 ≤15%」口径已由[限位与既有相机契约的合成 + 进出状态机](issues/03-camera-contract-composition-and-entry-state.md)取代：最远视野跟随 home.range（本部署 12,000 m）。不得再用 1,651 m 地面跨度直接约束雾的相机到片元距离。
11. 早期要求包含侧视远景及天空处理；维护者经原型已选[视距雾气的实现规格](issues/07-fog-implementation-spec.md#answer)的 B，仅处理有效几何深度地物，不采用天空背景染色。无雾降级时业务可用优先并提示，不承诺完全遮缝。
12. 另立调研票评估「把 Cesium 深度喂给 Three」的可行性（Q12=B）。

### 早期计算记录（历史，不作为现行限位或雾参数）

- 主场景区：E-W 13,413 m，N-S 11,008 m；**N-S 的 15% = 1,651 m**（这是"最高视野下地面垂直覆盖"的预算）。
- Cesium 默认 `fov = 60°` 是**水平**视场角，`fovy = 2·atan(tan(30°)/aspect)`。同一预算下 range 上限随画布宽高比浮动约 2×：aspect 1:1 → 1,430 m；4:3 → 1,906 m；16:9 → 2,542 m（均为正俯视口径）。**02 已定：运行时按真实 `fovY` 反算 `range_max = 1651 / (2·tan(fovY/2))`，不写死基准。**
- 现有 home 预设 `pitch −55, range 12000` 的垂直覆盖约 **9.5 km ≈ 主场景区 N-S 的 86%**，是上述预算的 **5.8×** —— 与票 30 的"12 km 是县域级"直接冲突，03 必须处置。

## 任务清单

- [x] [01: 主场景区的配置契约](issues/01-primary-area-config-contract.md) — 已 resolved：字段形状 / 坐标口径 / 兜底来源。
- [x] [02: 相机限位的数值契约](issues/02-camera-limit-numeric-contract.md) — 已 resolved：h_min / h_max / range 上限与 15% 预算的换算口径。
- [x] [03: 限位与既有相机契约的合成 + 进出状态机](issues/03-camera-contract-composition-and-entry-state.md) — 已 resolved：限位锚点 / 进出状态机 / 管线合成 / 软回弹 / ADR 0009。
- [x] [04: 调研 —— Cesium 地面视距雾的机制与限制](issues/04-research-cesium-ground-fog-mechanisms.md) — 已 resolved，产物 `research/cesium-ground-fog-mechanisms.md`。
- [x] [05: 调研 —— 精细矩形跳变的成因与可用手段](issues/05-research-overlay-rectangle-pop-mechanisms.md) — 已 resolved，产物 `research/overlay-rectangle-pop-mechanisms.md`。
- [x] [06: 调研 —— Three.js 雾 shader 可复用面与 Cesium 深度互通可行性](issues/06-research-three-fog-shader-reuse.md) — 已 resolved，产物 `research/three-fog-shader-reuse.md`；甲方裁定废止深度互通备选。
- [x] [07: 视距雾气的实现规格](issues/07-fog-implementation-spec.md) — 已 resolved：采用 B 仅地物距离雾，默认 18/42 km、#bdcdd6；进入时序要求“精细影像先隐藏 → 雾先保护 → 影像渐显”，失败时业务可用优先；实施验收保留 ≤15% P95 与透明管线/进出交接检查。
- [x] [08: 低精度 → 高精度过渡的解法](issues/08-coarse-to-fine-transition-solution.md) — 已 resolved：维护者在实际场景基本验收 B 过渡方向，三项后续要求已落 Answer；生产零跳变与性能仍待实施验收。

## Decisions so far

<!-- 本地图已关闭的决策票索引；一条决策只活在票里。 -->

- [01: 主场景区的配置契约](issues/01-primary-area-config-contract.md) — `map.primaryArea` 只设 `bounds`（`[W,S,E,N]` 度，与 `map.overlays[].bounds` 同口径）；配置必须写归一化顺序，运行时校验 `west<east`/`south<north`、**不自动翻转**，非法即记配置问题并进入关闭路径；兜底＝**部署期**计算候选值（B ＝ 影像 bounds ∩ DEM `valid_bounds`，围绕 `map.home` 经纬度＝进入系统默认位置＝归位位置、每边折半）写入同一字段，**运行时未配置就关闭**依赖主场景区的限位与自建雾并如实报浮标 —— 原「内置兜底自动得 B 收紧 50%」作废；契约不含数据越界校验（配置即权威）；本部署显式值仍为甲方框定县城范围。
- [02: 相机限位的数值契约](issues/02-camera-limit-numeric-contract.md) — 中心点 ∈ `primaryArea.bounds`（01）；`range ∈ [120, range_max]`，`range_max = 1651 / (2·tan(fovY/2))`（取运行时真实 fovY，随画布 aspect 变：1:1→1,430 / 4:3→1,906 / 16:9→2,542 m）；**正俯视只提供参考基准值，pitch 不参与收紧**；「垂直覆盖」度量＝屏幕竖直方向地面跨度，**只在正俯视定义**；**02 只保正俯视 ≤15%，侧视露出的范围外由 07 雾遮盖**；相机离地高度 `h = range·sin|pitch|`（h_max 被 range_max 隐式罩住）；**防入地＝地形感知下限**（`h ≥ 正下方地形 + 10 m`，margin 暂定可微调，不足时夹 range，机制落 03）。**⚠️ 其 `range_max` 锚点（2,542 m）已被 03 取代（12,000 m = home.range），限位数值以 03 / ADR 0009 为准。**
- [03: 限位与既有相机契约的合成 + 进出状态机](issues/03-camera-contract-composition-and-entry-state.md) — `range_max = home.range = 12,000 m`（**最远视野 = 归位默认视角**，取代 02 的 2,542 m 与"15% 垂直覆盖预算"）；显式模式锁（进入系统/归位进、返回全球出，判定与位置无关）；全球态闲置 5 秒回初始态（自转 + 闪烁「点击进入系统」），不重置模式/筛选；区内管线视图 `range ∈ [400, min(6000, range_max)] = [400, 6,000]`（因 range_max>6000，与现状一致，冲突消解）；边界软回弹（`target.pivot` 越出 ≤ 框短边 5% ≈ 550 m，松手阻尼弹回）；返回全球目标＝初始全景（h0/p−60/r 2×10⁷）；`areaState: 'locked'|'global'` 进 `filterStore`（与 `viewMode` 同层），`mapService` 转移、`cameraControl` 换 limits（`setRangeLimits` 与 `setPitchLimits` 对称）、`CockpitShell` 管 5 秒计时与引导页显隐；`intro.enabled=false` 按 global 启动；防入地继承 02（三处夹取交集）；ADR 0009 已建、ADR 0008 已补指向。
- [04: 调研 —— Cesium 地面视距雾的机制与限制](issues/04-research-cesium-ground-fog-mechanisms.md) — 内置 `scene.fog` 的密度由**相机高度**反算并乘 `1−|dot(朝向,上)|`，正俯视归零、半径随高度漂移，当不了稳定视距限制；引擎无现成雾/霾后处理级，但 `PostProcessStage` 默认就带 `depthTexture`，自建 depth 雾可行（`Context.depthTexture` 运行时存在但不在随包 d.ts 里；**06 更正：它实为布尔能力标志，非纹理对象**）。
- [05: 调研 —— 精细矩形跳变的成因与可用手段](issues/05-research-overlay-rectangle-pop-mechanisms.md) — 矩形边缘是 GLSL `step()` **硬切**，引擎零羽化、零交叉淡入；配置里的 `minimumLevel: 0` 是**空操作**（等于 provider 默认），精细层并非"近了才加载"；跳变有**两类**（首批瓦片整体出现 + 地形 LOD 牵着影像逐级换挡）；`ImageryLayer.alpha` 只是整层 uniform，`ImageryLayer.rectangle` 只读。
- [06: 调研 —— Three.js 雾 shader 可复用面与 Cesium 深度互通可行性](issues/06-research-three-fog-shader-reuse.md) — Three haze 的**密度曲线与闭式光深积分是纯数学**，可搬进 Cesium `PostProcessStage`；太阳耦合全在颜色项，常量雾色即可剥离；默认密度的距离估算仅适用于原研究的特定高度假设；旧 1,651 m 预算及倍率推导已失效，现行参数以雾规格最终决策为准。「Cesium 深度喂给 Three」评级**极难**（`Context.depthTexture` 仅是布尔能力标志、纹理不可跨 context、社区实测俯视遮挡错乱、且须推翻 ADR 0004）—— 甲方裁定**废止**该备选，雾锁定单一 Cesium 渲染器走路线 B。

- [视距雾气的实现规格](issues/07-fog-implementation-spec.md#answer) — 采用 B 地物距离雾及原型默认参数；提前准备/撤除与影像交接协调，异常时业务可用优先；按决策范围收口，进入遮挡失败记录、透明场景检查和 ≤15% P95 验收仍归下游原型/实施，不表示运行验收通过。
- [08: 低精度 → 高精度过渡的解法](issues/08-coarse-to-fine-transition-solution.md#answer) — 维护者在实际场景基本验收「藏精细影像 → 雾保护 → 渐显影像；返回反向交接」。正式实施需让进出雾变换稍快、采用冷白灰且不发绿、返回时镜头高度与雾气模糊同步变化并保持影像保护。原型决策通过不等于生产全程零跳变或 ≤15% P95 已达标。

## Not yet specified

<!-- 天空/地平线已成为「视距雾气的实现规格」中的明确问题并有独立原型，不再重复列为迷雾；按 aspect 推导上限的旧问题已被 home.range 决策取代。 -->
- 正式交付若矩形内部 LOD 换级仍肉眼可辨，再评估局部过渡、shader 羽化或**预烘焙中精度影像层**（成本高）作为兜底；本次原型观感通过不代表已经修复内部换级。
- 运维自检「限位与雾气已生效」的操作口径 —— **已由实现票 [36: 主场景区配置](../cockpit-shell-panel-layout/issues/36-primary-area-config.md) 落地**：`docs/cockpit-deployment.md` 新增 2.9 节（顺序是硬要求 + 三种浮标读数对照表 + 矩形怎么定），
  运行期读数为引擎浮标 `主场景区：…` 与宿主 `data-map-primary-area`(`-reason`)。雾气本身的可视验收仍归实施票 38。

## Out of scope

- 让 Three.js 接管 Cesium 场景或承担全场大气 —— ADR 0004 / ADR 0007 已锁死；Q12 已由 06 调研后**裁定废止**（极难，且须推翻 ADR 0004），不再作为备选。
- 重做地球自转与进入引导动画本身（票 30 已交付并验收；本图只处理进入途中的过渡瑕疵）。
- 甲方本地 3D Tiles 模型数据补齐（属 `.scratch/cockpit-shell-panel-layout/issues/21`）。
- 后处理通用框架化或其它后处理效果（本图只做视距雾一个）。
- 改 `mode` / `panelId` / 面板语义与布局。

## 进度：100%

8/8 张决策票已 resolved。[08：低精度 → 高精度过渡的解法](issues/08-coarse-to-fine-transition-solution.md#answer)经维护者在真实场景基本验收，方案方向和三条后续实施约束已落票；雾气决策另见[07](issues/07-fog-implementation-spec.md#answer)。本图按「锁定可实现的决策」范围收口，不代表原型直接入生产、全程零方块跳变或性能合格。

下一步：按地图约定在 `.scratch/cockpit-shell-panel-layout/issues/` 的 30 之后承接正式实现。进出雾速度稍快、冷白灰不发绿、返回高度与雾气同步且边缘持续受保护均须在真实画面复核；另检查目标瓦片、内部 LOD 换级、异常降级、管线可读性及 P95 帧耗时增幅 ≤15%。雾气与相机规格继续分别以[spec-fog.md](spec-fog.md)和[spec.md](spec.md)为准，新的实施约束以 08 的最终 Answer 优先。

历史 1,651 m 预算及旧雾密度推导不可作现行验收标准；本轮依 AGENTS.md 未运行 build/dev 或浏览器调试。