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.
Upgrading from 0.x? Stores written with canVODpy 0.x must be migrated
before a v1.0.0 run writes to them. See
Upgrading to v1.0.0 for the
commands, the changed settings and what is deprecated.
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 unit in pipeline.run("2025001", "2025007"):
print(sorted(unit.days), unit.vod.written)
Start here walks through the first run step
by step.
Packages
canvodpy installs all of them. Each can also be installed on its own.
| Package | What it does |
|---|
canvodpy | The command line, the Site API and the processing pipeline |
canvod-readers | Readers for RINEX, SBF, and NMEA files |
canvod-auxiliary | Orbit and clock products, satellite angles |
canvod-store | Icechunk stores for observations and VOD |
canvod-store-metadata | Store metadata (DataCite, ACDD, STAC) and the STAC catalog |
canvod-vod | VOD retrieval |
canvod-grids | Hemispheric grids |
canvod-viz | 2D and 3D plots |
canvod-ops | Preprocessing: temporal aggregation, grid cell assignment |
canvod-config | The settings file and its checks |
canvod-preflight | The canVOD file name convention |
canvod-utils | Shared utilities |
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, sorted into groups. The
contributor setup has the
details.
Documentation
All documentation is at canvodpy.eu:
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: [email protected]
