Mapr3D

A local 3D studio that pulls from maps. Pick any place on Earth, load it into an editable 3D scene where anything is printable, select and refine individual objects (terrain, buildings, water, imported meshes), then export a watertight STL for printing.

Not a one-shot terrain mesher — a scene editor. Objects stay discrete and editable; the printable solid is a compile step at export time.

Why it's built this way

• Detail comes from data, not software. The whole system is a data-sourcing pipeline with a studio UI on top. The data layer picks the best available source per region.
• Keep objects separate. The scene is a graph of discrete meshes. They are only boolean-unioned into one solid at export. That is what makes "pull a structure out and refine it" possible.
• Runs locally, no keys required. Elevation comes from keyless global terrain tiles (AWS Terrain Tiles); buildings from OpenStreetMap. Optional high-res sources (OpenTopography USGS 1 m lidar) plug in with an API key.

Architecture

Mapr3D runs as a plugin inside GeoLibre (MIT), an open-source cloud-native GIS platform. GeoLibre supplies the map, basemaps, layers, drawing tools, LiDAR/Gaussian-splat/3D-Tiles viewers and 70+ data formats; Mapr3D supplies the thing GeoLibre has no notion of — turning a region into a watertight, printable solid.

plugin/     TypeScript GeoLibre plugin — right-sidebar studio + toolbar menu
backend/    FastAPI engine: DEM resolver, OSM features, meshing, STL export
            (also serves the bundled app from backend/mapr3d/static)
build-app.sh  bundles plugin + GeoLibre -> backend/mapr3d/static
frontend/   Legacy standalone React studio (superseded by plugin/)

One process, one port. build-app.sh compiles the plugin, bakes it into a GeoLibre production build, and copies the result into the backend, which then serves the UI and the API from http://localhost:8000. GeoLibre is a build-time dependency only — it is cloned next to this repo and never runs as its own server.

Pipeline: frame a region on the map -> fetch best-available DEM + OSM -> build scene graph -> edit / refine -> boolean-union + base -> export STL.

Running it

./run.sh

That is it — it installs dependencies and builds the app bundle on first run (a few minutes), then serves everything on http://localhost:8000. Mapr3D auto-activates via the ?mapr3d=1 URL the server redirects to, so the studio panel opens ready to use.

macOS: double-click Mapr3D.command. Set MAPR3D_PORT to use a different port, or GEOLIBRE_DIR to point at an existing GeoLibre checkout.

Rebuild the bundle after changing the plugin:

./build-app.sh

GeoLibre pins external plugin bundles by content hash, so after a plugin rebuild it asks you to re-accept the update once (Settings -> Manage Plugins, or clear the geolibre.pluginBundlePins local-storage key).

Data sources (best per region)

Region	Source	Resolution	Key
US high-res	USGS 3DEP (National Map ImageServer)	1 m bare-earth	no
Global	AWS Terrain Tiles (Terrarium)	~ tile zoom (blended 3DEP/SRTM)	no
US high-res	OpenTopography USGS 3DEP 1 m	1 m	yes
Global DEM	OpenTopography SRTM / Copernicus	30 m	yes
Buildings	OpenStreetMap (Overpass, mirrored)	footprints + heights + roof shapes	no

The auto source tries keyless USGS 3DEP first in the US (true 1 m), then global terrain tiles. Buildings use OSM Simple 3D Buildings tags (roof:shape, roof:height) to build real gabled/hipped/pyramidal roofs, not flat boxes.

Quickstart

Easiest on macOS: double-click Mapr3D.command in Finder. It opens Terminal, installs dependencies on first run, and starts both servers.

Or from a terminal:

./run.sh

Then open http://localhost:5173. Press Ctrl+C to stop.

Prerequisites: uv and Node.js. Ports are configurable via MAPR3D_BACKEND_PORT / MAPR3D_FRONTEND_PORT.

Run the servers manually instead

# backend
cd backend && uv sync && uv run uvicorn mapr3d.main:app --reload --port 8000
# frontend (separate terminal)
cd frontend && npm install && npm run dev

Status

Early build. See the pipeline stages in backend/mapr3d/ and the studio in frontend/src/.

Roadmap

• Repo scaffold
• DEM resolver (keyless terrain tiles + synthetic fallback)
• Terrain -> watertight solid
• Map region picker + 3D studio viewport
• OSM buildings as selectable objects
• Editing: hide / delete / height scale
• STL export (watertight, scaled, base + vertical exaggeration)
• High-res lidar channel with graceful fallback (OpenTopography key)
• Boolean-union single-manifold export toggle
• Terrain detail (resolution) control
• Detailed basemaps (OSM streets + Esri satellite)
• Mesh-import injector — drop OBJ/STL/PLY/GLB meshes (3D Tiles / photogrammetry / Gaussian-splat exports) onto the terrain, place and scale them, export welded in
• Import hardening — mesh repair + auto-decimation, size guard, build notes surfaced in the UI
• Terrain refine ops (flatten a selected patch)
• Preserve imported meshes across a rebuild

Deliberately not doing direct Google Photorealistic 3D Tiles fetch: it requires a billed, keyed Google Map Tiles API. Mapr3D stays keyless — bring a 3D Tiles / splat mesh in through the mesh-import injector instead.