pygeofetch 2.0.2__tar.gz → 2.0.4__tar.gz

{pygeofetch-2.0.2 → pygeofetch-2.0.4}/CHANGELOG.md

@@ -1,9 +1,9 @@
 # Changelog
 
 All notable changes to PyGeoFetch are documented here.
-Format follows [Keep a Changelog](https://keepachangelog.com/en/2.0.2/).
+Format follows [Keep a Changelog](https://keepachangelog.com/en/2.0.4/).
 
-## [2.0.2] — 2026-07-29
+## [2.0.4] — 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/2.0.2/).
 
 ### Migration Guide
 ```python
-# Before (v2.0.2)
+# Before (v2.0.4)
 unwrapper = PhaseUnwrapper(cost_mode="defo", init_method="mcf")
 unwrapped = unwrapper.unwrap(phase, coherence, nlooks=2.0)
 
@@ -72,7 +72,7 @@ unwrapped = unwrapper.unwrap(
 
 ---
 
-## [2.0.2] — 2026-07-12
+## [2.0.4] — 2026-07-12
 
 ### Added
 - Federated search across 22+ satellite data providers
@@ -188,8 +188,8 @@ unwrapped = unwrapper.unwrap(
 
 | Version | Date | Key Changes |
 |---------|------------|-------------|
-| **2.0.2** | 2026-07-29 | SNAPHU unwrapping fixes, 87.1% reliable pixels |
-| **2.0.2** | 2026-07-12 | 22 providers, 17 indices, Sentinel-1C/D |
+| **2.0.4** | 2026-07-29 | SNAPHU unwrapping fixes, 87.1% reliable pixels |
+| **2.0.4** | 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-2.0.2/pygeofetch.egg-info → pygeofetch-2.0.4}/PKG-INFO

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

{pygeofetch-2.0.2 → pygeofetch-2.0.4}/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-2.0.2 → pygeofetch-2.0.4}/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-2.0.4/pygeofetch/insar/esd.py

@@ -0,0 +1,547 @@
+"""
+Real per-burst-overlap Enhanced Spectral Diversity (ESD), replacing the
+previous whole-image approximation.
+
+Formula confirmed against two independent, real academic sources:
+  Prats-Iraola et al. (2012), "Interferometric Processing of Sentinel-1
+    TOPS Data", IEEE TGRS.
+  Scheiber, R. & Moreira, A. (2000), "Coregistration of interferometric
+    SAR images using spectral diversity", IEEE TGRS.
+
+The azimuth shift (in seconds) is:
+    delta_t = delta_phi / (2 * pi * delta_f_ovl)
+where delta_phi is the double-difference phase between the forward-
+and backward-looking interferograms in the overlap, and delta_f_ovl
+is the Doppler centroid difference between the two looks (~1480 Hz
+for IW mode).
+"""
+
+from __future__ import annotations
+
+from datetime import datetime, timedelta
+import logging
+from typing import List, Optional, Tuple
+
+from pygeofetch.insar.annotation import SwathTiming
+
+logger = logging.getLogger("pygeofetch.insar.esd")
+
+# Real Sentinel-1 IW Doppler centroid frequency difference between
+# forward and backward looks in the burst overlap region.
+# Confirmed: Prats-Iraola et al. (2012), Table I.
+SENTINEL1_IW_DELTA_F_OVL_HZ = 1480.0
+
+
+def compute_overlap_row_ranges(
+    swath_timing: SwathTiming,
+    azimuth_time_interval_s: float,
+) -> List[Tuple[Tuple[int, int], Tuple[int, int]]]:
+    """
+    Compute the row ranges for each burst-overlap region.
+
+    Returns a list of ((bw_row_start, bw_row_end), (fw_row_start, fw_row_end))
+    tuples, one per adjacent burst pair. bw = backward-looking (end of
+    burst i), fw = forward-looking (start of burst i+1).
+    """
+    overlaps = []
+    lines_per_burst = swath_timing.lines_per_burst
+    bursts = swath_timing.bursts
+
+    for i in range(len(bursts) - 1):
+        # Backward-looking: last rows of burst i
+        bw_row_end = (i + 1) * lines_per_burst - 1
+        bw_row_start = i * lines_per_burst
+
+        # Forward-looking: first rows of burst i+1
+        fw_row_start = (i + 1) * lines_per_burst
+        fw_row_end = (i + 2) * lines_per_burst - 1
+
+        # Compute overlap extent from timing
+        burst_i_end_time = (
+            bursts[i].azimuth_time.timestamp()
+            + (lines_per_burst - 1) * azimuth_time_interval_s
+        )
+        burst_next_start_time = bursts[i + 1].azimuth_time.timestamp()
+
+        overlap_seconds = burst_i_end_time - burst_next_start_time
+        if overlap_seconds <= 0:
+            continue
+
+        overlap_lines = int(round(overlap_seconds / azimuth_time_interval_s))
+        if overlap_lines < 4:
+            continue
+
+        # Backward view: last `overlap_lines` rows of burst i
+        bw_row_start = bw_row_end - overlap_lines + 1
+        # Forward view: first `overlap_lines` rows of burst i+1
+        fw_row_end = fw_row_start + overlap_lines - 1
+
+        n_bw = bw_row_end - bw_row_start + 1
+        n_fw = fw_row_end - fw_row_start + 1
+
+        if n_bw != n_fw:
+            logger.warning(
+                "Overlap %d<->%d: backward-view row count (%d) does not "
+                "match forward-view row count (%d) -- unusual burst "
+                "timing; using the shorter of the two.",
+                i, i + 1, n_bw, n_fw,
+            )
+            n_common = min(n_bw, n_fw)
+            bw_row_start = bw_row_end - n_common + 1
+            fw_row_end = fw_row_start + n_common - 1
+
+        overlaps.append(((bw_row_start, bw_row_end), (fw_row_start, fw_row_end)))
+
+    return overlaps
+
+
+def _windowed_coherence(
+    ref_imagette, sec_imagette, window: int = 7
+) -> "np.ndarray":
+    """
+    Compute windowed coherence map (standard InSAR coherence estimation).
+
+    Unlike the previous single-scalar approach, this returns a 2D array
+    of local coherence values, allowing us to:
+      1. Reject low-coherence pixels (water, vegetation, shadow)
+      2. Use only high-coherence pixels for the ESD phase estimate
+      3. Report a robust MEDIAN coherence for the overlap quality check
+
+    Args:
+        ref_imagette: Complex reference overlap region (n_rows x n_cols)
+        sec_imagette: Complex secondary overlap region (same shape)
+        window: Coherence estimation window size (default 7)
+
+    Returns:
+        2D float32 array of local coherence values [0, 1]
+    """
+    import numpy as np
+    from scipy.ndimage import uniform_filter
+
+    cross = ref_imagette * np.conj(sec_imagette)
+
+    num_real = uniform_filter(cross.real, size=window)
+    num_imag = uniform_filter(cross.imag, size=window)
+    num = np.sqrt(num_real**2 + num_imag**2)
+
+    denom = np.sqrt(
+        uniform_filter(np.abs(ref_imagette) ** 2, size=window)
+        * uniform_filter(np.abs(sec_imagette) ** 2, size=window)
+        + 1e-10
+    )
+
+    coherence = np.clip(num / denom, 0.0, 1.0).astype(np.float32)
+    return coherence
+
+
+def _estimate_shift_from_overlap(
+    ref_bw, sec_bw, ref_fw, sec_fw,
+    delta_f_ovl_hz: float,
+    coherence_threshold: float = 0.3,
+    max_range_samples: int = 4096,
+) -> Tuple[Optional[float], float]:
+    """
+    Estimate azimuth shift from a single burst overlap using the
+    double-difference interferometric phase.
+
+    Memory optimization: subsamples in range if the overlap is wider
+    than max_range_samples (full scene = 23,674 cols; we only need
+    ~4096 for a statistically robust estimate).
+
+    Returns:
+        (shift_seconds, median_coherence)
+    """
+    import numpy as np
+
+    n_rows_bw, n_cols = ref_bw.shape
+    n_rows_fw, _ = ref_fw.shape
+
+    # Range subsampling for memory efficiency on full scenes
+    if n_cols > max_range_samples:
+        step = n_cols // max_range_samples
+        col_idx = np.arange(0, n_cols, step)
+        ref_bw = ref_bw[:, col_idx]
+        sec_bw = sec_bw[:, col_idx]
+        ref_fw = ref_fw[:, col_idx]
+        sec_fw = sec_fw[:, col_idx]
+        n_cols = len(col_idx)
+
+    # Ensure matching row counts
+    n_common = min(n_rows_bw, n_rows_fw)
+    ref_bw = ref_bw[:n_common]
+    sec_bw = sec_bw[:n_common]
+    ref_fw = ref_fw[:n_common]
+    sec_fw = sec_fw[:n_common]
+
+    # Compute windowed coherence on the backward-looking interferogram
+    coh_map = _windowed_coherence(ref_bw, sec_bw, window=7)
+    median_coh = float(np.median(coh_map))
+
+    if median_coh < coherence_threshold:
+        return None, median_coh
+
+    # Form forward and backward interferograms
+    ifg_bw = ref_bw * np.conj(sec_bw)  # backward-looking
+    ifg_fw = ref_fw * np.conj(sec_fw)  # forward-looking
+
+    # Double-difference phase: the key ESD quantity
+    # delta_phi = angle(ifg_bw) - angle(ifg_fw)
+    # Only use pixels where local coherence > threshold
+    mask = coh_map > coherence_threshold
+
+    if mask.sum() < 100:
+        return None, median_coh
+
+    # Compute double-difference phase only at high-coherence pixels
+    phase_bw = np.angle(ifg_bw)
+    phase_fw = np.angle(ifg_fw)
+    delta_phase = phase_bw[mask] - phase_fw[mask]
+
+    # Robust phase estimate: circular mean (not arithmetic mean)
+    mean_delta_phi = np.angle(np.mean(np.exp(1j * delta_phase)))
+
+    # Convert to time shift
+    shift_seconds = mean_delta_phi / (2.0 * np.pi * delta_f_ovl_hz)
+
+    return float(shift_seconds), median_coh
+
+
+from typing import Dict, List, Optional, Tuple
+
+def overlap_time_windows(
+    swath_timing: SwathTiming, azimuth_time_interval_s: float
+) -> List[Tuple[int, "datetime", "datetime"]]:
+    """
+    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.
+
+    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
+
+
+
+def compute_common_ground_overlaps(
+    ref_timing: SwathTiming,
+    sec_timing: SwathTiming,
+    azimuth_time_interval_s: float,
+) -> List[Dict]:
+    """
+    Per-reference-overlap diagnostic of how much COMMON double-covered
+    ground (in azimuth lines) this date pair actually shares.
+
+    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.
+
+    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.
+
+    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
+
+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
+
+    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
+
+        # 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)
+            skip_reasons.append("outside_array_bounds")
+            continue
+
+        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 valid.mean() < 0.5:
+            per_overlap_shifts.append(None)
+            skip_reasons.append(f"low_coherence({100*valid.mean():.0f}%)")
+            continue
+
+        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")
+
+    valid_shifts = [s for s in per_overlap_shifts if s is not None]
+    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
+
+    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