ortho-earth エンジン — 技術概要

すべてを球の上に描く、ブラウザだけで動く地図エンジン（自前の地図サーバーを持たない）
@ortho-earth/core · @ortho-earth/globe · WebGPU と WebGL2 · 実スケールの地形 · worker の流れ作業

1. 四つの層 — コアは硬く、アプリは柔らかく

部品は下にあるものほど硬く作っています（検定の関門・型定義・版で守る）。上のアプリは殻で、自由に変えてかまいません。 新しい仕事は、まず「どの層か」を言ってから書きます。

全体をつなぎとめる決まりは一つ：core と globe は国の名前を書かない。 機械の関門（verify:regionless）が globe のコードの地域の語を数え、増えたら落とします。 import の向きは一方通行で、japan → globe → core → ephem と japan → jp → core。globe と jp は互いを import しません。 両者が出会うのは、アプリが渡す申告の中だけです。

2. スレッドと worker

メインスレッドが持つのはカメラ・入力・DOM だけです。解読・組み立て・描画はすべて worker で動きます。 worker はすべて一つの入口（worker.js）から起動し、Worker の name で役割を指名します。 そのためバンドラが作る worker のビルドは一つで、共有する部品（GeoPBF の核・loaders.gl・シェーダ）は worker の数だけ複製されません。

地域パックは、ビルド時の空き枠を通して役割を足せます（日本は統計の worker を足す）。ホストはそれを知りません。 crossOriginIsolated は必須ではありません。あれば GeoPBF のバッファがコピー無しで worker へ渡り（SharedArrayBuffer）、 無ければ一度だけコピーされます。どちらでも全機能が動くことを関門（verify:nocoi）で確かめています。

3. 描画の土台 — WebGPU を先に、WebGL2 はいつでも

core には同じ顔（set・draw・dispose）を持つ描画器が二つあります。WebGPU 版と WebGL2 版です。 render worker が起動時にどちらかを選びます。

WebGPU には三枚の落ち網があります。初期化に失敗したら worker の中で WebGL2 へ切り替える。 黙った失敗（初期化は通ったのに画面に何も出ない）は最初のフレームを読み戻して見つける。20 秒たってもフレームが来なければ WebGL2 で起動し直す。

画質のための仕組みが二つ、両方の土台で動きます。遷移時の AA：カメラが動いている間は MSAA 1× で描き、 約 0.5 秒止まったら 4× で一枚だけ描く。動的解像度：フレームが重くなると canvas の解像度を段階的に下げ、線の太さは画面上で変えない。

4. カメラ・投影・ズーム

カメラは小さな素のオブジェクト（center・zoom・pitch・bearing）で、投影は 4×4 の行列一つです。 正射と透視は一続き：正射は、目を無限に遠ざけた透視です。投影は壁ではなくスライダーです。

• ズームは縮尺そのもの。z0 で世界が 256 px。同じ z はどこでも同じ倍率です。緯度による補正をカメラに戻すことはしません。
• 浮動小数点を誤魔化さない。絶対の経緯度を 32 bit 浮動小数に通しません。メッシュは局所の原点からの相対（RTE）で描き、カメラの経度は地球を何周回しても溜まらないよう畳みます。
• 既定は球。WGS84 の楕円体も選べます（?ell=1）。距離や面積の計測は常に楕円体で行います。
• 地面の下に潜ると黒くフェードします。カメラを勝手に押し上げることはしません。
• 飛行（flyTo・easeTo・fitBounds）は時間で評価する計画です。台本の再生は 1 歩 35 ms を上限とする仮想時計で進むので、遅い機械で録画してもずれません。

視点は URL にあります — #zoom/lat/lon[/45t][/-30r][/l=…][/c=テーマ][/t=UTC][/s=速さ]。アドレス欄はいつでも「いま見ているもの」へのリンクです。

5. 実スケールの地形

標高は誇張せずに描きます。高さは AltPBF から：三つの解像度の 1° セルを worker で解読し、 二つの標高アトラスに詰めます — カメラの周りの細かいセルの近景アトラスと、地平線までの粗いセルの遠景アトラス。 シェーダは両方から一続きの高さの場を読みます。

• 陰影・段彩・遠山の青は、アトラスから GPU で計算します。
• 基図・画像タイル・ベクタ・建物はすべて同じ場にドレープされるので、浮いたり埋もれたりしません。
• 地域は「この標高は地表面（DTM）だ」と申告でき、その場合は建物をその上に接地させます。
• 公開されている raster-dem（Terrarium・Mapbox・地理院の形式）で、組み込みの標高を置き換えられます：map.setTerrain(…)。

6. 基図・画像タイル・世界帯

おおよそ z8 より下では、地球儀が自分で世界を描きます — Natural Earth 10 m の国・湖・川・海洋境界と、 全球の標高と気候の場から毎フレーム計算する段彩（画像タイルは一枚もダウンロードしない）。世界のデータが担えるのは正直ここまでです。

そこから上は地域が引き継ぎます。入場するズームは地域の申告が決めます（日本は z6.5 から地理院のベクタ基図）。 ベクタタイルは tile と scene の worker を通ります。傾けた 3D の視点では、ズームアウトしても細かいタイルが地面を覆えている間は、粗いタイルに差し替えません。

画像タイル（XYZ・WMS・WMTS・PMTiles・手元の GeoPackage／MBTiles・四隅で貼る一枚の画像）は、まず地面のアトラスに合成し、 地形のシェーダがそのアトラスを画素ごとに引きます。だから画像は山の上に平らに乗るのではなく、斜面に沿います。 MapLibre の style.json も同じ流れに変換して読みます（map.setStyle）。

7. Gint — 問いに答えるベクタ

タイルは描くため、Gint は知るためにあります。Gint の層は GeoPBF の幾何を丸ごと GPU に持つので、 どの地物も選び・強調し・表と突き合わせられます。

• LOD は頂点シェーダの中で。頂点ごとに順位を持ち、今のズームに要る順位より下の頂点を捨てて前方へ寄せる。簡略化しても形に隙間が開きません。
• 面はステンシルで塗る（巻き数）。三角形化の手間が無く、共有する境界がずれません。
• 選択は GPU で、非同期に読み戻します。GPU で答えられない時は JavaScript の点in面（最小面積が勝ち）が答えます。
• 長い辺は地形に沿って曲がる。3D では、線をその下の地形に応じて GPU で細分します。

8. 3D メッシュ — 建物・3D Tiles・I3S・模型

一つのメッシュの核が、あらゆる 3D データを流します。核は建物がどの国のものかを知りません。地域が申告するのはデータの在り処だけです。

道はどれも同じです：解読（Draco を含む）→ 地心座標 → 正射の球 → 重複面の除去 → 地形への接地 → LOD → 原点相対の頂点 → 基図の平らな建物の輪郭を下で隠す被覆マスク。 解読した区は GPU がそのまま食える形で OPFS と IndexedDB に置くので、二度目はディスクから GPU へ直行します。

9. 空と共通の時計

おおよそ z5 より下では空が見えます：実在の星・惑星と月・星座・黄道と天の赤道・夜の側。さらに引くと、実スケールの太陽系へ入っていきます。

これらはすべて一つの時計に従います（map.clock・@ortho-earth/ephem — 太陽系アプリと同じ時計）。 既定は実時間で、止める・早送り・巻き戻し・1800〜2049 年の任意の時刻に合わせることができます。 太陽直下点と恒星時は両アプリで同じ式から出すので、夜の側・星・人工衛星はいつも一致します。 時計は render worker に一つの基準 {sim, wall, rate} として渡り、状態が変わった時にだけ送られます。

10. 公開面

import { createGlobe } from "@ortho-earth/globe";

const map = await createGlobe({ target: "#map", view: "#3/20/140" });
map.flyTo({ center: [139.767, 35.681], zoom: 14, pitch: 60 });

API の形は、できる所は MapLibre に合わせています。既存のスタイルや手癖がそのまま使えます。 上のすべては、公開パッケージそのものから頁を起動する関門で検めています — 検めたものが、インストールするものです。