PyGeoFetch 2.6.2.3__py3-none-any.whl → 2.6.2.5__py3-none-any.whl

pygeofetch/__init__.py

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

pygeofetch/cli/main.py

@@ -26,6 +26,8 @@ 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.multisensor_commands import multisensor
+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 +105,8 @@ cli.add_command(index)
 cli.add_command(post)
 cli.add_command(sar)
 cli.add_command(proc_pipeline)
+cli.add_command(optical)
+cli.add_command(multisensor)
 
 
 # ---------------------------------------------------------------------------

pygeofetch/cli/multisensor_commands.py

@@ -0,0 +1,243 @@
+"""CLI access to pygeofetch's 5 real multi-sensor pipelines."""
+
+from __future__ import annotations
+
+import json
+
+import click
+
+
+@click.group()
+def multisensor() -> None:
+    """Multi-sensor fusion pipelines: InSAR+optical, SAR+optical flood
+    mapping, terrain-corrected change, DEM differencing, vegetation
+    disturbance. See docs/processing/multi-sensor-pipelines.md."""
+
+
+def _print_result(result) -> None:
+    if result.success:
+        click.echo(f"✓ Success -> {result.final_output}")
+        if result.metadata:
+            click.echo(
+                json.dumps(
+                    {k: str(v) for k, v in result.metadata.items()},
+                    indent=2,
+                )
+            )
+    else:
+        click.echo(f"✗ Failed: {result.error}", err=True)
+        raise SystemExit(1)
+
+
+@multisensor.command("insar-optical-fusion")
+@click.option("--insar-velocity", required=True, type=click.Path(exists=True))
+@click.option("--insar-coherence", required=True, type=click.Path(exists=True))
+@click.option("--optical-ref", required=True, type=click.Path(exists=True))
+@click.option("--optical-sec", required=True, type=click.Path(exists=True))
+@click.option("--output-dir", required=True, type=click.Path())
+@click.option("--window-size", default=64, show_default=True, type=int)
+@click.option("--step-size", default=16, show_default=True, type=int)
+@click.option("--snr-threshold", default=3.0, show_default=True, type=float)
+@click.option("--coherence-low", default=0.4, show_default=True, type=float)
+@click.option("--coherence-high", default=0.6, show_default=True, type=float)
+@click.option("--cloud-mask", default=None, type=click.Path(exists=True))
+def insar_optical_fusion_cmd(
+    insar_velocity,
+    insar_coherence,
+    optical_ref,
+    optical_sec,
+    output_dir,
+    window_size,
+    step_size,
+    snr_threshold,
+    coherence_low,
+    coherence_high,
+    cloud_mask,
+):
+    """Fuse InSAR displacement with optical pixel offset tracking."""
+    from pygeofetch.multisensor import insar_optical_displacement_pipeline
+
+    result = insar_optical_displacement_pipeline(
+        insar_velocity,
+        insar_coherence,
+        optical_ref,
+        optical_sec,
+        output_dir,
+        cloud_mask_path=cloud_mask,
+        window_size=window_size,
+        step_size=step_size,
+        snr_threshold=snr_threshold,
+        coherence_low=coherence_low,
+        coherence_high=coherence_high,
+    )
+    _print_result(result)
+
+
+@multisensor.command("flood-map")
+@click.option("--sar", "sar_input", required=True, type=click.Path(exists=True))
+@click.option("--optical-green", required=True, type=click.Path(exists=True))
+@click.option("--optical-nir", required=True, type=click.Path(exists=True))
+@click.option("--output-dir", required=True, type=click.Path())
+@click.option("--sar-reference", default=None, type=click.Path(exists=True))
+@click.option("--sar-threshold", default=-15.0, show_default=True, type=float)
+@click.option("--ndwi-threshold", default=0.0, show_default=True, type=float)
+@click.option("--cloud-mask", default=None, type=click.Path(exists=True))
+@click.option(
+    "--fusion-mode",
+    default="cloud_aware",
+    show_default=True,
+    type=click.Choice(["cloud_aware", "union", "intersection"]),
+)
+def flood_map_cmd(
+    sar_input,
+    optical_green,
+    optical_nir,
+    output_dir,
+    sar_reference,
+    sar_threshold,
+    ndwi_threshold,
+    cloud_mask,
+    fusion_mode,
+):
+    """Fuse SAR and optical NDWI for flood/water extent mapping."""
+    from pygeofetch.multisensor import multi_sensor_flood_pipeline
+    from pygeofetch.sar import SARProcessor
+
+    result = multi_sensor_flood_pipeline(
+        SARProcessor(),
+        sar_input,
+        optical_green,
+        optical_nir,
+        output_dir,
+        sar_reference_path=sar_reference,
+        sar_threshold=sar_threshold,
+        optical_ndwi_threshold=ndwi_threshold,
+        cloud_mask_path=cloud_mask,
+        fusion_mode=fusion_mode,
+    )
+    _print_result(result)
+
+
+@multisensor.command("terrain-change")
+@click.option("--pre", "pre_path", required=True, type=click.Path(exists=True))
+@click.option("--post", "post_path", required=True, type=click.Path(exists=True))
+@click.option("--dem", "dem_path", required=True, type=click.Path(exists=True))
+@click.option(
+    "--pre-datetime",
+    required=True,
+    help="Real UTC ISO datetime, e.g. 2024-01-15T10:30:00",
+)
+@click.option("--post-datetime", required=True, help="Real UTC ISO datetime")
+@click.option("--lat", "latitude", required=True, type=float)
+@click.option("--lon", "longitude", required=True, type=float)
+@click.option("--output-dir", required=True, type=click.Path())
+@click.option("--change-threshold", default=0.1, show_default=True, type=float)
+def terrain_change_cmd(
+    pre_path,
+    post_path,
+    dem_path,
+    pre_datetime,
+    post_datetime,
+    latitude,
+    longitude,
+    output_dir,
+    change_threshold,
+):
+    """Terrain-corrected optical change detection (removes real
+    illumination artifacts using each date's own solar position)."""
+    from datetime import datetime, timezone
+
+    from pygeofetch.multisensor import terrain_corrected_change_pipeline
+
+    def _parse(dt_str):
+        dt = datetime.fromisoformat(dt_str)
+        return dt if dt.tzinfo else dt.replace(tzinfo=timezone.utc)
+
+    result = terrain_corrected_change_pipeline(
+        pre_path,
+        post_path,
+        dem_path,
+        _parse(pre_datetime),
+        _parse(post_datetime),
+        latitude,
+        longitude,
+        output_dir,
+        change_threshold=change_threshold,
+    )
+    _print_result(result)
+
+
+@multisensor.command("dem-diff")
+@click.option("--dem-old", required=True, type=click.Path(exists=True))
+@click.option("--dem-new", required=True, type=click.Path(exists=True))
+@click.option("--output-dir", required=True, type=click.Path())
+@click.option(
+    "--old-rmse",
+    default=1.0,
+    show_default=True,
+    type=float,
+    help="Real vertical RMSE of the old DEM, metres.",
+)
+@click.option(
+    "--new-rmse",
+    default=1.0,
+    show_default=True,
+    type=float,
+    help="Real vertical RMSE of the new DEM, metres.",
+)
+@click.option("--confidence-t", default=1.96, show_default=True, type=float)
+def dem_diff_cmd(dem_old, dem_new, output_dir, old_rmse, new_rmse, confidence_t):
+    """DEM-of-Difference volumetric change analysis."""
+    from pygeofetch.multisensor import dem_differencing_pipeline
+
+    result = dem_differencing_pipeline(
+        dem_old,
+        dem_new,
+        output_dir,
+        dem_old_vertical_rmse_m=old_rmse,
+        dem_new_vertical_rmse_m=new_rmse,
+        confidence_t_value=confidence_t,
+    )
+    _print_result(result)
+
+
+@multisensor.command("vegetation-disturbance")
+@click.option("--red-pre", required=True, type=click.Path(exists=True))
+@click.option("--nir-pre", required=True, type=click.Path(exists=True))
+@click.option("--red-post", required=True, type=click.Path(exists=True))
+@click.option("--nir-post", required=True, type=click.Path(exists=True))
+@click.option("--slc-pre", required=True, type=click.Path(exists=True))
+@click.option("--slc-post", required=True, type=click.Path(exists=True))
+@click.option("--output-dir", required=True, type=click.Path())
+@click.option("--ndvi-drop-threshold", default=0.15, show_default=True, type=float)
+@click.option("--coherence-threshold", default=0.3, show_default=True, type=float)
+@click.option("--coherence-window", default=7, show_default=True, type=int)
+def vegetation_disturbance_cmd(
+    red_pre,
+    nir_pre,
+    red_post,
+    nir_post,
+    slc_pre,
+    slc_post,
+    output_dir,
+    ndvi_drop_threshold,
+    coherence_threshold,
+    coherence_window,
+):
+    """Classify visible canopy loss vs. real sub-canopy ground
+    disturbance, from optical NDVI + SAR coherence."""
+    from pygeofetch.multisensor import vegetation_disturbance_pipeline
+
+    result = vegetation_disturbance_pipeline(
+        red_pre,
+        nir_pre,
+        red_post,
+        nir_post,
+        slc_pre,
+        slc_post,
+        output_dir,
+        ndvi_drop_threshold=ndvi_drop_threshold,
+        coherence_threshold=coherence_threshold,
+        coherence_window=coherence_window,
+    )
+    _print_result(result)

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/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))