pycopdem 0.1.0__tar.gz

pycopdem-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Borevitz Lab, Australian National University, and contributors
+
+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.

pycopdem-0.1.0/PKG-INFO

@@ -0,0 +1,155 @@
+Metadata-Version: 2.4
+Name: pycopdem
+Version: 0.1.0
+Summary: Cached Copernicus 30 m DEM windows with on-read terrain derivatives — download once per chunk, never twice
+Author: Borevitz Lab, Australian National University
+Author-email: Yasar Adeel Ansari <u6737670@anu.edu.au>
+License: MIT
+Project-URL: Homepage, https://github.com/thestochasticman/pycopdem
+Project-URL: Repository, https://github.com/thestochasticman/pycopdem
+Project-URL: Issues, https://github.com/thestochasticman/pycopdem/issues
+Keywords: dem,copernicus,elevation,terrain,topography,twi,geospatial
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+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: attrs
+Requires-Dist: typing_extensions
+Requires-Dist: numpy
+Requires-Dist: xarray
+Requires-Dist: zarr
+Requires-Dist: rasterio
+Requires-Dist: affine
+Requires-Dist: pysheds
+Dynamic: license-file
+
+# pycopdem
+
+**Cached [Copernicus GLO-30](https://registry.opendata.aws/copernicus-dem/)
+elevation with on-read terrain derivatives — download once per chunk,
+never twice.** Every elevation pixel this machine ever downloads lands
+in one sparse, chunk-indexed store on the DEM's native 1-arc-second
+grid; slope, aspect, flow accumulation, TWI and Heat Load Index are
+computed on read and never stored. Part of the
+[Borevitz Lab](https://borevitzlab.anu.edu.au/) ecosystem.
+
+## How it works
+
+```
+{data_root}/copdem_store/
+├── index.db      # SQLite ledger: which chunks are populated
+└── dem.zarr      # global sparse array; only written 1200×1200-px chunks exist
+```
+
+- The GLO-30 DEM is served as one COG per 1° × 1° cell on a 1-arc-second
+  EPSG:4326 lattice. The store uses the same lattice globally, chunked
+  at 1200 px (1/3°) — so **3 × 3 chunks nest exactly inside every
+  tile**, and fetching a chunk is a single integer-aligned windowed
+  read from one COG. No resampling, ever.
+- Any bbox maps deterministically to a set of chunk ids.
+  `Store.get_ds(bbox)` diffs them against the ledger and downloads
+  **only the missing chunks**. Elevation is time-invariant, so there's
+  no time axis and no date bookkeeping.
+- A 1° tile absent from S3 is genuinely all ocean: its chunks are
+  stored as nodata and marked complete.
+- Derivatives are a read-time transform (like everything derived in
+  this ecosystem): request them per call, pay compute not disk.
+
+## Usage
+
+The core API is **troi-agnostic** — just a bbox:
+
+```python
+from pycopdem.store import Store
+
+store = Store()
+bbox = [148.36265, -33.52606, 148.38265, -33.50606]  # [W, S, E, N]
+
+ds = store.get_ds(bbox)                              # elevation (lat, lon)
+ds = store.get_ds(bbox, derivatives=('slope', 'aspect', 'twi', 'hli'))
+
+store.fill(bbox)                                     # → 0: already local
+```
+
+Derivatives: `slope` and `aspect` (degrees), `accumulation` (pysheds
+fill-pits → fill-depressions → resolve-flats → flowdir → accumulation),
+`twi` (ln(accumulation / tan slope)), `hli` (McCune & Keon 2002).
+Dependencies resolve automatically — asking for `twi` computes slope
+and accumulation internally.
+
+Pipelines that speak the shared `troi.troi.Troi` use the
+adapters (dates on the troi are ignored — elevation doesn't change):
+
+```python
+ds = store.get_ds_troi(troi, derivatives=('slope',))
+```
+
+`download_terrain(troi)` remains as a thin wrapper.
+
+## Performance
+
+Live measurements against the Copernicus S3 bucket — a ~2 × 2 km AOI
+(one *chunk* = 1200 × 1200 px ≈ 37 × 30 km):
+
+| Scenario | Downloaded | Time |
+|---|---|---|
+| Cold fill | 1 chunk | 10.3 s |
+| Same request again | nothing | **0.0 s** |
+| AOI shifted ~28 km east | 1 new chunk | 4.2 s |
+| Read cached window (1200²) | — | 0.4 s |
+| Read + all 5 derivatives | — | 3.2 s (pysheds dominates) |
+
+Store footprint: ~10 MB for two chunks (~2 200 km² of elevation).
+Absolute times vary with network; the zero is the point — it's a
+ledger lookup, no network involved.
+
+## Install
+
+### pip
+
+```bash
+pip install git+https://github.com/thestochasticman/pycopdem.git
+```
+
+Dependencies (the `troi` core included, pulled from GitHub) are
+declared in `pyproject.toml` and installed automatically.
+
+### From source
+
+```bash
+git clone https://github.com/thestochasticman/pycopdem.git
+cd pycopdem
+pip install -e .
+```
+
+Package design (shared across the lab's packages — no inheritance,
+composition only):
+
+- **`Troi`** (from `troi`) — identity: what region.
+- **`CopernicusDEM`** (`pycopdem.copdem`) — config: tile source.
+- **`Paths`** (`pycopdem.paths`) — derived locations of the store for a
+  given `Config`.
+- **`grid`** — the fixed 1-arc-second grid and tile/chunk nesting
+  (pure, offline-testable math).
+- **`derive`** — the terrain derivatives (pure array math + pysheds).
+- **`Store`** (`pycopdem.store`) — ties them together.
+
+## Test
+
+```bash
+# offline (pure math + synthetic store):
+python pycopdem/grid.py     # True
+python pycopdem/paths.py    # True
+python pycopdem/derive.py   # True
+python pycopdem/store.py    # True
+
+# live (small real reads from the Copernicus S3 bucket):
+python pycopdem/download_terrain.py  # True
+```

pycopdem-0.1.0/README.md

@@ -0,0 +1,123 @@
+# pycopdem
+
+**Cached [Copernicus GLO-30](https://registry.opendata.aws/copernicus-dem/)
+elevation with on-read terrain derivatives — download once per chunk,
+never twice.** Every elevation pixel this machine ever downloads lands
+in one sparse, chunk-indexed store on the DEM's native 1-arc-second
+grid; slope, aspect, flow accumulation, TWI and Heat Load Index are
+computed on read and never stored. Part of the
+[Borevitz Lab](https://borevitzlab.anu.edu.au/) ecosystem.
+
+## How it works
+
+```
+{data_root}/copdem_store/
+├── index.db      # SQLite ledger: which chunks are populated
+└── dem.zarr      # global sparse array; only written 1200×1200-px chunks exist
+```
+
+- The GLO-30 DEM is served as one COG per 1° × 1° cell on a 1-arc-second
+  EPSG:4326 lattice. The store uses the same lattice globally, chunked
+  at 1200 px (1/3°) — so **3 × 3 chunks nest exactly inside every
+  tile**, and fetching a chunk is a single integer-aligned windowed
+  read from one COG. No resampling, ever.
+- Any bbox maps deterministically to a set of chunk ids.
+  `Store.get_ds(bbox)` diffs them against the ledger and downloads
+  **only the missing chunks**. Elevation is time-invariant, so there's
+  no time axis and no date bookkeeping.
+- A 1° tile absent from S3 is genuinely all ocean: its chunks are
+  stored as nodata and marked complete.
+- Derivatives are a read-time transform (like everything derived in
+  this ecosystem): request them per call, pay compute not disk.
+
+## Usage
+
+The core API is **troi-agnostic** — just a bbox:
+
+```python
+from pycopdem.store import Store
+
+store = Store()
+bbox = [148.36265, -33.52606, 148.38265, -33.50606]  # [W, S, E, N]
+
+ds = store.get_ds(bbox)                              # elevation (lat, lon)
+ds = store.get_ds(bbox, derivatives=('slope', 'aspect', 'twi', 'hli'))
+
+store.fill(bbox)                                     # → 0: already local
+```
+
+Derivatives: `slope` and `aspect` (degrees), `accumulation` (pysheds
+fill-pits → fill-depressions → resolve-flats → flowdir → accumulation),
+`twi` (ln(accumulation / tan slope)), `hli` (McCune & Keon 2002).
+Dependencies resolve automatically — asking for `twi` computes slope
+and accumulation internally.
+
+Pipelines that speak the shared `troi.troi.Troi` use the
+adapters (dates on the troi are ignored — elevation doesn't change):
+
+```python
+ds = store.get_ds_troi(troi, derivatives=('slope',))
+```
+
+`download_terrain(troi)` remains as a thin wrapper.
+
+## Performance
+
+Live measurements against the Copernicus S3 bucket — a ~2 × 2 km AOI
+(one *chunk* = 1200 × 1200 px ≈ 37 × 30 km):
+
+| Scenario | Downloaded | Time |
+|---|---|---|
+| Cold fill | 1 chunk | 10.3 s |
+| Same request again | nothing | **0.0 s** |
+| AOI shifted ~28 km east | 1 new chunk | 4.2 s |
+| Read cached window (1200²) | — | 0.4 s |
+| Read + all 5 derivatives | — | 3.2 s (pysheds dominates) |
+
+Store footprint: ~10 MB for two chunks (~2 200 km² of elevation).
+Absolute times vary with network; the zero is the point — it's a
+ledger lookup, no network involved.
+
+## Install
+
+### pip
+
+```bash
+pip install git+https://github.com/thestochasticman/pycopdem.git
+```
+
+Dependencies (the `troi` core included, pulled from GitHub) are
+declared in `pyproject.toml` and installed automatically.
+
+### From source
+
+```bash
+git clone https://github.com/thestochasticman/pycopdem.git
+cd pycopdem
+pip install -e .
+```
+
+Package design (shared across the lab's packages — no inheritance,
+composition only):
+
+- **`Troi`** (from `troi`) — identity: what region.
+- **`CopernicusDEM`** (`pycopdem.copdem`) — config: tile source.
+- **`Paths`** (`pycopdem.paths`) — derived locations of the store for a
+  given `Config`.
+- **`grid`** — the fixed 1-arc-second grid and tile/chunk nesting
+  (pure, offline-testable math).
+- **`derive`** — the terrain derivatives (pure array math + pysheds).
+- **`Store`** (`pycopdem.store`) — ties them together.
+
+## Test
+
+```bash
+# offline (pure math + synthetic store):
+python pycopdem/grid.py     # True
+python pycopdem/paths.py    # True
+python pycopdem/derive.py   # True
+python pycopdem/store.py    # True
+
+# live (small real reads from the Copernicus S3 bucket):
+python pycopdem/download_terrain.py  # True
+```

pycopdem-0.1.0/pycopdem/__init__.py

@@ -0,0 +1,11 @@
+# Light-weight exports only: pycopdem.store (and the download_terrain
+# wrapper) pull in rasterio/zarr/pysheds, so those stay behind explicit
+# submodule imports.
+from pycopdem.copdem import CopernicusDEM, defaultcopdem
+from pycopdem.paths import Paths
+
+__all__ = [
+    'CopernicusDEM',
+    'defaultcopdem',
+    'Paths',
+]

pycopdem-0.1.0/pycopdem/copdem.py

@@ -0,0 +1,18 @@
+from attrs import frozen
+
+@frozen
+class CopernicusDEM:
+    """Endpoint configuration for Copernicus GLO-30 DEM tiles on AWS.
+
+    The DEM is global, 30 m (1 arc-second), served as public
+    Cloud-Optimised GeoTIFFs — one per 1° x 1° cell. Tiles that would
+    be entirely ocean do not exist; the store treats a missing tile as
+    all-nodata.
+    """
+
+    base_url: str = 'https://copernicus-dem-30m.s3.amazonaws.com'
+
+    def tile_url(self, tile: str) -> str:
+        return f'{self.base_url}/{tile}/{tile}.tif'
+
+defaultcopdem = CopernicusDEM()

pycopdem-0.1.0/pycopdem/derive.py

@@ -0,0 +1,121 @@
+"""Topographic derivatives, computed on read — never stored.
+
+Slope, aspect, and Heat Load Index are cheap array math; flow
+accumulation and TWI run the pysheds conditioning chain (fill pits →
+fill depressions → resolve flats → flow direction → accumulation).
+Everything operates on an elevation window plus its pixel size, so the
+functions stay pure of store concerns.
+"""
+import numpy as np
+
+# pysheds 0.5 calls np.in1d which was removed in NumPy 2.0. Alias to np.isin
+# (the documented replacement, same semantics) before pysheds is imported.
+if not hasattr(np, 'in1d'):
+    np.in1d = np.isin
+
+
+def slope(dem: np.ndarray, xres: float, yres: float) -> np.ndarray:
+    """Slope in degrees from an elevation array and pixel sizes (metres)."""
+    gy, gx = np.gradient(dem, yres, xres)
+    return np.arctan(np.sqrt(gx ** 2 + gy ** 2)) * (180 / np.pi)
+
+
+def aspect(dem: np.ndarray, xres: float, yres: float) -> np.ndarray:
+    """Aspect (direction of steepest descent) in degrees, 0/360=N 90=E 180=S 270=W."""
+    gy, gx = np.gradient(dem, yres, xres)
+    deg = np.degrees(np.arctan2(-gx, gy))
+    return np.where(deg < 0, deg + 360, deg)
+
+
+def accumulation(dem: np.ndarray, transform, nodata: float = -9999.0) -> np.ndarray:
+    """Flow accumulation (cells) via pysheds on an in-memory window.
+
+    The window is written to a temporary GeoTIFF because pysheds'
+    conditioning chain reads from raster files.
+    """
+    import os
+    import tempfile
+    import rasterio
+    from pysheds.grid import Grid
+
+    filled = np.where(np.isnan(dem), nodata, dem).astype('float32')
+    fd, path = tempfile.mkstemp(suffix='.tif')
+    os.close(fd)
+    try:
+        with rasterio.open(
+            path, 'w', driver='GTiff', height=dem.shape[0], width=dem.shape[1],
+            count=1, dtype='float32', transform=transform, crs='EPSG:4326',
+            nodata=nodata,
+        ) as dst:
+            dst.write(filled, 1)
+        grid = Grid.from_raster(path, nodata=nodata)
+        raster = grid.read_raster(path, nodata=nodata)
+        inflated = grid.resolve_flats(grid.fill_depressions(grid.fill_pits(raster)))
+        fdir = grid.flowdir(inflated, nodata_out=0)
+        return np.asarray(grid.accumulation(fdir, nodata_out=0))
+    finally:
+        os.remove(path)
+
+
+def twi(acc: np.ndarray, slope_deg: np.ndarray) -> np.ndarray:
+    """Topographic wetness index: ln(accumulation / tan(slope))."""
+    ratio = acc / np.tan(np.radians(slope_deg))
+    ratio[ratio <= 0] = 1
+    return np.log(ratio)
+
+
+def hli(slope_deg: np.ndarray, aspect_deg: np.ndarray, latitude: float) -> np.ndarray:
+    """Heat Load Index (McCune & Keon 2002), ~0-1; higher = more insolation."""
+    slope_rad = np.radians(slope_deg)
+    lat_rad = np.radians(latitude)
+    folded = np.radians(np.abs(180 - np.abs(aspect_deg - 225)))
+    out = np.exp(
+        -1.467
+        + 1.582 * np.cos(lat_rad) * np.cos(slope_rad)
+        - 1.5 * np.cos(folded) * np.sin(slope_rad) * np.sin(lat_rad)
+        - 0.262 * np.sin(lat_rad) * np.sin(slope_rad)
+        + 0.607 * np.sin(folded) * np.sin(slope_rad)
+    )
+    return np.clip(out, 0, 1)
+
+
+def test_slope_of_inclined_plane():
+    """A plane rising 1 m per metre east has slope 45° everywhere inside."""
+    x = np.arange(50, dtype='float64')
+    dem = np.tile(x, (50, 1))          # elevation == x coordinate (1 m pixels)
+    s = slope(dem, 1.0, 1.0)
+    return abs(float(s[25, 25]) - 45.0) < 1e-6
+
+
+def test_aspect_points_downhill():
+    """Rising to the east -> steepest descent faces west (270°)."""
+    x = np.arange(50, dtype='float64')
+    dem = np.tile(x, (50, 1))
+    a = aspect(dem, 1.0, 1.0)
+    return abs(float(a[25, 25]) - 270.0) < 1e-6
+
+
+def test_flat_ground_hli_matches_formula():
+    h = hli(np.zeros((5, 5)), np.zeros((5, 5)), -33.5)
+    expected = np.exp(-1.467 + 1.582 * np.cos(np.radians(-33.5)))
+    return abs(float(h[2, 2]) - min(expected, 1.0)) < 1e-9
+
+
+def test_twi_monotonic_in_accumulation():
+    s = np.full((3, 3), 10.0)
+    low = twi(np.full((3, 3), 10.0), s)
+    high = twi(np.full((3, 3), 1000.0), s)
+    return float(high[1, 1]) > float(low[1, 1])
+
+
+def test():
+    return all([
+        test_slope_of_inclined_plane(),
+        test_aspect_points_downhill(),
+        test_flat_ground_hli_matches_formula(),
+        test_twi_monotonic_in_accumulation(),
+    ])
+
+
+if __name__ == '__main__':
+    print(test())

pycopdem-0.1.0/pycopdem/download_terrain.py

@@ -0,0 +1,78 @@
+"""Fetch the elevation window (+ derivatives) for a troi — via the
+machine-wide store.
+
+Thin compatibility wrapper: the heavy lifting (chunk-level dedup,
+windowed COG reads, on-read derivatives) lives in
+:class:`pycopdem.store.Store`. Kept as a module so the familiar
+``download_terrain(troi)`` entry point survives.
+"""
+import xarray as xr
+from troi import Troi
+from pycopdem.copdem import CopernicusDEM, defaultcopdem
+
+
+def download_terrain(troi: Troi, derivatives: tuple[str, ...] = (),
+                     copdem: CopernicusDEM = defaultcopdem) -> xr.Dataset:
+    """Return the Copernicus 30 m elevation window for ``troi.bbox``.
+
+    Fetches only the grid chunks no previous request has populated —
+    repeat and overlapping queries re-download nothing. Dates on the
+    troi are ignored: elevation is time-invariant.
+
+    Args:
+        troi: The :class:`troi.Troi` (bbox is what matters).
+        derivatives: Any of ``'slope'``, ``'aspect'``, ``'accumulation'``,
+            ``'twi'``, ``'hli'`` — computed on read, never stored.
+        copdem: Tile-source configuration; defaults to Copernicus on AWS.
+
+    Returns:
+        xarray.Dataset with dims ``(lat, lon)``: ``elevation`` plus one
+        variable per requested derivative.
+    """
+    from pycopdem.store import Store
+    store = Store(config=troi.config, copdem=copdem)
+    return store.get_ds_troi(troi, derivatives=derivatives)
+
+
+def test_live_fetch_and_dedup():
+    """Live: cold fetch covers the bbox; repeat and overlapping bboxes
+    fetch nothing; derivatives come back finite."""
+    import numpy as np
+    import tempfile
+    from troi import Config
+    from pycopdem.store import Store
+
+    tmpdir = tempfile.mkdtemp(prefix='pycopdem_live_test_')
+    cfg = Config(out_dir=tmpdir, tmp_dir=tmpdir)
+    store = Store(config=cfg)
+    bbox = [148.36265, -33.52606, 148.38265, -33.50606]
+
+    fetched = store.fill(bbox)
+    if fetched < 1:
+        return False
+    ds = store.get_ds(bbox)
+    elev = ds['elevation'].values
+    if not np.isfinite(elev).any() or float(np.nanmax(elev)) <= 0:
+        return False
+    # identical repeat -> nothing
+    if store.fill(bbox) != 0:
+        return False
+    # overlapping bbox shifted ~2 km -> shares chunks, fetches at most the difference
+    shifted = [bbox[0] + 0.02, bbox[1], bbox[2] + 0.02, bbox[3]]
+    if store.fill(shifted) != 0:  # within the same 1/3-degree chunks here
+        return False
+    # derivatives computed on read
+    dsd = store.get_ds(bbox, derivatives=('slope', 'aspect', 'twi', 'hli'))
+    return (
+        float(dsd['slope'].max()) >= 0
+        and np.isfinite(dsd['twi'].values).any()
+        and np.isfinite(dsd['hli'].values).any()
+    )
+
+
+def test():
+    return test_live_fetch_and_dedup()
+
+
+if __name__ == '__main__':
+    print(test())

pycopdem-0.1.0/pycopdem/grid.py

@@ -0,0 +1,135 @@
+"""The fixed global grid every stored elevation pixel lives on.
+
+The Copernicus GLO-30 DEM is served as 1° x 1° COG tiles on a
+1-arc-second (1/3600°) EPSG:4326 lattice anchored at integer degrees.
+This module defines the same lattice globally, chunked at 1200 x 1200
+pixels (1/3°) — chosen so exactly 3 x 3 chunks nest inside every 1°
+tile, which makes each chunk fetchable with a single integer-aligned
+windowed read from one COG. Any bbox maps deterministically to a set
+of chunk ids, which is what makes the store dedup-able: overlapping
+AOIs resolve to overlapping chunk sets, and a chunk is only ever
+downloaded once.
+
+All functions here are pure — no I/O, no store access.
+"""
+
+PX_PER_DEG = 3600             # 1 arc-second pixels
+CHUNK = 1200                  # pixels per chunk edge (1/3 degree)
+LON0, LAT_TOP = -180.0, 90.0  # grid origin: top-left corner
+WIDTH_PX = 360 * PX_PER_DEG
+HEIGHT_PX = 180 * PX_PER_DEG
+RES = 1.0 / PX_PER_DEG
+
+
+def window_for_bbox(bbox: list[float]) -> tuple[int, int, int, int]:
+    """Pixel window ``(row0, row1, col0, col1)`` covering ``bbox``, snapped
+    outward to whole chunks. Rows increase southward (row 0 at +90°)."""
+    west, south, east, north = bbox
+    col0 = int((west - LON0) * PX_PER_DEG // CHUNK) * CHUNK
+    col1 = -int(-((east - LON0) * PX_PER_DEG) // CHUNK) * CHUNK
+    row0 = int((LAT_TOP - north) * PX_PER_DEG // CHUNK) * CHUNK
+    row1 = -int(-((LAT_TOP - south) * PX_PER_DEG) // CHUNK) * CHUNK
+    return (row0, row1, col0, col1)
+
+
+def chunks_in_window(window: tuple[int, int, int, int]) -> list[tuple[int, int]]:
+    """All chunk ids ``(cy, cx)`` inside a chunk-aligned pixel window."""
+    row0, row1, col0, col1 = window
+    return [
+        (cy, cx)
+        for cy in range(row0 // CHUNK, row1 // CHUNK)
+        for cx in range(col0 // CHUNK, col1 // CHUNK)
+    ]
+
+
+def chunk_bounds(cy: int, cx: int) -> tuple[float, float, float, float]:
+    """EPSG:4326 ``(west, south, east, north)`` bounds of a chunk."""
+    west = LON0 + cx * CHUNK * RES
+    north = LAT_TOP - cy * CHUNK * RES
+    return (west, north - CHUNK * RES, west + CHUNK * RES, north)
+
+
+def tile_of_chunk(cy: int, cx: int) -> tuple[int, int]:
+    """The 1° DEM tile ``(lat, lon)`` (south-west corner, integer degrees)
+    containing this chunk. Chunks nest exactly: one chunk, one tile."""
+    west, south, _, _ = chunk_bounds(cy, cx)
+    import math
+    return (math.floor(south), math.floor(west))
+
+
+def tile_name(lat: int, lon: int) -> str:
+    """Copernicus GLO-30 tile stem for the 1° cell with SW corner (lat, lon)."""
+    ns = f'S{abs(lat):02d}_00' if lat < 0 else f'N{lat:02d}_00'
+    ew = f'W{abs(lon):03d}_00' if lon < 0 else f'E{lon:03d}_00'
+    return f'Copernicus_DSM_COG_10_{ns}_{ew}_DEM'
+
+
+def chunk_window_in_tile(cy: int, cx: int) -> tuple[int, int, int, int]:
+    """Integer pixel window ``(row0, row1, col0, col1)`` of this chunk
+    inside its containing tile's 3600 x 3600 raster."""
+    r0 = (cy * CHUNK) % PX_PER_DEG
+    c0 = (cx * CHUNK) % PX_PER_DEG
+    return (r0, r0 + CHUNK, c0, c0 + CHUNK)
+
+
+def coords_for_window(window: tuple[int, int, int, int]):
+    """Pixel-centre coordinate arrays ``(lat, lon)`` for a window
+    (lat descending)."""
+    import numpy as np
+    row0, row1, col0, col1 = window
+    lon = LON0 + (np.arange(col0, col1) + 0.5) * RES
+    lat = LAT_TOP - (np.arange(row0, row1) + 0.5) * RES
+    return lat, lon
+
+
+_BBOX = [148.36265, -33.52606, 148.38265, -33.50606]
+
+
+def test_window_is_chunk_aligned():
+    w = window_for_bbox(_BBOX)
+    return all(v % CHUNK == 0 for v in w) and w[1] > w[0] and w[3] > w[2]
+
+
+def test_chunks_nest_in_tiles():
+    """Every chunk's pixel window inside its tile must be within [0, 3600]
+    and aligned to CHUNK."""
+    for cy, cx in chunks_in_window(window_for_bbox(_BBOX)):
+        r0, r1, c0, c1 = chunk_window_in_tile(cy, cx)
+        if not (0 <= r0 < r1 <= PX_PER_DEG and 0 <= c0 < c1 <= PX_PER_DEG):
+            return False
+        if r0 % CHUNK or c0 % CHUNK:
+            return False
+    return True
+
+
+def test_tile_naming():
+    return tile_name(-34, 148) == 'Copernicus_DSM_COG_10_S34_00_E148_00_DEM'
+
+
+def test_chunk_bounds_inside_tile():
+    for cy, cx in chunks_in_window(window_for_bbox(_BBOX)):
+        tlat, tlon = tile_of_chunk(cy, cx)
+        w, s, e, n = chunk_bounds(cy, cx)
+        if not (tlon <= w and e <= tlon + 1 and tlat <= s and n <= tlat + 1):
+            return False
+    return True
+
+
+def test_overlapping_bboxes_share_chunks():
+    a = window_for_bbox(_BBOX)
+    b = window_for_bbox([_BBOX[0] + 0.05, _BBOX[1], _BBOX[2] + 0.05, _BBOX[3]])
+    return len(set(chunks_in_window(a)) & set(chunks_in_window(b))) > 0
+
+
+def test():
+    return all([
+        test_window_is_chunk_aligned(),
+        test_chunks_nest_in_tiles(),
+        test_tile_naming(),
+        test_chunk_bounds_inside_tile(),
+        test_overlapping_bboxes_share_chunks(),
+    ])
+
+
+if __name__ == '__main__':
+    print(test())

pycopdem-0.1.0/pycopdem/paths.py

@@ -0,0 +1,58 @@
+"""Derived on-disk locations of the machine-wide elevation store.
+
+The store is keyed by :class:`troi.Config` (one store per
+data root, shared by every request on this machine). Rule of thumb
+across the lab's packages: user-settable inputs → Config, derived
+locations → Paths. No inheritance — composition only.
+"""
+from attrs import frozen, field
+from troi import Config, config as default_config
+
+
+@frozen
+class Paths:
+    """Where the pycopdem store lives for a given Config.
+
+    Attributes:
+        config: The :class:`troi.Config` supplying the data root.
+        root: Store directory (``{config.tmp_dir}/copdem_store``).
+        store: The sparse Zarr store holding every downloaded elevation chunk.
+        index_db: SQLite ledger of populated chunks.
+
+    Example:
+        ```python
+        from pycopdem.paths import Paths
+
+        Paths().store  # '~/Downloads/Troi-Tmp/copdem_store/dem.zarr'
+        ```
+    """
+
+    config: Config = default_config
+
+    root: str = field(init=False)
+    store: str = field(init=False)
+    index_db: str = field(init=False)
+
+    root.default(lambda s: f'{s.config.tmp_dir}/copdem_store')
+    store.default(lambda s: f'{s.root}/dem.zarr')
+    index_db.default(lambda s: f'{s.root}/index.db')
+
+
+def test_paths_derive_from_config():
+    import tempfile
+    tmpdir = tempfile.mkdtemp(prefix='pycopdem_paths_test_')
+    cfg = Config(out_dir=tmpdir, tmp_dir=tmpdir)
+    paths = Paths(cfg)
+    return (
+        paths.root == f'{tmpdir}/copdem_store'
+        and paths.store == f'{tmpdir}/copdem_store/dem.zarr'
+        and paths.index_db == f'{tmpdir}/copdem_store/index.db'
+    )
+
+
+def test():
+    return test_paths_derive_from_config()
+
+
+if __name__ == '__main__':
+    print(test())

pycopdem-0.1.0/pycopdem/store.py

@@ -0,0 +1,313 @@
+"""One machine-wide elevation store that fills itself on demand.
+
+Every elevation pixel this machine ever downloads lands in a single
+sparse Zarr array on the fixed 1-arc-second EPSG:4326 grid
+(:mod:`pycopdem.grid`):
+
+    {config.tmp_dir}/copdem_store/
+    ├── index.db      # SQLite ledger: which chunks are populated
+    └── dem.zarr      # global sparse array; only written chunks exist on disk
+
+Elevation is time-invariant, so there is no time axis and no date
+bookkeeping — the ledger is just the set of populated ``(cy, cx)``
+chunks. ``Store.get_ds(bbox)`` diffs the requested chunks against the
+ledger, fetches only the missing ones (each chunk is a single
+integer-aligned windowed read from one Copernicus COG tile), then
+reads the window. Derivatives — slope, aspect, flow accumulation,
+TWI, HLI — are computed on read (:mod:`pycopdem.derive`), never stored.
+A 1° tile that does not exist on S3 is genuinely all ocean; its chunks
+are stored as nodata and marked complete.
+"""
+import sqlite3
+from attrs import frozen, field
+from datetime import datetime, timezone
+from os import makedirs
+
+import numpy as np
+import xarray as xr
+import zarr
+
+from troi import Config, config as default_config
+from pycopdem import derive, grid
+from pycopdem.copdem import CopernicusDEM, defaultcopdem
+from pycopdem.paths import Paths
+
+_SCHEMA = """
+CREATE TABLE IF NOT EXISTS chunks (
+    cy INTEGER NOT NULL,
+    cx INTEGER NOT NULL,
+    written_at TEXT NOT NULL,
+    PRIMARY KEY (cy, cx)
+) WITHOUT ROWID;
+"""
+
+DERIVATIVES = ('slope', 'aspect', 'accumulation', 'twi', 'hli')
+
+# Metres per degree of latitude (per degree of longitude scales by cos(lat)).
+_M_PER_DEG = 111_320.0
+
+
+@frozen
+class Store:
+    """The machine-wide elevation store: one grid, one ledger, zero re-downloads.
+
+    Composed from :class:`troi.Config` (where the store
+    lives) and :class:`pycopdem.copdem.CopernicusDEM` (where tiles come
+    from). No inheritance.
+
+    Example:
+        ```python
+        from pycopdem.store import Store
+
+        store = Store()
+        ds = store.get_ds(bbox)                                 # elevation only
+        ds = store.get_ds(bbox, derivatives=('slope', 'twi'))   # + derived layers
+        ```
+    """
+
+    config: Config = default_config
+    copdem: CopernicusDEM = defaultcopdem
+    paths: Paths = field(init=False)
+
+    paths.default(lambda s: Paths(s.config))
+
+    def __attrs_post_init__(s):
+        makedirs(s.paths.root, exist_ok=True)
+
+    def _db(s) -> sqlite3.Connection:
+        db = sqlite3.connect(s.paths.index_db)
+        db.execute('PRAGMA journal_mode=WAL')
+        db.executescript(_SCHEMA)
+        return db
+
+    def _array(s, mode: str = 'a') -> zarr.Array:
+        root = zarr.open_group(s.paths.store, mode=mode)
+        try:
+            return root['elevation']
+        except KeyError:
+            return root.create_array(
+                'elevation',
+                shape=(grid.HEIGHT_PX, grid.WIDTH_PX),
+                chunks=(grid.CHUNK, grid.CHUNK),
+                dtype='float32',
+                fill_value=np.nan,
+            )
+
+    # -- fill -------------------------------------------------------------
+
+    def fill(s, bbox: list[float]) -> int:
+        """Ensure every chunk covering ``bbox`` is populated.
+
+        Troi-agnostic (and, elevation being time-invariant, date-free).
+        Returns the number of chunks actually downloaded — 0 means the
+        request was already fully covered and no network was touched.
+        """
+        wanted = grid.chunks_in_window(grid.window_for_bbox(bbox))
+        db = s._db()
+        try:
+            done = set(db.execute('SELECT cy, cx FROM chunks').fetchall())
+            missing = [c for c in wanted if c not in done]
+            if not missing:
+                return 0
+            arr = s._array()
+            for cy, cx in missing:
+                s._fetch_chunk(arr, cy, cx)
+                with db:
+                    db.execute(
+                        'INSERT OR REPLACE INTO chunks (cy, cx, written_at) VALUES (?, ?, ?)',
+                        (cy, cx, datetime.now(timezone.utc).isoformat()),
+                    )
+            return len(missing)
+        finally:
+            db.close()
+
+    def _fetch_chunk(s, arr: zarr.Array, cy: int, cx: int) -> None:
+        """One integer-aligned windowed read from the chunk's COG tile."""
+        import rasterio
+        from rasterio.windows import Window
+
+        tile = grid.tile_name(*grid.tile_of_chunk(cy, cx))
+        r0, r1, c0, c1 = grid.chunk_window_in_tile(cy, cx)
+        try:
+            # The bucket is public, but rasterio recognises *.s3.amazonaws.com
+            # URLs and tries to sign requests with whatever AWS credentials
+            # are lying around — a stale SSO profile then fails the fetch
+            # with TokenRetrievalError before GDAL makes a request. Force
+            # anonymous access.
+            with rasterio.Env(AWS_NO_SIGN_REQUEST='YES'), \
+                    rasterio.open(s.copdem.tile_url(tile)) as src:
+                data = src.read(
+                    1, window=Window(c0, r0, c1 - c0, r1 - r0)
+                ).astype('float32')
+                if src.nodata is not None:
+                    data = np.where(data == src.nodata, np.nan, data)
+        except rasterio.errors.RasterioIOError as e:
+            # Only a missing tile means ocean. Any other IO failure (403,
+            # timeout, truncated response) must propagate — recording it as
+            # nodata would poison the store permanently.
+            msg = str(e)
+            if not ('404' in msg or 'No such file' in msg or 'does not exist' in msg):
+                raise
+            data = np.full((grid.CHUNK, grid.CHUNK), np.nan, dtype='float32')
+        arr[cy * grid.CHUNK:(cy + 1) * grid.CHUNK,
+            cx * grid.CHUNK:(cx + 1) * grid.CHUNK] = data
+
+    # -- read -------------------------------------------------------------
+
+    def get_ds(s, bbox: list[float], derivatives: tuple[str, ...] = ()) -> xr.Dataset:
+        """Return the elevation window for ``bbox``, downloading only what's
+        missing first, with any requested derivatives computed on read.
+
+        Args:
+            bbox: ``[west, south, east, north]`` in EPSG:4326.
+            derivatives: Any of ``'slope'``, ``'aspect'``,
+                ``'accumulation'``, ``'twi'``, ``'hli'`` (dependencies are
+                resolved automatically — e.g. ``'twi'`` implies computing
+                slope and accumulation).
+
+        Returns:
+            xarray.Dataset with dims ``(lat, lon)`` on the fixed grid:
+            ``elevation`` plus one variable per requested derivative.
+        """
+        unknown = set(derivatives) - set(DERIVATIVES)
+        if unknown:
+            raise ValueError(f'Unknown derivative(s): {sorted(unknown)} — pick from {DERIVATIVES}')
+        s.fill(bbox)
+
+        window = grid.window_for_bbox(bbox)
+        row0, row1, col0, col1 = window
+        dem = s._array(mode='r')[row0:row1, col0:col1]
+        lat, lon = grid.coords_for_window(window)
+        ds = xr.Dataset(
+            {'elevation': (('lat', 'lon'), dem)},
+            coords={'lat': lat, 'lon': lon},
+            attrs={'crs': 'EPSG:4326', 'resolution_arcsec': 1},
+        )
+
+        if derivatives:
+            centre_lat = float(lat.mean())
+            xres = grid.RES * _M_PER_DEG * np.cos(np.radians(centre_lat))
+            yres = grid.RES * _M_PER_DEG
+            slope_deg = derive.slope(dem, xres, yres)
+            need_acc = 'accumulation' in derivatives or 'twi' in derivatives
+            acc = None
+            if need_acc:
+                from affine import Affine
+                transform = Affine(grid.RES, 0, grid.LON0 + col0 * grid.RES,
+                                   0, -grid.RES, grid.LAT_TOP - row0 * grid.RES)
+                acc = derive.accumulation(dem, transform)
+            if 'slope' in derivatives:
+                ds['slope'] = (('lat', 'lon'), slope_deg)
+            if 'aspect' in derivatives or 'hli' in derivatives:
+                aspect_deg = derive.aspect(dem, xres, yres)
+                if 'aspect' in derivatives:
+                    ds['aspect'] = (('lat', 'lon'), aspect_deg)
+                if 'hli' in derivatives:
+                    ds['hli'] = (('lat', 'lon'), derive.hli(slope_deg, aspect_deg, centre_lat))
+            if 'accumulation' in derivatives:
+                ds['accumulation'] = (('lat', 'lon'), acc)
+            if 'twi' in derivatives:
+                ds['twi'] = (('lat', 'lon'), derive.twi(acc, slope_deg))
+        return ds
+
+    # -- Troi adapter (the reproducibility layer speaks Troi) -----------
+
+    def fill_troi(s, troi) -> int:
+        """:meth:`fill` for a :class:`troi.Troi` (dates ignored
+        — elevation is time-invariant)."""
+        return s.fill(troi.bbox)
+
+    def get_ds_troi(s, troi, derivatives: tuple[str, ...] = ()) -> xr.Dataset:
+        """:meth:`get_ds` for a :class:`troi.Troi`."""
+        return s.get_ds(troi.bbox, derivatives=derivatives)
+
+
+# -- offline tests (synthetic writes, no network) --------------------------
+
+_TEST_BBOX = [148.36265, -33.52606, 148.38265, -33.50606]
+
+
+def _tmp_store() -> Store:
+    import tempfile
+    tmpdir = tempfile.mkdtemp(prefix='pycopdem_store_test_')
+    return Store(config=Config(out_dir=tmpdir, tmp_dir=tmpdir))
+
+
+def _prime_synthetic(store: Store, bbox, value: float = 500.0, tilt: float = 0.0):
+    """Mark every chunk of bbox populated; elevation = value + tilt x column
+    (a plane rising eastward when tilt > 0)."""
+    window = grid.window_for_bbox(bbox)
+    arr = store._array()
+    db = store._db()
+    with db:
+        for cy, cx in grid.chunks_in_window(window):
+            cols = np.arange(cx * grid.CHUNK, (cx + 1) * grid.CHUNK, dtype='float32')
+            block = np.tile(value + tilt * cols, (grid.CHUNK, 1))
+            arr[cy * grid.CHUNK:(cy + 1) * grid.CHUNK,
+                cx * grid.CHUNK:(cx + 1) * grid.CHUNK] = block
+            db.execute(
+                'INSERT OR REPLACE INTO chunks (cy, cx, written_at) VALUES (?, ?, ?)',
+                (cy, cx, 'synthetic'),
+            )
+    db.close()
+
+
+def test_synthetic_write_read_roundtrip():
+    store = _tmp_store()
+    _prime_synthetic(store, _TEST_BBOX, value=512.0)
+    ds = store.get_ds(_TEST_BBOX)
+    return (
+        float(ds['elevation'][0, 0]) == 512.0
+        and ds.lat[0] > ds.lat[-1]  # lat descending
+    )
+
+
+def test_fill_skips_populated_chunks():
+    store = _tmp_store()
+    _prime_synthetic(store, _TEST_BBOX)
+    return store.fill(_TEST_BBOX) == 0
+
+
+def test_flat_ground_has_zero_slope():
+    store = _tmp_store()
+    _prime_synthetic(store, _TEST_BBOX, value=300.0)
+    ds = store.get_ds(_TEST_BBOX, derivatives=('slope',))
+    return float(ds['slope'].max()) == 0.0
+
+
+def test_derivatives_on_tilted_plane():
+    """A plane rising eastward -> positive slope, west-facing aspect,
+    finite TWI, HLI in (0, 1]."""
+    store = _tmp_store()
+    _prime_synthetic(store, _TEST_BBOX, value=300.0, tilt=0.5)
+    ds = store.get_ds(_TEST_BBOX, derivatives=('slope', 'aspect', 'twi', 'hli'))
+    return (
+        float(ds['slope'].min()) > 0.0
+        and abs(float(ds['aspect'][5, 5]) - 270.0) < 1.0
+        and np.isfinite(ds['twi'].values).all()
+        and 0 < float(ds['hli'][5, 5]) <= 1
+    )
+
+
+def test_unknown_derivative_raises():
+    store = _tmp_store()
+    _prime_synthetic(store, _TEST_BBOX)
+    try:
+        store.get_ds(_TEST_BBOX, derivatives=('curvature',))
+    except ValueError:
+        return True
+    return False
+
+
+def test():
+    return all([
+        test_synthetic_write_read_roundtrip(),
+        test_fill_skips_populated_chunks(),
+        test_flat_ground_has_zero_slope(),
+        test_derivatives_on_tilted_plane(),
+        test_unknown_derivative_raises(),
+    ])
+
+
+if __name__ == '__main__':
+    print(test())

pycopdem-0.1.0/pycopdem.egg-info/PKG-INFO

@@ -0,0 +1,155 @@
+Metadata-Version: 2.4
+Name: pycopdem
+Version: 0.1.0
+Summary: Cached Copernicus 30 m DEM windows with on-read terrain derivatives — download once per chunk, never twice
+Author: Borevitz Lab, Australian National University
+Author-email: Yasar Adeel Ansari <u6737670@anu.edu.au>
+License: MIT
+Project-URL: Homepage, https://github.com/thestochasticman/pycopdem
+Project-URL: Repository, https://github.com/thestochasticman/pycopdem
+Project-URL: Issues, https://github.com/thestochasticman/pycopdem/issues
+Keywords: dem,copernicus,elevation,terrain,topography,twi,geospatial
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+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: attrs
+Requires-Dist: typing_extensions
+Requires-Dist: numpy
+Requires-Dist: xarray
+Requires-Dist: zarr
+Requires-Dist: rasterio
+Requires-Dist: affine
+Requires-Dist: pysheds
+Dynamic: license-file
+
+# pycopdem
+
+**Cached [Copernicus GLO-30](https://registry.opendata.aws/copernicus-dem/)
+elevation with on-read terrain derivatives — download once per chunk,
+never twice.** Every elevation pixel this machine ever downloads lands
+in one sparse, chunk-indexed store on the DEM's native 1-arc-second
+grid; slope, aspect, flow accumulation, TWI and Heat Load Index are
+computed on read and never stored. Part of the
+[Borevitz Lab](https://borevitzlab.anu.edu.au/) ecosystem.
+
+## How it works
+
+```
+{data_root}/copdem_store/
+├── index.db      # SQLite ledger: which chunks are populated
+└── dem.zarr      # global sparse array; only written 1200×1200-px chunks exist
+```
+
+- The GLO-30 DEM is served as one COG per 1° × 1° cell on a 1-arc-second
+  EPSG:4326 lattice. The store uses the same lattice globally, chunked
+  at 1200 px (1/3°) — so **3 × 3 chunks nest exactly inside every
+  tile**, and fetching a chunk is a single integer-aligned windowed
+  read from one COG. No resampling, ever.
+- Any bbox maps deterministically to a set of chunk ids.
+  `Store.get_ds(bbox)` diffs them against the ledger and downloads
+  **only the missing chunks**. Elevation is time-invariant, so there's
+  no time axis and no date bookkeeping.
+- A 1° tile absent from S3 is genuinely all ocean: its chunks are
+  stored as nodata and marked complete.
+- Derivatives are a read-time transform (like everything derived in
+  this ecosystem): request them per call, pay compute not disk.
+
+## Usage
+
+The core API is **troi-agnostic** — just a bbox:
+
+```python
+from pycopdem.store import Store
+
+store = Store()
+bbox = [148.36265, -33.52606, 148.38265, -33.50606]  # [W, S, E, N]
+
+ds = store.get_ds(bbox)                              # elevation (lat, lon)
+ds = store.get_ds(bbox, derivatives=('slope', 'aspect', 'twi', 'hli'))
+
+store.fill(bbox)                                     # → 0: already local
+```
+
+Derivatives: `slope` and `aspect` (degrees), `accumulation` (pysheds
+fill-pits → fill-depressions → resolve-flats → flowdir → accumulation),
+`twi` (ln(accumulation / tan slope)), `hli` (McCune & Keon 2002).
+Dependencies resolve automatically — asking for `twi` computes slope
+and accumulation internally.
+
+Pipelines that speak the shared `troi.troi.Troi` use the
+adapters (dates on the troi are ignored — elevation doesn't change):
+
+```python
+ds = store.get_ds_troi(troi, derivatives=('slope',))
+```
+
+`download_terrain(troi)` remains as a thin wrapper.
+
+## Performance
+
+Live measurements against the Copernicus S3 bucket — a ~2 × 2 km AOI
+(one *chunk* = 1200 × 1200 px ≈ 37 × 30 km):
+
+| Scenario | Downloaded | Time |
+|---|---|---|
+| Cold fill | 1 chunk | 10.3 s |
+| Same request again | nothing | **0.0 s** |
+| AOI shifted ~28 km east | 1 new chunk | 4.2 s |
+| Read cached window (1200²) | — | 0.4 s |
+| Read + all 5 derivatives | — | 3.2 s (pysheds dominates) |
+
+Store footprint: ~10 MB for two chunks (~2 200 km² of elevation).
+Absolute times vary with network; the zero is the point — it's a
+ledger lookup, no network involved.
+
+## Install
+
+### pip
+
+```bash
+pip install git+https://github.com/thestochasticman/pycopdem.git
+```
+
+Dependencies (the `troi` core included, pulled from GitHub) are
+declared in `pyproject.toml` and installed automatically.
+
+### From source
+
+```bash
+git clone https://github.com/thestochasticman/pycopdem.git
+cd pycopdem
+pip install -e .
+```
+
+Package design (shared across the lab's packages — no inheritance,
+composition only):
+
+- **`Troi`** (from `troi`) — identity: what region.
+- **`CopernicusDEM`** (`pycopdem.copdem`) — config: tile source.
+- **`Paths`** (`pycopdem.paths`) — derived locations of the store for a
+  given `Config`.
+- **`grid`** — the fixed 1-arc-second grid and tile/chunk nesting
+  (pure, offline-testable math).
+- **`derive`** — the terrain derivatives (pure array math + pysheds).
+- **`Store`** (`pycopdem.store`) — ties them together.
+
+## Test
+
+```bash
+# offline (pure math + synthetic store):
+python pycopdem/grid.py     # True
+python pycopdem/paths.py    # True
+python pycopdem/derive.py   # True
+python pycopdem/store.py    # True
+
+# live (small real reads from the Copernicus S3 bucket):
+python pycopdem/download_terrain.py  # True
+```

pycopdem-0.1.0/pycopdem.egg-info/SOURCES.txt

@@ -0,0 +1,15 @@
+LICENSE
+README.md
+pyproject.toml
+pycopdem/__init__.py
+pycopdem/copdem.py
+pycopdem/derive.py
+pycopdem/download_terrain.py
+pycopdem/grid.py
+pycopdem/paths.py
+pycopdem/store.py
+pycopdem.egg-info/PKG-INFO
+pycopdem.egg-info/SOURCES.txt
+pycopdem.egg-info/dependency_links.txt
+pycopdem.egg-info/requires.txt
+pycopdem.egg-info/top_level.txt

pycopdem-0.1.0/pycopdem.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

pycopdem-0.1.0/pycopdem.egg-info/requires.txt

@@ -0,0 +1,8 @@
+attrs
+typing_extensions
+numpy
+xarray
+zarr
+rasterio
+affine
+pysheds

pycopdem-0.1.0/pycopdem.egg-info/top_level.txt

@@ -0,0 +1 @@
+pycopdem

pycopdem-0.1.0/pyproject.toml

@@ -0,0 +1,55 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "pycopdem"
+version = "0.1.0"
+description = "Cached Copernicus 30 m DEM windows with on-read terrain derivatives — download once per chunk, never twice"
+readme = "README.md"
+authors = [
+  { name = "Borevitz Lab, Australian National University" },
+  { name = "Yasar Adeel Ansari", email = "u6737670@anu.edu.au" },
+]
+license = { text = "MIT" }
+requires-python = ">=3.11"
+keywords = [
+  "dem",
+  "copernicus",
+  "elevation",
+  "terrain",
+  "topography",
+  "twi",
+  "geospatial",
+]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Science/Research",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Scientific/Engineering :: GIS",
+]
+# The geospatial stack (rasterio, pysheds, xarray, zarr, …) is provided by
+# conda via environment.yml; only the lab core is declared here so
+# `pip install -e .` is fast and doesn't re-resolve it.
+dependencies = [
+  "attrs",
+  "typing_extensions",
+  "numpy",
+  "xarray",
+  "zarr",
+  "rasterio",
+  "affine",
+  "pysheds",
+]
+
+[project.urls]
+Homepage = "https://github.com/thestochasticman/pycopdem"
+Repository = "https://github.com/thestochasticman/pycopdem"
+Issues = "https://github.com/thestochasticman/pycopdem/issues"
+
+[tool.setuptools.packages.find]
+include = ["pycopdem", "pycopdem.*"]

pycopdem-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+