Bindings for DEM processing routines.

.cargo/config.toml

@@ -1,5 +1,9 @@
 [alias]
-# Run doctests, displaying compiler output
-dto = "test --doc -- --show-output"
+# Run doctests, displaying compiler output.
+# Due to this issue:
+#    https://github.com/rust-lang/cargo/pull/9705#issuecomment-1226149265
+# the following is required for full output during documentation development debugging:
+#    RUSTDOCFLAGS="-Z unstable-options --nocapture" cargo +nightly test --doc
+dto = "test --doc -- --show-output --nocapture"
 # Run clippy, raising warnings to errors
 nowarn = "clippy --all-targets -- -D warnings"

.github/workflows/ci.yml

@@ -68,7 +68,7 @@ jobs:
       - name: Build (--all-features)
         run: cargo build --all-features
       - name: Run tests (--all-features)
-        run: cargo test --all-features
+        run: cargo test --all-features -- --nocapture
 
   ubuntu_lts:
     name: "ci ubuntu-lts"
@@ -111,4 +111,4 @@ jobs:
       - name: Build (--all-features)
         run: cargo build --all-features
       - name: Run tests (--all-features)
-        run: cargo test --all-features
+        run: cargo test --all-features -- --nocapture

.gitignore

@@ -4,7 +4,7 @@
 /gdal-sys/target
 /.idea
 /3rd
-/fixtures/tinymarble.tif.aux.xml
+/fixtures/*.aux.xml
 
 # gtags
 GPATH

CHANGES.md

@@ -2,6 +2,10 @@
 
 ## Unreleased
 
+- Added support for digital elevation model raster processing: `DemProcessing::aspect`, `DemProcessing::color_relief`, `DemProcessing::hillshade`, `DemProcessing::roughness`, `DemProcessing::slope`, `DemProcessing::terrain_ruggedness_index`, `DemProcessing::topographic_position_index`.
+
+   - <https://github.com/georust/gdal/pull/456> 
+
 - **Breaking**: `SpatialRef::set_axis_mapping_strategy` now takes `&mut self`
 
   - <https://github.com/georust/gdal/pull/461>
@@ -12,7 +16,7 @@
 
 - **Breaking**: `CslStringListIterator` returns a `CslStringListEntry` instead of `(String, String)` in order to differentiate between `key=value` entries vs `flag` entries.
 - **Breaking**: `CslStringList::fetch_name_value` returns `Option<String>` instead of `Result<Option<String>>`, better reflecting the semantics of GDAL C API.
- - Added `CslStringList::get_field`, `CslStringList::find_string`, `CslStringList::partial_find_string`, `CslStringList::find_string_case_sensitive`, `CslStringList::into_ptr`, `CslStringList::add_name_value`.
+- Added `CslStringList::get_field`, `CslStringList::find_string`, `CslStringList::partial_find_string`, `CslStringList::find_string_case_sensitive`, `CslStringList::into_ptr`, `CslStringList::add_name_value`.
 
    - <https://github.com/georust/gdal/pull/455>
 

fixtures/color-relief.clr

@@ -0,0 +1,6 @@
+100%   white
+75%   235:220:175
+50%   190 185 135
+20%    240 250 150
+0%      50  180  50
+nv     0   0   0   0

src/cpl.rs

@@ -29,7 +29,7 @@ use crate::utils::_string;
 ///
 /// # Example
 ///
-/// ```rust
+/// ```rust, no_run
 /// use gdal::cpl::CslStringList;
 ///
 /// let mut sl1 = CslStringList::new();

src/raster/mod.rs

@@ -76,6 +76,7 @@
 
 #[cfg(all(major_ge_3, minor_ge_1))]
 mod mdarray;
+pub mod processing;
 mod rasterband;
 mod rasterize;
 mod types;

src/raster/processing/dem/aspect.rs

@@ -0,0 +1,127 @@
+use crate::cpl::CslStringList;
+use crate::raster::processing::dem::{DemCommonOptions, DemCommonOptionsOwner, DemSlopeAlg};
+
+/// Configuration options for [`super::DemProcessing::aspect`].
+#[derive(Debug, Clone, Default)]
+pub struct AspectOptions {
+    common_options: DemCommonOptions,
+    algorithm: Option<DemSlopeAlg>,
+    zero_for_flat: Option<bool>,
+    trigonometric: Option<bool>,
+}
+
+impl AspectOptions {
+    /// Create a aspect-from-DEM processor
+    pub fn new() -> Self {
+        Default::default()
+    }
+
+    /// Specify the slope computation algorithm.
+    pub fn with_algorithm(&mut self, algorithm: DemSlopeAlg) -> &mut Self {
+        self.algorithm = Some(algorithm);
+        self
+    }
+
+    /// Return `0` for flat areas with `slope=0`, instead of `-9999`.
+    ///
+    /// See: [`zero_for_flat`](https://gdal.org/programs/gdaldem.html#cmdoption-zero_for_flat)
+    pub fn with_zero_for_flat(&mut self, state: bool) -> &mut Self {
+        self.zero_for_flat = Some(state);
+        self
+    }
+
+    /// Return trigonometric angle instead of azimuth. Thus 0° means East, 90° North, 180° West, 270° South.
+    pub fn with_trigonometric_angles(&mut self, state: bool) -> &mut Self {
+        self.trigonometric = Some(state);
+        self
+    }
+
+    /// Render relevant common options into [`CslStringList`] values, as compatible with
+    /// [`gdal_sys::GDALDEMProcessing`].
+    pub fn to_options_list(&self) -> CslStringList {
+        let mut opts = self.common_options.to_options_list();
+
+        if let Some(alg) = self.algorithm {
+            opts.add_string("-alg").unwrap();
+            opts.add_string(&alg.to_string()).unwrap();
+        }
+
+        if self.zero_for_flat == Some(true) {
+            opts.add_string("-zero_for_flat").unwrap();
+        }
+
+        if self.trigonometric == Some(true) {
+            opts.add_string("-trigonometric").unwrap();
+        }
+
+        opts
+    }
+}
+
+/// Exposes common DEM routine options to [`AspectOptions`]
+impl DemCommonOptionsOwner for AspectOptions {
+    fn opts(&self) -> &DemCommonOptions {
+        &self.common_options
+    }
+
+    fn opts_mut(&mut self) -> &mut DemCommonOptions {
+        &mut self.common_options
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use crate::assert_near;
+    use crate::cpl::CslStringList;
+    use crate::errors::Result;
+    use crate::raster::processing::dem::DemProcessing;
+    use crate::raster::StatisticsAll;
+    use crate::test_utils::{fixture, target};
+    use crate::Dataset;
+
+    use super::*;
+
+    #[test]
+    fn options() -> Result<()> {
+        let mut proc = AspectOptions::new();
+        proc.with_input_band(2.try_into().unwrap())
+            .with_algorithm(DemSlopeAlg::ZevenbergenThorne)
+            .with_compute_edges(true)
+            .with_zero_for_flat(true)
+            .with_trigonometric_angles(true)
+            .with_output_format("GTiff")
+            .with_additional_options("CPL_DEBUG=ON".parse()?);
+
+        let expected: CslStringList =
+            "-compute_edges -b 2 -of GTiff CPL_DEBUG=ON -alg ZevenbergenThorne -zero_for_flat -trigonometric"
+                .parse()?;
+        assert_eq!(expected.to_string(), proc.to_options_list().to_string());
+
+        Ok(())
+    }
+
+    #[test]
+    fn aspect() -> Result<()> {
+        let mut opts = AspectOptions::new();
+        opts.with_algorithm(DemSlopeAlg::Horn)
+            .with_zero_for_flat(true);
+
+        let ds = Dataset::open(fixture("dem-hills.tiff"))?;
+
+        let aspect = ds.aspect(target("dem-hills-aspect.tiff"), &opts)?;
+
+        let stats = aspect.rasterband(1)?.get_statistics(true, false)?.unwrap();
+
+        // These numbers were generated by extracting the output from:
+        //    gdaldem aspect -alg Horn -zero_for_flat fixtures/dem-hills.tiff target/dest.tiff
+        //    gdalinfo -stats target/dest.tiff
+        let expected = StatisticsAll {
+            min: 0.0,
+            max: 359.9951171875,
+            mean: 165.72752499998,
+            std_dev: 98.590199951445,
+        };
+        assert_near!(StatisticsAll, stats, expected, epsilon = 1e-10);
+        Ok(())
+    }
+}