Metadata-Version: 2.4
Name: clouds-everywhere
Version: 0.1.0
Summary: Check satellite imagery availability over any AOI by cloud cover — and find the data gaps
Author-email: Mohammad Anwar <mohammadanwarx99@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/mohammadanwarx/Clouds-Everywhere
Project-URL: Repository, https://github.com/mohammadanwarx/Clouds-Everywhere
Project-URL: Issues, https://github.com/mohammadanwarx/Clouds-Everywhere/issues
Keywords: satellite,remote-sensing,sentinel-2,landsat,modis,cloud-cover,stac,earth-observation,gis
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: GIS
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests
Requires-Dist: pandas
Requires-Dist: matplotlib
Requires-Dist: seaborn
Requires-Dist: folium
Requires-Dist: geopandas
Requires-Dist: pyproj
Requires-Dist: shapely
Provides-Extra: dev
Requires-Dist: jupyter; extra == "dev"
Requires-Dist: pytest; extra == "dev"
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"
Dynamic: license-file

# Clouds-Everywhere

Find out when cloud-free satellite imagery is available over your study area —
and where the data gaps are.

You give it an area, a date range, and a cloud limit. It answers in plain
language: which days, weeks, or months have usable imagery, and which tiles
are missing.

## Install

```bash
pip install clouds-everywhere
```

Or from source:

```bash
git clone https://github.com/mohammadanwarx/Clouds-Everywhere.git
cd Clouds-Everywhere
pip install -e .
```

## Quick start

```python
from clouds_everywhere import query

report = query(
    aoi        = "my_area.geojson",   # bbox, polygon, GeoJSON, or shapefile
    start_date = "2024-01-01",
    end_date   = "2024-02-29",
    max_cloud  = 20,                  # max cloud cover in %
    group_by   = "week",              # "day" | "week" | "month"
    satellites = ["sentinel2", "landsat"],
)

print(report)
```

```
  Sentinel-2  -  needs 9 tiles to fully cover your area
    [OK]  8-14 Jan 2024      All tiles have usable imagery  (15 images across 9 tiles)
    [GAP] 15-21 Jan 2024     Data gap - some tiles missing  (3/9 tiles; missing: 30SVJ, ...)
    [--]  5-11 Feb 2024      No usable imagery

    Summary: 3 fully-covered weeks, 5 with gaps, 1 empty  (of 9 weeks)
```

Each period gets one of three statuses:

| Status | Meaning |
|---|---|
| **available** | every tile has at least one usable image |
| **gap** | some tiles have imagery, but at least one is missing |
| **missing** | no usable imagery at all |

*Usable* means cloud cover is at or below your threshold.

## Your area, any format

The AOI can be any of these — the CRS is handled for you (everything is
reprojected to WGS84 automatically):

- a bbox: `[minX, minY, maxX, maxY]`
- polygon coordinates: `[[lon, lat], ...]`
- a GeoJSON dict (`Feature`, `FeatureCollection`, or geometry)
- a file: `.geojson`, `.json`, `.shp`, or `.zip` (zipped shapefile)

## Tables and plots

```python
report.to_dataframe()        # one row per period per satellite
report.tile_dataframe()      # one row per tile per period
report.available_periods()   # fully covered periods
report.gap_periods()         # periods with holes

from clouds_everywhere.viz import plot_availability_calendar
plot_availability_calendar(report)   # green / amber / red calendar
```

## Lower-level functions

- `search_images(...)` — flat list of matching scenes
- `check_coverage(...)` — tile coverage per date
- `viz.plot_coverage_heatmap`, `plot_cloud_timeline`, `plot_satellite_comparison`

## Demos

- [`demo.ipynb`](demo.ipynb) — search and coverage basics
- [`demo2.ipynb`](demo2.ipynb) — the `query()` workflow and all plots

## Tests

```bash
pytest
```

Fast and offline — all API calls are mocked.

## Data sources

Sentinel-2 and Landsat from the [Element84 Earth Search](https://earth-search.aws.element84.com)
STAC API. MODIS from NASA CMR STAC.
