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, accuracy assessment relative to field measurements, and export of results.

## Installation
To begin using TRiVIA, download the file [TRiVIA.zip](https://code.usgs.gov/wma/osd/trivia/-/blob/main/TRiVIA.zip) from the root directory of the main branch on this repository. The zip archive contains the current version of the TRiVIA installer and a tutorial illustrating how to use the software. Note that although TRiVIA does not require that the end user have a MATLAB license, the free MATLAB Component Runtime (MCR) must be installed locally and is included in the installer in TRiVIA.zip. To install both MCR and the TRiVIA app itself, unzip TRiVIA.zip and run the installer file.

## 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: [TRiVIA_TutorialV1.6.pdf](https://code.usgs.gov/wma/osd/trivia/-/blob/main/doc/TRiVIA_TutorialV1…).

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 TRiVIAv15.mlapp contains the code behind the graphical user interface. 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 two typical use cases: [TRiVIA_TutorialV1.6.pdf](https://code.usgs.gov/wma/osd/trivia/-/blob/main/doc/TRiVIA_TutorialV1…).

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

## Roadmap
This initial release of TRiVIA focuses on estimating surface flow velocities from nadir-viewing image time series. Possibilities for future enhancement of the software include allowing for bathymetric input so that river discharge can be calculated, adding export formats suitable with visualization packages such as Tableau, and improving the geo-referencing module.

## 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 primary developer, Carl J. Legleiter, at [cjl@usgs.gov](mailto:cjl@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 [Glacier Image Velocimetry Toolbox ](https://github.com/MaxVWDV/glacier-image-velocimetry) developed by Maximillian Van Wyk de Vries and Andrew D. Wickert and described in the following publication:
de Vries, M., & Wickert, A. D. (2021). Glacier Image Velocimetry: an open-source toolbox for easy and rapid calculation of high-resolution glacier velocity fields. The Cryosphere, 15(4), 2115–2132. https://doi.org/10.5194/tc-15-2115-2021

## 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 initial version, 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., 2022, TRiVIA - Toolbox for River Velocimetry using Images from Aircraft (ver. 1.5, December, 2022): U.S. Geological software release, https://doi.org/10.5066/P9AD3VT3.