PyGeoFetch 2.0.2__py3-none-any.whl → 2.0.4__py3-none-any.whl

pygeofetch/__init__.py

@@ -1,5 +1,5 @@
 """
-PyGeoFetch v2.0.2 — Universal Satellite Data Pipeline.
+PyGeoFetch v2.0.4 — 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__ = "2.0.2"
+__version__ = "2.0.4"
 __author__ = "PyGeoFetch Contributors"
 __license__ = "MIT"
 

pygeofetch/cli/main.py

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

pygeofetch/insar/esd.py

@@ -18,6 +18,7 @@ for IW mode).
 
 from __future__ import annotations
 
+from datetime import datetime, timedelta
 import logging
 from typing import List, Optional, Tuple
 
@@ -205,157 +206,342 @@ def _estimate_shift_from_overlap(
     return float(shift_seconds), median_coh
 
 
-def estimate_esd_shift_per_burst_overlap(
-    ref_complex,
-    sec_complex,
-    swath_timing: SwathTiming,
-    azimuth_time_interval_s: float,
-    row_offset: int = 0,
-    delta_f_ovl_hz: float = SENTINEL1_IW_DELTA_F_OVL_HZ,
-    coherence_threshold: float = 0.3,
-) -> Tuple[Optional[float], List[Optional[float]]]:
+from typing import Dict, List, Optional, Tuple
+
+def overlap_time_windows(
+    swath_timing: SwathTiming, azimuth_time_interval_s: float
+) -> List[Tuple[int, "datetime", "datetime"]]:
     """
-    Real per-burst-overlap ESD: estimate azimuth misregistration from
-    the actual burst overlap regions, replacing the previous whole-image
-    single-shift approximation.
+    Absolute azimuth-time window of every adjacent-burst overlap -- the
+    ground area imaged by BOTH burst i (its trailing lines) and burst
+    i+1 (its leading lines) in THIS scene.
 
-    Uses WINDOWED coherence estimation (7x7 window) and MEDIAN coherence
-    for the quality check, matching SNAP's approach. This is critical for
-    full-scene processing where the overlap spans the entire range width
-    (~23,000 pixels) including ocean, vegetation, and other low-coherence
-    terrain that would drag a global-mean coherence below threshold.
+    Returns:
+        List of (overlap_index, window_start, window_end) as absolute
+        azimuth datetimes.
+    """
+    bursts = swath_timing.bursts
+    lines_per_burst = swath_timing.lines_per_burst
+    out = []
+    for i in range(len(bursts) - 1):
+        start = bursts[i + 1].azimuth_time
+        end = bursts[i].azimuth_time + timedelta(
+            seconds=(lines_per_burst - 1) * azimuth_time_interval_s
+        )
+        out.append((i, start, end))
+    return out
 
-    Memory optimization: subsamples in range to max 4096 columns per
-    overlap, reducing peak memory from ~600 MB to ~100 MB per overlap
-    while maintaining statistical robustness.
 
-    Args:
-        ref_complex, sec_complex: Real, coregistered (at least coarsely)
-            complex SLC arrays, same shape -- full burst stack, or an
-            already-cropped extract (see row_offset).
-        swath_timing: Real burst metadata from annotation.parse_burst_info().
-        azimuth_time_interval_s: Real per-line time spacing.
-        row_offset: Real full-scene row that ref_complex/sec_complex's
-            row 0 corresponds to. Default 0 assumes the arrays start at
-            the full-scene row 0.
-        delta_f_ovl_hz: Doppler centroid difference in the overlap.
-        coherence_threshold: Minimum MEDIAN windowed coherence for an
-            overlap to be considered usable.
 
-    Returns:
-        (shift_seconds, per_overlap_shifts): shift_seconds is the real,
-        median azimuth timing shift (seconds) across all valid burst
-        overlaps (None if no overlap gave a usable estimate);
-        per_overlap_shifts is one entry per adjacent burst pair (None
-        where that overlap's coherence was too low or fell entirely
-        outside the given arrays).
+def compute_common_ground_overlaps(
+    ref_timing: SwathTiming,
+    sec_timing: SwathTiming,
+    azimuth_time_interval_s: float,
+) -> List[Dict]:
     """
-    import numpy as np
+    Per-reference-overlap diagnostic of how much COMMON double-covered
+    ground (in azimuth lines) this date pair actually shares.
 
-    if not isinstance(swath_timing, SwathTiming):
-        raise TypeError(
-            f"estimate_esd_shift_per_burst_overlap expects a SwathTiming "
-            f"object, got {type(swath_timing).__name__}. Pass the result of "
-            f"parse_burst_info(), not a raw bursts list."
-        )
+    For each reference overlap window, intersect it with every secondary
+    overlap window and keep the largest intersection. That intersection
+    length is the only ground on which the ESD double-difference is
+    physically meaningful for this pair.
 
-    overlaps = compute_overlap_row_ranges(swath_timing, azimuth_time_interval_s)
-    per_overlap_shifts: List[Optional[float]] = []
+    This is the number that cleanly separates the two regimes:
+      - same-family pairs (identical burst timing): common lines ~= the
+        full overlap length (tens of lines per overlap);
+      - cross-family pairs (8 vs 9 bursts, shifted timing): common lines
+        shrink toward 0, which is exactly why ESD finds few/no usable
+        overlaps for them -- a physical limitation, not a bug.
 
-    n_outside = 0
-    n_below_coh = 0
-    n_usable = 0
+    Returns:
+        List of dicts, one per reference overlap, each with:
+          ref_overlap_index, ref_window, best_sec_overlap_index,
+          sec_window, common_lines, common_window
+    """
+    dt = azimuth_time_interval_s
+    ref_wins = overlap_time_windows(ref_timing, dt)
+    sec_wins = overlap_time_windows(sec_timing, dt)
+
+    report = []
+    for i, r_start, r_end in ref_wins:
+        best_j, best_lines, best_win = None, 0, None
+        for j, s_start, s_end in sec_wins:
+            t0, t1 = max(r_start, s_start), min(r_end, s_end)
+            if t1 <= t0:
+                continue  # no intersection for this secondary overlap
+            n_lines = int(round((t1 - t0).total_seconds() / dt)) + 1
+            if n_lines > best_lines:
+                best_j, best_lines, best_win = j, n_lines, (t0, t1)
+        report.append({
+            "ref_overlap_index": i,
+            "ref_window": (r_start, r_end),
+            "best_sec_overlap_index": best_j,
+            "sec_window": best_win,
+            "common_lines": best_lines,
+            "common_window": best_win,
+        })
+    return report
 
-    h, w = ref_complex.shape
+def estimate_esd_shift_per_burst_overlap(
+    ref_complex, sec_complex,
+    swath_timing, azimuth_time_interval_s,
+    row_offset: int = 0,
+    sec_swath_timing=None,          # NEW: secondary burst timing
+    delta_f_ovl_hz=SENTINEL1_IW_DELTA_F_OVL_HZ,
+    coherence_threshold: float = 0.2,
+    min_common_lines: int = 3,
+):
+    import numpy as np
+    from scipy.ndimage import uniform_filter
 
-    for i, ((bw_start, bw_end), (fw_start, fw_end)) in enumerate(overlaps):
-        # Map full-scene rows to local array rows
-        local_bw_start = bw_start - row_offset
-        local_bw_end = bw_end - row_offset
-        local_fw_start = fw_start - row_offset
-        local_fw_end = fw_end - row_offset
+    dt = azimuth_time_interval_s
+    L = swath_timing.lines_per_burst
+    ref_wins = overlap_time_windows(swath_timing, dt)
+    # If no secondary timing given, fall back to ref-only (old behaviour)
+    sec_wins = (overlap_time_windows(sec_swath_timing, dt)
+                if sec_swath_timing is not None else ref_wins)
+
+    per_overlap_shifts = []
+    skip_reasons = []
+
+    for (i, r_start, r_end) in ref_wins:
+        # Find the secondary overlap with the largest time intersection
+        best = None
+        for (j, s_start, s_end) in sec_wins:
+            t0, t1 = max(r_start, s_start), min(r_end, s_end)
+            n_lines = int((t1 - t0).total_seconds() / dt) + 1
+            if best is None or n_lines > best[0]:
+                best = (n_lines, t0, t1)
+        n_lines, t0, t1 = best
+
+        if n_lines < min_common_lines:
+            per_overlap_shifts.append(None)
+            skip_reasons.append("no_common_ground")
+            continue
 
-        # Check bounds
-        if (local_bw_start < 0 or local_bw_end >= h
-                or local_fw_start < 0 or local_fw_end >= h):
-            n_outside += 1
+        # Map the common time window to reference rows (bw=burst i tail,
+        # fw=burst i+1 head). Secondary is coregistered to the ref grid,
+        # so it is indexed at the same rows.
+        bw_rows, fw_rows = [], []
+        for k in range(n_lines):
+            tt = t0 + timedelta(seconds=k * dt)
+            bw_rows.append(i * L + round((tt - swath_timing.bursts[i].azimuth_time).total_seconds() / dt) - row_offset)
+            fw_rows.append((i + 1) * L + round((tt - swath_timing.bursts[i + 1].azimuth_time).total_seconds() / dt) - row_offset)
+
+        bw = np.array([r for r in bw_rows if 0 <= r < ref_complex.shape[0]])
+        fw = np.array([r for r in fw_rows if 0 <= r < ref_complex.shape[0]])
+        if len(bw) < min_common_lines or len(fw) < min_common_lines:
             per_overlap_shifts.append(None)
-            logger.debug(
-                "Overlap %d<->%d: outside array bounds "
-                "(local rows bw=[%d,%d], fw=[%d,%d], array height=%d)",
-                i, i + 1, local_bw_start, local_bw_end,
-                local_fw_start, local_fw_end, h,
-            )
+            skip_reasons.append("outside_array_bounds")
             continue
 
-        # Extract overlap regions
-        ref_bw = ref_complex[local_bw_start:local_bw_end + 1, :]
-        sec_bw = sec_complex[local_bw_start:local_bw_end + 1, :]
-        ref_fw = ref_complex[local_fw_start:local_fw_end + 1, :]
-        sec_fw = sec_complex[local_fw_start:local_fw_end + 1, :]
-
-        # Estimate shift with windowed coherence
-        shift_s, median_coh = _estimate_shift_from_overlap(
-            ref_bw, sec_bw, ref_fw, sec_fw,
-            delta_f_ovl_hz=delta_f_ovl_hz,
-            coherence_threshold=coherence_threshold,
-        )
+        ref_bw, sec_bw = ref_complex[bw], sec_complex[bw]
+        ref_fw, sec_fw = ref_complex[fw], sec_complex[fw]
+        igram_bw = ref_bw * np.conj(sec_bw)
+        igram_fw = ref_fw * np.conj(sec_fw)
+
+        # Windowed coherence gate (same as before)
+        n_common = len(bw)
+        coh_window = min(5, n_common) if n_common >= 3 else 1
+        if coh_window >= 3:
+            num = np.abs(uniform_filter(igram_bw.real, size=coh_window)
+                         + 1j * uniform_filter(igram_bw.imag, size=coh_window))
+            denom = np.sqrt(uniform_filter(np.abs(ref_bw)**2, size=coh_window)
+                            * uniform_filter(np.abs(sec_bw)**2, size=coh_window) + 1e-10)
+            valid = np.isfinite(num / denom) & ((num / denom) >= coherence_threshold)
+        else:
+            valid = np.ones(igram_bw.shape, dtype=bool)
 
-        if shift_s is None:
-            n_below_coh += 1
+        if valid.mean() < 0.5:
             per_overlap_shifts.append(None)
-            logger.debug(
-                "Overlap %d<->%d: median windowed coherence %.3f < threshold %.2f",
-                i, i + 1, median_coh, coherence_threshold,
-            )
-        else:
-            n_usable += 1
-            per_overlap_shifts.append(shift_s)
-            logger.debug(
-                "Overlap %d<->%d: shift=%.6f ms, median_coh=%.3f",
-                i, i + 1, shift_s * 1000, median_coh,
-            )
+            skip_reasons.append(f"low_coherence({100*valid.mean():.0f}%)")
+            continue
 
-    # Report diagnostics
-    if n_usable == 0:
-        if n_outside > 0 and n_below_coh > 0:
-            logger.warning(
-                "Real per-burst-overlap ESD found no usable burst overlaps "
-                "out of %d total: %d fell outside the given (possibly "
-                "cropped) arrays, %d were below coherence_threshold=%.2f. "
-                "A mix of both -- see the per-overlap detail at DEBUG level.",
-                len(overlaps), n_outside, n_below_coh, coherence_threshold,
-            )
-        elif n_outside > 0:
-            logger.warning(
-                "Real per-burst-overlap ESD found no usable burst overlaps "
-                "out of %d total: all %d fell outside the given (possibly "
-                "cropped) arrays.",
-                len(overlaps), n_outside,
-            )
-        else:
-            logger.warning(
-                "Real per-burst-overlap ESD found no usable burst overlaps "
-                "out of %d total: 0 fell outside the given (possibly "
-                "cropped) arrays, %d were below coherence_threshold=%.2f. "
-                "Every real, in-bounds overlap was tested and found "
-                "genuinely below the coherence threshold -- this reflects "
-                "real decorrelation in the data, not something a larger "
-                "AOI would fix.",
-                len(overlaps), n_below_coh, coherence_threshold,
-            )
-        return None, per_overlap_shifts
+        double_diff = igram_fw * np.conj(igram_bw)
+        mean_phase = np.angle(np.mean(double_diff[valid]))
+        per_overlap_shifts.append(float(mean_phase / (2 * np.pi * delta_f_ovl_hz)))
+        skip_reasons.append("used")
 
-    # Combine valid shifts via median (robust to outliers)
     valid_shifts = [s for s in per_overlap_shifts if s is not None]
-    combined_shift = float(np.median(valid_shifts))
-
-    logger.info(
-        "Real per-burst-overlap ESD: %d/%d overlaps usable, "
-        "combined shift=%.6f ms (%.4f px)",
-        n_usable, len(overlaps),
-        combined_shift * 1000,
-        combined_shift / azimuth_time_interval_s,
-    )
+    if not valid_shifts:
+        n_outside = skip_reasons.count("outside_array_bounds")
+        n_nocommon = skip_reasons.count("no_common_ground")
+        n_low = sum(1 for r in skip_reasons if r.startswith("low_coherence"))
+        logger.warning(
+            "ESD: no usable overlaps of %d (%d no common ground, %d outside, %d low coh)",
+            len(ref_wins), n_nocommon, n_outside, n_low)
+        return None, per_overlap_shifts
 
-    return combined_shift, per_overlap_shifts
+    combined = float(np.median(valid_shifts))
+    logger.info("ESD common-ground: %d/%d usable, shift=%.6f ms (%.4f px)",
+                len(valid_shifts), len(ref_wins), combined*1000, combined/dt)
+    return combined, per_overlap_shifts
+
+
+# def estimate_esd_shift_per_burst_overlap(
+#     ref_complex,
+#     sec_complex,
+#     swath_timing: SwathTiming,
+#     azimuth_time_interval_s: float,
+#     row_offset: int = 0,
+#     delta_f_ovl_hz: float = SENTINEL1_IW_DELTA_F_OVL_HZ,
+#     coherence_threshold: float = 0.3,
+# ) -> Tuple[Optional[float], List[Optional[float]]]:
+#     """
+#     Real per-burst-overlap ESD: estimate azimuth misregistration from
+#     the actual burst overlap regions, replacing the previous whole-image
+#     single-shift approximation.
+
+#     Uses WINDOWED coherence estimation (7x7 window) and MEDIAN coherence
+#     for the quality check, matching SNAP's approach. This is critical for
+#     full-scene processing where the overlap spans the entire range width
+#     (~23,000 pixels) including ocean, vegetation, and other low-coherence
+#     terrain that would drag a global-mean coherence below threshold.
+
+#     Memory optimization: subsamples in range to max 4096 columns per
+#     overlap, reducing peak memory from ~600 MB to ~100 MB per overlap
+#     while maintaining statistical robustness.
+
+#     Args:
+#         ref_complex, sec_complex: Real, coregistered (at least coarsely)
+#             complex SLC arrays, same shape -- full burst stack, or an
+#             already-cropped extract (see row_offset).
+#         swath_timing: Real burst metadata from annotation.parse_burst_info().
+#         azimuth_time_interval_s: Real per-line time spacing.
+#         row_offset: Real full-scene row that ref_complex/sec_complex's
+#             row 0 corresponds to. Default 0 assumes the arrays start at
+#             the full-scene row 0.
+#         delta_f_ovl_hz: Doppler centroid difference in the overlap.
+#         coherence_threshold: Minimum MEDIAN windowed coherence for an
+#             overlap to be considered usable.
+
+#     Returns:
+#         (shift_seconds, per_overlap_shifts): shift_seconds is the real,
+#         median azimuth timing shift (seconds) across all valid burst
+#         overlaps (None if no overlap gave a usable estimate);
+#         per_overlap_shifts is one entry per adjacent burst pair (None
+#         where that overlap's coherence was too low or fell entirely
+#         outside the given arrays).
+#     """
+#     import numpy as np
+
+#     if not isinstance(swath_timing, SwathTiming):
+#         raise TypeError(
+#             f"estimate_esd_shift_per_burst_overlap expects a SwathTiming "
+#             f"object, got {type(swath_timing).__name__}. Pass the result of "
+#             f"parse_burst_info(), not a raw bursts list."
+#         )
+
+#     overlaps = compute_overlap_row_ranges(swath_timing, azimuth_time_interval_s)
+#     per_overlap_shifts: List[Optional[float]] = []
+
+#     n_outside = 0
+#     n_below_coh = 0
+#     n_usable = 0
+
+#     h, w = ref_complex.shape
+
+#     for i, ((bw_start, bw_end), (fw_start, fw_end)) in enumerate(overlaps):
+#         # Map full-scene rows to local array rows
+#         local_bw_start = bw_start - row_offset
+#         local_bw_end = bw_end - row_offset
+#         local_fw_start = fw_start - row_offset
+#         local_fw_end = fw_end - row_offset
+
+#         # Check bounds
+#         if (local_bw_start < 0 or local_bw_end >= h
+#                 or local_fw_start < 0 or local_fw_end >= h):
+#             n_outside += 1
+#             per_overlap_shifts.append(None)
+#             logger.debug(
+#                 "Overlap %d<->%d: outside array bounds "
+#                 "(local rows bw=[%d,%d], fw=[%d,%d], array height=%d)",
+#                 i, i + 1, local_bw_start, local_bw_end,
+#                 local_fw_start, local_fw_end, h,
+#             )
+#             continue
+
+#         # Extract overlap regions
+#         ref_bw = ref_complex[local_bw_start:local_bw_end + 1, :]
+#         sec_bw = sec_complex[local_bw_start:local_bw_end + 1, :]
+#         ref_fw = ref_complex[local_fw_start:local_fw_end + 1, :]
+#         sec_fw = sec_complex[local_fw_start:local_fw_end + 1, :]
+
+#         # Estimate shift with windowed coherence
+#         shift_s, median_coh = _estimate_shift_from_overlap(
+#             ref_bw, sec_bw, ref_fw, sec_fw,
+#             delta_f_ovl_hz=delta_f_ovl_hz,
+#             coherence_threshold=coherence_threshold,
+#         )
+
+#         if shift_s is None:
+#             n_below_coh += 1
+#             per_overlap_shifts.append(None)
+#             logger.debug(
+#                 "Overlap %d<->%d: median windowed coherence %.3f < threshold %.2f",
+#                 i, i + 1, median_coh, coherence_threshold,
+#             )
+#         else:
+#             n_usable += 1
+#             per_overlap_shifts.append(shift_s)
+#             logger.debug(
+#                 "Overlap %d<->%d: shift=%.6f ms, median_coh=%.3f",
+#                 i, i + 1, shift_s * 1000, median_coh,
+#             )
+
+#     # Report diagnostics
+#     if n_usable == 0:
+#         if n_outside > 0 and n_below_coh > 0:
+#             logger.warning(
+#                 "Real per-burst-overlap ESD found no usable burst overlaps "
+#                 "out of %d total: %d fell outside the given (possibly "
+#                 "cropped) arrays, %d were below coherence_threshold=%.2f. "
+#                 "A mix of both -- see the per-overlap detail at DEBUG level.",
+#                 len(overlaps), n_outside, n_below_coh, coherence_threshold,
+#             )
+#         elif n_outside > 0:
+#             logger.warning(
+#                 "Real per-burst-overlap ESD found no usable burst overlaps "
+#                 "out of %d total: all %d fell outside the given (possibly "
+#                 "cropped) arrays.",
+#                 len(overlaps), n_outside,
+#             )
+#         else:
+#             logger.warning(
+#                 "Real per-burst-overlap ESD found no usable burst overlaps "
+#                 "out of %d total: 0 fell outside the given (possibly "
+#                 "cropped) arrays, %d were below coherence_threshold=%.2f. "
+#                 "Every real, in-bounds overlap was tested and found "
+#                 "genuinely below the coherence threshold -- this reflects "
+#                 "real decorrelation in the data, not something a larger "
+#                 "AOI would fix.",
+#                 len(overlaps), n_below_coh, coherence_threshold,
+#             )
+#         return None, per_overlap_shifts
+
+#     # Combine valid shifts via median (robust to outliers)
+#     valid_shifts = [s for s in per_overlap_shifts if s is not None]
+#     combined_shift = float(np.median(valid_shifts))
+
+#     logger.info(
+#         "Real per-burst-overlap ESD: %d/%d overlaps usable, "
+#         "combined shift=%.6f ms (%.4f px)",
+#         n_usable, len(overlaps),
+#         combined_shift * 1000,
+#         combined_shift / azimuth_time_interval_s,
+#     )
+
+#     return combined_shift, per_overlap_shifts
+
+
+# def overlap_time_windows(swath_timing, dt):
+#     """Absolute azimuth-time windows for each adjacent-burst overlap."""
+#     bursts = swath_timing.bursts
+#     L = swath_timing.lines_per_burst
+#     out = []
+#     for i in range(len(bursts) - 1):
+#         start = bursts[i + 1].azimuth_time
+#         end = bursts[i].azimuth_time + timedelta(seconds=(L - 1) * dt)
+#         out.append((i, start, end))
+#     return out