catchmentsci / klt-iv

Image velocimetry software for use with fixed and mobile platforms

KLT-IV

Image velocimetry software for use with fixed and mobile platforms

📖 Table of Contents

Table of Contents

1. ➤ About The Project
2. ➤ Prerequisites
3. ➤ Repository Structure
4. ➤ Getting started
5. ➤ Legal
6. ➤ Published works using KLT-IV

📝 About The Project

This project seeks to provide software capable of accurately estimating 2D river flow velocities and flow discharge using optical imagery acquired from a range of remote sensing platforms. A complete workflow is provided which enables a range of video formats (mp4, avi, etc) to be used as the basis for analysis. Image stabilisation routines are available when using mobile platforms (e.g. UAVs), and orthorectification of vectors, or imagery is dealt with through application of a distorted camera model. Image analysis utilises the Kanade-Lucas-Tomasi feature detection and tracking procedures providing 2D velocity vectors. Post-processing of vectors is achieved through application of threshold filters and angle-based trajectory filtering. Discharge analysis is completed through application of surface α and inclusion of cross-section data.

🍴 Prerequisites

This project requires MATLAB 2019a, or later in addition to the following packages:

• Mapping Toolbox
• Image Processing Toolbox
• Statistics and Machine Learning Toolbox
• Curve Fitting Toolbox
• Computer Vision Toolbox

The following open source packages are used in this project:

• ffmpeg
• imGRAFT
• mlapptools

🌵 Repository Structure

• There are currently two branches of KLT-IV software on Git.
• v1.02 is the most recent, tested version.
• main is undergoing active development and has not been fully tested.

Below is the an outline of the folder structure within the main branch with descriptions provided:

.
├── code                    # folder containing scripts to run KLT-IV
│   ├── depreciated         # a number of files no longer used by KLT-IV
│   ├── external            # third party software required
│   ├── ffmpeg              # video editing/encoding software
│   ├── gui                 # files required to build the GUI
│   ├── klt                 # core files for running KLT-IV functions
├── compiled                # folder containing installation files for compiled version
│   ├── for_redistribution  # folder containing installation files for KLT
├── compiled resources      # additional resources for compilation
├── images                  # folder containing graphics for KLT-IV

🏃 Getting started

• Either download, or clone this repository to the hard drive on your PC.
• Open MATLAB, ensure that the folder and all sub-folders from this repository are present on the search path e.g. addpath(genpath('D:\KLT-IV\')).
• Either open the KLT.m file from within the klt subfolder and click Run (in Editor tab), or type KLT in to the command window. This will load the GUI.
  
• A full outline of the workflow and description of the functionality can be found here
• If you use this software, please cite using the information provided in the cite this repository tab which can be found in the About section at the top right of this page

👮 Legal

Disclaimer: This software is provided “as is”, without warranty of any kind, express or implied, including but not limited to the warranties of merchantability, fitness for a particular purpose and noninfringement. In no event shall the authors or copyright holders be liable for any claim, damages or other liability, whether in an action of contract, tort or otherwise, arising from, out of or in connection with the software or the use or other dealings in the software.

License: Licensing information can be found in the LICENSE.txt file

📑 Published works using KLT-IV

• Dariia Strelnikova, et al., (2022) Rapid detection of the change in surface flow patterns near fish passages at hydropower dams with the use of UAS based videos under controlled discharge conditions. Frontiers: Remote Sensing 3(798973). https://www.frontiersin.org/articles/10.3389/frsen.2022.798973/

• Robert Ljubičić, et al. (2021) A comparison of tools and techniques for stabilising unmanned aerial system (UAS) imagery for surface flow observations. Hydrology and Earth System Sciences 25(9): 5105-5132. https://hess.copernicus.org/articles/25/5105/2021/

• Matthew T Perks (2020) KLT-IV v1.0: Image velocimetry software for use with fixed and mobile platforms. Geoscientific Model Development 13(12): 6111-6130. https://gmd.copernicus.org/articles/13/6111/2020/

• Sophie Pearce, et al. (2020) An evaluation of image velocimetry techniques under low flow conditions and high seeding densities using unmanned aerial systems. Remote Sensing 12(2): 232. https://www.mdpi.com/2072-4292/12/2/232

• Matthew T. Perks, Andrew J. Russell, and Andrew RG Large (2016) Advances in flash flood monitoring using unmanned aerial vehicles (UAVs). Hydrology and Earth System Sciences 20(10): 4005-4015. https://hess.copernicus.org/articles/20/4005/2016/

Logo and splash screen artwork created by Kelly Stanford https://kellystanford.co.uk/

klt-iv's Issues

Add the option to display the trajectories plot but in pixel coordinates

When displaying output trajectories have the option to display the same plot but in pixel coordinates? Also very helpful when doing post-processing.

Add option to show entire frame, not just boundaries of the ROI

When plotting the trajectories for the velocities, would it be possible to show the entire frame and not just the boundaries of the ROI? Since we need to geo-reference the results afterwards it would be helpful the see the whole image.