TEAMER: Underwater Target Detection Software Demonstration on the RivGen Turbine

This repository includes data, object detection models, and processing scripts necessary to evaluate the accuracy of the object detection models created for the underwater target detection software demonstration on the RivGen turbine project and to reproduce the performance metrics (precision, recall, mAP50, mAP50-95) presented in the report.

- Contents - 
The included data consist of "images" and "labels". Images and labels were curated from 2021 and 2024 smolt outmigration periods at the project site in Igiugig, AK. Images are monochrome 8-bit images of objects (smolt, debris, and other) passing through the field of view of the deployed cameras during various operational stages of the RivGen turbine. 

Labels are text files indicating the class and bounding polygon of each object in an image. 
File names for both images and labels are time strings with the the format %yyyy_%mm_%dd_%HH_%MM_%SS.%3f. 
Labels are saved in the Ultralytics YOLO format for segmentation models (https://docs.ultralytics.com/datasets/segment/), which is as follows:

Each image in the dataset (located in "image" directories) has a corresponding text file (located in "labels" directories) with the same name as the image file but with the ".txt" extension.
Within each .txt file, each row corresponds to an object instance in the image.

Each row contains the following information about the object instance:
Class Index: An integer representing the class of the object (e.g., 0 for person, 1 for car, etc.).
Polygon coordinates: A series of segmentation polygon coordinates around the mask area, normalized to be between 0 and 1.

For example, an image with two objects of class indicies '0', and '1', made up of 3-point and 5-point segments, respectively, would appear as follows:
0 0.681 0.485 0.670 0.487 0.676 0.487
1 0.504 0.000 0.501 0.004 0.498 0.004 0.493 0.010 0.492 0.0104

The list of classes for the multiclass model are found in "all_classes.yaml", where the class "names" correspond to the class index in each label. Model indices and class names for the multi-class model are:

Class Index: Class Name
0: other
1: smolt
2: debris

Similarly, the list of classes for the binary "smolt" model are found in "smolt.yaml", though only one class, "smolt", is included in this model:

Class Index: Class Name
0: smolt

The 2021 and 2024 "test" datasets are included. These data were used to evaluate the accuracy of models version 1 (V1), V2, and V3, as described in the report. These data are organized into "test" directories found in the "2021" and "2024" directories, e.g., /data/2021/test/.

The "train" and "val" directories are also present as the presence of these directories is necessary for the included script to run successfully, though the associated data is not included.

The model weights files are included for models V1, V2, and V3 in the models directory, e.g., /models/v1_model_train_2021_val_2021_test_2021.pt.

Finally, the python script "test_models.py" is included, which loads each model and tests it against the associated test dataset. The resulting accuracy metrics are saved to figures in a ./runs/detect/ directory, which will be created when the script is run on the user's machine. Instructions for installing and using the python script are included in the README.

- Requirements - 
All instructions assume the user is using a computer using Ubuntu Linux 20.04+ with Python3.8+. Operation on other operating systems may require some modification to these instructions. Models will run on your computer's CUDA-capable NVIDIA GPU if one is available.
The README.md provides instruction for installing the requirements from the requirements.py file. 

The included data was revised/updated to reflect the post-access report for the project. Resource titles and descriptions were updated to reflect the most up-to-date resources. The file names were updated by adding a "_Ver1" and "_Ver2" to the end of the outdated file and a "_Ver3" to the end of the revised file. Two updates have occurred for this data set and can be followed using the file naming.

Tags: ak, alaska, cross-flow, data, detection, hydrokinetic, igiugig, images, machine-learning, marine, mhk, ml, perfomance-metrics, processing-scripts, python, rivgen, rivgen-turbine, salmon, smolt, software-demonstration, teamer, tracking, underwater-target-detection
Organization: Department of Energy