Python API 参考 - G1 机器

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

核心机器人控制

Galbot 人形机器人的主机器人控制界面。

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

获取控制器权限

def acquire_controller(controller_name: str) -> ControlStatus

获取硬件权限。

指定控制器取得硬件的所有权。与release_controller 相反。控制器仍必须启动才能开始执行。

参数

名称	类型	默认值	描述
`controller_name`	str	需要传参	要切换到的控制器名称

返回值

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

检查轨迹执行状态

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

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

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

参数

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

返回值

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

清除末端执行器命令

def clear_end_effector_command() -> ControlStatus

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

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

返回值

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

销毁

def destroy() -> None

清理系统资源。

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

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

执行关节轨迹

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

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

执行由具有关联关节位置、速度和计时信息的航点组成的轨迹。轨迹控制器在路点之间进行插值以生成平滑的运动。

参数

名称	类型	默认值	描述
`trajectory`	Trajectory	需要传参	批量轨迹点
`is_blocking`	bool	`True`	是否阻塞等待完成

返回值

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

warning

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

获取当前控制器

def get_active_controller(group_name: str) -> str

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

参数

名称	类型	默认值	描述
`group_name`	str	需要传参	要停止的控制器组名称

返回值

类型	描述
str	当前活动控制器的名称字符串。

获取电池管理信息

def get_bms_information() -> dict

获取BMS（电池管理系统）信息。

返回值

类型	描述
dict	共享指针，包含电池信息

获取相机内参

def get_camera_intrinsic(camera_id: SensorType) -> dict

获取相机内参。

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

参数

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

返回值

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

note

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

获取深度图像数据

def get_depth_data(camera_id: SensorType) -> dict

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

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

参数

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

返回值

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

note

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

note

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

获取设备信息

def get_device_information() -> dict

获取设备信息。

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

返回值

类型	描述
dict	返回设备信息的共享指针，包含型号、序列号、固件版本、硬件版本和厂商信息。若读取失败，返回空指针。

获取灵巧手状态

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

获取当前灵巧手状态。

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

参数

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

返回值

类型	描述
Any	DexhandState（灵巧手状态）

获取力传感器数据

def get_force_sensor_data(sensor_type: GalbotOneFoxtrotSensor) -> dict

获取力/扭矩传感器数据。

从指定的力/扭矩传感器检索最新测量值。这些传感器通常安装在手腕或末端执行器上，用于接触力监测和合规性控制。

参数

名称	类型	默认值	描述
`sensor_type`	GalbotOneFoxtrotSensor	需要传参	力传感器类型

返回值

类型	描述
dict	返回力传感器数据的共享指针，包含力向量 `[fx, fy, fz]`、力矩向量 `[tx, ty, tz]` 以及时间戳。若传感器未启用或读取失败，返回空指针。

note

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

获取坐标系名称

def get_frame_names() -> list[str]

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

返回值

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

获取夹爪状态

def get_gripper_state(end_effector: str) -> GripperState

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

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

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

参数

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

返回值

类型	描述
GripperState	返回夹爪状态的共享指针；若读取失败，返回空指针。

获取IMU数据

def get_imu_data(sensor_id: SensorType) -> dict

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

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

参数

名称	类型	默认值	描述
`sensor_id`	SensorType	需要传参	传感器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）为单位。

获取关节组名称

def get_joint_group_names() -> list[str]

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

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

返回值

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

获取关节名称

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

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

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

参数

名称	类型	默认值	描述
`only_active_joint`	bool	`True`	是否仅返回主动关节
`joint_groups`	Sequence[str]	`[]`	关节组列表

返回值

类型	描述
list[str]	按运动学链顺序排列的关节名称向量

获取关节位置

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

按组名称获取当前关节位置。

检索指定组中关节的当前角度位置。返回的向量顺序与 get_joint_names() 的关节顺序匹配。

参数

名称	类型	默认值	描述
`joint_groups`	Sequence[str]	需要传参	关节组列表
`joint_names`	Sequence[str]	`[]`	关节名称列表

返回值

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

获取关节状态

def get_joint_states(
    joint_group_vec: Sequence[str],
    joint_names_vec: Sequence[str] = []
) -> list[JointState]

通过组名称获取实时关节状态。

检索指定关节的综合状态信息，包括位置、速度、加速度、力（扭矩）和其他反馈数据。

参数

名称	类型	默认值	描述
`joint_group_vec`	Sequence[str]	需要传参	关节组向量
`joint_names_vec`	Sequence[str]	`[]`	关节名称向量

返回值

类型	描述
list[JointState]	结构向量，包含每个关节的当前状态

获取激光雷达数据

def get_lidar_data(sensor_id: SensorType) -> dict

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

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

参数

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

返回值

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

note

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

获取日志信息

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

获取日志信息。

参数

名称	类型	默认值	描述
`timewindow_s`	SupportsInt	需要传参	时间窗口（秒）
`log_level`	LogLevel	需要传参	日志级别

返回值

类型	描述
dict	共享指针，包含日志信息

获取里程计数据

def get_odom() -> dict

获取机器人里程信息。

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

返回值

类型	描述
dict	返回里程计数据的共享指针，包含位置、姿态、线速度、角速度与时间戳。若里程计不可用，返回空指针。

获取RGB图像数据

def get_rgb_data(camera_id: SensorType) -> dict

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

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

参数

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

返回值

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

note

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

获取传感器外参

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

获取传感器外参。

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

参数

名称	类型	默认值	描述
`sensor_id`	SensorType	需要传参	传感器ID
`reference_frame`	str	`'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 启用。

获取吸盘状态

def get_suction_cup_state(end_effector: str) -> SuctionCupState

获取当前吸盘状态。

检索指定吸盘的当前状态，包括激活状态和真空压力测量。

参数

名称	类型	默认值	描述
`end_effector`	str	需要传参	吸盘末端执行器

返回值

类型	描述
SuctionCupState	返回吸盘状态的共享指针；若读取失败，返回空指针。

获取坐标变换

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

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

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

参数

名称	类型	默认值	描述
`target_frame`	str	需要传参	目标坐标系
`source_frame`	str	需要传参	源坐标系
`timestamp_ns`	SupportsInt	`0`	时间戳（纳秒）
`timeout_ms`	SupportsInt	`100`	超时时间（毫秒）

返回值

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

获取超声波数据

def get_ultrasonic_data(ultrasonic_type: UltrasonicType) -> dict

从指定的超声波传感器获取距离测量值。

从超声波距离传感器之一检索最新的距离测量值。机器人通常在其周边布置有多个超声波传感器。

参数

名称	类型	默认值	描述
`ultrasonic_type`	UltrasonicType	需要传参	超声波传感器类型

返回值

类型	描述
dict	返回超声波测距数据的共享指针（单位：米）；若传感器未启用或读取失败，返回空指针。

note

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

获取音量

def get_volume() -> float

获取当前系统全局卷值。

返回值

类型	描述
float	float：返回当前音量值，范围为 0.0 到 100.0

获取 WBC 末端执行器位姿

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]` 当失败或缺少键时，可能返回空条目或部分数据。

初始化

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

初始化机器人控制系统。

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

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

参数

名称	类型	默认值	描述
`enable_sensor_set`	Set[SensorType]	`...`	要启用的传感器集合，如果为空，则启用默认的传感器集合，仅指定所需传感器可减少启动时间和资源占用

返回值

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

检查是否运行中

def is_running() -> bool

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

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

返回值

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

发布目标

def publish_target(target: SingoriXTarget) -> ControlStatus

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

参数

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

返回值

类型	描述
ControlStatus	无返回值

释放控制器权限

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

释放硬件权限。

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

参数

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

返回值

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

重新加载控制器

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

重新加载控制器。

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

参数

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

返回值

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

请求关机

def request_shutdown() -> None

请求系统关闭。

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

请求目标

def request_target(target: SingoriXTarget) -> ErrorInfo

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

参数

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

返回值

类型	描述
ErrorInfo	无返回值

设置底盘姿态

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

设置移动基础位姿命令。

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

参数

名称	类型	默认值	描述
`base_pose`	Pose	需要传参	底盘目标姿态
`is_blocking`	bool	`True`	是否阻塞等待完成
`timeout_s`	SupportsFloat	`15.0`	超时时间（秒）。

返回值

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

设置底盘姿态

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

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

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

参数

名称	类型	默认值	描述
`x`	SupportsFloat	需要传参	X坐标（米）
`y`	SupportsFloat	需要传参	Y坐标（米）
`yaw`	SupportsFloat	需要传参	航向角（弧度）
`frame_id`	str	`'odom'`	坐标系ID
`reference_frame_id`	str	`'odom'`	参考坐标系ID
`is_blocking`	bool	`True`	是否阻塞等待完成
`timeout_s`	SupportsFloat	`15.0`	超时时间（秒）。

返回值

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

设置底盘姿态

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 协调到达时间时，请使用此重载。

参数

名称	类型	默认值	描述
`x`	SupportsFloat	需要传参	X坐标（米）
`y`	SupportsFloat	需要传参	Y坐标（米）
`yaw`	SupportsFloat	需要传参	航向角（弧度）
`frame_id`	str	需要传参	坐标系ID
`reference_frame_id`	str	需要传参	参考坐标系ID
`time_from_start_s`	SupportsFloat	需要传参	预期到达时间（秒）
`is_blocking`	bool	`True`	是否阻塞等待完成
`timeout_s`	SupportsFloat	`15.0`	超时时间（秒）。

返回值

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

设置底盘速度

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

设置移动基础速度命令。

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

参数

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

返回值

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

设置灵巧手命令

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

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

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

参数

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

返回值

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

设置末端执行器命令

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

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

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

参数

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

返回值

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

设置夹爪命令

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

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

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

参数

名称	类型	默认值	描述
`end_effector`	str	需要传参	要控制的夹爪关节组名称（例如 `left_gripper`、`right_gripper`）。
`width_m`	SupportsFloat	需要传参	目标开口宽度（米）
`velocity_mps`	SupportsFloat	`0.03`	夹爪运动速度（米/秒）
`effort`	SupportsFloat	`30`	最大夹持力
`is_blocking`	bool	`True`	是否阻塞等待完成

返回值

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

设置关节命令

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

设置低级关节命令以进行高频流控制。

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

此 API 不会从当前/开始位置插值到第一个目标。控制器尽快将关节驱动到每个命令目标以满足 time_from_start_s （预期到达时间）。

对于标准关节（头、腿、手臂），当前版本仅JointCommand::position有效；

目前忽略速度、加速度和作用力。对于夹具关节，位置字段代表夹具宽度，并且速度和作用力字段均受到支持且有效。夹具运动使用指定速度和 time_from_start_s 之间较慢的一个。因此，在设置夹爪速度时，可以将time_from_start_s设置为0（最快到达），夹爪将直接由指定的速度控制。

参数

名称	类型	默认值	描述
`joint_commands`	Sequence[JointCommand]	需要传参	关节命令列表
`joint_groups`	Sequence[str]	`[]`	要控制的关节组，支持的组：legs（腿部）、head（头部）、left_arm（左臂）、right_arm（右臂）、gripper（夹爪）、suction_cup（吸盘）
`joint_names`	Sequence[str]	`[]`	关节名称列表
`time_from_start_s`	SupportsFloat	`10.0`	预期到达时间（秒）

返回值

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

warning

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

批量设置关节命令

def set_joint_commands_batch(trajectory: Trajectory) -> ControlStatus

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

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

参数

名称	类型	默认值	描述
`trajectory`	Trajectory	需要传参	包含带关节命令的路点的轨迹数据结构。每个 TrajectoryPoint 包含时间戳和关节命令

返回值

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

设置关节位置

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_positions`	list[float]	需要传参	目标关节位置
`joint_groups`	Sequence[str]	`[]`	要控制的关节组名称，支持的组："legs"（腿部）、"head"（头部）、"left_arm"（左臂）、"right_arm"（右臂），空向量表示所有支持的组
`joint_names`	Sequence[str]	`[]`	关节名称列表
`is_blocking`	bool	`True`	是否阻塞等待完成
`speed_rad_s`	SupportsFloat	`0.2`	最大运动速度（弧度/秒）
`timeout_s`	SupportsFloat	`15.0`	超时时间（秒）。

返回值

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

warning

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

设置吸盘命令

def set_suction_cup_command(end_effector: str, activate: bool) -> ControlStatus

控制吸盘激活状态。

激活或停用指定的吸盘末端执行器。

参数

名称	类型	默认值	描述
`end_effector`	str	需要传参	吸盘末端执行器
`activate`	bool	需要传参	是否激活吸盘

返回值

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

设置音量

def set_volume(volume: SupportsFloat) -> bool

设置系统全局音量值。

参数

名称	类型	默认值	描述
`volume`	SupportsFloat	需要传参	音量值（0-100）

返回值

类型	描述
bool	返回音量设置结果：成功为 `true`，失败为 `false`。

启动控制器

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

开始控制器执行。

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

参数

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

返回值

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

启动麦克风流输入

def start_microphone_stream_input(
    callback: Callable,
    chunk_size: SupportsInt = 2560,
    use_raw_audio: bool = False
) -> str

启动麦克风流音频输入。

参数

名称	类型	默认值	描述
`callback`	Callable	需要传参	音频数据回调函数
`chunk_size`	SupportsInt	`2560`	每个音频块的样本数
`use_raw_audio`	bool	`False`	是否使用原始音频。 - false: 使用处理后的音频（默认） - true: 输出原始 PCM 音频数据（目前不支持动态配置）

返回值

类型	描述
str	str：用于标识音频输入流的流 ID。

停止音频流输出

def stop_audio_stream_output(stream_id: str = '') -> None

停止指定音频输出流或所有活动音频输出流的播放。

参数

名称	类型	默认值	描述
`stream_id`	str	`''`	输出流ID

紧急停止底盘

def stop_base() -> ControlStatus

紧急停止移动底座运动。

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

返回值

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

停止控制器

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

停止控制器执行。

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

参数

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

返回值

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

停止麦克风流输入

def stop_microphone_stream_input(stream_id: str = '') -> None

停止指定的麦克风流式音频输入。

参数

名称	类型	默认值	描述
`stream_id`	str	`''`	输出流ID

停止轨迹执行

def stop_trajectory_execution() -> ControlStatus

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

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

返回值

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

切换控制器

def switch_controller(controller_name: str) -> ControlStatus

切换主动控制器策略。

将硬件控制转变为新策略。操作顺序：停止（旧）->释放（旧）->获取（新）->启动（新）。

参数

名称	类型	默认值	描述
`controller_name`	str	需要传参	要切换到的控制器名称

返回值

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

等待关机

def wait_for_shutdown() -> None

阻塞直到关闭完成。

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

note

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

写入音频流输出

def write_audio_stream_output(audio_chunk: str, stream_id: str = '') -> bool

将PCM格式的音频数据块写入音频输出流以进行实时播放。

参数

名称	类型	默认值	描述
`audio_chunk`	str	需要传参	音频数据块
`stream_id`	str	`''`	输出流ID

返回值

类型	描述
bool	返回操作结果：音频写入并成功下发播放任务为 `true`，失败为 `false`。

全身与底盘归零

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_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]	-

全身与底盘归零

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_id`	str	`'odom'`	坐标系ID
`reference_frame_id`	str	`'odom'`	参考坐标系ID
`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]	-

运动规划与执行

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

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

添加障碍物

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_id`	str	需要传参	障碍物唯一标识符（场景中不得重复），后续可用于删除或更新。
`obstacle_type`	str	需要传参	障碍物几何类型
`pose`	list[float]	需要传参	障碍物位姿（位置 + 四元数）
`scale`	list[float]	`[0.0, 0.0, 0.0]`	几何尺寸（米）： - box: [长度, 宽度, 高度] - sphere: [半径, -, -] - cylinder: [半径,高度,-] - mesh/point_cloud: 缩放因子
`key`	str	`''`	类型特定数据： - mesh/point_cloud: 文件路径（例如 "/path/to/model.stl"） - depth_image: 相机源数据 - robot_state: 机器人状态数据
`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	运动状态：- 成功：障碍物添加成功 - 无效输入：无效的障碍物ID（重复）、类型或参数 - 故障：处理几何形状或添加到场景失败

note

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

note

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

note

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

warning

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

附加目标对象

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_id`	str	需要传参	要移除的障碍物ID
`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	运动状态：SUCCESS（成功）、INVALID_INPUT（无效输入）或 FAULT（故障）

note

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

note

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

note

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

warning

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

附加工具

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

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

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

参数

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

返回值

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

note

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

note

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

warning

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

检查碰撞

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

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

检查自身碰撞和与环境障碍物的碰撞，支持批量处理。

因此，如果需要 Motion 考虑环境障碍物（包括点云），必须显式加载障碍物地图/对象（例如，obstacle_type = point_cloud 且在 key 中提供文件路径）。注意：将实时感知集成到 galbotMotion 是未来计划，目前内部验证有限。验证给定机器人配置是否无碰撞。

参数

名称	类型	默认值	描述
`start`	Sequence[RobotStates]	需要传参	起始机器人状态
`enable_collision_check`	bool	`True`	是否启用碰撞检查
`params`	Parameter	`...`	额外参数

返回值

类型	描述
tuple[MotionStatus, list[bool]]	若检测到碰撞则返回 `true`，否则返回 `false`。

note

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

note

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

note

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

清空障碍物

def clear_obstacle() -> MotionStatus

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

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

返回值

类型	描述
MotionStatus	-

note

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

note

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

分离目标对象

def detach_target_object(obstacle_id: str) -> MotionStatus

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

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

参数

名称	类型	默认值	描述
`obstacle_id`	str	需要传参	-

返回值

类型	描述
MotionStatus	-

note

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

分离工具

def detach_tool(chain: str) -> MotionStatus

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

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

参数

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

返回值

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

note

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

正向运动学

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

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

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

参数

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

返回值

类型	描述
tuple[MotionStatus, list[float]]	位姿：目标帧的计算位姿

note

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

warning

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

基于状态的正向运动学

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_frame`	str	需要传参	目标坐标系
`reference_robot_states`	RobotStates	`None`	参考机器人起始状态
`reference_frame`	str	`'base_link'`	参考坐标系
`params`	Parameter	`...`	额外参数

返回值

类型	描述
tuple[MotionStatus, list[float]]	位姿：目标帧的计算位姿

note

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

获取已构建障碍物列表

def get_built_obstacles_list() -> list[str]

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

返回值

类型	描述
list[str]	-

获取链关节状态

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

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

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

返回值

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

note

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

获取末端执行器姿态

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

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

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

参数

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

返回值

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

note

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

warning

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

获取指定链末端执行器姿态

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_name`	str	需要传参	链名称
`frame_id`	str	`'EndEffector'`	坐标系ID
`reference_frame`	str	`'base_link'`	参考坐标系

返回值

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

note

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

获取连杆名称

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

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

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

参数

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

返回值

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

note

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

note

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

获取运动规划配置

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

获取当前运动规划配置。

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

返回值

类型	描述
tuple[MotionStatus, MotionPlanConfig]	-

note

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

获取机器人状态

def get_robot_states() -> RobotStates

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

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

返回值

类型	描述
RobotStates	-

note

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

note

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

获取支持的链

def get_supported_chains() -> set[str]

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

返回值

类型	描述
set[str]	-

获取支持的末端执行器坐标系

def get_supported_ee_frames() -> set[str]

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

返回值

类型	描述
set[str]	-

获取支持的坐标系

def get_supported_frames() -> set[str]

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

返回值

类型	描述
set[str]	-

获取支持的连杆

def get_supported_links() -> set[str]

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

返回值

类型	描述
set[str]	-

获取支持的障碍物类型

def get_supported_obstacle_types() -> set[str]

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

返回值

类型	描述
set[str]	-

获取支持的工具列表

def get_supported_tool_list() -> set[str]

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

返回值

类型	描述
set[str]	-

初始化

def init() -> bool

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

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

返回值

类型	描述
bool	-

note

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

warning

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

逆向运动学

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_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]]]	字典：关节名称到其计算位置的映射。

note

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

note

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

warning

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

基于状态的逆向运动学

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_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]]]	字典：关节名称到其计算位置的映射。

note

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

轨迹规划

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]]]]

规划单个运动链的轨迹。

参数

名称	类型	默认值	描述
`target`	RobotStates	需要传参	目标位姿
`start`	RobotStates	`None`	起始机器人状态
`reference_robot_states`	RobotStates	`None`	参考机器人起始状态
`enable_collision_check`	bool	`True`	是否启用碰撞检查
`params`	Parameter	`...`	额外参数

返回值

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

note

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

note

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

note

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

warning

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

多路点轨迹规划

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]]]]

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

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

参数

名称	类型	默认值	描述
`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]]]]	运动规划成功返回 `true`，失败返回 `false`。

note

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

note

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

多路点轨迹规划

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]]]]

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

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

参数

名称	类型	默认值	描述
`targets`	dict]]	需要传参	多路点目标位姿字典（每个运动链对应一个路点序列）
`start`	Sequence[RobotStates]	`[]`	起始机器人状态
`reference_robot_states`	RobotStates	`None`	参考机器人起始状态
`enable_collision_check`	bool	`True`	是否启用碰撞检查
`params`	Parameter	`...`	额外参数

返回值

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

note

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

note

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

移动全身关节到零位

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_blocking`	bool	`True`	-
`leg_head_speed_rad_s`	SupportsFloat	`0.2`	-
`leg_head_timeout_s`	SupportsFloat	`15.0`	-
`params`	Parameter	`...`	-

返回值

类型	描述
MotionStatus	-

移除障碍物

def remove_obstacle(obstacle_id: str) -> MotionStatus

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

参数

名称	类型	默认值	描述
`obstacle_id`	str	需要传参	-

返回值

类型	描述
MotionStatus	-

note

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

设置末端执行器姿态

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、规划轨迹并可选择执行运动。支持阻塞（等待完成）和非阻塞（立即返回）模式。

参数

名称	类型	默认值	描述
`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	运动规划成功返回 `true`，失败返回 `false`。

note

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

note

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

warning

阻塞调用将暂停执行直到运动完成；建议在非阻塞模式下使用进度监控。

设置运动规划配置

def set_motion_plan_config(config: MotionPlanConfig) -> MotionStatus

设置全局运动规划配置。

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

参数

名称	类型	默认值	描述
`config`	MotionPlanConfig	需要传参	-

返回值

类型	描述
MotionStatus	-

note

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

note

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

状态转字符串

def status_to_string(status: MotionStatus) -> str

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

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

参数

名称	类型	默认值	描述
`status`	MotionStatus	需要传参	-

返回值

类型	描述
str	-

note

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

移动导航

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

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

检查目标到达

def check_goal_arrival() -> bool

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

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

返回值

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

note

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

note

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

note

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

检查路径可达性

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

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

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

参数

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

返回值

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

note

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

note

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

note

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

获取当前姿态

def get_current_pose() -> list[float]

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

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

返回值

类型	描述
list[float]	结构包含以下字段：- x: X坐标（米，地图坐标系） - y: Y坐标（米，地图坐标系） - theta: 方向（弧度，地图坐标系，逆时针从 x 轴算起）

note

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

note

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

获取导航状态

def get_navigation_status() -> NavigationTaskStatus

获取当前导航任务状态。

返回导航系统报告的最新任务状态（未知、正在运行、成功或失败）。在运行非阻塞导航时使用此功能可以轮询状态并在失败或超时时及时退出错误逻辑，从而避免死锁或无限期等待。

返回值

类型	描述
NavigationTaskStatus	导航任务状态当前任务状态。如果尚无状态则为 UNKNOWN；导航时为 RUNNING；任务完成时为 SUCCESS 或 FAILED。

note

在非阻塞导航中很有用：在 get_navigation_status() 上循环检查进度。

初始化

def init() -> bool

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

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

返回值

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

note

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

note

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

warning

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

检查是否已定位

def is_localized() -> bool

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

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

返回值

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

note

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

note

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

直线移动到目标

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

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

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

参数

名称	类型	默认值	描述
`goal_pose`	numpy.ArrayLike	需要传参	相对于当前机器人底座帧的目标位姿。包含： - x: 前后位移（米） - y: 左右位移（米） - theta: 转向角度（弧度）
`is_blocking`	bool	`True`	执行模式标志。 - true (阻塞): 阻塞直到运动完成、失败或超时 - false (非阻塞): 发送导航命令后立即返回
`timeout`	SupportsFloat	`8`	求解超时（毫秒）

返回值

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

note

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

note

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

note

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

warning

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

warning

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

导航到目标

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

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

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

参数

名称	类型	默认值	描述
`goal_pose`	numpy.ArrayLike	需要传参	目标位姿（地图坐标系）
`enable_collision_check`	bool	`True`	是否启用碰撞检查
`is_blocking`	bool	`False`	执行模式标志。 - true (阻塞): 阻塞直到到达目标或失败 - false (非阻塞): 发送导航命令后立即返回
`timeout`	SupportsFloat	`8`	阻塞模式下的最大等待时间（秒），默认值：8.0 秒，仅在 is_blocking 为 true 时相关，如果在时间内未到达目标，则返回超时状态
`omni_plan`	bool	`True`	运动规划模式标志。 - true: 启用全向运动规划（各向同性移动） - false: 使用有限方向的运动规划

返回值

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

note

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

note

对于阻塞模式，调用线程将阻塞直到导航完成或超时。

note

实际导航时间可能超过超时值（阻塞模式下）。

warning

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

重定位

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

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

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

参数

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

返回值

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

note

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

note

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

停止导航

def stop_navigation() -> tuple

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

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

返回值

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

note

可在导航期间随时调用。

note

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

note

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

感知模块接口

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

G1平台专用：get_instance(MachineType::S1)会抛出std::runtime_error。

获取模块的最新缓存结果

def get_latest_result(module: PerceptionModule) -> tuple

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

参数

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

返回值

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

初始化感知模块并加载模型

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

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

参数

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

返回值

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

为指定模块运行一次推理

def run_once(module: PerceptionModule) -> bool

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

参数

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

返回值

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

note

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

等待模块产生新结果或超时

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

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

参数

名称	类型	默认值	描述
`module`	PerceptionModule	需要传参	感知模块。
`timeout_s`	SupportsFloat	`5.0`	超时时间（秒）。

返回值

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

类型与枚举

音频数据

音频数据结构用于封装音频数据。

Member Variables

Name	Type	Description
`data`	list[int]	二进制数据包，具体格式由 format 字段指定。 - "pcm" 格式：PCM 音频数据（小端序，16 位整数） - "json" 格式：UTF-8 编码的 JSON 文本
`format`	str	音频数据格式说明，例如："pcm": 采样率 16000 Hz，位深度 16 bit，单声道；"json": UTF-8 编码的 JSON 文本
`header`	Header	消息头
`type`	str	音频数据类型标识符。 - "waken_up": 唤醒事件（格式为 JSON） - "speech": 语音数据（格式为 PCM）

碰撞检查选项

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

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

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

def get_disable_env_collision_check() -> bool

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

返回值

类型	描述
bool	-

检查自碰撞检测是否禁用

def get_disable_self_collision_check() -> bool

检查自碰撞检测是否禁用

返回值

类型	描述
bool	-

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

def print() -> None

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

启用或禁用环境碰撞检测

def set_disable_env_collision_check(disable: bool) -> None

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

参数

名称	类型	默认值	描述
`disable`	bool	需要传参	-

warning

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

启用或禁用自碰撞检测

def set_disable_self_collision_check(disable: bool) -> None

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

参数

名称	类型	默认值	描述
`disable`	bool	需要传参	-

warning

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

控制状态

控制命令执行状态枚举。

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

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

深度数据

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

Member Variables

Name	Type	Description
`data`	list[int]	包含原始或压缩深度图像数据的二进制数据块
`depth_scale`	int	深度缩放因子，用于将像素值转换为实际深度（米），真实深度 = 像素值 / depth_scale，例如：depth_scale = 1000 表示像素值单位为毫米
`format`	str	指定深度编码和压缩格式，例如："16UC1; compressedDepth png"（16 位无符号整数，PNG 压缩深度）
`header`	Header	包含采集时间戳和相机坐标系
`height`	int	深度图像的行数
`width`	int	深度图像的列数

检测与分割结果

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

Member Variables

Name	Type	Description
`bbox`	tuple[int, int, int, int]	Bounding box as (x, y, width, height)
`class_index`	int	Class index
`class_name`	str	Class name
`confidence`	float	Confidence score
`keypoints`	list[tuple[float, float]]	Keypoints as list of (x, y) tuples

检测结果

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

Member Variables

Name	Type	Description
`bounding_boxes`	list[tuple[int, int, int, int]]	Bounding boxes as list of (x, y, width, height)
`class_indices`	list[int]	List of class indices
`class_names`	list[str]	List of class names
`confidences`	list[float]	List of confidences
`detection_results`	list[DetectionAndSegmentationResult]	List of DetectionAndSegmentationResult
`grasp_pose_result`	list[list[float]]	Grasp pose results
`instance_mask`	Any	Instance mask as numpy array (HxW or HxWxC), or None if empty
`ocr_string`	list[str]	OCR results
`point_clouds`	list	Point clouds as list of Nx3 numpy arrays
`running_info`	str	Running info string
`sensor_name`	str	Sensor name
`target_point_poses`	list[numpy.NDArray[numpy.float32]"]]	4x4 poses from perception proto field target_point_poses (same buffer as target_poses here)
`target_poses`	list[numpy.NDArray[numpy.float32]"]]	List of 4x4 target pose matrices (C++ targetPoses; perception proto target_point_poses fills this)
`timestamp_ns`	int	Timestamp in nanoseconds

清空结果

def clear() -> None

清空所有存储的结果。

获取结果信息

def get_result_info() -> str

获取结果摘要字符串。

返回值

类型	描述
str	-

灵巧手状态

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

Member Variables

Name	Type	Description
`force_sensor_map`	dict[str, EffortInfo]	命名力传感器映射（Sharpa；其他为空）
`joint_state`	JointStateMessage	灵巧手关节状态消息
`timestamp_ns`	int	状态时间戳（自纪元以来的纳秒数）

灵巧手类型

SDK 使用此枚举将灵巧手命令和状态查询路由到正确的实现。Inspire 和 BrainCo 灵巧手共享标准关节命令/状态路径。Sharpa 灵巧手使用专用的 22 关节话题接口；完整状态在 DexhandState 中返回（包括力传感器）。

Enum Value	Description
`BRAINCO`	BrainCo 灵巧手
`INSPIRE`	Inspire 灵巧手
`SHARPA`	Sharpa 灵巧手

力矩信息

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

Member Variables

Name	Type	Description
`force`	Vector3	力向量（牛顿）：[fx, fy, fz] - fx: X 方向力 - fy: Y 方向力 - fz: Z 方向力
`timestamp_ns`	int	测量时间戳（自纪元以来的纳秒数）
`torque`	Vector3	力矩向量（牛顿·米）：[tx, ty, tz] - tx: 绕 X 轴力矩 - ty: 绕 Y 轴力矩 - tz: 绕 Z 轴力矩

错误

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

Member Variables

Name	Type	Description
`commpent`	str	组件
`description`	str	错误描述
`error_code`	int	用于程序化错误处理的数值错误代码

错误信息

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

Member Variables

Name	Type	Description
`error_vec`	list[Error]	误差向量
`timestamp_ns`	int	收集错误的时间戳（自纪元以来的纳秒数）

力数据

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

Member Variables

Name	Type	Description
`force`	Vector3	力
`timestamp_ns`	int	测量时间戳（自纪元以来的纳秒数）
`torque`	Vector3	力矩

坐标系

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

Member Variables

Name	Type	Description
`body_frame_id`	str	Body frame id
`header`	Header	Message header
`pose`	Pose	None
`reference_frame_id`	str	Reference frame id
`twist`	Twist	None
`wrench`	Wrench	None

G1控制器名称

G1 控制器名称的字符串常量。

定义G1机器人型号支持的控制器名称。

Enum Value	Description
`CHASSIS_POSE_CTRL`	底盘姿态控制器
`CHASSIS_TWIST_CTRL`	底盘速度控制器
`CONTROLLER_NAME_NUM`	控制器名称数量
`HEAD_PVT_BYPASS_CTRL`	头部位置-速度-力矩旁路控制器
`HEAD_PVT_CTRL`	头部位置-速度-力矩控制器
`LEFT_ARM_PVT_BYPASS_CTRL`	左臂位置-速度-力矩旁路控制器
`LEFT_ARM_PVT_CTRL`	左臂位置-速度-力矩控制器
`LEFT_DEXHAND_CTRL`	左手灵巧手控制器
`LEFT_GRIPPER_CTRL`	左夹爪控制器
`LEG_PVT_BYPASS_CTRL`	腿部位置-速度-力矩旁路控制器
`LEG_PVT_CTRL`	腿部位置-速度-力矩控制器
`RIGHT_ARM_PVT_BYPASS_CTRL`	右臂位置-速度-力矩旁路控制器
`RIGHT_ARM_PVT_CTRL`	右臂位置-速度-力矩控制器
`RIGHT_DEXHAND_CTRL`	右手灵巧手控制器
`RIGHT_GRIPPER_CTRL`	右夹爪控制器

G1关节组

"关节组"是 SDK 的主要控制/规划单元，而非单个关节： - 运动一致控制：每个链/末端执行器组都会验证和执行命令 - 确定性命令排序：joint_groups 按组顺序扩展为具体的 joint_names - 组级行为：每个组都有自己的主动/被动属性和执行容忍度 推荐用法：在填充 API 参数（例如 joint_groups）时，使用此结构体中的常量。如果需要精确的关节名称，请在运行时通过 get_joint_names(true, {group_name}) 查询，而非硬编码。在同时接受 joint_groups 和 joint_names 的 API 中，joint_names 优先。

Enum Value	Description
`chassis`	底盘机构组（关节位置控制中为被动），默认关节：chassis_joint1 ... chassis_joint4，典型用途：底盘状态分组；底座运动应使用底座 API
`head`	头部 2 自由度链条，默认关节：head_joint1、head_joint2，典型用途：注视/相机朝向控制
`left_arm`	左臂 7 自由度链条，默认关节：left_arm_joint1 ... left_arm_joint7，典型用途：左臂 Reach/操作
`left_dexhand`	左手灵巧手组，默认关节：left_dexhand_joint1 ... left_dexhand_joint6，典型用途：多指灵巧操作（左）
`left_gripper`	左夹爪链条，默认关节：left_gripper_joint1，典型用途：左夹爪开合和夹持宽度控制
`left_suction_cup`	左吸盘末端执行器组，默认关节：left_suction_cup_joint1，典型用途：左臂真空拾取/放置
`leg`	腿部链条，默认关节：leg_joint1 ... leg_joint5，典型用途：下半身姿态/运动相关控制
`right_arm`	右臂 7 自由度链条，默认关节：right_arm_joint1 ... right_arm_joint7，典型用途：右臂 Reach/操作
`right_dexhand`	右手灵巧手组，默认关节：right_dexhand_joint1 ... right_dexhand_joint6，典型用途：多指灵巧操作（右）
`right_gripper`	右夹爪链条，默认关节：right_gripper_joint1，典型用途：右夹爪开合和夹持宽度控制
`right_suction_cup`	右吸盘末端执行器组，默认关节：right_suction_cup_joint1，典型用途：右臂真空拾取/放置

Galbot One Foxtrot 传感器类型

描述机器人手腕力传感器的力传感器枚举。

识别安装在机器人腕关节处的力/扭矩传感器，用于力控制操作和接触检测。

Enum Value	Description
`LEFT_WRIST_FORCE`	左腕力传感器
`RIGHT_WRIST_FORCE`	右腕力传感器

夹爪状态

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

Member Variables

Name	Type	Description
`effort`	float	力矩
`is_moving`	bool	运动标志（来自运动窗口），false 表示在配置的时间窗口内未检测到有效运动，true 表示检测到有效运动
`joint_positions`	list[float]	夹爪关节位置（弧度），通常0-0.04米
`timestamp_ns`	int	状态时间戳（自纪元以来的纳秒数）
`velocity`	float	速度
`width`	float	夹爪开口宽度（米），距离

关节组命令

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

Member Variables

Name	Type	Description
`joint_commands`	list[JointCommand]	Joint commands at this point
`time_from_start_s`	float	Time from trajectory start in seconds

消息头

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

Member Variables

Name	Type	Description
`frame_id`	str	标识数据所在的坐标系，例如："base_link"、"world"、"camera_optical_frame"、"lidar_link"、"map"
`timestamp_ns`	int	数据采集的时间戳（自纪元以来的纳秒数），记录数据被捕获或生成的时间

IK求解器配置

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

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

获取关节限制安全裕度

def get_col_aware_ik_joint_limit_bias() -> float

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

返回值

类型	描述
float	-

获取碰撞感知IK求解器超时

def get_col_aware_ik_timeout() -> float

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

返回值

类型	描述
float	-

检查是否启用碰撞检查日志

def get_enable_collision_check_log() -> bool

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

返回值

类型	描述
bool	-

获取方向误差容差

def get_rotation_eps() -> list[float]

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

返回值

类型	描述
list[float]	-

获取IK求解器种子生成策略

def get_seed_type() -> SeedType

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

返回值

类型	描述
SeedType	-

获取笛卡尔位置误差容差

def get_translation_eps() -> list[float]

获取平移收敛容差（米）

返回值

类型	描述
list[float]	-

打印IK求解器配置到标准输出

def print() -> None

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

设置关节位置限制的安全裕度

def set_col_aware_ik_joint_limit_bias(bias: SupportsFloat) -> None

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

参数

名称	类型	默认值	描述
`bias`	SupportsFloat	需要传参	-

note

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

设置碰撞感知IK求解器超时

def set_col_aware_ik_timeout(timeout: SupportsFloat) -> None

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

参数

名称	类型	默认值	描述
`timeout`	SupportsFloat	需要传参	-

note

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

启用或禁用碰撞检测日志

def set_enable_collision_check_log(enable: bool) -> None

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

参数

名称	类型	默认值	描述
`enable`	bool	需要传参	-

note

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

设置方向误差容差

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

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

参数

名称	类型	默认值	描述
`eps`	list[float]	需要传参	-

note

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

设置种子类型

def set_seed_type(type: SeedType) -> None

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

参数

名称	类型	默认值	描述
`type`	SeedType	需要传参	-

设置笛卡尔位置误差容差

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

设置平移收敛容差（米）

参数

名称	类型	默认值	描述
`eps`	list[float]	需要传参	-

note

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

IMU数据

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

Member Variables

Name	Type	Description
`accel`	Vector3	加速度
`gyro`	Vector3	陀螺仪数据
`magnet`	Vector3	磁力计数据
`timestamp_ns`	int	测量时间戳（自纪元以来的纳秒数）

关节命令

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

Member Variables

Name	Type	Description
`acceleration`	float	加速度
`effort`	float	期望的关节力矩/作用力（牛顿米）
`position`	float	期望的关节位置（弧度）
`velocity`	float	期望的关节速度（弧度/秒）

关节状态

表示单个机器人关节的完整实时状态，包括运动学量（位置、速度、加速度）和动态量（扭矩/作用力和电机电流）。

Member Variables

Name	Type	Description
`acceleration`	float	-
`current`	float	-
`effort`	float	-
`position`	float	-
`velocity`	float	-

关节状态消息

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

Member Variables

Name	Type	Description
`joint_state_vec`	list[JointState]	关节状态向量
`timestamp_ns`	int	采集时间戳（自纪元以来的纳秒数）

关节状态

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

Member Variables

Name	Type	Description
`joint_positions`	list[float]	-

获取类型

def get_type() -> RobotStatesType

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

返回值

类型	描述
RobotStatesType	-

设置关节

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

设置指定索引的关节值

参数

名称	类型	默认值	描述
`index`	SupportsInt	需要传参	-
`val`	SupportsInt	需要传参	-

note

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

warning

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

设置关节位置

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

设置所有关节位置

参数

名称	类型	默认值	描述
`joints`	list[float]	需要传参	-

note

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

运动学边界

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

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

获取下限加速度限制

def get_acc_lower_limit() -> list[float]

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

返回值

类型	描述
list[float]	-

获取上限加速度限制

def get_acc_upper_limit() -> list[float]

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

返回值

类型	描述
list[float]	-

获取运动链名称

def get_chain_name() -> str

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

返回值

类型	描述
str	-

获取下限加加速度限制

def get_jerk_lower_limit() -> list[float]

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

返回值

类型	描述
list[float]	-

获取上限加加速度限制

def get_jerk_upper_limit() -> list[float]

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

返回值

类型	描述
list[float]	-

获取下限位置限制

def get_lower_limit() -> list[float]

获取关节位置下限（rad）

返回值

类型	描述
list[float]	-

获取上限位置限制

def get_upper_limit() -> list[float]

获取关节位置上限（rad）

返回值

类型	描述
list[float]	-

获取下限速度限制

def get_vel_lower_limit() -> list[float]

获取速度下限（rad/s）

返回值

类型	描述
list[float]	-

获取上限速度限制

def get_vel_upper_limit() -> list[float]

获取速度上限（rad/s）

返回值

类型	描述
list[float]	-

打印输出

def print() -> None

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

设置下限加速度限制

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

设置加速度下限

参数

名称	类型	默认值	描述
`limits`	list[float]	需要传参	-

note

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

设置上限加速度限制

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

设置加速度上限

参数

名称	类型	默认值	描述
`limits`	list[float]	需要传参	-

note

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

设置运动链名称

def set_chain_name(name: str) -> None

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

参数

名称	类型	默认值	描述
`name`	str	需要传参	-

设置下限加加速度限制

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

设置加加速度下限

参数

名称	类型	默认值	描述
`limits`	list[float]	需要传参	-

note

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

设置上限加加速度限制

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

设置加加速度上限

参数

名称	类型	默认值	描述
`limits`	list[float]	需要传参	-

note

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

设置下限位置限制

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

设置关节位置下限

参数

名称	类型	默认值	描述
`limits`	list[float]	需要传参	-

note

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

设置上限位置限制

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

设置关节位置上限

参数

名称	类型	默认值	描述
`limits`	list[float]	需要传参	-

note

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

设置下限速度限制

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

设置速度下限

参数

名称	类型	默认值	描述
`limits`	list[float]	需要传参	-

note

双向关节通常为负值。

设置上限速度限制

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

设置速度上限

参数

名称	类型	默认值	描述
`limits`	list[float]	需要传参	-

note

双向关节通常为正值。

激光雷达数据

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

Member Variables

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

直线轨迹碰撞检测基元

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

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

获取圆柱体基元半径

def get_cylinder_prim_radius() -> float

获取圆柱基元半径（米）

返回值

类型	描述
float	-

获取直线检查基元类型

def get_line_check_primitive_type() -> PrimitiveType

获取直线检查基元类型

返回值

类型	描述
PrimitiveType	-

获取直线基元曲率

def get_line_prim_curvature() -> float

获取直线基元曲率

返回值

类型	描述
float	-

打印输出

def print() -> None

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

设置圆柱体基元半径

def set_cylinder_prim_radius(radius: SupportsFloat) -> None

设置圆柱基元半径（米）

参数

名称	类型	默认值	描述
`radius`	SupportsFloat	需要传参	-

note

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

note

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

设置直线检查基元类型

def set_line_check_primitive_type(type: PrimitiveType) -> None

设置直线检查基元类型

参数

名称	类型	默认值	描述
`type`	PrimitiveType	需要传参	-

note

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

设置直线基元曲率

def set_line_prim_curvature(curvature: SupportsFloat) -> None

设置直线基元曲率

参数

名称	类型	默认值	描述
`curvature`	SupportsFloat	需要传参	-

note

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

note

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

日志级别

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

Enum Value	Description
`CRITICAL`	严重日志
`DEBUG`	调试日志
`ERROR`	错误日志
`INFO`	信息日志
`TRACE`	跟踪日志
`WARN`	警告日志

机器类型

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

Enum Value	Description
`G1`	G1机器人
`S1`	S1机器人

运动规划配置

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

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

创建碰撞检查选项

def create_collision_check_option() -> CollisionCheckOption

创建碰撞检测选项并返回

返回值

类型	描述
CollisionCheckOption	-

创建IK求解器配置

def create_ik_solver_config() -> IKSolverConfig

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

返回值

类型	描述
IKSolverConfig	-

创建直线轨迹检查基元

def create_line_traj_check_primitive() -> LineTrajCheckPrimitive

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

返回值

类型	描述
LineTrajCheckPrimitive	-

创建采样器配置

def create_sampler_config() -> SamplerConfig

创建采样器配置并返回

返回值

类型	描述
SamplerConfig	-

创建轨迹可行性检查选项

def create_trajectory_feasibility_check_option() -> TrajectoryFeasibilityCheckOption

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

返回值

类型	描述
TrajectoryFeasibilityCheckOption	-

创建轨迹规划配置

def create_trajectory_plan_config() -> TrajectoryPlanConfig

创建轨迹规划配置并返回

返回值

类型	描述
TrajectoryPlanConfig	-

获取碰撞检查选项

def get_collision_check_option() -> CollisionCheckOption

获取碰撞检测选项

返回值

类型	描述
CollisionCheckOption	-

note

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

获取碰撞检查选项引用

def get_collision_check_option_ref() -> CollisionCheckOption

获取碰撞检测选项引用

返回值

类型	描述
CollisionCheckOption	-

获取可行性边界

def get_feasibility_boundary() -> list[KinematicsBoundary]

获取可行性边界约束

返回值

类型	描述
list[KinematicsBoundary]	-

获取硬关节约束

def get_hard_joint_limit() -> list[KinematicsBoundary]

获取硬关节位置限制边界

返回值

类型	描述
list[KinematicsBoundary]	-

获取IK关节约束

def get_ik_joint_limit() -> list[KinematicsBoundary]

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

返回值

类型	描述
list[KinematicsBoundary]	-

获取IK求解器配置

def get_ik_solver_config() -> IKSolverConfig

获取逆运动学求解器配置

返回值

类型	描述
IKSolverConfig	-

note

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

获取IK求解器配置引用

def get_ik_solver_config_ref() -> IKSolverConfig

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

返回值

类型	描述
IKSolverConfig	-

获取直线轨迹检查基元

def get_line_traj_check_primitive() -> LineTrajCheckPrimitive

获取直线轨迹检查基元

返回值

类型	描述
LineTrajCheckPrimitive	-

note

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

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

def get_line_traj_check_primitive_ref() -> LineTrajCheckPrimitive

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

返回值

类型	描述
LineTrajCheckPrimitive	-

获取是否恢复IK关节限制

def get_revert_ik_joint_limit() -> bool

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

返回值

类型	描述
bool	-

获取需要恢复IK关节限制的运动链

def get_revert_ik_joint_limit_chains() -> list[str]

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

返回值

类型	描述
list[str]	-

获取采样器配置

def get_sampler_config() -> SamplerConfig

获取采样器配置

返回值

类型	描述
SamplerConfig	-

note

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

获取采样器配置引用

def get_sampler_config_ref() -> SamplerConfig

获取采样器配置引用

返回值

类型	描述
SamplerConfig	-

获取采样关节约束

def get_sampler_joint_limit() -> list[KinematicsBoundary]

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

返回值

类型	描述
list[KinematicsBoundary]	-

获取轨迹可行性检查选项

def get_trajectory_feasibility_check_option() -> TrajectoryFeasibilityCheckOption

获取轨迹可行性检查选项

返回值

类型	描述
TrajectoryFeasibilityCheckOption	-

note

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

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

def get_trajectory_feasibility_check_option_ref() -> TrajectoryFeasibilityCheckOption

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

返回值

类型	描述
TrajectoryFeasibilityCheckOption	-

获取轨迹规划配置

def get_trajectory_plan_config() -> TrajectoryPlanConfig

获取轨迹规划配置

返回值

类型	描述
TrajectoryPlanConfig	-

note

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

获取轨迹规划配置引用

def get_trajectory_plan_config_ref() -> TrajectoryPlanConfig

获取轨迹规划配置引用

返回值

类型	描述
TrajectoryPlanConfig	-

获取更新时间

def get_update_time() -> int

获取更新时间参数

返回值

类型	描述
int	-

打印输出

def print() -> None

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

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

设置碰撞检查选项

def set_collision_check_option(option: CollisionCheckOption) -> None

设置碰撞检测选项

参数

名称	类型	默认值	描述
`option`	CollisionCheckOption	需要传参	-

设置可行性边界

def set_feasibility_boundary(boundary: Sequence[KinematicsBoundary]) -> None

设置可行性边界约束

参数

名称	类型	默认值	描述
`boundary`	Sequence[KinematicsBoundary]	需要传参	-

note

这些边界用于一般轨迹可行性检查。

设置硬关节约束

def set_hard_joint_limit(boundary: Sequence[KinematicsBoundary]) -> None

设置硬关节位置限制边界

参数

名称	类型	默认值	描述
`boundary`	Sequence[KinematicsBoundary]	需要传参	-

note

硬限制必须永不违反；通常对应于物理极限。

设置IK关节约束

def set_ik_joint_limit(boundary: Sequence[KinematicsBoundary]) -> None

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

参数

名称	类型	默认值	描述
`boundary`	Sequence[KinematicsBoundary]	需要传参	-

note

IK 限制可能比硬限制更紧以改善收敛性。

设置IK求解器配置

def set_ik_solver_config(config: IKSolverConfig) -> None

设置逆运动学求解器配置

参数

名称	类型	默认值	描述
`config`	IKSolverConfig	需要传参	-

设置直线轨迹检查基元

def set_line_traj_check_primitive(primitive: LineTrajCheckPrimitive) -> None

设置直线轨迹检查基元

参数

名称	类型	默认值	描述
`primitive`	LineTrajCheckPrimitive	需要传参	-

设置是否恢复IK关节限制

def set_revert_ik_joint_limit(flag: bool) -> None

设置是否恢复逆运动学关节限制

参数

名称	类型	默认值	描述
`flag`	bool	需要传参	-

note

用于通过暂时恢复极端限制来从受限配置中恢复。

设置需要恢复IK关节限制的运动链

def set_revert_ik_joint_limit_chains(chains: Sequence[str]) -> None

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

参数

名称	类型	默认值	描述
`chains`	Sequence[str]	需要传参	-

note

如果非空，自动启用 revert_ik_joint_limit 标志。

note

空向量禁用选择性恢复（适用于所有链）。

设置采样器配置

def set_sampler_config(config: SamplerConfig) -> None

设置采样器配置

参数

名称	类型	默认值	描述
`config`	SamplerConfig	需要传参	-

设置采样关节约束

def set_sampler_joint_limit(boundary: Sequence[KinematicsBoundary]) -> None

设置采样器关节位置限制边界

参数

名称	类型	默认值	描述
`boundary`	Sequence[KinematicsBoundary]	需要传参	-

note

采样限制定义了探索配置空间的有效范围。

设置轨迹可行性检查选项

def set_trajectory_feasibility_check_option(option: TrajectoryFeasibilityCheckOption) -> None

设置轨迹可行性检查选项

参数

名称	类型	默认值	描述
`option`	TrajectoryFeasibilityCheckOption	需要传参	-

设置轨迹规划配置

def set_trajectory_plan_config(config: TrajectoryPlanConfig) -> None

设置轨迹规划配置

参数

名称	类型	默认值	描述
`config`	TrajectoryPlanConfig	需要传参	-

设置更新时间

def set_update_time(t: SupportsInt) -> None

设置更新时间参数

参数

名称	类型	默认值	描述
`t`	SupportsInt	需要传参	-

note

用于配置版本控制和缓存失效。

运动状态

机器人动作执行状态枚举。

表示机器人运动命令的执行状态，包括轨迹跟随、位姿到达等运动规划操作。

Enum Value	Description
`COMM_DISCONNECTED`	通信断开
`DATA_FETCH_FAILED`	数据获取失败
`FAULT`	故障
`INIT_FAILED`	初始化失败
`INVALID_INPUT`	无效输入
`IN_PROGRESS`	进行中
`PUBLISH_FAIL`	发布失败
`STATUS_NUM`	状态数量
`STOPPED_UNREACHED`	已停止但未到达
`SUCCESS`	成功
`TIMEOUT`	超时
`UNSUPPORTED_FUNCRION`	不支持的函数

导航任务状态

导航任务当前状态枚举。

表示导航系统报告的活动或已完成的导航任务的当前状态。用于非阻塞导航时轮询，及时检测RUNNING、SUCCESS或FAILED并退出错误逻辑。

Enum Value	Description
`FAILED`	失败
`RUNNING`	运行中
`SUCCESS`	导航任务成功完成
`UNKNOWN`	未知

里程计数据

里程计数据。包含来自里程计源（轮式编码器、IMU 融合等）的机器人位姿和速度估计。用于机器人定位和导航。

Member Variables

Name	Type	Description
`angular_velocity`	list[float]	角速度 [ωx, ωy, ωz]（弧度/秒）
`linear_velocity`	list[float]	线速度 [vx, vy, vz]（米/秒）
`orientation`	list[float]	四元数方向 [qx, qy, qz, qw]
`position`	list[float]	位置 [x, y, z]（米）
`timestamp_ns`	int	里程计时间戳（自纪元以来的纳秒数）

参数

运动规划参数配置类。

此类扩展了 PlannerConfig，为全身运动规划和执行提供全面的配置选项。它封装了执行模式、驱动类型、工具架处理、碰撞检查和坐标系规范。所有角度参数均以弧度为单位，线性参数以米（SI 单位）为单位。

Member Variables

Name	Type	Description
`joint_state`	dict[str, list[float]]	-
`timeout_second`	float	-

获取驱动类型

def get_actuate_type() -> str

获取驱动类型

返回值

类型	描述
str	-

获取是否阻塞

def get_blocking() -> bool

获取是否阻塞执行

返回值

类型	描述
bool	-

获取是否检测碰撞

def get_check_collision() -> bool

获取是否进行碰撞检测

返回值

类型	描述
bool	-

获取是否直接执行

def get_direct_execute() -> bool

获取是否直接执行

返回值

类型	描述
bool	-

获取参考帧

def get_reference_frame() -> str

获取参考坐标系

返回值

类型	描述
str	-

获取超时

def get_timeout() -> float

获取超时时间（秒）

返回值

类型	描述
float	-

获取工具位姿

def get_tool_pose() -> bool

获取目标工具位姿

返回值

类型	描述
bool	-

设置驱动类型

def set_actuate(actuate: str) -> None

设置驱动类型

参数

名称	类型	默认值	描述
`actuate`	str	需要传参	-

warning

actuate 必须为受支持的取值（"with_chain_only"、"with_torso"、"with_leg"），否则行为未定义。

设置是否阻塞

def set_blocking(blocking: bool) -> None

设置是否阻塞执行

参数

名称	类型	默认值	描述
`blocking`	bool	需要传参	-

设置是否检测碰撞

def set_check_collision(check_collision: bool) -> None

设置是否进行碰撞检测

参数

名称	类型	默认值	描述
`check_collision`	bool	需要传参	-

warning

禁用碰撞检查可能会导致不安全的轨迹。

设置是否直接执行

def set_direct_execute(direct_execute: bool) -> None

设置是否直接执行

参数

名称	类型	默认值	描述
`direct_execute`	bool	需要传参	-

设置是否移动直线

def set_move_line(move_line: bool) -> None

设置是否为直线运动

参数

名称	类型	默认值	描述
`move_line`	bool	需要传参	-

note

直线运动提供可预测的笛卡尔路径，但可能在狭窄空间中受限制。

设置参考帧

def set_reference_frame(frame: str) -> None

设置参考坐标系

参数

名称	类型	默认值	描述
`frame`	str	需要传参	-

note

必须是机器人 TF 树中的有效帧。

设置超时

def set_timeout(timeout: SupportsFloat) -> None

设置运动执行超时时间（秒）

参数

名称	类型	默认值	描述
`timeout`	SupportsFloat	需要传参	-

note

仅在阻塞模式启用时适用。

设置工具位姿

def set_tool_pose(tool_pose: bool) -> None

设置目标工具位姿

参数

名称	类型	默认值	描述
`tool_pose`	bool	需要传参	-

感知模块

启用的感知管道（初始化时加载的模型集）。

Enum Value	Description
`FOUNDATION_STEREO`	高精度立体深度；用于需要高精度的任务（如搬箱子场景）。
`LIGHT_STEREO`	轻量级立体深度；用于精度要求不高的场景（如迎宾场景）。此版本不支持。

点

表示三维笛卡尔空间中的位置。

Member Variables

Name	Type	Description
`x`	float	-
`y`	float	-
`z`	float	-

点云字段

描述 PointCloud2 点结构中的一个数据字段，定义其名称、类型、偏移量和计数。与 ROS 2sensor_msgs/PointField 兼容。

Member Variables

Name	Type	Description
`count`	int	此字段的数组长度，标量字段（x, y, z, intensity）通常为 1，数组字段可能大于 1（例如 count=3 表示 3 元素向量）
`datatype`	...	数据类型
`offset`	int	此字段相对于点数据结构起始位置的字节偏移量，例如：对于点布局 [x(float32), y(float32), z(float32), intensity(float32)]，x 的偏移为 0，y 的偏移为 4，z 的偏移为 8，intensity 的偏移为 12

点云字段数据类型

数据类型枚举。

定义点云字段的原始数据类型，确定每个字段值的字节大小和解释方法。

Enum Value	Description
`FLOAT32`	32位浮点数
`FLOAT64`	64位浮点数
`INT16`	16位整数
`INT32`	32位整数
`INT8`	8位整数
`UINT16`	16位无符号整数
`UINT32`	32位无符号整数
`UINT8`	8位无符号整数
`UNKNOWN`	未知

姿态

姿态（位置+方向）结构。

表示 3D 空间中的完整 6-DOF（自由度）姿态，结合位置（平移）和方向（旋转）信息。常用于机器人末端执行器姿态、物体姿态和坐标系变换。

姿态状态

表示笛卡尔空间 (SE(3)) 中的目标末端执行器姿态。扩展 RobotStates 为运动链指定基于姿态的运动目标。用于逆运动学和笛卡尔轨迹规划。姿态值：以米为单位的位置，以四元数为单位的方向。坐标系必须存在于机器人的 TF 树中。

获取类型

def get_type() -> RobotStatesType

获取位姿状态类型

返回值

类型	描述
RobotStatesType	-

几何基元类型

原始类型相关说明。

Enum Value	Description
`CYLINDER`	圆柱体
`LINE`	直线

四元数

使用四元数表示 (x, y, z, w) 表示 3D 旋转。单位四元数的大小为 1，表示有效旋转。

Member Variables

Name	Type	Description
`w`	float	-
`x`	float	-
`y`	float	-
`z`	float	-

RGB数据

包含来自 RGB 相机的压缩彩色图像数据。兼容 ROS 2sensor_msgs/CompressedImage 格式。

Member Variables

Name	Type	Description
`data`	list[int]	包含压缩图像数据的二进制数据块
`format`	str	指定压缩格式和编码
`header`	Header	包含采集时间戳和相机坐标系

机器人状态

封装机器人的完整运动状态，包括全身关节配置和移动底座位姿。此类作为更专业的状态表示（PoseState、JointStates）的基础，并在整个规划和控制管道中用于状态规范和反馈。所有角度值均以弧度为单位，线性值以米（SI 单位）为单位。基本姿态使用四元数表示方向（x、y、z、qx、qy、qz、qw）。

Member Variables

Name	Type	Description
`base_state`	list[float]	-
`whole_body_joint`	list[float]	-

获取类型

def get_type() -> RobotStatesType

获取机器人状态类型

返回值

类型	描述
RobotStatesType	-

设置基座状态

def set_base_state(base_pose: Pose) -> None

设置底座状态（位姿）

参数

名称	类型	默认值	描述
`base_pose`	Pose	需要传参	-

note

四元数必须单位归一化（x^2 + y^2 + z^2 + w^2 = 1）。

设置全身关节

def set_whole_body_joint(joint_positions: list[float]) -> None

设置全身关节位置

参数

名称	类型	默认值	描述
`joint_positions`	list[float]	需要传参	-

note

向量大小应等于总驱动关节数。

机器人状态类型

用于区分派生状态类型的枚举。

用于RobotStates派生类的运行时类型识别。

Enum Value	Description
`JOINT`	关节
`POSE`	姿态
`ROBOT_STATES`	机器人状态数量

采样器配置

基于采样的运动规划器的配置参数。

该结构配置基于采样的规划算法（例如，RRT、RRT*）。它控制状态空间采样分辨率、插值设置、路径简化和规划终止条件。基于采样的规划器通过随机采样状态并将它们连接起来构建运动计划图来探索配置空间。

获取是否插值

def get_interpolate() -> bool

获取是否启用插值

返回值

类型	描述
bool	-

获取插值数量

def get_interpolation_cnt() -> int

获取插值点数量

返回值

类型	描述
int	-

获取最大规划时间

def get_max_planning_time() -> float

获取最大规划时间（秒）

返回值

类型	描述
float	-

获取最大简化时间

def get_max_simplification_time() -> float

获取最大简化时间（秒）

返回值

类型	描述
float	-

获取是否简化

def get_simplify() -> bool

获取是否启用简化

返回值

类型	描述
bool	-

获取状态检查分辨率

def get_state_check_resolution() -> float

获取状态检查分辨率

返回值

类型	描述
float	-

获取状态检查类型

def get_state_check_type() -> StateCheckType

获取状态检查类型

返回值

类型	描述
StateCheckType	-

获取终止条件类型

def get_termination_condition_type() -> TerminationConditionType

获取终止条件类型

返回值

类型	描述
TerminationConditionType	-

打印输出

def print() -> None

打印采样器配置信息到标准输出

设置是否插值

def set_interpolate(enable: bool) -> None

设置是否启用插值

参数

名称	类型	默认值	描述
`enable`	bool	需要传参	-

note

插值可提高轨迹平滑度和碰撞检测覆盖率。

设置插值数量

def set_interpolation_cnt(cnt: SupportsInt) -> None

设置插值点数量

参数

名称	类型	默认值	描述
`cnt`	SupportsInt	需要传参	-

note

较高的计数可改善碰撞检测但增加计算成本。

设置最大规划时间

def set_max_planning_time(time: SupportsFloat) -> None

设置最大规划时间（秒）

参数

名称	类型	默认值	描述
`time`	SupportsFloat	需要传参	-

note

如果找到精确解，规划可能提前终止（取决于终止条件）。

设置最大简化时间

def set_max_simplification_time(time: SupportsFloat) -> None

设置最大简化时间（秒）

参数

名称	类型	默认值	描述
`time`	SupportsFloat	需要传参	-

note

较长的简化时间可能产生更短、更平滑的路径。

设置是否简化

def set_simplify(enable: bool) -> None

设置是否启用简化

参数

名称	类型	默认值	描述
`enable`	bool	需要传参	-

note

简化减少路点并提高轨迹效率。

设置状态检查分辨率

def set_state_check_resolution(resolution: SupportsFloat) -> None

设置状态检查分辨率

参数

名称	类型	默认值	描述
`resolution`	SupportsFloat	需要传参	-

note

较低的值增加规划精度但可能减慢计算速度。

设置状态检查类型

def set_state_check_type(type: StateCheckType) -> None

设置状态检查类型

参数

名称	类型	默认值	描述
`type`	StateCheckType	需要传参	-

设置终止条件类型

def set_termination_condition_type(type: TerminationConditionType) -> None

设置终止条件类型

参数

名称	类型	默认值	描述
`type`	TerminationConditionType	需要传参	-

随机种子类型

指定逆运动学 (IK) 解算器的初始化策略。不同的种子类型会影响收敛速度和解的质量。

Enum Value	Description
`RANDOM_PROGRESSIVE_SEED`	随机渐进种子
`RANDOM_SEED`	随机种子
`USER_DEFINED_SEED`	用户自定义种子

传感器类型

描述机器人上各种传感器的传感器类型枚举。

识别机器人上可用于感知、定位和操作任务的不同传感器类型。

Enum Value	Description
`BASE_LIDAR`	基座激光雷达
`BASE_ULTRASONIC`	基座超声波
`HEAD_LEFT_CAMERA`	左眼相机
`HEAD_RIGHT_CAMERA`	右眼相机
`LEFT_ARM_CAMERA`	左臂相机
`LEFT_ARM_DEPTH_CAMERA`	左臂深度相机
`LEFT_FRONT_SURROUND_CAMERA`	左前方环视相机
`LEFT_REAR_SURROUND_CAMERA`	左后方环视相机
`RIGHT_ARM_CAMERA`	右臂相机
`RIGHT_ARM_DEPTH_CAMERA`	右臂深度相机
`RIGHT_FRONT_SURROUND_CAMERA`	右前方环视相机
`RIGHT_REAR_SURROUND_CAMERA`	右后方环视相机
`TORSO_IMU`	躯干IMU

SingoriX目标

SingoriX控制器的目标表示，用于与SingoriX外部控制器通信。

Member Variables

Name	Type	Description
`header`	Header	Message header
`target_group_trajectory_map`	dict[str, TargetGroupTrajectory]	Joint-space trajectory map
`target_task_trajectory_map`	dict[str, TargetTaskTrajectory]	Task-space trajectory map

状态检查类型

状态检查类型相关说明。

Enum Value	Description
`EUCLIDEAN_DISTANCE`	欧氏距离
`RADIAN_DISTANCE`	弧度距离

吸盘动作状态

代表真空吸盘末端执行器的运行状态，跟踪从空闲到成功或失败的抽吸过程。

Enum Value	Description
`FAILED`	失败
`IDLE`	空闲
`SUCCESS`	吸盘动作成功
`SUCKING`	吸取中

吸盘状态

包含真空吸盘夹具的当前状态，包括激活状态、压力读数和动作状态。

Member Variables

Name	Type	Description
`action_state`	SUCTION_ACTION_STATE	动作状态
`activation`	bool	激活
`pressure`	float	压力
`timestamp_ns`	int	状态时间戳（自纪元以来的纳秒数）

目标配置

目标的配置参数，包含目标类型、采样方式、约束条件等设置。

Member Variables

Name	Type	Description
`target_data`	int	Target data bitmask
`target_id`	str	Target identifier
`target_priority`	int	Target priority
`target_sampling`	TargetSampling	Sampling strategy
`target_ts`	Timestamp	Target timestamp
`target_type`	int	Target type bitmask

目标关节组轨迹

目标在关节组空间中的轨迹，包含一系列途经点和时间信息。

Member Variables

Name	Type	Description
`group_commands`	list[GroupCommand]	Trajectory points
`joint_names`	list[str]	Joint names
`target_config`	TargetConfig	Target configuration

目标采样

目标轨迹的采样方法，用于在路径点之间生成中间点。

Enum Value	Description
`TARGET_SAMPLING_B_SPLINES`	B样条采样
`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_PROFILE`	S曲线轮廓采样
`TARGET_SAMPLING_TRAPEZOIDAL_PROFILE`	梯形轮廓采样

目标任务轨迹

目标在任务空间中的轨迹，包含任务级别的约束和要求。

Member Variables

Name	Type	Description
`group_names`	list[str]	Related group names
`joint_names`	list[str]	Related joint names
`subtask_names`	list[str]	Subtask names
`target_config`	TargetConfig	Target configuration
`task_commands`	list[TaskCommand]	Trajectory points

任务命令

任务级别的命令结构，包含一个或多个目标和执行参数。

Member Variables

Name	Type	Description
`subtask_commands`	list[FrameTriad]	Subtask commands at this point
`time_from_start_s`	float	Time from trajectory start in seconds

终止条件类型

终止条件类型相关说明。

Enum Value	Description
`TIMEOUT`	仅当超过最大规划时间时终止
`TIMEOUT_AND_EXACT_SOLUTION`	超时或精确解

时间戳

表示具有秒和纳秒分量的高精度时间点。兼容 ROS 2builtin_interfaces/Time 和 std_msgs/Header 时间戳格式。

Member Variables

Name	Type	Description
`nanosec`	int	纳秒
`sec`	int	秒

轨迹

包含完整的计划轨迹以及关节位置和计时信息。

Member Variables

Name	Type	Description
`joint_groups`	list[str]	用于按顺序展开目标关节的关节组名称。例如：{"head","left_arm"} 映射到 head_joint1...left_arm_joint1...
`joint_names`	list[str]	关节名称列表
`points`	list[TrajectoryPoint]	点云

轨迹控制状态

机器人轨迹执行状态枚举。

表示机器人沿着由多个路点组成的预先规划的轨迹运行时的实时执行状态。

Enum Value	Description
`COMPLETED`	已完成
`DATA_FETCH_FAILED`	数据获取失败
`ERROR`	错误日志
`INVALID_INPUT`	无效输入
`RUNNING`	运行中
`STOPPED_UNREACHED`	轨迹执行过程中停止但未达到终点

轨迹可行性检查选项

轨迹验证和可行性检查配置。

该结构提供了对在轨迹验证期间强制执行可行性约束的细粒度控制。它支持碰撞检测、关节限制合规性和速度剖面可行性的独立切换。有选择地禁用检查可以提高调试、模拟或保证满足某些约束的场景的计算性能。禁用可行性检查可能会产生不安全或物理上无法实现的轨迹。仅当通过其他方式验证约束时才应谨慎使用。

获取是否禁用碰撞检查

def get_disable_collision_check() -> bool

获取是否禁用碰撞检测

返回值

类型	描述
bool	-

获取是否禁用关节限制检查

def get_disable_joint_limit_check() -> bool

获取是否禁用关节限制检查

返回值

类型	描述
bool	-

获取是否禁用速度可行性检查

def get_disable_velocity_feasibility_check() -> bool

获取是否禁用速度可行性检查

返回值

类型	描述
bool	-

打印输出

def print() -> None

打印轨迹可行性检查选项到标准输出

设置是否禁用碰撞检查

def set_disable_collision_check(disable: bool) -> None

设置是否禁用碰撞检测

参数

名称	类型	默认值	描述
`disable`	bool	需要传参	-

warning

禁用碰撞检查可能导致轨迹与环境发生碰撞

设置是否禁用关节限制检查

def set_disable_joint_limit_check(disable: bool) -> None

设置是否禁用关节限制检查

参数

名称	类型	默认值	描述
`disable`	bool	需要传参	-

warning

禁用关节限制检查可能导致轨迹超出关节限位

设置是否禁用速度可行性检查

def set_disable_velocity_feasibility_check(disable: bool) -> None

设置是否禁用速度可行性检查

参数

名称	类型	默认值	描述
`disable`	bool	需要传参	-

note

速度可行性确保轨迹可以被机器人执行。

轨迹规划配置

轨迹规划和参数化配置。

该结构配置轨迹生成参数，用于将离散运动计划转换为平滑的时间参数化轨迹。它支持单段和多路点轨迹规划。轨迹规划涉及计算沿几何路径的速度和加速度分布，同时尊重运动学约束。

获取最小移动时间

def get_min_move_time() -> float

获取最小运动时间（秒）

返回值

类型	描述
float	-

获取直线插值中间点

def get_move_line_intermediate_point() -> float

获取直线运动中间点设置

返回值

类型	描述
float	-

获取路点规划预期时间

def get_way_point_plan_expected_time() -> float

获取路点规划期望时间

返回值

类型	描述
float	-

打印输出

def print() -> None

打印轨迹规划配置信息到标准输出

设置最小移动时间

def set_min_move_time(time: SupportsFloat) -> None

设置最小运动时间（秒）

参数

名称	类型	默认值	描述
`time`	SupportsFloat	需要传参	-

note

非零值防止运动过快；0.0 允许在运动学限制内的最高速度

设置直线插值中间点

def set_move_line_intermediate_point(value: SupportsFloat) -> None

设置直线运动中间点设置

参数

名称	类型	默认值	描述
`value`	SupportsFloat	需要传参	-

note

较高的值提高笛卡尔路径精度但增加计算成本。

设置路点规划预期时间

def set_way_point_plan_expected_time(time: SupportsFloat) -> None

设置路点规划期望时间

参数

名称	类型	默认值	描述
`time`	SupportsFloat	需要传参	-

note

用作时间最优轨迹生成算法的提示。

轨迹点

表示机器人轨迹中的路点，指定特定时间的关节状态。

Member Variables

Name	Type	Description
`joint_command_vec`	list[JointCommand]	关节命令向量
`time_from_start_second`	float	起始时间偏移（秒）

扭曲速度

表示刚体的线速度和角速度组合，遵循ROS标准消息格式。

Member Variables

Name	Type	Description
`angular`	Vector3	Angular velocity vector
`linear`	Vector3	Linear velocity vector

超声波数据

包含带有时间戳的单个超声波距离测量。

Member Variables

Name	Type	Description
`distance`	float	距离
`timestamp_ns`	int	超声波测量时间戳（纳秒）

超声波类型

底盘超声波传感器探头枚举（8个方向）

识别布置在移动底盘周围的各个超声波传感器，用于全向障碍物检测和接近感测。

Enum Value	Description
`BACK_LEFT`	左后超声波
`BACK_RIGHT`	右后超声波
`FRONT_LEFT`	左前超声波
`FRONT_RIGHT`	右前超声波
`LEFT_LEFT`	左侧左超声波
`LEFT_RIGHT`	左侧右超声波
`RIGHT_LEFT`	右侧左超声波
`RIGHT_RIGHT`	右侧右超声波

三维向量

表示三维矢量，用于力、扭矩、速度、加速度和其他矢量。

Member Variables

Name	Type	Description
`x`	float	X分量
`y`	float	Y分量
`z`	float	Z分量

全身控制异常

将 MotionStatus 枚举值转换为字符串。

力与力矩

力与力矩相关说明。

Member Variables

Name	Type	Description
`force`	Vector3	Force vector
`torque`	Vector3	Torque vector

检查运动状态

def check_motion_status(status: MotionStatus) -> str

检查当前运动状态，验证运动是否满足约束条件。

参数

名称	类型	默认值	描述
`status`	MotionStatus	需要传参	运动状态

返回值

类型	描述
str	str：运动状态的字符串表示。

创建参数

def create_parameter(
    direct_execute: bool,
    blocking: bool,
    timeout: SupportsFloat,
    actuate: str,
    tool_pose: bool,
    check_collision: bool,
    frame: str = 'base_link'
) -> Parameter

创建运动命令参数，设置执行方式、超时、碰撞检查等选项。

参数

名称	类型	默认值	描述
`direct_execute`	bool	需要传参	是否直接执行该运动。
`blocking`	bool	需要传参	是否阻塞执行直到完成。
`timeout`	SupportsFloat	需要传参	等待运动完成的最长时间。
`actuate`	str	需要传参	驱动类型（位置/速度/力矩）。
`tool_pose`	bool	需要传参	该运动是否针对工具位姿。
`check_collision`	bool	需要传参	是否进行碰撞检测。
`frame`	str	`'base_link'`	运动使用的坐标系，默认值为 "base_link"。

返回值

类型	描述
Parameter	Parameter：新的 Parameter 实例。

核心机器人控制​

获取控制器权限​

检查轨迹执行状态​

清除末端执行器命令​

销毁​

执行关节轨迹​

获取当前控制器​

获取电池管理信息​

获取相机内参​

获取深度图像数据​

获取设备信息​

获取灵巧手状态​

获取力传感器数据​

获取坐标系名称​

获取夹爪状态​

获取IMU数据​

获取关节组名称​

获取关节名称​

获取关节位置​

获取关节状态​

获取激光雷达数据​

获取日志信息​

获取里程计数据​

获取RGB图像数据​

获取传感器外参​

获取吸盘状态​

获取坐标变换​

获取超声波数据​

获取音量​

获取 WBC 末端执行器位姿​

初始化​

检查是否运行中​

发布目标​

释放控制器权限​

重新加载控制器​

请求关机​

请求目标​

设置底盘姿态​

设置底盘姿态​

设置底盘姿态​

设置底盘速度​

设置灵巧手命令​

设置末端执行器命令​

设置夹爪命令​

设置关节命令​

批量设置关节命令​

设置关节位置​

设置吸盘命令​

设置音量​

启动控制器​

启动麦克风流输入​

停止音频流输出​

紧急停止底盘​

停止控制器​

停止麦克风流输入​

停止轨迹执行​

切换控制器​

等待关机​

写入音频流输出​

全身与底盘归零​

全身与底盘归零​

运动规划与执行​

添加障碍物​

附加目标对象​

附加工具​

检查碰撞​

清空障碍物​

分离目标对象​

分离工具​

正向运动学​

基于状态的正向运动学​

获取已构建障碍物列表​

获取链关节状态​

获取末端执行器姿态​

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

获取连杆名称​

获取运动规划配置​

获取机器人状态​

获取支持的链​

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

核心机器人控制

获取控制器权限

检查轨迹执行状态

清除末端执行器命令

销毁

执行关节轨迹

获取当前控制器

获取电池管理信息

获取相机内参

获取深度图像数据

获取设备信息

获取灵巧手状态

获取力传感器数据

获取坐标系名称

获取夹爪状态

获取IMU数据

获取关节组名称

获取关节名称

获取关节位置

获取关节状态

获取激光雷达数据

获取日志信息

获取里程计数据

获取RGB图像数据

获取传感器外参

获取吸盘状态

获取坐标变换

获取超声波数据

获取音量

获取 WBC 末端执行器位姿

初始化

检查是否运行中

发布目标

释放控制器权限

重新加载控制器

请求关机

请求目标

设置底盘姿态

设置底盘姿态

设置底盘姿态

设置底盘速度

设置灵巧手命令

设置末端执行器命令

设置夹爪命令

设置关节命令

批量设置关节命令

设置关节位置

设置吸盘命令

设置音量

启动控制器

启动麦克风流输入

停止音频流输出

紧急停止底盘

停止控制器

停止麦克风流输入

停止轨迹执行

切换控制器

等待关机

写入音频流输出

全身与底盘归零

全身与底盘归零

运动规划与执行

添加障碍物

附加目标对象

附加工具

检查碰撞

清空障碍物

分离目标对象

分离工具

正向运动学

基于状态的正向运动学

获取已构建障碍物列表

获取链关节状态

获取末端执行器姿态

获取指定链末端执行器姿态

获取连杆名称

获取运动规划配置

获取机器人状态

获取支持的链

获取支持的末端执行器坐标系