Modern multi-technique toolkit (LSPIV, STIV and iWave) for water-surface velocity analysis and flow discharge measurements
Download · User Manual · What's new · CLI & Development · Examples · Citation
RIVeR (Rectification of Image Velocity Results) is a modern, open-source toolkit for water-surface velocimetry distributed by ORUS. It offers three techniques in one place: Large Scale Particle Image Velocimetry (LSPIV), Space-Time Image Velocimetry (STIV) and image wave velocimetry (iWave). Built with Python and React, it provides a user-friendly interface for water-surface velocity analysis and flow discharge measurements in rivers and large-scale hydraulic models.
RIVeR 3.8 Results step: LSPIV, STIV and iWave discharge compared on one cross section
RIVeR 3.8 brings the experimental multi-technique build of 3.7 to a regular release, with a redesigned interface. See the changelog for the full list.
Watch what's new in 3.8.0 (YouTube)
- Three techniques side by side: LSPIV, STIV and iWave, compared in one Results view. iWave parameters are chosen automatically and can be edited in Processing.
- Start from a folder of frames, not only from a video, and reopen moved projects with a Locate button when an input is missing.
- Stations under the analysis mask are skipped by STIV and iWave and listed in the report.
- Stabilization for oblique and IP camera footage, plus a redesigned Control Points step for fixed stations that grades each point's reprojection error.
- New A4 report with one block per cross section, its velocity and depth profile, and the calibration and parameter sheets.
- Redesigned interface in dark, light and Dracula themes, in 12 languages.
If you don't want to bother with code at all (we get it, sometimes you just want things to work!), pre-compiled standalone versions are available on the latest release page:
| ⊞ Windows | ⌘ macOS | ◆ Linux |
|---|---|---|
Setup .exe |
Installer .dmg |
Package .deb |
These packages include both the GUI and CLI tools in a ready-to-use application. Simply download, extract (if needed), and run the application — no Python or JavaScript knowledge required!
macOS users: If Gatekeeper blocks the app after installing, open a terminal and run:
xattr -rd com.apple.quarantine /Applications/RIVeR.appOr right-click the app → Open → Open anyway.
For a step-by-step guide to the GUI, see the User Manual.
RIVeR is a specialized tool for estimating discharge in rivers and channels from video footage, as a non-contact method. The software guides the process through intuitive defaults and pre-configured settings, enabling users to generate discharge calculations without extensive prior knowledge of the techniques. The workflow is a series of straightforward steps, culminating in a detailed visual report.
Originally developed in MATLAB in 2015 and well-received by the hydrology community, RIVeR has now been reimplemented in Python and JavaScript to improve accessibility, performance, and cross-platform compatibility.
Demonstration of interactive oblique image rectification process in RIVeR
- Three velocimetry techniques in one place: LSPIV, STIV and iWave, compared side by side
- Process footage from multiple sources:
- UAV/drone aerial imagery
- Oblique view camera (from riverbank)
- Fixed station cameras (continuous monitoring)
- Start from a video or from a folder of frames
- Drag-and-drop interface for quick video and data imports
- Frame extraction from videos with customizable parameters
- FFT-based PIV analysis with multi-pass support for increased accuracy
- STIV with a CNN angle model and manual angle tuning, and iWave with automatic parameters
- Interactive result visualization with customizable vector fields
- Georeferencing and coordinate transformations
- Multiple cross-section flow analysis
- Camera calibration tool for lens distortion correction, with reusable camera/lens profiles
- Video stabilization (UAV, oblique and IP camera) to counter camera shake before analysis
- Automated beautiful report generation (like this one !)
- Multi-platform support (Windows, macOS, Linux)
- Multi-units support (SI, imperial)
- Dark, light and Dracula themes
- 12 languages, listed below
- LSPIV: RIVeR's original FFT-based particle image velocimetry.
- STIV: a CNN-based Space-Time Image Velocimetry model, trained in-house, with a manual angle tuner in the STI viewer.
- iWave: an image wave velocimetry approach developed by dataforwater, included with credit to its original authors and not developed by the RIVeR team.
STIV and iWave are new and not yet peer-reviewed or formally validated. Feedback is welcome via Issues.
STIV's code is in this repository but its trained weights are not, to keep the repo lean. They are hosted on Zenodo and downloaded automatically during the build (see .github/scripts/download_stiv_weights.sh).
Manual download: https://zenodo.org/records/22050810 DOI: https://doi.org/10.5281/zenodo.22050810
The weights are licensed separately from RIVeR's AGPLv3 license: research and non-commercial use, no redistribution, and cite the DOI if used in published work. Without the weights file the STIV option is unavailable (greyed out) in the app, see river.core.stiv_pipeline.stiv_weights_available().
How to cite each technique is described in Citation.
RIVeR is available in 12 languages, with technical terminology reviewed for hydrology, PIV and bathymetry domains:
🇬🇧 English · 🇦🇷 Spanish · 🇫🇷 French · 🇯🇵 Japanese · 🇨🇳 Chinese · 🇩🇪 German · 🇸🇦 Arabic · 🇰🇷 Korean · 🇮🇹 Italian · 🇷🇺 Russian · 🇮🇳 Hindi · 🇧🇷 Portuguese
Want to contribute a new language? Translation files are located in gui/src/translations/ — add a new folder with a global.json file following the existing structure and open a Pull Request!
For those who prefer to work with the source code or contribute to RIVeR's development, here's how to get started:
- Python 3.12+
- pip package manager
- Git (for cloning the repository)
git clone https://github.com/oruscam/RIVeR.git
cd RIVeR
pip install -e .RIVeR CLI provides commands for the whole workflow from the command line: frame extraction, camera calibration, transformations, masks, LSPIV, STIV, iWave and discharge calculation.
pip install river-cliriver-cli [OPTIONS] COMMAND [ARGS]...To see all available commands and options:
river-cli --help# 1. Extract frames from video
river-cli video-to-frames river_video.mp4 ./frames --every 2
# 2. Generate transformation matrix
river-cli get-uav-transformation-matrix 100 200 300 400 0 0 10 10 \
--image-path ./frames/frame_001.jpg
# 3. Create ROI mask from cross-sections
# This writes mask.npy, bbox.json and mask.png into --workdir
river-cli create-mask-and-bbox 3 \
./frames/frame_001.jpg \
./xsections.json \
./transformation_matrix.json \
--workdir ./workdir \
--save-png-mask
# 4. (Optional) Create one or more user masks from polygon coordinates
river-cli create-user-mask ./frames/frame_001.jpg \
--workdir ./workdir \
--index 1 \
--point 120 340 --point 220 500 --point 400 420
river-cli create-user-mask ./frames/frame_001.jpg \
--workdir ./workdir \
--index 2 \
--point 600 300 --point 750 600 --point 900 450
# 5. Compile ROI mask and user masks into a final mask
# 0 is dominant: final = ROI AND all user masks
river-cli compile-masks \
--workdir ./workdir \
--roi ./workdir/mask.npy \
--usr ./workdir/usr_mask_1.npy \
--usr ./workdir/usr_mask_2.npy \
--out final_mask.npy \
--save-png-mask
# 6. Run PIV analysis using the final mask
river-cli piv-analyze ./frames \
--mask ./workdir/final_mask.npy \
--workdir ./results
# 7. Calculate discharge
river-cli update-xsection \
./xsections.json \
./results/piv_results.json \
./transformation_matrix.json \
--step 2 --fps 30 --id-section 0
# 8. (Optional) Generate a ChArUco calibration board to print/display
river-cli write-charuco-board --output ./board.png --board 20x15
# 9. (Optional) Calibrate camera intrinsics from a folder of board photos,
# then reuse the profile to undistort frames during extraction
river-cli camera-calibration --dir ./calibration_photos --save ./profile.json
river-cli video-to-frames river_video.mp4 ./frames --every 2 \
--undistort --profile-path ./profile.json
# 10. (Optional, UAV footage only) Stabilize extracted frames against camera shake
river-cli video-to-frames river_video.mp4 ./frames --every 2 \
--stabilize --stabilization-regions ./stabilization_regions.json
The workflow above is LSPIV. STIV, iWave and the full multi-technique run are available as stiv-analyze, iwave-analyze and analyze-all; run river-cli <command> --help for their options.
RIVeR also provides a user-friendly graphical interface built with React. The GUI offers an intuitive way to perform water-surface velocity analysis without using command-line tools.
Key GUI features include:
- Interactive workflow interface
- Visual cross-section creation
- Real-time PIV analysis visualization
- Camera calibration tool with reusable camera/lens profiles
- Video stabilization with a sanity-check view
- LSPIV, STIV and iWave with a shared Results view
- Result export capabilities
For detailed information about installation, usage, and features of the GUI, please see the dedicated GUI documentation.
RIVeR/
├── river/ # Python package (core algorithms + CLI)
│ ├── core/
│ │ ├── video_to_frames.py # Video frame extraction
│ │ ├── frames_to_frames.py # Frame-folder import and resampling
│ │ ├── stabilize_frames.py # UAV frame stabilization (LK point tracking)
│ │ ├── camera_calibration.py # Intrinsic lens calibration from ChArUco images
│ │ ├── coordinate_transform.py # Pixel <-> real-world transformations
│ │ ├── define_roi_masks.py # ROI and mask definitions
│ │ ├── compute_section.py # Cross-section computation
│ │ ├── image_preprocessing.py # Image preparation tools
│ │ ├── piv_fftmulti.py # FFT-based PIV processing (LSPIV)
│ │ ├── piv_loop.py # PIV processing loop (LSPIV)
│ │ ├── piv_pipeline.py # Main PIV pipeline (LSPIV)
│ │ ├── stiv_pipeline.py # STIV pipeline
│ │ ├── stiv_model/ # STIV network weights
│ │ ├── iwave_params.py # IWaVE parameter defaults
│ │ ├── iwave_pipeline.py # IWaVE pipeline
│ │ ├── orchestrator.py # Runs the selected techniques together
│ │ ├── matlab_smoothn.py # Smoothing algorithms
│ │ └── exceptions.py # Custom exceptions
│ ├── cli/ # river-cli entry point
│ │ └── commands/ # One module per command
│ └── docs/_static/ # README images and logo
├── gui/ # Electron + React desktop app
│ ├── electron/ # Main process and IPC handlers
│ ├── src/ # Renderer: pages, components, store, translations
│ └── commons/ # Types and helpers shared by both processes
├── examples/ # Jupyter notebooks (see below), with data/, results/, utils/
├── tests/ # pytest suite
├── scripts/ # Benchmarks and technique comparisons
├── user-manual.md
├── CHANGELOG.md
├── CITATION.cff
├── THIRD-PARTY-LICENSES.md
├── sample_report.html
├── pyproject.toml
├── requirements.txt
├── LICENSE
└── readme.md
Browse through our collection of Jupyter Notebook examples to learn how to use RIVeR for various analyses (requires development installation with the examples extra):
pip install -e ".[examples]"- Introduction to RIVeR
- Video Frame Extraction
- UAV/Drone Transformations
- Oblique View Transformations
- Fixed Station Transformations
- Cross Section Analysis
- PIV Analysis Workflow
- Discharge Calculation
These interactive examples provide step-by-step guidance for common RIVeR workflows. To run them, make sure you've completed the development installation with the examples extra shown above.
If you use RIVeR in your research, please cite:
@article{patalano2017river,
title={Rectification of Image Velocity Results (RIVeR): A simple and user-friendly toolbox
for large scale water surface Particle Image Velocimetry (PIV) and
Particle Tracking Velocimetry (PTV)},
author={Patalano, Antoine and García, Carlos Marcelo and Rodríguez, Andrés},
journal={Computers \& Geosciences},
volume={105},
pages={103--114},
year={2017},
publisher={Elsevier}
}RIVeR's iWave technique implements the image wave velocimetry method of Dolcetti et al., by way of the IWaVE package, which RIVeR bundles unmodified. If you use iWave results, please also cite:
@article{dolcetti2022noncontact,
title={Using Noncontact Measurement of Water Surface Dynamics to Estimate River Discharge},
author={Dolcetti, G. and Hortob{\'a}gyi, B. and Perks, M. and Tait, S. J. and Dervilis, N.},
journal={Water Resources Research},
volume={58},
number={9},
pages={e2022WR032829},
year={2022},
doi={10.1029/2022WR032829}
}If you use STIV results, please also cite the model weights: https://doi.org/10.5281/zenodo.22050810
See THIRD-PARTY-LICENSES.md for the licences of IWaVE and everything else RIVeR redistributes.
- Antoine Patalano - Project Lead, Feature Development - UNC / ORUS
- Leandro Massó - Feature Development - UNC / ORUS
- Nicolas Stefani - CLI & Backend Development
- Tomas Stefani - Frontend Development
- Agustín Patrito - Frontend Development
Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.
RIVeR is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0-or-later).
RIVeR redistributes third-party software inside its installers, including the IWaVE velocimetry package and static FFmpeg binaries. Their licences and copyright notices are listed in THIRD-PARTY-LICENSES.md.
The complete corresponding source for any released version is this repository, at the matching tag. For
the source of a bundled third-party component, or a copy on physical media, write to [email protected].
- Sample data in
examples/data/(videos, frames, bathymetry) is © UNC / CONICET / ORUS and is released under CC BY 4.0. - Documentation images in
river/docs/_static/are © UNC / CONICET / ORUS, released under CC BY 4.0. - STIV model weights were trained on data from UNC / CONICET / ORUS and are hosted separately on Zenodo under a research/non-commercial use license — not RIVeR's AGPL-3.0-or-later. No redistribution; cite the DOI if used in published work. See the "STIV model weights" section above and the Zenodo record for the full terms.
-
Contributing organizations:
-
WMO HydroHub: For funding the development of RIVeR 3 (2024-2025)
-
PIVlab project: The pioneering PIV analysis tool that inspired aspects of RIVeR's development
-
IWaVE by Giulio Dolcetti (University of Trento), Salvador Peña-Haro and Hessel Winsemius, maintained under the DataForWater organisation: the image wave velocimetry engine behind RIVeR's iWave technique