kodokan 0.0.2__tar.gz

kodokan-0.0.2/.gitattributes

@@ -0,0 +1 @@
+*.ipynb linguist-documentation

kodokan-0.0.2/.github/workflows/ci.yml

@@ -0,0 +1,48 @@
+# wads CI — calls the reusable workflow hosted in i2mint/wads.
+#
+# All configuration comes from this repo's pyproject.toml [tool.wads.ci.*].
+# To customize the workflow itself (rare), replace this file with the
+# full inline template `wads/data/github_ci_uv.yml` from i2mint/wads.
+#
+# Pinning: `@master` floats with wads. If you need version stability for
+# a release-sensitive repo, change `@master` to a wads tag (e.g. `@v0.1.81`).
+# CI failure does not block a published release — it blocks the publish
+# step itself — so floating master is generally safe.
+#
+# Permissions: GitHub validates that the caller grants AT LEAST the
+# permissions any job in the called workflow requests — at workflow-parse
+# time, not at run-time, even if the job would be skipped via `if:`.
+# The reusable workflow needs:
+#   contents: write   for the publish job's version-bump push-back
+#                     and for the github-pages job's gh-pages branch push
+#   pages: write      for the github-pages job's REST API Pages config
+# Both default to `write` on org-account GITHUB_TOKEN and need to be
+# granted explicitly on personal-account callers (where the default is
+# read-only). No `id-token: write` needed — the publish-github-pages
+# action uses peaceiris/actions-gh-pages (branch-based) + REST API,
+# not the OIDC `actions/deploy-pages` flow.
+name: Continuous Integration
+on: [push, pull_request]
+jobs:
+  ci:
+    uses: i2mint/wads/.github/workflows/uv-ci.yml@master
+    permissions:
+      contents: write
+      pages: write
+    # Explicit pass-through (not `secrets: inherit`) because `inherit` does
+    # not reliably propagate caller-repo secrets to a reusable workflow owned
+    # by a different account (verified empirically: personal-account caller +
+    # i2mint-org workflow → `${{ secrets.PYPI_PASSWORD }}` resolved to empty).
+    #
+    # This list is the per-repo *transport*: it should contain PYPI_PASSWORD
+    # (for publishing) plus every secret your tests/CI need. It is generated
+    # from [tool.wads.ci.env] in pyproject.toml. To add one, run
+    #   wads-secrets add VAR_NAME            # updates pyproject + this block
+    # or just append a line below. *Which* of these become job env vars (and
+    # which are required) is controlled by [tool.wads.ci.env] — passing a
+    # secret here does not by itself put it in the environment.
+    #
+    # A secret name must also be declared in the reusable workflow's superset
+    # (wads/ci_secrets.py). `wads-secrets add` warns if it is not.
+    secrets:
+      PYPI_PASSWORD: ${{ secrets.PYPI_PASSWORD }}

kodokan-0.0.2/.gitignore

@@ -0,0 +1,128 @@
+.claude/handoffs/
+.claude/scratch/
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+
+.DS_Store
+# C extensions
+*.so
+
+# TLS certificates
+## Ignore all PEM files anywhere
+*.pem
+## Also ignore any certs directory
+certs/
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+_build
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+docs/*
+
+# PyBuilder
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# pyenv
+.python-version
+
+# celery beat schedule file
+celerybeat-schedule
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+
+# PyCharm
+.idea
+
+# ML model weights (auto-downloaded by ultralytics/rtmlib)
+*.pt
+*.onnx
+
+# kodokan data artifacts (videos/keypoints/renders live outside the repo by default)
+/data/
+kodokan_data/

kodokan-0.0.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Thor Whalen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

kodokan-0.0.2/PKG-INFO

@@ -0,0 +1,170 @@
+Metadata-Version: 2.4
+Name: kodokan
+Version: 0.0.2
+Summary: Study Kodokan Judo throws from video via body-pose analysis
+Project-URL: Homepage, https://github.com/thorwhalen/kodokan
+Project-URL: Repository, https://github.com/thorwhalen/kodokan
+Project-URL: Documentation, https://thorwhalen.github.io/kodokan
+Author: Thor Whalen
+License: mit
+License-File: LICENSE
+Keywords: action-segmentation,judo,mediapipe,pose-estimation,video-analysis
+Requires-Python: >=3.10
+Requires-Dist: numpy
+Provides-Extra: acquire
+Requires-Dist: yb; extra == 'acquire'
+Provides-Extra: all
+Requires-Dist: dol; extra == 'all'
+Requires-Dist: dtaidistance; extra == 'all'
+Requires-Dist: matplotlib; extra == 'all'
+Requires-Dist: onnxruntime; extra == 'all'
+Requires-Dist: opencv-python; extra == 'all'
+Requires-Dist: pandas; extra == 'all'
+Requires-Dist: pyarrow; extra == 'all'
+Requires-Dist: rerun-sdk; extra == 'all'
+Requires-Dist: rtmlib; extra == 'all'
+Requires-Dist: scipy; extra == 'all'
+Requires-Dist: supervision; extra == 'all'
+Requires-Dist: ultralytics; extra == 'all'
+Requires-Dist: yb; extra == 'all'
+Provides-Extra: analysis
+Requires-Dist: dtaidistance; extra == 'analysis'
+Requires-Dist: pandas; extra == 'analysis'
+Requires-Dist: pyarrow; extra == 'analysis'
+Requires-Dist: scipy; extra == 'analysis'
+Provides-Extra: dev
+Requires-Dist: pytest-cov>=4.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: sphinx-rtd-theme>=1.0; extra == 'docs'
+Requires-Dist: sphinx>=6.0; extra == 'docs'
+Provides-Extra: pose
+Requires-Dist: onnxruntime; extra == 'pose'
+Requires-Dist: rtmlib; extra == 'pose'
+Requires-Dist: ultralytics; extra == 'pose'
+Provides-Extra: storage
+Requires-Dist: dol; extra == 'storage'
+Provides-Extra: viz
+Requires-Dist: matplotlib; extra == 'viz'
+Requires-Dist: opencv-python; extra == 'viz'
+Requires-Dist: rerun-sdk; extra == 'viz'
+Requires-Dist: supervision; extra == 'viz'
+Description-Content-Type: text/markdown
+
+# kodokan
+
+Study Kodokan Judo throws from video via body-pose analysis: download technique
+demonstrations, extract two-person (tori/uke) skeletons, split each clip into its
+repeated demonstrations, visualize them, and compare/score demonstrations.
+
+```python
+from kodokan.acquire import download_techniques
+from kodokan.track import estimate_poses_tracked
+from kodokan.segment import segment_demonstrations
+from kodokan.viz import render_skeleton_video
+
+res = download_techniques(playlist_items="2")[0]          # Seoi-nage (#002), with metadata
+seq = estimate_poses_tracked(res.path, source_url=res.info["webpage_url"])  # tracked tori/uke COCO-17
+demos = segment_demonstrations(seq, min_two_person_frac=0.3)                # per-demo (start_s, end_s)
+render_skeleton_video(seq, out_path="overlay.mp4", source_video=res.path)  # skeletons on the video
+render_skeleton_video(seq, out_path="skeleton.mp4", blank_canvas=True)      # skeletons on blank canvas
+```
+
+## What it does
+
+A functional pipeline over the official *Kodokan 100 Techniques* YouTube playlist:
+
+```
+acquire (yb) ─► pose (rtmlib / YOLO, tracked tori/uke) ─► segment (motion-energy)
+       └─► dol stores (Parquet pose + JSON segments) ─► visualize (overlay / blank / Rerun)
+       └─► compare two demos (joint-angle DTW) ─► score + eval harness
+```
+
+YouTube acquisition lives in the [`yb`](https://github.com/thorwhalen/yb) package
+(`download_youtube_playlist`); `kodokan` is the analysis layer on top.
+
+## Install
+
+`import kodokan` needs only **numpy**; everything heavy is an optional extra (imported
+lazily on first use), so the import never fails for a missing one:
+
+```bash
+pip install -e '.[all]'      # or pick extras: .[pose,viz,analysis,storage,acquire]
+```
+
+| extra | for | brings |
+|---|---|---|
+| `pose` | pose estimation | rtmlib, onnxruntime, ultralytics |
+| `viz` | rendering | opencv-python, rerun-sdk, supervision, matplotlib |
+| `analysis` | segment / compare / score | scipy, dtaidistance, pandas, pyarrow |
+| `storage` | dol stores | dol |
+| `acquire` | YouTube download | yb |
+
+You also need **ffmpeg** on PATH (acquisition/merge). The optional **3D lift**
+(`scripts/lift_3d_mediapipe.py`) runs in a **separate venv**, because MediaPipe is
+ABI-incompatible with numpy 2.x:
+
+```bash
+python -m venv ~/.kodokan_mp
+~/.kodokan_mp/bin/pip install 'mediapipe==0.10.18' 'numpy<2' 'opencv-python-headless==4.10.0.84'
+```
+
+Data (videos, keypoints, renders, weights) lives **outside the repo** under
+`~/kodokan_data` (override with `KODOKAN_DATA_DIR`).
+
+## The pipeline
+
+| module | purpose |
+|---|---|
+| `kodokan.acquire` | download techniques (wraps `yb`), skip the PV, keep source URLs |
+| `kodokan.pose` | `estimate_poses` facade (rtmlib / ultralytics backends), COCO-17, `PoseSequence` |
+| `kodokan.track` | `estimate_poses_tracked` — stable tori/uke identity (BoT-SORT + spatial continuity) |
+| `kodokan.segment` | hysteresis motion-energy segmentation + two-person gate + self-similarity |
+| `kodokan.store` | `pose_store` (tidy Parquet) / `segments_store` (JSON), the analysis SSOT |
+| `kodokan.viz` | overlay / blank-canvas MP4 + Rerun logging |
+| `kodokan.compare` | joint-angle (soft-)DTW comparison of two demonstrations |
+| `kodokan.score` | reference-based 0–100 scoring + per-joint/per-phase feedback |
+| `kodokan.descriptors` | experimental feature descriptors (for the eval harness) |
+
+Runnable end-to-end examples live in `examples/` (`warmup_seoinage.py`,
+`batch_pipeline.py`, `segment_review.py`, `compare_demos.py`, `score_demos.py`,
+`eval_features.py`).
+
+## Dataset
+
+`examples/batch_pipeline.py` builds a small dataset (10 techniques · 84
+demonstrations · 18.3k frames) into the `dol` stores. Load it:
+
+```python
+from kodokan.store import pose_store, segments_store, load_all_tidy
+seq = pose_store()["zIq0xI0ogxk"]          # (F, 2, 17, 3) COCO-17 (x, y, conf)
+demos = segments_store()["zIq0xI0ogxk"]    # demo intervals + source_url
+df = load_all_tidy()                       # tidy DataFrame across all clips
+```
+
+See [`misc/docs/dataset.md`](misc/docs/dataset.md).
+
+## Status & honest limits
+
+Works well: acquisition, tracked two-person pose, demo segmentation, the dol stores,
+visualization, and same-technique demo comparison (joint-angle DTW is speed-invariant)
+with interpretable per-joint/per-phase feedback.
+
+Does **not** work yet — and this is *measured, not assumed*: **technique recognition /
+cross-demo scoring**. A feature bake-off ([`misc/docs/feature-bakeoff.md`](misc/docs/feature-bakeoff.md))
+shows every 2D descriptor *and* MediaPipe 3D joint angles sit at chance (separation
+AUC ≈ 0.49–0.56). The blockers are noisy monocular 3D under grappling occlusion,
+tori/uke role inconsistency, and the weakness of hand-crafted angle-DTW for few
+examples — not viewpoint alone. Recognition needs a **learned** skeleton representation
+(few-shot JEANIE, or trained PoseC3D/CTR-GCN) and/or cleaner multi-person 3D with
+role-consistent features. The eval harness (`examples/eval_features*.py`) is ready to
+validate those.
+
+## Background & rationale
+
+- [`misc/docs/research-architecture.md`](misc/docs/research-architecture.md) — cited
+  tools/architecture research (75 refs).
+- [`misc/docs/dataset.md`](misc/docs/dataset.md) — dataset card.
+- [`misc/docs/feature-bakeoff.md`](misc/docs/feature-bakeoff.md) — why hand-crafted
+  features don't discriminate techniques (the empirical finding).

kodokan-0.0.2/README.md

@@ -0,0 +1,116 @@
+# kodokan
+
+Study Kodokan Judo throws from video via body-pose analysis: download technique
+demonstrations, extract two-person (tori/uke) skeletons, split each clip into its
+repeated demonstrations, visualize them, and compare/score demonstrations.
+
+```python
+from kodokan.acquire import download_techniques
+from kodokan.track import estimate_poses_tracked
+from kodokan.segment import segment_demonstrations
+from kodokan.viz import render_skeleton_video
+
+res = download_techniques(playlist_items="2")[0]          # Seoi-nage (#002), with metadata
+seq = estimate_poses_tracked(res.path, source_url=res.info["webpage_url"])  # tracked tori/uke COCO-17
+demos = segment_demonstrations(seq, min_two_person_frac=0.3)                # per-demo (start_s, end_s)
+render_skeleton_video(seq, out_path="overlay.mp4", source_video=res.path)  # skeletons on the video
+render_skeleton_video(seq, out_path="skeleton.mp4", blank_canvas=True)      # skeletons on blank canvas
+```
+
+## What it does
+
+A functional pipeline over the official *Kodokan 100 Techniques* YouTube playlist:
+
+```
+acquire (yb) ─► pose (rtmlib / YOLO, tracked tori/uke) ─► segment (motion-energy)
+       └─► dol stores (Parquet pose + JSON segments) ─► visualize (overlay / blank / Rerun)
+       └─► compare two demos (joint-angle DTW) ─► score + eval harness
+```
+
+YouTube acquisition lives in the [`yb`](https://github.com/thorwhalen/yb) package
+(`download_youtube_playlist`); `kodokan` is the analysis layer on top.
+
+## Install
+
+`import kodokan` needs only **numpy**; everything heavy is an optional extra (imported
+lazily on first use), so the import never fails for a missing one:
+
+```bash
+pip install -e '.[all]'      # or pick extras: .[pose,viz,analysis,storage,acquire]
+```
+
+| extra | for | brings |
+|---|---|---|
+| `pose` | pose estimation | rtmlib, onnxruntime, ultralytics |
+| `viz` | rendering | opencv-python, rerun-sdk, supervision, matplotlib |
+| `analysis` | segment / compare / score | scipy, dtaidistance, pandas, pyarrow |
+| `storage` | dol stores | dol |
+| `acquire` | YouTube download | yb |
+
+You also need **ffmpeg** on PATH (acquisition/merge). The optional **3D lift**
+(`scripts/lift_3d_mediapipe.py`) runs in a **separate venv**, because MediaPipe is
+ABI-incompatible with numpy 2.x:
+
+```bash
+python -m venv ~/.kodokan_mp
+~/.kodokan_mp/bin/pip install 'mediapipe==0.10.18' 'numpy<2' 'opencv-python-headless==4.10.0.84'
+```
+
+Data (videos, keypoints, renders, weights) lives **outside the repo** under
+`~/kodokan_data` (override with `KODOKAN_DATA_DIR`).
+
+## The pipeline
+
+| module | purpose |
+|---|---|
+| `kodokan.acquire` | download techniques (wraps `yb`), skip the PV, keep source URLs |
+| `kodokan.pose` | `estimate_poses` facade (rtmlib / ultralytics backends), COCO-17, `PoseSequence` |
+| `kodokan.track` | `estimate_poses_tracked` — stable tori/uke identity (BoT-SORT + spatial continuity) |
+| `kodokan.segment` | hysteresis motion-energy segmentation + two-person gate + self-similarity |
+| `kodokan.store` | `pose_store` (tidy Parquet) / `segments_store` (JSON), the analysis SSOT |
+| `kodokan.viz` | overlay / blank-canvas MP4 + Rerun logging |
+| `kodokan.compare` | joint-angle (soft-)DTW comparison of two demonstrations |
+| `kodokan.score` | reference-based 0–100 scoring + per-joint/per-phase feedback |
+| `kodokan.descriptors` | experimental feature descriptors (for the eval harness) |
+
+Runnable end-to-end examples live in `examples/` (`warmup_seoinage.py`,
+`batch_pipeline.py`, `segment_review.py`, `compare_demos.py`, `score_demos.py`,
+`eval_features.py`).
+
+## Dataset
+
+`examples/batch_pipeline.py` builds a small dataset (10 techniques · 84
+demonstrations · 18.3k frames) into the `dol` stores. Load it:
+
+```python
+from kodokan.store import pose_store, segments_store, load_all_tidy
+seq = pose_store()["zIq0xI0ogxk"]          # (F, 2, 17, 3) COCO-17 (x, y, conf)
+demos = segments_store()["zIq0xI0ogxk"]    # demo intervals + source_url
+df = load_all_tidy()                       # tidy DataFrame across all clips
+```
+
+See [`misc/docs/dataset.md`](misc/docs/dataset.md).
+
+## Status & honest limits
+
+Works well: acquisition, tracked two-person pose, demo segmentation, the dol stores,
+visualization, and same-technique demo comparison (joint-angle DTW is speed-invariant)
+with interpretable per-joint/per-phase feedback.
+
+Does **not** work yet — and this is *measured, not assumed*: **technique recognition /
+cross-demo scoring**. A feature bake-off ([`misc/docs/feature-bakeoff.md`](misc/docs/feature-bakeoff.md))
+shows every 2D descriptor *and* MediaPipe 3D joint angles sit at chance (separation
+AUC ≈ 0.49–0.56). The blockers are noisy monocular 3D under grappling occlusion,
+tori/uke role inconsistency, and the weakness of hand-crafted angle-DTW for few
+examples — not viewpoint alone. Recognition needs a **learned** skeleton representation
+(few-shot JEANIE, or trained PoseC3D/CTR-GCN) and/or cleaner multi-person 3D with
+role-consistent features. The eval harness (`examples/eval_features*.py`) is ready to
+validate those.
+
+## Background & rationale
+
+- [`misc/docs/research-architecture.md`](misc/docs/research-architecture.md) — cited
+  tools/architecture research (75 refs).
+- [`misc/docs/dataset.md`](misc/docs/dataset.md) — dataset card.
+- [`misc/docs/feature-bakeoff.md`](misc/docs/feature-bakeoff.md) — why hand-crafted
+  features don't discriminate techniques (the empirical finding).

kodokan-0.0.2/examples/batch_pipeline.py

@@ -0,0 +1,78 @@
+"""Batch the pipeline over several techniques into the dol stores.
+
+Downloads a range of playlist techniques (idempotent via a yt-dlp download
+archive), then for each clip runs tracked two-person pose and demo segmentation,
+writing results to the Parquet pose store and JSON segments store. Prints a
+summary table.
+
+Usage::
+    PYTHONPATH=<repo> python examples/batch_pipeline.py --items 2:11
+"""
+
+import argparse
+from pathlib import Path
+
+import numpy as np
+
+from kodokan import config, store
+from kodokan.acquire import download_techniques, local_clips
+from kodokan.segment import segment_demonstrations
+from kodokan.track import estimate_poses_tracked
+
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--items", default="2:11", help="yt-dlp 1-based playlist selector (#002-#011)")
+    ap.add_argument("--frame-step", type=int, default=1)
+    ap.add_argument("--device", default="mps")
+    args = ap.parse_args()
+
+    archive = config.clips_dir() / ".download_archive.txt"
+    print(f"[acquire] playlist items {args.items} (archive: {archive.name}) ...", flush=True)
+    download_techniques(playlist_items=args.items, download_archive=str(archive))
+    clips = local_clips()  # process whatever is on disk (robust to archive skips)
+    print(f"[acquire] {len(clips)} clips on disk", flush=True)
+
+    ps = store.pose_store()
+    ss = store.segments_store()
+    summary = []
+
+    for c in clips:
+        vid, title, url, path = c["id"], c["title"], c["webpage_url"], c["path"]
+        if not path or not Path(path).exists():
+            print(f"[skip] {vid} {title!r}: file missing", flush=True)
+            continue
+        print(f"\n=== {vid}  {title} ===", flush=True)
+        seq = estimate_poses_tracked(
+            path, frame_step=args.frame_step, device=args.device, source_url=url, progress=True
+        )
+        ps[vid] = seq
+        segs = segment_demonstrations(
+            seq, smooth_sigma=5, low_quantile=0.25, high_quantile=0.5,
+            min_duration_s=1.5, merge_gap_s=0.6, min_two_person_frac=0.3,
+        )
+        ss[vid] = {
+            "video_id": vid,
+            "technique": title,
+            "source_url": url,
+            "fps": seq.fps,
+            "n_demos": len(segs),
+            "demos": [
+                dict(index=s.index, start_s=s.start_s, end_s=s.end_s, duration_s=round(s.duration_s, 2))
+                for s in segs
+            ],
+        }
+        present = ~np.all(np.isnan(seq.keypoints[..., 0]), axis=2)
+        both = f"{(present.sum(1) == 2).mean():.0%}"
+        summary.append((vid, title, seq.n_frames, both, len(segs)))
+        print(f"  stored {seq.keypoints.shape}  both-present={both}  demos={len(segs)}", flush=True)
+
+    print("\n=== SUMMARY ===", flush=True)
+    print(f"{'video_id':12} {'frames':>6} {'2p%':>4} {'demos':>5}  technique", flush=True)
+    for vid, title, nf, p2, nd in summary:
+        print(f"{vid:12} {nf:>6} {p2:>4} {nd:>5}  {title}", flush=True)
+    print(f"\npose_store: {len(ps)} clips | segments_store: {len(ss)} clips", flush=True)
+
+
+if __name__ == "__main__":
+    main()

kodokan-0.0.2/examples/compare_demos.py

@@ -0,0 +1,97 @@
+"""Stage 1 demo: compare demonstrations of Seoi-nage via joint-angle DTW.
+
+Loads the full pose sequence + detected demo segments, then:
+  1. proves DTW speed-invariance (a demo vs a 1.5x time-stretched copy of itself),
+  2. builds a demo x demo normalized-DTW distance matrix (heatmap PNG),
+  3. plots per-angle deviation for a chosen pair (PNG).
+
+Usage::
+    PYTHONPATH=<repo> python examples/compare_demos.py
+"""
+
+import json
+
+import matplotlib
+
+matplotlib.use("Agg")
+import matplotlib.pyplot as plt
+import numpy as np
+
+from kodokan import config
+from kodokan.compare import (
+    ANGLE_NAMES,
+    _clean,
+    angle_features,
+    compare,
+    distance_matrix,
+    per_angle_deviation,
+    primary_person,
+    time_stretch,
+)
+from kodokan.pose import PoseSequence
+
+
+def main():
+    seq = PoseSequence.load_npz(config.pose_dir() / "seoi-nage_ultralytics_full.npz")
+    segs = json.loads((config.pose_dir() / "seoi-nage_segments.json").read_text())["demos"]
+
+    # angle features per demo (primary person within the demo window)
+    feats, labels = [], []
+    for d in segs:
+        fr = (d["start_frame"], d["end_frame"])
+        person = primary_person(seq, frame_range=fr)
+        f = _clean(angle_features(seq, person=person, frame_range=fr))
+        feats.append(f)
+        labels.append(f"{d['start_s']:.0f}-{d['end_s']:.0f}s")
+        print(f"demo {d['index']:2d} {labels[-1]:>10}  person{person}  clean_frames={len(f)}")
+
+    # --- 1) speed-invariance: demo vs 1.5x time-stretched self, vs a different demo ---
+    # choose two reasonably long clean demos
+    long_idx = sorted(range(len(feats)), key=lambda i: -len(feats[i]))[:2]
+    i, j = long_idx[0], long_idx[1]
+    self_d = compare(feats[i], feats[i])["normalized"]
+    stretch_d = compare(feats[i], time_stretch(feats[i], 1.5))["normalized"]
+    cross_d = compare(feats[i], feats[j])["normalized"]
+    print("\n--- DTW speed-invariance check (normalized distance) ---")
+    print(f"  demo {labels[i]} vs itself          : {self_d:.4f}")
+    print(f"  demo {labels[i]} vs 1.5x-stretched   : {stretch_d:.4f}   (should stay ~as low as self)")
+    print(f"  demo {labels[i]} vs demo {labels[j]} : {cross_d:.4f}   (a genuinely different rep)")
+
+    # --- 2) distance matrix heatmap ---
+    D = distance_matrix(feats)
+    fig, ax = plt.subplots(figsize=(7, 6))
+    im = ax.imshow(D, cmap="viridis")
+    ax.set_xticks(range(len(labels)), labels, rotation=60, ha="right", fontsize=8)
+    ax.set_yticks(range(len(labels)), labels, fontsize=8)
+    ax.set_title("Seoi-nage demos — pairwise normalized-DTW distance\n(joint-angle features; darker = more similar)")
+    fig.colorbar(im, ax=ax, shrink=0.8, label="DTW distance / step (rad)")
+    fig.tight_layout()
+    p1 = config.viz_dir() / "seoi-nage_demo_distance_matrix.png"
+    fig.savefig(p1, dpi=130)
+    print("\nsaved", p1.name)
+
+    # --- 3) per-angle deviation for the (i, j) pair ---
+    res = compare(feats[i], feats[j])
+    dev = np.degrees(per_angle_deviation(res))  # to degrees for readability
+    fig, (axA, axB) = plt.subplots(2, 1, figsize=(8, 7))
+    # representative angle (right elbow) along the DTW alignment
+    a, b, path = res["a"], res["b"], res["path"]
+    re = ANGLE_NAMES.index("r_elbow")
+    axA.plot(np.degrees([a[p][re] for p, _ in path]), label=f"demo {labels[i]}")
+    axA.plot(np.degrees([b[q][re] for _, q in path]), label=f"demo {labels[j]}")
+    axA.set_title("Right-elbow angle along the DTW alignment")
+    axA.set_xlabel("aligned step")
+    axA.set_ylabel("angle (deg)")
+    axA.legend(fontsize=8)
+    axB.bar(ANGLE_NAMES, dev, color="#c0392b")
+    axB.set_title(f"Mean per-joint-angle deviation: demo {labels[i]} vs {labels[j]}")
+    axB.set_ylabel("deg")
+    axB.tick_params(axis="x", rotation=45)
+    fig.tight_layout()
+    p2 = config.viz_dir() / "seoi-nage_demo_pair_deviation.png"
+    fig.savefig(p2, dpi=130)
+    print("saved", p2.name)
+
+
+if __name__ == "__main__":
+    main()