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).
