clouds-everywhere 0.1.0__tar.gz

clouds_everywhere-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mo_Anwar
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

clouds_everywhere-0.1.0/PKG-INFO

@@ -0,0 +1,138 @@
+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.

clouds_everywhere-0.1.0/README.md

@@ -0,0 +1,104 @@
+# 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.

clouds_everywhere-0.1.0/clouds_everywhere/__init__.py

@@ -0,0 +1,18 @@
+"""Clouds-Everywhere — check satellite imagery availability by cloud cover."""
+
+from .search import search_images
+from .coverage import check_coverage
+from .query import query
+from .models import (
+    SatelliteImage, TileResult, DateCoverage,
+    TilePeriodStat, PeriodCoverage, QueryReport,
+)
+from .aoi import to_bbox
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "query", "search_images", "check_coverage", "to_bbox",
+    "SatelliteImage", "TileResult", "DateCoverage",
+    "TilePeriodStat", "PeriodCoverage", "QueryReport",
+]

clouds_everywhere-0.1.0/clouds_everywhere/aoi.py

@@ -0,0 +1,161 @@
+"""
+aoi.py — normalize any AOI input to a WGS84 bbox [minX, minY, maxX, maxY].
+
+Accepted inputs
+---------------
+* Plain bbox list/tuple  : [minX, minY, maxX, maxY]
+* Polygon coords         : [[lon, lat], ...]  or  shapely Polygon
+* GeoJSON dict           : FeatureCollection, Feature, or geometry
+* File path (str/Path)   : .geojson, .json, .shp, .zip (zipped shapefile)
+
+Every spatial input is reprojected to WGS84 (EPSG:4326) before the bbox is
+returned, so callers never need to think about CRS.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import geopandas as gpd
+import pyproj
+from shapely.geometry import shape, Polygon
+from shapely.ops import transform, unary_union
+
+
+WGS84 = pyproj.CRS("EPSG:4326")
+
+
+# ── public entry point ────────────────────────────────────────────────────────
+
+def to_bbox(aoi) -> list[float]:
+    """Return [minX, minY, maxX, maxY] in WGS84 for any supported AOI input."""
+    geom, crs = _parse(aoi)
+    geom = _ensure_wgs84(geom, crs)
+    _validate_wgs84_bbox(geom.bounds)
+    minx, miny, maxx, maxy = geom.bounds
+    return [minx, miny, maxx, maxy]
+
+
+# ── parsers — all return (shapely_geom, pyproj.CRS | None) ───────────────────
+
+def _parse(aoi):
+    # shapely geometry passed directly — assume WGS84
+    if hasattr(aoi, "geom_type"):
+        return aoi, None
+
+    # file path
+    if isinstance(aoi, (str, Path)):
+        return _from_file(Path(aoi))
+
+    # empty containers are never a valid AOI
+    if isinstance(aoi, (list, tuple)) and len(aoi) == 0:
+        raise ValueError("AOI is empty - provide a bbox, polygon coords, or GeoJSON")
+
+    # plain bbox [minX, minY, maxX, maxY]
+    if (isinstance(aoi, (list, tuple))
+            and len(aoi) == 4
+            and all(isinstance(v, (int, float)) for v in aoi)):
+        return _bbox_to_polygon(aoi), None
+
+    # polygon as list of coordinate pairs [[x, y], ...]
+    if (isinstance(aoi, (list, tuple))
+            and all(isinstance(v, (list, tuple)) and len(v) == 2 for v in aoi)):
+        if len(aoi) < 3:
+            raise ValueError(
+                f"Polygon needs at least 3 coordinate pairs, got {len(aoi)}"
+            )
+        return _coords_to_polygon(aoi), None
+
+    # GeoJSON dict
+    if isinstance(aoi, dict):
+        return _from_geojson(aoi)
+
+    raise TypeError(f"Unsupported AOI type: {type(aoi)}")
+
+
+def _from_file(path: Path):
+    suffix = path.suffix.lower()
+
+    if suffix in (".geojson", ".json"):
+        gdf = gpd.read_file(path)
+    elif suffix == ".shp":
+        gdf = gpd.read_file(path)
+    elif suffix == ".zip":
+        gdf = gpd.read_file(f"zip://{path}")
+    else:
+        raise ValueError(f"Unsupported file format: {suffix!r}. Use .geojson, .json, .shp, or .zip")
+
+    geom = unary_union(gdf.geometry)
+    crs = gdf.crs  # pyproj.CRS or None
+    return geom, crs
+
+
+def _from_geojson(d: dict):
+    typ = d.get("type")
+
+    if typ == "FeatureCollection":
+        geoms = [shape(f["geometry"]) for f in d["features"] if f.get("geometry")]
+        geom = unary_union(geoms)
+    elif typ == "Feature":
+        geom = shape(d["geometry"])
+    elif typ in ("Polygon", "MultiPolygon", "Point", "LineString",
+                 "MultiPoint", "MultiLineString", "GeometryCollection"):
+        geom = shape(d)
+    else:
+        raise ValueError(f"Unrecognised GeoJSON type: {typ!r}")
+
+    # Some tools embed a CRS object (older GeoJSON / ArcGIS exports)
+    crs = None
+    crs_obj = d.get("crs")
+    if crs_obj:
+        epsg_name = crs_obj.get("properties", {}).get("name", "")
+        try:
+            crs = pyproj.CRS.from_user_input(epsg_name)
+        except Exception:
+            pass  # can't parse it; fall back to WGS84 assumption
+
+    return geom, crs
+
+
+def _bbox_to_polygon(bbox) -> Polygon:
+    minx, miny, maxx, maxy = bbox
+    return Polygon([
+        (minx, miny), (maxx, miny),
+        (maxx, maxy), (minx, maxy),
+        (minx, miny),
+    ])
+
+
+def _coords_to_polygon(coords) -> Polygon:
+    """Accept [[lon, lat], ...] or [[lat, lon], ...] and fix axis order."""
+    coords = [tuple(c) for c in coords]
+
+    xs = [c[0] for c in coords]
+    ys = [c[1] for c in coords]
+
+    # If xs fit in [-90, 90] but ys don't → coords are (lat, lon), swap them
+    if all(-90 <= v <= 90 for v in xs) and any(abs(v) > 90 for v in ys):
+        coords = [(y, x) for x, y in coords]
+
+    return Polygon(coords)
+
+
+# ── CRS reprojection ──────────────────────────────────────────────────────────
+
+def _ensure_wgs84(geom, crs):
+    if crs is None or crs.equals(WGS84):
+        return geom
+    transformer = pyproj.Transformer.from_crs(crs, WGS84, always_xy=True)
+    return transform(transformer.transform, geom)
+
+
+def _validate_wgs84_bbox(bounds):
+    minx, miny, maxx, maxy = bounds
+    if any(v != v for v in bounds):        # NaN check (NaN != NaN)
+        raise ValueError("AOI produced an empty or invalid geometry")
+    if not (-180 <= minx <= 180 and -180 <= maxx <= 180):
+        raise ValueError(f"Longitude out of WGS84 range: minX={minx}, maxX={maxx}")
+    if not (-90 <= miny <= 90 and -90 <= maxy <= 90):
+        raise ValueError(f"Latitude out of WGS84 range: minY={miny}, maxY={maxy}")
+    if minx >= maxx or miny >= maxy:
+        raise ValueError(f"Degenerate bbox (min >= max): {list(bounds)}")

clouds_everywhere-0.1.0/clouds_everywhere/coverage.py

@@ -0,0 +1,89 @@
+from collections import defaultdict
+
+from .providers import sentinel2, landsat
+from .models import DateCoverage
+from .aoi import to_bbox
+
+
+def check_coverage(aoi, start_date, end_date, max_cloud=20, satellites=("sentinel2", "landsat")):
+    """
+    For each date in the range, determine whether all tiles covering the bbox
+    are available and below the cloud threshold.
+
+    Returns a list of DateCoverage objects sorted by date, each flagged as:
+      "full"    — every required tile passes the cloud threshold
+      "partial" — some tiles pass, some are missing or too cloudy
+      "missing" — no tiles pass at all for that date
+    """
+    bbox = to_bbox(aoi)
+
+    fetchers = []
+    if "sentinel2" in satellites:
+        fetchers.append(("sentinel2", sentinel2.search_tiles))
+    if "landsat" in satellites:
+        fetchers.append(("landsat", landsat.search_tiles))
+
+    # One satellite failing (API down, no passes) must not abort coverage.
+    all_tile_results = []
+    for name, fetch in fetchers:
+        try:
+            all_tile_results += fetch(bbox, start_date, end_date)
+        except Exception as e:
+            print(f"[coverage] '{name}' unavailable for this request — skipping ({e})")
+
+    if not all_tile_results:
+        return []
+
+    # Analyse each satellite independently so Sentinel-2 and Landsat tile
+    # grids don't interfere with each other.
+    by_satellite = defaultdict(list)
+    for tr in all_tile_results:
+        by_satellite[tr.satellite].append(tr)
+
+    coverage_results = []
+
+    for satellite, tile_results in by_satellite.items():
+        required_tiles = set(tr.tile_id for tr in tile_results)
+
+        by_date = defaultdict(list)
+        for tr in tile_results:
+            by_date[tr.date].append(tr)
+
+        for date, date_tiles in sorted(by_date.items()):
+            tile_cloud = {tr.tile_id: tr.cloud_cover for tr in date_tiles}
+
+            covered = {
+                t: c for t, c in tile_cloud.items()
+                if c == -1 or c <= max_cloud          # -1 = cloud unknown, include it
+            }
+            failed  = {
+                t: c for t, c in tile_cloud.items()
+                if c != -1 and c > max_cloud
+            }
+            absent  = required_tiles - set(tile_cloud.keys())
+
+            covered_tiles = sorted(covered.keys())
+            missing_tiles = sorted(failed.keys()) + sorted(absent)
+
+            if not missing_tiles:
+                status = "full"
+            elif covered_tiles:
+                status = "partial"
+            else:
+                status = "missing"
+
+            valid_clouds = [c for c in covered.values() if c != -1]
+            avg_cloud = sum(valid_clouds) / len(valid_clouds) if valid_clouds else -1
+
+            coverage_results.append(DateCoverage(
+                date           = date,
+                satellite      = satellite,
+                status         = status,
+                required_tiles = sorted(required_tiles),
+                covered_tiles  = covered_tiles,
+                missing_tiles  = missing_tiles,
+                avg_cloud      = avg_cloud,
+                tile_details   = date_tiles,
+            ))
+
+    return sorted(coverage_results, key=lambda x: (x.date, x.satellite))