简介本资源是面向自动驾驶开发工程师的Apollo PnC路径规划与控制基础项目实践包聚焦于理解与定制化开发Apollo框架中核心决策模块适用于具备C/Cyber RT基础、正切入自动驾驶算法层开发的中级以上工程师。压缩包共12个文件含3个JSON配置文件用于PnC参数调优与模块行为定义、1个XML构建描述文件cyberfile.xml、1个BUILD编译规则文件及多个开发环境配置文件.clang-format、.editorconfig、.vscode设置等整体仅7KB轻量精炼便于快速导入IDE并启动调试。已有513人学习下载资源结构清晰体现Apollo典型工程组织范式从profiles参数配置、WORKSPACE构建入口到.vscode开发支持完整覆盖PnC模块本地编译、参数加载与接口对接所需基础骨架。读者可直接基于此项目开展路径规划算法替换、轨迹生成逻辑调试或控制指令注入验证是深入Apollo源码、打通PnC开发闭环的高价值起点。1. 这不是“跑通Demo”项目而是 Apollo PnC 开发者真正的起点你下载的application-pnc-main.zip不是 Apollo 官方 Docker 镜像里那个开箱即用的 demo_benchmark 示例也不是modules/planning目录下直接编译就能跑的默认规划器。它是一个可独立构建、带完整开发环境配置、面向真实模块定制的最小可行工程骨架——.buildtool.conf定义了 Bazel 构建行为.vscode/下的c_cpp_properties.json显式声明了 CyberRT 的 include 路径与宏定义WORKSPACE文件已预置 Apollo 8.0 兼容的外部依赖引用方式。这意味着你不需要先花三天配通整个 Apollo 主干也不必在cyber和bazel的版本冲突中反复重装这个项目从解压那一刻起就默认站在 Apollo PnC 模块开发的第一道起跑线上。它适合两类人一类是刚通过 Apollo Simulator 跑过dreamview但对planning_component.cc里OnPlanning()回调逻辑仍感模糊的工程师另一类是已在车企或 Tier1 参与量产 PnC 模块交付需要快速验证自研轨迹优化器如 ST 图动态规划 五次多项式平滑是否能无缝接入 Apollo 数据流的开发者。它解决的核心问题是如何让一个新写的 PlanningAlgorithm 类在不修改 Apollo 核心框架的前提下被 CyberRT 正确加载、接收/perception/obstacles和/localization/msf_pose并稳定发布/planning/trajectory。2. 理解 Apollo PnC 模块生命周期从 Cyber Component 初始化到 Trajectory 发布Apollo PnC 模块本质是一个 CyberRT Component其执行模型与 ROS2 Node 有本质区别它不依赖rclcpp::spin()循环而是由 Cyber Runtime 的调度器按OnTimer()或OnMessage()触发回调。application-pnc-main项目正是围绕这一机制构建的最小闭环。2.1 Cyber Component 结构解析为什么必须重写Init()和Proc()在application-pnc-main的src/planning_component.cc中Init()函数完成三件事加载planning_config.pb.txt位于conf/目录该文件定义了max_trajectory_point_num: 50、enable_prediction: true等关键开关创建PlanningBase子类实例如LatticePlanner或你自定义的MySTPlanner并传入PlanningConfig对象调用cyber::CreateReaderLocalizationEstimate订阅定位消息cyber::CreateReaderPerceptionObstacles订阅障碍物注意订阅句柄必须保存为成员变量如localization_reader_否则对象析构时 Reader 自动销毁导致后续消息无法到达。bool PlanningComponent::Init() { // 1. 加载配置 planning_config_ std::make_sharedPlanningConfig(); apollo::common::util::GetProtoFromFile( FLAGS_planning_config_file, planning_config_.get()); // 2. 实例化规划器 planner_ PlannerFactory::CreatePlanner( planning_config_-planner_type(), planning_config_); // 3. 创建 Reader 并绑定回调 —— 关键必须用 this- 绑定成员函数 localization_reader_ node_-CreateReaderLocalizationEstimate( FLAGS_localization_topic, [this](const std::shared_ptrLocalizationEstimate msg) { localization_ msg; }); perception_reader_ node_-CreateReaderPerceptionObstacles( FLAGS_perception_topic, [this](const std::shared_ptrPerceptionObstacles msg) { perception_obstacles_ msg; }); // 4. 创建 Writer —— 发布轨迹前必须确保 topic 名与 DreamView 配置一致 trajectory_writer_ node_-CreateWriterTrajectory( FLAGS_trajectory_topic); // 默认为 /planning/trajectory return true; }提示FLAGS_*宏来自gflags其值由conf/params/*.conf文件注入。若你修改了FLAGS_trajectory_topic必须同步更新dreamview/conf/dreamview.conf中的planning_topic字段否则 DreamView 不会渲染你的轨迹。2.2Proc()回调中的实时性保障为什么不能直接调用planner_-Plan()Proc()是 CyberRT 调度器每 10ms默认周期触发的函数但planner_-Plan()内部可能包含耗时操作如 A* 在全局路网搜索、QP 优化求解。直接在此处调用会导致线程阻塞破坏 CyberRT 的实时调度。正确做法是将感知/定位数据快照拷贝到工作线程由独立线程池执行规划计算主Proc()仅负责数据分发与结果发布。application-pnc-main在src/planning_component.cc中已预留线程池接口// 在 Init() 中初始化线程池 planning_thread_pool_ std::make_sharedThreadPool(4); // 4 线程 // 在 Proc() 中提交任务 void PlanningComponent::Proc() { if (!localization_ || !perception_obstacles_) return; // 拷贝当前帧数据避免多线程访问原始 shared_ptr auto loc_copy std::make_sharedLocalizationEstimate(*localization_); auto obs_copy std::make_sharedPerceptionObstacles(*perception_obstacles_); // 提交至线程池异步执行 planning_thread_pool_-Enqueue([this, loc_copy, obs_copy]() { auto trajectory planner_-Plan(loc_copy, obs_copy); if (trajectory) { // 注意Writer 必须在 CyberRT 主线程调用此处需线程安全队列 std::lock_guardstd::mutex lock(trajectory_mutex_); latest_trajectory_ trajectory; } }); } // 在 Proc() 末尾检查并发布主线程安全 if (latest_trajectory_) { trajectory_writer_-Write(latest_trajectory_); latest_trajectory_.reset(); }注意ThreadPool实现需保证Enqueue()不阻塞主线程。application-pnc-main使用的是cyber/common/thread_pool.h提供的无锁队列若你替换为std::thread手动管理必须确保Write()调用发生在 CyberRT 的 EventLoop 线程中否则会触发断言CHECK_EQ(cyber::base::ThreadLocalStore::GetValueint(cyber_event_loop), 1)。2.3 配置文件链式加载机制.buildtool.conf如何影响 Bazel 编译行为application-pnc-main的.buildtool.conf并非普通文本配置而是 Apollo Build ToolABT的指令集。它决定了 Bazel 构建时的 target 依赖、头文件搜索路径及链接选项[build] # 指定默认构建目标避免每次敲 bazel build //... default_target //src:planning_component [link] # 强制链接 CyberRT 的 core 库解决 undefined symbol: apollo::cyber::Init() required_libs cyber_core cyber_common cyber_time cyber_base [include] # 告知 ABT 将 Apollo 主干的 include 目录加入 -I 路径 apollo_include_dirs /opt/apollo/neo/include:/opt/apollo/neo/third_party当你执行./build.sh封装了abt buildABT 会读取此文件生成.bazelrc片段并自动注入--copt-I/opt/apollo/neo/include。若你未安装 Apollo Neo 环境需手动修改apollo_include_dirs指向你的 Apollo 源码路径如~/apollo/modules/planning否则#include cyber/cyber.h将报错。参数作用修改建议default_target设置abt build默认编译目标初期可设为//src:planning_component调试时改为//test:planning_testrequired_libs强制链接的库列表若添加自定义数学库如eigen3需在此追加eigen3apollo_include_dirs头文件搜索路径必须与cyber安装路径严格一致ls /opt/apollo/neo/include/cyber应存在3. 实战替换默认 LatticePlanner 为自定义 ST 图规划器Apollo 默认的LatticePlanner适用于结构化道路但在无车道线场景如停车场泊车易失效。本节以实现一个轻量级 ST 图动态规划器为例展示如何在application-pnc-main中集成新算法。3.1 创建规划器类继承PlanningBase并实现纯虚函数在src/planner/st_graph_planner.h中定义#pragma once #include modules/planning/planner/planning_base.h #include modules/planning/proto/planning_config.pb.h namespace apollo { namespace planning { class STGraphPlanner : public PlanningBase { public: explicit STGraphPlanner(const PlanningConfig config); virtual ~STGraphPlanner() default; // 必须实现输入定位感知输出轨迹 bool Plan(const std::shared_ptrconst LocalizationEstimate localization, const std::shared_ptrconst PerceptionObstacles obstacles, ADCTrajectory* trajectory) override; private: // ST 图核心时间维度离散化0~8s步长0.5s速度维度0~15m/s步长1m/s static constexpr int kSTTimeGrid 16; // 0, 0.5, ..., 7.5 static constexpr int kSTSpeedGrid 16; // 0, 1, ..., 15 PlanningConfig config_; }; } // namespace planning } // namespace apollo逻辑说明STGraphPlanner不直接处理原始点云而是依赖上游Prediction模块输出的PredictionObstacle已预测未来 5 秒轨迹。因此Plan()函数内需调用prediction_client_-GetPredictions()获取预测结果再构建 ST 网格节点。kSTTimeGrid和kSTSpeedGrid的取值直接影响 DP 搜索复杂度O(T×V)需在实时性100ms与精度间权衡。3.2 在 BUILD 文件中注册新规划器并导出工厂方法src/planner/BUILD文件需添加cc_library( name st_graph_planner, srcs [st_graph_planner.cc], hdrs [st_graph_planner.h], deps [ //modules/planning/proto:planning_config_cc_proto, //modules/common/proto:vehicle_config_cc_proto, //cyber:cyber, eigen_archive//:eigen3, # 依赖 Eigen 矩阵运算 ], ) # 导出工厂注册宏 cc_library( name planner_factory, srcs [planner_factory.cc], hdrs [planner_factory.h], deps [ :st_graph_planner, //modules/planning/planner:lattice_planner, # 保留原规划器 ], )src/planner/planner_factory.cc中注册#include modules/planning/planner/planner_factory.h #include modules/planning/planner/st_graph_planner.h namespace apollo { namespace planning { // 注册宏将 STGraphPlanner 绑定到枚举值 PLANNING_ST_GRAPH REGISTER_PLANNER(PLANNING_ST_GRAPH, STGraphPlanner); } // namespace planning } // namespace apollo参数说明REGISTER_PLANNER是 Apollo 的宏它将STGraphPlanner类型与PLANNING_ST_GRAPH枚举关联。后续只需在conf/planning_config.pb.txt中设置planner_type: PLANNING_ST_GRAPH框架即可自动创建该实例。3.3 配置文件驱动planning_config.pb.txt如何控制算法行为conf/planning_config.pb.txt是 Protocol Buffer 文本格式application-pnc-main已预置基础字段。启用 ST 图规划器需修改# conf/planning_config.pb.txt planner_type: PLANNING_ST_GRAPH # 替换为 PLANNING_LATTICE # ST 图专用参数 st_graph_config { time_resolution: 0.5 # 时间步长秒 speed_resolution: 1.0 # 速度步长m/s max_acceleration: 3.0 # 最大加速度m/s² max_jerk: 5.0 # 最大加加速度m/s³ } # 轨迹后处理五次多项式平滑必须开启否则 ST 图输出为折线 smoothing_config { enable_smoothing: true smoothing_method: QP_SMOOTHING # 使用二次规划平滑 }关键点smoothing_config不可省略。ST 图输出的是(s,t)点序列需经Spline1dGenerator转为连续s(t)函数再微分得v(t)、a(t)。若enable_smoothing: false轨迹将出现突变加速度车辆控制模块如 MPC会因输入不连续而发散。4. 排查常见构建与运行时错误从 Bazel 报错到 CyberRT 消息丢失即使代码逻辑正确application-pnc-main在实际部署中仍面临三类高频问题Bazel 编译失败、CyberRT 模块加载异常、消息流中断。以下是精准定位与修复方案。4.1 Bazel 构建失败undefined reference to apollo::cyber::Init()此错误表明链接器找不到 CyberRT 的符号根本原因是libcyber.so未被正确链接。检查src/BUILD中cc_binary的depscc_binary( name planning_component, srcs [planning_component.cc], deps [ //src/planner:planner_factory, # 必须包含 //cyber:cyber, # 必须显式声明 //modules/common:adapter, # 用于消息转换 ], )若仍报错执行ldd bazel-bin/src/planning_component | grep cyber确认输出包含libcyber.so /opt/apollo/neo/lib/libcyber.so。若显示not found说明LD_LIBRARY_PATH未包含 Apollo 库路径# 临时修复推荐 export LD_LIBRARY_PATH/opt/apollo/neo/lib:$LD_LIBRARY_PATH ./build.sh # 永久修复在 ~/.bashrc 中添加 echo export LD_LIBRARY_PATH/opt/apollo/neo/lib:$LD_LIBRARY_PATH ~/.bashrc source ~/.bashrc4.2 CyberRT 模块加载失败Failed to load component: planning_component启动后日志出现Failed to load component通常因component描述文件缺失。application-pnc-main要求在conf/目录下存在planning_component.conf# conf/planning_component.conf name: planning_component className: apollo::planning::PlanningComponent config_file: /apollo/conf/planning_config.pb.txt注意className必须与planning_component.cc中CYBER_REGISTER_COMPONENT(PlanningComponent)的类名完全一致含命名空间。若类名写成PlanningComponent缺apollo::planning::CyberRT 会因 RTTI 匹配失败而静默退出。4.3 消息流中断DreamView 显示 “No Planning Trajectory”使用cyber_monitor检查消息流# 查看所有 topic cyber_monitor # 重点检查三个 topic 的消息频率 cyber_monitor -c /planning/trajectory cyber_monitor -c /localization/msf_pose cyber_monitor -c /perception/obstacles若/planning/trajectory无消息但/localization/msf_pose有10Hz则问题在PlanningComponent内部。此时启用 DEBUG 日志# 修改 .env 文件增加日志级别 export GLOG_logtostderr1 export GLOG_minloglevel0 # INFO 级别 export GLOG_v2 # VLOG(2) 开启详细日志 # 重启模块 cyber_launch start /apollo/modules/planning/launch/planning.launch在planning_component.cc的Proc()函数开头添加AINFO Proc called at apollo::common::time::Clock::NowInSeconds(); AINFO Localization valid: (localization_ ? YES : NO); AINFO Obstacles valid: (perception_obstacles_ ? YES : NO);若日志显示Localization valid: NO说明localization_reader_未收到消息。检查FLAGS_localization_topic是否与localization模块发布的 topic 一致默认/localization/msf_pose并确认localization模块已启动。4.4 轨迹跟踪失败车辆在 DreamView 中抖动或偏离路径此问题多源于Trajectory消息的时间戳与LocalizationEstimate不同步。Apollo 要求轨迹点tpoints[i].relative_time必须严格递增且首点relative_time为0.0// 错误示例relative_time 从 0.1 开始 trajectory-add_trajectory_point()-set_relative_time(0.1); // 正确写法从 0.0 开始步长固定 for (int i 0; i 50; i) { auto* point trajectory-add_trajectory_point(); point-set_relative_time(i * 0.1); // 0.0, 0.1, 0.2, ... point-set_v(5.0); // 设定恒定速度 }验证方法用cyber_recorder录制/planning/trajectory然后 Python 解析from cyber_py import cyber, record f record.RecordReader(20240601_record.record) for channel, msg, t in f.read_messages(/planning/trajectory): traj planning_pb2.ADCTrajectory() traj.ParseFromString(msg) print(fFirst point time: {traj.trajectory_point[0].relative_time}) break输出必须为0.0否则 MPC 控制器将拒绝该轨迹。5. 进阶技巧用cyber_visualizer实时调试 ST 图搜索过程application-pnc-main默认不启用可视化调试但 Apollo 提供cyber_visualizer工具可实时渲染 ST 图网格、动态规划路径及障碍物投影。启用步骤如下5.1 启用 ST 图可视化通道在src/planner/st_graph_planner.cc的Plan()函数末尾添加可视化消息发布#include modules/planning/proto/st_graph_debug.pb.h #include cyber/common/file.h void STGraphPlanner::PublishSTDebug(const STGraphDebug debug_msg) { static auto writer cyber::CreateWriterSTGraphDebug(/planning/st_debug); writer-Write(debug_msg); }构造STGraphDebug消息时填充关键字段STGraphDebug debug_msg; debug_msg.mutable_header()-set_timestamp_sec(apollo::common::time::Clock::NowInSeconds()); debug_msg.set_total_search_time_ms(search_time_ms); // 添加 ST 网格节点最多 1000 个避免网络拥塞 for (int t 0; t kSTTimeGrid; t) { for (int v 0; v kSTSpeedGrid; v) { auto* node debug_msg.add_nodes(); node-set_t(t * 0.5); // 时间坐标 node-set_v(v * 1.0); // 速度坐标 node-set_cost(cost_grid[t][v]); // DP 累积代价 node-set_is_obstacle(is_obstacle[t][v]); } } PublishSTDebug(debug_msg);5.2 配置 Cyber Visualizer 显示层启动cyber_visualizer后在左侧面板点击Add Layer→ST Graph Debug设置 topic 为/planning/st_debug。界面将实时显示蓝色热力图cost_grid[t][v]值越蓝表示代价越低优先选择红色矩形框is_obstacle[t][v] true的区域代表该时空点被障碍物占据黄色折线DP 搜索出的最优路径横轴为时间t纵轴为速度v。技巧当车辆在路口犹豫时观察 ST 图中t2.0s附近是否出现大面积红色前方车辆急刹导致未来 2 秒内所有速度均被封锁若是则需调整st_graph_config.max_acceleration或prediction模块的置信度阈值避免过度保守。5.3 性能瓶颈定位用perf分析 ST 图 DP 循环若search_time_ms 80超过单帧预算需定位热点。编译时添加-g -O2# 修改 BUILD 文件为 st_graph_planner.cc 添加调试信息 cc_library( name st_graph_planner, srcs [st_graph_planner.cc], copts [-g, -O2], # 关键保留调试符号 ... )运行perf采集# 启动 planning_component cyber_launch start /apollo/modules/planning/launch/planning.launch # 采集 30 秒 CPU 样本 sudo perf record -g -p $(pgrep planning_component) -o perf.data -- sleep 30 # 生成火焰图 sudo perf script | ./FlameGraph/stackcollapse-perf.pl | ./FlameGraph/flamegraph.pl st_flame.svg典型瓶颈出现在STGraphPlanner::Search()内的双重循环for (int t 0; t kSTTimeGrid; t) { // perf 显示此行占 65% CPU for (int v 0; v kSTSpeedGrid; v) { cost_grid[t][v] min(cost_grid[t-1][v_prev]) obstacle_cost[t][v]; } }优化方案将obstacle_cost[t][v]预计算为std::vectorstd::vectorfloat避免每次查表用SIMD指令如__m128并行计算 4 个v值需引入immintrin.h对t0层使用std::fill_n()初始化而非循环赋值。最终一个经过perf优化的 ST 图规划器可在 Intel i7-11800H 上将search_time_ms从 120ms 降至 45ms满足 Apollo 10Hz 实时要求。本文还有配套的精品资源点击获取