ReefTone

ReefTone is a non-destructive underwater color-restoration studio. It combines an adaptive Python image pipeline with a responsive local web interface, so it feels like a focused desktop editor today and can grow into a hosted product later.

What is included

• HEIC/HEIF, JPEG, PNG, and TIFF input
• base bit-depth, ICC/P3, transfer-function, HDR gain-map, and auxiliary-image detection
• float32 processing from decode through correction
• scene analysis for red attenuation, cyan cast, haze, and low light
• underwater red compensation and confidence-gated white balance
• research-backed multiscale fusion of color-balanced and contrast-enhanced inputs
• exposure, contrast, black/white points, tone, vibrance, clarity, and denoise
• a neutral-point eyedropper plus per-slider reset and non-destructive bypass
• a real-time before/after editor with distinct presets, undo/redo, drag-and-drop, and keyboard-accessible controls
• point-centered magnifier zoom, fixed pixel-ratio views, and drag-to-pan
• collapsible source color-space and dynamic-range information
• full-resolution JPEG, PNG, and 16-bit TIFF export
• 10-bit HEIC export with source ICC, EXIF, and available XMP preservation
• format-specific color-fidelity guidance before export
• a framework-independent processing core designed to be reused on video frames

Source photos remain exactly where they are and are ignored by Git. Uploaded images are copied to a local, ignored cache. ReefTone never overwrites an original.

Quick start

Requires Python 3.11 or newer.

python3 -m venv .venv
source .venv/bin/activate
python -m pip install -e ".[dev]"
reeftone

Then open http://127.0.0.1:8765. On macOS, you can also double-click run.command after the first setup.

Stop the local service with Ctrl+C or by closing its Terminal window. ReefTone does not terminate on a browser unload event: browsers do not reliably distinguish a deliberate close from a reload, crash, sleeping tab, or another still-open tab, so automatic shutdown could interrupt an export.

The photos already in this folder appear as a private local library on the welcome screen. You can also drag a file anywhere over the app.

Recommended workflow

1. Open a photo and start with Natural. Use Dramatic for a warmer, darker, high-contrast treatment.
2. Use the comparison divider to check skin, coral, and open-water gradients.
3. Adjust Red recovery before adding saturation. This restores missing balance more naturally than globally boosting color.
4. Use Fusion clarity to blend in the multiscale contrast branch.
5. Export a JPEG for sharing or a 16-bit TIFF as a high-quality editing master.

Use the eyedropper only on something that should be gray, white, or neutral. ReefTone averages a small patch and balances it without changing any other slider. The arrow beside a slider resets only that setting; the eye button temporarily bypasses it while preserving the chosen value.

Keyboard shortcuts:

• ⌘/Ctrl + Z: undo
• ⇧ + ⌘/Ctrl + Z: redo
• hold \: momentarily reveal the original
• arrow keys on the comparison divider: move it precisely

Project structure

src/reeftone/
  processor.py      Adaptive correction engine
  image_io.py       HEIC/JPEG decode and high-quality export
  config.py         Validated controls and presets
  app.py            Local FastAPI application
  session.py        Bounded, private preview sessions
  static/           Responsive editor UI
tests/               Unit and API tests
docs/                Architecture and roadmap

Development

source .venv/bin/activate
pytest
ruff check .

For automatic reload while working on the interface:

uvicorn reeftone.app:app --reload --port 8765

ReefTone follows Semantic Versioning. See the changelog for the history and release process for the version checklist and commit conventions.

Color and precision notes

HEIC files are decoded with their orientation and embedded ICC metadata. ReefTone records the source bit depth and performs every correction in float32. JPEG and PNG exports are 8-bit delivery files; TIFF export is a 16-bit RGB master. Embedded ICC and EXIF blocks are retained for JPEG/PNG when the source decoder exposes them.

The current release is display-referred: it is optimized for Apple HEIC and standard JPEG photographs rather than camera RAW development. See the algorithm notes for details and limitations. The measurements behind the Dramatic look are recorded in the reference-style analysis.

Apple gain-map HDR is now detected and reported separately from the SDR base. ReefTone does not copy an unchanged gain map onto edited pixels or falsely tag an SDR result as HDR. The exact preservation matrix and native HDR roadmap are in the color-management notes.

Video roadmap

The correction function already accepts a single RGB array with no UI or file-system coupling. The video phase will add:

• FFmpeg-based HEVC/H.265 and HDR10 decode
• transfer-function-aware linearization (PQ, HLG, and SDR)
• temporal smoothing of analysis and gains to prevent flicker
• scene-change detection
• hardware-accelerated preview and encode
• audio, timing, and metadata passthrough

Video is intentionally not exposed in this first release; a still-image pipeline is much easier to validate for color correctness before adding temporal behavior.

License

MIT — see LICENSE.