pybullet.addUserDebugLine

1.pybullet.addUserDebugLine

PyBullet 中用于在仿真可视化窗口中绘制自定义调试线段的核心函数，常用于标记坐标系、显示路径、标注关键位置等场景.

1.1核心语法（函数签名）

p.addUserDebugLine 有 2 个必选参数，多个可选参数，基础调用格式如下

# 基础调用
line_id = p.addUserDebugLine(
    lineFromXYZ,  # 必选：线段起点
    lineToXYZ,    # 必选：线段终点
    lineColorRGB=[1, 0, 0],  # 可选：线段颜色
    lineWidth=1,  # 可选：线段宽度
    lifeTime=0,   # 可选：线段存活时间
    physicsClientId=0  # 可选：仿真客户端ID
)

1.2参数详细说明

参数名	类型	是否必选	默认值	核心说明
lineFromXYZ	list/tuple	是	-	线段起点 的三维坐标（x, y, z），对应世界坐标系中的位置示例：[0, 0, 0]（世界原点）、[1, 0.5, 0.2]
lineToXYZ	list/tuple	是	-	线段终点 的三维坐标（x, y, z），与起点共同确定线段的长度和方向示例：[1, 0, 0]（沿 x 轴正方向 1m 处）、[0, 1, 0.5]
lineColorRGB	list/tuple	否	[1, 0, 0]	线段的 RGB 颜色值，每个元素范围为 0~1（0 为最小值，1 为最大值）常用颜色：- 红色：[1, 0, 0]（默认）- 绿色：[0, 1, 0]- 蓝色：[0, 0, 1]- 白色：[1, 1, 1]- 黑色：[0, 0, 0]
lineWidth	float/int	否	1	线段的显示宽度，数值越大线段越粗（受可视化窗口缩放影响，仅用于视觉效果，不参与物理计算）示例：2（较粗）、5（粗线，用于重点标注）
lifeTime	float	否	0	线段的存活时间 （单位：秒），控制线段在窗口中显示的时长- 0：永久存活（直到仿真断开或手动删除线段）- 大于 0 的数值：存活指定秒数后自动消失示例：2.5（线段显示 2.5 秒后消失）
physicsClientId	int	否	0	物理仿真客户端 ID，用于多仿真环境区分（单环境下无需手动指定）

1.3返回值说明

p.addUserDebugLine 的返回值是 line_id（整数类型）：

1. 该值是绘制的调试线段的唯一标识符，每个线段对应一个唯一 ID
2. 后续可通过 p.removeUserDebugItem(line_id) 手动删除该线段（无论线段是否设置了存活时间）
3. 若绘制失败（如坐标参数格式错误），通常返回 -1

1.4关键使用补充

1.4.1. 线段的核心特性

• 无物理属性：调试线段仅用于可视化标注，不参与物理碰撞、受力计算，不会对仿真中的模型产生任何影响
• 坐标系依赖：线段的坐标基于 PyBullet 世界坐标系，若需跟随模型移动，需在仿真循环中实时重新绘制
• 多层绘制：支持同时绘制多条线段，后绘制的线段会覆盖先绘制的线段（视觉上重叠显示）

1.4.2. 手动删除线段

若需要主动移除已绘制的线段（而非等待自动消失），可使用 p.removeUserDebugItem()，示例：

# 绘制一条永久存活的线段
line1_id = p.addUserDebugLine([0,0,0], [1,0,0], [1,0,0])
# 手动删除该线段
p.removeUserDebugItem(line1_id)

1.5 常见使用场景

1. 坐标系标注：绘制 X/Y/Z 三轴，明确世界坐标系方向（如示例中的红、绿、蓝三轴）
2. 位置标注：标记模型关键位置（如机器人基座、目标点），便于观察位置变化
3. 路径显示：按时间序列绘制线段，显示模型的运动轨迹（如机器人移动路径）
4. 范围标注：绘制边界线段，标注仿真场景的有效范围（如工作空间边界）
5. 临时提示：绘制短期存活的线段，提示仿真中的关键事件（如碰撞发生位置）

1.6 常见使用场景

1. 坐标系标注：绘制 X/Y/Z 三轴，明确世界坐标系方向（如示例中的红、绿、蓝三轴）
2. 位置标注：标记模型关键位置（如机器人基座、目标点），便于观察位置变化
3. 路径显示：按时间序列绘制线段，显示模型的运动轨迹（如机器人移动路径）
4. 范围标注：绘制边界线段，标注仿真场景的有效范围（如工作空间边界）
5. 临时提示：绘制短期存活的线段，提示仿真中的关键事件（如碰撞发生位置）

2.pybullet.addUserDebugText

pybullet.addUserDebugText（简写为 p.addUserDebugText）的语法，这是 PyBullet 中用于在仿真可视化窗口中绘制自定义调试文本的核心函数，常用于标注模型名称、显示关键参数（位置 / 速度）、标记仿真状态等场景

2.1 核心语法（函数签名）

p.addUserDebugText 有 2 个必选参数，多个可选参数，基础调用格式如下：

# 基础调用
text_id = p.addUserDebugText(
    text,          # 必选：要显示的文本内容
    textPosition,  # 必选：文本在世界坐标系中的位置
    textColorRGB=[1, 1, 1],  # 可选：文本颜色
    textSize=1,              # 可选：文本大小
    lifeTime=0,               # 可选：文本存活时间
    parentObjectUniqueId=-1,  # 可选：父物体ID（文本跟随父物体移动）
    parentLinkIndex=-1,       # 可选：父物体连杆索引
    physicsClientId=0         # 可选：仿真客户端ID
)

2.2 参数详细说明

参数名	类型	是否必选	默认值	核心说明
text	str	是	-	要显示的调试文本内容，支持普通字符串、格式化字符串（如"机器人ID：{}".format(robot_id)）示例："World Origin"、"Robot Base"、f"Pos: {x:.2f}"
textPosition	list/tuple	是	-	文本锚点的三维坐标（x, y, z），基于世界坐标系（若指定父物体，则基于父物体局部坐标系）示例：[0, 0, 0]（世界原点）、[0, 0, 0.8]（机器人上方 0.8m 处）
textColorRGB	list/tuple	否	[1,1,1]	文本的 RGB 颜色值，每个元素范围为 0~1（0 为最小值，1 为最大值）常用颜色：- 白色：[1,1,1]（默认）、黑色：[0,0,0]- 红色：[1,0,0]、绿色：[0,1,0]、蓝色：[0,0,1]
textSize	float/int	否	1	文本的显示大小，数值越大文本越清晰（受可视化窗口缩放影响，仅视觉效果）示例：0.8（小号文本）、1.5（大号文本，用于重点标注）
lifeTime	float	否	0	文本的存活时间 （单位：秒），控制文本在窗口中显示的时长- 0：永久存活（直到仿真断开或手动删除）- 大于 0 的数值：存活指定秒数后自动消失示例：3.0（文本显示 3 秒后消失）
parentObjectUniqueId	int	否	-1	父物体的唯一 ID（由p.loadURDF()返回），用于让文本跟随父物体移动 / 旋转- -1：无父物体，文本固定在世界坐标系中- 非负整数：文本绑定到对应父物体，随父物体一起运动示例：robot_id（文本跟随机器人移动）
parentLinkIndex	int	否	-1	父物体的连杆索引，配合parentObjectUniqueId使用- -1：绑定到父物体的基座（默认）- 非负整数：绑定到父物体的指定连杆（如机械臂的末端执行器）
physicsClientId	int	否	0	物理仿真客户端 ID，用于多仿真环境区分（单环境下无需手动指定）

2.3 返回值说明

2.3.1. 文本的核心特性

• 无物理属性：调试文本仅用于可视化标注，不参与物理碰撞、受力计算，不会对仿真模型产生任何影响
• 绑定特性 ：通过parentObjectUniqueId可绑定到任意仿真物体，实现 "文本跟随物体移动" 的效果（无需手动更新位置）
• 层级特性：支持同时绘制多个文本，后绘制的文本会覆盖先绘制的文本（视觉上重叠显示）
• 格式支持：支持 Python 格式化字符串，可实时显示仿真参数（如位置、速度、步数等）

2.3.2. 手动删除文本

若需要主动移除已绘制的文本（而非等待自动消失），可使用 p.removeUserDebugItem()，示例：

# 绘制永久存活的文本
text1_id = p.addUserDebugText("Hello PyBullet", [0,0,0], [1,0,0])
# 手动删除该文本
p.removeUserDebugItem(text1_id)

2.3.3. 动态更新文本

若需要实时更新文本内容（如显示机器人实时位置），有两种实现方式：

1. 先删除旧文本，再绘制新文本（推荐，逻辑简单）
2. 暂不支持直接修改已有文本内容，需通过 "删除 + 重绘" 实现更新

2.4 常见使用场景

1. 固定标注：标记世界坐标系关键位置（如原点、目标点）、场景名称等
2. 跟随标注：绑定到仿真物体，显示物体名称（如 "R2D2 机器人"、"地面"）、物体 ID 等
3. 动态参数显示：实时更新文本，显示机器人位置 / 速度、仿真步数、重力参数等
4. 状态提示：绘制短期存活的文本，提示仿真关键事件（如 "速度已更新"、"碰撞发生"）
5. 连杆标注：绑定到机器人指定连杆，显示连杆名称（如 "末端执行器"、"肩关节"）

2.5 总结

1. 核心语法：text_id = p.addUserDebugText(text, textPosition, [可选参数])，必选参数仅文本内容和文本位置
2. 关键参数：textColorRGB（颜色）、textSize（大小）、lifeTime（存活时间）、parentObjectUniqueId（跟随父物体）是高频使用参数
3. 返回值：text_id 是文本唯一标识，用于手动删除文本（p.removeUserDebugItem）
4. 核心特性：文本无物理属性，仅可视化；支持绑定物体跟随移动；需通过 "删除 + 重绘" 实现动态更新
5. 常用场景：固定标注、跟随标注、动态参数显示、状态提示等，是 PyBullet 仿真调试和可视化的重要工具

3. p.addUserDebugParameter和p.readUserDebugParameter

调用了 PyBullet 的 p.addUserDebugParameter 函数（中文可译为 "添加用户调试参数"），这是 PyBullet GUI 模式下的核心调试工具，专门用于在可视化窗口中创建交互式控件，实现对仿真过程的实时手动调节。

3.1 核心语法（函数签名）

param_id = p.addUserDebugParameter(paramName, lowerLimit, upperLimit, initialValue)

eg1

mode_slider = p.addUserDebugParameter("Control Mode (0:Pos, 1:Torque)", 0, 1, 1)

参数位置	参数值	含义说明
paramName	"Control Mode (0:Pos, 1:Torque)"	滑块显示名称（在 PyBullet GUI 窗口中可见），用于提示用户滑块功能（切换控制模式）
lowerLimit	0	滑块最小值（对应位置控制模式，0=Position Control）
upperLimit	1	滑块最大值（对应力矩控制模式，1=Torque Control / Physics Enabled）
initialValue	1	滑块初始值（默认启用力矩控制模式，符合代码注释中的要求）
返回值	mode_slider	该滑块的唯一 ID（后续通过该 ID 读取滑块当前值，实现控制模式切换）

核心功能 ：创建一个仅支持 0 和 1 两个离散值的滑块（本质是数值滑块，用户可拖动或直接输入），用于实时切换机器人关节的控制模式（位置控制 / 力矩控制），其中力矩控制会启用完整物理特性（如重力负载、力矩约束等）。

eg2

speed_slider = p.addUserDebugParameter("Speed (sec/edge)", 1.0, 10.0, 3.0)

参数位置	参数值	含义说明
paramName	"Speed (sec/edge)"	滑块显示名称，提示用户该滑块用于调节 "每个运动阶段的耗时（秒 / 运动步）"
lowerLimit	1.0	滑块最小值（对应最快运动速度，仅需 1 秒完成单个运动步骤）
upperLimit	10.0	滑块最大值（对应最慢运动速度，需要 10 秒完成单个运动步骤）
initialValue	3.0	滑块初始值（默认运动速度：3 秒完成单个运动步骤）
返回值	speed_slider	该滑块的唯一 ID（后续通过该 ID 读取当前速度值，调节机器人运动快慢）

核心功能：创建一个连续数值滑块（支持 1.0~10.0 之间的任意浮点数），用于实时调节机器人的运动速度（本质是调节运动指令的执行耗时，间接控制关节运动的快慢）。

3.2 核心配套关系

1. p.addUserDebugParameter：创建交互参数控件（如滑动条、下拉框、按钮），显示在 PyBullet GUI 窗口的调试面板中，供用户手动操作调节参数。
2. p.readUserDebugParameter：读取控件的实时值，传入控件对应的唯一 ID，即可获取用户当前调节的参数值，供仿真程序逻辑使用。
3. 二者是「创建 - 读取」的绑定关系，没有 p.addUserDebugParameter 创建控件，p.readUserDebugParameter 就没有可读取的目标。

eg

control_mode = int(p.readUserDebugParameter(mode_slider) + 0.5)

功能

读取「模式选择滑动条」的实时值，并转换为整数类型，用于控制仿真中的逻辑模式（如机器人运动模式、控制策略切换）。

代码片段	核心说明
mode_slider	由 p.addUserDebugParameter 创建控件时返回的控件唯一 ID（整数类型），用于指定要读取的目标控件（此处对应 "模式调节滑动条"）。
p.readUserDebugParameter(mode_slider)	核心函数调用：传入控件 ID mode_slider，返回该控件当前的实时数值（浮点型，即使是整数滑动条，返回值也默认是浮点型）。
+ 0.5	这是四舍五入的巧妙实现 ：由于 p.readUserDebugParameter 返回浮点值，直接用 int() 转换会截断小数部分（如 2.9 转为 2），加 0.5 后再转 int 可实现近似四舍五入（如 2.9+0.5=3.4→int(3.4)=3，2.1+0.5=2.6→int(2.6)=2）。
int(...)	将浮点型的读取结果（加 0.5 后）转换为整数类型，因为 control_mode（控制模式）通常是离散的整数（如 0 = 位置控制、1 = 速度控制、2 = 力控制）。
control_mode = ...	将转换后的整数模式值赋值给变量，供后续仿真逻辑判断使用。

eg

edge_duration = p.readUserDebugParameter(speed_slider)

功能

读取「速度调节滑动条」的实时浮点值，用于控制仿真中的连续参数（如运动速度、持续时间、阻尼系数等）。

代码片段	核心说明
speed_slider	由 p.addUserDebugParameter 创建的「速度调节滑动条」控件 ID（整数类型）。
p.readUserDebugParameter(speed_slider)	读取该速度滑动条的实时值，返回浮点型（滑动条的核心特性是返回连续浮点值，适配速度、时长等连续参数的调节）。
edge_duration = ...	直接将浮点型读取结果赋值给变量（无需类型转换），因为 edge_duration（边缘持续时间 / 速度参数）是连续值，可直接用于仿真计算。

3.3 p.readUserDebugParameter 核心特性

1. 参数类型 ：仅需传入一个参数 ------userDebugParameterId（控件唯一 ID，由 p.addUserDebugParameter 返回）。
2. 返回值类型 ：
   • 滑动条（p.addUserDebugParameter 的 p.PARAMETER_FLOAT/p.PARAMETER_INT 类型）：返回浮点型（即使是整数滑动条，也会返回 x.0 格式的浮点值）。
   • 下拉框（p.PARAMETER_ENUM 类型）：返回浮点型对应的整数索引（加 0.5 后转 int 即可）。
   • 按钮（p.PARAMETER_BUTTON 类型）：返回布尔值对应的浮点型（0.0= 未按下，1.0= 已按下）。
3. 实时性：每次调用都会获取控件的当前最新值，在仿真循环中调用可实现「用户调节参数 → 程序实时响应」的交互效果。
4. 无物理属性：仅用于读取交互参数，不影响仿真物理计算，仅作为逻辑控制的输入。

3.4 关键补充说明

1. 控件类型适配 ：
   • 若 p.addUserDebugParameter 创建的是「下拉框（p.PARAMETER_ENUM）」，读取后同样需要 int(val + 0.5) 转换为整数索引，用于选择下拉选项。
   • 若创建的是「按钮（p.PARAMETER_BUTTON）」，读取后可通过 bool(int(val + 0.5)) 转换为布尔值，判断按钮是否被按下。
2. 实时响应 ：必须在仿真循环中调用 p.readUserDebugParameter，才能实时获取用户调节的参数值，实现 "调节即生效" 的效果。
3. 参数用途 ：
   • control_mode（整数型）：通常用于 if/elif 逻辑判断，切换离散的仿真模式。
   • edge_duration（浮点型）：通常用于直接参与物理计算，如设置速度、时长、阻尼等连续参数。

3.5 总结

1. 核心配套：p.addUserDebugParameter（创建交互控件）←→ p.readUserDebugParameter（读取控件值），实现用户与仿真的交互。
2. 第一行代码：读取模式滑动条值，通过 +0.5+int() 实现四舍五入转整数，用于离散模式切换。
3. 第二行代码：读取速度滑动条值，直接获取浮点型，用于连续参数计算。
4. 关键特性：p.readUserDebugParameter 传入控件 ID 即可读取实时值，需在仿真循环中调用以实现实时响应。
5. 核心用途：实现 "可视化窗口手动调节参数 + 仿真程序实时使用参数"，大幅提升仿真调试的便捷性。