附录 - 文档中心 - 舞肌科技

算法原理

优化公式

系统使用 AdaptiveOptimizerAnalytical 优化器，采用 Huber 损失 + 手写解析梯度 + NLopt SLSQP：

\begin{aligned} \min_{q} \quad & L(q) + \lambda \left\lVert q - q_{\mathrm{prev}} \right\rVert^2 \\ \text{s.t.} \quad & q_{\min} \le q \le q_{\max} \end{aligned}

其中 $q_{\mathrm{prev}}$ 为上一帧的关节角， $\lambda$ 是 norm_delta（速度正则化权重）。

自适应混合

算法根据手指捏合状态自动切换优化策略：

L = \sum_i \left[ \alpha_i L_{\mathrm{tip\_dir\_vec}, i} + (1 - \alpha_i) L_{\mathrm{full\_hand}, i} \right]

\alpha_i = \operatorname{clip}\!\left(\frac{d_2 - d_i}{d_2 - d_1},\; 0,\; 0.7\right)

TipDirVec 模式：优化指尖位置和方向，适用于精细捏合动作

FullHandVec 模式：优化全手姿态，适用于张开和抓握动作

Q: pinocchio 安装报错？

从 PyPI 镜像源安装遇到问题，请使用官方源。注意：PyPI 上的包名为 pin（非 pinocchio）：

pip install pin==3.8.0 -i https://pypi.org/simple

Q: macOS MuJoCo 窗口无法显示？

在 macOS 上运行仿真脚本需使用 mjpython 代替 python：

mjpython teleop_sim.py --play data/avp1.pkl --hand left

Q: 视频模式提示缺少 mediapipe 或 opencv-python？

请安装视频模式依赖：

pip install -e ".[video]"

这将安装视频模式所需的 mediapipe 和 opencv-python 包。

Q: RealSense 模式无法启动或提示 pyrealsense2 缺失？

请先安装 RealSense 额外依赖：

pip install -e ".[realsense]"

同时确认 Intel RealSense 设备已连接，并且没有被其他程序占用。

Q: RealSense 报告设备忙 (device is busy)？

这通常表示相机已被其他程序占用，例如调试工具或其他采集进程。关闭相关程序后重新运行即可。

Q: 开启 --show-video 后卡顿怎么办？

--show-video 主要用于调试，会额外显示图像与关键点叠加结果。若更关注实时性能，建议关闭该选项。