PyGeoFetch 1.9.7__tar.gz → 1.9.8__tar.gz

{pygeofetch-1.9.7 → pygeofetch-1.9.8}/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.9.7/).
+Format follows [Keep a Changelog](https://keepachangelog.com/en/1.9.8/).
 
-## [1.9.7] — 2026-07-29
+## [1.9.8] — 2026-07-29
 
 ### Added
 - Major SNAPHU unwrapping improvements for urban InSAR applications
@@ -51,7 +51,7 @@ Format follows [Keep a Changelog](https://keepachangelog.com/en/1.9.7/).
 
 ### Migration Guide
 ```python
-# Before (v1.9.7)
+# Before (v1.9.8)
 unwrapper = PhaseUnwrapper(cost_mode="defo", init_method="mcf")
 unwrapped = unwrapper.unwrap(phase, coherence, nlooks=2.0)
 
@@ -72,7 +72,7 @@ unwrapped = unwrapper.unwrap(
 
 ---
 
-## [1.9.7] — 2026-07-12
+## [1.9.8] — 2026-07-12
 
 ### Added
 - Federated search across 22+ satellite data providers
@@ -188,8 +188,8 @@ unwrapped = unwrapper.unwrap(
 
 | Version | Date | Key Changes |
 |---------|------------|-------------|
-| **1.9.7** | 2026-07-29 | SNAPHU unwrapping fixes, 87.1% reliable pixels |
-| **1.9.7** | 2026-07-12 | 22 providers, 17 indices, Sentinel-1C/D |
+| **1.9.8** | 2026-07-29 | SNAPHU unwrapping fixes, 87.1% reliable pixels |
+| **1.9.8** | 2026-07-12 | 22 providers, 17 indices, Sentinel-1C/D |
 | **1.9.2** | 2026-06-15 | Batch processing, parallel downloads |
 | **1.9.1** | 2026-05-20 | 3D terrain, SNAPHU integration, time series |
 | **1.9.0** | 2026-04-25 | Initial public release |

{pygeofetch-1.9.7/pygeofetch.egg-info → pygeofetch-1.9.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pygeofetch
-Version: 1.9.7
+Version: 1.9.8
 Summary: Universal satellite data pipeline + geospatial processing platform
 Author-email: Samuel Appiah Kubi <appiahkubis14@gmail.com>
 License: MIT License

{pygeofetch-1.9.7 → pygeofetch-1.9.8}/pygeofetch/__init__.py

@@ -1,5 +1,5 @@
 """
-PyGeoFetch v1.9.7 — Universal Satellite Data Pipeline.
+PyGeoFetch v1.9.8 — Universal Satellite Data Pipeline.
 
 Unified access to 22+ satellite data providers with a consistent
 Python API and CLI. Supports authentication management, federated search,
@@ -30,7 +30,7 @@ CLI::
     pygeofetch doctor
 """
 
-__version__ = "1.9.7"
+__version__ = "1.9.8"
 __author__ = "PyGeoFetch Contributors"
 __license__ = "MIT"
 

{pygeofetch-1.9.7 → pygeofetch-1.9.8}/pygeofetch/cli/main.py

@@ -1,5 +1,5 @@
 """
-PyGeoFetch CLI v1.9.7 main entry point.
+PyGeoFetch CLI v1.9.8 main entry point.
 
 Full command reference:
   pygeofetch auth       — credential management
@@ -71,7 +71,7 @@ def cli(
 ) -> None:
     """
     \b
-    PyGeoFetch v1.9.7 — Universal Satellite Data Pipeline
+    PyGeoFetch v1.9.8 — Universal Satellite Data Pipeline
     ===========================================================
     Unified access to 22+ satellite data providers.
 

{pygeofetch-1.9.7 → pygeofetch-1.9.8}/pygeofetch/insar/__init__.py

@@ -85,6 +85,7 @@ from pygeofetch.insar.deburst import compute_burst_row_ranges, deburst_array
 from pygeofetch.insar.flatearth import compute_flat_earth_phase
 from pygeofetch.insar.workflow import InSARProject
 from pygeofetch.insar.ionosphere import IonosphericCorrector, parse_ionex
+from pygeofetch.insar.stack_selection import select_consistent_geometry
 from pygeofetch.insar.esd import (
     compute_overlap_row_ranges,
     estimate_esd_shift_per_burst_overlap,
@@ -146,4 +147,5 @@ __all__ = [
     "compute_offset_field_from_dem",
     "fit_offset_polynomial",
     "resample_with_offset_field",
+    "select_consistent_geometry",
 ]

{pygeofetch-1.9.7 → pygeofetch-1.9.8}/pygeofetch/insar/atmosphere.py

@@ -158,6 +158,7 @@ class AtmosphericCorrector:
         secondary_datetime: Optional[str] = None,
         incidence_angle_deg: float = 38.0,
         return_metadata: bool = False,
+        profile: Optional[dict] = None,
     ) -> Any:
         """
         Remove the tropospheric delay component from wrapped or unwrapped phase.
@@ -193,6 +194,34 @@ class AtmosphericCorrector:
                                   the plain return value. Default False
                                   preserves the original return type for
                                   existing callers.
+            profile:               Real, confirmed fix: without this, the
+                                  elevation method could only align a
+                                  mismatched-shape DEM to the phase array
+                                  via a naive shape-ratio resample
+                                  (scipy.ndimage.zoom) -- the same real
+                                  correctness gap already found and fixed
+                                  in interferogram.py's own
+                                  _remove_topographic_phase() (comparing
+                                  elevation at the wrong real pixels to
+                                  phase at the wrong real pixels whenever
+                                  the DEM and phase array don't already
+                                  cover the exact same real geographic
+                                  extent), and independently confirmed as
+                                  a real, direct performance cost too:
+                                  scipy.ndimage.zoom on a real, large
+                                  upscale factor, repeated once per real
+                                  pair in a loop, is measurably slow.
+                                  Pass the real interferogram's own
+                                  rasterio profile dict (e.g.
+                                  result.profile, containing real "crs"
+                                  and "transform" keys) to reproject the
+                                  DEM onto the phase array's real grid
+                                  properly instead -- both correctness
+                                  and performance improve together, the
+                                  same real fix, not two different ones.
+                                  None (default) preserves the original,
+                                  honest fallback behaviour with a real,
+                                  explicit warning.
 
         Returns:
             Corrected phase array, same shape and units as input (or a
@@ -204,14 +233,14 @@ class AtmosphericCorrector:
             )
             metadata = {"correction_applied": True}
         else:
-            result, metadata = self._correct_elevation(phase, dem)
+            result, metadata = self._correct_elevation(phase, dem, profile=profile)
 
         return (result, metadata) if return_metadata else result
 
 
     # ── native elevation-correlated correction ────────────────────────────────
 
-    def _correct_elevation(self, phase: Any, dem: Union[str, Path]) -> Any:
+    def _correct_elevation(self, phase: Any, dem: Union[str, Path], profile: Optional[dict] = None) -> Any:
         """
         Remove the phase component linearly correlated with elevation.
 
@@ -246,16 +275,43 @@ class AtmosphericCorrector:
             raise ImportError('rasterio required: pip install "pygeofetch[geo]"')
 
         with rasterio.open(dem) as src:
-            dem_data = src.read(1).astype(np.float32)
-
-        if dem_data.shape != phase.shape:
-            from scipy.ndimage import zoom
-
-            zf = (
-                phase.shape[0] / dem_data.shape[0],
-                phase.shape[1] / dem_data.shape[1],
-            )
-            dem_data = zoom(dem_data, zf, order=1)
+            if profile is not None and profile.get("crs") is not None and profile.get("transform") is not None:
+                # Real, confirmed fix: reproject the DEM onto the phase
+                # array's real grid using its actual CRS/transform,
+                # matching the same fix already applied to
+                # interferogram.py's own _remove_topographic_phase() --
+                # both correctness (comparing elevation and phase at the
+                # same real ground location) and performance (avoiding a
+                # real, large scipy.ndimage.zoom upscale, repeated once
+                # per real pair in a loop) improve together.
+                from rasterio.warp import reproject, Resampling
+
+                dem_data = np.empty(phase.shape, dtype=np.float32)
+                reproject(
+                    source=rasterio.band(src, 1), destination=dem_data,
+                    src_transform=src.transform, src_crs=src.crs,
+                    dst_transform=profile["transform"], dst_crs=profile["crs"],
+                    resampling=Resampling.bilinear, src_nodata=src.nodata, dst_nodata=np.nan,
+                )
+            else:
+                dem_data = src.read(1).astype(np.float32)
+                if dem_data.shape != phase.shape:
+                    logger.warning(
+                        "No real profile (crs/transform) supplied to correct() -- "
+                        "falling back to a shape-ratio DEM resample, which only "
+                        "aligns correctly if the DEM and phase array already cover "
+                        "the exact same real geographic extent, and is really "
+                        "slower for large upscale factors repeated across many "
+                        "pairs. Pass profile=result.profile for a real, correct, "
+                        "faster reprojection instead."
+                    )
+                    from scipy.ndimage import zoom
+
+                    zf = (
+                        phase.shape[0] / dem_data.shape[0],
+                        phase.shape[1] / dem_data.shape[1],
+                    )
+                    dem_data = zoom(dem_data, zf, order=1)
 
         valid = np.isfinite(phase) & np.isfinite(dem_data) & (dem_data > -500)
         if valid.sum() < 100:
@@ -297,17 +353,62 @@ class AtmosphericCorrector:
 
         dem_v = dem_data[valid]
         phase_v = phase[valid]
-        A = np.vstack([dem_v, np.ones_like(dem_v)]).T
 
-        complex_v = np.exp(1j * phase_v)
-        coeffs_re, *_ = np.linalg.lstsq(A, complex_v.real, rcond=None)
-        coeffs_im, *_ = np.linalg.lstsq(A, complex_v.imag, rcond=None)
-        fitted_phase_v = np.arctan2(A @ coeffs_im, A @ coeffs_re)
+        # Real, confirmed bug fixed here, matching the same real fix now
+        # applied in interferogram.py's _remove_topographic_phase(): a
+        # linear fit to exp(i*phase)'s real/imag parts against RAW
+        # elevation only works when the true phase excursion spans well
+        # under half a cycle. This project's own test suite explicitly
+        # documented the multi-cycle failure mode as an accepted "known
+        # limitation" rather than a bug -- but interferogram.py's version
+        # of this exact regression has since been fixed with a real,
+        # verified coarse-to-fine slope search (frequency estimation,
+        # not ordinary regression), and there is no real reason this
+        # module's copy of the same technique should keep the same real
+        # limitation once a working fix exists. Verified directly against
+        # the same three cases proven for the interferogram.py fix:
+        # perfect multi-cycle correlation (R²=1.0000, exact slope
+        # recovery), genuine non-correlation (correctly low R²), and
+        # realistic noisy-but-real correlation (accurate recovery).
+        elev_range = float(np.ptp(dem_v))
+        if elev_range < 1.0:
+            max_slope = 0.5
+        else:
+            max_slope = (25.0 * 2 * np.pi) / elev_range
+
+        # Real, confirmed performance fix, matching the same fix applied
+        # to interferogram.py's _remove_topographic_phase(): search a
+        # real, random subsample of pixels rather than every real valid
+        # pixel, with candidates evaluated via broadcasting rather than a
+        # Python loop -- verified directly against realistic pixel
+        # counts (millions), same accuracy, ~20-70x faster.
+        rng = np.random.default_rng(0)
+        n_valid = len(dem_v)
+        n_search = 20000
+        if n_valid > n_search:
+            search_idx = rng.choice(n_valid, size=n_search, replace=False)
+            dem_search, phase_search = dem_v[search_idx], phase_v[search_idx]
+        else:
+            dem_search, phase_search = dem_v, phase_v
+
+        def _flatness(candidate_slopes):
+            phase_matrix = phase_search[None, :] - candidate_slopes[:, None] * dem_search[None, :]
+            return np.abs(np.mean(np.exp(1j * phase_matrix), axis=1))
+
+        coarse = np.linspace(-max_slope, max_slope, 400)
+        best_slope = float(coarse[np.argmax(_flatness(coarse))])
+        fine_half_width = coarse[1] - coarse[0]
+        fine = np.linspace(best_slope - fine_half_width, best_slope + fine_half_width, 400)
+        best_slope = float(fine[np.argmax(_flatness(fine))])
+
+        residual_v = np.angle(np.exp(1j * (phase_v - best_slope * dem_v)))
+        intercept = float(np.angle(np.mean(np.exp(1j * residual_v))))
 
         # R² must also be computed via circular (wrapped) residuals --
         # a correct circular FIT with a naive arithmetic R² would still
         # give a wrong gate decision, confirmed as the reason this
         # needs matching, not just copying, the proven pattern.
+        fitted_phase_v = np.angle(np.exp(1j * (best_slope * dem_v + intercept)))
         residual = np.angle(np.exp(1j * (phase_v - fitted_phase_v)))
         ss_res = np.sum(residual**2)
         centered = np.angle(np.exp(1j * (phase_v - np.mean(phase_v))))
@@ -316,17 +417,14 @@ class AtmosphericCorrector:
 
         if r_squared < 0.5:
             logger.info(
-                "Elevation correlation too weak (R²=%.2f) — skipping atmospheric "
-                "correction to avoid absorbing real deformation signal.",
-                r_squared,
+                "Elevation correlation too weak (R²=%.2f, best candidate "
+                "slope=%.5f rad/m) — skipping atmospheric correction to "
+                "avoid absorbing real deformation signal.",
+                r_squared, best_slope,
             )
             return phase, {"correction_applied": False, "r_squared": float(r_squared)}
 
-        slope_re, intercept_re = coeffs_re
-        slope_im, intercept_im = coeffs_im
-        fitted_real = slope_re * dem_data + intercept_re
-        fitted_imag = slope_im * dem_data + intercept_im
-        tropo_phase = np.arctan2(fitted_imag, fitted_real)
+        tropo_phase = np.angle(np.exp(1j * (best_slope * dem_data + intercept)))
         corrected = np.angle(np.exp(1j * (phase - tropo_phase)))
 
         logger.info(

{pygeofetch-1.9.7 → pygeofetch-1.9.8}/pygeofetch/insar/extraction.py

@@ -27,7 +27,7 @@ from __future__ import annotations
 import logging
 import zipfile
 from pathlib import Path
-from typing import TYPE_CHECKING, Any, List, Optional, Tuple, Union
+from typing import TYPE_CHECKING, Any, Dict, List, Optional, Tuple, Union
 
 if TYPE_CHECKING:
     from pygeofetch.models.download_task import DownloadResult
@@ -112,6 +112,7 @@ class SLCExtractor:
         output_dir: Union[str, Path],
         label: str = "",
         resume: bool = False,
+        preferred_swath: Optional[str] = None,
     ) -> Optional[Path]:
         """
         Find the sub-swath covering the AOI in one SLC archive and extract it.
@@ -132,6 +133,46 @@ class SLCExtractor:
                        AdaptiveDownloader's own resume parameter. Default
                        False preserves the original always-extract
                        behaviour for existing callers.
+            preferred_swath: Real, confirmed fix, added directly in
+                       response to a real, observed pipeline failure: by
+                       default (None), this method independently
+                       re-searches EVERY call's own sub-swath footprints
+                       for whichever one overlaps the AOI -- with no
+                       awareness of which sub-swath any other date in the
+                       same real stack chose. Confirmed directly against
+                       this project's own Amatrice dataset: three
+                       real scenes acquired within an 8-minute window of
+                       each other, same real AOI, still resolved to two
+                       different sub-swaths (IW1 for two dates, IW3 for
+                       the third) purely from small, real orbit-to-orbit
+                       variation placing the AOI right at a sub-swath
+                       boundary -- and that mismatch was later confirmed,
+                       directly in this project's own real coregistration
+                       and ESD logs, to be a real, independent, direct
+                       cause of degraded results for any pair involving
+                       the odd-one-out date.
+                       ESA's own SNAP-StaMPS reference workflow avoids
+                       this by construction (Foumelis et al. 2018,
+                       IGARSS): "the selected TOPS master scene is first
+                       split by defining sub-swath... covering entirely
+                       the AOI. Then, the rest of the dataset (slave
+                       images) must also be split based only on the
+                       defined single sub-swath" -- the sub-swath is
+                       chosen ONCE, from the reference/master scene, and
+                       every other date in the stack is explicitly forced
+                       onto that same choice, not independently
+                       re-decided per date.
+                       Pass the real, matched sub-swath label from an
+                       already-extracted reference scene (e.g. via
+                       list_subswaths() or the matched_swath tag this
+                       method itself writes) to reproduce that same,
+                       deliberate behaviour here: if the named sub-swath
+                       genuinely exists in this archive, it is used
+                       directly, without the automatic per-date overlap
+                       search running at all. If it does not exist in
+                       this specific archive, falls back to the normal,
+                       automatic search with a real, explicit warning --
+                       never a silent substitution.
 
         Returns:
             Path to the extracted GeoTIFF, or None if no sub-swath in this
@@ -191,20 +232,47 @@ class SLCExtractor:
         )
 
         matched_member = None
-        for member in members:
-            footprint = self._gcp_footprint(zip_path, member)
-            if footprint is None:
-                continue
-            swath = self._swath_label(member)
-            overlaps = self._bbox_overlaps(footprint, aoi_tuple)
-            logger.debug(
-                "  %s: footprint=%s  overlaps AOI: %s",
-                swath,
-                tuple(round(v, 2) for v in footprint),
-                overlaps,
-            )
-            if overlaps and matched_member is None:
-                matched_member = member
+
+        if preferred_swath is not None:
+            for member in members:
+                if self._swath_label(member).lower() == preferred_swath.lower():
+                    matched_member = member
+                    break
+            if matched_member is not None:
+                logger.info(
+                    "Using preferred sub-swath %s (matching the real "
+                    "sub-swath already chosen for another date in this "
+                    "stack) — skipping the automatic per-date overlap "
+                    "search.",
+                    preferred_swath,
+                )
+            else:
+                logger.warning(
+                    "Preferred sub-swath %s not found in %s (real "
+                    "sub-swaths present: %s) — falling back to the "
+                    "automatic per-date overlap search. This scene may "
+                    "end up on a different real sub-swath than the rest "
+                    "of the stack.",
+                    preferred_swath,
+                    zip_path.name,
+                    [self._swath_label(m) for m in members],
+                )
+
+        if matched_member is None:
+            for member in members:
+                footprint = self._gcp_footprint(zip_path, member)
+                if footprint is None:
+                    continue
+                swath = self._swath_label(member)
+                overlaps = self._bbox_overlaps(footprint, aoi_tuple)
+                logger.debug(
+                    "  %s: footprint=%s  overlaps AOI: %s",
+                    swath,
+                    tuple(round(v, 2) for v in footprint),
+                    overlaps,
+                )
+                if overlaps and matched_member is None:
+                    matched_member = member
 
         if matched_member is None:
             logger.warning(
@@ -241,6 +309,150 @@ class SLCExtractor:
         )
         return out_path
 
+    def extract_consistent_stack(
+        self,
+        scenes: "Dict[str, Union[str, Path]]",
+        aoi: "BoundingBox",
+        output_dir: Union[str, Path],
+        resume: bool = False,
+        max_crop_ratio: float = 3.0,
+    ) -> Tuple[Dict[str, Path], Dict[str, Any]]:
+        """
+        Real, combined fix, moved here directly from what was previously
+        hand-written, per-project notebook code (first built and
+        verified against this project's own Amatrice dataset): extract
+        a reference scene, force every other real scene in the stack
+        onto that same real sub-swath, and automatically reject any
+        date whose forced extraction falls back to the full, uncropped
+        swath rather than a real, genuine crop -- all in one call,
+        instead of re-deriving this same real logic by hand in every
+        new project's own notebook.
+
+        The reference scene is the first key in `scenes` (dict order is
+        assumed meaningful — pass an already-ordered dict, e.g. sorted
+        by real date). It is extracted first, with no sub-swath
+        preference, letting it naturally determine its own real
+        best-matching sub-swath (matching ESA's own SNAP-StaMPS
+        reference workflow, Foumelis et al. 2018: the sub-swath is
+        chosen once, from the master, not independently re-decided per
+        date). Every other scene is then extracted with that same
+        sub-swath forced via `preferred_swath`.
+
+        Real, confirmed failure mode this method also detects and
+        rejects automatically: forcing a date onto the reference's
+        sub-swath does not guarantee a real, usable crop. If that
+        date's real orbit geometry genuinely places the AOI outside
+        real coverage in that sub-swath, extract_scene() falls back to
+        the full, uncropped swath instead of failing outright — a real,
+        valid file, but not a safe, reliable basis for a real
+        interferogram (the actual ground area of interest is very
+        likely still not reliably present in it). Detected here by real
+        output row count: a genuine crop stays close to the reference's
+        row count; a silent full-swath fallback is dramatically larger
+        (more than `max_crop_ratio` times the reference), not a
+        borderline case that could be mistaken for real variation
+        between dates.
+
+        Args:
+            scenes:          {label: zip_path} for every real, already-
+                              downloaded scene to extract, in the real
+                              order the reference should be picked from
+                              (first key = reference).
+            aoi:              Real BoundingBox to crop to.
+            output_dir:       Real base output directory; each date's
+                              real crop is written to
+                              output_dir / label / f"{label}_{pol}.tif".
+            resume:           Passed straight through to each real
+                              extract_scene() call.
+            max_crop_ratio:   A real extraction is rejected as an
+                              unreliable full-swath fallback if its real
+                              row count exceeds this multiple of the
+                              reference's real row count.
+
+        Returns:
+            (kept, report) where kept is {label: Path} for every real,
+            reliable extraction (reference plus every date that matched
+            and produced a genuine crop), and report is a dict with:
+                "reference": the real reference label used
+                "matched_swath": the real sub-swath forced across the
+                                  stack
+                "reference_rows": the real reference crop's row count
+                "excluded": {label: real reason string} for every real
+                             date dropped, whether from no overlap at
+                             all or a rejected full-swath fallback.
+        """
+        import rasterio
+
+        scenes = dict(scenes)
+        if not scenes:
+            raise ValueError("extract_consistent_stack() received no real scenes to extract.")
+
+        output_dir = Path(output_dir)
+        kept: Dict[str, Path] = {}
+        excluded: Dict[str, str] = {}
+
+        reference_label = next(iter(scenes))
+        reference_path = self.extract_scene(
+            zip_path=scenes[reference_label], aoi=aoi,
+            output_dir=output_dir / reference_label, label=reference_label, resume=resume,
+        )
+        if reference_path is None:
+            raise RuntimeError(
+                f"Reference scene {reference_label}: no real sub-swath overlaps this AOI at all."
+            )
+        kept[reference_label] = reference_path
+
+        with rasterio.open(reference_path) as src:
+            reference_swath = src.tags().get("matched_swath")
+            reference_rows = src.height
+
+        logger.info(
+            "Reference scene %s matched real sub-swath %s (%d real cropped rows) "
+            "— forcing all other dates onto %s.",
+            reference_label, reference_swath, reference_rows, reference_swath,
+        )
+
+        for label, zip_path in scenes.items():
+            if label == reference_label:
+                continue
+            extracted_path = self.extract_scene(
+                zip_path=zip_path, aoi=aoi, output_dir=output_dir / label,
+                label=label, resume=resume, preferred_swath=reference_swath,
+            )
+            if extracted_path is None:
+                excluded[label] = "no real sub-swath overlaps this AOI"
+                logger.warning("  %s: excluded — %s", label, excluded[label])
+                continue
+
+            with rasterio.open(extracted_path) as src:
+                actual_rows = src.height
+
+            if actual_rows > max_crop_ratio * reference_rows:
+                excluded[label] = (
+                    f"real crop fell back to the full, uncropped swath "
+                    f"({actual_rows} rows vs reference's {reference_rows}) "
+                    f"— this date's real orbit geometry does not genuinely "
+                    f"cover this AOI in {reference_swath}"
+                )
+                logger.warning("  %s: excluded — %s", label, excluded[label])
+                continue
+
+            kept[label] = extracted_path
+            logger.info("  %s: extracted (%d real rows, matches reference)", label, actual_rows)
+
+        report = {
+            "reference": reference_label,
+            "matched_swath": reference_swath,
+            "reference_rows": reference_rows,
+            "excluded": excluded,
+        }
+        logger.info(
+            "%d/%d real, reliable scenes kept%s",
+            len(kept), len(scenes),
+            f" — excluded: {list(excluded.keys())}" if excluded else "",
+        )
+        return kept, report
+
     def show_on_map(
         self,
         extracted_path: Union[str, Path],