pygeofetch Documentation

# Username / password (USGS, NASA, Copernicus)
pygeofetch auth add usgs --username YOUR_USER --password YOUR_PASS
pygeofetch auth add copernicus --username email@example.com --password PASS
pygeofetch auth add nasa_earthdata --username USER --password PASS

# API key (Planet, OpenTopography, TerraBotics, Airbus)
pygeofetch auth add planet --api-key YOUR_API_KEY
pygeofetch auth add opentopography --api-key YOUR_KEY

# OAuth2 client credentials (Sentinel Hub)
pygeofetch auth add sentinel_hub --client-id YOUR_ID --client-secret YOUR_SECRET

# Interactive login — prompts for all fields
pygeofetch auth login copernicus

# List, test, remove
pygeofetch auth list
pygeofetch auth test usgs
pygeofetch auth remove planet --yes

# Export backup (WARNING: contains secrets — store securely)
pygeofetch auth export --output creds_backup.json

# Format: pygeofetch_{PROVIDER}_{FIELD}
export pygeofetch_USGS_USERNAME=myuser
export pygeofetch_USGS_PASSWORD=mypass
export pygeofetch_PLANET_API_KEY=PL-abc123
export pygeofetch_COPERNICUS_USERNAME=email@example.com
export pygeofetch_COPERNICUS_PASSWORD=pass
export pygeofetch_NASA_EARTHDATA_USERNAME=user
export pygeofetch_OPENTOPOGRAPHY_API_KEY=mykey
export pygeofetch_SENTINEL_HUB_CLIENT_ID=id
export pygeofetch_SENTINEL_HUB_CLIENT_SECRET=secret

# Global settings
export pygeofetch_LOG_LEVEL=DEBUG
export pygeofetch_DOWNLOAD__PARALLEL=8
export pygeofetch_CACHE__TTL_SECONDS=7200

# Basic — download 3 scenes from search results
pygeofetch download run \
  --from-search results.geojson \
  --output ./data/ \
  --parallel 2 \
  --max-items 3

# RGB bands only — ~150 MB vs 600 MB for full Sentinel-2 scene
pygeofetch download run \
  --from-search results.geojson \
  --output ./data/ \
  --bands "B02,B03,B04" \
  --max-items 5

# Full options — checksum, resume, bandwidth throttle, Slack notify
pygeofetch download run \
  --from-search results.geojson \
  --output ./data/ \
  --parallel 4 \
  --retry 5 \
  --verify-checksum \
  --resume \
  --bandwidth-limit 10MB \
  --priority high \
  --on-failure skip \
  --notify webhook:https://hooks.slack.com/services/YOUR/WEBHOOK

# Post-processing chain
pygeofetch download run \
  --from-search results.geojson \
  --output ./processed/ \
  --post-process "unzip,reproject:EPSG:4326,compress:lzw,cog"

# NDVI workflow — download Red + NIR, compute NDVI, export COG
pygeofetch download run \
  --from-search results.geojson \
  --bands "B04,B08" \
  --post-process "reproject:EPSG:4326,ndvi,cog" \
  --output ./ndvi/

from pygeofetch.insar import SLCExtractor, InterferogramGenerator, PhaseUnwrapper

extractor = SLCExtractor(polarisation="VV")
ref_tif, sec_tif = extractor.extract_pair(
    download_results[0], download_results[1], aoi=aoi, output_dir="./data",
)

gen = InterferogramGenerator()
result = gen.process_pair(ref_tif, sec_tif, dem="dem.tif")
print(f"Mean coherence: {result.coherence.mean():.3f}")

unwrapper = PhaseUnwrapper(cost_mode="defo")
unwrapped, conncomp = unwrapper.unwrap(result.interferogram, result.coherence)

orbit_path = client.fetch_orbit_file(
    product_name=scene.properties.get("name", scene.id),
    orbit_type="precise",
)

from pygeofetch.insar import DataValidator

result = DataValidator.validate_slc(slc_array, name="reference SLC")
result.raise_if_invalid()  # clear ValueError, not a downstream numerical artifact

gen = InterferogramGenerator(esd_enabled=True, use_gpu=False)
result = gen.process_pair(
    reference="slc_ref.tif", secondary="slc_sec.tif", dem="dem.tif",
    reference_safe_zip="ref.SAFE.zip", secondary_safe_zip="sec.SAFE.zip",
    reference_orbit_file=fetch_orbit_file("S1A_..._ref"),
    secondary_orbit_file=fetch_orbit_file("S1A_..._sec"),
)

from pygeofetch.insar import los_to_vertical_displacement

vertical_velocity = los_to_vertical_displacement(
    ts_result.velocity, incidence_angle_deg=39.0
)

result.save("./output", auto_visualize=True)
# wrapped_phase.png, coherence.png, amplitude.png — alongside the GeoTIFFs

gen = InterferogramGenerator(use_gpu=True)   # auto-detects; falls back to CPU cleanly if none found

from pygeofetch.insar import InSARProject
from pygeofetch.models import BoundingBox

project = InSARProject(
    name="my_aoi",
    aoi=BoundingBox(min_lon=-99.183, max_lon=-99.003, min_lat=19.278, max_lat=19.438),
    output_dir="data/my_aoi_insar",
)
project.search(start_date="2024-11-01", end_date="2025-01-15")   # real search, real map
project.download_and_extract(max_scenes=6)                        # real download + AOI crop
project.form_all_interferograms()                                 # full verified pipeline
project.summary()

from pygeofetch.processor import SpectralIndex

si = SpectralIndex()
ndvi = si.compute("NDVI", RED=red_array, NIR=nir_array)
ndvi = si.from_files("NDVI", red="B04.tif", nir="B08.tif", output="ndvi.tif")

from pygeofetch.processor import LandsatExtractor

extractor = LandsatExtractor()
scene = extractor.process_scene(download_result, output_dir="./data")

print(scene.sensor)      # "OLI" or "TM"
red, nir = scene.get("red"), scene.get("nir")

# Individual operations
corrected = client.preprocess.atmos("scene.tif", method="dos1")
masked    = client.preprocess.cloud_mask("scene.tif", method="scl", scl_band="SCL.tif")
clipped   = client.preprocess.clip("scene.tif", geometry="study_area.geojson")
reproj    = client.preprocess.reproject("scene.tif", crs="EPSG:4326")

pp = client.preprocess

terrain = pp.terrain_derivatives("dem.tif")           # slope, aspect, hillshade
twi     = pp.topographic_wetness_index("dem.tif")      # real flood-susceptibility screening
curv    = pp.curvature("dem.tif")                      # concave/convex — water convergence vs. dispersion
tri     = pp.terrain_ruggedness_index("dem.tif")       # Riley et al. 1999
sinks   = pp.identify_depressions("dem.tif")           # enclosed basins with no downhill outlet
network = pp.extract_drainage_network("dem.tif")       # real channels from D8 flow accumulation

from pygeofetch.viz import Plotter

pl = Plotter()
pl.quicklook(ndvi_array)              # index -> diverging colormap
pl.quicklook("sentinel1_sigma0.tif")  # SAR -> grayscale
pl.quicklook(flood_mask)              # categorical -> auto legend
pl.quicklook(download_result)         # DownloadResult resolved automatically

pl.plot_comparison(
    {"Baseline": ndvi_before, "Recent": ndvi_after, "Change": ndvi_change},
    per_panel_cmap={"Change": "RdBu"}, per_panel_range={"Change": (-0.5, 0.5)},
)

pl.plot_classification(
    classified_array,
    class_labels={0: "Stable", 1: "Moderate", 2: "Severe"},
    class_colors={0: "#2ecc71", 1: "#f39c12", 2: "#e74c3c"},
)

from pygeofetch.viz import MapViewer

mv = MapViewer(center=(6.198, -1.693), zoom=12)
mv.add_vector("boundary.geojson", layer_name="Study Area", style={"color": "#2c3e50", "fillOpacity": 0})
mv.add_raster("ndvi_change.tif", colormap="RdBu", vmin=-0.5, vmax=0.5, opacity=0.75)
mv.add_basemap("SATELLITE")
mv.save("interactive_map.html")

results = client.search(query, providers=["copernicus", "aws_earth"])

mv = MapViewer(center=(6.198, -1.693), zoom=9)
mv.add_basemap("SATELLITE")
mv.add_search_results(results)   # real footprints, real hover info
mv.show()                        # in Jupyter — or mv.save("results.html") elsewhere

# Fast, static, no extra dependency — hillshade-draped 3D surface
pl.plot_3d_terrain("dem.tif", drape=susceptibility, drape_colormap="Blues")

# Real interactive mesh (PyVista) — rotate/zoom/pan in-browser,
# exported as a standalone HTML file, no server needed
pl.plot_3d_terrain_interactive(
    "dem.tif", drape=twi, drape_colormap="YlGnBu",
    output="terrain_interactive.html",
)

mv.add_split_comparison(
    "dsm.tif", "dtm.tif", left_label="DSM", right_label="DTM",
)

from pathlib import Path
from pygeofetch import pygeofetch
from pygeofetch.models import SearchQuery, DownloadOptions

# Initialize client
client = pygeofetch()

# Add credentials (or use env vars)
client.add_credentials("usgs", username="user", password="pass")
client.add_credentials("planet", api_key="PL_KEY")

# Search across multiple providers
results = client.search(
    SearchQuery(
        bbox=(-74.1, 40.6, -73.7, 40.9),
        start_date="2024-01-01",
        end_date="2024-06-01",
        cloud_cover_max=20,
        max_results=50,
        sort_by="cloud_cover",
    ),
    providers=["usgs", "copernicus", "planetary_computer", "aws_earth"],
)

print(f"Found {len(results)} scenes")
for r in results[:3]:
    print(f"  {r.id} | {r.datetime} | {r.cloud_cover:.1f}% cloud")

# Download top 5 results
download_results = client.download(
    results[:5],
    destination=Path("./data/"),
    options=DownloadOptions(
        parallel=4,
        verify_checksum=True,
        resume=True,
        bands=["B02", "B03", "B04"],
        post_process=["reproject:EPSG:4326", "cog"],
    ),
)

for dr in download_results:
    if dr.success:
        print(f"  ✓ {dr.data_id} ({dr.bytes_downloaded // 1024 // 1024:.1f} MB)")
    else:
        print(f"  ✗ {dr.data_id}: {dr.error}")

download:
  parallel: 4
  retry_attempts: 5
  retry_delay_seconds: 1.0
  retry_max_delay_seconds: 60.0
  retry_jitter: true
  verify_checksum: false
  checksum_algorithm: sha256     # md5, sha256, sha512
  chunk_size_mb: 10
  resume: true
  bandwidth_limit_mbps: null     # null = unlimited
  overwrite_existing: false
  notify_on_completion: null     # webhook:URL or email:ADDRESS
  notify_on_failure: null
  on_failure: skip               # skip, abort, retry

cache:
  enabled: true
  ttl_seconds: 3600
  max_size_gb: 10
  location: ~/.pygeofetch/cache

search:
  default_providers: []
  max_results: 100
  timeout_seconds: 60
  on_provider_failure: skip
  sort_by: datetime
  sort_order: desc

auth:
  storage_backend: keyring       # keyring or file
  keyring_service: pygeofetch
  file_path: ~/.pygeofetch/credentials.enc

proxy:
  http_proxy: null
  https_proxy: null
  no_proxy: []

logging:
  level: INFO
  format: console                # console, json
  file: null
  max_file_size_mb: 10
  backup_count: 3

providers:
  planetary_computer:
    endpoint: https://planetarycomputer.microsoft.com/api/stac/v1
    timeout: 60
  element84:
    endpoint: https://earth-search.aws.element84.com/v1
    timeout: 60
  copernicus:
    endpoint: https://catalogue.dataspace.copernicus.eu/resto/api/
    timeout: 45
  planet:
    endpoint: https://api.planet.com/data/v1/
    rate_limit: 100
  usgs:
    endpoint: https://m2m.cr.usgs.gov/api/api/json/stable/
    timeout: 60

# Show the merged effective configuration
pygeofetch config show

# Get a specific key
pygeofetch config get download.parallel

# Set a value
pygeofetch config set download.parallel 8
pygeofetch config set cache.ttl_seconds 7200
pygeofetch config set search.default_providers "aws_earth,planetary_computer"

# Show config file path
pygeofetch config path

# Reset to defaults
pygeofetch config reset

# Skip failing providers — return partial results from others
pygeofetch search run --providers copernicus,usgs,planet \
  --on-provider-failure skip

# Abort entirely if any provider fails
pygeofetch search run --providers copernicus,usgs \
  --on-provider-failure abort

# Auto-retry failing providers (up to 3 attempts)
pygeofetch search run --providers copernicus \
  --on-provider-failure retry

# Install dev dependencies
pip install -e ".[dev,all]"

# Run all tests
pytest tests/ -v

# With coverage report
pytest tests/ -v --cov=pygeofetch --cov-report=html
open htmlcov/index.html

# Unit tests only (fast, no network)
pytest tests/unit/ -v

# Integration tests (requires real credentials)
pytest tests/integration/ -v --run-integration

# Run a specific test file
pytest tests/unit/test_search.py -v

# With hypothesis property-based testing
pytest tests/property/ -v --hypothesis-seed=12345

tests/
├── unit/
│   ├── test_search.py         # SearchQuery, provider adapters
│   ├── test_download.py       # DownloadOptions, resume, checksum
│   ├── test_auth.py           # Keyring, env vars, credential storage
│   ├── test_pipeline.py       # YAML parsing, step execution
│   ├── test_postprocess.py    # Processing chain actions
│   └── test_config.py         # Layered config merging
├── integration/
│   ├── test_aws_earth.py      # Live AWS Earth Open Data
│   ├── test_planetary.py      # Live Planetary Computer
│   └── conftest.py
├── property/
│   └── test_models.py         # hypothesis tests
├── cli/
│   └── test_cli_workflow.py   # CliRunner end-to-end
└── cassettes/                 # VCR HTTP recordings