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.ts）から起動し、Worker の name で役割を指名します。 そのためバンドラが作る worker のビルドは一つで、共有する部品（GeoPBF の核・loaders.gl・シェーダ）は worker の数だけ複製されません。

地域パックは自前の入口から自分の worker を起こします（日本の統計 worker＝@ortho-earth/jp の estat-worker.ts）。ホストはそれを知りません。 crossOriginIsolated は必須ではありません。あれば GeoPBF のバッファがコピー無しで worker へ渡り（SharedArrayBuffer）、 無ければ一度だけコピーされます。どちらでも全機能が動くことを関門（verify:nocoi）で確かめています。

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

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

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

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

文字も GPU で（2.1 から）：地名・道路名・アイコン・道路標識は SDF のグリフアトラスに焼き、WebGPU が地図と同じフレームで描きます。 真上から見ている間は style の層の位置に描くので、注記の上に線を置く style も MapLibre と同じ重なりになります。 WebGL2 では自動で Canvas2D の文字に戻り、?text=2d を付ければ WebGPU でも Canvas2D を選べます。

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

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

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

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

5. 実スケールの地形

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

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

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

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

そこから上は地域が引き継ぎます。入場するズームは地域の申告が決めます（日本は z6.5 から地理院のベクタ基図）。 ベクタタイルは tile と scene の worker を通ります。傾けた 3D の視点では、ズームアウトしても細かいタイルが地面を覆えている間は、粗いタイルに差し替えません。 タイルの形式は一つの登録簿に載るプラグインです。MVT は同梱、MLT（MapLibre Tile）は @ortho-earth/tile-formats が持ち、 ビルド時に #tile-formats を @ortho-earth/core/tileformats-mlt（登録する側）へ alias すると使えます。解読器は最初の MLT タイルで読まれるので、MLT に出会わない地図は何も払いません。 vector source は MapLibre と同じく "encoding": "mlt" と書き、PMTiles はヘッダで形式が分かります。

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

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

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

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

7.1 列チャンク — 位相を作らずに描く

Gint の強さは、最初の 1 枚の前に一周の下ごしらえ（共有弧・順位・度アンカー・焼き）を払って得ています。見るだけのファイルには別の道があります （#90）。map.addColumnar(src) は GeoParquet の row group、 または空間順に切った GeoPBF のチャンクを worker で GPU 向けの配列（チャンク原点相対の単位球 xyz・earcut の三角形・格子に丸めた 2〜3 段の LOD）に詰め、 地球と同じフレームのオーバーレイで描きます。属性は列のまま。paint と filter（Gint と同じ語彙）は worker が列から Gint と同じ fid 表に評価するので、 色替えで幾何は作り直しません。落とした .parquet は常にこの道、.geopbf／.fgb は columnarBytes（4 MB）を超えたらこの道です。ただし読み手が先頭チャンクで測る meta.share が「長い共有弧の塗り分け」（admin1・行政地図）を示す時は、それを得意とする Gint に残します。塗りは頂点ごとに地形に沿い、シーンの深度で隠れます。 共有境界は 2 回描かれ、編集は Gint に戻します。

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 に合わせています。既存のスタイルや手癖がそのまま使えます。 上のすべては、公開パッケージそのものから頁を起動する関門で検めています — 検めたものが、インストールするものです。 2.0 からはライブラリが strict な TypeScript で書かれ、型定義も同梱しています（npm にはコンパイル済みの .js と .d.ts）。1.x の互換層は外しました — MIGRATION.md を参照。