surtgis_relief/lib.rs
1//! # SurtGIS Relief
2//!
3//! Rayshader-style shaded-relief compositing on top of the terrain primitives
4//! that already live in `surtgis-algorithms`. This crate is a *compositor*,
5//! not a new set of algorithms — see `SPEC_SURTGIS_RELIEF.md` in the
6//! repository root for the full design.
7//!
8//! ## What lives here
9//!
10//! - [`ray_shade`] — ray-traced cast shadows via
11//! [`surtgis_algorithms::terrain::horizon_angle_map_fast`], with optional
12//! soft-shadow averaging over multiple sun samples.
13//! - [`sphere_shade`] — normal-based hillshade as an intensity layer in
14//! `[0, 1]`, wrapping
15//! [`surtgis_algorithms::terrain::hillshade`].
16//!
17//! ## What is re-exported
18//!
19//! Pixel-buffer and PNG output live in
20//! [`surtgis_colormap`](surtgis_colormap); we re-export the relevant types
21//! at the crate root for ergonomics.
22//!
23//! ```ignore
24//! use surtgis_relief::{ray_shade, sphere_shade, RayShadeParams, SunSample, RgbaImage};
25//!
26//! let shadow_mask = ray_shade(&dem, &RayShadeParams::default())?;
27//! let mut img = RgbaImage::from_intensity(&sphere_shade(&dem, Default::default())?);
28//! let shadow_layer = RgbaImage::from_intensity(&shadow_mask);
29//! img.multiply(&shadow_layer, 0.5)?;
30//! img.save_png("relief.png")?;
31//! ```
32
33use thiserror::Error;
34
35mod ambient;
36mod compose;
37mod ray_shade_impl;
38mod shadow_ray;
39mod sphere_shade_impl;
40mod water;
41
42pub use ambient::ambient_shade;
43pub use compose::ReliefBuilder;
44pub use ray_shade_impl::{RayShadeParams, SunSample, ray_shade};
45pub use shadow_ray::{cast_shadow_ray_mask, horizon_tan_map};
46pub use sphere_shade_impl::sphere_shade;
47pub use water::{WaterParams, detect_water, water_depth};
48
49// Re-exports from colormap so users only need to depend on relief.
50pub use surtgis_colormap::{ColorScheme, ColormapParams, EncodeError, RgbaImage};
51
52#[cfg(not(target_arch = "wasm32"))]
53pub use surtgis_colormap::{rgba_to_png_bytes, save_png};
54
55/// Errors produced by the relief crate.
56#[derive(Debug, Error)]
57pub enum ReliefError {
58 #[error("algorithm: {0}")]
59 Algorithm(#[from] surtgis_core::Error),
60 #[error("encode: {0}")]
61 Encode(#[from] EncodeError),
62 #[error("shape mismatch: {0}")]
63 Shape(String),
64 #[error("invalid parameter: {0}")]
65 InvalidParam(String),
66}
67
68/// `Result` alias scoped to this crate.
69pub type Result<T> = std::result::Result<T, ReliefError>;