PyGeoFetch 2.0.0__tar.gz → 2.0.1__tar.gz

{pygeofetch-2.0.0 → pygeofetch-2.0.1}/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.0/).
+Format follows [Keep a Changelog](https://keepachangelog.com/en/2.0.1/).
 
-## [2.0.0] — 2026-07-29
+## [2.0.1] — 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.0/).
 
 ### Migration Guide
 ```python
-# Before (v2.0.0)
+# Before (v2.0.1)
 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.0] — 2026-07-12
+## [2.0.1] — 2026-07-12
 
 ### Added
 - Federated search across 22+ satellite data providers
@@ -188,8 +188,8 @@ unwrapped = unwrapper.unwrap(
 
 | Version | Date | Key Changes |
 |---------|------------|-------------|
-| **2.0.0** | 2026-07-29 | SNAPHU unwrapping fixes, 87.1% reliable pixels |
-| **2.0.0** | 2026-07-12 | 22 providers, 17 indices, Sentinel-1C/D |
+| **2.0.1** | 2026-07-29 | SNAPHU unwrapping fixes, 87.1% reliable pixels |
+| **2.0.1** | 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.0/pygeofetch.egg-info → pygeofetch-2.0.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pygeofetch
-Version: 2.0.0
+Version: 2.0.1
 Summary: Universal satellite data pipeline + geospatial processing platform
 Author-email: Samuel Appiah Kubi <appiahkubis14@gmail.com>
 License: MIT License
@@ -85,7 +85,7 @@ Requires-Dist: localtileserver>=1.0.0; extra == "viz"
 Requires-Dist: ipysheet>=0.6.0; extra == "viz"
 Requires-Dist: ipyleaflet>=0.17.0; extra == "viz"
 Requires-Dist: ipywidgets>=8.0.0; extra == "viz"
-Requires-Dist: ipyevents>=2.0.0; extra == "viz"
+Requires-Dist: ipyevents>=2.0.1; extra == "viz"
 Requires-Dist: ipyfilechooser>=0.6.0; extra == "viz"
 Requires-Dist: sidecar>=0.6.0; extra == "viz"
 Requires-Dist: bokeh>=3.0.0; extra == "viz"

{pygeofetch-2.0.0 → pygeofetch-2.0.1}/pygeofetch/__init__.py

@@ -1,5 +1,5 @@
 """
-PyGeoFetch v2.0.0 — Universal Satellite Data Pipeline.
+PyGeoFetch v2.0.1 — 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.0"
+__version__ = "2.0.1"
 __author__ = "PyGeoFetch Contributors"
 __license__ = "MIT"
 

{pygeofetch-2.0.0 → pygeofetch-2.0.1}/pygeofetch/cli/main.py

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

{pygeofetch-2.0.0 → pygeofetch-2.0.1}/pygeofetch/insar/coregister.py

@@ -665,23 +665,67 @@ def _sample_complex_imagette(data, center_row: float, center_col: float, size: i
     return (real + 1j * imag).astype(np.complex64)
 
 
-def _imagette_coherence(ref_imagette, sec_imagette) -> float:
+# def _imagette_coherence(ref_imagette, sec_imagette) -> float:
+#     """
+#     Single scalar complex coherence between two same-shape imagettes —
+#     SNAP CrossCorrelationOp's "Method 1" (no internal sliding window;
+#     the whole imagette is treated as one coherence estimation window):
+#     https://step.esa.int/main/wp-content/help/versions/13.0.0/snap-toolboxes/eu.esa.microwavetbx.sar.op.insar.ui/operators/CrossCorrelationOp.html
+#     """
+#     import numpy as np
+
+#     num = abs(np.mean(ref_imagette * np.conj(sec_imagette)))
+#     denom = np.sqrt(
+#         np.mean(np.abs(ref_imagette) ** 2) * np.mean(np.abs(sec_imagette) ** 2)
+#     )
+#     if denom < 1e-12:
+#         return 0.0
+#     return float(np.clip(num / denom, 0.0, 1.0))
+
+
+# def _imagette_coherence(ref_imagette, sec_imagette) -> float:
+
+#     import numpy as np
+
+#     num = abs(np.mean(ref_imagette * np.conj(sec_imagette)))
+#     denom = np.sqrt(np.mean(np.abs(ref_imagette) ** 2) * np.mean(np.abs(sec_imagette) ** 2))
+#     if denom < 1e-12:
+#         return 0.0
+#     return float(np.clip(num / denom, 0.0, 1.0))
+
+def _imagette_coherence(ref_imagette, sec_imagette, window_size: int = 5) -> float:
     """
-    Single scalar complex coherence between two same-shape imagettes —
-    SNAP CrossCorrelationOp's "Method 1" (no internal sliding window;
-    the whole imagette is treated as one coherence estimation window):
-    https://step.esa.int/main/wp-content/help/versions/13.0.0/snap-toolboxes/eu.esa.microwavetbx.sar.op.insar.ui/operators/CrossCorrelationOp.html
+    Calculate coherence using windowed averaging (standard ESD approach).
+    
+    Args:
+        ref_imagette: Reference imagette (complex array)
+        sec_imagette: Secondary imagette (complex array)
+        window_size: Window size for coherence calculation (default: 5)
+    
+    Returns:
+        Average coherence value
     """
     import numpy as np
-
-    num = abs(np.mean(ref_imagette * np.conj(sec_imagette)))
-    denom = np.sqrt(
-        np.mean(np.abs(ref_imagette) ** 2) * np.mean(np.abs(sec_imagette) ** 2)
-    )
-    if denom < 1e-12:
-        return 0.0
-    return float(np.clip(num / denom, 0.0, 1.0))
-
+    from scipy.ndimage import uniform_filter
+    
+    # Calculate complex cross-correlation
+    cross_corr = ref_imagette * np.conj(sec_imagette)
+    
+    # Calculate windowed averages
+    num_real = uniform_filter(cross_corr.real, size=window_size)
+    num_imag = uniform_filter(cross_corr.imag, size=window_size)
+    num = np.sqrt(num_real**2 + num_imag**2)
+    
+    denom_ref = uniform_filter(np.abs(ref_imagette)**2, size=window_size)
+    denom_sec = uniform_filter(np.abs(sec_imagette)**2, size=window_size)
+    denom = np.sqrt(denom_ref * denom_sec)
+    
+    # Calculate coherence
+    coherence = np.where(denom > 1e-12, num / denom, 0.0)
+    coherence = np.clip(coherence, 0.0, 1.0)
+    
+    # Return average coherence
+    return float(np.mean(coherence))
 
 def refine_offsets_by_coherence(
     ref_complex,
@@ -1124,11 +1168,11 @@ def resample_with_offset_field(
     import numpy as np
     from scipy.ndimage import map_coordinates
 
-    h, w = data.shape
-    out_real = np.empty((h, w), dtype=np.float32)
-    out_imag = np.empty((h, w), dtype=np.float32)
-    data_real = data.real
-    data_imag = data.imag
+    # h, w = data.shape
+    # out_real = np.empty((h, w), dtype=np.float32)
+    # out_imag = np.empty((h, w), dtype=np.float32)
+    # data_real = data.real
+    # data_imag = data.imag
 
     # Process in row chunks rather than building ~10 full-resolution
     # float64 intermediate arrays (row_idx, col_idx, ref_global_row/col,
@@ -1142,41 +1186,85 @@ def resample_with_offset_field(
     # more than sufficient precision for sub-pixel offset resampling and
     # halves the footprint on its own; chunking bounds peak memory to
     # one row-block regardless of total crop size.
-    chunk_rows = max(1, min(h, 2000))
-    for row_start in range(0, h, chunk_rows):
-        row_end = min(row_start + chunk_rows, h)
-        row_idx, col_idx = np.mgrid[row_start:row_end, 0:w].astype(np.float32)
-
-        # row_idx/col_idx are the reference grid's local (0-based)
-        # coordinates. Convert to full-scene coordinates to correctly
-        # evaluate the fitted offset functions, which were built on real
-        # annotation-derived full-scene coordinates, not any particular
-        # crop's local ones.
-        ref_global_row = row_idx + ref_row_offset
-        ref_global_col = col_idx + ref_col_offset
-
-        offset_row = row_offset_fn(ref_global_row, ref_global_col)
-        offset_col = col_offset_fn(ref_global_row, ref_global_col)
-
-        # Where this pixel's secondary counterpart is, in full-scene coordinates
-        sec_global_row = ref_global_row + offset_row
-        sec_global_col = ref_global_col + offset_col
-
-        # Convert to the SECONDARY array's own local coordinates for
-        # actually indexing into `data` -- the secondary crop can have a
-        # different offset than the reference crop, so this is not the
-        # same subtraction as ref_row_offset/ref_col_offset above.
-        sample_rows = sec_global_row - sec_row_offset
-        sample_cols = sec_global_col - sec_col_offset
-
-        out_real[row_start:row_end] = map_coordinates(
-            data_real, [sample_rows, sample_cols], order=1, mode="constant", cval=0.0
-        )
-        out_imag[row_start:row_end] = map_coordinates(
-            data_imag, [sample_rows, sample_cols], order=1, mode="constant", cval=0.0
-        )
+
+        
+    h, w = data.shape
+    out_real = np.empty((h, w), dtype=np.float32)
+    out_imag = np.empty((h, w), dtype=np.float32)
+    data_real = data.real
+    data_imag = data.imag
+
+    # Process in 2D tiles for cache locality and strict memory bounding
+    tile_h, tile_w = 1024, 1024 
+    
+    for r_start in range(0, h, tile_h):
+        r_end = min(r_start + tile_h, h)
+        for c_start in range(0, w, tile_w):
+            c_end = min(c_start + tile_w, w)
+            
+            # Use ogrid to create broadcastable 1D arrays instead of full 2D mgrid matrices
+            row_idx = np.arange(r_start, r_end, dtype=np.float32)[:, None]
+            col_idx = np.arange(c_start, c_end, dtype=np.float32)[None, :]
+            
+            ref_global_row = row_idx + ref_row_offset
+            ref_global_col = col_idx + ref_col_offset
+            
+            # Evaluate polynomial (broadcasts automatically, minimal memory)
+            offset_row = row_offset_fn(ref_global_row, ref_global_col)
+            offset_col = col_offset_fn(ref_global_row, ref_global_col)
+            
+            sample_rows = ref_global_row + offset_row - sec_row_offset
+            sample_cols = ref_global_col + offset_col - sec_col_offset
+            
+            # Broadcast to 2D for map_coordinates
+            sample_rows_2d = np.broadcast_to(sample_rows, (r_end - r_start, c_end - c_start))
+            sample_cols_2d = np.broadcast_to(sample_cols, (r_end - r_start, c_end - c_start))
+            
+            out_real[r_start:r_end, c_start:c_end] = map_coordinates(
+                data_real, [sample_rows_2d, sample_cols_2d], order=1, mode="constant", cval=0.0
+            )
+            out_imag[r_start:r_end, c_start:c_end] = map_coordinates(
+                data_imag, [sample_rows_2d, sample_cols_2d], order=1, mode="constant", cval=0.0
+            )
+            
+            del sample_rows_2d, sample_cols_2d, offset_row, offset_col
 
     return (out_real + 1j * out_imag).astype(np.complex64)
+    # chunk_rows = max(1, min(h, 2000))
+    # for row_start in range(0, h, chunk_rows):
+    #     row_end = min(row_start + chunk_rows, h)
+    #     row_idx, col_idx = np.mgrid[row_start:row_end, 0:w].astype(np.float32)
+
+    #     # row_idx/col_idx are the reference grid's local (0-based)
+    #     # coordinates. Convert to full-scene coordinates to correctly
+    #     # evaluate the fitted offset functions, which were built on real
+    #     # annotation-derived full-scene coordinates, not any particular
+    #     # crop's local ones.
+    #     ref_global_row = row_idx + ref_row_offset
+    #     ref_global_col = col_idx + ref_col_offset
+
+    #     offset_row = row_offset_fn(ref_global_row, ref_global_col)
+    #     offset_col = col_offset_fn(ref_global_row, ref_global_col)
+
+    #     # Where this pixel's secondary counterpart is, in full-scene coordinates
+    #     sec_global_row = ref_global_row + offset_row
+    #     sec_global_col = ref_global_col + offset_col
+
+    #     # Convert to the SECONDARY array's own local coordinates for
+    #     # actually indexing into `data` -- the secondary crop can have a
+    #     # different offset than the reference crop, so this is not the
+    #     # same subtraction as ref_row_offset/ref_col_offset above.
+    #     sample_rows = sec_global_row - sec_row_offset
+    #     sample_cols = sec_global_col - sec_col_offset
+
+    #     out_real[row_start:row_end] = map_coordinates(
+    #         data_real, [sample_rows, sample_cols], order=1, mode="constant", cval=0.0
+    #     )
+    #     out_imag[row_start:row_end] = map_coordinates(
+    #         data_imag, [sample_rows, sample_cols], order=1, mode="constant", cval=0.0
+    #     )
+
+    # return (out_real + 1j * out_imag).astype(np.complex64)
 
 
 def _interpolate(orbit, t):

pygeofetch-2.0.1/pygeofetch/insar/esd.py

@@ -0,0 +1,361 @@
+"""
+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
+
+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
+
+
+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