lidar-rs 0.2.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,23 @@
1
+ [workspace]
2
+ resolver = "3"
3
+ members = ["crates/lidar", "crates/lidar-cli"]
4
+ exclude = ["python"]
5
+
6
+ [workspace.package]
7
+ version = "0.2.0"
8
+ edition = "2024"
9
+ license = "MIT"
10
+ rust-version = "1.90"
11
+ repository = "https://github.com/opengeos/lidar-rs"
12
+ authors = ["Qiusheng Wu <giswqs@gmail.com>"]
13
+
14
+ [workspace.dependencies]
15
+ lidar = { path = "crates/lidar", version = "0.2.0" }
16
+ richdem = { version = "0.2", default-features = false, features = ["terrio"] }
17
+ terrio = { version = "0.9", default-features = false, features = ["geotiff", "sqlite"] }
18
+ rayon = "1.10"
19
+ thiserror = "2"
20
+ serde = { version = "1", features = ["derive"] }
21
+ serde_json = "1"
22
+ clap = { version = "4", features = ["derive"] }
23
+ tempfile = "3"
lidar_rs-0.2.0/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2018-2026 Qiusheng Wu
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
lidar_rs-0.2.0/NOTICE ADDED
@@ -0,0 +1,23 @@
1
+ lidar-rs
2
+ Copyright (c) 2018-2026 Qiusheng Wu
3
+
4
+ This software is a pure-Rust port of the `lidar` Python package
5
+ (https://github.com/opengeos/lidar), implementing the level-set algorithm
6
+ for delineating nested surface depressions and mounts in digital elevation
7
+ models (DEMs):
8
+
9
+ - Wu, Q. (2021). lidar: A Python package for delineating nested surface
10
+ depressions from digital elevation data. Journal of Open Source Software,
11
+ 6(59), 2965. https://doi.org/10.21105/joss.02965
12
+ - Wu, Q., Lane, C.R., Wang, L., Vanderhoof, M.K., Christensen, J.R., &
13
+ Liu, H. (2019). Efficient Delineation of Nested Depression Hierarchy in
14
+ Digital Elevation Models for Hydrological Analysis Using Level-Set Method.
15
+ Journal of the American Water Resources Association, 55(2), 354-368.
16
+ https://doi.org/10.1111/1752-1688.12689
17
+
18
+ Third-party crates used directly:
19
+ - `terrio` (https://github.com/opengeos/terrio): MIT AND MPL-2.0 AND Apache-2.0
20
+ - `richdem` (https://github.com/opengeos/richdem-rs): GPL-3.0-only
21
+ Note: `lidar-rs` source code is licensed under the MIT License. Compiled
22
+ binaries or wheels linking `richdem` (GPL-3.0-only) are subject to the
23
+ terms of the GNU General Public License v3.0 when distributed.
@@ -0,0 +1,50 @@
1
+ Metadata-Version: 2.4
2
+ Name: lidar-rs
3
+ Version: 0.2.0
4
+ Classifier: Development Status :: 4 - Beta
5
+ Classifier: Intended Audience :: Science/Research
6
+ Classifier: Intended Audience :: Developers
7
+ Classifier: License :: OSI Approved :: MIT License
8
+ Classifier: Programming Language :: Python :: 3
9
+ Classifier: Programming Language :: Rust
10
+ Classifier: Topic :: Scientific/Engineering :: GIS
11
+ Requires-Dist: numpy>=1.24
12
+ Requires-Dist: pytest>=7 ; extra == 'test'
13
+ Provides-Extra: test
14
+ License-File: LICENSE
15
+ License-File: NOTICE
16
+ Summary: Pure-Rust port of opengeos/lidar for delineating nested surface depressions and mounts in DEMs (powered by terrio and richdem)
17
+ Keywords: GIS,lidar,dem,hydrology,depressions,terrain,rust
18
+ Author-email: Qiusheng Wu <giswqs@gmail.com>
19
+ License-Expression: MIT
20
+ Requires-Python: >=3.11
21
+ Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
22
+ Project-URL: Homepage, https://github.com/opengeos/lidar-rs
23
+ Project-URL: Issues, https://github.com/opengeos/lidar-rs/issues
24
+ Project-URL: Repository, https://github.com/opengeos/lidar-rs
25
+
26
+ # lidar-rs (Python bindings)
27
+
28
+ Pure-Rust port of [`opengeos/lidar`](https://github.com/opengeos/lidar) for delineating nested surface depressions and mounts in digital elevation models (DEMs), powered by [`terrio`](https://github.com/opengeos/terrio) and [`richdem`](https://github.com/opengeos/richdem-rs) with **zero GDAL or C/C++ dependencies**.
29
+
30
+ ## Installation
31
+
32
+ Build from source with [maturin](https://www.maturin.rs/):
33
+
34
+ ```sh
35
+ cd python
36
+ maturin develop --release
37
+ ```
38
+
39
+ ## Quick Start
40
+
41
+ ```python
42
+ import lidar_rs as lidar
43
+
44
+ med = lidar.MedianFilter("dem.tif", kernel_size=3, out_file="out/median.tif")
45
+ sink = lidar.ExtractSinks(med, min_size=1000, out_dir="out")
46
+ dep_id, dep_level = lidar.DelineateDepressions(
47
+ sink, min_size=1000, min_depth=0.3, interval=0.3, out_dir="out", bool_level_shp=True
48
+ )
49
+ ```
50
+
@@ -0,0 +1,24 @@
1
+ # lidar-rs (Python bindings)
2
+
3
+ Pure-Rust port of [`opengeos/lidar`](https://github.com/opengeos/lidar) for delineating nested surface depressions and mounts in digital elevation models (DEMs), powered by [`terrio`](https://github.com/opengeos/terrio) and [`richdem`](https://github.com/opengeos/richdem-rs) with **zero GDAL or C/C++ dependencies**.
4
+
5
+ ## Installation
6
+
7
+ Build from source with [maturin](https://www.maturin.rs/):
8
+
9
+ ```sh
10
+ cd python
11
+ maturin develop --release
12
+ ```
13
+
14
+ ## Quick Start
15
+
16
+ ```python
17
+ import lidar_rs as lidar
18
+
19
+ med = lidar.MedianFilter("dem.tif", kernel_size=3, out_file="out/median.tif")
20
+ sink = lidar.ExtractSinks(med, min_size=1000, out_dir="out")
21
+ dep_id, dep_level = lidar.DelineateDepressions(
22
+ sink, min_size=1000, min_depth=0.3, interval=0.3, out_dir="out", bool_level_shp=True
23
+ )
24
+ ```
@@ -0,0 +1,32 @@
1
+ [package]
2
+ name = "lidar"
3
+ description = "Pure-Rust port of opengeos/lidar for delineating nested surface depressions and mounts in DEMs using the level-set method, powered by terrio and richdem"
4
+ readme = "README.md"
5
+ keywords = ["gis", "lidar", "dem", "hydrology", "depressions"]
6
+ categories = ["science::geo", "algorithms"]
7
+ version.workspace = true
8
+ edition.workspace = true
9
+ license.workspace = true
10
+ rust-version.workspace = true
11
+ repository.workspace = true
12
+ authors.workspace = true
13
+
14
+ [features]
15
+ default = ["parallel", "pointcloud", "serde"]
16
+ ## Multi-threaded parallelism via `rayon`
17
+ parallel = ["dep:rayon", "richdem/parallel"]
18
+ ## LiDAR point cloud I/O, conversion, and DSM gridding via `terrio/pointcloud` (LAS, LAZ, COPC, PLY, E57)
19
+ pointcloud = ["terrio/pointcloud"]
20
+ ## Serialization of depression and result structs via `serde`
21
+ serde = ["dep:serde", "richdem/serde"]
22
+
23
+ [dependencies]
24
+ richdem.workspace = true
25
+ terrio.workspace = true
26
+ thiserror.workspace = true
27
+ rayon = { workspace = true, optional = true }
28
+ serde = { workspace = true, optional = true }
29
+
30
+ [dev-dependencies]
31
+ serde_json.workspace = true
32
+ tempfile.workspace = true
@@ -0,0 +1,146 @@
1
+ # lidar-rs
2
+
3
+ [![CI](https://github.com/opengeos/lidar-rs/actions/workflows/ci.yml/badge.svg)](https://github.com/opengeos/lidar-rs/actions/workflows/ci.yml)
4
+ [![Docs](https://img.shields.io/badge/docs-lidar--rs.opengeos.org-teal.svg)](https://lidar-rs.opengeos.org)
5
+ [![crates.io](https://img.shields.io/crates/v/lidar.svg)](https://crates.io/crates/lidar)
6
+ [![PyPI](https://img.shields.io/pypi/v/lidar-rs.svg)](https://pypi.org/project/lidar-rs/)
7
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
8
+
9
+ High-performance nested surface depression and mount delineation from Digital Elevation Models (DEMs) in **pure Rust**, ported from [`opengeos/lidar`](https://github.com/opengeos/lidar) and powered by [`terrio`](https://github.com/opengeos/terrio) and [`richdem`](https://github.com/opengeos/richdem-rs) with **zero GDAL or C/C++ dependencies**.
10
+
11
+ ## Highlights
12
+
13
+ - **DEM smoothing filters:** Mean (`mean_filter`), median (`median_filter`), and Gaussian (`gaussian_filter`) filters with symmetric boundary reflection, NoData preservation, and optional `rayon` row parallelism.
14
+ - **Sink extraction & DEM refinement (`extract_sinks`):** Priority-Flood depression filling via `richdem`, 4-connected region grouping, small artifact removal, refined DEM generation, geometric/topographic depression attributes (`regions_info.csv`), and polygonized Shapefile + attribute-joined GeoPackage export via `terrio`.
15
+ - **Nested depression hierarchy (`delineate_depressions`):** Wu et al. (2019) level-set algorithm delineating nested depressions across sink regions in parallel, computing all 18 geometric and topological attributes (`id`, `level`, `count`, `area`, `volume`, `avg_depth`, `max_depth`, `min_elev`, `max_elev`, `children_id`, `region_id`, `perimeter`, `major_axis`, `minor_axis`, `elongatedness`, `eccentricity`, `orientation`, `area_bbox_ratio`), and exporting per-level shapefiles (`shp-level/Single_level_*.shp`).
16
+ - **Nested mount hierarchy (`delineate_mounts` & `flip_dem`):** DEM/DSM inversion and elevated feature hierarchy delineation.
17
+ - **Pure-Rust geospatial utilities:** `polygonize`, `mosaic`, `reproject_image`, `resample`, `clip_image`, `image_to_cog`, `add_crs`, `join_csv_to_vector`, `csv_points_to_vector`, and LiDAR point cloud I/O, conversion, and DSM gridding (`read_lidar`, `write_lidar`, `convert_lidar`, `lidar_to_dsm`) via `terrio`.
18
+ - **Rust crate (`lidar`), standalone CLI (`lidar-cli`), and Python bindings (`lidar-rs` via PyO3 + maturin).**
19
+
20
+ ## Workspace Layout
21
+
22
+ | Path | Description |
23
+ |---|---|
24
+ | `crates/lidar` | Pure-Rust core library (published to crates.io as `lidar`) |
25
+ | `crates/lidar-cli` | Standalone `lidar` command-line tool (`lidar-cli`) |
26
+ | `python` | Python bindings (`lidar-rs`, PyO3 + NumPy) with drop-in `opengeos/lidar` API |
27
+ | `test_data` | Sample DEM/DSM/sink GeoTIFF datasets from `opengeos/lidar` |
28
+ | `docs` | Zensical documentation site and CLI installer scripts (`install.sh`, `install.ps1`) |
29
+
30
+ ## Rust Usage
31
+
32
+ Add `lidar` to your `Cargo.toml`:
33
+
34
+ ```toml
35
+ [dependencies]
36
+ lidar = "0.2"
37
+ ```
38
+
39
+ ```rust,no_run
40
+ use std::path::Path;
41
+ use lidar::{
42
+ DelineateOptions, ExtractSinksOptions,
43
+ delineate_depressions, extract_sinks, median_filter_file,
44
+ };
45
+
46
+ fn main() -> lidar::Result<()> {
47
+ let out_dir = Path::new("output");
48
+ let med_path = out_dir.join("median.tif");
49
+
50
+ median_filter_file("dem.tif", 3, Some(&med_path))?;
51
+
52
+ let sinks = extract_sinks(
53
+ &med_path,
54
+ out_dir,
55
+ &ExtractSinksOptions {
56
+ min_size: 1000,
57
+ ..Default::default()
58
+ },
59
+ )?;
60
+
61
+ let deps = delineate_depressions(
62
+ sinks.sink_path.as_ref().unwrap(),
63
+ out_dir,
64
+ &DelineateOptions {
65
+ min_size: 1000,
66
+ min_depth: 0.3,
67
+ interval: 0.3,
68
+ bool_level_shp: true,
69
+ ..Default::default()
70
+ },
71
+ )?;
72
+
73
+ println!(
74
+ "Delineated {} nested depressions across {} regions (max level = {})",
75
+ deps.depressions.len(),
76
+ deps.num_regions,
77
+ deps.max_level,
78
+ );
79
+ Ok(())
80
+ }
81
+ ```
82
+
83
+ ## Command-Line Interface
84
+
85
+ Install the standalone `lidar` CLI:
86
+
87
+ ```sh
88
+ # Linux and macOS
89
+ curl -LsSf https://lidar-rs.opengeos.org/install.sh | sh
90
+
91
+ # Windows (PowerShell)
92
+ powershell -ExecutionPolicy ByPass -c "irm https://lidar-rs.opengeos.org/install.ps1 | iex"
93
+
94
+ # Or from crates.io
95
+ cargo install lidar-cli
96
+ ```
97
+
98
+ Example commands:
99
+
100
+ ```sh
101
+ lidar median-filter dem.tif out/median.tif -k 3
102
+ lidar extract-sinks out/median.tif out --min-size 1000
103
+ lidar delineate-depressions out/sink.tif out --min-size 1000 --min-depth 0.3 --interval 0.3 --level-shp
104
+ lidar delineate-mounts dsm.tif out_mounts --min-size 1000 --min-height 0.3 --interval 0.3
105
+ lidar lidar-to-dsm cloud.laz dsm.tif --resolution 1.0
106
+ ```
107
+
108
+ ## Python Usage
109
+
110
+ ```sh
111
+ pip install lidar-rs
112
+ ```
113
+
114
+ ```python
115
+ import lidar_rs as lidar
116
+
117
+ med = lidar.MedianFilter("dem.tif", kernel_size=3, out_file="out/median.tif")
118
+ sink = lidar.ExtractSinks(med, min_size=1000, out_dir="out")
119
+ dep_id, dep_level = lidar.DelineateDepressions(
120
+ sink, min_size=1000, min_depth=0.3, interval=0.3, out_dir="out", bool_level_shp=True
121
+ )
122
+ ```
123
+
124
+ ## Performance
125
+
126
+ Measured in release mode (`cargo run --release --example benchmark`) on the 400 × 400 sample datasets (`test_data/dem.tif`, `sink.tif`, `dsm.tif`, 160,000 cells):
127
+
128
+ | Operation | Median Time |
129
+ |---|---:|
130
+ | `mean_filter` (3×3, in-memory) | 0.75 ms |
131
+ | `median_filter` (3×3, in-memory) | 1.27 ms |
132
+ | `gaussian_filter` (σ = 1.0, in-memory) | 1.51 ms |
133
+ | `extract_sinks` (in-memory, `min_size = 1000`) | 8.25 ms |
134
+ | `extract_sinks` (full file I/O: GeoTIFFs + CSV + Shapefile + GeoPackage) | 17.68 ms |
135
+ | `delineate_depressions` (in-memory, `interval = 0.3`) | 46.77 ms |
136
+ | `delineate_depressions` (full file I/O + per-level shapefiles) | 65.64 ms |
137
+ | `delineate_mounts` (`dsm.tif`, full pipeline + file I/O) | 78.39 ms |
138
+
139
+ ## Citations
140
+
141
+ - **Wu, Q.** (2021). lidar: A Python package for delineating nested surface depressions from digital elevation data. *Journal of Open Source Software*, 6(59), 2965. <https://doi.org/10.21105/joss.02965>
142
+ - **Wu, Q.**, Lane, C.R., Wang, L., Vanderhoof, M.K., Christensen, J.R., & Liu, H. (2019). Efficient Delineation of Nested Depression Hierarchy in Digital Elevation Models for Hydrological Analysis Using Level-Set Method. *Journal of the American Water Resources Association*, 55(2), 354–368. <https://doi.org/10.1111/1752-1688.12689>
143
+
144
+ ## License
145
+
146
+ `lidar-rs` source code is licensed under the [MIT License](LICENSE). See [NOTICE](NOTICE) for third-party crate license attributions (including `richdem` under GPL-3.0-only when linked in distributed binaries).
@@ -0,0 +1,103 @@
1
+ //! Release-mode benchmark for `lidar-rs` core operations on the 400×400 sample datasets.
2
+ //!
3
+ //! Run with: `cargo run --release --example benchmark`
4
+
5
+ use std::path::PathBuf;
6
+ use std::time::Instant;
7
+
8
+ use lidar::{
9
+ DelineateOptions, ExtractSinksOptions, Topology, delineate_depressions,
10
+ delineate_depressions_in_memory, delineate_mounts, extract_sinks, extract_sinks_in_memory,
11
+ gaussian_filter, load_raster, mean_filter, median_filter,
12
+ };
13
+
14
+ fn bench<F, R>(name: &str, runs: usize, mut f: F)
15
+ where
16
+ F: FnMut() -> R,
17
+ {
18
+ // Warmup
19
+ let _ = f();
20
+ let mut times = Vec::with_capacity(runs);
21
+ for _ in 0..runs {
22
+ let t0 = Instant::now();
23
+ let _ = f();
24
+ times.push(t0.elapsed().as_secs_f64() * 1000.0);
25
+ }
26
+ times.sort_by(f64::total_cmp);
27
+ let median = times[runs / 2];
28
+ println!("{name:<42} {median:>8.2} ms (median of {runs})");
29
+ }
30
+
31
+ fn main() -> lidar::Result<()> {
32
+ let data_dir = PathBuf::from(env!("CARGO_MANIFEST_DIR"))
33
+ .join("../..")
34
+ .join("test_data");
35
+ let dem = load_raster::<f64>(data_dir.join("dem.tif"), None)?;
36
+ let sink = load_raster::<f64>(data_dir.join("sink.tif"), None)?;
37
+ let tmp = tempfile::tempdir()?;
38
+
39
+ println!(
40
+ "lidar-rs {} benchmark on {}x{} DEM ({} cells)\n",
41
+ lidar::VERSION,
42
+ dem.width(),
43
+ dem.height(),
44
+ dem.width() * dem.height()
45
+ );
46
+
47
+ bench("mean_filter (3x3, in-memory)", 5, || {
48
+ mean_filter(&dem, 3).unwrap()
49
+ });
50
+ bench("median_filter (3x3, in-memory)", 5, || {
51
+ median_filter(&dem, 3).unwrap()
52
+ });
53
+ bench("gaussian_filter (sigma=1.0, in-memory)", 5, || {
54
+ gaussian_filter(&dem, 1.0).unwrap()
55
+ });
56
+ bench("extract_sinks (in-memory, min_size=1000)", 5, || {
57
+ extract_sinks_in_memory(&dem, 1000, Topology::D8).unwrap()
58
+ });
59
+ bench("delineate_depressions (in-memory)", 5, || {
60
+ delineate_depressions_in_memory(&sink, 1000, 0.3, 0.3).unwrap()
61
+ });
62
+ bench("extract_sinks (full file I/O + GPKG)", 3, || {
63
+ extract_sinks(
64
+ data_dir.join("dem.tif"),
65
+ tmp.path().join("sinks"),
66
+ &ExtractSinksOptions {
67
+ min_size: 1000,
68
+ ..Default::default()
69
+ },
70
+ )
71
+ .unwrap()
72
+ });
73
+ bench("delineate_depressions (full file I/O)", 3, || {
74
+ delineate_depressions(
75
+ data_dir.join("sink.tif"),
76
+ tmp.path().join("deps"),
77
+ &DelineateOptions {
78
+ min_size: 1000,
79
+ min_depth: 0.3,
80
+ interval: 0.3,
81
+ bool_level_shp: true,
82
+ ..Default::default()
83
+ },
84
+ )
85
+ .unwrap()
86
+ });
87
+ bench("delineate_mounts (dsm.tif, full I/O)", 3, || {
88
+ delineate_mounts(
89
+ data_dir.join("dsm.tif"),
90
+ tmp.path().join("mounts"),
91
+ &DelineateOptions {
92
+ min_size: 1000,
93
+ min_depth: 0.3,
94
+ interval: 0.3,
95
+ bool_level_shp: false,
96
+ ..Default::default()
97
+ },
98
+ )
99
+ .unwrap()
100
+ });
101
+
102
+ Ok(())
103
+ }
@@ -0,0 +1,38 @@
1
+ //! Error types for `lidar-rs`.
2
+
3
+ use thiserror::Error;
4
+
5
+ /// Unified error type returned by `lidar-rs` operations.
6
+ #[derive(Debug, Error)]
7
+ pub enum Error {
8
+ /// Error from the underlying `richdem` crate.
9
+ #[error("richdem error: {0}")]
10
+ RichDem(#[from] richdem::Error),
11
+
12
+ /// Error from the underlying `terrio` geospatial I/O crate.
13
+ #[error("terrio error: {0}")]
14
+ Terrio(#[from] terrio::Error),
15
+
16
+ /// Standard filesystem / I/O error.
17
+ #[error("I/O error: {0}")]
18
+ Io(#[from] std::io::Error),
19
+
20
+ /// Invalid argument or configuration parameter.
21
+ #[error("invalid argument: {0}")]
22
+ InvalidArgument(String),
23
+
24
+ /// Raster or array dimension mismatch or overflow.
25
+ #[error("dimension mismatch: {0}")]
26
+ DimensionMismatch(String),
27
+
28
+ /// Parse error (CSV, CRS, numeric values, etc.).
29
+ #[error("parse error: {0}")]
30
+ Parse(String),
31
+
32
+ /// Algorithm execution failure.
33
+ #[error("algorithm error: {0}")]
34
+ Algorithm(String),
35
+ }
36
+
37
+ /// Convenience `Result` alias for `lidar-rs`.
38
+ pub type Result<T> = std::result::Result<T, Error>;