Sylva

NOTE: This software is still in ALPHA development.

Terrestrial and airborne laser scanning processing for forest ecology and remote sensing. A Rust core (the sylva-rs crate) holds every computation and file format; Python gets a numpy-friendly API (import sylva) and a sylva command over it.

Contributing

Feedback, issues, and PRs all welcome. For issues please use GitHub issues (not a personal message) so the community can benefit.

Install

Requires Python 3.10 or later. The package is on PyPI: pypi.org/project/sylva-rs.

pip install sylva-rs

The wheels carry the compiled core for Linux (x86-64 and arm64), macOS (Intel and Apple silicon) and Windows. The distribution is called sylva-rs because an unrelated project owns the name sylva on PyPI; the package you import is sylva, and the two cannot be installed in the same environment.

Using a dedicated environment:

conda create -n sylva python=3.12
conda activate sylva
pip install sylva-rs

Optional extras: pip install "sylva-rs[examples]" for the notebooks. Reading RIEGL .rxp files needs RIEGL's RiVLib, which is proprietary and loaded at run time; see the install guide.

Rust

The core is on crates.io as sylva-rs, and the sylva command without Python as sylva-cli:

cargo add sylva-rs               # the library: use sylva_rs::...
cargo install sylva-cli          # the sylva command

From source

For development, or to build the extension yourself. A conda environment keeps the Python, the Rust toolchain and the C linker together:

git clone https://github.com/UQ-EORC/Sylva.git
cd Sylva
conda create -n sylva -c conda-forge python=3.12 rust maturin c-compiler
conda activate sylva
maturin develop --release        # builds the Rust core into the environment

c-compiler matters: rustc links through a program called cc, which conda's rust package does not provide, so without it the build stops at error: linker `cc` not found. The repository's environment.yml has the same list plus the test and notebook extras (conda env create -f environment.yml).

Without conda, any Python >= 3.10 with a Rust toolchain (rustup), a system C compiler (gcc, build-essential, or Xcode's command line tools) and pip install maturin does the same job.

A first look

import sylva
from sylva import ground, trees, voxels

cloud = ground.classify_ground_csf(sylva.read("plot.laz"))
cloud = ground.normalize_height(cloud, ground.make_dtm(cloud, resolution=0.5))
stems = trees.detect_stems(cloud)                        # positions and DBH
labels = trees.segment_trees(cloud, stems)               # tree_id per point

shots = sylva.Shots.load("plot.parquet")                 # pulses, misses included
grid = voxels.ray_voxelize(shots, 0.25, ground_class=2)  # ray-traced plant area density

from sylva.geo import coords, interpolate, masks

cloud = coords.reproject(cloud, "EPSG:7855")                  # to GDA2020 / MGA zone 55
trees_only = cloud.where("height > 1.3 & tree_id >= 0")       # attribute expression
plot = masks.crop_polygons(cloud, masks.read_polygons("plot.shp"))
full = interpolate.transfer_attributes(thinned, full, ["tree_id"], method="majority")

sylva ground plot.laz plot_norm.laz --dtm dtm.asc
sylva trees plot_norm.laz -o trees.csv --segment plot_trees.laz
sylva coreg survey.PROJ -o survey_coreg/ --merged survey.laz
sylva voxel plot.parquet plot.vox --voxel 0.25 --ground-class 2
sylva reproject plot.laz plot_mga55.laz --to EPSG:7855
sylva transform scan.laz scan_project.laz --matrix ScanPos001.DAT
sylva als-ground tiles/ ground/ --method csf                  # airborne tiles
sylva als-metrics ground/ metrics/ --resolution 20 --metrics zq95,zmean,cover
sylva als-trees ground/ trees.csv --crowns crowns.geojson

from sylva import als, change

cat = als.catalog("ground/")                                  # ALS tiles
metrics = als.grid_metrics(cat, 20.0)                          # rasters, one per metric
found = als.find_trees(cat, method="dalponte2016")             # tops and crowns

m = change.match_trees(stems_2019, stems_2024)                 # two epochs of a plot
inc = change.tree_increments(m, cloud_2019, cloud_2024, labels_2019, labels_2024)

Documentation

The documentation is at uq-eorc.github.io/Sylva; its sources are in docs/:

• Guides: plot workflow, pulse data and shots files, ray-traced voxels, QSMs, coordinates, interpolation, masking, change detection, command line
• Airborne lidar: tiles, area-based metrics, trees, canopy structure, full waveforms
• Example notebooks, one per stage, on a tile of the TERN Litchfield plot and on synthetic data
• Design notes: the Rust core, the Python layer over it, and how changes are checked
• Benchmarks: tree detection, QSMs against felled trees
• API reference (generated from the docstrings), development notes, references

Build the site with pip install -e '.[docs]' && mkdocs serve.

Authors

• Tim Devereux, The University of Queensland

Citation

If Sylva contributed to your work, please cite it:

Devereux, T. (2026). Sylva: terrestrial and airborne laser scanning processing for forest ecology (version 0.2.1) [Computer software]. The University of Queensland. https://github.com/UQ-EORC/Sylva

@software{sylva,
  author       = {Devereux, Tim},
  title        = {Sylva: terrestrial and airborne laser scanning processing
                  for forest ecology},
  year         = {2026},
  version      = {0.2.1},
  organization = {The University of Queensland},
  url          = {https://github.com/UQ-EORC/Sylva}
}

Licence

GNU General Public License v3.0 or later; see LICENSE. Anything distributed that builds on Sylva carries the same licence.