PMTilesとは — 3.6億枚のタイルを1ファイルに収める仕組みと、座標系を書く欄がない理由

,

PMTilesとは — 3.6億枚のタイルを1ファイルに収める仕組みと、座標系を書く欄がない理由

PMTilesとは — 3.6億枚のタイルを1ファイルに収める仕組みと、座標系を書く欄がない理由

お知らせ・2026年11月(記事本文の前に追加)

お知らせ(2026年11月)— ファイルフォーマット変換が使えるようになりました

iPhone アプリ JP-GeoConverter Pro(バージョン 2)に「ファイル変換」を載せました。CSV・SIMA・Shapefile・DXF・J-LandXML・LAS・PLATEAU・GeoTIFF など 18 形式を読み、13 形式に書き出せます。座標系は測地系 10 種類 × 緯度経度・平面直角 19 系・UTM 6 帯の 229 通りから選べ、形式と座標系の意味のある組み合わせは約 63 万通りです(組み合わせ上の数。数え方はこちらの記事)。

PMTilesは、Z/X/Yで並んだタイルのピラミッドを1つのファイルに収めるアーカイブ形式です。サーバを立てずに、オブジェクトストレージに置いた1ファイルからHTTP Rangeリクエストで必要なタイルだけを取り出せます。 仕様の中心は「127バイトのヘッダー」と「圧縮したディレクトリ」で、全世界のズーム0〜14(3億5,791万3,941枚)が4,088万エントリに縮みます。そして、ここまで座標系を書く欄が出てきません。GeoParquetやFlatGeobufと違い、PMTilesの仕様書には座標参照系(CRS)や投影法の規定がありません。 その理由と、そこで実務が引っかかる場所を順に見ます。


1ファイルの中身は5つの区画

PMTiles v3のアーカイブは、通常この順に並びます。

区画 役割
ヘッダー 127バイト固定。常にファイルの先頭
ルートディレクトリ タイルの索引(1段目)
JSONメタデータ レイヤ情報など
リーフディレクトリ(任意) タイルの索引(2段目)
タイルデータ タイルの実体

ヘッダー以外は位置を動かせます。ただし一つだけ硬い制約があります。ルートディレクトリは先頭16,384バイト(16KiB)以内に収まっていなければなりません。 ヘッダー127バイトを引くと、圧縮後のルートディレクトリは最大16,257バイトです。

この制約がある理由は読み出しの速さです。クライアントは「先頭16KiBを1回取る」だけでヘッダーとルートディレクトリを手に入れられます。何バイト目を読めばいいかを事前に知るための問い合わせが要りません。


ヘッダー127バイトに何が書かれているか

主なフィールドを抜き出します(整数はリトルエンディアン)。

位置 大きさ フィールド 内容
0x00 7 マジックナンバー PMTiles(UTF-8)
0x07 1 バージョン 3
0x08〜0x40 各8 各区画のオフセットと長さ ルート/メタデータ/リーフ/タイルデータ
0x48 8 Num Addressed Tiles ランレングス前のタイル数。0=不明
0x50 8 Num Tile Entries RunLength>0 のエントリ数。0=不明
0x58 8 Num Tile Contents タイルデータ内の実体の数。0=不明
0x60 1 Clustered 0x00 非クラスタ/0x01 クラスタ
0x61 1 Internal Compression ディレクトリとメタデータの圧縮
0x62 1 Tile Compression タイル本体の圧縮
0x63 1 Tile Type タイルの中身の形式
0x64 1 Min Zoom uint8
0x65 1 Max Zoom uint8(Min Zoom以上)
0x66 8 Min Position 範囲の最小(経度4+緯度4)
0x6E 8 Max Position 範囲の最大(経度4+緯度4)
0x76 1 Center Zoom 初期ズーム(読み手は使ってもよい)
0x77 8 Center Position 初期中心(同上)

圧縮の列挙は 0x00 不明/0x01 なし/0x02 gzip/0x03 brotli/0x04 zstd。
タイル種別の列挙は 0x00 不明・その他/0x01 MVT(Mapbox Vector Tile)/0x02 PNG/0x03 JPEG/0x04 WebP/0x05 AVIF/0x06 MapLibre Vector Tile。

座標に関係するフィールドはMin/Max/Center Positionの3つだけです。 しかもその中身は決まっています。

位置は「度 × 10,000,000 の32ビット整数」

Positionは8バイトで、前半4バイトが経度、後半4バイトが緯度。それぞれ値を10,000,000倍してリトルエンディアンの符号付き32ビット整数として格納します。読むときは10,000,000で割ります。

この固定小数が持つ刻みは 1e-7 度です。緯度方向に換算すると約1.1cm(緯度1度を約111kmとした概算)。範囲を表すbounds用としては十分すぎる細かさで、座標値そのものをここに入れる形式ではないことが分かります。緯度経度の小数桁と実距離の関係は緯度1度・経度1度は何メートル?(JP-GeoPrism)で扱っています。


索引はヒルベルト曲線の1本の通し番号

ディレクトリのエントリは4つの値を持ちます。

値 内容
TileID ズーム0から積み上げたヒルベルト曲線上の通し番号
Offset タイルデータ区画(またはリーフ区画)からの相対位置
Length 圧縮後のバイト数。0より大きくなければならない
RunLength そのエントリが受け持つ連続タイル数。0 はリーフディレクトリへのポインタ

TileIDの付き方は、仕様の例がそのまま分かりやすいです。0/0/0 = 0、1/0/1 = 2、1/1/0 = 4、2/0/0 = 5。Z/X/Yという3つの数が、1本の整数に畳まれます。 畳み方にヒルベルト曲線を使うので、地理的に近いタイルは番号も近くなります。これが効くのが地図を動かしたときで、隣り合うタイルがファイル上でも隣り合っていれば、まとめて1回のRangeリクエストで取れます。ヘッダーのClusteredフラグは「タイルデータがTileID順に並んでいる」ことを宣言するもので、クライアントはこれを見てリクエストをまとめられます。

ランレングスで3.6億枚が4,088万エントリになる

同じ中身のタイルが連続する場合、1つのエントリにまとめてRunLengthで数を持たせます。海だけのタイルや、データが無い領域のタイルは中身が同じになるので、ここが大きく効きます。仕様策定時の検証データ(全世界のベクトル基盤地図・ズーム0〜14)では、3億5,791万3,941枚のタイルが4,088万4,468エントリになりました。

ディレクトリ自体もさらに段階的に縮めます。

段階 ディレクトリの大きさ 元に対する割合
そのまま直列化(1エントリ24バイト) 981.2MB 100%
gzipだけ 305.4MB 約31%
varint化 526.4MB 53.6%
varint+デルタ符号化 243.2MB 24.8%
列方向の転置+gzip(最終形) 91.6MB 9.3%

デルタ符号化はTileIDとOffsetを前のエントリとの差で持つもので、タイルデータが連続しているときはOffsetを0にできます(「前のエントリの直後」を意味する)。列方向の転置は、同じ種類の値を並べて圧縮が効きやすくするための並べ替えです。転置を省くと最終形は102.0MBなので、転置の寄与は約10MBぶんになります。


肝心の話:座標系はどこにも書かれていない

ここまでヘッダーとディレクトリを全部見ましたが、座標参照系を指定するフィールドは1つもありません。 JSONメタデータの側も、必須なのはタイル種別がMVTのときの vector_layers(TileJSON 3.0準拠)だけで、任意キーは name・description・attribution・type・version・encoding です。EPSGコードを書く場所も、WKTやPROJJSONを置く場所もありません。

同じ「クラウドネイティブ」と呼ばれる形式を並べると、PMTilesだけ性格が違うことが分かります。

形式 座標系の書き場所 書かなかったときの扱い
Cloud Optimized GeoTIFF GeoKeyディレクトリ GeoTIFFのタグとして解釈される
GeoParquet geo メタデータのPROJJSON 省略=OGC:CRS84とみなす
FlatGeobuf ヘッダーの Crs テーブル code が0=不明
PMTiles 欄がない Z/X/Yピラミッドの約束に従う

これは仕様の欠落ではなく、形式の性格です。 PMTilesが収めているのは「地物」ではなく「タイル」です。タイルはZ/X/Yで位置が決まっていて、そのZ/X/Yがどの面の上の格子なのかは、タイルを作る側と表示する側の約束で決まっています。ウェブ地図の世界ではその約束が事実上ひととおりに固まっているので、ファイルに書く必要がない——という構造です。

逆に言うと、この約束から外れたものを入れても、ファイル自体は何も文句を言いません。 書く欄がないので、間違いを記録する場所もありません。ここが実務の引っかかりどころです。


引っかかる場所を6つ

1. 平面直角座標系のデータは、タイル化の前に投影を変える

測量成果やCADから出した座標は平面直角座標系(1〜19系)のメートル値です。これをそのままタイル化しようとすると、Z/X/Yの格子が前提にしている面と合いません。先に投影変換を通してから、タイル化の工程に渡します。

変換そのものは ogr2ogr で済みます。やり方と、エラーを出さずに数メートルずれる条件はogr2ogrで座標系を変換するには?に書いています。平面直角座標系とWebメルカトルを取り違えたときに何が起きるかはWebメルカトル(EPSG:3857)と平面直角座標系を取り違えないに整理しました。

地球儀からメルカトル図法、平面直角座標系19系へ至る投影の流れを示した図

2. タイルの中の座標は緯度経度ではない

PMTilesのタイル種別がMVTのとき、タイル1枚の中の座標は緯度経度でもメートルでもなく、タイル内の0〜4096という整数です。ヘッダーのboundsが緯度経度だからといって、中身も緯度経度だと考えると合いません。 この二層構造と、地理院タイルとズームが1ずれる話はベクトルタイルの座標は緯度経度じゃない?で扱っています。

3. boundsが違うと「データはあるのに出ない」

Center PositionとCenter Zoomは、読み手が初期表示に使ってもよい値です(仕様上は任意)。Min/Max Positionも、読み手が「この外にはタイルがない」と判断する材料に使えます。boundsを実際のデータ範囲より狭く書くと、範囲外のタイルは存在していても取りに行かれません。 変換ツールが自動計算した値をそのまま信じる前に、出力後のヘッダーを一度読んで確かめるのが安全です。

4. Clusteredが立っていないとリクエストがまとまらない

Clustered が 0x00 のアーカイブは、タイルデータがTileID順に並んでいる保証がありません。クライアントは隣接タイルをまとめて取る最適化ができず、タイルごとのリクエストに戻ります。動かないわけではなく、遅くなります。 「ローカルでは気にならないのに公開すると重い」の一因になり得ます。

5. 読み取り専用。1枚の差し替えでも全体を書き直す

PMTilesは読み出し向けの形式で、公式ドキュメントも「アーカイブを変えるにはファイル全体を書き直す」と書いています。差分更新や都市単位の部分更新を頻繁に回す用途には向きません。更新が前提ならSQLiteやPostgreSQL(ST_AsMVT)側で持ち、PMTilesは配布用のスナップショットとして書き出すという分担になります。

6. Rangeリクエストに対応していない置き場では読めない

PMTilesの読み出しはHTTP Rangeリクエストが前提です。公式ドキュメントも、ローカルで試すときはRangeリクエストに対応したサーバ(例として http-server)を使うよう書いています。静的ホスティングやCDNの設定でRangeが通らないと、1ファイルから必要な部分だけ取るという仕組みそのものが成立しません。


標高タイルを入れるときの encoding

JSONメタデータの任意キー encoding に terrarium を指定すると、タイルの画素が標高(メートル)を表すことを示せます。復号の式は仕様に書かれています。

標高[m] = (red * 256 + green + blue / 256) - 32768

これが使えるのは可逆圧縮のラスタ画像に限られます。JPEGのような非可逆形式では画素値が変わってしまうので、標高が壊れます。PNGやWebPの可逆モードを選ぶ必要があります。

楕円体高・ジオイド高・標高のどれを入れたのかは、encoding では区別できません。高さの種別の取り違えはGeoJSONやKMLの高さは楕円体高か標高かで扱っている論点と同じで、形式が区別してくれない項目は、作る側が記録を残すしかありません。 description や attribution に書いておくのが現実的な落としどころです。


まとめ

  • PMTilesはZ/X/Yタイルのピラミッドを収める単一ファイルのアーカイブ。ヘッダーは127バイト固定、ルートディレクトリは先頭16,384バイト以内(圧縮後最大16,257バイト)
  • 位置(bounds・center)は度×10,000,000の符号付き32ビット整数で、経度4バイト+緯度4バイト。刻みは1e-7度(緯度方向で約1.1cm相当)
  • TileIDはズーム0から積み上げたヒルベルト曲線の通し番号。0/0/0=0、1/0/1=2、1/1/0=4、2/0/0=5
  • 連続する同一タイルはRunLengthでまとめる。検証データでは3億5,791万3,941枚 → 4,088万4,468エントリ
  • ディレクトリはvarint+デルタ+列転置+gzipで981.2MB → 91.6MB(9.3%)
  • 座標参照系を書くフィールドが仕様に存在しない。 COG・GeoParquet・FlatGeobufと違い、座標系はファイルの外の約束に委ねられている
  • だから、平面直角座標系のデータはタイル化の前に投影変換が必要。間違えてもファイルは何も教えてくれない
  • 読み取り専用・Rangeリクエスト前提。更新はほかの仕組みで持ち、PMTilesは配布用のスナップショットとして書き出す

JP-GeoConverter Pro は、平面直角座標系と緯度経度の相互変換、JGD2024系の各補正を端末内で実行できます。タイル化の前段で座標系をそろえる作業の確認に使えます。
アプリ: https://apps.apple.com/jp/app/geoconverter-pro/id6761740960

出典

  • PMTiles v3 仕様書(5区画の構成と並び順・ヘッダー127バイト固定とフィールド配置・ルートディレクトリの16,384バイト制約と圧縮後最大16,257バイト・圧縮とタイル種別の列挙・Positionの8バイト構成と度×10^7の符号付き32ビット整数・TileIDのヒルベルト曲線と0/0/0=0/1/0/1=2/1/1/0=4/2/0/0=5・Length>0・RunLength=0がリーフポインタ・ディレクトリの符号化手順・JSONメタデータの必須キーと任意キー・encoding: terrarium の復号式と可逆圧縮限定・CRSや投影法の規定が無いこと) https://github.com/protomaps/PMTiles/blob/main/spec/v3/spec.md
  • Protomaps ブログ「PMTiles version 3: Disk Layout and Compressed Directories」(clusteredフラグとヒルベルト順・ランレングスで357,913,941枚が40,884,468エントリになること・ディレクトリ圧縮の4段階とvarint/デルタ/列転置の効果・981.2MB→91.6MB(9.3%)と転置なしの102.0MB) https://protomaps.com/blog/pmtiles-v3-layout-compression/
  • Protomaps ドキュメント「PMTiles」(Z/X/Yで addressed されたタイルの単一ファイルアーカイブであること・読み取り専用で変更には全体の書き直しが必要・更新用途はSQLite/PostgreSQL(ST_AsMVT)・HTTP Rangeリクエストによる読み出し・ローカル検証にはRange対応サーバが必要・投影法やCRSの記述が無いこと) https://docs.protomaps.com/pmtiles/

本記事の仕様の記載は2026年10月時点のPMTiles v3仕様書と公式ドキュメントに基づきます。仕様は更新される場合があります。


次に確認する


開発者より: アプリ・Kindle本・公開プロジェクトの一覧は GitHub: amru195704 にまとめています。


お願い
本記事の情報は参考目的で掲載しており、正確性・完全性を保証するものではありません。誤記・不正確な情報がございましたら、コメント欄よりご指摘いただければ、確認のうえ修正いたします。


アプリを入手(App Store):JP-GeoConverter Pro(座標変換) | JP-GeoPrism(測地系の可視化・学習)


コメントを残す

メールアドレスが公開されることはありません。 ※ が付いている欄は必須項目です

トップへ戻る