GeoPBF — Lightweight Binary GIS Format

Protocol Buffers ベースの地理空間バイナリフォーマット。
軽量・変換ハブ・ArrayBuffer ネイティブ — ブラウザ GIS のワイヤフォーマット

1. なぜ GeoPBF か

GeoJSON は可読性が高く扱いやすいが、大規模データではスケールしない。 テキスト形式のため転送量が大きく、パースに CPU 時間がかかり、 ブラウザのメインスレッドをブロックする。 Shapefile は広く普及しているが複数ファイル構成で Web に向かず、 タイル MVT は zoom ごとに分割されネットワーク効率が悪い。

GeoPBF は ブラウザ GIS の通信レイヤー として設計されたバイナリフォーマットである。 Protocol Buffers の圧縮効率、座標のデルタエンコーディング、 ArrayBuffer ネイティブな設計により、転送・デコード・Worker 間受け渡しのすべてが高速になる。

2. バイナリフォーマット構造

GeoPBF ファイルは Header Section と Body Section（FARRAY） の 2 部構成である。

フィールド	タグ	型	説明
GTYPE	8	Varint	0:Point 1:MPoint 2:Line 3:MLine 4:Poly 5:MPoly 6:Collection
LENGTH	9	Packed Varint	リング・マルチパートの頂点数列
COORDS	10	Packed SVarint	デルタ圧縮座標列 X₀,Y₀,ΔX₁,ΔY₁,...（後述）
INDEX	12	Packed Varint	グローバル KEYS 辞書へのインデックス
VALUE	11	Repeated Message	NULL/BOOL/INTEGER/FLOAT/STRING/DATE/COLOR/JSON/BLOB/IMAGE

3. デルタエンコーディング × Varint

座標を GeoJSON のように浮動小数点テキストで記録すると、 経度 139.7412345 だけで 11 バイト消費する。 GeoPBF は 2 段階の変換でこれを削減する。

隣接する頂点間の座標差は数百メートル程度（地図スケール次第）であり、 整数化後の差分は小さな値になる。 Varint は小さな整数を少ないバイト数で表現するため、 頂点が密なほど 1 頂点あたりのコストが下がる。地理データでは有利に働く性質である。

4. GIS 変換ハブ

GeoPBF は単なる保存フォーマットではなく、主要 GIS フォーマット間の 変換ハブ として機能する。 入力（デコード）と出力（エンコード）の両方に変換パスを持ち、 GeoPBF を中心に置くことで任意フォーマット間の相互変換が 1 ステップで可能になる。

上 8 行は自動判定の入口 geopbf(input) を通る。GeoParquet と PMTiles は規模が大きく必要時に 読めば足りるため、それぞれ専用のサブパス export（geopbf/geoparquet・geopbf/pmtiles） に分けてある（詳細は §13）。ラスタはさらに別経路で、geopbf/cog は Cloud Optimized GeoTIFF を HTTP Range で直接読み、変換自体を行わない（§12）。いずれも CLI に対応物があり、 npx geopbf enc / dec / pmtiles / parquet / parquet2pbf が GDAL 無しの素の Node で動く。

// どんな形式でも同じ API で読み込める
const pbf = await geopbf(file);          // File（Shapefile .zip, GeoJSON, KMZ ...）
const pbf = await geopbf(arrayBuffer);    // ArrayBuffer（fetch 結果など）
const pbf = await geopbf(geojsonObject);  // GeoJSON オブジェクト直接
const pbf = await geopbf(zip, { format: "moj" });   // 登記所備付地図 .zip（平面直角→WGS84）

// 各フォーマットへのエクスポート
const geojson  = pbf.geojson;    // → GeoJSON オブジェクト
const topojson = pbf.topojson;   // → TopoJSON（トポロジー保持）
const shp      = pbf.shape();    // → Shapefile (.zip Blob)
const kmz      = pbf.kmz();      // → KMZ Blob
const gml      = pbf.gml();      // → GML 文字列
const fgb      = await pbf.fgb(); // → FlatGeoBuf ArrayBuffer

// v1.5 — 大きい 2 形式は専用のサブパス export から（§13）
import { toPMTiles } from "geopbf/pmtiles";
import { toGeoParquet, fromGeoParquet } from "geopbf/geoparquet";
const { buffer } = await toPMTiles(pbf, { maxZoom: 12 });  // → PMTiles（MVT）バイト列
const pq   = await toGeoParquet(pbf);                   // → GeoParquet バイト列
const back = await fromGeoParquet(u8);                 // ← GeoParquet（geopandas/DuckDB 出力も可）

// ネイティブ保存（gzip 済み .geopbf）
await pbf.save('coastline');    // → coastline.geopbf をダウンロード

5. アンチメリジアン処理

アンチメリジアン（経度 ±180°）は地理データにおける代表的な落とし穴である。 ベーリング海をまたぐようなポリゴンは、多くのフォーマットで座標が +179° から −179° へジャンプする 単一リングとして格納される。 レンダラー・空間インデックス・クリッピング処理のいずれもこのようなデータでは誤動作する。

GeoPBF はアンチメリジアンの正確さをフォーマット不変条件として扱う： GeoPBF に格納されたジオメトリはすべてアンチメリジアンで切断されていることが保証される。 アンチメリジアンをまたぐポリゴンはフォーマット内に存在できない。

5.1 球面大円交点演算

カットは単純な ±180° 座標クランプではない。 antimeridianCut() は球面の公式を使って、 各交差セグメントがアンチメリジアンと交わる正確な緯度を計算する — 経線収束が顕著な極近傍では特に重要である。 カット後の各サブポリゴンは、正確な交点緯度に頂点を挿入した有効な閉リングとなる。

// 交差検出: 符号反転 + スパン 180° 超 → アンチメリジアン越え（単なる座標ジャンプとの区別）
// p[i][0] * p[i+1][0] < 0  &&  abs(p[i][0] - p[i+1][0]) > 180

// 球面交点緯度（大円の公式）
// x = sin(Δlat/2)·sin(avgLng)·cos(halfΔlng) - sin(avgLat)·cos(avgLng)·sin(halfΔlng)
// z = cos(lat0)·cos(lat1)·sin(Δlng)
// intersectLat = atan2(x, |z|)   ← 球面上で幾何学的に正確

6. ArrayBuffer と Worker アーキテクチャ

GeoPBF の内部表現は一貫して ArrayBuffer である。 これはブラウザの並列処理基盤（Web Workers）と深く統合するための設計上の選択であり、 3 つの重要な特性をもたらす。

6.1 Transferable（ゼロコピー転送）

// ArrayBuffer はメインスレッド → Worker へゼロコピーで転送
// （コピーではなく所有権の移動 → メモリ消費が増えない）
worker.postMessage(pbf.arrayBuffer, [pbf.arrayBuffer]);
// 転送後 pbf.arrayBuffer は detached（メインスレッドからアクセス不能）

// Worker 側
onmessage = ({ data: buf }) => {
	const view = new DataView(buf);  // 即座にデコード開始
	postMessage(result, [result]);    // 処理後もゼロコピーで返却
};

6.2 SharedArrayBuffer（複数 Worker 同時参照）

// gint デコード後の座標データを SharedArrayBuffer に展開
// → 複数の描画 Worker が同時に、コピーなしで参照できる
const sab = new SharedArrayBuffer(buf.byteLength);
new Uint8Array(sab).set(new Uint8Array(buf));

// tile worker × N が並列で LOD フィルタ & 描画
tileWorkers.forEach(w => w.postMessage({ sab, zoom, viewport }));

6.3 CompressionStream（ネイティブ gzip）

// 保存時: ブラウザネイティブの gzip 圧縮（外部ライブラリ不要）
let blob = new Blob([buf]);
blob = await (new Response(
	blob.stream().pipeThrough(new CompressionStream("gzip"))
)).blob();
postMessage(new File([blob], `${name}.geopbf`, { type: "application/x-geopbf" }));

7. Gint 拡張 — 64bit 座標パッキング

GeoPBF に gint エンコードを適用すると、各頂点の座標が 64bit 整数 1 つ にパックされる。 この 64bit 整数は Morton コードと VW ウェイトを同時に格納する。

1 つの 64bit 整数に「どこ（Morton）」と「どの LOD（VW ランク）」を同時に収めることで、 空間クエリと LOD フィルタが単純な整数演算だけで完結する。

// L1 / L2 判定（最上位ビット）
const isAnchor = (code >> 63n) === 1n;

// Morton コード取り出し（L2 の場合上位 58bit）
const mortonCode = code & 0x7FFFFFFFFFFFFFF8n;  // bits 3-62

// VW ウェイトランク取り出し（L2 の場合下位 6bit）
const vwRank = Number(code & 0x3Fn);  // bits 0-5 → 0〜63

// ズームレベル z での LOD フィルタ（1px² に対応するランク閾値）
const minRank = rankFromZoom(z);  // z が大きいほど低い閾値（より多くの頂点）
const visible = isAnchor || vwRank >= minRank;

8. 他フォーマットとの比較

8.1 実測ファイルサイズ

性格と規模の異なる公開データ 3 種を、同一マシンで端から端まで変換して実測した。 どの行も同じ地物を保持している。単位は 10 進 MB。

フォーマット	NE 10m admin_0 世界の国界 v5.1.1	国土数値情報 N03（2026） 全国市区町村界	TIGER 2024 ZCTA5 米国 ZIP コード区域
地物数	258	125,130	33,791
頂点数	548,469	15,669,416	51,258,797
座標格子	10⁻⁶°（0.11 m）	10⁻⁶°（0.11 m）	10⁻⁵°（1.1 m）
Shapefile（.shp+.dbf+.shx）	9.7	282.8	825.3
└ +.prj を zip −9	4.9	174.8	530.5
GML（.xml）	—	580.7	—
└ + gzip −9	—	123.2	—
GeoJSON	13.3	579.6	1,089.6
└ + gzip −9	4.7	138.6	265.8
FlatGeobuf	9.3	266.9	826.8
└ + gzip −9	5.4	156.3	421.9
GeoParquet（WKB・zstd・bbox 列）	4.5	124.5	333.7
GeoPBF	3.3	48.6	117.8
GeoPBF + gzip −9 （配布形）	2.7	34.4	95.2

頂点あたりのバイト数（無圧縮 → 圧縮後）。フォーマットの差はここに出る。

頂点あたり（バイト）	NE 10m admin_0	N03	ZCTA5
Shapefile	17.7 → 9.0	18.1 → 11.2	16.1 → 10.3
GeoJSON	24.2 → 8.6	37.0 → 8.8	21.3 → 5.2
FlatGeobuf	17.0 → 9.8	17.0 → 10.0	16.1 → 8.2
GeoPBF	6.0 → 4.9	3.1 → 2.2	2.3 → 1.9

再現は npx geopbf enc と npx geopbf parquet。FlatGeobuf の行は公式の flatgeobuf npm ライタで同じ地物を書いたもの。zip 行は .shp+.dbf+.shx+.prj を deflate −9 で こちらで固め直しており、3 データセットを同じ手順で測るためである — 配布 zip は中身がまちまちで （Natural Earth 4.9 MB は HTML README 入り、TIGER 528.8 MB は ISO メタデータ XML 入り、 国土数値情報 N03 803.2 MB は GML と shapefile と GeoJSON が全部入り）そのままでは比較にならない。 shapefile は原典の double をそのまま持つが、精度によらず 1 点 16 バイト固定なのでサイズ行は影響を受けない。

8.2 能力比較

指標	GeoJSON	Shapefile	MVT（タイル）	GeoPBF
エンコーディング	テキスト UTF-8	バイナリ（複数ファイル）	PBF バイナリ	PBF + デルタ + Varint
ファイル数	1	.shp + .dbf + .shx + ...	zoom × tile 数	1
Web 転送効率	低（テキスト大）	中	中（zoom 分割）	高（バイナリ + gzip）
Worker 転送	JSON シリアライズ必要	変換必要	ArrayBuffer	ArrayBuffer ゼロコピー
LOD サポート	なし	なし	zoom 別ファイル	VW ウェイト内包
空間インデックス	なし	.shx（線形）	タイル座標	ファイルには無し（Morton 64bit は読み込み時にメモリ上で作る）
フォーマット変換	要外部ライブラリ	要外部ライブラリ	限定的	12 フォーマット内蔵
トポロジー	なし	なし	なし	アーク共有・境界整合

9. API リファレンス

// ── 読み込み ──────────────────────────────────────────────
const pbf = await geopbf(input, options);
// input: File | Blob | ArrayBuffer | GeoJSON object | URL string
// options: { name, gint, nocache, clean }
//   gint:    false → トポロジーエンコード（gint変換）をスキップ
//   nocache: true  → IndexedDB キャッシュを無視して再取得
//   clean:   true  → トポロジー整合クリーン処理を実行

// ── データアクセス ──────────────────────────────────────────
pbf.length          // フィーチャ数
pbf.keys            // 属性名配列 ['name', 'rank', ...]
pbf.arrayBuffer     // 生 ArrayBuffer（Worker 転送用）
pbf.geojson         // GeoJSON FeatureCollection に変換
pbf.topojson        // TopoJSON に変換（トポロジー保持）
pbf.getFeature(i)   // i 番目のフィーチャだけをデコード

// ── エクスポート ────────────────────────────────────────────
await pbf.save('name')      // .geopbf（gzip）としてダウンロード
pbf.shape()               // Shapefile .zip
pbf.kmz()                 // KMZ
pbf.gml()                 // GML 文字列
pbf.gpx()                 // GPX 文字列
await pbf.fgb()           // FlatGeoBuf ArrayBuffer

// ── メタデータ O(1) 更新 ────────────────────────────────────
pbf.header({ name: 'New Name', description: '...', license: 'MIT' });

// ── 描画 ───────────────────────────────────────────────────
pbf.draw(canvasCtx, { fill: '#5a8050', stroke: '#a8d47e' });

10. 地図ライブラリ統合（v1.1）

v1.1.0 以降、npm パッケージは主要 Web 地図ライブラリ向けのアダプタを同梱する。 いずれもホスト側ライブラリを import しない依存ゼロのサブパス export であり、 共通ローダの上に載る。ファイル全体 gzip はマジックバイトで判別して透過的に展開し、デコードは new Function を使わない CSP セーフの noeval モード、properties は JSON-safe へ写像する（Date → ISO 文字列、bbox → 素の配列、バイナリ値は除去）。 各ライブラリの worker 受け渡しを壊さないための処置である。

import	形	対象
geopbf/maplibre	addProtocol ハンドラ	MapLibre GL JS (v4+)
geopbf/leaflet	L.GeoJSON サブクラス	Leaflet (1.x)
geopbf/openlayers	VectorSource loader ファクトリ	OpenLayers (6+)
geopbf/loaders	loaders.gl Loader オブジェクト	deck.gl · kepler.gl
geopbf/load	素の loadGeopbf(url)	Cesium · D3 など GeoJSON を食べる全て

// ── MapLibre — プロトコルソース ────────────────────────────
import { geopbfProtocol } from "geopbf/maplibre";
maplibregl.addProtocol("geopbf", geopbfProtocol);
map.addSource("rail", { type: "geojson", data: "geopbf://https://…/N02-25_RailroadSection" });

// ── Leaflet — レイヤープラグイン ───────────────────────────
import { extendLeaflet } from "geopbf/leaflet";
extendLeaflet(L);
L.geoPBF("geopbf://https://…").on("load", e => console.log(e.meta)).addTo(map);

// ── OpenLayers — ソース loader ────────────────────────────
import { makeGeopbfLoader } from "geopbf/openlayers";
const source = new VectorSource({ loader: makeGeopbfLoader(url, new GeoJSON()) });

// ── deck.gl — loaders.gl ──────────────────────────────────
import { GeoPBFLoader } from "geopbf/loaders";
new GeoJsonLayer({ data: url, loaders: [GeoPBFLoader] });

// ── それ以外 — 汎用ローダ ─────────────────────────────────
import { loadGeopbf } from "geopbf/load";
const r = await loadGeopbf(url);   // { geojson, name, license, attribution, minZoom, maxZoom, … }
viewer.dataSources.add(await Cesium.GeoJsonDataSource.load(r.geojson));

出典表記はファイル内部に格納される（§2）。Leaflet と OpenLayers のアダプタはヘッダの attribution を地図のクレジット表示へ自動配線する（明示指定が優先）。 loadGeopbf はヘッダメタデータ一式を返すため、手動配線も可能である。 呼び出し側の制約は 1 点のみで、MapLibre では内側 URL を絶対形で記述する （geopbf://https://…、pmtiles と同じ流儀）。MapLibre はソース URL を new URL() で正規化するため、相対形は復元できない。

11. 非信頼HTMLと消毒（v1.2）

GeoPBF は開いたフォーマットであり、ファイルは誰でも生成でき、URL 1 つで配布できる。したがって表示用 プロパティ — @tip・@pop、およびビューアが HTML として描画するあらゆる プロパティ — は非信頼入力として扱う必要がある。扱いを誤れば、細工されたファイルが ツールチップや吹き出しを開いた時点でページ内 script を実行できる（XSS）。対処は定石どおり、文字列が innerHTML に入る直前、すなわち出力側の境界で消毒する。保存側での消毒済みを 前提にはできない。ファイルはエディタを経由せずビューアへ到達しうるためである。

// 出力側の境界＝innerHTML の直前で消毒する
import { sanitizeHTML } from "geopbf/sanitize";
el.innerHTML = sanitizeHTML(feature.properties["@pop"]);

sanitizeHTML は依存ゼロの許可リスト式フィルタである。整形タグ・リスト・表・画像・リンクは 通過し、script・iframe・svg 等は中身ごと破棄、未知タグは殻だけを 剥いで中身を残す。イベント属性と style は通過しない。href は http(s)/mailto、img src は http(s)/data:image のみを許可する。リンクには target="_blank" rel="noopener noreferrer" を強制する。DOM に触れるのは呼び出し時のみで、 worker からの import も安全である。§10 との役割分担は明確で、 sanitizeProperties は値を JSON 安全に（型の問題）、sanitizeHTML は 表示安全に（マークアップの問題）する。両者は併用する。

12. COG — ラスタも同じ流儀で（v1.4）

COG（Cloud Optimized GeoTIFF）は HTTP Range で部分読みできる静的ファイルであり、GeoPBF と同じ 「サーバー不要」の構成をラスタへ適用した形式である。v1.4 の geopbf/cog は依存追加ゼロの 自前リーダで、ヘッダは 16KB の range 1 本で読み、タイル要求はオフセット順に 整列して隣接 range を1 リクエストへ合体（coalesce）する。解凍と再投影は worker プール、JPEG/WebP はブラウザのネイティブデコーダへ渡す。実測値は cog.metrics() が随時返す（range 本数・coalesce 圧縮率・デコード時間）。

import { openCog } from "geopbf/cog";
const cog = await openCog("https://…/TCI.tif");   // range 1本でヘッダ完読
const bm  = await cog.renderXYZ(14, x, y);          // Web メルカトルへ warp 済み ImageBitmap

対応サブセットは公共 COG 配信の実勢に合わせてある。タイル/ストリップ両レイアウト・BigTIFF・ 圧縮 none/deflate/LZW/JPEG/WebP・predictor 2・uint8 RGB(A)/パレット/単バンド uint16/int16/float32 （自動パーセンタイル・ストレッチ、GDAL_NODATA→透明）・CRS は EPSG:4326/3857/UTM （Krüger n 級数 6 次＝nm 精度の自前実装）。これを外れるファイルは黙って壊れるのではなく明示エラーで 拒否し、gdal_translate -of COG による事前変換を案内する。MapLibre へは geopbf/maplibre-cog の cog:// プロトコル、Leaflet へは geopbf/leaflet-cog の GridLayer を、それぞれ 1 行で接続する。 CLI は npx geopbf cog info <url> --bench が構造と実測値を出力する。

13. PMTiles と GeoParquet — 出ていく方向（v1.5）

v1.4 までの変換ハブは入力側のみを扱っていた。v1.5 で出力側が開き、GeoPBF は Mapbox Vector Tiles の PMTiles アーカイブ、または GeoParquet ファイルとして書き出せる。 GeoParquet からの逆変換も可能である。依存追加はなく、むしろ pako を削除した。 圧縮・伸長はすべてプラットフォーム側の codec を直接呼ぶ（ブラウザと worker は CompressionStream、Node は node:zlib）。残る実行時依存は pbf 1 本だったが、 1.6 で protobuf のワイヤ読み書きを自前に持ち込み、これも切った。依存は空である。

# CLI — 素の Node で動く（ネイティブビルド不要）
npx geopbf pmtiles countries.geopbf countries.pmtiles --maxzoom 10
npx geopbf parquet countries.geopbf countries.parquet
npx geopbf parquet2pbf countries.parquet back.geopbf     # 逆変換

import { toPMTiles } from "geopbf/pmtiles";
import { toGeoParquet } from "geopbf/geoparquet";

const pbf = await geopbf(file, { gint: true });
const { buffer, stats } = await toPMTiles(pbf, { maxZoom: 12 });  // stats.engine → "gpu" | "cpu"
const pq = await toGeoParquet(pbf);                      // pq.buffer, pq.geo

タイルは生のフィーチャではなく Gint から切る。 ortho-earth が GPU で描いている 派生バッファそのものであり、共有境界は 1 本の arc として一度だけ存在し、各頂点は Visvalingam–Whyatt のランクを持つ。したがってズーム別の簡略化は rank >= 閾値 のフィルタ 1 つに帰着し、隣り合う 2 つのポリゴンは必然的に同一の 頂点列へ簡略化される。どのズームでも隙間もスリバーも生じない。閾値は arc ごとに Douglas–Peucker 分解と突き合わせて較正してあるため、頂点数は tippecanoe の約 10% 以内に収まる。 かつどの頂点が残るかはランクが決めるので、境界の両側は同一の結果になる。

Natural Earth 10m countries（258 ポリゴン・48 万頂点・z0–10・4 コア Node）では、 GeoJSON から約 6.5 秒で 573,896 タイル / 151.0MB。tippecanoe v2.82 は 58 秒で 573,885 タイル / 147MB であり、タイル集合は数枚の差で一致する。内部タイルはレイヤ名と geopbf が書く フィーチャ id の分を除けばバイト単位で同じ大きさになる。同じ処理に GDAL の PMTiles ドライバ（3.12）は 780 秒を要した。US Census ZCTA5（33,092 郵便番号エリア・5,200 万頂点・z0–12） では 47 秒で 238,322 タイル / 251MB、tippecanoe は 251 秒で 238,319 タイル / 246MB。 MapLibre の z3/z7/z11 で描き比べても差は判別できない。

Parquet の行は空間順に並べて出力する。 フィーチャ bbox の中心を Sort-Tile-Recursive で 詰める（order: "str" が既定）。各 row group の bbox 統計が互いに重ならない 区画を覆うため、範囲条件を押し下げて読む側（DuckDB・pyarrow datasets・GeoPandas）は実際に交差する row group だけを取得する。100 万点を 50 row group にした実測では、row group の重なり比が 無ソート 24.5 → Morton 0.87 → Hilbert 0.28 → STR 0.00、市域サイズの問い合わせが触る row group は 50 から 1–2 へ減る。井口和裕氏の Spatial sort for well-packed GeoParquet（CNG Japan 2026） に倣った実装である。

GPU が担う範囲。 投影・ズーム別ランクフィルタ・整数→double 変換・bbox リダクションは、WebGPU があれば GPU で走り、無ければ同じ整数演算を CPU で走らせる。 どちらの経路でも出力はバイト一致であり、headless Chromium でカーネル単位に検証している。 ただしこれらの段が占めるのは、実測したどのデータでも仕事全体の 3–6% にすぎない。支配的なのは リング組み立て・クリッピング・MVT エンコード・gzip の側である。GPU はブラウザのメインスレッドを 空けておくための手段であって、この変換器が速い理由ではない。速度は Gint と組み立て段に由来する。

逆変換。 fromGeoParquet() は GeoParquet を GeoPBF へ戻す。 依存ゼロの Parquet リーダ（Thrift compact フッタ・DataPage v1/v2・PLAIN と辞書エンコーディング・ codec は none / snappy / gzip / zstd）と WKB パーサの組み合わせである。geopbf が書いたファイルは ビット単位で復元され、GeoPandas・pyarrow・DuckDB が書いたファイルも同じフィーチャとして読める。CRS は 経緯度（CRS84 / EPSG:4326）に限り、それ以外は ignoreCrs を渡さない限り拒否する。 PMTiles に同等の逆変換は用意していない。タイルは簡略化され量子化されているため、可能なのは近似的な 再構成だけであり、それを逆変換と称することはしない。

---