Metadata-Version: 2.4
Name: xcorduroy
Version: 0.0.3
Summary: Dask aware lightweight DEM utilities for Xarray
Keywords: dem,terrain,hillshade,slope,aspect,xarray,dask
Author: Raphael Hagen
Author-email: Raphael Hagen <norlandrhagen@gmail.com>
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: GIS
Classifier: Typing :: Typed
Requires-Dist: dask>=2024.1.0
Requires-Dist: numpy>=2.1.0
Requires-Dist: xarray>=2025.9.0
Requires-Dist: xproj>=0.2.1
Requires-Python: >=3.12
Project-URL: Homepage, https://norlandrhagen.github.io/corduroy/
Project-URL: Documentation, https://norlandrhagen.github.io/corduroy/
Project-URL: Repository, https://github.com/norlandrhagen/corduroy
Project-URL: Issues, https://github.com/norlandrhagen/corduroy/issues
Description-Content-Type: text/markdown

# xcorduroy

**Dask aware lightweight DEM utilities for Xarray**

[Documentation](https://norlandrhagen.github.io/corduroy/) ·
[Usage](https://norlandrhagen.github.io/corduroy/usage/) ·
[Design](https://norlandrhagen.github.io/corduroy/design/) ·
[API](https://norlandrhagen.github.io/corduroy/api/)

`xcorduroy` is a small Xarray accessor for computing hillshade, slope and aspect
from DEMs, with `dask`, `numpy`, `xarray` and `xproj` as its only dependencies.
Gradients use the Horn (1981) 3x3 kernel; aspect and hillshade follow the
ESRI/GDAL conventions (not numerically cross-checked against `gdaldem`). Chunked arrays are
handled with a dask halo, so lazy and in-memory results are identical.

> **Warning:** experimental. APIs may change without notice.

## Installation

```bash
uv add xcorduroy
# or
pip install xcorduroy
```

## Example

```python
import xarray as xr
import xproj    # registers the .proj accessor
import xcorduroy  # registers the .dem accessor

ds = xr.open_dataset("DEM.zarr", engine="zarr", chunks="auto")
ds = ds.proj.assign_crs(spatial_ref="EPSG:4326")

slope = ds["dem"].dem.slope()          # degrees, 0-90
aspect = ds["dem"].dem.aspect()        # degrees clockwise from north; flat cells NaN
hillshade = ds["dem"].dem.hillshade()  # 0-1, light from azimuth 315 / altitude 45
```

A plotted, runnable version is in `notebooks/DEM_example.ipynb`. See
[Usage](https://norlandrhagen.github.io/corduroy/usage/) for `resolution=`,
`z_factor=`, dimension naming and chunking, and
[Design](https://norlandrhagen.github.io/corduroy/design/) for the conventions
and the degree-to-metre approximation.

## Scope

The methods are inspired by `xdem` and `xarray-spatial`. If you need
well-validated functions for scientific analysis, use one of those. This is a
limited-scope, lightweight take on a few of the methods, not a replacement.

## Development

```bash
uv sync --all-groups
uv run pytest tests -n auto     # tests
uv run ty check src/            # type check
uv run prek run --all-files     # lint and format
uv run mkdocs serve             # docs preview
```

See [Contributing](https://norlandrhagen.github.io/corduroy/contributing/).

## What's in the name

Corduroy is the textured snow surface left by groomers, regular peaks and
valleys.
