terrand/
lib.rs

1#![forbid(unsafe_code)]
2#![deny(missing_docs)]
3
4//! **terrand** — Pure-Rust terrain analysis on ndarray.
5//!
6//! Provides DEM (Digital Elevation Model) analysis without GDAL or any C
7//! dependencies. All operations take `ndarray::Array2<f64>` as input and
8//! return ndarray arrays as output, making them composable with the rest of
9//! the Rust scientific computing ecosystem.
10//!
11//! # Modules
12//!
13//! | Module | Operations |
14//! |--------|-----------|
15//! | [`slope`](mod@slope) | Slope in degrees, radians, or percent |
16//! | [`aspect`](mod@aspect) | Slope direction as compass bearing |
17//! | [`curvature`](mod@curvature) | Profile, plan, and general curvature |
18//! | [`hillshade`](mod@hillshade) | Shaded-relief illumination |
19//! | [`roughness`](mod@roughness) | TRI, TPI, and surface roughness |
20//! | [`hydrology`](mod@hydrology) | Fill, flow direction, accumulation, watershed, basin, stream order |
21//! | [`viewshed`](mod@viewshed) | Line-of-sight visibility analysis |
22//! | [`contour`](mod@contour) | Marching-squares contour generation |
23//!
24//! # Quick start
25//!
26//! ```
27//! use ndarray::Array2;
28//! use terrand::{slope, aspect, hillshade, CellSize};
29//!
30//! // A synthetic DEM with a uniform east-facing slope.
31//! let dem = Array2::from_shape_fn((100, 100), |(_, c)| c as f64 * 10.0);
32//! let cell = CellSize::square(30.0).unwrap();
33//!
34//! let s = slope(&dem, cell);
35//! let a = aspect(&dem, cell);
36//! let hs = hillshade(&dem, cell, 315.0, 45.0);
37//! ```
38//!
39//! # Parallelism
40//!
41//! Enable the `parallel` feature to use Rayon for multi-threaded computation
42//! on all per-cell operations:
43//!
44//! ```toml
45//! [dependencies]
46//! terrand = { package = "terrand-rs", version = "0.1", features = ["parallel"] }
47//! ```
48//!
49//! # NaN and nodata handling
50//!
51//! NaN handling is operation-specific. Surface-analysis kernels generally
52//! propagate `NaN` through their 3x3 arithmetic on normal-size grids, but their
53//! small-grid fallbacks return documented flat values. Hydrology treats `NaN`
54//! as nodata for elevation rasters: `fill` leaves `NaN` cells unchanged, while
55//! `flow_direction` encodes `NaN` cells as direction `0`. Contour generation
56//! treats `NaN` cells as holes and skips quads containing them.
57//!
58//! # Algorithms
59//!
60//! Slope, aspect, and hillshade use the Horn (1981) 3x3 weighted gradient
61//! kernel with GDAL-compatible linear extrapolation at grid edges. Curvature
62//! uses Horn first-order gradients with the same edge extrapolation, plus
63//! finite-difference second derivatives clamped at grid edges.
64
65// Internal modules (not part of public API).
66mod kernel;
67
68// Public modules.
69pub mod aspect;
70pub mod cell_size;
71pub mod contour;
72pub mod curvature;
73pub mod error;
74pub mod hillshade;
75pub mod hydrology;
76pub mod roughness;
77pub mod slope;
78pub mod viewshed;
79
80// Re-export primary types and functions at crate root for ergonomic access.
81pub use aspect::{aspect, ASPECT_FLAT};
82pub use cell_size::CellSize;
83pub use curvature::{general_curvature, plan_curvature, profile_curvature};
84pub use error::{Error, Result};
85pub use hillshade::hillshade;
86pub use hydrology::{
87    basin, fill, flow_accumulation, flow_direction, snap_pour_point, stream_order_strahler,
88    watershed,
89};
90pub use roughness::{roughness, tpi, tri};
91pub use slope::{slope, slope_percent, slope_radians};
92pub use viewshed::{viewshed, ViewshedConfig, EARTH_RADIUS_M};
terrand/lib.rs

terrand/
lib.rs
