bottomtime 0.1.0__tar.gz → 0.2.0__tar.gz

bottomtime-0.2.0/.claude/settings.local.json

@@ -0,0 +1,30 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(sqlite3 \"file:data/dives.db?mode=ro\" \"SELECT source, count(*) FROM source_dives GROUP BY source;\" \"SELECT json_extract(header_json,'$.pnf.computer_model'), json_extract(header_json,'$.pnf.computer_firmware'), json_extract(header_json,'$.dive_details.Product'), count(*) FROM source_dives WHERE source='shearwater' GROUP BY 1,2,3;\")",
+      "Bash(sqlite3 \"file:data/dives.db?mode=ro\" \"SELECT json_extract(header_json,'$.file_id_mesgs[0].product_name'), json_extract(header_json,'$.file_id_mesgs[0].manufacturer'), json_extract(header_json,'$.file_id_mesgs[0].product'), count(*) FROM source_dives WHERE source='garmin' GROUP BY 1,2,3 LIMIT 10;\")",
+      "Bash(sqlite3 \"file:$(pwd)/data/dives.db?mode=ro&immutable=1\" \"SELECT source, count(*) FROM source_dives GROUP BY source;\")",
+      "Bash(DB=\"file:$(pwd)/data/dives.db?mode=ro&immutable=1\")",
+      "Bash(sqlite3 \"$DB\" \"SELECT json_extract(header_json,''$.pnf.computer_model''), json_extract(header_json,''$.pnf.computer_firmware''), json_extract(header_json,''$.dive_details.Product''), count(*) FROM source_dives WHERE source=''shearwater'' GROUP BY 1,2,3;\")",
+      "Bash(sqlite3 \"$DB\" \"SELECT json_extract(header_json,''$.file_id_mesgs[0].product_name''), json_extract(header_json,''$.device_info_mesgs[0].product_name''), json_extract(header_json,''$.device_info_mesgs[0].software_version''), count(*) FROM source_dives WHERE source=''garmin'' GROUP BY 1,2,3 LIMIT 10;\")",
+      "Bash(DB=\"file:$(pwd)/data/dives.db?mode=ro&immutable=1\")",
+      "Bash(sqlite3 \"$DB\" \"SELECT json_extract(header_json,''$.file_id_mesgs[0]'') FROM source_dives WHERE source=''garmin'' LIMIT 1;\")",
+      "Bash(sqlite3 \"$DB\" \"SELECT json_extract(header_json,''$.device_info_mesgs[0]'') FROM source_dives WHERE source=''garmin'' LIMIT 1;\")",
+      "Bash(sqlite3 \"$DB\" \"SELECT DISTINCT json_extract(header_json,''$.file_id_mesgs[0].garmin_product'') FROM source_dives WHERE source=''garmin'';\")",
+      "Bash(TMP=/var/folders/xx/8wmmss0x7lb3v3mrhc1rzzc00000gn/T/tmp.yC0jxrHEY0)",
+      "Bash(python -c \"import matplotlib; print(matplotlib.__version__)\")",
+      "Bash(python -m bottomtime.cli --db \"$TMP/dives.db\" plot 318 -o \"$TMP/d318.png\")",
+      "Bash(python -c \"\nfrom bottomtime.api import load_dive\nfrom bottomtime.plot import aligned_series\nd = load_dive(''$TMP/dives.db'', 318)\nfor s in aligned_series(d):\n    print(s[''source''], s[''label''], ''x0=%.0f'' % s[''x''][0], ''xN=%.0f'' % s[''x''][-1])\n\")",
+      "Bash(python -m pytest tests/ -q 2 >& 1)",
+      "Bash(python -c \"import sys; print(sys.prefix != sys.base_prefix, sys.prefix)\")",
+      "Bash(rg -n \"—|–\" --no-heading /Users/snehan/Downloads/bottomtime/README.md /Users/snehan/Downloads/bottomtime/src /Users/snehan/Downloads/bottomtime/tests /Users/snehan/Downloads/bottomtime/pyproject.toml)",
+      "Bash(rg -ni \"leverage|seamless|robust|delve|deep dive|journey|landscape|ecosystem|empower|unlock|supercharge|elevate|streamline|game-chang|cutting-edge|state-of-the-art|best-in-class|thrilled|excited|passionate|humbled|honored|compelling|actionable|utilize|in order to|testament|underscores|boasts|not just|isn''t about|not about\" --no-heading /Users/snehan/Downloads/bottomtime/README.md /Users/snehan/Downloads/bottomtime/src /Users/snehan/Downloads/bottomtime/tests)",
+      "Bash(ls -R /Users/snehan/Downloads/snehankekre.github.io/.claude 2 > /dev/null)",
+      "Bash(ls /Users/snehan/.claude/projects/-Users-snehan-Downloads-snehankekre-github-io/memory/ 2>/dev/null)",
+      "Bash(rg -n \"—|–\" /Users/snehan/Downloads/bottomtime/README.md /Users/snehan/Downloads/bottomtime/src /Users/snehan/Downloads/bottomtime/tests /Users/snehan/Downloads/bottomtime/pyproject.toml)",
+      "Bash(echo \"clean: $?\")",
+      "Bash(python -m pytest tests/ -q)"
+    ],
+    "deny": []
+  }
+}

{bottomtime-0.1.0 → bottomtime-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: bottomtime
-Version: 0.1.0
+Version: 0.2.0
 Summary: Lossless dive-log store: ingest, decode, and reconcile dives from Garmin (FIT) and Shearwater (Petrel Native Format) dive computers
 Project-URL: Homepage, https://github.com/snehankekre/bottomtime
 Project-URL: Issues, https://github.com/snehankekre/bottomtime/issues
@@ -16,6 +16,8 @@ Requires-Python: >=3.10
 Requires-Dist: garmin-fit-sdk>=21.0
 Provides-Extra: dev
 Requires-Dist: pytest; extra == 'dev'
+Provides-Extra: plot
+Requires-Dist: matplotlib>=3.5; extra == 'plot'
 Description-Content-Type: text/markdown
 
 # bottomtime
@@ -36,7 +38,7 @@ bottomtime keeps everything:
   types are preserved raw, per sample and per message.
 - **Decodes Shearwater's Petrel Native Format** directly from a Shearwater
   Cloud database (`dive_data.db`, the "Export Database" output) with a pure
-  Python decoder — including per-sample **GF99, deco ceiling, CNS and battery
+  Python decoder, including per-sample **GF99, deco ceiling, CNS and battery
   voltage** that Shearwater's own XML/CSV exports omit. Unknown record types
   are preserved raw.
 - **Archives every source file verbatim**, content-addressed by SHA-256. The
@@ -80,6 +82,47 @@ bottomtime verify --xml-dir ~/dives/shearwater-xml
 bottomtime status
 ```
 
+## Looking at your dives
+
+Once the store is built, interrogate it from the CLI:
+
+```sh
+bottomtime list                 # canonical dive table (--all includes test dives)
+bottomtime show 291             # one dive: computers, channels, gases, match quality
+bottomtime export 291 -o d.csv  # per-source sample series (also --format json)
+bottomtime plot 291 -o d.png    # aligned dual-computer profile + GF99/ppO2 panels
+```
+
+`plot` needs matplotlib: `pip install 'bottomtime[plot]'`. Alignment uses the
+matcher's clock offset and residual skew, so both computers' profiles sit on
+one time axis without resampling either.
+
+Or from Python:
+
+```python
+import bottomtime
+import pandas as pd
+
+for d in bottomtime.list_dives("data/dives.db"):
+    print(d["dive_number"], d["start_time_utc"], d["max_depth_m"], d["sources"])
+
+dive = bottomtime.load_dive("data/dives.db", 291)
+sw = pd.DataFrame(dive["sources"]["shearwater"]["samples"])
+sw.plot(x="t_s", y=["depth_m", "ceiling_m"])
+```
+
+`load_dive` returns everything about one dive: per-source samples
+(column-oriented, ready for DataFrames), gases, events, the verbatim decoded
+headers, computer model/firmware/serial, and the match metadata.
+
+And it's just SQLite; the views cover the common queries directly:
+
+```sh
+sqlite3 data/dives.db "SELECT dive_number, max_depth_m FROM v_dive_summary
+                       WHERE is_test=0 ORDER BY max_depth_m DESC LIMIT 10"
+datasette data/dives.db   # instant web UI + JSON API, if you have datasette
+```
+
 All commands are idempotent: re-running an ingest skips already-stored dives,
 so syncing after a dive trip only adds what's new.
 
@@ -100,9 +143,17 @@ documented fields and adds empirically verified mappings for GF99 (byte 25),
 deco ceiling (byte 24), battery voltage (byte 18) and @+5 TTS (bytes 26-27),
 validated against Shearwater Cloud's displayed values across hundreds of
 dives. Bytes without a known meaning are preserved per sample. If your dives
-disagree, `bottomtime verify` will say so loudly — issue reports with a
+disagree, `bottomtime verify` will say so loudly; issue reports with a
 failing blob are very welcome.
 
+PNF is shared across the Predator/Petrel firmware family. The empirical
+mappings above have so far been validated on **Perdix 2** and **Petrel 3**
+logs (the latter integrated with a Choptima CCR). Other models, and
+standalone vs. CCR-integrated units, may populate fields differently;
+unknown bytes are always preserved, and `bottomtime verify` cross-checks
+every decoded value, so drift on other hardware is detected rather than
+silently mis-decoded.
+
 ## License
 
 MIT

{bottomtime-0.1.0 → bottomtime-0.2.0}/README.md

@@ -16,7 +16,7 @@ bottomtime keeps everything:
   types are preserved raw, per sample and per message.
 - **Decodes Shearwater's Petrel Native Format** directly from a Shearwater
   Cloud database (`dive_data.db`, the "Export Database" output) with a pure
-  Python decoder — including per-sample **GF99, deco ceiling, CNS and battery
+  Python decoder, including per-sample **GF99, deco ceiling, CNS and battery
   voltage** that Shearwater's own XML/CSV exports omit. Unknown record types
   are preserved raw.
 - **Archives every source file verbatim**, content-addressed by SHA-256. The
@@ -60,6 +60,47 @@ bottomtime verify --xml-dir ~/dives/shearwater-xml
 bottomtime status
 ```
 
+## Looking at your dives
+
+Once the store is built, interrogate it from the CLI:
+
+```sh
+bottomtime list                 # canonical dive table (--all includes test dives)
+bottomtime show 291             # one dive: computers, channels, gases, match quality
+bottomtime export 291 -o d.csv  # per-source sample series (also --format json)
+bottomtime plot 291 -o d.png    # aligned dual-computer profile + GF99/ppO2 panels
+```
+
+`plot` needs matplotlib: `pip install 'bottomtime[plot]'`. Alignment uses the
+matcher's clock offset and residual skew, so both computers' profiles sit on
+one time axis without resampling either.
+
+Or from Python:
+
+```python
+import bottomtime
+import pandas as pd
+
+for d in bottomtime.list_dives("data/dives.db"):
+    print(d["dive_number"], d["start_time_utc"], d["max_depth_m"], d["sources"])
+
+dive = bottomtime.load_dive("data/dives.db", 291)
+sw = pd.DataFrame(dive["sources"]["shearwater"]["samples"])
+sw.plot(x="t_s", y=["depth_m", "ceiling_m"])
+```
+
+`load_dive` returns everything about one dive: per-source samples
+(column-oriented, ready for DataFrames), gases, events, the verbatim decoded
+headers, computer model/firmware/serial, and the match metadata.
+
+And it's just SQLite; the views cover the common queries directly:
+
+```sh
+sqlite3 data/dives.db "SELECT dive_number, max_depth_m FROM v_dive_summary
+                       WHERE is_test=0 ORDER BY max_depth_m DESC LIMIT 10"
+datasette data/dives.db   # instant web UI + JSON API, if you have datasette
+```
+
 All commands are idempotent: re-running an ingest skips already-stored dives,
 so syncing after a dive trip only adds what's new.
 
@@ -80,9 +121,17 @@ documented fields and adds empirically verified mappings for GF99 (byte 25),
 deco ceiling (byte 24), battery voltage (byte 18) and @+5 TTS (bytes 26-27),
 validated against Shearwater Cloud's displayed values across hundreds of
 dives. Bytes without a known meaning are preserved per sample. If your dives
-disagree, `bottomtime verify` will say so loudly — issue reports with a
+disagree, `bottomtime verify` will say so loudly; issue reports with a
 failing blob are very welcome.
 
+PNF is shared across the Predator/Petrel firmware family. The empirical
+mappings above have so far been validated on **Perdix 2** and **Petrel 3**
+logs (the latter integrated with a Choptima CCR). Other models, and
+standalone vs. CCR-integrated units, may populate fields differently;
+unknown bytes are always preserved, and `bottomtime verify` cross-checks
+every decoded value, so drift on other hardware is detected rather than
+silently mis-decoded.
+
 ## License
 
 MIT

{bottomtime-0.1.0 → bottomtime-0.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "bottomtime"
-version = "0.1.0"
+version = "0.2.0"
 description = "Lossless dive-log store: ingest, decode, and reconcile dives from Garmin (FIT) and Shearwater (Petrel Native Format) dive computers"
 readme = "README.md"
 license = "MIT"
@@ -21,6 +21,7 @@ classifiers = [
 dependencies = ["garmin-fit-sdk>=21.0"]
 
 [project.optional-dependencies]
+plot = ["matplotlib>=3.5"]
 dev = ["pytest"]
 
 [project.scripts]

{bottomtime-0.1.0 → bottomtime-0.2.0}/src/bottomtime/__init__.py

@@ -1,6 +1,6 @@
 """bottomtime: lossless dive-log store for multi-computer divers."""
 
-__version__ = "0.1.0"
+__version__ = "0.2.0"
 
 from .api import list_dives, load_dive
 

{bottomtime-0.1.0 → bottomtime-0.2.0}/src/bottomtime/api.py

@@ -11,9 +11,47 @@ import json
 import sqlite3
 from pathlib import Path
 
+from .decode.pnf import COMPUTER_MODELS
+
 _SAMPLE_TABLES = {"garmin": "garmin_samples", "shearwater": "shearwater_samples"}
 
 
+def computer_info(source: str, header: dict) -> dict:
+    """Model / firmware / serial of the computer that produced a source log,
+    extracted from its verbatim header."""
+    if source == "garmin":
+        file_id = (header.get("file_id_mesgs") or [{}])[0]
+        product = file_id.get("garmin_product") or file_id.get("product_name")
+        model = str(product).replace("_", " ").title() if product else None
+        firmware = next(
+            (
+                d.get("software_version")
+                for d in header.get("device_info_mesgs") or []
+                if d.get("software_version")
+            ),
+            None,
+        )
+        serial = file_id.get("serial_number")
+        return {"model": model, "firmware": firmware, "serial": serial}
+
+    pnf_header = header.get("pnf") or {}
+    model_id = pnf_header.get("computer_model")
+    model = (
+        COMPUTER_MODELS.get(model_id, f"model {model_id}")
+        if model_id is not None
+        else None
+    )
+    firmware = pnf_header.get("computer_firmware")
+    serial = (header.get("dive_details") or {}).get("SerialNumber")
+    if not serial and pnf_header.get("computer_serial") is not None:
+        serial = f"{pnf_header['computer_serial']:08X}"
+    return {
+        "model": model,
+        "firmware": f"v{firmware}" if firmware is not None else None,
+        "serial": serial,
+    }
+
+
 def _columns_of(con: sqlite3.Connection, table: str) -> list[str]:
     return [r[1] for r in con.execute(f"PRAGMA table_info({table})")]
 
@@ -45,6 +83,7 @@ def load_dive(db_path: str | Path, dive_number: int) -> dict:
                 (sd["id"],),
             ).fetchall()
             samples = {c: [r[i] for r in rows] for i, c in enumerate(cols)}
+            header = json.loads(sd["header_json"])
             entry = {
                 "source_dive_id": sd["id"],
                 "source_key": sd["source_key"],
@@ -52,9 +91,28 @@ def load_dive(db_path: str | Path, dive_number: int) -> dict:
                 "start_time_local": sd["start_time_local"],
                 "duration_s": sd["duration_s"],
                 "max_depth_m": sd["max_depth_m"],
+                "sample_interval_ms": sd["sample_interval_ms"],
                 "mode": sd["mode"],
-                "header": json.loads(sd["header_json"]),
+                "computer": computer_info(sd["source"], header),
+                "header": header,
                 "samples": samples,
+                "gases": [
+                    {k: g[k] for k in g.keys()}
+                    for g in con.execute(
+                        "SELECT gas_index, o2_pct, he_pct, circuit, enabled, used"
+                        " FROM gases WHERE source_dive_id=? ORDER BY gas_index",
+                        (sd["id"],),
+                    )
+                ],
+                "events": [
+                    {"t_s": e["t_s"], "kind": e["kind"],
+                     "payload": json.loads(e["payload_json"])}
+                    for e in con.execute(
+                        "SELECT t_s, kind, payload_json FROM events"
+                        " WHERE source_dive_id=? ORDER BY t_s",
+                        (sd["id"],),
+                    )
+                ],
             }
             key = sd["source"]
             if key in out["sources"]:  # several logs from one source (splits)
@@ -65,6 +123,18 @@ def load_dive(db_path: str | Path, dive_number: int) -> dict:
                     out["sources"][key] = [existing, entry]
             else:
                 out["sources"][key] = entry
+        out["matches"] = [
+            {k: m[k] for k in m.keys()}
+            for m in con.execute(
+                "SELECT m.garmin_source_dive_id, m.shearwater_source_dive_id,"
+                " m.clock_offset_s, m.residual_skew_s, m.xcorr_score,"
+                " m.duration_delta_s, m.max_depth_delta_m, m.method, m.status"
+                " FROM matches m JOIN dive_members dm"
+                " ON dm.source_dive_id = m.garmin_source_dive_id"
+                " WHERE dm.dive_id=? AND m.status IN ('auto','confirmed')",
+                (dive["id"],),
+            )
+        ]
         return out
     finally:
         con.close()

bottomtime-0.2.0/src/bottomtime/cli.py

@@ -0,0 +1,336 @@
+"""bottomtime command line interface.
+
+    bottomtime init
+    bottomtime ingest garmin <fit-dir>
+    bottomtime ingest shearwater <dive_data.db>
+    bottomtime match
+    bottomtime verify [--xml-dir DIR]
+    bottomtime status
+    bottomtime list [--all]
+    bottomtime show <dive-number>
+    bottomtime export <dive-number> [--format csv|json] [-o FILE]
+    bottomtime plot <dive-number> [-o FILE]
+
+All commands are idempotent: re-running an ingest skips anything already
+stored (content-hash keyed), match recomputes only 'auto' links.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from datetime import datetime, timedelta
+from pathlib import Path
+
+from .store import db as store_db
+
+
+def _fmt_duration(seconds) -> str:
+    if seconds is None:
+        return "?"
+    s = int(round(seconds))
+    h, rem = divmod(s, 3600)
+    m, sec = divmod(rem, 60)
+    return f"{h}:{m:02d}:{sec:02d}" if h else f"{m}:{sec:02d}"
+
+
+def _fmt_local(start_utc, utc_offset_min, fmt="%Y-%m-%d %H:%M") -> str:
+    if start_utc is None:
+        return "?"
+    dt = datetime.strptime(start_utc, "%Y-%m-%d %H:%M:%S")
+    if utc_offset_min is not None:
+        dt += timedelta(minutes=utc_offset_min)
+    return dt.strftime(fmt)
+
+
+def _fmt_offset(utc_offset_min) -> str:
+    if utc_offset_min is None:
+        return "UTC?"
+    sign = "+" if utc_offset_min >= 0 else "-"
+    h, m = divmod(abs(utc_offset_min), 60)
+    return f"UTC{sign}{h:02d}:{m:02d}"
+
+
+def _iter_source_entries(dive: dict):
+    for source, value in dive["sources"].items():
+        for entry in value if isinstance(value, list) else [value]:
+            yield source, entry
+
+
+def _computer_label(info: dict) -> str:
+    parts = [info.get("model") or "unknown"]
+    if info.get("firmware") is not None:
+        parts.append(str(info["firmware"]))
+    return " ".join(parts)
+
+
+def _cmd_list(con, include_tests: bool) -> int:
+    from .api import computer_info
+
+    where = "" if include_tests else "WHERE is_test = 0"
+    dives = con.execute(
+        f"SELECT * FROM v_dive_summary {where} ORDER BY start_time_utc"
+    ).fetchall()
+    members = {
+        r["id"]: r
+        for r in con.execute(
+            "SELECT id, source, mode, header_json FROM source_dives"
+        )
+    }
+    rows = []
+    for d in dives:
+        computers, mode = [], None
+        for sid in (int(i) for i in d["source_dive_ids"].split(",")):
+            sd = members[sid]
+            info = computer_info(sd["source"], json.loads(sd["header_json"]))
+            computers.append(info.get("model") or sd["source"])
+            if sd["source"] == "shearwater" or mode is None:
+                mode = sd["mode"] or mode
+        depth = f"{d['max_depth_m']:.1f}" if d["max_depth_m"] is not None else "?"
+        rows.append(
+            (
+                "T" if d["is_test"] else str(d["dive_number"]),
+                _fmt_local(d["start_time_utc"], d["utc_offset_min"]),
+                _fmt_duration(d["duration_s"]),
+                depth,
+                mode or "?",
+                " + ".join(sorted(set(computers))),
+            )
+        )
+    if not rows:
+        print("no dives (run ingest + match first)")
+        return 0
+    header = ("#", "start (local)", "duration", "max m", "mode", "computers")
+    widths = [max(len(header[i]), *(len(r[i]) for r in rows)) for i in range(len(header))]
+    fmt = "  ".join(
+        f"{{:{'>' if i in (0, 2, 3) else '<'}{widths[i]}}}" for i in range(len(header))
+    )
+    print(fmt.format(*header))
+    for r in rows:
+        print(fmt.format(*r))
+    return 0
+
+
+def _cmd_show(db_path: str, dive_number: int) -> int:
+    from .api import load_dive
+
+    dive = load_dive(db_path, dive_number)
+    depth = f"{dive['max_depth_m']:.1f} m" if dive["max_depth_m"] is not None else "?"
+    print(
+        f"dive {dive['dive_number']}  "
+        f"{_fmt_local(dive['start_time_utc'], dive['utc_offset_min'])} "
+        f"({_fmt_offset(dive['utc_offset_min'])})  "
+        f"duration {_fmt_duration(dive['duration_s'])}  max depth {depth}"
+    )
+    for source, e in _iter_source_entries(dive):
+        info = e["computer"]
+        serial = f"  serial {info['serial']}" if info.get("serial") else ""
+        print(f"\n  [{source}] {_computer_label(info)}{serial}"
+              f"  (source dive {e['source_dive_id']}, key {e['source_key']})")
+        interval = (
+            f"{e['sample_interval_ms'] / 1000:g} s"
+            if e["sample_interval_ms"] is not None
+            else "?"
+        )
+        n = len(e["samples"].get("t_s", []))
+        e_depth = f"{e['max_depth_m']:.1f} m" if e["max_depth_m"] is not None else "?"
+        print(
+            f"    start {e['start_time_local']} local  "
+            f"duration {_fmt_duration(e['duration_s'])}  max {e_depth}  "
+            f"mode {e['mode'] or '?'}  {n} samples @ {interval}"
+        )
+        channels = sorted(
+            c
+            for c, vals in e["samples"].items()
+            if c not in ("t_s", "extra_json") and any(v is not None for v in vals)
+        )
+        if channels:
+            print(f"    channels: {', '.join(channels)}")
+        gases = [
+            f"{(g['o2_pct'] or 0):g}/{(g['he_pct'] or 0):g}"
+            + (f" {g['circuit']}" if g["circuit"] else "")
+            for g in e["gases"]
+            if g["o2_pct"] or g["he_pct"]
+        ]
+        if gases:
+            print(f"    gases: {', '.join(gases)}")
+        if e["events"]:
+            print(f"    events: {len(e['events'])}")
+    for m in dive["matches"]:
+        skew = f"{m['residual_skew_s']:g} s" if m["residual_skew_s"] is not None else "?"
+        score = f"{m['xcorr_score']:.3f}" if m["xcorr_score"] is not None else "?"
+        delta = (
+            f"{m['max_depth_delta_m']:.2f} m"
+            if m["max_depth_delta_m"] is not None
+            else "?"
+        )
+        print(
+            f"\n  match garmin#{m['garmin_source_dive_id']} <-> "
+            f"shearwater#{m['shearwater_source_dive_id']}: "
+            f"clock offset {m['clock_offset_s']:+d} s, xcorr {score}, "
+            f"residual skew {skew}, depth delta {delta} ({m['status']})"
+        )
+    return 0
+
+
+def _cmd_export(db_path: str, dive_number: int, fmt: str, out: Path | None) -> int:
+    from .api import load_dive
+
+    dive = load_dive(db_path, dive_number)
+    if fmt == "json":
+        text = json.dumps(dive, separators=(",", ":"), default=str)
+        if out:
+            out.write_text(text)
+            print(f"wrote {out}")
+        else:
+            print(text)
+        return 0
+
+    import csv
+
+    columns: list[str] = []
+    for _source, e in _iter_source_entries(dive):
+        for c in e["samples"]:
+            if c not in columns:
+                columns.append(c)
+    fh = out.open("w", newline="") if out else sys.stdout
+    try:
+        writer = csv.writer(fh)
+        writer.writerow(["source", "source_dive_id"] + columns)
+        for source, e in _iter_source_entries(dive):
+            samples = e["samples"]
+            n = len(samples.get("t_s", []))
+            for i in range(n):
+                writer.writerow(
+                    [source, e["source_dive_id"]]
+                    + [
+                        samples[c][i] if c in samples else None
+                        for c in columns
+                    ]
+                )
+    finally:
+        if out:
+            fh.close()
+            print(f"wrote {out}")
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="bottomtime")
+    parser.add_argument("--db", default="data/dives.db", help="path to the dive store")
+    parser.add_argument(
+        "--archive", default="archive", help="directory for verbatim raw source copies"
+    )
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    sub.add_parser("init", help="create an empty dive store")
+
+    p_ingest = sub.add_parser("ingest", help="ingest a data source")
+    ingest_sub = p_ingest.add_subparsers(dest="source", required=True)
+    p_garmin = ingest_sub.add_parser("garmin", help="a directory of FIT files")
+    p_garmin.add_argument("fit_dir", type=Path)
+    p_garmin.add_argument(
+        "--index",
+        default="dives_index.json",
+        help="Garmin Connect index JSON filename inside fit-dir",
+    )
+    p_sw = ingest_sub.add_parser("shearwater", help="a Shearwater Cloud dive_data.db")
+    p_sw.add_argument("db_path", type=Path)
+
+    sub.add_parser("match", help="match dual-computer dives, build canonical dives")
+
+    p_verify = sub.add_parser("verify", help="run the verification suite")
+    p_verify.add_argument("--xml-dir", type=Path, default=None,
+                          help="directory of Shearwater XML exports to cross-check")
+
+    sub.add_parser("status", help="summarize the store")
+
+    p_list = sub.add_parser("list", help="list canonical dives")
+    p_list.add_argument("--all", action="store_true", help="include test dives")
+
+    p_show = sub.add_parser("show", help="show one dive in detail")
+    p_show.add_argument("dive_number", type=int)
+
+    p_export = sub.add_parser("export", help="export a dive's sample series")
+    p_export.add_argument("dive_number", type=int)
+    p_export.add_argument("--format", choices=("csv", "json"), default="csv")
+    p_export.add_argument("-o", "--out", type=Path, default=None)
+
+    p_plot = sub.add_parser("plot", help="plot a dive (requires matplotlib)")
+    p_plot.add_argument("dive_number", type=int)
+    p_plot.add_argument("-o", "--out", type=Path, default=None,
+                        help="write an image instead of opening a window")
+
+    args = parser.parse_args(argv)
+    con = store_db.connect(args.db)
+    archive_dir = Path(args.archive)
+
+    if args.command == "init":
+        print(f"initialized {args.db}")
+        return 0
+
+    if args.command == "ingest" and args.source == "garmin":
+        from .ingest.garmin_fit import ingest_garmin_dir
+
+        stats = ingest_garmin_dir(con, archive_dir, args.fit_dir, args.index)
+        print(f"garmin: {stats}")
+        return 1 if stats["failed"] else 0
+
+    if args.command == "ingest" and args.source == "shearwater":
+        from .ingest.shearwater_db import ingest_shearwater_db
+
+        stats = ingest_shearwater_db(con, archive_dir, args.db_path)
+        print(f"shearwater: {stats}")
+        return 1 if stats["failed"] else 0
+
+    if args.command == "match":
+        from .match.matcher import run_match
+
+        stats = run_match(con)
+        print(f"match: {stats}")
+        return 0
+
+    if args.command == "verify":
+        from .verify.crosscheck import run_verify
+
+        return run_verify(con, args.xml_dir)
+
+    if args.command == "list":
+        return _cmd_list(con, args.all)
+
+    if args.command in ("show", "export", "plot"):
+        try:
+            if args.command == "show":
+                return _cmd_show(args.db, args.dive_number)
+            if args.command == "export":
+                return _cmd_export(args.db, args.dive_number, args.format, args.out)
+            from .plot import plot_dive
+
+            plot_dive(args.db, args.dive_number, args.out)
+            return 0
+        except KeyError as e:
+            print(e.args[0] if e.args else e, file=sys.stderr)
+            return 1
+
+    if args.command == "status":
+        for line in con.execute(
+            "SELECT source || ' source dives: ' || count(*) FROM source_dives GROUP BY source"
+        ):
+            print(line[0])
+        for line in con.execute(
+            "SELECT 'canonical dives: ' || count(*) || ' (' ||"
+            " sum(CASE WHEN is_test THEN 1 ELSE 0 END) || ' test)' FROM dives"
+        ):
+            print(line[0])
+        for line in con.execute(
+            "SELECT 'matched pairs: ' || count(*) FROM matches WHERE status IN ('auto','confirmed')"
+        ):
+            print(line[0])
+        return 0
+
+    return 2
+
+
+if __name__ == "__main__":
+    sys.exit(main())

{bottomtime-0.1.0 → bottomtime-0.2.0}/src/bottomtime/decode/pnf.py

@@ -14,7 +14,7 @@ fields sit at legacy-offset + 1 (the PNF type byte), opening/closing record
 fields at the absolute offsets used for their legacy 128-byte block.
 
 Record types this decoder does not understand are returned raw in
-`PnfDive.unknown_records` — nothing is dropped.
+`PnfDive.unknown_records`; nothing is dropped.
 
 DECODER_VERSION history:
   1  initial port of the libdivecomputer field set
@@ -65,6 +65,23 @@ DIVE_MODES = {
 
 DECO_MODELS = {0: "gf", 1: "vpmb", 2: "vpmb_gfs", 3: "dciem"}
 
+# Final-record byte 13 model ids, names per libdivecomputer's descriptors.
+# The PNF layout is shared across the family; bottomtime's field mappings are
+# validated so far on Petrel 3 (10) and Perdix 2 (11) logs.
+COMPUTER_MODELS = {
+    2: "Predator",
+    3: "Petrel",
+    4: "Nerd",
+    5: "Perdix",
+    6: "Perdix AI",
+    7: "Nerd 2",
+    8: "Teric",
+    9: "Peregrine",
+    10: "Petrel 3",
+    11: "Perdix 2",
+    12: "Tern",
+}
+
 # Sample bytes not (yet) assigned a meaning; kept per sample as b<offset>.
 # 18 (battery), 24 (ceiling), 25 (gf99), 26-27 (@+5) were identified
 # empirically and promoted in v2. 30-31 read 0xFFFF (sentinel) so far.

{bottomtime-0.1.0 → bottomtime-0.2.0}/src/bottomtime/match/correlate.py

@@ -52,7 +52,7 @@ def median_abs_delta(
     lag_s: float = 0.0,
 ) -> float | None:
     """Median |depth difference| over the overlapping window, with series_b
-    shifted by lag_s. Robust where NCC is unstable (low-variance pool
+    shifted by lag_s. Stable where NCC is unstable (low-variance pool
     profiles): two computers on the same body must agree on depth."""
     if not series_a or not series_b:
         return None

bottomtime-0.2.0/src/bottomtime/plot.py

@@ -0,0 +1,163 @@
+"""Plot one canonical dive: both computers' depth profiles overlaid on a
+shared clock (using the matcher's backfilled UTC start times), plus deco and
+ppO2 panels when those channels are present.
+
+matplotlib is an optional dependency: pip install 'bottomtime[plot]'.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from pathlib import Path
+
+from .api import load_dive
+
+
+def _parse(ts: str) -> datetime:
+    return datetime.strptime(ts, "%Y-%m-%d %H:%M:%S")
+
+
+def _iter_source_entries(dive: dict):
+    for source, value in dive["sources"].items():
+        for entry in value if isinstance(value, list) else [value]:
+            yield source, entry
+
+
+def _nan(values: list) -> list[float]:
+    return [float("nan") if v is None else float(v) for v in values]
+
+
+def _has(entry: dict, channel: str) -> bool:
+    return any(v is not None for v in entry["samples"].get(channel, []))
+
+
+def aligned_series(dive: dict) -> list[dict]:
+    """One dict per source log: label plus x (seconds since the canonical
+    dive's start). Alignment uses each log's backfilled UTC start plus, for
+    Shearwater logs, the matcher's residual clock skew (the wall clock's
+    error beyond the whole-hour zone offset)."""
+    t0 = _parse(dive["start_time_utc"])
+    skew = {
+        m["shearwater_source_dive_id"]: m["residual_skew_s"] or 0.0
+        for m in dive.get("matches", [])
+    }
+    out = []
+    for source, entry in _iter_source_entries(dive):
+        start = entry["start_time_utc"] or dive["start_time_utc"]
+        base = (_parse(start) - t0).total_seconds()
+        if source == "shearwater":
+            base += skew.get(entry["source_dive_id"], 0.0)
+        model = entry["computer"].get("model") or source
+        out.append(
+            {
+                "source": source,
+                "label": model,
+                "x": [base + t for t in entry["samples"]["t_s"]],
+                "entry": entry,
+            }
+        )
+    return out
+
+
+def plot_dive(db_path: str | Path, dive_number: int, out: Path | None = None):
+    dive = load_dive(db_path, dive_number)
+    series = aligned_series(dive)
+
+    try:
+        import matplotlib
+
+        if out:
+            matplotlib.use("Agg")
+        import matplotlib.pyplot as plt
+    except ImportError:
+        raise SystemExit(
+            "bottomtime plot requires matplotlib: pip install 'bottomtime[plot]'"
+        )
+
+    panels = ["depth"]
+    if any(_has(s["entry"], "gf99") for s in series):
+        panels.append("gf99")
+    ppo2_channels = ("sensor1_ppo2", "sensor2_ppo2", "sensor3_ppo2",
+                     "avg_ppo2", "po2", "setpoint")
+    if any(_has(s["entry"], c) for s in series for c in ppo2_channels):
+        panels.append("ppo2")
+
+    fig, axes = plt.subplots(
+        len(panels), 1, sharex=True, figsize=(11, 2.8 * len(panels)), squeeze=False
+    )
+    axes = [ax for (ax,) in axes]
+    ax_by_panel = dict(zip(panels, axes))
+
+    ax = ax_by_panel["depth"]
+    for s in series:
+        samples = s["entry"]["samples"]
+        x_min = [x / 60.0 for x in s["x"]]
+        ax.plot(x_min, _nan(samples["depth_m"]), label=s["label"], linewidth=1.2)
+        if _has(s["entry"], "ceiling_m"):
+            ax.plot(
+                x_min,
+                _nan(samples["ceiling_m"]),
+                linestyle="--",
+                linewidth=0.9,
+                label=f"{s['label']} ceiling",
+            )
+    ax.invert_yaxis()
+    ax.set_ylabel("depth (m)")
+    ax.legend(loc="lower right", fontsize=8)
+    ax.grid(True, alpha=0.3)
+
+    if "gf99" in ax_by_panel:
+        ax = ax_by_panel["gf99"]
+        for s in series:
+            if _has(s["entry"], "gf99"):
+                ax.plot(
+                    [x / 60.0 for x in s["x"]],
+                    _nan(s["entry"]["samples"]["gf99"]),
+                    linewidth=1.0,
+                    label=f"{s['label']} GF99",
+                )
+        ax.set_ylabel("GF99 (%)")
+        ax.legend(loc="upper right", fontsize=8)
+        ax.grid(True, alpha=0.3)
+
+    if "ppo2" in ax_by_panel:
+        ax = ax_by_panel["ppo2"]
+        for s in series:
+            samples = s["entry"]["samples"]
+            x_min = [x / 60.0 for x in s["x"]]
+            for channel, style in (
+                ("sensor1_ppo2", "-"),
+                ("sensor2_ppo2", "-"),
+                ("sensor3_ppo2", "-"),
+                ("po2", "-"),
+                ("setpoint", ":"),
+            ):
+                if _has(s["entry"], channel):
+                    ax.plot(
+                        x_min,
+                        _nan(samples[channel]),
+                        style,
+                        linewidth=0.9,
+                        label=f"{s['label']} {channel}",
+                    )
+        ax.set_ylabel("ppO2 (bar)")
+        ax.legend(loc="upper right", fontsize=8)
+        ax.grid(True, alpha=0.3)
+
+    axes[-1].set_xlabel("runtime (min)")
+    depth = (
+        f"max {dive['max_depth_m']:.1f} m"
+        if dive["max_depth_m"] is not None
+        else ""
+    )
+    fig.suptitle(
+        f"dive {dive['dive_number']}  {dive['start_time_utc']} UTC  {depth}".rstrip()
+    )
+    fig.tight_layout()
+
+    if out:
+        fig.savefig(out, dpi=150)
+        print(f"wrote {out}")
+    else:
+        plt.show()
+    return fig

bottomtime-0.2.0/tests/test_cli.py

@@ -0,0 +1,151 @@
+import csv
+import io
+import json
+
+import pytest
+
+from bottomtime import cli
+from bottomtime.api import computer_info, load_dive
+from bottomtime.plot import aligned_series
+from bottomtime.store import db as store_db
+
+GARMIN_HEADER = {
+    "file_id_mesgs": [{"garmin_product": "descent_mk3", "serial_number": 12345}],
+    "device_info_mesgs": [{"software_version": 25.21}],
+}
+SHEARWATER_HEADER = {
+    "pnf": {"computer_model": 11, "computer_firmware": 100,
+            "computer_serial": 0xA823C228},
+    "dive_details": {"SerialNumber": "A823C228"},
+}
+
+
+@pytest.fixture
+def store(tmp_path):
+    db_path = tmp_path / "dives.db"
+    con = store_db.connect(db_path)
+    with con:
+        con.execute(
+            "INSERT INTO raw_artifacts (id, kind, sha256, size_bytes, original_path,"
+            " archive_path, imported_at) VALUES (1,'fit','x',1,'a','b','now')"
+        )
+        con.execute(
+            "INSERT INTO source_dives (id, source, artifact_id, source_key,"
+            " content_hash, decoder_version, start_time_utc, start_time_local,"
+            " utc_offset_min, duration_s, max_depth_m, sample_interval_ms, mode,"
+            " header_json) VALUES (1,'garmin',1,'act1','h1',1,"
+            " '2026-07-06 03:47:01','2026-07-06 11:47:01',480,120,20.0,1000,"
+            " 'multi_gas_diving',?)",
+            (json.dumps(GARMIN_HEADER),),
+        )
+        con.execute(
+            "INSERT INTO source_dives (id, source, artifact_id, source_key,"
+            " content_hash, decoder_version, start_time_utc, start_time_local,"
+            " utc_offset_min, duration_s, max_depth_m, sample_interval_ms, mode,"
+            " header_json) VALUES (2,'shearwater',1,'A823C228#1','h2',2,"
+            " '2026-07-06 03:43:52','2026-07-06 11:43:52',480,110,20.2,10000,"
+            " 'oc_tec',?)",
+            (json.dumps(SHEARWATER_HEADER),),
+        )
+        con.executemany(
+            "INSERT INTO garmin_samples (source_dive_id, t_s, depth_m) VALUES (1,?,?)",
+            [(t, t * 0.5) for t in range(5)],
+        )
+        con.executemany(
+            "INSERT INTO shearwater_samples (source_dive_id, t_s, depth_m, gf99)"
+            " VALUES (2,?,?,?)",
+            [(t * 10.0, t * 5.0, 10.0 + t) for t in range(3)],
+        )
+        con.execute(
+            "INSERT INTO gases (source_dive_id, gas_index, o2_pct, he_pct, circuit,"
+            " enabled) VALUES (2, 0, 21, 35, 'oc', 1)"
+        )
+        con.execute(
+            "INSERT INTO events (source_dive_id, t_s, kind, payload_json)"
+            " VALUES (2, 0, 'pnf_info_event', '{}')"
+        )
+        con.execute(
+            "INSERT INTO matches (garmin_source_dive_id, shearwater_source_dive_id,"
+            " clock_offset_s, residual_skew_s, xcorr_score, duration_delta_s,"
+            " max_depth_delta_m, method, status, matched_at)"
+            " VALUES (1, 2, 28800, 190.0, 0.999, 10, 0.2, 'test', 'auto', 'now')"
+        )
+        con.execute(
+            "INSERT INTO dives (id, dive_number, start_time_utc, utc_offset_min,"
+            " duration_s, max_depth_m, is_test) VALUES"
+            " (1, 1, '2026-07-06 03:47:01', 480, 120, 20.2, 0)"
+        )
+        con.execute(
+            "INSERT INTO dives (id, dive_number, start_time_utc, utc_offset_min,"
+            " duration_s, max_depth_m, is_test) VALUES"
+            " (2, NULL, '2026-07-06 05:00:00', 480, 30, 1.0, 1)"
+        )
+        con.executemany(
+            "INSERT INTO dive_members (dive_id, source_dive_id) VALUES (?,?)",
+            [(1, 1), (1, 2)],
+        )
+    con.close()
+    return db_path
+
+
+def test_computer_info():
+    g = computer_info("garmin", GARMIN_HEADER)
+    assert g == {"model": "Descent Mk3", "firmware": 25.21, "serial": 12345}
+    s = computer_info("shearwater", SHEARWATER_HEADER)
+    assert s == {"model": "Perdix 2", "firmware": "v100", "serial": "A823C228"}
+
+
+def test_list(store, capsys):
+    assert cli.main(["--db", str(store), "list"]) == 0
+    out = capsys.readouterr().out
+    assert "Descent Mk3 + Perdix 2" in out
+    assert "2026-07-06 11:47" in out  # local time
+    assert "oc_tec" in out  # shearwater mode preferred
+    assert "T" not in out.splitlines()[0]  # header, then only dive 1
+
+
+def test_show(store, capsys):
+    assert cli.main(["--db", str(store), "show", "1"]) == 0
+    out = capsys.readouterr().out
+    assert "dive 1" in out
+    assert "Descent Mk3 25.21" in out
+    assert "Perdix 2 v100" in out
+    assert "gases: 21/35 oc" in out
+    assert "clock offset +28800 s" in out
+    assert "gf99" in out  # channel coverage
+
+
+def test_show_missing_dive(store, capsys):
+    assert cli.main(["--db", str(store), "show", "99"]) == 1
+    assert "no dive with number 99" in capsys.readouterr().err
+
+
+def test_export_json(store, tmp_path, capsys):
+    out_file = tmp_path / "d1.json"
+    assert cli.main(
+        ["--db", str(store), "export", "1", "--format", "json", "-o", str(out_file)]
+    ) == 0
+    data = json.loads(out_file.read_text())
+    assert sorted(data["sources"]) == ["garmin", "shearwater"]
+    assert data["sources"]["garmin"]["samples"]["depth_m"] == [0.0, 0.5, 1.0, 1.5, 2.0]
+    assert data["matches"][0]["clock_offset_s"] == 28800
+
+
+def test_export_csv_stdout(store, capsys):
+    assert cli.main(["--db", str(store), "export", "1"]) == 0
+    rows = list(csv.reader(io.StringIO(capsys.readouterr().out)))
+    header = rows[0]
+    assert header[:3] == ["source", "source_dive_id", "t_s"]
+    assert "gf99" in header
+    body = rows[1:]
+    assert len(body) == 8  # 5 garmin + 3 shearwater, never merged
+    assert {r[0] for r in body} == {"garmin", "shearwater"}
+
+
+def test_aligned_series_applies_clock_offset_and_skew(store):
+    dive = load_dive(store, 1)
+    series = {s["source"]: s for s in aligned_series(dive)}
+    assert series["garmin"]["x"][0] == 0.0
+    # shearwater start_utc is 189 s before the dive start; +190 s skew -> +1 s
+    assert series["shearwater"]["x"][0] == pytest.approx(1.0)
+    assert series["shearwater"]["label"] == "Perdix 2"

bottomtime-0.1.0/src/bottomtime/cli.py

@@ -1,107 +0,0 @@
-"""bottomtime command line interface.
-
-    bottomtime init
-    bottomtime ingest garmin <fit-dir>
-    bottomtime ingest shearwater <dive_data.db>
-    bottomtime match
-    bottomtime verify [--xml-dir DIR]
-    bottomtime status
-
-All commands are idempotent: re-running an ingest skips anything already
-stored (content-hash keyed), match recomputes only 'auto' links.
-"""
-
-from __future__ import annotations
-
-import argparse
-import sys
-from pathlib import Path
-
-from .store import db as store_db
-
-
-def main(argv: list[str] | None = None) -> int:
-    parser = argparse.ArgumentParser(prog="bottomtime")
-    parser.add_argument("--db", default="data/dives.db", help="path to the dive store")
-    parser.add_argument(
-        "--archive", default="archive", help="directory for verbatim raw source copies"
-    )
-    sub = parser.add_subparsers(dest="command", required=True)
-
-    sub.add_parser("init", help="create an empty dive store")
-
-    p_ingest = sub.add_parser("ingest", help="ingest a data source")
-    ingest_sub = p_ingest.add_subparsers(dest="source", required=True)
-    p_garmin = ingest_sub.add_parser("garmin", help="a directory of FIT files")
-    p_garmin.add_argument("fit_dir", type=Path)
-    p_garmin.add_argument(
-        "--index",
-        default="dives_index.json",
-        help="Garmin Connect index JSON filename inside fit-dir",
-    )
-    p_sw = ingest_sub.add_parser("shearwater", help="a Shearwater Cloud dive_data.db")
-    p_sw.add_argument("db_path", type=Path)
-
-    sub.add_parser("match", help="match dual-computer dives, build canonical dives")
-
-    p_verify = sub.add_parser("verify", help="run the verification suite")
-    p_verify.add_argument("--xml-dir", type=Path, default=None,
-                          help="directory of Shearwater XML exports to cross-check")
-
-    sub.add_parser("status", help="summarize the store")
-
-    args = parser.parse_args(argv)
-    con = store_db.connect(args.db)
-    archive_dir = Path(args.archive)
-
-    if args.command == "init":
-        print(f"initialized {args.db}")
-        return 0
-
-    if args.command == "ingest" and args.source == "garmin":
-        from .ingest.garmin_fit import ingest_garmin_dir
-
-        stats = ingest_garmin_dir(con, archive_dir, args.fit_dir, args.index)
-        print(f"garmin: {stats}")
-        return 1 if stats["failed"] else 0
-
-    if args.command == "ingest" and args.source == "shearwater":
-        from .ingest.shearwater_db import ingest_shearwater_db
-
-        stats = ingest_shearwater_db(con, archive_dir, args.db_path)
-        print(f"shearwater: {stats}")
-        return 1 if stats["failed"] else 0
-
-    if args.command == "match":
-        from .match.matcher import run_match
-
-        stats = run_match(con)
-        print(f"match: {stats}")
-        return 0
-
-    if args.command == "verify":
-        from .verify.crosscheck import run_verify
-
-        return run_verify(con, args.xml_dir)
-
-    if args.command == "status":
-        for line in con.execute(
-            "SELECT source || ' source dives: ' || count(*) FROM source_dives GROUP BY source"
-        ):
-            print(line[0])
-        for line in con.execute(
-            "SELECT 'canonical dives: ' || count(*) || ' (' ||"
-            " sum(CASE WHEN is_test THEN 1 ELSE 0 END) || ' test)' FROM dives"
-        ):
-            print(line[0])
-        for line in con.execute(
-            "SELECT 'matched pairs: ' || count(*) FROM matches WHERE status IN ('auto','confirmed')"
-        ):
-            print(line[0])
-        return 0
-
-    return 2
-
-
-if __name__ == "__main__":
-    sys.exit(main())