GitHub - noppanut15/depthviz: Visualize your depth for your freediving videos: Works with or without dive computers.

✨ Features

Why use depthviz?

• 🎥 Stunning Depth Overlays – Turn dive logs into smooth, real-time depth displays.
• 💻 Works Anywhere – Runs on Windows, macOS, and Linux.
• 📊 Dive Log Friendly – Supports Apnealizer, Garmin, Suunto, Shearwater, and even manually recorded logs!
• 🎨 Fully Customizable – Adjust fonts, colors, decimal places, stroke width, and more.
• 🔗 Easy Video Integration – Works with CapCut, Premiere Pro, and other editors.
• ⚡ Smart Depth Smoothing – Automatically fills in missing data for a seamless and natural depth display. Includes zero-based depth mode to smoothly estimate a 0m start if your dive log starts underwater.

🌟 Like depthviz?

If you like depthviz and find it useful, please give it a shiny ✨

Get early access to new open-source projects, exclusive insights, and sneak peeks at upcoming depthviz features! 🚀

I’d love to see your diving stories or videos made with depthviz! Share your creations by tagging @noppanut15 or using #depthviz.

See you in the deep! 🌊😊

🛠️ Installation

Prerequisites

• Python 3.9 to 3.13
  Download Python • How to install Python
• pipx – the recommended tool for installing Python CLI tools
  How to install pipx

Install depthviz

Open your terminal and run:

Upgrade

When a new version is available, update with:

Check your current version:

🚀 Usage

🏁 First Time Using depthviz?

Start with this quick example:

depthviz -i my_dive.fit -s garmin -o overlay.mp4

• 📂 -i: Your dive log file
• 🔍 -s: Data source (garmin, suunto, etc.)
• 🎬 -o: Name of output video

For full customization, keep reading! 🚀

📌 Step 1: Prepare Your Dive Data

• 🙆 With a Dive Computer:
  Export your dive log from your dive computer or diving application. (see Supported Dive Log Formats below).
• 🙅 No Dive Computer?
  You can record your dive manually (details in No Dive Computer?).

📌 Step 2: Generate the Overlay

Run this command to create your depth overlay video from your dive log:

depthviz -i YOUR_DIVE_LOG -s DATA_SOURCE -o OUTPUT_VIDEO.mp4

Example (Garmin dive log):

depthviz -i 123456_ACTIVITY.fit -s garmin -o my_dive_overlay.mp4

📂 Supported Dive Log Formats

Source	Description	File type
apnealizer	Exported logs from the Apnealizer app.	CSV
shearwater	Logs from Shearwater dive computers.	XML
garmin	Logs from Garmin dive computers.	FIT
suunto	Logs from Suunto dive computers.	FIT
manual	Manually entered depth logs.	CSV

⚙️ Advanced Customization Options

depthviz \
    -i 123456_ACTIVITY.fit -s garmin -o mydive.mp4 \
    --depth-mode zero-based \
    --decimal-places 1 \
    --no-minus \
    --bg-color green \
    --font ~/Downloads/YourCustomFont.ttf

⏱️ Time Overlay Video

You can also generate a time overlay video as a separate video that displays the time elapsed during the dive. It will be exported in the same directory as the depth overlay video.

depthviz -i 123456_ACTIVITY.fit -s garmin -o mydive.mp4 --time

📌 Step 3: Integrate with Your Footage

Import the generated depth overlay and time overlay (if used) into your video editing software. Remove the background color. Adjust position of the overlays to suit your video style.

🎓 Watch a quick tutorial: How to import overlays in CapCut.

🚫 No Dive Computer?

No dive computer? No problem! You can still create a depth overlay! Simply record key moments of your dive (using depth markers on your rope, for example) and prepare a CSV file with two columns:

• Time: in seconds
• Depth: in meters

Example Manual Input File:

Example Command:

depthviz -i manual_input.csv -s manual -o output_video.mp4

💡 Raw vs Zero-Based Mode

depthviz offers two ways to display depth:

🧠 How It Works

depthviz transforms your dive log data into an overlay video that visually tracks your depth in real time. It supports multiple dive computer formats and even allows manual data input, making it a versatile tool for freedivers looking to analyze and improve their performance.

🔬 Understanding Depth Calculation

Dive computers record either depth directly or pressure, which depthviz converts into depth using fluid statics principles. Understanding this process helps ensure accurate depth visualization.

↘️ Calculating Hydrostatic Pressure

Underwater pressure consists of atmospheric pressure (collected during the surface interval or dive start) and hydrostatic pressure. To determine hydrostatic pressure:

Hydrostatic pressure increases with depth due to the weight of the water above, making it a key factor in depth calculations.

↘️ Converting Pressure to Depth

Once hydrostatic pressure is known, depth can be calculated using the formula:

Where:

• h = Depth in meters
• ρ = Water density (EN13319 standard: 1019.7 kg/m³, standard for dive computers)
• g = Gravity (9.80665 m/s²)

📊 Handling Missing Data

Dive computers record data at different rates, which may result in gaps in data due to device limitations, battery-saving settings, or inconsistent logging intervals. To create a smooth depth profile, depthviz applies Linear Interpolation to estimate missing values.

To estimate missing depth values, depthviz uses the following formula:

Where:

• d = Estimated depth
• t = Missing timestamp
• (t₀, d₀) and (t₁, d₁) = Known data points

This ensures a smooth transition between recorded depth values.

Example: If your dive log records 5m at 6s and jumps to 10m at 12s, depthviz estimates intermediate depths at 7s, 8s, etc., for a seamless display.

🎥 Creating the Overlay Video

Once the data is processed, depthviz:

✅ Smooths depth values, ensuring natural and fluid transitions between recorded points.
✅ Applies display settings, including color, font, and stroke width, for full customization.
✅ Generates an overlay video, ready for integration with your dive footage.

This functionality allows freedivers to analyze their performance, track progress, and create engaging underwater visuals effortlessly. Whether for personal improvement, training analysis, or social media sharing.

📦 What's Inside depthviz?

Every depthviz release includes a Software Bill of Materials (SBOM) in CycloneDX format, providing full transparency into its dependencies. Whether you're a developer, a security-conscious freediver, or just curious, you’ll find everything under the hood.

The SBOM is generated by the GitHub Actions workflow using the cyclonedx-python library.
You can download the latest SBOM from the release artifacts.

🌱 Contribution

Want to make depthviz even better? Whether it’s fixing bugs, adding features, or improving dive computer support, every contribution helps!

🔧 Contribute Code or Ideas

• Found a bug? Open an issue so it can be fixed!
• Have a feature idea? Share it in Discussions or open an issue.
• Ready to code? Fork the repo and submit a pull request.

📖 Before contributing, please read CONTRIBUTING.md for guidelines on reporting issues, submitting pull requests, and coding standards.

⌚ Help Expand Dive Computer Support

Is your dive computer not supported yet? You can help change that! By sharing a sample dive log file, you’ll help depthviz analyze its format and add support in future updates.

To contribute your dive log, check out the guide in Donate My Dive. Every log helps make depthviz better for all freedivers! 🌊💙

🙌 Credits & Contributors

depthviz wouldn’t be possible without our amazing community and the open-source projects it relies on.

See AUTHORS.md for a list of contributors, maintainers, and dependencies that help power this project.

⚖️ License

depthviz is free and open-source software licensed under the Apache License 2.0, created and supported by Noppanut Ploywong with ❤️ for fellow freedivers.

📬 Contact

• Have Questions or Ideas? Join the Discussions.
• Found a Bug or Have a Feature Request? Open an issue.
• Need to Reach Out Directly? Contact the maintainer at noppanut.connect@gmail.com.

Contributions and feedback are always appreciated! 🌊✨