PyGeoFetch 2.6.2.6__tar.gz → 2.6.2.7__tar.gz

{pygeofetch-2.6.2.6 → pygeofetch-2.6.2.7}/CHANGELOG.md

@@ -20,7 +20,7 @@ date, and marked accordingly rather than filled in with invented
 bullet points.
 ```
 
-## [Unreleased] — v2.6.2.6.4
+## [Unreleased] — v2.6.2.7.4
 
 ```{note}
 Not yet published to PyPI. This entry documents work completed and
@@ -130,7 +130,7 @@ audit and remain open for a follow-up pass.
 
 ---
 
-## [2.6.2.6.4] — 2026-08-25 (latest)
+## [2.6.2.7.4] — 2026-08-25 (latest)
 
 Confirmed via direct fetch of the current PyPI listing.
 
@@ -149,7 +149,7 @@ Confirmed via direct fetch of the current PyPI listing.
 - `SearchQuery.sort_ascending: bool` — earlier examples showed a `sort_order: "asc"/"desc"` string field that doesn't exist on the model (the CLI's `--sort-order` flag does convert to this internally, so CLI docs were unaffected)
 - `DownloadOptions.post_process` requires a list of `PostProcessAction` objects — passing plain strings raises a real `pydantic.ValidationError`
 
-## [2.6.2.6] — 2026-08-24
+## [2.6.2.7] — 2026-08-24
 Real, verified release. Detailed notes not independently recovered from PyPI's release-history page (no distinct per-version notes exposed for this release specifically).
 
 ## [2.6.1] — 2026-08-22
@@ -261,9 +261,9 @@ recovered.
 
 ```{note}
 The previous version of this changelog had an entry labeled
-**"2.6.2.6.4 — 2026-07-12"** describing 22+ providers, Sentinel-1C/1D
+**"2.6.2.7.4 — 2026-07-12"** describing 22+ providers, Sentinel-1C/1D
 support, SLC search with provider routing, precise orbit file
-management, 17 spectral indices, and various bug fixes. **2.6.2.6.4 was
+management, 17 spectral indices, and various bug fixes. **2.6.2.7.4 was
 only ever released once, on 2026-08-25** — it was never released on
 2026-07-12. The date matches this real release, **1.0.8**, exactly.
 That content is reproduced below under the version it actually
@@ -406,8 +406,8 @@ The version of this file uploaded for this update had **5 entries
 covering 5 dates**. PyPI's real release history has **54 releases**.
 Specific issues found and fixed:
 
-1. **Two different entries were both labeled `2.6.2.6.4`**, dated
-   2026-07-29 and 2026-07-12. **2.6.2.6.4 was only ever released once**,
+1. **Two different entries were both labeled `2.6.2.7.4`**, dated
+   2026-07-29 and 2026-07-12. **2.6.2.7.4 was only ever released once**,
    on 2026-08-25 (confirmed directly from the live PyPI listing).
 2. **The 2026-07-12 entry's date exactly matches a real release**
    — version **1.0.8** — and its content (22+ providers, Sentinel-1C/D,

{pygeofetch-2.6.2.6/pygeofetch.egg-info → pygeofetch-2.6.2.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pygeofetch
-Version: 2.6.2.6
+Version: 2.6.2.7
 Summary: Universal satellite data pipeline + geospatial processing platform
 Author-email: Samuel Appiah Kubi <appiahkubis14@gmail.com>
 License: MIT License
@@ -146,8 +146,9 @@ Dynamic: license-file
 [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.22087230.svg)](https://doi.org/10.5281/zenodo.22087230)
 [![Tests](https://github.com/EOCoreINT/pygeofetch/actions/workflows/tests.yml/badge.svg)](https://github.com/EOCoreINT/pygeofetch/actions/workflows/tests.yml)
 [![codecov](https://codecov.io/gh/appiahkubis14/pygeofetch/graph/badge.svg?token=2PS2A2VZL6)](https://codecov.io/gh/appiahkubis14/pygeofetch)
+[![Sponsor](https://img.shields.io/badge/Sponsor-%E2%9D%A4-ea4aaa?logo=githubsponsors)](https://github.com/sponsors/appiahkubis14)
 
-**A unified satellite data and geospatial processing platform — one CLI, one Python API, 24 providers, and a fully verified InSAR chain.**
+**A unified satellite data and geospatial processing platform — one CLI, one Python API, 22 verified providers, and a fully verified InSAR chain.**
 
 [Quick Start](#-quick-start) · [Mexico City Case Study](#-case-study-mapping-mexico-city-land-subsidence-with-insar) · [Case Study Repo ↗](https://github.com/EOCoreINT/mexico-subsidence-project) · [Documentation](https://pygeofetch.readthedocs.io/en/latest/) · [Notebooks](#-notebooks)
 
@@ -158,7 +159,7 @@ Dynamic: license-file
 
 ## Overview
 
-pygeofetch is a production-ready framework for acquiring and processing Earth observation data. It provides authenticated, unified access to **24 satellite repositories** — Sentinel, Landsat, Planet, Maxar, Airbus, Copernicus, USGS, NASA, JAXA, and more — through a single CLI and Python API, and layers a complete geospatial processing engine on top.
+pygeofetch is a production-ready framework for acquiring and processing Earth observation data. It provides authenticated, unified access to **22 verified satellite providers** — Sentinel, Landsat, Planet, Maxar, Airbus, Copernicus, USGS, NASA, JAXA, and more — through a single CLI and Python API, and layers a complete geospatial processing engine on top.
 
 Where pygeofetch goes further than most data-access libraries is in its **InSAR chain**: burst-aware coregistration, real flat-earth and topographic phase removal, ERA5 tropospheric and ionospheric correction, phase unwrapping, and SBAS time-series inversion — each stage independently verified against synthetic ground truth or real, published deformation studies, not assumed correct from theory alone. The [Mexico City case study](#-case-study-mapping-mexico-city-land-subsidence-with-insar) below walks through that chain end to end on real Sentinel-1 data.
 
@@ -166,7 +167,7 @@ Where pygeofetch goes further than most data-access libraries is in its **InSAR
 
 | | |
 |---|---|
-| 🔐 **Authenticated access** | 24 providers, credentials stored via system keyring (Keychain / Credential Manager / Secret Service) |
+| 🔐 **Authenticated access** | 22 verified providers; credentials stored via a Fernet-encrypted local file by default, or the system keyring (Keychain / Credential Manager / Secret Service) as an opt-in alternative |
 | 🔍 **Federated search** | One query across all providers → STAC 1.0 GeoJSON / GeoParquet / CSV, with real footprint geometry where the provider supplies it |
 | 📥 **Resilient downloads** | Parallel, resumable, checksum-verified, band-selective, atomic writes |
 | ⚙️ **Preprocessing** | Atmospheric correction, cloud masking, reprojection, resampling, pan-sharpening, mosaicking |
@@ -192,7 +193,7 @@ Satellite data access is fragmented — every provider has its own auth scheme,
 
 | Feature | pygeofetch | EODAG | pystac-client | satpy | sentinelsat |
 |---|---|---|---|---|---|
-| Providers | **24** | 10+ | STAC only | Limited | Sentinel only |
+| Providers | **22** | 10+ | STAC only | Limited | Sentinel only |
 | Processing engine | ✅ Full | ❌ | ❌ | Partial | ❌ |
 | Spectral indices | ✅ 17+ | ❌ | ❌ | ❌ | ❌ |
 | Full InSAR chain | ✅ Verified | ❌ | ❌ | ❌ | ❌ |
@@ -204,9 +205,9 @@ Satellite data access is fragmented — every provider has its own auth scheme,
 
 ## Providers
 
-**11 open-access providers**, no login required — including `planetary_computer`, `aws_earth`, `element84`, `noaa_big_data`, `esa_scihub`, `jaxa_earth`, and `geoserver_generic` for any OGC WMS/WFS/WCS endpoint.
+**22 verified providers total.** Open-access, no login required — including `planetary_computer`, `aws_earth`, `element84`, `noaa_big_data`, `jaxa_earth`, and `geoserver_generic` for any OGC WMS/WFS/WCS endpoint.
 
-**13 authenticated providers** — USGS, Copernicus CDSE, NASA Earthdata (+ Cloud), Alaska SAR Facility, OpenTopography, Planet Labs, Sentinel Hub, Maxar GBDX, Airbus OneAtlas, Google Earth Engine, TerraBotics, and Earth Explorer.
+Authenticated — USGS, Copernicus CDSE, NASA Earthdata (+ Cloud), Alaska SAR Facility, OpenTopography, Planet Labs, Sentinel Hub, Maxar GBDX, Airbus OneAtlas, and Earth Explorer.
 
 Every provider has been directly verified to return at minimum a correct bounding box; several are further confirmed to return real, precise footprint geometry against a live API response (marked in `pygeofetch providers info PROVIDER`). Run `pygeofetch providers list` for the full, current table.
 
@@ -260,23 +261,12 @@ Mexico City sits on a drained lakebed and is subsiding at some of the fastest ra
 
 **1. Authenticated federated search.** `client.search()` against Copernicus Data Space for SLC scenes over the city (bbox `-99.183, 19.278, -99.003, 19.438`, July 2016 – September 2017) returns a stack of Sentinel-1A/1B candidates in seconds, filterable straight down to a single consistent track.
 
-<p align="center"><img src="https://raw.githubusercontent.com/EOCoreINT/mexico-subsidence-project/main/analysis/data-search.png" width="85%" /></p>
-
 Results carry real footprint geometry and drop straight onto a map via `MapViewer`, with hover info for scene ID, date, satellite, and provider — useful for spotting swath overlap before committing to a download.
 
-<p align="center">
-  <img src="https://raw.githubusercontent.com/EOCoreINT/mexico-subsidence-project/main/analysis/search_1.png" width="48%" />
-  <img src="https://raw.githubusercontent.com/EOCoreINT/mexico-subsidence-project/main/analysis/search.png" width="48%" />
-</p>
-
 **2. DEM acquisition.** A matching search against OpenTopography returns seven DEM products for the AOI; pygeofetch downloads and clips the selected one (SRTM 30 m) automatically for topographic phase removal.
 
-<p align="center"><img src="https://raw.githubusercontent.com/EOCoreINT/mexico-subsidence-project/main/analysis/dem_acquisition.png" width="85%" /></p>
-
 **3. Preflight validation.** Before anything downloads, the `PreflightGate` checks search truncation, AOI coverage, temporal network connectivity, and burst-timing family compatibility from lightweight annotation XMLs — catching acquisitions that would waste compute before they cost bandwidth. This run avoided roughly 360 GB of downloads by excluding 48 of 115 candidate scenes at this stage alone.
 
-<p align="center"><img src="https://raw.githubusercontent.com/EOCoreINT/mexico-subsidence-project/main/analysis/preflight-log.png" width="85%" /></p>
-
 Real orbit state vectors then pre-filter the candidate pair list against Sentinel-1's own mission thresholds, rejecting pairs for excess burst-sync error, temporal baseline, or spatial baseline before any interferogram is attempted.
 
 <p align="center"><img src="https://raw.githubusercontent.com/EOCoreINT/mexico-subsidence-project/main/analysis/pre-filter-for-interferogram.png" width="85%" /></p>
@@ -298,8 +288,6 @@ Real orbit state vectors then pre-filter the candidate pair list against Sentine
 
 **7. SBAS time-series inversion.** The full 58-date descending stack, once low-coherence and unreliable-reference-pixel pairs are excluded, fractures into 17 disconnected network "islands" — a genuine finding about this AOI's data quality, not a bug. The largest connected island (10 dates, 11 pairs) carries the final inversion, referenced near Cerro de la Estrella.
 
-<p align="center"><img src="https://raw.githubusercontent.com/EOCoreINT/mexico-subsidence-project/main/analysis/1.png" width="85%" /></p>
-
 The resulting velocity field, uncertainty map, reliability mask, and displacement time series recover a 2nd–98th-percentile vertical velocity of **−35.5 to −2.9 cm/year** where reliable pixels exist.
 
 <p align="center"><img src="https://raw.githubusercontent.com/EOCoreINT/mexico-subsidence-project/main/analysis/island1_sbas_full_analysis.png" width="90%" /></p>
@@ -381,7 +369,7 @@ If you use PyGeoFetch in your research or operational work, please cite it using
   title        = {PyGeoFetch: A Unified Python Framework for Multi-Provider Satellite Data Acquisition, Pre-download Quality Control, and Geospatial Processing},
   year         = {2026},
   publisher    = {Zenodo},
-  version      = {2.6.2.6.1},
+  version      = {2.6.2.7.1},
   doi          = {10.5281/zenodo.22087230},
   url          = {https://doi.org/10.5281/zenodo.22087230}
 }
@@ -391,15 +379,28 @@ If you use PyGeoFetch in your research or operational work, please cite it using
 
 Full documentation: **https://pygeofetch.readthedocs.io/en/latest/** — CLI reference, provider auth guides, pipeline configuration, post-processing catalogue, and InSAR verification methodology.
 
+## Support this project
+
+pygeofetch is built and maintained by a single developer, in the open,
+alongside a full-time workload — the InSAR/optical fusion chain, the
+provider verification work, and the documentation are all real,
+independently-verified engineering, not a side project maintained on
+autopilot. If pygeofetch is useful to your research or your
+organization, sponsoring its development directly funds the time spent
+keeping 22 provider integrations current as their real APIs change, and
+building out the multi-sensor pipelines documented above.
+
+[![Sponsor on GitHub](https://img.shields.io/badge/Sponsor-GitHub%20Sponsors-ea4aaa?logo=githubsponsors)](https://github.com/sponsors/appiahkubis14)
+
 ## Contributing
 
 Contributions are welcome — see [CONTRIBUTING.md](CONTRIBUTING.md). Good first issues include extending real footprint geometry to remaining bbox-only providers, wiring stub providers to full API integrations, and adding new post-processing actions.
 
 ```bash
 git clone git@github.com:EOCoreINT/pygeofetch.git && cd pygeofetch
-pip install -e ".[dev,all]" && pytest tests/unit/ -v
-
+pip install -e ".[test]" && pytest tests/ -v
+```
 
 ## License
 
-MIT — see [LICENSE](LICENSE). © 2026 Samuel Appiah Kubi. Part of the **PyGeoVision** platform, alongside [pygeofetch](https://github.com/appiahkubis14/pygeofetch) itself.
+MIT — see [LICENSE](LICENSE). © 2026 Samuel Appiah Kubi.

{pygeofetch-2.6.2.6 → pygeofetch-2.6.2.7}/README.md

@@ -6,8 +6,9 @@
 [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.22087230.svg)](https://doi.org/10.5281/zenodo.22087230)
 [![Tests](https://github.com/EOCoreINT/pygeofetch/actions/workflows/tests.yml/badge.svg)](https://github.com/EOCoreINT/pygeofetch/actions/workflows/tests.yml)
 [![codecov](https://codecov.io/gh/appiahkubis14/pygeofetch/graph/badge.svg?token=2PS2A2VZL6)](https://codecov.io/gh/appiahkubis14/pygeofetch)
+[![Sponsor](https://img.shields.io/badge/Sponsor-%E2%9D%A4-ea4aaa?logo=githubsponsors)](https://github.com/sponsors/appiahkubis14)
 
-**A unified satellite data and geospatial processing platform — one CLI, one Python API, 24 providers, and a fully verified InSAR chain.**
+**A unified satellite data and geospatial processing platform — one CLI, one Python API, 22 verified providers, and a fully verified InSAR chain.**
 
 [Quick Start](#-quick-start) · [Mexico City Case Study](#-case-study-mapping-mexico-city-land-subsidence-with-insar) · [Case Study Repo ↗](https://github.com/EOCoreINT/mexico-subsidence-project) · [Documentation](https://pygeofetch.readthedocs.io/en/latest/) · [Notebooks](#-notebooks)
 
@@ -18,7 +19,7 @@
 
 ## Overview
 
-pygeofetch is a production-ready framework for acquiring and processing Earth observation data. It provides authenticated, unified access to **24 satellite repositories** — Sentinel, Landsat, Planet, Maxar, Airbus, Copernicus, USGS, NASA, JAXA, and more — through a single CLI and Python API, and layers a complete geospatial processing engine on top.
+pygeofetch is a production-ready framework for acquiring and processing Earth observation data. It provides authenticated, unified access to **22 verified satellite providers** — Sentinel, Landsat, Planet, Maxar, Airbus, Copernicus, USGS, NASA, JAXA, and more — through a single CLI and Python API, and layers a complete geospatial processing engine on top.
 
 Where pygeofetch goes further than most data-access libraries is in its **InSAR chain**: burst-aware coregistration, real flat-earth and topographic phase removal, ERA5 tropospheric and ionospheric correction, phase unwrapping, and SBAS time-series inversion — each stage independently verified against synthetic ground truth or real, published deformation studies, not assumed correct from theory alone. The [Mexico City case study](#-case-study-mapping-mexico-city-land-subsidence-with-insar) below walks through that chain end to end on real Sentinel-1 data.
 
@@ -26,7 +27,7 @@ Where pygeofetch goes further than most data-access libraries is in its **InSAR
 
 | | |
 |---|---|
-| 🔐 **Authenticated access** | 24 providers, credentials stored via system keyring (Keychain / Credential Manager / Secret Service) |
+| 🔐 **Authenticated access** | 22 verified providers; credentials stored via a Fernet-encrypted local file by default, or the system keyring (Keychain / Credential Manager / Secret Service) as an opt-in alternative |
 | 🔍 **Federated search** | One query across all providers → STAC 1.0 GeoJSON / GeoParquet / CSV, with real footprint geometry where the provider supplies it |
 | 📥 **Resilient downloads** | Parallel, resumable, checksum-verified, band-selective, atomic writes |
 | ⚙️ **Preprocessing** | Atmospheric correction, cloud masking, reprojection, resampling, pan-sharpening, mosaicking |
@@ -52,7 +53,7 @@ Satellite data access is fragmented — every provider has its own auth scheme,
 
 | Feature | pygeofetch | EODAG | pystac-client | satpy | sentinelsat |
 |---|---|---|---|---|---|
-| Providers | **24** | 10+ | STAC only | Limited | Sentinel only |
+| Providers | **22** | 10+ | STAC only | Limited | Sentinel only |
 | Processing engine | ✅ Full | ❌ | ❌ | Partial | ❌ |
 | Spectral indices | ✅ 17+ | ❌ | ❌ | ❌ | ❌ |
 | Full InSAR chain | ✅ Verified | ❌ | ❌ | ❌ | ❌ |
@@ -64,9 +65,9 @@ Satellite data access is fragmented — every provider has its own auth scheme,
 
 ## Providers
 
-**11 open-access providers**, no login required — including `planetary_computer`, `aws_earth`, `element84`, `noaa_big_data`, `esa_scihub`, `jaxa_earth`, and `geoserver_generic` for any OGC WMS/WFS/WCS endpoint.
+**22 verified providers total.** Open-access, no login required — including `planetary_computer`, `aws_earth`, `element84`, `noaa_big_data`, `jaxa_earth`, and `geoserver_generic` for any OGC WMS/WFS/WCS endpoint.
 
-**13 authenticated providers** — USGS, Copernicus CDSE, NASA Earthdata (+ Cloud), Alaska SAR Facility, OpenTopography, Planet Labs, Sentinel Hub, Maxar GBDX, Airbus OneAtlas, Google Earth Engine, TerraBotics, and Earth Explorer.
+Authenticated — USGS, Copernicus CDSE, NASA Earthdata (+ Cloud), Alaska SAR Facility, OpenTopography, Planet Labs, Sentinel Hub, Maxar GBDX, Airbus OneAtlas, and Earth Explorer.
 
 Every provider has been directly verified to return at minimum a correct bounding box; several are further confirmed to return real, precise footprint geometry against a live API response (marked in `pygeofetch providers info PROVIDER`). Run `pygeofetch providers list` for the full, current table.
 
@@ -120,23 +121,12 @@ Mexico City sits on a drained lakebed and is subsiding at some of the fastest ra
 
 **1. Authenticated federated search.** `client.search()` against Copernicus Data Space for SLC scenes over the city (bbox `-99.183, 19.278, -99.003, 19.438`, July 2016 – September 2017) returns a stack of Sentinel-1A/1B candidates in seconds, filterable straight down to a single consistent track.
 
-<p align="center"><img src="https://raw.githubusercontent.com/EOCoreINT/mexico-subsidence-project/main/analysis/data-search.png" width="85%" /></p>
-
 Results carry real footprint geometry and drop straight onto a map via `MapViewer`, with hover info for scene ID, date, satellite, and provider — useful for spotting swath overlap before committing to a download.
 
-<p align="center">
-  <img src="https://raw.githubusercontent.com/EOCoreINT/mexico-subsidence-project/main/analysis/search_1.png" width="48%" />
-  <img src="https://raw.githubusercontent.com/EOCoreINT/mexico-subsidence-project/main/analysis/search.png" width="48%" />
-</p>
-
 **2. DEM acquisition.** A matching search against OpenTopography returns seven DEM products for the AOI; pygeofetch downloads and clips the selected one (SRTM 30 m) automatically for topographic phase removal.
 
-<p align="center"><img src="https://raw.githubusercontent.com/EOCoreINT/mexico-subsidence-project/main/analysis/dem_acquisition.png" width="85%" /></p>
-
 **3. Preflight validation.** Before anything downloads, the `PreflightGate` checks search truncation, AOI coverage, temporal network connectivity, and burst-timing family compatibility from lightweight annotation XMLs — catching acquisitions that would waste compute before they cost bandwidth. This run avoided roughly 360 GB of downloads by excluding 48 of 115 candidate scenes at this stage alone.
 
-<p align="center"><img src="https://raw.githubusercontent.com/EOCoreINT/mexico-subsidence-project/main/analysis/preflight-log.png" width="85%" /></p>
-
 Real orbit state vectors then pre-filter the candidate pair list against Sentinel-1's own mission thresholds, rejecting pairs for excess burst-sync error, temporal baseline, or spatial baseline before any interferogram is attempted.
 
 <p align="center"><img src="https://raw.githubusercontent.com/EOCoreINT/mexico-subsidence-project/main/analysis/pre-filter-for-interferogram.png" width="85%" /></p>
@@ -158,8 +148,6 @@ Real orbit state vectors then pre-filter the candidate pair list against Sentine
 
 **7. SBAS time-series inversion.** The full 58-date descending stack, once low-coherence and unreliable-reference-pixel pairs are excluded, fractures into 17 disconnected network "islands" — a genuine finding about this AOI's data quality, not a bug. The largest connected island (10 dates, 11 pairs) carries the final inversion, referenced near Cerro de la Estrella.
 
-<p align="center"><img src="https://raw.githubusercontent.com/EOCoreINT/mexico-subsidence-project/main/analysis/1.png" width="85%" /></p>
-
 The resulting velocity field, uncertainty map, reliability mask, and displacement time series recover a 2nd–98th-percentile vertical velocity of **−35.5 to −2.9 cm/year** where reliable pixels exist.
 
 <p align="center"><img src="https://raw.githubusercontent.com/EOCoreINT/mexico-subsidence-project/main/analysis/island1_sbas_full_analysis.png" width="90%" /></p>
@@ -241,7 +229,7 @@ If you use PyGeoFetch in your research or operational work, please cite it using
   title        = {PyGeoFetch: A Unified Python Framework for Multi-Provider Satellite Data Acquisition, Pre-download Quality Control, and Geospatial Processing},
   year         = {2026},
   publisher    = {Zenodo},
-  version      = {2.6.2.6.1},
+  version      = {2.6.2.7.1},
   doi          = {10.5281/zenodo.22087230},
   url          = {https://doi.org/10.5281/zenodo.22087230}
 }
@@ -251,15 +239,28 @@ If you use PyGeoFetch in your research or operational work, please cite it using
 
 Full documentation: **https://pygeofetch.readthedocs.io/en/latest/** — CLI reference, provider auth guides, pipeline configuration, post-processing catalogue, and InSAR verification methodology.
 
+## Support this project
+
+pygeofetch is built and maintained by a single developer, in the open,
+alongside a full-time workload — the InSAR/optical fusion chain, the
+provider verification work, and the documentation are all real,
+independently-verified engineering, not a side project maintained on
+autopilot. If pygeofetch is useful to your research or your
+organization, sponsoring its development directly funds the time spent
+keeping 22 provider integrations current as their real APIs change, and
+building out the multi-sensor pipelines documented above.
+
+[![Sponsor on GitHub](https://img.shields.io/badge/Sponsor-GitHub%20Sponsors-ea4aaa?logo=githubsponsors)](https://github.com/sponsors/appiahkubis14)
+
 ## Contributing
 
 Contributions are welcome — see [CONTRIBUTING.md](CONTRIBUTING.md). Good first issues include extending real footprint geometry to remaining bbox-only providers, wiring stub providers to full API integrations, and adding new post-processing actions.
 
 ```bash
 git clone git@github.com:EOCoreINT/pygeofetch.git && cd pygeofetch
-pip install -e ".[dev,all]" && pytest tests/unit/ -v
-
+pip install -e ".[test]" && pytest tests/ -v
+```
 
 ## License
 
-MIT — see [LICENSE](LICENSE). © 2026 Samuel Appiah Kubi. Part of the **PyGeoVision** platform, alongside [pygeofetch](https://github.com/appiahkubis14/pygeofetch) itself.
+MIT — see [LICENSE](LICENSE). © 2026 Samuel Appiah Kubi.

{pygeofetch-2.6.2.6 → pygeofetch-2.6.2.7}/pygeofetch/__init__.py

@@ -30,7 +30,7 @@ CLI::
     pygeofetch doctor
 """
 
-__version__ = "2.6.2.6.4"
+__version__ = "2.6.2.7.4"
 __author__ = "PyGeoFetch Contributors"
 __license__ = "MIT"
 

pygeofetch-2.6.2.7/pygeofetch/geotech/risk_mapper.py

@@ -0,0 +1,276 @@
+"""
+Domain-specific geotechnical risk mapping.
+
+Extends this project's existing strain calculation
+(`pygeofetch.optical.offset_tracking.compute_horizontal_strain`) with
+curvature -- the real, standard second spatial derivative of a
+displacement field -- and combines both with velocity into a single,
+normalized, physically-capped risk index.
+
+Real, standard geotechnical grounding: curvature of the ground surface
+is a real, long-established predictor of structural damage in mining
+subsidence engineering (National Coal Board, 1975, *Subsidence
+Engineering Handbook*) -- a curved ground surface bends whatever rigid
+structure sits on it, and that bending strain is what actually cracks
+foundations and walls, not subsidence magnitude alone. The NCB's own
+real, cited strain-based damage categories are reused here as the real
+reference scale for this module's strain sub-score (see
+`compute_geotechnical_risk_index`'s own docstring).
+
+Real, honest note on `compute_curvature`'s two real inputs: the
+standard subsidence-engineering convention computes curvature from a
+*single* vertical displacement/subsidence field, not two horizontal
+components. This module's own `compute_curvature(dx, dy, ...)`
+generalizes that to accept displacement magnitude
+(sqrt(dx^2 + dy^2)) computed from two real horizontal components -- a
+real, honest extension for this project's own broader, multi-modal
+scope (lateral landslide movement, co-seismic horizontal slip), not
+identical to the classic vertical-subsidence-only NCB convention. Pass
+the same real array for both `dx` and `dy=0` (a real zero array, same
+shape) to reproduce standard single-field vertical curvature exactly.
+
+Real, direct connection to a previously-found bug, stated explicitly
+rather than left implicit: this project's own real, live Bu'ertai
+validation run produced a genuine 617% strain artifact from a small
+number of spurious optical correlator matches -- caught and fixed with
+real outlier protection in `compute_horizontal_strain` itself. The
+"strict, physically plausible capping" this module applies on top of
+that is a second, independent real safeguard: even a genuinely
+outlier-filtered strain value should never be allowed to dominate a
+risk score computed from it, since real ground strain at the level
+mining-subsidence engineering considers "very severe" is on the order
+of 1% (NCB, 1975) -- several orders of magnitude below any of the
+617%-class artifacts this project has directly, empirically observed.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+logger = logging.getLogger("pygeofetch.geotech.risk_mapper")
+
+
+class RiskMapperConfig(BaseModel):
+    """
+    Real, configurable reference scales for
+    `compute_geotechnical_risk_index`.
+
+    Real, cited defaults for strain (National Coal Board, 1975): the
+    NCB's own published damage categories place "very severe" damage
+    at real ground strains at or above 1.0% (0.01) -- used here as the
+    real strain value that alone saturates this sub-score to 100.
+
+    Real, honest note on the velocity and curvature defaults: unlike
+    strain, there is no single, universally-cited numeric threshold
+    for "high-risk" velocity or curvature across all real deformation
+    contexts (mining, landslide, urban subsidence each have their own
+    real, site-specific conventions) -- the defaults below are
+    reasonable, real, commonly-encountered reference points (matching
+    the same order of magnitude routinely reported in real InSAR
+    mining-subsidence literature this project's own Bu'ertai/Mexico
+    City validation work references), not a cited universal standard
+    the way the strain threshold is. Override them with a real,
+    site-specific reference value whenever one is available.
+    """
+
+    max_severe_strain: float = Field(
+        0.01,
+        gt=0,
+        description="Real strain (fraction, not %) at which the strain sub-score saturates to 100 -- NCB (1975) 'very severe' threshold.",
+    )
+    max_severe_velocity_m_per_year: float = Field(
+        0.5,
+        gt=0,
+        description="Real velocity magnitude (m/yr) at which the velocity sub-score saturates to 100 -- a reasonable, site-adjustable reference, not a cited universal standard.",
+    )
+    max_severe_curvature_per_m: float = Field(
+        0.001,
+        gt=0,
+        description="Real curvature magnitude (1/m) at which the curvature sub-score saturates to 100 -- a reasonable, site-adjustable reference, not a cited universal standard.",
+    )
+    strain_cap: float = Field(
+        0.10,
+        gt=0,
+        description="Real, hard physical plausibility ceiling (fraction) applied to strain before it enters the risk index at all -- protects against exactly the class of spurious, order-of-magnitude-too-large artifact this project has directly observed (a real 617% strain case), independent of whatever outlier protection already ran upstream.",
+    )
+    combination: str = Field(
+        "max_weighted",
+        description="'max_weighted' (default) or 'mean' -- see compute_geotechnical_risk_index's own docstring.",
+    )
+
+
+def compute_curvature(dx: Any, dy: Any, pixel_size_m: float) -> dict:
+    """
+    Real curvature (second spatial derivative) of a displacement
+    field -- see this module's own docstring for the real, important
+    distinction between this generalized, magnitude-based computation
+    and the classic, single-field vertical-subsidence convention.
+
+    Real, standard central finite-difference implementation: computes
+    `np.gradient` twice (first derivative, then the derivative of that)
+    on the real displacement magnitude field, matching the exact same
+    real numerical approach `compute_horizontal_strain` already uses
+    for its own first-derivative strain tensor.
+
+    Parameters
+    ----------
+    dx, dy : np.ndarray
+        Real horizontal displacement components, metres, same shape
+        (e.g. from `compute_pixel_offsets`). Pass a real zero array for
+        `dy` to compute standard single-field curvature on `dx` alone.
+    pixel_size_m : float
+        Real ground distance between adjacent grid samples, metres.
+
+    Returns
+    -------
+    dict
+        Real keys: ``"curvature_xx"``, ``"curvature_yy"`` (the two real
+        principal second-derivative components of displacement
+        magnitude), and ``"curvature_max"`` (real, per-pixel maximum
+        absolute value of the two -- the real, standard single scalar
+        used as the risk-relevant curvature magnitude in mining
+        subsidence engineering).
+
+    Raises
+    ------
+    ValueError
+        If `dx`/`dy` don't share a real, identical shape.
+    """
+    import numpy as np
+
+    dx = np.asarray(dx, dtype="float64")
+    dy = np.asarray(dy, dtype="float64")
+    if dx.shape != dy.shape:
+        raise ValueError(
+            f"compute_curvature: dx/dy shape mismatch {dx.shape} vs {dy.shape}"
+        )
+
+    magnitude = np.sqrt(dx**2 + dy**2)
+
+    # First derivative (real, same np.gradient convention already
+    # verified in compute_horizontal_strain: returns (d/d_row, d/d_col)).
+    d_mag_drow, d_mag_dcol = np.gradient(magnitude, pixel_size_m)
+    # Second derivative -- the real curvature.
+    _, curvature_xx = np.gradient(d_mag_dcol, pixel_size_m)
+    curvature_yy, _ = np.gradient(d_mag_drow, pixel_size_m)
+
+    curvature_max = np.maximum(np.abs(curvature_xx), np.abs(curvature_yy))
+
+    return {
+        "curvature_xx": curvature_xx,
+        "curvature_yy": curvature_yy,
+        "curvature_max": curvature_max,
+    }
+
+
+def compute_geotechnical_risk_index(
+    velocity: Any,
+    max_shear_strain: Any,
+    curvature: Any,
+    config: "RiskMapperConfig | None" = None,
+) -> dict:
+    """
+    Real, normalized (0-100) geotechnical risk index combining
+    velocity, strain, and curvature -- with real, physically-plausible
+    capping on strain before it enters the index at all.
+
+    Parameters
+    ----------
+    velocity : np.ndarray
+        Real displacement velocity magnitude, m/yr (vertical InSAR
+        velocity, fused multi-modal velocity, or horizontal magnitude
+        -- whichever real quantity is the relevant risk driver for
+        your specific site).
+    max_shear_strain : np.ndarray
+        Real max shear strain (fraction, not %) -- e.g. from
+        `compute_horizontal_strain`'s own `exy` output, or a real,
+        independently-computed principal shear strain.
+    curvature : np.ndarray
+        Real curvature magnitude (1/m) -- e.g.
+        `compute_curvature(...)["curvature_max"]`.
+    config : RiskMapperConfig, optional
+        Real, configurable reference scales and combination method.
+
+    Returns
+    -------
+    dict
+        Real keys: ``"risk_index"`` (0-100, per-pixel), ``"velocity_score"``,
+        ``"strain_score"``, ``"curvature_score"`` (each 0-100, the real
+        per-factor sub-scores before combination), and
+        ``"n_strain_capped"`` (real count of pixels where the real,
+        physical plausibility cap in `config.strain_cap` actually
+        triggered -- inspect this; a large number here means a lot of
+        your input strain is implausible and worth investigating at
+        its real source before trusting this risk map).
+
+    Notes
+    -----
+    Real, deliberate combination logic (`config.combination`):
+
+    - ``"max_weighted"`` (default): the risk index is dominated by
+      whichever single real factor is worst, not diluted by averaging
+      it with two moderate ones -- matching real geotechnical practice,
+      where one severe factor (e.g. curvature alone, even with modest
+      velocity and strain) is a real, standalone reason for concern.
+      Computed as `0.6 * max(scores) + 0.4 * mean(scores)`.
+    - ``"mean"``: a plain, equal-weighted average of the three real
+      sub-scores -- provided as a simpler, real alternative, but will
+      understate risk in a real scenario where only one factor is
+      severe.
+    """
+    import numpy as np
+
+    config = config or RiskMapperConfig()
+
+    velocity = np.abs(np.asarray(velocity, dtype="float64"))
+    strain = np.asarray(max_shear_strain, dtype="float64")
+    curvature = np.abs(np.asarray(curvature, dtype="float64"))
+
+    # Real, physical plausibility cap -- applied BEFORE strain enters
+    # the index at all, independent of whatever outlier protection
+    # already ran upstream (see this module's own docstring for the
+    # real, directly-observed 617% artifact this specifically guards
+    # against).
+    strain_capped = np.abs(strain)
+    n_strain_capped = int((strain_capped > config.strain_cap).sum())
+    strain_capped = np.clip(strain_capped, 0, config.strain_cap)
+
+    velocity_score = np.clip(
+        100 * velocity / config.max_severe_velocity_m_per_year, 0, 100
+    )
+    strain_score = np.clip(100 * strain_capped / config.max_severe_strain, 0, 100)
+    curvature_score = np.clip(
+        100 * curvature / config.max_severe_curvature_per_m, 0, 100
+    )
+
+    if config.combination == "max_weighted":
+        stacked = np.stack([velocity_score, strain_score, curvature_score])
+        risk_index = 0.6 * stacked.max(axis=0) + 0.4 * stacked.mean(axis=0)
+    elif config.combination == "mean":
+        risk_index = (velocity_score + strain_score + curvature_score) / 3.0
+    else:
+        raise ValueError(
+            f"compute_geotechnical_risk_index: config.combination must be "
+            f"'max_weighted' or 'mean', got {config.combination!r}"
+        )
+
+    if n_strain_capped > 0:
+        logger.warning(
+            "compute_geotechnical_risk_index: %d pixels had strain above the "
+            "real physical plausibility cap (%.1f%%) and were clipped -- "
+            "investigate the real source of these values before trusting "
+            "this risk map at those pixels.",
+            n_strain_capped,
+            100 * config.strain_cap,
+        )
+
+    return {
+        "risk_index": np.clip(risk_index, 0, 100),
+        "velocity_score": velocity_score,
+        "strain_score": strain_score,
+        "curvature_score": curvature_score,
+        "n_strain_capped": n_strain_capped,
+    }