FreeMoCap 安装配置完整指南：从零跑通开源无标记动作捕捉系统
【免费下载链接】freemocapFree Motion Capture for Everyone 💀✨项目地址: https://gitcode.com/GitHub_Trending/fr/freemocap
FreeMoCap 是一个免费开源、不挑硬件的无标记动作捕捉系统（motion capture）：用多台普通摄像头拍人，就能还原出 3D 骨骼运动数据，适合科研、教学和低成本动捕数据采集。不想买商业动捕设备，又想自己搭一套可用环境的，跟着下面做就行。
安装环境怎么检查：先备好 Python 3.11、uv 和 Node.js
动手前先确认这几样，缺一样后面都会卡住：
- Python ≥ 3.11：项目硬性要求 3.11 及以上（pyproject.toml 中声明了
requires-python = ">=3.11"），终端执行python --version看一下 - uv：一个速度很快的 Python 环境与包管理工具。这个仓库的依赖（skellytracker、skellycam 等）是从一组 git 仓库拉取的，官方说明里明确写了 conda +
pip install -e .这条路走不通，必须用 uv - Git：用来克隆仓库
- Node.js + npm：GUI 是 React + Electron 写的，跑前端要它
- NVIDIA GPU（可选）：Windows/Linux 上有 NVIDIA 显卡会默认装 GPU 加速版推理；没有也能跑，走 CPU 版即可
最小路径跑起来：克隆仓库并启动 Python 后端
📦 后端是全部安装的核心，一共 5 条命令。
克隆仓库：
git clone https://gitcode.com/GitHub_Trending/fr/freemocap它把源码拉到本地，看到一堆文件（包括freemocap/和freemocap-ui/两个目录）即成功。
进入项目根目录：
cd freemocap创建虚拟环境（一个独立的 Python 依赖沙盒，不污染系统环境）：
uv venv应看到Using Python 3.11.x和.venv创建成功的提示。
安装全部依赖：
uv sync这一步耗时最长（要拉取多个 git 依赖并安装推理引擎）。它会自动按平台选择版本：Windows/Linux 装 NVIDIA GPU 加速版，macOS 装 CPU 版。如果你的 Windows/Linux 机器没有受支持的显卡，改用 CPU 版：uv sync --no-default-groups --group cpu。
启动 Python 服务端（它是 FastAPI + uvicorn 组成的 HTTP/WebSocket 服务，前端的摄像头、标定、动捕能力都挂在它上面）：
uv run python freemocap/__main__.py终端会打印一行FREEMOCAP_PORT=53117之类的端口哨兵（sentinel，即"端口号公告"），服务开始监听本地端口并保持运行。
GUI 怎么启动：装前端依赖并弹出界面
🖥️ 后端开着别关，再开一个终端，同样进入项目根目录后：
进入前端目录并安装依赖（npm 读 freemocap-ui/package.json 里的依赖清单）：
cd freemocap-ui npm install看到added xxx packages无报错即完成。
启动 GUI：
npm run dev这会同时拉起 Vite 开发服务和 Electron 桌面窗口，应弹出一个 FreeMoCap 界面窗口，它默认连接本机后端（默认端口 53117，见 freemocap-ui/src/constants/server-urls.ts）。
验证成功，以及失败时怎么办
成功标志有两个，都满足才算装好：
- 后端终端稳定打印出
FREEMOCAP_PORT=<端口>且没有异常堆栈 - GUI 窗口弹出后，浏览器访问
http://localhost:53117/health能返回正常响应（这是服务自带的健康检查接口）
最常见的两种失败：
uv sync报 Python 版本不满足：说明系统里的 Python 低于 3.11。装一个新版 Python 后删除.venv重新uv venv && uv sync即可- 没有显卡却装了 CUDA 版，启动报错或推理极慢：在 Windows/Linux 上删掉虚拟环境，用 CPU 版重装：
uv sync --no-default-groups --group cpu。另外若端口被占，服务会自动顺延尝试下一个可用端口，以终端实际打印的端口号为准
新手常问的三个问题
Q：没有 NVIDIA 显卡能正常用吗？能。GPU 只是加速推理，CPU 版功能相同，只是速度受限，适合先跑通流程。
Q：怎么确认前后端连上了？看后端端口哨兵输出，再用浏览器开/health接口；GUI 里连接失败通常就是后端没起或端口对不上。
Q：动捕前需要的标定板（CharUco board，带棋盘的印刷图案，用来求相机参数）在哪？仓库里就有可打印的 ChArUco 标定板素材，GUI 的标定设置里也有对应尺寸选项，打印出来按界面提示拍摄即可：
到这里安装已经跑通，下一步就是接入摄像头、完成一次相机标定并录下第一段动捕数据，具体流程可以看 freemocap-docs/docs/guides/ 里的相机搭建与后处理指南。
【免费下载链接】freemocapFree Motion Capture for Everyone 💀✨项目地址: https://gitcode.com/GitHub_Trending/fr/freemocap
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
