安装

bash
python -m pip install fastsim-kinematics-solver-spi fastsim-kinematics-solver-portable

第一次求解

在本仓库包目录运行完整示例：

bash
python examples/quickstart.py

核心调用保持得很短：

python
from fastsim_kinematics_solver_portable import PortableKinematicsSolver
from fastsim_kinematics_solver_spi import IKRequest, JointState, Pose

solver = PortableKinematicsSolver.from_urdf(urdf_text)
result = solver.solve(
    IKRequest(
        request_id="pick-pregrasp",
        run_id="run-1",
        generation=1,
        robot_entity_id="robot",
        base_frame_id="base_link",
        tip_frame_id="tool_link",
        target=Pose("base_link", (0.45, 0.10, 0.35), (0.0, 0.0, 0.0, 1.0)),
        start=JointState(("joint1", "joint2"), (0.0, 0.0), ("rad", "rad")),
    )
)

读取 result.solutions 前先检查 result.status。无解、超时、取消、不支持和请求不合法都是正常的 结构化结果，分别返回稳定的 failure_code 与简短说明，而不是难以处理的内部异常。 关节 ID、顺序和单位必须与所选 URDF 运动链完全一致。在 FastSim 中，run_id 与 generation 来自 当前 Run；响应会原样返回它们，使 Application 层能在 reset 后丢弃已经过期的解。

首版能力边界

  • 支持 URDF 的 fixed、revolute、continuous、prismatic 关节。
  • 支持树状分支机器人；每次调用用 base-to-tip 明确选择一条串联链，因此可以选择双臂机器人的任意一臂。
  • 支持把串联的平移/旋转轴作为虚拟底盘关节。
  • FK 确定性执行；IK 支持初始关节状态、确定性 seed、关节锁定、限位、容差、迭代上限、超时与协作取消。
  • 首版只真实支持 collision_mode=none 和 max_solutions=1。其他请求明确返回 unsupported，不会 静默降低为更弱的求解。
  • 这个 Provider 暂不支持闭链、URDF planar/floating 关节、mimic 关节和碰撞 IK。

FastSim 通过 fastsim.kinematics_solvers 发现 kinematics-solver://fastsim/portable。URDF digest 只在创建 Provider 时计算一次；solve() 内没有 文件 IO、仿真器调用、网络调用或哈希计算。