An Open Python Ecosystem for GNSS-Transmissometry Canopy VOD Retrievals

canVODpy aims to be the central community-driven software suite for deriving canopy Vegetation Optical Depth (VOD) from the signal-to-noise ratio of the same GNSS signal, received at the same time by one receiver below the canopy and one with an unobstructed view of the sky.

Try it

The speedrun notebook goes through the whole pipeline on real test data, from receiver files to VOD, in your browser. All 21 notebooks are at canvodpy.eu/notebooks, each with its results and a link to open it in molab.

To run a notebook on your own machine instead, install uv and run:

uvx marimo edit --sandbox https://raw.githubusercontent.com/TUW-GEO/canvodpy-demo/main/03_convenience_speedrun.py

The notebooks download their test data on first use (about 350 MB).

Install

uv add canvodpy

canVODpy requires Python 3.14. It is tested on Linux, macOS (Apple silicon), and Windows.

Quick start

Create the settings file, check it, and process a week:

canvodpy config init --interactive     # asks for your site and folders
canvodpy config validate --site MySite # lists what a run would process
canvodpy run --site MySite --start 2025001 --end 2025007

Days are given as YYYYDDD (year and day of year). The same from Python:

from canvodpy import Site

site = Site("MySite")
with site.pipeline() as pipeline:
    for date_key, datasets in pipeline.process_range("2025001", "2025007"):
        site.vod.compute_day(datasets, "canopy_01_vs_reference_01")

Start here walks through the first run step by step.

Packages

canvodpy installs all of them. Each can also be installed on its own.

Optional extensions, such as canvod-filemap for file names that don't follow the convention, are in canvodpy-extensions.

Development

Development needs uv and just.

git clone --recurse-submodules https://github.com/TUW-GEO/canvodpy.git
cd canvodpy
just check-dev-tools   # checks that the tools are installed
uv sync
just hooks             # installs the pre-commit hooks
just test
just check             # lint, format, type check

just --list shows every command. The contributor setup has the details.

Documentation

All documentation is at canvodpy.eu:

• Start here: from installation to the first VOD
• Settings file
• Command line and Python
• Your own readers and VOD calculators
• Monorepo structure and developing with coding agents

Contributing

Contributions of all kinds are welcome. See CONTRIBUTING.md. First-time contributors: add yourself to CONTRIBUTORS.md in your pull request.

How to cite

If you use canVODpy, please cite it with its DOI, 10.5281/zenodo.18496233. This DOI always leads to the newest version, and Zenodo also lists a DOI for each version. CITATION.cff has the full citation, and GitHub shows it in the "Cite this repository" menu.

License

Licensed under the Apache License 2.0.

This software is provided "as is" without warranty of any kind. See the Impressum for the full legal notice and AI disclosure.

Affiliation

Climate and Environmental Remote Sensing Research Unit (CLIMERS) Department of Geodesy and Geoinformation, TU Wien

Contact: support@canvodpy.eu