Skip to main content

Python API 参考 - S1 机器

  • GalbotRobot: 核心机器人控制模块。用于机器人连接、生命周期管理、关节控制、传感器数据查询和硬件状态监控。
  • GalbotMotion: 运动规划与执行模块。用于笛卡尔空间/关节空间运动、轨迹规划、逆运动学和全身控制。
  • GalbotNavigation: 移动导航模块。用于移动底盘定位、地图构建、路径规划和自主移动。
  • GalbotPerception: 端侧感知模块。加载视觉模型、运行推理，并读取结构化结果（如立体深度）；与GalbotRobot传感器API配合使用。
  • Types & Enums: 数据结构、枚举与状态类型。本节用于查询类型定义、传感器类型、错误码及其他模块使用的数据结构。

核心机器人控制（GalbotRobot）​

Galbot 人形机器人的主控接口。

此类提供了一个用于控制 Galbot 机器人的单例接口。它支持：关节位置和轨迹控制、末端执行器控制、移动基座速度控制、传感器数据采集、坐标系变换和系统生命周期管理。使用 GalbotRobot::get_instance(MachineType) 获取特定平台 (G1/S1) 的参考。除非另有说明，所有角度均以弧度为单位。除非另有说明，所有线性距离均以米为单位。除非另有说明，所有时间戳均以纳秒为单位。

获取控制器权限（acquire_controller）​

def acquire_controller(controller_name: str) -> ControlStatus

获取硬件控制权限。

请求指定控制器接管硬件控制。该操作与 switch_controller 使用同一套 WBCS 切换请求机制。

参数

名称类型默认值描述
controller_namestr需要传参控制器名称字符串，例如 "left_arm_pvt_ctrl"。

返回值

类型描述
ControlStatus控制状态，指示获取操作的成功或失败

检查轨迹执行状态（check_trajectory_execution_status）​

def check_trajectory_execution_status(
    joint_groups: Sequence[str] = []
) -> list[TrajectoryControlStatus]

获取指定关节组的轨迹执行状态。

查询指定关节组的轨迹当前执行状态。这对于在非阻塞执行模式下监视轨迹进度很有用。

参数

名称类型默认值描述
joint_groupsSequence[str][]关节组列表

返回值

类型描述
list[TrajectoryControlStatus]轨迹控制状态列表：轨迹执行状态列表。

清除末端执行器命令（clear_end_effector_command）​

def clear_end_effector_command() -> ControlStatus

清除 WBC 末端执行器任务命令。

清除已发布到 WBC 通道的末端执行器任务轨迹命令。

返回值

类型描述
ControlStatus控制状态，表示命令发布结果。

销毁（destroy）​

def destroy() -> None

清理系统资源。

执行机器人控制系统资源的最终清理，包括中间件连接、传感器接口和通信通道。这是关闭序列的最后一步：request_shutdown() -> wait_for_shutdown() -> destroy()。

此方法应在程序结束时调用一次。调用 destroy() 后，SDK 进入终态，无法在同一进程重新初始化。如需再次使用，请退出当前进程并启动新进程。

执行关节轨迹（execute_joint_trajectory）​

def execute_joint_trajectory(trajectory: Trajectory, is_blocking: bool = True) -> ControlStatus

执行预先规划的关节轨迹。

执行由路径点组成的轨迹，每个路径点都关联着关节位置、速度和时间信息。轨迹控制器在路径点之间进行插值，以生成平滑的运动。

对于标准关节（头部、腿部、手臂），当前版本中只有位置有效；速度、加速度和力度目前被忽略。

参数

名称类型默认值描述
trajectoryTrajectory需要传参轨迹数据结构，包含路点和时序信息。必须指定 trajectory.joint_groups 或 trajectory.joint_names；如果两者都为空，则返回 INVALID_INPUT。
is_blockingboolTrue是否阻塞等待完成

返回值

类型描述
ControlStatus控制状态，指示轨迹执行/提交的成功或失败
warning

每个 TrajectoryPoint.joint_command_vec 的顺序必须与 trajectory.joint_names 定义的关节顺序或 trajectory.joint_groups 的展开顺序一致。

warning

对于逐帧模型推理输出，建议使用命令流式接口（set_joint_commands / set_joint_commands_batch），而不是反复重新提交完整轨迹。

获取当前控制器（get_active_controller）​

def get_active_controller(group_name: str) -> str

获取指定关节组的活动控制器名称。

返回当前 SDK 实例记录的该关节组控制器。该值会以模型默认控制器初始化，并在 SDK 控制器管理接口成功调用后更新。若控制已释放或该关节组无已知控制器，则返回 "CONTROLLER_NAME_NUM"。

参数

名称类型默认值描述
group_namestr需要传参要查询的关节组名称。

返回值

类型描述
strstd::string：当前 SDK 实例已知的活动控制器名称。

获取相机内参（get_camera_intrinsic）​

def get_camera_intrinsic(camera_id: SensorType) -> dict

获取相机内参。

获取指定相机的内参，包括焦距、主点、畸变系数等。

参数

名称类型默认值描述
camera_idSensorType需要传参RGB相机ID

返回值

类型描述
dict字典：包含相机内参。- header: 消息头（带时间戳和帧信息） - height: 图像高度（像素） - width: 图像宽度（像素） - distortion_model: 畸变模型，如 "plumb_bob" - D: 畸变系数（浮点数列表） - K: 相机内参矩阵（9个浮点数列表） - binning_x: 水平像素合并因子 - binning_y: 垂直像素合并因子 - roi: 感兴趣区域（整数列表） - camera_type: 相机类型。失败时返回空字典。
note

相机传感器必须在初始化期间通过 enable_sensor_set 启用。

获取深度图像数据（get_depth_data）​

def get_depth_data(camera_id: SensorType) -> dict

从指定相机获取最新的深度图像。

检索指定深度相机捕获的最新深度图像。深度值通常表示距相机传感器的距离。

参数

名称类型默认值描述
camera_idSensorType需要传参RGB相机ID

返回值

类型描述
dict字典：包含以下键：- header: 消息头（带时间戳和帧信息） - format: 图像格式，如 "depth16" 或其他 - depth_scale: 深度缩放因子 - height: 图像高度（像素） - width: 图像宽度（像素） - data: 压缩深度图像二进制数据（字节）。失败时返回空字典。
note

相机传感器必须在初始化期间通过 enable_sensor_set 启用。

note

深度值通常以毫米（mm）或米（m）为单位。

获取设备信息（get_device_information）​

def get_device_information() -> dict

获取设备信息。

检索基本设备信息，包括设备型号、序列号、固件版本、硬件版本和制造商。此信息用于设备管理、版本控制、系统诊断和设备识别。

返回值

类型描述
dict指向 DeviceInfo 结构的共享指针，其中包含： - model: 设备型号名称或标识符 - serial_number: 用于设备标识的唯一序列号 - firmware_version: 系统固件版本字符串 - hardware_version: 硬件版本或修订号 - manufacturer: 制造商名称或公司标识符 如果设备信息检索失败，则返回 nullptr。

获取灵巧手状态（get_dexhand_state）​

def get_dexhand_state(end_effector: str, dexhand_type: DexHandType = ...) -> Any

获取当前灵巧手状态。

检索灵巧手反馈到 dexhand_state。对于 INSPIRE 和 BRAINCO，仅填充 dexhand_state.joint_state，force_sensor_map 为空。对于 SHARPA，填充完整关节状态以及可用的命名力传感器数据。

参数

名称类型默认值描述
end_effectorstr需要传参灵巧手名称，例如 "left_dexhand" 或 "right_dexhand"。
dexhand_typeDexHandType...灵巧手型号类型（可选，默认：INSPIRE）。

返回值

类型描述
AnyDexhandState | None: 成功时 Dexhand 状态（使用 .joint_state; .force_sensor_map for Sharpa），否则为 None。

获取坐标系名称（get_frame_names）​

def get_frame_names() -> list[str]

获取 TF 树中所有可用的坐标系名称。

返回值

类型描述
list[str]所有可用坐标系名称列表。

获取夹爪状态（get_gripper_state）​

def get_gripper_state(end_effector: str) -> GripperState

获取指定夹爪的当前状态。

返回夹爪的位置、速度、受力以及运动状态估计信息。

GripperState.is_moving 基于时间窗口判定：若在内部窗口内未检测到有效开合变化，则该值会变为 false。

参数

名称类型默认值描述
end_effectorstr需要传参要查询的夹爪关节组名称（例如 left_gripper、right_gripper）。

返回值

类型描述
GripperState指向 GripperState 的共享指针，如果检索失败则为 nullptr。

获取IMU数据（get_imu_data）​

def get_imu_data(sensor_id: SensorType) -> dict

获取 IMU（惯性测量单元）传感器数据。

检索最新的 IMU 测量值，包括线性加速度、角速度和方向估计。

参数

名称类型默认值描述
sensor_idSensorType需要传参传感器ID

返回值

类型描述
dict字典：包含以下键：- timestamp_ns: 时间戳（纳秒） - accel: 加速度 Vector3 {"x": float, "y": float, "z": float} - gyro: 陀螺仪 Vector3 {"x": float, "y": float, "z": float} - magnet: 磁力计 Vector3 {"x": float, "y": float, "z": float}。失败时返回空字典。
note

IMU 传感器必须在初始化期间通过 enable_sensor_set 启用。

note

加速度以米每二次方秒（m/s²）为单位。

note

角速度以弧度每秒（rad/s）为单位。

获取红外图像数据（get_ir_data）​

def get_ir_data(camera_id: SensorType) -> dict

从指定的红外摄像机获取最新的红外图像。

检索指定红外摄像机拍摄的最新红外图像。仅当摄像机参数配置中的 ir_enabled 设置为 true 时可用。

参数

名称类型默认值描述
camera_idSensorType需要传参要查询的红外摄像头传感器 ID。有效值：LEFT_ARM_INFRA_CAMERA_1、LEFT_ARM_INFRA_CAMERA_2、RIGHT_ARM_INFRA_CAMERA_1、RIGHT_ARM_INFRA_CAMERA_2

返回值

类型描述
dictdict：包含以下键的字典： - 'header'：包含时间戳和帧信息的消息头 - 'format'：图像格式，例如 'mono8; jpeg compressed mono8' - 'data'：压缩灰度图像二进制数据（字节） 如果相机未启用、ir_enabled 为 false 或尚未收到任何数据，则返回空字典。
note

初始化期间，必须将红外传感器包含在 enable_sensor_set 中。

note

要发生订阅，相机参数主题中的 ir_enabled 必须为 true。

获取关节组名称（get_joint_group_names）​

def get_joint_group_names() -> list[str]

获取机器人可用的关节组名称。

检索机器人运动学配置中定义的所有关节组名称。这对于在运行时发现可用的控制组很有用。

返回值

类型描述
list[str]关节组名称向量，或如果检索失败则为空向量

获取关节名称（get_joint_names）​

def get_joint_names(only_active_joint: bool = True, joint_groups: Sequence[str] = []) -> list[str]

通过组名获取机器人关节名称。

检索属于指定关节组的关节名称。这对于在设置关节位置时确定正确的顺序很有用。

参数

名称类型默认值描述
only_active_jointboolTrue是否仅返回主动关节
joint_groupsSequence[str][]关节组列表

返回值

类型描述
list[str]返回关节名称列表，顺序取决于参数配置

获取关节位置（get_joint_positions）​

def get_joint_positions(
    joint_groups: Sequence[str] = [],
    joint_names: Sequence[str] = []
) -> list[float]

获取关节位置

参数

名称类型默认值描述
joint_groupsSequence[str][]关节组列表
joint_namesSequence[str][]关节名称列表

返回值

类型描述
list[float]当前关节角度向量（弧度）
note

返回顺序：指定 joint_names 时，按 joint_names 的精确顺序返回。仅指定 joint_groups 时，按关节组定义顺序返回。两者均为空时，按机器类型相关的本体关节顺序返回：G1 为 chassis、head、left_arm、right_arm、leg；S1 为 torso、head、left_arm、right_arm。

获取关节状态（get_joint_states）​

def get_joint_states(
    joint_groups: Sequence[str] = [],
    joint_names: Sequence[str] = []
) -> list[JointState]

获取关节状态

参数

名称类型默认值描述
joint_groupsSequence[str][]关节组名称列表
joint_namesSequence[str][]具体关节名称列表，优先于 joint_groups

返回值

类型描述
list[JointState]List[JointState]：对应关节的实时状态数据。

注意返回顺序：指定 joint_names 时，按 joint_names 的精确顺序返回；仅指定 joint_groups 时，按关节组定义顺序返回；两者均为空时，按机器类型相关的本体关节顺序返回，G1 为 chassis、head、left_arm、right_arm、leg，S1 为 torso、head、left_arm、right_arm。
note

返回顺序：指定 joint_names_vec 时，按 joint_names_vec 的精确顺序返回。仅指定 joint_group_vec 时，按关节组定义顺序返回。两者均为空时，按机器类型相关的本体关节顺序返回：G1 为 chassis、head、left_arm、right_arm、leg；S1 为 torso、head、left_arm、right_arm。

获取激光雷达数据（get_lidar_data）​

def get_lidar_data(sensor_id: SensorType) -> dict

获取最新的激光雷达点云数据。

检索指定 LiDAR 传感器捕获的最新 3D 点云。每个点通常包含 (x, y, z) 坐标和可选的强度值。

参数

名称类型默认值描述
sensor_idSensorType需要传参传感器ID

返回值

类型描述
dict字典：包含点云数据字段和二进制点数据。失败时返回空字典。
note

LiDAR 传感器必须在初始化期间通过 enable_sensor_set 启用。

获取日志信息（get_log_information）​

def get_log_information(timewindow_s: SupportsInt, log_level: LogLevel) -> dict

获取日志信息。

参数

名称类型默认值描述
timewindow_sSupportsInt需要传参时间窗口（秒）
log_levelLogLevel需要传参日志级别

返回值

类型描述
dict指向包含日志信息的 LogInfo 的共享指针

获取里程计数据（get_odom）​

def get_odom() -> dict

获取机器人里程信息。

从里程计系统检索机器人当前的姿态和速度估计。里程计通常融合车轮编码器、IMU 和其他本体感觉传感器。

返回值

类型描述
dict指向 OdomData 的共享指针，其中包含： - 相对于里程计坐标系原点的位置（以米为单位） - 方向（以四元数表示） - 线速度（以米每秒为单位） - 角速度（以弧度每秒为单位） - 时间戳（以纳秒为单位） 如果里程计不可用，则返回 nullptr。

获取RGB图像数据（get_rgb_data）​

def get_rgb_data(camera_id: SensorType) -> dict

从指定相机获取最新的 RGB 图像。

检索指定 RGB 相机捕获的最新彩色图像。

参数

名称类型默认值描述
camera_idSensorType需要传参RGB相机ID

返回值

类型描述
dict字典：包含以下键：- header: 消息头（带时间戳和帧信息） - format: 图像格式，如 "jpeg" 或 "png" - data: 压缩图像二进制数据（字节）。失败时返回空字典。
note

相机传感器必须在初始化期间通过 enable_sensor_set 启用。

获取传感器外参（get_sensor_extrinsic）​

def get_sensor_extrinsic(sensor_id: SensorType, reference_frame: str = 'base_link') -> tuple

获取传感器外参。

检索指定传感器的外部参数，包括相对于机器人基础坐标系的旋转和平移向量。

参数

名称类型默认值描述
sensor_idSensorType需要传参传感器ID
reference_framestr'base_link'参考坐标系

返回值

类型描述
tuple包含以下内容的 Pair：- 7 个 double 的向量，表示变换 [x, y, z, qx, qy, qz, qw]，其中 (x, y, z) 为平移（米），(qx, qy, qz, qw) 为四元数方向 - 变换有效时的时间戳（纳秒）。如果检索失败则返回空向量，时间戳为 0。
note

传感器必须在初始化期间通过 enable_sensor_set 启用。

获取同步观测数据（get_synced_observation）​

def get_synced_observation(
    cameras: Sequence[SensorType],
    with_joint_state: bool = True
) -> SyncedObservation

获取按相机时间戳对齐的同步观测数据。

以 cameras 中的第一个传感器作为锚点。锚定相机取最新帧，其他相机从内部缓冲区中按最近邻时间戳匹配。如果 with_joint_state 为 true，则按同一锚点时间戳返回最近邻关节状态。返回的 joint_state->joint_state_vec 中每个条目都包含 joint_name，便于调用方识别每个关节状态样本的语义。

参数

名称类型默认值描述
camerasSequence[SensorType]需要传参要进行同步的相机列表。cameras[0] 为锚定相机，且必须已启用。
with_joint_stateboolTrue是否包含最近邻匹配的关节状态。

返回值

类型描述
SyncedObservation同步观测数据的共享指针。成功时：rgb_data_map/depth_data_map 包含按时间戳对齐的相机帧；joint_state（请求时）包含带关节名称的最近邻关节状态样本。输入无效或数据获取失败时返回 nullptr。

获取坐标变换（get_transform）​

def get_transform(
    target_frame: str,
    source_frame: str,
    timestamp_ns: SupportsInt = 0,
    timeout_ms: SupportsInt = 100
) -> tuple

查询坐标系变换（TF） 查询机器人TF树中两个坐标系之间的变换。

这用于在不同参考坐标系之间转换姿态和位置（例如，从相机坐标系到基坐标系，从末端执行器到世界坐标系）。

参数

名称类型默认值描述
target_framestr需要传参目标坐标系
source_framestr需要传参源坐标系
timestamp_nsSupportsInt0时间戳（纳秒）
timeout_msSupportsInt100超时时间（毫秒）

返回值

类型描述
tuple包含以下内容的 Pair：- 7 个 double 的向量，表示变换 [x, y, z, qx, qy, qz, qw]，其中 (x, y, z) 为平移（米），(qx, qy, qz, qw) 为四元数方向 - 变换有效时的时间戳（纳秒）。如果检索失败或超时则返回空向量，时间戳为 0。

获取 WBC 末端执行器位姿（get_wbc_end_effector_poses）​

def get_wbc_end_effector_poses() -> dict[str, list[float]]

获取 WBC 末端执行器位姿。

返回 WBC 各末端执行器（左臂、右臂、头部）的当前位姿。

返回值

类型描述
dict[str, list[float]]字典映射，包含：
- "lee_pose"：左臂末端位姿 [x, y, z, qx, qy, qz, qw]
- "ree_pose"：右臂末端位姿 [x, y, z, qx, qy, qz, qw]
- "head_pose"：头部末端位姿 [x, y, z, qx, qy, qz, qw]
当失败或缺少键时，可能返回空条目或部分数据。

初始化（init）​

def init(enable_sensor_set: Set[SensorType] = ..., enable_sync_mode: bool = False) -> bool

初始化机器人控制系统。

初始化机器人硬件通信、中间件和传感器接口。为了优化资源使用，只有在 enable_sensor_set 中指定的传感器才会被初始化并可用于数据读取。

此方法应在程序启动时调用一次。在未调用 destroy() 的情况下多次调用不会报错，但只有第一次调用生效。

参数

名称类型默认值描述
enable_sensor_setSet[SensorType]...要启用的传感器集合，如果为空，则启用默认的传感器集合，仅指定所需传感器可减少启动时间和资源占用
enable_sync_modeboolFalse是否启用内部同步缓冲区，用于按时间戳对齐的观测数据接口。

返回值

类型描述
bool初始化成功返回 true，否则返回 false。

检查是否运行中（is_running）​

def is_running() -> bool

检查机器人控制系统是否正在运行。

查询机器人控制系统是否仍处于活动状态，或者是否已收到关闭信号（例如，SIGINT、SIGTERM）。

返回值

类型描述
bool系统正常运行时返回 true，否则返回 false。

发布目标（publish_target）​

def publish_target(target: SingoriXTarget) -> ControlStatus

将目标发布到机器人控制系统，使目标可被运动规划模块使用。这是Python绑定版本。

参数

名称类型默认值描述
targetSingoriXTarget需要传参目标对象

返回值

类型描述
ControlStatus无返回值

释放控制器权限（release_controller）​

def release_controller(group_name: str = 'all') -> ControlStatus

释放硬件权限。

控制硬件，释放关节。与 acquire_controller 相反。如果运行则隐式停止执行。

参数

名称类型默认值描述
group_namestr'all'要释放的关节组名称，支持的组：chassis（底盘）、legs（腿部）、head（头部）、left_arm（左臂）、right_arm（右臂）、gripper（夹爪）、suction_cup（吸盘）或 "all"（释放所有控制器）

返回值

类型描述
ControlStatus控制状态，指示释放操作的成功或失败

重新加载控制器（reload_controller）​

def reload_controller(group_name: str = 'all') -> ControlStatus

重新加载控制器。

重新初始化控制器。相当于一个完整的重启循环：停止->重置->启动。对于错误恢复或应用配置更改很有用。

参数

名称类型默认值描述
group_namestr'all'要重新加载的控制器组名称

返回值

类型描述
ControlStatus控制状态，指示重新加载操作的成功或失败

请求关机（request_shutdown）​

def request_shutdown() -> None

请求系统关闭。

发送关闭信号以启动系统正常关闭。这会触发已注册的退出回调并开始资源清理。作为关闭序列的第一步调用：request_shutdown() -> wait_for_shutdown() -> destroy()。

请求目标（request_target）​

def request_target(target: SingoriXTarget) -> ErrorInfo

向机器人控制系统请求一个目标，用于运动规划和执行。这是Python绑定版本。

参数

名称类型默认值描述
targetSingoriXTarget需要传参目标对象

返回值

类型描述
ErrorInfoErrorInfo | None：错误响应负载；如果未收到有效响应，则为 None。

设置底盘姿态（set_base_pose）​

def set_base_pose(
    base_pose: Pose,
    is_blocking: bool = True,
    timeout_s: SupportsFloat = 15.0
) -> ControlStatus

设置移动基础位姿命令。

命令机器人的移动底座移动到其参考坐标系中的指定姿态。这使用底盘姿态控制器（CHASSIS_POSE_CTRL）。当完整的 3D 姿态（位置 + 四元数方向）已经可用时，使用此重载。

参数

名称类型默认值描述
base_posePose需要传参底盘目标姿态
is_blockingboolTrue是否阻塞等待完成
timeout_sSupportsFloat15.0超时时间（秒）。

返回值

类型描述
ControlStatus控制状态，指示命令传输的成功或失败

设置底盘姿态（set_base_pose）​

def set_base_pose(
    x: SupportsFloat,
    y: SupportsFloat,
    yaw: SupportsFloat,
    frame_id: str = 'rel(0)',
    reference_frame_id: str = 'odom',
    is_blocking: bool = True,
    timeout_s: SupportsFloat = 15.0
) -> ControlStatus

使用可选坐标系设置移动基础姿态（x、y、航向角）。

将此重载用于由所选坐标系中的 x/y/航向角定义的平面 2D 目标命令。

参数

名称类型默认值描述
xSupportsFloat需要传参X坐标（米）
ySupportsFloat需要传参Y坐标（米）
yawSupportsFloat需要传参航向角（弧度）
frame_idstr'rel(0)'目标坐标系 ID。当前推荐值："rel(0)"。"rel(0)" 表示 x/y/yaw 目标相对于当前底座位姿解释。"base_link"、"odom" 和 "map" 保留以向后兼容，但不建议当前使用，后续版本可能修改或移除。默认："rel(0)"
reference_frame_idstr'odom'参考坐标系ID
is_blockingboolTrue是否阻塞等待完成
timeout_sSupportsFloat15.0超时时间（秒）。

返回值

类型描述
ControlStatus控制状态，指示命令传输的成功或失败

设置底盘姿态（set_base_pose）​

def set_base_pose(
    x: SupportsFloat,
    y: SupportsFloat,
    yaw: SupportsFloat,
    frame_id: str,
    reference_frame_id: str,
    time_from_start_s: SupportsFloat,
    is_blocking: bool = True,
    timeout_s: SupportsFloat = 15.0
) -> ControlStatus

使用明确的插值时间设置移动基础姿态（x、y、航向角）。

当必须通过 time_from_start_s 协调到达时间时，请使用此重载。

参数

名称类型默认值描述
xSupportsFloat需要传参X坐标（米）
ySupportsFloat需要传参Y坐标（米）
yawSupportsFloat需要传参航向角（弧度）
frame_idstr需要传参目标坐标系 ID。当前推荐值："rel(0)"。"rel(0)" 表示 x/y/yaw 目标相对于当前底座位姿解释。"base_link"、"odom" 和 "map" 保留以向后兼容，但不建议当前使用，后续版本可能修改或移除。
reference_frame_idstr需要传参参考坐标系ID
time_from_start_sSupportsFloat需要传参预期到达时间（秒）
is_blockingboolTrue是否阻塞等待完成
timeout_sSupportsFloat15.0超时时间（秒）。

返回值

类型描述
ControlStatus控制状态，指示命令传输的成功或失败

设置底盘速度（set_base_velocity）​

def set_base_velocity(
    linear_velocity: list[float],
    angular_velocity: list[float],
    duration_s: SupportsFloat = 0.0
) -> ControlStatus

设置移动基础速度命令。

命令机器人的移动底座以指定的线速度和角速度移动。速度在机器人的基坐标系中表示。

参数

名称类型默认值描述
linear_velocitylist[float]需要传参线速度（米/秒），在底座坐标系中表示。
顺序：{vx, vy, vz}
- vx: X 方向线速度（前后）
- vy: Y 方向线速度（左右）
- vz: Z 方向线速度（垂直）
angular_velocitylist[float]需要传参角速度（弧度/秒），在底座坐标系中表示。
顺序：{wx, wy, wz}
- wx: 绕 X 轴角速度（翻滚）
- wy: 绕 Y 轴角速度（俯仰）
- wz: 绕 Z 轴角速度（偏航）
duration_sSupportsFloat0.0持续时间（秒）

返回值

类型描述
ControlStatus控制状态，指示命令传输的成功或失败

设置灵巧手命令（set_dexhand_command）​

def set_dexhand_command(
    end_effector: str,
    dexhand_command: Sequence[JointCommand],
    dexhand_type: DexHandType = ...,
    is_blocking: bool = True
) -> ControlStatus

通过关节命令控制灵巧手。

使用关节命令向量控制灵巧手（位置、速度、力矩等）。

参数

名称类型默认值描述
end_effectorstr需要传参要控制的灵巧手名称（例如 left_dexhand、right_dexhand）。
dexhand_commandSequence[JointCommand]需要传参每个灵巧手关节的命令向量。Inspire: [位置, 速度, 加速度, 力矩] 范围 [0-1000, 0-1000, , 0-1000]。BrainCo: [位置, 速度, 加速度, 力矩] 范围 [0-100, -100-100, , ]。Sharpa: 22 个关节命令 [位置, 速度, 加速度, 力矩]。
dexhand_typeDexHandType...灵巧手型号。
is_blockingboolTrue是否阻塞等待动作完成。

返回值

类型描述
ControlStatus控制状态，表示命令发布结果。

设置末端执行器命令（set_end_effector_command）​

def set_end_effector_command(
    poses: Sequence[list[float]],
    end_effector_frames: Sequence[str],
    reference_frames: Sequence[str] = []
) -> ControlStatus

设置 WBC 末端执行器位姿命令（任务轨迹发布）。

poses 中每一行为 [x, y, z, qx, qy, qz, qw]（单位：米，四元数顺序 xyzw）。poses 与 end_effector_frames 的长度必须一致。

参数

名称类型默认值描述
posesSequence[list[float]]需要传参每个末端执行器对应一个位姿；每行格式为 [x, y, z, qx, qy, qz, qw]（单位：米，四元数顺序 xyzw）。
end_effector_framesSequence[str]需要传参每个位姿对应的目标坐标系 id（例如连杆名称）。
reference_framesSequence[str][]每个位姿对应的参考坐标系。省略或传入 [] 时默认对所有位姿使用 "world"。否则长度必须与 poses 一致。常用值："world"（默认）。

返回值

类型描述
ControlStatus控制状态，表示命令发布结果。

设置夹爪命令（set_gripper_command）​

def set_gripper_command(
    end_effector: str,
    width_m: SupportsFloat,
    velocity_mps: SupportsFloat = 0.03,
    effort: SupportsFloat = 5,
    is_blocking: bool = True
) -> ControlStatus

控制夹具张开宽度和力度。

命令夹具以受控的速度和最大夹持力移动到指定的开口宽度。

参数

名称类型默认值描述
end_effectorstr需要传参要控制的夹爪关节组名称（例如 left_gripper、right_gripper）。
width_mSupportsFloat需要传参目标夹爪开口宽度，单位为米 (m)，以夹爪两指内表面之间的距离计算。G1 夹爪宽度范围：0 ~ 0.12 m。S1 长行程夹爪宽度范围：0.007 ~ 0.11 m。S1 短行程夹爪宽度范围：0.007 ~ 0.076 m。
velocity_mpsSupportsFloat0.03夹爪闭合/打开速度，单位为米/秒 (m/s)。默认值：0.03 m/s。取值范围大于 0 且小于等于 0.2 m/s。
effortSupportsFloat5最大抓取力，单位为牛顿米 (N·m)。此参数限制施加的扭矩，以防止对抓取物体造成损坏。取值范围大于 0 且小于等于 100。默认值：5 N·m。
is_blockingboolTrue是否阻塞等待完成

返回值

类型描述
ControlStatus控制状态，指示夹爪命令的成功或失败

设置关节命令（set_joint_commands）​

def set_joint_commands(
    joint_commands: Sequence[JointCommand],
    joint_groups: Sequence[str] = [],
    joint_names: Sequence[str] = [],
    time_from_start_s: SupportsFloat = 0.0
) -> ControlStatus

设置用于高频流控制的底层关节指令。

适用于高频指令流（例如，逐帧模型推理输出）。

此 API 不会从当前/起始位置插值到第一个目标位置。控制器会尽可能快地驱动关节朝向每个指令目标位置。

对于标准关节（头部、腿部、手臂），当前版本中只有 JointCommand::position 有效；速度、加速度和力目前被忽略。

对于夹爪关节，位置字段表示夹爪宽度，速度和力字段均受支持且有效。

参数

名称类型默认值描述
joint_commandsSequence[JointCommand]需要传参关节命令列表
joint_groupsSequence[str][]要控制的关节组。支持的组：legs（腿部）、head（头部）、left_arm（左臂）、right_arm（右臂）、gripper（夹爪）、suction_cup（吸盘）。如果 joint_names 也为空，则不能为空，否则返回 INVALID_INPUT。
joint_namesSequence[str][]要控制的具体关节名称。此参数优先于 joint_groups。如果提供了 joint_names，则忽略 joint_groups。如果 joint_groups 也为空，则不能为空，否则返回 INVALID_INPUT。
time_from_start_sSupportsFloat0.0执行将在 time_start_s 秒后开始。（可选，默认值：0.0）

返回值

类型描述
ControlStatus控制状态，指示命令传输的成功或失败
warning

尤其在第一条命令下发时，请避免当前关节角与目标关节角差值过大。角度突变可能导致运动过快并带来安全风险。

批量设置关节命令（set_joint_commands_batch）​

def set_joint_commands_batch(trajectory: Trajectory) -> ControlStatus

以批处理模式设置关节命令（非阻塞） 实时控制模式下设置多个关节命令轨迹点，支持一次性提交多个时间点的轨迹控制命令。

提供非阻塞高频轨迹执行接口。与set_joint_commands类似，但支持批量轨迹控制，适用于VLA推理批量输出等场景。

参数

名称类型默认值描述
trajectoryTrajectory需要传参包含关节命令路点的轨迹数据结构。必须指定 trajectory.joint_groups 或 trajectory.joint_names；如果两者都为空，则返回 INVALID_INPUT。每个 TrajectoryPoint 包含 time_from_start 和关节命令列表。关节命令包括位置（弧度）、速度（弧度/秒）、加速度（弧度/秒²）、作用力（牛·米）、Kp（位置增益）和 Kd（速度增益）。

返回值

类型描述
ControlStatus控制状态，指示命令提交的成功或失败。立即返回，不等待执行完成（非阻塞）。
warning

每个 TrajectoryPoint.joint_command_vec 的顺序必须与 trajectory.joint_names 定义的关节顺序或 trajectory.joint_groups 的展开顺序一致。

设置关节位置（set_joint_positions）​

def set_joint_positions(
    joint_positions: list[float],
    joint_groups: Sequence[str] = [],
    joint_names: Sequence[str] = [],
    is_blocking: bool = True,
    speed_rad_s: SupportsFloat = 0.2,
    timeout_s: SupportsFloat = 15.0
) -> ControlStatus

按名称设置指定关节组的目标关节位置（用于低频关键帧/姿态转换） 命令机器人将指定关节移动到目标位置。

该运动以具有可配置速度限制的平滑轨迹执行。

参数

名称类型默认值描述
joint_positionslist[float]需要传参目标关节位置
joint_groupsSequence[str][]要控制的关节组名称。支持的组：腿部、头部、左臂、右臂。如果 joint_names 也为空，则不能为空，否则返回 INVALID_INPUT。
joint_namesSequence[str][]要控制的具体关节名称。此参数优先于 joint_groups。如果提供了 joint_names，则忽略 joint_groups。如果 joint_groups 也为空，则不能为空，否则返回 INVALID_INPUT。
is_blockingboolTrue是否阻塞等待完成。true：阻塞直到完成或超时；false：发送后立即返回。
speed_rad_sSupportsFloat0.2最大运动速度（弧度/秒）
timeout_sSupportsFloat15.0超时时间（秒）。

返回值

类型描述
ControlStatus控制状态，指示运动命令的成功或失败
warning

此 API 不适合高频率的逐帧运动控制。

启动控制器（start_controller）​

def start_controller(group_name: str = 'all') -> ControlStatus

开始控制器执行。

激活控制器以开始发送命令。与 stop_controller 相反。需要事先获得硬件权限（获取）。

参数

名称类型默认值描述
group_namestr'all'要启动的控制器组名称

返回值

类型描述
ControlStatus控制状态，指示启动操作的成功或失败

紧急停止底盘（stop_base）​

def stop_base() -> ControlStatus

紧急停止移动底座运动。

立即命令移动基地停止一切运动。这是一项安全功能，当需要立即停止基本运动时应使用。

返回值

类型描述
ControlStatus控制状态，指示命令传输的成功或失败

停止控制器（stop_controller）​

def stop_controller(group_name: str = 'all') -> ControlStatus

停止控制器执行。

停止命令执行但保留硬件权限。与 start_controller 相反。

参数

名称类型默认值描述
group_namestr'all'要停止的控制器组名称

返回值

类型描述
ControlStatus控制状态，指示停止操作的成功或失败

停止轨迹执行（stop_trajectory_execution）​

def stop_trajectory_execution() -> ControlStatus

停止所有当前正在执行的关节轨迹。

立即停止执行所有关节组中的所有活动关节轨迹。停止后关节将保持当前位置。

返回值

类型描述
ControlStatus控制状态，指示命令传输的成功或失败

切换控制器（switch_controller）​

def switch_controller(controller_name: str) -> ControlStatus

切换活动控制器策略。

将硬件控制切换到新的策略。请求会发送到 WBCS 控制器管理器，由其执行安全切换，并在接受请求后启动目标控制器。

参数

名称类型默认值描述
controller_namestr需要传参控制器名称字符串，例如 "chassis_pose_ctrl"。

返回值

类型描述
ControlStatus控制状态，指示切换操作的成功或失败

等待关机（wait_for_shutdown）​

def wait_for_shutdown() -> None

阻塞直到关闭完成。

阻塞调用线程直到所有模块都正常关闭完毕。作为关闭序列的第二步调用，在 request_shutdown() 之后、destroy() 之前。

note

当 is_running() 变为 false 时此函数将返回。

全身与底盘归零（zero_whole_body_and_base）​

def zero_whole_body_and_base(
    base_zero_pose: Pose,
    is_blocking: bool = True,
    leg_head_speed_rad_s: SupportsFloat = 0.2,
    leg_head_timeout_s: SupportsFloat = 15.0,
    params: Parameter = None
) -> tuple[MotionStatus, ControlStatus]

一键归零：将全身关节回零，并将底盘位姿回到零位。

该接口会调用 move_whole_body_joint_zero 完成关节归零，并将底盘目标位姿设为零。若 params 为空指针，则使用 default_param。

参数

名称类型默认值描述
base_zero_posePose需要传参-
is_blockingboolTrue-
leg_head_speed_rad_sSupportsFloat0.2-
leg_head_timeout_sSupportsFloat15.0-
paramsParameterNone-

返回值

类型描述
tuple[MotionStatus, ControlStatus]-

全身与底盘归零（zero_whole_body_and_base）​

def zero_whole_body_and_base(
    frame_id: str = 'odom',
    reference_frame_id: str = 'odom',
    is_blocking: bool = True,
    leg_head_speed_rad_s: SupportsFloat = 0.2,
    leg_head_timeout_s: SupportsFloat = 15.0,
    params: Parameter = None
) -> tuple[MotionStatus, ControlStatus]

一键归零：通过可选坐标系将全身关节归零，并将底座（x、y、航向角）归零。

参数

名称类型默认值描述
frame_idstr'odom'坐标系ID
reference_frame_idstr'odom'参考坐标系ID
is_blockingboolTrue是否阻塞等待完成
leg_head_speed_rad_sSupportsFloat0.2腿部和头部关节速度（弧度/秒）
leg_head_timeout_sSupportsFloat15.0腿部和头部运动超时（秒）
paramsParameterNone额外参数

返回值

类型描述
tuple[MotionStatus, ControlStatus]-

运动规划与执行（GalbotMotion）​

Galbot 机器人的统一运动规划和控制接口。

该接口提供全面的机器人运动控制 API，包括： - 正向和逆向运动学计算 - 单链和多链轨迹规划 - 碰撞检测（自碰撞和环境） - 工具和障碍物管理 - 全身协调运动规划使用 GalbotMotion::get_instance(MachineType) 获取特定平台 (G1/S1) 的实例。所有角度单位为弧度，线性单位为米（SI 标准）。四元数必须归一化：√(x² + y² + z² + w²) = 1。

添加障碍物（add_obstacle）​

def add_obstacle(
    obstacle_id: str,
    obstacle_type: str,
    pose: list[float],
    scale: list[float] = [0.0, 0.0, 0.0],
    key: str = '',
    target_frame: str = 'world',
    ee_frame: str = 'ee_base',
    reference_joint_positions: list[float] = [],
    reference_base_pose: list[float] = [],
    ignore_collision_link_names: Sequence[str] = [],
    safe_margin: SupportsFloat = 0.0,
    resolution: SupportsFloat = 0.01
) -> MotionStatus

将碰撞对象加载到环境中。

将几何或基于网格的障碍物插入环境中以避免碰撞。障碍可以是静态的（世界坐标系下固定的）或与机器人相关的。支持原始形状、网格、点云和深度图像。

参数

名称类型默认值描述
obstacle_idstr需要传参障碍物唯一标识符（场景中不得重复），后续可用于删除或更新。
obstacle_typestr需要传参障碍物几何类型
poselist[float]需要传参障碍物位姿：[x, y, z, qx, qy, qz, qw]（米，四元数），相对于 target_frame。
scalelist[float][0.0, 0.0, 0.0]几何尺寸（米）：
- box: [长度, 宽度, 高度]
- sphere: [半径, -, -]
- cylinder: [半径,高度,-]
- mesh/point_cloud: 缩放因子
keystr''类型特定数据：
- mesh/point_cloud: 文件路径（例如 "/path/to/model.stl"）
- depth_image: 相机源数据
- robot_state: 机器人状态数据
target_framestr'world'位姿参考坐标系（默认 "world"），可为 "world"、"base_link" 或运动链名称（如 "left_arm"）。
ee_framestr'ee_base'当 target_frame 为运动链名称时，指定链上参考帧（如 "ee_base"、"camera_base"、"camera_object"）。
reference_joint_positionslist[float][]用于计算坐标变换的机器人关节状态（弧度）。为空时使用当前机器人状态。
reference_base_poselist[float][]地图坐标系下的机器人基座位姿：[x, y, z, qx, qy, qz, qw]。为空时使用当前定位。
ignore_collision_link_namesSequence[str][]忽略碰撞的连杆名称列表
safe_marginSupportsFloat0.0安全距离缓冲（米）。当距离 < safe_margin 时判定碰撞，默认 0。
resolutionSupportsFloat0.01复杂几何体（mesh/point cloud/depth image）的离散化分辨率（米），默认 0.01。

返回值

类型描述
MotionStatus运动状态：- 成功：障碍物添加成功 - 无效输入：无效的障碍物ID（重复）、类型或参数 - 故障：处理几何形状或添加到场景失败
note

点云说明：point_cloud 指通过此 API 显式加载的点云障碍物（通常来自文件/离线数据）。它与导航系统维护的点云地图不同，GalbotMotion 不会自动订阅或与 galbotNav 的点云地图同步碰撞检测。

note

障碍物会持续存在，直到显式删除或清空。

note

对于移动障碍物，请在新位姿处删除并重新添加（当前无更新方法）。

warning

较大的 safe_margin（安全边距）值可能会过度约束规划空间，导致无法找到可行解，请谨慎使用。

附加目标对象（attach_target_object）​

def attach_target_object(
    obstacle_id: str,
    obstacle_type: str,
    pose: list[float],
    scale: list[float] = [0.0, 0.0, 0.0],
    key: str = '',
    target_frame: str = 'world',
    ee_frame: str = 'ee_base',
    reference_joint_positions: list[float] = [],
    reference_base_pose: list[float] = [],
    ignore_collision_link_names: Sequence[str] = [],
    safe_margin: SupportsFloat = 0.0,
    resolution: SupportsFloat = 0.01
) -> MotionStatus

将碰撞物体附加到机器人上（例如，抓取的物体）。与 add_obstacle() 类似，但对象随机器人移动（连接到连杆/运动链），用于表示抓取的物体、传感器或有效载荷。

在运动过程中，对象相对于连接坐标系的姿态保持不变。

参数

名称类型默认值描述
obstacle_idstr需要传参要移除的障碍物ID
obstacle_typestr需要传参障碍物几何类型
poselist[float]需要传参物体位姿：[x, y, z, qx, qy, qz, qw]（米，四元数），在附着时相对于 target_frame。
scalelist[float][0.0, 0.0, 0.0]几何尺寸（米）：box 为 [length, width, height]；sphere 为 [radius, -, -]；cylinder 为 [radius, height, -]。
keystr''障碍物唯一标识符
target_framestr'world'附着参考坐标系（默认 "world"）；抓取物体场景通常填写运动链名称（如 "left_arm"）。
ee_framestr'ee_base'当 target_frame 为运动链名称时，指定链上参考帧（如 "ee_base"、"camera_base" 等）。
reference_joint_positionslist[float][]用于计算附着变换的机器人关节状态（弧度）。为空时使用当前机器人状态。
reference_base_poselist[float][]地图坐标系下的机器人基座位姿：[x, y, z, qx, qy, qz, qw]。为空时使用当前定位。
ignore_collision_link_namesSequence[str][]忽略碰撞的连杆名称列表
safe_marginSupportsFloat0.0安全距离缓冲（米），默认 0。
resolutionSupportsFloat0.01复杂几何体的离散化分辨率（米），默认 0.01。

返回值

类型描述
MotionStatus运动状态：SUCCESS（成功）、INVALID_INPUT（无效输入）或 FAULT（故障）
note

点云说明：与 add_obstacle() 相同。此处的 point_cloud 是显式加载的点云对象，不会自动与任何导航端点云地图同步。

note

附加的对象随机器人移动；其碰撞几何体自动更新。

note

通常用于抓取和放置：抓取后附加目标对象，释放后分离。

warning

请确保 ignore_collision_link_names 包含抓取连杆，以避免误判为碰撞。

附加工具（attach_tool）​

def attach_tool(chain: str, tool: str) -> MotionStatus

将工具连接到末端执行器。

将工具（夹具、相机、定制末端执行器）加载到运动链上。更新运动学模型和碰撞几何体以包含该工具。

参数

名称类型默认值描述
chainstr需要传参用于挂载工具的运动链（例如 left_arm、right_arm）。
toolstr需要传参工具信息

返回值

类型描述
MotionStatus运动状态：- 成功：附加工具成功 - 无效输入：无效的运动链或工具名称 - 故障：附加工具失败
note

工具变换和碰撞几何体必须预先在机器人描述中配置。

note

附加新工具会自动分离该运动链上先前附加的任何工具。

warning

运动学和碰撞检查将反映附加的工具；请相应更新计划。

检查碰撞（check_collision）​

def check_collision(
    start: Sequence[RobotStates],
    enable_collision_check: bool = True,
    params: Parameter = ...
) -> tuple[MotionStatus, list[bool]]

检查机器人状态是否存在碰撞。

检查自身碰撞和与环境障碍物的碰撞，支持批量处理。因此，如果需要 Motion 考虑环境障碍物（包括点云），必须显式加载障碍物地图/对象（例如，obstacle_type = point_cloud 且在 key 中提供文件路径）。

注意：将实时感知集成到 galbotMotion 是未来计划，目前内部验证有限。

验证给定机器人配置是否无碰撞。

参数

名称类型默认值描述
startSequence[RobotStates]需要传参起始机器人状态
enable_collision_checkboolTrue是否启用碰撞检查
paramsParameter...额外参数

返回值

类型描述
tuple[MotionStatus, list[bool]]元组（状态，碰撞结果）：
- 状态：检测完成时为 MotionStatus::SUCCESS，否则为错误码
- 碰撞结果：布尔向量（与 start 等长），true 表示检测到碰撞，false 表示无碰撞
note

用于验证计划轨迹或基于采样的规划器。

note

尊重先前添加的障碍物中的 safe_margin（安全边距）设置。

note

尊重先前添加的障碍物中的 safe_margin（安全边距）设置。

清空障碍物（clear_obstacle）​

def clear_obstacle() -> MotionStatus

从规划场景中移除所有碰撞障碍物。

清除整个障碍物集，将规划场景重置为空（机器人几何体除外）。

返回值

类型描述
MotionStatus-
note

附加的对象（参见 attach_target_object）不会被清除。

note

即使场景已为空，也可以安全调用。

分离目标对象（detach_target_object）​

def detach_target_object(obstacle_id: str) -> MotionStatus

从机器人上分离物体（例如，释放后）。从机器人上移除附着的物体。通常在释放抓取的对象后调用。

该对象被完全从规划场景中移除（不转换为静态障碍物）。

参数

名称类型默认值描述
obstacle_idstr需要传参-

返回值

类型描述
MotionStatus-
note

如需在移除后将对象作为静态障碍物保留在场景中，请使用 clear_obstacle()。

分离工具（detach_tool）​

def detach_tool(chain: str) -> MotionStatus

将当前工具与末端执行器分离。

相应地更新运动学模型和碰撞几何体。

参数

名称类型默认值描述
chainstr需要传参要分离工具的运动链

返回值

类型描述
MotionStatus运动状态：- 成功：分离工具成功 - 无效输入：无效的运动链名称或未附加工具 - 故障：分离工具失败
note

如果没有工具附加，则操作成功但无效果。

正向运动学（forward_kinematics）​

def forward_kinematics(
    target_frame: str,
    reference_frame: str = 'base_link',
    joint_state: dict] = {},
    params: Parameter = ...
) -> tuple[MotionStatus, list[float]]

计算目标连杆的正向运动学。

计算给定关节配置的指定连杆的笛卡尔姿态。对于确定末端执行器位置、验证配置或计算中间连杆姿态很有用。

参数

名称类型默认值描述
target_framestr需要传参目标坐标系
reference_framestr'base_link'参考坐标系
joint_statedict]{}关节名到关节位置的映射；默认空字典表示使用当前机器人关节状态。
paramsParameter...额外参数

返回值

类型描述
tuple[MotionStatus, list[float]]元组（状态，位姿向量）：
- 状态：成功时为 MotionStatus::SUCCESS，否则为错误码
- 位姿向量：[x, y, z, qx, qy, qz, qw]（米，四元数），失败时为空
note

关节角度以弧度为单位，输出位姿以米为单位的单位四元数表示。

warning

target_frame 必须是 URDF 模型中的有效连杆。

基于状态的正向运动学（forward_kinematics_by_state）​

def forward_kinematics_by_state(
    target_frame: str,
    reference_robot_states: RobotStates = None,
    reference_frame: str = 'base_link',
    params: Parameter = ...
) -> tuple[MotionStatus, list[float]]

使用完整的机器人状态计算正向运动学。

与 forward_kinematics() 类似，但接受 RobotStates 对象来指定完整的机器人配置（全身关节+底座姿态）。

参数

名称类型默认值描述
target_framestr需要传参目标坐标系
reference_robot_statesRobotStatesNone参考机器人起始状态
reference_framestr'base_link'参考坐标系
paramsParameter...额外参数

返回值

类型描述
tuple[MotionStatus, list[float]]元组（状态，位姿向量）：
- 状态：成功时为 MotionStatus::SUCCESS，否则为错误码
- 位姿向量：[x, y, z, qx, qy, qz, qw]（米，四元数），失败时为空
note

在不修改实际状态的情况下为假设状态计算正向运动学时非常有用。

获取已构建障碍物列表（get_built_obstacles_list）​

def get_built_obstacles_list() -> list[str]

获取当前加载的障碍物 ID 列表。

返回值

类型描述
list[str]-

获取链关节状态（get_chain_joint_state）​

def get_chain_joint_state() -> dict[str, list[float]]

获取所有运动链的当前关节配置。

检索每条链的关节状态，将整体配置分解为各个链的贡献。

返回值

类型描述
dict[str, list[float]]-
note

关节向量大小因链的自由度而异。

获取末端执行器姿态（get_end_effector_pose）​

def get_end_effector_pose(
    end_effector_frame: str,
    reference_frame: str = 'base_link'
) -> tuple[MotionStatus, list[float]]

从机器人状态获取当前末端执行器姿态。

查询 TF（变换）树以检索指定末端执行器连杆的当前笛卡尔姿态。需要在机器人的 URDF 模型中定义该连杆。

参数

名称类型默认值描述
end_effector_framestr需要传参末端执行器坐标系
reference_framestr'base_link'参考坐标系

返回值

类型描述
tuple[MotionStatus, list[float]]元组 (状态, 位姿向量)：
- 状态：成功时为 MotionStatus::SUCCESS，错误码说明：
- DATA_FETCH_FAILED: TF 查找失败
- INVALID_INPUT: 无效的帧名称
- 位姿向量：[x, y, z, qx, qy, qz, qw]（单位：米，四元数），失败时为空
note

反映当前实际的机器人状态（非计划状态）。

warning

需要 TF 树正确发布且为最新状态。

获取指定链末端执行器姿态（get_end_effector_pose_on_chain）​

def get_end_effector_pose_on_chain(
    chain_name: str,
    frame_id: str = 'EndEffector',
    reference_frame: str = 'base_link'
) -> tuple[MotionStatus, list[float]]

获取特定运动链的当前末端执行器姿态。

通过链名称和坐标系类型检索末端执行器姿态的便捷方法，无需知道 URDF 中的确切连杆名称。

参数

名称类型默认值描述
chain_namestr需要传参链名称
frame_idstr'EndEffector'坐标系ID
reference_framestr'base_link'参考坐标系

返回值

类型描述
tuple[MotionStatus, list[float]]元组 (状态, 位姿向量)：状态（成功时为 MotionStatus::SUCCESS，否则为错误码），位姿向量 [x, y, z, qx, qy, qz, qw]（单位：米，四元数），失败时为空
note

内部将 chain_name + frame_id 映射到实际的 URDF 连杆名称。

获取雅可比矩阵（get_jacobian）​

def get_jacobian(
    chain_name: str,
    target_frame: str = 'EndEffector',
    reference_frame: str = 'base_link',
    joint_state: dict] = {},
    params: Parameter = ...
) -> tuple[MotionStatus, list[list[float]]]

计算指定运动链的雅可比矩阵

参数

名称类型默认值描述
chain_namestr需要传参链名称
target_framestr'EndEffector'雅可比矩阵计算的目标连杆。有效值：
- "EndEffector"（默认）：链末端执行器法兰，即 "<chain_name>_end_effector_mount_link"
- get_support_links() / get_link_names() 返回的任意有效 URDF 连杆名
注意：不支持 "Tool"（TCP）——运动学服务仅按连杆名计算雅可比矩阵，不具备工具位姿能力，传入 "Tool" 将返回 MotionStatus::UNSUPPORTED_FUNCRION。
reference_framestr'base_link'参考坐标系："base_link"（机器人基座坐标系）或 "world"（世界坐标系）。默认："base_link"
joint_statedict]{}关节状态对象，包含当前关节位置
paramsParameter...运动学参数配置

返回值

类型描述
tuple[MotionStatus, list[list[float]]]返回 numpy 数组，形状为 [6 x DOF]，表示末端执行器在参考坐标系下的雅可比矩阵
note

返回雅可比矩阵，形状为 [6 x DOF]，表示关节空间到任务空间的线性映射

note

用于运动学分析、力控、奇异值分解等场景

note

使用 get_support_links() / get_link_names() 可查询有效的 target_frame 连杆名称。

通过状态获取雅可比矩阵（get_jacobian_by_state）​

def get_jacobian_by_state(
    chain_name: str,
    target_frame: str = 'EndEffector',
    reference_frame: str = 'base_link',
    reference_robot_states: RobotStates = None,
    params: Parameter = ...
) -> tuple[MotionStatus, list[list[float]]]

通过给定的机器人状态计算指定运动链的雅可比矩阵

参数

名称类型默认值描述
chain_namestr需要传参链名称
target_framestr'EndEffector'雅可比矩阵计算的目标连杆。默认："EndEffector"（链法兰，"<chain_name>_end_effector_mount_link"），或 get_support_links() 返回的任意有效 URDF 连杆名。不支持 "Tool"（TCP），传入将返回 MotionStatus::UNSUPPORTED_FUNCRION（参见 get_jacobian()）。
reference_framestr'base_link'参考坐标系。默认："base_link"
reference_robot_statesRobotStatesNone机器人状态，包含关节位置信息
paramsParameter...运动学参数配置

返回值

类型描述
tuple[MotionStatus, list[list[float]]]元组（状态，雅可比矩阵）：
- 状态：成功时为 MotionStatus::SUCCESS，否则为错误码
- 雅可比矩阵：6xN 矩阵（N 为链自由度），失败时为空
note

返回雅可比矩阵，形状为 [6 x DOF]

def get_link_names(only_end_effector: bool = False) -> list[str]

从运动学模型中获取机器人连杆名称。

检索机器人 URDF 模型中定义的连杆名称列表，可用于过滤末端执行器连杆或返回所有连杆。

参数

名称类型默认值描述
only_end_effectorboolFalse是否仅返回末端执行器连杆，true 仅返回末端执行器/工具连杆，false 返回所有连杆（包括底座、中间连杆等），默认 false（所有连杆）

返回值

类型描述
list[str]连杆名称字符串向量（如果检索失败则为空）
note

基于连杆没有子连杆来检测末端执行器。

note

用于正向运动学查询或 TF 帧验证。

获取运动规划配置（get_motion_plan_config）​

def get_motion_plan_config() -> tuple[MotionStatus, MotionPlanConfig]

获取当前运动规划配置。

检索活动规划器配置，包括速度/加速度限制和规划算法参数。

返回值

类型描述
tuple[MotionStatus, MotionPlanConfig]-
note

用于检查当前限制或保存/恢复配置。

获取机器人状态（get_robot_states）​

def get_robot_states() -> RobotStates

获取当前完整的机器人状态。

检索当前全身关节配置和移动底座姿态。代表机器人的完整运动状态。

返回值

类型描述
RobotStates-
note

反映实际机器人状态（来自传感器反馈/状态估计）。

note

用作规划操作的种子/参考。

获取支持的链（get_supported_chains）​

def get_supported_chains() -> set[str]

获取支持的运动链名称列表（例如 left_arm、right_arm）。

返回值

类型描述
set[str]-

获取支持的末端执行器坐标系（get_supported_ee_frames）​

def get_supported_ee_frames() -> set[str]

获取支持的末端执行器坐标系标识符集。

返回值

类型描述
set[str]-

获取支持的坐标系（get_supported_frames）​

def get_supported_frames() -> set[str]

获取支持的参考坐标系名称集。

返回值

类型描述
set[str]-
def get_supported_links() -> set[str]

获取支持的连杆名称列表（正向运动学/逆向运动学的 URDF 连杆名称）。

返回值

类型描述
set[str]-

获取支持的障碍物类型（get_supported_obstacle_types）​

def get_supported_obstacle_types() -> set[str]

获取支持的障碍物类型集（例如盒子、球体、圆柱体、网格）。

返回值

类型描述
set[str]-

获取支持的工具列表（get_supported_tool_list）​

def get_supported_tool_list() -> set[str]

获取 attach_tool 支持的工具名称列表。

返回值

类型描述
set[str]-

初始化（init）​

def init() -> bool

初始化运动规划系统和通信接口。

必须在任何其他 API 函数之前调用。初始化内部通信中间件，加载机器人运动学模型，并建立与控制服务的连接。

返回值

类型描述
bool-
note

可安全多次调用；成功后的后续调用返回第一次初始化的结果。

warning

如果 init() 返回 false，则所有其他 API 调用将失败。

逆向运动学（inverse_kinematics）​

def inverse_kinematics(
    target_pose: list[float],
    chain_names: Sequence[str],
    target_frame: str = 'EndEffector',
    reference_frame: str = 'base_link',
    initial_joint_positions: dict] = {},
    enable_collision_check: bool = True,
    params: Parameter = ...
) -> tuple[MotionStatus, dict[str, list[float]]]

计算目标笛卡尔姿态的逆运动学。

求解实现指定末端执行器姿态的关节配置。支持单链 IK（仅手臂）或协调多链 IK（手臂 + 躯干/腿）。

参数

名称类型默认值描述
target_poselist[float]需要传参目标笛卡尔位姿：[x, y, z, qx, qy, qz, qw]（米，四元数）。
chain_namesSequence[str]需要传参要解决逆运动学的运动链名称列表
target_framestr'EndEffector'目标坐标系
reference_framestr'base_link'参考坐标系
initial_joint_positionsdict]{}初始关节位置猜测
enable_collision_checkboolTrue是否启用碰撞检查
paramsParameter...额外参数

返回值

类型描述
tuple[MotionStatus, dict[str, list[float]]]元组（状态，解映射）：
- 状态：若可求解则为 MotionStatus::SUCCESS，否则为错误码
- 解映射：{chain_name -> joint_angles}（弧度），失败时为空
note

IK 可能有多个解；返回第一个有效的解。

note

种子配置影响收敛速度和哪个解被选中。

warning

如果目标在工作空间之外或处于奇异配置，则无法保证有解。

基于状态的逆向运动学（inverse_kinematics_by_state）​

def inverse_kinematics_by_state(
    target_pose: list[float],
    chain_names: Sequence[str],
    target_frame: str = 'EndEffector',
    reference_frame: str = 'base_link',
    reference_robot_states: RobotStates = None,
    enable_collision_check: bool = True,
    params: Parameter = ...
) -> tuple[MotionStatus, dict[str, list[float]]]

使用完整的机器人状态作为种子计算逆运动学。

与 inverse_kinematics() 类似，但接受 RobotStates 来指定种子配置，从而允许精确控制整个机器人状态。

参数

名称类型默认值描述
target_poselist[float]需要传参目标笛卡尔位姿：[x, y, z, qx, qy, qz, qw]（米，四元数）。
chain_namesSequence[str]需要传参要解决逆运动学的运动链名称列表
target_framestr'EndEffector'目标坐标系
reference_framestr'base_link'参考坐标系
reference_robot_statesRobotStatesNone参考机器人起始状态
enable_collision_checkboolTrue是否启用碰撞检查
paramsParameter...额外参数

返回值

类型描述
tuple[MotionStatus, dict[str, list[float]]]元组（状态，解映射）：
- 状态：若可求解则为 MotionStatus::SUCCESS，否则为错误码
- 解映射：{chain_name -> joint_angles}（弧度），失败时为空
note

在不修改实际状态的情况下为假设状态离线规划时非常有用。

轨迹规划（motion_plan）​

def motion_plan(
    target: RobotStates,
    start: RobotStates = None,
    reference_robot_states: RobotStates = None,
    enable_collision_check: bool = True,
    params: Parameter = ...
) -> tuple[MotionStatus, dict[str, list[list[float]]]]

规划单个运动链的轨迹。

参数

名称类型默认值描述
targetRobotStates需要传参目标位姿
startRobotStatesNone起始机器人状态
reference_robot_statesRobotStatesNone参考机器人起始状态
enable_collision_checkboolTrue是否启用碰撞检查
paramsParameter...额外参数

返回值

类型描述
tuple[MotionStatus, dict[str, list[list[float]]]]元组（状态，轨迹映射）：
- 状态：规划成功时为 MotionStatus::SUCCESS，否则为错误码
- 轨迹映射：{chain_name -> waypoint_list}，其中 waypoint_list 为关节配置序列（弧度）
note

碰撞语义：GalbotMotion 不提供实时障碍物订阅；规划期间仅考虑通过 API 添加的障碍物。

note

轨迹时间参数化，具有速度/加速度约束。

note

对于直接执行（params->is_direct_execute=true），轨迹会自动下发到机器人执行。

warning

target 必须是 PoseState 或 JointStates；传递 base RobotStates 将导致 INVALID_INPUT 错误。

多路点轨迹规划（motion_plan_multi_waypoints）​

def motion_plan_multi_waypoints(
    target: RobotStates,
    waypoint_poses: Sequence[list[float]],
    start: RobotStates = None,
    reference_robot_states: RobotStates = None,
    enable_collision_check: bool = True,
    params: Parameter = ...
) -> tuple[MotionStatus, dict[str, list[list[float]]]]

通过多个链的路径点规划协调轨迹。

通过路径点序列实现协调的多臂或全身运动。每个链都可以有自己的路点序列，以同步方式执行。

参数

名称类型默认值描述
targetRobotStates需要传参目标位姿
waypoint_posesSequence[list[float]]需要传参路点位姿列表
startRobotStatesNone起始机器人状态
reference_robot_statesRobotStatesNone参考机器人起始状态
enable_collision_checkboolTrue是否启用碰撞检查
paramsParameter...额外参数

返回值

类型描述
tuple[MotionStatus, dict[str, list[list[float]]]]运动规划成功返回 true，失败返回 false。
note

所有链的轨迹在时间上同步以实现协调运动。

note

用于双臂操作或移动操作任务。

多路点轨迹规划（motion_plan_multi_waypoints）​

def motion_plan_multi_waypoints(
    targets: dict]],
    start: Sequence[RobotStates] = [],
    reference_robot_states: RobotStates = None,
    enable_collision_check: bool = True,
    params: Parameter = ...
) -> tuple[MotionStatus, dict[str, list[list[float]]]]

通过多个链的路径点规划协调轨迹。

通过路径点序列实现协调的多臂或全身运动。每个链都可以有自己的路点序列，以同步方式执行。

参数

名称类型默认值描述
targetsdict]]需要传参多路点目标位姿字典（每个运动链对应一个路点序列）
startSequence[RobotStates][]起始机器人状态
reference_robot_statesRobotStatesNone参考机器人起始状态
enable_collision_checkboolTrue是否启用碰撞检查
paramsParameter...额外参数

返回值

类型描述
tuple[MotionStatus, dict[str, list[list[float]]]]元组（状态，轨迹映射）：
- 状态：规划成功时为 MotionStatus::SUCCESS，否则为错误码
- 轨迹映射：{chain_name -> waypoint_list}（所有运动链）
note

所有链的轨迹在时间上同步以实现协调运动。

note

用于双臂操作或移动操作任务。

移动全身关节到零位（move_whole_body_joint_zero）​

def move_whole_body_joint_zero(
    is_blocking: bool = True,
    leg_head_speed_rad_s: SupportsFloat = 0.2,
    leg_head_timeout_s: SupportsFloat = 15.0,
    params: Parameter = ...
) -> MotionStatus

将全身关节移动到预定义的零（家庭）配置。

腿部和头部关节通过 GalbotRobot（直接关节控制）进行控制，而左/右臂则通过启用碰撞检查的运动规划器进行规划。

零配置的联合顺序遵循 SDK 约定：leg(5) + head(2) + left_arm(7) + right_arm(7)。

参数

名称类型默认值描述
is_blockingboolTrue-
leg_head_speed_rad_sSupportsFloat0.2-
leg_head_timeout_sSupportsFloat15.0-
paramsParameter...-

返回值

类型描述
MotionStatus-

移除障碍物（remove_obstacle）​

def remove_obstacle(obstacle_id: str) -> MotionStatus

从规划场景中移除碰撞障碍物。

参数

名称类型默认值描述
obstacle_idstr需要传参-

返回值

类型描述
MotionStatus-
note

移除不存在的障碍物返回 INVALID_INPUT（非 NO_ERROR）。

设置末端执行器姿态（set_end_effector_pose）​

def set_end_effector_pose(
    target_pose: list[float],
    end_effector_frame: str,
    reference_frame: str = 'base_link',
    reference_robot_states: RobotStates = None,
    enable_collision_check: bool = True,
    is_blocking: bool = True,
    timeout: SupportsFloat = -1.0,
    params: Parameter = ...
) -> MotionStatus

命令末端执行器移动到目标笛卡尔坐标位姿。

笛卡尔运动命令的高级接口。内部执行逆运动学 (IK)、轨迹规划并执行运动。is_blocking 标志仅控制此 API 是等待完成还是在启动后台执行任务后立即返回。

参数

名称类型默认值描述
target_poselist[float]需要传参目标笛卡尔位姿：[x, y, z, qx, qy, qz, qw]（米，四元数）。
end_effector_framestr需要传参末端执行器坐标系
reference_framestr'base_link'参考坐标系
reference_robot_statesRobotStatesNone参考机器人起始状态
enable_collision_checkboolTrue是否启用碰撞检查
is_blockingboolTrue如果为真，则等待动作完成或超时。如果为假，机器人仍会执行动作，而此 API 会在启动一个等待执行完成的后台任务后立即返回。
timeoutSupportsFloat-1.0SDK 等待动作完成的最长时间（以秒为单位）。如果小于 0，则使用 params->timeout_second。在非阻塞模式下，此超时时间应用于后台任务。
paramsParameter...额外参数

返回值

类型描述
MotionStatus运动状态：- 成功：运动成功完成（阻塞）或后台执行开始（非阻塞）- 超时：运动超过超时时长- 输入无效：姿态或参数无效- 故障：规划或执行失败
note

运动类型（直线/关节空间）由 params->move_line 控制。

note

运动速度参数在 /data/galbot/config/default/service_motion_plan/traj_plan 下配置。

note

对于直接执行（params->is_direct_execute=true），避免传递 reference_robot_states。

warning

非阻塞模式不会取消或跳过机器人运动；它只会让此 API 立即返回。

设置运动规划配置（set_motion_plan_config）​

def set_motion_plan_config(config: MotionPlanConfig) -> MotionStatus

设置全局运动规划配置。

更新规划器设置，例如速度/加速度限制、规划算法参数和优化目标。影响后续所有的计划操作。

参数

名称类型默认值描述
configMotionPlanConfig需要传参-

返回值

类型描述
MotionStatus-
note

更改会持续存在，直到显式重置或进程重启。

note

有关可用参数，请参阅 MotionPlanConfig 文档。

状态转字符串（status_to_string）​

def status_to_string(status: MotionStatus) -> str

将 MotionStatus 枚举转换为人类可读的字符串。

将状态代码映射到用于日志记录、错误报告或 UI 显示的描述性字符串。

参数

名称类型默认值描述
statusMotionStatus需要传参-

返回值

类型描述
str-
note

使用 status_string_map_ 进行查找；如果状态未知则返回 UNKNOWN。

移动导航（GalbotNavigation）​

移动机器人底盘导航与定位接口。

该类提供线程安全的单例接口，用于控制移动底盘导航系统。支持二维位姿估计、重定位、带动态避障的目标导航与路径规划。导航系统在全局地图坐标系下工作，支持阻塞与非阻塞两种导航模式，并兼容差分驱动和全向底盘。除非另有说明，所有位姿参数均以地图坐标系表示。

添加导航箱子（add_bounding_box）​

def add_bounding_box(box_info: dict) -> tuple

添加用于导航障碍物过滤的箱子。

将 SDK 定义的箱子区域发送给融合服务，使导航在处理融合障碍物点时忽略这些区域，而不是把它们当作障碍物。box_tag 是箱子的唯一标记；后续调用 remove_bounding_box() 移除该箱子时，应传入相同的 box_tag。箱子位姿相对于 parent_link_name 表示。

参数

名称类型默认值描述
box_infodict需要传参箱子信息参数，字段包括：
- box_size: [length_x, length_y, length_z]，箱子在局部 x/y/z 轴方向上的尺寸，单位为米。
- box_pose: [x, y, z, qx, qy, qz, qw]，箱子相对于 parent_link_name 的位姿。
- box_tag: 箱子的唯一标记，后续 remove_bounding_box() 需要使用相同的 box_tag。
- parent_link_name: box_pose 所在的父连杆或父坐标系名称。

返回值

类型描述
tupleNavigationStatus::SUCCESS 如果盒子被融合接受；NavigationStatus::INVALID_INPUT 如果盒子信息格式错误；NavigationStatus::COMM_ERR 如果融合服务请求失败。
def attach_box_to_link(box_info: dict, ignore_collision_links: Sequence[str] = []) -> tuple

将箱子碰撞物挂载到机器人连杆。

该接口会把箱子作为附着碰撞物发送给 PNS。box_tag 是箱子的唯一标记；后续调用 detach_box_from_link() 解除该箱子挂载时，应传入相同的 box_tag。box_info.parent_link_name 作为 box_info.box_pose 的父连杆。

参数

名称类型默认值描述
box_infodict需要传参箱子信息参数，字段包括：
- box_size: [length_x, length_y, length_z]，箱子在局部 x/y/z 轴方向上的尺寸，单位为米。
- box_pose: [x, y, z, qx, qy, qz, qw]，箱子相对于 parent_link_name 的位姿。
- box_tag: 箱子的唯一标记，后续 detach_box_from_link() 需要使用相同的 box_tag。
- parent_link_name: box_pose 所在的父连杆或父坐标系名称。
ignore_collision_linksSequence[str][]碰撞检测时需要忽略该附着箱子的机器人连杆列表。

返回值

类型描述
tupleNavigationStatus::SUCCESS 如果盒子已连接；NavigationStatus::INVALID_INPUT 如果盒子信息格式错误；NavigationStatus::WAIT_INITIALIZED 如果 PNS 服务未准备就绪；NavigationStatus::COMM_ERR 如果 PNS 请求失败。

检查目标到达（check_goal_arrival）​

def check_goal_arrival() -> bool

检查机器人是否成功达到当前目标。

该方法查询导航系统以确定机器人是否已在可接受的位置和方向公差内到达目标位姿。当使用非阻塞导航模式轮询完成情况时，这特别有用。

返回值

类型描述
bool若机器人在容差阈值内到达目标则返回 true；若仍在导航、无活动目标或尚未到达则返回 false。
note

在非阻塞导航场景中最有用。

note

到达的公差阈值由导航模块的内部参数定义（通常在 YAML 配置文件中设置）。

note

如果没有激活的导航命令，此方法返回 false。

检查路径可达性（check_path_reachability）​

def check_path_reachability(goal_pose: numpy.ArrayLike, start_pose: numpy.ArrayLike) -> bool

检查地图中是否存在从起点到目标的无碰撞路径。

此方法查询全局路径规划器以确定指定的起始姿态和目标姿态之间是否存在有效的无碰撞路径。这对于在尝试导航之前验证目标姿态或多目标路径规划非常有用。

参数

名称类型默认值描述
goal_posenumpy.ArrayLike需要传参目标位姿（地图坐标系）
start_posenumpy.ArrayLike需要传参起始位姿

返回值

类型描述
bool若起点到目标存在无碰撞路径则返回 true；若未找到有效路径则返回 false。
note

此方法仅基于地图检查静态障碍物。

note

路径计算可能根据距离需要一些时间。

note

返回 true 并不保证成功导航。

def detach_box_from_link(box_tag: SupportsInt) -> tuple

从机器人连杆解除箱子碰撞物。

根据 box_tag 解除对应箱子的附着碰撞物。这里的 box_tag 应与 attach_box_to_link() 挂载该箱子时使用的 box_tag 保持一致。

参数

名称类型默认值描述
box_tagSupportsInt需要传参箱子的唯一标记，应与 attach_box_to_link() 挂载该箱子时使用的 box_tag 一致。

返回值

类型描述
tupleNavigationStatus::SUCCESS 如果盒子已分离；NavigationStatus::WAIT_INITIALIZED 如果 PNS 服务未准备就绪；NavigationStatus::COMM_ERR 如果 PNS 请求失败。

转储导航动态配置以进行调试（dump_navigation_configs）​

def dump_navigation_configs() -> tuple

转储导航动态配置以进行调试。

此方法查询常用的导航配置键，并通过 SDK 日志记录器打印响应。它用于诊断和调试。

返回值

类型描述
tuple导航状态指示所有调试查询请求是否已被接受。
note

输出格式取决于 PNS 服务响应，可能是 JSON 或 protobuf 文本格式。

获取导航箱子（get_bounding_box）​

def get_bounding_box() -> list

获取当前用于导航障碍物过滤的箱子。

查询融合服务，返回当前的箱子信息列表。box_tag 是箱子的唯一标记。

返回值

类型描述
list当前箱子信息列表；通信失败或没有可用箱子时返回空列表。

获取当前姿态（get_current_pose）​

def get_current_pose() -> list[float]

获取地图坐标系中机器人底盘的当前估计位姿。

该方法返回来自定位系统的最新姿态估计。位姿表示机器人的 base_link 坐标系相对于地图坐标系原点的位置和方向。

返回值

类型描述
list[float]姿态：以米为单位的位置 (x, y, z) 和以单位四元数 (x, y, z, w) 表示的方向在地图坐标系中。
note

仅当 is_localized() 返回 true 时返回的位姿才有效。

note

该位姿表示机器人底盘接地轮廓（base footprint）的中心。

获取任务状态（get_navigation_status）​

def get_navigation_status() -> NavigationTaskStatus

获取当前导航任务状态。

该接口适合在非阻塞模式下轮询任务进度，并根据状态判断任务是否完成。

返回值

类型描述
NavigationTaskStatusNavigationTaskStatus：当前任务状态。若尚未收到状态，则为 UNKNOWN；任务执行中为 RUNNING；任务结束后返回终态。
note

适用于非阻塞模式：循环查询 get_navigation_status()，并在终态或超时后退出。

查询任务状态（get_navigation_target_status）​

def get_navigation_target_status(task_id: str) -> NavigationTaskSnapshot

查询异步导航任务的最新状态。

该接口用于获取已提交任务的当前执行结果，适合在非阻塞模式下持续监控任务进度。

参数

名称类型默认值描述
task_idstr需要传参任务标识，由对应异步导航接口返回。

返回值

类型描述
NavigationTaskSnapshotNavigationTaskSnapshot 包含所请求任务的最新已知状态。

初始化（init）​

def init() -> bool

初始化导航子系统及其依赖项。

在使用任何其他导航功能之前必须调用此方法。它初始化通信通道、加载地图、启动定位模块并准备路径规划器。

返回值

类型描述
bool初始化成功返回 true，否则返回 false。
note

此方法应在获取单例实例后仅调用一次。

note

后续调用将返回第一次初始化的结果。

warning

在成功初始化前调用导航方法将导致错误。

检查是否已定位（is_localized）​

def is_localized() -> bool

检查机器人当前是否在地图中定位。

该方法查询定位系统以确定机器人是否具有足够置信度的有效姿态估计。未定位的机器人不应执行导航任务。

返回值

类型描述
bool若机器人已可靠定位则返回 true；若定位丢失或不确定则返回 false。
note

建议在发出导航命令前检查定位状态。

note

如果返回 false，请考虑调用 relocalize() 并提供初始猜测。

直线移动到目标（move_straight_to）​

def move_straight_to(
    goal_pose: numpy.ArrayLike,
    is_blocking: bool = True,
    timeout: SupportsFloat = 8
) -> tuple

将机器人移动到里程计坐标系中的相对目标位姿。

此方法命令机器人移动到相对于其在里程计 (odom) 坐标系中的当前位置指定的姿态。这对于不需要基于地图的规划的短距离、精确的运动非常有用。与navigate_to_goal()不同，此方法不执行动态障碍物检测或全局路径规划。它使用全向运动规划来直接移动到目标。

参数

名称类型默认值描述
goal_posenumpy.ArrayLike需要传参相对于当前机器人底座帧的目标位姿。
包含：
- x: 前后位移（米）
- y: 左右位移（米）
- theta: 转向角度（弧度）
is_blockingboolTrue执行模式标志。
- true (阻塞): 阻塞直到运动完成、失败或超时
- false (非阻塞): 发送导航命令后立即返回
timeoutSupportsFloat8阻塞模式最大等待时间（秒），默认 8.0 秒；仅在 is_blocking 为 true 时生效。

返回值

类型描述
tuple导航状态指示结果：- 非阻塞模式：命令接受状态 - 阻塞模式：最终运动结果（成功、失败、超时）
note

此方法不检查障碍物或碰撞。请先检查路径可达性。

note

此方法使用里程计帧，不需要地图帧。

note

适用于小的精确调整，如最终接近。

warning

由于禁用了碰撞检查，请确保路径无障。

warning

长距离下里程计漂移可能影响精度。建议缩短单次移动距离或定期重定位。

轨迹导航（navigate_along_trajectory）​

def navigate_along_trajectory(
    waypoints: Sequence[Pose],
    frame_id: str = 'map',
    speed_ratio: SupportsFloat = 1.0,
    enable_collision_check: bool = True
) -> TaskHandle

使用有序三维位姿提交轨迹导航任务。

该接口将输入位姿视为轨迹参考，导航系统可以对路径进行平滑和优化，因此中间位姿不保证被精确经过，但最终位姿会作为导航目标。

参数

名称类型默认值描述
waypointsSequence[Pose]需要传参按顺序排列的轨迹位姿点。
frame_idstr'map'参考坐标系，支持 "map"、"base_link"。
speed_ratioSupportsFloat1.0速度缩放因子 (0, 1.0]。
enable_collision_checkboolTrue是否启用碰撞检测。

返回值

类型描述
TaskHandleTaskHandle 包含提交的任务 ID、请求结果和消息。

多路点导航（navigate_through_waypoints）​

def navigate_through_waypoints(
    waypoints: Sequence[Waypoint],
    frame_id: str = 'map',
    enable_collision_check: bool = True
) -> TaskHandle

提交多路点导航任务。

该接口一次请求下发多个路点，并按照输入顺序逐点执行，适合需要明确经过多个目标位置的导航场景。

参数

名称类型默认值描述
waypointsSequence[Waypoint]需要传参按顺序排列的路点列表。
frame_idstr'map'参考坐标系，支持 "map"、"base_link"。
enable_collision_checkboolTrue是否启用碰撞检测。

返回值

类型描述
TaskHandleTaskHandle 包含提交的任务 ID、请求结果和消息。

导航到目标（navigate_to_goal）​

def navigate_to_goal(
    goal_pose: numpy.ArrayLike,
    enable_collision_check: bool = True,
    is_blocking: bool = False,
    timeout: SupportsFloat = 8,
    omni_plan: bool = False
) -> tuple

将机器人导航至地图坐标系中的目标位姿。

该方法命令移动底座使用全局路径规划器和局部轨迹控制器导航到指定的目标位姿。如果启用了碰撞检查，规划器将计算从当前姿态到目标的无碰撞路径，同时考虑静态地图障碍物和动态障碍物。

参数

名称类型默认值描述
goal_posenumpy.ArrayLike需要传参目标位姿（地图坐标系）
enable_collision_checkboolTrue是否启用碰撞检查
is_blockingboolFalse执行模式标志。默认值：false。false（非阻塞）：发送导航命令后立即返回，并启动一个 SDK 端的监视线程。返回状态指示命令是否被接受，而不是是否已达到目标。true（阻塞）：阻塞，直到达到目标、导航失败或当前线程超时。返回状态反映最终的导航结果。
timeoutSupportsFloat8SDK 端导航监控超时时间（以秒为单位）。默认值：8.0 秒。在阻塞模式下，当前线程监控此超时时间。在非阻塞模式下，后台监控线程使用此超时时间。如果在超时前未达到目标且导航尚未停止，SDK 将自动调用 stop_navigation 函数。
omni_planboolFalse运动规划模式标志。默认值：false。true：启用全向运动规划（全向驱动），允许机器人向任意方向移动并独立旋转。false：使用带运动学约束的差动驱动规划。

返回值

类型描述
tuple导航状态指示结果：- 非阻塞模式：命令接受状态 - 阻塞模式：最终导航结果（成功、失败、超时）
note

机器人必须先定位（is_localized() 返回 true），才能开始导航。

note

导航请求通信超时时间在内部是固定的，与 SDK 端导航监视器超时时间是分开的。

note

在阻塞模式和非阻塞模式下，SDK 端监控都会使用超时机制。

warning

长距离导航可能需要较长时间；建议使用非阻塞模式或监控进度。

导航到目标V2（navigate_to_goal_v2）​

def navigate_to_goal_v2(
    goal_pose: numpy.ArrayLike,
    max_vel: numpy.ArrayLike,
    pose_frame: str = 'map',
    enable_collision_check: bool = True,
    is_blocking: bool = False,
    timeout: SupportsFloat = 5.0,
    omni_plan: bool = False
) -> tuple

使用导航 v2 接口引导机器人到达目标姿态。

此方法向 PNS 服务发送导航 v2 规划请求。它支持通过 pose_frame 设置全局和局部目标坐标系，并在发送目标请求之前应用导航速度和运行时超时配置。

参数

名称类型默认值描述
goal_posenumpy.ArrayLike需要传参目标姿态：位置（x，y，z）以米为单位，方向以单位四元数（x，y，z，w）表示，在 pose_frame 中解释。
max_velnumpy.ArrayLike需要传参最大导航速度限制 [vx, vy, vyaw]。每个参数必须在 [0.05, 1.5] 范围内。线速度分量单位为米/秒，偏航速度单位为弧度/秒。低于 0.05 的值可能太小，无法可靠地驱动基座。
pose_framestr'map'目标姿态的参考系。仅“map”和“base_link”有效。默认值：“map”。“map”：地图坐标系中的全局目标姿态。“base_link”：相对于机器人基座的局部目标姿态。
enable_collision_checkboolTrue如果为真，则启用规划和运行时执行中最接近的 v2 碰撞检查字段。默认值：真。
is_blockingboolFalse执行模式标志。默认值：false。false（非阻塞）：发送导航命令后立即返回，并启动一个 SDK 端的监视线程。返回状态指示命令是否被接受。true（阻塞）：阻塞，直到到达目标、导航失败、被中断或 SDK 端监视超时。返回状态反映最终的导航结果。
timeoutSupportsFloat5.0导航运行时超时时间（以秒为单位）。默认值：5.0 秒。此值通过 set_navigation_timeout() 函数发送到 PNS 服务。负值将禁用导航运动时间限制。当超时时间为非负数时，SDK 端监控使用超时时间 + 5.0 秒；对于负超时时间，SDK 端监控将等待直至收到终端任务状态报告。
omni_planboolFalse运动规划模式标志。默认值：false。true：启用全方位运动规划。false：使用基于航向的规划。

返回值

类型描述
tuple导航状态指示结果：- 非阻塞模式下：命令接受状态 - 阻塞模式下：最终导航结果。成功和中断分别报告为 NavigationStatus::SUCCESS，失败报告为 NavigationStatus::FAIL，SDK 监视器超时报告为 NavigationStatus::TIMEOUT。
note

此方法使用导航 v2 主题和协议。

note

pose_frame 目前支持“map”表示全局目标，“base_link”表示局部目标。

warning

此方法可能会更改导航控制参数，进而影响基站控制行为，例如速度限制和导航超时。如果应用程序之后需要独立的底层基站控制，请重新设置基站控制参数以覆盖导航配置。

warning

长距离导航可能需要较长时间；建议使用非阻塞模式或监控进度。

速度指令导航机器人（navigate_with_velocity）​

def navigate_with_velocity(
    vx: SupportsFloat,
    vy: SupportsFloat,
    vyaw: SupportsFloat,
    duration_s: SupportsFloat = 3.0,
    enable_collision_check: bool = True
) -> tuple

使用导航 v2 接口，通过速度指令导航机器人。

此方法发送基于速度的导航指令。该指令包含平面基座速度分量和持续时间；执行持续时间由导航服务处理。

参数

名称类型默认值描述
vxSupportsFloat需要传参沿x轴的线速度，单位为米每秒。
vySupportsFloat需要传参沿y轴的线速度，单位为米每秒。
vyawSupportsFloat需要传参绕 z 轴的角速度，单位为弧度每秒。
duration_sSupportsFloat3.0命令持续时间（秒）。必须大于 0.0。默认值：3.0 秒。
enable_collision_checkboolTrue如果为真，则启用运行时碰撞检查，通过最接近的匹配 v2 碰撞字段进行碰撞检测。默认值：真。

返回值

类型描述
tuple导航状态指示导航服务是否已成功接受速度指令。
note

此方法使用导航 v2 主题和协议。

note

enable_collision_check 是一个运行时碰撞检查标志，而不是一个完整的避障策略开关。

warning

此方法是非阻塞的。它会在速度命令被接受后返回，而不是在速度持续时间结束后返回。

重定位（relocalize）​

def relocalize(init_pose: numpy.ArrayLike) -> tuple

执行重新定位以重新估计机器人在地图坐标系中的姿态。

该方法重置定位滤波器并提供初始姿态估计，以帮助机器人在已知地图中重新建立其位置。当机器人失去定位或手动将机器人放置在已知位置时，这非常有用。

参数

名称类型默认值描述
init_posenumpy.ArrayLike需要传参初始姿态估计

返回值

类型描述
tuple导航状态，指示重定位请求的结果。详见 NavigationStatus 枚举的取值说明。
note

重定位时机器人应保持静止以获得最佳效果。

note

调用此方法后，使用 is_localized() 验证成功。

移除导航箱子（remove_bounding_box）​

def remove_bounding_box(box_tag: SupportsInt) -> tuple

移除用于导航障碍物过滤的箱子。

根据 box_tag 移除对应箱子。这里的 box_tag 应与 add_bounding_box() 添加该箱子时使用的 box_tag 保持一致。

参数

名称类型默认值描述
box_tagSupportsInt需要传参箱子的唯一标记，应与 add_bounding_box() 添加该箱子时使用的 box_tag 一致。

返回值

类型描述
tupleNavigationStatus::SUCCESS 如果盒子被融合移除；NavigationStatus::COMM_ERR 如果融合服务请求失败。

设置导航到达阈值（set_navigation_arrival_threshold）​

def set_navigation_arrival_threshold(threshold: numpy.ArrayLike) -> tuple

设置导航到达阈值。

此方法更新导航规划和控制使用的位置和偏航容差，以确定是否已到达目标。

参数

名称类型默认值描述
thresholdnumpy.ArrayLike需要传参到达阈值 [x_error, y_error, yaw_error]。每个元素必须在 [0.03, 2.0] 范围内。位置误差以米为单位，偏航误差以弧度为单位。支持的最小精度为 0.03 米或弧度。

返回值

类型描述
tuple导航状态，指示配置请求是否已被接受。
note

不同类型的任务可能需要不同的到达精度。请在开始相应的导航任务之前配置此值。

设置导航运动学限制（set_navigation_kinematics_limits）​

def set_navigation_kinematics_limits(
    vel_limit: numpy.ArrayLike,
    acc_limit: numpy.ArrayLike,
    jerk_limit: numpy.ArrayLike
) -> tuple

设置导航运动学限制。

此方法通过 PNS 动态配置界面更新导航速度、加速度和加加速度限制。

参数

名称类型默认值描述
vel_limitnumpy.ArrayLike需要传参最大速度限制 [vx, vy, vyaw]。每个分量必须在 [0.05, 1.5] 范围内。线速度分量单位为米/秒，偏航速度单位为弧度/秒。低于 0.05 的值可能太小，无法可靠地驱动基座。
acc_limitnumpy.ArrayLike需要传参最大加速度限制 [ax, ay, ayaw]。每个分量的值必须在 [0.05, 7.5] 范围内。线加速度分量的单位为米/秒²，偏航加速度的单位为弧度/秒²。低于 0.05 的值可能太小，无法可靠地驱动底座。
jerk_limitnumpy.ArrayLike需要传参最大加加速度限制 [jx, jy, jyaw]。每个元素必须在 [0.05, 37.5] 范围内。线性加加速度分量单位为米/秒³，偏航加加速度单位为弧度/秒³。低于 0.05 的值可能太小，无法可靠地驱动基座。

返回值

类型描述
tuple导航状态，指示配置请求是否已被接受。
note

此配置需要在开始导航任务之前设置。

warning

此方法可能会更改导航控制参数，进而影响基础控制行为。如果应用程序之后需要独立的底层基础控制，请重新设置基础控制参数以覆盖导航配置。

设置动态目标（set_navigation_target）​

def set_navigation_target(
    target: Pose,
    frame: str = 'map',
    speed_ratio: SupportsFloat = 1.0,
    enable_collision_check: bool = True
) -> TaskHandle

异步提交动态导航目标。

该接口适用于目标可能频繁变化的场景，例如动态跟踪或遥操作。提交新目标后，导航系统会以最新目标为准重新规划；

前一个目标可能被后续请求抢占。为保证导航过程稳定，建议不要以过高频率调用。

参数

名称类型默认值描述
targetPose需要传参目标位姿，格式为 Pose（x, y, z, qx, qy, qz, qw）。
framestr'map'目标位姿参考坐标系，支持 "map"、"base_link"。
speed_ratioSupportsFloat1.0速度缩放因子 (0, 1.0]。
enable_collision_checkboolTrue是否启用碰撞检测。

返回值

类型描述
TaskHandleTaskHandle 包含提交的任务 ID、请求结果和消息。

设置导航超时时间（set_navigation_timeout）​

def set_navigation_timeout(timeout_s: SupportsFloat) -> tuple

设置导航超时配置。

此方法通过 PNS 动态配置接口更新导航超时。它可作为不应无限期运行的任务的安全保障。

参数

名称类型默认值描述
timeout_sSupportsFloat需要传参超时时间（秒）。

返回值

类型描述
tuple导航状态，指示配置请求是否已被接受。
note

该超时的具体服务端含义由 PNS 导航服务定义。

设置导航速度限制（set_navigation_velocity_limit）​

def set_navigation_velocity_limit(vel_limit: numpy.ArrayLike) -> tuple

设置导航速度限制。

此方法通过 PNS 动态配置接口更新导航速度限制。

参数

名称类型默认值描述
vel_limitnumpy.ArrayLike需要传参最大导航速度限制 [vx, vy, vyaw]。每个参数必须在 [0.05, 1.5] 范围内。线速度分量单位为米/秒，偏航速度单位为弧度/秒。低于 0.05 的值可能太小，无法可靠地驱动基座。

返回值

类型描述
tuple导航状态，指示配置请求是否已被接受。
note

此配置需要在开始导航任务之前设置。

warning

此方法可能会更改导航控制参数，进而影响基础控制行为。如果应用程序之后需要独立的底层基础控制，请重新设置基础控制参数以覆盖导航配置。

停止导航（stop_navigation）​

def stop_navigation() -> tuple

停止当前的导航任务并使机器人停止。

此方法立即取消任何正在进行的导航命令（来自navigate_to_goal()或move_straight_to()）并命令机器人停止。机器人将根据其运动学约束减速并安全停止。

返回值

类型描述
tuple导航状态指示是否成功将停止命令发送到导航系统。
note

可在导航期间随时调用。

note

停止后，机器人的位置可能与原始位置不同。

note

机器人将尝试根据其加速度限制平滑停止。

感知模块接口（GalbotPerception）​

感知模块接口；通过 get_instance(MachineType) 获取单例。

获取模块的最新缓存结果（get_latest_result）​

def get_latest_result(module: PerceptionModule) -> tuple

返回模块的最新缓存结果，不阻塞。

参数

名称类型默认值描述
modulePerceptionModule需要传参感知模块。

返回值

类型描述
tuple如果有结果可用返回true，否则返回false。

初始化感知模块并加载模型（init）​

def init(enabled_modules: Set[PerceptionModule]) -> bool

初始化感知模块并加载指定模块的模型。

参数

名称类型默认值描述
enabled_modulesSet[PerceptionModule]需要传参要启用的感知模块集合。

返回值

类型描述
bool如果所有请求的模块都成功加载则返回true。

为指定模块运行一次推理（run_once）​

def run_once(module: PerceptionModule) -> bool

为指定模块运行一次推理。

参数

名称类型默认值描述
modulePerceptionModule需要传参感知模块。

返回值

类型描述
bool成功返回true，失败返回false。
note

初始化后，等待约10秒让模型准备就绪后再调用run_once。

等待模块产生新结果或超时（wait_for_new_result）​

def wait_for_new_result(module: PerceptionModule, timeout_s: SupportsFloat = 5.0) -> bool

阻塞直到模块产生新结果或超时。与run_once配合使用获取最新输出。

参数

名称类型默认值描述
modulePerceptionModule需要传参感知模块。
timeout_sSupportsFloat5.0超时时间（秒）。

返回值

类型描述
bool成功返回true，超时返回false。

类型与枚举（Types & Enums）​

音频数据结构（AudioData）​

音频数据结构。

成员变量​
名称类型描述
datalist[int]音频数据包。
formatstr音频格式。
headerHeader音频消息头。
typestr音频类型。

碰撞检查选项（CollisionCheckOption）​

碰撞检测启用/禁用配置。

该结构在运动规划和执行期间提供对碰撞检查的细粒度控制。它支持独立切换自碰撞检测（机器人连杆相互碰撞）和环境碰撞检测（机器人与障碍物或工作空间边界碰撞）。禁用碰撞检查可以提高计算性能，但可能会导致不安全的轨迹。在受控环境中谨慎使用。

检查环境碰撞检测是否禁用（get_disable_env_collision_check）​

def get_disable_env_collision_check() -> bool

检查环境碰撞检测是否禁用

返回值

类型描述
bool-

检查自碰撞检测是否禁用（get_disable_self_collision_check）​

def get_disable_self_collision_check() -> bool

检查自碰撞检测是否禁用

返回值

类型描述
bool-

打印碰撞检测配置到标准输出（print）​

def print() -> None

打印碰撞检测配置到标准输出

启用或禁用环境碰撞检测（set_disable_env_collision_check）​

def set_disable_env_collision_check(disable: bool) -> None

设置是否禁用环境碰撞检测

参数

名称类型默认值描述
disablebool需要传参-
warning

禁用环境检查可能导致与障碍物发生碰撞。

启用或禁用自碰撞检测（set_disable_self_collision_check）​

def set_disable_self_collision_check(disable: bool) -> None

true禁用自碰撞检测，false启用

参数

名称类型默认值描述
disablebool需要传参-
warning

禁用自碰撞检查可能导致物理上不可行的配置。

控制状态（ControlStatus）​

控制命令执行状态枚举。

表示机器人控制命令的执行状态，包括关节控制、末端执行器控制等运动控制操作。

枚举值描述
COMM_DISCONNECTED通信断开
DATA_FETCH_FAILED数据获取失败
FAULT故障
INIT_FAILED初始化失败
INVALID_INPUT无效输入
IN_PROGRESS进行中
PUBLISH_FAIL发布失败
STOPPED_UNREACHED已停止但未到达
SUCCESS成功
TIMEOUT超时

深度数据（DepthData）​

包含来自深度相机或 RGB-D 传感器的压缩深度图像数据。与 ROS 2 的 sensor_msgs/compressedImage 消息类型兼容（支持深度扩展）。

成员变量​
名称类型描述
databytes包含原始或压缩深度图像数据的二进制数据块
depth_scaleint深度缩放因子，用于将像素值转换为实际深度（米），真实深度 = 像素值 / depth_scale，例如：depth_scale = 1000 表示像素值单位为毫米
formatstr指定深度编码和压缩格式，例如："16UC1; compressedDepth png"（16 位无符号整数，PNG 压缩深度）
headerHeader包含采集时间戳和相机坐标系
heightint深度图像的行数
widthint深度图像的列数

检测与分割结果（DetectionAndSegmentationResult）​

单对象检测或实例分割结果（2D框、类别、可选掩码/关键点）。

成员变量​
名称类型描述
bboxtuple[int, int, int, int]边界框为 (x, y, 宽度, 高度)
class_indexint类别索引
class_namestr类名
confidencefloat置信度得分
keypointslist[tuple[float, float]]关键点以 (x, y) 元组列表的形式呈现

检测结果（DetectionResult）​

单个模块周期的聚合感知输出（图像、掩码、姿态、点云等）。

成员变量​
名称类型描述
bounding_boxeslist[tuple[int, int, int, int]]边界框以列表形式表示（x，y，宽度，高度）
class_indiceslist[int]类索引列表
class_nameslist[str]类名列表
confidenceslist[float]置信列表
detection_resultslist[DetectionAndSegmentationResult]检测和分割结果列表
grasp_pose_resultlist[list[float]]抓握姿势结果
instance_maskAny实例掩码为 NumPy 数组（HxW 或 HxWxC），如果为空则为 None。
ocr_stringlist[str]OCR结果
point_cloudslist点云数据以 Nx3 numpy 数组列表的形式呈现
running_infostr运行信息字符串
sensor_namestr传感器名称
target_point_poseslist[numpy.NDArray[numpy.float32]"]]来自感知原型场 target_point_poses 的 4x4 姿态（与此处 target_poses 相同的缓冲区）
target_poseslist[numpy.NDArray[numpy.float32]"]]4x4 目标姿态矩阵列表（C++ targetPoses；感知原型 target_point_poses 填充此列表）
timestamp_nsint时间戳（纳秒）

清空结果（clear）​

def clear() -> None

清空所有存储的结果。

获取结果信息（get_result_info）​

def get_result_info() -> str

获取结果摘要字符串。

返回值

类型描述
str-

灵巧手状态（DexhandState）​

包含带时间戳的关节反馈；并在可用时（例如 Sharpa）包含来自灵巧手力反馈话题的逐传感器力/力矩测量。Sharpa 每只手按 22 关节建模。

成员变量​
名称类型描述
force_sensor_mapdict[str, EffortInfo]命名力传感器映射（Sharpa；其他为空）
joint_stateJointStateMessage灵巧手关节状态消息
timestamp_nsint状态时间戳（自纪元以来的纳秒数）

灵巧手类型（DexHandType）​

SDK 使用该枚举将灵巧手命令与状态查询路由到正确实现。Inspire 和 BrainCo 灵巧手走标准关节命令/状态通道。Sharpa 灵巧手使用专用 22 关节话题接口；完整状态通过 DexhandState 返回（包含力传感器）。Linker Hand L20 使用独立的 16 关节通道，以灵巧手组名为键；与 Sharpa 类似，其关节指令和反馈均以弧度为单位。

枚举值描述
BRAINCOBrainCo 灵巧手
INSPIREInspire 灵巧手
LINKER_L20Linker Hand L20 灵巧手
SHARPASharpa 灵巧手

力矩信息（EffortInfo）​

表示通常由力/扭矩传感器测量的 6 自由度 (6-DOF) 力螺旋（力和扭矩）。也称为空间力或广义力。

成员变量​
名称类型描述
forceVector3力向量（牛顿）：[fx, fy, fz]
- fx: X 方向力
- fy: Y 方向力
- fz: Z 方向力
timestamp_nsint测量时间戳（自纪元以来的纳秒数）
torqueVector3力矩向量（牛顿·米）：[tx, ty, tz]
- tx: 绕 X 轴力矩
- ty: 绕 Y 轴力矩
- tz: 绕 Z 轴力矩

错误（Error）​

描述单个模块或组件的错误，包括错误代码和用于调试和诊断的人类可读描述。

成员变量​
名称类型描述
commpentstr组件
descriptionstr错误描述
error_codeint用于程序化错误处理的数值错误代码

错误信息（ErrorInfo）​

包含来自多个模块或组件的带时间戳的错误消息集合。

成员变量​
名称类型描述
error_veclist[Error]误差向量
timestamp_nsint收集错误的时间戳（自纪元以来的纳秒数）

力数据（ForceData）​

包含来自 6 轴力/扭矩传感器的带有时间戳的力和扭矩测量值，通常安装在机器人手腕或工具端接口处。

成员变量​
名称类型描述
forceVector3力
timestamp_nsint测量时间戳（自纪元以来的纳秒数）
torqueVector3力矩向量（牛顿·米）：[tx, ty, tz]

坐标系（FrameTriad）​

表示坐标系三个正交轴的可视化表示，通常用于显示坐标系的方向和姿态。

成员变量​
名称类型描述
body_frame_idstr机身坐标系
headerHeader消息头
posePose无
reference_frame_idstr参考坐标系
twistTwist无
wrenchWrench无

夹爪状态（GripperState）​

表示平行爪夹具的当前状态，包括张开宽度、运动状态和抓取力。

成员变量​
名称类型描述
effortfloat力矩
is_movingbool运动标志（来自运动窗口），false 表示在配置的时间窗口内未检测到有效运动，true 表示检测到有效运动
joint_positionslist[float]夹爪关节位置（弧度），通常0-0.04米
timestamp_nsint状态时间戳（自纪元以来的纳秒数）
velocityfloat夹爪开合速度（米/秒）。
widthfloat夹爪开口宽度（米），距离

关节组命令（GroupCommand）​

用于控制一组关节的命令结构，包含多个关节的目标位置和参数。

成员变量​
名称类型描述
joint_commandslist[JointCommand]关节命令点
time_from_start_sfloat从轨迹起点算起的时间（秒）

消息头（Header）​

标准消息头包含时间戳和坐标系信息。时间戳以纳秒的形式存储（与其他传感器类型统一）。

成员变量​
名称类型描述
frame_idstr标识数据所在的坐标系，例如："base_link"、"world"、"camera_optical_frame"、"lidar_link"、"map"
timestamp_nsint数据采集的时间戳（自纪元以来的纳秒数），记录数据被捕获或生成的时间

IK 求解器配置（IKSolverConfig）​

逆运动学 (IK) 解算器配置参数。

该结构配置数值逆运动学解算器，用于计算实现所需末端执行器姿态的关节配置。它支持具有可配置种子策略、收敛容差、关节限制处理和超时参数的碰撞感知 IK。IK 求解是一种迭代数值优化过程，可以受益于多次随机初始化来找到可行的无碰撞解决方案。

获取关节限制安全裕度（get_col_aware_ik_joint_limit_bias）​

def get_col_aware_ik_joint_limit_bias() -> float

获取碰撞感知逆运动学关节限制偏差。较大的偏差会使求解器更倾向于避开碰撞区域。

返回值

类型描述
float-

获取碰撞感知IK 求解器超时（get_col_aware_ik_timeout）​

def get_col_aware_ik_timeout() -> float

获取碰撞感知逆运动学求解超时时间（秒）

返回值

类型描述
float-

检查是否启用碰撞检查日志（get_enable_collision_check_log）​

def get_enable_collision_check_log() -> bool

获取是否启用碰撞检测日志输出

返回值

类型描述
bool-

获取方向误差容差（get_rotation_eps）​

def get_rotation_eps() -> list[float]

获取旋转收敛容差（弧度）

返回值

类型描述
list[float]-

获取IK 求解器种子生成策略（get_seed_type）​

def get_seed_type() -> SeedType

获取逆运动学求解种子类型

返回值

类型描述
SeedType-

获取笛卡尔位置误差容差（get_translation_eps）​

def get_translation_eps() -> list[float]

获取平移收敛容差（米）

返回值

类型描述
list[float]-

打印IK 求解器配置到标准输出（print）​

def print() -> None

打印逆运动学求解器配置到标准输出

设置关节位置限制的安全裕度（set_col_aware_ik_joint_limit_bias）​

def set_col_aware_ik_joint_limit_bias(bias: SupportsFloat) -> None

设置碰撞感知逆运动学关节限制偏差

参数

名称类型默认值描述
biasSupportsFloat需要传参-
note

防止 IK 求解器提议在奇点附近的配置。

设置碰撞感知IK 求解器超时（set_col_aware_ik_timeout）​

def set_col_aware_ik_timeout(timeout: SupportsFloat) -> None

设置碰撞感知逆运动学求解超时时间（秒）

参数

名称类型默认值描述
timeoutSupportsFloat需要传参-
note

较长的超时允许更多种子尝试但会延迟规划。

启用或禁用碰撞检测日志（set_enable_collision_check_log）​

def set_enable_collision_check_log(enable: bool) -> None

设置是否启用碰撞检测日志输出

参数

名称类型默认值描述
enablebool需要传参-
note

用于调试由于碰撞约束导致的 IK 失败。

设置方向误差容差（set_rotation_eps）​

def set_rotation_eps(eps: list[float]) -> None

设置旋转收敛容差（弧度）

参数

名称类型默认值描述
epslist[float]需要传参-
note

当方向误差在此容差内时接受 IK 解。

设置种子类型（set_seed_type）​

def set_seed_type(type: SeedType) -> None

设置逆运动学求解种子类型

参数

名称类型默认值描述
typeSeedType需要传参-

设置笛卡尔位置误差容差（set_translation_eps）​

def set_translation_eps(eps: list[float]) -> None

设置平移收敛容差（米）

参数

名称类型默认值描述
epslist[float]需要传参-
note

当位置误差在此容差内时接受 IK 解。

IMU数据（ImuData）​

包含来自惯性测量单元 (IMU) 的带时间戳的数据，包括加速度计、陀螺仪和磁力计测量值。

成员变量​
名称类型描述
accelVector3线加速度（米/秒²）：[ax, ay, az]。
gyroVector3陀螺仪数据
magnetVector3磁力计数据
timestamp_nsint测量时间戳（自纪元以来的纳秒数）

关节命令（JointCommand）​

指定轨迹或控制命令中单个机器人关节所需的运动参数。

成员变量​
名称类型描述
accelerationfloat加速度
effortfloat期望的关节力矩（牛顿·米）
positionfloat期望的关节位置（弧度）
velocityfloat期望的关节速度（弧度/秒）

单关节状态（JointState）​

表示单个机器人关节的完整实时状态，包含关节标识、采样时间戳、运动学量（位置、速度、加速度）以及动力学量（力矩/effort 与电机电流）。

成员变量​
名称类型描述
accelerationfloat-
currentfloat-
effortfloat-
positionfloat-
timestamp_nsint-
velocityfloat-

关节状态消息（JointStateMessage）​

多个关节的关节状态的时间戳集合，通常表示机器人在某一时刻的完整关节配置的快照。

成员变量​
名称类型描述
joint_state_veclist[JointState]关节状态向量
timestamp_nsint采集时间戳（自纪元以来的纳秒数）

关节状态（JointStates）​

表示运动链的目标关节配置。扩展 RobotStates 以指定基于关节的运动目标。用于关节轨迹规划和正向运动学计算。所有关节角度必须以弧度为单位。矢量大小必须与指定运动链的自由度匹配。

成员变量​
名称类型描述
joint_positionslist[float]-

获取类型（get_type）​

def get_type() -> RobotStatesType

获取状态类型，指示这是关节空间目标

返回值

类型描述
RobotStatesType-

设置关节（set_joint）​

def set_joint(index: SupportsInt, val: SupportsInt) -> None

设置指定索引的关节值

参数

名称类型默认值描述
indexSupportsInt需要传参-
valSupportsInt需要传参-
note

函数执行边界检查；无效索引被静默忽略。

warning

越界访问不会返回错误；请确保索引有效。

设置关节位置（set_joint_positions）​

def set_joint_positions(joints: list[float]) -> None

设置所有关节位置

参数

名称类型默认值描述
jointslist[float]需要传参-
note

向量大小应等于链中驱动关节的数量。

运动学边界（KinematicsBoundary）​

机器人运动链关节的运动边界参数。

该结构定义了机器人运动链（例如，机械臂、移动底座或腿链）的运动学约束。它指定了链条中每个关节的位置、速度、加速度和加加速度限制。这些边界对于确保轨迹规划和执行过程中安全且物理上可行的运动至关重要。每个向量应包含运动链中每个关节的一个值。所有关节空间量均以弧度或每单位时间的弧度指定。

获取下限加速度限制（get_acc_lower_limit）​

def get_acc_lower_limit() -> list[float]

获取加速度下限（rad/s²）

返回值

类型描述
list[float]-

获取上限加速度限制（get_acc_upper_limit）​

def get_acc_upper_limit() -> list[float]

获取加速度上限（rad/s²）

返回值

类型描述
list[float]-

获取运动链名称（get_chain_name）​

def get_chain_name() -> str

获取该边界约束所属的运动链名称

返回值

类型描述
str-

获取下限加加速度限制（get_jerk_lower_limit）​

def get_jerk_lower_limit() -> list[float]

获取加加速度下限（rad/s³）

返回值

类型描述
list[float]-

获取上限加加速度限制（get_jerk_upper_limit）​

def get_jerk_upper_limit() -> list[float]

获取加加速度上限（rad/s³）

返回值

类型描述
list[float]-

获取下限位置限制（get_lower_limit）​

def get_lower_limit() -> list[float]

获取关节位置下限（rad）

返回值

类型描述
list[float]-

获取上限位置限制（get_upper_limit）​

def get_upper_limit() -> list[float]

获取关节位置上限（rad）

返回值

类型描述
list[float]-

获取下限速度限制（get_vel_lower_limit）​

def get_vel_lower_limit() -> list[float]

获取速度下限（rad/s）

返回值

类型描述
list[float]-

获取上限速度限制（get_vel_upper_limit）​

def get_vel_upper_limit() -> list[float]

获取速度上限（rad/s）

返回值

类型描述
list[float]-

打印输出（print）​

def print() -> None

打印运动学边界约束信息到标准输出

设置下限加速度限制（set_acc_lower_limit）​

def set_acc_lower_limit(limits: list[float]) -> None

设置加速度下限

参数

名称类型默认值描述
limitslist[float]需要传参-
note

用于轨迹优化和平滑约束。

设置上限加速度限制（set_acc_upper_limit）​

def set_acc_upper_limit(limits: list[float]) -> None

设置加速度上限

参数

名称类型默认值描述
limitslist[float]需要传参-
note

用于轨迹优化和平滑约束。

设置运动链名称（set_chain_name）​

def set_chain_name(name: str) -> None

设置该边界约束所属的运动链名称

参数

名称类型默认值描述
namestr需要传参-

设置下限加加速度限制（set_jerk_lower_limit）​

def set_jerk_lower_limit(limits: list[float]) -> None

设置加加速度下限

参数

名称类型默认值描述
limitslist[float]需要传参-
note

加加速度约束可提高运动平滑度并减少机械应力。

设置上限加加速度限制（set_jerk_upper_limit）​

def set_jerk_upper_limit(limits: list[float]) -> None

设置加加速度上限

参数

名称类型默认值描述
limitslist[float]需要传参-
note

加加速度约束可提高运动平滑度并减少机械应力。

设置下限位置限制（set_lower_limit）​

def set_lower_limit(limits: list[float]) -> None

设置关节位置下限

参数

名称类型默认值描述
limitslist[float]需要传参-
note

向量大小必须等于链中的关节数。

设置上限位置限制（set_upper_limit）​

def set_upper_limit(limits: list[float]) -> None

设置关节位置上限

参数

名称类型默认值描述
limitslist[float]需要传参-
note

向量大小必须等于链中的关节数。

设置下限速度限制（set_vel_lower_limit）​

def set_vel_lower_limit(limits: list[float]) -> None

设置速度下限

参数

名称类型默认值描述
limitslist[float]需要传参-
note

双向关节通常为负值。

设置上限速度限制（set_vel_upper_limit）​

def set_vel_upper_limit(limits: list[float]) -> None

设置速度上限

参数

名称类型默认值描述
limitslist[float]需要传参-
note

双向关节通常为正值。

激光雷达数据（LidarData）​

与 ROS 2sensor_msgs/PointCloud2 兼容的通用 N 维点云结构。将点数据存储为二进制 blob，并使用定义数据布局的字段描述符。支持有序（结构化）和无序（非结构化）点云。

成员变量​
名称类型描述
datalist[int]包含所有点数据的二进制数据块（按行优先顺序排列），大小应等于 row_step × height 字节，每个点占用 point_step 字节，布局根据 fields 描述符确定
fieldslist[PointField]描述每个点中存在的数据通道（x, y, z, intensity, rgb 等）及其二进制布局。
headerHeader消息头
heightint点云高度，无序点云 height = 1（单行），有序点云 height = 行数（例如，来自旋转 LiDAR 或深度相机）
is_bigendianbool数据的字节序，true 表示大端序，false 表示小端序（x86/ARM 系统通常为小端序）
is_densebool是否所有点都有效，true 表示所有点都有效且没有 NaN 或 Inf 值，false 表示点云可能包含无效点（NaN 或 Inf）
point_stepint单个点结构的总字节大小，包括所有字段和填充，必须 >= 所有字段大小的总和，可能包含对齐填充
row_stepint行行间距
widthint点云宽度，无序点云 width = 点的总数，有序点云 width = 每行的点数（列数），总点数 = height × width

直线轨迹碰撞检测基元（LineTrajCheckPrimitive）​

用于笛卡尔线性轨迹验证的几何基元配置。

该结构配置笛卡尔空间中线性末端执行器轨迹的碰撞检测几何表示。它支持两种基本类型：无限细线和扫掠体积圆柱体。选择适当的原语会影响碰撞检测的保守性和计算成本。圆柱体基元可以更准确地对机器人的实际扫描体积进行建模，但需要更昂贵的几何查询。

获取圆柱体基元半径（get_cylinder_prim_radius）​

def get_cylinder_prim_radius() -> float

获取圆柱基元半径（米）

返回值

类型描述
float-

获取直线检查基元类型（get_line_check_primitive_type）​

def get_line_check_primitive_type() -> PrimitiveType

获取直线检查基元类型

返回值

类型描述
PrimitiveType-

获取直线基元曲率（get_line_prim_curvature）​

def get_line_prim_curvature() -> float

获取直线基元曲率

返回值

类型描述
float-

打印输出（print）​

def print() -> None

打印直线轨迹检查基元信息到标准输出

设置圆柱体基元半径（set_cylinder_prim_radius）​

def set_cylinder_prim_radius(radius: SupportsFloat) -> None

设置圆柱基元半径（米）

参数

名称类型默认值描述
radiusSupportsFloat需要传参-
note

较大的半径增加安全裕度但可能过于保守。

note

仅当基元类型为 CYLINDER 时适用。

设置直线检查基元类型（set_line_check_primitive_type）​

def set_line_check_primitive_type(type: PrimitiveType) -> None

设置直线检查基元类型

参数

名称类型默认值描述
typePrimitiveType需要传参-
note

推荐 CYLINDER 用于安全关键应用。

设置直线基元曲率（set_line_prim_curvature）​

def set_line_prim_curvature(curvature: SupportsFloat) -> None

设置直线基元曲率

参数

名称类型默认值描述
curvatureSupportsFloat需要传参-
note

控制如何将弯曲路径离散为直线段。

note

较低的值提高精度但增加计算成本。

日志级别（LogLevel）​

表示日志消息的严重级别。

枚举值描述
CRITICAL严重日志
DEBUG调试日志
ERROR错误日志
INFO信息日志
TRACE跟踪日志
WARN警告日志

机器类型（MachineType）​

此枚举定义了 Galbot SDK 支持的不同机器人平台或机器类型。客户端可以使用这些值来指定他们正在使用的机器人模型，特别是对于返回特定于平台的实现的工厂方法。将枚举保留在通用类型定义中可确保整个 SDK 的一致性，同时隐藏各个模块中的实现细节。

枚举值描述
G1G1机器人
S1S1机器人

运动规划配置（MotionPlanConfig）​

全面的运动规划配置管理。

MotionPlanConfig 充当所有运动规划子系统的集中配置容器。它聚合了采样策略、轨迹生成参数、逆运动学解算器设置、碰撞检测选项、可行性验证标准和运动学约束边界。此类提供了用于配置复杂运动规划管道的统一接口，支持简单的机械臂规划和具有多个运动链的全身人形运动生成。配置对象通过共享指针进行延迟初始化和管理，以优化内存使用并支持可选功能配置。

创建碰撞检查选项（create_collision_check_option）​

def create_collision_check_option() -> CollisionCheckOption

创建碰撞检测选项并返回

返回值

类型描述
CollisionCheckOption-

创建IK 求解器配置（create_ik_solver_config）​

def create_ik_solver_config() -> IKSolverConfig

创建逆运动学求解器配置并返回

返回值

类型描述
IKSolverConfig-

创建直线轨迹检查基元（create_line_traj_check_primitive）​

def create_line_traj_check_primitive() -> LineTrajCheckPrimitive

创建直线轨迹检查基元并返回

返回值

类型描述
LineTrajCheckPrimitive-

创建采样器配置（create_sampler_config）​

def create_sampler_config() -> SamplerConfig

创建采样器配置并返回

返回值

类型描述
SamplerConfig-

创建轨迹可行性检查选项（create_trajectory_feasibility_check_option）​

def create_trajectory_feasibility_check_option() -> TrajectoryFeasibilityCheckOption

创建轨迹可行性检查选项并返回

返回值

类型描述
TrajectoryFeasibilityCheckOption-

创建轨迹规划配置（create_trajectory_plan_config）​

def create_trajectory_plan_config() -> TrajectoryPlanConfig

创建轨迹规划配置并返回

返回值

类型描述
TrajectoryPlanConfig-

获取碰撞检查选项（get_collision_check_option）​

def get_collision_check_option() -> CollisionCheckOption

获取碰撞检测选项

返回值

类型描述
CollisionCheckOption-
note

使用 create_collision_check_option() 确保有效的配置。

获取碰撞检查选项引用（get_collision_check_option_ref）​

def get_collision_check_option_ref() -> CollisionCheckOption

获取碰撞检测选项引用

返回值

类型描述
CollisionCheckOption-

获取可行性边界（get_feasibility_boundary）​

def get_feasibility_boundary() -> list[KinematicsBoundary]

获取可行性边界约束

返回值

类型描述
list[KinematicsBoundary]-

获取硬关节约束（get_hard_joint_limit）​

def get_hard_joint_limit() -> list[KinematicsBoundary]

获取硬关节位置限制边界

返回值

类型描述
list[KinematicsBoundary]-

获取IK 关节约束（get_ik_joint_limit）​

def get_ik_joint_limit() -> list[KinematicsBoundary]

获取逆运动学关节位置限制边界

返回值

类型描述
list[KinematicsBoundary]-

获取IK 求解器配置（get_ik_solver_config）​

def get_ik_solver_config() -> IKSolverConfig

获取逆运动学求解器配置

返回值

类型描述
IKSolverConfig-
note

使用 create_ik_solver_config() 确保有效的配置。

获取IK 求解器配置引用（get_ik_solver_config_ref）​

def get_ik_solver_config_ref() -> IKSolverConfig

获取逆运动学求解器配置引用

返回值

类型描述
IKSolverConfig-

获取直线轨迹检查基元（get_line_traj_check_primitive）​

def get_line_traj_check_primitive() -> LineTrajCheckPrimitive

获取直线轨迹检查基元

返回值

类型描述
LineTrajCheckPrimitive-
note

使用 create_line_traj_check_primitive() 确保有效的配置。

获取直线轨迹检查基元引用（get_line_traj_check_primitive_ref）​

def get_line_traj_check_primitive_ref() -> LineTrajCheckPrimitive

获取直线轨迹检查基元引用

返回值

类型描述
LineTrajCheckPrimitive-

获取是否恢复 IK 关节限制（get_revert_ik_joint_limit）​

def get_revert_ik_joint_limit() -> bool

获取是否恢复逆运动学关节限制

返回值

类型描述
bool-

获取需要恢复 IK 关节限制的运动链（get_revert_ik_joint_limit_chains）​

def get_revert_ik_joint_limit_chains() -> list[str]

获取需要恢复逆运动学关节限制的运动链列表

返回值

类型描述
list[str]-

获取采样器配置（get_sampler_config）​

def get_sampler_config() -> SamplerConfig

获取采样器配置

返回值

类型描述
SamplerConfig-
note

使用 create_sampler_config() 确保有效的配置。

获取采样器配置引用（get_sampler_config_ref）​

def get_sampler_config_ref() -> SamplerConfig

获取采样器配置引用

返回值

类型描述
SamplerConfig-

获取采样关节约束（get_sampler_joint_limit）​

def get_sampler_joint_limit() -> list[KinematicsBoundary]

获取采样器关节位置限制边界

返回值

类型描述
list[KinematicsBoundary]-

获取轨迹可行性检查选项（get_trajectory_feasibility_check_option）​

def get_trajectory_feasibility_check_option() -> TrajectoryFeasibilityCheckOption

获取轨迹可行性检查选项

返回值

类型描述
TrajectoryFeasibilityCheckOption-
note

使用 create_trajectory_feasibility_check_option() 确保有效的配置。

获取轨迹可行性检查选项引用（get_trajectory_feasibility_check_option_ref）​

def get_trajectory_feasibility_check_option_ref() -> TrajectoryFeasibilityCheckOption

获取轨迹可行性检查选项引用

返回值

类型描述
TrajectoryFeasibilityCheckOption-

获取轨迹规划配置（get_trajectory_plan_config）​

def get_trajectory_plan_config() -> TrajectoryPlanConfig

获取轨迹规划配置

返回值

类型描述
TrajectoryPlanConfig-
note

使用 create_trajectory_plan_config() 确保有效的配置。

获取轨迹规划配置引用（get_trajectory_plan_config_ref）​

def get_trajectory_plan_config_ref() -> TrajectoryPlanConfig

获取轨迹规划配置引用

返回值

类型描述
TrajectoryPlanConfig-

获取更新时间（get_update_time）​

def get_update_time() -> int

获取更新时间参数

返回值

类型描述
int-

打印输出（print）​

def print() -> None

将完整的运动规划配置打印到标准输出。

以人类可读格式输出所有子配置参数和运动学边界信息，便于调试、日志记录以及配置状态校验。

设置碰撞检查选项（set_collision_check_option）​

def set_collision_check_option(option: CollisionCheckOption) -> None

设置碰撞检测选项

参数

名称类型默认值描述
optionCollisionCheckOption需要传参-

设置可行性边界（set_feasibility_boundary）​

def set_feasibility_boundary(boundary: Sequence[KinematicsBoundary]) -> None

设置可行性边界约束

参数

名称类型默认值描述
boundarySequence[KinematicsBoundary]需要传参-
note

这些边界用于一般轨迹可行性检查。

设置硬关节约束（set_hard_joint_limit）​

def set_hard_joint_limit(boundary: Sequence[KinematicsBoundary]) -> None

设置硬关节位置限制边界

参数

名称类型默认值描述
boundarySequence[KinematicsBoundary]需要传参-
note

硬限制必须永不违反；通常对应于物理极限。

设置IK 关节约束（set_ik_joint_limit）​

def set_ik_joint_limit(boundary: Sequence[KinematicsBoundary]) -> None

设置逆运动学关节位置限制边界

参数

名称类型默认值描述
boundarySequence[KinematicsBoundary]需要传参-
note

IK 限制可能比硬限制更紧以改善收敛性。

设置IK 求解器配置（set_ik_solver_config）​

def set_ik_solver_config(config: IKSolverConfig) -> None

设置逆运动学求解器配置

参数

名称类型默认值描述
configIKSolverConfig需要传参-

设置直线轨迹检查基元（set_line_traj_check_primitive）​

def set_line_traj_check_primitive(primitive: LineTrajCheckPrimitive) -> None

设置直线轨迹检查基元

参数

名称类型默认值描述
primitiveLineTrajCheckPrimitive需要传参-

设置是否恢复 IK 关节限制（set_revert_ik_joint_limit）​

def set_revert_ik_joint_limit(flag: bool) -> None

设置是否恢复逆运动学关节限制

参数

名称类型默认值描述
flagbool需要传参-
note

用于通过暂时恢复极端限制来从受限配置中恢复。

设置需要恢复 IK 关节限制的运动链（set_revert_ik_joint_limit_chains）​

def set_revert_ik_joint_limit_chains(chains: Sequence[str]) -> None

设置需要恢复逆运动学关节限制的运动链列表

参数

名称类型默认值描述
chainsSequence[str]需要传参-
note

如果非空，自动启用 revert_ik_joint_limit 标志。

note

空向量禁用选择性恢复（适用于所有链）。

设置采样器配置（set_sampler_config）​

def set_sampler_config(config: SamplerConfig) -> None

设置采样器配置

参数

名称类型默认值描述
configSamplerConfig需要传参-

设置采样关节约束（set_sampler_joint_limit）​

def set_sampler_joint_limit(boundary: Sequence[KinematicsBoundary]) -> None

设置采样器关节位置限制边界

参数

名称类型默认值描述
boundarySequence[KinematicsBoundary]需要传参-
note

采样限制定义了探索配置空间的有效范围。

设置轨迹可行性检查选项（set_trajectory_feasibility_check_option）​

def set_trajectory_feasibility_check_option(option: TrajectoryFeasibilityCheckOption) -> None

设置轨迹可行性检查选项

参数

名称类型默认值描述
optionTrajectoryFeasibilityCheckOption需要传参-

设置轨迹规划配置（set_trajectory_plan_config）​

def set_trajectory_plan_config(config: TrajectoryPlanConfig) -> None

设置轨迹规划配置

参数

名称类型默认值描述
configTrajectoryPlanConfig需要传参-

设置更新时间（set_update_time）​

def set_update_time(t: SupportsInt) -> None

设置更新时间参数

参数

名称类型默认值描述
tSupportsInt需要传参-
note

用于配置版本控制和缓存失效。

运动状态（MotionStatus）​

机器人动作执行状态枚举。

表示机器人运动命令的执行状态，包括轨迹跟随、位姿到达等运动规划操作。

枚举值描述
COMM_DISCONNECTED通信断开
DATA_FETCH_FAILED数据获取失败
FAULT故障
INIT_FAILED初始化失败
INVALID_INPUT无效输入
IN_PROGRESS进行中
PUBLISH_FAIL发布失败
STATUS_NUM状态数量
STOPPED_UNREACHED已停止但未到达
SUCCESS成功
TIMEOUT超时
UNSUPPORTED_FUNCRION不支持的函数

导航任务快照。

导航任务状态。

枚举值描述
CLOSE_TO_OBSTACLE接近障碍物。
COLLISION碰撞。
FAILED失败。
INTERRUPTED中断。
OCCUPIED占用。
RUNNING运行中。
SUCCESS成功。
UNKNOWN未知。

里程计数据（OdomData）​

里程计数据。 包含来自里程计源（轮式编码器、IMU 融合等）的机器人位姿和速度估计。用于机器人定位和导航。

成员变量​
名称类型描述
angular_velocitylist[float]角速度 [ωx, ωy, ωz]（弧度/秒）
linear_velocitylist[float]线速度 [vx, vy, vz]（米/秒）
orientationlist[float]四元数方向 [qx, qy, qz, qw]
positionlist[float]位置 [x, y, z]（米）
timestamp_nsint里程计时间戳（自纪元以来的纳秒数）

参数（Parameter）​

运动规划参数配置类。

此类扩展了 PlannerConfig，为全身运动规划和执行提供全面的配置选项。它封装了执行模式、驱动类型、工具架处理、碰撞检查和坐标系规范。所有角度参数均以弧度为单位，线性参数以米（SI 单位）为单位。

成员变量​
名称类型描述
joint_statedict[str, list[float]]-
timeout_secondfloat-

获取驱动类型（get_actuate_type）​

def get_actuate_type() -> str

获取驱动类型

返回值

类型描述
str-

获取是否阻塞（get_blocking）​

def get_blocking() -> bool

获取是否阻塞执行

返回值

类型描述
bool-

获取是否检测碰撞（get_check_collision）​

def get_check_collision() -> bool

获取是否进行碰撞检测

返回值

类型描述
bool-

获取是否直接执行（get_direct_execute）​

def get_direct_execute() -> bool

获取是否直接执行

返回值

类型描述
bool-

获取参考帧（get_reference_frame）​

def get_reference_frame() -> str

获取参考坐标系

返回值

类型描述
str-

获取超时（get_timeout）​

def get_timeout() -> float

获取超时时间（秒）

返回值

类型描述
float-

获取工具位姿（get_tool_pose）​

def get_tool_pose() -> bool

获取目标工具位姿

返回值

类型描述
bool-

设置驱动类型（set_actuate）​

def set_actuate(actuate: str) -> None

设置驱动类型

参数

名称类型默认值描述
actuatestr需要传参-
warning

actuate 必须为受支持的取值（"with_chain_only"、"with_torso"、"with_leg"），否则行为未定义。

设置是否阻塞（set_blocking）​

def set_blocking(blocking: bool) -> None

设置是否阻塞执行

参数

名称类型默认值描述
blockingbool需要传参-

设置是否检测碰撞（set_check_collision）​

def set_check_collision(check_collision: bool) -> None

设置是否进行碰撞检测

参数

名称类型默认值描述
check_collisionbool需要传参-
warning

禁用碰撞检查可能会导致不安全的轨迹。

设置是否直接执行（set_direct_execute）​

def set_direct_execute(direct_execute: bool) -> None

设置是否直接执行

参数

名称类型默认值描述
direct_executebool需要传参-

设置是否移动直线（set_move_line）​

def set_move_line(move_line: bool) -> None

设置是否为直线运动

参数

名称类型默认值描述
move_linebool需要传参-
note

直线运动提供可预测的笛卡尔路径，但可能在狭窄空间中受限制。

设置参考帧（set_reference_frame）​

def set_reference_frame(frame: str) -> None

设置参考坐标系

参数

名称类型默认值描述
framestr需要传参-
note

必须是机器人 TF 树中的有效帧。

设置超时（set_timeout）​

def set_timeout(timeout: SupportsFloat) -> None

设置运动执行超时时间（秒）

参数

名称类型默认值描述
timeoutSupportsFloat需要传参-
note

仅在阻塞模式启用时适用。

设置工具位姿（set_tool_pose）​

def set_tool_pose(tool_pose: bool) -> None

设置目标工具位姿

参数

名称类型默认值描述
tool_posebool需要传参-

感知模块（PerceptionModule）​

启用的感知管道（初始化时加载的模型集）。

枚举值描述
FOUNDATION_STEREO高精度立体深度；用于需要高精度的任务（如搬箱子场景）。
LIGHT_STEREO轻量级立体深度；用于精度要求不高的场景（如迎宾场景）。此版本不支持。

点（Point）​

表示三维笛卡尔空间中的位置。

成员变量​
名称类型描述
xfloat-
yfloat-
zfloat-

二维点（Point2d）​

表示二维笛卡尔空间中的位置。

成员变量​
名称类型描述
xfloat-
yfloat-

点云字段（PointField）​

描述 PointCloud2 点结构中的一个数据字段，定义其名称、类型、偏移量和计数。与 ROS 2sensor_msgs/PointField 兼容。

成员变量​
名称类型描述
countint此字段的数组长度，标量字段（x, y, z, intensity）通常为 1，数组字段可能大于 1（例如 count=3 表示 3 元素向量）
datatype...数据类型
offsetint此字段相对于点数据结构起始位置的字节偏移量，例如：对于点布局 [x(float32), y(float32), z(float32), intensity(float32)]，x 的偏移为 0，y 的偏移为 4，z 的偏移为 8，intensity 的偏移为 12

点云字段数据类型（PointFieldDataType）​

数据类型枚举。

定义点云字段的原始数据类型，确定每个字段值的字节大小和解释方法。

枚举值描述
FLOAT3232位浮点数
FLOAT6464位浮点数
INT1616位整数
INT3232位整数
INT88位整数
UINT1616位无符号整数
UINT3232位无符号整数
UINT88位无符号整数
UNKNOWN未知

姿态（Pose）​

姿态（位置+方向）结构。

表示 3D 空间中的完整 6-DOF（自由度）姿态，结合位置（平移）和方向（旋转）信息。常用于机器人末端执行器姿态、物体姿态和坐标系变换。

二维位姿（Pose2d）​

二维位姿（位置+偏航）结构，适用于移动基座和导航目标表示二维笛卡尔空间中的平面位姿，结合了位置（平移）和航向角信息。

常用于移动基座位姿和局部导航目标。

成员变量​
名称类型描述
thetafloat-

姿态状态（PoseState）​

表示笛卡尔空间 (SE(3)) 中的目标末端执行器姿态。扩展 RobotStates 为运动链指定基于姿态的运动目标。用于逆运动学和笛卡尔轨迹规划。姿态值：以米为单位的位置，以四元数为单位的方向。坐标系必须存在于机器人的 TF 树中。

获取类型（get_type）​

def get_type() -> RobotStatesType

获取位姿状态类型

返回值

类型描述
RobotStatesType-

几何基元类型（PrimitiveType）​

原始类型相关说明。

枚举值描述
CYLINDER圆柱体
LINE直线

四元数（Quaternion）​

使用四元数表示 (x, y, z, w) 表示 3D 旋转。单位四元数的大小为 1，表示有效旋转。

成员变量​
名称类型描述
wfloat-
xfloat-
yfloat-
zfloat-

RGB数据（RgbData）​

包含来自 RGB 相机的压缩彩色图像数据。兼容 ROS 2sensor_msgs/CompressedImage 格式。

成员变量​
名称类型描述
databytes包含压缩图像数据的二进制数据块
formatstr指定压缩格式和编码
headerHeader包含采集时间戳和相机坐标系

机器人状态（RobotStates）​

封装机器人的完整运动状态，包括全身关节配置和移动底座位姿。此类作为更专业的状态表示（PoseState、JointStates）的基础，并在整个规划和控制管道中用于状态规范和反馈。所有角度值均以弧度为单位，线性值以米（SI 单位）为单位。基本姿态使用四元数表示方向（x、y、z、qx、qy、qz、qw）。

成员变量​
名称类型描述
base_statelist[float]-
whole_body_jointlist[float]-

获取类型（get_type）​

def get_type() -> RobotStatesType

获取机器人状态类型

返回值

类型描述
RobotStatesType-

设置基座状态（set_base_state）​

def set_base_state(base_pose: Pose) -> None

设置底座状态（位姿）

参数

名称类型默认值描述
base_posePose需要传参-
note

四元数必须单位归一化（x^2 + y^2 + z^2 + w^2 = 1）。

设置全身关节（set_whole_body_joint）​

def set_whole_body_joint(joint_positions: list[float]) -> None

设置全身关节位置

参数

名称类型默认值描述
joint_positionslist[float]需要传参-
note

向量大小应等于总驱动关节数。

机器人状态类型（RobotStatesType）​

用于区分派生状态类型的枚举。

用于RobotStates派生类的运行时类型识别。

枚举值描述
JOINT关节
POSE姿态
ROBOT_STATES机器人状态数量

S1控制器名称（S1ControllerName）​

S1 控制器名称的字符串常量。

定义S1机器人型号支持的控制器名称。

枚举值描述
ELEVATOR_CTRL升降控制器
HEAD_PVT_CTRL头部位置-速度-力矩控制器
LEFT_ARM_PVT_CTRL左臂位置-速度-力矩控制器
LEFT_CAMERA_CTRL左眼相机控制器
LEFT_GRIPPER_CTRL左夹爪控制器
RIGHT_ARM_PVT_CTRL右臂位置-速度-力矩控制器
RIGHT_CAMERA_CTRL右眼相机控制器
RIGHT_GRIPPER_CTRL右夹爪控制器
SWERVE_CHASSIS_POSE_CTRL转向底盘姿态控制器
SWERVE_CHASSIS_TWIST_CTRL转向底盘速度控制器

S1关节组（S1JointGroup）​

“关节组”是 SDK 的主要控制/规划单元，而不是单个关节： 运动一致控制：每个链/末端执行器组都会验证和执行命令。确定性命令排序：joint_groups 按组顺序扩展为具体的 joint_names。组级行为：每个组都有自己的主动/被动属性和执行容忍度。推荐用法：在填充 API 参数（例如 joint_groups）时，使用此结构体中的常量。如果需要精确的关节名称，请在运行时通过 get_joint_names(true, {group_name}) 查询它们，而不是硬编码。在同时接受 joint_groups 和 joint_names 的 API 中，joint_names 优先。

枚举值描述
head头部
left_arm左7自由度手臂链。默认关节：left_arm_joint1 ... left_arm_joint7。典型用途：左臂操作。
left_camera左眼相机
left_gripper左夹爪链。默认关节：left_gripper_joint1。典型用途：夹爪宽度控制。
right_arm右7自由度手臂链。默认关节：right_arm_joint1 ... right_arm_joint7。典型用途：右臂操作。
right_camera左眼相机
right_gripper右夹爪链。默认关节：right_gripper_joint1。典型用途：夹爪宽度控制。
swerve_chassis舵机底盘机构组（关节位置控制中为被动）。
默认关节：Wheel_1_direction、Wheel_1_velocity、Wheel_2_direction、Wheel_2_velocity...
torso躯干

采样器配置（SamplerConfig）​

基于采样的运动规划器的配置参数。

该结构配置基于采样的规划算法（例如，RRT、RRT*）。它控制状态空间采样分辨率、插值设置、路径简化和规划终止条件。基于采样的规划器通过随机采样状态并将它们连接起来构建运动计划图来探索配置空间。

获取是否插值（get_interpolate）​

def get_interpolate() -> bool

获取是否启用插值

返回值

类型描述
bool-

获取插值数量（get_interpolation_cnt）​

def get_interpolation_cnt() -> int

获取插值点数量

返回值

类型描述
int-

获取最大规划时间（get_max_planning_time）​

def get_max_planning_time() -> float

获取最大规划时间（秒）

返回值

类型描述
float-

获取最大简化时间（get_max_simplification_time）​

def get_max_simplification_time() -> float

获取最大简化时间（秒）

返回值

类型描述
float-

获取是否简化（get_simplify）​

def get_simplify() -> bool

获取是否启用简化

返回值

类型描述
bool-

获取状态检查分辨率（get_state_check_resolution）​

def get_state_check_resolution() -> float

获取状态检查分辨率

返回值

类型描述
float-

获取状态检查类型（get_state_check_type）​

def get_state_check_type() -> StateCheckType

获取状态检查类型

返回值

类型描述
StateCheckType-

获取终止条件类型（get_termination_condition_type）​

def get_termination_condition_type() -> TerminationConditionType

获取终止条件类型

返回值

类型描述
TerminationConditionType-

打印输出（print）​

def print() -> None

打印采样器配置信息到标准输出

设置是否插值（set_interpolate）​

def set_interpolate(enable: bool) -> None

设置是否启用插值

参数

名称类型默认值描述
enablebool需要传参-
note

插值可提高轨迹平滑度和碰撞检测覆盖率。

设置插值数量（set_interpolation_cnt）​

def set_interpolation_cnt(cnt: SupportsInt) -> None

设置插值点数量

参数

名称类型默认值描述
cntSupportsInt需要传参-
note

较高的计数可改善碰撞检测但增加计算成本。

设置最大规划时间（set_max_planning_time）​

def set_max_planning_time(time: SupportsFloat) -> None

设置最大规划时间（秒）

参数

名称类型默认值描述
timeSupportsFloat需要传参-
note

如果找到精确解，规划可能提前终止（取决于终止条件）。

设置最大简化时间（set_max_simplification_time）​

def set_max_simplification_time(time: SupportsFloat) -> None

设置最大简化时间（秒）

参数

名称类型默认值描述
timeSupportsFloat需要传参-
note

较长的简化时间可能产生更短、更平滑的路径。

设置是否简化（set_simplify）​

def set_simplify(enable: bool) -> None

设置是否启用简化

参数

名称类型默认值描述
enablebool需要传参-
note

简化减少路点并提高轨迹效率。

设置状态检查分辨率（set_state_check_resolution）​

def set_state_check_resolution(resolution: SupportsFloat) -> None

设置状态检查分辨率

参数

名称类型默认值描述
resolutionSupportsFloat需要传参-
note

较低的值增加规划精度但可能减慢计算速度。

设置状态检查类型（set_state_check_type）​

def set_state_check_type(type: StateCheckType) -> None

设置状态检查类型

参数

名称类型默认值描述
typeStateCheckType需要传参-

设置终止条件类型（set_termination_condition_type）​

def set_termination_condition_type(type: TerminationConditionType) -> None

设置终止条件类型

参数

名称类型默认值描述
typeTerminationConditionType需要传参-

随机种子类型（SeedType）​

指定逆运动学 (IK) 解算器的初始化策略。不同的种子类型会影响收敛速度和解的质量。

枚举值描述
RANDOM_PROGRESSIVE_SEED随机渐进种子
RANDOM_SEED随机种子
USER_DEFINED_SEED用户自定义种子

传感器类型（SensorType）​

描述机器人上各种传感器的传感器类型枚举。

识别机器人上可用于感知、定位和操作任务的不同传感器类型。

枚举值描述
BACK_IMUS1 后置激光雷达 IMU（惯性测量单元）
BACK_LIDARS1 后置激光雷达（后置），安装在车尾用于后方感知
CHASSIS_IMU底盘惯性测量单元 (IMU)
CHASSIS_LIDARS1 底盘激光雷达（前置），安装在底盘上用于前向感知
HEAD_IMUS1头部激光雷达惯性测量单元（IMU）
HEAD_LEFT_CAMERA头部左侧摄像头，通常是用于立体视觉的RGB摄像头
HEAD_LIDARS1 头部激光雷达（前置），安装在头部用于前向感知
HEAD_RIGHT_CAMERA头部右侧摄像头，通常是用于立体视觉的RGB摄像头
LEFT_ARM_CAMERA左臂摄像头，安装在左侧机械臂上，用于视觉伺服
LEFT_ARM_DEPTH_CAMERA左臂深度摄像头，提供左臂工作区的 RGB-D 数据
LEFT_ARM_INFRA_CAMERA_1左臂红外摄像头 1，提供左臂工作区域的红外数据
LEFT_ARM_INFRA_CAMERA_2左臂红外摄像头 2，提供左臂工作区域的红外数据
RIGHT_ARM_CAMERA右臂摄像头，安装在右侧机械臂上，用于视觉伺服
RIGHT_ARM_DEPTH_CAMERA右臂深度摄像头，提供右臂工作空间的 RGB-D 数据
RIGHT_ARM_INFRA_CAMERA_1右臂红外摄像头 1，提供右臂工作区域的红外数据
RIGHT_ARM_INFRA_CAMERA_2右臂红外摄像头 2，提供右臂工作区域的红外数据

SingoriX目标（SingoriXTarget）​

SingoriX控制器的目标表示，用于与SingoriX外部控制器通信。

成员变量​
名称类型描述
headerHeader消息头
target_group_trajectory_mapdict[str, TargetGroupTrajectory]关节空间轨迹映射
target_task_trajectory_mapdict[str, TargetTaskTrajectory]任务空间轨迹映射

状态检查类型（StateCheckType）​

状态检查类型相关说明。

枚举值描述
EUCLIDEAN_DISTANCE欧氏距离
RADIAN_DISTANCE弧度距离

吸盘动作状态（SUCTION_ACTION_STATE）​

代表真空吸盘末端执行器的运行状态，跟踪从空闲到成功或失败的抽吸过程。

枚举值描述
FAILED失败
IDLE空闲
SUCCESS吸盘动作成功
SUCKING吸取中

吸盘状态（SuctionCupState）​

包含真空吸盘夹具的当前状态，包括激活状态、压力读数和动作状态。

成员变量​
名称类型描述
action_stateSUCTION_ACTION_STATE动作状态
activationbool激活
pressurefloat压力
timestamp_nsint状态时间戳（自纪元以来的纳秒数）

同步观测数据（SyncedObservation）​

同步多传感器观测数据。

包含按时间戳对齐的相机帧和可选关节状态。对齐锚点为传入 get_synced_observation() 的第一个相机。

成员变量​
名称类型描述
depth_data_mapdict[SensorType, DepthData]按时间戳对齐的深度图数据
joint_stateJointStateMessage锚点时间戳对应的最近邻关节状态
rgb_data_mapdict[SensorType, RgbData]按时间戳对齐的 RGB 图像数据

目标配置（TargetConfig）​

目标的配置参数，包含目标类型、采样方式、约束条件等设置。

成员变量​
名称类型描述
target_dataint目标数据位掩码
target_idstr目标标识符
target_priorityint目标优先级
target_samplingTargetSampling采样策略
target_tsTimestamp目标时间戳
target_typeint目标类型位掩码

目标关节组轨迹（TargetGroupTrajectory）​

目标在关节组空间中的轨迹，包含一系列途经点和时间信息。

成员变量​
名称类型描述
group_commandslist[GroupCommand]轨迹点
joint_nameslist[str]关节名称
target_configTargetConfig目标配置

目标采样（TargetSampling）​

目标轨迹的采样方法，用于在路径点之间生成中间点。

枚举值描述
TARGET_SAMPLING_B_SPLINESB样条采样
TARGET_SAMPLING_CUBIC_SPLINES三次样条采样
TARGET_SAMPLING_CUSTOM自定义采样
TARGET_SAMPLING_DEFAULT默认采样
TARGET_SAMPLING_DIRECT_PASS直接传递
TARGET_SAMPLING_LINEAR_INTERPOLATE线性插值采样
TARGET_SAMPLING_QUINTIC_SPLINES五次样条采样
TARGET_SAMPLING_S_CURVE_PROFILES曲线轮廓采样
TARGET_SAMPLING_TRAPEZOIDAL_PROFILE梯形轮廓采样

目标任务轨迹（TargetTaskTrajectory）​

目标在任务空间中的轨迹，包含任务级别的约束和要求。

成员变量​
名称类型描述
group_nameslist[str]关联的关节组名称
joint_nameslist[str]关联的关节名称
subtask_nameslist[str]子任务名称
target_configTargetConfig目标配置
task_commandslist[TaskCommand]轨迹点

任务命令（TaskCommand）​

任务级别的命令结构，包含一个或多个目标和执行参数。

成员变量​
名称类型描述
subtask_commandslist[FrameTriad]该时刻的子任务命令
time_from_start_sfloat相对轨迹起点的时间（秒）

导航任务句柄（TaskHandle）​

异步提交导航任务后返回的句柄。

终止条件类型（TerminationConditionType）​

终止条件类型相关说明。

枚举值描述
TIMEOUT仅当超过最大规划时间时终止
TIMEOUT_AND_EXACT_SOLUTION超时或精确解

时间戳（Timestamp）​

表示具有秒和纳秒分量的高精度时间点。兼容 ROS 2builtin_interfaces/Time 和 std_msgs/Header 时间戳格式。

成员变量​
名称类型描述
nanosecint纳秒
secint秒

轨迹（Trajectory）​

表示一个完整的机器人轨迹，包含多个随时间变化的路点。joint_groups 和 joint_names 不能同时为空。如果同时为空，函数将返回 ControlStatus::INVALID_INPUT。此限制确保了关节顺序的确定性，防止因隐式内部默认顺序（可能在 SDK 版本之间变化）导致的难以察觉的 bug。使用方法：推荐设置具有语义组名的 joint_groups 或 joint_names。如果同时设置，joint_names 优先于 joint_groups

成员变量​
名称类型描述
joint_groupslist[str]关节组名称列表，如 ["left_arm", "right_arm"]。注意：joint_groups 和 joint_names 不能同时为空
joint_nameslist[str]显式关节名称。当非空时，优先于 joint_groups，并且仅验证为活动关节。当 joint_groups 也为空时，不能同时为空。
pointslist[TrajectoryPoint]有序的轨迹路点列表。每个点的 joint_command_vec 必须与 joint_names 或 joint_groups 定义的关节顺序匹配。关节顺序的确定方式：(1) 如果 joint_names 非空，则使用 joint_names；(2) 否则使用 joint_groups 按顺序展开（例如，{"head","left_arm"} 展开为 head_joint1, head_joint2, left_arm_joint1, ... left_arm_joint7）。

轨迹控制状态（TrajectoryControlStatus）​

机器人轨迹执行状态枚举。

表示机器人沿着由多个路点组成的预先规划的轨迹运行时的实时执行状态。

枚举值描述
COMPLETED已完成
DATA_FETCH_FAILED数据获取失败
ERROR错误日志
INVALID_INPUT无效输入
RUNNING运行中
STOPPED_UNREACHED轨迹执行过程中停止但未达到终点

轨迹可行性检查选项（TrajectoryFeasibilityCheckOption）​

轨迹验证和可行性检查配置。

该结构提供了对在轨迹验证期间强制执行可行性约束的细粒度控制。它支持碰撞检测、关节限制合规性和速度剖面可行性的独立切换。有选择地禁用检查可以提高调试、模拟或保证满足某些约束的场景的计算性能。禁用可行性检查可能会产生不安全或物理上无法实现的轨迹。仅当通过其他方式验证约束时才应谨慎使用。

获取是否禁用碰撞检查（get_disable_collision_check）​

def get_disable_collision_check() -> bool

获取是否禁用碰撞检测

返回值

类型描述
bool-

获取是否禁用关节限制检查（get_disable_joint_limit_check）​

def get_disable_joint_limit_check() -> bool

获取是否禁用关节限制检查

返回值

类型描述
bool-

获取是否禁用速度可行性检查（get_disable_velocity_feasibility_check）​

def get_disable_velocity_feasibility_check() -> bool

获取是否禁用速度可行性检查

返回值

类型描述
bool-

打印输出（print）​

def print() -> None

打印轨迹可行性检查选项到标准输出

设置是否禁用碰撞检查（set_disable_collision_check）​

def set_disable_collision_check(disable: bool) -> None

设置是否禁用碰撞检测

参数

名称类型默认值描述
disablebool需要传参-
warning

禁用碰撞检查可能导致轨迹与环境发生碰撞

设置是否禁用关节限制检查（set_disable_joint_limit_check）​

def set_disable_joint_limit_check(disable: bool) -> None

设置是否禁用关节限制检查

参数

名称类型默认值描述
disablebool需要传参-
warning

禁用关节限制检查可能导致轨迹超出关节限位

设置是否禁用速度可行性检查（set_disable_velocity_feasibility_check）​

def set_disable_velocity_feasibility_check(disable: bool) -> None

设置是否禁用速度可行性检查

参数

名称类型默认值描述
disablebool需要传参-
note

速度可行性确保轨迹可以被机器人执行。

轨迹规划配置（TrajectoryPlanConfig）​

轨迹规划和参数化配置。

该结构配置轨迹生成参数，用于将离散运动计划转换为平滑的时间参数化轨迹。它支持单段和多路点轨迹规划。轨迹规划涉及计算沿几何路径的速度和加速度分布，同时尊重运动学约束。

获取最小移动时间（get_min_move_time）​

def get_min_move_time() -> float

获取最小运动时间（秒）

返回值

类型描述
float-

获取直线插值中间点（get_move_line_intermediate_point）​

def get_move_line_intermediate_point() -> float

获取直线运动中间点设置

返回值

类型描述
float-

获取路点规划预期时间（get_way_point_plan_expected_time）​

def get_way_point_plan_expected_time() -> float

获取路点规划期望时间

返回值

类型描述
float-

打印输出（print）​

def print() -> None

打印轨迹规划配置信息到标准输出

设置最小移动时间（set_min_move_time）​

def set_min_move_time(time: SupportsFloat) -> None

设置最小运动时间（秒）

参数

名称类型默认值描述
timeSupportsFloat需要传参-
note

非零值防止运动过快；0.0 允许在运动学限制内的最高速度

设置直线插值中间点（set_move_line_intermediate_point）​

def set_move_line_intermediate_point(value: SupportsFloat) -> None

设置直线运动中间点设置

参数

名称类型默认值描述
valueSupportsFloat需要传参-
note

较高的值提高笛卡尔路径精度但增加计算成本。

设置路点规划预期时间（set_way_point_plan_expected_time）​

def set_way_point_plan_expected_time(time: SupportsFloat) -> None

设置路点规划期望时间

参数

名称类型默认值描述
timeSupportsFloat需要传参-
note

用作时间最优轨迹生成算法的提示。

轨迹点（TrajectoryPoint）​

表示机器人轨迹中的路点，指定特定时间的关节状态。joint_command_vec 的顺序必须与 Trajectory.joint_names 或 Trajectory.joint_groups（按顺序展开）定义的关节顺序一致。顺序不匹配将导致未定义行为。

成员变量​
名称类型描述
joint_command_veclist[JointCommand]该路点所有关节的关节命令列表。顺序必须与 joint_names 或 joint_groups 展开顺序一致。
time_from_start_secondfloat起始时间偏移（秒）

扭曲速度（Twist）​

表示刚体的线速度和角速度组合，遵循ROS标准消息格式。

成员变量​
名称类型描述
angularVector3角速度矢量
linearVector3线速度矢量

三维向量（Vector3）​

表示三维矢量，用于力、扭矩、速度、加速度和其他矢量。

成员变量​
名称类型描述
xfloatX分量
yfloatY分量
zfloatZ分量

路点（Waypoint）​

多路点导航的目标路点定义。

路点可选参数（WaypointParams）​

用于调整单个路点到达精度和运动平滑度的可选参数。

成员变量​
名称类型描述
acceleration_scalefloat-
arrival_orientation_thresholdfloat-
arrival_position_threshold_xfloat-
arrival_position_threshold_yfloat-
jerk_scalefloat-
velocity_scalefloat-

全身控制异常（WBCException）​

将 MotionStatus 枚举值转换为字符串。

力与力矩（Wrench）​

力与力矩相关说明。

成员变量​
名称类型描述
forceVector3力矢量
torqueVector3扭矩矢量

检查运动状态（check_motion_status）​

def check_motion_status(status: MotionStatus) -> str

检查当前运动状态，验证运动是否满足约束条件。

参数

名称类型默认值描述
statusMotionStatus需要传参运动状态

返回值

类型描述
strstr：运动状态的字符串表示。

创建 JointStates 实例（create_joint_state）​

def create_joint_state() -> JointStates

创建一个 JointStates 实例。

返回值

类型描述
JointStatesJointStates：新的关节状态对象。

创建参数（create_parameter）​

def create_parameter(
    direct_execute: bool,
    blocking: bool,
    timeout: SupportsFloat,
    actuate: str,
    tool_pose: bool,
    check_collision: bool,
    frame: str = 'base_link'
) -> Parameter

创建运动命令参数，设置执行方式、超时、碰撞检查等选项。

参数

名称类型默认值描述
direct_executebool需要传参是否直接执行该运动。
blockingbool需要传参是否阻塞执行直到完成。
timeoutSupportsFloat需要传参等待运动完成的最长时间。
actuatestr需要传参驱动类型（位置/速度/力矩）。
tool_posebool需要传参该运动是否针对工具位姿。
check_collisionbool需要传参是否进行碰撞检测。
framestr'base_link'运动使用的坐标系，默认值为 "base_link"。

返回值

类型描述
ParameterParameter：新的 Parameter 实例。

创建 PoseState 实例（create_pose_state）​

def create_pose_state() -> PoseState

创建一个 PoseState 实例。

返回值

类型描述
PoseStatePoseState：新的位姿状态对象。