threejs-water-optics

水の光学

要求される観測量を所有する最も複雑でない水の表現を選び、その状態から変位、微分量、泡、濡れ具合、光輸送を導出します。

1. 水モデルを絞り込む

必要な観測量	表現	無効となる条件
静的な水面と水深地形。必要なのは底面の可視性、屈折、減衰、またはコースティクスのみ	静的な水深地形と光輸送	水面の動き、水際の移動、または相互作用が必要
海岸に沿って進む規定の波頭。流れや相互作用は扱わない	海岸 SDF と規定の海岸線位相	回折、遡上、全体的な流れ、または変化する乾湿トポロジーが重要
少数のコヒーレントな波。局所的な擾乱はない	パラメトリックな変位水面	広帯域の確率的な波成分や密な相互作用が支配的
有界な弱い波と局所的な衝撃	線形高さ場	砕波、全体的な流れ、または乾湿トポロジーが重要
固定された水深地形。位相平均された浅水変形・屈折	波作用またはレイ	回折、干渉、または瞬時の波頭の偶奇性が重要
固定された水深地形。線形の回折・干渉	周波数領域の緩勾配方程式	砕波、遡上、移動床、または実時間の広帯域スペクトルが必要
常時水で覆われた変動水深上の長波	線形の標高・流量による浅水モデル	乾湿フロント、砕波段波、または有限振幅の流れが重要
遡上、砕波段波、水深平均した後流、または変化する乾湿トポロジー	正値性を保つ非線形浅水モデル	分散性のある砕波、または三次元の砕波が必要
転覆、巻き込まれた空気、噴流、または三次元渦	外部の自由水面／粒子／VOF ソルバー	単価値モデルまたは水深平均モデルで十分
物体の動きが水に影響し、水からの反力が物体に影響する	選択した水ソルバーと双方向連成ブランチ	一方向の視覚的追従、または規定の後流で十分

広帯域の一様な風波またはうねりは $threejs-spectral-ocean に振り分けます。法線のみのディテールは表示上の最適化であり、別の物理モデルではありません。

領域サイズ、解像可能な最小波長、相互作用半径、水深地形の変化、位相／誤差許容値、保存要件、乾湿トポロジー、継続的な計算予算を記録します。ハイブリッド化は、空間または周波数の明示的な受け渡し点を設ける場合に限ります。

完了条件： 必要なすべての観測量に、妥当な所有者がそれぞれ 1 つだけ割り当てられ、却下した各表現について、妥当性または実測コストに基づく理由が示されていること。

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.

水面基準面、重力、底面と海岸距離の情報源、有効マスク、セルのフットプリント、再構成／フィルター、境界ラベル、障害物の表現、流れ、クロックを宣言します。水平面での海岸距離は、垂直方向の水深ではありません。

水の状態、形状、沖合からの外力、泡、露出した底面の濡れ具合、コースティクス、不透明な屈折入力、最終出力には、それぞれ所有者を 1 つだけ割り当てます。すべての境界は、周期境界、反射／壁境界、吸収／放射境界、規定流入、または名前付きの数学的処理を伴う流出のいずれかにします。

各水境界について、生成元、利用先、状態の所有者、単位と安定した物理座標系／原点、サンプル時刻または適用間隔、クロック、更新頻度、サンプル位相、支持範囲／フィルター、有効性、古さ、誤差、状態／リソースのバージョンを宣言します。流量と、区間で積分した質量、運動量、エネルギーを区別します。外力、反力、形状、表示の所有権と適用順序を明示します。クロックの不連続、原点の再設定、表現または所有者の変更、互換性のないバージョンが発生した場合は、依存するすべてのソルバー、泡、濡れ具合、クエリ、時間的状態をリセットします。複数システムにまたがる経路で、なお所有権の選択が必要な場合は $threejs-choose-skills を呼び出します。

完了条件： すべてのサンプルで、底面、海岸、基準面、状態、境界、クロック、出力の所有権が一致し、SDF のゼロ等高線と z_b=eta_0 の等高線が、宣言されたゲート条件を満たしていること。

3. 選択した分岐を実装する

リンク先の見出し範囲のみを読み込みます。見出しから始め、同じレベルまたはそれより上の次の見出しの直前で止めます。

選択した表現	必須の参照範囲
静的な水面と海底地形	領域データと不変条件、続いて以下の必須の光学範囲
パラメトリック変位水面	厳密なパラメトリック波および物理座標の水平クエリ
有界線形ハイトフィールド	有界線形ハイトフィールド
規定の海岸追従位相	領域データと不変条件および規定の海岸線位相
波作用または光線	領域データと不変条件および水深を考慮した波作用と光線
周波数領域の緩勾配法	領域データと不変条件および緩勾配分岐
固定湿潤域の線形浅水モデル	領域データと不変条件および固定湿潤域の線形浅水モデル
非線形の湿潤・乾燥浅水モデル	領域データと不変条件および湿潤・乾燥境界を伴う非線形浅水モデル
外部ソルバー	以下の外部ソルバーアダプター契約を使用します。公開チャネルに必要な共有範囲のみを読み込みます

名前を挙げた項目を選択した場合に限り、次の追加範囲を読み込みます。

• 沖合との連成：沖合・沿岸域の受け渡し。
• 砕波、泡、または露出した海底の湿潤状態：砕波、泡、湿潤状態。
• スパース実行：スパースなアクティブタイル。
• ライブグリッドの CPU クエリ：ライブ GPU グリッドのクエリ契約。
• 受け手空間の集光：受け手空間の集光。
• 屈折または界面反射：屈折とフレネル。
• 吸収または散乱：Beer-Lambert 輸送。
• 沿岸光学・ライフサイクル統合：光学とプレゼンテーション。
• GPU 実装：WebGPU 実装。

水面・光学分岐の後は、水面の受け入れ基準の該当する箇条書きを適用します。沿岸分岐の後は、沿岸の受け入れ基準の該当する箇条書きを適用します。

パラメトリック水面

変位マップ、両方の解析接線、水平ヤコビアン、および上向きの外積法線を評価します。物理座標の水平クエリでは、水平マップを逆変換します。

分岐の完了条件： パラメーター座標と物理座標の水平サンプルの意味が曖昧でないこと、解析接線・法線が有限差分と一致すること、最小ヤコビアンが正であるか、すべての折り返しが無効として分類されること、そしてクエリ残差が合格基準を満たすこと。

有界線形水位場

ピンポン方式の水位／鉛直速度状態、固定 dt、次元を持つソース、明示的な境界条件を使用し、次の順序でディスパッチします。

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

この分岐を採用する前に、 有界水位場の分散比較ツール をインポートし、選択した c、dt、dx、 dz、kx、kz を指定して boundedHeightfieldDispersion() を呼び出します。この関数は、減衰なし（gamma=0）の離散位相を予測します。 この予測値を、測定した解析モードの位相と比較します。実際の減衰とソース設定について、振幅誤差を別途測定します。 このヘルパーは非有限の演算を拒否し、CFL 条件が限界と等しい場合を除外して、全体の安定性と表現モードの適用可否を区別します。DC の位相フィールドは、偽の数値測定値ではなく、明示的に利用不可とされます。

分岐の完了条件： CFL マージンが正であること、解析モードの位相と振幅の誤差、境界反射、平均ドリフト、精度誤差、有限値スキャンがすべて合格すること、イベントが重なっても書き込み競合が発生しないこと、すべてのコンシューマーが新しい状態から導関数を読み取ること。

海岸線追従の規定位相

海岸からの距離、または収束済みのアイコナール伝播時間フィールドから波峰の位相を導出します。 位相分岐が担うのは波峰の配置と規定の洗浄マスクのみです。流れ、運動量、波エネルギーについては主張しません。

分岐の完了条件： 波峰の方向、間隔、速度、海岸線に沿った連続性、アイコナール残差と到達不能の分類、メディアル軸に基づく海岸の所有権、フラグメントフットプリントのフィルタリングが、それぞれのゲートをすべて通過し、流れ／エネルギーを扱わないことが明示されていること。

波作用またはレイ

周波数と方向ごとに、次元を持つ作用／エネルギーを輸送します。流れ、固有周波数、群速度、求積、散逸、独立して管理される表示位相を明示します。レイは回折や干渉については主張しません。

分岐の完了条件： 表現される帯域全体で、分散／群速度、位相ループまたはカール、作用／エネルギー収支、浅水変形／屈折、正則化、引き継ぎ時の反射が合格すること。

緩勾配方程式

放射境界／開放境界を用いて、固定された緩やかに変化する水深地形に対する複素位相／振幅を解きます。ソースと水深地形が定常している場合は、オフラインでの解法を優先します。

分岐の完了条件： 製造解または独立した参照値による収束、位相／振幅の補間、境界反射、保存フィールドの無効化が合格すること。

固定湿潤線形浅水系

互換性のある離散発散／勾配、または有限体積法による単一のフラックスを用いて、自由水面の摂動と深さ積分流量を時間発展させます。

分岐の完了条件： 永続的な湿潤状態が維持されること、質量と宣言されたエネルギー挙動が収支を満たすこと、分散と境界反射が合格すること、湿潤／乾燥、砕波、有限振幅について主張しないこと。

非線形湿潤／乾燥浅水系

単一の正準面フラックス、平衡を保つ水深地形、正値性を保つ更新、乾燥セルの除算方針、固定の安定時間ステップ、保存則に基づくソース計上を用いて、保存量である水深と運動量を時間発展させます。

分岐の完了条件： 報告のないクランプなしで水深が非負に保たれること、静止水面が静止状態を保つこと、境界／ソースフラックスに対する質量収支が閉じること、乾燥セルが有限値を保つこと、海岸線／遡上と格子／時間ステップ／乾燥しきい値に関する収束が合格すること、境界反射がゲートの範囲内であること。

外部ソルバー

バージョン管理された水面、速度、湿潤／乾燥、マテリアル、プレゼンテーションの状態を、明示的なアダプターを通じて使用します。外部プロセス／キュー／フェンスの遅延と、利用不可のチャンネルを明示します。

分岐の完了条件： 単位、座標系、クロック、補間、エラー、ライフサイクル、障害／復旧、プレゼンテーションの所有権が実証されること。レンダーフレームが外部ソルバーの結果を同期的に読み戻したり、外部ソルバーを進めたりしないこと。

双方向の剛体連成

物体の運動を水に反映させ、水からの反作用も物体に伝える必要がある場合は、宣言済みの連成区間を1つ使用します。

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. 共有サーフェス状態を一度だけ導出する

ジオメトリ、接線、法線、速度、シャドウ、泡の発生源、屈折、時間方向の各利用側は、選択した状態バージョンから導出します。ハンドオフでは、すべての位置でジオメトリの所有者を1つにします。コヒーレントなサーフェスでは振幅を一致させてブレンドを微分し、ウェイトの勾配も含めます。パワーウィンドウは、独立した帯域または直交する帯域にのみ適用します。

表現されている原因のうち最も強いもの、すなわちモデル化された砕波損失、較正済みの衝撃波／エントロピー損失、厳密な圧縮／ヤコビアン、または規定された波頭の到達から、泡の発生源を1つ構築します。移流するカバレッジまたは保存される面密度のどちらかを格納し、それに対応する方程式を使用します。1つの散逸分配で、1つの履歴を駆動します。

露出した底面の受け手を1つだけ定め、濡れ状態の所有者とします。浸水、または宣言された規定の洗浄マスクによって濡れ状態にし、乾燥はタイムステップに対して正しく処理します。濡れ状態が変えるのは受け手のマテリアル応答であり、水の質量や海岸線の形状ではありません。

疎な沿岸部の実行では、可視性だけでなく、因果的な影響範囲と相互作用の支持領域に基づいてアクティブ化します。タイル全体に対するステンシル処理の前にハローと境界を埋め、隣接タイル間で同一の面フラックスを維持し、アクティブ化／非アクティブ化に伴う状態と誤差を考慮します。

完了条件： すべての幾何および光学系の利用側を1つの状態バージョンで説明でき、泡と濡れ状態にそれぞれ単一の所有者とリセット規則があり、疎な非アクティブ領域に明示的なモデルがあり、表示される継ぎ目に複数のサーフェスが存在しないこと。

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、明示的な精度、ミップマップを生成しない設定、およびステンシル用の整数ロードを使用します。グリッド全体のプロデューサーとコンシューマーの依存関係は、必ずディスパッチ境界をまたぐようにします。 renderer.computeAsync(...) は初期化時にも安全に使用できますが、プロミスの解決は GPU 処理の完了を示すものではありません。シミュレーション解像度はビューポート解像度から独立させます。

水を除外した不透明パスを使用し、その結果を消費する水／合成処理の負荷を明示的に見積もります。アタッチメントへの書き込み中にそのアタッチメントをサンプリングしてはなりません。また、複数の走査を 1 つのパスとして扱ってはなりません。RenderPipeline と出力変換は 1 つだけ使用します。 renderOutput(...) が変換を担う場合は、 pipeline.outputColorTransform = false を設定します。pipeline.outputNode を置き換えた後は、pipeline.needsUpdate = true を設定します。 プレゼンテーションでは、安定した ID を持つ不変の前状態／現在状態を使用します。 サイズ変更、表現形式、更新頻度、アクティブ領域、基準面、原点、ソース、ソルバーバージョンが変わった場合は、互換性のある状態を移行するか、依存するすべての履歴をリセットします。リソースとリスナーは、それらを所有するオブジェクトとともに破棄します。

完了条件： 初期化済みのネイティブ WebGPU バックエンド／機能、ディスパッチと割り当ての一覧、ピーク時のライブバイト数、精度の比較、ウォームアップ後の継続的な計測時間、再構築／破棄後の安定性が記録されていること。フレーム処理のクリティカルパスで読み戻しが行われず、出力変換が二重に適用されないこと。

7. 最終的な反証確認

最終画像だけでなく、該当する診断情報を確認します。

• 海底地形、海岸距離／フレーム、湿潤マスク、境界、状態、導関数
• 位相／作用量／流量、エネルギーまたは質量の残差、反射、湿潤／乾燥状態
• 泡の発生源／輸送／反応と湿潤度の履歴
• 屈折の有効性、フレネル反射／全反射、減衰項、集光の堆積
• 固定カメラと複数の時刻での最終画像、およびエフェクト無効時のキャプチャ

完了条件： 選択したすべての分岐基準に合格していること。対象外とした現象がすべて主張の範囲外であること。すべての受け渡しにプロデューサーとコンシューマーがそれぞれ 1 つずつ存在すること。すべてのリソースに所有者とリセット／破棄のルールがあること。そして、1 つの因果的な水の状態が 1 つの最終出力変換に到達すること。