PyGeoFetch 1.7.0__tar.gz → 1.9.0__tar.gz

{pygeofetch-1.7.0 → pygeofetch-1.9.0}/CHANGELOG.md

@@ -1,9 +1,9 @@
 # Changelog
 
 All notable changes to PyGeoFetch are documented here.
-Format follows [Keep a Changelog](https://keepachangelog.com/en/1.7.0/).
+Format follows [Keep a Changelog](https://keepachangelog.com/en/1.9.0/).
 
-## [1.7.0] — 2026-07-12
+## [1.9.0] — 2026-07-12
 
 ### Added
 - Federated search across 22+ satellite data providers

{pygeofetch-1.7.0/pygeofetch.egg-info → pygeofetch-1.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pygeofetch
-Version: 1.7.0
+Version: 1.9.0
 Summary: Universal satellite data pipeline + geospatial processing platform
 Author-email: Samuel Appiah Kubi <appiahkubis14@gmail.com>
 License: MIT License
@@ -94,8 +94,8 @@ Requires-Dist: plotly>=5.14.0; extra == "viz"
 Requires-Dist: whitebox>=2.3.0; extra == "viz"
 Requires-Dist: whiteboxgui>=2.3.0; extra == "viz"
 Requires-Dist: geemap>=0.28.0; extra == "viz"
-Requires-Dist: osmnx>=1.7.0; extra == "viz"
-Requires-Dist: contextily>=1.7.0; extra == "viz"
+Requires-Dist: osmnx>=1.9.0; extra == "viz"
+Requires-Dist: contextily>=1.9.0; extra == "viz"
 Requires-Dist: xyzservices>=2023.10.0; extra == "viz"
 Requires-Dist: mapclassify>=2.5.0; extra == "viz"
 Requires-Dist: geoplot>=0.5.0; extra == "viz"
@@ -467,6 +467,70 @@ pygeofetch proc-pipeline template change_detection
 
 ---
 
+
+### 🌐 InSAR Processing (`pygeofetch.insar`)
+
+A full Interferometric SAR chain for Sentinel-1 — search through SBAS time series inversion, pure Python, no external InSAR software required beyond `snaphu-py`'s bundled unwrapper.
+
+```bash
+pip install "pygeofetch[insar]"        # native SBAS inversion
+pip install "pygeofetch[insar-full]"   # + MintPy passthrough for advanced corrections
+```
+
+| Component | Description |
+|---|---|
+| `InterferogramGenerator` | Coregistration (real orbit-based, or shape-based fallback) + Enhanced Spectral Diversity (ESD) refinement for TOPS burst continuity + topographic phase removal |
+| `PhaseUnwrapper` | SNAPHU (Chen & Zebker 2001) via the official `snaphu-py` bindings — the same algorithm used by ASF, ISCE2/3, GAMMA, and SNAP |
+| `AtmosphericCorrector` | Elevation-correlated regression or ERA5 reanalysis-based tropospheric delay correction |
+| `SBASTimeSeries` | Small BAseline Subset displacement/velocity inversion (Berardino et al. 2002) |
+| `DataValidator` | SLC, coherence, and SBAS-network sanity checks, wired in at every real pipeline entry point |
+
+Real orbit-based coregistration computes genuine per-pixel offsets from actual satellite orbit state vectors and acquisition timing (not a shape-matching guess) — supply a DEM, both SAFE archives, and both `.EOF` orbit files, and it's used automatically; otherwise falls back cleanly to shape-based resampling.
+
+Every stage supports automatic visualization (`auto_visualize=True`) and optional GPU acceleration (`use_gpu=True`, CuPy) for coherence estimation and SBAS inversion on large scenes.
+
+See [`pygeofetch/insar/README.md`](pygeofetch/insar/README.md) for the full processing chain, verification methodology, and current limitations.
+
+
+```python
+# InSAR — search to SBAS time series
+from pygeofetch.insar import (
+    InterferogramGenerator, PhaseUnwrapper, AtmosphericCorrector,
+    SBASTimeSeries, DataValidator,
+)
+from pygeofetch.insar.timeseries import InterferogramPair
+from pygeofetch.core.orbits import fetch_orbit_file
+
+# Coregistration + interferogram formation (real orbit-based when a DEM,
+# both SAFE archives, and both orbit files are supplied; falls back to
+# shape-based resampling otherwise)
+gen = InterferogramGenerator(coherence_window=5, esd_enabled=True, use_gpu=False)
+result = gen.process_pair(
+    reference="slc_ref.tif", secondary="slc_sec.tif", dem="dem.tif",
+    reference_safe_zip="ref.SAFE.zip", secondary_safe_zip="sec.SAFE.zip",
+    reference_orbit_file=fetch_orbit_file("S1A_..._ref"),
+    secondary_orbit_file=fetch_orbit_file("S1A_..._sec"),
+)
+result.save("./output", auto_visualize=True)
+
+# Atmospheric correction + phase unwrapping
+atm = AtmosphericCorrector(method="elevation")
+corrected_phase = atm.correct(result.interferogram, dem="dem.tif")
+
+unwrapper = PhaseUnwrapper(cost_mode="defo", init_method="mcf")
+unwrapped, conncomp = unwrapper.unwrap(corrected_phase, result.coherence)
+
+# SBAS time series inversion across a network of interferograms
+pairs = [
+    InterferogramPair("2026-01-01", "2026-01-13", unwrapped, result.coherence),
+    # ... additional pairs forming a connected network
+]
+sbas = SBASTimeSeries(wavelength_m=0.05546576, reference_date="2026-01-01")
+ts_result = sbas.invert(pairs, reference_pixel=(10, 15))  # known-stable pixel
+ts_result.save("./timeseries", auto_visualize=True)
+print(f"Mean velocity: {ts_result.velocity.mean()*1000:.1f} mm/year")
+```
+
 ## 🖥️ Complete CLI Reference
 
 ```
@@ -653,3 +717,8 @@ pytest tests/unit/ -v
 pygeofetch is free and open source software, licensed under the [MIT License](LICENSE).
 
 © 2026 Samuel Appiah Kubi. Part of the **PyGeoVision** platform — [pygeofetch](https://github.com/appiahkubis14/pygeofetch) (data + processing)  complete Earth observation pipeline.
+
+
+
+
+

{pygeofetch-1.7.0 → pygeofetch-1.9.0}/README.md

@@ -331,6 +331,70 @@ pygeofetch proc-pipeline template change_detection
 
 ---
 
+
+### 🌐 InSAR Processing (`pygeofetch.insar`)
+
+A full Interferometric SAR chain for Sentinel-1 — search through SBAS time series inversion, pure Python, no external InSAR software required beyond `snaphu-py`'s bundled unwrapper.
+
+```bash
+pip install "pygeofetch[insar]"        # native SBAS inversion
+pip install "pygeofetch[insar-full]"   # + MintPy passthrough for advanced corrections
+```
+
+| Component | Description |
+|---|---|
+| `InterferogramGenerator` | Coregistration (real orbit-based, or shape-based fallback) + Enhanced Spectral Diversity (ESD) refinement for TOPS burst continuity + topographic phase removal |
+| `PhaseUnwrapper` | SNAPHU (Chen & Zebker 2001) via the official `snaphu-py` bindings — the same algorithm used by ASF, ISCE2/3, GAMMA, and SNAP |
+| `AtmosphericCorrector` | Elevation-correlated regression or ERA5 reanalysis-based tropospheric delay correction |
+| `SBASTimeSeries` | Small BAseline Subset displacement/velocity inversion (Berardino et al. 2002) |
+| `DataValidator` | SLC, coherence, and SBAS-network sanity checks, wired in at every real pipeline entry point |
+
+Real orbit-based coregistration computes genuine per-pixel offsets from actual satellite orbit state vectors and acquisition timing (not a shape-matching guess) — supply a DEM, both SAFE archives, and both `.EOF` orbit files, and it's used automatically; otherwise falls back cleanly to shape-based resampling.
+
+Every stage supports automatic visualization (`auto_visualize=True`) and optional GPU acceleration (`use_gpu=True`, CuPy) for coherence estimation and SBAS inversion on large scenes.
+
+See [`pygeofetch/insar/README.md`](pygeofetch/insar/README.md) for the full processing chain, verification methodology, and current limitations.
+
+
+```python
+# InSAR — search to SBAS time series
+from pygeofetch.insar import (
+    InterferogramGenerator, PhaseUnwrapper, AtmosphericCorrector,
+    SBASTimeSeries, DataValidator,
+)
+from pygeofetch.insar.timeseries import InterferogramPair
+from pygeofetch.core.orbits import fetch_orbit_file
+
+# Coregistration + interferogram formation (real orbit-based when a DEM,
+# both SAFE archives, and both orbit files are supplied; falls back to
+# shape-based resampling otherwise)
+gen = InterferogramGenerator(coherence_window=5, esd_enabled=True, use_gpu=False)
+result = gen.process_pair(
+    reference="slc_ref.tif", secondary="slc_sec.tif", dem="dem.tif",
+    reference_safe_zip="ref.SAFE.zip", secondary_safe_zip="sec.SAFE.zip",
+    reference_orbit_file=fetch_orbit_file("S1A_..._ref"),
+    secondary_orbit_file=fetch_orbit_file("S1A_..._sec"),
+)
+result.save("./output", auto_visualize=True)
+
+# Atmospheric correction + phase unwrapping
+atm = AtmosphericCorrector(method="elevation")
+corrected_phase = atm.correct(result.interferogram, dem="dem.tif")
+
+unwrapper = PhaseUnwrapper(cost_mode="defo", init_method="mcf")
+unwrapped, conncomp = unwrapper.unwrap(corrected_phase, result.coherence)
+
+# SBAS time series inversion across a network of interferograms
+pairs = [
+    InterferogramPair("2026-01-01", "2026-01-13", unwrapped, result.coherence),
+    # ... additional pairs forming a connected network
+]
+sbas = SBASTimeSeries(wavelength_m=0.05546576, reference_date="2026-01-01")
+ts_result = sbas.invert(pairs, reference_pixel=(10, 15))  # known-stable pixel
+ts_result.save("./timeseries", auto_visualize=True)
+print(f"Mean velocity: {ts_result.velocity.mean()*1000:.1f} mm/year")
+```
+
 ## 🖥️ Complete CLI Reference
 
 ```
@@ -517,3 +581,8 @@ pytest tests/unit/ -v
 pygeofetch is free and open source software, licensed under the [MIT License](LICENSE).
 
 © 2026 Samuel Appiah Kubi. Part of the **PyGeoVision** platform — [pygeofetch](https://github.com/appiahkubis14/pygeofetch) (data + processing)  complete Earth observation pipeline.
+
+
+
+
+

{pygeofetch-1.7.0 → pygeofetch-1.9.0}/pygeofetch/__init__.py

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

{pygeofetch-1.7.0 → pygeofetch-1.9.0}/pygeofetch/insar/__init__.py

@@ -52,9 +52,39 @@ Usage::
 
 from pygeofetch.insar.atmosphere import AtmosphericCorrector
 from pygeofetch.insar.extraction import SLCExtractor
+from pygeofetch.insar.gpu import gpu_available
 from pygeofetch.insar.interferogram import InterferogramGenerator, InterferogramResult
 from pygeofetch.insar.timeseries import SBASTimeSeries
 from pygeofetch.insar.unwrap import PhaseUnwrapper
+from pygeofetch.insar.validate import DataValidator, ValidationResult
+from pygeofetch.insar.visualize import (
+    visualize_interferogram,
+    visualize_timeseries,
+    visualize_unwrapped,
+)
+
+# Real, orbit-based coregistration components. All exported here are
+# individually verified against known ground truth (see each module's
+# docstring for specifics): annotation.py against ESA's own field-path
+# spec; orbit parsing/interpolation against exact reference values;
+# find_zero_doppler_time against known times from starting guesses up
+# to 30 seconds off; geodetic_to_ecef via round-trip verification.
+# solve_ground_point (in geolocation.py) is deliberately NOT exported
+# here — it has a known, unresolved reliability gap and is not
+# recommended as a primary coregistration path; use
+# compute_offset_field_from_dem() instead, which avoids it entirely.
+from pygeofetch.insar.annotation import SLCGeometry, parse_slc_geometry
+from pygeofetch.insar.geolocation import (
+    geodetic_to_ecef,
+    find_zero_doppler_time,
+    parse_orbit_file,
+    interpolate_orbit_state,
+)
+from pygeofetch.insar.coregister import (
+    compute_offset_field_from_dem,
+    fit_offset_polynomial,
+    resample_with_offset_field,
+)
 
 __all__ = [
     "InterferogramGenerator",
@@ -63,4 +93,19 @@ __all__ = [
     "SBASTimeSeries",
     "AtmosphericCorrector",
     "SLCExtractor",
-]
+    "DataValidator",
+    "ValidationResult",
+    "gpu_available",
+    "visualize_interferogram",
+    "visualize_unwrapped",
+    "visualize_timeseries",
+    "SLCGeometry",
+    "parse_slc_geometry",
+    "geodetic_to_ecef",
+    "find_zero_doppler_time",
+    "parse_orbit_file",
+    "interpolate_orbit_state",
+    "compute_offset_field_from_dem",
+    "fit_offset_polynomial",
+    "resample_with_offset_field",
+]

pygeofetch-1.9.0/pygeofetch/insar/annotation.py

@@ -0,0 +1,153 @@
+"""
+Sentinel-1 annotation XML parsing — real per-pixel acquisition timing.
+
+This is the missing link between "a pixel at (row, col) in an extracted
+SLC GeoTIFF" and "the exact acquisition time and slant range needed to
+feed geolocation.py's orbit-based solver" — that information does not
+exist in the GeoTIFF itself (a general raster format); it lives in a
+separate XML file inside the .SAFE archive.
+
+Field paths confirmed against ESA's own Mission Performance Centre
+documentation (Thermal Denoising of Products Generated by the S-1 IPF,
+MPC-0392):
+
+    /product/imageAnnotation/imageInformation/productFirstLineUtcTime
+    /product/imageAnnotation/imageInformation/azimuthTimeInterval
+    /product/imageAnnotation/imageInformation/slantRangeTime
+    /product/generalAnnotation/productInformation/rangeSamplingRate
+"""
+
+from __future__ import annotations
+
+import logging
+import zipfile
+from dataclasses import dataclass
+from datetime import datetime, timedelta
+from pathlib import Path
+from typing import Optional, Union
+
+logger = logging.getLogger("pygeofetch.insar.annotation")
+
+SPEED_OF_LIGHT = 299792458.0
+
+
+@dataclass
+class SLCGeometry:
+    """
+    Real per-pixel acquisition geometry for one Sentinel-1 SLC measurement,
+    parsed from its annotation XML — everything needed to convert a pixel
+    (row, col) into an exact acquisition time and slant range.
+    """
+
+    first_line_time: datetime
+    azimuth_time_interval_s: float
+    near_range_time_s: float
+    range_sampling_rate_hz: float
+    n_lines: int
+    n_columns: int
+
+    def azimuth_time(self, row: float) -> datetime:
+        """Exact acquisition time of a given (possibly fractional) row."""
+        return self.first_line_time + timedelta(
+            seconds=row * self.azimuth_time_interval_s
+        )
+
+    def range_time(self, col: float) -> float:
+        """Two-way slant range time (seconds) of a given (possibly
+        fractional) column."""
+        return self.near_range_time_s + col / self.range_sampling_rate_hz
+
+    def slant_range_m(self, col: float) -> float:
+        """One-way slant range (metres) of a given column."""
+        return self.range_time(col) * SPEED_OF_LIGHT / 2.0
+
+    def row_for_azimuth_time(self, t: datetime) -> float:
+        """Inverse of azimuth_time(): which (fractional) row corresponds
+        to a given acquisition time."""
+        return (t - self.first_line_time).total_seconds() / self.azimuth_time_interval_s
+
+    def col_for_range_time(self, range_time_s: float) -> float:
+        """Inverse of range_time(): which (fractional) column corresponds
+        to a given two-way range time."""
+        return (range_time_s - self.near_range_time_s) * self.range_sampling_rate_hz
+
+
+def parse_slc_geometry(
+    safe_zip_path: Union[str, Path], member_hint: Optional[str] = None
+) -> SLCGeometry:
+    """
+    Parse real per-pixel acquisition geometry from a Sentinel-1 SAFE
+    archive's annotation XML.
+
+    Args:
+        safe_zip_path: Path to the downloaded .SAFE.zip archive.
+        member_hint:   Optional substring to disambiguate which
+                       annotation file to use when multiple sub-swaths/
+                       polarisations are present (e.g. "iw2-vv" or the
+                       measurement filename this geometry corresponds
+                       to). If None, uses the first annotation XML found.
+
+    Returns:
+        A real SLCGeometry with the exact timing needed to feed
+        geolocation.py's solve_ground_point().
+
+    Raises:
+        ValueError if no annotation XML is found, or a required field
+        is missing — surfaced clearly rather than returning a
+        geometry built from guessed/default values.
+    """
+    import xml.etree.ElementTree as ET
+
+    with zipfile.ZipFile(safe_zip_path) as zf:
+        candidates = [
+            n for n in zf.namelist()
+            if "/annotation/" in n and n.lower().endswith(".xml")
+            and "/calibration/" not in n.lower()
+        ]
+        if member_hint:
+            filtered = [n for n in candidates if member_hint.lower() in n.lower()]
+            if filtered:
+                candidates = filtered
+
+        if not candidates:
+            raise ValueError(
+                f"{safe_zip_path}: no annotation XML found — this doesn't "
+                f"look like a real Sentinel-1 SAFE archive, or the "
+                f"expected internal structure has changed."
+            )
+
+        with zf.open(candidates[0]) as f:
+            root = ET.parse(f).getroot()
+
+    def get_text(path: str) -> str:
+        elem = root.find(path)
+        if elem is None or elem.text is None:
+            raise ValueError(
+                f"{safe_zip_path}: required annotation field missing: {path}"
+            )
+        return elem.text
+
+    first_line_str = get_text(".//imageAnnotation/imageInformation/productFirstLineUtcTime")
+    first_line_time = datetime.fromisoformat(first_line_str)
+
+    geometry = SLCGeometry(
+        first_line_time=first_line_time,
+        azimuth_time_interval_s=float(
+            get_text(".//imageAnnotation/imageInformation/azimuthTimeInterval")
+        ),
+        near_range_time_s=float(
+            get_text(".//imageAnnotation/imageInformation/slantRangeTime")
+        ),
+        range_sampling_rate_hz=float(
+            get_text(".//generalAnnotation/productInformation/rangeSamplingRate")
+        ),
+        n_lines=int(get_text(".//imageAnnotation/imageInformation/numberOfLines")),
+        n_columns=int(get_text(".//imageAnnotation/imageInformation/numberOfColumns")),
+    )
+
+    logger.info(
+        "Parsed real SLC geometry from %s: %d x %d, starting %s",
+        Path(safe_zip_path).name, geometry.n_lines, geometry.n_columns,
+        geometry.first_line_time,
+    )
+    return geometry