PyGeoFetch 1.6.0__tar.gz → 1.8.0__tar.gz

{pygeofetch-1.6.0 → pygeofetch-1.8.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.6.0/).
+Format follows [Keep a Changelog](https://keepachangelog.com/en/1.8.0/).
 
-## [1.6.0] — 2026-07-12
+## [1.8.0] — 2026-07-12
 
 ### Added
 - Federated search across 22+ satellite data providers

{pygeofetch-1.6.0/pygeofetch.egg-info → pygeofetch-1.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pygeofetch
-Version: 1.6.0
+Version: 1.8.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.6.0; extra == "viz"
+Requires-Dist: osmnx>=1.8.0; extra == "viz"
+Requires-Dist: contextily>=1.8.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"

{pygeofetch-1.6.0 → pygeofetch-1.8.0}/pygeofetch/__init__.py

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

{pygeofetch-1.6.0 → pygeofetch-1.8.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.8.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

pygeofetch-1.8.0/pygeofetch/insar/coregister.py

@@ -0,0 +1,339 @@
+"""
+Real orbit-based coregistration offset field.
+
+Combines annotation.py (real per-pixel acquisition timing) and
+geolocation.py (the orbit-based Doppler/Range/Ellipsoid solve) to
+compute a genuine, physically-grounded offset field between a
+reference and secondary SLC — replacing the naive shape-only resample
+that was previously used regardless of whether the two images were
+actually aligned.
+
+Method (standard practice, e.g. Kampes, Hanssen & Perski 2003; matches
+what the 2019 URSI paper and the current TOPS coregistration literature
+both describe): compute the real offset at a sparse grid of points
+across the image (not every pixel — solving per pixel would be far
+too slow and offers no real accuracy benefit, since the offset field
+is smooth), fit a low-degree 2D polynomial to that sparse grid, then
+apply the fitted, dense field to resample the secondary image.
+"""
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+from typing import Tuple, Union
+
+logger = logging.getLogger("pygeofetch.insar.coregister")
+
+
+def compute_offset_field_from_dem(
+    ref_geometry,
+    ref_orbit,
+    sec_geometry,
+    sec_orbit,
+    dem_path: Union[str, Path],
+    ref_scene_center_time,
+    sec_scene_center_time,
+    grid_points: int = 7,
+):
+    """
+    Compute a real, orbit-based offset field using ground points sampled
+    directly from a real DEM's own geographic coordinates — not solved
+    for via the unreliable solve_ground_point(). This is the
+    recommended path: it uses only components verified reliable
+    (geodetic_to_ecef, a closed-form conversion with no iteration, and
+    find_zero_doppler_time, confirmed robust even from starting guesses
+    tens of seconds off), never the 3-equation Doppler/Range/Ellipsoid
+    solve that has a known, unresolved reliability gap.
+
+    Args:
+        ref_geometry, sec_geometry: SLCGeometry for each image.
+        ref_orbit, sec_orbit: (times, positions, velocities) for each.
+        dem_path:      A real DEM covering the scene, with real
+                       geographic (lat/lon) referencing — the same DEM
+                       already optionally supplied to process_pair()
+                       for topographic phase removal.
+        ref_scene_center_time, sec_scene_center_time: Approximate
+                       acquisition time for each image (e.g. each
+                       geometry's azimuth_time() at its own centre row)
+                       — used as the starting guess for
+                       find_zero_doppler_time(), which only needs to be
+                       roughly right (confirmed robust to a 30-second-
+                       off starting guess in testing).
+        grid_points:   Sample grid resolution per axis.
+
+    Returns:
+        (grid_rows, grid_cols, offset_rows, offset_cols) — same shape
+        as compute_offset_field(), ready for fit_offset_polynomial().
+
+    Raises:
+        RuntimeError if too many grid points fail (more than half) —
+        a real, actionable signal (e.g. the DEM doesn't actually
+        overlap the scene), not silently tolerated.
+    """
+    import numpy as np
+    import rasterio
+
+    from pygeofetch.insar.geolocation import geodetic_to_ecef, find_zero_doppler_time
+
+    with rasterio.open(dem_path) as src:
+        dem = src.read(1)
+        transform = src.transform
+        dem_h, dem_w = dem.shape
+
+    dem_row_samples = [int(r) for r in _linspace(0, dem_h - 1, grid_points)]
+    dem_col_samples = [int(c) for c in _linspace(0, dem_w - 1, grid_points)]
+
+    grid_rows, grid_cols, offset_rows, offset_cols = [], [], [], []
+    n_failed = 0
+    n_total = 0
+
+    for dem_row in dem_row_samples:
+        for dem_col in dem_col_samples:
+            n_total += 1
+            try:
+                lon, lat = transform * (dem_col + 0.5, dem_row + 0.5)
+                height = float(dem[dem_row, dem_col])
+                if not np.isfinite(height):
+                    height = 0.0
+                ground_point = geodetic_to_ecef(lat, lon, height)
+
+                t_ref = find_zero_doppler_time(
+                    ref_orbit[0], ref_orbit[1], ref_orbit[2],
+                    ground_point, ref_scene_center_time,
+                )
+                t_sec = find_zero_doppler_time(
+                    sec_orbit[0], sec_orbit[1], sec_orbit[2],
+                    ground_point, sec_scene_center_time,
+                )
+
+                ref_row = ref_geometry.row_for_azimuth_time(t_ref)
+                sec_row = sec_geometry.row_for_azimuth_time(t_sec)
+
+                sat_pos_ref, _ = _interpolate(ref_orbit, t_ref)
+                sat_pos_sec, _ = _interpolate(sec_orbit, t_sec)
+                range_ref_time = 2 * _distance(sat_pos_ref, ground_point) / 299792458.0
+                range_sec_time = 2 * _distance(sat_pos_sec, ground_point) / 299792458.0
+                ref_col = ref_geometry.col_for_range_time(range_ref_time)
+                sec_col = sec_geometry.col_for_range_time(range_sec_time)
+
+                if not (0 <= ref_row < ref_geometry.n_lines and 0 <= ref_col < ref_geometry.n_columns):
+                    continue  # this DEM point falls outside the actual SLC extent
+
+                grid_rows.append(ref_row)
+                grid_cols.append(ref_col)
+                offset_rows.append(sec_row - ref_row)
+                offset_cols.append(sec_col - ref_col)
+            except RuntimeError as exc:
+                n_failed += 1
+                logger.debug("DEM-driven offset field: point (%d, %d) failed: %s", dem_row, dem_col, exc)
+
+    if n_failed > n_total / 2:
+        raise RuntimeError(
+            f"DEM-driven offset field: {n_failed}/{n_total} points failed "
+            f"— check that the DEM genuinely overlaps the scene and the "
+            f"orbit files' validity periods cover both acquisition times."
+        )
+    if not grid_rows:
+        raise RuntimeError(
+            "DEM-driven offset field: no valid grid points fell within "
+            "the actual SLC extent — check the DEM covers the scene."
+        )
+
+    logger.info(
+        "DEM-driven offset field: %d/%d points solved successfully",
+        len(grid_rows), n_total,
+    )
+    return grid_rows, grid_cols, offset_rows, offset_cols
+
+
+def compute_offset_field(
+    ref_geometry,
+    ref_orbit,
+    sec_geometry,
+    sec_orbit,
+    image_shape: Tuple[int, int],
+    dem_height_m: float = 0.0,
+    grid_points: int = 7,
+):
+    """
+    Compute a real, orbit-based offset field between a reference and
+    secondary SLC image, sampled on a sparse grid and ready for
+    polynomial fitting.
+
+    Args:
+        ref_geometry, sec_geometry: SLCGeometry from
+                       annotation.parse_slc_geometry() for each image.
+        ref_orbit, sec_orbit: (times, positions, velocities) from
+                       geolocation.parse_orbit_file() for each image.
+        image_shape:   (rows, cols) of the reference image.
+        dem_height_m:  Constant height above the ellipsoid to use for
+                       the geolocation solve (0.0 = pure ellipsoid). A
+                       real per-pixel DEM lookup would be more accurate
+                       over rugged terrain but isn't wired in here yet.
+        grid_points:   Number of sample points per axis (grid_points^2
+                       total ground-point solves) — 7 is a reasonable
+                       default balancing accuracy and speed; the offset
+                       field is smooth, so a sparse grid captures it well.
+
+    Returns:
+        (grid_rows, grid_cols, offset_rows, offset_cols): four lists of
+        equal length — the sample grid positions in the reference image
+        and the real, solved offset (secondary - reference) at each,
+        in pixels.
+
+    Raises:
+        RuntimeError if too many grid points fail to solve (more than
+        half) — a real, actionable signal that the orbit data or
+        geometry inputs are likely wrong, surfaced clearly rather than
+        silently fitting a polynomial to mostly-garbage points.
+    """
+    from pygeofetch.insar.geolocation import solve_ground_point, find_zero_doppler_time
+
+    rows, cols = image_shape
+    row_samples = [int(r) for r in _linspace(0, rows - 1, grid_points)]
+    col_samples = [int(c) for c in _linspace(0, cols - 1, grid_points)]
+
+    grid_rows, grid_cols, offset_rows, offset_cols = [], [], [], []
+    n_failed = 0
+    n_total = 0
+    last_ground_point = None  # warm-start seed, carried across grid points
+
+    for row in row_samples:
+        for col in col_samples:
+            n_total += 1
+            try:
+                t_ref = ref_geometry.azimuth_time(row)
+                range_time = ref_geometry.range_time(col)
+
+                sat_pos, sat_vel = _interpolate(ref_orbit, t_ref)
+                ground_point = solve_ground_point(
+                    sat_pos, sat_vel, range_time, dem_height_m=dem_height_m,
+                    initial_guess=last_ground_point,
+                )
+                last_ground_point = ground_point  # seed the next grid point
+
+                t_sec = find_zero_doppler_time(
+                    sec_orbit[0], sec_orbit[1], sec_orbit[2], ground_point, t_ref
+                )
+                sec_row = sec_geometry.row_for_azimuth_time(t_sec)
+
+                sat_pos_sec, _ = _interpolate(sec_orbit, t_sec)
+                range_sec_m = _distance(sat_pos_sec, ground_point)
+                range_time_sec = 2 * range_sec_m / 299792458.0
+                sec_col = sec_geometry.col_for_range_time(range_time_sec)
+
+                grid_rows.append(row)
+                grid_cols.append(col)
+                offset_rows.append(sec_row - row)
+                offset_cols.append(sec_col - col)
+            except RuntimeError as exc:
+                n_failed += 1
+                logger.debug("Offset field: grid point (%d, %d) failed: %s", row, col, exc)
+                # Don't carry a failed point's (non-existent) result forward
+                # as the next warm-start seed -- last_ground_point simply
+                # stays at its last successful value, which is still a
+                # reasonable seed for the next point.
+
+    if n_failed > n_total / 2:
+        raise RuntimeError(
+            f"Offset field computation: {n_failed}/{n_total} grid points "
+            f"failed to solve — this usually means the orbit data doesn't "
+            f"actually correspond to this scene, or the annotation timing "
+            f"is wrong, not a transient numerical issue. Check that the "
+            f"orbit file's validity period actually covers this "
+            f"acquisition's real timestamp."
+        )
+    if n_failed > 0:
+        logger.warning(
+            "Offset field: %d/%d grid points failed to solve (proceeding "
+            "with the remaining %d) — the polynomial fit below is still "
+            "valid, but based on fewer points than requested.",
+            n_failed, n_total, n_total - n_failed,
+        )
+
+    return grid_rows, grid_cols, offset_rows, offset_cols
+
+
+def fit_offset_polynomial(grid_rows, grid_cols, offsets, degree: int = 1):
+    """
+    Fit a low-degree 2D polynomial to a sparse offset grid — standard
+    practice (Kampes, Hanssen & Perski 2003; matches the 2019 URSI
+    paper's approach) rather than every-pixel solving, since the true
+    offset field varies smoothly across a scene.
+
+    Returns a callable f(row, col) -> offset, evaluable at any pixel.
+    """
+    import numpy as np
+
+    rows = np.asarray(grid_rows, dtype=np.float64)
+    cols = np.asarray(grid_cols, dtype=np.float64)
+    vals = np.asarray(offsets, dtype=np.float64)
+
+    if degree == 1:
+        A = np.column_stack([np.ones_like(rows), rows, cols])
+    elif degree == 2:
+        A = np.column_stack([
+            np.ones_like(rows), rows, cols, rows * cols, rows**2, cols**2,
+        ])
+    else:
+        raise ValueError(f"Unsupported polynomial degree: {degree} (use 1 or 2)")
+
+    coeffs, *_ = np.linalg.lstsq(A, vals, rcond=None)
+
+    def evaluate(row, col):
+        row = np.asarray(row, dtype=np.float64)
+        col = np.asarray(col, dtype=np.float64)
+        if degree == 1:
+            return coeffs[0] + coeffs[1] * row + coeffs[2] * col
+        return (
+            coeffs[0] + coeffs[1] * row + coeffs[2] * col
+            + coeffs[3] * row * col + coeffs[4] * row**2 + coeffs[5] * col**2
+        )
+
+    return evaluate
+
+
+def resample_with_offset_field(data, row_offset_fn, col_offset_fn):
+    """
+    Resample a complex array using a real, per-pixel offset field
+    (from fit_offset_polynomial), rather than a naive shape-only zoom.
+
+    Args:
+        data:           Complex array to resample (the secondary SLC).
+        row_offset_fn, col_offset_fn: Callables from fit_offset_polynomial(),
+                       giving the real (secondary - reference) offset
+                       at any (row, col) in the reference grid.
+
+    Returns:
+        The resampled complex array, on the reference image's grid.
+    """
+    import numpy as np
+    from scipy.ndimage import map_coordinates
+
+    h, w = data.shape
+    row_idx, col_idx = np.mgrid[0:h, 0:w].astype(np.float64)
+
+    sample_rows = row_idx + row_offset_fn(row_idx, col_idx)
+    sample_cols = col_idx + col_offset_fn(row_idx, col_idx)
+
+    real = map_coordinates(data.real, [sample_rows, sample_cols], order=1, mode="constant", cval=0.0)
+    imag = map_coordinates(data.imag, [sample_rows, sample_cols], order=1, mode="constant", cval=0.0)
+    return (real + 1j * imag).astype(np.complex64)
+
+
+def _interpolate(orbit, t):
+    from pygeofetch.insar.geolocation import interpolate_orbit_state
+
+    return interpolate_orbit_state(orbit[0], orbit[1], orbit[2], t)
+
+
+def _distance(a, b):
+    return sum((a[i] - b[i]) ** 2 for i in range(3)) ** 0.5
+
+
+def _linspace(start, stop, n):
+    if n == 1:
+        return [start]
+    step = (stop - start) / (n - 1)
+    return [start + i * step for i in range(n)]