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.
• 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.

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: priority-flood depression filling, D8 flow direction with O(n) flow accumulation, Horn slope, and a Topographic Wetness Index. It produces draped, clickable layers for flow paths (upslope contributing area, ha), wetness index (TWI percentile), ponding depth in closed depressions (m), and spring/seep candidates (wetness × flow convergence × slope-break × shallow restrictive layer from SSURGO soils). Tier 2 (hydro_scenario.py) runs event scenarios — snowmelt (inches of SWE over N melt days, optional rain-on-snow, antecedent moisture, frozen ground) or a rainstorm (depth over a duration) — partitioning each soil cell into runoff versus infiltration via the SCS Curve-Number method (SSURGO hydrologic soil groups, AMC I/II/III), then routing down the Tier-1 D8 graph for per-cell runoff, routed event-flow volumes, and a peak-discharge estimate at the AOI outlet. Honest framing: the geometry — where water concentrates — is the reliable output; discharge magnitude carries a ±50% class band because the catchment is ungauged.

Use cases:

• Agriculture — locate wet-index hollows and ponding cells that drown crops or bog down equipment, to guide tile-drainage and field-traffic planning.
• Ecology — map spring/seep candidates and convergent flow paths that mark seasonal wetland and riparian habitat across the land.
• Conservation — target erosion-control and buffer plantings along the routed high-runoff channels a modeled storm concentrates.

Wildfire

Mazzap runs fire-behavior scenarios on top of the LANDFIRE fuel layers a US VEIL already carries — surface fuel models (FBFM13/40), canopy cover, height, base height, and bulk density. Combined with the land's terrain (slope, aspect), local hydrology influence, an ignition point, and a chosen weather/wind scenario, it models arrival time, flame length, fireline intensity, ember exposure, and crown-fire class across the land, reusing the same Simulation-window and draped-layer machinery as the hydrology scenarios. Treat the result as scenario-grade exploration, not an operational forecast: where fire spreads is more reliable than exact times, flame lengths, or intensities.

Use cases:

• Agriculture — compare wind scenarios to see where crown fire could reach a woodlot or shelterbelt bordering cropland, informing defensible-space clearing.
• Ecology — explore how fuel and canopy structure shape modeled fire intensity across a habitat mosaic.
• Conservation — rehearse where a prescribed burn might spread or spot before committing to a burn plan.

Evapotranspiration & water balance

Mazzap simulates how much water the land actually loses to the atmosphere. From the VEIL's Daymet climate forcing it derives daily reference ET (ET0) with an ensemble of standard methods — FAO-56 Penman-Monteith (reduced-data form), Priestley-Taylor, Hargreaves-Samani, and Oudin (derive_et0_daily.py) — and reports the spread between methods as an explicit uncertainty band rather than a single false-precise number. A FAO-56 root-zone soil-water-balance (et_water_balance.py) then converts that reference demand into actual ET (AET) using basal crop coefficients from land cover and canopy, a water-stress coefficient from SSURGO available-water capacity, canopy interception, and a self-contained temperature-index snow model (robust where gridded SWE is unreliable). This closes the land's water balance — P = ET + runoff + Δstorage + recharge — the loss term the hydrology model previously left open, and feeds antecedent soil moisture back into the runoff scenarios. Honest framing: ET0 is FAO-56-correct, but absolute annual AET is only ±20–35% without local flux-tower or gauge validation; relative timing, seasonality, and wet/dry antecedent state are far more trustworthy than the absolute totals. Queryable over MCP via et_summary, et_at, and water_balance.

![Mazzap evapotranspiration simulation: mo