Skip to main content

Map Integration

The map is the central UI element in Xylem. It uses Mapbox GL JS via react-map-gl for rendering interactive 2D/3D maps with GIS layers, site boundaries, and building visualizations.

Architecture​

┌──────────────────────────────────────────────────┐
│                  Map Workspace                    │
│                                                  │
│  ┌───────────────────────────────────────────┐   │
│  │  react-map-gl (Mapbox GL JS)              │   │
│  │                                           │   │
│  │  ┌─────────────┐  ┌──────────────────┐   │   │
│  │  │ Base Layers  │  │  Data Layers     │   │   │
│  │  │ (raster/     │  │  - Site boundary │   │   │
│  │  │  vector      │  │  - Buildings     │   │   │
│  │  │  tiles from  │  │  - Roads         │   │   │
│  │  │  Geo Server) │  │  - Zones         │   │   │
│  │  └─────────────┘  └──────────────────┘   │   │
│  │                                           │   │
│  └───────────────────────────────────────────┘   │
│                                                  │
│  ┌─────────┐  ┌──────────┐  ┌───────────────┐   │
│  │ Search  │  │ Layers   │  │ Compass/      │   │
│  │ Bar     │  │ Control  │  │ Rotation      │   │
│  └─────────┘  └──────────┘  └───────────────┘   │
└──────────────────────────────────────────────────┘

Map Components​

GeocoderWrapper​

Wraps the @mapbox/search-js-react geocoder for location search. Includes:

  • Address autocomplete search bar
  • Auto-fly to selected location
  • Integration with the map viewport state

Layer Controls​

Toggle visibility of GIS layers from the Geo Tile Server:

  • Base layers — Satellite, street map, terrain (radio-button selection)
  • Data layers — Overlay layers with toggle switches
  • Auto-zoom to layer bounds when enabled

Map Rotation​

Interactive compass knob for controlling the map bearing (yaw):

  • Drag to rotate the map freely
  • Release to stop (no momentum)
  • Visual compass indicator shows current bearing

GIS Tile Sources​

Map tiles are loaded from the Geo Tile Server (geo.xylem.city):

Tile TypeURL PatternFormat
Rastergeo.xylem.city/raster/{layer}/{z}/{x}/{y}.pngPNG tiles
Vectorgeo.xylem.city/tiles/{layer}.pmtilesPMTiles (Protomaps)

Layers are managed through the admin panel and the Geo Server's API.

3D Visualization​

For building solutions, the frontend uses Three.js to render:

  • 3D extruded building footprints
  • Tower height visualization
  • Floor-by-floor breakdown
  • Solar shadow analysis overlays

Solar Analysis​

Uses SunCalc library to calculate:

  • Sun position at any time of day/year
  • Shadow direction and length
  • Sunlight hours for different building faces
  • Integration with the simulation engine's solar analysis results (pvlib)

Geospatial Utilities​

Turf.js is used extensively for client-side geospatial operations:

  • Area calculations
  • Bounding box computation
  • Point-in-polygon checks
  • Buffer generation
  • Distance measurements