Visor de TopoJSON

Qué hace este visor

TopoJSON es un pariente compacto de GeoJSON. Guarda cada borde compartido una sola vez y suele escribir las coordenadas como números enteros pequeños. Eso hace que los archivos sean mucho más pequeños, y por eso lo usan los mapas de D3.js, los mapas electorales y muchos proyectos de periodismo de datos. La desventaja es que no puedes leer un archivo TopoJSON a simple vista, y muchas herramientas SIG y mapas web no pueden abrirlo sin convertirlo antes.

Este visor abre el archivo directamente. Arrastra un archivo .topojson o .json al mapa y el visor comprueba que sea una topología real, reconstruye cada forma a partir de sus arcos y dibuja cada objeto con nombre como una capa aparte con su propio color. La barra lateral muestra cuántos objetos, elementos y arcos tiene el archivo, si está cuantizado y qué tan fina es su cuadrícula, y cuánto más grandes serían los mismos datos en GeoJSON normal. Haz clic en un elemento para leer sus atributos, incluido su id de TopoJSON.

Añadí una función que no encontrarás en un visor de GeoJSON normal: «Highlight shared borders». Dibuja solo los arcos que comparten dos elementos distintos, directamente desde la topología. Es la forma más rápida de comprobar que un mapa de países, provincias o distritos electorales tiene de verdad bordes compartidos limpios, sin huecos ni solapes. Cuando necesites los datos en otra herramienta, descarga un objeto o todos como GeoJSON. No se sube nada: el archivo nunca sale de tu ordenador.

TopoJSON frente a GeoJSON

Los dos formatos son JSON y los dos describen puntos, líneas y polígonos con atributos. La diferencia está en cómo guardan las coordenadas.

Mi regla práctica: usa TopoJSON cuando envíes muchos polígonos que se tocan a un navegador, como países, estados o distritos, y el tamaño importe. Usa GeoJSON para todo lo demás, sobre todo cuando otras personas o herramientas vayan a editar los datos.

Qué hay dentro de un archivo TopoJSON

Un archivo TopoJSON es un único objeto JSON con el tipo "Topology". Estos son sus miembros principales:

type

Siempre "Topology". Un archivo que dice "FeatureCollection" es GeoJSON, no TopoJSON.

objects

Un diccionario de objetos con nombre, por ejemplo countries y capitals. Cada uno es una geometría o una GeometryCollection, y cada uno se convierte en una capa en este visor.

arcs

La lista compartida de líneas. Los polígonos y las líneas no guardan coordenadas propias: guardan los números de los arcos que los forman.

transform

Opcional. Si está presente, el archivo está cuantizado: las posiciones de los arcos son enteros, y scale y translate los convierten de nuevo en longitud y latitud.

bbox

Opcional. El rectángulo envolvente de todos los datos, como [mín x, mín y, máx x, máx y].

properties, id

Cada geometría puede llevar properties (los atributos) y un id, igual que un elemento GeoJSON.

Aquí tienes una topología completa y muy pequeña con dos campos cuadrados que se tocan. Es el mismo ejemplo que resuelve la sección de matemáticas más abajo.

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

El campo A usa los arcos 0 y 1. El campo B usa el arco 2 y después el -1. Un índice negativo significa «usa este arco al revés»: -1 es el arco 0 invertido, porque el número es el complemento a uno ~0. El borde entre los campos (arco 0) se escribe una sola vez.

Detalles técnicos

Esto es exactamente lo que el visor lee y muestra.

Archivos aceptados

Archivos .topojson y .json con "type": "Topology", hasta 100 MB. Un archivo GeoJSON recibe un mensaje claro que te lleva al Visor de GeoJSON.

Tipos de geometría

Point, MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon y GeometryCollection, incluidas las geometrías null (se omiten).

Objetos

Cada objeto con nombre se convierte en su propia capa, con casilla, color, tipo de geometría, número de elementos y de campos, y una descarga en GeoJSON.

Archivos cuantizados

Compatibles por completo. El visor lee transform, decodifica los enteros codificados como deltas y muestra el tamaño de un paso de la cuadrícula sobre el terreno, en metros.

Bordes compartidos

En los objetos con polígonos, el visor construye la malla de arcos que usan dos elementos distintos (topojson.mesh con a !== b) y puede dibujarla encima.

Atributos

Todas las properties aparecen en la ventana emergente. Un id de TopoJSON se añade como atributo id para que lo veas y se conserve al exportar.

Sistema de coordenadas

El TopoJSON para mapas web suele estar en longitud y latitud WGS84. Los archivos que se proyectaron antes de convertirlos (por ejemplo, US Albers para un mapa de D3) no están en grados y no se pueden colocar en un mapa del mundo.

Exportación

Cada objeto en su propio archivo GeoJSON, o todos los objetos en un solo GeoJSON con un atributo topojson_object que indica de dónde viene cada elemento.

Mapa base

Mapa de calles por defecto, con opción de satélite. Pon la opacidad de relleno en 0 para ver solo los contornos.

Privacidad

El archivo se lee y se decodifica en tu navegador. No se envía nada a un servidor.

Cómo ver un archivo TopoJSON, paso a paso

Este es el flujo completo con el ejemplo incluido: 50 países europeos de Natural Earth y 22 capitales, guardados como una topología cuantizada con dos objetos.

1

Paso 1: Abre el visor

El mapa se abre con un mapa base de calles. Usa Upload, arrastra un archivo al mapa o haz clic en Sample Data.

2

Paso 2: Carga un archivo TopoJSON

El archivo se decodifica en tu navegador y cada objeto se dibuja con su propio color. File Info muestra el número de objetos, elementos y arcos, el paso de cuantización y lo grande que serían los mismos datos en GeoJSON.

3

Paso 3: Trabaja con los objetos

El panel Objects lista cada objeto de la topología con su tipo de geometría y su número de elementos. Desmarca un objeto para ocultarlo o haz clic en su cuadrado de color para cambiar el color.

4

Paso 4: Resalta los bordes compartidos

Marca «Highlight shared borders» para dibujar los arcos que comparten dos elementos distintos, construidos desde la propia topología. Las costas no se comparten, así que quedan sin marcar.

5

Paso 5: Lee los atributos

Haz clic en cualquier elemento para abrir sus atributos. La ventana emergente también indica el objeto al que pertenece y muestra el id de TopoJSON.

6

Paso 6: Exporta a GeoJSON

Usa el enlace GeoJSON junto a un objeto para descargar solo ese objeto, o Download All as GeoJSON para todo en un solo archivo.

Otras formas de abrir y convertir TopoJSON

Este visor sirve para mirar un archivo rápidamente. Estas son las otras herramientas que uso cuando un archivo TopoJSON necesita trabajo de verdad.

Las mismas tareas en código

Estos comandos convierten un archivo de países en ambas direcciones y lo leen en JavaScript y 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")

Mi opinión: guarda tus datos maestros en GeoJSON, GeoPackage o Shapefile, y genera el TopoJSON como último paso para la web. Es fácil de volver a generar, pero difícil de editar a mano.

Cómo funciona el visor

Esto es lo que ocurre entre soltar un archivo y verlo en el mapa. Cada paso se ejecuta en tu navegador.

1. Leer y comprobar el JSON. El archivo se lee como texto y se analiza. Si el type de nivel superior no es "Topology", o faltan objects o arcs, recibes un error claro en lugar de un mapa vacío.
2. Decodificar los arcos. Si el archivo tiene un transform, cada arco se decodifica de enteros codificados como deltas a longitud y latitud. Sin transform, las posiciones de los arcos se usan tal cual.
3. Reconstruir cada objeto. Para cada objeto con nombre, topojson.feature une los arcos referenciados en anillos y líneas, invierte los arcos con índice negativo y devuelve una FeatureCollection de GeoJSON con las properties e ids originales.
4. Construir la malla de bordes compartidos. En los objetos con polígonos, topojson.mesh con el filtro a !== b reúne cada arco que pertenece a dos elementos distintos. Los arcos que usa un solo elemento, como las costas, quedan fuera.
5. Medir el archivo. El visor cuenta objetos, elementos y arcos, calcula el tamaño de un paso de cuantización en metros y mide lo grande que sería el GeoJSON decodificado.
6. Dibujar y encuadrar. Cada objeto se convierte en una capa de Leaflet con su propio color. Los puntos se dibujan como círculos. El mapa hace zoom a todos los datos visibles.

La decodificación la hace topojson-client, la biblioteca de referencia escrita por el creador del formato, así que el visor lee los archivos exactamente como los mapas de D3.

Cómo TopoJSON reduce el tamaño de los archivos

TopoJSON ahorra espacio de tres formas: arcos compartidos, cuantización y codificación delta. Aquí están las matemáticas de cada una, con la topología de ejemplo de arriba.

índice  i ≥ 0  →  arco i, del primer punto al último
índice  i < 0  →  arco ~i = −i − 1, del último punto al primero

Anillo del campo A:  [0, 1]    = arco 0, luego arco 1
Anillo del campo B:  [2, −1]   = arco 2, luego arco 0 invertido

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

longitud = x_entero · scale_x + translate_x
latitud  = y_entero · scale_y + translate_y

arco guardado:   [[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] y 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)

Cuándo ayuda un visor de TopoJSON

Estas son las situaciones en las que recurro a un visor rápido de TopoJSON.

1. Revisar un archivo antes de crear un mapa con D3. Mira qué objetos contiene un archivo TopoJSON descargado, cómo se llaman y qué atributos tienen, para saber qué escribir en `topo.objects` antes de empezar a programar.
2. Comprobar los bordes tras simplificar. Después de simplificar un mapa en mapshaper o toposimplify, activa «Highlight shared borders» para confirmar que los vecinos siguen compartiendo un borde limpio, sin huecos ni astillas.
3. Sacar GeoJSON de un archivo TopoJSON. Muchos mapas web y herramientas SIG solo aceptan GeoJSON. Descarga un objeto o el archivo entero como GeoJSON sin instalar nada.
4. Revisar mapas electorales y censales. Las redacciones publican a menudo límites de distritos y municipios como TopoJSON. Abre el archivo para revisar nombres, ids y cobertura antes de unir tus resultados.
5. Comparar niveles de cuantización. Abre el mismo mapa creado con distintas cuantizaciones y compara el tamaño del paso en metros y el tamaño del archivo, para elegir el archivo más pequeño que aún se vea bien.
6. Enseñar cómo funciona la topología. La lista de objetos, el número de arcos y la vista de bordes compartidos facilitan mostrar a los estudiantes por qué una topología ocupa menos que el GeoJSON normal.
7. Abrir archivos de los paquetes world-atlas y us-atlas. Estos paquetes populares de npm incluyen TopoJSON de países, estados y condados de EE. UU. Ábrelos aquí para ver exactamente lo que contienen.
8. Averiguar por qué un archivo no carga. Si una biblioteca de mapas falla con un archivo, el visor te dice si es TopoJSON de verdad, GeoJSON con la extensión equivocada o un archivo con referencias a arcos rotas.

Preguntas frecuentes

Bibliotecas y datos

Este visor se basa en software de código abierto y datos abiertos. Muchas gracias a las personas detrás de estos proyectos.

• topojson-client 3.1 · ISC · Mike Bostock
  Decodifica la topología: convierte los arcos de nuevo en coordenadas, reconstruye cada objeto como GeoJSON y construye la malla de bordes compartidos.
• Leaflet 1.9 · BSD-2-Clause · Volodymyr Agafonkin and contributors
  Dibuja el mapa interactivo, las capas y las ventanas emergentes.
• Natural Earth (1:50m Admin 0 countries) · Dominio público · Natural Earth contributors
  Fronteras de los países usadas en el archivo de ejemplo.
• OpenStreetMap, Protomaps (hosted by KONAKTIVE), CARTO, Esri World Imagery · ODbL y condiciones del proveedor · OpenStreetMap contributors, Protomaps, KONAKTIVE, CARTO, Esri
  Teselas e imágenes del mapa base.

Visores de archivos SIG relacionados