pingverter 2.1.4

A Python-based converter for sonar logs used by PINGMapper

A Python-based convertor for sonar logs collected with consumer-grade fishfinders.

PINGVerter is designed to pre-process sonar logs for PINGMapper post-processing. It is not intended to function as a stand-alone package.

Compatibility

• Humminbird ( *.DAT/ *.SON/ *.IDX)
• Lowrance ( *.sl2 / *.sl3)
• Garmin (*.RSD)
• Cerulean (Omniscan 450 SS *.svlog)
• EdgeTech JSF (*.jsf)
• XTF (*.xtf)

Installation

pip install pingverter

Usage - Example Only

PINGVerter can be used as a stand-alone engine for decoding sonar logs and exporting ping attributes to CSV. While this functionality is described here, please use PINGMapper for all sonar log processing.

Humminbird

# Import
from pingverter import hum2pingmapper

# Parameters
inFile = r'C:\Path\To\Recording\Rec00001.DAT'
projDir = r'C:\Path\To\Outputs\MyProject'

sonar_object = hum2pingmapper(inFile, projDir)

Lowrance

# Import
from pingverter import low2pingmapper

# Parameters
inFile = r'C:\Path\To\Recording\Log.sl2'
projDir = r'C:\Path\To\Outputs\MyProject'

sonar_object = low2pingmapper(inFile, projDir)

Lowrance SL2/SL3 files can also be exported as synchronized raw sample projects for viewer applications, with optional per-beam waterfall PNG previews:

from pingverter import low

inFile = r'C:\Path\To\Recording\Log.sl3'
outDir = r'C:\Path\To\Outputs\SonarProject'

sonar_object = low(inFile, nchunk=500, exportUnknown=True)
manifest = sonar_object.write_sonar_data_player_project(outDir, include_pngs=True)

The project writer creates manifest.json, pings.csv, frames.jsonl, samples.u16le, and one channel PNG per decoded Lowrance beam. Lowrance sample payloads are expanded to uint16-le for compatibility with viewers that share the Garmin project sample format.

Garmin

# Import
from pingverter import gar2pingmapper

# Parameters
inFile = r'C:\Path\To\Recording\Log.RSD'
projDir = r'C:\Path\To\Outputs\MyProject'

sonar_object = gar2pingmapper(inFile, projDir)

Garmin RSD files can also be exported as synchronized raw sample projects for viewer applications, with optional per-channel waterfall PNG previews:

from pingverter import gar

inFile = r'C:\Path\To\Recording\Log.RSD'
outDir = r'C:\Path\To\Outputs\SonarProject'

sonar_object = gar(inFile, nchunk=500, exportUnknown=True)
manifest = sonar_object.write_sonar_data_player_project(outDir, include_pngs=True)

The project writer creates manifest.json, pings.csv, frames.jsonl, samples.u16le, and one channel PNG per decoded Garmin channel. The same project format is consumed by SonarDataPlayer.

You can also use the shared export API for any supported source format:

from pingverter import export_sonar_data_player_project

inFile = r'C:\Path\To\Recording\Line001.xtf'
outDir = r'C:\Path\To\Outputs\SonarProject'

manifest = export_sonar_data_player_project(inFile, outDir, include_pngs=True)

Cerulean

# Import
from pingverter import cerul2pingmapper

# Parameters
inFile = r'C:\Path\To\Recording\Log.svlog'
projDir = r'C:\Path\To\Outputs\MyProject'

sonar_object = cerul2pingmapper(inFile, projDir)

JSF

# Import
from pingverter import jsf2pingmapper

# Parameters
inFile = r'C:\Path\To\Recording\Line001.jsf'
projDir = r'C:\Path\To\Outputs\MyProject'

sonar_object = jsf2pingmapper(inFile, projDir)

XTF

# Import
from pingverter import xtf2pingmapper

# Parameters
inFile = r'C:\Path\To\Recording\Line001.xtf'
projDir = r'C:\Path\To\Outputs\MyProject'

sonar_object = xtf2pingmapper(inFile, projDir)

Outputs from the above examples will be exported to C:\Path\To\Outputs\MyProject\meta.

Acknowledgments

PINGVerter has been made possible through mentorship, partnerships, financial support, open-source software, manuscripts, and documentation linked below.

NOTE: The contents of this repository are those of the author(s) and do not necessarily represent the views of the individuals and organizations specifically mentioned here.

• Dr. Arthur Trembanis (Post-Doc Advisor) & Dr. Daniel Buscombe (PhD Advisor)

• Coastal Sediments, Hydrodynamics and Engineering Lab (CSHEL), College of Earth, Ocean, & Environment (CEOE), University of Delaware

• PINGMapper

  • 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
  • Bodine, C. S., Buscombe, D., & Hocking, T. D. (2024). Automated river substrate mapping from sonar imagery with machine learning. Journal of Geophysical Research: Machine Learning and Computation, 1, e2024JH000135. https://doi.org/10.1029/2024JH000135

• PyHum

  • Buscombe, D., Grams, P.E., and Smith, S. (2015) "Automated riverbed sediment classification using low-cost sidescan sonar", Journal of Hydraulic Engineering, https://doi.org/10.1061/(ASCE)HY.1943-7900.0001079, 06015019.
  • Buscombe, D., 2017, Shallow water benthic imaging and substrate characterization using recreational-grade sidescan-sonar. ENVIRONMENTAL MODELLING & SOFTWARE 89, 1-18.

• 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 - Kenneth Thoro Martinsen

• Navico (Lowrance, Simrad, B&G) Sonar Log File Format - Herbert Oppmann

• Garmin Sonar Log File Format - Herbert Oppmann

• Blue Robotics (BR)

• BR Ping Protocol

• Cerulean Sonar

• Cerulean Sonar Docs

• Blue Robotics Ping Protocol

• SidescanTools

  • SidescanTools is an open-source software to read and process data from side-scan sonar instruments.

• Vincent Capone - Black Laser Learning

Future Development, Collaborations, & Partnerships

If you are interested in partnering on future developments, please reach out to Cameron Bodine.