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

pygeofetch/__init__.py

@@ -1,5 +1,5 @@
 """
-PyGeoFetch v2.0.3 — 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.3"
+__version__ = "2.0.4"
 __author__ = "PyGeoFetch Contributors"
 __license__ = "MIT"
 

pygeofetch/cli/main.py

@@ -1,5 +1,5 @@
 """
-PyGeoFetch CLI v2.0.3 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.3 — Universal Satellite Data Pipeline
+    PyGeoFetch v2.0.4 — Universal Satellite Data Pipeline
     ===========================================================
     Unified access to 22+ satellite data providers.
 

pygeofetch/insar/unwrap.py

@@ -22,25 +22,258 @@ Install: pip install "pygeofetch[insar]"   (installs snaphu, scipy)
 from __future__ import annotations
 
 import logging
+import platform
+import subprocess
+import urllib.request
+import zipfile
+import shutil
+import json
+import tempfile
+from dataclasses import dataclass, field
 from pathlib import Path
-from typing import Any, Optional, Tuple, Union
+from typing import Any, Dict, Optional, Tuple, Union
 
 logger = logging.getLogger("pygeofetch.insar.unwrap")
 
 
-def _require_snaphu():
-    try:
-        import snaphu
+@dataclass
+class UnwrapResult:
+    """
+    Result of phase unwrapping for one interferogram pair.
+    
+    Mirrors the InterferogramResult.save() pattern: the notebook cell
+    stays focused on orchestration (which pairs, what parameters), while
+    this class handles all file I/O, georeferencing, nodata masking,
+    and optional visualization.
+    """
+
+    unwrapped_phase: Any      # float32 array, radians, continuous
+    conncomp: Any             # int32 array, 0 = unreliable/masked
+    coherence: Any            # float32 array, 0-1 (multilooked coherence used)
+    profile: Dict[str, Any]   # rasterio-style profile for georeferencing
+    reference_date: Optional[str] = None
+    secondary_date: Optional[str] = None
+    nlooks: float = 1.0
+    cost_mode: str = "defo"
+    init_method: str = "mcf"
+    reliable_fraction: float = 0.0
+    metadata: Dict[str, Any] = field(default_factory=dict)
+
+    def save(
+        self,
+        output_dir: Union[str, Path],
+        save_png: bool = False,
+        mask_unreliable: bool = True,
+    ) -> Dict[str, Path]:
+        """
+        Save unwrapped phase and connected components as GeoTIFFs.
+
+        Writes:
+            unwrapped_phase.tif   (float32, radians, nodata=-9999)
+            conncomp.tif          (int32, 0=unreliable)
+            coherence.tif         (float32, 0-1)
+            [optional] unwrapped_phase.png, conncomp.png
+
+        Args:
+            output_dir:       Directory to save into.
+            save_png:         If True, also save PNG visualizations.
+            mask_unreliable:  If True (default), pixels with conncomp==0
+                              are set to nodata in the unwrapped phase
+                              GeoTIFF. This is baked in automatically so
+                              every user gets correct nodata handling
+                              without having to remember to do it manually.
+
+        Returns:
+            Dict mapping product name to output path.
+        """
+        import numpy as np
+
+        try:
+            import rasterio
+        except ImportError:
+            raise ImportError('rasterio required: pip install "pygeofetch[geo]"')
+
+        out_dir = Path(output_dir)
+        out_dir.mkdir(parents=True, exist_ok=True)
+        paths = {}
+
+        base_profile = {
+            "driver": "GTiff",
+            "count": 1,
+            "height": self.unwrapped_phase.shape[0],
+            "width": self.unwrapped_phase.shape[1],
+            "crs": self.profile.get("crs"),
+            "transform": self.profile.get("transform"),
+            "compress": "deflate",
+            "tiled": True,
+            "blockxsize": 256,
+            "blockysize": 256,
+        }
+
+        # ── Unwrapped phase ──
+        unw_to_save = self.unwrapped_phase.copy()
+        if mask_unreliable:
+            unw_to_save[self.conncomp == 0] = -9999.0
+
+        phase_path = out_dir / "unwrapped_phase.tif"
+        phase_profile = dict(base_profile, dtype="float32", nodata=-9999.0)
+        with rasterio.open(phase_path, "w", **phase_profile) as dst:
+            dst.write(unw_to_save.astype(np.float32)[np.newaxis])
+        paths["unwrapped_phase"] = phase_path
+
+        # ── Connected components ──
+        cc_path = out_dir / "conncomp.tif"
+        cc_profile = dict(base_profile, dtype="int32", nodata=0)
+        with rasterio.open(cc_path, "w", **cc_profile) as dst:
+            dst.write(self.conncomp.astype(np.int32)[np.newaxis])
+        paths["conncomp"] = cc_path
+
+        # ── Coherence ──
+        coh_path = out_dir / "coherence.tif"
+        coh_profile = dict(base_profile, dtype="float32", nodata=-1.0)
+        with rasterio.open(coh_path, "w", **coh_profile) as dst:
+            dst.write(self.coherence.astype(np.float32)[np.newaxis])
+        paths["coherence"] = coh_path
 
-        return snaphu
-    except ImportError:
-        raise ImportError(
-            "snaphu-py is not installed.\n"
-            'Install with: pip install "pygeofetch[insar]"\n'
-            "Or directly:  pip install snaphu\n\n"
-            "snaphu-py provides Python bindings for SNAPHU, the same "
-            "phase-unwrapping algorithm (Chen & Zebker 2001) used by "
-            "ASF, ISCE2/3, GAMMA, and SNAP."
+        logger.info(
+            "Unwrap products saved → %s (reliable=%.1f%%)",
+            out_dir, self.reliable_fraction * 100,
+        )
+
+        # ── Optional PNG visualizations ──
+        if save_png:
+            self._save_pngs(out_dir, unw_to_save, paths)
+
+        return paths
+
+    def _save_pngs(self, out_dir: Path, unw_masked, paths: Dict[str, Path]) -> None:
+        """Save PNG visualizations with robust percentile scaling."""
+        import numpy as np
+        import matplotlib
+        matplotlib.use("Agg")  # non-interactive backend for headless saving
+        import matplotlib.pyplot as plt
+
+        # ── Unwrapped phase PNG ──
+        fig, ax = plt.subplots(1, 1, figsize=(14, 8))
+        masked_unw = np.ma.masked_where(self.conncomp == 0, self.unwrapped_phase)
+        finite_unw = self.unwrapped_phase[self.conncomp > 0]
+        if finite_unw.size > 0:
+            vmin = float(np.percentile(finite_unw, 2))
+            vmax = float(np.percentile(finite_unw, 98))
+        else:
+            vmin, vmax = -np.pi, np.pi
+        im = ax.imshow(masked_unw, cmap="jet", vmin=vmin, vmax=vmax)
+        ax.set_title(
+            f"Unwrapped Phase (rad)\n"
+            f"{self.reference_date} → {self.secondary_date} | "
+            f"reliable={self.reliable_fraction*100:.1f}%"
+        )
+        fig.colorbar(im, ax=ax, fraction=0.046, pad=0.04)
+        png_path = out_dir / "unwrapped_phase.png"
+        fig.savefig(png_path, dpi=150, bbox_inches="tight")
+        plt.close(fig)
+
+        # ── Connected components PNG ──
+        fig, ax = plt.subplots(1, 1, figsize=(14, 8))
+        masked_cc = np.ma.masked_where(self.conncomp == 0, self.conncomp)
+        ax.imshow(masked_cc, cmap="tab20")
+        ax.set_title(
+            f"Connected Components\n"
+            f"{self.reference_date} → {self.secondary_date} | "
+            f"reliable={self.reliable_fraction*100:.1f}%"
+        )
+        png_path = out_dir / "conncomp.png"
+        fig.savefig(png_path, dpi=150, bbox_inches="tight")
+        plt.close(fig)
+
+        logger.info("Unwrap PNGs saved → %s", out_dir)
+
+
+def _ensure_snaphu_cli() -> str:
+    """
+    Ensures the SNAPHU CLI executable is available.
+    1. Checks system PATH.
+    2. Checks ~/.pygeofetch/bin/snaphu(.exe).
+    3. If on Windows and missing, downloads the pre-compiled binary from GitHub.
+    """
+    exe_name = "snaphu.exe" if platform.system() == "Windows" else "snaphu"
+    
+    # 1. System PATH
+    path = shutil.which(exe_name)
+    if path:
+        return path
+        
+    # 2. Local cache
+    bin_dir = Path.home() / ".pygeofetch" / "bin"
+    bin_dir.mkdir(parents=True, exist_ok=True)
+    local_exe = bin_dir / exe_name
+    
+    if local_exe.exists():
+        return str(local_exe)
+        
+    # 3. Download if on Windows
+    if platform.system() == "Windows":
+        logger.info("SNAPHU executable not found. Downloading pre-compiled binary for Windows...")
+        api_url = "https://api.github.com/repos/isce-framework/snaphu-py/releases/latest"
+        asset_url = None
+        
+        try:
+            req = urllib.request.Request(api_url, headers={'User-Agent': 'PyGeoFetch'})
+            with urllib.request.urlopen(req, timeout=15) as response:
+                data = json.loads(response.read().decode())
+                
+            for asset in data.get("assets", []):
+                name = asset["name"].lower()
+                if "win" in name and name.endswith(".zip"):
+                    asset_url = asset["browser_download_url"]
+                    break
+                    
+            if not asset_url:
+                # Fallback to scottstanie's repo which often hosts the windows binaries
+                api_url2 = "https://api.github.com/repos/scottstanie/snaphu-py/releases/latest"
+                req2 = urllib.request.Request(api_url2, headers={'User-Agent': 'PyGeoFetch'})
+                with urllib.request.urlopen(req2, timeout=15) as response2:
+                    data2 = json.loads(response2.read().decode())
+                for asset in data2.get("assets", []):
+                    if "win" in asset["name"].lower() and asset["name"].endswith(".zip"):
+                        asset_url = asset["browser_download_url"]
+                        break
+        except Exception as e:
+            logger.warning(f"Could not query GitHub API for SNAPHU binary: {e}")
+            
+        if not asset_url:
+            raise RuntimeError(
+                "Could not find a pre-compiled SNAPHU executable for Windows.\n"
+                "Please install it manually and add it to your PATH, or install via pip:\n"
+                "  pip install snaphu"
+            )
+            
+        logger.info(f"Downloading SNAPHU from {asset_url}...")
+        try:
+            with tempfile.TemporaryDirectory() as tmp_dir:
+                zip_path = Path(tmp_dir) / "snaphu.zip"
+                urllib.request.urlretrieve(asset_url, str(zip_path))
+                
+                with zipfile.ZipFile(zip_path, 'r') as zf:
+                    exe_files = [f for f in zf.namelist() if f.lower().endswith(".exe")]
+                    if not exe_files:
+                        raise RuntimeError("Downloaded zip did not contain an .exe file.")
+                    
+                    with zf.open(exe_files[0]) as src, open(local_exe, "wb") as dst:
+                        shutil.copyfileobj(src, dst)
+                        
+            logger.info(f"SNAPHU downloaded successfully to {local_exe}")
+            return str(local_exe)
+        except Exception as e:
+            raise RuntimeError(f"Failed to download/extract SNAPHU executable: {e}")
+            
+    else:
+        raise RuntimeError(
+            "SNAPHU executable not found in PATH.\n"
+            "Please install it using your system package manager:\n"
+            "  Ubuntu/Debian: sudo apt-get install snaphu\n"
+            "  macOS (Homebrew): brew install snaphu\n"
+            "Or install the Python bindings: pip install snaphu"
         )
 
 
@@ -52,49 +285,6 @@ def goldstein_filter(
 ):
     """
     Adaptive Goldstein phase filter.
-
-    Suppresses interferometric phase noise in the frequency domain,
-    per-tile, weighting each spatial frequency by its own local power.
-    This is fundamentally different from multilook() -- multilooking
-    averages blindly in the spatial domain regardless of what's in the
-    data; Goldstein filtering adaptively preserves real fringe patterns
-    while suppressing noise, since noise and signal separate cleanly in
-    the frequency domain but not in the spatial domain. The two are
-    complementary, not substitutes -- multilook first to reduce array
-    size and get an honest coherence estimate, then Goldstein filter
-    the (still noisy) phase before unwrapping.
-
-    Verified before use, not assumed: on synthetic data with known
-    ground truth (real fringe pattern, coherence=0.5, matching this
-    project's real Mexico City coherence level), filtering reduced mean
-    phase error from 0.96 rad to 0.36 rad against the true phase (62%
-    reduction). More directly: on synthetic data at coherence=0.55 that
-    reproducibly failed to unwrap (0% reliable, matching every real
-    failure seen across this project's Obuasi, Accra, and Mexico City
-    InSAR work), the SAME data with Goldstein filtering applied first
-    unwrapped at 94.8% reliable.
-
-    Args:
-        interferogram: Complex interferogram (ref * conj(sec)), any
-                       shape. Real, non-complex wrapped phase should be
-                       converted first via np.exp(1j * phase).
-        alpha:         Filter strength, 0.0 (no filtering, returns the
-                       input essentially unchanged) to 1.0 (aggressive,
-                       risks distorting real signal in low-SNR tiles).
-                       0.5-0.7 is a reasonable starting range; higher
-                       values trade more noise suppression for more
-                       risk of altering genuine phase structure.
-        tile_size:     FFT tile size in pixels. Smaller tiles adapt to
-                       local noise better but have less frequency
-                       resolution; larger tiles are the opposite.
-                       32-64 is standard practice.
-        overlap:       Fraction of tile overlap (0-1), blended with a
-                       Hann window to avoid tile-boundary artifacts.
-                       0.5 (50%) is standard and verified here.
-
-    Returns:
-        Filtered complex interferogram, same shape and dtype
-        (complex64) as the input.
     """
     import numpy as np
 
@@ -138,7 +328,7 @@ def goldstein_filter(
 
     valid = weight_sum > 0
     output[valid] /= weight_sum[valid]
-    output[~valid] = interferogram[~valid]  # untouched where no tile ever covered it
+    output[~valid] = interferogram[~valid]
     return output.astype(np.complex64)
 
 
@@ -150,75 +340,7 @@ def bridge_unwrap_regions(
     reference_pixel=None,
 ):
     """
-    Bridging unwrapping-error correction (Yunjun, Fattahi & Amelung 2019,
-    Computers & Geosciences 133, 104331 -- the method MintPy uses,
-    ported and adapted natively here rather than depending on MintPy).
-
-    SNAPHU unwraps each connected component (conncomp) internally
-    consistently, but has no way to relate physically DISCONNECTED
-    regions to each other -- each island's phase could be off from the
-    others by an unknown INTEGER multiple of 2*pi, since SNAPHU's
-    network-flow solver never sees a path connecting them. Bridging
-    finds the closest point-pair between regions and estimates that
-    integer offset from the real, local median phase difference there
-    (robust to per-pixel noise), then corrects the whole region by that
-    exact multiple of 2*pi.
-
-    Real, important, honest limitation, not a flaw in this
-    implementation specifically: bridging can only recover RELATIVE
-    consistency between regions, never absolute truth. The largest
-    region is used as the reference (offset 0); if THAT region itself
-    carries a real, undetected cycle error, every other region gets
-    correctly bridged relative to it but the whole scene stays offset
-    from ground truth by that same amount. This is the same fundamental
-    limitation that's why SBASTimeSeries needs an explicit reference
-    pixel -- no phase-based method alone can anchor to an absolute
-    value without external ground truth (a GPS station, a known-stable
-    reference point, etc.).
-
-    Verified before use: on synthetic data with THREE disconnected
-    regions and different, deliberate, known integer-cycle errors
-    introduced in each (including realistic per-pixel phase noise at
-    coherence=0.6), every pairwise region-to-region consistency check
-    came back under 0.02 rad after correction -- confirming the method
-    correctly recovers mutual consistency, the real, valid claim this
-    technique can make (verified NOT to claim absolute-truth recovery,
-    which no such method can deliver without external reference data).
-
-    Args:
-        unwrapped_phase: 2D array of unwrapped phase (radians), as
-                       produced by PhaseUnwrapper.unwrap().
-        conncomp:      2D array of connected-component labels from the
-                       same unwrap() call, same shape. 0 = unreliable
-                       (not part of any real region).
-        bridge_radius: Half-size of the window around each bridge
-                       endpoint used to compute the robust median phase
-                       difference. Matches MintPy's own default (50).
-        min_region_size: Regions smaller than this (in pixels) are
-                       excluded from bridging -- too small to trust a
-                       median estimate from, left as unreliable.
-        reference_pixel: Optional (row, col). If given, the region
-                       CONTAINING this pixel is used as the reference
-                       (offset 0) instead of always defaulting to the
-                       largest region. Matters for multi-pair use (e.g.
-                       SBAS): bridging each pair independently with the
-                       default (largest-region) reference can anchor
-                       different pairs to genuinely different real
-                       locations, since "largest region" isn't
-                       necessarily the same region pair to pair —
-                       confirmed directly: the same pixel's bridged
-                       value varied by tens of radians across pairs
-                       without this, corrupting the downstream joint
-                       inversion even though each pair was individually
-                       correctly bridged. Pass the SAME reference_pixel
-                       used for SBAS's own referencing to fix this.
-
-    Returns:
-        (corrected_phase, offsets_applied) -- corrected_phase is the
-        same shape as unwrapped_phase, with each region's integer-cycle
-        offset applied. offsets_applied is a dict mapping region label
-        to the real, applied correction in radians (0 for the
-        reference region, by definition).
+    Bridging unwrapping-error correction.
     """
     import numpy as np
     from scipy.spatial import cKDTree
@@ -238,9 +360,7 @@ def bridge_unwrap_regions(
         if rp_label == 0 or rp_label not in valid_labels:
             raise ValueError(
                 f"reference_pixel {reference_pixel} is not part of any "
-                f"valid (reliable, large-enough) region — cannot anchor "
-                f"bridging there. Pick a pixel with conncomp != 0 in a "
-                f"region at least min_region_size={min_region_size} pixels."
+                f"valid (reliable, large-enough) region."
             )
         reference_label = rp_label
     else:
@@ -252,7 +372,7 @@ def bridge_unwrap_regions(
     remaining = set(valid_labels) - {reference_label}
 
     while remaining:
-        best = None  # (distance, label, target_label, point_a, point_b)
+        best = None
         for lbl in remaining:
             lbl_points = np.column_stack(np.where(conncomp == lbl))
             for resolved_lbl, ref_points in resolved_points.items():
@@ -295,64 +415,7 @@ def multilook(
     wrapped_phase: Optional[bool] = None,
 ) -> Any:
     """
-    Average an array down by the given factor in each dimension before
-    unwrapping — reduces both pixel count and phase noise, the standard
-    technique for improving unwrapping reliability on low-coherence data
-    (Eineder 1999; cited directly in ESA's InSAR processing tutorial,
-    TM-19: "In cases of low coherence (say 0.1), the number of looks to
-    be averaged should increase up to 100").
-
-    Args:
-        data:            2D array to multilook. Complex (interferogram),
-                        or real-valued (coherence, wrapped phase,
-                        unwrapped phase, or any other raster).
-        looks_azimuth:   Averaging factor along axis 0.
-        looks_range:     Averaging factor along axis 1.
-        wrapped_phase:   Required for real-valued input, not optional or
-                        defaulted — dtype alone cannot tell wrapped phase
-                        apart from coherence or unwrapped phase, and
-                        guessing wrong is not a small error:
-
-                        - wrapped_phase=True: circular (complex-exponential)
-                          averaging. Correct for phase bounded to
-                          [-pi, pi) — plain arithmetic averaging would be
-                          biased wherever a look-window straddles the
-                          wrap boundary (e.g. averaging -3.1 and +3.1 rad
-                          arithmetically gives ~0, when the true circular
-                          average is near +-pi).
-                        - wrapped_phase=False: plain arithmetic averaging.
-                          Correct for coherence (bounded [0,1], not an
-                          angle at all) and for unwrapped phase (an
-                          unbounded real value). Verified directly:
-                          circular-averaging real unwrapped phase of
-                          ~45 rad silently collapses it to ~1.3 rad,
-                          destroying the very thing unwrapping produced.
-
-                        Complex input (interferograms) ignores this
-                        parameter entirely and always averages directly
-                        as complex numbers — unambiguous, no real/wrapped
-                        distinction applies.
-
-    Returns:
-        The multilooked array, same dtype family as the input.
-
-    Raises:
-        ValueError: if `data` is real-valued and `wrapped_phase` was not
-            explicitly specified — a real, deliberate refusal to guess,
-            not an oversight. Silent dtype-based guessing was the
-            original design of this function before this exact failure
-            mode was found and fixed.
-
-    Example::
-
-        # A real interferogram (complex) -- unambiguous
-        igram_ml = multilook(interferogram, looks_azimuth=4, looks_range=1)
-
-        # Wrapped phase -- must say so explicitly
-        phase_ml = multilook(wrapped_phase_rad, 4, 1, wrapped_phase=True)
-
-        # Coherence -- must say so explicitly (plain averaging)
-        coherence_ml = multilook(coherence, 4, 1, wrapped_phase=False)
+    Average an array down by the given factor in each dimension.
     """
     import numpy as np
 
@@ -368,13 +431,8 @@ def multilook(
     if wrapped_phase is None:
         raise ValueError(
             "multilook() received real-valued input but wrapped_phase was "
-            "not specified. This is required, not optional: dtype alone "
-            "cannot distinguish wrapped phase (needs circular averaging) "
-            "from coherence or unwrapped phase (needs plain arithmetic "
-            "averaging), and guessing wrong silently corrupts the data "
-            "rather than raising an error. Pass wrapped_phase=True for "
-            "wrapped phase in radians, or wrapped_phase=False for "
-            "coherence, unwrapped phase, or any other real-valued raster."
+            "not specified. Pass wrapped_phase=True for wrapped phase, "
+            "or wrapped_phase=False for coherence/unwrapped phase."
         )
 
     if wrapped_phase:
@@ -386,50 +444,83 @@ def multilook(
 
 class PhaseUnwrapper:
     """
-    Phase unwrapping via SNAPHU (Statistical-cost, Network-flow Algorithm).
-
-    Args:
-        cost_mode: SNAPHU cost function — ``"topo"`` (default, for terrain),
-                   ``"defo"`` (for deformation — less smoothing bias),
-                   ``"smooth"`` (generic smoothness prior),
-                   ``"nostatcosts"`` (uniform cost, fastest, least accurate).
-        init_method: ``"mcf"`` (default — Minimum Cost Flow, matches ASF/GAMMA)
-                     or ``"mst"`` (Minimum Spanning Tree — faster, less optimal).
-
-    Example::
-
-        from pygeofetch.insar import InterferogramGenerator, PhaseUnwrapper
-
-        gen    = InterferogramGenerator()
-        result = gen.process_pair("ref.tif", "sec.tif", dem="dem.tif")
-
-        unwrapper = PhaseUnwrapper(cost_mode="defo")
-        unwrapped, conncomp = unwrapper.unwrap(
-            result.interferogram, result.coherence
-        )
-
-    Choosing cost_mode:
-        - Use ``"topo"`` for DEM generation / topographic mapping tasks
-          where phase gradients follow terrain.
-        - Use ``"defo"`` for deformation monitoring (subsidence, volcanic,
-          earthquake) where phase gradients follow displacement, not
-          terrain — this is the standard choice for MintPy/SBAS workflows.
+    Phase unwrapping via SNAPHU.
     """
 
     def __init__(self, cost_mode: str = "defo", init_method: str = "mcf") -> None:
         valid_costs = ("topo", "defo", "smooth", "nostatcosts")
         if cost_mode not in valid_costs:
-            raise ValueError(
-                f"cost_mode must be one of {valid_costs}, got {cost_mode!r}"
-            )
+            raise ValueError(f"cost_mode must be one of {valid_costs}, got {cost_mode!r}")
         valid_inits = ("mcf", "mst")
         if init_method not in valid_inits:
-            raise ValueError(
-                f"init_method must be one of {valid_inits}, got {init_method!r}"
-            )
+            raise ValueError(f"init_method must be one of {valid_inits}, got {init_method!r}")
         self._cost_mode = cost_mode
         self._init_method = init_method
 
+    def _unwrap_cli(self, igram, corr, nlooks, min_conncomp_frac, min_region_size):
+        """
+        Fallback unwrapping using the SNAPHU CLI executable.
+        Bypasses Python C-extension compilation issues on Windows entirely.
+        """
+        import numpy as np
+        
+        cli_path = _ensure_snaphu_cli()
+        height, width = igram.shape
+        
+        with tempfile.TemporaryDirectory() as tmp_dir:
+            tmp = Path(tmp_dir)
+            igram_path = tmp / "igram.cpx"
+            corr_path = tmp / "corr.cor"
+            unw_path = tmp / "unw.unw"
+            cc_path = tmp / "conncomp.cc"
+            conf_path = tmp / "snaphu.conf"
+            
+            # Write binary files
+            igram.tofile(str(igram_path))
+            corr.tofile(str(corr_path))
+            
+            # Write config file using relative paths to avoid Windows space issues
+            nlooks_int = max(1, int(nlooks))
+            conf_text = f"""INFILE            igram.cpx
+                INFILEFORMAT      COMPLEX_DATA
+                CORRFILE          corr.cor
+                CORRFILEFORMAT    FLOAT_DATA
+                OUTFILE           unw.unw
+                OUTFILEFORMAT     FLOAT_DATA
+                CONNCOMPFILE      conncomp.cc
+                CONNCOMPOUTFORMAT UINT_DATA
+                LINELENGTH        {width}
+                STATCOSTMODE      {self._cost_mode.upper()}
+                INITMETHOD        {self._init_method.upper()}
+                NLOOKSRANGE       {nlooks_int}
+                NLOOKSAZ          {nlooks_int}
+                """
+            conf_path.write_text(conf_text)
+            
+            # Run SNAPHU from within the temp directory
+            try:
+                cmd = [cli_path, "-f", "snaphu.conf"]
+                result = subprocess.run(cmd, capture_output=True, text=True, cwd=str(tmp), timeout=3600)
+                if result.returncode != 0:
+                    raise RuntimeError(f"SNAPHU CLI failed with code {result.returncode}: {result.stderr}")
+            except Exception as e:
+                raise RuntimeError(f"SNAPHU CLI execution failed: {e}")
+                
+            # Read outputs
+            unw = np.fromfile(str(unw_path), dtype=np.float32).reshape((height, width))
+            conncomp = np.fromfile(str(cc_path), dtype=np.uint32).reshape((height, width))
+            
+        # Apply reliability filtering to match Python API behavior
+        total_pixels = height * width
+        labels, counts = np.unique(conncomp, return_counts=True)
+        for lbl, count in zip(labels, counts):
+            if lbl == 0:
+                continue
+            if count < min_region_size or (count / total_pixels) < min_conncomp_frac:
+                conncomp[conncomp == lbl] = 0
+                
+        return unw, conncomp.astype(np.int32)
+
     def unwrap(
         self,
         interferogram: Any,
@@ -439,56 +530,11 @@ class PhaseUnwrapper:
         min_conncomp_frac: float = 0.01,
         min_region_size: int = 100,
     ) -> Tuple[Any, Any]:
-        """
-        Unwrap a wrapped interferogram phase.
-
-        Args:
-            interferogram: Complex64 array (wrapped interferogram) OR
-                           float32 array of wrapped phase in radians.
-            coherence:     Float32 coherence array, 0-1, same shape.
-            nlooks:        Effective number of looks (affects statistical
-                           cost weighting). Use the multilook factor applied
-                           during interferogram formation.
-            mask:          Optional boolean array — True = valid, False = masked out
-                           (e.g. water bodies, layover/shadow regions).
-            min_conncomp_frac: Minimum size of a connected component, as a
-                           fraction of total pixels, for SNAPHU to mark it
-                           reliable (conncomp != 0). snaphu-py's own
-                           default (0.01 = 1% of the whole scene) can
-                           discard genuinely valid, internally-consistent
-                           regions when the real coherent area is small
-                           relative to the full scene — confirmed
-                           directly: a real low-coherence scene with a
-                           small but real coherent patch reported 100%
-                           unreliable at the default, purely because that
-                           real patch fell under the 1%-of-scene pixel
-                           threshold, not because nothing was actually
-                           unwrappable. Lower this (e.g. 0.001-0.005) for
-                           scenes with small AOIs or patchy real coherence.
-            min_region_size: Minimum absolute pixel count for the same
-                           reliability decision — snaphu-py's own default
-                           is 100. Works alongside min_conncomp_frac (the
-                           less restrictive of the two typically governs
-                           on a small scene).
-
-        Returns:
-            (unwrapped_phase, conncomp) — both same shape as input.
-            unwrapped_phase: float32 radians, continuous (not wrapped to [-pi, pi))
-            conncomp:        int32 connected-component labels (0 = unreliable/masked)
-
-        Example::
-
-            unwrapped, conncomp = unwrapper.unwrap(igram, coherence, nlooks=4.0)
-            # conncomp == 0 marks pixels SNAPHU could not confidently unwrap
-            reliable = conncomp > 0
-        """
         np = self._np()
-        sx = _require_snaphu()
 
         if np.iscomplexobj(interferogram):
             igram = interferogram.astype(np.complex64)
         else:
-            # Treat as wrapped phase in radians — convert to unit-magnitude complex
             igram = np.exp(1j * interferogram).astype(np.complex64)
 
         corr = np.clip(coherence, 0.0, 1.0).astype(np.float32)
@@ -496,9 +542,6 @@ class PhaseUnwrapper:
         if mask is not None:
             corr = np.where(mask, corr, 0.0).astype(np.float32)
 
-        # Real, worthwhile defensive check: NaN/Inf coherence (e.g. from
-        # an upstream division-by-zero on a fully decorrelated pixel)
-        # would otherwise reach SNAPHU as invalid input.
         corr = np.nan_to_num(corr, nan=0.0, posinf=0.0, neginf=0.0)
 
         logger.info(
@@ -510,7 +553,9 @@ class PhaseUnwrapper:
         )
 
         try:
-            unwrapped, conncomp = sx.unwrap(
+            # Try Python API first (fastest)
+            import snaphu
+            unwrapped, conncomp = snaphu.unwrap(
                 igram,
                 corr,
                 nlooks=nlooks,
@@ -519,12 +564,17 @@ class PhaseUnwrapper:
                 min_conncomp_frac=min_conncomp_frac,
                 min_region_size=min_region_size,
             )
+        except ImportError:
+            # Fallback to CLI (solves Windows installation nightmares)
+            logger.info("snaphu Python package not found. Falling back to SNAPHU CLI executable...")
+            unwrapped, conncomp = self._unwrap_cli(
+                igram, corr, nlooks, min_conncomp_frac, min_region_size
+            )
         except Exception as exc:
             raise RuntimeError(
                 f"SNAPHU unwrapping failed: {exc}\n"
                 "Common causes: incompatible array shapes, all-zero coherence, "
-                "or insufficient memory for large scenes. Consider multilooking "
-                "the interferogram first to reduce pixel count."
+                "or insufficient memory for large scenes."
             ) from exc
 
         n_unreliable = int(np.sum(conncomp == 0))
@@ -532,8 +582,7 @@ class PhaseUnwrapper:
         if pct > 30:
             logger.warning(
                 "%.1f%% of pixels are in the unreliable connected component "
-                "(conncomp==0). Consider improving coherence via multilooking "
-                "or filtering, or check for large decorrelated areas.",
+                "(conncomp==0). Consider improving coherence via multilooking.",
                 pct,
             )
         else:
@@ -541,6 +590,87 @@ class PhaseUnwrapper:
 
         return unwrapped.astype(np.float32), conncomp
 
+    def unwrap_pair(
+        self,
+        interferogram: Any,
+        coherence: Any,
+        profile: Dict[str, Any],
+        reference_date: Optional[str] = None,
+        secondary_date: Optional[str] = None,
+        nlooks: float = 1.0,
+        looks_azimuth: int = 1,
+        looks_range: int = 1,
+        mask: Optional[Any] = None,
+        min_conncomp_frac: float = 0.001,
+        min_region_size: int = 100,
+    ) -> UnwrapResult:
+        """
+        Unwrap a single interferogram pair and return an UnwrapResult.
+        
+        This is the high-level method that combines unwrap() + result
+        packaging. Use this in notebook cells for clean orchestration:
+        
+            result = unwrapper.unwrap_pair(phase_ml, coh_ml, profile,
+                                           looks_azimuth=UNWRAP_LOOKS_AZ, 
+                                           looks_range=UNWRAP_LOOKS_RG)
+            result.save(output_dir / f"{d1}_{d2}", save_png=True)
+        
+        Args:
+            interferogram: Complex interferogram or wrapped phase (radians).
+            coherence:     Coherence array (0-1), same shape.
+            profile:       Rasterio-style profile for georeferencing.
+            reference_date, secondary_date: ISO date strings for labeling.
+            nlooks:        Effective number of looks.
+            looks_azimuth, looks_range: Multilook factors used to produce the
+                                        input arrays. Used to correctly scale
+                                        the georeferencing transform.
+            mask:          Optional boolean mask (True=valid).
+            min_conncomp_frac: Minimum connected component fraction.
+            min_region_size: Minimum region size in pixels.
+        
+        Returns:
+            UnwrapResult with all data packaged and ready to save.
+        """
+        import numpy as np
+
+        unwrapped, conncomp = self.unwrap(
+            interferogram, coherence,
+            nlooks=nlooks,
+            mask=mask,
+            min_conncomp_frac=min_conncomp_frac,
+            min_region_size=min_region_size,
+        )
+
+        reliable_fraction = float(np.mean(conncomp > 0))
+
+        # Scale the profile transform to match the multilooked arrays
+        scaled_profile = dict(profile)
+        if looks_azimuth > 1 or looks_range > 1:
+            if scaled_profile.get("transform") is not None:
+                from rasterio.transform import Affine
+                scaled_profile["transform"] = scaled_profile["transform"] * Affine.scale(looks_range, looks_azimuth)
+            scaled_profile["height"] = unwrapped.shape[0]
+            scaled_profile["width"] = unwrapped.shape[1]
+
+        return UnwrapResult(
+            unwrapped_phase=unwrapped,
+            conncomp=conncomp,
+            coherence=coherence,
+            profile=scaled_profile,
+            reference_date=reference_date,
+            secondary_date=secondary_date,
+            nlooks=nlooks,
+            cost_mode=self._cost_mode,
+            init_method=self._init_method,
+            reliable_fraction=reliable_fraction,
+            metadata={
+                "cost_mode": self._cost_mode,
+                "init_method": self._init_method,
+                "nlooks": nlooks,
+                "reliable_fraction": reliable_fraction,
+            },
+        )
+
     def unwrap_files(
         self,
         interferogram_path: Union[str, Path],
@@ -549,26 +679,6 @@ class PhaseUnwrapper:
         nlooks: float = 1.0,
         mask_path: Optional[Union[str, Path]] = None,
     ) -> Path:
-        """
-        Unwrap directly from/to GeoTIFF files, preserving georeferencing.
-
-        Args:
-            interferogram_path: Wrapped phase or complex interferogram GeoTIFF.
-            coherence_path:     Coherence GeoTIFF (0-1).
-            output_path:        Output path for the unwrapped phase GeoTIFF.
-            nlooks:              Effective number of looks.
-            mask_path:           Optional binary mask GeoTIFF (1=valid, 0=masked).
-
-        Returns:
-            Path to the unwrapped phase GeoTIFF.
-
-        Example::
-
-            unwrapper.unwrap_files(
-                "wrapped_phase.tif", "coherence.tif",
-                output_path="unwrapped.tif", nlooks=4.0,
-            )
-        """
         np = self._np()
         try:
             import rasterio
@@ -622,5 +732,4 @@ class PhaseUnwrapper:
 
     def _np(self):
         import numpy as np
-
         return np

pygeofetch/meta.yaml

@@ -1,4 +1,4 @@
-{% set version = "2.0.3" %}
+{% set version = "2.0.4" %}
 
 package:
   name: pygeofetch

{pygeofetch-2.0.3.dist-info → pygeofetch-2.0.4.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pygeofetch
-Version: 2.0.3
+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.3.dist-info → pygeofetch-2.0.4.dist-info}/RECORD

@@ -1,11 +1,11 @@
-pygeofetch/__init__.py,sha256=g7_nMbdOgkKQ2ey8F9Vne6cto0205qDjI-sfcj-JULs,1990
-pygeofetch/meta.yaml,sha256=k9ZW4b5eJItOWjelJsCPU0XUp1-2KgXXiklYjo4vxSI,1280
+pygeofetch/__init__.py,sha256=BKesKaBedlzLMOOF5DKJ5qFl2_HT0ND_1DzMXYQuSLc,1990
+pygeofetch/meta.yaml,sha256=jLWw6eKXkoNNHhqAMfC8viFsNaPLFS6cVVXBnzFq5u0,1280
 pygeofetch/cli/__init__.py,sha256=QZMIIHEgmjGFieucqq9fZ5uephxP9-jdu1s8Q4qqw8o,30
 pygeofetch/cli/auth_commands.py,sha256=YqbrN_BYcAYCaUIYLpSJ_VIw35tKFUiD9Kc55SWbDWg,7742
 pygeofetch/cli/config_commands.py,sha256=1Pps0HLCLPODMlM6SFV8ru3IKCDpexSTz8uKIXvIIF8,3918
 pygeofetch/cli/download_commands.py,sha256=reQ9vmA50mj1zqechjLHAOe_cjBfa1miqfWa8UiIlxU,11741
 pygeofetch/cli/index_commands.py,sha256=IoLGrsSU-lTcBitFFsg8EtucqSKZtNL-0ODj_I8Twew,10020
-pygeofetch/cli/main.py,sha256=6p8mrv2zmIF0NFV04v1gf4Gp0VU48xHmRC4XlXi1pW8,30335
+pygeofetch/cli/main.py,sha256=wJG74Rbfsolf4xgUTq4S8UTZ0aVrX1IxyRSJzUA1ncA,30335
 pygeofetch/cli/pipeline_process_commands.py,sha256=OvuouT35zZlrC-7hWAJRfaY_aUNk4ScK0Fia9WVB_Gw,6904
 pygeofetch/cli/postprocess_commands.py,sha256=kof_f-kjjvYl5eqPqrcNHSOUM_qVkGdSh6-N4vcx2y4,5825
 pygeofetch/cli/preprocess_commands.py,sha256=cFp1VR03Q1pmCwiBWYmS5lXF3NOnzVAq3XgrZh3rBdU,8696
@@ -39,7 +39,7 @@ pygeofetch/insar/splitspectrum_diagnostic.py,sha256=_IlfBs__BW7Yz2RwdmWxfrOspe67
 pygeofetch/insar/stack_selection.py,sha256=ebFwO063cCT9kn3zLPlkYu6fpnfx-SRC90Ch18E7qJk,13157
 pygeofetch/insar/synthetic.py,sha256=FazdaG_u3GR1qk8022T92W2uxDJPg7OJaUSGY0wR0pw,16248
 pygeofetch/insar/timeseries.py,sha256=EtLJiPySMaUWwyNxI2GyfBdkqB4W-uvL-_E_T_POHz4,32063
-pygeofetch/insar/unwrap.py,sha256=Sv6T5X5Zis44c_uxZy466vaHahwfO0tTiqvl0wdknag,27369
+pygeofetch/insar/unwrap.py,sha256=3cAEI80KkY98lZ8rHNWlqzr-TXt_6RVWT3auslTi4FA,28218
 pygeofetch/insar/validate.py,sha256=BZaVvaPNllfDzoPwat0vDA4do6H5xh5Ju_g4r5YNogE,10110
 pygeofetch/insar/visualize.py,sha256=D_KlWkpuOvfjke6ThHcMBkZTRwWn1KdBFNL1TBcy6kI,7543
 pygeofetch/insar/workflow.py,sha256=8IxGgabdz9fDLoGAVrJRCdw16GP3sSDSoFPXyv1RXcg,11713
@@ -104,9 +104,9 @@ pygeofetch/utils/validators.py,sha256=f-k3mGFP4byjimyDymhPEdsz5I16jZacx1HSnwrARj
 pygeofetch/viz/__init__.py,sha256=xf2C9IL4n3bv3oxk8RYkogq7nkuNyt18V-urAoXWRQY,449
 pygeofetch/viz/map.py,sha256=vYO99NvTumCAVXVtXcEzMx_cpmH-FvSVNWl8X0PNSgE,15494
 pygeofetch/viz/plot.py,sha256=I16rdOWb80gcjYDsDvTMzuyek7QHgUNOQxY2RejBAPs,53675
-pygeofetch-2.0.3.dist-info/licenses/LICENSE,sha256=zavMyhODD6NvZTmmKFEtATrngwY4CU_NEtY7lhjxGnI,1075
-pygeofetch-2.0.3.dist-info/METADATA,sha256=ogUCAYOSzmGFw-n2_2siFpF3CNsKg1uB5mhjFfXv0pQ,43254
-pygeofetch-2.0.3.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
-pygeofetch-2.0.3.dist-info/entry_points.txt,sha256=dHiUXLF5xNJ8vgtXZoUQNleEMQUeDPZiKQOE1tW8SDY,55
-pygeofetch-2.0.3.dist-info/top_level.txt,sha256=rOmnZargIfNk99fwVOqt6OJyJvpSTBBAYO5HU37yhHk,11
-pygeofetch-2.0.3.dist-info/RECORD,,
+pygeofetch-2.0.4.dist-info/licenses/LICENSE,sha256=zavMyhODD6NvZTmmKFEtATrngwY4CU_NEtY7lhjxGnI,1075
+pygeofetch-2.0.4.dist-info/METADATA,sha256=RtGCL4jStxgOt8TpMJb0WHGaCPdQPpoByRXVqGpKeAo,43254
+pygeofetch-2.0.4.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+pygeofetch-2.0.4.dist-info/entry_points.txt,sha256=dHiUXLF5xNJ8vgtXZoUQNleEMQUeDPZiKQOE1tW8SDY,55
+pygeofetch-2.0.4.dist-info/top_level.txt,sha256=rOmnZargIfNk99fwVOqt6OJyJvpSTBBAYO5HU37yhHk,11
+pygeofetch-2.0.4.dist-info/RECORD,,