pygeofetch 2.6.2.2__tar.gz → 2.6.2.4__tar.gz

{pygeofetch-2.6.2.2 → pygeofetch-2.6.2.4}/CHANGELOG.md

@@ -20,7 +20,7 @@ date, and marked accordingly rather than filled in with invented
 bullet points.
 ```
 
-## [Unreleased] — v2.6.2.1
+## [Unreleased] — v2.6.2.4.4
 
 ```{note}
 Not yet published to PyPI. This entry documents work completed and
@@ -130,7 +130,7 @@ audit and remain open for a follow-up pass.
 
 ---
 
-## [2.6.2.2] — 2026-08-25 (latest)
+## [2.6.2.4.4] — 2026-08-25 (latest)
 
 Confirmed via direct fetch of the current PyPI listing.
 
@@ -149,7 +149,7 @@ Confirmed via direct fetch of the current PyPI listing.
 - `SearchQuery.sort_ascending: bool` — earlier examples showed a `sort_order: "asc"/"desc"` string field that doesn't exist on the model (the CLI's `--sort-order` flag does convert to this internally, so CLI docs were unaffected)
 - `DownloadOptions.post_process` requires a list of `PostProcessAction` objects — passing plain strings raises a real `pydantic.ValidationError`
 
-## [2.6.2] — 2026-08-24
+## [2.6.2.4] — 2026-08-24
 Real, verified release. Detailed notes not independently recovered from PyPI's release-history page (no distinct per-version notes exposed for this release specifically).
 
 ## [2.6.1] — 2026-08-22
@@ -261,9 +261,9 @@ recovered.
 
 ```{note}
 The previous version of this changelog had an entry labeled
-**"2.6.2.2 — 2026-07-12"** describing 22+ providers, Sentinel-1C/1D
+**"2.6.2.4.4 — 2026-07-12"** describing 22+ providers, Sentinel-1C/1D
 support, SLC search with provider routing, precise orbit file
-management, 17 spectral indices, and various bug fixes. **2.6.2.2 was
+management, 17 spectral indices, and various bug fixes. **2.6.2.4.4 was
 only ever released once, on 2026-08-25** — it was never released on
 2026-07-12. The date matches this real release, **1.0.8**, exactly.
 That content is reproduced below under the version it actually
@@ -406,8 +406,8 @@ The version of this file uploaded for this update had **5 entries
 covering 5 dates**. PyPI's real release history has **54 releases**.
 Specific issues found and fixed:
 
-1. **Two different entries were both labeled `2.6.2.2`**, dated
-   2026-07-29 and 2026-07-12. **2.6.2.2 was only ever released once**,
+1. **Two different entries were both labeled `2.6.2.4.4`**, dated
+   2026-07-29 and 2026-07-12. **2.6.2.4.4 was only ever released once**,
    on 2026-08-25 (confirmed directly from the live PyPI listing).
 2. **The 2026-07-12 entry's date exactly matches a real release**
    — version **1.0.8** — and its content (22+ providers, Sentinel-1C/D,

{pygeofetch-2.6.2.2/pygeofetch.egg-info → pygeofetch-2.6.2.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pygeofetch
-Version: 2.6.2.2
+Version: 2.6.2.4
 Summary: Universal satellite data pipeline + geospatial processing platform
 Author-email: Samuel Appiah Kubi <appiahkubis14@gmail.com>
 License: MIT License
@@ -26,7 +26,7 @@ License: MIT License
         SOFTWARE.
         
 Project-URL: Homepage, https://www.eocoreint.com/
-Project-URL: Documentation, https://pygeofetch.readthedocs.io/en/latest/
+Project-URL: Documentation, https://appiahkubis14.github.io/pygeofetch-docs/
 Project-URL: Repository, https://github.com/EOCoreINT/pygeofetch
 Project-URL: Bug Tracker, https://github.com/EOCoreINT/pygeofetch/issues
 Keywords: satellite,remote-sensing,GIS,earth-observation,geospatial,SAR,Sentinel,Landsat
@@ -153,9 +153,9 @@ Dynamic: license-file
 
 [Quick Start](#-quick-start) · [Mexico City Case Study](#-case-study-mapping-mexico-city-land-subsidence-with-insar) · [Case Study Repo ↗](https://github.com/EOCoreINT/mexico-subsidence-project) · [Documentation](https://pygeofetch.readthedocs.io/en/latest/) · [Notebooks](#-notebooks)
 
-<br>
-<img src="icon/concept_a.png" alt="PyGeoFetch Logo" width="350">
-<br>
+<!-- <br>
+<img src="https://raw.githubusercontent.com/EOCoreINT/pygeofetch/refs/heads/main/icon/concept_a.png" alt="PyGeoFetch Logo" width="350">
+<br> -->
 
 </div>
 
@@ -386,7 +386,7 @@ If you use PyGeoFetch in your research or operational work, please cite it using
   title        = {PyGeoFetch: A Unified Python Framework for Multi-Provider Satellite Data Acquisition, Pre-download Quality Control, and Geospatial Processing},
   year         = {2026},
   publisher    = {Zenodo},
-  version      = {2.6.2.2},
+  version      = {2.6.2.4.1},
   doi          = {10.5281/zenodo.22087230},
   url          = {https://doi.org/10.5281/zenodo.22087230}
 }

{pygeofetch-2.6.2.2 → pygeofetch-2.6.2.4}/README.md

@@ -11,9 +11,9 @@
 
 [Quick Start](#-quick-start) · [Mexico City Case Study](#-case-study-mapping-mexico-city-land-subsidence-with-insar) · [Case Study Repo ↗](https://github.com/EOCoreINT/mexico-subsidence-project) · [Documentation](https://pygeofetch.readthedocs.io/en/latest/) · [Notebooks](#-notebooks)
 
-<br>
-<img src="icon/concept_a.png" alt="PyGeoFetch Logo" width="350">
-<br>
+<!-- <br>
+<img src="https://raw.githubusercontent.com/EOCoreINT/pygeofetch/refs/heads/main/icon/concept_a.png" alt="PyGeoFetch Logo" width="350">
+<br> -->
 
 </div>
 
@@ -244,7 +244,7 @@ If you use PyGeoFetch in your research or operational work, please cite it using
   title        = {PyGeoFetch: A Unified Python Framework for Multi-Provider Satellite Data Acquisition, Pre-download Quality Control, and Geospatial Processing},
   year         = {2026},
   publisher    = {Zenodo},
-  version      = {2.6.2.2},
+  version      = {2.6.2.4.1},
   doi          = {10.5281/zenodo.22087230},
   url          = {https://doi.org/10.5281/zenodo.22087230}
 }

{pygeofetch-2.6.2.2 → pygeofetch-2.6.2.4}/pygeofetch/__init__.py

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

{pygeofetch-2.6.2.2 → pygeofetch-2.6.2.4}/pygeofetch/cli/main.py

@@ -26,6 +26,7 @@ from pygeofetch.cli.auth_commands import auth
 from pygeofetch.cli.config_commands import config
 from pygeofetch.cli.download_commands import download
 from pygeofetch.cli.index_commands import index
+from pygeofetch.cli.optical_commands import optical
 from pygeofetch.cli.pipeline_process_commands import proc_pipeline
 from pygeofetch.cli.postprocess_commands import post
 from pygeofetch.cli.preprocess_commands import preprocess
@@ -103,6 +104,7 @@ cli.add_command(index)
 cli.add_command(post)
 cli.add_command(sar)
 cli.add_command(proc_pipeline)
+cli.add_command(optical)
 
 
 # ---------------------------------------------------------------------------
@@ -919,4 +921,4 @@ def main() -> None:
 
 
 if __name__ == "__main__":
-    main()
+    main()

pygeofetch-2.6.2.4/pygeofetch/cli/optical_commands.py

@@ -0,0 +1,105 @@
+"""CLI commands for optical pixel offset tracking (POT)."""
+
+from __future__ import annotations
+
+import sys
+
+import click
+from rich.console import Console
+
+console = Console()
+
+
+@click.group()
+def optical() -> None:
+    """Optical pixel offset tracking — measures large 2D ground
+    displacement via image correlation, complementing InSAR for
+    motion that exceeds phase InSAR's coherence limit."""
+
+
+@optical.command("offset-track")
+@click.option("--ref", "reference_path", required=True, type=click.Path(exists=True), help="Reference-date raster.")
+@click.option("--sec", "secondary_path", required=True, type=click.Path(exists=True), help="Secondary-date raster.")
+@click.option("--output", "-o", required=True, type=click.Path(), help="Output GeoTIFF (dx/dy/snr, 3 bands).")
+@click.option("--band", default=1, show_default=True, type=int, help="1-based band index to correlate.")
+@click.option("--window-size", default=64, show_default=True, type=int, help="Search window size, pixels.")
+@click.option("--step-size", default=16, show_default=True, type=int, help="Spacing between window centers, pixels.")
+@click.option("--chip-size", default=None, type=int, help="Reference template size, pixels. Default: window-size // 2.")
+@click.option("--snr-threshold", default=3.0, show_default=True, type=float, help="Minimum SNR to mark a window reliable.")
+@click.option("--cloud-mask", default=None, type=click.Path(exists=True), help="Real Sentinel-2 SCL raster, already aligned to --ref.")
+@click.option("--water-mask-threshold", default=None, type=float, help="Mask pixels where NDWI exceeds this value (needs --green-band/--nir-band).")
+@click.option("--green-band", default=None, type=int, help="1-based green band index, for --water-mask-threshold.")
+@click.option("--nir-band", default=None, type=int, help="1-based NIR band index, for --water-mask-threshold.")
+def offset_track_cmd(
+    reference_path,
+    secondary_path,
+    output,
+    band,
+    window_size,
+    step_size,
+    chip_size,
+    snr_threshold,
+    cloud_mask,
+    water_mask_threshold,
+    green_band,
+    nir_band,
+):
+    """
+    Measure 2D ground displacement between two optical scenes via
+    image correlation.
+
+    \b
+    Examples:
+      # Basic: two co-registered scenes, real cloud masking via SCL
+      pygeofetch optical offset-track \\
+          --ref before.tif --sec after.tif \\
+          --cloud-mask before_SCL.tif \\
+          --output displacement.tif
+
+      # Mining-scale displacement, larger search window
+      pygeofetch optical offset-track \\
+          --ref jan.tif --sec jun.tif \\
+          --window-size 96 --step-size 24 \\
+          --output mine_displacement.tif
+    """
+    from pygeofetch.optical.offset_tracking import compute_pixel_offsets, prepare_optical_pair
+
+    try:
+        ref_arr, sec_arr, ref_profile = prepare_optical_pair(
+            reference_path,
+            secondary_path,
+            band_index=band,
+            cloud_mask_path=cloud_mask,
+            water_mask_threshold=water_mask_threshold,
+            green_band_index=green_band,
+            nir_band_index=nir_band,
+        )
+    except ValueError as exc:
+        console.print(f"[red]✗[/] {exc}")
+        sys.exit(1)
+
+    pixel_size_m = abs(ref_profile["transform"].a)
+    result = compute_pixel_offsets(
+        ref_arr,
+        sec_arr,
+        pixel_size_m=pixel_size_m,
+        window_size=window_size,
+        step_size=step_size,
+        chip_size=chip_size,
+        snr_threshold=snr_threshold,
+    )
+
+    out_transform = ref_profile["transform"] * ref_profile["transform"].scale(step_size, step_size)
+    out_profile = dict(ref_profile)
+    out_profile.update(
+        height=result.dx.shape[0],
+        width=result.dx.shape[1],
+        transform=out_transform,
+    )
+    written = result.export_geotiff(output, out_profile)
+
+    n_reliable = int(result.reliable.sum())
+    n_total = int(result.reliable.size)
+    console.print(f"[green]✓[/] offset-track → {written}")
+    console.print(f"  {n_reliable}/{n_total} windows reliable ({100 * n_reliable / n_total:.1f}%)")
+    console.print(f"  window={window_size}px  step={step_size}px  pixel_size={pixel_size_m:.2f}m")

{pygeofetch-2.6.2.2 → pygeofetch-2.6.2.4}/pygeofetch/cli/search_commands.py

@@ -282,6 +282,7 @@ def search_run(
 
     sb = PyGeoFetch()
 
+    optical_config = None
     if validate_optical and (
         optical_max_cloud_cover,
         optical_min_coverage,
@@ -298,22 +299,48 @@ def search_run(
             overrides["required_bands"] = [
                 b.strip() for b in optical_required_bands.split(",")
             ]
-        sb.optical_validation_config = OpticalValidationConfig(**overrides)
+        optical_config = OpticalValidationConfig(**overrides)
+        sb.optical_validation_config = optical_config
 
     with console.status(
         f"[cyan]Searching {len(provider_list or [])} provider(s)...[/]"
     ):
-        results = sb.search(
-            query,
-            providers=provider_list,
-            use_cache=not no_cache,
-            validate_optical=validate_optical,
-        )
+        if validate_optical:
+            # Real, deliberate choice: search WITHOUT filtering here, then
+            # validate directly in this CLI layer, rather than calling
+            # search(validate_optical=True) and losing visibility into
+            # what got rejected and why. sb.search()'s own contract
+            # (returns only the passed scenes) is left untouched for
+            # every other caller -- this is a CLI-only reporting path,
+            # not a change to the library's real filtering behavior.
+            raw_results = sb.search(
+                query,
+                providers=provider_list,
+                use_cache=not no_cache,
+                validate_optical=False,
+            )
+            results, validation_summary = _validate_and_summarize(
+                sb, raw_results, query, optical_config
+            )
+        else:
+            results = sb.search(
+                query,
+                providers=provider_list,
+                use_cache=not no_cache,
+                validate_optical=False,
+            )
+            validation_summary = None
 
     if not results:
         console.print("[yellow]No results found.[/]")
         return
 
+    # Real, clean validation info + full results table, organized so the
+    # summary always appears before the detailed table -- not interleaved
+    # with save/format output below.
+    if validation_summary is not None:
+        _display_validation_summary(validation_summary)
+
     # Save if requested
     if output:
         out_path = Path(output)
@@ -365,6 +392,92 @@ def search_run(
             click.echo(r.id)
 
 
+def _validate_and_summarize(sb, raw_results, query, optical_config):
+    """
+    Real validation pass over every raw candidate, returning both the
+    scenes that actually pass and a real, structured summary of what got
+    rejected and why -- the information sb.search(validate_optical=True)
+    alone discards once it returns only the filtered list.
+    """
+    from collections import Counter
+
+    from pygeofetch.validation import OpticalPreflightValidator, OpticalValidationConfig
+
+    validator = OpticalPreflightValidator(optical_config or OpticalValidationConfig())
+    aoi = sb._derive_aoi_polygon(query)
+
+    passed_results = []
+    rejection_reasons: Counter = Counter()
+    warning_reasons: Counter = Counter()
+    n_warned_but_passed = 0
+
+    for scene in raw_results:
+        report = validator.validate_scene(scene, aoi, query.start_date, query.end_date)
+        if report.passed:
+            passed_results.append(scene)
+            if report.issues:
+                n_warned_but_passed += 1
+                for issue in report.issues:
+                    warning_reasons[issue.code] += 1
+        else:
+            for issue in report.issues:
+                if issue.severity == "ERROR":
+                    rejection_reasons[issue.code] += 1
+
+    summary = {
+        "n_total": len(raw_results),
+        "n_passed": len(passed_results),
+        "n_rejected": len(raw_results) - len(passed_results),
+        "n_warned_but_passed": n_warned_but_passed,
+        "rejection_reasons": rejection_reasons,
+        "warning_reasons": warning_reasons,
+    }
+    return passed_results, summary
+
+
+def _display_validation_summary(summary: dict) -> None:
+    """Clean, real info block summarizing optical validation -- shown
+    before the detailed results table, not interleaved with it."""
+    n_total = summary["n_total"]
+    n_passed = summary["n_passed"]
+    n_rejected = summary["n_rejected"]
+    pct = (100 * n_passed / n_total) if n_total else 0.0
+
+    console.print(
+        f"\n[bold]Optical validation:[/] {n_passed}/{n_total} scenes passed "
+        f"({pct:.0f}%)"
+        + (f", [yellow]{n_rejected} rejected[/]" if n_rejected else "")
+        + (
+            f", [cyan]{summary['n_warned_but_passed']} passed with warnings[/]"
+            if summary["n_warned_but_passed"]
+            else ""
+        )
+    )
+
+    if summary["rejection_reasons"]:
+        reasons_table = Table(
+            title="Rejection reasons", header_style="bold red", show_lines=False
+        )
+        reasons_table.add_column("Code", style="red")
+        reasons_table.add_column("Count", justify="right")
+        for code, count in summary["rejection_reasons"].most_common():
+            reasons_table.add_row(code, str(count))
+        console.print(reasons_table)
+
+    if summary["warning_reasons"]:
+        warn_table = Table(
+            title="Warnings on passed scenes",
+            header_style="bold yellow",
+            show_lines=False,
+        )
+        warn_table.add_column("Code", style="yellow")
+        warn_table.add_column("Count", justify="right")
+        for code, count in summary["warning_reasons"].most_common():
+            warn_table.add_row(code, str(count))
+        console.print(warn_table)
+    console.print()  # real spacing before the full results table below
+
+
 def _display_table(results) -> None:
     table = Table(title=f"{len(results)} Results", header_style="bold blue")
     table.add_column("ID", style="cyan", max_width=30)
@@ -441,4 +554,4 @@ def _save_csv(results, path: Path) -> None:
         )
         writer.writeheader()
         for r in results:
-            writer.writerow(_item_to_dict(r))
+            writer.writerow(_item_to_dict(r))