Visualizzatore TopoJSON

Cosa fa questo visualizzatore

TopoJSON è un parente compatto di GeoJSON. Salva ogni confine condiviso una sola volta e di solito scrive le coordinate come piccoli numeri interi. Così i file sono molto più piccoli, ed è per questo che lo usano le mappe D3.js, le mappe elettorali e molti progetti di giornalismo dei dati. Lo svantaggio è che un file TopoJSON non si legge a occhio, e molti strumenti GIS e mappe web non lo aprono senza convertirlo prima.

Questo visualizzatore apre il file direttamente. Trascina un file .topojson o .json sulla mappa: lo strumento controlla che sia davvero una topologia, ricostruisce ogni forma dai suoi archi e disegna ogni oggetto con nome come un layer separato con il suo colore. La barra laterale mostra quanti oggetti, elementi e archi ha il file, se è quantizzato e quanto è fine la sua griglia, e quanto sarebbero più grandi gli stessi dati in GeoJSON normale. Clicca su un elemento per leggerne gli attributi, compreso il suo id TopoJSON.

Ho aggiunto una funzione che non trovi in un normale visualizzatore GeoJSON: "Highlight shared borders". Disegna solo gli archi che due elementi diversi condividono, direttamente dalla topologia. È il modo più veloce per controllare che una mappa di paesi, province o collegi elettorali abbia davvero confini condivisi puliti, senza vuoti né sovrapposizioni. Quando ti servono i dati in un altro strumento, scarica un oggetto o tutti in GeoJSON. Non viene caricato nulla: il file non lascia mai il tuo computer.

TopoJSON e GeoJSON a confronto

Entrambi i formati sono JSON ed entrambi descrivono punti, linee e poligoni con attributi. La differenza sta nel modo in cui salvano le coordinate.

La mia regola pratica: usa TopoJSON quando invii a un browser molti poligoni che si toccano, come paesi, regioni o collegi, e la dimensione conta. Usa GeoJSON per tutto il resto, soprattutto quando altre persone o strumenti modificheranno i dati.

Cosa c'è dentro un file TopoJSON

Un file TopoJSON è un unico oggetto JSON con il tipo "Topology". Questi sono i suoi membri principali:

type

Sempre "Topology". Un file che dice "FeatureCollection" è GeoJSON, non TopoJSON.

objects

Un dizionario di oggetti con nome, per esempio countries e capitals. Ognuno è una geometria o una GeometryCollection, e ognuno diventa un layer in questo visualizzatore.

arcs

L'elenco condiviso delle linee. Poligoni e linee non contengono coordinate proprie: elencano i numeri degli archi che li formano.

transform

Facoltativo. Se presente, il file è quantizzato: le posizioni degli archi sono interi, e scale e translate li riportano a longitudine e latitudine.

bbox

Facoltativo. Il riquadro di delimitazione di tutti i dati, come [min x, min y, max x, max y].

properties, id

Ogni geometria può avere properties (gli attributi) e un id, proprio come un elemento GeoJSON.

Ecco una topologia completa e molto piccola, con due campi quadrati che si toccano. È lo stesso esempio che la sezione di matematica qui sotto risolve.

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

Il campo A usa gli archi 0 e 1. Il campo B usa l'arco 2 e poi -1. Un indice negativo significa "usa questo arco al contrario": -1 è l'arco 0 invertito, perché il numero è il complemento a uno ~0. Il confine tra i campi (arco 0) è scritto una sola volta.

Dettagli tecnici

Ecco esattamente cosa legge e mostra il visualizzatore.

File accettati

File .topojson e .json con "type": "Topology", fino a 100 MB. Un file GeoJSON riceve un messaggio chiaro che ti indirizza al Visualizzatore GeoJSON.

Tipi di geometria

Point, MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon e GeometryCollection, comprese le geometrie null (vengono saltate).

Oggetti

Ogni oggetto con nome diventa un layer a sé, con casella, colore, tipo di geometria, numero di elementi e di campi, e un download in GeoJSON.

File quantizzati

Supportati del tutto. Il visualizzatore legge transform, decodifica gli interi codificati come delta e mostra la dimensione di un passo della griglia sul terreno, in metri.

Confini condivisi

Per gli oggetti con poligoni, il visualizzatore costruisce la rete degli archi usati da due elementi diversi (topojson.mesh con a !== b) e può disegnarla sopra.

Attributi

Tutte le properties compaiono nel popup. Un id TopoJSON viene aggiunto come attributo id, così lo vedi e resta anche nell'esportazione.

Sistema di coordinate

Il TopoJSON per le mappe web di solito è in longitudine e latitudine WGS84. I file proiettati prima della conversione (per esempio US Albers per una mappa D3) non sono in gradi e non si possono collocare su una mappa del mondo.

Esportazione

Ogni oggetto in un proprio file GeoJSON, oppure tutti gli oggetti in un solo GeoJSON con un attributo topojson_object che indica da dove viene ogni elemento.

Mappa di base

Mappa stradale come impostazione predefinita, con opzione satellitare. Porta l'opacità di riempimento a 0 per vedere solo i contorni.

Privacy

Il file viene letto e decodificato nel tuo browser. Non viene inviato nulla a un server.

Come visualizzare un file TopoJSON, passo dopo passo

Ecco tutto il flusso con l'esempio incluso: 50 paesi europei di Natural Earth e 22 capitali, salvati come un'unica topologia quantizzata con due oggetti.

1

Passo 1: Apri il visualizzatore

La mappa si apre con una mappa stradale di base. Usa Upload, trascina un file sulla mappa oppure clicca su Sample Data.

2

Passo 2: Carica un file TopoJSON

Il file viene decodificato nel tuo browser e ogni oggetto viene disegnato con il suo colore. File Info mostra il numero di oggetti, elementi e archi, il passo di quantizzazione e quanto sarebbero grandi gli stessi dati in GeoJSON.

3

Passo 3: Lavora con gli oggetti

Il pannello Objects elenca ogni oggetto della topologia con il tipo di geometria e il numero di elementi. Togli la spunta per nascondere un oggetto, oppure clicca sul quadratino del colore per cambiarlo.

4

Passo 4: Evidenzia i confini condivisi

Spunta "Highlight shared borders" per disegnare gli archi che due elementi diversi condividono, ricavati dalla topologia stessa. Le coste non sono condivise, quindi restano semplici.

5

Passo 5: Leggi gli attributi

Clicca su qualsiasi elemento per aprirne gli attributi. Il popup indica anche l'oggetto a cui appartiene e mostra l'id TopoJSON.

6

Passo 6: Esporta in GeoJSON

Usa il link GeoJSON accanto a un oggetto per scaricare solo quell'oggetto, oppure Download All as GeoJSON per avere tutto in un file.

Altri modi per aprire e convertire TopoJSON

Questo visualizzatore serve per guardare un file in fretta. Questi sono gli altri strumenti che uso quando un file TopoJSON richiede un lavoro vero.

Gli stessi lavori in codice

Questi comandi convertono un file di paesi in entrambe le direzioni e lo leggono in JavaScript e in 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")

Il mio parere: tieni i tuoi dati principali in GeoJSON, GeoPackage o Shapefile, e crea il TopoJSON come ultimo passo per il web. È facile da ricreare, ma difficile da modificare a mano.

Come funziona il visualizzatore

Ecco cosa succede tra il momento in cui lasci cadere un file e quello in cui lo vedi sulla mappa. Ogni passo avviene nel tuo browser.

1. Leggere e controllare il JSON. Il file viene letto come testo e analizzato. Se il type di primo livello non è "Topology", o mancano objects o arcs, ricevi un errore chiaro invece di una mappa vuota.
2. Decodificare gli archi. Se il file ha un transform, ogni arco viene decodificato dagli interi codificati come delta a longitudine e latitudine. Senza transform, le posizioni degli archi si usano così come sono.
3. Ricostruire ogni oggetto. Per ogni oggetto con nome, topojson.feature unisce gli archi richiamati in anelli e linee, inverte gli archi con indice negativo e restituisce una FeatureCollection GeoJSON con le properties e gli id originali.
4. Costruire la rete dei confini condivisi. Per gli oggetti con poligoni, topojson.mesh con il filtro a !== b raccoglie ogni arco che appartiene a due elementi diversi. Gli archi usati da un solo elemento, come le coste, restano fuori.
5. Misurare il file. Il visualizzatore conta oggetti, elementi e archi, calcola la dimensione di un passo di quantizzazione in metri e misura quanto sarebbe grande il GeoJSON decodificato.
6. Disegnare e inquadrare. Ogni oggetto diventa un layer Leaflet con il suo colore. I punti sono disegnati come cerchi. La mappa fa zoom su tutti i dati visibili.

La decodifica vera e propria la fa topojson-client, la libreria di riferimento scritta dal creatore del formato, quindi il visualizzatore legge i file esattamente come le mappe D3.

Come TopoJSON rende i file più piccoli

TopoJSON risparmia spazio in tre modi: archi condivisi, quantizzazione e codifica delta. Ecco la matematica di ciascuno, con la topologia di esempio vista sopra.

indice  i ≥ 0  →  arco i, dal primo all'ultimo punto
indice  i < 0  →  arco ~i = −i − 1, dall'ultimo al primo punto

Anello del campo A:  [0, 1]    = arco 0, poi arco 1
Anello del campo B:  [2, −1]   = arco 2, poi arco 0 invertito

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

longitudine = x_intero · scale_x + translate_x
latitudine  = y_intero · scale_y + translate_y

arco salvato:   [[4000, 7000], [0, 1000]]

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

con scale [0.001, 0.001] e translate [−10, 40]:
punto 1:  (4000 · 0.001 − 10,  7000 · 0.001 + 40) = (−6, 47)
punto 2:  (4000 · 0.001 − 10,  8000 · 0.001 + 40) = (−6, 48)

Quando serve un visualizzatore TopoJSON

Queste sono le situazioni in cui uso un visualizzatore TopoJSON veloce.

1. Controllare un file prima di creare una mappa D3. Guarda quali oggetti contiene un file TopoJSON scaricato, come si chiamano e quali attributi hanno, così sai cosa scrivere in `topo.objects` prima di iniziare a programmare.
2. Controllare i confini dopo la semplificazione. Dopo aver semplificato una mappa con mapshaper o toposimplify, attiva "Highlight shared borders" per verificare che i vicini condividano ancora un confine pulito, senza vuoti né schegge.
3. Ricavare GeoJSON da un file TopoJSON. Molte mappe web e strumenti GIS accettano solo GeoJSON. Scarica un oggetto o l'intero file in GeoJSON senza installare nulla.
4. Controllare mappe elettorali e di censimento. Le redazioni pubblicano spesso i confini di collegi e comuni in TopoJSON. Apri il file per controllare nomi, id e copertura prima di unire i tuoi risultati.
5. Confrontare livelli di quantizzazione. Apri la stessa mappa creata con quantizzazioni diverse e confronta il passo in metri e la dimensione del file, per scegliere il file più piccolo che ha ancora un buon aspetto.
6. Spiegare come funziona la topologia. L'elenco degli oggetti, il numero di archi e la vista dei confini condivisi rendono facile mostrare agli studenti perché una topologia pesa meno del GeoJSON normale.
7. Aprire i file dei pacchetti world-atlas e us-atlas. Questi popolari pacchetti npm contengono TopoJSON di paesi, stati e contee degli Stati Uniti. Aprili qui per vedere esattamente cosa contengono.
8. Capire perché un file non si carica. Se una libreria di mappe non riesce ad aprire un file, il visualizzatore ti dice se è davvero TopoJSON, un GeoJSON con l'estensione sbagliata o un file con riferimenti agli archi rotti.

Domande frequenti

Librerie e dati

Questo visualizzatore è costruito su software open source e dati aperti. Grazie alle persone dietro questi progetti.

• topojson-client 3.1 · ISC · Mike Bostock
  Decodifica la topologia: riporta gli archi a coordinate, ricostruisce ogni oggetto in GeoJSON e costruisce la rete dei confini condivisi.
• Leaflet 1.9 · BSD-2-Clause · Volodymyr Agafonkin and contributors
  Disegna la mappa interattiva, i layer e i popup.
• Natural Earth (1:50m Admin 0 countries) · Pubblico dominio · Natural Earth contributors
  Confini dei paesi usati nel file di esempio.
• OpenStreetMap, Protomaps (hosted by KONAKTIVE), CARTO, Esri World Imagery · ODbL e condizioni del fornitore · OpenStreetMap contributors, Protomaps, KONAKTIVE, CARTO, Esri
  Tile e immagini della mappa di base.

Visualizzatori di file GIS correlati