Mazzap v2 — a georeferenced 3D digital-twin engine

https://github.com/user-attachments/assets/deb9e860-abf8-4e34-ab9b-88b3c7a2643f

Mazzap v2 turns a patch of real ground into a VEIL — a Virtually Embodied Intelligent Land: a standalone, fully georeferenced 3D digital twin that Mazzap models and instantiates from open geospatial data. Open it in a browser, click to read true GPS coordinates, drape your own map layers onto the terrain, simulate the processes that move water and fire across it, and ask questions about it in natural language.

No database, no cloud, no build step at view time: one tiny zero-dependency Node static server serves a Three.js viewer over a self-contained bundle of geospatial data. Nothing is fetched from the network when you view it.

# A fresh clone ships the engine, not a place — build a twin first:
npm run demo       # build the bundled Flatirons demo twin (needs internet + GDAL)
npm run serve-demo # -> http://127.0.0.1:4174

# ...or build your own area interactively, then serve it:
npm run init       # guided setup: draw an AOI, fetch data, build the twin
npm start          # -> http://127.0.0.1:4173

(npm start with no twin built yet just tells you to run one of the above.)

Requires Node ≥ 18 (the server uses the built-in fetch); the data pipeline scripts need Python 3 with GDAL (osgeo), numpy, pyproj, and Pillow. The MCP/chat path also needs the Python mcp SDK from requirements.txt. If you'd rather not assemble that toolchain yourself, run it in a container — GDAL, numpy, Node, and the rest come pinned and pre-built.

Point it at your own DEM and imagery (see "Build your own twin" below) — the engine is region-agnostic. The coordinate system, the vegetation knowledge, the map-layer styling, and any source-acquisition scripts all live in data and in an optional regional pack, never hardcoded in the engine.

What you get

• 3D terrain from any DEM (a LiDAR DTM, USGS 3DEP, a national survey grid), rendered as a lit mesh with selectable surface modes (aerial / false-color / hillshade / elevation).
• Aerial imagery draped on the terrain, aligned to the grid so it conforms to the topography instead of floating.
• Classified point-cloud view — switch independently between the normal textured DEM/rendered-tree mesh scene and a PLY-style LiDAR viewer. Point presets expose ground, ground + vegetation, vegetation, or every return; points can be colored by the orthophoto, ASPRS class, elevation, or intensity.
• Click-to-identify + GPS readout — click anywhere to pin the real-world lat/lon (validated against proj4js), elevation, and every map feature true at that spot.
• Atlas layers — import any vector or raster geospatial file and it is reprojected to the scene, clipped to the terrain footprint, auto-styled, and made clickable. Bring soils, wetlands, zoning, habitat, hydrology, land cover — whatever you have.
• Vegetation — a capability ladder that derives trees from the best signal available (LiDAR segmentation stems, a canopy-height model, or an NDVI canopy), rendered as low-LOD 3D forms. Anywhere in the continental US, the bundled us-national pack types them evergreen/deciduous and names their community from LANDFIRE — no regional setup (see "Vegetation" under docs/make-a-twin.md).
• Simulation — model the processes that move across the land, not just what's on it: terrain hydrology (flow, wetness, ponding, seeps, and snowmelt/storm runoff scenarios), evapotranspiration & water balance (FAO-56 reference and actual ET, closing the land's water budget), wildfire behavior scenarios, and solar siting (panel radiation, PV yield, shade/cloud losses, and angle recommendations). Each renders as draped, clickable layers in the viewer's Simulation window, and is honest about its uncertainty. See "Simulation".
• Solar panel planning — combine astronomy, viewshed horizons, and Daymet climate normals to rank panel sites, answer proposed-site questions, and visualize annual/winter PV potential. See "Solar siting".
• Astronomy — a local ephemeris-driven sky, lighting model, and time scrubber for sun, moon, planets, stars, constellations, eclipses, rise/set, golden hour, and terrain-aware solar context. See "Astronomy".
• Viewshed & distant terrain — compute what is visible from an observer point, rank viewpoints, query visibility through MCP, and render 3DEP distant terrain with NAIP drapes around the twin. See "Viewshed & distant terrain".
• Ask the land chat — a collapsible panel that talks to an LLM wired to the twin's read-only query tools (the MCP server), scoped to the whole twin, a polygon you draw, or a point you pick. See docs/mcp.md.
• QField survey companion — generate a QField project from the active twin, collect trails / stream centerlines / photo points / observations in the field, then upload the zipped project folder back through the viewer. Uploads become journaled survey_* entities, rendered as survey layers and queryable through MCP. See docs/survey.md.
• Live telemetry — register Meshtastic/LoRa gateways from the viewer, render live tracker positions, replay recorded days with realtime/speed controls and tracker POV, then append selected samples into the curated twin store. See docs/live-inputs.md.
• Plan — a smooth, interactive 3D workspace with live terrain/vegetation feedback for tree/shrub removal, free-text species-aware planting, and depressions/mounds. Hold Ctrl/Command to navigate without leaving a brush; G.A.I.A. composes swales, orchards, and gardens from the same primitives. Plans autosave as immutable revisions, support named versions and branches, can be safely discarded, and rerun hydrology, wildfire, ET, solar, and viewshed against the effective land. G.A.I.A. can draft and visualize proposals before an explicitly confirmed apply. See docs/plan.md.

Plan land alternatives

Plan is a non-destructive workspace for trying changes to the land before making decisions in the field. The baseline twin never changes: each completed brush gesture becomes an immutable plan revision, and every simulation result stays scoped to the exact plan and revision that produced it.

Use Plan by hand

1. Open Plan from the left rail, then click New or select an existing plan. Choose Baseline, Planned, or Difference at any time to compare the original land with the active alternative.
2. Select Remove plants, Add tree, Add bush, Depression, or Mound. Set brush radius and, where relevant, species, modeled stage, spacing, and earth depth/height. Click once to place a plant; drag to paint plantings or earthworks. The 3D terrain and vegetation update while you draw.
3. Hold Ctrl (or Command on macOS) while dragging to move the camera without leaving the brush. Esc cancels an unfinished gesture; Ctrl/Command+Z undoes the last completed one.
4. Watch the save indicator and change summary. Finished gestures autosave as immutable revisions, so Save version is for naming a checkpoint—not for protecting ordinary work. Select an older version to inspect or simulate it; use Branch to turn that read-only version into a new editable alternative. Discard archives the whole plan without deleting its revision history.
5. Open Simulation and run hydrology, wildfire, Water & ET, solar, or viewshed normally. With a plan selected, VEIL automatically runs against that revision's effective terrain and vegetation instead of the baseline.

Plan with G.A.I.A.

1. Open Ask G.A.I.A. and describe the outcome and location—for example, “Draft a swale along the main flow path with a capture basin; show me the difference, but do not apply it.” Use Draw region or Pick point first when the request should be spatially constrained.
2. G.A.I.A. creates or extends a plan, validates its proposed edits, estimates quantities, and opens the proposal in the already-running viewer's Difference view. This is a preview: it does not alter the plan head or the baseline.
3. Inspect the live terrain, switch among Baseline, Planned, and Difference, and read the proposal quantities. Ask G.A.I.A. to revise the draft if needed. When it is right, click Approve as new revision (or give an equally explicit approval in chat). Approval creates one immutable revision; stale proposals are rejected rather than overwriting newer work.
4. Ask G.A.I.A. to run a plan simulation, or use the Simulation pane yourself, then compare results across saved versions or branches.

The detailed edit model, simulation coupling, REST endpoints, MCP tools, and current limits are documented in docs/plan.md.

Simulation

Mapping shows what's on the land; simulation models the processes that move across it. Mazzap runs these inside the viewer's collapsible Simulation window, each rendered as draped, clickable layers that conform to the topography — and each is explicit about what it can and cannot tell you.

Hydrology

Mazzap models where water moves and pools across the land, in two tiers. Tier 1 (analyze_hydrology.py) works the bare LiDAR/DEM surface: p