---

RIVeR: Rectification of Image Velocity Results

RIVeR (Rectification of Image Velocity Results) is a modern, open-source toolkit for Large Scale Particle Image Velocimetry (LSPIV) distributed by ORUS. 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.

Example of RIVeR velocimetry analysis of river flow

---

💧 Overview

RIVeR is a specialized tool for applying Large Scale Particle Image Velocimetry (LSPIV) techniques as a non-contact method to estimate discharge in rivers and channels from video footage. The software guides the process through intuitive defaults and pre-configured settings, enabling users to generate discharge calculations without extensive prior knowledge of the technique. The workflow guides users through a series of straightforward steps culminating in comprehensive visual reports.

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

---

📖 User Manual

For a detailed step-by-step guide on using RIVeR's GUI (Graphical User Interface), please refer to the User Manual.

---

✨ Key Features

• Process footage from multiple sources:
  • UAV/drone aerial imagery
  • Oblique view camera (from riverbank)
  • Fixed station cameras (continous monitoring)
• 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
• Interactive result visualization with customizable vector fields
• Georeferencing and coordinate transformations
• Multi Cross-sectional flow analysis
• Automated beautiful report generation (like this one !)
• Multi-platform support (Windows, macOS, Linux)
• Multi-units support (SI, imperial)

---

🌍 Multi-Language Support

RIVeR is available in 12 languages, with technical terminology reviewed for hydrology, PIV and bathymetry domains:

🇬🇧 English	🇯🇵 Japanese	🇸🇦 Arabic	🇷🇺 Russian
🇦🇷 Spanish	🇨🇳 Chinese	🇰🇷 Korean	🇮🇳 Hindi
🇫🇷 French	🇩🇪 German	🇮🇹 Italian	🇧🇷 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!

---

📥 Download Compiled Releases

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:

⊞ Windows	⌘ macOS	◆ Linux
EXE	DMG	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.app

Or right-click the app → Open → Open anyway.

---

🧑‍💻 Developer Installation & Usage

For those who prefer to work with the source code or contribute to RIVeR's development, here's how to get started:

Prerequisites

• Python 3.12+
• pip package manager
• Git (for cloning the repository)

Development Installation

git clone https://github.com/oruscam/RIVeR.git
cd RIVeR
pip install -e .

CLI Installation

RIVeR CLI provides a comprehensive set of commands for performing LSPIV analysis through the command line.

pip install river-cli

Basic Usage

river-cli [OPTIONS] COMMAND [ARGS]...

To see all available commands and options:

river-cli --help

Example Workflow

# 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

Graphical User Interface (GUI)

RIVeR also provides a user-friendly graphical interface built with React. The GUI offers an intuitive way to perform LSPIV analysis without using command-line tools.

Key GUI features include:

• Interactive workflow interface
• Visual cross-section creation
• Real-time PIV analysis visualization
• Result export capabilities

For detailed information about installation, usage, and features of the GUI, please see the dedicated GUI documentation.

---

📂 Project Structure

river/
.
├── LICENSE
├── examples       # Jupyter examples
│   ├── 00_introduction.ipynb
│   ├── 01_video_to_frames.ipynb
│   ├── 02a_nadir_transformation.ipynb
│   ├── 02b_oblique_transformation.ipynb
│   ├── 02c_fixed_station_transformation.ipynb
│   ├── 03_cross_sections.ipynb
│   ├── 04_piv_analysis.ipynb
│   ├── 05_discharge_calculation.ipynb
│   ├── data
│   ├── results
│   └── utils
├── gui
├── pyproject.toml
├── readme.md
├── requirements.txt
└── river
    ├── cli
    ├── core
    │   ├── compute_section.py       # Section computation utilities
    │   ├── coordinate_transform.py   # Coordinate system transformations
    │   ├── define_roi_masks.py      # ROI and mask definitions
    │   ├── exceptions.py            # Custom exceptions
    │   ├── image_preprocessing.py   # Image preparation tools
    │   ├── matlab_smoothn.py        # Smoothing algorithms
    │   ├── piv_fftmulti.py         # FFT-based PIV processing
    │   ├── piv_loop.py             # PIV processing loop
    │   ├── piv_pipeline.py         # Main PIV pipeline
    │   └── video_to_frames.py      # Video frame extraction
    └── docs

---

📚 Jupyter Examples

Browse through our collection of Jupyter Notebook examples to learn how to use RIVeR for various analyses (requires development installation):

• 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 described above.

🔬 Citation

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}
}

---

👥 Authors

Core Team

• Antoine Patalano - Project Lead, Feature Development - [UNC/ORUS]
• Leandro Massó - Feature Development - [UNC/ORUS]

Development Team

• Nicolas Stefani - CLI & Backend Development
• Tomas Stefani - Frontend Development
• Agustín Patrito - Frontend Development

---

🤝 Contributing

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.

---

📜 License

RIVeR is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0).

---

💭Acknowledgments

• Contributing organizations:

  • UNC (National University of Córdoba) - Faculty of Exact, Physical and Natural Sciences
  • INA (National Institute of Water, Argentina)
  • CONICET (National Scientific and Technical Research Council)

• 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