6. 核心消息类型

本文详述 builtin_interfaces、std_msgs、geometry_msgs 三个基础消息包。

6.1 builtin_interfaces

头文件：autonomy/commsgs/builtin_interfaces.hpp

时间与时长是全部 Stamped 消息的基础。

6.1.1 Time

字段	类型	说明
`sec`	`int32`	Unix epoch 秒
`nanosec`	`uint32`	纳秒分量 [0, 10⁹)

方法	说明
`Time::Now()`	当前系统时间
`ToUnixTimeNanos()`	合并为 64 位纳秒
`Seconds()`	浮点秒
`Nanoseconds()`	总纳秒（32 位，注意溢出）
`Min()` / `Max()`	边界值

auto t = commsgs::builtin_interfaces::Time::Now();
auto t2 = commsgs::builtin_interfaces::Time(100, 500000000);  // 100.5s

6.1.2 Duration

字段	类型	说明
`duration_`	`int64_t`	内部纳秒存储

支持与 std::chrono::duration 互转，提供 + - * 运算符（带溢出检查）。

auto d = commsgs::builtin_interfaces::Duration::FromSeconds(1.5);
auto elapsed = commsgs::builtin_interfaces::Time::Now() - start_time;

6.2 std_msgs

头文件：autonomy/commsgs/std_msgs.hpp

6.2.1 Header

字段	类型	说明
`stamp`	`builtin_interfaces::Time`	时间戳
`frame_id`	`std::string`	坐标系名称

所有 *Stamped 消息的公共前缀。

6.2.2 其他类型

类型	字段	用途
`ColorRGBA`	`r, g, b, a` (float)	可视化颜色
`String`	`data` (string)	字符串包装
`Float32MultiArray`	`layout`, `data`	多维浮点数组
`MultiArrayLayout`	`dim`, `data_offset`	数组布局描述
`MultiArrayDimension`	`label`, `size`, `stride`	单维描述

MultiArray* 系列自 Foxy 起标记为 deprecated，建议使用语义化消息替代。

6.2.3 转换完整度

类型	ToProto	FromProto
`Header`	✅	✅
`ColorRGBA`	✅	✅
`String`	✅	✅
`MultiArray*`	✅	✅

6.3 geometry_msgs

头文件：autonomy/commsgs/geometry_msgs.hpp

导航栈中使用最频繁的消息包。

6.3.1 基础向量与点

类型	字段	语义
`Vector3`	`x, y, z` (float)	自由向量（锚定原点，变换时仅旋转）
`Point`	`x, y, z` (float)	空间点（变换时平移+旋转）
`Point32`	`x, y, z` (float)	32 位精度点
`Quaternion`	`x, y, z, w` (float)	四元数旋转
`Polygon`	`vector<Point32>`	多边形顶点

6.3.2 位姿与运动

类型	组成	用途
`Pose`	`Point position` + `Quaternion orientation`	6-DOF 位姿
`Pose2D`	`x, y, theta` (double)	平面位姿
`Twist`	`Vector3 linear` + `Vector3 angular`	6-DOF 速度
`Twist2D`	`x, y, theta` (double)	平面速度
`Accel`	`Vector3 linear` + `Vector3 angular`	加速度
`Wrench`	`Vector3 force` + `Vector3 torque`	力/力矩

6.3.3 Stamped 变体

类型	额外字段	典型 topic
`PoseStamped`	`header` + `pose`	`/goal_pose`, 路径点
`Pose2DStamped`	`header` + `pose`	平面目标
`TwistStamped`	`header` + `twist`	`/cmd_vel`
`Twist2DStamped`	`header` + `velocity`	平面速度命令
`PointStamped`	`header` + `point`	标注点
`QuaternionStamped`	`header` + `quaternion`	方向
`Vector3Stamped`	`header` + `vector`	力/加速度向量

6.3.4 协方差变体

类型	协方差大小	顺序
`PoseWithCovariance`	36 (6×6)	x, y, z, roll, pitch, yaw
`TwistWithCovariance`	36 (6×6)	同上
`AccelWithCovariance`	36 (6×6)	同上

对应 *Stamped 变体：PoseWithCovarianceStamped、TwistWithCovarianceStamped 等。

6.3.5 变换

类型	字段	说明
`Transform`	`Vector3 translation` + `Quaternion rotation`	刚体变换
`TransformStamped`	`header` + `child_frame_id` + `transform`	TF 边
`TransformStampeds`	`vector<TransformStamped>`	批量变换
`VelocityStamped`	`header` + `body_frame_id` + `Twist velocity`	体坐标系速度

TF 约定：

header.frame_id     = 父坐标系（reference frame）
child_frame_id      = 子坐标系（target frame）
transform           = 从 child 到 parent 的变换

6.3.6 集合类型

类型	组成	用途
`PoseArray`	`header` + `vector<Pose>`	粒子滤波器粒子
`Pose2DArray`	`header` + `vector<Pose2D>`	平面粒子

6.3.7 Apollo 扩展

类型	字段	用途
`PointENU`	`x, y, z` (double)	UTM/ENU 坐标
`PointLLH`	`lon, lat, height` (double)	经纬高（WGS84）
`Inertia`	`m, com, ixx..izz`	刚体惯性张量
`InertiaStamped`	`header` + `inertia`	带时间戳惯性

6.3.8 转换完整度

类别	完整度	备注
Vector3 / Point / Quaternion	✅ 完整
Pose / Twist / Transform	✅ 完整
*Stamped 系列	✅ 大部分完整
*WithCovariance	✅ 完整
Polygon	⏳ 部分	`ToProto` 可能遗漏 points
PoseArray	⏳ 部分	header 转换待补全
PointENU / PointLLH	✅ 完整

6.4 使用频率排序

导航栈中最常用的 geometry_msgs 类型：

优先级	类型	使用模块
★★★	`PoseStamped`	planning, control, navigator
★★★	`Twist` / `TwistStamped`	control
★★★	`TransformStamped`	transform, localization
★★☆	`Pose` / `Pose2D`	checker, 几何计算
★★☆	`PoseWithCovariance`	localization, odom
★☆☆	`Polygon`	costmap 禁区
★☆☆	`PointENU` / `PointLLH`	高精地图

6.5 代码示例：完整位姿链路

// 1. 里程计位姿（带协方差）
commsgs::geometry_msgs::PoseWithCovarianceStamped loc;
loc.header.stamp = commsgs::builtin_interfaces::Time::Now();
loc.header.frame_id = "map";
loc.pose.pose.position.x = 1.0;
loc.pose.covariance.resize(36, 0.0);
loc.pose.covariance[0] = 0.01;   // x 方差
loc.pose.covariance[7] = 0.01;   // y 方差
loc.pose.covariance[35] = 0.05;  // yaw 方差

// 2. 提取 PoseStamped 用于规划
commsgs::geometry_msgs::PoseStamped current;
current.header = loc.header;
current.pose = loc.pose.pose;

// 3. 计算速度命令
commsgs::geometry_msgs::TwistStamped cmd;
cmd.header.stamp = commsgs::builtin_interfaces::Time::Now();
cmd.header.frame_id = "base_link";
cmd.twist.linear.x = 0.5;
cmd.twist.angular.z = 0.1;