# FreeMoCap v1.8.2 源码深度解析

> 创建日期：2026-05-27
> 上游版本：v1.8.2（commit clone 自 https://github.com/freemocap/freemocap）
> 主仓 LOC：14,210（freemocap 包内 145 个 .py 文件）
> 仓库定位：8.8k★ / 808 fork / AGPL-3.0 / Python 3.10–3.12

---

## 0. 一句话定性

**FreeMoCap 主仓本身不是动捕算法库，而是一个 PySide6 GUI 编排器**——它把 7 个 `skelly_*` 子包（采集 / 检测 / 同步 / 后处理 / 可视化 / Blender 导出）和 `aniposelib`（多视角几何核心）串成一条端到端的离线动捕流水线。论真正的算力，主仓不到 30%，70% 在外部依赖。

---

## 1. 依赖拓扑：算力在哪里

`pyproject.toml:68-84` 暴露了真相：

| 外部包 | 版本 | 在流水线中的角色 |
|---|---|---|
| `skellycam` | 2025.09.1097 | 多摄像头采集（PySide6 widget） |
| `skellytracker[all]` | 2025.10.1024 | 2D 关键点检测（包装 MediaPipe/YOLO/OpenPose） |
| `skelly_synchronize` | 2025.04.1037 | 多机位时间戳软同步（音频/亮度） |
| `skellyforge` | 2024.12.1009 | 后处理 task pipeline（插值/滤波/旋转） |
| `skelly_viewer` | 2025.04.1028 | 3D 骨架可视化 |
| `ajc27_freemocap_blender_addon` | 2026.04.1039 | Blender 桥接插件 |
| `aniposelib` | 0.4.3 | **多视角几何真核心**（DLT 三角化、Bundle Adjustment、外参标定） |
| `opencv-contrib-python` | 4.8.* | ChArUco 检测、相机标定底层 |
| `PySide6` | 6.6–6.8 | GUI 框架 |
| `pydantic` | 2.* | 数据 schema |

关键判断：**抄 FreeMoCap 不如抄 aniposelib + skellytracker**——这两个包才是真正可复用的"动捕基础设施"。FreeMoCap 主仓贡献的是 GUI 编排和参数管理（`ProcessingParameterModel`），算法都在外面。

---

## 2. 入口与主流程

### 2.1 程序入口

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

```python
def main():
    ...
    qt_gui_main()  # main_window/freemocap_main.py:29-59
```

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

### 2.2 主窗口 5 大 Tab

`MainWindow(QMainWindow)` @ `gui/qt/main_window/freemocap_main_window.py:92-150` 用一个 `CentralTabWidget` 串起 5 个 Tab + 右侧 `ControlPanelWidget`（3 子 Tab）+ 底部 `LogViewWidget`：

| Tab | Widget | 来源 |
|---|---|---|
| 0 | HomeWidget | 本仓 `widgets/home_widget.py` |
| 1 | SkellyCamWidget（录制） | **外部库 skellycam** |
| 2 | SkellyViewer（3D 可视化） | **外部库 skelly_viewer** |
| 3 | DirectoryViewWidget | 本仓 |
| 4 | ActiveRecordingInfoWidget | 本仓 |

右侧 ControlPanel：① 摄像头配置 → ② 数据处理（标定→2D→三角化→后处理）→ ③ 导出（Blender / Jupyter）。

### 2.3 端到端流水线

```
[1] 用户点 "Start New Session"  →  handle_start_new_session_action()
                                   freemocap_main_window.py:195
[2] 摄像头 Tab：SkellyCamWidget 启动多机位录制（外部库）
[3] 录制完成发信号 videos_saved_to_this_folder_signal
                                   freemocap_main_window.py:232
[4] 若勾选 "Auto Process Videos"：自动点击 Process 按钮
                                   freemocap_main_window.py:177
[5] 处理流水线（后台子进程）：
       标定（CHARUCO 视频 → camera_calibration.toml）
         ↓
       视频时间戳软同步（skelly_synchronize：audio / brightness）
         ↓
       2D 检测（skellytracker → MediaPipe / YOLO / OpenPose）
         ↓
       3D 三角化（aniposelib DLT + 加权异常点剔除）
         ↓
       后处理（skellyforge：插值 → Butterworth 滤波 → 找参考帧 → 坐标系旋转）
         ↓
       刚体约束（enforce_rigid_bones）
         ↓
       质心计算（segment COM + total body COM）
         ↓
       导出（CSV / NPY / Blender .blend / Jupyter）
[6] processing_finished_signal → 自动加载到 SkellyViewer Tab
                                   freemocap_main_window.py:274-276
```

---

## 3. 标定 + 三角化（招牌核心）

### 3.1 CHARUCO 棋盘定义

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

```python
@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**：默认，ArUco `DICT_4X4_250`，marker = 0.8 × square
- **5×3**：小空间备选

### 3.2 标定主入口

`core_processes/capture_volume_calibration/run_anipose_capture_volume_calibration.py:17-35` →
`AniposeCameraCalibrator` @ `anipose_camera_calibration/anipose_camera_calibrator.py:42-87`

### 3.3 标定流程

**内参（每相机）**：`freemocap_anipose.py:2178-2202`，`CameraGroup.calibrate_videos()`。
内参初始化用 `cv2.initCameraMatrix2D()`（`freemocap_anipose.py:2091`）。

**外参（相机间关系）**：
1. ChArUco 2D 检测 — `_get_charuco_2d_data()` @ `freemocap_anipose.py:2150-2168`（调 skellytracker）
2. 外参初始化 — `get_initial_extrinsics()` @ `freemocap_anipose.py:499-513`（`extract_rtvecs` from aniposelib）
3. 相机图连通性 — `get_calibration_graph()` @ `freemocap_anipose.py:387-403`
4. 相机矩阵 — `compute_camera_matrices()` @ `freemocap_anipose.py:427-434`
5. **Bundle Adjustment 迭代优化** — `bundle_adjust_iter()` @ `freemocap_anipose.py:1145-1265`

`aniposelib` 关键 import（`freemocap_anipose.py:17-18`）：

```python
from aniposelib.boards import extract_points, extract_rtvecs, get_video_params, merge_rows, CharucoBoard
from aniposelib.utils import get_rtvec, make_M
```

### 3.4 三角化算法：Numba 加速的 DLT

`freemocap_anipose.py:55-67`：

```python
@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 速度。

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

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

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

```
全相机三角化  →  计算重投影误差
  ↓ 若超 target_reprojection_error
系统地枚举"丢 1 / 2 / ... / maximum_cameras_to_drop 个相机"的所有子集组合
  ↓ 每个子集都三角化一次 + 算误差
对每个有效子集赋权：weight = exp(-5.0 × error / target_reprojection_error)
  ↓
所有子集的 3D 点加权平均 → 输出最终 3D + 每相机置信度权重
```

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

```python
minimum_cameras_for_triangulation: int = 2
maximum_cameras_to_drop: int = 1
target_reprojection_error: float = 0.01
```

**为什么牛**：硬剔除会丢信息，软剔除（指数权重）让"还行"的相机也能贡献。这对低成本多机位（4-6 个 webcam，会有 1-2 个角度差）尤其重要。

### 3.6 重投影误差诊断

`freemocap_anipose.py:1105-1143` — `CameraGroup.reprojection_error()` 返回 `(n_cams, n_points, 2)` 误差张量。
`triangulate_3d_data.py:74-82` 把误差按 (相机, 帧, 关键点) reshape 存档。
`diagnostics/calibration/calculate_calibration_diagnostics.py:12-46` 输出 CSV：相邻 ChArUco 角点距离的 mean/median/std/与标称值偏差。

### 3.7 多机位同步：纯软件

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

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

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

---

## 4. 2D 关键点检测（Tracker 策略模式）

### 4.1 支持的 Tracker

| Tracker | 模型类 | 状态 |
|---|---|---|
| **MediaPipe Holistic**（默认） | `MediapipeModelInfo` / `MediapipeTrackingParams` | 主流程 |
| YOLO | `YOLOModelInfo` / `YOLOTrackingParams` | `experimental/alternative_trackers/run_yolo.py:7` |
| OpenPose | `OpenPoseModelInfo` / `OpenPoseTrackingParams` | `experimental/alternative_trackers/run_openpose.py:8` |
| YOLOMediapipeCombo | `YOLOMediapipeComboTracker` | `image_tracking_pipeline_functions.py:85-86`（YOLO crop → MediaPipe pose） |

默认 tracker 在 `data_layer/recording_models/recording_info_model.py:42`：`active_tracker="mediapipe"`。

### 4.2 检测入口

`core_processes/process_motion_capture_videos/processing_pipeline_functions/image_tracking_pipeline_functions.py:26-98`：

```python
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。

### 4.3 数据格式

`tests/test_image_tracking_data_shape.py:26-61` 钉死了 shape：

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

注意：第 4 维是 **3 不是 2**——多出来的是 confidence。3D 三角化阶段才会丢掉 conf 通道（`triangulate_3d_data.py:26-46` 期望 shape[3] == 2，由上游切片）。

### 4.4 并发：multiprocessing

`image_tracking_pipeline_functions.py:89-96` 接 `tracking_params.num_processes`。默认 `multiprocessing.cpu_count() - 1`（`experimental/alternative_trackers/run_yolo.py:20-22`）。

每路视频独立进程，避开 Python GIL。

### 4.5 Landmark 映射

`post_process_skeleton_data/post_process_skeleton.py:130-136`：

```python
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` 字段即可。

### 4.6 缓存路径

`recording_info_model.py:116-122`：每个 tracker 的 2D 结果写 `output_data/raw_data/{tracker}_data_2d.npy`，**前缀命名**让多 tracker 结果共存对比。

---

## 5. 3D 后处理（skellyforge 任务管道）

### 5.1 Butterworth 滤波

参数（`data_layer/recording_models/post_processing_parameter_models.py:25-28`）：

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

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

### 5.2 任务管道

`post_process_skeleton_data/post_process_skeleton.py:69-104` 走 `skellyforge.TaskWorkerThread`，任务顺序固定（`post_process_skeleton.py:83`）：

```python
[
    TASK_INTERPOLATION,        # 缺帧插值（max_gap_to_fill=10）
    TASK_FILTERING,            # Butterworth
    TASK_FINDING_GOOD_FRAME,   # 找标定参考帧
    TASK_SKELETON_ROTATION,    # 坐标系旋转
]
```

每个任务可独立开关（boolean 参数挂在 `PostProcessingParametersModel`）。

### 5.3 刚体约束（自实现，不依赖 skellyforge）

`post_process_skeleton_data/enforce_rigid_bones.py`：

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

```python
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 检测误差导致的"骨头忽长忽短"。

### 5.4 坐标系对齐

**90° 绕 X 轴旋转**（`utilities/geometry/rotate_by_90_degrees_around_x_axis.py:4-14`）：

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

从"摄像头坐标系（Z 朝前）"换到"人体运动学坐标系（Y 朝上）"。可选投影到 Z 平面：`project_3d_data_to_z_plane()` @ `process_single_camera_skeleton_data.py:16-44`。

### 5.5 质心计算（替代关节角度）

`post_process_skeleton_data/calculate_center_of_mass.py:12-77,116-141`：

```python
def calculate_center_of_mass_from_skeleton(skeleton: Skeleton):
    return segment_com_data, total_body_com
    #      shape (frames, segments, 3)   shape (frames, 3)
```

**注意**：v1.8.2 没有原生关节角度（Euler / 四元数）输出，只有关键点位置 + 质心。要做关节角度分析得拿 NPY 自己算。

---

## 6. 数据导出

### 6.1 格式矩阵

| 格式 | 路径 | 用途 |
|---|---|---|
| NPY | `output_data/mediapipe_skeleton_3d.npy` | 主产物，shape `(frames, markers, 3)` |
| CSV（by_trajectory） | `{recording}_by_trajectory.csv` | 每帧一行，列=每个 marker 的 x/y/z |
| CSV（by_frame tidy） | `{recording}_by_frame.csv` | tidy 格式：frame/timestamp/model/keypoint/x/y/z/reprojection_error |
| JSON | `{recording}_by_frame.json` | 完整原始数据 |
| **.blend** | `{recording}.blend` | Blender 场景（带骨架 armature） |
| .ipynb | `auto_generated_notebook.ipynb` | Jupyter 数据探索模板 |

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

### 6.2 Blender 桥接（最有意思）

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

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

```python
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`）调用外部插件：

```python
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(overwrite=True, ...)` → `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`

**为什么这设计聪明**：bpy 作为 Python 库装起来很折磨（要 Blender 版本对齐），子进程模式把 Blender 当成黑盒服务，FreeMoCap 主进程的 Python 环境干净。

### 6.3 列名约定（tracker-aware）

`post_process_skeleton_data/split_and_save.py:67-121`：

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

split 也按 category 切（`split_and_save.py:32-64`）：

```python
for category in ["body", "left_hand", "right_hand", "face"]:
    n = getattr(model_info, f"num_tracked_points_{category}")
    split_data[category] = skeleton_3d_data[:, prev_index:prev_index+n, :]
```

### 6.4 时间戳问题

**CSV 不带时间戳**——行号即帧索引（`split_and_save.py:152-154`）。帧率元数据存在 `PostProcessingParametersModel.framerate`（默认 30），不内嵌到导出文件。后续做精确时序分析得拿 `synchronized_videos/timestamps/*.npy` 配合用。

---

## 7. Skeleton Schema（统一骨架定义）

### 7.1 核心 Pydantic 模型

`data_layer/skeleton_models/skeleton.py:13-133`：

```python
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] = {}             # 每点 shape (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
```

### 7.2 段定义

`data_layer/skeleton_models/segments.py:8-17`：

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

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

### 7.3 虚拟关键点

`data_layer/skeleton_models/marker_info.py:38-68` — 支持加权平均生成虚拟点：

```python
# 典型：mid_shoulder = 0.5 * left_shoulder + 0.5 * right_shoulder
class MarkerInfo(BaseModel):
    original_marker_names: List[str]
    virtual_marker_definition: Optional[VirtualMarkerInfo] = None
    all_markers_list: List[str] = Field(default_factory=list)
```

这让上层算法（质心、骨长）能用稳定的解剖学参考点，不受单点遮挡影响。

---

## 8. GUI / 数据层架构

### 8.1 RecordingInfoModel：路径属性生成器

`data_layer/recording_models/recording_info_model.py:41-217`：

```python
class RecordingInfoModel:
    @property
    def synchronized_videos_folder_path(self) -> str: ...
    @property
    def output_data_folder_path(self) -> str: ...
    @property
    def data_2d_npy_file_path(self) -> str: ...      # {tracker}_2dData...
    @property
    def data_3d_npy_file_path(self) -> str: ...
    @property
    def reprojection_error_data_npy_file_path(self) -> str: ...
    @property
    def total_body_center_of_mass_npy_file_path(self) -> str: ...
    @property
    def calibration_toml_path(self) -> str: ...
    @property
    def status_check(self) -> Dict[...]:             # 递归查文件存在性
        ...
```

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

### 8.2 录制目录结构

```
freemocap_data/recording_sessions/
└── session_<timestamp>/
    └── recording_<timestamp>/
        ├── synchronized_videos/
        │   ├── camera_0.mp4
        │   ├── camera_1.mp4
        │   └── timestamps/
        │       ├── camera_0_timestamps.npy
        │       └── camera_1_timestamps.npy
        ├── annotated_videos/                        # 可选：2D 关键点叠加视频
        ├── output_data/
        │   ├── mediapipe_2dData_numCams_numFrames_numTrackedPoints_pixelXY.npy
        │   ├── raw_data/
        │   │   ├── mediapipe_3dData_numFrames_numTrackedPoints_spatialXYZ.npy
        │   │   └── mediapipe_3dData_numFrames_numTrackedPoints_reprojectionError.npy
        │   ├── center_of_mass/
        │   │   └── mediapipe_total_body_center_of_mass_xyz.npy
        │   ├── mediapipe_skeleton_3d.npy
        │   └── recording_parameters.json
        ├── <recording>_camera_calibration.toml
        └── <recording>.blend
```

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

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

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

```python
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 线程绝对不卡，重计算独立崩溃也不杀掉主进程。

### 8.4 跨平台路径

`system/paths_and_filenames/path_getters.py:31-250`：

```python
def os_independent_home_dir():           # Path.home()
def get_freemocap_data_folder_path():    # ~/.freemocap_data 或自定义
def get_recording_session_folder_path():
def create_new_session_folder():
def get_calibrations_folder_path():
def get_logs_info_and_settings_folder_path():
```

全部走 `pathlib.Path`——自动适配 mac/Linux/Windows。GUI 状态持久化用 `gui_state.json` 存自定义数据根目录。

---

## 9. 招牌设计 Top 10（值得抄什么）

1. **加权异常点剔除三角化** (`freemocap_anipose.py:88-190`) — `exp(-5·error/threshold)` 软权重，多相机时鲁棒胜过硬 RANSAC
2. **`@jit(nopython=True)` 单点 DLT 三角化** (`freemocap_anipose.py:55-67`) — Numba 让 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 管道** — `[INTERPOLATION, FILTERING, FINDING_FRAME, ROTATION]` 可拼装
8. **刚体骨长中位数约束 + 子树级联传播** (`enforce_rigid_bones.py`) — 不用 IK 就能压住骨头抖
9. **Blender 子进程模式** — `--background --python script.py`，主进程 Python 环境干净
10. **CHARUCO + 软件音频/亮度同步** — 用 webcam 也能搞动捕

---

## 10. 局限性（别被官方话术骗了）

| 宣传 | 实情 |
|---|---|
| "实时动作捕捉" | **离线后处理**。录的时候是实时同步采集，但 2D 检测 / 三角化 / 后处理全是录完了一起跑 |
| "实时关节角度" | **不输出关节角度**。v1.8.2 只有关键点位置和质心，关节角度得自己算 |
| "支持任意 tracker" | 主流程默认只接 MediaPipe；YOLO / OpenPose 在 `experimental/` 没上主线 |
| "GPU 加速" | 主仓不暴露 GPU 配置，全靠 MediaPipe 内部判断 |
| "媲美 Vicon" | 重投影误差量级 ~ 像素级；Vicon 亚毫米级标定。差 2-3 个数量级 |

---

## 11. 适合什么 / 不适合什么

✅ **适合**：
- 教学 / 科研动作分析（人体生物力学、运动学研究）
- 低成本 3D 角色动画毛坯（导 Blender 后人手 retarget）
- 隐私敏感场景（数据全本地）

❌ **不适合**：
- 实时游戏 / VR 全身追踪
- 高精度临床步态分析（亚毫米级别）
- 商业产品发行（**AGPL-3.0**——SaaS 化要开源整个调用链）

---

## 12. 延伸思考（可改造方向）

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

---

## 13. 文件级索引（快速查表）

| 模块 | 关键文件 |
|---|---|
| 入口 | `freemocap/__main__.py:24` → `gui/qt/freemocap_main.py:29` |
| 主窗口 | `gui/qt/main_window/freemocap_main_window.py:92-150` |
| CHARUCO 板 | `core_processes/capture_volume_calibration/charuco_stuff/charuco_board_definition.py:7-44` |
| 标定主入口 | `core_processes/capture_volume_calibration/run_anipose_capture_volume_calibration.py:17-35` |
| 三角化算法 | `.../anipose_camera_calibration/freemocap_anipose.py:55-67`（DLT）/ `:88-190`（加权剔除） |
| Bundle Adjustment | `.../freemocap_anipose.py:1145-1265` |
| 重投影误差 | `.../freemocap_anipose.py:1105-1143` |
| 软同步 | `.../synchronize_videos_thread_worker.py:6,49-61` |
| 2D 检测入口 | `core_processes/process_motion_capture_videos/processing_pipeline_functions/image_tracking_pipeline_functions.py:26-98` |
| Tracker 参数模型 | `data_layer/recording_models/post_processing_parameter_models.py:25-44` |
| Butterworth | `data_layer/recording_models/post_processing_parameter_models.py:25-28` |
| 后处理任务管道 | `core_processes/post_process_skeleton_data/post_process_skeleton.py:69-104` |
| 刚体约束 | `core_processes/post_process_skeleton_data/enforce_rigid_bones.py:10-86` |
| 坐标系旋转 | `utilities/geometry/rotate_by_90_degrees_around_x_axis.py:4-14` |
| 质心计算 | `core_processes/post_process_skeleton_data/calculate_center_of_mass.py:12-141` |
| 导出 split & save | `core_processes/post_process_skeleton_data/split_and_save.py:32-177` |
| Blender 子进程 | `core_processes/export_data/blender_stuff/export_to_blender/methods/ajc_addon/run_ajc_addon_main.py:73-99` |
| Blender 路径检测 | `core_processes/export_data/blender_stuff/get_best_guess_of_blender_path.py:27-86` |
| Skeleton schema | `data_layer/skeleton_models/skeleton.py:13-133` |
| RecordingInfoModel | `data_layer/recording_models/recording_info_model.py:41-217` |
| 后台任务 worker | `gui/qt/workers/process_motion_capture_data_thread_worker.py:16-76` |
| 跨平台路径 | `system/paths_and_filenames/path_getters.py:31-250` |

---

> 解析方法：4 个 Explore 子 agent 并行拆 ①标定+三角化 ②pose 检测 ③后处理+导出 ④GUI+数据层，主线程读 pyproject.toml + 入口串总线索。所有论断带 file:line。