Toolbox for River Velocimetry using Images from Aircraft (TRiVIA)

# TRiVIA
Toolbox for River Velocimetry using Images from Aircraft: TRiVIA

## Description
The Toolbox for River Velocimetry using Images from Aircraft, or TRiVIA for short, is an application to facilitate estimation of surface flow velocities in river channels from various types of remotely sensed data acquired with a nadir-viewing geometry (i.e., looking straight down). Spatially distributed information on flow speed is derived using a computational method known as Particle Image Velocimetry (PIV). TRiVIA provides an integrated workflow for video/image import and subsetting, image stabilization, geo-referencing, region of interest definition, image pre-processing, PIV, visualization, accuracy assessment relative to field measurements, discharge calculation based on an independent source of depth information provided by the user, moving aircraft river velocimetry, and export of results.

## Installation
The top level of this repository includes a zip file that contains an installer for the latest version of TRiVIA as well as a tutorial document that illustrates how to use the software. Note that although TRiVIA does not require the end user to have a MATLAB license, the free MATLAB Component Runtime (MCR) must be installed locally. To begin using TRiVIA, download [TRiVIA.zip](https://code.usgs.gov/wma/osd/trivia/-/blob/main/TRiVIA.zip) from the root directory of this repository. To install the latest version of the TRiVIA app (along with MCR if you do not already have it), unzip TRiVIA.zip and run the installer.

## Usage
For an example application of TRiVIA that illustrates how to use the software using data sets freely available through the USGS ScienceBase catalog, please refer to the tutorial document that is included in the zip archive and also available in the doc folder of this repository: [TRiVIAtutorialV2_2.pdf](https://code.usgs.gov/wma/osd/trivia/-/blob/main/doc/v2.2/TRiVIAtutoria…). In addition, a new tutorial focused on images acquired from an Uncrewed Aircraft System (UAS) and featuring a different example data set has been added: [UAS_TRiVIAtutorialV2_1.pdf](https://code.usgs.gov/wma/osd/trivia/-/blob/main/doc/v2.1/UASexample/UA…).

The code folder in this repository contains the MATLAB source code used to develop TRiVIA. The software was produced using MATLAB's App Designer and the main file [TRiVIAv2_2_1.mlapp](https://code.usgs.gov/wma/osd/trivia/-/blob/main/code/app/TRiVIAv2_2_1…) contains the code behind the graphical user interface, which is also exported to the plain text file [TRiVIAv2_2_1_exported.m](https://code.usgs.gov/wma/osd/trivia/-/blob/main/code/app/TRiVIAv2_2_1_…). Additional helper functions called by the app are also available as *.m files in various subfolders of the code folder.

## Support
The doc folder in this repository includes a tutorial that explains how to use TRiVIA for several typical use cases: [TRiVIAtutorialV2_2.pdf](https://code.usgs.gov/wma/osd/trivia/-/blob/main/doc/v2.2/TRiVIAtutoria…). A second, abbreviated tutorial focuses on images acquired from an Uncrewed Aircraft System (UAS): [UAS_TRiVIAtutorialV2_1.pdf](https://code.usgs.gov/wma/osd/trivia/-/blob/main/doc/v2.1/UASexample/UA…).

For technical questions or issues regarding TRiVIA, please contact the developers at [TRiVIAinfo@usgs.gov](mailto:TRiVIAinfo@usgs.gov).

## Roadmap
The current release of TRiVIA focuses on estimating surface flow velocities from nadir-viewing image time series acquired from either stationary or moving aircraft. Possibilities for future enhancement of the software include approaches for inferring water depth based on image-derived velocity estimates and other channel characteristics.

## Contributing
If you have additional feature requests or would like to collaborate to improve TRiVIA, please refer to [CONTRIBUTING.md](https://code.usgs.gov/wma/osd/trivia/-/blob/main/CONTRIBUTING.md) contact the developers at [TRiVIAinfo@usgs.gov](mailto:TRiVIAinfo@usgs.gov).

## Authors and acknowledgment
Carl J. Legleiter ([cjl@usgs.gov](mailto:cjl@usgs.gov)) is the lead developer for TRiVIA and is supported through the USGS Water Mission Area's Next Generation Water Observing System (NGWOS). Paul Kinzel, Geoff DeBenedetto, and Frank Engel all provided useful feeback during the initial development process. The core PIV algorithm included in TRiVIA was adapted from the [PIVlab Toolbox](https://github.com/Shrediquette/PIVlab) developed by William Thielicke and described in the following publications:
- Thielicke, W., & Stamhuis, E. J. (2014). PIVlab - Towards User-friendly, Affordable and Accurate Digital Particle Image Velocimetry in MATLAB. Journal of Open Research Software, 2(1), e30. [https://doi.org/10.5334/jors.bl](https://doi.org/10.5334/jors.bl)
- Thielicke, W., & Sonntag, R. (2021). Particle Image Velocimetry for MATLAB: Accuracy and enhanced algorithms in PIVlab. Journal of Open Research Software, 9(1), 12. [https://doi.org/10.5334/jors.334](https://doi.org/10.5334/jors.334)

The stabilization module incorporates functionality from the VISION tool described in the following publication:
- Pizarro, A., Dal Sasso, S. F., & Manfreda, S. (2022). VISION: VIdeo StabilisatION using automatic features selection for image velocimetry analysis in rivers. SoftwareX, 19, 101173. [https://doi.org/10.1016/j.softx.2022.101173](https://doi.org/10.1016/j.softx.2022.101173)

## License
TRiVIA is licensed under the Creative Commons Zero v1.0 Universal [LICENSE.md](https://code.usgs.gov/wma/osd/trivia/-/blob/main/LICENSE.md).

## Project status
The TRiVIA project is ongoing and the lead developer is committed to refining the software, adding new features, and responding to user needs.

## USGS project metadata
The USGS IPDS record associated with this software is: IP-144279

The Digital Object Identifier (DOI) for this software is: [https://doi.org/10.5066/P9AD3VT3](https://doi.org/10.5066/P9AD3VT3)

## Disclaimer
This software has been approved for release by the U.S. Geological Survey (USGS). Although the software has been subjected to rigorous review, the USGS reserves the right to update the software as needed pursuant to further analysis and review. No warranty, expressed or implied, is made by the USGS or the U.S. Government as to the functionality of the software and related material nor shall the fact of release constitute any such warranty. Furthermore, the software is released on condition that neither the USGS nor the U.S. Government shall be held liable for any damages resulting from its authorized or unauthorized use.

Any use of trade, firm, or product names is for descriptive purposes only and does not imply endorsement by the U.S. Government.

## Citation
This information product is in the public domain, however citation is appreciated.

Suggested citation:
Legleiter, C.J., 2025, TRiVIA - Toolbox for River Velocimetry using Images from Aircraft (ver. 2.2.1, July, 2025): U.S. Geological Survey software release, https://doi.org/10.5066/P9AD3VT3.