MHKiT-DOLFyN GUI

A desktop GUI for reading, inspecting, and exporting ADCP and ADV binary instrument data to standardized NetCDF (.nc) files. Powered by mhkit.dolfyn, the Doppler Oceanographic Library for Python included in MHKiT-Python.

Workflow

1. Import files

Browse your filesystem and add binary instrument files to the conversion queue. Files load in parallel and appear in the queue with a Ready status as soon as they are converted into an intermediate format (xarray Dataset) for analysis prior to export.

Manufacturer	Instrument	Type	Extensions
Nortek	Signature	ADCP	.ad2cp
Nortek	Vector	ADV	.vec
Nortek	AWAC	ADCP	.wpr
Teledyne RDI	Workhorse, RiverPro, and others	ADCP	.000 .ens .enx .lta .pd0 .sta

2. Review datasets

The Review panel shows a dataset summary for each file. Switch to the Per-File tab to browse every variable, dimension, and coordinate axis; click any variable to see its shape, type, statistics, and sample values.

When multiple files are loaded, the Combined tab gives a deployment-level overview: total time coverage, ensemble counts, and automatic warnings for instrument mismatches, coordinate-system differences, or unexpected time gaps between files.

3. Add deployment metadata (optional)

Use the Custom Deployment Metadata editor to create or attach a userdata.json sidecar file. This lets you supply information the binary file cannot record — magnetic declination (required for true-north ENU rotations), deployment coordinates, instrument depth, orientation, and salinity. mhkit.dolfyn reads this file automatically alongside the binary data.

4. Export to NetCDF

Configure an output directory and filename pattern in the Export panel, select which files to include, and click Export. Each file is saved as a self-describing NetCDF (.nc) using mhkit.dolfyn.

Show Code generates a standalone Python script that reproduces the exact same conversion — useful for scripted pipelines or sharing reproducible workflows.

Event log and preferences

The Event Log at the bottom of the window logs events with timestamps. Useful for tracking file processing and exporting actions.

Preferences (status bar → Preferences) lets you tune concurrent read threads, the in-memory dataset cache, time-gap detection thresholds, and default output paths.

Installation

MHKiT-DOLFyN GUI requires Python 3.11+. It is recommended to use Miniconda or the Anaconda Python Distribution.

Option 1: Run from source (recommended)

Clone the repo and create the Conda environment. environment.yml installs all runtime dependencies (mhkit, PySide6, netCDF4, HDF5, PyYAML, psutil), so you can launch immediately with run.py — no package install needed.

git clone https://github.com/MHKiT-Software/mhkit_dolfyn_pyqt_gui

cd mhkit_dolfyn_pyqt_gui

conda env create -f environment.yml

conda activate mhkit-dolfyn-gui

python run.py

Option 2: Build a standalone app bundle (PyInstaller)

Produces a self-contained MHKiT-DOLFyN.app (macOS) or MHKiT-DOLFyN.exe (Windows) in dist/ that runs without a Python environment. Start from the Option 1 setup steps, then:

pip install -e ".[dev]"

pyinstaller mhkit_dolfyn.spec --noconfirm

The built bundle will be at dist/MHKiT-DOLFyN/ (or dist/MHKiT-DOLFyN.app on macOS).

Option 3: pip install with CLI entry point

Install the package to get the mhkit-dolfyn-gui command available anywhere on your PATH. Start from the Option 1 setup steps, then:

pip install -e .

Then launch from any directory:

mhkit-dolfyn-gui

Development

Install with development dependencies:

pip install -e ".[dev]"

Run tests, linting, and formatting checks:

ruff check src/ tests/
ruff format --check src/ tests/
pytest -v

Copyright and license

MHKiT-DOLFyN GUI is copyright through the National Laboratory of the Rockies, Pacific Northwest National Laboratory, and Sandia National Laboratories. The software is distributed under the Revised BSD License. See copyright and license for more information.