C++ API 参考 - S1 机器人

• GalbotRobot: 核心机器人控制模块。用于机器人连接、生命周期管理、关节控制、传感器数据查询和硬件状态监控。
• GalbotMotion: 运动规划与执行模块。用于笛卡尔空间/关节空间运动、轨迹规划、逆运动学和全身控制。
• GalbotNavigation: 移动导航模块。用于移动底盘定位、地图构建、路径规划和自主移动。
• Types & Enums: 数据结构、枚举与状态类型。本节用于查询类型定义、传感器类型、错误码及其他模块使用的数据结构。

---

核心机器人控制

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

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

析构函数

virtual galbot::sdk::GalbotRobot::~GalbotRobot()=default

初始化

virtual bool galbot::sdk::GalbotRobot::init(const std::unordered_set< SensorType > &enable_sensor_set={})=0

初始化机器人控制系统。

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

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

参数

Name	Type	Description
enable_sensor_set	const std::unordered_set< SensorType > &	要启用的传感器集合，如果为空，则启用默认的传感器集合，仅指定所需传感器可减少启动时间和资源占用

返回值

Type	Description
bool	初始化成功返回 true，否则返回 false。

发布目标

virtual ControlStatus galbot::sdk::GalbotRobot::PublishTarget(const SingoriXTarget &target)=0

将目标发布到机器人控制系统，使目标可被运动规划模块使用。

参数

Name	Type	Description
target	const SingoriXTarget &	目标对象

返回值

Type	Description
ControlStatus	无返回值

请求目标

virtual std::shared_ptr< ErrorInfo > galbot::sdk::GalbotRobot::RequestTarget(const SingoriXTarget &target)=0

向机器人控制系统请求一个目标，用于运动规划和执行。

参数

Name	Type	Description
target	const SingoriXTarget &	目标对象

返回值

Type	Description
std::shared_ptr< ErrorInfo >	返回共享指针：本地预检查失败或服务响应结果。若客户端不可用、连接断开、超时或返回空响应，则返回 nullptr。

设置关节命令

virtual ControlStatus galbot::sdk::GalbotRobot::set_joint_commands(
    const std::vector< JointCommand > &joint_commands,
    const std::vector< std::string > &joint_groups={},
    const std::vector< std::string > &joint_names={},
    const double time_from_start_s=10
) =0

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

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

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

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

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

参数

Name	Type	Description
joint_commands	const std::vector< JointCommand > &	关节命令列表
joint_groups	const std::vector< std::string > &	要控制的关节组。支持的组：legs（腿部）、head（头部）、left_arm（左臂）、right_arm（右臂）、gripper（夹爪）、suction_cup（吸盘）。如果 joint_names 也为空，则不能为空，否则返回 INVALID_INPUT。
joint_names	const std::vector< std::string > &	要控制的具体关节名称。此参数优先于 joint_groups。如果提供了 joint_names，则忽略 joint_groups。如果 joint_groups 也为空，则不能为空，否则返回 INVALID_INPUT。
time_from_start_s	const double	预期到达时间（秒）

返回值

Type	Description
ControlStatus	控制状态，指示命令传输的成功或失败

warning

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

设置关节位置

virtual ControlStatus galbot::sdk::GalbotRobot::set_joint_positions(
    const std::vector< double > &joint_positions,
    const std::vector< std::string > &joint_groups={},
    const std::vector< std::string > &joint_names={},
    const bool is_blocking=true,
    const double speed_rad_s=0.2,
    const double timeout_s=15
) =0

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

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

参数

Name	Type	Description
joint_positions	const std::vector< double > &	目标关节位置
joint_groups	const std::vector< std::string > &	要控制的关节组名称。支持的组：腿部、头部、左臂、右臂。如果 joint_names 也为空，则不能为空，否则返回 INVALID_INPUT。
joint_names	const std::vector< std::string > &	要控制的具体关节名称。此参数优先于 joint_groups。如果提供了 joint_names，则忽略 joint_groups。如果 joint_groups 也为空，则不能为空，否则返回 INVALID_INPUT。
is_blocking	const bool	是否阻塞等待完成。true：阻塞直到完成或超时；false：发送后立即返回。
speed_rad_s	const double	最大运动速度（弧度/秒）
timeout_s	const double	超时时间（秒）

返回值

Type	Description
ControlStatus	控制状态，指示运动命令的成功或失败

warning

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

检查轨迹执行状态

virtual std::vector< TrajectoryControlStatus > galbot::sdk::GalbotRobot::check_trajectory_execution_status(
    std::vector< std::string > joint_groups
) =0

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

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

参数

Name	Type	Description
joint_groups	std::vector< std::string >	关节组列表

返回值

Type	Description
std::vector< TrajectoryControlStatus >	轨迹控制状态列表：轨迹执行状态列表。

执行关节轨迹

virtual ControlStatus galbot::sdk::GalbotRobot::execute_joint_trajectory(
    Trajectory trajectory,
    bool is_blocking=true
) =0

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

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

参数

Name	Type	Description
trajectory	Trajectory	轨迹数据结构，包含路点和时序信息。必须指定 trajectory.joint_groups 或 trajectory.joint_names；如果两者都为空，则返回 INVALID_INPUT。
is_blocking	bool	是否阻塞等待完成

返回值

Type	Description
ControlStatus	控制状态，指示轨迹执行/提交的成功或失败

warning

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

warning

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

批量设置关节命令

virtual ControlStatus galbot::sdk::GalbotRobot::set_joint_commands_batch(const Trajectory &trajectory)=0

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

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

参数

Name	Type	Description
trajectory	const Trajectory &	包含关节命令路点的轨迹数据结构。必须指定 trajectory.joint_groups 或 trajectory.joint_names；如果两者都为空，则返回 INVALID_INPUT。每个 TrajectoryPoint 包含 time_from_start 和关节命令列表。关节命令包括位置（弧度）、速度（弧度/秒）、加速度（弧度/秒²）、作用力（牛·米）、Kp（位置增益）和 Kd（速度增益）。

返回值

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

warning

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

设置夹爪命令

virtual ControlStatus galbot::sdk::GalbotRobot::set_gripper_command(
    const std::string &end_effector,
    double width_m,
    double velocity_mps=0.03,
    double effort=30,
    bool is_blocking=true
) =0

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

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

参数

Name	Type	Description
end_effector	const std::string &	要控制的夹爪关节组名称（例如 left_gripper、right_gripper）。
width_m	double	目标开口宽度（米）
velocity_mps	double	夹爪运动速度（米/秒）
effort	double	最大夹持力（牛顿·米，N·m）。
is_blocking	bool	是否阻塞等待完成

返回值

Type	Description
ControlStatus	控制状态，指示夹爪命令的成功或失败

获取夹爪状态

virtual std::shared_ptr< GripperState > galbot::sdk::GalbotRobot::get_gripper_state(
    const std::string &end_effector
) =0

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

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

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

参数

Name	Type	Description
end_effector	const std::string &	要查询的夹爪关节组名称（例如 left_gripper、right_gripper）。

返回值

Type	Description
std::shared_ptr< GripperState >	返回夹爪状态的共享指针；若读取失败，返回 nullptr。

获取灵巧手状态

virtual ControlStatus galbot::sdk::GalbotRobot::get_dexhand_state(
    const std::string &end_effector,
    DexhandState &dexhand_state,
    DexHandType dexhand_type=DexHandType::INSPIRE
) =0

获取当前灵巧手（dexhand）状态。

将灵巧手反馈写入 dexhand_state。对于 INSPIRE 和 BRAINCO，仅填充 dexhand_state.joint_state，force_sensor_map 为空；对于 SHARPA，会填充完整关节状态，并在可用时返回命名力传感器数据。

参数

Name	Type	Description
end_effector	const std::string &	要查询的灵巧手关节组名称（例如 left_dexhand、right_dexhand）。
dexhand_state	DexhandState &	输出：灵巧手状态（joint_state 及可选 force_sensor_map）。
dexhand_type	DexHandType	灵巧手型号（INSPIRE、BRAINCO 或 SHARPA）。

返回值

Type	Description
ControlStatus	控制状态，指示成功或失败。

设置灵巧手命令

virtual ControlStatus galbot::sdk::GalbotRobot::set_dexhand_command(
    const std::string &end_effector,
    const std::vector< JointCommand > &dexhand_command,
    DexHandType dexhand_type=DexHandType::INSPIRE,
    bool is_blocking=true
) =0

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

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

参数

Name	Type	Description
end_effector	const std::string &	要控制的灵巧手名称（例如 left_dexhand、right_dexhand）。
dexhand_command	const std::vector< JointCommand > &	每个灵巧手关节的命令向量。Inspire: [位置, 速度, 加速度, 力矩] 范围 [0-1000, 0-1000, , 0-1000]。BrainCo: [位置, 速度, 加速度, 力矩] 范围 [0-100, -100-100, , ]。Sharpa: 22 个关节命令 [位置, 速度, 加速度, 力矩]。
dexhand_type	DexHandType	灵巧手型号。
is_blocking	bool	是否阻塞等待动作完成。

返回值

Type	Description
ControlStatus	控制状态，表示命令发布结果。

获取关节位置

virtual std::vector< double > galbot::sdk::GalbotRobot::get_joint_positions(
    const std::vector< std::string > &joint_groups,
    const std::vector< std::string > &joint_names
) =0

获取关节位置

参数

Name	Type	Description
joint_groups	const std::vector< std::string > &	关节组列表
joint_names	const std::vector< std::string > &	关节名称列表

返回值

Type	Description
std::vector< double >	当前关节角度向量（弧度）

note

返回值顺序：指定 joint_names 时按 joint_names 顺序；仅指定 joint_groups 时按组定义顺序；都为空时按 chassis、head、left_arm、right_arm、leg 顺序返回身体关节

获取关节组名称

virtual std::vector< std::string > galbot::sdk::GalbotRobot::get_joint_group_names()=0

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

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

返回值

Type	Description
std::vector< std::string >	关节组名称向量，或如果检索失败则为空向量

获取关节名称

virtual std::vector< std::string > galbot::sdk::GalbotRobot::get_joint_names(
    bool only_active_joint=true,
    const std::vector< std::string > &joint_groups={}
) =0

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

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

参数

Name	Type	Description
only_active_joint	bool	是否仅返回主动关节
joint_groups	const std::vector< std::string > &	关节组列表

返回值

Type	Description
std::vector< std::string >	返回关节名称列表，顺序取决于参数配置

获取关节状态

virtual std::vector< JointState > galbot::sdk::GalbotRobot::get_joint_states(
    const std::vector< std::string > &joint_group_vec,
    const std::vector< std::string > &joint_names_vec={}
) =0

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

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

参数

Name	Type	Description
joint_group_vec	const std::vector< std::string > &	关节组向量
joint_names_vec	const std::vector< std::string > &	关节名称向量

返回值

Type	Description
std::vector< JointState >	结构向量，包含每个关节的当前状态

note

返回值顺序：指定 joint_names 时按 joint_names 顺序；仅指定 joint_groups 时按组定义顺序；都为空时按 chassis、head、left_arm、right_arm、leg 顺序返回身体关节

设置底盘速度

virtual ControlStatus galbot::sdk::GalbotRobot::set_base_velocity(
    const std::array< double, 3 > &linear_velocity,
    const std::array< double, 3 > &angular_velocity,
    double duration_s=0.0
) =0

设置移动基础速度命令。

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

参数

Name	Type	Description
linear_velocity	const std::array< double, 3 > &	线速度（米/秒），在底座坐标系中表示。 顺序：{vx, vy, vz} - vx: X 方向线速度（前后） - vy: Y 方向线速度（左右） - vz: Z 方向线速度（垂直）
angular_velocity	const std::array< double, 3 > &	角速度（弧度/秒），在底座坐标系中表示。 顺序：{wx, wy, wz} - wx: 绕 X 轴角速度（翻滚） - wy: 绕 Y 轴角速度（俯仰） - wz: 绕 Z 轴角速度（偏航）
duration_s	double	持续时间（秒）

返回值

Type	Description
ControlStatus	控制状态，指示命令传输的成功或失败

设置底盘姿态

virtual ControlStatus galbot::sdk::GalbotRobot::set_base_pose(
    const Pose &base_pose,
    bool is_blocking=true,
    double timeout_s=15.0
) =0

设置移动基础位姿命令。

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

参数

Name	Type	Description
base_pose	const Pose &	底盘目标姿态
is_blocking	bool	是否阻塞等待完成
timeout_s	double	超时时间（秒）

返回值

Type	Description
ControlStatus	控制状态，指示命令传输的成功或失败

设置底盘姿态

virtual ControlStatus galbot::sdk::GalbotRobot::set_base_pose(
    double x,
    double y,
    double yaw,
    const std::string &frame_id="odom",
    const std::string &reference_frame_id="odom",
    bool is_blocking=true,
    double timeout_s=15.0
) =0

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

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

参数

Name	Type	Description
x	double	X坐标（米）
y	double	Y坐标（米）
yaw	double	航向角（弧度）
frame_id	const std::string &	坐标系ID
reference_frame_id	const std::string &	参考坐标系ID
is_blocking	bool	是否阻塞等待完成
timeout_s	double	超时时间（秒）

返回值

Type	Description
ControlStatus	控制状态，指示命令传输的成功或失败

设置底盘姿态

virtual ControlStatus galbot::sdk::GalbotRobot::set_base_pose(
    double x,
    double y,
    double yaw,
    const std::string &frame_id,
    const std::string &reference_frame_id,
    double time_from_start_s,
    bool is_blocking=true,
    double timeout_s=15.0
) =0

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

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

参数

Name	Type	Description
x	double	X坐标（米）
y	double	Y坐标（米）
yaw	double	航向角（弧度）
frame_id	const std::string &	坐标系ID
reference_frame_id	const std::string &	参考坐标系ID
time_from_start_s	double	预期到达时间（秒）
is_blocking	bool	是否阻塞等待完成
timeout_s	double	超时时间（秒）

返回值

Type	Description
ControlStatus	控制状态，指示命令传输的成功或失败

设置末端执行器命令

virtual ControlStatus galbot::sdk::GalbotRobot::set_end_effector_command(
    const std::vector< std::vector< double > > &poses,
    const std::vector< std::string > &end_effector_frames,
    const std::vector< std::string > &reference_frames={},
    double time_from_start_s=0.0
) =0

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

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

参数

Name	Type	Description
poses	const std::vector< std::vector< double > > &	每个末端执行器对应一个位姿；每行格式为 [x, y, z, qx, qy, qz, qw]（单位：米，四元数顺序 xyzw）。
end_effector_frames	const std::vector< std::string > &	每个位姿对应的目标坐标系 id（例如连杆名称）。
reference_frames	const std::vector< std::string > &	每个位姿对应的参考坐标系。省略或传入 [] 时默认对所有位姿使用 "world"。否则长度必须与 poses 一致。常用值："world"（默认）。
time_from_start_s	double	从轨迹起点开始的时间（秒，可选，默认 0.0）。

返回值

Type	Description
ControlStatus	控制状态，表示命令发布结果。

清除末端执行器命令

virtual ControlStatus galbot::sdk::GalbotRobot::clear_end_effector_command()=0

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

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

返回值

Type	Description
ControlStatus	控制状态，表示命令发布结果。

获取 WBC 末端执行器位姿

virtual std::unordered_map< std::string, std::vector< double > > galbot::sdk::GalbotRobot::get_wbc_end_effector_poses() =0

获取 WBC 末端执行器位姿。

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

返回值

Type	Description
std::unordered_map< std::string, std::vector< double > >	字典映射，包含： - "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] 当失败或缺少键时，可能返回空条目或部分数据。

紧急停止底盘

virtual ControlStatus galbot::sdk::GalbotRobot::stop_base()=0

紧急停止移动底座运动。

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

返回值

Type	Description
ControlStatus	控制状态，指示命令传输的成功或失败

全身与底盘归零

virtual std::pair< MotionStatus, ControlStatus > galbot::sdk::GalbotRobot::zero_whole_body_and_base(
    const Pose &base_zero_pose,
    bool is_blocking=true,
    double leg_head_speed_rad_s=0.2,
    double leg_head_timeout_s=15.0,
    std::shared_ptr< Parameter > params=nullptr
) =0

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

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

参数

Name	Type	Description
base_zero_pose	const Pose &	底盘零位姿态
is_blocking	bool	是否阻塞等待完成
leg_head_speed_rad_s	double	腿部和头部关节速度（弧度/秒）
leg_head_timeout_s	double	腿部和头部运动超时（秒）
params	std::shared_ptr< Parameter >	额外参数

返回值

Type	Description
std::pair< MotionStatus, ControlStatus >	元组 (运动状态（关节），控制状态（底座））

全身与底盘归零

virtual std::pair< MotionStatus, ControlStatus > galbot::sdk::GalbotRobot::zero_whole_body_and_base(
    const std::string &frame_id="odom",
    const std::string &reference_frame_id="odom",
    bool is_blocking=true,
    double leg_head_speed_rad_s=0.2,
    double leg_head_timeout_s=15.0,
    std::shared_ptr< Parameter > params=nullptr
) =0

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

参数

Name	Type	Description
frame_id	const std::string &	坐标系ID
reference_frame_id	const std::string &	参考坐标系ID
is_blocking	bool	是否阻塞等待完成
leg_head_speed_rad_s	double	腿部和头部关节速度（弧度/秒）
leg_head_timeout_s	double	腿部和头部运动超时（秒）
params	std::shared_ptr< Parameter >	额外参数

返回值

Type	Description
std::pair< MotionStatus, ControlStatus >	元组 (运动状态（关节），控制状态（底座））

停止轨迹执行

virtual ControlStatus galbot::sdk::GalbotRobot::stop_trajectory_execution()=0

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

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

返回值

Type	Description
ControlStatus	控制状态，指示命令传输的成功或失败

重新加载控制器

virtual ControlStatus galbot::sdk::GalbotRobot::reload_controller(const std::string &group_name="all")=0

重新加载控制器。

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

参数

Name	Type	Description
group_name	const std::string &	要重新加载的控制器组名称

返回值

Type	Description
ControlStatus	控制状态，指示重新加载操作的成功或失败

切换控制器

virtual ControlStatus galbot::sdk::GalbotRobot::switch_controller(const std::string &controller_name)=0

切换活动控制器策略。

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

参数

Name	Type	Description
controller_name	const std::string &	控制器名称字符串，例如 "chassis_pose_ctrl"。

返回值

Type	Description
ControlStatus	控制状态，指示切换操作的成功或失败

获取当前控制器

virtual std::string galbot::sdk::GalbotRobot::get_active_controller(const std::string &group_name)=0

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

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

参数

Name	Type	Description
group_name	const std::string &	要查询的关节组名称。

返回值

Type	Description
std::string	std::string：当前 SDK 实例已知的活动控制器名称。

获取控制器权限

virtual ControlStatus galbot::sdk::GalbotRobot::acquire_controller(const std::string &controller_name)=0

获取硬件控制权限。

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

参数

Name	Type	Description
controller_name	const std::string &	控制器名称字符串，例如 "left_arm_pvt_ctrl"。

返回值

Type	Description
ControlStatus	控制状态，指示获取操作的成功或失败

释放控制器权限

virtual ControlStatus galbot::sdk::GalbotRobot::release_controller(const std::string &group_name="all")=0

释放硬件权限。

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

参数

Name	Type	Description
group_name	const std::string &	要释放的关节组名称，支持的组：chassis（底盘）、legs（腿部）、head（头部）、left_arm（左臂）、right_arm（右臂）、gripper（夹爪）、suction_cup（吸盘）或 "all"（释放所有控制器）

返回值

Type	Description
ControlStatus	控制状态，指示释放操作的成功或失败

启动控制器

virtual ControlStatus galbot::sdk::GalbotRobot::start_controller(const std::string &group_name="all")=0

开始控制器执行。

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

参数

Name	Type	Description
group_name	const std::string &	要启动的控制器组名称

返回值

Type	Description
ControlStatus	控制状态，指示启动操作的成功或失败

停止控制器

virtual ControlStatus galbot::sdk::GalbotRobot::stop_controller(const std::string &group_name="all")=0

停止控制器执行。

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

参数

Name	Type	Description
group_name	const std::string &	要停止的控制器组名称

返回值

Type	Description
ControlStatus	控制状态，指示停止操作的成功或失败

获取IMU数据

virtual std::shared_ptr< ImuData > galbot::sdk::GalbotRobot::get_imu_data(SensorType imu_type)=0

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

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

参数

Name	Type	Description
imu_type	SensorType	IMU传感器类型

返回值

Type	Description
std::shared_ptr< ImuData >	返回 IMU 数据结构的共享指针；若传感器未启用或读取失败，返回 nullptr。

note

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

note

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

note

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

获取里程计数据

virtual std::shared_ptr< OdomData > galbot::sdk::GalbotRobot::get_odom()=0

获取机器人里程信息。

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

返回值

Type	Description
std::shared_ptr< OdomData >	返回里程计数据的共享指针，包含位置、姿态、线速度、角速度与时间戳。若里程计不可用，返回空指针。

获取设备信息

virtual std::shared_ptr< DeviceInfo > galbot::sdk::GalbotRobot::get_device_information()=0

获取设备信息。

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

返回值

Type	Description
std::shared_ptr< DeviceInfo >	返回设备信息的共享指针，包含型号、序列号、固件版本、硬件版本和厂商信息。若读取失败，返回空指针。

获取RGB图像数据

virtual std::shared_ptr< RgbData > galbot::sdk::GalbotRobot::get_rgb_data(const SensorType rgb_camera)=0

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

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

参数

Name	Type	Description
rgb_camera	const SensorType	RGB相机名称

返回值

Type	Description
std::shared_ptr< RgbData >	返回 RGB 图像数据的共享指针，包含图像缓冲区、分辨率、编码与时间戳。若相机未启用或读取失败，返回空指针。

note

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

获取深度图像数据

virtual std::shared_ptr< DepthData > galbot::sdk::GalbotRobot::get_depth_data(const SensorType depth_camera)=0

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

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

参数

Name	Type	Description
depth_camera	const SensorType	深度相机名称

返回值

Type	Description
std::shared_ptr< DepthData >	返回深度图像数据的共享指针，包含图像缓冲区、分辨率、编码与时间戳。若相机未启用或读取失败，返回空指针。

note

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

note

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

获取激光雷达数据

virtual std::shared_ptr< LidarData > galbot::sdk::GalbotRobot::get_lidar_data(const SensorType lidar)=0

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

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

参数

Name	Type	Description
lidar	const SensorType	激光雷达名称

返回值

Type	Description
std::shared_ptr< LidarData >	返回 PointCloud2 点云数据的共享指针（坐标单位为米，参考 LiDAR 坐标系）。若 LiDAR 未启用或读取失败，返回空指针。

note

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

获取相机内参

virtual std::shared_ptr< CameraInfo > galbot::sdk::GalbotRobot::get_camera_intrinsic(
    const SensorType camera
) =0

获取相机内参。

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

参数

Name	Type	Description
camera	const SensorType	相机名称

返回值

Type	Description
std::shared_ptr< CameraInfo >	返回相机内参数据的共享指针，包含焦距、主点坐标、畸变系数等参数。若相机未启用或读取失败，返回空指针。

note

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

获取坐标变换

virtual std::pair< std::vector< double >, int64_t > galbot::sdk::GalbotRobot::get_transform(
    const std::string &target_frame,
    const std::string &source_frame,
    int64_t timestamp_ns=0,
    int64_t timeout_ms=100
) =0

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

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

参数

Name	Type	Description
target_frame	const std::string &	目标坐标系
source_frame	const std::string &	源坐标系
timestamp_ns	int64_t	时间戳（纳秒）
timeout_ms	int64_t	超时时间（毫秒）

返回值

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

获取坐标系名称

virtual std::vector< std::string > galbot::sdk::GalbotRobot::get_frame_names()=0

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

返回值

Type	Description
std::vector< std::string >	所有可用坐标系名称列表。

获取传感器外参

virtual std::pair< std::vector< double >, int64_t > galbot::sdk::GalbotRobot::get_sensor_extrinsic(
    const SensorType sensor_id,
    const std::string &reference_frame="base_link"
) =0

获取传感器外参。

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

参数

Name	Type	Description
sensor_id	const SensorType	传感器ID
reference_frame	const std::string &	参考坐标系

返回值

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

note

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

检查是否运行中

virtual bool galbot::sdk::GalbotRobot::is_running()=0

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

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

返回值

Type	Description
bool	系统正常运行时返回 true，否则返回 false。

请求关机

virtual void galbot::sdk::GalbotRobot::request_shutdown()=0

请求系统关闭。

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

等待关机

virtual void galbot::sdk::GalbotRobot::wait_for_shutdown()=0

阻塞直到关闭完成。

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

note

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

销毁

virtual void galbot::sdk::GalbotRobot::destroy()=0

清理系统资源。

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

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

注册退出回调

virtual void galbot::sdk::GalbotRobot::register_exit_callback(std::function< void()> exit_function)=0

注册关闭事件的回调函数。

注册一个用户定义的回调函数，当收到关闭信号时将调用该函数。可以注册多个回调，并按照注册顺序执行。

参数

Name	Type	Description
exit_function	std::function< void()>	退出时执行的回调函数，签名：void()，用于在程序退出时执行清理操作（例如保存数据、释放资源）

note

回调函数应快速完成以避免延迟关闭。

获取日志信息

virtual std::shared_ptr< LogInfo > galbot::sdk::GalbotRobot::get_log_information(
    uint64 timewindow_s,
    LogLevel log_level
) =0

获取日志信息。

参数

Name	Type	Description
timewindow_s	uint64
log_level	LogLevel

返回值

Type	Description
std::shared_ptr< LogInfo >	共享指针，包含日志信息

获取实例

static GalbotRobot & galbot::sdk::GalbotRobot::get_instance(MachineType m)

运行时工厂方法，用于选择具体机器人单例。

参数

Name	Type	Description
m	MachineType	机器类型

返回值

Type	Description
GalbotRobot &	指定机器类型的单例机器人接口引用。

---

运动规划与执行

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

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

析构函数

virtual galbot::sdk::GalbotMotion::~GalbotMotion()=default

初始化

virtual bool galbot::sdk::GalbotMotion::init()=0

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

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

返回值

Type	Description
bool	初始化成功返回 true，否则返回 false。

note

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

warning

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

检查是否有效

virtual bool galbot::sdk::GalbotMotion::is_valid()=0

检查运动接口是否正确初始化和运行。

返回值

Type	Description
bool	若对象有效且可用则返回 true，否则返回 false。

note

如果初始化状态不确定，应在关键操作前检查。

正向运动学

virtual std::tuple< MotionStatus, std::vector< double > > galbot::sdk::GalbotMotion::forward_kinematics(
    const std::string &target_frame,
    const std::string &reference_frame="base_link",
    const std::unordered_map< std::string, std::vector< double > > &joint_state={},
    std::shared_ptr< Parameter > params=default_param
) =0

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

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

参数

Name	Type	Description
target_frame	const std::string &	目标坐标系
reference_frame	const std::string &	参考坐标系
joint_state	const std::unordered_map< std::string, std::vector< double > > &	关节名到关节位置的映射；默认空字典表示使用当前机器人关节状态。
params	std::shared_ptr< Parameter >	额外参数

返回值

Type	Description
std::tuple< MotionStatus, std::vector< double > >	元组（状态，位姿向量）： - 状态：成功时为 MotionStatus::SUCCESS，否则为错误码 - 位姿向量：[x, y, z, qx, qy, qz, qw]（米，四元数），失败时为空

note

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

warning

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

基于状态的正向运动学

virtual std::tuple< MotionStatus, std::vector< double > > galbot::sdk::GalbotMotion::forward_kinematics_by_state(
    const std::string &target_frame,
    const std::shared_ptr< RobotStates > &reference_robot_states=nullptr,
    const std::string &reference_frame="base_link",
    std::shared_ptr< Parameter > params=default_param
) =0

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

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

参数

Name	Type	Description
target_frame	const std::string &	目标坐标系
reference_robot_states	const std::shared_ptr< RobotStates > &	参考机器人起始状态
reference_frame	const std::string &	参考坐标系
params	std::shared_ptr< Parameter >	额外参数

返回值

Type	Description
std::tuple< MotionStatus, std::vector< double > >	元组（状态，位姿向量）： - 状态：成功时为 MotionStatus::SUCCESS，否则为错误码 - 位姿向量：[x, y, z, qx, qy, qz, qw]（米，四元数），失败时为空

note

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

逆向运动学

virtual std::tuple< MotionStatus, std::unordered_map< std::string, std::vector< double > > > galbot::sdk::GalbotMotion::inverse_kinematics(
    const std::vector< double > &target_pose,
    const std::vector< std::string > &chain_names,
    const std::string &target_frame="EndEffector",
    const std::string &reference_frame="base_link",
    const std::unordered_map< std::string, std::vector< double > > &initial_joint_positions={},
    const bool &enable_collision_check=true,
    std::shared_ptr< Parameter > params=default_param
) =0

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

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

参数

Name	Type	Description
target_pose	const std::vector< double > &	目标笛卡尔位姿：[x, y, z, qx, qy, qz, qw]（米，四元数）。
chain_names	const std::vector< std::string > &	要解决逆运动学的运动链名称列表
target_frame	const std::string &	目标坐标系
reference_frame	const std::string &	参考坐标系
initial_joint_positions	const std::unordered_map< std::string, std::vector< double > > &	初始关节位置猜测
enable_collision_check	const bool &	是否启用碰撞检查
params	std::shared_ptr< Parameter >	额外参数

返回值

Type	Description
std::tuple< MotionStatus, std::unordered_map< std::string, std::vector< double > > >	元组（状态，解映射）： - 状态：若可求解则为 MotionStatus::SUCCESS，否则为错误码 - 解映射：{chain_name -> joint_angles}（弧度），失败时为空

note

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

note

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

warning

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

基于状态的逆向运动学

virtual std::tuple< MotionStatus, std::unordered_map< std::string, std::vector< double > > > galbot::sdk::GalbotMotion::inverse_kinematics_by_state(
    const std::vector< double > &target_pose,
    const std::vector< std::string > &chain_names,
    const std::string &target_frame="EndEffector",
    const std::string &reference_frame="base_link",
    const std::shared_ptr< RobotStates > &reference_robot_states=nullptr,
    const bool &enable_collision_check=true,
    std::shared_ptr< Parameter > params=default_param
) =0

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

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

参数

Name	Type	Description
target_pose	const std::vector< double > &	目标笛卡尔位姿：[x, y, z, qx, qy, qz, qw]（米，四元数）。
chain_names	const std::vector< std::string > &	要解决逆运动学的运动链名称列表
target_frame	const std::string &	目标坐标系
reference_frame	const std::string &	参考坐标系
reference_robot_states	const std::shared_ptr< RobotStates > &	参考机器人起始状态
enable_collision_check	const bool &	是否启用碰撞检查
params	std::shared_ptr< Parameter >	额外参数

返回值

Type	Description
std::tuple< MotionStatus, std::unordered_map< std::string, std::vector< double > > >	元组（状态，解映射）： - 状态：若可求解则为 MotionStatus::SUCCESS，否则为错误码 - 解映射：{chain_name -> joint_angles}（弧度），失败时为空

note

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

获取雅可比矩阵

virtual std::tuple< MotionStatus, std::vector< std::vector< double > > > galbot::sdk::GalbotMotion::get_jacobian(
    const std::string &chain_name,
    const std::string &target_frame="EndEffector",
    const std::string &reference_frame="base_link",
    const std::unordered_map< std::string, std::vector< double > > &joint_state={},
    std::shared_ptr< Parameter > params=default_param
) =0

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

参数

Name	Type	Description
chain_name	const std::string &	链名称
target_frame	const std::string &	计算雅可比的目标连杆："EndEffector"（法兰盘）或 "Tool"（工具中心点）。默认："EndEffector"
reference_frame	const std::string &	参考坐标系："base_link"（机器人基座坐标系）或 "world"（世界坐标系）。默认："base_link"
joint_state	const std::unordered_map< std::string, std::vector< double > > &	关节状态对象，包含当前关节位置
params	std::shared_ptr< Parameter >	运动学参数配置

返回值

Type	Description
std::tuple< MotionStatus, std::vector< std::vector< double > > >	返回 numpy 数组，形状为 [6 x DOF]，表示末端执行器在参考坐标系下的雅可比矩阵

note

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

note

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

通过状态获取雅可比矩阵

virtual std::tuple< MotionStatus, std::vector< std::vector< double > > > galbot::sdk::GalbotMotion::get_jacobian_by_state(
    const std::string &chain_name,
    const std::string &target_frame="EndEffector",
    const std::string &reference_frame="base_link",
    const std::shared_ptr< RobotStates > &reference_robot_states=nullptr,
    std::shared_ptr< Parameter > params=default_param
) =0

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

参数

Name	Type	Description
chain_name	const std::string &	链名称
target_frame	const std::string &	计算雅可比的目标连杆。默认："EndEffector"
reference_frame	const std::string &	参考坐标系。默认："base_link"
reference_robot_states	const std::shared_ptr< RobotStates > &	机器人状态，包含关节位置信息
params	std::shared_ptr< Parameter >	运动学参数配置

返回值

Type	Description
std::tuple< MotionStatus, std::vector< std::vector< double > > >	元组（状态，雅可比矩阵）： - 状态：成功时为 MotionStatus::SUCCESS，否则为错误码 - 雅可比矩阵：6xN 矩阵（N 为链自由度），失败时为空

note

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

获取末端执行器姿态

virtual std::tuple< MotionStatus, std::vector< double > > galbot::sdk::GalbotMotion::get_end_effector_pose(
    const std::string &end_effector_frame,
    const std::string &reference_frame="base_link"
) =0

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

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

参数

Name	Type	Description
end_effector_frame	const std::string &	末端执行器坐标系
reference_frame	const std::string &	参考坐标系

返回值

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

note

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

warning

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

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

virtual std::tuple< MotionStatus, std::vector< double > > galbot::sdk::GalbotMotion::get_end_effector_pose_on_chain(
    const std::string &chain_name,
    const std::string frame_id="EndEffector",
    const std::string &reference_frame="base_link"
) =0

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

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

参数

Name	Type	Description
chain_name	const std::string &	链名称
frame_id	const std::string	坐标系ID
reference_frame	const std::string &	参考坐标系

返回值

Type	Description
std::tuple< MotionStatus, std::vector< double > >	元组 (状态, 位姿向量)：状态（成功时为 MotionStatus::SUCCESS，否则为错误码），位姿向量 [x, y, z, qx, qy, qz, qw]（单位：米，四元数），失败时为空

note

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

设置末端执行器姿态

virtual MotionStatus galbot::sdk::GalbotMotion::set_end_effector_pose(
    const std::vector< double > &target_pose,
    const std::string &end_effector_frame,
    const std::string &reference_frame="base_link",
    std::shared_ptr< RobotStates > reference_robot_states=nullptr,
    const bool &enable_collision_check=true,
    const bool &is_blocking=true,
    const double &timeout=-1.0,
    std::shared_ptr< Parameter > params=default_param
) =0

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

笛卡尔运动命令的高级接口。在内部执行 IK、规划轨迹并可选择执行运动。支持阻塞（等待完成）和非阻塞（立即返回）模式。

参数

Name	Type	Description
target_pose	const std::vector< double > &	目标笛卡尔位姿：[x, y, z, qx, qy, qz, qw]（米，四元数）。
end_effector_frame	const std::string &	末端执行器坐标系
reference_frame	const std::string &	参考坐标系
reference_robot_states	std::shared_ptr< RobotStates >	参考机器人起始状态
enable_collision_check	const bool &	是否启用碰撞检查
is_blocking	const bool &	是否阻塞等待完成
timeout	const double &	阻塞模式超时（秒）。当 timeout < 0 且 is_blocking=true 时，使用 params->timeout_second。
params	std::shared_ptr< Parameter >	额外参数

返回值

Type	Description
MotionStatus	MotionStatus： - SUCCESS：阻塞模式下表示运动完成；非阻塞模式下表示命令发送成功。 - TIMEOUT：运动超过超时时间。 - INVALID_INPUT：输入参数无效。 - FAULT：规划或执行失败。

note

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

note

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

warning

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

轨迹规划

virtual std::tuple< MotionStatus, std::unordered_map< std::string, std::vector< std::vector< double > > > > galbot::sdk::GalbotMotion::motion_plan(
    std::shared_ptr< RobotStates > target,
    std::shared_ptr< RobotStates > start=nullptr,
    std::shared_ptr< RobotStates > reference_robot_states=nullptr,
    bool enable_collision_check=true,
    std::shared_ptr< Parameter > params=default_param
) =0

规划单个运动链的轨迹。

参数

Name	Type	Description
target	std::shared_ptr< RobotStates >	目标位姿
start	std::shared_ptr< RobotStates >	起始机器人状态
reference_robot_states	std::shared_ptr< RobotStates >	参考机器人起始状态
enable_collision_check	bool	是否启用碰撞检查
params	std::shared_ptr< Parameter >	额外参数

返回值

Type	Description
std::tuple< MotionStatus, std::unordered_map< std::string, std::vector< std::vector< double > > > >	元组（状态，轨迹映射）： - 状态：规划成功时为 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 错误。

单链多路点轨迹规划

virtual std::tuple< MotionStatus, std::unordered_map< std::string, std::vector< std::vector< double > > > > galbot::sdk::GalbotMotion::motion_plan_multi_waypoints(
    std::shared_ptr< RobotStates > target,
    std::vector< std::vector< double > > targets,
    std::shared_ptr< RobotStates > start=nullptr,
    std::shared_ptr< RobotStates > reference_robot_states=nullptr,
    bool enable_collision_check=true,
    std::shared_ptr< Parameter > params=default_param
) =0

为单条运动链规划多路点轨迹。

参数

Name	Type	Description
target	std::shared_ptr< RobotStates >	定义路点类型的模板状态（PoseState 或 JointStates）并指定运动链名称，状态类型决定了路点数据的格式
targets	std::vector< std::vector< double > >	多路点目标位姿字典（每个运动链对应一个路点序列）
start	std::shared_ptr< RobotStates >	可选起始状态（JointStates）。为 nullptr 时使用当前机器人状态。警告：直接执行时请保持为 nullptr。
reference_robot_states	std::shared_ptr< RobotStates >	参考机器人起始状态
enable_collision_check	bool	是否启用碰撞检查
params	std::shared_ptr< Parameter >	额外参数

返回值

Type	Description
std::tuple< MotionStatus, std::unordered_map< std::string, std::vector< std::vector< double > > > >	元组 (状态, 轨迹映射)：状态（规划成功时为 MotionStatus::SUCCESS，否则为错误码），轨迹映射 {运动链名 -> 路点列表}，平滑轨迹通过所有路点

note

碰撞语义：与 motion_plan() 相同。碰撞工作区间在路点处用 get_support_links() 定义。

note

规划器确保路点处的 C1 连续性（连续速度）。

note

中间路点可能无法精确到达（插值导致）。

多路点轨迹规划

virtual std::tuple< MotionStatus, std::unordered_map< std::string, std::vector< std::vector< double > > > > galbot::sdk::GalbotMotion::motion_plan_multi_waypoints(
    std::unordered_map< std::shared_ptr< RobotStates >, std::vector< std::vector< double > > > targets,
    std::vector< std::shared_ptr< RobotStates > > start={},
    std::shared_ptr< RobotStates > reference_robot_states=nullptr,
    bool enable_collision_check=true,
    std::shared_ptr< Parameter > params=default_param
) =0

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

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

参数

Name	Type	Description
targets	std::unordered_map< std::shared_ptr< RobotStates >, std::vector< std::vector< double > > >	多路点目标位姿字典（每个运动链对应一个路点序列）
start	std::vector< std::shared_ptr< RobotStates > >	起始机器人状态
reference_robot_states	std::shared_ptr< RobotStates >	参考机器人起始状态
enable_collision_check	bool	是否启用碰撞检查
params	std::shared_ptr< Parameter >	额外参数

返回值

Type	Description
std::tuple< MotionStatus, std::unordered_map< std::string, std::vector< std::vector< double > > > >	元组（状态，轨迹映射）： - 状态：规划成功时为 MotionStatus::SUCCESS，否则为错误码 - 轨迹映射：{chain_name -> waypoint_list}（所有运动链）

note

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

note

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

移动全身关节到零位

virtual MotionStatus galbot::sdk::GalbotMotion::move_whole_body_joint_zero(
    bool is_blocking=true,
    double leg_head_speed_rad_s=0.2,
    double leg_head_timeout_s=15.0,
    std::shared_ptr< Parameter > params=default_param
) =0

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

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

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

参数

Name	Type	Description
is_blocking	bool	是否阻塞等待完成
leg_head_speed_rad_s	double	腿部和头部关节速度（弧度/秒）
leg_head_timeout_s	double	腿部和头部运动超时（秒）
params	std::shared_ptr< Parameter >	额外参数

返回值

Type	Description
MotionStatus	运动状态 总体执行状态

检查碰撞

virtual std::tuple< MotionStatus, std::vector< bool > > galbot::sdk::GalbotMotion::check_collision(
    const std::vector< std::shared_ptr< RobotStates > > &start,
    bool enable_collision_check=true,
    std::shared_ptr< Parameter > params=default_param
) =0

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

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

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

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

参数

Name	Type	Description
start	const std::vector< std::shared_ptr< RobotStates > > &	起始机器人状态
enable_collision_check	bool	是否启用碰撞检查
params	std::shared_ptr< Parameter >	额外参数

返回值

Type	Description
std::tuple< MotionStatus, std::vector< bool > >	元组（状态，碰撞结果）： - 状态：检测完成时为 MotionStatus::SUCCESS，否则为错误码 - 碰撞结果：布尔向量（与 start 等长），true 表示检测到碰撞，false 表示无碰撞

note

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

note

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

note

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

附加工具

virtual MotionStatus galbot::sdk::GalbotMotion::attach_tool(
    const std::string &chain,
    const std::string &tool
) =0

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

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

参数

Name	Type	Description
chain	const std::string &	用于挂载工具的运动链（例如 left_arm、right_arm）。
tool	const std::string &	工具信息

返回值

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

note

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

note

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

warning

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

分离工具

virtual MotionStatus galbot::sdk::GalbotMotion::detach_tool(const std::string &chain)=0

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

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

参数

Name	Type	Description
chain	const std::string &	要分离工具的运动链

返回值

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

note

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

添加障碍物

virtual MotionStatus galbot::sdk::GalbotMotion::add_obstacle(
    const std::string &obstacle_id,
    const std::string &obstacle_type,
    const std::vector< double > &pose,
    const std::array< double, 3 > &scale={},
    const std::string &key="",
    const std::string &target_frame="world",
    const std::string &ee_frame="ee_base",
    const std::vector< double > &reference_joint_positions={},
    const std::vector< double > &reference_base_pose={},
    const std::vector< std::string > &ignore_collision_link_names={},
    const double &safe_margin=0,
    const double &resolution=0.01
) =0

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

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

参数

Name	Type	Description
obstacle_id	const std::string &	障碍物唯一标识符（场景中不得重复），后续可用于删除或更新。
obstacle_type	const std::string &	障碍物几何类型
pose	const std::vector< double > &	障碍物位姿：[x, y, z, qx, qy, qz, qw]（米，四元数），相对于 target_frame。
scale	const std::array< double, 3 > &	几何尺寸（米）： - box: [长度, 宽度, 高度] - sphere: [半径, -, -] - cylinder: [半径,高度,-] - mesh/point_cloud: 缩放因子
key	const std::string &	类型特定数据： - mesh/point_cloud: 文件路径（例如 "/path/to/model.stl"） - depth_image: 相机源数据 - robot_state: 机器人状态数据
target_frame	const std::string &	位姿参考坐标系（默认 "world"），可为 "world"、"base_link" 或运动链名称（如 "left_arm"）。
ee_frame	const std::string &	当 target_frame 为运动链名称时，指定链上参考帧（如 "ee_base"、"camera_base"、"camera_object"）。
reference_joint_positions	const std::vector< double > &	用于计算坐标变换的机器人关节状态（弧度）。为空时使用当前机器人状态。
reference_base_pose	const std::vector< double > &	地图坐标系下的机器人基座位姿：[x, y, z, qx, qy, qz, qw]。为空时使用当前定位。
ignore_collision_link_names	const std::vector< std::string > &	忽略碰撞的连杆名称列表
safe_margin	const double &	安全距离缓冲（米）。当距离 < safe_margin 时判定碰撞，默认 0。
resolution	const double &	复杂几何体（mesh/point cloud/depth image）的离散化分辨率（米），默认 0.01。

返回值

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

note

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

note

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

note

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

warning

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

移除障碍物

virtual MotionStatus galbot::sdk::GalbotMotion::remove_obstacle(const std::string &obstacle_id)=0

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

参数

Name	Type	Description
obstacle_id	const std::string &	要移除的障碍物ID

返回值

Type	Description
MotionStatus	运动状态：SUCCESS（成功）、INVALID_INPUT（障碍物 ID 未找到）或 FAULT（故障）

note

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

清空障碍物

virtual MotionStatus galbot::sdk::GalbotMotion::clear_obstacle()=0

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

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

返回值

Type	Description
MotionStatus	运动状态：SUCCESS（成功）或 FAULT（故障）

note

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

note

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

附加目标对象

virtual MotionStatus galbot::sdk::GalbotMotion::attach_target_object(
    const std::string &obstacle_id,
    const std::string &obstacle_type,
    const std::vector< double > &pose,
    const std::array< double, 3 > &scale={},
    const std::string &key="",
    const std::string &target_frame="world",
    const std::string &ee_frame="ee_base",
    const std::vector< double > &reference_joint_positions={},
    const std::vector< double > &reference_base_pose={},
    const std::vector< std::string > &ignore_collision_link_names={},
    const double &safe_margin=0,
    const double &resolution=0.01
) =0

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

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

参数

Name	Type	Description
obstacle_id	const std::string &	要移除的障碍物ID
obstacle_type	const std::string &	障碍物几何类型
pose	const std::vector< double > &	物体位姿：[x, y, z, qx, qy, qz, qw]（米，四元数），在附着时相对于 target_frame。
scale	const std::array< double, 3 > &	几何尺寸（米）：box 为 [length, width, height]；sphere 为 [radius, -, -]；cylinder 为 [radius, height, -]。
key	const std::string &	障碍物唯一标识符
target_frame	const std::string &	附着参考坐标系（默认 "world"）；抓取物体场景通常填写运动链名称（如 "left_arm"）。
ee_frame	const std::string &	当 target_frame 为运动链名称时，指定链上参考帧（如 "ee_base"、"camera_base" 等）。
reference_joint_positions	const std::vector< double > &	用于计算附着变换的机器人关节状态（弧度）。为空时使用当前机器人状态。
reference_base_pose	const std::vector< double > &	地图坐标系下的机器人基座位姿：[x, y, z, qx, qy, qz, qw]。为空时使用当前定位。
ignore_collision_link_names	const std::vector< std::string > &	忽略碰撞的连杆名称列表
safe_margin	const double &	安全距离缓冲（米），默认 0。
resolution	const double &	复杂几何体的离散化分辨率（米），默认 0.01。

返回值

Type	Description
MotionStatus	运动状态：SUCCESS（成功）、INVALID_INPUT（无效输入）或 FAULT（故障）

note

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

note

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

note

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

warning

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

分离目标对象

virtual MotionStatus galbot::sdk::GalbotMotion::detach_target_object(const std::string &obstacle_id)=0

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

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

参数

Name	Type	Description
obstacle_id	const std::string &	要移除的障碍物ID

返回值

Type	Description
MotionStatus	运动状态：SUCCESS（成功）、INVALID_INPUT（障碍物 ID 未找到）或 FAULT（故障）

note

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

设置运动规划配置

virtual MotionStatus galbot::sdk::GalbotMotion::set_motion_plan_config(
    std::shared_ptr< MotionPlanConfig > config
) =0

设置全局运动规划配置。

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

参数

Name	Type	Description
config	std::shared_ptr< MotionPlanConfig >	新的运动规划配置

返回值

Type	Description
MotionStatus	运动状态：- 成功：配置应用成功 - 无效输入：无效的配置参数 - 故障：配置更新失败

note

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

note

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

获取运动规划配置

virtual std::tuple< MotionStatus, MotionPlanConfig > galbot::sdk::GalbotMotion::get_motion_plan_config()=0

获取当前运动规划配置。

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

返回值

Type	Description
std::tuple< MotionStatus, MotionPlanConfig >	元组 (状态, 配置)：状态（成功时为 MotionStatus::SUCCESS，否则为错误码），配置（当前的 MotionPlanConfig 对象，失败时为默认构造）

note

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

获取连杆名称

virtual std::vector< std::string > galbot::sdk::GalbotMotion::get_link_names(bool only_end_effector=false)=0

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

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

参数

Name	Type	Description
only_end_effector	bool	是否仅返回末端执行器连杆，true 仅返回末端执行器/工具连杆，false 返回所有连杆（包括底座、中间连杆等），默认 false（所有连杆）

返回值

Type	Description
std::vector< std::string >	连杆名称字符串向量（如果检索失败则为空）

note

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

note

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

获取支持的连杆

virtual const std::set< std::string > & galbot::sdk::GalbotMotion::get_support_links()=0

获取机器人模型中有效的连杆名称列表。

返回加载的 URDF 运动学模型中定义的所有连杆名称，可用于验证正向运动学查询或 TF 查找。

返回值

Type	Description
const std::set< std::string > &	支持的连杆名称字符串集合的常量引用

note

此集合在初始化期间从机器人 URDF 文件填充。

获取支持的链

virtual const std::set< std::string > & galbot::sdk::GalbotMotion::get_support_chains()=0

获取有效的运动链名称列表。

返回所有预定义运动链的名称（例如 "left_arm"、"right_arm"、"torso"、"left_leg"、"right_leg"）。链是被视为一个单元进行规划和控制的关节组。

返回值

Type	Description
const std::set< std::string > &	支持的运动链名称列表，例如： - "left_arm" - 左臂 - "right_arm" - 右臂 - "torso" - 躯干 - "left_leg" - 左腿 - "right_leg" - 右腿

note

链定义在机器人配置文件中指定。

获取支持的坐标系

virtual const std::set< std::string > & galbot::sdk::GalbotMotion::get_support_frame()=0

获取有效的参考坐标系名称列表。

返回姿态规范支持的标准参考坐标系（例如 "base_link"、"world"、"odom"）。

返回值

Type	Description
const std::set< std::string > &	支持的参考坐标系，例如： - "base_link" - 机器人底座 - "world" - 世界坐标系 - "odom" - 里程计坐标系

note

这些是全局/基座帧；各个连杆帧通过它们访问。

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

virtual const std::set< std::string > & galbot::sdk::GalbotMotion::get_support_ee_frame()=0

获取有效的末端执行器坐标系类型列表。

返回可为末端执行器姿态指定的帧类型（例如 "EndEffector"、"Camera"、"TCP"）。

返回值

Type	Description
const std::set< std::string > &	支持的末端执行器帧类型，例如： - "EndEffector" - 默认末端执行器 - "Camera" - 相机坐标系 - "TCP" - 工具中心点

note

实际连杆名称由链名称 + 帧类型组合派生。

获取支持的工具列表

virtual const std::set< std::string > & galbot::sdk::GalbotMotion::get_support_tool_list()=0

获取可附加的可用工具列表。

返回可通过 attach_tool() 连接的预定义工具（夹持器、传感器、自定义末端执行器）的名称。

返回值

Type	Description
const std::set< std::string > &	支持的工具名称列表，例如夹持器、传感器、自定义末端执行器。

note

工具必须预先配置几何体和运动学偏移。

获取支持的障碍物类型

virtual std::set< std::string > galbot::sdk::GalbotMotion::get_support_obstacle_type()=0

获取支持的碰撞障碍物几何类型列表。

返回 add_obstacle() 和 attach_target_object() 支持的几何类型（例如 "box"、"sphere"、"cylinder"、"mesh"、"point_cloud"、"depth_image"）。

返回值

Type	Description
std::set< std::string >	支持的障碍物几何类型，例如： - "box" - 立方体 - "sphere" - 球体 - "cylinder" - 圆柱体 - "mesh" - 网格模型 - "point_cloud" - 点云 - "depth_image" - 深度图

note

不同类型需要不同的缩放/键参数格式。

获取已构建对象列表

virtual std::vector< std::string > galbot::sdk::GalbotMotion::get_built_object_list()=0

获取规划场景中当前添加的障碍物列表。

返回场景中当前存在的所有障碍物（静态障碍物和附加对象）的障碍物 ID。

返回值

Type	Description
std::vector< std::string >	障碍物ID字符串向量（如果没有障碍物则为空）

note

用于调试场景状态或防止重复 ID。

获取附加对象列表

virtual std::vector< std::string > galbot::sdk::GalbotMotion::get_attached_object_list()=0

获取机器人上当前附加的物体列表。

返回当前附加到机器人的所有障碍物 ID（通过 attach_target_object() 添加）。

返回值

Type	Description
std::vector< std::string >	附加对象ID字符串向量（如果没有附加对象则为空）

note

用于追踪抓取的对象或负载。

检查连杆名称是否有效

virtual bool galbot::sdk::GalbotMotion::is_link_name_valid(
    const std::string &value,
    bool throw_exception=false
) =0

根据机器人模型验证连杆名称。

检查所提供的连杆名称是否存在于加载的 URDF 模型中。

参数

Name	Type	Description
value	const std::string &	要验证的全身关节状态
throw_exception	bool	验证失败时是否抛出异常

返回值

Type	Description
bool	若连杆名称有效则返回 true，否则返回 false。

note

使用 get_support_links() 获取有效连杆名称。

检查链名称是否有效

virtual bool galbot::sdk::GalbotMotion::is_chain_name_valid(
    const std::string &value,
    bool throw_exception=false
) =0

验证运动链名称。

检查机器人配置中是否定义了提供的链名称。

参数

Name	Type	Description
value	const std::string &	要验证的全身关节状态
throw_exception	bool	验证失败时是否抛出异常

返回值

Type	Description
bool	若运动链名称有效则返回 true，否则返回 false。

note

使用 get_support_chains() 获取有效链名称。

检查坐标系名称是否有效

virtual bool galbot::sdk::GalbotMotion::is_frame_name_valid(
    const std::string &value,
    bool throw_exception=false
) =0

验证参考坐标系名称。

检查提供的坐标系名称是否是姿态规范的有效参考坐标系。

参数

Name	Type	Description
value	const std::string &	要验证的参考坐标系名称（如 "base_link"、"world"）。
throw_exception	bool	验证失败时是否抛出异常

返回值

Type	Description
bool	若坐标系名称有效则返回 true，否则返回 false。

note

使用 get_support_frame() 获取有效帧名称。

检查末端执行器坐标系是否有效

virtual bool galbot::sdk::GalbotMotion::is_ee_frame_valid(
    const std::string &value,
    bool throw_exception=false
) =0

验证末端执行器坐标系类型。

检查提供的帧类型对于末端执行器坐标系规格是否有效。

参数

Name	Type	Description
value	const std::string &	要验证的末端执行器坐标系类型（如 "EndEffector"、"Camera"、"TCP"）。
throw_exception	bool	验证失败时是否抛出异常

返回值

Type	Description
bool	若末端执行器坐标系类型有效则返回 true，否则返回 false。

note

使用 get_support_ee_frame() 获取有效帧类型。

检查工具名称是否有效

virtual bool galbot::sdk::GalbotMotion::is_tool_name_valid(
    const std::string &value,
    bool throw_exception=false
) =0

验证工具名称。

检查提供的工具名称是否可用于附件。

参数

Name	Type	Description
value	const std::string &	要验证的全身关节状态
throw_exception	bool	验证失败时是否抛出异常

返回值

Type	Description
bool	若工具名称有效则返回 true，否则返回 false。

note

使用 get_support_tool_list() 获取可用工具列表。

检查障碍物类型是否有效

virtual bool galbot::sdk::GalbotMotion::is_obstacle_type_valid(
    const std::string &value,
    bool throw_exception=false
) =0

验证障碍物几何类型。

检查所提供的类型是否支持障碍物创建。

参数

Name	Type	Description
value	const std::string &	要验证的全身关节状态
throw_exception	bool	验证失败时是否抛出异常

返回值

Type	Description
bool	若障碍物类型有效则返回 true，否则返回 false。

note

使用 get_support_obstacle_type() 获取支持的类型。

检查全身状态是否有效

virtual bool galbot::sdk::GalbotMotion::is_whole_body_state_valid(
    const std::vector< double > &value,
    bool throw_exception=false
) =0

验证全身关节配置向量。

检查提供的矢量是否具有适合全身状态的正确尺寸（机器人自由度）。

参数

Name	Type	Description
value	const std::vector< double > &	要验证的全身关节配置向量（弧度）。
throw_exception	bool	验证失败时是否抛出异常

返回值

Type	Description
bool	若向量长度与机器人自由度匹配则返回 true，否则返回 false。

note

预期大小：get_robot_dof() 个元素。

note

不验证关节限制合规性，仅验证向量维度。

检查7维姿态是否有效

virtual bool galbot::sdk::GalbotMotion::is_pose_7d_valid(
    const std::vector< double > &value,
    bool throw_exception=false
) =0

验证 7D 姿态向量（位置 + 四元数）。

检查提供的姿态向量是否恰好有 7 个元素：[x, y, z, qx, qy, qz, qw]。

参数

Name	Type	Description
value	const std::vector< double > &	要验证的 7D 位姿向量。
throw_exception	bool	验证失败时是否抛出异常

返回值

Type	Description
bool	若向量长度为 7（[x,y,z,qx,qy,qz,qw]）则返回 true，否则返回 false。

note

不强制四元数归一化；仅检查维度。

warning

使用未归一化的四元数将导致运动学中的不确定行为。

检查链关节状态是否有效

virtual bool galbot::sdk::GalbotMotion::is_chain_joint_state_valid(
    const std::unordered_map< std::string, std::vector< double > > &value,
    bool throw_exception=false
) =0

验证链索引关节配置图。

检查链名称是否有效以及每个链的关节向量是否具有正确的维度。

参数

Name	Type	Description
value	const std::unordered_map< std::string, std::vector< double > > &	要验证的全身关节状态
throw_exception	bool	验证失败时是否抛出异常

返回值

Type	Description
bool	若所有运动链名称和向量长度均有效则返回 true，否则返回 false。

note

验证链名称存在性和关节向量维度。

获取机器人自由度

virtual int galbot::sdk::GalbotMotion::get_robot_dof()=0

获取机器人总自由度 (DOF)。

返回完整机器人（全身）中驱动关节的数量，用于验证关节状态向量维度。

返回值

Type	Description
int	机器人自由度（驱动关节）数量

note

典型的人形移动机械臂：15-30 自由度。

获取机器人状态

virtual RobotStates galbot::sdk::GalbotMotion::get_robot_states()=0

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

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

返回值

Type	Description
RobotStates	机器人状态对象包含：whole_body_joint（完整的关节配置，单位：弧度），base_state（移动底座位姿 [x, y, z, qx, qy, qz, qw]，单位：米，四元数）

note

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

note

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

获取全身状态

virtual std::vector< double > galbot::sdk::GalbotMotion::get_whole_body_state()=0

获取当前全身关节配置。

检索机器人中所有驱动关节的关节角度。

返回值

Type	Description
std::vector< double >	关节角度向量（弧度）

note

关节排序由机器人 URDF/配置定义。

获取底盘状态

virtual std::vector< double > galbot::sdk::GalbotMotion::get_chassis_state()=0

获取当前移动基础姿态。

检索机器人移动底座在地图坐标系中的位置和方向。

返回值

Type	Description
std::vector< double >	基座位姿向量：[x, y, z, qx, qy, qz, qw]（米，单位四元数）

note

对于非移动机器人，通常返回单位位姿。

note

位姿来自定位/里程计系统。

获取链关节状态

virtual std::unordered_map< std::string, std::vector< double > > galbot::sdk::GalbotMotion::get_chain_joint_state() =0

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

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

返回值

Type	Description
std::unordered_map< std::string, std::vector< double > >	映射 {运动链名 -> 关节配置}（单位：弧度）对应每个运动链，例如：{"left_arm" -> [7 个关节角度], "right_arm" -> [7 个关节角度]}

note

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

获取链姿态状态

virtual std::unordered_map< std::string, std::vector< double > > galbot::sdk::GalbotMotion::get_chain_pose_state(
    const std::string &frame="base_link"
) =0

获取所有运动链的当前笛卡尔姿态。

计算所有链末端执行器的正向运动学，返回它们在指定参考坐标系中的位姿。

参数

Name	Type	Description
frame	const std::string &	参考坐标系

返回值

Type	Description
std::unordered_map< std::string, std::vector< double > >	映射 {运动链名 -> 位姿向量}，其中位姿向量是每个运动链末端执行器的 [x, y, z, qx, qy, qz, qw]（米，四元数）

note

比 get_chain_joint_state() 计算量更大，可用于获取末端执行器相对于指定帧的位姿。

替换关节状态

virtual bool galbot::sdk::GalbotMotion::replace_joint_state(
    const std::string &chain_name,
    const std::vector< double > &chain_joint,
    std::vector< double > &whole_body_joint
) =0

更新全身配置中的特定链条关节。

用于修改完整的全身关节向量内的链的关节值，同时保留其他链的状态的效用函数。

参数

Name	Type	Description
chain_name	const std::string &	链名称
chain_joint	const std::vector< double > &	要更新的链关节
whole_body_joint	std::vector< double > &	原始全身关节向量

返回值

Type	Description
bool	替换成功返回 true；若运动链名称无效或尺寸不匹配则返回 false。

note

whole_body_joint 就地修改；请确保维度正确。

note

用于离线状态操作或自定义规划种子。

状态转字符串

virtual std::string galbot::sdk::GalbotMotion::status_to_string(MotionStatus status)=0

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

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

参数

Name	Type	Description
status	MotionStatus	运动状态枚举值

返回值

Type	Description
std::string	描述性状态字符串（例如，"SUCCESS: 执行成功"，"TIMEOUT: 执行超时"）

note

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

获取实例

static GalbotMotion & galbot::sdk::GalbotMotion::get_instance(MachineType m)

用于选择具体运动规划单例的运行时工厂。

参数

Name	Type	Description
m	MachineType	机器类型

返回值

Type	Description
GalbotMotion &	指定机器类型的单例运动接口引用。

---

移动导航

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

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

析构函数

virtual galbot::sdk::GalbotNavigation::~GalbotNavigation()=default

初始化

virtual bool galbot::sdk::GalbotNavigation::init()=0

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

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

返回值

Type	Description
bool	初始化成功返回 true，否则返回 false。

note

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

note

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

warning

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

重定位

virtual NavigationStatus galbot::sdk::GalbotNavigation::relocalize(const Pose &init_pose)=0

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

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

参数

Name	Type	Description
init_pose	const Pose &	初始姿态估计

返回值

Type	Description
NavigationStatus	导航状态，指示重定位请求的结果。详见 NavigationStatus 枚举的取值说明。

note

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

note

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

检查是否已定位

virtual bool galbot::sdk::GalbotNavigation::is_localized()=0

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

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

返回值

Type	Description
bool	若机器人已可靠定位则返回 true；若定位丢失或不确定则返回 false。

note

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

note

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

获取当前姿态

virtual Pose galbot::sdk::GalbotNavigation::get_current_pose()=0

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

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

返回值

Type	Description
Pose	结构包含以下字段：- x: X坐标（米，地图坐标系） - y: Y坐标（米，地图坐标系） - theta: 方向（弧度，地图坐标系，逆时针从 x 轴算起）

note

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

note

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

导航到目标

virtual NavigationStatus galbot::sdk::GalbotNavigation::navigate_to_goal(
    const Pose &goal_pose,
    bool enable_collision_check=true,
    bool is_blocking=false,
    float timeout=8,
    bool omni_plan=true
) =0

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

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

参数

Name	Type	Description
goal_pose	const Pose &	目标位姿（地图坐标系）
enable_collision_check	bool	是否启用碰撞检查
is_blocking	bool	执行模式标志。 - true（阻塞）：阻塞直到到达目标、失败或超时。 - false（非阻塞）：发送导航命令后立即返回。
timeout	float	阻塞模式下的最大等待时间（秒），默认值：8.0 秒，仅在 is_blocking 为 true 时相关，如果在时间内未到达目标，则返回超时状态
omni_plan	bool	运动规划模式标志。 - true: 启用全向运动规划（各向同性移动） - false: 使用有限方向的运动规划

返回值

Type	Description
NavigationStatus	导航状态指示结果：- 非阻塞模式：命令接受状态 - 阻塞模式：最终导航结果（成功、失败、超时）

note

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

note

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

note

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

warning

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

直线移动到目标

virtual NavigationStatus galbot::sdk::GalbotNavigation::move_straight_to(
    const Pose &goal_pose,
    bool is_blocking=true,
    float timeout=8
) =0

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

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

参数

Name	Type	Description
goal_pose	const Pose &	相对于当前机器人底座帧的目标位姿。 包含： - x: 前后位移（米） - y: 左右位移（米） - theta: 转向角度（弧度）
is_blocking	bool	执行模式标志。 - true (阻塞): 阻塞直到运动完成、失败或超时 - false (非阻塞): 发送导航命令后立即返回
timeout	float	阻塞模式最大等待时间（秒），默认 8.0 秒；仅在 is_blocking 为 true 时生效。

返回值

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

note

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

note

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

note

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

warning

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

warning

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

停止导航

virtual NavigationStatus galbot::sdk::GalbotNavigation::stop_navigation()=0

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

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

返回值

Type	Description
NavigationStatus	导航状态指示是否成功将停止命令发送到导航系统。

note

可在导航期间随时调用。

note

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

note

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

检查路径可达性

virtual bool galbot::sdk::GalbotNavigation::check_path_reachability(
    const Pose &goal_pose,
    const Pose &start_pose
) =0

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

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

参数

Name	Type	Description
goal_pose	const Pose &	目标位姿（地图坐标系）
start_pose	const Pose &	起始位姿

返回值

Type	Description
bool	若起点到目标存在无碰撞路径则返回 true；若未找到有效路径则返回 false。

note

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

note

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

note

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

检查目标到达

virtual bool galbot::sdk::GalbotNavigation::check_goal_arrival()=0

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

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

返回值

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

note

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

note

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

note

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

获取导航状态

virtual NavigationTaskStatus galbot::sdk::GalbotNavigation::get_navigation_status()=0

获取当前导航任务状态。

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

返回值

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

note

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

获取实例

static GalbotNavigation & galbot::sdk::GalbotNavigation::get_instance(MachineType m)

用于选择具体导航单例的运行时工厂。

这种静态工厂方法允许在运行时根据机器人机器类型选择导航实现。方法声明驻留在接口标头中以实现编译时可用性，而实际的实现逻辑（包括特定于平台的 include 和 switch 语句）包含在相应的 .cpp 文件中。这种设计保持接口干净，同时启用特定于平台的实例化，而无需暴露实现细节。

参数

Name	Type	Description
m	MachineType	机器类型

返回值

Type	Description
GalbotNavigation &	指定机器类型的单例导航接口引用。

note

添加新机器类型支持需要更新此类。

---

类型与枚举

驱动类型

指定在运动规划和执行期间应启动哪些运动链。这控制机器人是否仅使用目标手臂，或者还涉及躯干或腿部运动。

Enum Value	Description
ACTUATE_WITH_CHAIN_ONLY	仅执行目标运动链
ACTUATE_WITH_TORSO	执行目标运动链和躯干
ACTUATE_WITH_LEG	执行目标运动链和腿部
ACTUATE_TYPE_NUM	驱动类型数量

---

音频数据

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

成员变量

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

---

电池管理信息

电池管理系统 (BMS) 信息。

成员变量

Name	Type	Description
voltage	float	电压
current	float	电流 (A)
battery_level	float	电池电量
temperature	float	温度
charging_status	bool	充电状态
health_status	bool	健康状态
capacity	float	容量

---

相机信息

完整的相机标定数据，包括内参、畸变系数、校正和投影矩阵。与 ROS 2 的 sensor_msgs/CameraInfo 消息类型兼容。

成员变量

Name	Type	Description
header	Header	包含时间戳和相机坐标系 ID（例如 "camera_optical_frame"）
height	uint32_t	校准期间此相机生成的图像垂直分辨率
width	uint32_t	校准期间此相机生成的图像水平分辨率
distortion_model	std::string	指定使用的镜头畸变模型。 常见值： - "plumb_bob": Brown-Conrady 模型（径向 k1/k2/k3 和切向 p1/p2 畸变） - "rational_polynomial": 扩展模型（包含额外参数） - "equidistant": 鱼眼镜头模型
d	std::vector< double >	畸变参数向量，大小和解释取决于畸变模型。 例如 "plumb_bob" 模型：[k1, k2, p1, p2, k3] - k1, k2, k3: 径向畸变系数 - p1, p2: 切向畸变系数
k	std::array< double, 9 >	3×3 矩阵（行优先顺序），将相机坐标系中的 3D 点映射到 2D 像素坐标： fx 0 cx 0 fy cy 0 0 1 fx, fy: 焦距（像素单位） cx, cy: 主点（光学中心）坐标（像素）
r	std::array< double, 9 >	3×3 旋转矩阵（行优先顺序）。 对于立体相机：旋转左/右相机图像平面使其共面。
p	std::array< double, 12 >	3×4 投影矩阵（行优先顺序），将 3D 点投影到校正后的图像坐标。 fx', fy': 校正后的焦距 cx', cy': 校正后的主点 Tx, Ty: 平移分量（立体相机）
binning_x	uint32_t	水平方向像素合并数。 - 0 或 1: 不合并 - 2: 每 2 个像素合并为 1 个输出像素 - 4: 每 4 个像素合并为 1 个输出像素
binning_y	uint32_t	垂直方向像素合并数。 - 0 或 1: 不合并 - 2: 每 2 个像素合并为 1 个输出像素 - 4: 每 4 个像素合并为 1 个输出像素
roi	RegionOfInterest	感兴趣区域
camera_type	std::string	可选字段，指定相机类型或型号，例如："monocular"、"stereo_left"、"stereo_right"、"depth"
T	std::vector< double >	可选的变换矩阵，用于厂商特定或扩展的标定数据。大小和解释取决于具体实现。

---

运动链类型

识别机器人结构中的不同运动链，以进行正向/反向运动学计算和运动规划。

Enum Value	Description
HEAD	头部
LEFT_ARM	左臂
RIGHT_ARM	右臂
LEG	腿部
TORSO	躯干
CHAIN_NUM	运动链数量

---

碰撞检查选项

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

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

启用或禁用自碰撞检测

void galbot::sdk::CollisionCheckOption::set_disable_self_collision_check(bool disable)

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

参数

Name	Type	Description
disable	bool	传入 true 表示禁用自碰撞检测，传入 false 表示启用。

warning

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

启用或禁用环境碰撞检测

void galbot::sdk::CollisionCheckOption::set_disable_env_collision_check(bool disable)

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

参数

Name	Type	Description
disable	bool	是否禁用碰撞检测

warning

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

检查自碰撞检测是否禁用

bool galbot::sdk::CollisionCheckOption::get_disable_self_collision_check() const

检查自碰撞检测是否禁用

返回值

Type	Description
bool	若当前已禁用自碰撞检测，则返回 true；否则返回 false。

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

bool galbot::sdk::CollisionCheckOption::get_disable_env_collision_check() const

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

返回值

Type	Description
bool	若当前已禁用环境碰撞检测，则返回 true；否则返回 false。

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

void galbot::sdk::CollisionCheckOption::print() const

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

---

控制状态

控制命令执行状态枚举。

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

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

---

深度数据

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

深度图转 OpenCV Mat

std::shared_ptr< cv::Mat > galbot::sdk::DepthData::convert_to_cv2_mat()

将深度数据解码并转换为 OpenCV Mat 格式以进行处理。

返回值

Type	Description
std::shared_ptr< cv::Mat >	解码成功时返回 std::shared_ptr<cv::Mat> 智能指针；解码失败时返回空指针。

成员变量

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

---

设备信息

描述有关机器人或模块的基本信息，用于设备管理、日志记录、诊断和维护跟踪。

成员变量

Name	Type	Description
model	std::string	设备型号名称或标识符
serial_number	std::string	设备序列号
firmware_version	std::string	系统固件版本字符串
hardware_version	std::string	硬件版本或修订号
manufacturer	std::string	制造商名称或公司标识符

---

灵巧手状态

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

成员变量

Name	Type	Description
timestamp_ns	int64_t	状态时间戳（自纪元以来的纳秒数）
joint_state	JointStateMessage	灵巧手关节状态消息
force_sensor_map	std::unordered_map< std::string, EffortInfo >	命名力传感器映射（Sharpa；其他为空）

---

灵巧手类型

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

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

---

力矩信息

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

成员变量

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

---

错误

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

构造函数

galbot::sdk::Error::Error(std::string commpent_input, int error_code_input, std::string description_input)

构造函数

参数

Name	Type	Description
commpent_input	std::string	组件名称
error_code_input	int	错误代码
description_input	std::string	错误描述

成员变量

Name	Type	Description
commpent	std::string	组件
error_code	uint64_t	用于程序化错误处理的数值错误代码
description	std::string	错误描述

---

错误信息

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

成员变量

Name	Type	Description
timestamp_ns	int64_t	收集错误的时间戳（自纪元以来的纳秒数）
error_vec	std::vector< Error >	误差向量

---

力数据

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

成员变量

Name	Type	Description
timestamp_ns	int64_t	测量时间戳（自纪元以来的纳秒数）
force	Vector3	力
torque	Vector3	力矩向量（牛顿·米）：[tx, ty, tz]

---

坐标系

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

成员变量

Name	Type	Description
header	Header
body_frame_id	std::string
reference_frame_id	std::string
pose	std::optional< Pose >
twist	std::optional< Twist >
wrench	std::optional< Wrench >

---

SDK日志流

构造函数

galbot::sdk::GalbotSdkLogStream::GalbotSdkLogStream(
    LogLevel level,
    const char *file,
    const char *func,
    int line
)

参数

Name	Type	Description
level	LogLevel
file	const char *
func	const char *
line	int

operator<<

GalbotSdkLogStream & galbot::sdk::GalbotSdkLogStream::operator<<(const T &v)

参数

Name	Type	Description
v	const T &

operator<<

GalbotSdkLogStream & galbot::sdk::GalbotSdkLogStream::operator<<(std::ostream &(*manip)(std::ostream &))

参数

Name	Type	Description
manip	std::ostream &(*)(std::ostream &)

析构函数

galbot::sdk::GalbotSdkLogStream::~GalbotSdkLogStream() noexcept

---

夹爪状态

析构函数，销毁日志流对象

成员变量

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

---

关节组命令

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

成员变量

Name	Type	Description
time_from_start_s	double
joint_commands	std::vector< JointCommand >

---

消息头

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

成员变量

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

---

IK 求解器配置

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

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

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

void galbot::sdk::IKSolverConfig::set_col_aware_ik_timeout(double timeout)

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

参数

Name	Type	Description
timeout	double	求解超时（毫秒）

note

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

设置种子类型

void galbot::sdk::IKSolverConfig::set_seed_type(SeedType type)

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

参数

Name	Type	Description
type	SeedType	种子生成方法

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

void galbot::sdk::IKSolverConfig::set_col_aware_ik_joint_limit_bias(double bias)

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

参数

Name	Type	Description
bias	double	关节限制禁忌区域的距离阈值（单位：弧度）

note

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

设置笛卡尔位置误差容差

void galbot::sdk::IKSolverConfig::set_translation_eps(const std::array< double, 3 > &eps)

设置平移收敛容差（米）

参数

Name	Type	Description
eps	const std::array< double, 3 > &	每轴位置误差容差 {x, y, z}（单位：米）

note

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

设置方向误差容差

void galbot::sdk::IKSolverConfig::set_rotation_eps(const std::array< double, 3 > &eps)

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

参数

Name	Type	Description
eps	const std::array< double, 3 > &	按轴给出的方向误差容差 {roll, pitch, yaw}（单位：弧度）

note

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

启用或禁用碰撞检测日志

void galbot::sdk::IKSolverConfig::set_enable_collision_check_log(bool enable)

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

参数

Name	Type	Description
enable	bool	true 以输出碰撞检测日志，false 以抑制日志

note

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

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

double galbot::sdk::IKSolverConfig::get_col_aware_ik_timeout() const

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

返回值

Type	Description
double	超时持续时间（单位：毫秒）

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

SeedType galbot::sdk::IKSolverConfig::get_seed_type() const

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

返回值

Type	Description
SeedType	当前种子生成方法

获取关节限制安全裕度

double galbot::sdk::IKSolverConfig::get_col_aware_ik_joint_limit_bias() const

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

返回值

Type	Description
double	关节限制偏置距离（单位：弧度）

获取笛卡尔位置误差容差

const std::array< double, 3 > & galbot::sdk::IKSolverConfig::get_translation_eps() const

获取平移收敛容差（米）

返回值

Type	Description
const std::array< double, 3 > &	每轴位置误差容差 {x, y, z}（单位：米）

获取方向误差容差

const std::array< double, 3 > & galbot::sdk::IKSolverConfig::get_rotation_eps() const

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

返回值

Type	Description
const std::array< double, 3 > &	按轴给出的姿态容差 {roll, pitch, yaw}（单位：弧度）。

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

bool galbot::sdk::IKSolverConfig::get_enable_collision_check_log() const

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

返回值

Type	Description
bool	启用碰撞检测日志时返回 true，禁用时返回 false。

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

void galbot::sdk::IKSolverConfig::print() const

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

嵌套枚举

随机种子类型

逆运动学求解种子类型枚举

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

---

IMU数据

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

成员变量

Name	Type	Description
timestamp_ns	int64_t	测量时间戳（自纪元以来的纳秒数）
accel	Vector3	线加速度（米/秒²）：[ax, ay, az]。
gyro	Vector3	陀螺仪数据
magnet	Vector3	磁力计数据

---

关节命令

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

成员变量

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

---

单关节状态

单关节状态结构。

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

单关节状态

galbot::sdk::JointState::JointState()=default

单关节状态结构。

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

构造函数

galbot::sdk::JointState::JointState(
    double position_input,
    double velocity_input,
    double acceleration_input,
    double effort_input,
    double current_input
)

构造函数，

使用输入参数初始化关节状态

参数

Name	Type	Description
position_input	double	位置输入
velocity_input	double	速度输入
acceleration_input	double	加速度输入
effort_input	double	关节力矩/effort（牛顿·米，N·m）。
current_input	double	电流输入

成员变量

Name	Type	Description
position	double	关节角位置（弧度）
velocity	double	关节角速度（弧度/秒）
acceleration	double	关节角加速度（弧度/秒²）
effort	double	关节力矩（牛顿·米，N·m）。
current	double	关节电流（安培）

---

关节状态消息

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

成员变量

Name	Type	Description
timestamp_ns	int64_t	采集时间戳（自纪元以来的纳秒数）
joint_state_vec	std::vector< JointState >	关节状态向量

---

关节状态

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

获取类型

Type galbot::sdk::JointStates::get_type() const override

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

返回值

Type	Description
Type	，指示这是关节空间目标

设置关节位置

void galbot::sdk::JointStates::set_joint_positions(const std::vector< double > &joints)

设置所有关节位置

参数

Name	Type	Description
joints	const std::vector< double > &	关节状态列表

note

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

设置关节

void galbot::sdk::JointStates::set_joint(int index, int val)

设置指定索引的关节值

参数

Name	Type	Description
index	int	关节索引
val	int	关节值数组

note

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

warning

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

成员变量

Name	Type	Description
joint_positions	std::vector< double >	链的目标关节配置

---

运动学边界

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

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

设置运动链名称

void galbot::sdk::KinematicsBoundary::set_chain_name(const std::string &name)

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

参数

Name	Type	Description
name	const std::string &	边界名称

设置下限位置限制

void galbot::sdk::KinematicsBoundary::set_lower_limit(const std::vector< double > &limits)

设置关节位置下限

参数

Name	Type	Description
limits	const std::vector< double > &	每个关节的下限位置限制向量

note

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

设置上限位置限制

void galbot::sdk::KinematicsBoundary::set_upper_limit(const std::vector< double > &limits)

设置关节位置上限

参数

Name	Type	Description
limits	const std::vector< double > &	每个关节的上限位置限制向量

note

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

设置下限速度限制

void galbot::sdk::KinematicsBoundary::set_vel_lower_limit(const std::vector< double > &limits)

设置速度下限

参数

Name	Type	Description
limits	const std::vector< double > &	每个关节的速度下限向量（单位：rad/s）。

note

双向关节通常为负值。

设置上限速度限制

void galbot::sdk::KinematicsBoundary::set_vel_upper_limit(const std::vector< double > &limits)

设置速度上限

参数

Name	Type	Description
limits	const std::vector< double > &	每个关节的速度上限向量（单位：rad/s）。

note

双向关节通常为正值。

设置下限加速度限制

void galbot::sdk::KinematicsBoundary::set_acc_lower_limit(const std::vector< double > &limits)

设置加速度下限

参数

Name	Type	Description
limits	const std::vector< double > &	每个关节的加速度下限向量（单位：rad/s²）。

note

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

设置上限加速度限制

void galbot::sdk::KinematicsBoundary::set_acc_upper_limit(const std::vector< double > &limits)

设置加速度上限

参数

Name	Type	Description
limits	const std::vector< double > &	每个关节的加速度上限向量（单位：rad/s²）。

note

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

设置下限加加速度限制

void galbot::sdk::KinematicsBoundary::set_jerk_lower_limit(const std::vector< double > &limits)

设置加加速度下限

参数

Name	Type	Description
limits	const std::vector< double > &	每个关节的加加速度下限向量（单位：rad/s³）。

note

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

设置上限加加速度限制

void galbot::sdk::KinematicsBoundary::set_jerk_upper_limit(const std::vector< double > &limits)

设置加加速度上限

参数

Name	Type	Description
limits	const std::vector< double > &	每个关节的加加速度上限向量（单位：rad/s³）。

note

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

获取运动链名称

const std::string & galbot::sdk::KinematicsBoundary::get_chain_name() const

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

返回值

Type	Description
const std::string &	运动链名称字符串的常量引用

获取下限位置限制

const std::vector< double > & galbot::sdk::KinematicsBoundary::get_lower_limit() const

获取关节位置下限（rad）

返回值

Type	Description
const std::vector< double > &	向量下限位置限制（每个关节，单位：弧度）

获取上限位置限制

const std::vector< double > & galbot::sdk::KinematicsBoundary::get_upper_limit() const

获取关节位置上限（rad）

返回值

Type	Description
const std::vector< double > &	向量上限位置限制（每个关节，单位：弧度）

获取下限速度限制

const std::vector< double > & galbot::sdk::KinematicsBoundary::get_vel_lower_limit() const

获取速度下限（rad/s）

返回值

Type	Description
const std::vector< double > &	向量下限速度限制（每个关节，单位：弧度/秒）

获取上限速度限制

const std::vector< double > & galbot::sdk::KinematicsBoundary::get_vel_upper_limit() const

获取速度上限（rad/s）

返回值

Type	Description
const std::vector< double > &	向量上限速度限制（每个关节，单位：弧度/秒）

获取下限加速度限制

const std::vector< double > & galbot::sdk::KinematicsBoundary::get_acc_lower_limit() const

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

返回值

Type	Description
const std::vector< double > &	常量引用，向量下限加速度限制（单位：rad/s²）

获取上限加速度限制

const std::vector< double > & galbot::sdk::KinematicsBoundary::get_acc_upper_limit() const

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

返回值

Type	Description
const std::vector< double > &	常量引用：每个关节的加速度上限向量（单位：rad/s²）。

获取下限加加速度限制

const std::vector< double > & galbot::sdk::KinematicsBoundary::get_jerk_lower_limit() const

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

返回值

Type	Description
const std::vector< double > &	向量下限加加速度限制（每个关节，单位：rad/s³）

获取上限加加速度限制

const std::vector< double > & galbot::sdk::KinematicsBoundary::get_jerk_upper_limit() const

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

返回值

Type	Description
const std::vector< double > &	向量上限加加速度限制（每个关节，单位：rad/s³）

打印输出

void galbot::sdk::KinematicsBoundary::print() const

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

---

激光雷达数据

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

成员变量

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

---

直线轨迹碰撞检测基元

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

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

设置直线检查基元类型

void galbot::sdk::LineTrajCheckPrimitive::set_line_check_primitive_type(PrimitiveType type)

设置直线检查基元类型

参数

Name	Type	Description
type	PrimitiveType	直线轨迹类型

note

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

设置圆柱体基元半径

void galbot::sdk::LineTrajCheckPrimitive::set_cylinder_prim_radius(double radius)

设置圆柱基元半径（米）

参数

Name	Type	Description
radius	double	轨迹曲率半径

note

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

note

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

设置直线基元曲率

void galbot::sdk::LineTrajCheckPrimitive::set_line_prim_curvature(double curvature)

设置直线基元曲率

参数

Name	Type	Description
curvature	double	曲线曲率

note

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

note

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

获取直线检查基元类型

PrimitiveType galbot::sdk::LineTrajCheckPrimitive::get_line_check_primitive_type() const

获取直线检查基元类型

返回值

Type	Description
PrimitiveType	当前基元类型（LINE 或 CYLINDER）

获取圆柱体基元半径

double galbot::sdk::LineTrajCheckPrimitive::get_cylinder_prim_radius() const

获取圆柱基元半径（米）

返回值

Type	Description
double	圆柱体基元半径（单位：米）

获取直线基元曲率

double galbot::sdk::LineTrajCheckPrimitive::get_line_prim_curvature() const

获取直线基元曲率

返回值

Type	Description
double	直线基元曲率

打印输出

void galbot::sdk::LineTrajCheckPrimitive::print() const

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

嵌套枚举

几何基元类型

直线轨迹检查基元类型枚举

Enum Value	Description
LINE	直线
CYLINDER	圆柱体

---

日志配置

定义日志系统的配置参数，包括文件设置、日志级别和输出选项。

成员变量

Name	Type	Description
path	std::string	路径
file_name	std::string	文件名
file_max_size	uint64_t	最大文件大小
file_max_num	uint64_t	最大文件数
level	LogLevel	级别
console_output	bool	控制台输出

---

日志信息

日志信息。

成员变量

Name	Type	Description
level	std::string
message	std::string	消息

---

日志级别

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

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

---

机器类型

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

Enum Value	Description
S1	S1机器人

---

运动规划配置

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

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

构造函数

galbot::sdk::MotionPlanConfig::MotionPlanConfig()=default

运动规划配置类

设置更新时间

void galbot::sdk::MotionPlanConfig::set_update_time(int64_t t)

设置更新时间参数

参数

Name	Type	Description
t	int64_t	时间参数

note

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

获取更新时间

int64_t galbot::sdk::MotionPlanConfig::get_update_time()

获取更新时间参数

返回值

Type	Description
int64_t	更新时间（单位：秒）

创建采样器配置

std::shared_ptr< SamplerConfig > galbot::sdk::MotionPlanConfig::create_sampler_config()

创建采样器配置并返回

返回值

Type	Description
std::shared_ptr< SamplerConfig >	采样器配置的共享指针

创建轨迹规划配置

std::shared_ptr< TrajectoryPlanConfig > galbot::sdk::MotionPlanConfig::create_trajectory_plan_config()

创建轨迹规划配置并返回

返回值

Type	Description
std::shared_ptr< TrajectoryPlanConfig >	轨迹规划配置的共享指针

创建IK 求解器配置

std::shared_ptr< IKSolverConfig > galbot::sdk::MotionPlanConfig::create_ik_solver_config()

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

返回值

Type	Description
std::shared_ptr< IKSolverConfig >	IK 求解器配置的共享指针

创建碰撞检查选项

std::shared_ptr< CollisionCheckOption > galbot::sdk::MotionPlanConfig::create_collision_check_option()

创建碰撞检测选项并返回

返回值

Type	Description
std::shared_ptr< CollisionCheckOption >	碰撞检查选项的共享指针

创建轨迹可行性检查选项

std::shared_ptr< TrajectoryFeasibilityCheckOption > galbot::sdk::MotionPlanConfig::create_trajectory_feasibility_check_option()

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

返回值

Type	Description
std::shared_ptr< TrajectoryFeasibilityCheckOption >	轨迹可行性检查选项的共享指针

创建直线轨迹检查基元

std::shared_ptr< LineTrajCheckPrimitive > galbot::sdk::MotionPlanConfig::create_line_traj_check_primitive()

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

返回值

Type	Description
std::shared_ptr< LineTrajCheckPrimitive >	直线轨迹检查基元的共享指针

设置采样器配置

void galbot::sdk::MotionPlanConfig::set_sampler_config(const std::shared_ptr< SamplerConfig > &config)

设置采样器配置

参数

Name	Type	Description
config	const std::shared_ptr< SamplerConfig > &	采样器配置的共享指针；传入 nullptr 清除配置。

设置轨迹规划配置

void galbot::sdk::MotionPlanConfig::set_trajectory_plan_config(
    const std::shared_ptr< TrajectoryPlanConfig > &config
)

设置轨迹规划配置

参数

Name	Type	Description
config	const std::shared_ptr< TrajectoryPlanConfig > &	新的运动规划配置

设置IK 求解器配置

void galbot::sdk::MotionPlanConfig::set_ik_solver_config(const std::shared_ptr< IKSolverConfig > &config)

设置逆运动学求解器配置

参数

Name	Type	Description
config	const std::shared_ptr< IKSolverConfig > &	IK 求解器配置的共享指针；传入 nullptr 清除配置。

设置碰撞检查选项

void galbot::sdk::MotionPlanConfig::set_collision_check_option(
    const std::shared_ptr< CollisionCheckOption > &option
)

设置碰撞检测选项

参数

Name	Type	Description
option	const std::shared_ptr< CollisionCheckOption > &	碰撞检查选项的共享指针；传入 nullptr 清除选项。

设置轨迹可行性检查选项

void galbot::sdk::MotionPlanConfig::set_trajectory_feasibility_check_option(
    const std::shared_ptr< TrajectoryFeasibilityCheckOption > &option
)

设置轨迹可行性检查选项

参数

Name	Type	Description
option	const std::shared_ptr< TrajectoryFeasibilityCheckOption > &	选项

设置可行性边界

void galbot::sdk::MotionPlanConfig::set_feasibility_boundary(
    const std::vector< KinematicsBoundary > &boundary
)

设置可行性边界约束

参数

Name	Type	Description
boundary	const std::vector< KinematicsBoundary > &	运动学边界向量，每个运动链一个

note

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

设置直线轨迹检查基元

void galbot::sdk::MotionPlanConfig::set_line_traj_check_primitive(
    const std::shared_ptr< LineTrajCheckPrimitive > &primitive
)

设置直线轨迹检查基元

参数

Name	Type	Description
primitive	const std::shared_ptr< LineTrajCheckPrimitive > &	运动基元

设置IK 关节约束

void galbot::sdk::MotionPlanConfig::set_ik_joint_limit(const std::vector< KinematicsBoundary > &boundary)

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

参数

Name	Type	Description
boundary	const std::vector< KinematicsBoundary > &	IK 求解器关节约束的运动学边界向量

note

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

设置采样关节约束

void galbot::sdk::MotionPlanConfig::set_sampler_joint_limit(const std::vector< KinematicsBoundary > &boundary)

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

参数

Name	Type	Description
boundary	const std::vector< KinematicsBoundary > &	采样算法的运动学边界向量

note

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

设置硬关节约束

void galbot::sdk::MotionPlanConfig::set_hard_joint_limit(const std::vector< KinematicsBoundary > &boundary)

设置硬关节位置限制边界

参数

Name	Type	Description
boundary	const std::vector< KinematicsBoundary > &	边界约束

note

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

设置是否恢复 IK 关节限制

void galbot::sdk::MotionPlanConfig::set_revert_ik_joint_limit(bool flag)

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

参数

Name	Type	Description
flag	bool	标志位

note

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

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

void galbot::sdk::MotionPlanConfig::set_revert_ik_joint_limit_chains(const std::vector< std::string > &chains)

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

参数

Name	Type	Description
chains	const std::vector< std::string > &	运动链列表

note

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

note

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

获取采样器配置

std::shared_ptr< SamplerConfig > galbot::sdk::MotionPlanConfig::get_sampler_config() const

获取采样器配置

返回值

Type	Description
std::shared_ptr< SamplerConfig >	采样器配置的共享指针；未设置时返回 nullptr。

note

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

获取轨迹规划配置

std::shared_ptr< TrajectoryPlanConfig > galbot::sdk::MotionPlanConfig::get_trajectory_plan_config() const

获取轨迹规划配置

返回值

Type	Description
std::shared_ptr< TrajectoryPlanConfig >	轨迹规划配置的共享指针；未设置时返回 nullptr。

note

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

获取IK 求解器配置

std::shared_ptr< IKSolverConfig > galbot::sdk::MotionPlanConfig::get_ik_solver_config() const

获取逆运动学求解器配置

返回值

Type	Description
std::shared_ptr< IKSolverConfig >	IK 求解器配置的共享指针；未设置时返回 nullptr。

note

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

获取碰撞检查选项

std::shared_ptr< CollisionCheckOption > galbot::sdk::MotionPlanConfig::get_collision_check_option() const

获取碰撞检测选项

返回值

Type	Description
std::shared_ptr< CollisionCheckOption >	碰撞检查选项的共享指针；未设置时返回 nullptr。

note

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

获取轨迹可行性检查选项

std::shared_ptr< TrajectoryFeasibilityCheckOption > galbot::sdk::MotionPlanConfig::get_trajectory_feasibility_check_option() const

获取轨迹可行性检查选项

返回值

Type	Description
std::shared_ptr< TrajectoryFeasibilityCheckOption >	轨迹可行性检查选项的共享指针；未设置时返回 nullptr。

note

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

获取直线轨迹检查基元

std::shared_ptr< LineTrajCheckPrimitive > galbot::sdk::MotionPlanConfig::get_line_traj_check_primitive() const

获取直线轨迹检查基元

返回值

Type	Description
std::shared_ptr< LineTrajCheckPrimitive >	直线轨迹检查基元的共享指针；未设置时返回 nullptr。

note

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

获取采样器配置引用

SamplerConfig & galbot::sdk::MotionPlanConfig::get_sampler_config_ref()

获取采样器配置引用

返回值

Type	Description
SamplerConfig &	采样器配置的可修改引用（保证非空）。

获取轨迹规划配置引用

TrajectoryPlanConfig & galbot::sdk::MotionPlanConfig::get_trajectory_plan_config_ref()

获取轨迹规划配置引用

返回值

Type	Description
TrajectoryPlanConfig &	轨迹规划配置的可修改引用（保证非空）。

获取IK 求解器配置引用

IKSolverConfig & galbot::sdk::MotionPlanConfig::get_ik_solver_config_ref()

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

返回值

Type	Description
IKSolverConfig &	IK 求解器配置的可修改引用（保证非空）。

获取碰撞检查选项引用

CollisionCheckOption & galbot::sdk::MotionPlanConfig::get_collision_check_option_ref()

获取碰撞检测选项引用

返回值

Type	Description
CollisionCheckOption &	碰撞检查选项的可修改引用（保证非空）。

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

TrajectoryFeasibilityCheckOption & galbot::sdk::MotionPlanConfig::get_trajectory_feasibility_check_option_ref()

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

返回值

Type	Description
TrajectoryFeasibilityCheckOption &	轨迹可行性检查选项的可修改引用（保证非空）。

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

LineTrajCheckPrimitive & galbot::sdk::MotionPlanConfig::get_line_traj_check_primitive_ref()

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

返回值

Type	Description
LineTrajCheckPrimitive &	直线轨迹检查基元的可修改引用（保证非空）。

获取可行性边界

const std::vector< KinematicsBoundary > & galbot::sdk::MotionPlanConfig::get_feasibility_boundary() const

获取可行性边界约束

返回值

Type	Description
const std::vector< KinematicsBoundary > &	运动学可行性边界向量的可修改引用。

获取可行性边界

std::vector< KinematicsBoundary > & galbot::sdk::MotionPlanConfig::get_feasibility_boundary()

获取可行性边界约束

返回值

Type	Description
std::vector< KinematicsBoundary > &	运动学可行性边界向量的可修改引用。

获取IK 关节约束

const std::vector< KinematicsBoundary > & galbot::sdk::MotionPlanConfig::get_ik_joint_limit() const

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

返回值

Type	Description
const std::vector< KinematicsBoundary > &	IK 关节限制边界向量的可修改引用。

获取IK 关节约束

std::vector< KinematicsBoundary > & galbot::sdk::MotionPlanConfig::get_ik_joint_limit()

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

返回值

Type	Description
std::vector< KinematicsBoundary > &	IK 关节限制边界向量的可修改引用。

获取采样关节约束

const std::vector< KinematicsBoundary > & galbot::sdk::MotionPlanConfig::get_sampler_joint_limit() const

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

返回值

Type	Description
const std::vector< KinematicsBoundary > &	采样关节限制边界向量的可修改引用。

获取采样关节约束

std::vector< KinematicsBoundary > & galbot::sdk::MotionPlanConfig::get_sampler_joint_limit()

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

返回值

Type	Description
std::vector< KinematicsBoundary > &	采样关节限制边界向量的可修改引用。

获取硬关节约束

const std::vector< KinematicsBoundary > & galbot::sdk::MotionPlanConfig::get_hard_joint_limit() const

获取硬关节位置限制边界

返回值

Type	Description
const std::vector< KinematicsBoundary > &	硬关节限制边界向量的可修改引用。

note

硬限制代表绝对的机械/安全约束，必须永不违反。

获取硬关节约束

std::vector< KinematicsBoundary > & galbot::sdk::MotionPlanConfig::get_hard_joint_limit()

获取硬关节位置限制边界

返回值

Type	Description
std::vector< KinematicsBoundary > &	硬关节限制边界向量的可修改引用。

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

const std::vector< std::string > & galbot::sdk::MotionPlanConfig::get_revert_ik_joint_limit_chains() const

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

返回值

Type	Description
const std::vector< std::string > &	需要恢复 IK 关节限制的运动链名称向量的可修改引用（保证非空）。

note

空向量表示在所有链上恢复（如果标志启用）。

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

std::vector< std::string > & galbot::sdk::MotionPlanConfig::get_revert_ik_joint_limit_chains()

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

返回值

Type	Description
std::vector< std::string > &	需要恢复 IK 关节限制的运动链名称向量的可修改引用（保证非空）。

获取是否恢复 IK 关节限制

bool galbot::sdk::MotionPlanConfig::get_revert_ik_joint_limit()

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

返回值

Type	Description
bool	true：将 IK 关节限制恢复为硬限制；false：使用默认限制。

打印输出

void galbot::sdk::MotionPlanConfig::print() const

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

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

---

运动状态

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

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

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

---

导航状态

导航任务执行状态枚举。

定义执行导航命令（例如移动到目标位置或遵循路径）时可能的结果。

Enum Value	Description
SUCCESS	导航任务成功完成
FAIL	失败
TIMEOUT	执行超时，任务未在允许的时间内完成
INVALID_INPUT	无效输入
MODE_ERR	模式错误
COMM_ERR	通信错误
WAIT_INITIALIZED	等待初始化

---

导航任务状态

导航任务当前状态枚举。

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

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

---

里程计数据

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

成员变量

Name	Type	Description
timestamp_ns	int64_t	里程计时间戳（自纪元以来的纳秒数）
position	std::array< double, 3 >	位置 [x, y, z]（米）
orientation	std::array< double, 4 >	四元数方向 [qx, qy, qz, qw]
linear_velocity	std::array< double, 3 >	线速度 [vx, vy, vz]（米/秒）
angular_velocity	std::array< double, 3 >	角速度 [ωx, ωy, ωz]（弧度/秒）

---

参数

运动规划参数配置类。

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

参数

galbot::sdk::Parameter::Parameter()=default

运动规划参数配置类。

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

构造函数

galbot::sdk::Parameter::Parameter(
    bool direct_execute,
    bool blocking,
    double timeout,
    std::string actuate,
    bool tool_pose,
    bool check_collision,
    const std::string &frame="base_link"
)

全身运动规划配置的参数化构造函数。

参数

Name	Type	Description
direct_execute	bool	true立即执行计划的运动，false不执行
blocking	bool	是否阻塞等待完成
timeout	double	运动执行允许的最大时间（秒）
actuate	std::string	驱动模式字符串。可选值："with_chain_only"（仅目标链/手臂）、"with_torso"（手臂+躯干）、"with_leg"（手臂+腿）。
tool_pose	bool	true目标姿态相对于工具帧，false相对于末端执行器
check_collision	bool	如果为 true，则在规划期间启用碰撞检测；如果为 false，则跳过碰撞检测
frame	const std::string &	参考坐标系

note

仅当 blocking 为 true 时 timeout 才相关。

note

无效的 actuate 字符串会导致未定义行为；确保使用有效键。

设置是否直接执行

void galbot::sdk::Parameter::set_direct_execute(bool direct_execute)

设置是否直接执行

参数

Name	Type	Description
direct_execute	bool	是否直接执行

设置是否阻塞

void galbot::sdk::Parameter::set_blocking(bool blocking)

设置是否阻塞执行

参数

Name	Type	Description
blocking	bool	是否阻塞

设置超时

void galbot::sdk::Parameter::set_timeout(double timeout)

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

参数

Name	Type	Description
timeout	double	运动执行允许的最大时间（秒，必须为正值）。

note

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

设置驱动类型

void galbot::sdk::Parameter::set_actuate(const std::string &actuate)

设置驱动类型

参数

Name	Type	Description
actuate	const std::string &	驱动类型

warning

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

设置工具位姿

void galbot::sdk::Parameter::set_tool_pose(bool tool_pose)

设置目标工具位姿

参数

Name	Type	Description
tool_pose	bool	工具位姿

设置是否检测碰撞

void galbot::sdk::Parameter::set_check_collision(bool check_collision)

设置是否进行碰撞检测

参数

Name	Type	Description
check_collision	bool	如果为 true，规划器会对自碰撞和环境障碍物进行碰撞检测；如果为 false，则跳过碰撞检查

warning

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

设置参考帧

void galbot::sdk::Parameter::set_reference_frame(const std::string &frame)

设置参考坐标系

参数

Name	Type	Description
frame	const std::string &	参考帧名称（例如："base_link"、"world"、"odom"）

note

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

设置是否使用直线运动

void galbot::sdk::Parameter::set_move_line(bool flag)

设置是否为直线运动

参数

Name	Type	Description
flag	bool	标志位

note

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

获取是否直接执行

bool galbot::sdk::Parameter::get_direct_execute() const

获取是否直接执行

返回值

Type	Description
bool	true 直接执行计划的运动，false 不执行。

获取是否阻塞

bool galbot::sdk::Parameter::get_blocking() const

获取是否阻塞执行

返回值

Type	Description
bool	true 阻塞直到运动完成或超时，false 不阻塞。

获取超时

double galbot::sdk::Parameter::get_timeout() const

获取超时时间（秒）

返回值

Type	Description
double	超时时长（秒，正值）。

获取驱动类型

std::string galbot::sdk::Parameter::get_actuate_type() const

获取驱动类型

返回值

Type	Description
std::string	驱动类型字符串（"with_chain_only"、"with_torso"、"with_leg"或"unknown"（如果未找到））

获取工具位姿

bool galbot::sdk::Parameter::get_tool_pose() const

获取目标工具位姿

返回值

Type	Description
bool	true 目标姿态相对于工具帧，false 相对于末端执行器。

获取是否检测碰撞

bool galbot::sdk::Parameter::get_check_collision() const

获取是否进行碰撞检测

返回值

Type	Description
bool	如果启用碰撞检测则为 true，否则为 false

获取参考帧

std::string galbot::sdk::Parameter::get_reference_frame() const

获取参考坐标系

返回值

Type	Description
std::string	参考帧名称

是否使用直线运动

bool galbot::sdk::Parameter::is_move_line()

判断是否为直线运动

返回值

Type	Description
bool	true 使用直线（笛卡尔）运动，false 使用标准轨迹。

---

规划器配置

运动规划配置结构。

用于机器人运动规划和执行的全面配置，控制规划模式、碰撞检查、参考坐标系和执行参数等行为。

成员变量

Name	Type	Description
is_direct_execute	bool	是否在规划后立即执行轨迹，true 表示一次性完成规划和执行，false 表示仅规划轨迹（用于预览或验证）
is_blocking	bool	是否同步等待操作完成，true 表示阻塞直到规划/执行完成或超时发生，false 表示立即返回（异步模式）
timeout_second	double	阻塞操作的超时时间（秒），等待规划或执行完成的最大时间，默认值：20 秒
actuate_type	ActuateType	驱动类型（运动链选择）。 - "with_chain_only": 仅使用指定的运动链 - "with_torso": 包含躯干 - "with_leg": 包含腿部 - "unknown": 未知类型
is_tool_pose	bool	目标是否指定为工具中心点 (TCP) 位姿，true 表示目标是末端执行器 TCP 位姿（笛卡尔空间），false 表示目标是关节空间配置
is_relative_pose	bool	目标位姿是否相对于当前位姿，true 表示目标位姿是相对于当前位置的位移，false 表示目标位姿是绝对位姿
is_check_collision	bool	是否在规划期间启用碰撞检测，true 表示检查与障碍物和自碰撞，false 表示跳过碰撞检测（请谨慎使用）
reference_frame	std::string	目标位姿的参考坐标系。 指定目标位姿所在的坐标系，例如： - "base_link": 机器人底座坐标系 - "world": 世界坐标系 - "odom": 里程计坐标系
joint_state	std::unordered_map< std::string, std::vector< double > >	指定规划的起始关节配置。 - 键（key）：关节名称 - 值（value）：关节角度（弧度） - 空字典表示使用当前机器人状态
move_line	bool	是否规划直线运动，true 表示在笛卡尔空间中规划直线运动（末端执行器沿直线移动），false 表示在关节空间中规划标准轨迹（可能不是笛卡尔直线）

---

点

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

成员变量

Name	Type	Description
x	double	X坐标（米）
y	double	Y坐标（米）
z	double	Z坐标（米）

---

点云字段

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

成员变量

Name	Type	Description
name	std::string	此数据通道的标识符。 标准字段名称包括： - "x", "y", "z": 3D 笛卡尔坐标 - "intensity": 强度 - "rgb" 或 "rgba": 颜色 - "timestamp": 时间戳
offset	uint32_t	此字段相对于点数据结构起始位置的字节偏移量，例如：对于点布局 [x(float32), y(float32), z(float32), intensity(float32)]，x 的偏移为 0，y 的偏移为 4，z 的偏移为 8，intensity 的偏移为 12
datatype	DataType	数据类型
count	uint32_t	此字段的数组长度，标量字段（x, y, z, intensity）通常为 1，数组字段可能大于 1（例如 count=3 表示 3 元素向量）

嵌套枚举

数据类型

点字段数据类型枚举

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

---

姿态

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

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

姿态

galbot::sdk::Pose::Pose()=default

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

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

构造函数

galbot::sdk::Pose::Pose(const T &pos, const T &quat)

构造函数，使用位置和四元数初始化位姿

参数

Name	Type	Description
pos	const T &	三维位置向量 [x, y, z]，单位：米，长度必须为 3。
quat	const T &	四元数

构造函数

galbot::sdk::Pose::Pose(const T &vec)

构造函数，使用7维向量初始化位姿

参数

Name	Type	Description
vec	const T &	7维向量：[x, y, z, qx, qy, qz, qw]，前三项为位置（米），后四项为四元数

成员变量

Name	Type	Description
position	Point	三维位置（x, y, z），单位：米。
orientation	Quaternion	方向

---

姿态状态

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

获取类型

Type galbot::sdk::PoseState::get_type() const override

获取位姿状态类型

返回值

Type	Description
Type	笛卡尔位姿目标

成员变量

Name	Type	Description
frame_id	std::string	运动链上的目标帧（例如："left_ee"）
reference_frame	std::string	参考坐标系（例如："base_link"）
pose	Pose	位姿

---

四元数

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

成员变量

Name	Type	Description
x	double	X坐标
y	double	Y坐标
z	double	Z坐标
w	double	四元数w分量

---

参考坐标系

指定表达姿态、位置或轨迹的坐标系。注意：这是一个用于 C 风格兼容性的普通枚举（不是枚举类）。

Enum Value	Description
FRAME_WORLD	世界坐标系
FRAME_BASE	基座坐标系

---

感兴趣区域

定义图像内的矩形子区域以进行选择性处理。与 ROS 2sensor_msgs/RegionOfInterest 兼容。

成员变量

Name	Type	Description
x_offset	uint32_t	X偏移
y_offset	uint32_t	Y偏移
height	uint32_t	感兴趣区域的像素行数
width	uint32_t	感兴趣区域的像素列数
do_rectify	bool	是否校正

---

RGB数据

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

RGB 图像转 OpenCV Mat

std::shared_ptr< cv::Mat > galbot::sdk::RgbData::convert_to_cv2_mat()

将RGB图像数据解码并转换为OpenCV

Mat格式以进行处理

返回值

Type	Description
std::shared_ptr< cv::Mat >	解码成功时返回 std::shared_ptr<cv::Mat> 智能指针；解码失败时返回空指针。

成员变量

Name	Type	Description
header	Header	包含采集时间戳和相机坐标系
format	std::string	指定压缩格式和编码
data	std::vector< uint8_t >	包含压缩图像数据的二进制数据块

---

机器人状态

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

获取类型

virtual Type galbot::sdk::RobotStates::get_type() const

获取机器人状态类型

返回值

Type	Description
Type	类型枚举值，基类为 ROBOT_STATES

机器人状态

galbot::sdk::RobotStates::RobotStates()=default

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

设置全身关节

void galbot::sdk::RobotStates::set_whole_body_joint(const std::vector< double > &joint_positions)

设置全身关节位置

参数

Name	Type	Description
joint_positions	const std::vector< double > &	目标关节位置

note

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

设置基座状态

void galbot::sdk::RobotStates::set_base_state(const Pose &base_pose)

设置底座状态（位姿）

参数

Name	Type	Description
base_pose	const Pose &	SE(3)中的基座姿态：位置（米）和方向（四元数）

note

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

构造函数

galbot::sdk::RobotStates::RobotStates(
    const std::string &chain,
    const std::vector< double > &whole_joint,
    const Pose &base_pose
)

构造函数，使用运动链、全身关节和底座位姿初始化机器人状态

参数

Name	Type	Description
chain	const std::string &	要分离工具的运动链
whole_joint	const std::vector< double > &	全身关节
base_pose	const Pose &	移动基座位姿：位置（米）+ 姿态（单位四元数）。

成员变量

Name	Type	Description
chain_name	std::string	链名称
whole_body_joint	std::vector< double >	全身关节
base_state	std::vector< double >	移动基座位姿：[x, y, z, qx, qy, qz, qw]（米，四元数）。

嵌套枚举

类型

机器人状态类型枚举

Used for runtime type identification of RobotStates-derived classes.

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

---

S1控制器名称

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

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

成员变量

Name	Type	Description
SWERVE_CHASSIS_POSE_CTRL	constexpr Name	转向底盘姿态控制器
SWERVE_CHASSIS_TWIST_CTRL	constexpr Name	转向底盘速度控制器
ELEVATOR_CTRL	constexpr Name	升降控制器
HEAD_PVT_CTRL	constexpr Name	头部位置-速度-力矩控制器
LEFT_ARM_PVT_CTRL	constexpr Name	左臂位置-速度-力矩控制器
RIGHT_ARM_PVT_CTRL	constexpr Name	右臂位置-速度-力矩控制器
LEFT_GRIPPER_CTRL	constexpr Name	左夹爪控制器
RIGHT_GRIPPER_CTRL	constexpr Name	右夹爪控制器
LEFT_CAMERA_CTRL	constexpr Name	左眼相机控制器
RIGHT_CAMERA_CTRL	constexpr Name	右眼相机控制器

---

S1关节组

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

成员变量

Name	Type	Description
HEAD	constexpr Name	头部
LEFT_ARM	constexpr Name	左7自由度手臂链。默认关节：left_arm_joint1 ... left_arm_joint7。典型用途：左臂操作。
RIGHT_ARM	constexpr Name	右7自由度手臂链。默认关节：right_arm_joint1 ... right_arm_joint7。典型用途：右臂操作。
LEFT_GRIPPER	constexpr Name	左夹爪链。默认关节：left_gripper_joint1。典型用途：夹爪开合和宽度控制。
RIGHT_GRIPPER	constexpr Name	右夹爪链。默认关节：right_gripper_joint1。典型用途：夹爪开合和宽度控制。
TORSO	constexpr Name	躯干
SWERVE_CHASSIS	constexpr Name	舵机底盘机构组（关节位置控制中为被动）。 默认关节：Wheel_1_direction、Wheel_1_velocity、Wheel_2_direction、Wheel_2_velocity...
LEFT_CAMERA	constexpr Name	左眼相机
RIGHT_CAMERA	constexpr Name	左眼相机

---

采样器配置

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

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

设置状态检查类型

void galbot::sdk::SamplerConfig::set_state_check_type(StateCheckType type)

设置状态检查类型

参数

Name	Type	Description
type	StateCheckType	评估状态相似性的距离度量类型

设置状态检查分辨率

void galbot::sdk::SamplerConfig::set_state_check_resolution(double resolution)

设置状态检查分辨率

参数

Name	Type	Description
resolution	double	认为两个状态不同的最小距离阈值（单位：弧度或无量纲）

note

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

设置是否插值

void galbot::sdk::SamplerConfig::set_interpolate(bool enable)

设置是否启用插值

参数

Name	Type	Description
enable	bool	true 启用插值，false 仅使用采样路点

note

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

设置插值数量

void galbot::sdk::SamplerConfig::set_interpolation_cnt(int cnt)

设置插值点数量

参数

Name	Type	Description
cnt	int	要插入的中间路点数量（0 = 使用自动计算）

note

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

设置是否简化

void galbot::sdk::SamplerConfig::set_simplify(bool enable)

设置是否启用简化

参数

Name	Type	Description
enable	bool	true 启用路径简化和平滑，false 使用原始规划路径

note

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

设置最大简化时间

void galbot::sdk::SamplerConfig::set_max_simplification_time(double time)

设置最大简化时间（秒）

参数

Name	Type	Description
time	double	最大简化持续时间（单位：秒）；负值表示无时间限制

note

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

设置终止条件类型

void galbot::sdk::SamplerConfig::set_termination_condition_type(TerminationConditionType type)

设置终止条件类型

参数

Name	Type	Description
type	TerminationConditionType	终止条件类型（仅超时或超时/精确解）

设置最大规划时间

void galbot::sdk::SamplerConfig::set_max_planning_time(double time)

设置最大规划时间（秒）

参数

Name	Type	Description
time	double	最大规划持续时间（单位：秒）

note

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

获取状态检查类型

StateCheckType galbot::sdk::SamplerConfig::get_state_check_type() const

获取状态检查类型

返回值

Type	Description
StateCheckType	评估状态相似性的距离度量类型

获取状态检查分辨率

double galbot::sdk::SamplerConfig::get_state_check_resolution() const

获取状态检查分辨率

返回值

Type	Description
double	分辨率值（单位：弧度或无量纲，取决于状态检查类型）

获取是否插值

bool galbot::sdk::SamplerConfig::get_interpolate() const

获取是否启用插值

返回值

Type	Description
bool	如果启用插值则为 true，否则为 false

获取插值数量

int galbot::sdk::SamplerConfig::get_interpolation_cnt() const

获取插值点数量

返回值

Type	Description
int	要插入的中间路点数量

获取是否简化

bool galbot::sdk::SamplerConfig::get_simplify() const

获取是否启用简化

返回值

Type	Description
bool	如果启用路径简化则为 true，否则为 false

获取最大简化时间

double galbot::sdk::SamplerConfig::get_max_simplification_time() const

获取最大简化时间（秒）

返回值

Type	Description
double	最大简化持续时间（单位：秒）

获取终止条件类型

TerminationConditionType galbot::sdk::SamplerConfig::get_termination_condition_type() const

获取终止条件类型

返回值

Type	Description
TerminationConditionType	终止条件类型

获取最大规划时间

double galbot::sdk::SamplerConfig::get_max_planning_time() const

获取最大规划时间（秒）

返回值

Type	Description
double	最大规划持续时间（单位：秒）

打印输出

void galbot::sdk::SamplerConfig::print() const

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

嵌套枚举

状态检查类型

状态检查类型枚举

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

终止条件类型

终止条件类型枚举

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

---

随机种子类型

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

Enum Value	Description
RANDOM_SEED	随机种子
RANDOM_PROGRESSIVE_SEED	随机渐进种子
USER_DEFINED_SEED	用户自定义种子
SEED_TYPE_NUM	种子类型数量

---

传感器状态

表示传感器数据采集和处理操作的状态，适用于相机、激光雷达、IMU、力传感器和其他传感器类型。

Enum Value	Description
SUCCESS	成功
TIMEOUT	超时
FAULT	故障
INVALID_INPUT	无效输入
INIT_FAILED	初始化失败
IN_PROGRESS	进行中
STOPPED_UNREACHED	已停止但未到达
DATA_FETCH_FAILED	数据获取失败，传感器可能已断开连接或损坏
PUBLISH_FAIL	发布失败
COMM_DISCONNECTED	通信断开
STATUS_NUM	状态数量

---

传感器类型

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

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

Enum Value	Description
HEAD_LEFT_CAMERA	左眼相机
HEAD_RIGHT_CAMERA	右眼相机
LEFT_ARM_CAMERA	左臂相机
RIGHT_ARM_CAMERA	右臂相机
LEFT_ARM_DEPTH_CAMERA	左臂深度相机
RIGHT_ARM_DEPTH_CAMERA	右臂深度相机
HEAD_LIDAR	头部激光雷达
BACK_LIDAR	背部激光雷达
CHASSIS_LIDAR	底盘激光雷达
HEAD_IMU	头部IMU
BACK_IMU	背部IMU
CHASSIS_IMU	底盘IMU
BASE_ULTRASONIC	基座超声波
SENSOR_NUM	传感器数量

---

SingoriX目标

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

成员变量

Name	Type	Description
header	Header
target_group_trajectory_map	std::unordered_map< std::string, TargetGroupTrajectory >
target_task_trajectory_map	std::unordered_map< std::string, TargetTaskTrajectory >

---

吸盘动作状态

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

Enum Value	Description
suction_action_idle	吸取动作空闲
suction_action_sucking	吸取动作吸取中
suction_action_success	吸取动作成功
suction_action_failed	吸取动作失败

---

吸盘状态

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

成员变量

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

---

目标配置

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

成员变量

Name	Type	Description
target_data	int32_t
target_type	int32_t
target_sampling	TargetSampling
target_priority	int32_t
target_id	std::string
target_ts	Timestamp

---

目标数据位

用于表示目标数据类型的位掩码，标识目标包含哪些数据分量。

Enum Value	Description
TARGET_DATA_NONE
TARGET_DATA_JOINT_POS
TARGET_DATA_JOINT_VEL
TARGET_DATA_JOINT_ACC
TARGET_DATA_JOINT_EFF
TARGET_DATA_FRAME_POSE
TARGET_DATA_FRAME_TWIST
TARGET_DATA_FRAME_WRENCH
TARGET_DATA_DEFAULT

---

目标关节组轨迹

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

成员变量

Name	Type	Description
target_config	TargetConfig
joint_names	std::vector< std::string >
group_commands	std::vector< GroupCommand >

---

目标采样

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

Enum Value	Description
TARGET_SAMPLING_DEFAULT
TARGET_SAMPLING_DIRECT_PASS
TARGET_SAMPLING_LINEAR_INTERPOLATE
TARGET_SAMPLING_TRAPEZOIDAL_PROFILE
TARGET_SAMPLING_S_CURVE_PROFILE
TARGET_SAMPLING_CUBIC_SPLINES
TARGET_SAMPLING_QUINTIC_SPLINES
TARGET_SAMPLING_B_SPLINES
TARGET_SAMPLING_CUSTOM

---

目标任务轨迹

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

成员变量

Name	Type	Description
target_config	TargetConfig
group_names	std::vector< std::string >
joint_names	std::vector< std::string >
subtask_names	std::vector< std::string >
task_commands	std::vector< TaskCommand >

---

目标类型位

用于表示目标类型的位掩码，标识目标是哪种类型（关节空间、任务空间等）。

Enum Value	Description
TARGET_TYPE_NONE
TARGET_TYPE_TOUCH
TARGET_TYPE_CLEAR
TARGET_TYPE_PREPENDNOW
TARGET_TYPE_APPEND
TARGET_TYPE_OVERRIDE
TARGET_TYPE_PROVERRIDE
TARGET_TYPE_DEFAULT

---

任务命令

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

成员变量

Name	Type	Description
time_from_start_s	double
subtask_commands	std::vector< FrameTriad >

---

时间戳

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

成员变量

Name	Type	Description
sec	int64_t	秒
nanosec	uint32_t	纳秒

---

轨迹

表示一个完整的机器人轨迹，包含多个随时间变化的路点。joint_groups 和 joint_names 不能同时为空。如果同时为空，函数将返回 ControlStatus::INVALID_INPUT。此限制确保了关节顺序的确定性，防止因隐式内部默认顺序（可能在 SDK 版本之间变化）导致的难以察觉的 bug。使用方法：推荐设置具有语义组名的 joint_groups 或 joint_names。如果同时设置，joint_names 优先于 joint_groups

成员变量

Name	Type	Description
points	std::vector< 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）。
joint_groups	std::vector< std::string >	关节组名称列表，如 ["left_arm", "right_arm"]。注意：joint_groups 和 joint_names 不能同时为空
joint_names	std::vector< std::string >	显式关节名称。当非空时，优先于 joint_groups，并且仅验证为活动关节。当 joint_groups 也为空时，不能同时为空。

---

轨迹控制状态

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

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

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

---

轨迹可行性检查选项

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

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

设置是否禁用碰撞检查

void galbot::sdk::TrajectoryFeasibilityCheckOption::set_disable_collision_check(bool disable)

设置是否禁用碰撞检测

参数

Name	Type	Description
disable	bool	是否禁用碰撞检测

warning

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

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

void galbot::sdk::TrajectoryFeasibilityCheckOption::set_disable_joint_limit_check(bool disable)

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

参数

Name	Type	Description
disable	bool	传入 true 表示跳过关节限位验证，传入 false 表示强制执行位置限位验证。

warning

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

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

void galbot::sdk::TrajectoryFeasibilityCheckOption::set_disable_velocity_feasibility_check(bool disable)

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

参数

Name	Type	Description
disable	bool	true 跳过速度限制验证，false 强制执行速度验证。

note

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

获取是否禁用碰撞检查

bool galbot::sdk::TrajectoryFeasibilityCheckOption::get_disable_collision_check() const

获取是否禁用碰撞检测

返回值

Type	Description
bool	若当前已禁用碰撞检查则返回 true；否则返回 false。

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

bool galbot::sdk::TrajectoryFeasibilityCheckOption::get_disable_joint_limit_check() const

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

返回值

Type	Description
bool	若当前已禁用关节限位检查则返回 true；否则返回 false。

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

bool galbot::sdk::TrajectoryFeasibilityCheckOption::get_disable_velocity_feasibility_check() const

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

返回值

Type	Description
bool	若当前已禁用速度可行性检查则返回 true；否则返回 false。

打印输出

void galbot::sdk::TrajectoryFeasibilityCheckOption::print() const

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

---

轨迹规划配置

轨迹规划和参数化配置。

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

设置最小移动时间

void galbot::sdk::TrajectoryPlanConfig::set_min_move_time(double time)

设置最小运动时间（秒）

参数

Name	Type	Description
time	double	最小轨迹执行时间（单位：秒）

note

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

设置直线插值中间点

void galbot::sdk::TrajectoryPlanConfig::set_move_line_intermediate_point(double value)

设置直线运动中间点设置

参数

Name	Type	Description
value	double	线性路径段的中间路点数量（无量纲）

note

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

设置路点规划预期时间

void galbot::sdk::TrajectoryPlanConfig::set_way_point_plan_expected_time(double time)

设置路点规划期望时间

参数

Name	Type	Description
time	double	路点序列的预期轨迹执行时间（单位：秒）

note

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

获取最小移动时间

double galbot::sdk::TrajectoryPlanConfig::get_min_move_time() const

获取最小运动时间（秒）

返回值

Type	Description
double	最小轨迹执行时间（单位：秒）

获取直线插值中间点

double galbot::sdk::TrajectoryPlanConfig::get_move_line_intermediate_point() const

获取直线运动中间点设置

返回值

Type	Description
double	线性路径段的中间路点数量（无量纲）

获取路点规划预期时间

double galbot::sdk::TrajectoryPlanConfig::get_way_point_plan_expected_time() const

获取路点规划期望时间

返回值

Type	Description
double	路点规划的预期轨迹执行时间（单位：秒）

打印输出

void galbot::sdk::TrajectoryPlanConfig::print() const

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

---

轨迹点

表示机器人轨迹中的路点，指定特定时间的关节状态。joint_command_vec 的顺序必须与 Trajectory.joint_names 或 Trajectory.joint_groups（按顺序展开）定义的关节顺序一致。顺序不匹配将导致未定义行为。

成员变量

Name	Type	Description
time_from_start_second	double	起始时间偏移（秒）
joint_command_vec	std::vector< JointCommand >	该路点所有关节的关节命令列表。顺序必须与 joint_names 或 joint_groups 展开顺序一致。

---

坐标变换消息

表示带时间戳的坐标系变换，包括平移和旋转。常用于机器人技术中的 TF（变换）树。

成员变量

Name	Type	Description
timestamp_ns	int64_t	变换时间戳（自纪元以来的纳秒数）
translation	Point	平移向量（米）。
rotation	Quaternion	旋转

---

扭曲速度

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

成员变量

Name	Type	Description
linear	Vector3
angular	Vector3

---

超声波数据

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

成员变量

Name	Type	Description
timestamp_ns	int64_t	超声波测量时间戳（纳秒）
distance	double	到最近障碍物的测量距离（米）。

---

超声波类型

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

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

Enum Value	Description
FRONT_LEFT	左前超声波
FRONT_RIGHT	右前超声波
RIGHT_LEFT	右侧左超声波
RIGHT_RIGHT	右侧右超声波
BACK_LEFT	左后超声波
BACK_RIGHT	右后超声波
LEFT_LEFT	左侧左超声波
LEFT_RIGHT	左侧右超声波
ULTRASONIC_NUM	超声波传感器数量

---

三维向量

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

成员变量

Name	Type	Description
x	double	X分量
y	double	Y分量
z	double	Z分量

---

力与力矩

力与力矩相关说明。

成员变量

Name	Type	Description
force	Vector3
torque	Vector3

---