ausdem 0.1.0__tar.gz

ausdem-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sia Ghelichkhan
+
+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.

ausdem-0.1.0/PKG-INFO

@@ -0,0 +1,153 @@
+Metadata-Version: 2.4
+Name: ausdem
+Version: 0.1.0
+Summary: Fetch Australian Digital Elevation Model (DEM) data from Geoscience Australia WCS services as xarray arrays.
+Author-email: Sia Ghelichkhan <ghelichkhani.siavash@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/g-adopt/ausdem
+Project-URL: Repository, https://github.com/g-adopt/ausdem
+Project-URL: Issues, https://github.com/g-adopt/ausdem/issues
+Project-URL: Changelog, https://github.com/g-adopt/ausdem/blob/main/CHANGELOG.md
+Project-URL: Data source, https://www.ga.gov.au/scientific-topics/national-location-information/digital-elevation-data
+Keywords: DEM,elevation,SRTM,LiDAR,Australia,Geoscience Australia,WCS
+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.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: GIS
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.25
+Requires-Dist: numpy
+Requires-Dist: xarray
+Requires-Dist: rioxarray
+Requires-Dist: rasterio
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: matplotlib; extra == "dev"
+Dynamic: license-file
+
+# ausdem
+
+[![CI](https://github.com/g-adopt/ausdem/actions/workflows/test.yml/badge.svg)](https://github.com/g-adopt/ausdem/actions/workflows/test.yml)
+[![PyPI](https://img.shields.io/pypi/v/ausdem.svg)](https://pypi.org/project/ausdem/)
+[![Python versions](https://img.shields.io/pypi/pyversions/ausdem.svg)](https://pypi.org/project/ausdem/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+Fetch Australian Digital Elevation Model (DEM) data from Geoscience Australia
+straight into Python as georeferenced [xarray](https://docs.xarray.dev) arrays.
+
+It talks to GA's public [Web Coverage Services](https://services.ga.gov.au),
+asking only for the bounding box you want rather than downloading whole
+continental tiles. The data and services come from GA's
+[Digital Elevation Data](https://www.ga.gov.au/scientific-topics/national-location-information/digital-elevation-data)
+page.
+
+## Install
+
+```bash
+pip install ausdem
+```
+
+Requires `requests`, `numpy`, `xarray`, `rioxarray` and `rasterio` (pulled in
+automatically).
+
+## Usage
+
+```python
+import ausdem
+
+# A small area around Canberra (min_lon, min_lat, max_lon, max_lat)
+dem = ausdem.get_dem((149.0, -35.4, 149.1, -35.3))
+
+dem.plot()                       # it's a normal xarray DataArray
+print(float(dem.max()))          # highest point in the box
+
+ausdem.save_geotiff(dem, "canberra.tif")   # or: dem.rio.to_raster("canberra.tif")
+```
+
+The returned object is an `xarray.DataArray` with dimensions `(y, x)`, a NaN
+no-data mask, and a `.rio` accessor (CRS, transform, `to_raster`). So you get
+the array for analysis and can drop it to a GeoTIFF whenever you like.
+
+### Choosing a dataset
+
+```python
+ausdem.list_datasets()
+# ['lidar_5m', 'srtm_1s_dem', 'srtm_1s_dem_h']
+
+dem_h = ausdem.get_dem(bbox, dataset="srtm_1s_dem_h")   # hydro-enforced
+lidar = ausdem.get_dem(bbox, dataset="lidar_5m")        # 5 m, where surveyed
+```
+
+| key             | product                                   | resolution |
+|-----------------|-------------------------------------------|------------|
+| `srtm_1s_dem`   | SRTM 1 Second DEM (bare earth), national  | ~30 m      |
+| `srtm_1s_dem_h` | SRTM 1 Second DEM-H (hydro-enforced)      | ~30 m      |
+| `lidar_5m`      | LiDAR-derived 5 m DEM (surveyed areas)    | 5 m        |
+
+The smoothed `DEM-S` product is not served over WCS; download it from the
+[ELVIS portal](https://elevation.fsdf.org.au/). The LiDAR DEM only covers
+surveyed areas (coastal zone, Murray-Darling floodplains, population centres);
+requests outside coverage either come back as a no-data (NaN) tile or raise
+`ausdem.WCSError`, depending on the area.
+
+Pass `resolution=` (in degrees) to resample, e.g. `resolution=0.001` for a
+coarser, lighter grid.
+
+## Command line
+
+```bash
+ausdem 149.0 -35.4 149.1 -35.3 -o canberra.tif
+ausdem 149.0 -35.4 149.1 -35.3 -o canberra_demh.tif -d srtm_1s_dem_h
+ausdem --list
+```
+
+## Notes
+
+Coordinates are decimal degrees. SRTM products are served in WGS84
+(EPSG:4326) and the LiDAR product in GDA94 (EPSG:4283); for input bounding
+boxes the two are interchangeable at this scale. Very large requests are
+rejected client-side to avoid pulling huge rasters by accident; tile your area
+or coarsen the resolution if you hit that.
+
+## Example
+
+There is a small standalone script in [`examples/`](examples/) that fetches a
+DEM and plots it:
+
+```bash
+python examples/plot_dem.py            # a box near Canberra, writes dem.png
+```
+
+## Development
+
+```bash
+git clone https://github.com/g-adopt/ausdem
+cd ausdem
+pip install -e ".[dev]"
+pytest -m "not network"      # offline tests
+pytest                        # include the live GA WCS test
+```
+
+## License
+
+MIT, see [LICENSE](LICENSE).
+
+## Citation
+
+If you use ausdem in your work, please cite it. Release archives are deposited
+on Zenodo and a DOI will be added here after the first release; in the meantime
+see [CITATION.cff](CITATION.cff).

ausdem-0.1.0/README.md

@@ -0,0 +1,112 @@
+# ausdem
+
+[![CI](https://github.com/g-adopt/ausdem/actions/workflows/test.yml/badge.svg)](https://github.com/g-adopt/ausdem/actions/workflows/test.yml)
+[![PyPI](https://img.shields.io/pypi/v/ausdem.svg)](https://pypi.org/project/ausdem/)
+[![Python versions](https://img.shields.io/pypi/pyversions/ausdem.svg)](https://pypi.org/project/ausdem/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+Fetch Australian Digital Elevation Model (DEM) data from Geoscience Australia
+straight into Python as georeferenced [xarray](https://docs.xarray.dev) arrays.
+
+It talks to GA's public [Web Coverage Services](https://services.ga.gov.au),
+asking only for the bounding box you want rather than downloading whole
+continental tiles. The data and services come from GA's
+[Digital Elevation Data](https://www.ga.gov.au/scientific-topics/national-location-information/digital-elevation-data)
+page.
+
+## Install
+
+```bash
+pip install ausdem
+```
+
+Requires `requests`, `numpy`, `xarray`, `rioxarray` and `rasterio` (pulled in
+automatically).
+
+## Usage
+
+```python
+import ausdem
+
+# A small area around Canberra (min_lon, min_lat, max_lon, max_lat)
+dem = ausdem.get_dem((149.0, -35.4, 149.1, -35.3))
+
+dem.plot()                       # it's a normal xarray DataArray
+print(float(dem.max()))          # highest point in the box
+
+ausdem.save_geotiff(dem, "canberra.tif")   # or: dem.rio.to_raster("canberra.tif")
+```
+
+The returned object is an `xarray.DataArray` with dimensions `(y, x)`, a NaN
+no-data mask, and a `.rio` accessor (CRS, transform, `to_raster`). So you get
+the array for analysis and can drop it to a GeoTIFF whenever you like.
+
+### Choosing a dataset
+
+```python
+ausdem.list_datasets()
+# ['lidar_5m', 'srtm_1s_dem', 'srtm_1s_dem_h']
+
+dem_h = ausdem.get_dem(bbox, dataset="srtm_1s_dem_h")   # hydro-enforced
+lidar = ausdem.get_dem(bbox, dataset="lidar_5m")        # 5 m, where surveyed
+```
+
+| key             | product                                   | resolution |
+|-----------------|-------------------------------------------|------------|
+| `srtm_1s_dem`   | SRTM 1 Second DEM (bare earth), national  | ~30 m      |
+| `srtm_1s_dem_h` | SRTM 1 Second DEM-H (hydro-enforced)      | ~30 m      |
+| `lidar_5m`      | LiDAR-derived 5 m DEM (surveyed areas)    | 5 m        |
+
+The smoothed `DEM-S` product is not served over WCS; download it from the
+[ELVIS portal](https://elevation.fsdf.org.au/). The LiDAR DEM only covers
+surveyed areas (coastal zone, Murray-Darling floodplains, population centres);
+requests outside coverage either come back as a no-data (NaN) tile or raise
+`ausdem.WCSError`, depending on the area.
+
+Pass `resolution=` (in degrees) to resample, e.g. `resolution=0.001` for a
+coarser, lighter grid.
+
+## Command line
+
+```bash
+ausdem 149.0 -35.4 149.1 -35.3 -o canberra.tif
+ausdem 149.0 -35.4 149.1 -35.3 -o canberra_demh.tif -d srtm_1s_dem_h
+ausdem --list
+```
+
+## Notes
+
+Coordinates are decimal degrees. SRTM products are served in WGS84
+(EPSG:4326) and the LiDAR product in GDA94 (EPSG:4283); for input bounding
+boxes the two are interchangeable at this scale. Very large requests are
+rejected client-side to avoid pulling huge rasters by accident; tile your area
+or coarsen the resolution if you hit that.
+
+## Example
+
+There is a small standalone script in [`examples/`](examples/) that fetches a
+DEM and plots it:
+
+```bash
+python examples/plot_dem.py            # a box near Canberra, writes dem.png
+```
+
+## Development
+
+```bash
+git clone https://github.com/g-adopt/ausdem
+cd ausdem
+pip install -e ".[dev]"
+pytest -m "not network"      # offline tests
+pytest                        # include the live GA WCS test
+```
+
+## License
+
+MIT, see [LICENSE](LICENSE).
+
+## Citation
+
+If you use ausdem in your work, please cite it. Release archives are deposited
+on Zenodo and a DOI will be added here after the first release; in the meantime
+see [CITATION.cff](CITATION.cff).

ausdem-0.1.0/ausdem/__init__.py

@@ -0,0 +1,27 @@
+"""ausdem: fetch Australian DEM data from Geoscience Australia WCS services.
+
+Quick start
+-----------
+>>> import ausdem
+>>> dem = ausdem.get_dem((149.0, -35.4, 149.1, -35.3))   # around Canberra
+>>> ausdem.save_geotiff(dem, "canberra.tif")
+
+See :func:`ausdem.list_datasets` for the available DEM products.
+"""
+
+from .client import WCSError
+from .core import get_dem, save_geotiff
+from .datasets import DATASETS, DEFAULT_DATASET, get_dataset, list_datasets
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "get_dem",
+    "save_geotiff",
+    "list_datasets",
+    "get_dataset",
+    "DATASETS",
+    "DEFAULT_DATASET",
+    "WCSError",
+    "__version__",
+]

ausdem-0.1.0/ausdem/cli.py

@@ -0,0 +1,76 @@
+"""Command-line interface: ``ausdem`` downloads a DEM to a GeoTIFF."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+from .core import get_dem, save_geotiff
+from .datasets import DATASETS, DEFAULT_DATASET, list_datasets
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog="ausdem",
+        description="Fetch Australian DEM data from Geoscience Australia.",
+    )
+    p.add_argument(
+        "bbox",
+        nargs=4,
+        type=float,
+        metavar=("MIN_LON", "MIN_LAT", "MAX_LON", "MAX_LAT"),
+        help="Bounding box in decimal degrees.",
+    )
+    p.add_argument("-o", "--output", required=True, help="Output GeoTIFF path.")
+    p.add_argument(
+        "-d",
+        "--dataset",
+        default=DEFAULT_DATASET,
+        choices=list_datasets(),
+        help=f"DEM product (default: {DEFAULT_DATASET}).",
+    )
+    p.add_argument(
+        "-r",
+        "--resolution",
+        type=float,
+        default=None,
+        help="Output pixel size in degrees (default: dataset native).",
+    )
+    p.add_argument(
+        "--list",
+        action="store_true",
+        help="List available datasets and exit.",
+    )
+    return p
+
+
+def main(argv: list[str] | None = None) -> int:
+    argv = list(sys.argv[1:] if argv is None else argv)
+
+    if "--list" in argv:
+        for key in list_datasets():
+            print(f"{key:16s}  {DATASETS[key].title}")
+            print(f"{'':16s}  {DATASETS[key].description}")
+        return 0
+
+    args = _build_parser().parse_args(argv)
+    try:
+        dem = get_dem(
+            tuple(args.bbox),
+            dataset=args.dataset,
+            resolution=args.resolution,
+        )
+        save_geotiff(dem, args.output)
+    except Exception as exc:  # surface a clean message, not a traceback
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+
+    print(
+        f"wrote {args.output}  [{args.dataset}] "
+        f"shape={tuple(dem.sizes[d] for d in ('y', 'x'))}"
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

ausdem-0.1.0/ausdem/client.py

@@ -0,0 +1,89 @@
+"""Low-level WCS GetCoverage client for the Geoscience Australia DEM services.
+
+The GA services are ArcGIS MapServer WCS endpoints. WCS 2.0.1 GetCoverage is
+unreliable on these endpoints, but WCS 1.0.0 ``GetCoverage`` returns a clean
+32-bit float GeoTIFF, so that is what we use here.
+"""
+
+from __future__ import annotations
+
+from typing import Tuple
+
+import requests
+
+from .datasets import Dataset
+
+# ArcGIS returns an HTML/XML error body (not a TIFF) when a request is invalid
+# or falls entirely outside the data extent.
+_TIFF_MAGIC = (b"II*\x00", b"MM\x00*")
+
+
+class WCSError(RuntimeError):
+    """Raised when the WCS service returns an error instead of a coverage."""
+
+
+def _parse_error(content: bytes) -> str:
+    """Extract a human-readable message from an ArcGIS error body."""
+    text = content.decode("utf-8", errors="replace")
+    # Strip tags so both the ArcGIS HTML and OGC XML errors read cleanly.
+    import re
+
+    text = re.sub(r"<[^>]+>", " ", text)
+    text = " ".join(text.split())
+    return text[:500] if text else "empty response"
+
+
+def get_coverage(
+    dataset: Dataset,
+    bbox: Tuple[float, float, float, float],
+    res_x: float,
+    res_y: float,
+    timeout: float = 120.0,
+    session: requests.Session | None = None,
+) -> bytes:
+    """Issue a WCS 1.0.0 GetCoverage request and return GeoTIFF bytes.
+
+    Parameters
+    ----------
+    dataset:
+        The :class:`~ausdem.datasets.Dataset` to query.
+    bbox:
+        ``(min_lon, min_lat, max_lon, max_lat)`` in the dataset's request CRS.
+    res_x, res_y:
+        Output pixel size in CRS units (degrees).
+    timeout:
+        Per-request timeout in seconds.
+    session:
+        Optional :class:`requests.Session` for connection reuse.
+
+    Returns
+    -------
+    bytes
+        The raw GeoTIFF payload.
+    """
+    min_x, min_y, max_x, max_y = bbox
+    params = {
+        "service": "WCS",
+        "version": "1.0.0",
+        "request": "GetCoverage",
+        "coverage": dataset.coverage,
+        "CRS": dataset.crs,
+        "RESPONSE_CRS": dataset.crs,
+        "BBOX": f"{min_x},{min_y},{max_x},{max_y}",
+        "RESX": repr(res_x),
+        "RESY": repr(res_y),
+        "FORMAT": "GeoTIFF",
+    }
+
+    http = session or requests
+    resp = http.get(dataset.url, params=params, timeout=timeout)
+    resp.raise_for_status()
+
+    content = resp.content
+    if not content.startswith(_TIFF_MAGIC):
+        raise WCSError(
+            f"{dataset.key}: service did not return a GeoTIFF. "
+            f"This usually means the bounding box is outside the data extent "
+            f"or too large. Service said: {_parse_error(content)}"
+        )
+    return content

ausdem-0.1.0/ausdem/core.py

@@ -0,0 +1,127 @@
+"""High-level API: fetch a DEM as an xarray DataArray and save it as GeoTIFF."""
+
+from __future__ import annotations
+
+import math
+from typing import Tuple
+
+import numpy as np
+import rioxarray  # noqa: F401  (registers the .rio accessor on xarray objects)
+import xarray as xr
+
+from .client import get_coverage
+from .datasets import DEFAULT_DATASET, get_dataset, list_datasets  # noqa: F401
+
+# Values at or below this magnitude are treated as the float "no data" sentinel
+# that the GA services use for sea / outside-coverage pixels.
+_NODATA_THRESHOLD = -1e30
+
+# Refuse absurdly large requests by default so a typo in the bbox does not pull
+# hundreds of megapixels off the service.
+_MAX_PIXELS = 25_000_000
+
+
+def _open_geotiff(content: bytes, mask: bool) -> xr.DataArray:
+    """Decode GeoTIFF bytes into an in-memory, georeferenced DataArray."""
+    from rasterio.io import MemoryFile
+
+    with MemoryFile(content) as memfile:
+        with memfile.open() as src:
+            da = rioxarray.open_rasterio(src).load()
+
+    # Collapse the singleton band dimension: a DEM is a single 2-D surface.
+    if "band" in da.dims and da.sizes["band"] == 1:
+        da = da.squeeze("band", drop=True)
+
+    da = da.astype("float32")
+    if mask:
+        sentinel = (da <= _NODATA_THRESHOLD) | da.isnull()
+        da = da.where(~sentinel)
+    da.rio.write_nodata(np.nan, inplace=True)
+    da.name = "elevation"
+    da.attrs.setdefault("units", "m")
+    return da
+
+
+def get_dem(
+    bbox: Tuple[float, float, float, float],
+    dataset: str = DEFAULT_DATASET,
+    resolution: float | Tuple[float, float] | None = None,
+    mask: bool = True,
+    timeout: float = 120.0,
+) -> xr.DataArray:
+    """Fetch a DEM for ``bbox`` and return it as an xarray DataArray.
+
+    Parameters
+    ----------
+    bbox:
+        ``(min_lon, min_lat, max_lon, max_lat)`` in decimal degrees.
+    dataset:
+        Dataset key. One of :func:`ausdem.list_datasets` (default
+        ``"srtm_1s_dem"``). Use ``"srtm_1s_dem_h"`` for the hydrologically
+        enforced surface or ``"lidar_5m"`` for the 5 m LiDAR DEM where covered.
+    resolution:
+        Output pixel size in degrees. A single float sets both axes; a
+        ``(res_x, res_y)`` tuple sets them independently. Defaults to the
+        dataset's native resolution.
+    mask:
+        If True (default), replace the service's no-data sentinel with NaN.
+    timeout:
+        Per-request timeout in seconds.
+
+    Returns
+    -------
+    xarray.DataArray
+        A georeferenced 2-D array (``y``, ``x``) with a ``.rio`` accessor.
+        Save it with :func:`save_geotiff` or ``da.rio.to_raster("out.tif")``.
+
+    Examples
+    --------
+    >>> import ausdem
+    >>> dem = ausdem.get_dem((149.0, -35.4, 149.1, -35.3))
+    >>> dem.shape
+    (360, 360)
+    >>> ausdem.save_geotiff(dem, "canberra.tif")
+    """
+    ds = get_dataset(dataset)
+
+    min_lon, min_lat, max_lon, max_lat = bbox
+    if min_lon >= max_lon or min_lat >= max_lat:
+        raise ValueError(
+            "bbox must be (min_lon, min_lat, max_lon, max_lat) with "
+            f"min < max; got {bbox!r}"
+        )
+
+    if resolution is None:
+        res_x, res_y = ds.res_x, ds.res_y
+    elif isinstance(resolution, (int, float)):
+        res_x = res_y = float(resolution)
+    else:
+        res_x, res_y = (float(v) for v in resolution)
+    if res_x <= 0 or res_y <= 0:
+        raise ValueError(f"resolution must be positive; got {resolution!r}")
+
+    n_pixels = math.ceil((max_lon - min_lon) / res_x) * math.ceil(
+        (max_lat - min_lat) / res_y
+    )
+    if n_pixels > _MAX_PIXELS:
+        raise ValueError(
+            f"Request would be ~{n_pixels:,} pixels (> {_MAX_PIXELS:,}). "
+            "Use a smaller bbox or a coarser `resolution`."
+        )
+
+    content = get_coverage(ds, bbox, res_x, res_y, timeout=timeout)
+    da = _open_geotiff(content, mask=mask)
+    da.attrs["dataset"] = ds.key
+    da.attrs["source"] = ds.title
+    da.attrs["service_url"] = ds.url
+    return da
+
+
+def save_geotiff(da: xr.DataArray, path: str) -> str:
+    """Write a DataArray returned by :func:`get_dem` to a GeoTIFF file.
+
+    Returns the path written, so it can be used inline.
+    """
+    da.rio.to_raster(path)
+    return path

ausdem-0.1.0/ausdem/datasets.py

@@ -0,0 +1,118 @@
+"""Registry of Geoscience Australia DEM datasets exposed over WCS.
+
+Each entry describes a Web Coverage Service (WCS) endpoint published by
+Geoscience Australia together with the metadata needed to issue a
+``GetCoverage`` request: the coverage identifier, the coordinate reference
+system the service accepts for requests, and the native ground resolution.
+
+The catalogue page these come from is:
+https://www.ga.gov.au/scientific-topics/national-location-information/digital-elevation-data
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+_BASE = "https://services.ga.gov.au/gis/services/{service}/MapServer/WCSServer"
+
+
+@dataclass(frozen=True)
+class Dataset:
+    """Description of a single GA DEM coverage served over WCS."""
+
+    key: str
+    title: str
+    service: str
+    #: Coverage identifier used by the WCS 1.0.0 ``coverage`` parameter.
+    coverage: str
+    #: CRS the service accepts for request BBOX and output (EPSG code).
+    crs: str
+    #: Native pixel size in CRS units (degrees) along x and y.
+    res_x: float
+    res_y: float
+    description: str
+
+    @property
+    def url(self) -> str:
+        return _BASE.format(service=self.service)
+
+
+# One arc-second is 1/3600 of a degree.
+_ARCSEC = 1.0 / 3600.0
+
+DATASETS = {
+    "srtm_1s_dem": Dataset(
+        key="srtm_1s_dem",
+        title="SRTM-derived 1 Second DEM (bare earth)",
+        service="DEM_SRTM_1Second_2024",
+        coverage="1",
+        crs="EPSG:4326",
+        res_x=_ARCSEC,
+        res_y=_ARCSEC,
+        description=(
+            "National ~30 m bare-earth Digital Elevation Model derived from the "
+            "February 2000 Shuttle Radar Topography Mission, with vegetation "
+            "offsets removed."
+        ),
+    ),
+    "srtm_1s_dem_h": Dataset(
+        key="srtm_1s_dem_h",
+        title="SRTM-derived 1 Second DEM-H (hydrologically enforced)",
+        service="DEM_SRTM_1Second_Hydro_Enforced_2024",
+        coverage="1",
+        crs="EPSG:4326",
+        res_x=_ARCSEC,
+        res_y=_ARCSEC,
+        description=(
+            "National ~30 m hydrologically enforced DEM (DEM-H): the smoothed "
+            "SRTM DEM conditioned with drainage enforcement so that water flows "
+            "consistently downhill. Best choice for hydrological modelling."
+        ),
+    ),
+    "lidar_5m": Dataset(
+        key="lidar_5m",
+        title="LiDAR-derived 5 m DEM of Australia",
+        service="DEM_LiDAR_5m_2025",
+        coverage="1",
+        # This service only accepts GDA94 geographic (EPSG:4283), not 4326.
+        crs="EPSG:4283",
+        res_x=5.5063478185957097e-05,
+        res_y=5.16012325277870332e-05,
+        description=(
+            "5 m bare-earth DEM compiled from 200+ LiDAR surveys (2001-2015). "
+            "Coverage is limited to surveyed areas: the populated coastal zone, "
+            "the Murray-Darling floodplains and individual population centres. "
+            "Requests outside surveyed areas return no data."
+        ),
+    ),
+}
+
+#: Datasets that exist in the SRTM 1 Second package but are NOT served over WCS
+#: (download-only via the ELVIS portal). Kept here for discoverability.
+DOWNLOAD_ONLY = {
+    "srtm_1s_dem_s": (
+        "SRTM-derived 1 Second DEM-S (smoothed). Not available as a WCS "
+        "coverage; download from the ELVIS portal: https://elevation.fsdf.org.au/"
+    ),
+}
+
+DEFAULT_DATASET = "srtm_1s_dem"
+
+
+def get_dataset(key: str) -> Dataset:
+    """Return the :class:`Dataset` for ``key`` or raise a helpful error."""
+    try:
+        return DATASETS[key]
+    except KeyError:
+        available = ", ".join(sorted(DATASETS))
+        hint = ""
+        if key in DOWNLOAD_ONLY:
+            hint = f"\n'{key}' is download-only: {DOWNLOAD_ONLY[key]}"
+        raise KeyError(
+            f"Unknown dataset '{key}'. Available WCS datasets: {available}.{hint}"
+        ) from None
+
+
+def list_datasets() -> list[str]:
+    """Return the keys of all datasets available over WCS."""
+    return sorted(DATASETS)

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

@@ -0,0 +1,153 @@
+Metadata-Version: 2.4
+Name: ausdem
+Version: 0.1.0
+Summary: Fetch Australian Digital Elevation Model (DEM) data from Geoscience Australia WCS services as xarray arrays.
+Author-email: Sia Ghelichkhan <ghelichkhani.siavash@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/g-adopt/ausdem
+Project-URL: Repository, https://github.com/g-adopt/ausdem
+Project-URL: Issues, https://github.com/g-adopt/ausdem/issues
+Project-URL: Changelog, https://github.com/g-adopt/ausdem/blob/main/CHANGELOG.md
+Project-URL: Data source, https://www.ga.gov.au/scientific-topics/national-location-information/digital-elevation-data
+Keywords: DEM,elevation,SRTM,LiDAR,Australia,Geoscience Australia,WCS
+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.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: GIS
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.25
+Requires-Dist: numpy
+Requires-Dist: xarray
+Requires-Dist: rioxarray
+Requires-Dist: rasterio
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: matplotlib; extra == "dev"
+Dynamic: license-file
+
+# ausdem
+
+[![CI](https://github.com/g-adopt/ausdem/actions/workflows/test.yml/badge.svg)](https://github.com/g-adopt/ausdem/actions/workflows/test.yml)
+[![PyPI](https://img.shields.io/pypi/v/ausdem.svg)](https://pypi.org/project/ausdem/)
+[![Python versions](https://img.shields.io/pypi/pyversions/ausdem.svg)](https://pypi.org/project/ausdem/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+Fetch Australian Digital Elevation Model (DEM) data from Geoscience Australia
+straight into Python as georeferenced [xarray](https://docs.xarray.dev) arrays.
+
+It talks to GA's public [Web Coverage Services](https://services.ga.gov.au),
+asking only for the bounding box you want rather than downloading whole
+continental tiles. The data and services come from GA's
+[Digital Elevation Data](https://www.ga.gov.au/scientific-topics/national-location-information/digital-elevation-data)
+page.
+
+## Install
+
+```bash
+pip install ausdem
+```
+
+Requires `requests`, `numpy`, `xarray`, `rioxarray` and `rasterio` (pulled in
+automatically).
+
+## Usage
+
+```python
+import ausdem
+
+# A small area around Canberra (min_lon, min_lat, max_lon, max_lat)
+dem = ausdem.get_dem((149.0, -35.4, 149.1, -35.3))
+
+dem.plot()                       # it's a normal xarray DataArray
+print(float(dem.max()))          # highest point in the box
+
+ausdem.save_geotiff(dem, "canberra.tif")   # or: dem.rio.to_raster("canberra.tif")
+```
+
+The returned object is an `xarray.DataArray` with dimensions `(y, x)`, a NaN
+no-data mask, and a `.rio` accessor (CRS, transform, `to_raster`). So you get
+the array for analysis and can drop it to a GeoTIFF whenever you like.
+
+### Choosing a dataset
+
+```python
+ausdem.list_datasets()
+# ['lidar_5m', 'srtm_1s_dem', 'srtm_1s_dem_h']
+
+dem_h = ausdem.get_dem(bbox, dataset="srtm_1s_dem_h")   # hydro-enforced
+lidar = ausdem.get_dem(bbox, dataset="lidar_5m")        # 5 m, where surveyed
+```
+
+| key             | product                                   | resolution |
+|-----------------|-------------------------------------------|------------|
+| `srtm_1s_dem`   | SRTM 1 Second DEM (bare earth), national  | ~30 m      |
+| `srtm_1s_dem_h` | SRTM 1 Second DEM-H (hydro-enforced)      | ~30 m      |
+| `lidar_5m`      | LiDAR-derived 5 m DEM (surveyed areas)    | 5 m        |
+
+The smoothed `DEM-S` product is not served over WCS; download it from the
+[ELVIS portal](https://elevation.fsdf.org.au/). The LiDAR DEM only covers
+surveyed areas (coastal zone, Murray-Darling floodplains, population centres);
+requests outside coverage either come back as a no-data (NaN) tile or raise
+`ausdem.WCSError`, depending on the area.
+
+Pass `resolution=` (in degrees) to resample, e.g. `resolution=0.001` for a
+coarser, lighter grid.
+
+## Command line
+
+```bash
+ausdem 149.0 -35.4 149.1 -35.3 -o canberra.tif
+ausdem 149.0 -35.4 149.1 -35.3 -o canberra_demh.tif -d srtm_1s_dem_h
+ausdem --list
+```
+
+## Notes
+
+Coordinates are decimal degrees. SRTM products are served in WGS84
+(EPSG:4326) and the LiDAR product in GDA94 (EPSG:4283); for input bounding
+boxes the two are interchangeable at this scale. Very large requests are
+rejected client-side to avoid pulling huge rasters by accident; tile your area
+or coarsen the resolution if you hit that.
+
+## Example
+
+There is a small standalone script in [`examples/`](examples/) that fetches a
+DEM and plots it:
+
+```bash
+python examples/plot_dem.py            # a box near Canberra, writes dem.png
+```
+
+## Development
+
+```bash
+git clone https://github.com/g-adopt/ausdem
+cd ausdem
+pip install -e ".[dev]"
+pytest -m "not network"      # offline tests
+pytest                        # include the live GA WCS test
+```
+
+## License
+
+MIT, see [LICENSE](LICENSE).
+
+## Citation
+
+If you use ausdem in your work, please cite it. Release archives are deposited
+on Zenodo and a DOI will be added here after the first release; in the meantime
+see [CITATION.cff](CITATION.cff).

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

@@ -0,0 +1,15 @@
+LICENSE
+README.md
+pyproject.toml
+ausdem/__init__.py
+ausdem/cli.py
+ausdem/client.py
+ausdem/core.py
+ausdem/datasets.py
+ausdem.egg-info/PKG-INFO
+ausdem.egg-info/SOURCES.txt
+ausdem.egg-info/dependency_links.txt
+ausdem.egg-info/entry_points.txt
+ausdem.egg-info/requires.txt
+ausdem.egg-info/top_level.txt
+tests/test_ausdem.py

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

@@ -0,0 +1 @@
+

ausdem-0.1.0/ausdem.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+ausdem = ausdem.cli:main

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

@@ -0,0 +1,15 @@
+requests>=2.25
+numpy
+xarray
+rioxarray
+rasterio
+
+[dev]
+pytest
+build
+twine
+ruff
+matplotlib
+
+[test]
+pytest

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

@@ -0,0 +1 @@
+ausdem

ausdem-0.1.0/pyproject.toml

@@ -0,0 +1,59 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "ausdem"
+dynamic = ["version"]
+description = "Fetch Australian Digital Elevation Model (DEM) data from Geoscience Australia WCS services as xarray arrays."
+readme = "README.md"
+requires-python = ">=3.9"
+authors = [{ name = "Sia Ghelichkhan", email = "ghelichkhani.siavash@gmail.com" }]
+license = { text = "MIT" }
+keywords = ["DEM", "elevation", "SRTM", "LiDAR", "Australia", "Geoscience Australia", "WCS"]
+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.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering :: GIS",
+]
+dependencies = [
+    "requests>=2.25",
+    "numpy",
+    "xarray",
+    "rioxarray",
+    "rasterio",
+]
+
+[project.optional-dependencies]
+test = ["pytest"]
+dev = ["pytest", "build", "twine", "ruff", "matplotlib"]
+
+[project.scripts]
+ausdem = "ausdem.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/g-adopt/ausdem"
+Repository = "https://github.com/g-adopt/ausdem"
+Issues = "https://github.com/g-adopt/ausdem/issues"
+Changelog = "https://github.com/g-adopt/ausdem/blob/main/CHANGELOG.md"
+"Data source" = "https://www.ga.gov.au/scientific-topics/national-location-information/digital-elevation-data"
+
+[tool.setuptools.dynamic]
+version = { attr = "ausdem.__version__" }
+
+[tool.setuptools.packages.find]
+include = ["ausdem*"]
+
+[tool.pytest.ini_options]
+markers = ["network: test that hits the live GA WCS service"]
+
+[tool.ruff]
+line-length = 88

ausdem-0.1.0/setup.cfg

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

ausdem-0.1.0/tests/test_ausdem.py

@@ -0,0 +1,71 @@
+"""Tests for ausdem.
+
+The network test is marked so it can be skipped offline:
+    pytest -m "not network"
+"""
+
+import numpy as np
+import pytest
+
+import ausdem
+from ausdem import core
+
+
+def test_list_datasets():
+    keys = ausdem.list_datasets()
+    assert "srtm_1s_dem" in keys
+    assert "srtm_1s_dem_h" in keys
+    assert "lidar_5m" in keys
+
+
+def test_unknown_dataset_hint():
+    with pytest.raises(KeyError):
+        ausdem.get_dataset("does_not_exist")
+    # DEM-S should point the user at the download-only note.
+    with pytest.raises(KeyError, match="download-only"):
+        ausdem.get_dataset("srtm_1s_dem_s")
+
+
+def test_bad_bbox():
+    with pytest.raises(ValueError):
+        ausdem.get_dem((149.1, -35.4, 149.0, -35.3))  # min_lon > max_lon
+
+
+def test_pixel_guard():
+    # Continental bbox at native res blows past the pixel cap before any I/O.
+    with pytest.raises(ValueError, match="pixels"):
+        ausdem.get_dem((113.0, -44.0, 154.0, -10.0), resolution=0.0002777)
+
+
+def test_open_geotiff_masks_sentinel():
+    # Build a tiny GeoTIFF in memory with a sentinel value and check masking.
+    from rasterio.io import MemoryFile
+    from rasterio.transform import from_origin
+
+    data = np.array([[10.0, -3.4e38], [20.0, 30.0]], dtype="float32")
+    with MemoryFile() as mem:
+        with mem.open(
+            driver="GTiff",
+            height=2,
+            width=2,
+            count=1,
+            dtype="float32",
+            crs="EPSG:4326",
+            transform=from_origin(149.0, -35.0, 0.1, 0.1),
+        ) as dst:
+            dst.write(data, 1)
+        content = mem.read()
+
+    da = core._open_geotiff(content, mask=True)
+    assert da.name == "elevation"
+    assert bool(np.isnan(da.values).any())
+    assert np.nanmax(da.values) == 30.0
+
+
+@pytest.mark.network
+def test_get_dem_live():
+    dem = ausdem.get_dem((149.0, -35.4, 149.1, -35.3))
+    assert dem.dims == ("y", "x")
+    assert dem.rio.crs is not None
+    assert np.isfinite(dem.values).any()
+    assert dem.attrs["dataset"] == "srtm_1s_dem"