Pingmapper

PINGMapper v2.0.0-alpha adds to existing functionality from v1.0.0 and many bug fixes. The new features will be documented in a forthcoming manuscript, at which time a production-ready release will be made. Bugs are expected!!! Please report them [here](https://github.com/CameronBodine/PINGMapper/issues).

New Features
**Automated Substrate Classification**
Neural network models trained with [Segmentation Gym](https://github.com/Doodleverse/segmentation_gym) have been incorporated into PINGMapper. The models will perform a pixel-wise prediction across 6 different substrate classes [Fines - Rippled, Fines - Flat, Cobble - Boulder, Hard Bottom, Wood, Other]. Plots of the predictions can be optionally exported. Raster and polygon maps can also be exported and overlayed on the sonar mosaics.

_NOTE: Exercise caution when interpreting and using the outputs from the substrate prediction. The models were trained on two river systems in Mississippi. It is currently unknown how well the models will perform on other aquatic systems._

**Image Corrections**
To correct for the impact of attenuation on the sonar imagery, a new feature called Empirical Gain Normalization (EGN) is now available. This process involves calculating the average pixel intensity for each range bin and dividing the raw backscatter by the associated average.

_NOTE: Correcting imagery with EGN does take some time; please be patient._

**Use Matplotlib colormaps on sonar mosaics**
You can now assign one of matplotlibs [many colormaps](https://matplotlib.org/stable/tutorials/colors/colormaps.html) to sonar mosaics.

Ready to get started?

**New PINGMapper Users**
Please follow the [installation instructions](https://cameronbodine.github.io/PINGMapper/docs/gettingstarted/Installation.html).

**Existing PINGMapper Users**
Update your current installation by following these [instructions](https://cameronbodine.github.io/PINGMapper/docs/gettingstarted/UpdateInstallation.html).

Then check to make sure everything is running as expected by running the [test](https://cameronbodine.github.io/PINGMapper/docs/gettingstarted/Testing.html).

New workflows, models, and bug fixes added to PING-Mapper since v1.0.0:

- Automated depth detection (31)
- Automated shadow removal (37, updated model coming in near future)
- Export speed corrected non-rectified images for labeling w/ Doodler (35)
- Process corrupt recordings w/ missing data (33)
- Addressed memory leaks during batch processing (38)
- And other minor bug fixes...

What's Changed
* Development --> Main by CameronBodine in https://github.com/CameronBodine/PINGMapper/pull/40
* Merge pull request 40 from CameronBodine/development by CameronBodine in https://github.com/CameronBodine/PINGMapper/pull/41
* Merge pull request 41 from CameronBodine/main by CameronBodine in https://github.com/CameronBodine/PINGMapper/pull/42


**Full Changelog**: https://github.com/CameronBodine/PINGMapper/compare/v1.0.0...v1.1.0

[)](https://pypi.org/project/pingverter/)
[PINGVerter](https://github.com/CameronBodine/PINGVerter) is a new Python-based convertor for sonar logs collected with consumer-grade fishfinders. `PINGMapper` now uses [PINGVerter](https://github.com/CameronBodine/PINGVerter) as the primary processing engine for decoding sonar logs. It is designed to ease adding support for new sonar data acquisition platforms and filetypes. Find out more below...

Support for Lowrance®
It is now possible to process **sl2** and **sl3** files with `PING-Mapper`. All of the processing features `PING-Mapper` made possible for Humminbird® are now available for Lowrance®. This includes EGN corrections, shadow removal, depth detection, substrate mapping, etc.

Acknowledgments
Adding support for sl2/3 files would not have been possible without these incredible open-source projects and documentation:
- [SL3Reader](https://github.com/halmaia/SL3Reader)
- Halmai, Akos; Gradwohl Valkay, Alexandra; Czigany, Szabolcs; Ficsor, Johanna; Liptay, ZoltAn Arpad; Kiss, Kinga; Loczy, Denes and Pirkhoffer, Ervin. 2020. "Applicability of a Recreational-Grade Interferometric Sonar for the Bathymetric Survey and Monitoring of the Drava River" ISPRS International Journal of Geo-Information 9, no. 3: 149. https://doi.org/10.3390/ijgi9030149
- [sonarlight](https://github.com/KennethTM/sonarlight) - Kenneth Thoro Martinsen
- [Navico (Lowrance, Simrad, B&G) Sonar Log File Format](https://www.memotech.franken.de/FileFormats/Navico_SLG_Format.pdf) - Herbert Oppmann


*Please report any issues with processing sl2 or sl3 files [here](https://github.com/CameronBodine/PINGVerter/issues)*

~1.3x Speedup
[PINGVerter](https://github.com/CameronBodine/PINGVerter) and `PINGMapper` now feature an improved mechanism for reading sonar logs, inspired by [sonarlight](https://github.com/KennethTM/sonarlight). This results in **~1.3x speedup** when running the [Small Dataset Test](https://cameronbodine.github.io/PINGMapper/docs/gettingstarted/Testing.html#small-dataset-test).

Overview

PING-Mapper is a Python interface for reading, processing, and mapping side scan sonar data from Humminbird® sonar systems. This release is the archived version of PING-Mapper v1.0.0 (6/1/2022) described in the companion manuscript:

Bodine, C. S., Buscombe, D., Best, R. J., Redner, J. A., & Kaeser, A. J. (2022). PING-Mapper: Open-source software for automated benthic imaging and mapping using recreation-grade sonar. Earth and Space Science, 9, e2022EA002469. [https://doi.org/10.1029/2022EA002469](https://doi.org/10.1029/2022EA002469)

Features

**Decode Humminbird® Sonar Recordings**
PING-Mapper will automatically decode sonar recordings (***.DAT, ***.SON, ***.IDX files) from any Humminbird model (tested on 1197, 1198, 1199, Helix, Solix, Onix models).

**Export Ping Attributes**
All associated ping attributes (latitude, longitude, heading, depth, etc.) are automatically exported to ***.CSV.

**Export Sonograms**
Option to export non-georectified sonograms with the water column present (WCP) or with the water column removed (WCR) based on the Humminbird® sensor depth estimates and slant-range correction with a flat-bottom assumption.

**Export Trackline**
A smoothed trackline is fit to raw GPS coordinates. New coordinates are re-interpolated along the smoothed trackline to ensure optimal sonar mosaics.

**Export Sonar Mosaics** 
Export georectified sonar mosaics as geotiff with the water column present (WCP; spatially inaccurate bed locations due to presence of water column) or water column removed (WCR; spatially accurate bed locations) for further analysis in any GIS.

Full Changelog
https://github.com/CameronBodine/PINGMapper/compare/data...v1.0.0

data
Sample sonar recording from the Pearl River, MS.

- Instrument: Humminbird Solix w/ Mega Imaging.

- Date collected: March 3, 2021.

- Duration: 01h:00m:06s.

Distributed with permission from the U.S. Fish and Wildlife Service.