Visualizador de TopoJSON

O que este visualizador faz

TopoJSON é um parente compacto do GeoJSON. Ele guarda cada fronteira compartilhada uma única vez e costuma escrever as coordenadas como números inteiros pequenos. Isso deixa os arquivos muito menores, e é por isso que mapas em D3.js, mapas eleitorais e muitos projetos de jornalismo de dados usam o formato. A desvantagem é que não dá para ler um arquivo TopoJSON a olho nu, e muitas ferramentas GIS e mapas web não conseguem abri-lo sem convertê-lo antes.

Este visualizador abre o arquivo diretamente. Arraste um arquivo .topojson ou .json para o mapa, e ele confere se é mesmo uma topologia, reconstrói cada forma a partir dos seus arcos e desenha cada objeto nomeado como uma camada separada, com cor própria. A barra lateral mostra quantos objetos, feições e arcos o arquivo tem, se ele é quantizado e quão fina é a sua grade, e quanto maiores seriam os mesmos dados em GeoJSON comum. Clique em uma feição para ler seus atributos, incluindo o id do TopoJSON.

Adicionei um recurso que você não encontra em um visualizador de GeoJSON comum: "Highlight shared borders". Ele desenha só os arcos que duas feições diferentes compartilham, direto da topologia. É o jeito mais rápido de conferir se um mapa de países, municípios ou distritos eleitorais tem mesmo fronteiras compartilhadas limpas, sem vãos nem sobreposições. Quando precisar dos dados em outra ferramenta, baixe um objeto ou todos como GeoJSON. Nada é enviado: o arquivo nunca sai do seu computador.

TopoJSON e GeoJSON comparados

Os dois formatos são JSON, e os dois descrevem pontos, linhas e polígonos com atributos. A diferença está na forma de guardar as coordenadas.

Minha regra prática: use TopoJSON quando você envia muitos polígonos que se tocam para um navegador, como países, estados ou distritos, e o tamanho importa. Use GeoJSON para todo o resto, principalmente quando outras pessoas ou ferramentas vão editar os dados.

O que tem dentro de um arquivo TopoJSON

Um arquivo TopoJSON é um único objeto JSON com o tipo "Topology". Estes são os seus membros principais:

type

Sempre "Topology". Um arquivo que diz "FeatureCollection" é GeoJSON, não TopoJSON.

objects

Um dicionário de objetos nomeados, por exemplo countries e capitals. Cada um é uma geometria ou uma GeometryCollection, e cada um vira uma camada neste visualizador.

arcs

A lista compartilhada de linhas. Polígonos e linhas não guardam coordenadas próprias: eles listam os números dos arcos que os formam.

transform

Opcional. Quando existe, o arquivo é quantizado: as posições dos arcos são inteiros, e scale e translate os transformam de volta em longitude e latitude.

bbox

Opcional. O retângulo envolvente de todos os dados, como [mín x, mín y, máx x, máx y].

properties, id

Cada geometria pode ter properties (os atributos) e um id, igual a uma feição GeoJSON.

Aqui está uma topologia completa e bem pequena, com dois campos quadrados que se tocam. É o mesmo exemplo que a seção de matemática mais abaixo resolve.

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

O campo A usa os arcos 0 e 1. O campo B usa o arco 2 e depois o -1. Um índice negativo significa "use este arco ao contrário": -1 é o arco 0 invertido, porque o número é o complemento de um ~0. A fronteira entre os campos (arco 0) é escrita uma só vez.

Detalhes técnicos

Isto é exatamente o que o visualizador lê e mostra.

Arquivos aceitos

Arquivos .topojson e .json com "type": "Topology", até 100 MB. Um arquivo GeoJSON recebe uma mensagem clara que indica o Visualizador de GeoJSON.

Tipos de geometria

Point, MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon e GeometryCollection, incluindo geometrias null (elas são puladas).

Objetos

Cada objeto nomeado vira uma camada própria, com caixa de seleção, cor, tipo de geometria, número de feições e de campos, e um download em GeoJSON.

Arquivos quantizados

Suportados por completo. O visualizador lê o transform, decodifica os inteiros codificados como deltas e mostra o tamanho de um passo da grade no terreno, em metros.

Fronteiras compartilhadas

Para objetos com polígonos, o visualizador monta a malha de arcos usados por duas feições diferentes (topojson.mesh com a !== b) e pode desenhá-la por cima.

Atributos

Todas as properties aparecem na janela de informação. Um id do TopoJSON é adicionado como atributo id, para você vê-lo e para ele continuar na exportação.

Sistema de coordenadas

O TopoJSON para mapas web normalmente está em longitude e latitude WGS84. Arquivos projetados antes da conversão (por exemplo, US Albers para um mapa em D3) não estão em graus e não podem ser colocados em um mapa-múndi.

Exportação

Cada objeto em um arquivo GeoJSON próprio, ou todos os objetos em um único GeoJSON com um atributo topojson_object que diz de onde veio cada feição.

Mapa base

Mapa de ruas por padrão, com opção de satélite. Coloque a opacidade de preenchimento em 0 para ver só os contornos.

Privacidade

O arquivo é lido e decodificado no seu navegador. Nada é enviado a um servidor.

Como visualizar um arquivo TopoJSON, passo a passo

Este é o fluxo completo com o exemplo incluído: 50 países europeus do Natural Earth e 22 capitais, guardados como uma topologia quantizada com dois objetos.

1

Passo 1: Abra o visualizador

O mapa abre com um mapa base de ruas. Use Upload, arraste um arquivo para o mapa ou clique em Sample Data.

2

Passo 2: Carregue um arquivo TopoJSON

O arquivo é decodificado no seu navegador, e cada objeto é desenhado com a sua cor. File Info mostra o número de objetos, feições e arcos, o passo de quantização e quão grande seriam os mesmos dados em GeoJSON.

3

Passo 3: Trabalhe com os objetos

O painel Objects lista cada objeto da topologia com seu tipo de geometria e número de feições. Desmarque um objeto para escondê-lo, ou clique no quadrado de cor para mudar a cor.

4

Passo 4: Destaque as fronteiras compartilhadas

Marque "Highlight shared borders" para desenhar os arcos que duas feições diferentes compartilham, montados a partir da própria topologia. Os litorais não são compartilhados, então ficam sem destaque.

5

Passo 5: Leia os atributos

Clique em qualquer feição para abrir seus atributos. A janela também mostra o objeto ao qual ela pertence e o id do TopoJSON.

6

Passo 6: Exporte para GeoJSON

Use o link GeoJSON ao lado de um objeto para baixar só esse objeto, ou Download All as GeoJSON para tudo em um único arquivo.

Outras formas de abrir e converter TopoJSON

Este visualizador serve para olhar um arquivo rapidamente. Estas são as outras ferramentas que uso quando um arquivo TopoJSON precisa de trabalho de verdade.

As mesmas tarefas em código

Estes comandos convertem um arquivo de países nas duas direções e o leem em JavaScript e em 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")

Minha opinião: mantenha seus dados principais em GeoJSON, GeoPackage ou Shapefile, e gere o TopoJSON como último passo para a web. Ele é fácil de gerar de novo, mas difícil de editar à mão.

Como o visualizador funciona

Isto é o que acontece entre soltar um arquivo e vê-lo no mapa. Cada passo roda no seu navegador.

1. Ler e conferir o JSON. O arquivo é lido como texto e analisado. Se o type do nível superior não for "Topology", ou se faltar objects ou arcs, você recebe um erro claro em vez de um mapa vazio.
2. Decodificar os arcos. Se o arquivo tem um transform, cada arco é decodificado de inteiros codificados como deltas para longitude e latitude. Sem transform, as posições dos arcos são usadas como estão.
3. Reconstruir cada objeto. Para cada objeto nomeado, topojson.feature junta os arcos referenciados em anéis e linhas, inverte os arcos com índice negativo e devolve uma FeatureCollection GeoJSON com as properties e ids originais.
4. Montar a malha de fronteiras compartilhadas. Para objetos com polígonos, topojson.mesh com o filtro a !== b reúne cada arco que pertence a duas feições diferentes. Arcos usados por uma única feição, como os litorais, ficam de fora.
5. Medir o arquivo. O visualizador conta objetos, feições e arcos, calcula o tamanho de um passo de quantização em metros e mede quão grande seria o GeoJSON decodificado.
6. Desenhar e enquadrar. Cada objeto vira uma camada do Leaflet com cor própria. Os pontos são desenhados como círculos. O mapa dá zoom em todos os dados visíveis.

A decodificação em si é feita pelo topojson-client, a biblioteca de referência escrita pelo criador do formato, então o visualizador lê os arquivos exatamente como os mapas em D3.

Como o TopoJSON deixa os arquivos menores

O TopoJSON economiza espaço de três formas: arcos compartilhados, quantização e codificação delta. Aqui está a matemática de cada uma, com a topologia de exemplo acima.

índice  i ≥ 0  →  arco i, do primeiro ao último ponto
índice  i < 0  →  arco ~i = −i − 1, do último ao primeiro ponto

Anel do campo A:  [0, 1]    = arco 0, depois arco 1
Anel do campo B:  [2, −1]   = arco 2, depois arco 0 invertido

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

longitude = x_inteiro · scale_x + translate_x
latitude  = y_inteiro · scale_y + translate_y

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

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

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

Quando um visualizador de TopoJSON ajuda

Estas são as situações em que eu recorro a um visualizador rápido de TopoJSON.

1. Conferir um arquivo antes de montar um mapa em D3. Veja quais objetos um arquivo TopoJSON baixado contém, como eles se chamam e quais atributos têm, para saber o que escrever em `topo.objects` antes de começar a programar.
2. Conferir as fronteiras depois de simplificar. Depois de simplificar um mapa no mapshaper ou no toposimplify, ligue "Highlight shared borders" para confirmar que os vizinhos ainda compartilham uma fronteira limpa, sem vãos nem lascas.
3. Tirar GeoJSON de um arquivo TopoJSON. Muitos mapas web e ferramentas GIS só aceitam GeoJSON. Baixe um objeto ou o arquivo inteiro como GeoJSON sem instalar nada.
4. Revisar mapas eleitorais e de censo. Redações costumam publicar limites de distritos e municípios em TopoJSON. Abra o arquivo para conferir nomes, ids e cobertura antes de juntar seus resultados a ele.
5. Comparar níveis de quantização. Abra o mesmo mapa gerado com quantizações diferentes e compare o tamanho do passo em metros e o tamanho do arquivo, para escolher o menor arquivo que ainda fica bom.
6. Ensinar como a topologia funciona. A lista de objetos, o número de arcos e a visão das fronteiras compartilhadas facilitam mostrar aos alunos por que uma topologia é menor que o GeoJSON comum.
7. Abrir arquivos dos pacotes world-atlas e us-atlas. Esses pacotes populares do npm trazem TopoJSON de países, estados e condados dos EUA. Abra-os aqui para ver exatamente o que contêm.
8. Descobrir por que um arquivo não carrega. Se uma biblioteca de mapas falha com um arquivo, o visualizador diz se ele é mesmo TopoJSON, GeoJSON com a extensão errada ou um arquivo com referências quebradas a arcos.

Perguntas frequentes

Bibliotecas e dados

Este visualizador é feito com software de código aberto e dados abertos. Muito obrigado às pessoas por trás destes projetos.

• topojson-client 3.1 · ISC · Mike Bostock
  Decodifica a topologia: transforma os arcos de volta em coordenadas, reconstrói cada objeto como GeoJSON e monta a malha de fronteiras compartilhadas.
• Leaflet 1.9 · BSD-2-Clause · Volodymyr Agafonkin and contributors
  Desenha o mapa interativo, as camadas e as janelas de informação.
• Natural Earth (1:50m Admin 0 countries) · Domínio público · Natural Earth contributors
  Fronteiras dos países usadas no arquivo de exemplo.
• OpenStreetMap, Protomaps (hosted by KONAKTIVE), CARTO, Esri World Imagery · ODbL e termos do provedor · OpenStreetMap contributors, Protomaps, KONAKTIVE, CARTO, Esri
  Blocos e imagens do mapa base.

Visualizadores de arquivos GIS relacionados