threejs-sky-atmosphere-and-haze

天空、大气与雾霾

所有分支都围绕一种大气模型、一条场景线性 HDR 路径和一个最终输出负责人构建。

流程

1. 选择传输方式

选择满足所需可观测结果且成本最低的分支：

需求	分支	有效声明
区域性创作天空、距离雾霾或高度雾霾	SkyMesh 加 TSL 雾效／雾霾	在有界局部坐标系中呈现创作效果
实时行星天空和大气透视	紧凑型 Hillaire 风格 LUT	在测得的误差范围内近似高阶传输
固定大气，且需要更严格的光谱／角度精度	Bruneton 风格散射阶数或离线求解	通过与选定参考结果对比证明精度

对会变化的摄像机和太阳使用紧凑型分支。当高阶分支的重新生成成本和高维产品适合实际工作负载时，再使用该分支。将离线积分器作为参考依据，而非用于可见像素的运行时计算。

完成标准： 实现明确指定一个分支、其支持的空间范围、其物理效果或创作效果的声明，以及用于验收的误差或视觉标准。

2. 确立统一模型

为半径、位置和积分步长声明一个长度单位；以其倒数单位存储消光／散射系数，使 beta * ds 无量纲。定义天体或局部坐标系、原点策略、高度模型、太阳方向约定、光谱／工作基底，以及太阳光源采用法向辐照度还是有限圆盘辐亮度。

初始化 WebGPURenderer，等待 renderer.init() 完成，并在分配计算／存储产品前确认使用原生 WebGPU 后端。传输数据使用 NoColorSpace，并在主机输出阶段之前保持辐亮度处于场景线性空间。

关于具有物理量纲的消光、LUT 辐射度学、映射方程、相位约定、产品依赖关系、导入的 LUT／产品兼容性，或单一单位等价性测试，请阅读 references/atmosphere-transport.md。

完成标准： 所有生产者和消费者都使用相同的坐标系、长度换算、太阳约定和辐射度学基底；对于具有物理量纲的消光，CPU 和 GPU 对同一测试样例得出的光学深度也必须一致。

3. 按依赖顺序构建产品

编写的本地分支直接从共享模型采样天空和距离／高度雾。只有在雾作为独立的深度感知后处理时，才需要宿主深度。对于紧凑 LUT 分支，不要仅仅因为选择了该分支就分配产品。根据消费者需求准入产品：

产品	仅在以下情况下分配
透射率	已准入的天空、大气透视或光照路径直接或通过依赖产品需要它
多重散射	已准入的天空、大气透视或光照闭合包含高阶响应
辐照度	已准入的漫射光照消费者对其进行采样
天空视图	已准入的可见天空消费者对其进行采样
大气透视 RGB 内散射和 RGB 光学深度	已准入的深度感知合成消费者对这对负载进行采样

仅含天空或仅含光照的分支没有大气透视分配或视图依赖项。

为每个产品指定独立的依赖键和上次更新原因。大气剖面和天体变化会使基础产品失效。相机相对于天体的姿态、投影、视口和深度映射变化会使大气透视产品失效。相机偏航、投影抖动和纯浮动原点平移不会使未变化的天体坐标系 LUT 失效。

使用 StorageTexture 和 textureStore() 写入 2D 产品；使用 Storage3DTexture 和 storageTexture3D() 写入 3D 产品。明确设置格式、过滤器、环绕方式和 mip 所有权。将 renderer.computeAsync() 视为提交操作，而非 GPU 完成操作；通过实际的完成机制同步读取回传、复用和回收。

完成条件： 每个被采样的产品都列出其所有物理和视图依赖项；没有消费者会观察到较新的依赖项搭配较旧的依赖产品；已被取代的工作无法发布到当前模型纪元之上；每个未准入的产品都没有任何分配或依赖状态；基础 LUT 在仅相机变化时保持有效。

4. 合成所选分支

对于场景内编写的分支，将 SkyMesh 和 TSL 雾／霾附加到宿主场景，并使其输出保持场景线性。

对于独立的深度感知雾／霾或 LUT 大气透视分支，复用宿主场景颜色和深度。将当前透视、反向、对数或正交深度约定重建为度量线段，然后与大气求交，并在首次进入不透明天体时停止。不要在不透明区间之后继续进行远侧壳层积分。通过显式覆盖信息或声明的清空深度编码对天空进行分类。

对于该分支中的可见表面，严格应用：

C_out = C_scene * T_segment + S_segment

对于天空像素，采样天空辐射以及经过校准的太阳／月球圆盘。将直接光照、天空漫射光照、云影、不透明可见性和相机线段传输作为独立因子处理。由 renderOutput() 或 RenderPipeline.outputColorTransform 负责呈现。

对于行星天体、外部相机、椭球体、非透视深度或壳层／后处理交接，请阅读 references/body-depth-and-composition.md。

完成条件： 每个已准入的场景内分支都恰好到达一次宿主输出路径；每个启用的深度感知分支都能在声明的容差范围内重建已知位置，保持天空／表面覆盖稳定，并在零大气控制下返回 C_scene；色调映射／输出转换只运行一次。

5. 暴露经过准入的光照交接信息

当其他系统使用大气推导的光照时，只暴露其所需的量：

• 采样时间、模型修订版本、物理坐标系／原点、支持范围、滤波方式、采样时长和误差；
• 采样点到太阳的单位方向和太阳圆盘角半径；
• 经校准的太阳量、单位和基准；
• 已经经过大气衰减的直射阳光，或未衰减的光源及大气透射率；
• 定向天空辐射亮度、依赖法线的天空辐照度，以及各自是否包含直射太阳圆盘；
• 摄像机线段的 RGB 透射率和 RGB 空气散射。

云层增加仅由云层产生的光学深度；几何体增加可见性；水增加自身路径消光。使用方选择一种大气直射光形式，并对每个因子只应用一次。

**完成标准：**仅用于视觉效果的分支不包含未使用的光照接口；每个准入的光照使用方都能识别量、单位、坐标系、采样时长和已包含的衰减，并且其因子追踪证明大气、云层、几何体、水和空中传输各自最多只出现一次。

6. 验证所选分支

验证分支实际使用的机制：

• LUT 正向／逆向映射在纹素中心、边界、地平线分界和方位角接缝处的表现；
• 相位归一化和前向瓣符号；
• 光学深度、辐射亮度和能量与更高精度参考值的收敛情况；
• 天体交点和所有已启用的深度编码；
• 参数、摄像机、抖动、视口和原点变化时的产品失效情况；
• 固定视角下线性 HDR 天空、地平线、夜景、地表雾霾和外部摄像机诊断；
• 创建、调整大小／切换层级、完成和释放时的所有权。

**完成标准：**每个已启用分支都通过数值和视觉门槛；每项诊断都标明所显示产品的修订版本；重复调整大小／切换层级后，每个保留的产品都只剩一个有效代次。

失败特征

症状	检查项
光晕出现在太阳的反方向	相位方向符号
雾霾随世界缩放而变化	长度／系数换算
地平线接缝或天体边缘跳变	LUT 接缝、天体区间或所有权转换
地形被重复变暗	直射光或空中传输因子的所有权
摄像机抖动导致基础 LUT 重新生成	依赖键范围过宽
离轴雾霾距离过短	将归一化深度误认为射线距离

路由边界

此技能负责分子／气溶胶天空传输、大气推导的太阳／天空光照，以及摄像机线段空中透视。天气塑形的云密度和仅由云层产生的阴影，请使用 $threejs-volumetric-clouds；共享场景信号和最终输出所有权，请使用 $threejs-image-pipeline；测光／色调映射，请使用 $threejs-exposure-color-grading；地形／天体细节，请使用 $threejs-procedural-planets。