Specification.ja

Wiki ▸ 仕様

[原文]

TopoJSON は GeoJSON の拡張形式です。TopoJSON は GeoJSON オブジェクトを格納するために "Topology" という新しい型を導入しました。 topology には objects マップが一つ含まれます（下例）。objects マップは複数のジオメトリオブジェクトを名前（下例の場合 aruba ）でインデックス付けして格納します。格納されているジオメトリオブジェクトが、ポリゴン、マルチ・ポリゴン、ジオメトリコレクションといった標準 GeoJSON オブジェクトになります。ただしジオメトリオブジェクトの座標は各オブジェトに含まれるのではなく、topology のarcs 配列に一括して格納されます。各 arc はラインストリングと同様の点の連なりです。複数の arc がまとめられることでジオメトリを作ります。Topojson には transform というプロパティがあります。これはデルタエンコードされた整数座標を、元の値（緯度や経度など）へ変換する方法を指定します。

例

次の例は Aruba島 を表すポリゴンジオメトリのオブジェトを含む完全な TopoJSONファイルです。

{
  "type": "Topology",
  "transform": {
    "scale": [0.036003600360036005, 0.017361589674592462],
    "translate": [-180, -89.99892578124998]
  },
  "objects": {
    "aruba": {
      "type": "Polygon",
      "arcs": [[0]],
      "id": 533
    }
  },
  "arcs": [
    [[3058, 5901], [0, -2], [-2, 1], [-1, 3], [-2, 3], [0, 3], [1, 1], [1, -3], [2, -5], [1, -1]]
  ]
}

他にもtopology test suite で豊富な例を紹介しています。

ジオメトリオブジェクト

TopoJSON のジオメトリオブジェクトは GeoJSON のものと基本同一ですが、座標の定義方法のみが異なっています。TopoJSONでは、座標は topology 内の arcs プロパティの配列として定義され、ゼロから始まるインデックスで参照されます。ラインストリングの定義方法の一例を挙げてみます。

{"type": "LineString", "arcs": [42]}

ここで 42 は topology.arcs[42] の arc を参照しています。ラインストリングの座標が単一の arc としてではなくarcs 配列 として定義されていることに注意してください。これは必要に応じ、複数の arcs を結合してラインストリングを作れるようにするためです（下例）。

{"type": "LineString", "arcs": [42, 43]}

同様に、穴のあるポリゴンは次のように定義できます。

{"type": "Polygon", "arcs": [[42, 43], [44]]}

このように複数の arc を結合する場合には、arc の最後の座標は、次の arc の最初の座標と一致している必要があります。arc 42 が A → B → C という点の並びで arc 43 の並びが C → D → E の場合、線ストリング [42, 43] は A → B → C → D → E という点の並びを表します。

多くの場合、共有 arc は反転させて使う必要が生じます。たとえばカリフォルニア州とネバダ州の州境を、カリフォルニア州側では南向きに、ネバダ州側では北向きに処理するような場合です。arc 内の座標の並びを反転させるには座標に負のインデックスを指定します。ただしゼロにマイナスはつけられないため、一つマイナスにずらして指定します。arc -1 は arc 0 の反転を表し、arc -2 は arc 1 の反転、以下同様となります。

ポイントとマルチポイントのジオメトリオブジェクトは、GeoJSON と同様に、arcs 内ではなく座標で直接記述されます。ただし、次節で述べるように、その座標は固定整数として記述され、 arcs と同様の方法で変換されなければなりません。

Arcs と座標

topology の arcs 配列は、実際のところマルチラインストリングそのものです。GeoJSON と同様、各ポイントは少なくとも二つの次元 ( x と y ) を持ちます。しかし GeoJSON とは異なり、TodoJSON の各座標はひとつ前のポイントからの相対座標である 整数値として記述されます。最初のポイントは、原点 (0, 0 ) からの相対座標となります。これを緯度と経度（あるいは絶対座標）に変換するために、topology は scale と translate で構成される transform で一次変換を定義します（下例）。

"transform": {
  "scale": [0.035896033450880604, 0.005251163636665131],
  "translate": [-179.14350338367416, 18.906117143691233]
}

相対整数座標から固定整数座標への変換のため、各 arc の繰り返し処理の際に相対差が累積されます。固定整数座標から絶対座標への変換には、scale で各座標を縮尺し、translate を加えて適切な座標とします。

function arcToCoordinates(topology, arc) {
  var x = 0, y = 0;
  return arc.map(function(point) {
    return [
      (x += point[0]) * topology.transform.scale[0] + topology.transform.translate[0],
      (y += point[1]) * topology.transform.scale[1] + topology.transform.translate[1]
    ];
  });
}

arc 座標には x、y 以外の座標を追加することもできます。こうした座標の扱いについては本仕様書の範疇を越えますが、一例を挙げると、ズームを変化させていっても動的単純化を維持できるように、各ポイントの視覚的重要性を各座標に保存して置くケースです。この値は Visvalingham アルゴリズムのような単純化アルゴリズムによって計算され、必要な場合、arc へのフィルター処理を高速に行えるようになります。

GeoJSON のポリゴンの配置順序が時計回り・反時計回りどちらでもよいのに対し、TopoJSON では半球上のすべてのポリゴンを時計回りに配置することを推奨しています。反時計回りに配置することは、ポリゴンをその半球からはみ出して配置することを意味します。

フィーチャー

TopoJSON は GeoJSON のフィーチャーもフィーチャーコレクションもサポートしていません。代わりにこれらのオブジェクトをそれぞれジオメトリとジオメトリコレクションへと変換します。さらに TopoJSON ではジオメトリオブジェクト内に直接識別子 (id) やプロパティを格納することもできます。 この単純化した記述法により、同一性を保ちつつずっと効率的なエンコードが可能となるのです。