《PyBullet入门精华》

---

1 PyBullet入门介绍

---

2 相机入门介绍

---

3 机械臂入门介绍

---

4 URDF入门介绍

---

5 机械臂与强化学习

---

---

1、学习建议：通读PyBullet源码十分有必要

PyBullet源码十分重要，里面包含了很多例子，可以直接拿来使用。提醒大家，不要单一依赖PyBullet官方教程或者网上各个技术博主的经验分享，很多时候，这些介绍并不全面，真正全面的介绍还得看PyBullet源码的例子。

2、PyBullet源码存放位置

我本机上PyBullet源码的存放地址为：

D:\Python37\Lib\site-packages

在这个目录下，PyBullet源码相关的包是这些，如下图所示：

3、pybullet_data介绍

这是最核心的资产包，包含了所有预置的机器人模型、物体和环境场景。

pybullet_data的目的是开箱即用，无需自己寻找或制作机器人模型，包含各种机器人构型的URDF示例。

pybullet_data/
├── urdf/                    # 主要模型目录
│   ├── kuka_iiwa/          # KUKA LBR iiwa机械臂
│   ├── franka_panda/       # Franka Emika Panda机械臂
│   ├── urdf/               # Universal Robots系列（UR5、UR10）
│   ├── humanoid/           # 双足人形机器人
│   ├── plane.urdf          # 基本地面
│   └── ...                 # 其他机器人
├── sdf/                    # SDF格式模型
├── mjcf/                   # MuJoCo格式模型
├── robot_data/             # 机器人配置数据
├── tessellation/           # 网格细分数据
└── ...

如何使用pybullet_data呢？请看下面的代码：

import pybullet as p
import pybullet_data

# 设置数据路径（关键步骤！）
p.setAdditionalSearchPath(pybullet_data.getDataPath())

# 现在可以轻松加载模型
plane_id = p.loadURDF("plane.urdf")  # 自动在pybullet_data中查找
kuka_id = p.loadURDF("kuka_iiwa/model.urdf", [0,0,0])

4、pybullet_envs介绍

这是PyBullet的强化学习环境套件，实现了多个标准的Gymnasium（原OpenAI Gym）环境。它主要包含两大环境类别：机器人运动控制和机器人操作任务。

机器人 locomotion（运动控制）：

环境名称	仿生对象	核心任务
HalfCheetahBulletEnv	猎豹	在平面上高速奔跑
AntBulletEnv	蚂蚁	稳定、灵活的多足行走
HopperBulletEnv	单腿机器人	连续跳跃前进并保持平衡
Walker2DBulletEnv	双足机器人	模拟人类步行
HumanoidBulletEnv	人形机器人	复杂的全身平衡与行走

机器人 manipulation（操作任务）：

环境名称	机器人平台	核心任务
KukaGymEnv	KUKA iiwa 机械臂	抓取、放置或操作物体
RacecarGymEnv	轮式小车	导航、避障、速度控制
PandaGymEnv	Franka Panda 机械臂	灵巧操作与交互任务

pybullet_envs的基本使用如下所示：

import gymnasium as gym
import pybullet_envs

# 创建环境（与标准Gym API完全兼容）
env = gym.make("HalfCheetahBulletEnv-v0")

# 标准RL交互循环
observation, info = env.reset()
for _ in range(1000):
    action = env.action_space.sample()  # 随机动作
    observation, reward, terminated, truncated, info = env.step(action)

pybullet_envs的特点：

直接替代MuJoCo环境：接口与MuJoCo版本完全一致

支持无头模式：训练时自动使用DIRECT模式加速

包含基准性能：提供参考分数用于算法评估

5、pybullet_utils的使用介绍

这是PyBullet的瑞士军刀工具箱，包含各种辅助函数，不依赖C++扩展（纯Python）。其主要模块如下所示：

5.1、变换工具 (transformations.py)

from pybullet_utils.transformations import *
# 四元数操作
quat = quaternion_from_euler(0, 0, 0)
euler = euler_from_quaternion([0, 0, 0, 1])
# 坐标变换
T = translation_matrix([1, 2, 3])
R = rotation_matrix(0.5, [0, 0, 1])

5.2、 摄像机工具 (camera.py)

from pybullet_utils.camera import Camera
# 创建摄像机
cam = Camera(p, robot_id)
# 获取图像
rgb, depth, seg = cam.get_images()
# 保存截图
cam.save_rgb("screenshot.png")

5.3、URDF编辑器 (urdfEditor.py)

from pybullet_utils.urdfEditor import UrdfEditor
# 可视化编辑URDF
editor = UrdfEditor()
editor.loadUrdf("robot.urdf")
# 交互式修改关节、链接

5.4、 VR/AR支持 (xr.py)

from pybullet_utils.xr import XRController
# 连接VR设备
controller = XRController(p)
# 获取手柄位置
pos, orn = controller.get_pose()

5.5、数学工具 (bullet.py)

from pybullet_utils.bullet import *
# 线段相交检测
hit, pos, normal = rayTestSegments(ray_from, ray_to)
# AABB（轴向包围盒）计算
aabb_min, aabb_max = getAABB(robot_id)

6、pybullet_robots介绍

注意：这个包是机器人专用接口，但是在较新版本中已逐渐被整合到pybullet_data和pybullet_envs中，但在一些旧代码中仍能看到。其遗留功能主要有：

from pybullet_robots.panda.panda_sim import PandaSim
# 创建Panda机器人仿真器
panda = PandaSim(p, position=[0,0,0])
# 提供更高级的控制接口
panda.move_to_joint_positions([0,0,0,0,0,0,0])

7、pybullet_examples介绍

pybullet_examples 是 PyBullet 官方提供的示例代码集合，用于展示各种功能用法和 API 调用方式，相当于一个 “活文档” 和 “功能演示库”。这个文件夹包含了从基础到高级的100多个独立示例脚本，涵盖了 PyBullet 的绝大部分功能。它不是通过安装包分发的，而是包含在 PyBullet 的 GitHub 源码仓库中。pybullet_examples核心内容分为下面几大类别：

7.1、基础仿真示例

文件名	功能说明
hello_world.py	最简示例：加载地面和立方体
simBrick.py	基础物理：堆叠方块测试
simCubes.py	大量刚体性能测试
gravity.py	自定义重力场演示

7.2、机器人控制示例

文件名	功能说明
simIK.py	逆运动学求解演示
inverse_kinematics.py	多种逆运动学算法对比
simJointControl.py	关节位置/速度/力矩控制
simCartPole.py	经典倒立摆控制
simTwoJoints.py	简单二连杆控制

7.3、传感器与数据获取

文件名	功能说明
getCameraImage.py	获取相机图像（RGB、深度、分割）
pointCloudFromCameraImage.py	深度图转点云
raytraceDemo.py	射线碰撞检测
contactPoints.py	接触力获取与分析

7.4、文件格式与模型加载

文件名	功能说明
loadURDF.py	URDF 文件加载的各种选项
loadSDF.py	SDF 格式加载演示
importSTL.py	STL 网格文件导入
pybullet_save_state.py	仿真状态保存与恢复

7.5、特定机器人示例

文件名	功能说明
kuka.py	KUKA iiwa 机械臂控制
panda.py	Franka Panda 机械臂演示
humanoid.py	人形机器人步行控制
racecar.py	赛车仿真与控制
quadruped.py	四足机器人运动

7.6、高级功能

文件名	功能说明
simSoftBody.py	软体动力学（布料、气球）
simDeformable.py	可变形体仿真
simConstraint.py	自定义约束和关节
minitaur.py	复杂机器人（Minitaur）控制
vr.py	VR 虚拟现实集成

8、如何使用pybullet_examples中的代码示例

8.1、直接从源码运行

# 克隆源码仓库
git clone https://github.com/bulletphysics/bullet3.git

# 进入示例目录
cd bullet3/examples/pybullet/examples

# 运行具体示例
python hello_world.py
python kuka.py

8.2、在 PyBullet 安装后查找

import pybullet as p
import os

# 获取示例路径（如果通过pip安装）
# 注意：pip安装的版本可能不包含所有示例
data_path = p.getDataPath()
print(data_path)  # 可能指向包含示例的目录

8.3、作为代码模板学习

# 例如：学习如何获取相机图像
# 查看 getCameraImage.py 的代码结构：

import pybullet as p
import pybullet_data

# 连接物理服务器
p.connect(p.GUI)
p.setAdditionalSearchPath(pybullet_data.getDataPath())

# 加载场景
p.loadURDF("plane.urdf")
robot = p.loadURDF("r2d2.urdf", [0,0,1])

# 设置相机参数
view_matrix = p.computeViewMatrix(
    cameraEyePosition=[0.5, 0, 1],
    cameraTargetPosition=[0, 0, 0],
    cameraUpVector=[0, 0, 1]
)
projection_matrix = p.computeProjectionMatrixFOV(
    fov=60, aspect=1.0, nearVal=0.1, farVal=100.0
)

# 获取图像（核心API使用）
width, height = 320, 240
images = p.getCameraImage(
    width, height,
    view_matrix,
    projection_matrix,
    shadow=True
)

# images包含：RGB、深度、蒙版等
rgb_array = images[2]  # RGB像素数据

9、pybullet_examples的学习路径建议

用户层次	学习阶段	关键示例文件	核心学习目标
初学者	0-1周	hello_world.py	掌握最基本的仿真环境搭建与启动流程
		simBrick.py	理解刚体物理的基础概念（质量、碰撞、堆叠）
		loadURDF.py	学习加载和导入标准的机器人/物体模型文件
中级用户	1-4周	simIK.py	掌握机械臂逆运动学原理与求解方法
		getCameraImage.py	学习配置虚拟摄像头并获取RGB、深度、分割图像
		kuka.py	理解从模型加载、运动学求解到关节控制的完整机器人控制流程
高级用户	1个月以上	simSoftBody.py	探索布料、绳索等可变形体的软体动力学仿真
		vr.py	了解与虚拟现实(VR)设备进行集成的交互方法
		minitaur.py	学习复杂四足机器人的运动控制与平衡算法

这个表格清晰地展示了从入门到精通的不同阶段，每个阶段对应的关键学习示例及其要达成的核心目标，便于使用者根据自身水平进行针对性的学习和实践。

---