TopoJSON-Viewer

Was dieser Viewer macht

TopoJSON ist ein kompakter Verwandter von GeoJSON. Jede gemeinsame Grenze wird nur einmal gespeichert, und Koordinaten werden meist als kleine ganze Zahlen geschrieben. Dadurch sind die Dateien viel kleiner, und deshalb nutzen D3.js-Karten, Wahlkarten und viele Datenjournalismus-Projekte das Format. Der Nachteil: Eine TopoJSON-Datei lässt sich nicht mit bloßem Auge lesen, und viele GIS-Programme und Webkarten können sie nicht ohne vorherige Umwandlung öffnen.

Dieser Viewer öffnet die Datei direkt. Ziehen Sie eine .topojson- oder .json-Datei auf die Karte, und er prüft, ob es wirklich eine Topologie ist, baut jede Form aus ihren Bögen (Arcs) neu auf und zeichnet jedes benannte Objekt als eigenen Layer in eigener Farbe. Die Seitenleiste zeigt, wie viele Objekte, Features und Bögen die Datei hat, ob sie quantisiert ist und wie fein ihr Raster ist, und wie viel größer dieselben Daten als normales GeoJSON wären. Klicken Sie auf ein Objekt, um seine Attribute zu lesen, einschließlich seiner TopoJSON-id.

Eine Funktion gibt es in einem normalen GeoJSON-Viewer nicht: „Highlight shared borders“. Sie zeichnet nur die Bögen, die zwei verschiedene Features teilen, direkt aus der Topologie. So prüfen Sie am schnellsten, ob eine Länder-, Kreis- oder Wahlkarte wirklich saubere gemeinsame Grenzen ohne Lücken oder Überlappungen hat. Wenn Sie die Daten in einem anderen Programm brauchen, laden Sie ein Objekt oder alle als GeoJSON herunter. Nichts wird hochgeladen: Die Datei verlässt nie Ihren Computer.

TopoJSON und GeoJSON im Vergleich

Beide Formate sind JSON, und beide beschreiben Punkte, Linien und Polygone mit Attributen. Der Unterschied liegt darin, wie sie die Koordinaten speichern.

Meine Faustregel: Nehmen Sie TopoJSON, wenn Sie viele aneinandergrenzende Polygone an einen Browser ausliefern, etwa Länder, Bundesländer oder Wahlkreise, und die Größe zählt. Für alles andere nehmen Sie GeoJSON, vor allem, wenn andere Menschen oder Programme die Daten bearbeiten.

Was in einer TopoJSON-Datei steckt

Eine TopoJSON-Datei ist ein einziges JSON-Objekt mit dem Typ "Topology". Das sind seine wichtigsten Bestandteile:

type

Immer "Topology". Eine Datei mit "FeatureCollection" ist GeoJSON, nicht TopoJSON.

objects

Ein Verzeichnis benannter Objekte, zum Beispiel countries und capitals. Jedes ist eine Geometrie oder eine GeometryCollection und wird in diesem Viewer ein Layer.

arcs

Die gemeinsame Liste der Linien. Polygone und Linien enthalten selbst keine Koordinaten, sondern die Nummern der Bögen, aus denen sie bestehen.

transform

Optional. Wenn vorhanden, ist die Datei quantisiert: Die Bogenpositionen sind ganze Zahlen, und scale und translate machen daraus wieder Länge und Breite.

bbox

Optional. Das umschließende Rechteck aller Daten als [min x, min y, max x, max y].

properties, id

Jede Geometrie kann properties (die Attribute) und eine id tragen, genau wie ein GeoJSON-Feature.

Hier ist eine vollständige, sehr kleine Topologie mit zwei quadratischen Feldern, die sich berühren. Mit genau diesem Beispiel rechnet auch der Mathematikteil weiter unten.

{
  "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]]
  ]
}

Feld A nutzt die Bögen 0 und 1. Feld B nutzt Bogen 2 und dann -1. Ein negativer Index bedeutet „diesen Bogen rückwärts verwenden“: -1 ist Bogen 0 umgekehrt, weil die Zahl das Einerkomplement ~0 ist. Die Grenze zwischen den Feldern (Bogen 0) steht nur einmal in der Datei.

Technische Details

Genau das liest und zeigt der Viewer.

Akzeptierte Dateien

.topojson- und .json-Dateien mit "type": "Topology", bis 100 MB. Bei einer GeoJSON-Datei erscheint ein klarer Hinweis auf den GeoJSON-Viewer.

Geometrietypen

Point, MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon und GeometryCollection, auch null-Geometrien (sie werden übersprungen).

Objekte

Jedes benannte Objekt wird ein eigener Layer mit Kontrollkästchen, Farbe, Geometrietyp, Anzahl der Features und Felder sowie einem GeoJSON-Download.

Quantisierte Dateien

Voll unterstützt. Der Viewer liest transform, dekodiert die delta-kodierten ganzen Zahlen und zeigt die Größe eines Rasterschritts im Gelände in Metern.

Gemeinsame Grenzen

Bei Objekten mit Polygonen baut der Viewer das Netz der Bögen, die zwei verschiedene Features nutzen (topojson.mesh mit a !== b), und kann es darüber zeichnen.

Attribute

Alle properties erscheinen im Popup. Eine TopoJSON-id wird als Attribut id ergänzt, damit Sie sie sehen und sie beim Export erhalten bleibt.

Koordinatensystem

TopoJSON für Webkarten liegt normalerweise in WGS84-Länge und -Breite vor. Dateien, die vor der Umwandlung projiziert wurden (etwa US Albers für eine D3-Karte), sind nicht in Grad und lassen sich nicht auf einer Weltkarte platzieren.

Export

Jedes Objekt als eigene GeoJSON-Datei, oder alle Objekte in einer GeoJSON-Datei mit dem Attribut topojson_object, das die Herkunft jedes Features nennt.

Basiskarte

Standardmäßig eine Straßenkarte, mit Satellitenoption. Setzen Sie die Füllung auf 0, um nur die Umrisse zu sehen.

Datenschutz

Die Datei wird in Ihrem Browser gelesen und dekodiert. Nichts wird an einen Server gesendet.

So zeigen Sie eine TopoJSON-Datei an, Schritt für Schritt

Hier ist der ganze Ablauf mit der eingebauten Beispieldatei: 50 europäische Länder aus Natural Earth und 22 Hauptstädte, gespeichert als eine quantisierte Topologie mit zwei Objekten.

1

Schritt 1: Viewer öffnen

Die Karte öffnet sich mit einer Straßenkarte. Nutzen Sie Upload, ziehen Sie eine Datei auf die Karte oder klicken Sie auf Sample Data.

2

Schritt 2: TopoJSON-Datei laden

Die Datei wird in Ihrem Browser dekodiert, und jedes Objekt erscheint in eigener Farbe. File Info zeigt die Anzahl der Objekte, Features und Bögen, den Quantisierungsschritt und wie groß dieselben Daten als GeoJSON wären.

3

Schritt 3: Mit den Objekten arbeiten

Der Bereich Objects listet jedes Objekt der Topologie mit Geometrietyp und Anzahl der Features. Entfernen Sie das Häkchen, um ein Objekt auszublenden, oder klicken Sie auf das Farbquadrat, um die Farbe zu ändern.

4

Schritt 4: Gemeinsame Grenzen hervorheben

Aktivieren Sie „Highlight shared borders“, um die Bögen zu zeichnen, die zwei verschiedene Features teilen, direkt aus der Topologie. Küstenlinien werden nicht geteilt und bleiben daher unverändert.

5

Schritt 5: Attribute lesen

Klicken Sie auf ein Feature, um seine Attribute zu öffnen. Das Popup nennt auch das Objekt, zu dem es gehört, und zeigt die TopoJSON-id.

6

Schritt 6: Als GeoJSON exportieren

Mit dem GeoJSON-Link neben einem Objekt laden Sie nur dieses Objekt herunter, mit Download All as GeoJSON alles in einer Datei.

Andere Wege, TopoJSON zu öffnen und umzuwandeln

Dieser Viewer ist für den schnellen Blick in eine Datei. Diese Werkzeuge nutze ich, wenn eine TopoJSON-Datei richtig bearbeitet werden muss.

Dieselben Aufgaben im Code

Diese Befehle wandeln eine Länderdatei in beide Richtungen um und lesen sie in JavaScript und 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")

Meine Meinung: Halten Sie Ihre Stammdaten in GeoJSON, GeoPackage oder Shapefile, und erzeugen Sie das TopoJSON als letzten Schritt für das Web. Es lässt sich leicht neu bauen, aber schlecht von Hand bearbeiten.

So arbeitet der Viewer

Das passiert zwischen dem Ablegen einer Datei und dem Bild auf der Karte. Jeder Schritt läuft in Ihrem Browser.

1. JSON lesen und prüfen. Die Datei wird als Text gelesen und geparst. Ist der oberste type nicht "Topology", oder fehlen objects oder arcs, erhalten Sie eine klare Fehlermeldung statt einer leeren Karte.
2. Bögen dekodieren. Hat die Datei ein transform, wird jeder Bogen von delta-kodierten ganzen Zahlen zurück in Länge und Breite umgerechnet. Ohne transform werden die Bogenpositionen so verwendet, wie sie sind.
3. Jedes Objekt neu aufbauen. Für jedes benannte Objekt fügt topojson.feature die referenzierten Bögen zu Ringen und Linien zusammen, dreht Bögen mit negativem Index um und liefert eine GeoJSON-FeatureCollection mit den ursprünglichen properties und ids.
4. Netz der gemeinsamen Grenzen bauen. Bei Objekten mit Polygonen sammelt topojson.mesh mit dem Filter a !== b jeden Bogen, der zu zwei verschiedenen Features gehört. Bögen, die nur ein Feature nutzt, etwa Küstenlinien, bleiben weg.
5. Datei vermessen. Der Viewer zählt Objekte, Features und Bögen, berechnet die Größe eines Quantisierungsschritts in Metern und misst, wie groß das dekodierte GeoJSON wäre.
6. Zeichnen und einpassen. Jedes Objekt wird ein Leaflet-Layer mit eigener Farbe. Punkte erscheinen als Kreise. Die Karte zoomt auf alle sichtbaren Daten.

Das Dekodieren selbst übernimmt topojson-client, die Referenzbibliothek vom Erfinder des Formats. Der Viewer liest Dateien also genau so wie D3-Karten.

Wie TopoJSON Dateien kleiner macht

TopoJSON spart auf drei Wegen Platz: gemeinsame Bögen, Quantisierung und Delta-Kodierung. Hier ist die Mathematik zu jedem Schritt, mit der Beispiel-Topologie von oben.

Index  i ≥ 0  →  Bogen i, vom ersten zum letzten Punkt
Index  i < 0  →  Bogen ~i = −i − 1, vom letzten zum ersten Punkt

Ring von Feld A:  [0, 1]    = Bogen 0, dann Bogen 1
Ring von Feld B:  [2, −1]   = Bogen 2, dann Bogen 0 umgekehrt

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

Länge  = x_ganzzahl · scale_x + translate_x
Breite = y_ganzzahl · scale_y + translate_y

gespeicherter Bogen:   [[4000, 7000], [0, 1000]]

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

mit scale [0.001, 0.001] und translate [−10, 40]:
Punkt 1:  (4000 · 0.001 − 10,  7000 · 0.001 + 40) = (−6, 47)
Punkt 2:  (4000 · 0.001 − 10,  8000 · 0.001 + 40) = (−6, 48)

Wann ein TopoJSON-Viewer hilft

In diesen Situationen greife ich zu einem schnellen TopoJSON-Viewer.

1. Eine Datei prüfen, bevor Sie eine D3-Karte bauen. Sehen Sie, welche Objekte eine heruntergeladene TopoJSON-Datei enthält, wie sie heißen und welche Attribute sie haben. Dann wissen Sie, was Sie in `topo.objects` schreiben, bevor Sie programmieren.
2. Grenzen nach dem Vereinfachen prüfen. Nach dem Vereinfachen einer Karte in mapshaper oder toposimplify zeigt „Highlight shared borders“, ob Nachbarn noch eine saubere gemeinsame Grenze ohne Lücken oder Splitter haben.
3. GeoJSON aus einer TopoJSON-Datei holen. Viele Webkarten und GIS-Programme nehmen nur GeoJSON. Laden Sie ein Objekt oder die ganze Datei als GeoJSON herunter, ohne etwas zu installieren.
4. Wahl- und Zensuskarten prüfen. Redaktionen veröffentlichen Wahlkreis- und Kreisgrenzen oft als TopoJSON. Öffnen Sie die Datei, um Namen, ids und Abdeckung zu prüfen, bevor Sie Ihre Ergebnisse damit verknüpfen.
5. Quantisierungsstufen vergleichen. Öffnen Sie dieselbe Karte mit verschiedenen Quantisierungen und vergleichen Sie Schrittweite in Metern und Dateigröße, um die kleinste Datei zu finden, die noch gut aussieht.
6. Topologie anschaulich erklären. Die Objektliste, die Zahl der Bögen und die Ansicht der gemeinsamen Grenzen zeigen Lernenden leicht, warum eine Topologie kleiner ist als normales GeoJSON.
7. Dateien aus world-atlas und us-atlas öffnen. Diese beliebten npm-Pakete liefern TopoJSON für Länder, US-Bundesstaaten und Countys. Öffnen Sie sie hier, um genau zu sehen, was sie enthalten.
8. Herausfinden, warum eine Datei nicht lädt. Wenn eine Kartenbibliothek an einer Datei scheitert, sagt Ihnen der Viewer, ob es wirklich TopoJSON ist, GeoJSON mit falscher Endung oder eine Datei mit kaputten Bogenverweisen.

Häufig gestellte Fragen

Bibliotheken und Daten

Dieser Viewer baut auf Open-Source-Software und offenen Daten auf. Vielen Dank an die Menschen hinter diesen Projekten.

• topojson-client 3.1 · ISC · Mike Bostock
  Dekodiert die Topologie: macht aus Bögen wieder Koordinaten, baut jedes Objekt als GeoJSON neu auf und erzeugt das Netz der gemeinsamen Grenzen.
• Leaflet 1.9 · BSD-2-Clause · Volodymyr Agafonkin and contributors
  Zeichnet die interaktive Karte, die Layer und die Popups.
• Natural Earth (1:50m Admin 0 countries) · Gemeinfrei · Natural Earth contributors
  Ländergrenzen in der Beispieldatei.
• OpenStreetMap, Protomaps (hosted by KONAKTIVE), CARTO, Esri World Imagery · ODbL und Nutzungsbedingungen des Anbieters · OpenStreetMap contributors, Protomaps, KONAKTIVE, CARTO, Esri
  Kacheln und Luftbilder der Basiskarte.

Verwandte Viewer für GIS-Dateien