depthviz


Namedepthviz JSON
Version 0.6.0 PyPI version JSON
download
home_pageNone
SummaryVisualize your depth for your freediving videos: Works with or without dive computers.
upload_time2025-02-10 10:42:01
maintainerNone
docs_urlNone
authorNoppanut Ploywong
requires_python<4.0,>=3.9
licenseApache-2.0
keywords freediving dive video overlay depth dive-computer dive-log hud
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage No coveralls.
            <div align="center">
  <a href="#"><p align="center"><picture><source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/noppanut15/depthviz/main/assets/logo/depthviz-logo-dark.png" width="350px"><img src="https://raw.githubusercontent.com/noppanut15/depthviz/main/assets/logo/depthviz-logo-light.png" width="350px" title="depthviz logo" /></picture></p></a>

  <a name="readme-top"></a>

*A CLI tool for freedivers<br>to create depth & time overlay videos <br>from **dive computers** or **any manual logs**.*

[![PyPI - Version][version_badge_img]][version_badge_url] [![GitHub Actions Workflow Status][build_badge_img]][build_badge_url] [![Coveralls][coverage_badge_img]][coverage_badge_url] [![PyPI - Status][pypi_status_img]][pypi_status_url] [![PyPI Downloads][download_badge_img]][download_badge_url]

**&searr;&nbsp;&nbsp;Quick Links&nbsp;&nbsp;&swarr;**

[Features](#-features) • [Installation](#️-installation) • [Usage](#-usage) • [No Dive Computer?](#-no-dive-computer) • [How It Works](#-how-it-works) • [Contribution](#-contribution) • [License](#️-license) • [Contact](#-contact)

**&searr;&nbsp;&nbsp;Share the project's link to your friends&nbsp;&nbsp;&swarr;**

[![Share on X][x_share_img]][x_share_url] [![Share on Facebook][facebook_share_img]][facebook_share_url] [![Share on Telegram][telegram_share_img]][telegram_share_url] [![Share on WhatsApp][whatsapp_share_img]][whatsapp_share_url] [![Share on Reddit][reddit_share_img]][reddit_share_url]
</div>

<p align="center"><img src="https://raw.githubusercontent.com/noppanut15/depthviz/main/assets/depthviz-demo-v3-optimized.gif" alt="depthviz DEMO"/></p>

---
## ✨ Features

<img src="https://raw.githubusercontent.com/noppanut15/depthviz/main/assets/final-video-showcase-400x400.gif" alt="A GIF showcasing the final video which contains depth and time overlays" align="right" width="385px" />
 
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](#-handling-missing-data) for a seamless and natural depth display. Includes [*zero-based*](#-raw-vs-zero-based-mode) depth mode to smoothly estimate a 0m start if your dive log starts underwater.

> [!TIP]
> Perfect for performance freedivers tracking PBs or analyzing technique. Overlay your data and see every moment of your dive!

<div align="right">

[&nwarr; Back to top](#readme-top)

</div>

---

## 🌟 Like depthviz?

If you like `depthviz` and find it useful, please give it a shiny [![star](https://img.shields.io/github/stars/noppanut15/depthviz
)](#top) ✨

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

<a href="https://github.com/noppanut15/" title="Follow Me on GitHub"><picture><source media="(prefers-color-scheme: dark)" srcset="https://img.shields.io/badge/follow%20me%20on%20github-white.svg?style=for-the-badge&logo=github&logoColor=black"><img src="https://img.shields.io/badge/follow%20me%20on%20github-%23121011.svg?style=for-the-badge&logo=github&logoColor=white" title="Follow Me on GitHub" /></picture></a>

I’d love to see your diving stories or videos made with `depthviz`! Share your creations by tagging [@noppanut15](https://www.instagram.com/noppanut15/) or using **#depthviz**. 

See you in the deep! 🌊😊

<div align="right">

[&nwarr; Back to top](#readme-top)

</div>

## 🛠️ Installation
### Prerequisites
- **Python 3.9 or higher**  
  [Download Python](https://www.python.org/downloads/) • [How to install Python](https://realpython.com/installing-python/)
- **pipx** – the recommended tool for installing Python CLI tools  
  [How to install pipx](https://pipx.pypa.io/stable/installation/)

### Install depthviz

Open your terminal and run:
```bash
pipx install depthviz
```

### Upgrade

When a new version is available, update with:

```bash
pipx upgrade depthviz
```

Check your current version:
```bash
depthviz --version
```

<div align="right">

[&nwarr; Back to top](#readme-top)

</div>

## 🚀 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:**<br>Export your dive log from your dive computer or diving application. (see [Supported Dive Log Formats](#-supported-dive-log-formats) below).
- **🙅 No Dive Computer?**<br>You can record your dive manually (details in [No Dive Computer?](#-no-dive-computer)).

---

### 📌 Step 2: Generate the Overlay

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

```bash
depthviz -i YOUR_DIVE_LOG -s DATA_SOURCE -o OUTPUT_VIDEO.mp4
```
**Example (Garmin dive log):**
```bash
depthviz -i 123456_ACTIVITY.fit -s garmin -o my_dive_overlay.mp4
```
| &nbsp;&nbsp;&nbsp;&nbsp;Option&nbsp;&nbsp;&nbsp;&nbsp; | Short | Values                                                               | Description                                                                                           |
| ------------------------------------------------------ | :---: | -------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| `--input`                                              | `-i`  | File path                                                            | Path or filename to your dive log file.                                                               |
| `--source`                                             | `-s`  | `apnealizer`,<br>`shearwater`,<br>`garmin`,<br>`suunto`,<br>`manual` | The data source.<br>(See the [Supported Dive Log Formats](#-supported-dive-log-formats) for details.) |
| `--output`                                             | `-o`  | File path                                                            | Path or filename for the output video. (must end with `.mp4`)                                         |

#### 📂 Supported Dive Log Formats

|    Source    | Description                                                                                                                                                                                                                                                   | File type |
| :----------: | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-------: |
| `apnealizer` | Exported logs from the **Apnealizer** app. <br> [![Get log][get_log_img]](https://apnealizer.com/)                                                                                                                                                            |    CSV    |
| `shearwater` | Logs from **Shearwater** dive computers. <br> [![Get log][get_log_img]](https://shearwater.com/pages/shearwater-cloud)                                                                                                                                        |    XML    |
|   `garmin`   | Logs from **Garmin** dive computers. <br> [![Get log][get_log_img]](https://connect.garmin.com/signin/) [![How to][how_to_img]](https://github.com/noppanut15/depthviz/blob/main/docs/GARMIN.md)                                                              |    FIT    |
|   `suunto`   | Logs from **Suunto** dive computers. <br> [![Get log][get_log_img]](https://www.suunto.com/suunto-app/suunto-app-2022/)  [![How to][how_to_img]](https://www.suunto.com/Support/faq-articles/suunto-app/what-type-of-files-can-i-export-from-the-suunto-app/) |    FIT    |
|   `manual`   | Manually entered depth logs. <br> [![How to][how_to_img]](#-no-dive-computer)                                                                                                                                                                                 |    CSV    |


#### ⚙️ Advanced Customization Options
<details><summary><strong>View Advanced Options</strong></summary>

Want more control? Use these optional parameters:

| &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Option&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; | &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Values&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; |                           Default                           | Description                                                                                                                         |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :----------------------------------------------------------------------------: | :---------------------------------------------------------: | ----------------------------------------------------------------------------------------------------------------------------------- |
| `-d` or <br/>`--decimal-places`                                                                                                                                    |                                `0`, `1`, or `2`                                |                             `0`                             | Number of decimal places in the depth overlay.                                                                                      |
| `--depth-mode`                                                                                                                                                     |                         `raw` <br/>or<br/>`zero-based`                         |                            `raw`                            | `raw` shows the actual depth; `zero-based` forces the overlay to start/end at 0m. [See Raw vs Zero-Based](#-raw-vs-zero-based-mode) |
| `--no-minus`                                                                                                                                                       |                                       -                                        |                              -                              | Removes the minus sign from depth values (e.g., `10m` instead of `-10m`).                                                           |
| `--font`                                                                                                                                                           |                                   File path                                    | [Default font](https://fonts.google.com/specimen/Open+Sans) | Path to a custom font file for the text.                                                                                            |
| `--bg-color`                                                                                                                                                       |                             Color name or hex code                             |                           `black`                           | Background color (e.g., `green`, `'#000000'`).                                                                                      |
| `--stroke-width`                                                                                                                                                   |                                Positive integer                                |                             `5`                             | Thickness of the text outline for better visibility.                                                                                |
</details>

<details><summary><strong>Example Command with Advanced Options</strong></summary><br>

Example of generating a depth overlay video named `mydive.mp4` using data from `123456_ACTIVITY.fit` exported from [Garmin Connect](https://github.com/noppanut15/depthviz/blob/main/docs/GARMIN.md):

```bash
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
```

- Set the depth display mode to **zero-based** to adjust the depth to start and end at 0m. (Learn more about [Zero-Based Depth Mode](#-raw-vs-zero-based-mode))
- The depth values will be displayed with **one** decimal place.
- The minus sign will be **hidden**.
- The background color will be set to **green** for chroma keying.
- A **custom font** file at `~/Downloads/YourCustomFont.ttf` will be used for the text.

</details>
<br>

<p align="center"><img src="https://raw.githubusercontent.com/noppanut15/depthviz/main/assets/depth-decimal-places-5s-trimmed.gif" width="600px" alt="decimal places comparison"/></p>

> [!TIP]
> Use the `--decimal-places` option to control the precision of the depth display (e.g., `--decimal-places 1` displays depths like `-12.5m`)

#### ⏱️ Time Overlay Video

<p align="center"><img src="https://raw.githubusercontent.com/noppanut15/depthviz/main/assets/time-overlays.gif" alt="time overlay demo" width="600px"/></p>

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.

| &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Option&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; | Values | Description                  |
| ------------------------------------------------------------------------------------------------------------------------------------------------------ | ------ | ---------------------------- |
| `--time`                                                                                                                                               | -      | Create a time overlay video. |

<details><summary><strong>Example Command with Time Overlay</strong></summary><br>

Example of generating a depth overlay video named `mydive.mp4` and a time overlay video by adding the `--time` option:

```bash
depthviz -i 123456_ACTIVITY.fit -s garmin -o mydive.mp4 --time
```
> The time overlay video will be automatically generated and saved in the same directory as the depth overlay video with the filename `mydive_time.mp4`.

</details>

---

### 📌 Step 3: Integrate with Your Footage

<p align="center"><picture><source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/noppanut15/depthviz/main/assets/step3-dark-v2.jpeg" width="500px"><img src="https://raw.githubusercontent.com/noppanut15/depthviz/main/assets/step3-light-v2.jpeg" width="500px" title="integrate overlays with your footage" /></picture></p> 

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](https://www.youtube.com/watch?v=ZggKrWk98Ag): How to import overlays in CapCut.

> [!TIP]
> **🎨 Chroma Keying**: If you want to remove the background color from the overlay, use the [chroma key](https://en.wikipedia.org/wiki/Chroma_key) effect in your video editor. You can use the `--bg-color` option to set the background color to match your video editor's chroma key color. Using `--bg-color green` is a common choice.

<div align="right">

[&nwarr; Back to top](#readme-top)

</div>

## 🚫 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:**

| Time  | Depth |
| :---: | :---: |
|   0   |   0   |
|   6   |   5   |
|  12   |  10   |
|  19   |  15   |
|  26   |  10   |
|  33   |   5   |
|  39   |   0   |

[![Download Input File](https://img.shields.io/badge/Download%20Input%20File-1974D2?style=for-the-badge&logo=readdotcv)](https://github.com/noppanut15/depthviz/blob/main/assets/manual-input-example.csv)

**Example Command**:
```bash
depthviz -i manual_input.csv -s manual -o output_video.mp4
```

> [!TIP]
> For a simple dive, recording **just three points** (start, maximum depth, end) is enough. `depthviz` will interpolate the values for a smooth depth profile!

> [!IMPORTANT]
> For more complex dives (e.g., dives with significant variations in descent/ascent rate or bottom time), **more data points** are recommended.

<a href="https://2bfreeequipment.com/shop/2-b-free-freediving-rope-superstatic-marked-with-stopper/"><p align="center"><img src="https://raw.githubusercontent.com/noppanut15/depthviz/main/assets/marked-rope-example.png" alt="Example of a Freediving Rope with Depth Markers" width="600px"/></p></a>
> [!TIP]
> Freediving rope with depth markers can help you record key moments of your dive.

<div align="right">

[&nwarr; Back to top](#readme-top)

</div>

## 💡 Raw vs Zero-Based Mode

<p align="center"><img src="https://raw.githubusercontent.com/noppanut15/depthviz/main/assets/depth-mode-comparison.jpg" alt="Depth Mode: raw vs zero-based" width="600px"/></p>

`depthviz` offers **two ways** to display depth:

|       Mode        | Best For                 | Description                                                                                                                                               |
| :---------------: | ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `raw` *(Default)* | Accuracy, Dive Analysis  | Shows **actual recorded** depth. Your dive might start at **-0.3m, -0.5m, etc.** if the dive computer didn’t record at the surface. *(left figure)*       |
|   `zero-based`    | Aesthetic Video Overlays | Adjusts depth to **start and end at 0m** for a smoother display. Assumes a **1m/s descent/ascent rate** for the missing surface portion. *(right figure)* |

> [!TIP]
> - Use `raw`  mode if accuracy matters (e.g., dive analysis).  
> - Use `zero-based` if your dive log starts/ends underwater but you want a clean 0m start/end. (e.g., social media videos)

<div align="right">

[&nwarr; Back to top](#readme-top)

</div>

## 🧠 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:

<br><p align="center"><picture><source media="(prefers-color-scheme: dark)" srcset="https://latex.codecogs.com/svg.image?\large&space;{\color{White}P_{\text{hydro}}=P_{\text{absolute}}-P_{\text{atmospheric}}}"><img src="https://latex.codecogs.com/svg.image?\large&space;$$P_{\text{hydro}}=P_{\text{absolute}}-P_{\text{atmospheric}}$$" title="$$P_{\text{hydro}}=P_{\text{absolute}}-P_{\text{atmospheric}}$$" /></picture></p><br>

<!-- $$
P_{\text{hydro}} = P_{\text{absolute}} - P_{\text{atmospheric}}
$$ -->

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:

<br><p align="center"><picture><source media="(prefers-color-scheme: dark)" srcset="https://latex.codecogs.com/svg.image?\large&space;{\color{White}h=\frac{P_{\text{hydro}}}{\rho&space;g}}"><img src="https://latex.codecogs.com/svg.image?\large&space;$$h=\frac{P_{\text{hydro}}}{\rho&space;g}$$" title="$$h=\frac{P_{\text{hydro}}}{\rho&space;g}$$" /></picture></p>

<!-- $$
h=\frac{P_{\text{hydro}}}{\rho g}
$$ -->

Where:

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

> [!NOTE]
> Water density varies between saltwater and freshwater, which can affect depth accuracy. Custom density settings are planned for future updates.

### 📊 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](https://en.wikipedia.org/wiki/Linear_interpolation) to estimate missing values.

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

<br><p align="center"><picture><source media="(prefers-color-scheme: dark)" srcset="https://latex.codecogs.com/svg.image?\large&space;{\color{White}d=d_0+(t-t_0)\frac{d_1-d_0}{t_1-t_0}}"><img src="https://latex.codecogs.com/svg.image?\large&space;$$d=d_0+(t-t_0)\frac{d_1-d_0}{t_1-t_0}$$" title="$$d=d_0+(t-t_0)\frac{d_1-d_0}{t_1-t_0}$$" /></picture></p>

<!-- $$
d=d_0+(t-t_0)\frac{d_1-d_0}{t_1-t_0}
$$ -->

Where:

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

This ensures a smooth transition between recorded depth values.

<p align="center">
  <img src="https://raw.githubusercontent.com/noppanut15/depthviz/main/assets/linear-interpolation-example.png" width="500" alt="Example Chart: Linear Interpolation of Depth Over Time"/>
</p>

> **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.<br>✅ **Applies display settings**, including color, font, and stroke width, for full customization.<br>✅ **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.

<div align="right">

[&nwarr; Back to top](#readme-top)

</div>

## 📦 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.

<details>
  <summary>💡 <strong>What’s an SBOM?</strong> (Click to expand)</summary>

An SBOM is like a **blueprint of `depthviz`**—a complete list of every package it depends on. It helps with:  
- ✅ **Security:** Identify known vulnerabilities in dependencies  
- ✅ **Transparency:** See exactly what’s inside `depthviz`  
- ✅ **Reliability:** Ensures `depthviz` remains stable and up-to-date  
</details>


The SBOM is generated by the [GitHub Actions workflow](https://github.com/noppanut15/depthviz/blob/main/.github/workflows/deploy.yaml) using the [cyclonedx-python](https://github.com/CycloneDX/cyclonedx-python) library.<br>You can download the latest **SBOM** from the [release artifacts](https://github.com/noppanut15/depthviz/releases).

<div align="right">

[&nwarr; Back to top](#readme-top)

</div>

## 🌱 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](https://github.com/noppanut15/depthviz/issues) so it can be fixed!  
- Have a feature idea? Share it in [Discussions](https://github.com/noppanut15/depthviz/discussions) or [open an issue](https://github.com/noppanut15/depthviz/issues).
- Ready to code? Fork the repo and submit a [pull request](https://github.com/noppanut15/depthviz/pulls).

> 📖 **Before contributing, please read** [CONTRIBUTING.md](https://github.com/noppanut15/depthviz/blob/main/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](https://github.com/noppanut15/depthviz/issues/15). 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](https://github.com/noppanut15/depthviz/blob/main/AUTHORS.md) for a list of contributors, maintainers, and dependencies that help power this project.

<div align="right">

[&nwarr; Back to top](#readme-top)

</div>

## ⚖️ License

`depthviz` is free and open-source software licensed under the [Apache License 2.0](https://github.com/noppanut15/depthviz/blob/main/LICENSE), created and supported by [Noppanut Ploywong](https://github.com/noppanut15) with ❤️ for fellow freedivers.

<div align="right">

[&nwarr; Back to top](#readme-top)

</div>

## 📬 Contact

- **Have Questions or Ideas?** Join the [Discussions](https://github.com/noppanut15/depthviz/discussions).  
- **Found a Bug or Have a Feature Request?** [Open an issue](https://github.com/noppanut15/depthviz/issues).  
- **Need to Reach Out Directly?** Contact the maintainer at [noppanut.connect@gmail.com](mailto:noppanut.connect@gmail.com).

Contributions and feedback are always appreciated! 🌊✨

<div align="right">

[&nwarr; Back to top](#readme-top)

</div>

<!-- Badge links -->
[version_badge_img]: https://img.shields.io/pypi/v/depthviz?label=version&logo=pypi&logoColor=white
[build_badge_img]: https://img.shields.io/github/actions/workflow/status/noppanut15/depthviz/deploy.yaml?logo=github
[coverage_badge_img]: https://img.shields.io/coveralls/github/noppanut15/depthviz?logo=coveralls
[pypi_status_img]: https://img.shields.io/pypi/status/depthviz?logo=pypi&logoColor=white
[download_badge_img]: https://static.pepy.tech/badge/depthviz
[version_badge_url]: https://pypi.org/project/depthviz/
[build_badge_url]: https://github.com/noppanut15/depthviz/actions
[coverage_badge_url]: https://coveralls.io/github/noppanut15/depthviz
[pypi_status_url]: https://pypi.org/project/depthviz/
[download_badge_url]: https://pepy.tech/projects/depthviz

<!-- Social links -->
[x_share_url]: https://x.com/intent/tweet?hashtags=depth%2Cfreediving%2Cvideo%2Cautomation&text=A%20CLI%20tool%20for%20freedivers%20to%20create%20depth%20%26%20time%20overlay%20videos%20from%20dive%20computers%20or%20any%20manual%20logs.&url=https%3A%2F%2Fgithub.com%2Fnoppanut15%2Fdepthviz
[telegram_share_url]: https://t.me/share/url?url=https%3A//github.com/noppanut15/depthviz&text=A%20CLI%20tool%20for%20freedivers%20to%20create%20depth%20%26%20time%20overlay%20videos%20from%20dive%20computers%20or%20any%20manual%20logs.
[whatsapp_share_url]: https://api.whatsapp.com/send?text=A%20CLI%20tool%20for%20freedivers%20to%20create%20depth%20%26%20time%20overlay%20videos%20from%20dive%20computers%20or%20any%20manual%20logs.%20https%3A%2F%2Fgithub.com%2Fnoppanut15%2Fdepthviz
[reddit_share_url]: https://www.reddit.com/submit?url=https%3A%2F%2Fgithub.com%2Fnoppanut15%2Fdepthviz&title=A%20CLI%20tool%20for%20freedivers%20to%20create%20depth%20%26%20time%20overlay%20videos%20from%20dive%20computers%20or%20any%20manual%20logs.%20%23depth%20%23freediving%20%23video%20%23automation
[facebook_share_url]: https://www.facebook.com/sharer/sharer.php?u=https%3A//github.com/noppanut15/depthviz
[x_share_img]: https://img.shields.io/badge/x_(twitter)-black?style=for-the-badge&logo=x
[telegram_share_img]: https://img.shields.io/badge/telegram-black?style=for-the-badge&logo=telegram
[whatsapp_share_img]: https://img.shields.io/badge/whatsapp-black?style=for-the-badge&logo=whatsapp
[reddit_share_img]: https://img.shields.io/badge/reddit-black?style=for-the-badge&logo=reddit
[facebook_share_img]: https://img.shields.io/badge/facebook-black?style=for-the-badge&logo=facebook

<!-- Help -->
[how_to_img]: https://img.shields.io/badge/How%20to-1974D2?style=flat-square&logo=gitbook&logoColor=white
[get_log_img]: https://img.shields.io/badge/Get%20log-1974D2?style=flat-square&logo=transmission&logoColor=white

            

Raw data

            {
    "_id": null,
    "home_page": null,
    "name": "depthviz",
    "maintainer": null,
    "docs_url": null,
    "requires_python": "<4.0,>=3.9",
    "maintainer_email": null,
    "keywords": "freediving, dive, video, overlay, depth, dive-computer, dive-log, hud",
    "author": "Noppanut Ploywong",
    "author_email": "noppanut.connect@gmail.com",
    "download_url": "https://files.pythonhosted.org/packages/84/18/4fdc86778cdce8ae04964b585456c55c73828fdfb35c085b639a5ecc5af6/depthviz-0.6.0.tar.gz",
    "platform": null,
    "description": "<div align=\"center\">\n  <a href=\"#\"><p align=\"center\"><picture><source media=\"(prefers-color-scheme: dark)\" srcset=\"https://raw.githubusercontent.com/noppanut15/depthviz/main/assets/logo/depthviz-logo-dark.png\" width=\"350px\"><img src=\"https://raw.githubusercontent.com/noppanut15/depthviz/main/assets/logo/depthviz-logo-light.png\" width=\"350px\" title=\"depthviz logo\" /></picture></p></a>\n\n  <a name=\"readme-top\"></a>\n\n*A CLI tool for freedivers<br>to create depth & time overlay videos <br>from **dive computers** or **any manual logs**.*\n\n[![PyPI - Version][version_badge_img]][version_badge_url] [![GitHub Actions Workflow Status][build_badge_img]][build_badge_url] [![Coveralls][coverage_badge_img]][coverage_badge_url] [![PyPI - Status][pypi_status_img]][pypi_status_url] [![PyPI Downloads][download_badge_img]][download_badge_url]\n\n**&searr;&nbsp;&nbsp;Quick Links&nbsp;&nbsp;&swarr;**\n\n[Features](#-features) \u2022 [Installation](#\ufe0f-installation) \u2022 [Usage](#-usage) \u2022 [No Dive Computer?](#-no-dive-computer) \u2022 [How It Works](#-how-it-works) \u2022 [Contribution](#-contribution) \u2022 [License](#\ufe0f-license) \u2022 [Contact](#-contact)\n\n**&searr;&nbsp;&nbsp;Share the project's link to your friends&nbsp;&nbsp;&swarr;**\n\n[![Share on X][x_share_img]][x_share_url] [![Share on Facebook][facebook_share_img]][facebook_share_url] [![Share on Telegram][telegram_share_img]][telegram_share_url] [![Share on WhatsApp][whatsapp_share_img]][whatsapp_share_url] [![Share on Reddit][reddit_share_img]][reddit_share_url]\n</div>\n\n<p align=\"center\"><img src=\"https://raw.githubusercontent.com/noppanut15/depthviz/main/assets/depthviz-demo-v3-optimized.gif\" alt=\"depthviz DEMO\"/></p>\n\n---\n## \u2728 Features\n\n<img src=\"https://raw.githubusercontent.com/noppanut15/depthviz/main/assets/final-video-showcase-400x400.gif\" alt=\"A GIF showcasing the final video which contains depth and time overlays\" align=\"right\" width=\"385px\" />\n \nWhy use *depthviz*?\n\n- \ud83c\udfa5 **Stunning Depth Overlays** \u2013 Turn dive logs into smooth, real-time depth displays.\n- \ud83d\udcbb **Works Anywhere** \u2013 Runs on Windows, macOS, and Linux.\n- \ud83d\udcca **Dive Log Friendly** \u2013 Supports Apnealizer, Garmin, Suunto, Shearwater, and *even manually recorded logs!*\n- \ud83c\udfa8 **Fully Customizable** \u2013 Adjust fonts, colors, decimal places, stroke width, and more.\n- \ud83d\udd17 **Easy Video Integration** \u2013 Works with CapCut, Premiere Pro, and other editors.\n- \u26a1 **Smart Depth Smoothing** \u2013 Automatically [fills in missing data](#-handling-missing-data) for a seamless and natural depth display. Includes [*zero-based*](#-raw-vs-zero-based-mode) depth mode to smoothly estimate a 0m start if your dive log starts underwater.\n\n> [!TIP]\n> Perfect for performance freedivers tracking PBs or analyzing technique. Overlay your data and see every moment of your dive!\n\n<div align=\"right\">\n\n[&nwarr; Back to top](#readme-top)\n\n</div>\n\n---\n\n## \ud83c\udf1f Like depthviz?\n\nIf you like `depthviz` and find it useful, please give it a shiny [![star](https://img.shields.io/github/stars/noppanut15/depthviz\n)](#top) \u2728\n\n**Get early access** to new open-source projects, exclusive insights, and sneak peeks at upcoming `depthviz` features! \ud83d\ude80\n\n<a href=\"https://github.com/noppanut15/\" title=\"Follow Me on GitHub\"><picture><source media=\"(prefers-color-scheme: dark)\" srcset=\"https://img.shields.io/badge/follow%20me%20on%20github-white.svg?style=for-the-badge&logo=github&logoColor=black\"><img src=\"https://img.shields.io/badge/follow%20me%20on%20github-%23121011.svg?style=for-the-badge&logo=github&logoColor=white\" title=\"Follow Me on GitHub\" /></picture></a>\n\nI\u2019d love to see your diving stories or videos made with `depthviz`! Share your creations by tagging [@noppanut15](https://www.instagram.com/noppanut15/) or using **#depthviz**. \n\nSee you in the deep! \ud83c\udf0a\ud83d\ude0a\n\n<div align=\"right\">\n\n[&nwarr; Back to top](#readme-top)\n\n</div>\n\n## \ud83d\udee0\ufe0f Installation\n### Prerequisites\n- **Python 3.9 or higher**  \n  [Download Python](https://www.python.org/downloads/) \u2022 [How to install Python](https://realpython.com/installing-python/)\n- **pipx** \u2013 the recommended tool for installing Python CLI tools  \n  [How to install pipx](https://pipx.pypa.io/stable/installation/)\n\n### Install depthviz\n\nOpen your terminal and run:\n```bash\npipx install depthviz\n```\n\n### Upgrade\n\nWhen a new version is available, update with:\n\n```bash\npipx upgrade depthviz\n```\n\nCheck your current version:\n```bash\ndepthviz --version\n```\n\n<div align=\"right\">\n\n[&nwarr; Back to top](#readme-top)\n\n</div>\n\n## \ud83d\ude80 Usage\n\n### \ud83c\udfc1 First Time Using depthviz?\nStart with this quick example:\n\n```\ndepthviz -i my_dive.fit -s garmin -o overlay.mp4\n```\n- \ud83d\udcc2 `-i`: Your dive log file\n- \ud83d\udd0d `-s`: Data source (`garmin`, `suunto`, etc.)\n- \ud83c\udfac `-o`: Name of output video\n\nFor full customization, keep reading! \ud83d\ude80\n\n---\n\n### \ud83d\udccc Step 1: Prepare Your Dive Data\n\n- **\ud83d\ude46 With a Dive Computer:**<br>Export your dive log from your dive computer or diving application. (see [Supported Dive Log Formats](#-supported-dive-log-formats) below).\n- **\ud83d\ude45 No Dive Computer?**<br>You can record your dive manually (details in [No Dive Computer?](#-no-dive-computer)).\n\n---\n\n### \ud83d\udccc Step 2: Generate the Overlay\n\nRun this command to create your depth overlay video from your dive log:\n\n```bash\ndepthviz -i YOUR_DIVE_LOG -s DATA_SOURCE -o OUTPUT_VIDEO.mp4\n```\n**Example (Garmin dive log):**\n```bash\ndepthviz -i 123456_ACTIVITY.fit -s garmin -o my_dive_overlay.mp4\n```\n| &nbsp;&nbsp;&nbsp;&nbsp;Option&nbsp;&nbsp;&nbsp;&nbsp; | Short | Values                                                               | Description                                                                                           |\n| ------------------------------------------------------ | :---: | -------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |\n| `--input`                                              | `-i`  | File path                                                            | Path or filename to your dive log file.                                                               |\n| `--source`                                             | `-s`  | `apnealizer`,<br>`shearwater`,<br>`garmin`,<br>`suunto`,<br>`manual` | The data source.<br>(See the [Supported Dive Log Formats](#-supported-dive-log-formats) for details.) |\n| `--output`                                             | `-o`  | File path                                                            | Path or filename for the output video. (must end with `.mp4`)                                         |\n\n#### \ud83d\udcc2 Supported Dive Log Formats\n\n|    Source    | Description                                                                                                                                                                                                                                                   | File type |\n| :----------: | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-------: |\n| `apnealizer` | Exported logs from the **Apnealizer** app. <br> [![Get log][get_log_img]](https://apnealizer.com/)                                                                                                                                                            |    CSV    |\n| `shearwater` | Logs from **Shearwater** dive computers. <br> [![Get log][get_log_img]](https://shearwater.com/pages/shearwater-cloud)                                                                                                                                        |    XML    |\n|   `garmin`   | Logs from **Garmin** dive computers. <br> [![Get log][get_log_img]](https://connect.garmin.com/signin/) [![How to][how_to_img]](https://github.com/noppanut15/depthviz/blob/main/docs/GARMIN.md)                                                              |    FIT    |\n|   `suunto`   | Logs from **Suunto** dive computers. <br> [![Get log][get_log_img]](https://www.suunto.com/suunto-app/suunto-app-2022/)  [![How to][how_to_img]](https://www.suunto.com/Support/faq-articles/suunto-app/what-type-of-files-can-i-export-from-the-suunto-app/) |    FIT    |\n|   `manual`   | Manually entered depth logs. <br> [![How to][how_to_img]](#-no-dive-computer)                                                                                                                                                                                 |    CSV    |\n\n\n#### \u2699\ufe0f Advanced Customization Options\n<details><summary><strong>View Advanced Options</strong></summary>\n\nWant more control? Use these optional parameters:\n\n| &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Option&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; | &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Values&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; |                           Default                           | Description                                                                                                                         |\n| ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :----------------------------------------------------------------------------: | :---------------------------------------------------------: | ----------------------------------------------------------------------------------------------------------------------------------- |\n| `-d` or <br/>`--decimal-places`                                                                                                                                    |                                `0`, `1`, or `2`                                |                             `0`                             | Number of decimal places in the depth overlay.                                                                                      |\n| `--depth-mode`                                                                                                                                                     |                         `raw` <br/>or<br/>`zero-based`                         |                            `raw`                            | `raw` shows the actual depth; `zero-based` forces the overlay to start/end at 0m. [See Raw vs Zero-Based](#-raw-vs-zero-based-mode) |\n| `--no-minus`                                                                                                                                                       |                                       -                                        |                              -                              | Removes the minus sign from depth values (e.g., `10m` instead of `-10m`).                                                           |\n| `--font`                                                                                                                                                           |                                   File path                                    | [Default font](https://fonts.google.com/specimen/Open+Sans) | Path to a custom font file for the text.                                                                                            |\n| `--bg-color`                                                                                                                                                       |                             Color name or hex code                             |                           `black`                           | Background color (e.g., `green`, `'#000000'`).                                                                                      |\n| `--stroke-width`                                                                                                                                                   |                                Positive integer                                |                             `5`                             | Thickness of the text outline for better visibility.                                                                                |\n</details>\n\n<details><summary><strong>Example Command with Advanced Options</strong></summary><br>\n\nExample of generating a depth overlay video named `mydive.mp4` using data from `123456_ACTIVITY.fit` exported from [Garmin Connect](https://github.com/noppanut15/depthviz/blob/main/docs/GARMIN.md):\n\n```bash\ndepthviz \\\n    -i 123456_ACTIVITY.fit -s garmin -o mydive.mp4 \\\n    --depth-mode zero-based \\\n    --decimal-places 1 \\\n    --no-minus \\\n    --bg-color green \\\n    --font ~/Downloads/YourCustomFont.ttf\n```\n\n- Set the depth display mode to **zero-based** to adjust the depth to start and end at 0m. (Learn more about [Zero-Based Depth Mode](#-raw-vs-zero-based-mode))\n- The depth values will be displayed with **one** decimal place.\n- The minus sign will be **hidden**.\n- The background color will be set to **green** for chroma keying.\n- A **custom font** file at `~/Downloads/YourCustomFont.ttf` will be used for the text.\n\n</details>\n<br>\n\n<p align=\"center\"><img src=\"https://raw.githubusercontent.com/noppanut15/depthviz/main/assets/depth-decimal-places-5s-trimmed.gif\" width=\"600px\" alt=\"decimal places comparison\"/></p>\n\n> [!TIP]\n> Use the `--decimal-places` option to control the precision of the depth display (e.g., `--decimal-places 1` displays depths like `-12.5m`)\n\n#### \u23f1\ufe0f Time Overlay Video\n\n<p align=\"center\"><img src=\"https://raw.githubusercontent.com/noppanut15/depthviz/main/assets/time-overlays.gif\" alt=\"time overlay demo\" width=\"600px\"/></p>\n\nYou 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.\n\n| &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Option&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; | Values | Description                  |\n| ------------------------------------------------------------------------------------------------------------------------------------------------------ | ------ | ---------------------------- |\n| `--time`                                                                                                                                               | -      | Create a time overlay video. |\n\n<details><summary><strong>Example Command with Time Overlay</strong></summary><br>\n\nExample of generating a depth overlay video named `mydive.mp4` and a time overlay video by adding the `--time` option:\n\n```bash\ndepthviz -i 123456_ACTIVITY.fit -s garmin -o mydive.mp4 --time\n```\n> The time overlay video will be automatically generated and saved in the same directory as the depth overlay video with the filename `mydive_time.mp4`.\n\n</details>\n\n---\n\n### \ud83d\udccc Step 3: Integrate with Your Footage\n\n<p align=\"center\"><picture><source media=\"(prefers-color-scheme: dark)\" srcset=\"https://raw.githubusercontent.com/noppanut15/depthviz/main/assets/step3-dark-v2.jpeg\" width=\"500px\"><img src=\"https://raw.githubusercontent.com/noppanut15/depthviz/main/assets/step3-light-v2.jpeg\" width=\"500px\" title=\"integrate overlays with your footage\" /></picture></p> \n\nImport 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.\n\n> [\ud83c\udf93 Watch a quick tutorial](https://www.youtube.com/watch?v=ZggKrWk98Ag): How to import overlays in CapCut.\n\n> [!TIP]\n> **\ud83c\udfa8 Chroma Keying**: If you want to remove the background color from the overlay, use the [chroma key](https://en.wikipedia.org/wiki/Chroma_key) effect in your video editor. You can use the `--bg-color` option to set the background color to match your video editor's chroma key color. Using `--bg-color green` is a common choice.\n\n<div align=\"right\">\n\n[&nwarr; Back to top](#readme-top)\n\n</div>\n\n## \ud83d\udeab No Dive Computer?\n\n**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:\n- **Time**: in seconds\n- **Depth**: in meters\n\n**Example Manual Input File:**\n\n| Time  | Depth |\n| :---: | :---: |\n|   0   |   0   |\n|   6   |   5   |\n|  12   |  10   |\n|  19   |  15   |\n|  26   |  10   |\n|  33   |   5   |\n|  39   |   0   |\n\n[![Download Input File](https://img.shields.io/badge/Download%20Input%20File-1974D2?style=for-the-badge&logo=readdotcv)](https://github.com/noppanut15/depthviz/blob/main/assets/manual-input-example.csv)\n\n**Example Command**:\n```bash\ndepthviz -i manual_input.csv -s manual -o output_video.mp4\n```\n\n> [!TIP]\n> For a simple dive, recording **just three points** (start, maximum depth, end) is enough. `depthviz` will interpolate the values for a smooth depth profile!\n\n> [!IMPORTANT]\n> For more complex dives (e.g., dives with significant variations in descent/ascent rate or bottom time), **more data points** are recommended.\n\n<a href=\"https://2bfreeequipment.com/shop/2-b-free-freediving-rope-superstatic-marked-with-stopper/\"><p align=\"center\"><img src=\"https://raw.githubusercontent.com/noppanut15/depthviz/main/assets/marked-rope-example.png\" alt=\"Example of a Freediving Rope with Depth Markers\" width=\"600px\"/></p></a>\n> [!TIP]\n> Freediving rope with depth markers can help you record key moments of your dive.\n\n<div align=\"right\">\n\n[&nwarr; Back to top](#readme-top)\n\n</div>\n\n## \ud83d\udca1 Raw vs Zero-Based Mode\n\n<p align=\"center\"><img src=\"https://raw.githubusercontent.com/noppanut15/depthviz/main/assets/depth-mode-comparison.jpg\" alt=\"Depth Mode: raw vs zero-based\" width=\"600px\"/></p>\n\n`depthviz` offers **two ways** to display depth:\n\n|       Mode        | Best For                 | Description                                                                                                                                               |\n| :---------------: | ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `raw` *(Default)* | Accuracy, Dive Analysis  | Shows **actual recorded** depth. Your dive might start at **-0.3m, -0.5m, etc.** if the dive computer didn\u2019t record at the surface. *(left figure)*       |\n|   `zero-based`    | Aesthetic Video Overlays | Adjusts depth to **start and end at 0m** for a smoother display. Assumes a **1m/s descent/ascent rate** for the missing surface portion. *(right figure)* |\n\n> [!TIP]\n> - Use `raw`  mode if accuracy matters (e.g., dive analysis).  \n> - Use `zero-based` if your dive log starts/ends underwater but you want a clean 0m start/end. (e.g., social media videos)\n\n<div align=\"right\">\n\n[&nwarr; Back to top](#readme-top)\n\n</div>\n\n## \ud83e\udde0 How It Works\n\n`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.\n\n### \ud83d\udd2c Understanding Depth Calculation\nDive computers record either **depth** directly or **pressure**, which `depthviz` converts into depth using *fluid statics principles*. Understanding this process helps ensure accurate depth visualization.\n\n#### \u2198\ufe0f Calculating Hydrostatic Pressure\n\nUnderwater pressure consists of atmospheric pressure (collected during the surface interval or dive start) and hydrostatic pressure. To determine hydrostatic pressure:\n\n<br><p align=\"center\"><picture><source media=\"(prefers-color-scheme: dark)\" srcset=\"https://latex.codecogs.com/svg.image?\\large&space;{\\color{White}P_{\\text{hydro}}=P_{\\text{absolute}}-P_{\\text{atmospheric}}}\"><img src=\"https://latex.codecogs.com/svg.image?\\large&space;$$P_{\\text{hydro}}=P_{\\text{absolute}}-P_{\\text{atmospheric}}$$\" title=\"$$P_{\\text{hydro}}=P_{\\text{absolute}}-P_{\\text{atmospheric}}$$\" /></picture></p><br>\n\n<!-- $$\nP_{\\text{hydro}} = P_{\\text{absolute}} - P_{\\text{atmospheric}}\n$$ -->\n\nHydrostatic pressure increases with depth due to the weight of the water above, making it a key factor in depth calculations.\n\n#### \u2198\ufe0f Converting Pressure to Depth\n\nOnce hydrostatic pressure is known, depth can be calculated using the formula:\n\n<br><p align=\"center\"><picture><source media=\"(prefers-color-scheme: dark)\" srcset=\"https://latex.codecogs.com/svg.image?\\large&space;{\\color{White}h=\\frac{P_{\\text{hydro}}}{\\rho&space;g}}\"><img src=\"https://latex.codecogs.com/svg.image?\\large&space;$$h=\\frac{P_{\\text{hydro}}}{\\rho&space;g}$$\" title=\"$$h=\\frac{P_{\\text{hydro}}}{\\rho&space;g}$$\" /></picture></p>\n\n<!-- $$\nh=\\frac{P_{\\text{hydro}}}{\\rho g}\n$$ -->\n\nWhere:\n\n- **h** = Depth in meters\n- **\u03c1** = Water density *(EN13319 standard: 1019.7 kg/m\u00b3, standard for dive computers)*\n- **g** = Gravity (9.80665 m/s\u00b2)\n\n> [!NOTE]\n> Water density varies between saltwater and freshwater, which can affect depth accuracy. Custom density settings are planned for future updates.\n\n### \ud83d\udcca Handling Missing Data\n\nDive 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](https://en.wikipedia.org/wiki/Linear_interpolation) to estimate missing values.\n\nTo estimate missing depth values, `depthviz` uses the following formula:\n\n<br><p align=\"center\"><picture><source media=\"(prefers-color-scheme: dark)\" srcset=\"https://latex.codecogs.com/svg.image?\\large&space;{\\color{White}d=d_0+(t-t_0)\\frac{d_1-d_0}{t_1-t_0}}\"><img src=\"https://latex.codecogs.com/svg.image?\\large&space;$$d=d_0+(t-t_0)\\frac{d_1-d_0}{t_1-t_0}$$\" title=\"$$d=d_0+(t-t_0)\\frac{d_1-d_0}{t_1-t_0}$$\" /></picture></p>\n\n<!-- $$\nd=d_0+(t-t_0)\\frac{d_1-d_0}{t_1-t_0}\n$$ -->\n\nWhere:\n\n- **d** = Estimated depth\n- **t** = Missing timestamp\n- **(t\u2080, d\u2080)** and **(t\u2081, d\u2081)** = Known data points\n\nThis ensures a smooth transition between recorded depth values.\n\n<p align=\"center\">\n  <img src=\"https://raw.githubusercontent.com/noppanut15/depthviz/main/assets/linear-interpolation-example.png\" width=\"500\" alt=\"Example Chart: Linear Interpolation of Depth Over Time\"/>\n</p>\n\n> **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.\n\n\n### \ud83c\udfa5 Creating the Overlay Video\n\nOnce the data is processed, `depthviz`:\n\n\u2705 **Smooths depth values**, ensuring natural and fluid transitions between recorded points.<br>\u2705 **Applies display settings**, including color, font, and stroke width, for full customization.<br>\u2705 **Generates an overlay video**, ready for integration with your dive footage.\n\nThis 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.\n\n<div align=\"right\">\n\n[&nwarr; Back to top](#readme-top)\n\n</div>\n\n## \ud83d\udce6 What's Inside depthviz?\n\nEvery `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\u2019ll find everything under the hood.\n\n<details>\n  <summary>\ud83d\udca1 <strong>What\u2019s an SBOM?</strong> (Click to expand)</summary>\n\nAn SBOM is like a **blueprint of `depthviz`**\u2014a complete list of every package it depends on. It helps with:  \n- \u2705 **Security:** Identify known vulnerabilities in dependencies  \n- \u2705 **Transparency:** See exactly what\u2019s inside `depthviz`  \n- \u2705 **Reliability:** Ensures `depthviz` remains stable and up-to-date  \n</details>\n\n\nThe SBOM is generated by the [GitHub Actions workflow](https://github.com/noppanut15/depthviz/blob/main/.github/workflows/deploy.yaml) using the [cyclonedx-python](https://github.com/CycloneDX/cyclonedx-python) library.<br>You can download the latest **SBOM** from the [release artifacts](https://github.com/noppanut15/depthviz/releases).\n\n<div align=\"right\">\n\n[&nwarr; Back to top](#readme-top)\n\n</div>\n\n## \ud83c\udf31 Contribution\n\nWant to make `depthviz` even better? Whether it\u2019s fixing bugs, adding features, or improving dive computer support, every contribution helps!\n\n### \ud83d\udd27 Contribute Code or Ideas  \n- Found a bug? [Open an issue](https://github.com/noppanut15/depthviz/issues) so it can be fixed!  \n- Have a feature idea? Share it in [Discussions](https://github.com/noppanut15/depthviz/discussions) or [open an issue](https://github.com/noppanut15/depthviz/issues).\n- Ready to code? Fork the repo and submit a [pull request](https://github.com/noppanut15/depthviz/pulls).\n\n> \ud83d\udcd6 **Before contributing, please read** [CONTRIBUTING.md](https://github.com/noppanut15/depthviz/blob/main/CONTRIBUTING.md) for guidelines on reporting issues, submitting pull requests, and coding standards.\n\n### \u231a Help Expand Dive Computer Support  \nIs your dive computer not supported yet? You can help change that! By sharing a sample dive log file, you\u2019ll help `depthviz` analyze its format and add support in future updates.  \n\nTo contribute your dive log, check out the guide in [Donate My Dive](https://github.com/noppanut15/depthviz/issues/15). Every log helps make `depthviz` better for all freedivers! \ud83c\udf0a\ud83d\udc99 \n\n### \ud83d\ude4c Credits & Contributors  \n`depthviz` wouldn\u2019t be possible without our amazing community and the open-source projects it relies on.  \n\nSee [AUTHORS.md](https://github.com/noppanut15/depthviz/blob/main/AUTHORS.md) for a list of contributors, maintainers, and dependencies that help power this project.\n\n<div align=\"right\">\n\n[&nwarr; Back to top](#readme-top)\n\n</div>\n\n## \u2696\ufe0f License\n\n`depthviz` is free and open-source software licensed under the [Apache License 2.0](https://github.com/noppanut15/depthviz/blob/main/LICENSE), created and supported by [Noppanut Ploywong](https://github.com/noppanut15) with \u2764\ufe0f for fellow freedivers.\n\n<div align=\"right\">\n\n[&nwarr; Back to top](#readme-top)\n\n</div>\n\n## \ud83d\udcec Contact\n\n- **Have Questions or Ideas?** Join the [Discussions](https://github.com/noppanut15/depthviz/discussions).  \n- **Found a Bug or Have a Feature Request?** [Open an issue](https://github.com/noppanut15/depthviz/issues).  \n- **Need to Reach Out Directly?** Contact the maintainer at [noppanut.connect@gmail.com](mailto:noppanut.connect@gmail.com).\n\nContributions and feedback are always appreciated! \ud83c\udf0a\u2728\n\n<div align=\"right\">\n\n[&nwarr; Back to top](#readme-top)\n\n</div>\n\n<!-- Badge links -->\n[version_badge_img]: https://img.shields.io/pypi/v/depthviz?label=version&logo=pypi&logoColor=white\n[build_badge_img]: https://img.shields.io/github/actions/workflow/status/noppanut15/depthviz/deploy.yaml?logo=github\n[coverage_badge_img]: https://img.shields.io/coveralls/github/noppanut15/depthviz?logo=coveralls\n[pypi_status_img]: https://img.shields.io/pypi/status/depthviz?logo=pypi&logoColor=white\n[download_badge_img]: https://static.pepy.tech/badge/depthviz\n[version_badge_url]: https://pypi.org/project/depthviz/\n[build_badge_url]: https://github.com/noppanut15/depthviz/actions\n[coverage_badge_url]: https://coveralls.io/github/noppanut15/depthviz\n[pypi_status_url]: https://pypi.org/project/depthviz/\n[download_badge_url]: https://pepy.tech/projects/depthviz\n\n<!-- Social links -->\n[x_share_url]: https://x.com/intent/tweet?hashtags=depth%2Cfreediving%2Cvideo%2Cautomation&text=A%20CLI%20tool%20for%20freedivers%20to%20create%20depth%20%26%20time%20overlay%20videos%20from%20dive%20computers%20or%20any%20manual%20logs.&url=https%3A%2F%2Fgithub.com%2Fnoppanut15%2Fdepthviz\n[telegram_share_url]: https://t.me/share/url?url=https%3A//github.com/noppanut15/depthviz&text=A%20CLI%20tool%20for%20freedivers%20to%20create%20depth%20%26%20time%20overlay%20videos%20from%20dive%20computers%20or%20any%20manual%20logs.\n[whatsapp_share_url]: https://api.whatsapp.com/send?text=A%20CLI%20tool%20for%20freedivers%20to%20create%20depth%20%26%20time%20overlay%20videos%20from%20dive%20computers%20or%20any%20manual%20logs.%20https%3A%2F%2Fgithub.com%2Fnoppanut15%2Fdepthviz\n[reddit_share_url]: https://www.reddit.com/submit?url=https%3A%2F%2Fgithub.com%2Fnoppanut15%2Fdepthviz&title=A%20CLI%20tool%20for%20freedivers%20to%20create%20depth%20%26%20time%20overlay%20videos%20from%20dive%20computers%20or%20any%20manual%20logs.%20%23depth%20%23freediving%20%23video%20%23automation\n[facebook_share_url]: https://www.facebook.com/sharer/sharer.php?u=https%3A//github.com/noppanut15/depthviz\n[x_share_img]: https://img.shields.io/badge/x_(twitter)-black?style=for-the-badge&logo=x\n[telegram_share_img]: https://img.shields.io/badge/telegram-black?style=for-the-badge&logo=telegram\n[whatsapp_share_img]: https://img.shields.io/badge/whatsapp-black?style=for-the-badge&logo=whatsapp\n[reddit_share_img]: https://img.shields.io/badge/reddit-black?style=for-the-badge&logo=reddit\n[facebook_share_img]: https://img.shields.io/badge/facebook-black?style=for-the-badge&logo=facebook\n\n<!-- Help -->\n[how_to_img]: https://img.shields.io/badge/How%20to-1974D2?style=flat-square&logo=gitbook&logoColor=white\n[get_log_img]: https://img.shields.io/badge/Get%20log-1974D2?style=flat-square&logo=transmission&logoColor=white\n",
    "bugtrack_url": null,
    "license": "Apache-2.0",
    "summary": "Visualize your depth for your freediving videos: Works with or without dive computers.",
    "version": "0.6.0",
    "project_urls": {
        "Repository": "https://github.com/noppanut15/depthviz"
    },
    "split_keywords": [
        "freediving",
        " dive",
        " video",
        " overlay",
        " depth",
        " dive-computer",
        " dive-log",
        " hud"
    ],
    "urls": [
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "e3234c9fa85571664603e7e17150ba578619f8817bf623c5c22fd14d8331ac74",
                "md5": "c50d2d46f358731c1300d52175b601b8",
                "sha256": "78014b0d4a878c18c32b3c1077a475c3ffff06309b3e15acb76fb8becd80c530"
            },
            "downloads": -1,
            "filename": "depthviz-0.6.0-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "c50d2d46f358731c1300d52175b601b8",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": "<4.0,>=3.9",
            "size": 3684160,
            "upload_time": "2025-02-10T10:41:59",
            "upload_time_iso_8601": "2025-02-10T10:41:59.002200Z",
            "url": "https://files.pythonhosted.org/packages/e3/23/4c9fa85571664603e7e17150ba578619f8817bf623c5c22fd14d8331ac74/depthviz-0.6.0-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "84184fdc86778cdce8ae04964b585456c55c73828fdfb35c085b639a5ecc5af6",
                "md5": "6fae0e68b55a35f03f264cdefbaa3f26",
                "sha256": "381f3666bcfd68d15f00647c39fe1c77a7164ec122289bfe51f57ce22607b578"
            },
            "downloads": -1,
            "filename": "depthviz-0.6.0.tar.gz",
            "has_sig": false,
            "md5_digest": "6fae0e68b55a35f03f264cdefbaa3f26",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": "<4.0,>=3.9",
            "size": 3673885,
            "upload_time": "2025-02-10T10:42:01",
            "upload_time_iso_8601": "2025-02-10T10:42:01.096969Z",
            "url": "https://files.pythonhosted.org/packages/84/18/4fdc86778cdce8ae04964b585456c55c73828fdfb35c085b639a5ecc5af6/depthviz-0.6.0.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2025-02-10 10:42:01",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "github_user": "noppanut15",
    "github_project": "depthviz",
    "travis_ci": false,
    "coveralls": false,
    "github_actions": true,
    "tox": true,
    "lcname": "depthviz"
}
        
Elapsed time: 0.39521s