# Forge3d Terrain Cartography

> Use al renderizar terreno 3D en mapas de impresión.

- Skill: `ntizar/forge3d-terrain-cartography` (Agent Skill)
- Install (CLI): `npx skillmds@latest add ntizar/forge3d-terrain-cartography`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ntizar/forge3d-terrain-cartography/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: ntizar (https://skillmd.com/u/ntizar)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/ntizar/forge3d-terrain-cartography

---


# Forge3D — Terreno path-traced y cartografía desde Python

**Repo:** github.com/milos-agathon/forge3d (640⭐, Rust+Python, MIT/Apache-2.0 core, actualizado ago-2026)
**Docs:** https://milos-agathon.github.io/forge3d/ · **Galería:** /gallery/ (masters hasta 7200×7200)

## Qué es y cuándo usarlo

Motor de render **offline** (path tracing con iluminación global y sombras) expuesto como wheels de Python. A diferencia de los visores web que ya cubrimos (three.js/MapLibre/globos → skills `photorealistic-3d-tiles-threejs`, `navara-3d-globe-engine`, `monolith-terrain`), forge3d produce **mapas cartográficos finalizados a resolución de impresión** — títulos, leyendas, escala y norte incluidos, compuestos in-engine, sin compositor externo.

Usar cuando se necesite:
- Visualizaciones de terreno fotorrealistas para **informes/PDF** (sombras solares, relieve, hidrología)
- **Secuencias de frames** animadas (bucle Python + ffmpeg): humo de incendios, evolución temporal de campos
- Mapas temáticos sobre DEM: densidad poblacional extruida (WorldPop/GHSL), land cover Sentinel-2, clima TerraClimate, hidrológica HydroSHEDS
- Cartografía de ciudades con edificios LOD2 (CityGML/CityJSON sobre RGE ALTI)

## Instalación

```bash
pip install forge3d              # core open-source (MIT OR Apache-2.0)
pip install "forge3d[jupyter]"   # widget de notebook
pip install "forge3d[datasets]"  # datasets de muestra on-demand
pip install "forge3d[all]"       # todo
```

Requiere GPU con WebGPU (o fallback Vulkan). Python 3.10+.

## Patrón núcleo: 60 segundos a un render

```python
import forge3d as f3d

dem_path = f3d.fetch_dem("rainier")          # DEM de muestra on-demand

with f3d.open_viewer_async(terrain_path=dem_path, width=1440, height=900) as viewer:
    viewer.set_z_scale(0.1)                   # exageración vertical
    viewer.set_orbit_camera(phi_deg=28, theta_deg=49, radius=5400, fov_deg=42)
    viewer.set_sun(azimuth_deg=302, elevation_deg=24)   # sol = clave para sombras
    viewer.snapshot("rainier.png", width=1920, height=1080)
```

`fetch_dem` baja el modelo de elevación, `open_viewer_async` abre ventana orbitable real, `snapshot` escribe el frame a la resolución pedida.

## Superficie del motor (lo que cubre)

| Área | Capacidad |
|---|---|
| **Terrain** | `open_viewer_async()`, `ViewerHandle`, GeoTIFF o DEMs numpy, clipmaps para regiones grandes |
| **Rendering** | Path tracing, materiales PBR, subsurface scattering, agua con reflejos, nubes y contact shadows, AOV + salida EXR |
| **Data** | Streaming COG, helpers CRS, nubes de puntos LAZ/COPC/EPT, 3D Tiles, GeoJSON, CityJSON, datasets on-demand |
| **Cartografía** | Overlays ráster/vector, labels con halo y oclusión, graticules, `Legend`, `ScaleBar`, `NorthArrow`, `MapPlate` |
| **Offscreen** | `Scene`, `Session`, `TerrainRenderer` + `TerrainRenderParams` para trabajo headless y batch |
| **Output** | PNG y PNG16, **exportación vectorial SVG y PDF**, scene bundles, widgets notebook |

## Patrón animación temporal (time-lapse)

Las escenas se pilotan 100% desde Python: "un eje temporal es otro bucle más" — fetch de campos (p. ej. predicción HRRR para humo volumétrico), step del reloj, `snapshot()` por frame, y los frames van a ffmpeg. Mismo scene graph que los stills, una sola cámara, sin compositing.

## Integración con proyectos de David

- **Sombras solares Madrid / shadeMap**: `set_sun(azimuth_deg, elevation_deg)` + path tracing = sombras reales con GI para las horas críticas; exportar PNG16/SVG para informes.
- **DataHub España / informes**: figuras de relieve e hipometría vectoriales (SVG/PDF) en vez de PNG rasterizados.
- **Agua (Water3J)**: agua con reflejos PBR del motor para láminas de inundación sobre terreno.
- Alternativa **offline Python** a `monolith-terrain` / `three-scope-map` (que son navegador).

## Comparativa de alternativas (consulta 2026-09-04)

| Herramienta | Liga | Cuándo gana |
|---|---|---|
| **forge3d** (640⭐) | Render offline Python | Fotorrealismo path-traced + cartografía publicable + time-lapse |
| `monolith-terrain` / `three-scope-map` / `map33-js` | Navegador three.js | Interactividad en web pública, gratis, sin GPU local |
| `navara-3d-globe-engine` (MapLibre 3D) | WebGIS teselas | Mapa-base con teselas oficiales, contexto de ciudad |
| QGIS + Blender | Desktop tradicional | Control total pero manual, sin scripting Python integrado |

## Pitfalls

- **Funciones Pro de pago**: composición `MapPlate`, exportación vectorial y pipelines de importación de edificios están gatingados — desbloqueo con `forge3d.set_license_key(...)`. El core (terreno, path tracing, overlays, PNG) es libre. Para SVG/PDF vectoriales sin licencia → render core + recomponer fuera. (David: SOLO herramientas gratuitas → tratar Pro como extra opcional, nunca base de pipeline.)
- **GPU obligatoria**: WebGPU/Vulkan. En máquina sin GPU discreta, headless puede fallar o ir lento — probar primero con un DEM pequeño (`fetch_dem`).
- **`set_z_scale` crítico**: los DEM vienen en metros; sin exageración vertical (0.05–0.2) el terreno sale plano en renders a distancia orbital.
- **Proyecto joven (creado 2025-07, 640⭐)**: API sujeta a cambios; fijar versión en requirements si entra en pipeline de producción.
- Los renders de README/galería van downsampled — los masters reales llegan a 7200×7200 (peso alto en PNG16/EXR).

## Verificación

```bash
python -c "import forge3d as f3d; print(f3d.__version__)"
# Smoke test: dem = f3d.fetch_dem("rainier") → snapshot 800×600 → comprobar PNG existe y pesa >0
```

## Referencias

- Quickstart: https://milos-agathon.github.io/forge3d/start/quickstart.html
- Feature map: https://milos-agathon.github.io/forge3d/guides/feature_map.html
- Tutorials GIS/Python: https://milos-agathon.github.io/forge3d/tutorials/index.html
- API reference: https://milos-agathon.github.io/forge3d/api/api_reference.html
- Ejemplo live orbitable (Mount Shasta): https://milosgis.com/