Metadata-Version: 2.4
Name: pygeomapper
Version: 0.1.0
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Rust
Classifier: Topic :: Scientific/Engineering :: GIS
Requires-Dist: numpy>=1.22.0
Requires-Dist: scipy>=1.9.0
Requires-Dist: matplotlib>=3.6.0
Requires-Dist: rasterio>=1.3.0
Requires-Dist: pyproj>=3.4.0
Requires-Dist: tifffile>=2023.1.0
Requires-Dist: pillow>=9.0.0
Requires-Dist: xdem>=0.0.18 ; extra == 'dem'
Requires-Dist: pywbt>=0.2.0 ; extra == 'dem'
Requires-Dist: pytest>=7.0 ; extra == 'dev'
Requires-Dist: nbformat ; extra == 'dev'
Requires-Dist: scikit-learn>=1.2.0 ; extra == 'dev'
Requires-Dist: jupyter ; extra == 'dev'
Requires-Dist: maturin>=1.5,<2.0 ; extra == 'dev'
Requires-Dist: scikit-learn>=1.2.0 ; extra == 'ml'
Requires-Dist: spyndex>=0.4.0 ; extra == 'spectral'
Requires-Dist: pystac-client>=0.7.0 ; extra == 'stac'
Requires-Dist: pytest>=7.0 ; extra == 'test'
Requires-Dist: nbformat ; extra == 'test'
Requires-Dist: scikit-learn>=1.2.0 ; extra == 'test'
Requires-Dist: forge3d>=1.0.0 ; extra == 'viz3d'
Provides-Extra: dem
Provides-Extra: dev
Provides-Extra: ml
Provides-Extra: spectral
Provides-Extra: stac
Provides-Extra: test
Provides-Extra: viz3d
License-File: LICENSE
License-File: NOTICE
Summary: A toolkit for automated geological and geomorphic mapping from surface geology, remote sensing and DEM data, with 3D terrain visualization and analysis
Keywords: geology,geomorphology,remote-sensing,change-detection,dem,insar,alphaearth,rust
Author: Larry Syu-Heng Lai
License-Expression: AGPL-3.0-or-later
Requires-Python: >=3.10
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Homepage, https://github.com/GeoLarryLai/pyGeoMapper
Project-URL: Issues, https://github.com/GeoLarryLai/pyGeoMapper/issues
Project-URL: Repository, https://github.com/GeoLarryLai/pyGeoMapper

<p align="center"><img src="https://raw.githubusercontent.com/GeoLarryLai/pyGeoMapper/main/image/logo.png" alt="pyGeoMapper" width="160"></p>

# pyGeoMapper

[![PyPI version](https://img.shields.io/pypi/v/pygeomapper.svg)](https://pypi.org/project/pygeomapper/) [![pepy downloads](https://static.pepy.tech/badge/pygeomapper)](https://pepy.tech/project/pygeomapper)

![DEM of Difference and spectral change](https://raw.githubusercontent.com/GeoLarryLai/pyGeoMapper/main/image/dod_and_spectral_change.png)

pyGeoMapper maps what changed on the ground and what the ground is made of, from satellite images and elevation
models (DEMs). It is a Python toolkit with a Rust core, and it ends in 3D block diagrams you can open in a browser.

Status: 0.1.0, early-stage research software. APIs may change; check results before use.
Not related to `The-Magicians-Code/PyGeoMapper`.

**Use it to:**

- measure elevation and surface change after a landslide, flood, wildfire or earthquake;
- map geological units automatically from terrain and spectral data, with honest held-out accuracy;
- draw cross-sections and 3D block diagrams of a field area.

![3D geological block diagram](https://raw.githubusercontent.com/GeoLarryLai/pyGeoMapper/main/image/3d_block_diagram.png)

## Install

```bash
pip install pygeomapper
# from source (Python 3.10+, Rust 1.75+):
git clone https://github.com/GeoLarryLai/pyGeoMapper.git && cd pyGeoMapper
pip install maturin && maturin develop --release
```

Optional extras: `stac`, `ml`, `viz3d`, `spectral`, `dem`, `test`.

## Quick start

```python
from pygeomapper import raster_io, surface_change, terrain_analysis

dem1 = raster_io.load_geotiff("example_data/oso_dem_pre_cop30.tif")
dem2 = raster_io.load_geotiff("example_data/oso_dem_post_3dep.tif")
dod = surface_change.compute_dod(dem1, dem2)                        # elevation change between the two DEMs
cwt = terrain_analysis.compute_multiscale_complexity(dem2)          # terrain roughness at several scales
```

## Key features

- **Raster I/O (`raster_io`):** CRS-aware GeoTIFF/COG and multi-band stacks, STAC search, AlphaEarth embeddings.
- **Spectral indices (`spectral_indices`):** NDVI, NBR, NDWI, NDMI, BSI and mineral ratios in parallel Rust.
- **Surface change (`surface_change`):** DEM of Difference with co-registration and LoD volumes, spectral and
  embedding change, InSAR/GNSS 3D displacement, debris-flow susceptibility and multi-hazard fingerprints.
- **Terrain (`terrain_analysis`):** slope, aspect, hillshade, curvature, roughness and multiscale 2D CWT complexity.
- **Mapping (`auto_mapping`):** unsupervised and supervised unit mapping with spatial-block holdout validation.
- **Cross-sections (`cross_section`):** swath profiles, 3-point bed attitudes and geological cross-sections.
- **3D (`viewer_3d`):** 3D block, cutaway and fence diagrams, GLB/PLY/OBJ export and an offline WebGL viewer.

## Examples

Five executed notebooks in `notebooks/` of the [repository](https://github.com/GeoLarryLai/pyGeoMapper) walk through every module with public data:

1. `pyGeoMapper_1_spectral_and_surface_change.ipynb`: spectral indices and surface change (Oso landslide)
2. `pyGeoMapper_2_terrain_complexity_and_cwt.ipynb`: terrain derivatives and multiscale complexity
3. `pyGeoMapper_3_auto_mapping_and_cross_section.ipynb`: automated unit mapping and a cross-section
4. `pyGeoMapper_4_3d_block_diagram_and_viewer.ipynb`: 3D block diagrams and the offline viewer
5. `pyGeoMapper_5_multi_hazard_change_showcase.ipynb`: earthquake, volcano, glacier, landslide, flood and wildfire cases

## How to cite

> Lai, L. S.-H. (2026). pyGeoMapper (version 0.1.0) [Computer software]. https://github.com/GeoLarryLai/pyGeoMapper

Full metadata is in `CITATION.cff` in the repository. Methods: [Horn (1981)](https://doi.org/10.1109/PROC.1981.11918),
[Zevenbergen & Thorne (1987)](https://doi.org/10.1002/esp.3290120107),
[Nuth & Kääb (2011)](https://doi.org/10.5194/tc-5-271-2011),
[Montero et al. (2023)](https://doi.org/10.1038/s41597-023-02096-0),
[Lai et al. (2025)](https://doi.org/10.5194/esurf-13-417-2025),
[Brown et al. (2025)](https://arxiv.org/abs/2507.22291),
[Okada (1985)](https://doi.org/10.1785/BSSA0750041135),
[Staley et al. (2017)](https://doi.org/10.1016/j.geomorph.2016.10.019),
[Horton et al. (2017)](https://doi.org/10.3133/ds1052). Data sources: `example_data/SOURCES.txt`, `NOTICE`.

## Licence

Copyright (C) 2026 Larry Syu-Heng Lai. AGPL-3.0-or-later (`LICENSE`, `NOTICE`).

