threejs-spectral-ocean

谱海洋

从方向方差密度构建一个有量纲的随机海面，形成一片位移并着色的表面。谱域是一个水平齐次的周期区域，每个级联都有一个平均水深和一条色散关系。

1. 确定表示方式

根据所需的可观测效果选择，而不是根据期望的外观选择：

可观测效果	适用方案
少量手动设定的模式或精确且廉价的 CPU 查询	$threejs-water-optics 中的参数化波
有界扰动或明确的边界	$threejs-water-optics 中的有界高度场
大范围随机方向海面	本频谱 FFT 技能
随水深变化的折射、衍射、破碎、爬高或干湿前沿	$threejs-water-optics 中的海岸分支；本技能可提供外海强迫
翻卷、夹带空气、射流或三维涡旋	外部自由表面求解器

仅当可见波长范围包含足够多的独立模式，导致直接求和成本更高或明显重复时，才选择 FFT 级联。记录可见波长区间、覆盖范围、可容忍的相位／坡度误差、周期重复距离、交互需求以及实测存储预算。

满足条件： 每种所需的水体可观测效果都由一行方案负责，并且每个被排除的方案都有明确的适用性或成本理由。

2. 固定频谱约定

使用米、秒、弧度每米和弧度每秒。声明：

• 稳定的水平物理坐标系和水面基准；
• 每个级联的区域长度、分辨率、Delta k、表示的径向频带和保护带；
• 逆变换符号、归一化方式和中心索引修正；
• 重力、平均水深、表面张力、密度和均匀水流；
• 频谱族、方向约定、种子和级联功率窗口；
• 一个系数／状态时钟和一个渲染表面所有者。

所需的逆变换约定为

f[j] = sum_n F[n] exp(+i 2 pi n dot j / N).

如果实现使用归一化逆变换，应调整系数初始化的缩放，而不是事后调试海面。水流是独立的水体速度和多普勒项；大气风绝不会变成水流。

对于风海，记录采样风向量、参考高度、平均时间窗口和覆盖范围、风廓线／阻力校准、稳定性处理、风区长度、强迫持续时间或波龄、方向扩展模型以及表示的源项。连续调整统计状态；阵风可以影响飞沫，但不得重新播种成熟波浪。

固定此约定时，只加载以下参考章节： 环境强迫、 波矢与变换约定和色散与有量纲频谱。

满足条件： 每个系数和时钟的单位都明确无歧义，初始化与验证使用相同的变换约定，并且重放同一强迫快照时会得到相同的系数和相位。

3. 构建确定性级联

加载有关级联功率与确定性系数、位移与导数谱、打包与逆 FFT以及变换门限的参考章节。在实现或更改变换时，导入或改编 FFT 约定预言机。将每个 makeConventionFixtures() 频谱输入实现，然后在加载生产频谱之前，将其 measureTransform() 指标和调用方声明的门限传给 applyTolerances()。CPU 预言机有意仅支持 8/16/32 尺寸，会拒绝无效数值输入和空门限，并会明确报告零参考相对误差；它不是生产 FFT 的尺寸上限。

对于方向角频率方差密度 S_omega，

P(k_x,k_z) = S_omega(omega(k),theta) |d omega/dk| / |k|,
[P] = m^4.

在离散系数方差中纳入 Delta k_x Delta k_z。功率窗口须满足：在所表示的频带上，sum_c w_c(k)=1；平滑重叠时，振幅使用 sqrt(w_c)。在同一物理网格上，根据 (seed,cascade,signed_mode_x,signed_mode_z) 生成正态随机数，使中心存储偏移不会改变保留模式的随机种子。

演化内禀厄米共轭对，并将均匀流速平流作为共同相位应用。其两个驻定图表频率不同；查询速度界限时须保留两者。在波矢空间中构造导数，然后变换高度、水平位移、斜率和位移导数。任何除法之前，都要显式处理 DC 和自共轭 Nyquist 单元。

**完成条件：**方向归一化、功率窗口总和、目标方差与实际方差、系数确定性、厄米共轭误差、DC、两个轴向频点、一个斜向频点、一对共轭频点、所有 Nyquist 奇偶情况、CPU-DFT 误差、Parseval 误差以及 IFFT 后虚部泄漏均通过已声明的门限。

4. 组合成一个精确的表面

仅加载精确位移几何，以获取复合切线、速度、采样和折叠规则。

在非线性几何计算之前，先对所有级联场求和。对于

P(q) = (q_x + chi D_x, h, q_z + chi D_z),

根据求和后的位移推导两个参数切线，并将法线设为 normalize(cross(P_qz,P_qx))。计算完整的水平雅可比，包括混合导数。这些紧凑公式假定 chi 为常数；若其随空间或时间变化，还须加入乘积法则项。行列式非正表示发生折叠，而不是法线贴图缺陷。生产防护带会移除 Nyquist 线；仅针对奇偶性的变换测试夹具无法证明几何已充分解析。

使用单模态判据选择 chi 的符号：在正向逆变换约定下，h=a cos(kx) 且波峰陡峭度为正时，必须产生 X=x-chi a sin(kx)，使波峰受压缩。

几何必须能够解析所表示的位移频带。滤除或省略其足迹无法解析的模式，并报告这些模式对高度/斜率的贡献。每个显示位置只能由一个网格/材质负责。

**完成条件：**单模态传播与位移符号正确；解析切线和法线与有限差分相符；测量合并方差和最小雅可比；统计折叠次数；并且位置、法线、速度、泡沫和时间消费者读取同一不可变状态对。

5. 仅添加有表示依据的可选状态

Foam

启用泡沫时，仅加载 泡沫部分。

从级联压缩、雅可比演变、曲率或经校准的破碎代理中构建一个源，然后演变一个有界历史。声明拉格朗日参数存储、欧拉平流或守恒密度输运。源、输运、反应、扩散和显示覆盖范围应可分别检查。

查询

启用 CPU 查询时，仅加载 CPU 查询部分。

在 CPU 上保留确定性的系数子集。将参数坐标采样与物理水平采样分别公开。对于有峰值的欧拉查询，需反演 X(q)=x；省略模态的误差界、反演残差、数值误差和 GPU 探测偏差应分别记录。帧路径不得执行同步映射回读。

光学

安装并可用 $threejs-water-optics 时，调用它以获取 Fresnel、折射、Beer-Lambert 和接收端焦散规则。这样，表面几何、导数、泡沫和光学便共享同一成因和最终输出变换。若该工具不可用，则报告 missing optics owner，并将光学排除在此实现及其声明范围之外。

**完成条件：**每个启用的选项都有明确的负责人、有效区间、支持范围／滤波器、重置规则和故障诊断；禁用的选项不分配状态，也不作任何声明。

6. 仅在需要时耦合海岸

当海洋连接到水深变化或湿／干状态负责人时，仅加载 海岸供体部分及其相位解析、相位平均和所有权子部分。 在任一求解器运行前，记录频谱供体、海岸使用方，以及强迫、反应、渲染表面和泡沫负责人；SI 单位；共同的物理帧／原点和水位基准；时钟、采样时刻或传输区间、采样频率和采样相位；频带支持范围、滤波器和求积；有效性、过时状态和误差；以及供体／接收端状态和资源版本。将大气强迫、平均流、波浪传输和海岸反应保留为独立信号。时钟不连续、重定位、版本不兼容、表示形式变化或所有权变化后，重置依赖的边界、查询、泡沫、几何和时间状态。如果组合路径仍未为每个可观测量明确一个负责人，则调用 $threejs-choose-skills。

二选一：

• **相位解析：**传输具有共同相位、固有频率、采样时刻、频带标识和误差的高程与深度积分流量。仅指定入射特征；保留海岸的出射特征。
• **相位平均：**传输有量纲的波作用量／能量、固有频率、群速度、流速、方向、求积和频带标识。接收端单独负责局部显示相位。

FFT 仍是离岸供体。仅通过在其材质中采样水深，不会使其获得折射、衍射、破碎、爬高或湿／干状态的所有权。相干的供体／接收端副本使用同一个空间渲染负责人；功率窗口仅适用于独立或正交频带。

**完成条件：**明确指定生产者、使用方、区间、采样相位、单位、支持范围、滤波器、有效性、过时状态、误差、状态版本、反射范围以及渲染／泡沫所有权；单模态法向和斜向测试能够闭合相位、高程、流量或作用量、透射功率和反射。

7. 集成并验证 GPU 路径

仅加载 WebGPU 和性能， 了解后端、资源、调度、精度和生命周期要求。

先初始化 WebGPURenderer，再检查其后端或限制。使用 NoColorSpace 和显式精度的 StorageTexture 数据。全局生产者/消费者依赖会跨越调度边界。根据变换正确性、已初始化的设备限制、占用率、流量和持续运行计时，选择经过验证的全局乒乓 FFT——Stockham 自动排序或显式位反转基 2——或驻留工作组的行变换。

通过一个 RenderPipeline 和一个输出变换进行渲染。当渲染租约使用系数、已解析地图、泡沫、查询和呈现世代时，保持它们不可变；调整大小、种子、频谱、节奏、表示方式或原点发生变化时，要迁移兼容状态，或重置所有依赖历史记录。

针对每个命名目标，报告实际分配、峰值存活字节数、调度次数、精度对比、持续运行时的稳定计时，以及固定相机下的最终/无泡沫/无细节/无后处理截图。

**完成条件：**记录已初始化的后端和选定的限制；通过上述所有数值门槛；不存在关键帧回读；生命周期重建/释放后分配量达到稳定水平；最终图像只有一个表面所有者和一个输出变换。