Visionneuse TopoJSON

Ce que fait cette visionneuse

TopoJSON est un cousin compact de GeoJSON. Il enregistre chaque frontière partagée une seule fois et écrit en général les coordonnées sous forme de petits nombres entiers. Les fichiers sont donc beaucoup plus petits, et c'est pour cela que les cartes D3.js, les cartes électorales et de nombreux projets de journalisme de données l'utilisent. L'inconvénient : un fichier TopoJSON ne se lit pas à l'œil nu, et beaucoup d'outils SIG et de cartes web ne savent pas l'ouvrir sans le convertir d'abord.

Cette visionneuse ouvre le fichier directement. Déposez un fichier .topojson ou .json sur la carte : elle vérifie qu'il s'agit bien d'une topologie, reconstruit chaque forme à partir de ses arcs et dessine chaque objet nommé comme une couche séparée, avec sa propre couleur. Le panneau latéral indique combien d'objets, d'entités et d'arcs contient le fichier, s'il est quantifié et quelle est la finesse de sa grille, et combien les mêmes données pèseraient de plus en GeoJSON classique. Cliquez sur une entité pour lire ses attributs, y compris son id TopoJSON.

J'ai ajouté une fonction absente des visionneuses GeoJSON classiques : « Highlight shared borders ». Elle dessine uniquement les arcs que partagent deux entités différentes, directement à partir de la topologie. C'est le moyen le plus rapide de vérifier qu'une carte de pays, de départements ou de circonscriptions a vraiment des frontières partagées propres, sans trous ni chevauchements. Quand il vous faut les données dans un autre outil, téléchargez un objet ou tous en GeoJSON. Rien n'est envoyé : le fichier ne quitte jamais votre ordinateur.

TopoJSON ou GeoJSON

Les deux formats sont du JSON, et les deux décrivent des points, des lignes et des polygones avec des attributs. La différence tient à la façon dont ils stockent les coordonnées.

Ma règle pratique : utilisez TopoJSON quand vous envoyez à un navigateur beaucoup de polygones qui se touchent, comme des pays, des régions ou des circonscriptions, et que la taille compte. Utilisez GeoJSON pour tout le reste, surtout quand d'autres personnes ou outils vont modifier les données.

Ce que contient un fichier TopoJSON

Un fichier TopoJSON est un seul objet JSON de type "Topology". Voici ses principaux membres :

type

Toujours "Topology". Un fichier qui indique "FeatureCollection" est du GeoJSON, pas du TopoJSON.

objects

Un dictionnaire d'objets nommés, par exemple countries et capitals. Chacun est une géométrie ou une GeometryCollection, et chacun devient une couche dans cette visionneuse.

arcs

La liste partagée des lignes. Les polygones et les lignes ne contiennent pas de coordonnées eux-mêmes : ils listent les numéros des arcs qui les forment.

transform

Facultatif. S'il est présent, le fichier est quantifié : les positions des arcs sont des entiers, et scale et translate les ramènent en longitude et latitude.

bbox

Facultatif. Le rectangle englobant de toutes les données, sous la forme [min x, min y, max x, max y].

properties, id

Chaque géométrie peut porter des properties (les attributs) et un id, comme une entité GeoJSON.

Voici une topologie complète et très petite, avec deux champs carrés qui se touchent. C'est le même exemple que la section de mathématiques plus bas détaille.

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

Le champ A utilise les arcs 0 et 1. Le champ B utilise l'arc 2 puis -1. Un indice négatif veut dire « utiliser cet arc à l'envers » : -1 est l'arc 0 inversé, car le nombre est le complément à un ~0. La frontière entre les champs (arc 0) n'est écrite qu'une fois.

Détails techniques

Voici exactement ce que la visionneuse lit et affiche.

Fichiers acceptés

Fichiers .topojson et .json avec "type": "Topology", jusqu'à 100 Mo. Un fichier GeoJSON reçoit un message clair qui vous renvoie vers la Visionneuse GeoJSON.

Types de géométrie

Point, MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon et GeometryCollection, y compris les géométries null (elles sont ignorées).

Objets

Chaque objet nommé devient sa propre couche, avec case à cocher, couleur, type de géométrie, nombre d'entités et de champs, et un téléchargement en GeoJSON.

Fichiers quantifiés

Pris en charge complètement. La visionneuse lit transform, décode les entiers codés en delta et affiche la taille d'un pas de grille sur le terrain, en mètres.

Frontières partagées

Pour les objets avec des polygones, la visionneuse construit le maillage des arcs utilisés par deux entités différentes (topojson.mesh avec a !== b) et peut le dessiner par-dessus.

Attributs

Toutes les properties s'affichent dans la fenêtre. Un id TopoJSON est ajouté comme attribut id, pour que vous le voyiez et qu'il reste dans l'export.

Système de coordonnées

Le TopoJSON pour les cartes web est en général en longitude et latitude WGS84. Les fichiers projetés avant la conversion (par exemple en US Albers pour une carte D3) ne sont pas en degrés et ne peuvent pas être placés sur une carte du monde.

Export

Chaque objet dans son propre fichier GeoJSON, ou tous les objets dans un seul GeoJSON avec un attribut topojson_object qui indique l'origine de chaque entité.

Fond de carte

Carte routière par défaut, avec une option satellite. Mettez l'opacité de remplissage à 0 pour ne voir que les contours.

Confidentialité

Le fichier est lu et décodé dans votre navigateur. Rien n'est envoyé à un serveur.

Comment afficher un fichier TopoJSON, étape par étape

Voici tout le déroulé avec l'exemple intégré : 50 pays européens issus de Natural Earth et 22 capitales, enregistrés dans une seule topologie quantifiée à deux objets.

1

Étape 1: Ouvrir la visionneuse

La carte s'ouvre avec un fond routier. Utilisez Upload, glissez un fichier sur la carte ou cliquez sur Sample Data.

2

Étape 2: Charger un fichier TopoJSON

Le fichier est décodé dans votre navigateur et chaque objet est dessiné dans sa couleur. File Info indique le nombre d'objets, d'entités et d'arcs, le pas de quantification et la taille qu'auraient les mêmes données en GeoJSON.

3

Étape 3: Travailler avec les objets

Le panneau Objects liste chaque objet de la topologie avec son type de géométrie et son nombre d'entités. Décochez un objet pour le masquer, ou cliquez sur son carré de couleur pour la changer.

4

Étape 4: Mettre en avant les frontières partagées

Cochez « Highlight shared borders » pour dessiner les arcs partagés par deux entités différentes, construits à partir de la topologie elle-même. Les côtes ne sont pas partagées, elles restent donc simples.

5

Étape 5: Lire les attributs

Cliquez sur une entité pour ouvrir ses attributs. La fenêtre indique aussi l'objet auquel elle appartient et affiche l'id TopoJSON.

6

Étape 6: Exporter en GeoJSON

Utilisez le lien GeoJSON à côté d'un objet pour télécharger seulement cet objet, ou Download All as GeoJSON pour tout avoir dans un fichier.

Autres façons d'ouvrir et de convertir du TopoJSON

Cette visionneuse sert à regarder un fichier rapidement. Voici les autres outils que j'utilise quand un fichier TopoJSON demande un vrai travail.

Les mêmes tâches en code

Ces commandes convertissent un fichier de pays dans les deux sens et le lisent en JavaScript et en 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")

Mon avis : gardez vos données de référence en GeoJSON, GeoPackage ou Shapefile, et créez le TopoJSON en dernière étape pour le web. Il se reconstruit facilement, mais se modifie mal à la main.

Comment fonctionne la visionneuse

Voici ce qui se passe entre le dépôt d'un fichier et son affichage sur la carte. Chaque étape se déroule dans votre navigateur.

1. Lire et vérifier le JSON. Le fichier est lu comme du texte puis analysé. Si le type de premier niveau n'est pas "Topology", ou s'il manque objects ou arcs, vous recevez un message d'erreur clair au lieu d'une carte vide.
2. Décoder les arcs. Si le fichier a un transform, chaque arc est décodé des entiers codés en delta vers la longitude et la latitude. Sans transform, les positions des arcs sont utilisées telles quelles.
3. Reconstruire chaque objet. Pour chaque objet nommé, topojson.feature assemble les arcs référencés en anneaux et en lignes, inverse les arcs d'indice négatif et renvoie une FeatureCollection GeoJSON avec les properties et les id d'origine.
4. Construire le maillage des frontières partagées. Pour les objets avec des polygones, topojson.mesh avec le filtre a !== b réunit chaque arc qui appartient à deux entités différentes. Les arcs utilisés par une seule entité, comme les côtes, sont laissés de côté.
5. Mesurer le fichier. La visionneuse compte les objets, les entités et les arcs, calcule la taille d'un pas de quantification en mètres et mesure la taille qu'aurait le GeoJSON décodé.
6. Dessiner et cadrer. Chaque objet devient une couche Leaflet avec sa propre couleur. Les points sont dessinés en cercles. La carte zoome sur toutes les données visibles.

Le décodage lui-même est fait par topojson-client, la bibliothèque de référence écrite par le créateur du format, donc la visionneuse lit les fichiers exactement comme les cartes D3.

Comment TopoJSON réduit la taille des fichiers

TopoJSON gagne de la place de trois façons : arcs partagés, quantification et codage delta. Voici les mathématiques de chacune, avec la topologie d'exemple ci-dessus.

indice  i ≥ 0  →  arc i, du premier au dernier point
indice  i < 0  →  arc ~i = −i − 1, du dernier au premier point

Anneau du champ A :  [0, 1]    = arc 0, puis arc 1
Anneau du champ B :  [2, −1]   = arc 2, puis arc 0 inversé

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

longitude = x_entier · scale_x + translate_x
latitude  = y_entier · scale_y + translate_y

arc enregistré :   [[4000, 7000], [0, 1000]]

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

avec scale [0.001, 0.001] et translate [−10, 40] :
point 1 :  (4000 · 0.001 − 10,  7000 · 0.001 + 40) = (−6, 47)
point 2 :  (4000 · 0.001 − 10,  8000 · 0.001 + 40) = (−6, 48)

Quand une visionneuse TopoJSON est utile

Voici les situations où j'utilise une visionneuse TopoJSON rapide.

1. Vérifier un fichier avant de créer une carte D3. Voyez quels objets contient un fichier TopoJSON téléchargé, comment ils s'appellent et quels attributs ils ont, pour savoir quoi écrire dans `topo.objects` avant de coder.
2. Vérifier les frontières après simplification. Après avoir simplifié une carte dans mapshaper ou toposimplify, activez « Highlight shared borders » pour confirmer que les voisins partagent toujours une frontière propre, sans trous ni éclats.
3. Sortir du GeoJSON d'un fichier TopoJSON. Beaucoup de cartes web et d'outils SIG n'acceptent que le GeoJSON. Téléchargez un objet ou le fichier entier en GeoJSON sans rien installer.
4. Contrôler des cartes électorales et de recensement. Les rédactions publient souvent les limites de circonscriptions et de communes en TopoJSON. Ouvrez le fichier pour contrôler les noms, les id et la couverture avant d'y joindre vos résultats.
5. Comparer des niveaux de quantification. Ouvrez la même carte construite avec différentes quantifications et comparez le pas en mètres et la taille du fichier, pour choisir le plus petit fichier qui reste beau.
6. Expliquer le fonctionnement d'une topologie. La liste des objets, le nombre d'arcs et la vue des frontières partagées permettent de montrer facilement aux élèves pourquoi une topologie pèse moins que du GeoJSON classique.
7. Ouvrir les fichiers des paquets world-atlas et us-atlas. Ces paquets npm populaires contiennent du TopoJSON pour les pays, les États et les comtés des États-Unis. Ouvrez-les ici pour voir exactement ce qu'ils contiennent.
8. Comprendre pourquoi un fichier ne se charge pas. Si une bibliothèque de cartes échoue sur un fichier, la visionneuse vous dit s'il s'agit vraiment de TopoJSON, de GeoJSON avec la mauvaise extension ou d'un fichier aux références d'arcs cassées.

Questions fréquentes

Bibliothèques et données

Cette visionneuse repose sur des logiciels open source et des données ouvertes. Un grand merci aux personnes derrière ces projets.

• topojson-client 3.1 · ISC · Mike Bostock
  Décode la topologie : retransforme les arcs en coordonnées, reconstruit chaque objet en GeoJSON et construit le maillage des frontières partagées.
• Leaflet 1.9 · BSD-2-Clause · Volodymyr Agafonkin and contributors
  Dessine la carte interactive, les couches et les fenêtres d'information.
• Natural Earth (1:50m Admin 0 countries) · Domaine public · Natural Earth contributors
  Frontières des pays utilisées dans le fichier d'exemple.
• OpenStreetMap, Protomaps (hosted by KONAKTIVE), CARTO, Esri World Imagery · ODbL et conditions du fournisseur · OpenStreetMap contributors, Protomaps, KONAKTIVE, CARTO, Esri
  Tuiles et images du fond de carte.

Visionneuses de fichiers SIG associées