pyGeoMapper

Python and Rust workflows for geologic mapping, 3D structural reconstruction, and surface-change analysis from satellite imagery and elevation models.

Overview

Field geology connects maps and structures in three spatial dimensions with change through time. pyGeoMapper brings these 3+1D perspectives into a Python workflow with a Rust core: supervised geologic mapping from terrain features and Google AlphaEarth embeddings, cross-sections and browser-viewable 3D structural models, and land-surface change analysis. It combines multiscale terrain analysis through pyTopoComplexity with DEM differencing, spectral indices, InSAR, and optical feature tracking to support interpretation of landslides, earthflows, earthquakes, glaciers, fires, and floods.

The package is under active development. Its methods are experimental and not fully validated; results require geological interpretation and independent checks.

A 62.5-second overview of the mapping, structural reconstruction, and surface-change workflows. Silent; loops automatically.

Data types

pyGeoMapper can read, analyze, and visualize:

Elevation: DEMs and lidar (Copernicus GLO-30, USGS 3DEP lidar); terrain derivatives, CWT complexity, and DEM of Difference.
Optical imagery: multispectral Sentinel-2 and Landsat, and NAIP aerial RGB; spectral indices (NDVI, NBR, NDWI, BSI, clay and iron ratios), index change, and optical feature-tracking velocity.
Satellite embeddings: 64-band Google AlphaEarth annual embeddings for classification and embedding change.
InSAR: Sentinel-1 LiCSAR displacement, offsets, and wrapped phase; UAVSAR unwrapped phase to line-of-sight displacement; Okada fault models.
Ice velocity: NASA ITS_LIVE velocity grids and speed change.
Geology: map polygons as training and validation labels, bed attitudes (strike/dip), and fault traces for cross-sections and 3D block models.

Landscape features and geologic mapping

Supervised machine learning uses geomorphic surface features and surface-geology constraints to map geologic units, which are reconstructed as cross-sections and 3D structural models.

Multiscale CWT complexity — Sheep Mountain, Wyoming — **DEM** + 2D Mexican-hat **continuous wavelet transform** (pyTopoComplexity): ridges and valleys, mean complexity, A–A′ energy profile, and dominant wavelength.

Automatic geologic mapping at Sheep Mountain — Sheep Mountain, Wyoming — **64-band AlphaEarth embeddings** + **supervised ML**, trained on USGS geologic map units in the northwest half and validated on the held-out southeast half (accuracy 91.0%, macro-F1 0.89).

Cross-section — Sheep Mountain, Wyoming — **mapped units + 3-point bed attitudes** projected to A–A′ and B–B′ (~60° apart), with the published SW-dipping ~50° basement thrust.

Rotating Sheep Mountain block and sections — Sheep Mountain, Wyoming — **reconstructed 3D geologic block** with matching faulted A–A′ and B–B′ sections; 72 frames at 3 fps (about 24 seconds per turn).

Surface change

Toolkits detect surface change at different temporal and spatial scales using elevation, optical, radar, and velocity data. Five notebooks walk through the methods with public data.

2014 Oso landslide, Washington — **DEMs** (pre COP30, post 3DEP lidar) → DEM of Difference (red = erosion, blue = deposit); **Sentinel-2** spectral change (ΔNDVI, ΔNBR); and terrain Δ complexity via CWT (pyTopoComplexity).

2020 Holiday Farm Fire, Oregon — **Sentinel-2** SWIR–NIR–red composites before and after, and **burn-ratio change (ΔNBR)**; cyan outline marks higher debris-flow hazard.

Yolo Bypass Flood, California — 2019 Yolo Bypass flood, California — **Sentinel-2** before and during the flood, and **water-index change (ΔNDWI)**; cyan outline is the mapped shoreline.

Myanmar 2025 earthquake LiCSAR — 2025 Mw 7.7 Sagaing Fault earthquake, Myanmar — **Sentinel-1 LiCSAR InSAR**: north–south displacement, azimuth and range offsets, and wrapped phase.

Slumgullion Earthflow, Colorado — **NAIP optical feature tracking** (velocity 2017–2023), **UAVSAR** LOS and rewrapped phase (12–19 August 2011), and **DEM difference** 2024−2015 (red = lowering, blue = raising). Arrows are optical motion only.

Jakobshavn ITS_LIVE glacier velocity — Jakobshavn Isbræ, West Greenland — **NASA ITS_LIVE velocity**: 2018 surface speed with flow directions, and 2018−2016 speed change.

Key features

Surface change

DEM of Difference, spectral-index change, InSAR, and optical feature tracking for surface-change analysis.

Spectral and terrain

Spectral indices and multiscale terrain metrics.

Geological mapping

Auto-mapping of geologic units, scored on held-out blocks.

Sections and 3D

Cross-sections, 3D block/fence diagrams and an offline WebGL viewer.

Installation

pip install pygeomapper

Requires Python 3.10 or newer. One standard installation includes the mapping, machine-learning, and 3D-viewing dependencies; no extras are needed.

Citation

Lai, L.S.-H. (2026) pyGeoMapper (version 0.3.0). Zenodo, https://doi.org/10.5281/zenodo.23832020

pyGeoMapper is under the GNU Affero General Public License 3.0 or later. You are free to use, modify, and share it; anyone distributing modified code or running a modified version as a network service must share its source under the same license.

Next project pyPetrograph A machine-learning toolkit for thin-section petrography, from grain mapping to mineral naming.