C++ API 文档

MoveIt 2 的 C++ API 是其最主要、最完整的 API 接口。相比 Python API，C++ API 可以完整访问 MoveIt 2 的所有核心功能，涵盖底层的数据结构、算法和工具类。它基于 ROS 2 的 rclcpp 客户端库构建，适用于对性能、实时性和功能完整性有较高要求的应用场景。

本文档介绍 C++ API 的核心类、基本用法以及关键子系统。

核心 API 类

以下表格列出了 MoveIt 2 C++ API 中最常用的核心类及其对应的头文件：

类名	头文件	说明
`move_group::MoveGroupInterface`	`moveit/move_group_interface/move_group_interface.h`	高层运动规划接口
`planning_scene::PlanningScene`	`moveit/planning_scene/planning_scene.h`	规划场景管理
`collision_detection::World`	`moveit/collision_detection/world.h`	碰撞世界模型
`robot_model::RobotModel`	`moveit/robot_model/robot_model.h`	机器人模型
`robot_state::RobotState`	`moveit/robot_state/robot_state.h`	机器人状态
`robot_trajectory::RobotTrajectory`	`moveit/robot_trajectory/robot_trajectory.h`	机器人轨迹
`kinematics::KinematicsBase`	`moveit/kinematics_base/kinematics_base.h`	运动学求解基类

代码示例：MoveGroupInterface 基本用法

以下示例展示了如何使用 MoveGroupInterface 进行基本的运动规划，涵盖设置目标位姿、规划以及执行运动三个核心步骤：

#include <memory>
#include <rclcpp/rclcpp.hpp>
#include <moveit/move_group_interface/move_group_interface.h>

int main(int argc, char** argv)
{
  // 初始化 ROS 2 节点
  rclcpp::init(argc, argv);

  // 创建 ROS 2 节点
  auto const node = std::make_shared<rclcpp::Node>(
    "moveit_cpp_example",
    rclcpp::NodeOptions().automatically_declare_parameters_from_overrides(true)
  );

  // 创建 MoveGroupInterface，指定规划组名称
  // 规划组名称需与 SRDF 中定义的 <group name="..."> 一致
  auto move_group = moveit::planning_interface::MoveGroupInterface(node, "arm");

  // 设置目标位姿
  // 通过设置末端执行器的目标位姿来定义规划目标
  geometry_msgs::msg::Pose target_pose;
  target_pose.orientation.w = 1.0;
  target_pose.position.x = 0.28;
  target_pose.position.y = -0.2;
  target_pose.position.z = 0.5;
  move_group.setPoseTarget(target_pose);

  // 创建规划器并执行规划
  moveit::planning_interface::MoveGroupInterface::Plan my_plan;
  bool success = (move_group.plan(my_plan) == moveit::core::MoveErrorCode::SUCCESS);

  if (success)
  {
    // 规划成功，执行运动
    move_group.execute(my_plan);
  }
  else
  {
    RCLCPP_ERROR(node->get_logger(), "运动规划失败");
  }

  // 关闭 ROS 2
  rclcpp::shutdown();
  return 0;
}

关键说明

规划组（Planning Group）：MoveGroupInterface 的构造函数接收规划组名称，该名称需与 SRDF 文件中定义的 <group> 一致。
setPoseTarget()：设置末端执行器的目标位姿（位置 + 姿态）。也可以使用 setJointValueTarget() 设置关节空间目标。
plan()：仅执行规划，不实际运动。返回值指示规划是否成功。
execute()：根据规划结果执行实际运动。也可以使用 move() 一步完成规划与运动。
线程安全：MoveGroupInterface 的方法不应在回调函数中直接调用。如需在回调中触发规划，应将 CurrentStateMonitor 与回调线程分开运行，或改用 MoveItCpp API。

规划场景监控器（Planning Scene Monitor）

规划场景监控器（Planning Scene Monitor, PSM） 是 MoveIt 2 中维护机器人环境状态的核心组件。它持续监听 ROS 话题，实时更新规划场景：

订阅 /get_planning_scene 服务和 /planning_scene 话题，同步场景状态。
通过 OccupancyMapUpdater 集成传感器数据（如点云），动态更新 3D 占据图。
提供 LockedPlanningSceneRO / LockedPlanningSceneRW 守卫类，确保多线程环境下的线程安全访问。

PSM 是 MoveGroupInterface 的底层依赖之一——MoveGroup 节点通过 PSM 获取当前场景状态，进而完成碰撞检测和规划。

运动规划管线（Planning Pipeline）

运动规划管线 将一个规划请求分解为多个可配置的阶段：

规划请求适配器（Planning Request Adapters）：在规划前对请求进行预处理。例如 FixStartStateBounds 修复起始状态越界、FixStartStatePathConstraints 为起始状态添加路径约束、ValidateWorkspaceBounds 验证工作空间。
规划求解器（Planner）：调用具体的规划算法生成路径。MoveIt 2 默认使用 OMPL（开源运动规划库），同时也支持 Pilz 工业轨迹规划器、CHOMP、STOMP 等。
后处理适配器（Post-Processing Adapters）：对规划结果进行优化。其中最重要的是时间参数化（如 addTimeParameterization），负责将空间路径转换为带时间、速度和加速度信息的轨迹。

通过 PlanningPipeline 类，开发者可以以编程方式配置这些阶段，也可以通过 ROS 参数文件灵活定义。

外部 API 文档

完整的 C++ API 文档由 Doxygen 自动生成，包含所有类、方法和命名空间的详细参考：

MoveIt 2 C++ API 文档（Doxygen）