Pinocchio 是一个用于刚体系统机器人运动学和机器人动力学计算的数学库，常被用作机器人控制、规划或仿真中的 kinematics/dynamics backend。
它负责回答“给定机器人模型和状态，几何与动力学量是多少”这类问题。例如给定关节配置 ，计算末端位姿；给定 ，计算某个 frame 的雅可比矩阵；给定 和 ，计算速度、加速度或动力学相关量。
核心问题
机器人控制链路里经常需要把关节状态转换成任务空间状态：
Pinocchio 的定位是高性能、结构化地计算这些对象。它本身不决定目标怎么来，也不决定机器人应该采取哪种安全策略。
核心机制
典型使用流程是先从 URDF 或代码构建 model，再在每个控制周期用当前 和 更新 data：
- 解析机器人模型，得到关节树、link/frame、惯量和固定变换。
- 调用前向运动学相关算法，把当前 传播到各 frame。
- 调用 joint Jacobian 计算，再用 frame id 和参考系取 Frame Jacobian。
- 把 FK、Jacobian 或动力学量交给上层 IK、规划器、控制器或诊断逻辑。
在 Pinocchio 的 frame Jacobian 语义中，给定 frame id 和 reference frame 后， 表示该 frame 在指定参考系下的空间速度。调用 getFrameJacobian() 前需要先计算 joint Jacobian，否则读到的 Jacobian 不是当前状态下的有效结果。
工程用途
在遥操作或闭环位姿跟踪中，Pinocchio 常作为“模型数学引擎”：
- 用 arm position 计算当前末端 pose。
- 用当前 pose 和目标 pose 计算任务空间误差。
- 用当前 计算末端 Jacobian。
- 把误差和 Jacobian 交给 DLS、伪逆 IK 或其他优化器求下一步关节命令。
因此 pinocchio_dls 这类命名通常表示“Pinocchio 提供 FK/Jacobian，DLS 提供数值 IK 策略”，不是 Pinocchio 自带完整遥操作控制器。
边界与常见坑
Pinocchio 不是完整的 IK policy，也不是 MoveIt Servo 这种实时 servo 层。它不会自动处理碰撞检查、关节限位、运动平滑、状态上报或 PlanningScene；这些需要由上层系统实现或接入。
常见问题包括：
- URDF 的 frame 名、关节顺序、关节方向或末端工具偏置与实机不一致，导致 FK/Jacobian 看似稳定但物理含义错误。
- 忘记在读取 frame Jacobian 前计算 joint Jacobian，或在状态更新后复用旧 data。
- 混淆 Jacobian 的参考系：LOCAL、WORLD、LOCAL_WORLD_ALIGNED 等参考系不同，误差向量也必须在相同参考系下表达。
- 把“能算 Jacobian”误认为“已经有完整 IK 和安全控制策略”。