FreeMoCap v1.8.2 源码深度解析

1一句话定性

把 4–6 个普通 webcam / GoPro / 手机摄像头围成半圆，用 ChArUco 棋盘标定相机几何，MediaPipe 在每路视频上跑 2D 关键点，DLT + 加权异常点剔除三角化成 3D 骨架，Butterworth + 刚体约束后处理，最后 Blender 子进程导出 .blend 场景。所有计算本地 CPU 跑，数据不出设备。

官方话术 "实时动捕" 是录制时实时多机同步采集的实时，不是检测/三角化实时——后者是录完了离线后处理。这一点要在做决策前看清。

2依赖拓扑：算力在哪里

翻 pyproject.toml:68-84，依赖列表就是这个项目的真实地图：

3入口与主流程

3.1 程序入口

freemocap/__main__.py:24 — qt_gui_main() 是唯一入口，CLI 一行带过：

def main():
    ...
    qt_gui_main()  # gui/qt/main_window/freemocap_main.py:29-59

启动后进 PySide6 主事件循环，支持 EXIT_CODE_REBOOT 重启机制（freemocap_main.py:87）。

3.2 主窗口 5 大 Tab

MainWindow(QMainWindow) @ gui/qt/main_window/freemocap_main_window.py:92-150

右侧 ControlPanelWidget（widgets/control_panel/control_panel_dock_widget.py:32-62）3 子 Tab：摄像头配置 → 数据处理 → 导出。

3.3 端到端流水线

4标定 + 三角化（招牌核心）

4.1 CHARUCO 棋盘定义

core_processes/capture_volume_calibration/charuco_stuff/charuco_board_definition.py:7-44

@dataclass
class CharucoBoardDefinition:
    name: str
    number_of_squares_width: int
    number_of_squares_height: int
    black_square_side_length: int
    aruco_marker_length_proportional: float
    aruco_marker_dict: Dict = cv2.aruco.getPredefinedDictionary(cv2.aruco.DICT_4X4_250)

预设两块板：7×5（默认）和 5×3（小空间备选），都用 DICT_4X4_250 字典，marker = 0.8 × square。

4.2 标定流程

主入口：AniposeCameraCalibrator @ anipose_camera_calibration/anipose_camera_calibrator.py:42-87

1. 内参（每相机）：CameraGroup.calibrate_videos() @ freemocap_anipose.py:2178-2202，cv2.initCameraMatrix2D() 从 ChArUco 角点初始化（:2091）。
2. 外参初始化：get_initial_extrinsics() @ :499-513，调 aniposelib 的 extract_rtvecs。
3. 相机图连通性：get_calibration_graph() @ :387-403。
4. Bundle Adjustment 迭代：bundle_adjust_iter() @ :1145-1265。

4.3 三角化：Numba 加速的 DLT

freemocap_anipose.py:55-67

@jit(nopython=True, parallel=False)
def triangulate_simple(points, camera_mats):
    num_cams = len(camera_mats)
    A = np.zeros((num_cams * 2, 4))
    for i in range(num_cams):
        x, y = points[i]
        mat = camera_mats[i]
        A[(i * 2): (i * 2 + 1)] = x * mat[2] - mat[0]
        A[(i * 2 + 1): (i * 2 + 2)] = y * mat[2] - mat[1]
    u, s, vh = np.linalg.svd(A, full_matrices=True)
    p3d = vh[-1]
    p3d = p3d[:3] / p3d[3]  # 齐次坐标归一化
    return p3d

线性 DLT：构造 4×N 矩阵 → SVD → 取最小奇异向量 → 齐次归一。@jit(nopython=True) 让单点三角化贴近 C 速度。

4.4 招牌设计：加权异常点剔除三角化

freemocap_anipose.py:88-190 — triangulate_with_outlier_rejection()。

不同于硬 RANSAC 的"要么用要么扔"，FreeMoCap 走柔和路线：

参数（freemocap_anipose.py:91-93）：

4.5 重投影误差诊断

freemocap_anipose.py:1105-1143 — CameraGroup.reprojection_error() 返回 (n_cams, n_points, 2) 误差张量。diagnostics/calibration/calculate_calibration_diagnostics.py:12-46 输出 CSV：相邻 ChArUco 角点距离的 mean/median/std/偏差。

4.6 多机位同步：纯软件

没有硬件触发。synchronize_videos_thread_worker.py:6,49-61 走两条路：

from skelly_synchronize.skelly_synchronize import (
    synchronize_videos_from_audio,         # 默认：音频对齐
    synchronize_videos_from_brightness,    # 备选：亮度跳变
)

录制时记每帧时间戳到 synchronized_videos/timestamps/*.npy，对齐在后处理阶段做：找音频对齐峰 → 算相对偏移 → 帧重索引。

52D 关键点检测（Tracker 策略模式）

5.1 支持的 Tracker

默认 tracker 写死在 recording_info_model.py:42：active_tracker="mediapipe"。

5.2 检测入口（极薄）

process_motion_capture_videos/processing_pipeline_functions/image_tracking_pipeline_functions.py:26-98

def run_image_tracking_pipeline(...) -> np.ndarray:
    image_data_numCams_numFrames_numTrackedPts_XYZ = process_folder_of_videos(
        model_info=processing_parameters.tracking_model_info,
        tracking_params=processing_parameters.tracking_parameters_model,
        synchronized_video_path=synchronized_videos_folder_path,
        output_folder_path=output_data_folder_path,
        num_processes=tracking_params.num_processes,
    )

外包装薄如纸——实际检测全在 skellytracker.process_folder_of_videos() 里。FreeMoCap 不关心 tracker 内部，只接收统一 ndarray。

5.3 数据格式（钉死）

tests/test_image_tracking_data_shape.py:26-61 把 shape 钉死成：

shape = (num_cameras, num_frames, num_landmarks, 3)
                                                  ^^^^^^^^^^^
                                                  xy + confidence

第 4 维是 3 不是 2——多出来的是 confidence。3D 三角化阶段才会丢掉 conf 通道。

5.4 并发：multiprocessing

image_tracking_pipeline_functions.py:89-96 接 tracking_params.num_processes。默认 multiprocessing.cpu_count() - 1。每路视频独立进程，避开 GIL。

5.5 Landmark 映射：属性反射

post_process_skeleton_data/post_process_skeleton.py:130-136

def get_landmark_names(model_info: ModelInfo) -> list:
    if hasattr(model_info, "body_landmark_names"):
        return model_info.body_landmark_names
    elif hasattr(model_info, "landmark_names"):
        return model_info.landmark_names

属性反射 + duck typing——加新 tracker 不改主流程，只要 ModelInfo 子类提供 *_landmark_names 字段。

63D 后处理（skellyforge 任务管道）

6.1 Butterworth 滤波参数

data_layer/recording_models/post_processing_parameter_models.py:25-28

class ButterworthFilterParametersModel(BaseModel):
    sampling_rate: float = 30
    cutoff_frequency: float = 7
    order: int = 4

30 fps、7 Hz 截止、4 阶——典型人体运动学滤波（人手脚最快动作 ~10 Hz 上限）。

6.2 任务管道顺序

post_process_skeleton.py:69-104 走 skellyforge TaskWorkerThread，固定顺序（:83）：

每个任务独立 boolean 开关，挂在 PostProcessingParametersModel 上。

6.3 刚体约束（自实现，不依赖外部）

post_process_skeleton_data/enforce_rigid_bones.py

• calculate_bone_lengths_and_statistics() @ :10-41——每帧算骨长，求 median / stdev
• enforce_rigid_bones() @ :44-86——中位数骨长标准化 + 子关节级联传播

direction = (distal - proximal) / |distal - proximal|
adjustment = (desired_length - current_length) * direction
rigid_marker_data[distal_marker][frame] += adjustment
adjust_children(distal_marker, frame, adjustment, ...)  # 递归

把当前帧骨长拉回到序列中位数，再把偏移传给下游所有子关节（保持相对位姿）。处理 2D 检测误差导致的"骨头忽长忽短"。

6.4 坐标系对齐：90° 绕 X 轴

utilities/geometry/rotate_by_90_degrees_around_x_axis.py:4-14

swapped[:, :, 0] = raw[:, :, 0]    # X 不变
swapped[:, :, 1] = raw[:, :, 2]    # Y ← Z
swapped[:, :, 2] = -raw[:, :, 1]   # Z ← -Y

从"摄像头坐标系（Z 朝前）"换到"人体运动学坐标系（Y 朝上）"。

6.5 质心（替代关节角度）

post_process_skeleton_data/calculate_center_of_mass.py:12-141 返回：

• segment_com_data：shape (frames, segments, 3)
• total_body_com：shape (frames, 3)

7数据导出

7.1 格式矩阵

不支持 FBX / glTF——要用得手动从 .blend 二次导出。

7.2 Blender 桥接（最有意思的设计）

策略：不用 bpy 内嵌进程，而是外挂 Blender 可执行作为子进程。

core_processes/export_data/blender_stuff/export_to_blender/methods/ajc_addon/run_ajc_addon_main.py:73-99

command_list = [
    str(blender_exe_path),
    "--background",          # 无 GUI
    "--python",
    simple_run_script,         # methods/ajc_addon/run_simple.py
    "--",
    str(recording_folder_path),
    str(blender_file_path),
]
blender_process = run_subprocess(command_list=command_list)
while True:
    output = blender_process.stdout.readline()
    if blender_process.poll() is not None:
        break
    if output:
        logging.debug(output.strip().decode())
blender_process.terminate()

子进程脚本（run_simple.py:4-8）调用外部插件：

from ajc27_freemocap_blender_addon.main import ajc27_run_as_main_function
ajc27_run_as_main_function(recording_path=..., blend_file_path=...)

插件首次运行由 bpy_install_addon.py:33-51 现场安装：打 ZIP → bpy.ops.preferences.addon_install → bpy.ops.wm.save_userpref。

Blender 路径自动检测（get_best_guess_of_blender_path.py:27-86）：Windows 扫 Program Files/Blender Foundation，macOS /Applications/Blender.app/Contents/MacOS/Blender，Linux /usr/bin/blender。

7.3 列名约定（tracker-aware）

post_process_skeleton_data/split_and_save.py:67-121

# 如果 model_info 有具名 landmark：
column_names.append(f"{category}_{name}_{x|y|z}")    # body_nose_x, body_left_shoulder_y
# 否则降级到数字索引：
column_names.append(f"{category}_{i:04d}_{x|y|z}")    # body_0000_x, body_0001_x

同时按 category 切（:32-64）：body / left_hand / right_hand / face。

7.4 时间戳：CSV 不带

CSV 行号即帧索引。帧率元数据存在 PostProcessingParametersModel.framerate（默认 30），不内嵌到导出文件。精确时序分析得拿 synchronized_videos/timestamps/*.npy 配合用。

8Skeleton Schema（统一骨架定义）

8.1 核心 Pydantic 模型

data_layer/skeleton_models/skeleton.py:13-133

class Skeleton(BaseModel):
    model_config = ConfigDict(arbitrary_types_allowed=True)
    markers: MarkerInfo
    num_tracked_points: int
    segments: Optional[Dict[str, Segment]] = None
    marker_data: Dict[str, np.ndarray] = {}             # 每点 (frames, 3)
    virtual_marker_data: Dict[str, np.ndarray] = {}
    joint_hierarchy: Optional[Dict[str, List[str]]] = None
    center_of_mass_definitions: Optional[Dict[str, SegmentAnthropometry]] = None
    num_frames: Optional[int] = None

8.2 段定义

data_layer/skeleton_models/segments.py:8-17

class Segment(BaseModel):
    proximal: str
    distal: str

class SegmentAnthropometry(BaseModel):
    segment_com_length: float       # 质心位置占段长比例
    segment_com_percentage: float   # 段占全身质量比例

8.3 虚拟关键点

marker_info.py:38-68 支持加权平均生成虚拟点，典型如 mid_shoulder = 0.5 * left_shoulder + 0.5 * right_shoulder。这让上层算法（质心、骨长）能用稳定的解剖学参考点，不受单点遮挡影响。

9GUI / 数据层架构

9.1 RecordingInfoModel：路径属性生成器

data_layer/recording_models/recording_info_model.py:41-217

class RecordingInfoModel:
    @property
    def synchronized_videos_folder_path(self) -> str: ...
    @property
    def data_2d_npy_file_path(self) -> str: ...
    @property
    def data_3d_npy_file_path(self) -> str: ...
    @property
    def calibration_toml_path(self) -> str: ...
    @property
    def status_check(self) -> Dict[...]:    # 递归查文件存在性
        ...

不存路径字符串、只用属性生成器——根路径变了之后所有派生路径自动跟。status_check 是状态机的反面：不维护"录制完成 / 处理完成"标志位，而是每次按需扫文件存在性。

9.2 录制目录结构

文件名常量集中在 system/paths_and_filenames/file_and_folder_names.py:1-83。

9.3 后台任务：QThread + multiprocessing 双层夹心

gui/qt/workers/process_motion_capture_data_thread_worker.py:16-76

class ProcessMotionCaptureDataThreadWorker(QThread):
    in_progress = Signal(...)
    finished = Signal(bool)

    def run(self):
        self._process = multiprocessing.Process(
            target=process_recording_folder,
            args=(...),
        )
        self._process.start()
        while self._process.is_alive():
            time.sleep(0.01)
            if not self._queue.empty():
                record = self._queue.get()
                self.in_progress.emit(record)
        self.finished.emit(self._success)

• QThread 外层：Qt 信号槽友好、生命周期可控、可发 in_progress 给 UI
• multiprocessing.Process 内层：真正干活，绕开 GIL
• multiprocessing.Queue：从工作进程把日志/进度推回 QThread

GUI 应用的"重活外包"教科书模式：UI 线程绝对不卡，重计算独立崩溃也不杀主进程。

10招牌设计 Top 10

1. 加权异常点剔除三角化（freemocap_anipose.py:88-190）— exp(-5·error/threshold) 软权重，多相机时鲁棒胜过硬 RANSAC
2. Numba @jit(nopython=True) 单点 DLT（:55-67）— Python 几何运算贴近 C
3. RecordingInfoModel 属性生成器 + status_check — 不维护状态机，按需扫文件
4. QThread × multiprocessing.Process × Queue × Signal 四件套 — GUI 重活外包标准范式
5. Tracker 策略模式（ModelInfo + duck typing） — 加新 tracker 不动主流程
6. {tracker}_data_2d.npy 前缀命名 — 多算法结果共存对比
7. skellyforge TaskWorkerThread 管道 — 可拼装的后处理 task 列表
8. 刚体骨长中位数约束 + 子树级联传播（enforce_rigid_bones.py）— 不用 IK 就能压住骨头抖
9. Blender 子进程模式 — --background --python script.py，主进程 Python 环境干净
10. CHARUCO + 软件音频/亮度同步 — 用 webcam 也能搞动捕

11局限性（别被官方话术骗了）

12适合 / 不适合

13延伸思考（可改造方向）

1. 抽离 aniposelib + 加权剔除算法：单独打个 Python 库给所有"多相机三角化"业务用，不必带 PySide6。
2. 替换 skellyforge 后处理：上 Kalman 滤波 / 双向 LSTM 时序去抖，比 Butterworth 强。
3. 加关节角度计算：拿 Skeleton.joint_hierarchy + Pydantic 模型，每段两个 segment 算夹角，输出 Euler / 四元数。
4. GPU MediaPipe：用 mediapipe.tasks.python.vision.PoseLandmarker 替代旧 holistic API，启 GPU delegate。
5. WebRTC 实时模式：skellycam 出 RTP 流 → 服务器侧实时 2D + 增量三角化 → 真做到"实时动捕"。但要硬件触发同步才靠谱。

14文件级索引（快速查表）