Skip to content

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

TypeScript

chkpt

jonmatthis6bf3ef4d0a21
diff --git a/freemocap-ui-old/electron-old/main/services/update-handler.ts b/freemocap-ui-old/electron-old/main/services/update-handler.ts
new file mode 100644
index 00000000..35bb6182
--- /dev/null
+++ b/freemocap-ui-old/electron-old/main/services/update-handler.ts
@@ -0,0 +1,72 @@
+
+import { app, ipcMain, BrowserWindow } from 'electron';
+import { autoUpdater } from 'electron-updater';
+
+export class UpdateHandler {
+ private mainWindow: BrowserWindow;
+
+ constructor(window: BrowserWindow) {
+ this.mainWindow = window;
+ this.setupAutoUpdater();
+ this.registerIpcHandlers();
+ }
+
+ private setupAutoUpdater() {
+ autoUpdater.autoDownload = false;
+ autoUpdater.disableWebInstaller = false;
+ autoUpdater.allowDowngrade = false;
+
+ autoUpdater.on('checking-for-update', () => {
+ console.log('Checking for updates...');
+ });
+
+ autoUpdater.on('update-available', (info) => {
+ console.log('Update available:', info);
+ this.mainWindow.webContents.send('update-available', {
+ version: info.version,
+ currentVersion: app.getVersion(),
+ });
+ });
+
+ autoUpdater.on('update-not-available', () => {
+ console.log('No updates available');
+ });
+
+ autoUpdater.on('download-progress', (progress) => {
+ this.mainWindow.webContents.send('download-progress', progress);
+ });
+
+ autoUpdater.on('update-downloaded', () => {
+ this.mainWindow.webContents.send('update-downloaded');
+ });
+
+ autoUpdater.on('error', (error) => {
+ console.error('Update error:', error);
+ this.mainWindow.webContents.send('update-error', error);
+ });
+ }
+
+ private registerIpcHandlers() {
+ ipcMain.handle('check-update', async () => {
+ if (!app.isPackaged) {
+ return {
+ error: 'Updates only work in packaged app',
+ available: false
+ };
+ }
+ return await autoUpdater.checkForUpdatesAndNotify();
+ });
+
+ ipcMain.handle('download-update', async () => {
+ return await autoUpdater.downloadUpdate();
+ });
+
+ ipcMain.handle('install-update', () => {
+ autoUpdater.quitAndInstall(false, true);
+ });
+ }
+
+ static initialize(window: BrowserWindow) {
+ return new UpdateHandler(window);
+ }
+}
diff --git a/freemocap/api/http/calibration/calibration_router.py b/freemocap/api/http/calibration/calibration_router.py
index d4dccb1e..ca68d0a2 100644
--- a/freemocap/api/http/calibration/calibration_router.py
+++ b/freemocap/api/http/calibration/calibration_router.py
@@ -2,13 +2,25 @@ import logging
from copy import deepcopy
from pathlib import Path
+import numpy as np
+import toml
from fastapi import APIRouter, HTTPException
-from pydantic import BaseModel, Field
+from pydantic import BaseModel, Field, ValidationError, ConfigDict
from skellycam.core.recorders.videos.recording_info import RecordingInfo
from freemocap.app.freemocap_application import get_freemocap_app
+from freemocap.core.calibration.shared.calibration_models import CalibrationResult
+from freemocap.core.calibration.shared.feet_groundplane import (
+ estimate_groundplane_from_feet,
+ build_mediapipe_body_marker_name_to_index,
+)
+from freemocap.core.calibration.shared.groundplane_alignment import (
+ apply_groundplane_to_cameras,
+ groundplane_metadata,
+)
from freemocap.core.pipeline.pipeline_configs import CalibrationPipelineConfig
from freemocap.system.default_paths import FREEMOCAP_TEST_DATA_PATH
+from freemocap.utilities.toml_mixin import numpy_to_python
logger = logging.getLogger(__name__)
@@ -26,23 +38,40 @@ class CalibrationConfigResponse(BaseModel):
success: bool
message: str | None = None
-class CalibrateRecordingRequest(BaseModel):
- calibration_recording_directory: str = Field(alias="calibrationRecordingDirectory")
- calibration_config: CalibrationPipelineConfig = Field(alias="calibrationTaskConfig",
- default=CalibrationPipelineConfig)
+def _calibrate_request_schema_extra(schema: dict) -> None:
+ schema["examples"] = [CalibrateRecordingRequest.create_test_data_request().model_dump(by_alias=True)]
+
+class CalibrateRecordingRequest(BaseModel):
+ model_config = ConfigDict(
+ populate_by_name=True,
+ json_schema_extra=_calibrate_request_schema_extra,
+ )
+ calibration_config: CalibrationPipelineConfig = Field(
+ alias="calibrationTaskConfig",
+ default_factory=CalibrationPipelineConfig,
+ )
def to_recording_info(self) -> RecordingInfo:
- recording_dir = Path(self.calibration_recording_directory).expanduser()
+ if self.calibration_config.calibration_recording_folder is None:
+ raise ValidationError("CalibrationConfig.calibration_recording_folder not set")
+ recording_dir = Path(self.calibration_config.calibration_recording_folder).expanduser()
return RecordingInfo(
recording_directory=str(recording_dir.parent),
recording_name=recording_dir.stem,
mic_device_index=-1,
)
-class StartCalibrationRecordingRequest(CalibrateRecordingRequest):
- # StartCalibrationRecording needs same info as CalibrateRecording. Duplicating request for pattern
- pass
+ @classmethod
+ def create_test_data_request(cls) -> "CalibrateRecordingRequest":
+ config = CalibrationPipelineConfig()
+ config.calibration_recording_folder = FREEMOCAP_TEST_DATA_PATH
+ config.charuco_board_x_squares = 7
+ config.charuco_board_y_squares = 5
+ config.charuco_square_length = 54
+ return cls(calibration_config=config)
+
+
class StopCalibrationRecordingRequest(BaseModel):
@@ -92,7 +121,7 @@ def update_all_calibration_config(request: CalibrationConfigRequest) -> Calibrat
@calibration_router.post("/recording/start")
async def start_calibration_recording(
- request: StartCalibrationRecordingRequest,
+ request: CalibrateRecordingRequest,
) -> StartCalibrationRecordingResponse:
"""Start calibration recording with given config."""
try:
@@ -146,3 +175,122 @@ async def calibrate_recording(request: CalibrateRecordingRequest) -> CalibrateRe
except Exception as e:
logger.exception(f"Error calibrating recording: {e}")
raise HTTPException(status_code=500, detail=str(e))
+
+
+class ApplyFeetGroundplaneRequest(BaseModel):
+ model_config = ConfigDict(populate_by_name=True)
+
+ recording_folder: str = Field(alias="recordingFolder")
+ force: bool = Field(
+ default=False,
+ description="Re-estimate groundplane even if one was already applied.",
+ )
+
+
+class ApplyFeetGroundplaneResponse(BaseModel):
+ success: bool
+ message: str | None = None
+ method: str | None = None
+
+
+@calibration_router.post("/apply-feet-groundplane")
+def apply_feet_groundplane(
+ request: ApplyFeetGroundplaneRequest,
+) -> ApplyFeetGroundplaneResponse:
+ """Manually apply feet-based ground plane to an existing calibration.
+
+ Loads the calibration TOML and skeleton 3D data from the recording folder,
+ estimates the ground plane from foot markers, updates the camera extrinsics,
+ and re-saves the TOML.
+
+ Skips if groundplane was already applied, unless force=True.
+ """
+ try:
+ recording_folder = Path(request.recording_folder).expanduser()
+ output_folder = recording_folder / "output_data"
+
+ # Find calibration TOML in recording folder
+ toml_candidates = list(recording_folder.glob("*_camera_calibration.toml"))
+ if not toml_candidates:
+ raise HTTPException(
+ status_code=404,
+ detail=f"No calibration TOML found in {recording_folder}",
+ )
+ calibration_toml_path = toml_candidates[0]
+
+ # Check if groundplane already applied
+ if not request.force:
+ toml_data = toml.loads(calibration_toml_path.read_text())
+ metadata = toml_data.get("metadata", {})
+ if metadata.get("groundplane_applied", False):
+ return ApplyFeetGroundplaneResponse(
+ success=True,
+ message=f"Groundplane already applied (method: {metadata.get('groundplane_method', 'unknown')}). Use force=true to re-estimate.",
+ method=metadata.get("groundplane_method"),
+ )
+
+ # Load skeleton 3D body data
+ body_npy_candidates = list(output_folder.glob("*body*3d*.npy"))
+ if not body_npy_candidates:
+ # Try the combined skeleton file
+ body_npy_candidates = list(output_folder.glob("*skeleton_3d.npy"))
+
+ if not body_npy_candidates:
+ raise HTTPException(
+ status_code=404,
+ detail=f"No body 3D data found in {output_folder}",
+ )
+
+ body_3d = np.load(body_npy_candidates[0])
+ marker_name_to_index = build_mediapipe_body_marker_name_to_index()
+
+ # If we loaded the full skeleton (body+hands+face), take only body portion (first 33)
+ if body_3d.shape[1] > 33:
+ body_3d = body_3d[:, :33, :]
+
+ ground_plane = estimate_groundplane_from_feet(
+ skeleton_3d=body_3d,
+ marker_name_to_index=marker_name_to_index,
+ )
+
+ if ground_plane is None:
+ return ApplyFeetGroundplaneResponse(
+ success=False,
+ message="Could not estimate ground plane from foot markers (missing data or markers)",
+ )
+
+ # Load calibration, apply, re-save
+ calibration = CalibrationResult.load_anipose_toml(calibration_toml_path)
+ updated_cameras = apply_groundplane_to_cameras(calibration.cameras, ground_plane)
+
+ toml_data = toml.loads(calibration_toml_path.read_text())
+ existing_metadata = toml_data.get("metadata", {})
+ existing_metadata.update(groundplane_metadata(ground_plane, recording_folder.stem))
+
+ updated_result = CalibrationResult(
+ cameras=updated_cameras,
+ board=calibration.board,
+ reprojection_error_px=calibration.reprojection_error_px,
+ initial_cost=calibration.initial_cost,
+ final_cost=calibration.final_cost,
+ n_iterations=calibration.n_iterations,
+ time_seconds=calibration.time_seconds,
+ n_observations_used=calibration.n_observations_used,
+ n_observations_rejected=calibration.n_observations_rejected,
+ )
+ updated_result.dump_anipose_toml(
+ path=calibration_toml_path,
+ metadata=numpy_to_python(existing_metadata),
+ )
+
+ return ApplyFeetGroundplaneResponse(
+ success=True,
+ message="Feet-based ground plane applied to calibration",
+ method="feet",
+ )
+
+ except HTTPException:
+ raise
+ except Exception as e:
+ logger.exception(f"Error applying feet ground plane: {e}")
+ raise HTTPException(status_code=500, detail=str(e))
diff --git a/freemocap/api/http/mocap/mocap_router.py b/freemocap/api/http/mocap/mocap_router.py
index fe1bf55e..9b093976 100644
--- a/freemocap/api/http/mocap/mocap_router.py
+++ b/freemocap/api/http/mocap/mocap_router.py
@@ -3,11 +3,11 @@ from copy import deepcopy
from pathlib import Path
from fastapi import APIRouter, HTTPException
-from pydantic import BaseModel, Field
+from pydantic import BaseModel, ConfigDict, Field
from skellycam.core.recorders.videos.recording_info import RecordingInfo
from freemocap.app.freemocap_application import get_freemocap_app
-from freemocap.core.pipeline.pipeline_configs import MocapPipelineConfig
+from freemocap.core.pipeline.pipeline_configs import CalibrationSource, MocapPipelineConfig
from freemocap.system.default_paths import FREEMOCAP_TEST_DATA_PATH
logger = logging.getLogger(__name__)
@@ -47,10 +47,24 @@ class StopMocapRecordingRequest(BaseModel):
mocap_config: MocapPipelineConfig = Field(alias="mocapTaskConfig")
+def _process_mocap_request_schema_extra(schema: dict) -> None:
+ schema["examples"] = [ProcessMocapRecordingRequest.create_test_data_request().model_dump()]
+
+
class ProcessMocapRecordingRequest(BaseModel):
- mocap_recording_directory: str = Field( default=FREEMOCAP_TEST_DATA_PATH)
+ model_config = ConfigDict(json_schema_extra=_process_mocap_request_schema_extra)
+ mocap_recording_directory: str = Field(default=FREEMOCAP_TEST_DATA_PATH)
mocap_config: MocapPipelineConfig = Field(default_factory=MocapPipelineConfig)
+ @classmethod
+ def create_test_data_request(cls) -> "ProcessMocapRecordingRequest":
+ config = MocapPipelineConfig()
+ config.calibration_source = CalibrationSource.MOST_RECENT
+ return cls(
+ mocap_recording_directory=FREEMOCAP_TEST_DATA_PATH,
+ mocap_config=config,
+ )
+
def to_recording_info(self) -> RecordingInfo:
recording_dir = Path(self.mocap_recording_directory).expanduser()
return RecordingInfo(
diff --git a/freemocap/core/calibration/anipose_calibration/helpers/calibration_helpers.py b/freemocap/core/calibration/anipose_calibration/helpers/calibration_helpers.py
index 085c3de0..61b9b120 100644
--- a/freemocap/core/calibration/anipose_calibration/helpers/calibration_helpers.py
+++ b/freemocap/core/calibration/anipose_calibration/helpers/calibration_helpers.py
@@ -16,6 +16,7 @@ from skellytracker.trackers.charuco_tracker.charuco_observation import CharucoOb
from freemocap.core.calibration.anipose_calibration.helpers.freemocap_anipose import AniposeCameraGroup, \
AniposeCharucoBoard
+from freemocap.core.calibration.shared.groundplane_alignment import GroundPlaneResult
from freemocap.core.calibration.shared.groundplane_math import find_still_charuco_frame, CharucoVisibilityError, \
CharucoVelocityError, compute_board_basis_vectors
from freemocap.core.types.type_overloads import VideoIdString
@@ -110,7 +111,7 @@ def set_charuco_board_as_groundplane(
anipose_camera_group: AniposeCameraGroup,
anipose_charuco_board: AniposeCharucoBoard,
recording_folder_path: "Path | None" = None,
-) -> tuple[AniposeCameraGroup, GroundPlaneSuccess]:
+) -> tuple[AniposeCameraGroup, GroundPlaneSuccess, GroundPlaneResult | None]:
"""Set the charuco board plane as the world groundplane."""
logger.info("Getting 2D Charuco data")
data2d_by_video: dict[VideoIdString, np.ndarray] = {}
@@ -147,10 +148,10 @@ def set_charuco_board_as_groundplane(
)
except CharucoVisibilityError as e:
logger.warning("Ground-plane alignment skipped β€” reverting to original calibration: %s", e, exc_info=True)
- return anipose_camera_group, GroundPlaneSuccess(success=False, error=str(e))
+ return anipose_camera_group, GroundPlaneSuccess(success=False, error=str(e)), None
except CharucoVelocityError as e:
logger.warning("Ground-plane alignment skipped β€” reverting to original calibration: %s", e, exc_info=True)
- return anipose_camera_group, GroundPlaneSuccess(success=False, error=str(e))
+ return anipose_camera_group, GroundPlaneSuccess(success=False, error=str(e)), None
charuco_frame = charuco_3d_xyz_interpolated[charuco_still_frame_idx]
@@ -163,6 +164,12 @@ def set_charuco_board_as_groundplane(
charuco_origin_in_world = charuco_frame[0]
rmat_charuco_to_world = np.column_stack([x_hat, y_hat, z_hat])
+ ground_plane_result = GroundPlaneResult(
+ origin=charuco_origin_in_world,
+ rotation_matrix=rmat_charuco_to_world,
+ method="charuco",
+ )
+
rvecs_new, tvecs_new = _adjust_world_reference_frame_to_charuco(
camera_group=anipose_camera_group,
charuco_origin_in_world=charuco_origin_in_world,
@@ -185,7 +192,7 @@ def set_charuco_board_as_groundplane(
np.save(charuco_save_path, charuco_3d_xyz_interpolated)
logger.info(f"Charuco 3d data saved to {charuco_save_path}")
- return anipose_camera_group, GroundPlaneSuccess(success=True)
+ return anipose_camera_group, GroundPlaneSuccess(success=True), ground_plane_result
def _adjust_world_reference_frame_to_charuco(
diff --git a/freemocap/core/calibration/anipose_calibration/run_anipose_calibration.py b/freemocap/core/calibration/anipose_calibration/run_anipose_calibration.py
index 70518a7a..d8e79f62 100644
--- a/freemocap/core/calibration/anipose_calibration/run_anipose_calibration.py
+++ b/freemocap/core/calibration/anipose_calibration/run_anipose_calibration.py
@@ -19,6 +19,7 @@ from freemocap.core.calibration.anipose_calibration.helpers.calibration_helpers
set_charuco_board_as_groundplane, get_real_world_matrices
from freemocap.core.calibration.anipose_calibration.helpers.freemocap_anipose import AniposeCamera, AniposeCameraGroup
from freemocap.core.calibration.shared.calibration_models import CharucoBoardDefinition, CalibrationResult
+from freemocap.core.calibration.shared.groundplane_alignment import GroundPlaneResult
from freemocap.core.calibration.shared.charuco_observation_aggregator import CharucoObservationAggregator
from freemocap.core.pipeline.pipeline_configs import CalibrationPipelineConfig
from freemocap.core.pipeline.posthoc.video_group_helper import VideoMetadata
@@ -39,7 +40,7 @@ def run_anipose_calibration(
init_intrinsics: bool = True,
init_extrinsics: bool = True,
verbose: bool = True,
-) -> CalibrationResult:
+) -> tuple[CalibrationResult, GroundPlaneResult | None]:
"""Run anipose calibration from charuco observations.
Returns a CalibrationResult with optimized camera models.
@@ -98,6 +99,7 @@ def run_anipose_calibration(
logger.info("Pinned camera 0 to origin")
# Ground plane correction
+ ground_plane_result: GroundPlaneResult | None = None
if use_charuco_as_groundplane:
observation_recorders_by_video: dict[VideoIdString, BaseRecorder] = {
video_id: BaseRecorder() for video_id in charuco_observations_by_frame[0].keys()
@@ -112,7 +114,7 @@ def run_anipose_calibration(
for video_id, recorder in observation_recorders_by_video.items():
recorder.add_observation(observation=charuco_observations_by_camera[video_id])
- anipose_camera_group, groundplane_success = set_charuco_board_as_groundplane(
+ anipose_camera_group, groundplane_success, ground_plane_result = set_charuco_board_as_groundplane(
observation_recorders=observation_recorders_by_video,
anipose_camera_group=anipose_camera_group,
anipose_charuco_board=anipose_charuco_board,
@@ -132,7 +134,7 @@ def run_anipose_calibration(
elapsed = time.monotonic() - t_start
- return CalibrationResult(
+ result = CalibrationResult(
cameras=camera_models,
board=board,
reprojection_error_px=float(error),
@@ -143,3 +145,4 @@ def run_anipose_calibration(
n_observations_used=len(charuco_frame_numbers) * len(camera_models),
n_observations_rejected=0,
)
+ return result, ground_plane_result
diff --git a/freemocap/core/calibration/calibration_task.py b/freemocap/core/calibration/calibration_task.py
index 40a51ea3..715566a8 100644
--- a/freemocap/core/calibration/calibration_task.py
+++ b/freemocap/core/calibration/calibration_task.py
@@ -25,6 +25,7 @@ from freemocap.core.calibration.anipose_calibration.run_anipose_calibration impo
from freemocap.core.calibration.pyceres_calibration.pyceres_calibration_pipeline import run_pyceres_calibration
from freemocap.core.calibration.shared.calibration_models import CharucoBoardDefinition, CharucoCornersObservation, \
CornerObservation, CalibrationResult
+from freemocap.core.calibration.shared.groundplane_alignment import GroundPlaneResult, groundplane_metadata
from freemocap.core.calibration.shared.calibration_paths import get_last_successful_calibration_toml_path
from freemocap.core.calibration.shared.calibration_save import save_calibration_copies
from freemocap.utilities.toml_mixin import numpy_to_python
@@ -122,12 +123,15 @@ def _save_result(
result: CalibrationResult,
recording_info: RecordingInfo,
solver_method: str,
+ ground_plane: GroundPlaneResult | None = None,
) -> Path:
"""Save CalibrationResult to all standard locations via anipose-compatible TOML."""
- metadata = {
+ metadata: dict = {
"solver_method": solver_method,
"recording_info": recording_info.model_dump(),
}
+ if ground_plane is not None:
+ metadata.update(groundplane_metadata(ground_plane, recording_info.recording_name))
recording_toml = save_calibration_copies(
save_fn=lambda path: result.dump_anipose_toml(path=path, metadata=metadata),
@@ -149,7 +153,7 @@ def _run_pyceres_path(
board: CharucoBoardDefinition,
task_config: CalibrationPipelineConfig,
video_metadata: dict[VideoIdString, VideoMetadata],
-) -> CalibrationResult:
+) -> tuple[CalibrationResult, GroundPlaneResult | None]:
"""Run calibration using the pyceres bundle adjustment solver."""
if len(all_observations) == 0:
raise ValueError("No valid charuco observations found")
@@ -160,7 +164,7 @@ def _run_pyceres_path(
for vid_id, vm in video_metadata.items()
}
- result = run_pyceres_calibration(
+ result, ground_plane = run_pyceres_calibration(
board=board,
all_observations=all_observations,
image_sizes=image_sizes,
@@ -174,7 +178,7 @@ def _run_pyceres_path(
f"reprojection error: {result.reprojection_error_px:.4f}px, "
f"time: {result.time_seconds:.2f}s"
)
- return result
+ return result, ground_plane
# =============================================================================
@@ -189,23 +193,24 @@ def _run_anipose_path(
task_config: CalibrationPipelineConfig,
recording_info: RecordingInfo,
video_metadata: dict[VideoIdString, VideoMetadata],
-) -> CalibrationResult:
+) -> tuple[CalibrationResult, GroundPlaneResult | None]:
"""Run calibration using the legacy anipose solver."""
logger.info("Starting anipose calibration...")
- result = run_anipose_calibration(
+ result, ground_plane = run_anipose_calibration(
charuco_observations_by_frame=charuco_observations_by_frame,
board=board,
calibration_pipeline_config=task_config,
recording_info=recording_info,
video_metadata=video_metadata,
+ use_charuco_as_groundplane=task_config.use_groundplane,
)
logger.info(
f"Anipose calibration complete β€” "
f"reprojection error: {result.reprojection_error_px:.4f}px"
)
- return result
+ return result, ground_plane
# =============================================================================
@@ -261,9 +266,10 @@ def run_calibration_task(
# ---- Route to solver ----
logger.info(f"Using calibration solver: {task_config.solver_method.value}")
+ ground_plane: GroundPlaneResult | None = None
match task_config.solver_method:
case CalibrationSolverMethod.ANIPOSE:
- result = _run_anipose_path(
+ result, ground_plane = _run_anipose_path(
charuco_observations_by_frame=charuco_observations_by_frame,
board=board,
task_config=task_config,
@@ -271,7 +277,7 @@ def run_calibration_task(
video_metadata=video_metadata,
)
case CalibrationSolverMethod.PYCERES:
- result = _run_pyceres_path(
+ result, ground_plane = _run_pyceres_path(
all_observations=all_observations,
board=board,
task_config=task_config,
@@ -285,6 +291,7 @@ def run_calibration_task(
result=result,
recording_info=recording_info,
solver_method=task_config.solver_method.value,
+ ground_plane=ground_plane,
)
# ---- Log calibration health (including board reconstruction accuracy) ----
diff --git a/freemocap/core/calibration/pyceres_calibration/helpers/postprocessing.py b/freemocap/core/calibration/pyceres_calibration/helpers/postprocessing.py
index 5bc0060d..75c08044 100644
--- a/freemocap/core/calibration/pyceres_calibration/helpers/postprocessing.py
+++ b/freemocap/core/calibration/pyceres_calibration/helpers/postprocessing.py
@@ -12,6 +12,7 @@ from scipy.spatial.transform import Rotation
from freemocap.core.calibration.shared.calibration_models import CameraModel, CameraExtrinsics, \
CharucoCornersObservation, CharucoBoardDefinition
+from freemocap.core.calibration.shared.groundplane_alignment import GroundPlaneResult, apply_groundplane_to_cameras
from freemocap.core.calibration.shared.groundplane_math import find_still_charuco_frame, compute_board_basis_vectors
logger = logging.getLogger(__name__)
@@ -156,16 +157,16 @@ def _triangulate_charuco_corners(
return result
-def align_to_charuco_groundplane(
+def estimate_charuco_groundplane(
*,
cameras: list[CameraModel],
board: CharucoBoardDefinition,
all_observations: list[CharucoCornersObservation],
-) -> list[CameraModel]:
- """Transform the world frame so the charuco board defines the ground plane.
+) -> GroundPlaneResult:
+ """Estimate the ground plane from charuco board observations.
- The charuco board's origin corner becomes the world origin, its X edge
- defines +X, and the board normal defines +Z (up).
+ Triangulates charuco corners, finds a stationary frame, and computes
+ orthonormal basis vectors from the board corners.
Args:
cameras: Calibrated camera models.
@@ -173,18 +174,16 @@ def align_to_charuco_groundplane(
all_observations: All frame observations for triangulation.
Returns:
- Camera models with extrinsics adjusted to the new world frame.
+ GroundPlaneResult with origin at board corner 0 and basis from board edges.
"""
- logger.info("Aligning world frame to charuco ground plane...")
+ logger.info("Estimating ground plane from charuco board...")
- # Triangulate all charuco corners
charuco_3d = _triangulate_charuco_corners(
cameras=cameras,
all_observations=all_observations,
board=board,
)
- # Find a stationary frame
still_frame_idx = find_still_charuco_frame(
charuco_3d=charuco_3d,
squares_x=board.squares_x,
@@ -194,7 +193,6 @@ def align_to_charuco_groundplane(
frame_corners = charuco_3d[still_frame_idx]
- # Validate key corners are visible
origin = frame_corners[0]
if np.isnan(origin).any():
raise RuntimeError(
@@ -202,46 +200,41 @@ def align_to_charuco_groundplane(
"Cannot establish ground plane."
)
- # Compute orthonormal basis from the board corners
x_hat, y_hat, z_hat = compute_board_basis_vectors(
charuco_frame=frame_corners,
squares_x=board.squares_x,
squares_y=board.squares_y,
)
- # Rotation from charuco frame to current world frame
- R_charuco_to_world = np.column_stack([x_hat, y_hat, z_hat])
-
- # Transform all cameras: new extrinsics map from "charuco world" to camera
- result: list[CameraModel] = []
- for cam in cameras:
- R_cam = cam.extrinsics.rotation_matrix
- t_cam = cam.extrinsics.translation
+ return GroundPlaneResult(
+ origin=origin,
+ rotation_matrix=np.column_stack([x_hat, y_hat, z_hat]),
+ method="charuco",
+ )
- # Shift origin, then rotate
- t_delta = R_cam @ origin
- t_new = t_cam + t_delta
- # Compose with charuco-to-world rotation
- R_new = R_cam @ R_charuco_to_world
+def align_to_charuco_groundplane(
+ *,
+ cameras: list[CameraModel],
+ board: CharucoBoardDefinition,
+ all_observations: list[CharucoCornersObservation],
+) -> tuple[list[CameraModel], GroundPlaneResult]:
+ """Transform the world frame so the charuco board defines the ground plane.
- quat_xyzw = Rotation.from_matrix(R_new).as_quat()
- quat_wxyz = np.array(
- [quat_xyzw[3], quat_xyzw[0], quat_xyzw[1], quat_xyzw[2]],
- dtype=np.float64,
- )
+ The charuco board's origin corner becomes the world origin, its X edge
+ defines +X, and the board normal defines +Z (up).
- result.append(
- CameraModel(
- name=cam.name,
- image_size=cam.image_size,
- intrinsics=cam.intrinsics,
- extrinsics=CameraExtrinsics(
- quaternion_wxyz=quat_wxyz,
- translation=t_new,
- ),
- )
- )
+ Args:
+ cameras: Calibrated camera models.
+ board: Board definition.
+ all_observations: All frame observations for triangulation.
- logger.info("Ground plane alignment complete")
- return result
+ Returns:
+ Tuple of (camera models with adjusted extrinsics, ground plane result).
+ """
+ ground_plane = estimate_charuco_groundplane(
+ cameras=cameras,
+ board=board,
+ all_observations=all_observations,
+ )
+ return apply_groundplane_to_cameras(cameras, ground_plane), ground_plane
diff --git a/freemocap/core/calibration/pyceres_calibration/pyceres_calibration_pipeline.py b/freemocap/core/calibration/pyceres_calibration/pyceres_calibration_pipeline.py
index 34bccb41..02d99ef2 100644
--- a/freemocap/core/calibration/pyceres_calibration/pyceres_calibration_pipeline.py
+++ b/freemocap/core/calibration/pyceres_calibration/pyceres_calibration_pipeline.py
@@ -17,6 +17,7 @@ from freemocap.core.calibration.pyceres_calibration.helpers.initialization impor
from freemocap.core.calibration.pyceres_calibration.helpers.models import PyceresCalibrationSolverConfig
from freemocap.core.calibration.pyceres_calibration.helpers.postprocessing import pin_camera_to_origin, \
align_to_charuco_groundplane
+from freemocap.core.calibration.shared.groundplane_alignment import GroundPlaneResult
from freemocap.core.calibration.pyceres_calibration.helpers.solver import run_pyceres_bundle_adjustment
from freemocap.core.calibration.shared.calibration_models import CharucoBoardDefinition, CharucoCornersObservation, \
CalibrationResult, CameraModel
@@ -32,7 +33,7 @@ def run_pyceres_calibration(
camera_names: list[str],
config: PyceresCalibrationSolverConfig,
use_groundplane: bool = False,
-) -> CalibrationResult:
+) -> tuple[CalibrationResult, GroundPlaneResult | None]:
"""Run the complete camera calibration pipeline.
Args:
@@ -164,9 +165,10 @@ def run_pyceres_calibration(
camera_index=0,
)
+ ground_plane_result: GroundPlaneResult | None = None
if use_groundplane:
try:
- final_cameras = align_to_charuco_groundplane(
+ final_cameras, ground_plane_result = align_to_charuco_groundplane(
cameras=final_cameras,
board=board,
all_observations=all_observations,
@@ -205,4 +207,4 @@ def run_pyceres_calibration(
f"fx={cam.intrinsics.fx:.1f}, fy={cam.intrinsics.fy:.1f}"
)
- return result
+ return result, ground_plane_result
diff --git a/freemocap/core/calibration/shared/feet_groundplane.py b/freemocap/core/calibration/shared/feet_groundplane.py
new file mode 100644
index 00000000..e49138d5
--- /dev/null
+++ b/freemocap/core/calibration/shared/feet_groundplane.py
@@ -0,0 +1,148 @@
+"""Estimate ground plane from person's foot marker positions.
+
+Ported from skellyforge's Human.put_skeleton_on_ground() method.
+Returns a GroundPlaneResult that can be applied to camera extrinsics
+via apply_groundplane_to_cameras().
+"""
+
+import logging
+
+import numpy as np
+from numpy.typing import NDArray
+
+from freemocap.core.calibration.shared.groundplane_alignment import GroundPlaneResult
+
+logger = logging.getLogger(__name__)
+
+REQUIRED_FOOT_MARKERS = [
+ "left_heel",
+ "right_heel",
+ "left_foot_index",
+ "right_foot_index",
+]
+
+UP_DIRECTION_MARKERS = [
+ "left_shoulder",
+ "right_shoulder",
+]
+
+
+def _find_still_frame(trajectories: NDArray[np.float64]) -> int:
+ """Find frame where foot markers are most stationary.
+
+ Args:
+ trajectories: (n_frames, n_markers, 3) foot marker positions.
+
+ Returns:
+ Frame index with minimum maximum velocity across markers.
+ """
+ velocity = np.linalg.norm(np.diff(trajectories, axis=0), axis=2)
+ visible_frames = ~np.isnan(velocity).any(axis=1)
+
+ if not visible_frames.any():
+ raise ValueError("No frames with all foot markers visible")
+
+ max_velocity_per_frame = np.nanmax(velocity[visible_frames], axis=1)
+ lowest_velocity_idx = int(np.nanargmin(max_velocity_per_frame))
+ return int(np.where(visible_frames)[0][lowest_velocity_idx])
+
+
+def _get_unit_vector(vector: NDArray[np.float64]) -> NDArray[np.float64]:
+ norm = np.linalg.norm(vector)
+ if norm < 1e-10:
+ raise ValueError("Cannot normalize near-zero vector")
+ return vector / norm
+
+
+def estimate_groundplane_from_feet(
+ skeleton_3d: NDArray[np.float64],
+ marker_name_to_index: dict[str, int],
+) -> GroundPlaneResult | None:
+ """Estimate ground plane from foot marker positions.
+
+ Uses the skellyforge approach: find still frame, compute basis vectors
+ from foot positions and shoulder midpoint (neck_center proxy).
+
+ Args:
+ skeleton_3d: (n_frames, n_markers, 3) triangulated skeleton data.
+ marker_name_to_index: Mapping of marker names to indices in the
+ skeleton_3d array. Must contain left_heel, right_heel,
+ left_foot_index, right_foot_index, left_shoulder, right_shoulder.
+
+ Returns:
+ GroundPlaneResult, or None if required markers are missing.
+ """
+ # Validate required markers
+ all_required = REQUIRED_FOOT_MARKERS + UP_DIRECTION_MARKERS
+ missing = [m for m in all_required if m not in marker_name_to_index]
+ if missing:
+ logger.warning(f"Missing markers for feet ground plane: {missing}")
+ return None
+
+ # Extract foot trajectories: (n_frames, 4, 3)
+ foot_indices = [marker_name_to_index[m] for m in REQUIRED_FOOT_MARKERS]
+ foot_trajectories = skeleton_3d[:, foot_indices, :]
+
+ # Find still frame
+ try:
+ still_frame = _find_still_frame(foot_trajectories)
+ except ValueError as e:
+ logger.warning(f"Could not find still frame for feet ground plane: {e}")
+ return None
+
+ logger.info(f"Using frame {still_frame} for feet ground plane estimation")
+
+ # Center = mean of 4 foot markers at still frame
+ center = np.mean(foot_trajectories[still_frame], axis=0)
+ if np.isnan(center).any():
+ logger.warning("Foot marker center contains NaN at still frame")
+ return None
+
+ # Forward direction: center β†’ midpoint of foot_index markers
+ left_foot_index_pos = skeleton_3d[still_frame, marker_name_to_index["left_foot_index"]]
+ right_foot_index_pos = skeleton_3d[still_frame, marker_name_to_index["right_foot_index"]]
+ mid_foot_index = (left_foot_index_pos + right_foot_index_pos) / 2
+
+ # Up direction: center β†’ neck_center (midpoint of shoulders)
+ left_shoulder = skeleton_3d[still_frame, marker_name_to_index["left_shoulder"]]
+ right_shoulder = skeleton_3d[still_frame, marker_name_to_index["right_shoulder"]]
+ neck_center = (left_shoulder + right_shoulder) / 2
+
+ try:
+ forward = _get_unit_vector(mid_foot_index - center)
+ up = _get_unit_vector(neck_center - center)
+
+ x_hat = _get_unit_vector(np.cross(forward, up))
+ y_hat = _get_unit_vector(np.cross(up, x_hat))
+ z_hat = _get_unit_vector(np.cross(x_hat, y_hat))
+ except ValueError as e:
+ logger.warning(f"Could not compute basis vectors for feet ground plane: {e}")
+ return None
+
+ rotation_matrix = np.column_stack([x_hat, y_hat, z_hat])
+
+ return GroundPlaneResult(
+ origin=center,
+ rotation_matrix=rotation_matrix,
+ method="feet",
+ )
+
+
+def build_mediapipe_body_marker_name_to_index() -> dict[str, int]:
+ """Build marker name β†’ index mapping for mediapipe body landmarks.
+
+ The body landmarks are the first 33 markers in the mediapipe skeleton
+ array, in the order defined by mediapipe_model_info.yaml.
+ """
+ names = [
+ "nose", "left_eye_inner", "left_eye", "left_eye_outer",
+ "right_eye_inner", "right_eye", "right_eye_outer",
+ "left_ear", "right_ear", "mouth_left", "mouth_right",
+ "left_shoulder", "right_shoulder", "left_elbow", "right_elbow",
+ "left_wrist", "right_wrist", "left_pinky", "right_pinky",
+ "left_index", "right_index", "left_thumb", "right_thumb",
+ "left_hip", "right_hip", "left_knee", "right_knee",
+ "left_ankle", "right_ankle", "left_heel", "right_heel",
+ "left_foot_index", "right_foot_index",
+ ]
+ return {name: idx for idx, name in enumerate(names)}
diff --git a/freemocap/core/calibration/shared/groundplane_alignment.py b/freemocap/core/calibration/shared/groundplane_alignment.py
new file mode 100644
index 00000000..98fd6c17
--- /dev/null
+++ b/freemocap/core/calibration/shared/groundplane_alignment.py
@@ -0,0 +1,98 @@
+"""Shared ground plane alignment for camera calibration.
+
+Provides GroundPlaneResult (the output of any ground plane estimation method)
+and apply_groundplane_to_cameras (transforms camera extrinsics to a new world
+frame defined by the ground plane).
+
+Used by both charuco-based and feet-based ground plane estimation.
+"""
+
+import logging
+from dataclasses import dataclass
+
+import numpy as np
+from numpy.typing import NDArray
+from scipy.spatial.transform import Rotation
+
+from freemocap.core.calibration.shared.calibration_models import (
+ CameraExtrinsics,
+ CameraModel,
+)
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class GroundPlaneResult:
+ """Result of ground plane estimation from any method."""
+
+ origin: NDArray[np.float64] # (3,) world origin position
+ rotation_matrix: NDArray[np.float64] # (3,3) [x_hat | y_hat | z_hat]
+ method: str # "charuco" or "feet"
+
+
+def apply_groundplane_to_cameras(
+ cameras: list[CameraModel],
+ ground_plane: GroundPlaneResult,
+) -> list[CameraModel]:
+ """Apply ground plane transform to camera extrinsics.
+
+ Shifts the world origin to ground_plane.origin and rotates the world
+ frame so that the ground plane's basis vectors become the new axes.
+
+ Args:
+ cameras: Calibrated camera models.
+ ground_plane: Estimated ground plane (origin + rotation).
+
+ Returns:
+ Camera models with extrinsics adjusted to the new world frame.
+ """
+ origin = ground_plane.origin
+ R_ground_to_world = ground_plane.rotation_matrix
+
+ result: list[CameraModel] = []
+ for cam in cameras:
+ R_cam = cam.extrinsics.rotation_matrix
+ t_cam = cam.extrinsics.translation
+
+ # Shift origin, then rotate
+ t_delta = R_cam @ origin
+ t_new = t_cam + t_delta
+
+ # Compose with ground-to-world rotation
+ R_new = R_cam @ R_ground_to_world
+
+ quat_xyzw = Rotation.from_matrix(R_new).as_quat()
+ quat_wxyz = np.array(
+ [quat_xyzw[3], quat_xyzw[0], quat_xyzw[1], quat_xyzw[2]],
+ dtype=np.float64,
+ )
+
+ result.append(
+ CameraModel(
+ name=cam.name,
+ image_size=cam.image_size,
+ intrinsics=cam.intrinsics,
+ extrinsics=CameraExtrinsics(
+ quaternion_wxyz=quat_wxyz,
+ translation=t_new,
+ ),
+ )
+ )
+
+ logger.info(
+ f"Ground plane alignment complete (method: {ground_plane.method})"
+ )
+ return result
+
+
+def groundplane_metadata(
+ ground_plane: GroundPlaneResult,
+ recording_id: str,
+) -> dict:
+ """Return metadata dict to merge into calibration TOML."""
+ return {
+ "groundplane_applied": True,
+ "groundplane_method": ground_plane.method,
+ "groundplane_recording_id": recording_id,
+ }
diff --git a/freemocap/core/mocap/posthoc_mocap_task.py b/freemocap/core/mocap/posthoc_mocap_task.py
index 2fab5952..9857fcd3 100644
--- a/freemocap/core/mocap/posthoc_mocap_task.py
+++ b/freemocap/core/mocap/posthoc_mocap_task.py
@@ -6,10 +6,18 @@ Receives collected mediapipe observations, builds skeleton via triangulation.
Called by PosthocAggregationNode after all frames are collected.
Pre-bind task_config via functools.partial when creating the pipeline.
"""
+from __future__ import annotations
+
import logging
+import shutil
from collections.abc import Callable
from pathlib import Path
+from typing import TYPE_CHECKING
+
+import toml
+if TYPE_CHECKING:
+ from skellyforge.skellymodels.managers.human import Human
from skellycam.core.recorders.videos.recording_info import RecordingInfo
from skellytracker.trackers.base_tracker.base_tracker_abcs import BaseObservation, BaseRecorder
from skellytracker.trackers.legacy_mediapipe_tracker.legacy_mediapipe_observation import LegacyMediapipeObservations, \
@@ -18,12 +26,22 @@ from skellytracker.trackers.mediapipe_tracker import MediapipeObservation
from freemocap.core.blender.export_to_blender import export_to_blender
from freemocap.core.blender.helpers.get_best_guess_of_blender_path import get_best_guess_of_blender_path
+from freemocap.core.calibration.shared.calibration_models import CalibrationResult
from freemocap.core.calibration.shared.calibration_paths import get_last_successful_calibration_toml_path
+from freemocap.core.calibration.shared.feet_groundplane import (
+ estimate_groundplane_from_feet,
+ build_mediapipe_body_marker_name_to_index,
+)
+from freemocap.core.calibration.shared.groundplane_alignment import (
+ apply_groundplane_to_cameras,
+ groundplane_metadata,
+)
from freemocap.core.mocap.mocap_helpers.skeleton_from_mediapipe_observations import \
skeleton_from_mediapipe_observation_recorders
from freemocap.core.pipeline.pipeline_configs import MocapPipelineConfig
from freemocap.core.pipeline.posthoc.video_group_helper import VideoMetadata
from freemocap.core.types.type_overloads import VideoIdString
+from freemocap.utilities.toml_mixin import numpy_to_python
logger = logging.getLogger(__name__)
@@ -68,7 +86,10 @@ def run_post_mocap_aggregation_task(
observation_recorders[vid_id].add_observation(observation=obs)
# ---- Get calibration path ----
- if task_config.calibration_toml_path:
+ from freemocap.core.pipeline.pipeline_configs import CalibrationSource
+ if task_config.calibration_source == CalibrationSource.SPECIFIED:
+ if not task_config.calibration_toml_path:
+ raise RuntimeError("calibration_source is 'specified' but calibration_toml_path is not set.")
calibration_toml_path = Path(task_config.calibration_toml_path)
if not calibration_toml_path.exists():
raise RuntimeError(
@@ -84,6 +105,12 @@ def run_post_mocap_aggregation_task(
)
logger.info(f"Using most recent calibration TOML: {calibration_toml_path}")
+ # ---- Copy calibration file into recording folder ----
+ recording_folder = Path(recording_info.full_recording_path)
+ recording_calibration_copy = recording_folder / calibration_toml_path.name
+ shutil.copy2(calibration_toml_path, recording_calibration_copy)
+ logger.info(f"Copied calibration file to recording folder: {recording_calibration_copy}")
+
# ---- Run skeleton triangulation ----
if report_progress is not None:
report_progress("Triangulating skeleton", 0.3)
@@ -91,11 +118,20 @@ def run_post_mocap_aggregation_task(
output_folder = Path(recording_info.full_recording_path) / "output_data"
- skeleton_from_mediapipe_observation_recorders(
+ skeleton = skeleton_from_mediapipe_observation_recorders(
observation_recorders=observation_recorders,
path_to_calibration_toml=calibration_toml_path,
path_to_output_data_folder=output_folder,
)
+
+ # ---- Feet-based ground plane β†’ camera calibration update ----
+ _maybe_apply_feet_groundplane(
+ skeleton=skeleton,
+ calibration_toml_path=recording_calibration_copy,
+ recording_id=recording_info.recording_name,
+ task_config=task_config,
+ )
+
if create_blender_output:
export_to_blender(
@@ -106,3 +142,89 @@ def run_post_mocap_aggregation_task(
logger.info(
f"Posthoc mocap complete! Output saved to {output_folder}"
)
+
+
+def _maybe_apply_feet_groundplane(
+ *,
+ skeleton: "Human",
+ calibration_toml_path: Path,
+ recording_id: str,
+ task_config: MocapPipelineConfig,
+) -> None:
+ """Apply feet-based ground plane to camera calibration if appropriate.
+
+ Skips if:
+ - update_camera_positions_from_feet is False in config
+ - Ground plane was already applied during calibration (unless force_reestimate)
+ """
+ if not task_config.update_camera_positions_from_feet:
+ logger.debug("Feet ground plane update disabled in config")
+ return
+
+ # Check if groundplane was already applied during calibration
+ if not task_config.force_reestimate_groundplane:
+ try:
+ toml_data = toml.loads(calibration_toml_path.read_text())
+ metadata = toml_data.get("metadata", {})
+ if metadata.get("groundplane_applied", False):
+ logger.info(
+ f"Groundplane already applied (method: {metadata.get('groundplane_method', 'unknown')}), "
+ f"skipping feet-based estimation"
+ )
+ return
+ except Exception as e:
+ logger.warning(f"Could not read calibration TOML metadata: {e}")
+
+ # Get body 3D data from skeleton
+ try:
+ body_3d = skeleton.body.xyz.as_array # (n_frames, n_body_markers, 3)
+ except Exception as e:
+ logger.warning(f"Could not access body 3D data for feet ground plane: {e}")
+ return
+
+ marker_name_to_index = build_mediapipe_body_marker_name_to_index()
+
+ ground_plane = estimate_groundplane_from_feet(
+ skeleton_3d=body_3d,
+ marker_name_to_index=marker_name_to_index,
+ )
+
+ if ground_plane is None:
+ logger.warning("Feet ground plane estimation returned None β€” skipping camera update")
+ return
+
+ # Load calibration, apply ground plane, re-save
+ try:
+ calibration = CalibrationResult.load_anipose_toml(calibration_toml_path)
+ updated_cameras = apply_groundplane_to_cameras(calibration.cameras, ground_plane)
+
+ # Read existing TOML to preserve metadata, then update
+ toml_data = toml.loads(calibration_toml_path.read_text())
+ existing_metadata = toml_data.get("metadata", {})
+
+ # Merge groundplane metadata
+ gp_meta = groundplane_metadata(ground_plane, recording_id)
+ existing_metadata.update(gp_meta)
+
+ # Re-save with updated cameras and metadata
+ updated_result = CalibrationResult(
+ cameras=updated_cameras,
+ board=calibration.board,
+ reprojection_error_px=calibration.reprojection_error_px,
+ initial_cost=calibration.initial_cost,
+ final_cost=calibration.final_cost,
+ n_iterations=calibration.n_iterations,
+ time_seconds=calibration.time_seconds,
+ n_observations_used=calibration.n_observations_used,
+ n_observations_rejected=calibration.n_observations_rejected,
+ )
+ updated_result.dump_anipose_toml(
+ path=calibration_toml_path,
+ metadata=numpy_to_python(existing_metadata),
+ )
+ logger.info(
+ f"Updated calibration TOML with feet-based ground plane "
+ f"(recording: {recording_id})"
+ )
+ except Exception as e:
+ logger.warning(f"Failed to apply feet ground plane to calibration: {e}", exc_info=True)
diff --git a/freemocap/core/pipeline/pipeline_configs.py b/freemocap/core/pipeline/pipeline_configs.py
index d41d3cd2..07f815ff 100644
--- a/freemocap/core/pipeline/pipeline_configs.py
+++ b/freemocap/core/pipeline/pipeline_configs.py
@@ -76,6 +76,13 @@ class CalibrationSolverMethod(str, Enum):
PYCERES = "pyceres"
+class CalibrationSource(str, Enum):
+ """How to select the calibration TOML for a mocap pipeline run."""
+ MOST_RECENT = "most_recent"
+ SPECIFIED = "specified"
+ # FROM_ACTIVE_RECORDING = "from_active_recording" # NotImplemented
+
+
# ---------------------------------------------------------------------------
# Task configs
# ---------------------------------------------------------------------------
@@ -87,9 +94,9 @@ class CalibrationPipelineConfig(BaseModel):
calibration_recording_folder: str | None = Field(
default=None, alias="calibrationRecordingFolder",
)
- charuco_board_x_squares: int = Field(gt=0, default=7, alias="charucoBoardXSquares")
- charuco_board_y_squares: int = Field(gt=0, default=5, alias="charucoBoardYSquares")
- # charuco_square_length: float = Field(gt=0, default=1, alias="charucoSquareLength")
+ charuco_board_x_squares: int = Field(gt=0, default=5, alias="charucoBoardXSquares")
+ charuco_board_y_squares: int = Field(gt=0, default=3, alias="charucoBoardYSquares")
+ charuco_square_length: float = Field(gt=0, default=54, alias="charucoSquareLength", description="Length of one side of a black square on teh charuco board, default unit: mm")
solver_method: CalibrationSolverMethod = Field(
default=CalibrationSolverMethod.ANIPOSE,
@@ -150,10 +157,25 @@ class MocapPipelineConfig(BaseModel):
detector_config: DetectorConfig = Field(default_factory=LegacyMediapipeDetectorConfig)
realtime_filter_config: RealtimeFilterConfig = Field(default_factory=RealtimeFilterConfig)
+ calibration_source: CalibrationSource = Field(
+ default=CalibrationSource.MOST_RECENT,
+ alias="calibrationSource",
+ description="How to select the calibration: 'most_recent' uses the latest successful calibration, 'specified' uses calibration_toml_path.",
+ )
calibration_toml_path: str | None = Field(
default=None,
alias="calibrationTomlPath",
- description="Optional override for calibration TOML file. If None, uses the most recent successful calibration.",
+ description="Path to calibration TOML. Only used when calibration_source is 'specified'.",
+ )
+ update_camera_positions_from_feet: bool = Field(
+ default=True,
+ alias="updateCameraPositionsFromFeet",
+ description="If no groundplane was applied during calibration, estimate ground plane from foot markers and update camera extrinsics in the calibration TOML.",
+ )
+ force_reestimate_groundplane: bool = Field(
+ default=False,
+ alias="forceReestimateGroundplane",
+ description="Re-estimate groundplane even if one was already applied during calibration.",
)
@classmethod
diff --git a/freemocap/core/pipeline/posthoc/video_node.py b/freemocap/core/pipeline/posthoc/video_node.py
index c2cd5add..5ea224fc 100644
--- a/freemocap/core/pipeline/posthoc/video_node.py
+++ b/freemocap/core/pipeline/posthoc/video_node.py
@@ -100,6 +100,8 @@ class VideoNode(BaseNode):
existing_base_path = output_path.with_suffix(
f".prev{output_path.suffix}"
)
+ if existing_base_path.exists():
+ existing_base_path.unlink()
output_path.rename(existing_base_path)
logger.info(
f"Found existing annotated video for {video_path.stem}, "
@@ -142,9 +144,11 @@ class VideoNode(BaseNode):
if prev_annotated_path is not None:
base_reader = cv2.VideoCapture(str(prev_annotated_path), cv2.CAP_FFMPEG)
if not base_reader.isOpened():
- raise RuntimeError(
- f"Failed to open previous annotated video: {prev_annotated_path}"
+ logger.warning(
+ f"Failed to open previous annotated video for {video_path.stem} β€” "
+ f"will annotate from source frames instead"
)
+ base_reader = None
# Create video writer matching source video properties
fps = video_reader.get(cv2.CAP_PROP_FPS)
@@ -185,11 +189,15 @@ class VideoNode(BaseNode):
if base_reader is not None:
base_ok, base_frame = base_reader.read()
if not base_ok or base_frame is None:
- raise RuntimeError(
+ logger.warning(
f"Previous annotated video ran out of frames at frame {frame_number} "
- f"for {video_path.stem} β€” frame count mismatch with source video"
+ f"for {video_path.stem} β€” falling back to source frames"
)
- annotation_base = base_frame
+ base_reader.release()
+ base_reader = None
+ annotation_base = image
+ else:
+ annotation_base = base_frame
else:
annotation_base = image
diff --git a/uv.lock b/uv.lock
index c02d1764..9980e085 100644
--- a/uv.lock
+++ b/uv.lock
@@ -588,7 +588,7 @@ dev = [
[[package]]
name = "freemocap-blender-addon"
version = "2025.11.1038"
-source = { git = "https://github.com/freemocap/freemocap_blender_addon?branch=development#4429743282d867ee44e0ebb936041963dbf8a1de" }
+source = { git = "https://github.com/freemocap/freemocap_blender_addon?branch=development#e64d80125d5816b50f87006e54fe98c6f6415713" }
[[package]]
name = "h11"
@@ -2310,15 +2310,15 @@ wheels = [
[[package]]
name = "uvicorn"
-version = "0.43.0"
+version = "0.44.0"
source = { registry = "https://pypi.org/simple" }
dependencies = [
{ name = "click" },
{ name = "h11" },
]
-sdist = { url = "https://files.pythonhosted.org/packages/62/f2/368268300fb8af33743508d738ef7bb4d56afdb46c6d9c0fa3dd515df171/uvicorn-0.43.0.tar.gz", hash = "sha256:ab1652d2fb23abf124f36ccc399828558880def222c3cb3d98d24021520dc6e8", size = 85686, upload-time = "2026-04-03T18:37:48.984Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/5e/da/6eee1ff8b6cbeed47eeb5229749168e81eb4b7b999a1a15a7176e51410c9/uvicorn-0.44.0.tar.gz", hash = "sha256:6c942071b68f07e178264b9152f1f16dfac5da85880c4ce06366a96d70d4f31e", size = 86947, upload-time = "2026-04-06T09:23:22.826Z" }
wheels = [
- { url = "https://files.pythonhosted.org/packages/55/df/0cf5b0c451602748fdc7a702d4667f6e209bf96aa6e3160d754234445f2a/uvicorn-0.43.0-py3-none-any.whl", hash = "sha256:46fac64f487fd968cd999e5e49efbbe64bd231b5bd8b4a0b482a23ebce499620", size = 68591, upload-time = "2026-04-03T18:37:47.64Z" },
+ { url = "https://files.pythonhosted.org/packages/b7/23/a5bbd9600dd607411fa644c06ff4951bec3a4d82c4b852374024359c19c0/uvicorn-0.44.0-py3-none-any.whl", hash = "sha256:ce937c99a2cc70279556967274414c087888e8cec9f9c94644dfca11bd3ced89", size = 69425, upload-time = "2026-04-06T09:23:21.524Z" },
]
[[package]]