threejs-water-optics

水体光学

选择拥有所需可观测量的最简单水体表示，然后从该状态推导位移、导数、泡沫、湿润度和光传输。

1. 确定水体模型

所需可观测量	表示方式	以下情况无效
静态水面和水深地形；只关心水底可见度、折射、衰减或焦散	静态水深地形加光传输	需要水面运动、水线运动或交互
沿海岸传播的预设波峰；不声称存在流动或交互	海岸 SDF 加预设岸线相位	需要衍射、溯岸、整体流动或湿干拓扑变化
少量相干波；没有局部扰动	参数化位移水面	宽带随机波或密集交互占主导
有界弱波和局部冲量	线性高度场	需要破碎、整体流动或湿干拓扑
固定水深地形；相位平均的浅化／折射	波作用量或射线	需要衍射、干涉或瞬时波峰奇偶性
固定水深地形；线性衍射／干涉	频域缓坡方程	需要破碎、溯岸、移动床面或实时宽频谱
永久被水覆盖的可变水深区域中的长波	线性水位／流量浅水模型	需要湿干前沿、涌浪或有限振幅流动
溯岸、涌浪、深度平均尾流或湿润拓扑变化	保正的非线性浅水模型	需要色散效应或三维破碎
翻卷、卷入空气、喷流或三维涡旋	外部自由表面／粒子／VOF 求解器	单值模型或深度平均模型已足够
刚体运动影响水体，且水体反作用影响刚体	选定的水体求解器加双向耦合分支	单向视觉跟随或预设尾流已足够

将宽广均匀的风浪或涌浪交由 $threejs-spectral-ocean 处理。仅法线细节属于显示优化，不是另一种物理归属。

记录域大小、可解析的最短波长、交互半径、水深地形变化、相位／误差容差、守恒需求、湿干拓扑和持续运行预算。仅在明确的空间或频率交接处进行混合。

完成条件： 每个所需可观测量都恰好有一个有效归属；每种被排除的表示方式都有明确的有效性理由或实测成本理由。

2. 固定坐标、状态和归属

在稳定的物理坐标系中使用米和秒：

z_b(x,z) = upward-positive bed elevation
eta(x,z,t) = free-surface elevation
h = max(eta-z_b,0)

phi > 0 on land
phi = 0 at the authored still-water coast
phi < 0 in water.

声明水位基准、重力、床面和海岸距离数据源、有效掩码、单元覆盖范围、重建／滤波方式、边界标签、障碍物表示、流速和时钟。水平海岸距离不等于垂直水深。

为水体状态、几何、离岸强迫、泡沫、裸露床面湿润度、焦散、不透明折射输入和最终输出分别指定唯一归属。每个边界都必须是周期、反射／壁面、吸收／辐射、指定入流或出流，并注明对应的数学处理方式。

对于每个水体边界，声明生产者、使用者和状态归属；单位和稳定的物理坐标系／原点；采样时刻或应用间隔、时钟、频率和采样相位；支撑范围／滤波方式；有效性、陈旧度和误差；以及状态／资源版本。区分变化率与按时间间隔积分的质量、动量或能量。明确强迫、反作用、几何和呈现的归属及其顺序。时钟不连续、坐标重定位、表示方式或归属变更、版本不兼容时，都必须重置所有依赖的求解器、泡沫、湿润度、查询和时间状态。如果多系统路由仍需选择归属，则调用 $threejs-choose-skills。

完成条件： 在每次采样时，床面、海岸、基准、状态、边界和输出的归属保持一致；SDF 零等值线和 z_b=eta_0 等值线符合其声明的准入条件。

3. 实现所选分支

只读取链接标题范围：从标题开始，到下一个同级或更高级标题之前为止。

所选表示	所需参考范围
静态水面和水深地形	领域数据与不变量，然后是下方所需的光学范围
参数化位移水面	精确参数化波浪和物理水平查询
有界线性高度场	有界线性高度场
预设的沿岸相位	领域数据与不变量和预设岸线相位
波作用量或射线	领域数据与不变量和深度感知的波作用量与射线
频域缓坡方程	领域数据与不变量和缓坡方程分支
固定湿区线性浅水方程	领域数据与不变量和固定湿区线性浅水方程
非线性干湿浅水方程	领域数据与不变量和含干湿前沿的非线性浅水方程
外部求解器	使用下方的外部求解器适配器契约；仅加载其已发布通道所需的共享范围

仅在选定相应关注点时，才加载以下附加范围：

• 离岸耦合：离岸/近岸交接；
• 破碎、泡沫或裸露床面的湿润状态：破碎、泡沫和湿润状态；
• 稀疏执行：稀疏活动瓦片；
• 实时网格 CPU 查询：实时 GPU 网格查询契约；
• 接收面焦散：接收面空间焦散；
• 折射或界面反射：折射和菲涅耳效应；
• 吸收或散射：比尔-朗伯传输；
• 沿岸光学/生命周期集成：光学与呈现；
• GPU 实现：WebGPU 实现。

完成水面/光学分支后，应用水面验收中对应的条目。完成沿岸分支后，应用沿岸验收中对应的条目。

参数化水面

计算一个位移映射、两个解析切线、水平方向雅可比矩阵，以及朝上的叉积法线。物理水平查询需要对水平映射求逆。

**分支完成条件：**参数采样和物理水平采样的语义明确无歧义；解析切线/法线与有限差分结果一致；最小雅可比值为正，或每个折叠处都被判定为无效；并且查询残差达到其门槛。

有界线性高度场

使用乒乓式高度／垂直速度状态、固定 dt、带量纲的源、明确的边界条件，并按以下顺序调度：

event gather -> propagate -> swap -> derivatives -> optical auxiliaries.

接受此分支前，先导入有界高度场色散比较器，并使用选定的 c、dt、dx、dz、kx 和 kz 调用 boundedHeightfieldDispersion()。该函数会预测无阻尼（gamma=0）离散相位；请将此预测与测得的解析模态相位进行比较。针对实际阻尼和源配置，单独测量振幅误差。该辅助函数会拒绝非有限运算，排除临界 CFL 相等的情况，并区分全局稳定性与所表示模态的准入；直流相位字段会明确标记为不可用，而不会伪造数值测量结果。

分支完成条件： CFL 裕度为正；解析模态相位与振幅误差、边界反射、平均值漂移、精度误差和有限值扫描均通过；重叠事件不存在写入竞争；且所有使用方都从新状态读取导数。

预设的沿岸相位

根据离岸距离或收敛的程函旅行时间场推导波峰相位。相位分支只负责波峰位置和预设的冲洗掩码；不宣称具有流动、动量或波浪能量。

分支完成条件： 波峰方向、间距和速度；沿岸连续性；程函残差和不可达分类；中轴线的海岸归属；以及片元覆盖范围过滤均通过各自的门槛，并明确说明不涉及流动或能量。

波作用量或射线

按频率和方向输运带量纲的波作用量／能量。明确区分流速、固有频率、群速度、求积、耗散，以及单独负责的显示相位。射线不宣称能够模拟绕射／干涉。

分支完成条件： 表示频带内的色散／群速度、相位环绕或旋度、波作用量／能量平衡、浅化／折射、正则化和交接反射均通过。

缓坡方程

针对固定且缓慢变化的水深地形，在辐射／开放边界条件下求解复数相位／振幅。若源和水深地形保持不变，优先选择离线求解。

分支完成条件： 制造解或独立参考解的收敛性、相位／振幅插值、边界反射和存储场失效处理均通过。

固定湿区线性浅水模型

使用兼容的离散散度／梯度，或单一有限体积通量，演化表面扰动和深度积分流量。

分支完成条件： 强制状态始终处于湿区；质量和声明的能量行为守恒；色散和边界反射通过；并且不声称支持湿／干交替、涌浪或有限振幅。

非线性湿／干浅水模型

使用单一规范面通量、平衡保持水深地形、保正更新、干单元除法策略、固定稳定步长和守恒的源项核算，演化守恒形式的水深和动量。

分支完成条件： 水深保持非负，且不进行未报告的钳制；静止湖保持静止；质量与边界／源通量守恒；干单元保持有限值；岸线／爬高以及网格／时间步长／干阈值收敛性通过；边界反射符合门槛。

外部求解器

通过明确的适配器读取其带版本的表面、速度、湿／干、材质和呈现状态。明确显示外部进程／队列／栅栏延迟和不可用通道。

分支完成条件： 已验证单位、坐标系、时钟、插值、误差、生命周期、故障／恢复和呈现归属；渲染帧不会同步读回数据，也不会推进外部求解。

双向物体耦合

当物体运动必须影响水体，且水体必须对物体作出响应时，使用一个声明的耦合时间间隔：

predict body state
-> sample the same previous/current water bracket at body support points
-> scatter displacement or impulse to water conservatively
-> advance water once
-> reduce reaction force, torque, and interface work over the same support
-> correct body state
-> commit both versions together.

使用同一个物理帧、单位、采样标识和支撑域／雅可比约定。 不要将碰撞和渲染 LOD 纳入耦合支撑域。将该方法归类为显式松耦合或有界残差迭代；强附加质量效应或刚性反馈需要采用迭代分支或外部耦合求解器。

分支完成条件： 等大反向的冲量、力、力矩、排水体积和界面功残差均满足各自的门限；静止浮力、平移／旋转、网格／时间步长及迭代控制均收敛；且没有渲染帧回读会推进或校正任一状态。

4. 一次性推导共享表面状态

几何、切线、法线、速度、阴影、泡沫源、折射和时间相关使用方均由选定的状态版本推导。每个位置的几何交接都只有一个所有者。相干表面使用匹配的振幅并对混合进行求导，包括权重梯度；功率窗口仅适用于独立或正交频带。

根据最主要的已表示成因构建一个泡沫源：模拟的破碎损失、经校准的冲击／熵损失、精确压缩／雅可比，或指定的波峰到达。存储输运覆盖率或守恒面密度，并使用与之匹配的方程。一个耗散分区驱动一段历史记录。

恰好由一个暴露床面接收器负责湿润状态。淹没或声明的指定冲刷遮罩会将其设为湿润；干燥过程须正确反映时间步长。湿润状态会改变接收器的材质响应，而不是水体质量或岸线几何。

对于稀疏的沿海执行，应根据因果影响和交互支撑域来激活，而不只是依据可见性。在整瓦片模板运算前填充光环和边界；在相邻单元间保持面通量一致；并核算激活／停用状态及误差。

完成条件： 一个状态版本能够解释所有几何和光学使用方；泡沫和湿润状态各自只有一个所有者和重置规则；稀疏非活动区域有明确模型；且显示出的接缝不存在两个表面。

5. 评估光学传输

不透明物体颜色／深度输入不包含水体。在使用折射光线的路径长度前，先重建并验证该光线。判定入射侧，接近全内反射时使用精确的介电质 Fresnel 公式，并以米为单位应用 Beer-Lambert 消光：

sigma_t = sigma_a + sigma_s
T = exp(-sigma_t pathLengthMeters)

L_water = F L_reflection
        + (1-F) etaRadiance [T L_background + (1-T) omega_0 L_source].

对 etaRadiance，明确采用参考中的物理辐亮度或简化辐亮度约定；Fresnel 功率透射不会自动完成跨折射率的辐亮度转换。对于正消光，使用实际消光量对散射进行归一化，并单独处理零消光分支；以稳定方式计算较短的光学厚度。焦散应替代相应的直接光传输，而不是重复叠加。泡沫应替代此响应中有界的一部分。除非另一个明确核算的瓣替代它，否则太阳高光由镜面 BRDF 负责。

焦散在接收器空间中沉积表面单元功率，并使用接收器映射的行列式。跟踪无效／全内反射采样、沉积前后的功率、正则化、滤波和钳制。

完成条件： Fresnel／全内反射分类、折射光线残差、路径长度有效性、吸收／散射分区、焦散接收器位置、能量账本，以及最终视图／无光学效果视图／无焦散视图／无泡沫视图均通过验证。

6. 集成 GPU 状态和生命周期

调用 await renderer.init()，并要求 renderer.backend.isWebGPUBackend === true，然后再分配或提交 计算／存储工作。模拟纹理使用 NoColorSpace、显式精度、不生成 mip，并对模板使用整数加载。每个整网格生产者／消费者依赖都跨越一次分派边界。 renderer.computeAsync(...) 可安全用于初始化；其解析的 Promise 不能作为 GPU 已完成工作的证据。模拟分辨率应独立于视口分辨率。

先执行一个排除水体的不透明通道，再明确计算消耗该通道结果的水体／合成工作预算。写入某个附件时，不要同时采样该附件，也不要将多次遍历标记为一个通道。使用一个 RenderPipeline 和一个输出变换。如果 renderOutput(...) 负责转换，则设置 pipeline.outputColorTransform = false。替换 pipeline.outputNode 后，设置 pipeline.needsUpdate = true。 呈现过程使用具有稳定标识的不可变上一帧／当前帧状态。 调整大小、表示方式、更新频率、活动域、基准面、原点、数据源和求解器版本发生变化时，应迁移兼容状态，或重置所有相关历史记录。由资源的所有者负责释放资源和监听器。

完成标准： 记录已初始化的原生 WebGPU 后端／能力、分派与分配清单、峰值存活字节数、精度对比、预热后的持续运行耗时，以及重建／释放后的平台期；不得残留对帧关键路径的回读或重复输出变换。

7. 最终证伪

检查适用的诊断信息，而不只是最终图像：

• 水深地形、海岸距离／帧、湿润掩码、边界、状态、导数；
• 相位／作用量／流量、能量或质量残差、反射、干湿状态；
• 泡沫源／输运／反应和湿润度历史；
• 折射有效性、Fresnel／TIR、消光项、焦散沉积；
• 固定相机和多个时间点下的最终效果及禁用效果画面。

完成标准： 每项选定分支标准均通过，每种未涵盖的现象均不在声明范围内，每个交接都只有一个生产者和一个消费者，每项资源都有明确的所有者和重置／释放规则，并且一个因果水体状态只经过一次最终输出变换。