IKPy 是 Python 中专门用于机器人 ** 正运动学（FK）和逆运动学（IK）** 求解的轻量化库，其核心语法围绕 “运动链（Chain）” 展开，完全兼容 URDF 机器人描述格式。

一、 核心类：ikpy.chain

Chain是 IKPy 库的核心类，用于表征机器人的 “连杆 - 关节” 运动链结构，所有运动学求解都基于该类的实例对象。

二、 核心类方法：创建运动链

IKPy 提供多种创建运动链的方式，其中从 URDF 文件创建是最常用的方式，另外还有手动创建方式，具体如下：

1. Chain.from_urdf_file()

from ikpy.chain import Chain

# 基础用法
chain = Chain.from_urdf_file(urdf_file_path, [active_links_mask=None, base_elements=None, last_link_vector=None])

功能说明

从机器人 URDF 文件中自动解析连杆（Link）和关节（Joint）信息，构建对应的 IKPy 运动链（Chain）实例，无需手动定义连杆尺寸、关节类型等参数，直接复用 URDF 的机器人结构描述，是机器人运动学开发的便捷方式。

参数详解

参数名	含义说明	代码中使用情况
urdf_file_path	必选参数，URDF 文件的绝对路径 / 相对路径（字符串类型），指定要解析的机器人模型文件	urdf_path（已提前获取的 URDF 路径）
active_links_mask	可选参数，布尔列表 / 整数列表，用于指定运动链中的 “活跃连杆”（可动连杆），非活跃连杆会被固定	代码中未显式指定，默认所有连杆均活跃
base_elements	可选参数，列表类型，指定运动链的基座（根连杆）对应的 URDF 元素名称，默认自动识别根连杆	代码中未指定，使用默认值
last_link_vector	可选参数，3D 向量（列表 / 数组），指定末端连杆的延伸向量（用于修正末端执行器位置）	代码中未指定，使用默认值

返回值

返回ikpy.chain.Chain类的实例对象（代码中赋值给chain变量），该对象包含了机器人运动链的所有结构信息，是后续正 / 逆运动学求解的载体。

2. 补充：手动创建运动链（Chain()构造方法）

若无需依赖 URDF 文件，可手动定义连杆参数创建运动链，语法如下（了解即可，不如 URDF 方式常用）：

from ikpy.chain import Chain
from ikpy.link import Link, URDFLink

# 手动定义连杆列表
links = [
    # 基座连杆（固定）
    Link(name="base", joint_type="fixed", origin=[0,0,0]),
    # 旋转连杆1
    URDFLink(name="link1", joint_type="revolute", origin=[0,0,0.1], axis=[0,1,0]),
    # 可添加更多连杆...
]
# 手动创建运动链
chain = Chain(links=links, name="my_robot_chain")

三、 核心对象属性：访问运动链结构信息

创建chain实例后，可通过其内置属性获取机器人运动链的详细结构信息。

1. chain.links

# 获取运动链中所有连杆的列表
link_list = chain.links

功能说明

返回一个 **ikpy.link.Link对象列表 **，列表中的每个元素对应机器人的一个连杆（从基座（根连杆）到末端执行器（最后一个连杆）按顺序排列），通过遍历该列表可获取每个连杆的详细信息（如名称、关节类型等）。

代码对应场景

# 遍历chain.links，打印每个连杆的索引、名称和关节类型
for i, link in enumerate(chain.links):
    print(f"Link {i}: {link.name} (Type: {link.joint_type})")

• link：列表中的每个元素，是ikpy.link.Link对象，表征单个连杆；
• 遍历顺序：与 URDF 文件中连杆的定义顺序一致，从基座（索引 0）到末端执行器（索引len(chain.links)-1）。

2. link.name

# 获取单个连杆的名称
link_name = link.name

功能说明

返回字符串类型的连杆名称，该名称与 URDF 文件中<link name="xxx">标签定义的名称完全一致，用于识别连杆身份。

3. link.joint_type

# 获取单个连杆对应的关节类型
joint_type = link.joint_type

返回字符串类型的关节类型，与 URDF 文件中<joint type="xxx">标签定义的类型一致，核心取值包括：

• "revolute"：旋转关节（可绕单一轴旋转，如机械臂舵机关节）；
• "prismatic"：移动关节（可沿单一轴平移，如直线模组）；
• "fixed"：固定关节（无相对运动，如基座与地面的连接）；
• 其他："spherical"（球关节，较少用）。

补充：其他常用chain属性

属性名	功能说明
chain.name	返回运动链的名称（字符串类型），可在创建时指定，默认值为 "chain"
chain.n_links	返回运动链中连杆的总数（整数类型），等价于len(chain.links)
chain.active_links_mask	返回运动链的活跃连杆掩码（列表类型），标识哪些连杆是可动的

四、 核心对象方法：运动学求解（正运动学 + 逆运动学）

这是 IKPy 库的核心功能，创建chain实例后，通过其内置方法实现正 / 逆运动学求解，是机器人轨迹规划、姿态控制的基础。

1. 正运动学求解：chain.forward_kinematics()

# 基础用法
fk_transform_matrix = chain.forward_kinematics(joint_angles, [full_kinematics=False])

功能说明

已知各关节角度，求解末端执行器的位姿（位置 + 姿态），即从机器人基座开始，沿运动链的链式层级，依次计算每个连杆的位姿变换，最终得到末端执行器的全局位姿，完全依赖 URDF 解析的链式结构。

参数详解

参数名	含义说明
joint_angles	必选参数，列表 / 数组类型，长度等于运动链的关节数，存储各关节的角度（旋转关节，单位：弧度）/ 位移（移动关节，单位：米）
full_kinematics	可选参数，布尔类型，默认False；设为True时，返回所有连杆的位姿矩阵，而非仅末端连杆

返回值

• 当full_kinematics=False（默认）：返回4x4 齐次变换矩阵（numpy 数组），该矩阵包含末端执行器的位置和姿态信息：
  • 矩阵的[:3, 3]部分：提取末端执行器的 3D 位置（x, y, z）；
  • 矩阵的[:3, :3]部分：提取末端执行器的姿态（旋转矩阵）。
• 当full_kinematics=True：返回一个列表，列表中的每个元素是对应连杆的 4x4 齐次变换矩阵，可获取所有连杆的位姿。

# 假设关节角度全为0（零位姿态）
joint_angles = [0] * len(chain.links)
# 正运动学求解
fk_matrix = chain.forward_kinematics(joint_angles)
# 提取末端执行器的3D位置
end_effector_pos = fk_matrix[:3, 3]
# 提取末端执行器的旋转矩阵
end_effector_rot = fk_matrix[:3, :3]
print("末端执行器位置：", end_effector_pos)
print("末端执行器旋转矩阵：", end_effector_rot)

2. 逆运动学求解：chain.inverse_kinematics()

# 基础用法
joint_angles_solution = chain.inverse_kinematics(target_position, [target_orientation=None, initial_joint_angles=None, verbose=False])

功能说明

已知末端执行器的目标位姿（位置 / 姿态），求解满足该位姿的关节角度，是正运动学的逆过程，通过迭代算法求解（默认使用 LM 算法），同样依赖 URDF 解析的链式结构。

参数详解

参数名	含义说明
target_position	必选参数，列表 / 数组类型（3 个元素），指定末端执行器的目标 3D 位置（x, y, z）
target_orientation	可选参数，列表 / 数组类型（3x3 旋转矩阵或 4 元素四元数），指定末端目标姿态；默认None，仅约束位置
initial_joint_angles	可选参数，列表 / 数组类型，指定迭代求解的初始关节角度；默认None，使用零位姿态作为初始值
verbose	可选参数，布尔类型，默认False；设为True时，打印迭代求解过程的详细信息（方便调试）

返回值

返回列表类型，长度等于运动链的关节数，存储满足末端目标位姿的关节角度解（旋转关节：弧度；移动关节：米）。

# 定义末端执行器目标位置（x=0.2, y=0, z=0.3）
target_pos = [0.2, 0, 0.3]
# 定义末端执行器目标姿态（可选，这里用单位旋转矩阵，表示无旋转）
target_rot = np.eye(3)
# 逆运动学求解
joint_solution = chain.inverse_kinematics(target_position=target_pos, target_orientation=target_rot)
print("满足目标位姿的关节角度：", joint_solution)

五、 补充：ikpy.link模块（连杆定义）

IKPy 的link模块提供了连杆相关的类，用于描述单个连杆的属性，核心类包括：

1. Link：基础连杆类，手动创建运动链时使用，需手动指定连杆名称、关节类型、原点坐标、旋转轴等参数；
2. URDFLink：继承自Link，专门用于从 URDF 文件解析连杆信息，无需手动配置参数，Chain.from_urdf_file()内部会自动使用该类创建连杆实例。

常用Link类属性（补充）

属性名	含义说明
link.origin	连杆的原点坐标（相对于父连杆的位置，3D 向量）
link.axis	连杆对应关节的运动轴（旋转 / 移动轴，3D 向量）
link.length	连杆的长度（标量，简化的连杆尺寸描述）
link.mass	连杆的质量（标量，物理属性，部分运动学求解会用到）

六、 IKPy 专属语法核心总结

1. 核心载体：ikpy.chain.Chain类是所有操作的核心，表征机器人运动链；
2. 实例创建：Chain.from_urdf_file(urdf_path)是最常用方式，自动解析 URDF 构建运动链；
3. 结构访问：chain.links获取所有连杆列表，link.name/link.joint_type访问单个连杆属性；
4. 核心功能：
   • 正运动学：chain.forward_kinematics(joint_angles)，关节角度→末端位姿；
   • 逆运动学：chain.inverse_kinematics(target_position)，末端位姿→关节角度；
5. 关键特性：所有语法均围绕 “URDF 链式结构” 展开，无需重复定义机器人模型，直接对接机器人仿真 / 实际硬件，简化运动学开发流程。