PyGeoFetch 2.4.0__tar.gz → 2.6.0__tar.gz

{pygeofetch-2.4.0 → pygeofetch-2.6.0}/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.4.0/).
+Format follows [Keep a Changelog](https://keepachangelog.com/en/2.6.0/).
 
-## [2.4.0] — 2026-07-29
+## [2.6.0] — 2026-07-29
 
 ### Added
 - Major SNAPHU unwrapping improvements for urban InSAR applications
@@ -72,7 +72,7 @@ unwrapped = unwrapper.unwrap(
 
 ---
 
-## [2.4.0] — 2026-07-12
+## [2.6.0] — 2026-07-12
 
 ### Added
 - Federated search across 22+ satellite data providers
@@ -188,8 +188,8 @@ unwrapped = unwrapper.unwrap(
 
 | Version | Date | Key Changes |
 |---------|------------|-------------|
-| **2.4.0** | 2026-07-29 | SNAPHU unwrapping fixes, 87.1% reliable pixels |
-| **2.4.0** | 2026-07-12 | 22 providers, 17 indices, Sentinel-1C/D |
+| **2.6.0** | 2026-07-29 | SNAPHU unwrapping fixes, 87.1% reliable pixels |
+| **2.6.0** | 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.4.0/pygeofetch.egg-info → pygeofetch-2.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pygeofetch
-Version: 2.4.0
+Version: 2.6.0
 Summary: Universal satellite data pipeline + geospatial processing platform
 Author-email: Samuel Appiah Kubi <appiahkubis14@gmail.com>
 License: MIT License
@@ -97,7 +97,7 @@ Requires-Dist: geemap>=0.28.0; extra == "viz"
 Requires-Dist: osmnx>=1.9.4; extra == "viz"
 Requires-Dist: contextily>=1.9.4; extra == "viz"
 Requires-Dist: xyzservices>=2023.10.0; extra == "viz"
-Requires-Dist: mapclassify>=2.5.0; extra == "viz"
+Requires-Dist: mapclassify>=2.6.0; extra == "viz"
 Requires-Dist: geoplot>=0.5.0; extra == "viz"
 Requires-Dist: mplleaflet>=0.0.5; extra == "viz"
 Requires-Dist: branca>=0.6.0; extra == "viz"

{pygeofetch-2.4.0 → pygeofetch-2.6.0}/pygeofetch/__init__.py

@@ -30,7 +30,7 @@ CLI::
     pygeofetch doctor
 """
 
-__version__ = "2.4.0"
+__version__ = "2.6.0"
 __author__ = "PyGeoFetch Contributors"
 __license__ = "MIT"
 

{pygeofetch-2.4.0 → pygeofetch-2.6.0}/pygeofetch/insar/preflight.py

@@ -1,38 +1,34 @@
 """
 Pre-download data-quality gate for InSAR stack selection.
-
 Runs AFTER search, BEFORE download. Catches — and where possible
 auto-corrects — real, confirmed data-selection failures this project
 has hit, so bandwidth and hours are never spent on a stack that was
 guaranteed to fail:
-
-  1. Search truncation          -> auto-widen max_results & re-search
-  2. Mixed relative orbits      -> confirmed (already enforced by
-                                    select_consistent_geometry(), which
-                                    should already have run before this
-                                    gate; re-checked here defensively)
-  3. Multi-candidate per date   -> coverage-aware dedup (already
-                                    handled by search_and_select_
-                                    consistent_stack(), which this gate
-                                    calls)
-  4. 0%/low AOI coverage        -> drop + report genuine gaps
-  5. Sparse temporal sampling   -> predict SBAS connectivity, warn
-  6. Burst-timing family risk   -> honest advisory, NOT a detector --
-                                    see _screen_burst_families()'s own
-                                    docstring for why a real pre-
-                                    download detector isn't achievable
-                                    with what's available before
-                                    download, and for a real, confirmed
-                                    bug found in an earlier version
-                                    that claimed to be one anyway.
-
+Search truncation          -> auto-widen max_results & re-search
+Mixed relative orbits      -> confirmed (already enforced by
+select_consistent_geometry(), which
+should already have run before this
+gate; re-checked here defensively)
+Multi-candidate per date   -> coverage-aware dedup (already
+handled by search_and_select_
+consistent_stack(), which this gate
+calls)
+0%/low AOI coverage        -> drop + report genuine gaps
+Sparse temporal sampling   -> predict SBAS connectivity, warn
+Burst-timing family risk   -> honest advisory, NOT a detector --
+see _screen_burst_families()'s own
+docstring for why a real pre-
+download detector isn't achievable
+with what's available before
+download, and for a real, confirmed
+bug found in an earlier version
+that claimed to be one anyway.
 The definitive burst-family check still happens post-download via
 select_burst_synchronized_dates() (it needs SwathTiming parsed from
 each product's real annotation XML, which isn't available before
 download). This gate handles what real pre-download signals actually
 allow, and is explicit about the one real risk it cannot resolve early.
 """
-
 from __future__ import annotations
 
 import logging
@@ -44,16 +40,14 @@ from shapely.geometry import shape, box
 
 logger = logging.getLogger("pygeofetch.insar.preflight")
 
-
 # ─────────────────────────────────────────────────────────────────────────────
 # Report data model
-# ─────────────────────────────────────────────────────────────────────────────
+# ────────────────────────────────────────────────────────────────────────────
 
 SEVERITY_GREEN = "GREEN"    # safe to proceed
 SEVERITY_YELLOW = "YELLOW"  # proceed, but with logged caveats
 SEVERITY_RED = "RED"        # do not download; fix first
 
-
 @dataclass
 class PreflightIssue:
     """A single problem found during preflight, with its fix."""
@@ -63,12 +57,10 @@ class PreflightIssue:
     auto_fixed: bool = False  # did the gate heal this automatically?
     fix_detail: str = ""      # what the auto-fix did, if applied
 
-
 @dataclass
 class PreflightReport:
     """
     Full outcome of the pre-download gate.
-
     Carries the go/no-go decision, every issue found, every auto-fix
     applied, and — critically — the provenance manifest that makes the
     whole run reproducible and defensible.
@@ -78,16 +70,45 @@ class PreflightReport:
     issues: List[PreflightIssue] = field(default_factory=list)
     selected: List[Any] = field(default_factory=list)   # final scene objects
     manifest: Dict[str, Any] = field(default_factory=dict)
+    original_count: int = 0  # how many scenes came IN, before any filtering -- see summary()'s own real-bug note
 
     def summary(self) -> str:
         lines = [f"PREFLIGHT {self.severity} — {'PROCEED' if self.go else 'BLOCKED'}"]
+
+        # Print Bandwidth Manifest if available
+        if "bandwidth_and_manifest" in self.manifest:
+            bw = self.manifest["bandwidth_and_manifest"]
+            lines.append(f"  [INFO] Estimated download size: {bw['estimated_bandwidth_gb']} GB for {len(bw['download_manifest'])} scenes.")
+
         for issue in self.issues:
             fixed = " [AUTO-FIXED]" if issue.auto_fixed else ""
             lines.append(f"  [{issue.severity}] {issue.code}{fixed}: {issue.message}")
             if issue.auto_fixed and issue.fix_detail:
                 lines.append(f"        -> {issue.fix_detail}")
-        return "\n".join(lines)
 
+        # REAL BUG FOUND AND GUARDED AGAINST HERE: a real notebook
+        # called gate.run(selected, search_report) and printed
+        # report.summary() -- which correctly showed real dates being
+        # excluded -- but never reassigned `selected = report.selected`
+        # afterward, so every downstream step (the very next cell,
+        # literally titled "Download the real, filtered scenes") kept
+        # using the original, unfiltered list. The filtering logic was
+        # completely correct; the scenes it said to exclude got
+        # downloaded anyway, because nothing after this function call
+        # actually used its return value. This can't be fixed from
+        # inside this class (a function can't force a caller to use
+        # its return value) but it CAN be made loud and impossible to
+        # miss in the one place every real run already prints.
+        if self.original_count and len(self.selected) < self.original_count:
+            dropped = self.original_count - len(self.selected)
+            lines.append(
+                f"  [REMINDER] {dropped} of {self.original_count} scene(s) were "
+                f"excluded by this gate. Use report.selected -- not your original "
+                f"list -- for every downstream step (download, extraction, "
+                f"processing). Passing the original list silently re-includes "
+                f"exactly what this gate just excluded."
+            )
+        return "\n".join(lines)
 
 # ─────────────────────────────────────────────────────────────────────────────
 # The gate itself
@@ -96,7 +117,6 @@ class PreflightReport:
 class PreflightGate:
     """
     Orchestrates every pre-download check and auto-heals what it can.
-
     Usage:
         gate = PreflightGate(client, aoi_bbox, start_date, end_date)
         report = gate.run(selected, search_report)
@@ -105,7 +125,6 @@ class PreflightGate:
             raise RuntimeError("Preflight blocked the stack. See report.")
         download_results = client.download(report.selected, ...)
     """
-
     def __init__(
         self,
         client: Any,
@@ -162,7 +181,7 @@ class PreflightGate:
         # authenticated provider these real annotation fetches need.
         self.attempt_real_burst_check = attempt_real_burst_check
 
-    # ── public entry point ────────────────────────────────────────────────
+    # ── public entry point ───────────────────────────────────────────────
     def run(self, selected: List[Any], search_report: Dict[str, Any]) -> PreflightReport:
         issues: List[PreflightIssue] = []
         selected = list(selected)  # work on a copy
@@ -172,6 +191,15 @@ class PreflightGate:
         if trunc_issue:
             issues.append(trunc_issue)
 
+        # Baseline for the "did anything get silently dropped downstream"
+        # reminder in summary() -- captured HERE, after truncation
+        # resolves, not at the very top: truncation can legitimately
+        # GROW the candidate pool (a wider re-search finding more real
+        # scenes), which isn't a "drop" and shouldn't suppress a real
+        # warning about coverage/burst-family filtering that happens
+        # after this point.
+        original_count = len(selected)
+
         # Check 2: AOI coverage per scene (drop genuine gaps)
         selected, cov_issues = self._check_coverage(selected)
         issues.extend(cov_issues)
@@ -180,7 +208,6 @@ class PreflightGate:
         issues.extend(self._check_temporal_network(selected))
 
         # Check 4: burst-timing family proxy screen
-
         geometry_report = search_report.get("geometry_report", {})
         selected, burst_issues = self._screen_burst_families(selected, geometry_report)
         issues.extend(burst_issues)
@@ -195,6 +222,7 @@ class PreflightGate:
         report = PreflightReport(
             go=go, severity=severity, issues=issues,
             selected=selected, manifest=manifest,
+            original_count=original_count,
         )
         logger.info("\n%s", report.summary())
         return report
@@ -294,7 +322,6 @@ class PreflightGate:
         candidate_pairs = generate_candidate_pairs(
             dates, max_temporal_baseline_days=self.max_temporal_baseline_days,
         )
-
         adjacency: Dict[str, set] = {d: set() for d in dates}
         for d1, d2 in candidate_pairs:
             adjacency[d1].add(d2)
@@ -309,8 +336,8 @@ class PreflightGate:
             for nb in adjacency[d] - visited:
                 visited.add(nb)
                 stack.append(nb)
-        unconnected = set(dates) - visited
 
+        unconnected = set(dates) - visited
         issues = []
         if unconnected:
             issues.append(PreflightIssue(
@@ -351,7 +378,6 @@ class PreflightGate:
         full products), falling back to an honest "unassessed" advisory
         only if that isn't available or doesn't succeed. Never silently
         claims risk is absent just because it couldn't be checked.
-
         REAL BUG FIXED: earlier versions returned only `issues`, never
         `selected` -- so a successful real detection's own
         "BURST_FAMILY_DETECTED" issue was marked auto_fixed=True with a
@@ -366,7 +392,6 @@ class PreflightGate:
         report claimed the exclusion had already happened. Now returns
         the real, actually-filtered selection, matching the pattern
         _check_coverage() already used correctly.
-
         HISTORY, kept because it explains why this function is careful
         about false passes: an earlier version grouped scenes by
         (Track, Satellite) and treated agreement within a group as
@@ -381,7 +406,6 @@ class PreflightGate:
         check needs to catch. A second, independent bug in that version
         also made the (Track, Satellite) grouping non-functional in
         practice (wrong dict keys against the real scene object).
-
         What this function guarantees regardless of which path fires:
         every selected scene really is on a single, consistent track
         (already enforced by select_consistent_geometry(); re-checked
@@ -401,7 +425,6 @@ class PreflightGate:
             tracks.add(track)
 
         issues: List[PreflightIssue] = []
-
         if len(tracks) > 1:
             # Should be unreachable if select_consistent_geometry() already
             # ran correctly -- a real defensive check, not the expected path.
@@ -416,7 +439,6 @@ class PreflightGate:
             ))
 
         satellites_present = geometry_report.get("satellites", set())
-
         real_result = self._try_real_burst_family_check(selected) if self.attempt_real_burst_check else None
 
         nodes_version = "unknown"
@@ -496,6 +518,7 @@ class PreflightGate:
                 f"specific pairs to correlate poorly too."
                 if internal_bridges else ""
             )
+
             issues.append(PreflightIssue(
                 code="BURST_FAMILY_DETECTED",
                 severity=SEVERITY_GREEN if resolved else SEVERITY_YELLOW,
@@ -531,6 +554,7 @@ class PreflightGate:
                     f"its own (see message). Full stack kept: {chosen_dates}."
                 ),
             ))
+
             # ACTUALLY apply the recommendation -- not just report it.
             chosen_set = set(chosen_dates)
             filtered_selected = [s for s in selected if str(s.datetime)[:10] in chosen_set]
@@ -561,7 +585,6 @@ class PreflightGate:
                 "absent."
             ),
         ))
-
         return selected, issues
 
     def _try_real_burst_family_check(
@@ -569,7 +592,6 @@ class PreflightGate:
     ) -> Optional[Tuple[List[str], Dict[str, Any]]]:
         """
         Best-effort REAL pre-download burst-family classification.
-
         Uses providers.copernicus_nodes to fetch only each candidate
         date's lightweight annotation XML (not the full, multi-GB
         product) plus its real orbit file, then runs the SAME, already-
@@ -580,7 +602,6 @@ class PreflightGate:
         parse_slc_geometry() read only the annotation XML either way,
         confirmed directly with an end-to-end test where the real,
         unmodified parser reads a mini-zip built this way correctly.
-
         Returns None -- never raises -- if anything real goes wrong:
         missing "copernicus" credentials, a network failure, an
         unexpected real API response shape, too few dates with both
@@ -589,12 +610,14 @@ class PreflightGate:
         advisory," never "risk confirmed absent."
         """
         import tempfile
-
+        import shutil
+        import importlib
         try:
-            from pygeofetch.providers.copernicus_nodes import fetch_annotation_zip
-            from pygeofetch.core.orbits import fetch_orbit_file
-            from pygeofetch.insar.stack_selection import select_burst_synchronized_dates
-            from pygeofetch.insar.geolocation import geodetic_to_ecef
+            for _mod_name in (
+                "pygeofetch.providers.copernicus_nodes", "pygeofetch.core.orbits",
+                "pygeofetch.insar.stack_selection", "pygeofetch.insar.geolocation",
+            ):
+                importlib.import_module(_mod_name)
         except ImportError as exc:
             logger.info("Real pre-download burst check unavailable (%s).", exc)
             return None
@@ -605,6 +628,42 @@ class PreflightGate:
             logger.info("Real pre-download burst check: couldn't create a scratch dir (%s).", exc)
             return None
 
+        # REAL BUG FOUND AND FIXED: work_dir was never removed on any exit
+        # path -- not on success, not on the early "too few usable dates"
+        # return, not on the exception fallback. Every real call to this
+        # method (i.e. every real preflight run with attempt_real_burst_
+        # check=True, which is the default) left behind a full scratch
+        # directory of real annotation mini-zips and real, full orbit
+        # files (~4MB+ each) that was never cleaned up. Re-running the
+        # same preflight cell repeatedly while iterating on a notebook --
+        # completely normal, everyday usage -- accumulates one orphaned
+        # directory per run, unbounded, on whatever drive the OS temp
+        # folder lives on (on Windows, typically the same small system
+        # drive as everything else). A real, concrete, plausible path to
+        # exhausting that drive, which is a well-known way to make a
+        # Jupyter kernel become unresponsive or fail to save cleanly --
+        # matching a real report of a notebook going inactive with blank
+        # cell outputs immediately after a preflight run. The real body
+        # of this method is now factored into _run_real_burst_family_check
+        # below, wrapped here so work_dir is removed on every real exit
+        # path, success or failure, not just the ones tested before.
+        try:
+            return self._run_real_burst_family_check(selected, work_dir)
+        finally:
+            shutil.rmtree(work_dir, ignore_errors=True)
+
+    def _run_real_burst_family_check(self, selected: List[Any], work_dir: Path):
+        """
+        The real body of _try_real_burst_family_check(), factored out so
+        that method's own try/finally can guarantee work_dir cleanup on
+        every real exit path here -- including the early returns --
+        without duplicating the rmtree call at each one.
+        """
+        from pygeofetch.providers.copernicus_nodes import fetch_annotation_zip
+        from pygeofetch.core.orbits import fetch_orbit_file
+        from pygeofetch.insar.stack_selection import select_burst_synchronized_dates
+        from pygeofetch.insar.geolocation import geodetic_to_ecef
+
         safe_zips: Dict[str, Any] = {}
         orbit_files: Dict[str, Any] = {}
 
@@ -615,16 +674,40 @@ class PreflightGate:
             except Exception as exc:
                 logger.info("Real pre-download burst check: no annotation for %s (%s).", date, exc)
                 continue
+
             try:
                 name = s.properties.get("name") if hasattr(s, "properties") else None
-                orbit_file = fetch_orbit_file(
-                    product_name=name, output_dir=str(work_dir), orbit_type="precise",
-                ) if name else None
+                if not name:
+                    continue
+
+                # ── FIX: ORBIT CASCADING ──
+                # Previously, this only tried "precise". If precise wasn't 
+                # available (e.g., recent acquisitions), the date was dropped.
+                # Now it cascades: Precise -> Restituted -> Predicted.
+                orbit_file = None
+                for orbit_type in ["precise", "restituted", "predicted"]:
+                    try:
+                        orbit_file = fetch_orbit_file(
+                            product_name=name, output_dir=str(work_dir), orbit_type=orbit_type,
+                        )
+                        if orbit_file is not None:
+                            if orbit_type != "precise":
+                                logger.warning(
+                                    "Orbit cascading: fell back to '%s' orbit for %s "
+                                    "(precise not available).", orbit_type, date
+                                )
+                            break
+                    except Exception as exc:
+                        logger.debug("Orbit cascade: '%s' failed for %s (%s).", orbit_type, date, exc)
+                        continue
+
                 if orbit_file is None:
+                    logger.info("Real pre-download burst check: no orbit file (any type) for %s.", date)
                     continue
+                    
                 orbit_files[date] = orbit_file
             except Exception as exc:
-                logger.info("Real pre-download burst check: no orbit file for %s (%s).", date, exc)
+                logger.info("Real pre-download burst check: orbit cascade failed for %s (%s).", date, exc)
                 continue
 
         usable_dates = sorted(set(safe_zips) & set(orbit_files))
@@ -640,7 +723,6 @@ class PreflightGate:
             aoi_center_lat = (self.aoi_bbox.min_lat + self.aoi_bbox.max_lat) / 2
             aoi_center_lon = (self.aoi_bbox.min_lon + self.aoi_bbox.max_lon) / 2
             ground_point = geodetic_to_ecef(aoi_center_lat, aoi_center_lon, 0.0)
-
             chosen_dates, family_report = select_burst_synchronized_dates(
                 usable_dates, safe_zips, orbit_files, ground_point,
                 min_majority_dates=self.min_majority_family_dates,
@@ -660,6 +742,22 @@ class PreflightGate:
         self, selected: List[Any], search_report: Dict[str, Any],
         issues: List[PreflightIssue],
     ) -> Dict[str, Any]:
+        # ── FIX: BANDWIDTH & DOWNLOAD MANIFEST ──
+        # Calculate estimated bandwidth and build a concrete manifest of 
+        # what will actually be downloaded, preventing surprise disk fills.
+        ESTIMATED_GB_PER_SLC_SCENE = 7.5  # Sentinel-1 IW SLC average size
+        estimated_bandwidth_gb = len(selected) * ESTIMATED_GB_PER_SLC_SCENE
+
+        download_manifest = []
+        for s in selected:
+            props = s.properties if hasattr(s, "properties") else {}
+            download_manifest.append({
+                "date": str(s.datetime)[:10],
+                "scene_id": props.get("name"),
+                "satellite": props.get("platform"),
+                "polarisation": props.get("polarisation"),
+            })
+
         return {
             "search": {
                 "start_date": self.start_date,
@@ -681,6 +779,11 @@ class PreflightGate:
                     search_report.get("geometry_report", {}).get("satellites", set())
                 ),
             },
+            # NEW: Bandwidth & Manifest section
+            "bandwidth_and_manifest": {
+                "estimated_bandwidth_gb": round(estimated_bandwidth_gb, 2),
+                "download_manifest": download_manifest,
+            },
             "preflight": {
                 "severity": self._overall_severity(issues),
                 "issues": [

{pygeofetch-2.4.0 → pygeofetch-2.6.0}/pygeofetch/meta.yaml

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

{pygeofetch-2.4.0 → pygeofetch-2.6.0/pygeofetch.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pygeofetch
-Version: 2.4.0
+Version: 2.6.0
 Summary: Universal satellite data pipeline + geospatial processing platform
 Author-email: Samuel Appiah Kubi <appiahkubis14@gmail.com>
 License: MIT License
@@ -97,7 +97,7 @@ Requires-Dist: geemap>=0.28.0; extra == "viz"
 Requires-Dist: osmnx>=1.9.4; extra == "viz"
 Requires-Dist: contextily>=1.9.4; extra == "viz"
 Requires-Dist: xyzservices>=2023.10.0; extra == "viz"
-Requires-Dist: mapclassify>=2.5.0; extra == "viz"
+Requires-Dist: mapclassify>=2.6.0; extra == "viz"
 Requires-Dist: geoplot>=0.5.0; extra == "viz"
 Requires-Dist: mplleaflet>=0.0.5; extra == "viz"
 Requires-Dist: branca>=0.6.0; extra == "viz"

{pygeofetch-2.4.0 → pygeofetch-2.6.0}/pygeofetch.egg-info/requires.txt

@@ -91,7 +91,7 @@ geemap>=0.28.0
 osmnx>=1.9.4
 contextily>=1.9.4
 xyzservices>=2023.10.0
-mapclassify>=2.5.0
+mapclassify>=2.6.0
 geoplot>=0.5.0
 mplleaflet>=0.0.5
 branca>=0.6.0

{pygeofetch-2.4.0 → pygeofetch-2.6.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "pygeofetch"
-version = "2.4.0"
+version = "2.6.0"
 description = "Universal satellite data pipeline + geospatial processing platform"
 readme = "README.md"
 license = { file = "LICENSE" }
@@ -100,7 +100,7 @@ viz = [
     "osmnx>=1.9.4",
     "contextily>=1.9.4",
     "xyzservices>=2023.10.0",
-    "mapclassify>=2.5.0",
+    "mapclassify>=2.6.0",
     "geoplot>=0.5.0",
     "mplleaflet>=0.0.5",
     "branca>=0.6.0",