/ geopbf

GeoPBF — Lightweight Binary GIS Format

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

Table of Contents
  1. なぜ GeoPBF か
  2. バイナリフォーマット構造
  3. デルタエンコーディング × Varint
  4. GIS 変換ハブ
  5. アンチメリジアン処理
  6. ArrayBuffer と Worker アーキテクチャ
  7. Gint 拡張 — 64bit 座標パッキング
  8. 他フォーマットとの比較
  9. API リファレンス
  10. 地図ライブラリ統合
  11. 非信頼HTMLと消毒
  12. COG — ラスタも同じ流儀で
  13. PMTiles と GeoParquet — 出ていく方向

1. なぜ GeoPBF か

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

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

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

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

Header
メタデータ
NAME · KEYS(属性名グローバル辞書)· PRECISION · BUFS(バイナリプール)
DESCRIPTION · LICENSE · ATTRIBUTION · MIN_ZOOM · MAX_ZOOM
メタデータは O(1) でバイナリスライスにより更新可能(再エンコード不要)
↓
FARRAY
フィーチャ配列
FEATURE × N
  └ GEOMETRY: GTYPE · LENGTH · COORDS(デルタ圧縮)
  └ PROPERTIES: INDEX(KEYS参照)· VALUE(型付き)
フィールドタグ型説明
GTYPE8Varint0:Point 1:MPoint 2:Line 3:MLine 4:Poly 5:MPoly 6:Collection
LENGTH9Packed Varintリング・マルチパートの頂点数列
COORDS10Packed SVarintデルタ圧縮座標列 X₀,Y₀,ΔX₁,ΔY₁,...(後述)
INDEX12Packed Varintグローバル KEYS 辞書へのインデックス
VALUE11Repeated MessageNULL/BOOL/INTEGER/FLOAT/STRING/DATE/COLOR/FUNC/JSON/BBOX/BLOB/IMAGE — メッセージ 1 つに 1 フィールド、フィールド番号が型
GARRAY13MessageGeometryCollection の要素を入れ子の GEOMETRY メッセージで

リーダが知っておくべき細部(すべてワイヤ仕様に): デルタの鎖はリングごとに (0,0) から始まる、ポリゴンのリングは閉点を省く、要素 1 つの Multi* は単数型で書く、 BUFS の各要素は個別に raw DEFLATE 圧縮、COLOR は正規形の rgb()/rgba() 文字列だけ、 DATE は秒精度。

O(1) ヘッダー更新

NAME・DESCRIPTION・LICENSE などのメタデータはヘッダーに独立して格納されているため、 バイナリスライスで直接書き換えが可能。フィーチャ本体を再エンコードする必要がなく、 巨大データセットの名称変更やライセンス情報の更新が即座に完了する。

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

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

① Raw float
139.74000
35.68000
139.74123
35.68123
139.74246
② Delta
139.74000
35.68000
+0.00123
+0.00123
+0.00123
③ × 10⁶ (int)
139740000
35680000
+1234
+1234
+1234
④ Varint bytes
4 bytes
4 bytes
2 bytes
2 bytes
2 bytes

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

GeoJSON との比較

GeoJSON の "coordinates":[139.741234,35.681234] は約 30 バイト(テキスト)。 GeoPBF のデルタ Varint 表現では初回 8 バイト、以降の頂点は 2〜3 バイト。 §8.1 で実測した 3 データセットでは、無圧縮 GeoJSON 比で 75〜92% の削減。 さらに gzip(CompressionStream)で 18〜29% 減る。この上積みが小さいのは、 gzip が探す冗長性を構造の側で先に除いてあるためである。

4. GIS 変換ハブ

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

フォーマット読み込み書き出し特記
GeoJSON✓✓File/Blob/Object すべて対応
Shapefile✓ (.zip)✓ (.zip)マルチファイルを zip 単体で処理
KMZ / KML✓✓Google Earth 互換
GML✓✓OGC 標準
GPX✓✓GPS トラック・ウェイポイント
FlatGeoBuf✓✓高速ストリーミング対応
TopoJSON✓✓トポロジー保持 入出力
NDJSON / GeoJSON Text Sequence✓—1 行 1 地物(.ndjson .geojsonl .geojsons .jsonl)。geopbf/ndjson が流し読みする。書き出しの口は内蔵しない
CZML(Cesium)✓✓時刻つき位置は time 配列に、パケットの残りは czml 属性で往復
GeoPackage✓—依存ゼロの SQLite リーダで 1 層({ layer })。geopbf/gpkg はタイル表も開く
SpatiaLite✓—.sqlite .sqlite3 .spatialite .db。同じリーダ・SpatiaLite の BLOB ジオメトリ
File Geodatabase✓ (.zip)—Esri の .gdb フォルダを zip したもの。中の *.gdbtable で判別、{ layer } で表を選ぶ
CSV / TSV / XLSX✓✓経緯度列か WKT 列({ lon, lat, wkt, sheet, delimiter })。書き出しは pbf.getCSV()(属性+点なら経緯度・それ以外は bbox)と geopbf/encodeXLSX
DXF✓—AutoCAD DXF({ crs, unitScale, closedAsPolygon })。平面直角座標系は geopbf/proj
登記所備付地図(法務省)✓ (.zip)—14条地図・筆ポリゴン。デコード時に JGD2011 平面直角座標(19 系)→ WGS84 を実施。拡張子が .zip で Shapefile と競合するため { format: "moj" } で明示指定
GeoParquet (v1.5)✓✓WKB + bbox 覆域列・行は空間順。依存ゼロのリーダは geopandas / pyarrow / DuckDB の出力も読む — §13
PMTiles(MVT)(v1.5)—✓タイルは Gint から切るため、ズーム別簡略化はランクのフィルタ 1 つ — §13。逆変換は無い(タイルは簡略化・量子化済み)
GeoPBF✓ (native)✓ (native)ネイティブ高速ロード
Gint✓ (decode)✓ (encode)Morton + VW 拡張(後述)

「読み込み」に ✓ のある行はすべて自動判定の入口 geopbf(input) を通る(GeoParquet も。依存ゼロの リーダは geopbf/geoparquet にある)。PMTiles の書き出しは規模が大きく必要時に読めば足りるため、 専用のサブパス export(geopbf/pmtiles)に分けてある(詳細は §13)。ラスタはさらに別経路で、geopbf/cog は Cloud Optimized GeoTIFF を HTTP Range で直接読み、変換自体を行わない(§12)。多くは CLI に対応物があり、 npx geopbf enc / dec / pmtiles / parquet / parquet2pbf / gpkg2pbf / spatialite2pbf / dxf2pbf / csv2pbf / gdb2pbf が GDAL 無しの素の Node で動く。

自動フォーマット判定

geopbf(input) に File・Blob・ArrayBuffer・ Object のいずれを渡しても、拡張子・MIME タイプ・マジックバイトから フォーマットを自動判定して適切なデコーダを呼び出す。対応は .geopbf .pbf .geojson .json .topojson .ndjson .geojsonl .geojsons .jsonl .fgb .gpkg .sqlite .sqlite3 .spatialite .db .parquet .geoparquet .csv .tsv .xlsx .zip .kml .kmz .gpx .gml .xml .czml .dxf (いずれも .gz 可・gzip は署名で判別)。呼び出し側はフォーマットを意識する必要がない。 .zip は中身を見る(*.gdbtable があれば File Geodatabase、無ければ Shapefile)。 唯一の例外が登記所備付地図で、拡張子 .zip が両方と重なるため { format: "moj" } で明示する。デコードできない File は黙って空の FeatureCollection を返さず、明示エラーで落とす。

// どんな形式でも同じ 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)

// 各フォーマットへのエクスポート(*File() は worker でエンコードして File を返す)
const geojson  = pbf.geojson;                 // → GeoJSON オブジェクト(同期)
const topojson = pbf.topojson();              // → TopoJSON(トポロジー保持・{ gint: true } が要る)
const shp      = await pbf.shapeFile();   // → Shapefile (.zip)
const kmz      = await pbf.kmzFile();     // → KMZ
const gml      = await pbf.gmlFile();     // → GML(gpxFile・czmlFile・geojsonFile・topojsonFile も同様)
const fgb      = await pbf.fgbFile();     // → FlatGeobuf

// 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);                   // → { buffer, geo, stats }
const { pbf: back } = await fromGeoParquet(u8);        // ← GeoParquet(geopandas/DuckDB 出力も可)

// ネイティブ保存(gzip 済み .geopbf)
const file = await pbf.geopbfFile();   // → File「<name>.geopbf」(pbf.save() は bucket へ保存する別の口)

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

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

GeoPBF はアンチメリジアンの正確さをフォーマット不変条件として扱う: GeoPBF に格納されたジオメトリはすべてアンチメリジアンで切断されていることが保証される。 アンチメリジアンをまたぐポリゴンはフォーマット内に存在できない。唯一の外し方は new GeoPBF({ cut: false }) で、 形を変えずに往復させたい器(geoedit のセッション保存)のためにある。

エンコード時に自動適用 — 全インポートパス共通

setFeature() はすべてのフィーチャをバッファに書き込む前に antimeridianFeature(q) を呼び出す — ソースフォーマットに関わらず。 GeoJSON・Shapefile・KMZ・GML・GPX・FlatGeoBuf・TopoJSON — すべて同じパスを通る。 呼び出し側はジオメトリを事前処理する必要がない。

5.1 球面大円交点演算

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

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

// 球面交点緯度(大円の公式)
// x = sin(lat0−lat1)·sin(avgLng)·cos(halfΔlng) - sin(lat0+lat1)·cos(avgLng)·sin(halfΔlng)
// z = cos(lat0)·cos(lat1)·sin(Δlng)
// intersectLat = atan2(x, |z|)   ← 球面上で幾何学的に正確
Gint との関係

Morton コードは座標が有界な領域内に収まることを前提とする。 ±180° をまたぐジオメトリは整数空間の端から端へジャンプするような Morton コードを生成し、 二分探索と空間近接性の保証を破壊する。 エンコード時にカットを済ませることで、GeoPBF タイル内のすべての Morton コードが 下流で特別扱い不要な空間的一貫性を持つ。

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

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

Main Thread
geopbf(file)
pbf.arrayBuffer
worker.postMessage(buf, [buf])
— 転送後は参照不能 —
→
Encoder Worker
gint encode
topology analysis
postMessage(result, [result])
zero-copy 返却
→
Render Worker
SharedArrayBuffer
複数 Worker が同時参照
LOD フィルタ処理
WebGPU / WebGL2 描画

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" }));
Worker との相性が良い理由

GeoJSON はオブジェクトグラフ(JSON)であり、Worker に渡すには JSON.stringify → 転送 → JSON.parse という シリアライズ/デシリアライズが必要で、大規模データでは数百ミリ秒を消費する。 GeoPBF は最初から ArrayBuffer であるため、 ゼロコピー転送 で Worker 間を移動でき、 受け取り側はポインタを進めるだけで座標を読める。 メインスレッドは一切ブロックされない。

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

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

L1 node
(anchor)
1
Morton code (63 bits) — 精度 10⁻⁷ deg 固定
bit 63 = 1 → L1(アンカー頂点、常に保持)
L2 node
(detail)
0
Morton code (57 bits)
VW rank
(6 bits)
bit 63 = 0 → L2(詳細頂点、LOD フィルタ対象・格子は 8×10⁻⁷ deg に丸め) ·  bits 6-62 = Morton  ·  bits 0-5 = VW ウェイトランク(0〜63)

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

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

// Morton コード取り出し(L2 の場合 bits 6-62。丸めた格子の下位 6bit は 0)
const mortonCode = code & 0x7FFFFFFFFFFFFFC0n;  // bits 6-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 コード区域
地物数258125,13033,791
頂点数548,46915,669,41651,258,797
座標格子10⁻⁶°(0.11 m)10⁻⁶°(0.11 m)10⁻⁵°(1.1 m)
Shapefile(.shp+.dbf+.shx)9.7282.8825.3
  └ +.prj を zip −94.9174.8530.5
GML(.xml)—580.7—
  └ + gzip −9—123.2—
GeoJSON13.3579.61,089.6
  └ + gzip −94.7138.6265.8
FlatGeobuf9.3266.9826.8
  └ + gzip −95.4156.3421.9
GeoParquet(WKB・zstd・bbox 列)4.5124.5333.7
GeoPBF3.348.6117.8
GeoPBF + gzip −9 (配布形)2.734.495.2

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

頂点あたり(バイト)NE 10m admin_0N03ZCTA5
Shapefile17.7 → 9.018.1 → 11.216.1 → 10.3
GeoJSON24.2 → 8.637.0 → 8.821.3 → 5.2
FlatGeobuf17.0 → 9.817.0 → 10.016.1 → 8.2
GeoPBF6.0 → 4.93.1 → 2.22.3 → 1.9
Shapefile と FlatGeobuf は同じ場所に着地する

どちらも頂点あたり 16〜18 バイト。理由も同じで、1 点につき IEEE-754 の double を 2 本、 ジオメトリの形によらず置くからである。両者の差はレコードヘッダと属性の持ち方であって座標ではない。 1998 年の Shapefile と 2019 年の FlatGeobuf のあいだに 20 年あって、ジオメトリ部は動かなかった。 GeoPBF は代わりに整数格子上のデルタを置くので、コストは頂点密度とともに 下がる。 数メートル刻みの境界線なら頂点あたり 2〜3 バイト、属性列の多い疎なジオメトリならもう少し多い。

同じ条件で比べる

gzip 同士で比べると、GeoPBF は GeoJSON の 1.8〜4.0 分の 1 である。無圧縮の行が示す 5〜17 倍ではない。 どのフォーマットも実際は圧縮して配るのだから、こちらが正味の数字になる。 圧縮が一番効くのはテキスト(GeoJSON は元の 24〜36%、GML は 21% まで落ちる)、 double 系のバイナリは中庸(shapefile 51〜64%・FlatGeobuf 51〜59%=隣り合う座標は double の上位バイトを 共有するので効く。効かないのは下位の仮数ビットだけ)、 そして GeoPBF が一番効かない(71〜82%)。圧縮器が探す冗長性を、構造の側で先に潰してあるからである。 無圧縮の行はデコーダがメモリ上で歩く量、圧縮後の行が回線を渡る量にあたる。

再現は 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 は読み込み時にメモリ上で作る)
フォーマット変換 要外部ライブラリ 要外部ライブラリ 限定的 18 フォーマットの読み込み内蔵
トポロジー なし なし なし アーク共有・境界整合

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  → トポロジー整合クリーン処理を実行

//   worker:  false → 呼び出しスレッドで復号(Worker の無い Node では自動)

// ── データアクセス ──────────────────────────────────────────
pbf.length          // フィーチャ数
pbf.keys            // 属性名配列 ['name', 'rank', ...]
pbf.arrayBuffer     // 生 ArrayBuffer(Worker 転送用。set(ArrayBuffer) は復号 worker へ transfer する)
pbf.geojson         // GeoJSON FeatureCollection に変換
pbf.topojson()      // TopoJSON に変換(トポロジー保持・Gint が要る)
pbf.getFeature(i)   // i 番目のフィーチャだけをデコード(getGeometry / getProperties / propsRow も同様)
pbf.contain([lng, lat])          // 点を含む最小の面(fid か null)
pbf.identifyAt(lng, lat, opts)   // 点・線・面の当たり判定(半径はメートル)

// ── エクスポート ────────────────────────────────────────────
await pbf.save()             // 設定した bucket へ保存(createGeopbf(apiBase, { bucket }))
await pbf.geopbfFile()       // .geopbf の File(geojsonFile / topojsonFile / shapeFile / kmzFile / gpxFile / czmlFile / gmlFile / fgbFile)
await pbf.preview(canvas)    // worker で描くサムネイル(OffscreenCanvas / ImageBitmap)

// ── メタデータ O(1) 更新 ────────────────────────────────────
pbf.name('New Name'); pbf.description('...'); pbf.license('MIT');   // または pbf.updateHeader({ … })

// ── 低いレベルの入口(パッケージのサブパス) ────────────────
// geopbf             GeoPBF クラス(new GeoPBF(opts).set(…))      geopbf/core · /pbf-base   GeoPBFBase=拡張メソッドの無い器
// geopbf/pbf         protobuf の wire の読み書き                   geopbf/gint · /topology · /identify   Gint の焼き込み・GintBUF・当たり判定
// geopbf/pmtiles · /geoparquet · /parquet · /spatial-order       書き出しと読み込み(§13)     geopbf/tilesource   Gint から要求タイルだけ MVT に
// geopbf/convert             変換器を一括で import               geopbf/convert/gpu   変換器が使う WebGPU デバイス
// geopbf/gpkg · /sqlite · /spatialite · /mbtiles · /filegdb · /fgb · /dxf · /table · /ndjson   形式リーダ(自動判定の入口を通さず使える)
// geopbf/proj · /epsg · /datum   WKT / EPSG 投影・TKY2JGD / PatchJGD の測地系変換    geopbf/convert/node-gint   Node で Gint を焼く
// geopbf/cog · /cog/core · /cog/source · /cog/tiff · /cog/decode · /maplibre-cog · /leaflet-cog   Cloud Optimized GeoTIFF(§12)
// geopbf/featureservice      ArcGIS FeatureServer / OGC API – Features をソースに   geopbf/georef   IIIF Georeference Annotation
// geopbf/edit · /edit/*      編集モデル(DOM 非依存)         geopbf/worker · /no-builtin-workers   worker の入口とその外し方
// geopbf/sanitize · /czml · /gzip · /encodeZIP · /decodeZIP · /encodeXLSX · /fname2mime   ユーティリティ
2.0 での変更

2.0 では 1.x が互換のために残していた物を外した。noeval オプション(FUNC 値は常にソース文字列のまま)、 validate: "legacy"("lenient" に落ちる)、closeFilter(f)(cloneMap({ filter: f }) を使う)、 静的な GeoPBF.concatinate(pbf.concat(...others) を使う)、そして geopbf/core と geopbf/pbf-base の 器の名前 GeoPBF(そこでは GeoPBFBase。geopbf の GeoPBF は拡張つきのクラス)である。 fmap・_name などの内部の欄は公開の型に出ない。pbf.length・each/forEach・pbf.name() を使う。 ライブラリ自体は TypeScript(strict)になった。npm パッケージはコンパイル済みの JavaScript と .d.ts の型宣言を同梱するので、geopbf とそのサブパスは追加のパッケージ無しで型が付く。 旧 → 新の全体は MIGRATION.md。

10. 地図ライブラリ統合(v1.1)

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

import 形 対象
geopbf/maplibre addProtocol ハンドラ(GeoJSON ソース、または /{z}/{x}/{y} でベクタタイル) 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" });
map.addSource("rail-tiles", { type: "vector", tiles: ["geopbf://https://…/N02-25_RailroadSection/{z}/{x}/{y}"] });   // 同じ URL に /{z}/{x}/{y}=Gint から要求タイルだけ MVT に(共有境界は継ぎ目無し・feature.id=fid)

// ── 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 は依存追加ゼロの 自前リーダで、ヘッダは 64KB の 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/4258/4269/4612/6668)・3857・UTM(WGS84 326xx/327xx・JGD 6688–6691 / 3097–3101)・ 平面直角座標系 I〜XIX(6669–6687 / 2443–2461)(geopbf/proj と同じ 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 に同等の逆変換は用意していない。タイルは簡略化され量子化されているため、可能なのは近似的な 再構成だけであり、それを逆変換と称することはしない。


geopbf v2.1.1 · Kenji Yoshida · MIT License · 2026