Skip to content

Free Motion Capture for Everyone πŸ’€βœ¨

TypeScript

fix versions and stuff, hopefully

jonmatthis8d27c626bf4d
diff --git a/.github/workflows/build-installers-pyinstaller.yml b/.github/workflows/build-installers-pyinstaller.yml
index 447aaa68..26bb3c1e 100644
--- a/.github/workflows/build-installers-pyinstaller.yml
+++ b/.github/workflows/build-installers-pyinstaller.yml
@@ -41,15 +41,17 @@ jobs:
label: windows-x64-cpu
server-binary: freemocap_server.exe
electron-arch: x64
-
- - os: macos-15-intel
- platform: macos
- arch: x64
- variant: cpu
- label: macos-x64-intel
- server-binary: freemocap_server
- electron-arch: x64
-
+#
+# # macOS is Apple-Silicon only: onnxruntime (pulled via skellytracker) ships
+# # no macOS x86_64 wheels, so an Intel-Mac build can't resolve its ML backend.
+# - os: macos-15-intel
+# platform: macos
+# arch: x64
+# variant: cpu
+# label: macos-x64-intel
+# server-binary: freemocap_server
+# electron-arch: x64
+#
- os: macos-latest
platform: macos
arch: arm64
@@ -416,16 +418,7 @@ jobs:
include-hidden-files: true
- name: Upload auto-update metadata (macOS)
- if: matrix.platform == 'macos' && matrix.arch == 'x64'
- uses: actions/upload-artifact@v7
- with:
- name: update-metadata-${{ matrix.label }}
- path: |
- freemocap-ui/release/**/latest-mac.yml
- include-hidden-files: true
-
- - name: Upload auto-update metadata (macOS ARM)
- if: matrix.platform == 'macos' && matrix.arch == 'arm64'
+ if: matrix.platform == 'macos'
uses: actions/upload-artifact@v7
with:
name: update-metadata-${{ matrix.label }}
@@ -484,7 +477,7 @@ jobs:
# ── Server binaries ──
# Artifact directories are named server-<label>, e.g.:
- # server-windows-x64-cuda, server-windows-x64-cpu, server-macos-x64-intel,
+ # server-windows-x64-cuda, server-windows-x64-cpu,
# server-macos-arm64-apple-silicon, server-linux-x64-cuda,
# server-linux-x64-cpu
# Strip the "server-" prefix to get the human-readable suffix.
@@ -509,7 +502,7 @@ jobs:
# ── App installers ──
# Artifact directories are named installer-<label>, e.g.:
# installer-windows-x64-cuda, installer-windows-x64-cpu,
- # installer-macos-x64-intel, etc.
+ # installer-macos-arm64-apple-silicon, etc.
# Electron-builder names only contain the arch (x64/arm64),
# so we rename each file to: freemocap_<VERSION>_<label>.<ext>
for dir in artifacts/installer-*; do
@@ -542,25 +535,21 @@ jobs:
if [ -d "artifacts/update-metadata-windows-x64-cuda" ]; then
YML=$(find artifacts/update-metadata-windows-x64-cuda -name 'latest.yml' | head -1)
if [ -n "$YML" ]; then
- # Replace the original artifact filename with the renamed one
- sed -i "s|freemocap_.*_installer\.exe|freemocap_${VERSION}_windows-x64-cuda.exe|g" "$YML"
+ # Replace electron-builder's FreeMoCap_<ver>_<arch>_installer.exe
+ # reference with the renamed asset. The prefix is case-tolerant
+ # because electron uses the "FreeMoCap" productName casing.
+ sed -i "s|[Ff]ree[Mm]o[Cc]ap_.*_installer\.exe|freemocap_${VERSION}_windows-x64-cuda.exe|g" "$YML"
cp "$YML" "release-assets/latest.yml"
echo "Copied latest.yml for Windows"
fi
fi
- # macOS: latest-mac.yml (combine x64 and arm64 entries)
- # electron-updater picks the right arch from a single latest-mac.yml
- MAC_YML=""
- for dir in artifacts/update-metadata-macos-*; do
- found=$(find "$dir" -name 'latest-mac.yml' 2>/dev/null | head -1)
- if [ -n "$found" ] && [ -z "$MAC_YML" ]; then
- MAC_YML="$found"
- fi
- done
+ # macOS: latest-mac.yml (Apple Silicon only β€” see the build matrix)
+ MAC_YML=$(find artifacts/update-metadata-macos-arm64-apple-silicon -name 'latest-mac.yml' 2>/dev/null | head -1)
if [ -n "$MAC_YML" ]; then
- # Patch filenames to match renamed assets
- sed -i "s|freemocap_.*_installer\.zip|freemocap_${VERSION}_macos-x64-intel.zip|g" "$MAC_YML"
+ # Patch electron-builder's FreeMoCap_<ver>_<arch>_installer.zip reference
+ # to the renamed release asset (case-tolerant prefix).
+ sed -i "s|[Ff]ree[Mm]o[Cc]ap_.*_installer\.zip|freemocap_${VERSION}_macos-arm64-apple-silicon.zip|g" "$MAC_YML"
cp "$MAC_YML" "release-assets/latest-mac.yml"
echo "Copied latest-mac.yml for macOS"
fi
@@ -569,7 +558,7 @@ jobs:
if [ -d "artifacts/update-metadata-linux-x64-cuda" ]; then
YML=$(find artifacts/update-metadata-linux-x64-cuda -name 'latest-linux.yml' | head -1)
if [ -n "$YML" ]; then
- sed -i "s|freemocap_.*\.AppImage|freemocap_${VERSION}_linux-x64-cuda.AppImage|g" "$YML"
+ sed -i "s|[Ff]ree[Mm]o[Cc]ap_.*\.AppImage|freemocap_${VERSION}_linux-x64-cuda.AppImage|g" "$YML"
cp "$YML" "release-assets/latest-linux.yml"
echo "Copied latest-linux.yml for Linux"
fi
diff --git a/docs/superpowers/plans/2026-06-22-charuco-observation-cache.md b/docs/superpowers/plans/2026-06-22-charuco-observation-cache.md
deleted file mode 100644
index 1c759637..00000000
--- a/docs/superpowers/plans/2026-06-22-charuco-observation-cache.md
+++ /dev/null
@@ -1,1577 +0,0 @@
-# Charuco Observation Cache Implementation Plan
-
-> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
-
-**Goal:** Capture Charuco observations from the realtime pipeline during calibration recordings and replay them in posthoc VideoNodes to skip redundant OpenCV detection.
-
-**Architecture:** A new `CharucoRecorderNode` (SourceNode subclass) subscribes to `CameraNodeOutputTopic` and a new `CalibrationRecordingStateTopic`. During the recording window it buffers full `CharucoObservation` objects per (camera_id, frame_number). On recording stop it pickles them to `{recording_path}/output_data/charuco_observations_realtime.pkl`. The `VideoNode._run()` main loop β€” whose sequential `video_reader.read()` structure never changes β€” checks the cache before calling `detector.detect()`.
-
-**Tech Stack:** Python multiprocessing, pickle, OpenCV (unchanged), existing pubsub system, existing test infrastructure (MockCameraGroup + drive_realtime_lockstep + freemocap_test_data).
-
-## Global Constraints
-
-- VideoNode's `video_reader.read()` loop is NEVER altered β€” cache only gates `detector.detect()`
-- Every frame gets a `VideoNodeOutputMessage` published β€” frame sequencing is sacrosanct
-- Cache miss β†’ silent fallback to normal detection path
-- Board config mismatch β†’ cache rejected (validated on load)
-- Pickle format for full CharucoObservation round-trip fidelity
-
----
-
-### Task 1: CalibrationRecordingStateMessage + Topic
-
-**Files:**
-- Modify: `freemocap/pubsub/pubsub_topics.py` β€” add message + topic after the RecordingState section
-- Test: `freemocap/tests/pubsub/test_calibration_recording_state_topic.py` (new)
-
-**Interfaces:**
-- Produces: `CalibrationRecordingStateMessage(recording_info: RecordingInfo, is_active: bool)` β€” published by calibration router, consumed by CharucoRecorderNode
-- Produces: `CalibrationRecordingStateTopic = create_topic(CalibrationRecordingStateMessage)` β€” auto-registered via `__init_subclass__`
-
-- [ ] **Step 1: Write the failing test**
-
-```python
-# freemocap/tests/pubsub/test_calibration_recording_state_topic.py
-import pickle
-from skellycam.core.recorders.videos.recording_info import RecordingInfo
-from freemocap.pubsub.pubsub_topics import (
- CalibrationRecordingStateMessage,
- CalibrationRecordingStateTopic,
-)
-from freemocap.pubsub.pubsub_abcs import PubSubTopicABC
-
-
-def test_message_roundtrip():
- """CalibrationRecordingStateMessage survives pickle roundtrip."""
- info = RecordingInfo.create_temp()
- msg = CalibrationRecordingStateMessage(recording_info=info, is_active=True)
-
- reloaded = pickle.loads(pickle.dumps(msg))
-
- assert reloaded.recording_info.recording_name == info.recording_name
- assert reloaded.is_active is True
-
-
-def test_message_defaults():
- """Default values are sensible."""
- msg = CalibrationRecordingStateMessage()
-
- assert msg.is_active is False
-
-
-def test_topic_is_registered():
- """CalibrationRecordingStateTopic is auto-discovered."""
- registered = PubSubTopicABC.get_registered_topics()
- assert CalibrationRecordingStateTopic in registered
-
-
-def test_topic_message_type():
- """Topic wraps the correct message type."""
- assert CalibrationRecordingStateTopic.message_type is CalibrationRecordingStateMessage
-```
-
-- [ ] **Step 2: Run test to verify it fails**
-
-Run: `uv run pytest freemocap/tests/pubsub/test_calibration_recording_state_topic.py -v`
-Expected: FAIL β€” `ImportError` or `NameError` for `CalibrationRecordingStateMessage`
-
-- [ ] **Step 3: Write minimal implementation**
-
-In `freemocap/pubsub/pubsub_topics.py`, add after the `SkeletonFitterResetMessage` section (before the topic instantiation block, around line 216):
-
-```python
-# ---------------------------------------------------------------------------
-# Calibration recording state (bridge between HTTP endpoint and pipeline nodes)
-# ---------------------------------------------------------------------------
-# Published by the calibration HTTP endpoint when a calibration recording
-# starts or stops. The CharucoRecorderNode subscribes to toggle buffering.
-
-from skellycam.core.recorders.videos.recording_info import RecordingInfo
-
-@dataclass
-class CalibrationRecordingStateMessage(TopicMessageABC):
- recording_info: RecordingInfo | None = None
- is_active: bool = False
-```
-
-Then in the topic instantiation block (around line 198), add:
-
-```python
-CalibrationRecordingStateTopic = create_topic(CalibrationRecordingStateMessage)
-```
-
-- [ ] **Step 4: Run test to verify it passes**
-
-Run: `uv run pytest freemocap/tests/pubsub/test_calibration_recording_state_topic.py -v`
-Expected: PASS (3 tests)
-
-- [ ] **Step 5: Commit**
-
-```bash
-git add freemocap/pubsub/pubsub_topics.py freemocap/tests/pubsub/test_calibration_recording_state_topic.py
-git commit -m "feat: add CalibrationRecordingStateMessage + Topic to pubsub
-
-CalibrationRecordingStateTopic bridges the HTTP calibration endpoint
-and pipeline nodes β€” signals when a calibration recording starts/stops
-so the CharucoRecorderNode can toggle observation buffering.
-
-Co-Authored-By: Claude <[email protected]>"
-```
-
----
-
-### Task 2: CharucoRecorderNode
-
-**Files:**
-- Create: `freemocap/core/pipeline/realtime/charuco_recorder_node.py`
-- Test: `freemocap/tests/pipelines/test_charuco_recorder.py` (new)
-
-**Interfaces:**
-- Consumes: `CalibrationRecordingStateTopic` (from Task 1), `CameraNodeOutputTopic` (existing)
-- Produces: `charuco_observations_realtime.pkl` at `{recording_path}/output_data/`
-- `CharucoRecorderNode.create(*, camera_ids, ipc, pubsub, worker_registry) -> CharucoRecorderNode`
-- `CharucoRecorderNode._run(*, camera_node_output_sub, recording_state_sub, ipc, shutdown_self_flag) -> None`
-
-- [ ] **Step 1: Write the failing test**
-
-```python
-# freemocap/tests/pipelines/test_charuco_recorder.py
-import multiprocessing
-import pickle
-import tempfile
-from pathlib import Path
-
-import numpy as np
-import pytest
-from skellycam.core.recorders.videos.recording_info import RecordingInfo
-from skellytracker.trackers.charuco_tracker.charuco_board_definition import CharucoBoardDefinition
-from skellytracker.trackers.charuco_tracker.charuco_observation import CharucoObservation
-
-from freemocap.core.pipeline.abcs.pipeline_ipc import PipelineIPC
-from freemocap.core.pipeline.realtime.charuco_recorder_node import CharucoRecorderNode
-from freemocap.pubsub.pubsub_manager import PubSubTopicManager
-from freemocap.pubsub.pubsub_topics import (
- CalibrationRecordingStateMessage,
- CalibrationRecordingStateTopic,
- CameraNodeOutputMessage,
- CameraNodeOutputTopic,
-)
-
-
-def global_kill_flag():
- return multiprocessing.Value("b", False)
-
-
-def pubsub(global_kill_flag):
- ps = PubSubTopicManager.create(global_kill_flag=global_kill_flag)
- yield ps
- ps.close()
-
-
-def ipc(global_kill_flag):
- return PipelineIPC.create(global_kill_flag=global_kill_flag)
-
-
-def recording_info(tmp_path):
- return RecordingInfo(
- recording_directory=str(tmp_path),
- recording_name="test_recording",
- mic_device_index=-1,
- )
-
-
-def make_empty_charuco_observation():
- """Return a CharucoObservation with no detected corners."""
- board = CharucoBoardDefinition.create_test_data_7x5()
- return CharucoObservation.from_detection_results(
- board_definition=board,
- image_size=(1920, 1080),
- charuco_corners=None,
- charuco_ids=None,
- marker_corners=None,
- marker_ids=None,
- )
-
-
-def make_detected_charuco_observation():
- """Return a CharucoObservation with fake detected corners."""
- board = CharucoBoardDefinition.create_test_data_7x5()
- # Create fake detection: 4 corners with IDs [0,1,2,3]
- charuco_corners = np.array([[[100.0, 200.0]], [[150.0, 200.0]], [[200.0, 200.0]], [[250.0, 200.0]]], dtype=np.float32)
- charuco_ids = np.array([0, 1, 2, 3], dtype=np.int32)
- marker_corners = np.array([[[[0, 0]], [[0, 0]], [[0, 0]], [[0, 0]]]], dtype=np.float32)
- marker_ids = np.array([0], dtype=np.int32)
- return CharucoObservation.from_detection_results(
- board_definition=board,
- image_size=(1920, 1080),
- charuco_corners=charuco_corners,
- charuco_ids=charuco_ids,
- marker_corners=marker_corners,
- marker_ids=marker_ids,
- )
-
-
-class TestCharucoRecorderNode:
- def test_starts_idle(self, pubsub, ipc):
- """Before recording signal, no observations are buffered."""
- camera_node_output_pub = pubsub.get_publication_queue(CameraNodeOutputTopic)
- recording_state_pub = pubsub.get_publication_queue(CalibrationRecordingStateTopic)
-
- # Publish a camera output while no recording is active
- obs = make_detected_charuco_observation()
- camera_node_output_pub.put(CameraNodeOutputMessage(
- camera_id="cam_0",
- frame_number=0,
- charuco_observation=obs,
- ))
- pubsub.drain()
-
- # Recorder should NOT have buffered anything (it hasn't started recording)
- # We verify this by checking that publishing recording_state without
- # starting first doesn't write a cache file.
- # (This is a structural test β€” the recorder's _run loop isn't running yet.)
- # The real test is: after creating and destroying without ever sending
- # is_active=True, no cache file exists.
-
- def test_buffer_appends_per_frame(self, pubsub, ipc, recording_info, tmp_path):
- """When recording, each CameraNodeOutputMessage appends to buffer."""
- # This test exercises the buffer logic directly by simulating
- # what _run() does internally.
- from freemocap.core.pipeline.realtime.charuco_recorder_node import CharucoRecorderNode
-
- # Simulate the internal buffer state
- buffer: dict = {}
- camera_ids = ["cam_0", "cam_1"]
- buffer = {cid: [] for cid in camera_ids}
-
- # Simulate receiving frames during recording
- for frame_number in range(5):
- for cam_id in camera_ids:
- obs = make_detected_charuco_observation() if frame_number % 2 == 0 else make_empty_charuco_observation()
- buffer[cam_id].append(obs)
-
- # Verify: 5 frames per camera
- assert len(buffer["cam_0"]) == 5
- assert len(buffer["cam_1"]) == 5
- # Verify: frame index = list index
- assert buffer["cam_0"][3] is not None # frame 3 was even β†’ detected
- assert buffer["cam_0"][4].charuco_empty # frame 4 was odd β†’ empty
-
- def test_cache_file_is_valid_pickle(self, pubsub, ipc, recording_info, tmp_path):
- """The cache pickle file can be loaded and contains expected structure."""
- board = CharucoBoardDefinition.create_test_data_7x5()
- cache_data = {
- "board_definition": board,
- "observations": {
- "cam_0": [make_detected_charuco_observation() for _ in range(3)],
- },
- "frame_range": (0, 2),
- "recording_uuid": "test-uuid",
- }
- cache_path = tmp_path / "output_data" / "charuco_observations_realtime.pkl"
- cache_path.parent.mkdir(parents=True, exist_ok=True)
- with open(cache_path, "wb") as f:
- pickle.dump(cache_data, f)
-
- # Load and verify
- with open(cache_path, "rb") as f:
- loaded = pickle.load(f)
-
- assert loaded["board_definition"].squares_x == board.squares_x
- assert loaded["board_definition"].squares_y == board.squares_y
- assert len(loaded["observations"]["cam_0"]) == 3
- assert loaded["frame_range"] == (0, 2)
- assert not loaded["observations"]["cam_0"][0].charuco_empty
-
- def test_empty_observations_preserved(self):
- """Frames with no detection are stored β€” frame index invariant."""
- buffer = []
- for i in range(5):
- if i in [0, 2, 4]:
- buffer.append(make_detected_charuco_observation())
- else:
- buffer.append(make_empty_charuco_observation())
-
- assert len(buffer) == 5
- assert not buffer[0].charuco_empty
- assert buffer[1].charuco_empty
- assert not buffer[2].charuco_empty
- assert buffer[3].charuco_empty
- assert not buffer[4].charuco_empty
-```
-
-- [ ] **Step 2: Run test to verify it fails**
-
-Run: `uv run pytest freemocap/tests/pipelines/test_charuco_recorder.py -v`
-Expected: FAIL β€” `ImportError` for `charuco_recorder_node` module
-
-- [ ] **Step 3: Write minimal implementation**
-
-```python
-# freemocap/core/pipeline/realtime/charuco_recorder_node.py
-"""
-CharucoRecorderNode: persists Charuco observations from realtime CameraNodes
-during calibration recording windows, so posthoc calibration can skip
-redundant OpenCV detection.
-"""
-import logging
-import multiprocessing
-import pickle
-from dataclasses import dataclass, field
-from pathlib import Path
-from multiprocessing.sharedctypes import Synchronized
-
-from skellycam.core.types.type_overloads import CameraIdString
-from skellytracker.trackers.charuco_tracker.charuco_observation import CharucoObservation
-
-from freemocap.core.pipeline.abcs.pipeline_ipc import PipelineIPC
-from freemocap.core.pipeline.abcs.source_node_abc import SourceNode
-from freemocap.core.types.type_overloads import TopicSubscriptionQueue
-from freemocap.pubsub.pubsub_manager import PubSubTopicManager
-from freemocap.pubsub.pubsub_topics import (
- CalibrationRecordingStateMessage,
- CalibrationRecordingStateTopic,
- CameraNodeOutputMessage,
- CameraNodeOutputTopic,
-)
-
-logger = logging.getLogger(__name__)
-
-CACHE_FILENAME = "charuco_observations_realtime.pkl"
-OUTPUT_DATA_DIR = "output_data"
-
-
-@dataclass
-class CharucoRecorderNode(SourceNode):
- """Buffers CharucoObservations during calibration recordings.
-
- Subscribes to CameraNodeOutputTopic (for observations) and
- CalibrationRecordingStateTopic (for start/stop signals).
-
- On recording stop, pickles the full buffer to
- ``{recording_path}/output_data/charuco_observations_realtime.pkl``.
- """
-
- camera_ids: list[CameraIdString] = field(default_factory=list)
- progress_subscription: TopicSubscriptionQueue | None = None
-
- @classmethod
- def create(
- cls,
- *,
- camera_ids: list[CameraIdString],
- ipc: PipelineIPC,
- pubsub: PubSubTopicManager,
- ) -> "CharucoRecorderNode":
- camera_node_output_sub = pubsub.get_subscription(CameraNodeOutputTopic)
- recording_state_sub = pubsub.get_subscription(CalibrationRecordingStateTopic)
-
- shutdown_self_flag, worker = cls._create_worker(
- target=cls._run,
- name="CharucoRecorderNode",
- log_queue=ipc.ws_queue,
- kwargs=dict(
- camera_ids=camera_ids,
- camera_node_output_sub=camera_node_output_sub,
- recording_state_sub=recording_state_sub,
- ipc=ipc,
- shutdown_self_flag=None,
- ),
- )
- return cls(
- camera_ids=camera_ids,
- shutdown_self_flag=shutdown_self_flag,
- worker=worker,
- )
-
- @staticmethod
- def _run(
- *,
- camera_ids: list[CameraIdString],
- camera_node_output_sub: TopicSubscriptionQueue,
- recording_state_sub: TopicSubscriptionQueue,
- ipc: PipelineIPC,
- shutdown_self_flag: Synchronized,
- ) -> None:
- from queue import Empty
-
- logger.info("CharucoRecorderNode started β€” waiting for calibration recording signal")
-
- buffer: dict[CameraIdString, list[CharucoObservation | None]] = {
- cid: [] for cid in camera_ids
- }
- recording_info = None
- is_recording = False
-
- try:
- while ipc.should_continue:
- # Drain recording state messages
- while True:
- try:
- msg = recording_state_sub.get_nowait()
- if isinstance(msg, CalibrationRecordingStateMessage):
- if msg.is_active and not is_recording:
- is_recording = True
- recording_info = msg.recording_info
- buffer = {cid: [] for cid in camera_ids}
- logger.info(
- f"Calibration recording started: "
- f"{recording_info.recording_name if recording_info else 'unknown'}"
- )
- elif not msg.is_active and is_recording:
- is_recording = False
- logger.info(
- f"Calibration recording stopped β€” "
- f"flushing {sum(len(v) for v in buffer.values())} observations"
- )
- _flush_buffer(
- buffer=buffer,
- recording_info=recording_info,
- )
- except Empty:
- break
-
- # Drain camera node output messages (only when recording)
- while True:
- try:
- msg = camera_node_output_sub.get_nowait()
- if (
- is_recording
- and isinstance(msg, CameraNodeOutputMessage)
- and msg.camera_id in buffer
- ):
- buffer[msg.camera_id].append(msg.charuco_observation)
- except Empty:
- break
-
- except Exception:
- logger.exception("CharucoRecorderNode crashed")
- finally:
- # Flush if still recording on shutdown
- if is_recording:
- logger.warning(
- "CharucoRecorderNode shutting down while recording active β€” "
- "flushing partial buffer"
- )
- _flush_buffer(buffer=buffer, recording_info=recording_info)
- logger.info("CharucoRecorderNode exiting")
-
-
-def _flush_buffer(
- *,
- buffer: dict[CameraIdString, list],
- recording_info,
-) -> None:
- """Write the buffer to a pickle file."""
- if recording_info is None:
- logger.warning("No recording_info β€” cannot flush buffer")
- return
-
- recording_path = Path(recording_info.full_recording_path)
- output_dir = recording_path / OUTPUT_DATA_DIR
- output_dir.mkdir(parents=True, exist_ok=True)
- cache_path = output_dir / CACHE_FILENAME
-
- # Determine frame range
- all_lengths = [len(obs_list) for obs_list in buffer.values()]
- if not all_lengths or max(all_lengths) == 0:
- logger.info("Buffer is empty β€” writing empty cache")
- first_frame = last_frame = 0
- else:
- first_frame = 0
- last_frame = max(all_lengths) - 1
-
- # Extract board definition from first non-empty observation
- board_definition = None
- for obs_list in buffer.values():
- for obs in obs_list:
- if obs is not None and isinstance(obs, CharucoObservation):
- try:
- board_definition = obs.board_definition
- except AttributeError:
- pass
- if board_definition is not None:
- break
- if board_definition is not None:
- break
-
- cache_data = {
- "board_definition": board_definition,
- "observations": buffer,
- "frame_range": (first_frame, last_frame),
- "recording_uuid": recording_info.recording_uuid if recording_info else "",
- }
-
- with open(cache_path, "wb") as f:
- pickle.dump(cache_data, f)
-
- total_obs = sum(len(v) for v in buffer.values())
- logger.info(
- f"Wrote {total_obs} observations ({len(buffer)} cameras) to {cache_path}"
- )
-```
-
-- [ ] **Step 4: Run test to verify it passes**
-
-Run: `uv run pytest freemocap/tests/pipelines/test_charuco_recorder.py -v`
-Expected: PASS (4 tests)
-
-- [ ] **Step 5: Commit**
-
-```bash
-git add freemocap/core/pipeline/realtime/charuco_recorder_node.py freemocap/tests/pipelines/test_charuco_recorder.py
-git commit -m "feat: add CharucoRecorderNode for realtime observation capture
-
-Subscribes to CameraNodeOutputTopic + CalibrationRecordingStateTopic.
-Buffers full CharucoObservation objects per (camera_id, frame_number)
-during calibration recording windows. Pickles to cache on stop.
-
-Co-Authored-By: Claude <[email protected]>"
-```
-
----
-
-### Task 3: Calibration Router β€” Publish Recording State
-
-**Files:**
-- Modify: `freemocap/api/http/calibration/calibration_router.py:128-143` (start endpoint), `:146-171` (stop endpoint)
-
-**Interfaces:**
-- Consumes: `CalibrationRecordingStateTopic`, `CalibrationRecordingStateMessage` (from Task 1), `get_freemocap_app()` (existing)
-- Produces: Publishes `CalibrationRecordingStateMessage(is_active=True)` on start, `(is_active=False)` on stop
-
-- [ ] **Step 1: Write the failing test**
-
-```python
-# freemocap/tests/http/test_calibration_router_recording_state.py
-from unittest.mock import patch, MagicMock, AsyncMock
-import pytest
-from fastapi.testclient import TestClient
-
-from freemocap.api.http.calibration.calibration_router import calibration_router
-from freemocap.pubsub.pubsub_topics import (
- CalibrationRecordingStateMessage,
- CalibrationRecordingStateTopic,
-)
-
-
-def mock_app():
- """Mock FreemocapApplication with a realtime pipeline that has pubsub."""
- app = MagicMock()
- app.start_recording_all = AsyncMock()
- app.stop_recording_all = AsyncMock(return_value=MagicMock(
- full_recording_path="/tmp/test/test_recording",
- recording_name="test_recording",
- ))
- app.create_posthoc_calibration_pipeline = AsyncMock(return_value=MagicMock(id="pipe_123"))
-
- # Mock realtime pipeline manager with one alive pipeline
- mock_pipeline = MagicMock()
- mock_pipeline.alive = True
- mock_pipeline.pubsub = MagicMock()
- mock_pipeline.pubsub.publish = MagicMock()
-
- app.realtime_pipeline_manager = MagicMock()
- app.realtime_pipeline_manager.pipelines = {"pipe_1": mock_pipeline}
-
- return app
-
-
-def client(mock_app):
- from fastapi import FastAPI
- test_app = FastAPI()
- test_app.include_router(calibration_router)
-
- with patch(
- "freemocap.api.http.calibration.calibration_router.get_freemocap_app",
- return_value=mock_app,
- ):
- with patch(
- "freemocap.api.http.calibration.calibration_router._reject_if_recording_directory_not_empty",
- return_value=None,
- ):
- yield TestClient(test_app)
-
-
-class TestCalibrationRecordingStatePublishing:
- def test_start_publishes_recording_state(self, client, mock_app):
- """POST /calibration/recording/start publishes is_active=True."""
- response = client.post("/calibration/recording/start", json={
- "calibrationTaskConfig": {
- "charucoBoard": {
- "squaresX": 7,
- "squaresY": 5,
- "squareLengthMm": 54,
- "markerLengthRatio": 0.8,
- "arucoDictionaryEnum": "DICT_4X4_250",
- }
- },
- "calibrationRecordingDirectory": "/tmp/test",
- })
- assert response.status_code == 200
-
- # Verify publish was called on each alive pipeline
- for pipeline in mock_app.realtime_pipeline_manager.pipelines.values():
- pipeline.pubsub.publish.assert_called()
- call_args = pipeline.pubsub.publish.call_args
- # topic_type should be CalibrationRecordingStateTopic
- # message should be CalibrationRecordingStateMessage(is_active=True)
-
- def test_stop_publishes_recording_state(self, client, mock_app):
- """POST /calibration/recording/stop publishes is_active=False."""
- response = client.post("/calibration/recording/stop", json={
- "calibrationTaskConfig": {
- "charucoBoard": {
- "squaresX": 7,
- "squaresY": 5,
- "squareLengthMm": 54,
- "markerLengthRatio": 0.8,
- "arucoDictionaryEnum": "DICT_4X4_250",
- }
- },
- })
- assert response.status_code == 200
-
- for pipeline in mock_app.realtime_pipeline_manager.pipelines.values():
- pipeline.pubsub.publish.assert_called()
-```
-
-- [ ] **Step 2: Run test to verify it fails**
-
-Run: `uv run pytest freemocap/tests/http/test_calibration_router_recording_state.py -v`
-Expected: FAIL β€” assertions about `publish` being called fail (it's not called yet)
-
-- [ ] **Step 3: Write minimal implementation**
-
-In `freemocap/api/http/calibration/calibration_router.py`, add imports at the top:
-
-```python
-from freemocap.pubsub.pubsub_topics import (
- CalibrationRecordingStateMessage,
- CalibrationRecordingStateTopic,
-)
-```
-
-Modify `start_calibration_recording` (after line 136, inside the try block):
-
-```python
-@calibration_router.post("/recording/start")
-async def start_calibration_recording(
- request: CalibrateRecordingRequest,
-) -> StartCalibrationRecordingResponse:
- """Start calibration recording with given config."""
- try:
- recording_info = request.to_recording_info()
- _reject_if_recording_directory_not_empty(recording_info)
- await get_freemocap_app().start_recording_all(recording_info=recording_info)
- logger.info(f"Starting calibration recording: {recording_info}")
-
- # Notify realtime pipelines that a calibration recording has started
- app = get_freemocap_app()
- for pipeline in app.realtime_pipeline_manager.pipelines.values():
- if pipeline.alive:
- pipeline.pubsub.publish(
- CalibrationRecordingStateTopic,
- CalibrationRecordingStateMessage(
- recording_info=recording_info,
- is_active=True,
- ),
- )
- logger.debug(
- f"Published CalibrationRecordingState(is_active=True) "
- f"to pipeline [{pipeline.id}]"
- )
-
- return StartCalibrationRecordingResponse(success=True, message="Recording started")
- except HTTPException:
- raise
- except Exception as e:
- logger.exception(f"Error starting calibration recording: {e}")
- raise HTTPException(status_code=500, detail=str(e))
-```
-
-Modify `stop_calibration_recording` (before launching the posthoc pipeline, after line 157):
-
-```python
-@calibration_router.post("/recording/stop")
-async def stop_calibration_recording(
- request: StopCalibrationRecordingRequest,
-) -> dict:
- """Stop current calibration recording and launch posthoc calibration pipeline."""
- app = get_freemocap_app()
- try:
- recording_info = await app.stop_recording_all()
- if recording_info is None:
- logger.warning("No active recording to stop")
- return {"success": True}
-
- # Notify realtime pipelines that calibration recording has stopped
- for pipeline in app.realtime_pipeline_manager.pipelines.values():
- if pipeline.alive:
- pipeline.pubsub.publish(
- CalibrationRecordingStateTopic,
- CalibrationRecordingStateMessage(
- recording_info=recording_info,
- is_active=False,
- ),
- )
- logger.debug(
- f"Published CalibrationRecordingState(is_active=False) "
- f"to pipeline [{pipeline.id}]"
- )
-
- logger.info(f"Recording stopped - saved to: {recording_info.full_recording_path}")
- pipeline = await app.create_posthoc_calibration_pipeline(
- recording_info=recording_info,
- calibration_config=request.calibration_config,
- )
- logger.info("Calibration recording stopped, posthoc calibration pipeline launched")
- return {
- "success": True,
- "pipeline_id": pipeline.id,
- "recording_name": recording_info.recording_name,
- "recording_path": str(recording_info.full_recording_path),
- }
- except Exception as e:
- logger.exception(f"Error stopping calibration recording: {e}")
- raise HTTPException(status_code=500, detail=str(e))
-```
-
-- [ ] **Step 4: Run test to verify it passes**
-
-Run: `uv run pytest freemocap/tests/http/test_calibration_router_recording_state.py -v`
-Expected: PASS
-
-- [ ] **Step 5: Commit**
-
-```bash
-git add freemocap/api/http/calibration/calibration_router.py freemocap/tests/http/test_calibration_router_recording_state.py
-git commit -m "feat: publish calibration recording state to realtime pipelines
-
-POST /calibration/recording/start β†’ publishes is_active=True
-POST /calibration/recording/stop β†’ publishes is_active=False
-
-Only publishes to alive pipelines (no-op if no realtime pipeline active).
-
-Co-Authored-By: Claude <[email protected]>"
-```
-
----
-
-### Task 4: RealtimePipeline β€” Create CharucoRecorderNode
-
-**Files:**
-- Modify: `freemocap/core/pipeline/realtime/realtime_pipeline.py:98-205` (create method and shutdown)
-
-**Interfaces:**
-- Consumes: `CharucoRecorderNode` (from Task 2)
-- Produces: `RealtimePipeline.charuco_recorder_node: CharucoRecorderNode | None`
-- When `charuco_tracking_enabled=True` in pipeline config, create + start the recorder node
-
-- [ ] **Step 1: Write the failing test**
-
-```python
-# Add to freemocap/tests/pipelines/test_realtime_pipeline.py
-# (or a focused test file)
-
-def test_pipeline_creates_recorder_when_charuco_enabled():
- """RealtimePipeline creates CharucoRecorderNode when charuco tracking is on."""
- # This will be tested in the E2E test (Task 6) β€”
- # unit-level verification that the pipeline has a charuco_recorder_node
- # attribute when charuco_tracking_enabled=True
- pass # Placeholder β€” covered by E2E integration test
-```
-
-Since this is primarily wiring, the integration test in Task 6 covers it. The unit test here is a structural check.
-
-- [ ] **Step 2: Skip (covered by integration test)**
-
-- [ ] **Step 3: Write implementation**
-
-In `realtime_pipeline.py`, add import:
-
-```python
-from freemocap.core.pipeline.realtime.charuco_recorder_node import CharucoRecorderNode
-```
-
-Add field to `RealtimePipeline` dataclass (after `skeleton_inference_node`):
-
-```python
-@dataclass
-class RealtimePipeline:
- # ... existing fields ...
- skeleton_inference_node: RealtimeSkeletonInferenceNode | None
- charuco_recorder_node: CharucoRecorderNode | None # NEW
-```
-
-In `RealtimePipeline.create()`, add after the `skeleton_inference_node` creation block (around line 158):
-
-```python
- # Create CharucoRecorderNode if charuco tracking is enabled.
- # This node buffers observations during calibration recording windows
- # so posthoc calibration can skip redundant detection.
- charuco_recorder_node: CharucoRecorderNode | None = None
- if pipeline_config.camera_node_config.charuco_tracking_enabled:
- charuco_recorder_node = CharucoRecorderNode.create(
- camera_ids=pipeline_camera_ids,
- ipc=ipc,
- pubsub=pubsub,
- )
-```
-
-In the return `cls(...)` constructor call, add:
-
-```python
- return cls(
- # ... existing fields ...
- skeleton_inference_node=skeleton_inference_node,
- charuco_recorder_node=charuco_recorder_node, # NEW
- )
-```
-
-In `start()`, add after the camera node start loop (around line 234-236):
-
-```python
- if self.charuco_recorder_node is not None:
- self.charuco_recorder_node.start()
- logger.info(f"CharucoRecorderNode started for pipeline [{self.id}]")
-```
-
-In `shutdown()`, add in the shutdown sequence (after skeleton inference node shutdown, around line 256):
-
-```python
- if self.charuco_recorder_node is not None and self.charuco_recorder_node.is_alive:
- self.charuco_recorder_node.worker._intentionally_terminated = True
- self.charuco_recorder_node.shutdown()
-```
-
-Update `alive` property to include recorder node:
-
-```python
- @property
- def alive(self) -> bool:
- if not self.started:
- return False
- nodes_alive = (
- all(node.is_alive for node in self.camera_nodes.values())
- and self.aggregation_node.is_alive
- )
- if self.skeleton_inference_node is not None:
- nodes_alive = nodes_alive and self.skeleton_inference_node.is_alive
- if self.charuco_recorder_node is not None:
- nodes_alive = nodes_alive and self.charuco_recorder_node.is_alive
- return nodes_alive
-```
-
-- [ ] **Step 4: Verify with existing tests**
-
-Run: `uv run pytest freemocap/tests/pipelines/test_realtime_pipeline.py -v`
-Expected: PASS (existing tests should still pass β€” recorder node is only created when charuco_tracking_enabled, which the "charuco_only" param already enables)
-
-- [ ] **Step 5: Commit**
-
-```bash
-git add freemocap/core/pipeline/realtime/realtime_pipeline.py
-git commit -m "feat: wire CharucoRecorderNode into RealtimePipeline
-
-Created when charuco_tracking_enabled=True. Started after camera nodes,
-shut down in shutdown sequence. Tracked in alive property.
-
-Co-Authored-By: Claude <[email protected]>"
-```
-
----
-
-### Task 5: Cache-Aware VideoNode
-
-**Files:**
-- Modify: `freemocap/core/pipeline/posthoc/video_node.py:130-330` (the `_run` static method)
-- Test: `freemocap/tests/pipelines/test_video_node_cache.py` (new)
-
-**Interfaces:**
-- Consumes: `charuco_observations_realtime.pkl` cache file (from Task 2)
-- Produces: `VideoNodeOutputMessage` (unchanged β€” existing aggregator contract)
-- `_try_load_cache(recording_path, camera_id, board_config) -> dict[int, CharucoObservation] | None`
-- `_get_observation(frame_number, image, detector, cache) -> BaseObservation`
-
-- [ ] **Step 1: Write the failing test**
-
-```python
-# freemocap/tests/pipelines/test_video_node_cache.py
-import pickle
-import tempfile
-from pathlib import Path
-
-import numpy as np
-import pytest
-from skellytracker.trackers.charuco_tracker.charuco_board_definition import CharucoBoardDefinition
-from skellytracker.trackers.charuco_tracker.charuco_observation import CharucoObservation
-from skellytracker.trackers.charuco_tracker.charuco_tracker_config import CharucoDetectorConfig
-
-from freemocap.core.pipeline.posthoc.video_node import _try_load_cache, _get_observation
-
-
-def board_7x5():
- return CharucoBoardDefinition.create_test_data_7x5()
-
-
-def board_5x3():
- return CharucoBoardDefinition.create_letter_size_5x3()
-
-
-def cache_path(tmp_path):
- return tmp_path / "output_data" / "charuco_observations_realtime.pkl"
-
-
-def make_fake_observation(board, has_detection=True):
- """Create a minimal CharucoObservation for testing."""
- if has_detection:
- charuco_corners = np.array([[[100.0, 200.0]]], dtype=np.float32)
- charuco_ids = np.array([0], dtype=np.int32)
- marker_corners = np.array([[[[0, 0]], [[0, 0]], [[0, 0]], [[0, 0]]]], dtype=np.float32)
- marker_ids = np.array([0], dtype=np.int32)
- else:
- charuco_corners = None
- charuco_ids = None
- marker_corners = None
- marker_ids = None
-
- return CharucoObservation.from_detection_results(
- board_definition=board,
- image_size=(1920, 1080),
- charuco_corners=charuco_corners,
- charuco_ids=charuco_ids,
- marker_corners=marker_corners,
- marker_ids=marker_ids,
- )
-
-
-class TestTryLoadCache:
- def test_returns_none_when_cache_missing(self, tmp_path, board_7x5):
- """If no cache file exists, return None."""
- result = _try_load_cache(
- recording_path=tmp_path,
- camera_id="cam_0",
- board_config=board_7x5,
- )
- assert result is None
-
- def test_returns_observations_when_cache_exists(self, tmp_path, cache_path, board_7x5):
- """Valid cache returns observations dict."""
- cache_path.parent.mkdir(parents=True, exist_ok=True)
- obs_list = [make_fake_observation(board_7x5, has_detection=True) for _ in range(5)]
- cache_data = {
- "board_definition": board_7x5,
- "observations": {"cam_0": obs_list},
- "frame_range": (0, 4),
- "recording_uuid": "test-uuid",
- }
- with open(cache_path, "wb") as f:
- pickle.dump(cache_data, f)
-
- result = _try_load_cache(
- recording_path=tmp_path,
- camera_id="cam_0",
- board_config=board_7x5,
- )
- assert result is not None
- assert len(result) == 5
- assert not result[0].charuco_empty
-
- def test_returns_none_on_board_mismatch(self, tmp_path, cache_path, board_7x5, board_5x3):
- """Different board config β†’ cache rejected."""
- cache_path.parent.mkdir(parents=True, exist_ok=True)
- cache_data = {
- "board_definition": board_7x5,
- "observations": {"cam_0": []},
- "frame_range": (0, 0),
- "recording_uuid": "",
- }
- with open(cache_path, "wb") as f:
- pickle.dump(cache_data, f)
-
- result = _try_load_cache(
- recording_path=tmp_path,
- camera_id="cam_0",
- board_config=board_5x3, # Different!
- )
- assert result is None
-
- def test_returns_none_on_corrupt_cache(self, tmp_path, cache_path, board_7x5):
- """Corrupt pickle β†’ return None (don't crash)."""
- cache_path.parent.mkdir(parents=True, exist_ok=True)
- cache_path.write_text("not a pickle file")
-
- result = _try_load_cache(
- recording_path=tmp_path,
- camera_id="cam_0",
- board_config=board_7x5,
- )
- assert result is None
-
- def test_returns_none_when_camera_not_in_cache(self, tmp_path, cache_path, board_7x5):
- """Camera ID not in cache β†’ return None."""
- cache_path.parent.mkdir(parents=True, exist_ok=True)
- cache_data = {
- "board_definition": board_7x5,
- "observations": {"cam_0": []}, # cam_0 only, not cam_1
- "frame_range": (0, 0),
- "recording_uuid": "",
- }
- with open(cache_path, "wb") as f:
- pickle.dump(cache_data, f)
-
- result = _try_load_cache(
- recording_path=tmp_path,
- camera_id="cam_1", # Not in cache
- board_config=board_7x5,
- )
- assert result is None
-
-
-class TestGetObservation:
- def test_uses_cache_when_frame_present(self, board_7x5):
- """When cache has the frame, return cached observation."""
- cached_obs = make_fake_observation(board_7x5, has_detection=True)
- cache = {0: cached_obs}
-
- result = _get_observation(
- frame_number=0,
- image=np.zeros((1080, 1920, 3), dtype=np.uint8),
- detector=None, # Should not be called
- cache=cache,
- )
- assert result is cached_obs
-
- def test_falls_back_to_detector_when_frame_missing(self, board_7x5):
- """When cache doesn't have the frame, call detector."""
- cache = {0: make_fake_observation(board_7x5)}
-
- mock_detector_called = False
- class FakeDetector:
- def detect(self, frame_number, image):
- nonlocal mock_detector_called
- mock_detector_called = True
- return make_fake_observation(board_7x5, has_detection=False)
-
- result = _get_observation(
- frame_number=1, # Not in cache
- image=np.zeros((1080, 1920, 3), dtype=np.uint8),
- detector=FakeDetector(),
- cache=cache,
- )
- assert mock_detector_called
- assert result.charuco_empty
-
- def test_falls_back_when_cache_is_none(self, board_7x5):
- """None cache β†’ always call detector."""
- mock_detector_called = False
- class FakeDetector:
- def detect(self, frame_number, image):
- nonlocal mock_detector_called
- mock_detector_called = True
- return make_fake_observation(board_7x5)
-
- result = _get_observation(
- frame_number=0,
- image=np.zeros((1080, 1920, 3), dtype=np.uint8),
- detector=FakeDetector(),
- cache=None,
- )
- assert mock_detector_called
-```
-
-- [ ] **Step 2: Run test to verify it fails**
-
-Run: `uv run pytest freemocap/tests/pipelines/test_video_node_cache.py -v`
-Expected: FAIL β€” `ImportError` for `_try_load_cache` or `_get_observation`
-
-- [ ] **Step 3: Write implementation**
-
-Add these imports at the top of `video_node.py`:
-
-```python
-import pickle
-from skellytracker.trackers.charuco_tracker.charuco_observation import CharucoObservation
-```
-
-Add these module-level constants and functions after the `VideoNode` class (before `get_progress_messages`):
-
-```python
-CACHE_FILENAME = "charuco_observations_realtime.pkl"
-
-
-def _try_load_cache(
- *,
- recording_path: Path,
- camera_id: CameraIdString,
- board_config,
-) -> dict[int, object] | None:
- """Load the realtime Charuco observation cache if it exists and matches.
-
- Returns a dict mapping frame_number β†’ CharucoObservation, or None if
- the cache is missing, corrupt, or has a different board config.
- """
- cache_path = recording_path / "output_data" / CACHE_FILENAME
- if not cache_path.exists():
- return None
-
- try:
- with open(cache_path, "rb") as f:
- cache_data = pickle.load(f)
- except Exception:
- logger.warning(
- f"Failed to load Charuco observation cache from {cache_path} β€” "
- f"falling back to normal detection",
- exc_info=True,
- )
- return None
-
- # Validate board config match
- cached_board = cache_data.get("board_definition")
- if cached_board is None:
- logger.warning("Cache missing board_definition β€” rejecting")
- return None
-
- # Compare key board parameters
- if (
- cached_board.squares_x != board_config.squares_x
- or cached_board.squares_y != board_config.squares_y
- or abs(cached_board.square_length_mm - board_config.square_length_mm) > 0.01
- or cached_board.aruco_dictionary_enum != board_config.aruco_dictionary_enum
- ):
- logger.info(
- f"Cache board config mismatch β€” "
- f"cache=({cached_board.squares_x}x{cached_board.squares_y}, "
- f"{cached_board.square_length_mm}mm), "
- f"request=({board_config.squares_x}x{board_config.squares_y}, "
- f"{board_config.square_length_mm}mm) β€” "
- f"falling back to normal detection"
- )
- return None
-
- observations = cache_data.get("observations", {})
- if camera_id not in observations:
- logger.info(
- f"Camera {camera_id} not found in cache β€” "
- f"falling back to normal detection"
- )
- return None
-
- obs_list = observations[camera_id]
- logger.info(
- f"Loaded {len(obs_list)} cached Charuco observations "
- f"for camera {camera_id} from {cache_path}"
- )
- return {frame_number: obs for frame_number, obs in enumerate(obs_list)}
-
-
-def _get_observation(
- *,
- frame_number: int,
- image,
- detector,
- cache: dict[int, object] | None,
-):
- """Get observation for a frame β€” from cache if available, else detect.
-
- Args:
- frame_number: The current frame number.
- image: The frame image (only used if cache miss).
- detector: The CharucoDetector (only called on cache miss).
- cache: Frame_number β†’ CharucoObservation mapping, or None.
-
- Returns:
- CharucoObservation from cache or from detector.detect().
- """
- if cache is not None and frame_number in cache:
- return cache[frame_number]
-
- return detector.detect(
- frame_number=frame_number,
- image=image,
- )
-```
-
-Modify `VideoNode._run()` to load the cache at the top and use `_get_observation`. Change the `_run` method signature to accept `recording_path` (already present) and update imports. In the main loop (around line 234-246), replace:
-
-```python
- observation = detector.detect(
- frame_number=frame_number,
- image=image,
- )
-```
-
-With:
-
-```python
- observation = _get_observation(
- frame_number=frame_number,
- image=image,
- detector=detector,
- cache=cache,
- )
-```
-
-And add at the top of the `_run` try block (after detector creation, before the video loop, around line 157):
-
-```python
- # Try to load cached Charuco observations from a prior realtime
- # recording window. On cache hit, detection is skipped per-frame
- # but video I/O and frame sequencing are completely unchanged.
- cache = _try_load_cache(
- recording_path=recording_path,
- camera_id=camera_id,
- board_config=detector_config,
- )
- if cache is not None:
- logger.info(
- f"VideoNode [{camera_id}]: using cached observations "
- f"({len(cache)} frames) β€” detection will be skipped"
- )
-```
-
-- [ ] **Step 4: Run test to verify it passes**
-
-Run: `uv run pytest freemocap/tests/pipelines/test_video_node_cache.py -v`
-Expected: PASS (8 tests)
-
-- [ ] **Step 5: Commit**
-
-```bash
-git add freemocap/core/pipeline/posthoc/video_node.py freemocap/tests/pipelines/test_video_node_cache.py
-git commit -m "feat: cache-aware VideoNode skips detection when cache exists
-
-_try_load_cache() checks for charuco_observations_realtime.pkl, validates
-board config matches. _get_observation() returns cached result on hit,
-falls through to detector.detect() on miss.
-
-Video I/O loop is UNCHANGED β€” every frame is read from cv2.VideoCapture
-sequentially. Only the detector.detect() call is gated.
-
-Co-Authored-By: Claude <[email protected]>"
-```
-
----
-
-### Task 6: End-to-End Integration Test
-
-**Files:**
-- Create: `freemocap/tests/pipelines/test_calibration_cache_e2e.py`
-- Modify: `freemocap/tests/pipelines/conftest.py` β€” add CharucoRecorderNode fixture if needed
-
-**Interfaces:**
-- Consumes: All components from Tasks 1-5
-- Uses existing: `MockCameraGroup`, `drive_realtime_lockstep`, `freemocap_test_data`, `charuco_board_7x5`, `posthoc_manager`, `recording_info`, `synchronized_videos_dir`, `global_kill_flag`
-
-- [ ] **Step 1: Write the E2E test**
-
-```python
-# freemocap/tests/pipelines/test_calibration_cache_e2e.py
-"""
-End-to-end test: realtime Charuco capture β†’ cache file β†’ posthoc calibration via cache.
-
-Uses MockCameraGroup + drive_realtime_lockstep to simulate a realtime pipeline
-processing freemocap_test_data (7x5 charuco board, 3 cameras, 222 frames).
-Verifies the cache file is written and produces equivalent calibration results.
-"""
-import logging
-import pickle
-import time
-from pathlib import Path
-
-import pytest
-from skellycam.core.ipc.process_management.managed_worker import WorkerMode
-from skellycam.core.ipc.process_management.worker_registry import WorkerRegistry
-from skellytracker.trackers.charuco_tracker.charuco_board_definition import CharucoBoardDefinition
-
-from freemocap.core.pipeline.realtime.realtime_pipeline import RealtimePipeline
-from freemocap.core.pipeline.realtime.realtime_pipeline_config import RealtimePipelineConfig
-from freemocap.core.pipeline.realtime.camera_node_config import CameraNodeConfig
-from freemocap.core.pipeline.realtime.realtime_aggregator_node_config import RealtimeAggregatorNodeConfig
-from freemocap.core.tasks.calibration.calibration_task_config import PosthocCalibrationPipelineConfig
-from freemocap.core.tasks.calibration.shared.calibration_paths import get_last_successful_calibration_toml_path
-from freemocap.pubsub.pubsub_topics import (
- CalibrationRecordingStateMessage,
- CalibrationRecordingStateTopic,
-)
-from freemocap.tests.pipelines.helpers import wait_for_pipeline
-from freemocap.tests.pipelines.mocks.mock_camera_group import MockCameraGroup
-from freemocap.tests.pipelines.mocks.realtime_driver import drive_realtime_lockstep
-
-logger = logging.getLogger(__name__)
-
-CACHE_FILENAME = "charuco_observations_realtime.pkl"
-
-
[email protected](scope="module")
-def realtime_cache_path(test_recording_path: Path) -> Path:
- """Path where the CharucoRecorderNode writes its cache."""
- return test_recording_path / "output_data" / CACHE_FILENAME
-
-
[email protected](scope="module")
-def realtime_pipeline_for_capture(
- global_kill_flag,
- synchronized_videos_dir: Path,
- charuco_board_7x5: CharucoBoardDefinition,
- realtime_max_frames: int,
-) -> RealtimePipeline:
- """Create a realtime pipeline with CharucoRecorderNode, drive through all frames."""
- logger.info("=" * 60)
- logger.info("SETUP: Creating realtime pipeline with CharucoRecorderNode")
-
- # Create mock camera group from test data
- mock_group = MockCameraGroup.create(
- synchronized_videos_dir=str(synchronized_videos_dir),
- global_kill_flag=global_kill_flag,
- )
-
- # Build pipeline config with Charuco tracking enabled
- camera_node_config = CameraNodeConfig(
- charuco_tracking_enabled=True,
- charuco_detector_config=charuco_board_7x5.to_detector_config(),
- skeleton_tracking_enabled=False,
- )
- aggregator_config = RealtimeAggregatorNodeConfig(
- charuco_tracking_enabled=True,
- )
- pipeline_config = RealtimePipelineConfig(
- camera_node_config=camera_node_config,
- aggregator_node_config=aggregator_config,
- )
-
- worker_registry = WorkerRegistry(
- global_kill_flag=global_kill_flag,
- worker_mode=WorkerMode.THREAD,
- )
-
- pipeline = RealtimePipeline.create(
- camera_group=mock_group,
- pipeline_config=pipeline_config,
- worker_registry=worker_registry,
- )
-
- pipeline.start()
- logger.info(f"RealtimePipeline [{pipeline.id}] started")
-
- # Verify CharucoRecorderNode was created
- assert pipeline.charuco_recorder_node is not None, (
- "CharucoRecorderNode should be created when charuco_tracking_enabled=True"
- )
-
- # Publish calibration recording start
- logger.info("Publishing CalibrationRecordingState(is_active=True)")
- pipeline.pubsub.publish(
- CalibrationRecordingStateTopic,
- CalibrationRecordingStateMessage(is_active=True),
- )
-
- # Drive through all frames
- num_frames = realtime_max_frames if realtime_max_frames > 0 else 222
- logger.info(f"Driving {num_frames} frames through realtime pipeline")
- result = drive_realtime_lockstep(
- pipeline=pipeline,
- mock_group=mock_group,
- num_frames=num_frames,
- )
- logger.info(f"Processed {len(result.outputs)} frames")
-
- # Publish calibration recording stop
- logger.info("Publishing CalibrationRecordingState(is_active=False)")
- pipeline.pubsub.publish(
- CalibrationRecordingStateTopic,
- CalibrationRecordingStateMessage(is_active=False),
- )
-
- # Allow time for the recorder to flush
- time.sleep(0.5)
-
- yield pipeline
-
- # Cleanup
- logger.info("Shutting down realtime pipeline")
- pipeline.shutdown()
- mock_group.close()
-
-
-class TestCalibrationCacheE2E:
- """End-to-end tests for the Charuco observation cache pipeline."""
-
- def test_cache_file_written(self, realtime_pipeline_for_capture, realtime_cache_path):
- """After a calibration recording with realtime pipeline active,
- the cache file is written to the recording's output_data directory."""
- assert realtime_cache_path.exists(), (
- f"Cache file not found at {realtime_cache_path}"
- )
-
- with open(realtime_cache_path, "rb") as f:
- cache_data = pickle.load(f)
-
- assert "observations" in cache_data
- assert "board_definition" in cache_data
- assert "frame_range" in cache_data
-
- # Should have observations for each camera in the test data (3 cameras)
- observations = cache_data["observations"]
- assert len(observations) >= 1, "At least one camera should have observations"
-
- for cam_id, obs_list in observations.items():
- assert len(obs_list) > 0, f"Camera {cam_id} should have observations"
- logger.info(f"Camera {cam_id}: {len(obs_list)} observations")
-
- def test_cache_contains_valid_observations(self, realtime_pipeline_for_capture, realtime_cache_path):
- """Cache contains non-empty CharucoObservation objects for frames
- where the board was visible."""
- with open(realtime_cache_path, "rb") as f:
- cache_data = pickle.load(f)
-
- observations = cache_data["observations"]
-
- # Count frames with detected corners vs empty
- total_detected = 0
- total_empty = 0
- for cam_id, obs_list in observations.items():
- for obs in obs_list:
- if obs is not None and hasattr(obs, 'charuco_empty') and not obs.charuco_empty:
- total_detected += 1
- else:
- total_empty += 1
-
- logger.info(f"Cache stats: {total_detected} detected, {total_empty} empty")
- # At least some frames should have detected the board
- assert total_detected > 0, (
- "Expected at least some frames with detected Charuco corners"
- )
-
- def test_posthoc_calibration_with_cache(
- self,
- recording_info,
- posthoc_manager,
- charuco_board_7x5,
- realtime_cache_path,
- test_recording_path,
- ):
- """Posthoc calibration pipeline runs when cache exists and produces
- equivalent results to the baseline (no-cache) calibration."""
- logger.info("Running posthoc calibration WITH cache")
-
- # Record baseline calibration time from the session fixture
- # (which runs without cache). Then run WITH cache and compare.
- t0 = time.perf_counter()
- config = PosthocCalibrationPipelineConfig(charuco_board=charuco_board_7x5)
- pipeline = posthoc_manager.create_calibration_pipeline(
- recording_info=recording_info,
- calibration_config=config,
- )
- logger.info(f"Calibration pipeline with cache: id={pipeline.id}")
- wait_for_pipeline(pipeline)
- elapsed = time.perf_counter() - t0
- logger.info(f"Calibration with cache completed in {elapsed:.1f}s")
-
- calibration_toml = get_last_successful_calibration_toml_path()
- assert calibration_toml.exists(), (
- f"Calibration TOML not found at {calibration_toml}"
- )
- logger.info(f"Calibration TOML written: {calibration_toml}")
-
- def test_no_cache_no_crash(self, recording_info, posthoc_manager, charuco_board_7x5, test_recording_path):
- """If cache file is missing (clean state), posthoc calibration still works
- via normal video detection path."""
- cache_path = test_recording_path / "output_data" / CACHE_FILENAME
-
- # Remove cache if it exists
- if cache_path.exists():
- cache_path.unlink()
-
- config = PosthocCalibrationPipelineConfig(charuco_board=charuco_board_7x5)
- pipeline = posthoc_manager.create_calibration_pipeline(
- recording_info=recording_info,
- calibration_config=config,
- )
- wait_for_pipeline(pipeline)
-
- calibration_toml = get_last_successful_calibration_toml_path()
- assert calibration_toml.exists(), (
- "Calibration should complete via normal video path when cache is missing"
- )
-```
-
-- [ ] **Step 2: Run the E2E test (cache write)**
-
-Run: `uv run pytest freemocap/tests/pipelines/test_calibration_cache_e2e.py::TestCalibrationCacheE2E::test_cache_file_written -v --timeout=300`
-Expected: PASS β€” cache file written with observations
-
-- [ ] **Step 3: Run the E2E test (cache validation)**
-
-Run: `uv run pytest freemocap/tests/pipelines/test_calibration_cache_e2e.py::TestCalibrationCacheE2E::test_cache_contains_valid_observations -v --timeout=60`
-Expected: PASS β€” observations contain detected corners
-
-- [ ] **Step 4: Run the E2E test (posthoc with cache)**
-
-Run: `uv run pytest freemocap/tests/pipelines/test_calibration_cache_e2e.py::TestCalibrationCacheE2E::test_posthoc_calibration_with_cache -v --timeout=600`
-Expected: PASS β€” calibration produces valid TOML
-
-- [ ] **Step 5: Run the E2E test (no-cache fallback)**
-
-Run: `uv run pytest freemocap/tests/pipelines/test_calibration_cache_e2e.py::TestCalibrationCacheE2E::test_no_cache_no_crash -v --timeout=600`
-Expected: PASS β€” calibration works without cache
-
-- [ ] **Step 6: Run full regression suite**
-
-Run: `uv run pytest freemocap/tests/pipelines/ -v --timeout=600 -k "not slow"`
-Expected: All existing tests PASS (no regressions)
-
-- [ ] **Step 7: Commit**
-
-```bash
-git add freemocap/tests/pipelines/test_calibration_cache_e2e.py
-git commit -m "test: E2E tests for Charuco observation cache pipeline
-
-Tests the full roundtrip: realtime pipeline captures observations β†’
-writes cache β†’ posthoc calibration uses cached observations.
-Also verifies graceful fallback when cache is missing.
-
-Co-Authored-By: Claude <[email protected]>"
-```
-
----
-
-### Task 7: Verify & Polish
-
-- [ ] **Step 1: Run the full test suite**
-
-```bash
-uv run poe test
-```
-
-Expected: All tests pass, no regressions.
-
-- [ ] **Step 2: Lint**
-
-```bash
-uv run poe lint
-```
-
-Fix any lint issues.
-
-- [ ] **Step 3: Clean up any debug/temporary files**
-
-Remove any `__pycache__` or temp files created during development.
-
-- [ ] **Step 4: Final commit if any polish was needed**
-
-```bash
-git add -u
-git commit -m "chore: lint fixes and polish for Charuco observation cache"
-```
diff --git a/docs/superpowers/specs/2026-06-22-charuco-observation-cache-design.md b/docs/superpowers/specs/2026-06-22-charuco-observation-cache-design.md
deleted file mode 100644
index 1a939573..00000000
--- a/docs/superpowers/specs/2026-06-22-charuco-observation-cache-design.md
+++ /dev/null
@@ -1,175 +0,0 @@
-# Charuco Observation Cache: Reuse Realtime Detections in Posthoc Calibration
-
-**Date:** 2026-06-22
-**Status:** Design approved, pending implementation
-
-## Context
-
-When a calibration recording is started while a realtime pipeline is active, the `CameraNode` already runs full Charuco board detection on every frame (via `skellytracker.CharucoDetector.detect()`). These observations are published on the pubsub bus, consumed by the `RealtimeAggregatorNode` for triangulation and frontend display, and then **discarded**.
-
-When the posthoc calibration pipeline runs afterward, each `VideoNode` re-reads the same frames from video files on disk and **re-runs the exact same Charuco detection** β€” effectively doing the same OpenCV work twice.
-
-This spec describes a system to capture realtime Charuco observations during the calibration recording window and feed them into the posthoc pipeline, skipping redundant detection while preserving all frame synchronization guarantees.
-
-## Design
-
-### Architecture Overview
-
-```
-Calibration Recording (realtime active):
- CameraNode β†’ detects Charuco β†’ publishes CameraNodeOutputMessage
- β”‚ ↓
- β”‚ RealtimeAggregatorNode (display, unchanged)
- β”‚
- └──→ CharucoRecorderNode [NEW]
- ↓
- buffers full CharucoObservation per (camera_id, frame_number)
- ↓
- on recording stop: pickle.dump β†’ charuco_observations_realtime.pkl
-
-Posthoc Calibration:
- VideoNode β†’ cv2.VideoCapture.read() EVERY frame (unchanged)
- β”‚
- β”œβ”€β”€ cache hit: return pickled CharucoObservation (skip detect)
- └── cache miss: detector.detect(image) (normal path)
- ↓
- PosthocAggregatorNode (unchanged)
- ↓
- run_posthoc_calibration_task() (unchanged)
-```
-
-### New Components
-
-#### 1. `CalibrationRecordingStateMessage` + `CalibrationRecordingStateTopic`
-
-**File:** `freemocap/pubsub/pubsub_topics.py`
-
-```python
-@dataclass
-class CalibrationRecordingStateMessage(TopicMessageABC):
- recording_info: RecordingInfo # from skellycam
- is_active: bool
-
-class CalibrationRecordingStateTopic(PubSubTopicABC):
- message_type = CalibrationRecordingStateMessage
-```
-
-Added to the pipeline's topic set. Published by the calibration HTTP endpoint on recording start/stop. Subscribed by the `CharucoRecorderNode`.
-
-#### 2. `CharucoRecorderNode`
-
-**File:** `freemocap/core/pipeline/realtime/charuco_recorder_node.py` (new)
-
-A `SourceNode` that subscribes to `CameraNodeOutputTopic` and `CalibrationRecordingStateTopic`.
-
-- **IDLE state:** Ignores camera outputs.
-- **RECORDING state:** Appends `msg.charuco_observation` to `buffer[camera_id]` on every `CameraNodeOutputMessage`. Always appends β€” even when `charuco_empty=True` β€” so `buffer[camera_id][frame_N]` is the observation for frame N.
-- **On recording stop:** Pickles the buffer plus metadata (`CharucoBoardDefinition`, frame range, recording UUID) to `{recording_path}/output_data/charuco_observations_realtime.pkl`.
-
-#### 3. Cache-Aware `VideoNode`
-
-**File:** `freemocap/core/pipeline/posthoc/video_node.py` (modified)
-
-The `_run()` loop structure is **unchanged**. Every frame is read from video sequentially β€” no seeking, no skipping. The only change is how the observation is obtained:
-
-```python
-for frame_number in range(frame_count):
- success, image = video_reader.read() # ALWAYS
-
- observation = _get_observation(
- frame_number=frame_number,
- image=image,
- detector=detector,
- cache=cache,
- )
-
- video_output_pub.put(VideoNodeOutputMessage(
- camera_id=camera_id,
- frame_number=frame_number,
- observation=observation,
- ))
-```
-
-```python
-def _get_observation(frame_number, image, detector, cache):
- if cache is not None and frame_number in cache:
- return cache[frame_number] # pickle-deserialized CharucoObservation
- return detector.detect(frame_number=frame_number, image=image)
-```
-
-`_try_load_cache()`:
-1. Checks `charuco_observations_realtime.pkl` exists
-2. Validates `CharucoBoardDefinition` matches current config
-3. Returns `dict[int, CharucoObservation]` keyed by frame number
-4. Returns `None` on any mismatch or missing file β†’ seamless fallback
-
-### Cache File Format
-
-**Path:** `{recording_path}/output_data/charuco_observations_realtime.pkl`
-
-**Format:** Python pickle containing:
-```python
-{
- "board_definition": CharucoBoardDefinition,
- "observations": {
- camera_id: list[CharucoObservation | None] # indexed by frame_number
- },
- "frame_range": (int, int),
- "recording_uuid": str,
-}
-```
-
-Full `CharucoObservation` objects β€” not a simplified format. Deserialization produces objects bit-identical to what `CharucoDetector.detect()` returns.
-
-### Modified Components
-
-| Component | File | Change |
-|---|---|---|
-| `CalibrationRecordingStateMessage` + Topic | `pubsub/pubsub_topics.py` | New topic + message type |
-| `CharucoRecorderNode` | `core/pipeline/realtime/charuco_recorder_node.py` | New SourceNode |
-| `RealtimePipeline` | `core/pipeline/realtime/realtime_pipeline.py` | Optionally creates CharucoRecorderNode |
-| `calibration_router.py` | `api/http/calibration/calibration_router.py` | Publishes CalibrationRecordingStateMessage on start/stop |
-| `video_node.py` | `core/pipeline/posthoc/video_node.py` | Cache lookup in `_run()` main loop |
-| `posthoc_pipeline.py` | `core/pipeline/posthoc/posthoc_pipeline.py` | Passes recording path for cache lookup |
-
-### Invariants
-
-1. **Video frame sequencing is NEVER altered.** Every VideoNode reads every frame from `cv2.VideoCapture.read()` sequentially. No frame seeking. The cache only gates the `detector.detect()` call.
-2. **One VideoNodeOutputMessage per frame per camera.** The PosthocAggregationNode sees the same message pattern regardless of cache usage.
-3. **Graceful degradation.** If the realtime pipeline was not running during recording, or the cache file is missing, or the board config doesn't match β€” the VideoNode falls back to normal detection.
-4. **Board config validated on load.** Cache is rejected if the pickled `CharucoBoardDefinition` doesn't match the calibration request's board config.
-
-## Verification Plan
-
-### Layer 1: Unit β€” CharucoRecorderNode
-**File:** `freemocap/tests/pipelines/test_charuco_recorder.py` (new)
-
-- Starts idle, ignores messages before recording signal
-- Buffers observations (both detected and empty) during recording
-- Frame index = list index invariant
-- Flushes to pickle on recording stop
-- Multiple cameras
-
-### Layer 2: Unit β€” Cache-aware VideoNode
-**File:** `freemocap/tests/pipelines/test_video_node_cache.py` (new)
-
-- Loads cache when present and valid
-- Falls back on missing/mismatched/corrupt cache
-- Publishes sequential frames regardless of path
-- CharucoObservation roundtrip fidelity through pickle
-
-### Layer 3: Integration β€” Full pipeline E2E
-**File:** `freemocap/tests/pipelines/test_calibration_cache_e2e.py` (new)
-
-Uses existing infrastructure: `MockCameraGroup`, `drive_realtime_lockstep`, `freemocap_test_data` (7x5 charuco board, 3 cameras, 222 frames):
-
-- `test_cache_path_produces_same_calibration_as_video_path` β€” TOML equivalence within tolerance
-- `test_cache_is_faster_than_video` β€” wall-clock time reduced
-- `test_graceful_fallback_when_no_cache` β€” normal video path succeeds
-
-### Layer 4: Regression
-All existing pipeline tests must continue to pass:
-- `test_posthoc_calibration_pipeline.py`
-- `test_realtime_pipeline.py` (charuco_only and full)
-- `test_posthoc_mocap_pipeline.py`
-- `test_anthropometry_validation.py`
diff --git a/freemocap-ui/package.json b/freemocap-ui/package.json
index 06d74f3f..126bd16e 100644
--- a/freemocap-ui/package.json
+++ b/freemocap-ui/package.json
@@ -1,6 +1,6 @@
{
"name": "freemocap",
- "version": "2.0.0-alpha.1",
+ "version": "2.0.0-alpha.2",
"main": "dist-electron/main/index.js",
"description": "FreeMoCap - Free Open Source Markerless Motion Capture For Everyone",
"author": "Skelly FreeMocap <[email protected]>",
diff --git a/freemocap/__init__.py b/freemocap/__init__.py
index 3c04bf0b..4f133349 100644
--- a/freemocap/__init__.py
+++ b/freemocap/__init__.py
@@ -2,7 +2,7 @@
__author__ = """Skelly FreeMoCap"""
__email__ = "[email protected]"
-__version__ = "v1.4.7"
+__version__ = "v2.0.0-alpha.2"
__description__ = "A free and open source markerless motion capture system for everyone πŸ’€βœ¨"
__package_name__ = "freemocap"
diff --git a/freemocap/core/__init__.py b/freemocap/core/__init__.py
index b953c6d9..680da98d 100644
--- a/freemocap/core/__init__.py
+++ b/freemocap/core/__init__.py
@@ -1,14 +1,5 @@
"""A free and open source markerless motion capture system for everyone πŸ’€βœ¨"""
-__author__ = """Skelly FreeMoCap"""
-__email__ = "[email protected]"
-__version__ = "v1.4.7"
-__description__ = "A free and open source markerless motion capture system for everyone πŸ’€βœ¨"
-
-__package_name__ = "freemocap"
-__repo_url__ = f"https://github.com/freemocap/{__package_name__}/"
-__repo_issues_url__ = f"{__repo_url__}issues"
-
from skellylogs import configure_logging, LogLevels
LOG_LEVEL = LogLevels.TRACE
diff --git a/poe_tasks.toml b/poe_tasks.toml
index 70054ea4..f918f1ba 100644
--- a/poe_tasks.toml
+++ b/poe_tasks.toml
@@ -54,6 +54,21 @@ test-pipelines = { cmd = "pytest freemocap/tests/pipelines/ -v --timeout=600 --t
test-pipelines-fast = { cmd = "pytest freemocap/tests/pipelines/ -v -m 'not slow' --timeout=600 --timeout-method=thread", help = "E2E pipeline tests minus the slow full-skeleton realtime case" }
test-all = { sequence = ["test"], help = "Run all backend tests (run `npm test` in freemocap-ui/ separately for frontend)" }
+# ── Version bumping (bumpver) ───────────────────────────────────────────
+# The canonical version lives in [tool.bumpver] current_version (pyproject.toml).
+# bumpver rewrites it into the Python package, Electron package.json, and docs
+# in each ecosystem's format, then commits + tags + pushes (see [tool.bumpver]).
+#
+# --ignore-vcs-tag skips the stale v1.x git tags (git describe finds v1.4.7 on
+# `development`, which predates the v2 rewrite). Add --dry to preview any bump.
+version = { cmd = "bumpver show", help = "Show the current canonical version" }
+bump-alpha = { cmd = "bumpver update --tag=alpha --tag-num --ignore-vcs-tag", help = "Bump alpha number: v2.0.0-alpha.2 -> v2.0.0-alpha.3" }
+bump-beta = { cmd = "bumpver update --tag=beta --ignore-vcs-tag", help = "Promote to beta: v2.0.0-alpha.X -> v2.0.0-beta.0" }
+bump-rc = { cmd = "bumpver update --tag=rc --ignore-vcs-tag", help = "Promote to rc: v2.0.0-beta.X -> v2.0.0-rc.0" }
+bump-final = { cmd = "bumpver update --tag=final --ignore-vcs-tag", help = "Promote to final: v2.0.0-rc.X -> v2.0.0" }
+bump-minor = { cmd = "bumpver update --minor --tag=alpha --tag-num --ignore-vcs-tag", help = "Next minor alpha: v2.0.0 -> v2.1.0-alpha.0" }
+bump-major = { cmd = "bumpver update --major --tag=alpha --tag-num --ignore-vcs-tag", help = "Next major alpha: v2.0.0 -> v3.0.0-alpha.0" }
+
[tool.poe.tasks.test-ui]
cmd = "npm run test"
cwd = "freemocap-ui"
diff --git a/pyproject.toml b/pyproject.toml
index 443f67cb..ed99dbc5 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -1,7 +1,7 @@
[project]
name = "freemocap"
-version = "0.1.0"
-description = "Add your description here"
+version = "2.0.0a2" # bumpver
+description = "A free and open source markerless motion capture system for everyone πŸ’€βœ¨"
readme = "README.md"
requires-python = ">=3.11"
dependencies = [
@@ -102,18 +102,35 @@ name = "rtmlib"
version = "0.0.14"
requires-dist = ["numpy", "opencv-contrib-python", "opencv-python", "tqdm"]
+# ---- Version Bumping (bumpver) ----
+# Run with: uv run poe bump-alpha (see [tool.poe.tasks] in poe_tasks.toml)
+#
+# `current_version` below is the ONE canonical version. bumpver writes it to
+# every file in the format that ecosystem requires:
+# - pyproject.toml `version` PEP 440, e.g. 2.0.0a2 (pip/uv)
+# - freemocap/__init__.py `__version__` display, e.g. v2.0.0-alpha.2 (Python runtime)
+# - freemocap-ui/package.json `version` npm semver, e.g. 2.0.0-alpha.2 (Electron)
+# - freemocap-docs .../downloads.ts display, e.g. 2.0.0-alpha.2 (docs site)
+#
+# The v2 rewrite lives on `development`, which branched before the v1.5+ tags,
+# so `git describe` still resolves to v1.4.7. Every bump command therefore passes
+# --ignore-vcs-tag to bypass those stale VCS tags (baked into the poe tasks).
[tool.bumpver]
-current_version = "v1.4.7"
-version_pattern = "vMAJOR.MINOR.PATCH[-TAG]"
+current_version = "v2.0.0-alpha.2"
+version_pattern = "vMAJOR.MINOR.PATCH[-TAG.NUM]"
commit_message = "Bump version {old_version} -> {new_version}"
commit = true
tag = true
push = true
[tool.bumpver.file_patterns]
-#"pyproject.toml" = ['current_version = "{version}"', 'version = "{version}"']
-"freemocap/__init__.py" = ["{version}"]
-".github/workflows/*_installer.yml" = ['export PYAPP_PROJECT_VERSION={version}']
+# The `# bumpver` marker pins this to the [project] version line ONLY β€” a bare
+# `version = "..."` pattern also matches the rtmlib [[tool.uv.dependency-metadata]]
+# pin above and clobbers it. (Both the marker and that pin go away when rtmlib does.)
+"pyproject.toml" = ['version = "{pep440_version}" # bumpver']
+"freemocap/__init__.py" = ['__version__ = "{version}"']
+"freemocap-ui/package.json" = ['"version": "MAJOR.MINOR.PATCH[-TAG.NUM]"']
+"freemocap-docs/src/components/download/data/downloads.ts" = ["DEFAULT_VERSION = 'MAJOR.MINOR.PATCH[-TAG.NUM]'"]