TopoJSON ビューアー

このビューアーでできること

TopoJSONはGeoJSONのコンパクトな親戚です。共有する境界を1回だけ保存し、座標をふつう小さな整数で書きます。そのためファイルがとても小さくなり、D3.jsの地図、選挙地図、多くのデータジャーナリズムのプロジェクトで使われています。欠点は、TopoJSONファイルを目で見ても内容が読めないことと、多くのGISツールやWeb地図が変換なしでは開けないことです。

このビューアーはファイルを直接開きます。.topojsonまたは.jsonファイルを地図にドロップすると、本当にトポロジーかどうかを確かめ、アークから各図形を組み立て直し、名前の付いたオブジェクトごとに色を変えて別々のレイヤーとして描きます。サイドバーには、オブジェクト数、フィーチャ数、アーク数、量子化されているかとグリッドの細かさ、同じデータを普通のGeoJSONにした場合にどれだけ大きくなるかが表示されます。フィーチャをクリックすると、TopoJSONのidを含む属性が読めます。

普通のGeoJSONビューアーにはない機能を1つ加えました。「Highlight shared borders」です。2つの異なるフィーチャが共有するアークだけを、トポロジーから直接描きます。国、都道府県、選挙区の地図に、隙間や重なりのないきれいな共有境界が本当にあるかを確認する最も速い方法です。別のツールでデータが必要なときは、1つのオブジェクトまたはすべてをGeoJSONでダウンロードしてください。何もアップロードされず、ファイルがコンピューターから出ることはありません。

TopoJSONとGeoJSONの違い

どちらの形式もJSONで、どちらも属性付きのポイント、ライン、ポリゴンを表します。違いは座標の保存方法です。

私の目安です。国、州、選挙区のように接し合うポリゴンを大量にブラウザへ送り、サイズが重要な場合はTopoJSONを使います。それ以外、特に他の人やツールがデータを編集する場合はGeoJSONを使います。

TopoJSONファイルの中身

TopoJSONファイルは、typeが"Topology"の1つのJSONオブジェクトです。主なメンバーは次のとおりです。

type

常に "Topology"。"FeatureCollection" と書かれたファイルはTopoJSONではなくGeoJSONです。

objects

名前付きオブジェクトの辞書で、たとえば countries や capitals。それぞれがジオメトリまたは GeometryCollection で、このビューアーでは1つずつレイヤーになります。

arcs

共有のライン一覧です。ポリゴンやライン自体は座標を持たず、自分を作るアークの番号を並べます。

transform

省略可能。あるとファイルは量子化されています。アークの位置は整数で、scale と translate で経度・緯度に戻します。

bbox

省略可能。全データの外接矩形で、[最小 x, 最小 y, 最大 x, 最大 y] の形です。

properties, id

各ジオメトリは、GeoJSONのフィーチャと同じく properties（属性）と id を持てます。

これは、接し合う2つの正方形の畑を含む、ごく小さな完全なトポロジーです。下の数学のセクションで計算するのと同じ例です。

{
  "type": "Topology",
  "transform": { "scale": [0.001, 0.001], "translate": [-10, 40] },
  "objects": {
    "fields": {
      "type": "GeometryCollection",
      "geometries": [
        { "type": "Polygon", "arcs": [[0, 1]],  "properties": { "name": "A" } },
        { "type": "Polygon", "arcs": [[2, -1]], "properties": { "name": "B" } }
      ]
    }
  },
  "arcs": [
    [[4000, 7000], [0, 1000]],
    [[4000, 8000], [-1000, 0], [0, -1000], [1000, 0]],
    [[4000, 7000], [1000, 0], [0, 1000], [-1000, 0]]
  ]
}

畑Aはアーク 0 と 1 を使います。畑Bはアーク 2 と、続けて -1 を使います。負のインデックスは「このアークを逆向きに使う」という意味です。-1 は1の補数 ~0 なので、アーク0を逆にしたものです。畑どうしの境界（アーク0）は1回しか書かれていません。

技術的な詳細

ビューアーが読み込んで表示する内容を正確に説明します。

対応ファイル

"type": "Topology" を持つ .topojson と .json ファイル、100 MBまで。GeoJSONファイルの場合は、GeoJSONビューアーを案内するわかりやすいメッセージが出ます。

ジオメトリタイプ

Point、MultiPoint、LineString、MultiLineString、Polygon、MultiPolygon、GeometryCollection。nullのジオメトリにも対応します（スキップされます）。

オブジェクト

名前付きのオブジェクトはそれぞれ1つのレイヤーになり、チェックボックス、色、ジオメトリタイプ、フィーチャ数、フィールド数、GeoJSONのダウンロードが付きます。

量子化されたファイル

完全に対応しています。transform を読み、デルタ符号化された整数を復号し、グリッド1ステップの地上での大きさをメートルで表示します。

共有境界

ポリゴンを含むオブジェクトでは、2つの異なるフィーチャが使うアークのメッシュ（a !== b を指定した topojson.mesh）を作り、上に重ねて描けます。

属性

すべての properties がポップアップに表示されます。TopoJSONの id は属性 id として加えるので、画面で見られ、書き出しにも残ります。

座標系

Web地図用のTopoJSONはふつうWGS84の経度・緯度です。変換前に投影されたファイル（たとえばD3地図用のUS Albers）は度単位ではないので、世界地図の上には置けません。

書き出し

各オブジェクトを別々のGeoJSONファイルに、またはすべてのオブジェクトを1つのGeoJSONに。後者では、各フィーチャの出どころを示す属性 topojson_object が付きます。

ベースマップ

標準は道路地図で、衛星画像も選べます。塗りの不透明度を0にすると輪郭だけが見えます。

プライバシー

ファイルはブラウザ内で読み込まれ、復号されます。サーバーには何も送られません。

TopoJSONファイルを表示する手順

組み込みのサンプルで全体の流れを示します。Natural Earthのヨーロッパ50か国と22の首都を、2つのオブジェクトを持つ1つの量子化トポロジーとして保存したものです。

1

ステップ1: ビューアーを開く

地図は道路のベースマップ付きで開きます。Uploadを使うか、ファイルを地図にドラッグするか、Sample Dataをクリックします。

2

ステップ2: TopoJSONファイルを読み込む

ファイルはブラウザ内で復号され、各オブジェクトがそれぞれの色で描かれます。File Infoには、オブジェクト数、フィーチャ数、アーク数、量子化のステップ、同じデータをGeoJSONにした場合の大きさが表示されます。

3

ステップ3: オブジェクトを操作する

Objectsパネルには、トポロジー内の各オブジェクトがジオメトリタイプとフィーチャ数とともに並びます。チェックを外すと非表示になり、色の四角をクリックすると色を変えられます。

4

ステップ4: 共有境界を強調する

「Highlight shared borders」にチェックを入れると、2つの異なるフィーチャが共有するアークを、トポロジーそのものから描きます。海岸線は共有されていないので、そのままです。

5

ステップ5: 属性を読む

フィーチャをクリックすると属性が開きます。ポップアップには、そのフィーチャが属するオブジェクト名とTopoJSONのidも表示されます。

6

ステップ6: GeoJSONに書き出す

オブジェクトの横にあるGeoJSONリンクでそのオブジェクトだけを、Download All as GeoJSONですべてを1つのファイルでダウンロードします。

TopoJSONを開いて変換するほかの方法

このビューアーはファイルをすばやく確認するためのものです。TopoJSONファイルで本格的な作業が必要なときは、次のツールを使います。

同じ作業をコードで

次のコマンドは国のファイルを双方向に変換し、JavaScriptとPythonで読み込みます。

# mapshaper (npm install -g mapshaper)
mapshaper countries.shp -o format=topojson quantization=1e5 countries.topojson
mapshaper countries.topojson -o format=geojson countries.geojson

# topojson-server / topojson-client command line tools
geo2topo countries=countries.geojson > countries.topojson
topo2geo countries=countries.geojson < countries.topojson

# GDAL / OGR: each TopoJSON object becomes its own layer
ogrinfo countries.topojson
ogr2ogr -f GeoJSON countries.geojson countries.topojson countries

// D3.js + topojson-client in the browser
const topo = await d3.json("countries.topojson");
const countries = topojson.feature(topo, topo.objects.countries);
const borders = topojson.mesh(topo, topo.objects.countries, (a, b) => a !== b);

# Python: GeoPandas reads TopoJSON through GDAL, one object at a time
import geopandas as gpd
countries = gpd.read_file("countries.topojson", layer="countries")

私の考えでは、元データはGeoJSON、GeoPackage、Shapefileで管理し、TopoJSONはWeb向けの最後のステップで作るのがよいです。作り直すのは簡単ですが、手で編集するのは大変だからです。

ビューアーの仕組み

ファイルをドロップしてから地図に表示されるまでの流れです。すべてのステップはブラウザ内で動きます。

1. JSONを読み込んで確認する. ファイルをテキストとして読み込み、解析します。最上位の type が "Topology" でない場合や、objects や arcs がない場合は、空の地図ではなくわかりやすいエラーを表示します。
2. アークを復号する. ファイルに transform があれば、各アークをデルタ符号化された整数から経度・緯度に戻します。transformがなければ、アークの位置をそのまま使います。
3. 各オブジェクトを組み立て直す. 名前付きのオブジェクトごとに、topojson.feature が参照されたアークをつないでリングやラインにし、負のインデックスのアークを逆向きにし、元のpropertiesとidを持つGeoJSONのFeatureCollectionを返します。
4. 共有境界のメッシュを作る. ポリゴンを含むオブジェクトでは、フィルター a !== b を指定した topojson.mesh が、2つの異なるフィーチャに属するアークをすべて集めます。海岸線のように1つのフィーチャしか使わないアークは除かれます。
5. ファイルを測る. オブジェクト、フィーチャ、アークの数を数え、量子化1ステップの大きさをメートルで求め、復号したGeoJSONがどれだけの大きさになるかを測ります。
6. 描いて表示範囲を合わせる. 各オブジェクトはそれぞれの色のLeafletレイヤーになります。ポイントは円で描きます。地図は表示中のすべてのデータにズームします。

復号そのものは、形式の考案者が書いたリファレンスライブラリのtopojson-clientが行います。そのため、このビューアーはD3の地図とまったく同じようにファイルを読み込みます。

TopoJSONがファイルを小さくする仕組み

TopoJSONは、アークの共有、量子化、デルタ符号化という3つの方法で容量を節約します。上のサンプルのトポロジーを使って、それぞれの計算を説明します。

インデックス  i ≥ 0  →  アーク i、最初の点から最後の点へ
インデックス  i < 0  →  アーク ~i = −i − 1、最後の点から最初の点へ

畑Aのリング:  [0, 1]    = アーク0、続いてアーク1
畑Bのリング:  [2, −1]   = アーク2、続いて逆向きのアーク0

scale_x = (x_max − x_min) / (q − 1)
scale_y = (y_max − y_min) / (q − 1)

経度 = x_整数 · scale_x + translate_x
緯度 = y_整数 · scale_y + translate_y

保存されたアーク:   [[4000, 7000], [0, 1000]]

点1:  x = 4000             y = 7000
点2:  x = 4000 + 0 = 4000  y = 7000 + 1000 = 8000

scale [0.001, 0.001] と translate [−10, 40] を使うと:
点1:  (4000 · 0.001 − 10,  7000 · 0.001 + 40) = (−6, 47)
点2:  (4000 · 0.001 − 10,  8000 · 0.001 + 40) = (−6, 48)

TopoJSONビューアーが役立つ場面

私が手早くTopoJSONビューアーを使うのは、次のような場面です。

1. D3の地図を作る前にファイルを確認する. ダウンロードしたTopoJSONファイルにどんなオブジェクトがあり、どんな名前で、どんな属性を持つかを確認できます。コードを書き始める前に、`topo.objects` に何を書けばよいかがわかります。
2. 単純化した後の境界を確認する. mapshaperやtoposimplifyで地図を単純化した後、「Highlight shared borders」をオンにして、隣同士が隙間や細い破片のないきれいな境界を今も共有しているかを確認します。
3. TopoJSONファイルからGeoJSONを取り出す. 多くのWeb地図やGISツールはGeoJSONしか受け付けません。何もインストールせずに、1つのオブジェクトまたはファイル全体をGeoJSONでダウンロードできます。
4. 選挙や国勢調査の地図を確認する. 報道機関は選挙区や市区町村の境界をTopoJSONで公開することがよくあります。結果を結合する前に、ファイルを開いて名前、id、範囲を確認できます。
5. 量子化レベルを比べる. 量子化の設定を変えて作った同じ地図を開き、メートル単位のステップとファイルサイズを比べて、見た目を保てる最小のファイルを選べます。
6. トポロジーの仕組みを教える. オブジェクトの一覧、アークの数、共有境界の表示を使うと、トポロジーが普通のGeoJSONより小さい理由を学生に簡単に示せます。
7. world-atlasとus-atlasのファイルを開く. これらの人気のnpmパッケージには、国、米国の州、郡のTopoJSONが入っています。ここで開くと中身が正確にわかります。
8. ファイルが読み込めない理由を調べる. 地図ライブラリがファイルの読み込みに失敗したとき、本当にTopoJSONなのか、拡張子が違うだけのGeoJSONなのか、アークの参照が壊れたファイルなのかをビューアーが教えてくれます。

よくある質問

ライブラリとデータ

このビューアーはオープンソースソフトウェアとオープンデータの上に作られています。これらのプロジェクトに関わる皆さんに感謝します。

• topojson-client 3.1 · ISC · Mike Bostock
  トポロジーを復号します。アークを座標に戻し、各オブジェクトをGeoJSONとして組み立て直し、共有境界のメッシュを作ります。
• Leaflet 1.9 · BSD-2-Clause · Volodymyr Agafonkin and contributors
  インタラクティブな地図、レイヤー、ポップアップを描きます。
• Natural Earth (1:50m Admin 0 countries) · パブリックドメイン · Natural Earth contributors
  サンプルファイルで使っている国境データ。
• OpenStreetMap, Protomaps (hosted by KONAKTIVE), CARTO, Esri World Imagery · ODbLと提供元の利用規約 · OpenStreetMap contributors, Protomaps, KONAKTIVE, CARTO, Esri
  ベースマップのタイルと画像。

関連するGISファイルビューアー