企业官网建设流程全解析

FreeMoCap 30分钟跑通指南：从空白环境到第一次动作捕捉

【免费下载链接】freemocapFree Motion Capture for Everyone 💀✨项目地址: https://gitcode.com/GitHub_Trending/fr/freemocap

FreeMoCap 是一个免费的开源无标记点动作捕捉（markerless motion capture）系统：只需要几台普通相机加一张 Charuco 标定板，不用光条相机和专业设备，就能在科研和教学里跑出研究级精度的 3D 人体动作数据。这篇文章带你从一台干净的环境出发，按「环境自检 → 克隆搭建 → 双终端启动 → 验证结果」的任务链走一遍，目标是 30 分钟内让它的桌面 GUI 完整弹出来。

先说清楚架构，后面每个命令各管一半：后端是 Python 写的 FastAPI 服务，前端是 Electron + React 桌面界面。启动时我们需要开两个终端，分别跑这两半。

环境自检清单

动手前花 1 分钟确认三样东西：

1. Python 3.11 或更高版本。项目 pyproject.toml 里声明了requires-python = ">=3.11"，这是硬门槛，3.10 及以下装不上。用python --version确认（macOS 下换成python3 --version）。
2. Git。用来克隆仓库，git --version确认。
3. Node.js LTS。前端是 Electron + React 应用，构建运行都靠它，仓库 README 未锁定具体版本，装最新 LTS 即可（以仓库 README 为准）。

还有一个隐形前提：磁盘留足 10GB 以上。依赖里包含 MediaPipe、OpenCV 等视觉栈，uv sync还会从多个 git 仓库拉取 skellytracker 等子项目，下载量不小。

克隆与搭建：为什么必须用 uv

先别急着conda create。README 明确写了：核心依赖（skellytracker、skellycam 等）是通过 uv 从 git 源直接拉取的，conda +pip install -e .这条路走不通。所以工具链里多了一个主角 uv——一个非常快的 Python 包与环境管理器，按 uv 官方说明装好即可。

克隆仓库，得到freemocap/目录：

git clone https://gitcode.com/GitHub_Trending/fr/freemocap cd freemocap

uv venv在项目根目录生成隔离的虚拟环境.venv，避免污染系统 Python：

uv venv

然后是全文最关键的一步：uv sync按锁定的 uv.lock 一次性装齐后端依赖，并按平台自动选追踪器版本——Windows/Linux 有 NVIDIA GPU 时自动装 CUDA 加速版，macOS 或无 GPU 机器自动装 CPU 版：

uv sync

如果你的 Windows/Linux 机器没有 NVIDIA 显卡，默认路径会在 GPU 依赖上卡住，改用这条强制 CPU 版：

uv sync --no-default-groups --group cpu

这一步首次运行约 5~15 分钟（取决于网速），可以先去倒杯水。

首次启动：两个终端各跑一半

终端 1：启动 Python 后端。下面这条命令用 venv 里的 Python 跑服务入口，FastAPI 会在53117端口监听（端口定义在 freemocap/api/server_constants.py 的PREFERRED_PORT；README 里出现的 8005 端口是旧信息，以代码为准）：

uv run python freemocap/__main__.py

日志停止滚动报错、进程挂在监听状态，后端就算活了。

终端 2：启动 Electron GUI。前端代码在 freemocap-ui/，先装 npm 依赖，再进开发模式，一个 Electron 窗口就会弹出来：

cd freemocap-ui npm install npm run dev

验证结果：确认你真的跑通了

别只信"窗口弹出来了"。用健康检查接口确认后端真在服务，下面这条命令请求/health端点，正常会返回存活状态和进程号：

curl http://localhost:53117/health

看到类似{"alive":true,"pid":12345}的响应，再确认 GUI 窗口正常显示并能连上本地服务器——FreeMoCap 就完整跑通了。

最常见的 3 个报错

1. pip install -e .报依赖解析失败。不是网络问题，是这条路本身不支持 git 源依赖。回上文用uv venv+uv sync重来。
2. uv sync卡在 CUDA/TensorRT 相关包上。机器没有 NVIDIA 显卡时默认会尝试 GPU 版追踪器，中断后改用uv sync --no-default-groups --group cpu。
3. GUI 弹不出来或界面连不上服务器。先确认终端 1 的进程还活着、53117 端口没被占用，再跑一次上面的 curl 验证。开发模式下两个进程要同时手动运行，别关错窗口。

接下来做什么

跑通只是拿到门票，真正的动作捕捉流程是：标定 Charuco 板 → 架设相机采集 → 三角化重建 3D 骨骼。仓库里就放着标定板图样，shared/charuco/ 目录下有高清版，可以直接打印：

三条可执行的下一步：

1. 打开 GUI 的相机配置页，接一路普通 USB 相机，先跑通实时骨骼检测；
2. 按 shared/charuco/charuco_board_image_highRes.png 打印标定板，在软件里走一遍完整标定；
3. 录一段短视频，用离线（posthoc）处理流程产出你的第一份 3D 动作数据。

【免费下载链接】freemocapFree Motion Capture for Everyone 💀✨项目地址: https://gitcode.com/GitHub_Trending/fr/freemocap