Portolan Transit Maps

Portolan — Mapas de Tránsito que se Dibujan Solos

Repo fuente: github.com/alexwohlbruck/portolan (MIT, Go, activo 2026) — https://github.com/alexwohlbruck/portolan

Qué es

Pipeline GTFS → mapa de tránsito esquemático automático (no estaciones sobre coordenadas, sino el clásico diagrama de metro con líneas de colores). Da un feed GTFS de una ciudad + geometría de vías de OpenStreetMap y produce cartografía donde:

• Cada línea tiene su color; líneas que comparten vía corren como bandas paralelas con spacing uniforme.
• Los corredores comparten una línea central (centerline) y las bandas se separan/unen con curvas suaves en los nudos a cualquier nivel de zoom.
• Estaciones agrupadas por datos de transbordo del propio feed (un complejo = una etiqueta con todos los marcadores de ruta).
• Reconstrucción de ciudad completa en segundos (compilación Go <1s), bucle edición→rebuild→revisión muy rápido.

17 ciudades configuradas (NYC, Chicago, Londres, París, Berlín, Tokio, Barcelona, Boston, Toronto, Viena, Santiago…), TODO por config en portolan.json — cero código específico por ciudad.

Cuándo usar este skill

• Cuando pidas un mapa tipo metro/esquemático de una red de transporte (metro, tranvía, cercanías) generado desde GTFS real.
• Cuando haya que resolver el problema del "spaghetti": 15 líneas superpuestas en el mismo corredor.
• Diferenciación: transit-map-simulation = vehículos animados en tiempo real sobre mapa; gtfs-box-3d-viewer = visualización 3D de operación; Portolan = cartografía esquemática generada automáticamente.

Uso básico

# Workbench interactivo (selector de ciudad, mapa vivo, slider de hora del día)
go run ./cmd/portolan atlas          # http://127.0.0.1:8765

# Construir una ciudad desde CLI
go run ./cmd/portolan chart --gtfs nyc.zip --rail nyc-rail.geojson --out nyc.geojson

# Extraer geometría de vías desde OSM
tools/feed.sh rail london

# Ciudades configuradas y estado de inputs
make cities
make city CITY=london   # construye + puntúa

# Score de calidad geométrica contra un dibujo humano de referencia
portolan sound --network testdata/sketches/nyc.json --build nyc.geojson
# → jaggedness / wobble p90 / desviación media / self-intersections / PASS-FAIL

Las 7 etapas del pipeline (docs/ALGORITHM.md)

1. CHART — cargar y normalizar GTFS + geometría.
2. SOUND — sondeos de sección transversal perpendiculares para medir offsets entre vías.
3. BUNDLE — empaquetado de vías paralelas sostenidas y centerline por mediana.
4. BERTH — asignación de "atraques": qué ruta va en qué posición de la banda.
5. ORDER — orden de líneas dentro del corredor (heurística local, no solve exacto).
6. FAIR — alisado/fairing de curvas en nudos (forks que salen con rampa coseno).
7. EMIT — salida GeoJSON + gates de calidad.

Leyes de geometría (docs/LESSONS.md — tercera tentativa, dos pipelines muertos)

Estas reglas son el verdadero valor del repo; cada una costó defectos visibles:

1. NUNCA media ponderada por distancia → siempre mediana. La media atrae "gravitatoriamente" la línea hacia strands extraños; la mediana adopta u ignora honestamente.
2. Secciones transversales por intersección perpendicular, nunca proyección al punto más cercano (la proyección se ancla a endpoints → cuerdas en extremos y sesgo en curvas).
3. Las sondas caminan por el arco, nunca por la tangente recta (±75 m rectos se salen del corredor en cada curva → esquinas cortadas de 10 m).
4. Cambios de nº de strands con rampa, nunca escalón: suavizar la SERIE de offsets (σ≈5 muestras), no la geometría.
5. Bundling exige paralelismo sostenido (≥~60 m dentro de ~12 m) — esto hace que los "kiss-welds" fantasma sean irrepresentables. El bundling es VISUAL (2D): vías apiladas sin conexión física también se agrupan.
6. Extremos empalman en nodos con ventana escalada por offset (~5 m de recorrido por m de offset, rampa coseno), y solo en nodos reales y asentados.
7. Ley de diseño: prohibidas las pasadas de reparación. Una salida mala = una etapa mala. Arreglar aguas abajo genera interacciones que rompen otros sitios (la lección que mató el intento 2: 13 passes _fix_* compitiendo entre sí).
8. Nada de raster para la topología — el esqueleto raster de eje medial (intento 2) lo cuantizaba todo: wobble, nodos 130 m desplazados, uniones fantasma, costuras de teselas. Geometría vectorial exacta end-to-end.

Integración con proyectos de David

• España Atlas / DataHub: Barcelona ya está configurada en Portolan — patrón directo para mapa esquemático de metro desde feeds GTFS del consorcio.
• Análisis de corredores GTFS: detectar "corredor = paralelismo sostenido" es reutilizable para agrupar rutas por infraestructura compartida (planes de movilidad).
• Calidad verificable: el patrón "golden sketch + scorer PASS/FAIL" (desviación media <2 m vs dibujo humano) es exportable a cualquier pipeline geométrico — adoptar como práctica.
• Rendering con MapLibre: spacing uniforme en zoom continuo exige build de MapLibre con variable line offsets; con offsets fijos pre-horneados funciona MapLibre estándar.

Pitfalls

• Buses NO implementados (necesitan modelo de corredor viario, no de vía); ferris sí (la shape publicada ES la geometría).
• Donde OSM no tiene vías, cae al shape tosco del feed (artefactos visibles).
• Interiores de nudos muy congestionados (tipo City Hall loop) aún con artefactos.
• Orden en corredores es estimación local — líneas pueden cruzarse sin razón en splits complejos.
• Proyecto joven (agosto 2026, ~48⭐): API inestable, leer docs/CLI.md de la versión clonada.

Verificación

cd portolan && go build ./... && go run ./cmd/portolan chart --gtfs <feed.zip> --rail <rail.geojson> --out test.geojson
# Gate real: `portolan sound` contra testdata/sketches/nyc.json debe dar PASS
# (jaggedness max turn <~25°, 0 self-intersections, desviación media <2 m)

Referencias

• docs/ALGORITHM.md (7 etapas), docs/LESSONS.md (leyes geométricas), docs/CITIES.md (añadir ciudad), docs/SERVICE-SCENARIOS.md (mapas por hora del día), docs/TOOLS.md (workbench y scorer)
• Creado por el pipeline stars-explorer el 2026-09-02.