C++ API 参考 - S1 机器人

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

---

核心机器人控制（GalbotRobot）

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

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

析构函数（~GalbotRobot）

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

初始化（init）

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

初始化机器人控制系统。

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

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

参数

名称	类型	描述
enable_sensor_set	const std::unordered_set< SensorType > &	要启用的传感器集合，如果为空，则启用默认的传感器集合，仅指定所需传感器可减少启动时间和资源占用
enable_sync_mode	bool

返回值

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

发布目标（PublishTarget）

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

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

参数

名称	类型	描述
target	const SingoriXTarget &	目标对象

返回值

类型	描述
ControlStatus	无返回值

请求目标（RequestTarget）

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

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

参数

名称	类型	描述
target	const SingoriXTarget &	目标对象

返回值

类型	描述
std::shared_ptr< ErrorInfo >	指向本地预检查失败或服务响应中 ErrorInfo 的共享指针。当客户端不可用、断开连接、超时或返回空响应时，返回 nullptr。

设置关节命令（set_joint_commands）

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=0.0
) =0

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

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

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

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

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

参数

名称	类型	描述
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	执行将在 time_start_s 秒后开始。（可选，默认值：0.0）

返回值

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

warning

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

设置关节位置（set_joint_positions）

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

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

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

参数

名称	类型	描述
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	超时时间（秒）

返回值

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

warning

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

检查轨迹执行状态（check_trajectory_execution_status）

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

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

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

参数

名称	类型	描述
joint_groups	std::vector< std::string >	关节组列表

返回值

类型	描述
std::vector< TrajectoryControlStatus >	轨迹控制状态列表：轨迹执行状态列表。

执行关节轨迹（execute_joint_trajectory）

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

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

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

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

参数

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

返回值

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

warning

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

warning

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

批量设置关节命令（set_joint_commands_batch）

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

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

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

参数

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

返回值

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

warning

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

设置夹爪命令（set_gripper_command）

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

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

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

参数

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

返回值

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

获取夹爪状态（get_gripper_state）

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

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

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

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

参数

名称	类型	描述
end_effector	const std::string &	要查询的夹爪关节组名称（例如 left_gripper、right_gripper）。

返回值

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

获取灵巧手状态（get_dexhand_state）

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，会填充完整关节状态，并在可用时返回命名力传感器数据。

参数

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

返回值

类型	描述
ControlStatus	控制状态，指示成功或失败。

设置灵巧手命令（set_dexhand_command）

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

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

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

参数

名称	类型	描述
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	是否阻塞等待动作完成。

返回值

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

获取关节位置（get_joint_positions）

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

获取关节位置

参数

名称	类型	描述
joint_groups	const std::vector< std::string > &	关节组列表
joint_names	const std::vector< std::string > &	关节名称列表

返回值

类型	描述
std::vector< double >	当前关节角度向量（弧度）

note

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

获取关节组名称（get_joint_group_names）

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

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

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

返回值

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

获取关节名称（get_joint_names）

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

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

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

参数

名称	类型	描述
only_active_joint	bool	是否仅返回主动关节
joint_groups	const std::vector< std::string > &	关节组列表

返回值

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

获取关节状态（get_joint_states）

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

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

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

参数

名称	类型	描述
joint_group_vec	const std::vector< std::string > &	关节组向量
joint_names_vec	const std::vector< std::string > &	关节名称向量

返回值

类型	描述
std::vector< JointState >	包含每个关节当前状态的 JointState 结构向量

note

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

设置底盘速度（set_base_velocity）

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

设置移动基础速度命令。

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

参数

名称	类型	描述
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	持续时间（秒）

返回值

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

设置底盘姿态（set_base_pose）

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 姿态（位置 + 四元数方向）已经可用时，使用此重载。

参数

名称	类型	描述
base_pose	const Pose &	底盘目标姿态
is_blocking	bool	是否阻塞等待完成
timeout_s	double	超时时间（秒）

返回值

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

设置底盘姿态（set_base_pose）

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

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

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

参数

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

返回值

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

设置底盘姿态（set_base_pose）

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

参数

名称	类型	描述
x	double	X坐标（米）
y	double	Y坐标（米）
yaw	double	航向角（弧度）
frame_id	const std::string &	目标坐标系 ID。当前推荐值："rel(0)"。"rel(0)" 表示 x/y/yaw 目标相对于当前底座位姿解释。"base_link"、"odom" 和 "map" 保留以向后兼容，但不建议当前使用，后续版本可能修改或移除。
reference_frame_id	const std::string &	参考坐标系ID
time_from_start_s	double	预期到达时间（秒）
is_blocking	bool	是否阻塞等待完成
timeout_s	double	超时时间（秒）

返回值

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

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

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={}
) =0

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

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

参数

名称	类型	描述
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"（默认）。

返回值

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

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

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

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

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

返回值

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

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

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

获取 WBC 末端执行器位姿。

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

返回值

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

紧急停止底盘（stop_base）

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

紧急停止移动底座运动。

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

返回值

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

全身与底盘归零（zero_whole_body_and_base）

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。

参数

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

返回值

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

全身与底盘归零（zero_whole_body_and_base）

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、航向角）归零。

参数

名称	类型	描述
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 >	额外参数

返回值

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

停止轨迹执行（stop_trajectory_execution）

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

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

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

返回值

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

重新加载控制器（reload_controller）

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

重新加载控制器。

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

参数

名称	类型	描述
group_name	const std::string &	要重新加载的控制器组名称

返回值

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

切换控制器（switch_controller）

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

切换活动控制器策略。

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

参数

名称	类型	描述
controller_name	const std::string &	控制器名称字符串，例如 "chassis_pose_ctrl"。

返回值

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

获取当前控制器（get_active_controller）

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

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

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

参数

名称	类型	描述
group_name	const std::string &	要查询的关节组名称。

返回值

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

获取控制器权限（acquire_controller）

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

获取硬件控制权限。

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

参数

名称	类型	描述
controller_name	const std::string &	控制器名称字符串，例如 "left_arm_pvt_ctrl"。

返回值

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

释放控制器权限（release_controller）

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

释放硬件权限。

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

参数

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

返回值

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

启动控制器（start_controller）

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

开始控制器执行。

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

参数

名称	类型	描述
group_name	const std::string &	要启动的控制器组名称

返回值

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

停止控制器（stop_controller）

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

停止控制器执行。

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

参数

名称	类型	描述
group_name	const std::string &	要停止的控制器组名称

返回值

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

获取IMU数据（get_imu_data）

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

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

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

参数

名称	类型	描述
imu_type	SensorType	IMU传感器类型

返回值

类型	描述
std::shared_ptr< ImuData >	指向 ImuData 结构的共享指针，如果传感器未启用或数据检索失败，则为 nullptr。

note

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

note

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

note

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

获取里程计数据（get_odom）

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

获取机器人里程信息。

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

返回值

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

获取设备信息（get_device_information）

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

获取设备信息。

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

返回值

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

获取RGB图像数据（get_rgb_data）

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

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

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

参数

名称	类型	描述
rgb_camera	const SensorType	RGB相机名称

返回值

类型	描述
std::shared_ptr< RgbData >	指向包含图像缓冲区、尺寸、编码和时间戳的 RgbData 的共享指针。如果摄像头未启用或数据检索失败，则返回 nullptr。

note

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

获取深度图像数据（get_depth_data）

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

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

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

参数

名称	类型	描述
depth_camera	const SensorType	深度相机名称

返回值

类型	描述
std::shared_ptr< DepthData >	指向 DepthData 的共享指针，其中包含深度图像缓冲区、尺寸、编码和时间戳。如果摄像头未启用或数据检索失败，则返回 nullptr。

note

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

note

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

获取红外图像数据（get_ir_data）

virtual std::shared_ptr< IrData > galbot::sdk::GalbotRobot::get_ir_data(const SensorType ir_camera)=0

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

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

参数

名称	类型	描述
ir_camera	const SensorType	SensorType 枚举，指定要查询哪个红外摄像头（LEFT_ARM_INFRA_CAMERA_1/2 或 RIGHT_ARM_INFRA_CAMERA_1/2）

返回值

类型	描述
std::shared_ptr< IrData >	指向包含灰度图像缓冲区和时间戳的 IrData 的共享指针。如果相机未启用、ir_enabled 为 false 或数据检索失败，则返回 nullptr。

note

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

note

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

获取同步观测数据（get_synced_observation）

virtual std::shared_ptr< SyncedObservation > galbot::sdk::GalbotRobot::get_synced_observation(
    const std::vector< SensorType > &cameras,
    bool with_joint_state=true
) =0

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

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

参数

名称	类型	描述
cameras	const std::vector< SensorType > &	要进行同步的相机列表。cameras[0] 为锚定相机，且必须已启用。
with_joint_state	bool	是否包含最近邻匹配的关节状态。

返回值

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

获取激光雷达数据（get_lidar_data）

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

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

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

参数

名称	类型	描述
lidar	const SensorType	激光雷达名称

返回值

类型	描述
std::shared_ptr< LidarData >	指向 LidarData（PointCloud2 格式）的共享指针，其中包含相对于 LiDAR 坐标系的点云坐标（单位为米）。如果 LiDAR 未启用或数据检索失败，则返回 nullptr。

note

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

获取相机内参（get_camera_intrinsic）

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

获取相机内参。

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

参数

名称	类型	描述
camera	const SensorType	相机名称

返回值

类型	描述
std::shared_ptr< CameraInfo >	指向 CameraInfo 的共享指针，其中包含： - focal_length_x, focal_length_y: 像素焦距 - principal_point_x, principal_point_y: 像素主点坐标 - distortion_coeffs: 畸变系数向量（例如，k1, k2, p1, p2, k3） - 根据需要提供更多相机特定参数 如果相机未启用或数据检索失败，则返回 nullptr。

note

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

获取坐标变换（get_transform）

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树中两个坐标系之间的变换。

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

参数

名称	类型	描述
target_frame	const std::string &	目标坐标系
source_frame	const std::string &	源坐标系
timestamp_ns	int64_t	时间戳（纳秒）
timeout_ms	int64_t	超时时间（毫秒）

返回值

类型	描述
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。

获取坐标系名称（get_frame_names）

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

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

返回值

类型	描述
std::vector< std::string >	所有可用坐标系名称列表。

获取传感器外参（get_sensor_extrinsic）

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

获取传感器外参。

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

参数

名称	类型	描述
sensor_id	const SensorType	传感器ID
reference_frame	const std::string &	参考坐标系

返回值

类型	描述
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 启用。

检查是否运行中（is_running）

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

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

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

返回值

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

请求关机（request_shutdown）

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

请求系统关闭。

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

等待关机（wait_for_shutdown）

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

阻塞直到关闭完成。

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

note

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

销毁（destroy）

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

清理系统资源。

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

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

注册退出回调（register_exit_callback）

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

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

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

参数

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

note

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

获取日志信息（get_log_information）

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

获取日志信息。

参数

名称	类型	描述
timewindow_s	uint64
log_level	LogLevel

返回值

类型	描述
std::shared_ptr< LogInfo >	指向包含日志信息的 LogInfo 的共享指针

获取实例（get_instance）

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

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

参数

名称	类型	描述
m	MachineType	机器类型

返回值

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

---

运动规划与执行（GalbotMotion）

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

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

析构函数（~GalbotMotion）

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

初始化（init）

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

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

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

返回值

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

note

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

warning

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

检查是否有效（is_valid）

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

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

返回值

类型	描述
bool	若对象有效且可用则返回 true，否则返回 false。

note

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

正向运动学（forward_kinematics）

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

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

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

参数

名称	类型	描述
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 >	额外参数

返回值

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

note

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

warning

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

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

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 对象来指定完整的机器人配置（全身关节+底座姿态）。

参数

名称	类型	描述
target_frame	const std::string &	目标坐标系
reference_robot_states	const std::shared_ptr< RobotStates > &	参考机器人起始状态
reference_frame	const std::string &	参考坐标系
params	std::shared_ptr< Parameter >	额外参数

返回值

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

note

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

逆向运动学（inverse_kinematics）

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（手臂 + 躯干/腿）。

参数

名称	类型	描述
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 >	额外参数

返回值

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

note

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

note

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

warning

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

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

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 来指定种子配置，从而允许精确控制整个机器人状态。

参数

名称	类型	描述
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 >	额外参数

返回值

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

note

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

获取雅可比矩阵（get_jacobian）

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

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

参数

名称	类型	描述
chain_name	const std::string &	链名称
target_frame	const std::string &	雅可比矩阵计算的目标连杆。有效值： - "EndEffector"（默认）：链末端执行器法兰，即 "<chain_name>_end_effector_mount_link" - get_support_links() / get_link_names() 返回的任意有效 URDF 连杆名 注意：不支持 "Tool"（TCP）——运动学服务仅按连杆名计算雅可比矩阵，不具备工具位姿能力，传入 "Tool" 将返回 MotionStatus::UNSUPPORTED_FUNCRION。
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 >	运动学参数配置

返回值

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

note

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

note

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

note

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

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

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

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

参数

名称	类型	描述
chain_name	const std::string &	链名称
target_frame	const std::string &	雅可比矩阵计算的目标连杆。默认："EndEffector"（链法兰，"<chain_name>_end_effector_mount_link"），或 get_support_links() 返回的任意有效 URDF 连杆名。不支持 "Tool"（TCP），传入将返回 MotionStatus::UNSUPPORTED_FUNCRION（参见 get_jacobian()）。
reference_frame	const std::string &	参考坐标系。默认："base_link"
reference_robot_states	const std::shared_ptr< RobotStates > &	机器人状态，包含关节位置信息
params	std::shared_ptr< Parameter >	运动学参数配置

返回值

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

note

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

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

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 模型中定义该连杆。

参数

名称	类型	描述
end_effector_frame	const std::string &	末端执行器坐标系
reference_frame	const std::string &	参考坐标系

返回值

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

note

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

warning

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

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

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 中的确切连杆名称。

参数

名称	类型	描述
chain_name	const std::string &	链名称
frame_id	const std::string	坐标系ID
reference_frame	const std::string &	参考坐标系

返回值

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

note

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

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

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)、轨迹规划并执行运动。is_blocking 标志仅控制此 API 是等待完成还是在启动后台执行任务后立即返回。

参数

名称	类型	描述
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 &	如果为真，则等待动作完成或超时。如果为假，机器人仍会执行动作，而此 API 会在启动一个等待执行完成的后台任务后立即返回。
timeout	const double &	SDK 等待动作完成的最长时间（以秒为单位）。如果小于 0，则使用 params->timeout_second。在非阻塞模式下，此超时时间应用于后台任务。
params	std::shared_ptr< Parameter >	额外参数

返回值

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

note

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

note

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

note

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

warning

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

轨迹规划（motion_plan）

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

规划单个运动链的轨迹。

参数

名称	类型	描述
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 >	额外参数

返回值

类型	描述
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 错误。

单链多路点轨迹规划（motion_plan_multi_waypoints）

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

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

参数

名称	类型	描述
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 >	额外参数

返回值

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

note

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

note

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

note

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

多路点轨迹规划（motion_plan_multi_waypoints）

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

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

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

参数

名称	类型	描述
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 >	额外参数

返回值

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

note

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

note

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

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

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)。

参数

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

返回值

类型	描述
MotionStatus	运动状态 总体执行状态

检查碰撞（check_collision）

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 是未来计划，目前内部验证有限。

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

参数

名称	类型	描述
start	const std::vector< std::shared_ptr< RobotStates > > &	起始机器人状态
enable_collision_check	bool	是否启用碰撞检查
params	std::shared_ptr< Parameter >	额外参数

返回值

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

note

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

note

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

note

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

附加工具（attach_tool）

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

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

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

参数

名称	类型	描述
chain	const std::string &	用于挂载工具的运动链（例如 left_arm、right_arm）。
tool	const std::string &	工具信息

返回值

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

note

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

note

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

warning

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

分离工具（detach_tool）

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

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

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

参数

名称	类型	描述
chain	const std::string &	要分离工具的运动链

返回值

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

note

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

添加障碍物（add_obstacle）

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

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

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

参数

名称	类型	描述
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。

返回值

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

note

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

note

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

note

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

warning

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

移除障碍物（remove_obstacle）

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

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

参数

名称	类型	描述
obstacle_id	const std::string &	要移除的障碍物ID

返回值

类型	描述
MotionStatus	运动状态：SUCCESS（成功）、INVALID_INPUT（障碍物 ID 未找到）或 FAULT（故障）

note

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

清空障碍物（clear_obstacle）

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

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

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

返回值

类型	描述
MotionStatus	运动状态：SUCCESS（成功）或 FAULT（故障）

note

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

note

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

附加目标对象（attach_target_object）

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() 类似，但对象随机器人移动（连接到连杆/运动链），用于表示抓取的物体、传感器或有效载荷。

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

参数

名称	类型	描述
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。

返回值

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

note

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

note

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

note

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

warning

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

分离目标对象（detach_target_object）

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

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

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

参数

名称	类型	描述
obstacle_id	const std::string &	要移除的障碍物ID

返回值

类型	描述
MotionStatus	运动状态：SUCCESS（成功）、INVALID_INPUT（障碍物 ID 未找到）或 FAULT（故障）

note

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

设置运动规划配置（set_motion_plan_config）

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

设置全局运动规划配置。

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

参数

名称	类型	描述
config	std::shared_ptr< MotionPlanConfig >	新的运动规划配置

返回值

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

note

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

note

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

获取运动规划配置（get_motion_plan_config）

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

获取当前运动规划配置。

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

返回值

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

note

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

获取连杆名称（get_link_names）

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

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

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

参数

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

返回值

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

note

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

note

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

获取支持的连杆（get_support_links）

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

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

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

返回值

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

note

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

获取支持的链（get_support_chains）

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

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

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

返回值

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

note

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

获取支持的坐标系（get_support_frame）

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

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

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

返回值

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

note

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

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

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

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

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

返回值

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

note

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

获取支持的工具列表（get_support_tool_list）

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

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

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

返回值

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

note

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

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

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"）。

返回值

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

note

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

获取已构建对象列表（get_built_object_list）

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

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

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

返回值

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

note

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

获取附加对象列表（get_attached_object_list）

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

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

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

返回值

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

note

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

检查连杆名称是否有效（is_link_name_valid）

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

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

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

参数

名称	类型	描述
value	const std::string &	要验证的全身关节状态
throw_exception	bool	验证失败时是否抛出异常

返回值

类型	描述
bool	若连杆名称有效则返回 true，否则返回 false。

note

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

检查链名称是否有效（is_chain_name_valid）

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

验证运动链名称。

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

参数

名称	类型	描述
value	const std::string &	要验证的全身关节状态
throw_exception	bool	验证失败时是否抛出异常

返回值

类型	描述
bool	若运动链名称有效则返回 true，否则返回 false。

note

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

检查坐标系名称是否有效（is_frame_name_valid）

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

验证参考坐标系名称。

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

参数

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

返回值

类型	描述
bool	若坐标系名称有效则返回 true，否则返回 false。

note

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

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

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

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

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

参数

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

返回值

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

note

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

检查工具名称是否有效（is_tool_name_valid）

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

验证工具名称。

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

参数

名称	类型	描述
value	const std::string &	要验证的全身关节状态
throw_exception	bool	验证失败时是否抛出异常

返回值

类型	描述
bool	若工具名称有效则返回 true，否则返回 false。

note

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

检查障碍物类型是否有效（is_obstacle_type_valid）

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

验证障碍物几何类型。

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

参数

名称	类型	描述
value	const std::string &	要验证的全身关节状态
throw_exception	bool	验证失败时是否抛出异常

返回值

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

note

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

检查全身状态是否有效（is_whole_body_state_valid）

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

验证全身关节配置向量。

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

参数

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

返回值

类型	描述
bool	若向量长度与机器人自由度匹配则返回 true，否则返回 false。

note

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

note

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

检查7维姿态是否有效（is_pose_7d_valid）

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

参数

名称	类型	描述
value	const std::vector< double > &	要验证的 7D 位姿向量。
throw_exception	bool	验证失败时是否抛出异常

返回值

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

note

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

warning

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

检查链关节状态是否有效（is_chain_joint_state_valid）

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

验证链索引关节配置图。

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

参数

名称	类型	描述
value	const std::unordered_map< std::string, std::vector< double > > &	要验证的全身关节状态
throw_exception	bool	验证失败时是否抛出异常

返回值

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

note

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

获取机器人自由度（get_robot_dof）

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

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

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

返回值

类型	描述
int	机器人自由度（驱动关节）数量

note

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

获取机器人状态（get_robot_states）

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

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

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

返回值

类型	描述
RobotStates	RobotStates 对象包含： - whole_body_joint：完整的关节配置（弧度） - base_state：移动基座姿态 [x, y, z, qx, qy, qz, qw]（米，四元数）

note

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

note

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

获取全身状态（get_whole_body_state）

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

获取当前全身关节配置。

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

返回值

类型	描述
std::vector< double >	关节角度向量（弧度），大小 = get_robot_dof()

note

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

获取底盘状态（get_chassis_state）

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

获取当前移动基础姿态。

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

返回值

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

note

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

note

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

获取链关节状态（get_chain_joint_state）

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

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

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

返回值

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

note

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

获取链姿态状态（get_chain_pose_state）

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

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

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

参数

名称	类型	描述
frame	const std::string &	参考坐标系

返回值

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

note

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

替换关节状态（replace_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

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

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

参数

名称	类型	描述
chain_name	const std::string &	链名称
chain_joint	const std::vector< double > &	要更新的链关节
whole_body_joint	std::vector< double > &	原始全身关节向量

返回值

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

note

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

note

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

状态转字符串（status_to_string）

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

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

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

参数

名称	类型	描述
status	MotionStatus	运动状态枚举值

返回值

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

note

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

获取实例（get_instance）

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

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

参数

名称	类型	描述
m	MachineType	机器类型

返回值

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

---

移动导航（GalbotNavigation）

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

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

析构函数（~GalbotNavigation）

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

初始化（init）

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

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

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

返回值

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

note

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

note

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

warning

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

重定位（relocalize）

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

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

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

参数

名称	类型	描述
init_pose	const Pose &	初始姿态估计

返回值

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

note

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

note

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

检查是否已定位（is_localized）

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

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

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

返回值

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

note

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

note

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

获取当前姿态（get_current_pose）

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

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

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

返回值

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

note

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

note

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

导航到目标（navigate_to_goal）

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=false
) =0

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

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

参数

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

返回值

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

note

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

note

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

note

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

warning

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

设置动态目标（set_navigation_target）

virtual TaskHandle galbot::sdk::GalbotNavigation::set_navigation_target(
    const Pose &target,
    const std::string &frame="map",
    float speed_ratio=1.0,
    bool enable_collision_check=true
) =0

异步提交动态导航目标。

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

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

参数

名称	类型	描述
target	const Pose &	目标位姿，格式为 Pose（x, y, z, qx, qy, qz, qw）。
frame	const std::string &	目标位姿参考坐标系，支持 "map"、"base_link"。
speed_ratio	float	速度缩放因子 (0, 1.0]。
enable_collision_check	bool	是否启用碰撞检测。

返回值

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

查询任务状态（get_navigation_target_status）

virtual NavigationTaskSnapshot galbot::sdk::GalbotNavigation::get_navigation_target_status(
    const std::string &task_id
) =0

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

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

参数

名称	类型	描述
task_id	const std::string &	任务标识，由对应异步导航接口返回。

返回值

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

多路点导航（navigate_through_waypoints）

virtual TaskHandle galbot::sdk::GalbotNavigation::navigate_through_waypoints(
    const std::vector< Waypoint > &waypoints,
    const std::string &frame_id="map",
    bool enable_collision_check=true
) =0

提交多路点导航任务。

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

参数

名称	类型	描述
waypoints	const std::vector< Waypoint > &	按顺序排列的路点列表。
frame_id	const std::string &	参考坐标系，支持 "map"、"base_link"。
enable_collision_check	bool	是否启用碰撞检测。

返回值

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

轨迹导航（navigate_along_trajectory）

virtual TaskHandle galbot::sdk::GalbotNavigation::navigate_along_trajectory(
    const std::vector< Pose > &waypoints,
    const std::string &frame_id="map",
    float speed_ratio=1.0,
    bool enable_collision_check=true
) =0

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

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

参数

名称	类型	描述
waypoints	const std::vector< Pose > &	按顺序排列的轨迹位姿点。
frame_id	const std::string &	参考坐标系，支持 "map"、"base_link"。
speed_ratio	float	速度缩放因子 (0, 1.0]。
enable_collision_check	bool	是否启用碰撞检测。

返回值

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

导航到目标V2（navigate_to_goal_v2）

virtual NavigationStatus galbot::sdk::GalbotNavigation::navigate_to_goal_v2(
    const Pose &goal_pose,
    const std::array< double, 3 > &max_vel,
    const std::string &pose_frame="map",
    bool enable_collision_check=true,
    bool is_blocking=false,
    float timeout=5.0f,
    bool omni_plan=false
) =0

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

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

参数

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

返回值

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

note

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

note

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

warning

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

warning

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

直线移动到目标（move_straight_to）

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

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

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

参数

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

返回值

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

note

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

note

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

note

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

warning

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

warning

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

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

virtual NavigationStatus galbot::sdk::GalbotNavigation::navigate_with_velocity(
    double vx,
    double vy,
    double vyaw,
    double duration_s=3.0,
    bool enable_collision_check=true
) =0

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

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

参数

名称	类型	描述
vx	double	沿x轴的线速度，单位为米每秒。
vy	double	沿y轴的线速度，单位为米每秒。
vyaw	double	绕 z 轴的角速度，单位为弧度每秒。
duration_s	double	命令持续时间（秒）。必须大于 0.0。默认值：3.0 秒。
enable_collision_check	bool	如果为真，则启用运行时碰撞检查，通过最接近的匹配 v2 碰撞字段进行碰撞检测。默认值：真。

返回值

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

note

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

note

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

warning

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

停止导航（stop_navigation）

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

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

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

返回值

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

note

可在导航期间随时调用。

note

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

note

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

添加导航箱子（add_bounding_box）

virtual NavigationStatus galbot::sdk::GalbotNavigation::add_bounding_box(const BoxInfo &box_info)=0

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

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

参数

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

返回值

类型	描述
NavigationStatus	NavigationStatus::SUCCESS 如果盒子被融合接受；NavigationStatus::INVALID_INPUT 如果盒子信息格式错误；NavigationStatus::COMM_ERR 如果融合服务请求失败。

移除导航箱子（remove_bounding_box）

virtual NavigationStatus galbot::sdk::GalbotNavigation::remove_bounding_box(int box_tag)=0

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

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

参数

名称	类型	描述
box_tag	int	箱子的唯一标记，应与 add_bounding_box() 添加该箱子时使用的 box_tag 一致。

返回值

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

获取导航箱子（get_bounding_box）

virtual std::vector< BoxInfo > galbot::sdk::GalbotNavigation::get_bounding_box()=0

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

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

返回值

类型	描述
std::vector< BoxInfo >	当前箱子信息列表；通信失败或没有可用箱子时返回空列表。

挂载箱子到连杆（attach_box_to_link）

virtual NavigationStatus galbot::sdk::GalbotNavigation::attach_box_to_link(
    const BoxInfo &box_info,
    const std::vector< std::string > &ignore_collision_links={}
) =0

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

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

参数

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

返回值

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

从连杆解除箱子（detach_box_from_link）

virtual NavigationStatus galbot::sdk::GalbotNavigation::detach_box_from_link(int box_tag)=0

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

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

参数

名称	类型	描述
box_tag	int	箱子的唯一标记，应与 attach_box_to_link() 挂载该箱子时使用的 box_tag 一致。

返回值

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

检查路径可达性（check_path_reachability）

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

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

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

参数

名称	类型	描述
goal_pose	const Pose &	目标位姿（地图坐标系）
start_pose	const Pose &	起始位姿

返回值

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

note

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

note

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

note

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

检查目标到达（check_goal_arrival）

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

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

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

返回值

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

note

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

note

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

note

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

获取任务状态（get_navigation_status）

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

获取当前导航任务状态。

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

返回值

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

note

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

设置导航速度限制（set_navigation_velocity_limit）

virtual NavigationStatus galbot::sdk::GalbotNavigation::set_navigation_velocity_limit(
    const std::array< double, 3 > &vel_limit
) =0

设置导航速度限制。

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

参数

名称	类型	描述
vel_limit	const std::array< double, 3 > &	最大导航速度限制 [vx, vy, vyaw]。每个参数必须在 [0.05, 1.5] 范围内。线速度分量单位为米/秒，偏航速度单位为弧度/秒。低于 0.05 的值可能太小，无法可靠地驱动基座。

返回值

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

note

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

warning

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

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

virtual NavigationStatus galbot::sdk::GalbotNavigation::set_navigation_kinematics_limits(
    const std::array< double, 3 > &vel_limit,
    const std::array< double, 3 > &acc_limit,
    const std::array< double, 3 > &jerk_limit
) =0

设置导航运动学限制。

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

参数

名称	类型	描述
vel_limit	const std::array< double, 3 > &	最大速度限制 [vx, vy, vyaw]。每个分量必须在 [0.05, 1.5] 范围内。线速度分量单位为米/秒，偏航速度单位为弧度/秒。低于 0.05 的值可能太小，无法可靠地驱动基座。
acc_limit	const std::array< double, 3 > &	最大加速度限制 [ax, ay, ayaw]。每个分量的值必须在 [0.05, 7.5] 范围内。线加速度分量的单位为米/秒²，偏航加速度的单位为弧度/秒²。低于 0.05 的值可能太小，无法可靠地驱动底座。
jerk_limit	const std::array< double, 3 > &	最大加加速度限制 [jx, jy, jyaw]。每个元素必须在 [0.05, 37.5] 范围内。线性加加速度分量单位为米/秒³，偏航加加速度单位为弧度/秒³。低于 0.05 的值可能太小，无法可靠地驱动基座。

返回值

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

note

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

warning

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

设置导航超时时间（set_navigation_timeout）

virtual NavigationStatus galbot::sdk::GalbotNavigation::set_navigation_timeout(double timeout_s)=0

设置导航超时配置。

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

参数

名称	类型	描述
timeout_s	double	导航超时时间（秒）。小于或等于 0 的值将禁用导航运动时间限制。

返回值

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

note

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

设置导航到达阈值（set_navigation_arrival_threshold）

virtual NavigationStatus galbot::sdk::GalbotNavigation::set_navigation_arrival_threshold(
    const std::array< double, 3 > &threshold
) =0

设置导航到达阈值。

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

参数

名称	类型	描述
threshold	const std::array< double, 3 > &	到达阈值 [x_error, y_error, yaw_error]。每个元素必须在 [0.03, 2.0] 范围内。位置误差以米为单位，偏航误差以弧度为单位。支持的最小精度为 0.03 米或弧度。

返回值

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

note

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

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

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

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

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

返回值

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

note

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

获取实例（get_instance）

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

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

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

参数

名称	类型	描述
m	MachineType	机器类型

返回值

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

note

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

---

感知模块接口（GalbotPerception）

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

析构函数（~GalbotPerception）

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

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

virtual bool galbot::sdk::GalbotPerception::init(const std::set< PerceptionModule > &enabled_modules)=0

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

参数

名称	类型	描述
enabled_modules	const std::set< PerceptionModule > &	要启用的感知模块集合。

返回值

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

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

virtual bool galbot::sdk::GalbotPerception::run_once(PerceptionModule module)=0

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

参数

名称	类型	描述
module	PerceptionModule	要运行的感知模块。

note

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

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

virtual bool galbot::sdk::GalbotPerception::wait_for_new_result(
    PerceptionModule module,
    double timeout_s=5.0
) =0

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

参数

名称	类型	描述
module	PerceptionModule	感知模块。
timeout_s	double	超时时间（秒）。

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

virtual bool galbot::sdk::GalbotPerception::get_latest_result(
    PerceptionModule module,
    DetectionResult &result
) =0

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

参数

名称	类型	描述
module	PerceptionModule	感知模块。
result	DetectionResult &	输出检测结果。

返回值

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

获取感知模块单例实例（get_instance）

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

获取Perception模块单例实例。

参数

名称	类型	描述
m	MachineType	机器类型（如 MachineType::G1 或 MachineType::S1）。

返回值

类型	描述
GalbotPerception &	指定机器类型的单例实例引用。

---

类型与枚举（Types & Enums）

驱动类型（ActuateType）

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

枚举值	描述
ACTUATE_WITH_CHAIN_ONLY	仅执行目标运动链
ACTUATE_WITH_TORSO	执行目标运动链和躯干
ACTUATE_WITH_LEG	执行目标运动链和腿部
ACTUATE_TYPE_NUM	驱动类型数量

---

音频数据结构（AudioData）

音频数据结构。

成员变量

名称	类型	描述
header	Header	音频消息头。
type	std::string	音频类型。
format	std::string	音频格式。
data	std::vector< uint8_t >	音频数据包。

---

轴对齐2D边界框（BBox）

轴对齐2D边界框，带有类别ID和置信度分数辅助功能。

获取左上角x坐标（x1）

int BBox::x1() const

获取左上角y坐标（y1）

int BBox::y1() const

获取右下角x坐标（x2）

int BBox::x2() const

获取右下角y坐标（y2）

int BBox::y2() const

计算边界框面积（area）

float BBox::area() const

计算边界框中心点（center）

cv::Point2f BBox::center() const

成员变量

名称	类型	描述
rect	cv::Rect
cls	std::pair< int, float >

---

电池管理信息（BmsInfo）

计算边界框中心点。

成员变量

名称	类型	描述
voltage	float	电压
current	float	电流 (A)
battery_level	float	电池电量
temperature	float	温度
charging_status	bool	充电状态
health_status	bool	健康状态
capacity	float	容量

---

箱子信息（BoxInfo）

导航障碍物过滤使用的箱子信息。

该结构体用于描述需要被导航障碍物融合忽略的箱子区域，例如机器人携带的箱子或已知不会作为环境障碍物处理的区域。box_pose 遵循 SDK 的 Pose 约定：位置加四元数，四元数顺序为 x/y/z/w。box_tag 是箱子的唯一标记。

成员变量

名称	类型	描述
box_size	BoxSize	箱子在局部 x/y/z 轴方向上的尺寸，单位为米
box_pose	Pose	箱子相对于 parent_link_name 的位姿，四元数顺序为 x/y/z/w
box_tag	int	箱子的唯一标记
parent_link_name	std::string	box_pose 所在的父连杆或父坐标系名称

---

箱子尺寸（BoxSize）

箱子尺寸。 描述箱子在局部 x/y/z 轴方向上的物理尺寸，单位为米。

成员变量

名称	类型	描述
length_x	float	箱子沿 x 轴方向的长度，单位为米
length_y	float	箱子沿 y 轴方向的长度，单位为米
length_z	float	箱子沿 z 轴方向的长度，单位为米

---

相机信息（CameraInfo）

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

成员变量

名称	类型	描述
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 >	可选的变换矩阵，用于厂商特定或扩展的标定数据。大小和解释取决于具体实现。

---

运动链类型（ChainType）

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

枚举值	描述
HEAD	头部
LEFT_ARM	左臂
RIGHT_ARM	右臂
LEG	腿部
TORSO	躯干
CHAIN_NUM	运动链数量

---

碰撞检查选项（CollisionCheckOption）

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

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

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

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

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

参数

名称	类型	描述
disable	bool	传入 true 表示禁用自碰撞检测，传入 false 表示启用。

warning

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

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

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

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

参数

名称	类型	描述
disable	bool	是否禁用碰撞检测

warning

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

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

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

检查自碰撞检测是否禁用

返回值

类型	描述
bool	若当前已禁用自碰撞检测，则返回 true；否则返回 false。

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

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

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

返回值

类型	描述
bool	若当前已禁用环境碰撞检测，则返回 true；否则返回 false。

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

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

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

---

控制状态（ControlStatus）

控制命令执行状态枚举。

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

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

---

深度数据（DepthData）

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

深度图转 OpenCV Mat（convert_to_cv2_mat）

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

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

返回值

类型	描述
std::shared_ptr< cv::Mat >	解码成功时返回 std::shared_ptr<cv::Mat> 智能指针；解码失败时返回空指针。

成员变量

名称	类型	描述
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 表示像素值单位为毫米

---

检测与分割结果（DetectionAndSegmentationResult）

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

传感器数据指针类型定义（SENSORDATA_POINTER_TYPEDEFS）

DetectionAndSegmentationResult::SENSORDATA_POINTER_TYPEDEFS(DetectionAndSegmentationResult)

检测与分割结果（DetectionAndSegmentationResult）

DetectionAndSegmentationResult::DetectionAndSegmentationResult()

构造函数（DetectionAndSegmentationResult）

DetectionAndSegmentationResult::DetectionAndSegmentationResult(
    const cv::Rect &box,
    const std::string &name,
    const int index,
    const float conf,
    const std::vector< cv::Point2f > &kps=std::vector< cv::Point2f >(),
    const std::vector< cv::Point > &poly=std::vector< cv::Point >()
)

参数

名称	类型	描述
box	const cv::Rect &
name	const std::string &
index	const int
conf	const float
kps	const std::vector< cv::Point2f > &
poly	const std::vector< cv::Point > &

打印结果信息（printInfo）

void DetectionAndSegmentationResult::printInfo(std::ostream &os, bool showPolygon=false) const

参数

名称	类型	描述
os	std::ostream &
showPolygon	bool

成员变量

名称	类型	描述
bbox	cv::Rect
className	std::string
classIndex	int
confidence	float
keypoints	std::vector< cv::Point2f >
polygon	std::vector< cv::Point >

---

检测结果（DetectionResult）

打印检测和分割结果信息。

传感器数据指针类型定义（SENSORDATA_POINTER_TYPEDEFS）

DetectionResult::SENSORDATA_POINTER_TYPEDEFS(DetectionResult)

添加检测结果（addResult）

void DetectionResult::addResult(
    const cv::Rect &box,
    const std::string &className,
    int classIndex,
    float confidence
)

参数

名称	类型	描述
box	const cv::Rect &
className	const std::string &
classIndex	int
confidence	float

添加带关键点的检测结果（addResult）

void DetectionResult::addResult(
    const cv::Rect &box,
    const std::vector< cv::Point2f > &kps,
    const std::string &className,
    int classIndex,
    float confidence
)

参数

名称	类型	描述
box	const cv::Rect &
kps	const std::vector< cv::Point2f > &
className	const std::string &
classIndex	int
confidence	float

添加姿态（addPose）

void DetectionResult::addPose(const Eigen::Matrix4f &pose)

参数

名称	类型	描述
pose	const Eigen::Matrix4f &

添加关键点（addKeypoints）

void DetectionResult::addKeypoints(const std::vector< cv::Point2f > &kps)

参数

名称	类型	描述
kps	const std::vector< cv::Point2f > &

添加点云（addPointCloud）

void DetectionResult::addPointCloud(const PointCloudPtr &cloud)

参数

名称	类型	描述
cloud	const PointCloudPtr &

设置运行信息（setRunningInfo）

void DetectionResult::setRunningInfo(const std::string &info)

参数

名称	类型	描述
info	const std::string &

添加分类掩码（addClassMask）

void DetectionResult::addClassMask(const cv::Mat &mask)

参数

名称	类型	描述
mask	const cv::Mat &

添加实例掩码（addInstanceMask）

void DetectionResult::addInstanceMask(const cv::Mat &mask)

参数

名称	类型	描述
mask	const cv::Mat &

清空结果（clear）

void DetectionResult::clear()

获取结果信息（getResultInfo）

std::string DetectionResult::getResultInfo()

从其他结果复制（copyFrom）

void DetectionResult::copyFrom(const DetectionResult &other)

参数

名称	类型	描述
other	const DetectionResult &

构造函数（DetectionResult）

DetectionResult::DetectionResult()

成员变量

名称	类型	描述
timestamp_ns	EIGEN_MAKE_ALIGNED_OPERATOR_NEW int64_t
sensorName	std::string
resultImage	cv::Mat
resultPointCloud	std::vector< PointCloudPtr >
detectionAndSegmentationResults	std::vector< DetectionAndSegmentationResult >
boundingBoxes	std::vector< cv::Rect >
classNames	std::vector< std::string >
classIndices	std::vector< int >
confidences	std::vector< float >
ocrString	std::vector< std::string >
targetPoses	std::vector< Eigen::Matrix4f >
keypoints	std::vector< std::vector< cv::Point2f > >
runningInfo	std::string
classMask	cv::Mat
instanceMask	cv::Mat
garbage_result	GarbageResult::Ptr
object6DPoses	std::map< std::string, std::vector< Eigen::Matrix4f > >
grasp_pose_result	std::vector< std::vector< float > >
targetPointPoses	std::vector< Eigen::Matrix4f >
preTargetPointPoses	std::vector< Eigen::Matrix4f >
ocrPointPoses	std::vector< Eigen::Matrix4f >
ocrLabelImage	std::map< std::string, std::vector< cv::Mat > >
ocrResults	std::map< std::string, Eigen::Matrix4f >

---

设备信息（DeviceInfo）

构造函数，初始化检测结果。

成员变量

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

---

灵巧手状态（DexhandState）

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

成员变量

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

---

灵巧手类型（DexHandType）

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

枚举值	描述
INSPIRE	Inspire 灵巧手
BRAINCO	BrainCo 灵巧手
SHARPA	Sharpa 灵巧手
LINKER_L20	Linker Hand L20 灵巧手

---

力矩信息（EffortInfo）

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

成员变量

名称	类型	描述
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 轴力矩

---

错误（Error）

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

构造函数（Error）

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

构造函数

参数

名称	类型	描述
commpent_input	std::string	组件名称
error_code_input	int	错误代码
description_input	std::string	错误描述

成员变量

名称	类型	描述
commpent	std::string	组件
error_code	uint64_t	用于程序化错误处理的数值错误代码
description	std::string	错误描述

---

错误信息（ErrorInfo）

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

成员变量

名称	类型	描述
timestamp_ns	int64_t	收集错误的时间戳（自纪元以来的纳秒数）
error_vec	std::vector< Error >	误差向量

---

力数据（ForceData）

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

成员变量

名称	类型	描述
timestamp_ns	int64_t	测量时间戳（自纪元以来的纳秒数）
force	Vector3	力
torque	Vector3	力矩向量（牛顿·米）：[tx, ty, tz]

---

坐标系（FrameTriad）

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

成员变量

名称	类型	描述
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日志流（GalbotSdkLogStream）

构造函数（GalbotSdkLogStream）

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

参数

名称	类型	描述
level	LogLevel
file	const char *
func	const char *
line	int

operator<<

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

参数

名称	类型	描述
v	const T &

operator<<

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

参数

名称	类型	描述
manip	std::ostream &(*)(std::ostream &)

析构函数（~GalbotSdkLogStream）

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

---

垃圾检测结果（GarbageResult）

析构函数，销毁日志流对象并将缓冲的日志消息刷新输出。

传感器数据指针类型定义（SENSORDATA_POINTER_TYPEDEFS）

GarbageResult::SENSORDATA_POINTER_TYPEDEFS(GarbageResult)

添加垃圾检测结果（addResult）

void GarbageResult::addResult(
    const std::string &uuid,
    Eigen::Vector3f box_shape,
    const Eigen::Vector3f &box_center_pos,
    const cv::Rect &box
)

参数

名称	类型	描述
uuid	const std::string &
box_shape	Eigen::Vector3f
box_center_pos	const Eigen::Vector3f &
box	const cv::Rect &

添加点云（按UUID）（addPointCloud）

void GarbageResult::addPointCloud(const std::string &uuid, const PointCloudPtr &bbox_pointcloud)

参数

名称	类型	描述
uuid	const std::string &
bbox_pointcloud	const PointCloudPtr &

成员变量

名称	类型	描述
boxes_shape	EIGEN_MAKE_ALIGNED_OPERATOR_NEW std::map< std::string, Eigen::Vector3f >
boxes_center_pos	std::map< std::string, Eigen::Vector3f >
bboxes	std::map< std::string, cv::Rect >
bboxes_pointcloud	std::map< std::string, PointCloudPtr >

---

夹爪状态（GripperState）

为指定UUID添加边界框点云数据。

成员变量

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

---

关节组命令（GroupCommand）

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

成员变量

名称	类型	描述
time_from_start_s	double
joint_commands	std::vector< JointCommand >

---

消息头（Header）

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

成员变量

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

---

IK 求解器配置（IKSolverConfig）

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

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

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

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

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

参数

名称	类型	描述
timeout	double	求解超时（毫秒）

note

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

设置种子类型（set_seed_type）

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

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

参数

名称	类型	描述
type	SeedType	种子生成方法

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

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

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

参数

名称	类型	描述
bias	double	关节限制禁忌区域的距离阈值（单位：弧度）

note

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

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

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

设置平移收敛容差（米）

参数

名称	类型	描述
eps	const std::array< double, 3 > &	每轴位置误差容差 {x, y, z}（单位：米）

note

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

设置方向误差容差（set_rotation_eps）

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

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

参数

名称	类型	描述
eps	const std::array< double, 3 > &	按轴给出的方向误差容差 {roll, pitch, yaw}（单位：弧度）

note

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

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

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

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

参数

名称	类型	描述
enable	bool	true 以输出碰撞检测日志，false 以抑制日志

note

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

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

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

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

返回值

类型	描述
double	超时持续时间（单位：毫秒）

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

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

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

返回值

类型	描述
SeedType	当前种子生成方法

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

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

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

返回值

类型	描述
double	关节限制偏置距离（单位：弧度）

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

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

获取平移收敛容差（米）

返回值

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

获取方向误差容差（get_rotation_eps）

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

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

返回值

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

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

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

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

返回值

类型	描述
bool	启用碰撞检测日志时返回 true，禁用时返回 false。

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

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

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

嵌套枚举

随机种子类型（SeedType）

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

枚举值	描述
RANDOM_SEED	随机种子
RANDOM_PROGRESSIVE_SEED	随机渐进种子
USER_DEFINED_SEED	用户自定义种子

---

IMU数据（ImuData）

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

成员变量

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

---

红外图像数据（IrData）

包含来自深度相机（例如 RealSense infra1/infra2）的压缩红外 (IR) 图像数据。兼容 ROS 2 sensor_msgs/CompressedImage 格式，采用单声道编码。

红外图转 OpenCV Mat（convert_to_cv2_mat）

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

将压缩的红外图像数据解码为 OpenCV Mat。

使用 cv::imdecode 和 IMREAD_GRAYSCALE 对内部存储的压缩二进制数据进行解码，生成单通道 Mat。

返回值

类型	描述
std::shared_ptr< cv::Mat >	解码成功时返回 std::shared_ptr<cv::Mat> 智能指针；解码失败时返回空指针。

成员变量

名称	类型	描述
header	Header	包含采集时间戳和相机坐标系
format	std::string	指定压缩格式和编码。例如："mono8; jpeg compressed mono8"
height	uint32_t	图片高度（像素）。
width	uint32_t	图片宽度（以像素为单位）。
data	std::vector< uint8_t >	包含压缩红外图像的二进制数据块。

---

关节命令（JointCommand）

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

成员变量

名称	类型	描述
position	double	期望的关节位置（弧度）
velocity	double	期望的关节速度（弧度/秒）
acceleration	double	加速度
effort	double	期望的关节力矩（牛顿·米）

---

单关节状态（JointState）

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

单关节状态（JointState）

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

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

构造函数（JointState）

galbot::sdk::JointState::JointState(
    double position_input,
    double velocity_input,
    double acceleration_input,
    double effort_input,
    double current_input,
    int64_t timestamp_ns_input,
    const std::string &joint_name_input=""
)

构造函数。

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

参数

名称	类型	描述
position_input	double	位置输入
velocity_input	double	速度输入
acceleration_input	double	加速度输入
effort_input	double	关节力矩/effort（牛顿·米，N·m）。
current_input	double	电流输入
timestamp_ns_input	int64_t	关节状态时间戳（自纪元以来的纳秒数）。
joint_name_input	const std::string &	关节名称，用于标识该关节状态样本。

成员变量

名称	类型	描述
joint_name	std::string	关节名称
timestamp_ns	int64_t	关节状态时间戳（自纪元以来的纳秒数）
position	double	关节角位置（弧度）
velocity	double	关节角速度（弧度/秒）
acceleration	double	关节角加速度（弧度/秒²）
effort	double	关节力矩（牛顿·米，N·m）。
current	double	关节电流（安培）

---

关节状态消息（JointStateMessage）

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

成员变量

名称	类型	描述
timestamp_ns	int64_t	采集时间戳（自纪元以来的纳秒数）
joint_state_vec	std::vector< JointState >	关节状态向量

---

关节状态（JointStates）

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

获取类型（get_type）

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

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

返回值

类型	描述
Type	类型::JOINT，表示这是一个关节间隙目标

设置关节位置（set_joint_positions）

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

设置所有关节位置

参数

名称	类型	描述
joints	const std::vector< double > &	关节状态列表

note

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

设置关节（set_joint）

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

设置指定索引的关节值

参数

名称	类型	描述
index	int	关节索引
val	int	关节值数组

note

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

warning

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

成员变量

名称	类型	描述
joint_positions	std::vector< double >	链的目标关节配置

---

运动学边界（KinematicsBoundary）

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

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

设置运动链名称（set_chain_name）

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

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

参数

名称	类型	描述
name	const std::string &	边界名称

设置下限位置限制（set_lower_limit）

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

设置关节位置下限

参数

名称	类型	描述
limits	const std::vector< double > &	每个关节的下限位置限制向量

note

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

设置上限位置限制（set_upper_limit）

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

设置关节位置上限

参数

名称	类型	描述
limits	const std::vector< double > &	每个关节的上限位置限制向量

note

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

设置下限速度限制（set_vel_lower_limit）

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

设置速度下限

参数

名称	类型	描述
limits	const std::vector< double > &	每个关节的速度下限向量（单位：rad/s）。

note

双向关节通常为负值。

设置上限速度限制（set_vel_upper_limit）

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

设置速度上限

参数

名称	类型	描述
limits	const std::vector< double > &	每个关节的速度上限向量（单位：rad/s）。

note

双向关节通常为正值。

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

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

设置加速度下限

参数

名称	类型	描述
limits	const std::vector< double > &	每个关节的加速度下限向量（单位：rad/s²）。

note

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

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

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

设置加速度上限

参数

名称	类型	描述
limits	const std::vector< double > &	每个关节的加速度上限向量（单位：rad/s²）。

note

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

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

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

设置加加速度下限

参数

名称	类型	描述
limits	const std::vector< double > &	每个关节的加加速度下限向量（单位：rad/s³）。

note

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

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

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

设置加加速度上限

参数

名称	类型	描述
limits	const std::vector< double > &	每个关节的加加速度上限向量（单位：rad/s³）。

note

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

获取运动链名称（get_chain_name）

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

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

返回值

类型	描述
const std::string &	运动链名称字符串的常量引用

获取下限位置限制（get_lower_limit）

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

获取关节位置下限（rad）

返回值

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

获取上限位置限制（get_upper_limit）

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

获取关节位置上限（rad）

返回值

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

获取下限速度限制（get_vel_lower_limit）

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

获取速度下限（rad/s）

返回值

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

获取上限速度限制（get_vel_upper_limit）

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

获取速度上限（rad/s）

返回值

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

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

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

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

返回值

类型	描述
const std::vector< double > &	常量引用，向量下限加速度限制（单位：rad/s²）

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

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

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

返回值

类型	描述
const std::vector< double > &	常量引用：每个关节的加速度上限向量（单位：rad/s²）。

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

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

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

返回值

类型	描述
const std::vector< double > &	向量下限加加速度限制（每个关节，单位：rad/s³）

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

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

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

返回值

类型	描述
const std::vector< double > &	向量上限加加速度限制（每个关节，单位：rad/s³）

打印输出（print）

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

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

---

激光雷达数据（LidarData）

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

成员变量

名称	类型	描述
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）

---

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

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

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

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

void galbot::sdk::LineTrajCheckPrimitive::set_line_check_primitive_type(PrimitiveType type)

设置直线检查基元类型

参数

名称	类型	描述
type	PrimitiveType	直线轨迹类型

note

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

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

void galbot::sdk::LineTrajCheckPrimitive::set_cylinder_prim_radius(double radius)

设置圆柱基元半径（米）

参数

名称	类型	描述
radius	double	轨迹曲率半径

note

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

note

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

设置直线基元曲率（set_line_prim_curvature）

void galbot::sdk::LineTrajCheckPrimitive::set_line_prim_curvature(double curvature)

设置直线基元曲率

参数

名称	类型	描述
curvature	double	曲线曲率

note

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

note

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

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

PrimitiveType galbot::sdk::LineTrajCheckPrimitive::get_line_check_primitive_type() const

获取直线检查基元类型

返回值

类型	描述
PrimitiveType	当前基元类型（LINE 或 CYLINDER）

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

double galbot::sdk::LineTrajCheckPrimitive::get_cylinder_prim_radius() const

获取圆柱基元半径（米）

返回值

类型	描述
double	圆柱体基元半径（单位：米）

获取直线基元曲率（get_line_prim_curvature）

double galbot::sdk::LineTrajCheckPrimitive::get_line_prim_curvature() const

获取直线基元曲率

返回值

类型	描述
double	直线基元曲率

打印输出（print）

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

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

嵌套枚举

几何基元类型（PrimitiveType）

直线轨迹检查基元类型枚举

枚举值	描述
LINE	直线
CYLINDER	圆柱体

---

日志配置（LoggerConfig）

定义日志系统的配置参数，包括文件设置、日志级别和输出选项。

成员变量

名称	类型	描述
path	std::string	路径
file_name	std::string	文件名
file_max_size	uint64_t	最大文件大小
file_max_num	uint64_t	最大文件数
level	LogLevel	级别
console_output	bool	控制台输出

---

日志信息（LogInfo）

日志信息。

成员变量

名称	类型	描述
level	std::string
message	std::string	消息

---

日志级别（LogLevel）

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

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

---

机器类型（MachineType）

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

枚举值	描述
S1	S1机器人

---

运动规划配置（MotionPlanConfig）

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

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

构造函数（MotionPlanConfig）

galbot::sdk::MotionPlanConfig::MotionPlanConfig()=default

运动规划配置类

设置更新时间（set_update_time）

void galbot::sdk::MotionPlanConfig::set_update_time(int64_t t)

设置更新时间参数

参数

名称	类型	描述
t	int64_t	时间参数

note

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

获取更新时间（get_update_time）

int64_t galbot::sdk::MotionPlanConfig::get_update_time()

获取更新时间参数

返回值

类型	描述
int64_t	上次配置修改的时间戳（单位：纳秒）

创建采样器配置（create_sampler_config）

std::shared_ptr< SamplerConfig > galbot::sdk::MotionPlanConfig::create_sampler_config()

创建采样器配置并返回

返回值

类型	描述
std::shared_ptr< SamplerConfig >	采样器配置的共享指针

创建轨迹规划配置（create_trajectory_plan_config）

std::shared_ptr< TrajectoryPlanConfig > galbot::sdk::MotionPlanConfig::create_trajectory_plan_config()

创建轨迹规划配置并返回

返回值

类型	描述
std::shared_ptr< TrajectoryPlanConfig >	轨迹规划配置的共享指针

创建IK 求解器配置（create_ik_solver_config）

std::shared_ptr< IKSolverConfig > galbot::sdk::MotionPlanConfig::create_ik_solver_config()

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

返回值

类型	描述
std::shared_ptr< IKSolverConfig >	IK 求解器配置的共享指针

创建碰撞检查选项（create_collision_check_option）

std::shared_ptr< CollisionCheckOption > galbot::sdk::MotionPlanConfig::create_collision_check_option()

创建碰撞检测选项并返回

返回值

类型	描述
std::shared_ptr< CollisionCheckOption >	碰撞检查选项的共享指针

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

std::shared_ptr< TrajectoryFeasibilityCheckOption > galbot::sdk::MotionPlanConfig::create_trajectory_feasibility_check_option()

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

返回值

类型	描述
std::shared_ptr< TrajectoryFeasibilityCheckOption >	轨迹可行性检查选项的共享指针

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

std::shared_ptr< LineTrajCheckPrimitive > galbot::sdk::MotionPlanConfig::create_line_traj_check_primitive()

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

返回值

类型	描述
std::shared_ptr< LineTrajCheckPrimitive >	直线轨迹检查基元的共享指针

设置采样器配置（set_sampler_config）

void galbot::sdk::MotionPlanConfig::set_sampler_config(const std::shared_ptr< SamplerConfig > &config)

设置采样器配置

参数

名称	类型	描述
config	const std::shared_ptr< SamplerConfig > &	采样器配置的共享指针；传入 nullptr 清除配置。

设置轨迹规划配置（set_trajectory_plan_config）

void galbot::sdk::MotionPlanConfig::set_trajectory_plan_config(
    const std::shared_ptr< TrajectoryPlanConfig > &config
)

设置轨迹规划配置

参数

名称	类型	描述
config	const std::shared_ptr< TrajectoryPlanConfig > &	新的运动规划配置

设置IK 求解器配置（set_ik_solver_config）

void galbot::sdk::MotionPlanConfig::set_ik_solver_config(const std::shared_ptr< IKSolverConfig > &config)

设置逆运动学求解器配置

参数

名称	类型	描述
config	const std::shared_ptr< IKSolverConfig > &	IK 求解器配置的共享指针；传入 nullptr 清除配置。

设置碰撞检查选项（set_collision_check_option）

void galbot::sdk::MotionPlanConfig::set_collision_check_option(
    const std::shared_ptr< CollisionCheckOption > &option
)

设置碰撞检测选项

参数

名称	类型	描述
option	const std::shared_ptr< CollisionCheckOption > &	碰撞检查选项的共享指针；传入 nullptr 清除选项。

设置轨迹可行性检查选项（set_trajectory_feasibility_check_option）

void galbot::sdk::MotionPlanConfig::set_trajectory_feasibility_check_option(
    const std::shared_ptr< TrajectoryFeasibilityCheckOption > &option
)

设置轨迹可行性检查选项

参数

名称	类型	描述
option	const std::shared_ptr< TrajectoryFeasibilityCheckOption > &	选项

设置可行性边界（set_feasibility_boundary）

void galbot::sdk::MotionPlanConfig::set_feasibility_boundary(
    const std::vector< KinematicsBoundary > &boundary
)

设置可行性边界约束

参数

名称	类型	描述
boundary	const std::vector< KinematicsBoundary > &	运动学边界向量，每个运动链一个

note

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

设置直线轨迹检查基元（set_line_traj_check_primitive）

void galbot::sdk::MotionPlanConfig::set_line_traj_check_primitive(
    const std::shared_ptr< LineTrajCheckPrimitive > &primitive
)

设置直线轨迹检查基元

参数

名称	类型	描述
primitive	const std::shared_ptr< LineTrajCheckPrimitive > &	运动基元

设置IK 关节约束（set_ik_joint_limit）

void galbot::sdk::MotionPlanConfig::set_ik_joint_limit(const std::vector< KinematicsBoundary > &boundary)

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

参数

名称	类型	描述
boundary	const std::vector< KinematicsBoundary > &	IK 求解器关节约束的运动学边界向量

note

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

设置采样关节约束（set_sampler_joint_limit）

void galbot::sdk::MotionPlanConfig::set_sampler_joint_limit(const std::vector< KinematicsBoundary > &boundary)

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

参数

名称	类型	描述
boundary	const std::vector< KinematicsBoundary > &	采样算法的运动学边界向量

note

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

设置硬关节约束（set_hard_joint_limit）

void galbot::sdk::MotionPlanConfig::set_hard_joint_limit(const std::vector< KinematicsBoundary > &boundary)

设置硬关节位置限制边界

参数

名称	类型	描述
boundary	const std::vector< KinematicsBoundary > &	边界约束

note

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

设置是否恢复 IK 关节限制（set_revert_ik_joint_limit）

void galbot::sdk::MotionPlanConfig::set_revert_ik_joint_limit(bool flag)

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

参数

名称	类型	描述
flag	bool	标志位

note

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

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

void galbot::sdk::MotionPlanConfig::set_revert_ik_joint_limit_chains(const std::vector< std::string > &chains)

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

参数

名称	类型	描述
chains	const std::vector< std::string > &	运动链列表

note

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

note

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

获取采样器配置（get_sampler_config）

std::shared_ptr< SamplerConfig > galbot::sdk::MotionPlanConfig::get_sampler_config() const

获取采样器配置

返回值

类型	描述
std::shared_ptr< SamplerConfig >	采样器配置的共享指针；未设置时返回 nullptr。

note

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

获取轨迹规划配置（get_trajectory_plan_config）

std::shared_ptr< TrajectoryPlanConfig > galbot::sdk::MotionPlanConfig::get_trajectory_plan_config() const

获取轨迹规划配置

返回值

类型	描述
std::shared_ptr< TrajectoryPlanConfig >	轨迹规划配置的共享指针；未设置时返回 nullptr。

note

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

获取IK 求解器配置（get_ik_solver_config）

std::shared_ptr< IKSolverConfig > galbot::sdk::MotionPlanConfig::get_ik_solver_config() const

获取逆运动学求解器配置

返回值

类型	描述
std::shared_ptr< IKSolverConfig >	IK 求解器配置的共享指针；未设置时返回 nullptr。

note

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

获取碰撞检查选项（get_collision_check_option）

std::shared_ptr< CollisionCheckOption > galbot::sdk::MotionPlanConfig::get_collision_check_option() const

获取碰撞检测选项

返回值

类型	描述
std::shared_ptr< CollisionCheckOption >	碰撞检查选项的共享指针；未设置时返回 nullptr。

note

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

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

std::shared_ptr< TrajectoryFeasibilityCheckOption > galbot::sdk::MotionPlanConfig::get_trajectory_feasibility_check_option() const

获取轨迹可行性检查选项

返回值

类型	描述
std::shared_ptr< TrajectoryFeasibilityCheckOption >	轨迹可行性检查选项的共享指针；未设置时返回 nullptr。

note

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

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

std::shared_ptr< LineTrajCheckPrimitive > galbot::sdk::MotionPlanConfig::get_line_traj_check_primitive() const

获取直线轨迹检查基元

返回值

类型	描述
std::shared_ptr< LineTrajCheckPrimitive >	直线轨迹检查基元的共享指针；未设置时返回 nullptr。

note

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

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

SamplerConfig & galbot::sdk::MotionPlanConfig::get_sampler_config_ref()

获取采样器配置引用

返回值

类型	描述
SamplerConfig &	采样器配置的可修改引用（保证非空）。

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

TrajectoryPlanConfig & galbot::sdk::MotionPlanConfig::get_trajectory_plan_config_ref()

获取轨迹规划配置引用

返回值

类型	描述
TrajectoryPlanConfig &	轨迹规划配置的可修改引用（保证非空）。

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

IKSolverConfig & galbot::sdk::MotionPlanConfig::get_ik_solver_config_ref()

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

返回值

类型	描述
IKSolverConfig &	IK 求解器配置的可修改引用（保证非空）。

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

CollisionCheckOption & galbot::sdk::MotionPlanConfig::get_collision_check_option_ref()

获取碰撞检测选项引用

返回值

类型	描述
CollisionCheckOption &	碰撞检查选项的可修改引用（保证非空）。

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

TrajectoryFeasibilityCheckOption & galbot::sdk::MotionPlanConfig::get_trajectory_feasibility_check_option_ref()

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

返回值

类型	描述
TrajectoryFeasibilityCheckOption &	轨迹可行性检查选项的可修改引用（保证非空）。

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

LineTrajCheckPrimitive & galbot::sdk::MotionPlanConfig::get_line_traj_check_primitive_ref()

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

返回值

类型	描述
LineTrajCheckPrimitive &	直线轨迹检查基元的可修改引用（保证非空）。

获取可行性边界（get_feasibility_boundary）

const std::vector< KinematicsBoundary > & galbot::sdk::MotionPlanConfig::get_feasibility_boundary() const

获取可行性边界约束

返回值

类型	描述
const std::vector< KinematicsBoundary > &	运动学可行性边界向量的可修改引用。

获取可行性边界（get_feasibility_boundary）

std::vector< KinematicsBoundary > & galbot::sdk::MotionPlanConfig::get_feasibility_boundary()

获取可行性边界约束

返回值

类型	描述
std::vector< KinematicsBoundary > &	运动学可行性边界向量的可修改引用。

获取IK 关节约束（get_ik_joint_limit）

const std::vector< KinematicsBoundary > & galbot::sdk::MotionPlanConfig::get_ik_joint_limit() const

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

返回值

类型	描述
const std::vector< KinematicsBoundary > &	IK 关节限制边界向量的可修改引用。

获取IK 关节约束（get_ik_joint_limit）

std::vector< KinematicsBoundary > & galbot::sdk::MotionPlanConfig::get_ik_joint_limit()

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

返回值

类型	描述
std::vector< KinematicsBoundary > &	IK 关节限制边界向量的可修改引用。

获取采样关节约束（get_sampler_joint_limit）

const std::vector< KinematicsBoundary > & galbot::sdk::MotionPlanConfig::get_sampler_joint_limit() const

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

返回值

类型	描述
const std::vector< KinematicsBoundary > &	采样关节限制边界向量的可修改引用。

获取采样关节约束（get_sampler_joint_limit）

std::vector< KinematicsBoundary > & galbot::sdk::MotionPlanConfig::get_sampler_joint_limit()

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

返回值

类型	描述
std::vector< KinematicsBoundary > &	采样关节限制边界向量的可修改引用。

获取硬关节约束（get_hard_joint_limit）

const std::vector< KinematicsBoundary > & galbot::sdk::MotionPlanConfig::get_hard_joint_limit() const

获取硬关节位置限制边界

返回值

类型	描述
const std::vector< KinematicsBoundary > &	硬关节限制边界向量的可修改引用。

note

硬限制代表绝对的机械/安全约束，必须永不违反。

获取硬关节约束（get_hard_joint_limit）

std::vector< KinematicsBoundary > & galbot::sdk::MotionPlanConfig::get_hard_joint_limit()

获取硬关节位置限制边界

返回值

类型	描述
std::vector< KinematicsBoundary > &	硬关节限制边界向量的可修改引用。

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

const std::vector< std::string > & galbot::sdk::MotionPlanConfig::get_revert_ik_joint_limit_chains() const

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

返回值

类型	描述
const std::vector< std::string > &	需要恢复 IK 关节限制的运动链名称向量的可修改引用（保证非空）。

note

空向量表示在所有链上恢复（如果标志启用）。

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

std::vector< std::string > & galbot::sdk::MotionPlanConfig::get_revert_ik_joint_limit_chains()

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

返回值

类型	描述
std::vector< std::string > &	需要恢复 IK 关节限制的运动链名称向量的可修改引用（保证非空）。

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

bool galbot::sdk::MotionPlanConfig::get_revert_ik_joint_limit()

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

返回值

类型	描述
bool	true：将 IK 关节限制恢复为硬限制；false：使用默认限制。

打印输出（print）

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

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

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

---

运动状态（MotionStatus）

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

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

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

---

导航状态（NavigationStatus）

导航任务执行状态枚举。

定义执行导航命令（例如移动到目标位置或遵循路径）时可能的结果。

枚举值	描述
SUCCESS	导航任务成功完成
FAIL	失败
TIMEOUT	执行超时，任务未在允许的时间内完成
INVALID_INPUT	无效输入
MODE_ERR	模式错误
COMM_ERR	通信错误
WAIT_INITIALIZED	等待初始化

---

导航任务快照（NavigationTaskSnapshot）

导航任务快照。

成员变量

名称	类型	描述
task_id	std::string	任务标识。
status	NavigationTaskStatus	任务最新状态。
msg	std::string	任务对应的简短消息。

---

导航任务状态（NavigationTaskStatus）

导航任务状态。

枚举值	描述
UNKNOWN	未知。
RUNNING	运行中。
SUCCESS	成功。
FAILED	失败。
INTERRUPTED	中断。
OCCUPIED	占用。
COLLISION	碰撞。
CLOSE_TO_OBSTACLE	接近障碍物。

---

里程计数据（OdomData）

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

成员变量

名称	类型	描述
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]（弧度/秒）

---

参数（Parameter）

运动规划参数配置类。

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

参数（Parameter）

galbot::sdk::Parameter::Parameter()=default

运动规划参数配置类。

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

构造函数（Parameter）

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"
)

全身运动规划配置的参数化构造函数。

参数

名称	类型	描述
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 字符串会导致未定义行为；确保使用有效键。

设置是否直接执行（set_direct_execute）

void galbot::sdk::Parameter::set_direct_execute(bool direct_execute)

设置是否直接执行

参数

名称	类型	描述
direct_execute	bool	是否直接执行

设置是否阻塞（set_blocking）

void galbot::sdk::Parameter::set_blocking(bool blocking)

设置是否阻塞执行

参数

名称	类型	描述
blocking	bool	是否阻塞

设置超时（set_timeout）

void galbot::sdk::Parameter::set_timeout(double timeout)

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

参数

名称	类型	描述
timeout	double	运动执行允许的最大时间（秒，必须为正值）。

note

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

设置驱动类型（set_actuate）

void galbot::sdk::Parameter::set_actuate(const std::string &actuate)

设置驱动类型

参数

名称	类型	描述
actuate	const std::string &	驱动类型

warning

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

设置工具位姿（set_tool_pose）

void galbot::sdk::Parameter::set_tool_pose(bool tool_pose)

设置目标工具位姿

参数

名称	类型	描述
tool_pose	bool	工具位姿

设置是否检测碰撞（set_check_collision）

void galbot::sdk::Parameter::set_check_collision(bool check_collision)

设置是否进行碰撞检测

参数

名称	类型	描述
check_collision	bool	如果为 true，规划器会对自碰撞和环境障碍物进行碰撞检测；如果为 false，则跳过碰撞检查

warning

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

设置参考帧（set_reference_frame）

void galbot::sdk::Parameter::set_reference_frame(const std::string &frame)

设置参考坐标系

参数

名称	类型	描述
frame	const std::string &	参考帧名称（例如："base_link"、"world"、"odom"）

note

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

设置是否使用直线运动（set_move_line）

void galbot::sdk::Parameter::set_move_line(bool flag)

设置是否为直线运动

参数

名称	类型	描述
flag	bool	标志位

note

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

获取是否直接执行（get_direct_execute）

bool galbot::sdk::Parameter::get_direct_execute() const

获取是否直接执行

返回值

类型	描述
bool	true 直接执行计划的运动，false 不执行。

获取是否阻塞（get_blocking）

bool galbot::sdk::Parameter::get_blocking() const

获取是否阻塞执行

返回值

类型	描述
bool	true 阻塞直到运动完成或超时，false 不阻塞。

获取超时（get_timeout）

double galbot::sdk::Parameter::get_timeout() const

获取超时时间（秒）

返回值

类型	描述
double	超时时长（秒，正值）。

获取驱动类型（get_actuate_type）

std::string galbot::sdk::Parameter::get_actuate_type() const

获取驱动类型

返回值

类型	描述
std::string	驱动类型字符串（"with_chain_only"、"with_torso"、"with_leg"或"unknown"（如果未找到））

获取工具位姿（get_tool_pose）

bool galbot::sdk::Parameter::get_tool_pose() const

获取目标工具位姿

返回值

类型	描述
bool	true 目标姿态相对于工具帧，false 相对于末端执行器。

获取是否检测碰撞（get_check_collision）

bool galbot::sdk::Parameter::get_check_collision() const

获取是否进行碰撞检测

返回值

类型	描述
bool	如果启用碰撞检测则为 true，否则为 false

获取参考帧（get_reference_frame）

std::string galbot::sdk::Parameter::get_reference_frame() const

获取参考坐标系

返回值

类型	描述
std::string	参考帧名称

是否使用直线运动（is_move_line）

bool galbot::sdk::Parameter::is_move_line()

判断是否为直线运动

返回值

类型	描述
bool	true 使用直线（笛卡尔）运动，false 使用标准轨迹。

---

感知模块（PerceptionModule）

启用的感知管道（初始化时加载的模型集）。

枚举值	描述
FOUNDATION_STEREO
LIGHT_STEREO
STATUS_NUM

---

规划器配置（PlannerConfig）

运动规划配置结构。

用于机器人运动规划和执行的全面配置，控制规划模式、碰撞检查、参考坐标系和执行参数等行为。

成员变量

名称	类型	描述
enable_env_collision_check	bool
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 表示在关节空间中规划标准轨迹（可能不是笛卡尔直线）

---

点（Point）

表示三维笛卡尔空间中的位置。

成员变量

名称	类型	描述
x	double	X坐标（米）
y	double	Y坐标（米）
z	double	Z坐标（米）

---

二维点（Point2d）

表示二维笛卡尔空间中的位置。

成员变量

名称	类型	描述
x	double	X坐标（米）
y	double	Y坐标（米）

---

点云字段（PointField）

描述 PointCloud2 点结构中的一个数据字段，定义其名称、类型、偏移量和计数。与 ROS 2sensor_msgs/PointField 兼容。

成员变量

名称	类型	描述
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 元素向量）

嵌套枚举

数据类型（DataType）

点字段数据类型枚举

枚举值	描述
UNKNOWN	未知
INT8	8位整数
UINT8	8位无符号整数
INT16	16位整数
UINT16	16位无符号整数
INT32	32位整数
UINT32	32位无符号整数
FLOAT32	32位浮点数
FLOAT64	64位浮点数

---

姿态（Pose）

姿态（位置+方向）结构。

表示 3D 空间中的完整 6-DOF（自由度）姿态，结合位置（平移）和方向（旋转）信息。常用于机器人末端执行器姿态、物体姿态和坐标系变换。

姿态（Pose）

galbot::sdk::Pose::Pose()=default

姿态（位置+方向）结构。

表示 3D 空间中的完整 6-DOF（自由度）姿态，结合位置（平移）和方向（旋转）信息。常用于机器人末端执行器姿态、物体姿态和坐标系变换。

构造函数（Pose）

galbot::sdk::Pose::Pose(const T &pos, const T &quat)

构造函数，使用位置和四元数初始化位姿

参数

名称	类型	描述
pos	const T &	三维位置向量 [x, y, z]，单位：米，长度必须为 3。
quat	const T &	四元数

构造函数（Pose）

galbot::sdk::Pose::Pose(const T &vec)

构造函数，使用7维向量初始化位姿

参数

名称	类型	描述
vec	const T &	7维向量：[x, y, z, qx, qy, qz, qw]，前三项为位置（米），后四项为四元数

成员变量

名称	类型	描述
position	Point	三维位置（x, y, z），单位：米。
orientation	Quaternion	方向

---

二维位姿（Pose2d）

二维位姿（位置+偏航）结构，适用于移动基座和导航目标表示二维笛卡尔空间中的平面位姿，结合了位置（平移）和航向角信息。

常用于移动基座位姿和局部导航目标。

二维位姿（Pose2d）

galbot::sdk::Pose2d::Pose2d()=default

二维位姿（位置+偏航）结构，适用于移动基座和导航目标表示二维笛卡尔空间中的平面位姿，结合了位置（平移）和航向角信息。

常用于移动基座位姿和局部导航目标。

构造函数（Pose2d）

galbot::sdk::Pose2d::Pose2d(const T &vec)

使用单个三维向量初始化 Pose2d。

参数

名称	类型	描述
vec	const T &	三维向量：[x, y, theta]，其中前两个元素是位置（米），最后一个元素是偏航角（弧度）。

成员变量

名称	类型	描述
position	Point2d	二维空间中的位置 (x, y)，单位为米
theta	double	偏航角（弧度）

---

姿态状态（PoseState）

表示笛卡尔空间 (SE(3)) 中的目标末端执行器姿态。扩展 RobotStates 为运动链指定基于姿态的运动目标。用于逆运动学和笛卡尔轨迹规划。姿态值：以米为单位的位置，以四元数为单位的方向。坐标系必须存在于机器人的 TF 树中。

获取类型（get_type）

Type galbot::sdk::PoseState::get_type() const override

获取位姿状态类型

返回值

类型	描述
Type	类型::POSE，表示这是一个笛卡尔姿态目标

成员变量

名称	类型	描述
frame_id	std::string	运动链上的目标帧（例如："left_ee"）
reference_frame	std::string	参考坐标系（例如："base_link"）
pose	Pose	位姿

---

四元数（Quaternion）

使用四元数表示 (x, y, z, w) 表示 3D 旋转。单位四元数的大小为 1，表示有效旋转。

成员变量

名称	类型	描述
x	double	X坐标
y	double	Y坐标
z	double	Z坐标
w	double	四元数w分量

---

参考坐标系（ReferenceFrame）

指定表达姿态、位置或轨迹的坐标系。注意：这是一个用于 C 风格兼容性的普通枚举（不是枚举类）。

枚举值	描述
FRAME_WORLD	世界坐标系
FRAME_BASE	基座坐标系

---

感兴趣区域（RegionOfInterest）

定义图像内的矩形子区域以进行选择性处理。与 ROS 2sensor_msgs/RegionOfInterest 兼容。

成员变量

名称	类型	描述
x_offset	uint32_t	X偏移
y_offset	uint32_t	Y偏移
height	uint32_t	感兴趣区域的像素行数
width	uint32_t	感兴趣区域的像素列数
do_rectify	bool	是否校正

---

RGB数据（RgbData）

包含来自 RGB 相机的压缩彩色图像数据。兼容 ROS 2sensor_msgs/CompressedImage 格式。

RGB 图像转 OpenCV Mat（convert_to_cv2_mat）

std::shared_ptr< cv::Mat > galbot::sdk::RgbData::convert_to_cv2_mat()

将RGB图像数据解码并转换为OpenCV

Mat格式以进行处理

返回值

类型	描述
std::shared_ptr< cv::Mat >	解码成功时返回 std::shared_ptr<cv::Mat> 智能指针；解码失败时返回空指针。

成员变量

名称	类型	描述
header	Header	包含采集时间戳和相机坐标系
format	std::string	指定压缩格式和编码
data	std::vector< uint8_t >	包含压缩图像数据的二进制数据块

---

机器人状态（RobotStates）

封装机器人的完整运动状态，包括全身关节配置和移动底座位姿。此类作为更专业的状态表示（PoseState、JointStates）的基础，并在整个规划和控制管道中用于状态规范和反馈。所有角度值均以弧度为单位，线性值以米（SI 单位）为单位。基本姿态使用四元数表示方向（x、y、z、qx、qy、qz、qw）。

获取类型（get_type）

virtual Type galbot::sdk::RobotStates::get_type() const

获取机器人状态类型

返回值

类型	描述
Type	类型枚举值，基类为 ROBOT_STATES

机器人状态（RobotStates）

galbot::sdk::RobotStates::RobotStates()=default

封装机器人的完整运动状态，包括全身关节配置和移动底座位姿。此类作为更专业的状态表示（PoseState、JointStates）的基础，并在整个规划和控制管道中用于状态规范和反馈。所有角度值均以弧度为单位，线性值以米（SI 单位）为单位。基本姿态使用四元数表示方向（x、y、z、qx、qy、qz、qw）。

设置全身关节（set_whole_body_joint）

void galbot::sdk::RobotStates::set_whole_body_joint(const std::vector< double > &joint_positions)

设置全身关节位置

参数

名称	类型	描述
joint_positions	const std::vector< double > &	目标关节位置

note

向量大小应等于总驱动关节数。

设置基座状态（set_base_state）

void galbot::sdk::RobotStates::set_base_state(const Pose &base_pose)

设置底座状态（位姿）

参数

名称	类型	描述
base_pose	const Pose &	SE(3)中的基座姿态：位置（米）和方向（四元数）

note

四元数必须单位归一化（x^2 + y^2 + z^2 + w^2 = 1）。

构造函数（RobotStates）

galbot::sdk::RobotStates::RobotStates(
    const std::string &chain,
    const std::vector< double > &whole_joint,
    const Pose &base_pose
)

构造函数，使用运动链、全身关节和底座位姿初始化机器人状态

参数

名称	类型	描述
chain	const std::string &	要分离工具的运动链
whole_joint	const std::vector< double > &	全身关节
base_pose	const Pose &	移动基座位姿：位置（米）+ 姿态（单位四元数）。

成员变量

名称	类型	描述
chain_name	std::string	链名称
whole_body_joint	std::vector< double >	全身关节
base_state	std::vector< double >	移动基座位姿：[x, y, z, qx, qy, qz, qw]（米，四元数）。

嵌套枚举

类型（Type）

机器人状态类型枚举

Used for runtime type identification of RobotStates-derived classes.

枚举值	描述
POSE	姿态
JOINT	关节
ROBOT_STATES	机器人状态数量

---

S1控制器名称（S1ControllerName）

S1 控制器名称的字符串常量。

定义S1机器人型号支持的控制器名称。

成员变量

名称	类型	描述
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关节组（S1JointGroup）

“关节组”是 SDK 的主要控制/规划单元，而不是单个关节： 运动一致控制：每个链/末端执行器组都会验证和执行命令。确定性命令排序：joint_groups 按组顺序扩展为具体的 joint_names。组级行为：每个组都有自己的主动/被动属性和执行容忍度。推荐用法：在填充 API 参数（例如 joint_groups）时，使用此结构体中的常量。如果需要精确的关节名称，请在运行时通过 get_joint_names(true, {group_name}) 查询它们，而不是硬编码。在同时接受 joint_groups 和 joint_names 的 API 中，joint_names 优先。

成员变量

名称	类型	描述
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	左眼相机

---

采样器配置（SamplerConfig）

基于采样的运动规划器的配置参数。

该结构配置基于采样的规划算法（例如，RRT、RRT*）。它控制状态空间采样分辨率、插值设置、路径简化和规划终止条件。基于采样的规划器通过随机采样状态并将它们连接起来构建运动计划图来探索配置空间。

设置状态检查类型（set_state_check_type）

void galbot::sdk::SamplerConfig::set_state_check_type(StateCheckType type)

设置状态检查类型

参数

名称	类型	描述
type	StateCheckType	评估状态相似性的距离度量类型

设置状态检查分辨率（set_state_check_resolution）

void galbot::sdk::SamplerConfig::set_state_check_resolution(double resolution)

设置状态检查分辨率

参数

名称	类型	描述
resolution	double	认为两个状态不同的最小距离阈值（单位：弧度或无量纲）

note

较低的值增加规划精度但可能减慢计算速度。

设置是否插值（set_interpolate）

void galbot::sdk::SamplerConfig::set_interpolate(bool enable)

设置是否启用插值

参数

名称	类型	描述
enable	bool	true 启用插值，false 仅使用采样路点

note

插值可提高轨迹平滑度和碰撞检测覆盖率。

设置插值数量（set_interpolation_cnt）

void galbot::sdk::SamplerConfig::set_interpolation_cnt(int cnt)

设置插值点数量

参数

名称	类型	描述
cnt	int	要插入的中间路点数量（0 = 使用自动计算）

note

较高的计数可改善碰撞检测但增加计算成本。

设置是否简化（set_simplify）

void galbot::sdk::SamplerConfig::set_simplify(bool enable)

设置是否启用简化

参数

名称	类型	描述
enable	bool	true 启用路径简化和平滑，false 使用原始规划路径

note

简化减少路点并提高轨迹效率。

设置最大简化时间（set_max_simplification_time）

void galbot::sdk::SamplerConfig::set_max_simplification_time(double time)

设置最大简化时间（秒）

参数

名称	类型	描述
time	double	最大简化持续时间（单位：秒）；负值表示无时间限制

note

较长的简化时间可能产生更短、更平滑的路径。

设置终止条件类型（set_termination_condition_type）

void galbot::sdk::SamplerConfig::set_termination_condition_type(TerminationConditionType type)

设置终止条件类型

参数

名称	类型	描述
type	TerminationConditionType	终止条件类型（仅超时或超时/精确解）

设置最大规划时间（set_max_planning_time）

void galbot::sdk::SamplerConfig::set_max_planning_time(double time)

设置最大规划时间（秒）

参数

名称	类型	描述
time	double	最大规划持续时间（单位：秒）

note

如果找到精确解，规划可能提前终止（取决于终止条件）。

获取状态检查类型（get_state_check_type）

StateCheckType galbot::sdk::SamplerConfig::get_state_check_type() const

获取状态检查类型

返回值

类型	描述
StateCheckType	评估状态相似性的距离度量类型

获取状态检查分辨率（get_state_check_resolution）

double galbot::sdk::SamplerConfig::get_state_check_resolution() const

获取状态检查分辨率

返回值

类型	描述
double	分辨率值（单位：弧度或无量纲，取决于状态检查类型）

获取是否插值（get_interpolate）

bool galbot::sdk::SamplerConfig::get_interpolate() const

获取是否启用插值

返回值

类型	描述
bool	如果启用插值则为 true，否则为 false

获取插值数量（get_interpolation_cnt）

int galbot::sdk::SamplerConfig::get_interpolation_cnt() const

获取插值点数量

返回值

类型	描述
int	要插入的中间路点数量

获取是否简化（get_simplify）

bool galbot::sdk::SamplerConfig::get_simplify() const

获取是否启用简化

返回值

类型	描述
bool	如果启用路径简化则为 true，否则为 false

获取最大简化时间（get_max_simplification_time）

double galbot::sdk::SamplerConfig::get_max_simplification_time() const

获取最大简化时间（秒）

返回值

类型	描述
double	最大简化持续时间（单位：秒）

获取终止条件类型（get_termination_condition_type）

TerminationConditionType galbot::sdk::SamplerConfig::get_termination_condition_type() const

获取终止条件类型

返回值

类型	描述
TerminationConditionType	终止条件类型

获取最大规划时间（get_max_planning_time）

double galbot::sdk::SamplerConfig::get_max_planning_time() const

获取最大规划时间（秒）

返回值

类型	描述
double	最大规划持续时间（单位：秒）

打印输出（print）

void galbot::sdk::SamplerConfig::print() const

打印采样器配置信息到标准输出

嵌套枚举

状态检查类型（StateCheckType）

状态检查类型枚举

枚举值	描述
EUCLIDEAN_DISTANCE	欧氏距离
RADIAN_DISTANCE	弧度距离

终止条件类型（TerminationConditionType）

终止条件类型枚举

枚举值	描述
TIMEOUT	仅当超过最大规划时间时终止
TIMEOUT_AND_EXACT_SOLUTION	超时或精确解

---

随机种子类型（SeedType）

指定逆运动学 (IK) 解算器的初始化策略。不同的种子类型会影响收敛速度和解的质量。

枚举值	描述
RANDOM_SEED	随机种子
RANDOM_PROGRESSIVE_SEED	随机渐进种子
USER_DEFINED_SEED	用户自定义种子
SEED_TYPE_NUM	种子类型数量

---

传感器状态（SensorStatus）

表示传感器数据采集和处理操作的状态，适用于相机、激光雷达、IMU、力传感器和其他传感器类型。

枚举值	描述
SUCCESS	成功
TIMEOUT	超时
FAULT	故障
INVALID_INPUT	无效输入
INIT_FAILED	初始化失败
IN_PROGRESS	进行中
STOPPED_UNREACHED	已停止但未到达
DATA_FETCH_FAILED	数据获取失败，传感器可能已断开连接或损坏
PUBLISH_FAIL	发布失败
COMM_DISCONNECTED	通信断开
STATUS_NUM	状态数量

---

传感器类型（SensorType）

描述机器人上各种传感器的传感器类型枚举。

识别机器人上可用于感知、定位和操作任务的不同传感器类型。

枚举值	描述
HEAD_LEFT_CAMERA	头部左侧摄像头，通常是用于立体视觉的RGB摄像头
HEAD_RIGHT_CAMERA	头部右侧摄像头，通常是用于立体视觉的RGB摄像头
LEFT_ARM_CAMERA	左臂摄像头，安装在左侧机械臂上，用于视觉伺服
RIGHT_ARM_CAMERA	右臂摄像头，安装在右侧机械臂上，用于视觉伺服
LEFT_ARM_DEPTH_CAMERA	左臂深度摄像头，提供左臂工作区的 RGB-D 数据
RIGHT_ARM_DEPTH_CAMERA	右臂深度摄像头，提供右臂工作空间的 RGB-D 数据
LEFT_ARM_INFRA_CAMERA_1	左臂红外摄像头 1，提供左臂工作区域的红外数据
LEFT_ARM_INFRA_CAMERA_2	左臂红外摄像头 2，提供左臂工作区域的红外数据
RIGHT_ARM_INFRA_CAMERA_1	右臂红外摄像头 1，提供右臂工作区域的红外数据
RIGHT_ARM_INFRA_CAMERA_2	右臂红外摄像头 2，提供右臂工作区域的红外数据
HEAD_LIDAR	S1 头部激光雷达（前置），安装在头部用于前向感知
BACK_LIDAR	S1 后置激光雷达（后置），安装在车尾用于后方感知
CHASSIS_LIDAR	S1 底盘激光雷达（前置），安装在底盘上用于前向感知
HEAD_IMU	S1头部激光雷达惯性测量单元（IMU）
BACK_IMU	S1 后置激光雷达 IMU（惯性测量单元）
CHASSIS_IMU	底盘惯性测量单元 (IMU)
SENSOR_NUM	传感器枚举总数（用于边界检查或阵列尺寸确定）

---

SingoriX目标（SingoriXTarget）

SingoriX控制器的目标表示，用于与SingoriX外部控制器通信。

成员变量

名称	类型	描述
header	Header
target_group_trajectory_map	std::unordered_map< std::string, TargetGroupTrajectory >
target_task_trajectory_map	std::unordered_map< std::string, TargetTaskTrajectory >

---

吸盘动作状态（SUCTION_ACTION_STATE）

代表真空吸盘末端执行器的运行状态，跟踪从空闲到成功或失败的抽吸过程。

枚举值	描述
suction_action_idle	吸取动作空闲
suction_action_sucking	吸取动作吸取中
suction_action_success	吸取动作成功
suction_action_failed	吸取动作失败

---

吸盘状态（SuctionCupState）

包含真空吸盘夹具的当前状态，包括激活状态、压力读数和动作状态。

成员变量

名称	类型	描述
timestamp_ns	int64_t	状态时间戳（自纪元以来的纳秒数）
activation	bool	激活
pressure	double	压力
action_state	SUCTION_ACTION_STATE	动作状态

---

同步观测数据（SyncedObservation）

同步多传感器观测数据。

包含按时间戳对齐的相机帧和可选关节状态。对齐锚点为传入 get_synced_observation() 的第一个相机。

成员变量

名称	类型	描述
rgb_data_map	std::unordered_map< SensorType, std::shared_ptr< RgbData > >
depth_data_map	std::unordered_map< SensorType, std::shared_ptr< DepthData > >
joint_state	std::shared_ptr< JointStateMessage >

---

目标配置（TargetConfig）

目标的配置参数，包含目标类型、采样方式、约束条件等设置。

成员变量

名称	类型	描述
target_data	int32_t
target_type	int32_t
target_sampling	TargetSampling
target_priority	int32_t
target_id	std::string
target_ts	Timestamp

---

目标数据位（TargetDataBits）

用于表示目标数据类型的位掩码，标识目标包含哪些数据分量。

枚举值	描述
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

---

目标关节组轨迹（TargetGroupTrajectory）

目标在关节组空间中的轨迹，包含一系列途经点和时间信息。

成员变量

名称	类型	描述
target_config	TargetConfig
joint_names	std::vector< std::string >
group_commands	std::vector< GroupCommand >

---

目标采样（TargetSampling）

目标轨迹的采样方法，用于在路径点之间生成中间点。

枚举值	描述
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

---

目标任务轨迹（TargetTaskTrajectory）

目标在任务空间中的轨迹，包含任务级别的约束和要求。

成员变量

名称	类型	描述
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 >

---

目标类型位（TargetTypeBits）

用于表示目标类型的位掩码，标识目标是哪种类型（关节空间、任务空间等）。

枚举值	描述
TARGET_TYPE_NONE
TARGET_TYPE_TOUCH
TARGET_TYPE_CLEAR
TARGET_TYPE_PREPENDNOW
TARGET_TYPE_APPEND
TARGET_TYPE_OVERRIDE
TARGET_TYPE_PROVERRIDE
TARGET_TYPE_DEFAULT

---

任务命令（TaskCommand）

任务级别的命令结构，包含一个或多个目标和执行参数。

成员变量

名称	类型	描述
time_from_start_s	double
subtask_commands	std::vector< FrameTriad >

---

导航任务句柄（TaskHandle）

异步提交导航任务后返回的句柄。

成员变量

名称	类型	描述
task_id	std::string	任务标识。
request_sent	bool	请求是否被导航服务接收。
msg	std::string	请求结果对应的简短消息。

---

时间戳（Timestamp）

表示具有秒和纳秒分量的高精度时间点。兼容 ROS 2builtin_interfaces/Time 和 std_msgs/Header 时间戳格式。

成员变量

名称	类型	描述
sec	int64_t	秒
nanosec	uint32_t	纳秒

---

轨迹（Trajectory）

表示一个完整的机器人轨迹，包含多个随时间变化的路点。joint_groups 和 joint_names 不能同时为空。如果同时为空，函数将返回 ControlStatus::INVALID_INPUT。此限制确保了关节顺序的确定性，防止因隐式内部默认顺序（可能在 SDK 版本之间变化）导致的难以察觉的 bug。使用方法：推荐设置具有语义组名的 joint_groups 或 joint_names。如果同时设置，joint_names 优先于 joint_groups

成员变量

名称	类型	描述
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 也为空时，不能同时为空。

---

轨迹控制状态（TrajectoryControlStatus）

机器人轨迹执行状态枚举。

表示机器人沿着由多个路点组成的预先规划的轨迹运行时的实时执行状态。

枚举值	描述
INVALID_INPUT	无效输入
RUNNING	运行中
COMPLETED	已完成
STOPPED_UNREACHED	轨迹执行过程中停止但未达到终点
ERROR	错误日志
DATA_FETCH_FAILED	数据获取失败
STATUS_NUM	状态数量

---

轨迹可行性检查选项（TrajectoryFeasibilityCheckOption）

轨迹验证和可行性检查配置。

该结构提供了对在轨迹验证期间强制执行可行性约束的细粒度控制。它支持碰撞检测、关节限制合规性和速度剖面可行性的独立切换。有选择地禁用检查可以提高调试、模拟或保证满足某些约束的场景的计算性能。禁用可行性检查可能会产生不安全或物理上无法实现的轨迹。仅当通过其他方式验证约束时才应谨慎使用。

设置是否禁用碰撞检查（set_disable_collision_check）

void galbot::sdk::TrajectoryFeasibilityCheckOption::set_disable_collision_check(bool disable)

设置是否禁用碰撞检测

参数

名称	类型	描述
disable	bool	是否禁用碰撞检测

warning

禁用碰撞检查可能导致轨迹与环境发生碰撞

设置是否禁用关节限制检查（set_disable_joint_limit_check）

void galbot::sdk::TrajectoryFeasibilityCheckOption::set_disable_joint_limit_check(bool disable)

设置是否禁用关节限制检查

参数

名称	类型	描述
disable	bool	传入 true 表示跳过关节限位验证，传入 false 表示强制执行位置限位验证。

warning

禁用关节限制检查可能导致轨迹超出关节限位

设置是否禁用速度可行性检查（set_disable_velocity_feasibility_check）

void galbot::sdk::TrajectoryFeasibilityCheckOption::set_disable_velocity_feasibility_check(bool disable)

设置是否禁用速度可行性检查

参数

名称	类型	描述
disable	bool	true 跳过速度限制验证，false 强制执行速度验证。

note

速度可行性确保轨迹可以被机器人执行。

获取是否禁用碰撞检查（get_disable_collision_check）

bool galbot::sdk::TrajectoryFeasibilityCheckOption::get_disable_collision_check() const

获取是否禁用碰撞检测

返回值

类型	描述
bool	若当前已禁用碰撞检查则返回 true；否则返回 false。

获取是否禁用关节限制检查（get_disable_joint_limit_check）

bool galbot::sdk::TrajectoryFeasibilityCheckOption::get_disable_joint_limit_check() const

获取是否禁用关节限制检查

返回值

类型	描述
bool	若当前已禁用关节限位检查则返回 true；否则返回 false。

获取是否禁用速度可行性检查（get_disable_velocity_feasibility_check）

bool galbot::sdk::TrajectoryFeasibilityCheckOption::get_disable_velocity_feasibility_check() const

获取是否禁用速度可行性检查

返回值

类型	描述
bool	若当前已禁用速度可行性检查则返回 true；否则返回 false。

打印输出（print）

void galbot::sdk::TrajectoryFeasibilityCheckOption::print() const

打印轨迹可行性检查选项到标准输出

---

轨迹规划配置（TrajectoryPlanConfig）

轨迹规划和参数化配置。

该结构配置轨迹生成参数，用于将离散运动计划转换为平滑的时间参数化轨迹。它支持单段和多路点轨迹规划。轨迹规划涉及计算沿几何路径的速度和加速度分布，同时尊重运动学约束。

设置最小移动时间（set_min_move_time）

void galbot::sdk::TrajectoryPlanConfig::set_min_move_time(double time)

设置最小运动时间（秒）

参数

名称	类型	描述
time	double	最小轨迹执行时间（单位：秒）

note

非零值防止运动过快；0.0 允许在运动学限制内的最高速度

设置直线插值中间点（set_move_line_intermediate_point）

void galbot::sdk::TrajectoryPlanConfig::set_move_line_intermediate_point(double value)

设置直线运动中间点设置

参数

名称	类型	描述
value	double	线性路径段的中间路点数量（无量纲）

note

较高的值提高笛卡尔路径精度但增加计算成本。

设置路点规划预期时间（set_way_point_plan_expected_time）

void galbot::sdk::TrajectoryPlanConfig::set_way_point_plan_expected_time(double time)

设置路点规划期望时间

参数

名称	类型	描述
time	double	路点序列的预期轨迹执行时间（单位：秒）

note

用作时间最优轨迹生成算法的提示。

获取最小移动时间（get_min_move_time）

double galbot::sdk::TrajectoryPlanConfig::get_min_move_time() const

获取最小运动时间（秒）

返回值

类型	描述
double	最小轨迹执行时间（单位：秒）

获取直线插值中间点（get_move_line_intermediate_point）

double galbot::sdk::TrajectoryPlanConfig::get_move_line_intermediate_point() const

获取直线运动中间点设置

返回值

类型	描述
double	线性路径段的中间路点数量（无量纲）

获取路点规划预期时间（get_way_point_plan_expected_time）

double galbot::sdk::TrajectoryPlanConfig::get_way_point_plan_expected_time() const

获取路点规划期望时间

返回值

类型	描述
double	路点规划的预期轨迹执行时间（单位：秒）

打印输出（print）

void galbot::sdk::TrajectoryPlanConfig::print() const

打印轨迹规划配置信息到标准输出

---

轨迹点（TrajectoryPoint）

表示机器人轨迹中的路点，指定特定时间的关节状态。joint_command_vec 的顺序必须与 Trajectory.joint_names 或 Trajectory.joint_groups（按顺序展开）定义的关节顺序一致。顺序不匹配将导致未定义行为。

成员变量

名称	类型	描述
time_from_start_second	double	起始时间偏移（秒）
joint_command_vec	std::vector< JointCommand >	该路点所有关节的关节命令列表。顺序必须与 joint_names 或 joint_groups 展开顺序一致。

---

坐标变换消息（TransformMessage）

表示带时间戳的坐标系变换，包括平移和旋转。常用于机器人技术中的 TF（变换）树。

成员变量

名称	类型	描述
timestamp_ns	int64_t	变换时间戳（自纪元以来的纳秒数）
translation	Point	平移向量（米）。
rotation	Quaternion	旋转

---

扭曲速度（Twist）

表示刚体的线速度和角速度组合，遵循ROS标准消息格式。

成员变量

名称	类型	描述
linear	Vector3
angular	Vector3

---

三维向量（Vector3）

表示三维矢量，用于力、扭矩、速度、加速度和其他矢量。

成员变量

名称	类型	描述
x	double	X分量
y	double	Y分量
z	double	Z分量

---

路点（Waypoint）

使用默认调参构造路点（Waypoint）

galbot::sdk::Waypoint::Waypoint(const Pose &pose)

使用默认调参构造路点。

参数

名称	类型	描述
pose	const Pose &	目标位姿。

使用自定义调参构造路点（Waypoint）

galbot::sdk::Waypoint::Waypoint(const Pose &pose, const WaypointParams &params)

使用自定义调参构造路点。

参数

名称	类型	描述
pose	const Pose &	目标位姿。
params	const WaypointParams &	可选的路点调参。

成员变量

名称	类型	描述
pose	Pose	该路点对应的目标位姿。
params	WaypointParams	单个路点的可选调参。

---

路点可选参数（WaypointParams）

用于调整单个路点到达精度和运动平滑度的可选参数。

成员变量

名称	类型	描述
arrival_position_threshold_x	double	X 方向到达阈值（米）。
arrival_position_threshold_y	double	Y 方向到达阈值（米）。
arrival_orientation_threshold	double	姿态到达阈值（弧度）。
velocity_scale	double	沿路点执行的速度缩放因子。
acceleration_scale	double	沿路点执行的加速度缩放因子。
jerk_scale	double	沿路点执行的加加速度缩放因子。

---

力与力矩（Wrench）

力与力矩相关说明。

成员变量

名称	类型	描述
force	Vector3
torque	Vector3

---