Argoverse API 完全解析：自动驾驶数据集与高精地图开发利器

前言

在自动驾驶技术飞速发展的今天，高质量的数据集和强大的数据处理工具成为了科研与工程落地的关键。由 Argo AI（现隶属于大众集团与福特）开源的 Argoverse 项目，不仅提供了大规模的 3D 跟踪与运动预测数据集，还配套了功能丰富的 API，帮助开发者高效地处理 LiDAR、相机、地图等数据。本文将深入剖析 Argoverse API 的设计思路、核心功能以及实际使用方法，为从事自动驾驶、机器人、SLAM 等领域的读者提供一份详细的技术参考。

官方已发布 Argoverse 2 API，但本篇文章仍聚焦于经典的 Argoverse 1.x 版本，其在学术和工业界仍有广泛使用。

---

一、Argoverse 项目概览

1.1 数据集的独特价值

Argoverse 包含两个子集：

• Argoverse-Tracking：113 个高精度标注的驾驶场景（训练 65、验证 24、测试 24）。数据包括：

  • 30Hz 的原始相机图像（环视 7 个摄像头）

  • 10Hz 的 LiDAR 点云（已转换到后轴中心坐标系）

  • 5Hz 的立体相机对

  • 精确的 ego-vehicle 位姿（城市坐标系下的 SE(3)）

  • 3D 物体标注（带朝向与尺寸的 cuboid）

• Argoverse-Forecasting：约 32 万条运动预测序列（每条序列 5 秒），关注主车（agent）的未来轨迹，同时包含周围交通参与者的历史信息。特别适用于行为预测、轨迹生成等任务。

与 nuScenes、Waymo Open Dataset 等竞品相比，Argoverse 的独特优势在于高质量的 HD 地图------包含了车道中心线、路口拓扑、地面高度等语义信息，且与数据保持严格的时间同步。

1.2 API 的核心职责

Argoverse API 提供了三大模块：

1. 地图接口 (argoverse.map_representation.map_api.ArgoverseMap)

   支持地图元素的加载、查询（最近车道、路口编号等）、坐标变换等。

2. 跟踪数据加载器 (ArgoverseTrackingLoader)

   按帧或按物体轨迹加载 LiDAR 点云、图像、标注框。

3. 预测数据加载器 (ArgoverseForecastingLoader)

   高效读取运动预测序列（CSV 格式），并关联地图数据。

此外，API 还包括可视化工具（基于 mayavi 或 matplotlib）、评估指标（mAP、minADE 等）、标定转换等功能。

---

二、环境搭建与数据集准备

2.1 系统要求与依赖

• 操作系统：Linux 或 macOS（Windows 未官方支持，但可通过 WSL2 使用）

• Python 3.7 / 3.8

• 必需：pip, numpy, pandas, opencv-python, shapely, pyyaml, tqdm, numba

• 可选：mayavi（3D 可视化）、ffmpeg（视频生成）、plotly（交互式图表）、open3d（立体视觉）

2.2 下载与安装

# 克隆仓库
git clone https://github.com/argoai/argoverse-api.git
cd argoverse-api

# 下载 HD 地图（需先注册官网账号）
wget https://s3.amazonaws.com/argoverse/datasets/hd_maps.tar.gz
tar -xzf hd_maps.tar.gz   # 解压后得到 map_files 目录

# 安装 argoverse 包（开发模式）
pip install -e .

# 验证安装
python -c "import argoverse; print('OK')"

数据集下载地址：Argoverse 官网。建议先下载 sample 版本（tracking_sample.tar.gz 和 forecasting_sample.tar.gz）进行测试。

最终的目录结构应类似于：

argoverse-api/

├── argoverse/ # API 源码

├── map_files/ # HD 地图文件（解压后）

├── argoverse-tracking/ # 跟踪数据集（自行解压）

└── argoverse-forecasting/# 预测数据集

三、核心 API 使用教程

3.1 地图操作实战

from argoverse.map_representation.map_api import ArgoverseMap

# 初始化地图（首次加载会缓存）
avm = ArgoverseMap()

# 获取某个城市的所有车道中心线（示例：MIA 迈阿密）
city_name = "MIA"
lane_ids = avm.city_lane_centerlines[city_name].keys()

# 查询某条车道的几何数据（List of (x,y)）
lane_id = list(lane_ids)[0]
centerline = avm.get_lane_segment_centerline(lane_id, city_name)

# 给定 ego 车辆坐标，找到最近的车道
ego_x, ego_y = 300.0, 450.0
closest_lane = avm.get_closest_lane(ego_x, ego_y, city_name)
print(f"Closest lane ID: {closest_lane}")

# 获取某个点的地面高度（用于投影）
z = avm.get_ground_height_at_xy(ego_x, ego_y, city_name)

3.2 加载跟踪数据

from argoverse.data_loading.argoverse_tracking_loader import ArgoverseTrackingLoader

loader = ArgoverseTrackingLoader("./argoverse-tracking/sample")
log_id = "2bc6a872-9979-3493-82eb-fb55407473c9"  # 示例 log

# 获取第一帧 LiDAR 点云（已在 egovehicle 坐标系下）
lidar_data = loader.get_lidar(log_id, 0)   # 返回 (N,4) 数组，列：x,y,z,intensity
points = lidar_data[:, :3]

# 获取该帧的相机图像
cam_name = "ring_front_center"
img = loader.get_image(log_id, 0, cam_name)   # numpy array (H,W,3)

# 获取该帧的 3D 标注框
labels = loader.get_label(log_id, 0)         # list of Label objects
for label in labels:
    print(label.label_class, label.translation, label.rotation)

3.3 加载预测数据

from argoverse.data_loading.argoverse_forecasting_loader import ArgoverseForecastingLoader

# 初始化加载器（指向包含 CSV 文件的目录）
forecast_loader = ArgoverseForecastingLoader("./argoverse-forecasting/sample")

# 获取第一个序列
seq = forecast_loader[0]
print(seq.seq_id)

# 获取主车轨迹 (x, y, timestamp)
agent_traj = seq.agent_trajectory   # DataFrame

# 获取所有物体轨迹（包含类型标签）
all_tracks = seq.tracks
for obj_id, obj_df in all_tracks.items():
    print(obj_id, obj_df.iloc[0]['object_type'])

# 获取地图数据（需要指定城市名）
city = seq.city
avm = ArgoverseMap()
# 利用地图 API 进行进一步处理...

四、坐标变换深度解析

Argoverse 中坐标框架较多，容易混淆，官方给出了明确的定义：

坐标系	描述	常见数据
city	城市全局坐标系（地图基准）	HD 地图、预测轨迹
egovehicle	后轴中心，x 向前，y 向左，z 向上	LiDAR 点云、相机外参
camera	相机光心坐标系（x 向右，y 向下，z 向前）	图像像素投影
object	物体中心坐标系（x 向前）	3D 标注框的相对位姿

重要变换矩阵：

• city_SE3_egovehicle：将点从 egovehicle 变换到 city

• egovehicle_SE3_camera：从相机坐标系到 egovehicle（通常 API 里会使用其逆矩阵）

• egovehicle_SE3_object：从物体坐标系到 egovehicle（标注时给出）

使用示例（将 LiDAR 点投影到图像）：

import numpy as np
from argoverse.utils.calibration import get_camera_extrinsics, get_camera_intrinsics
from argoverse.utils.transform import egovehicle_to_city, city_to_egovehicle

# 获取标定参数
calib_file = f"{log_dir}/{log_id}/vehicle_calibration_info.json"
intrinsics = get_camera_intrinsics(calib_file, cam_name)
extrinsics = get_camera_extrinsics(calib_file, cam_name)  # camera_SE3_egovehicle

# 将点从 egovehicle 转到相机坐标系
pts_egovehicle = points  # (N,3)
pts_camera = extrinsics.transform(pts_egovehicle)

# 透视投影到像素坐标
u, v = intrinsics.project_3d_to_2d(pts_camera)

五、可视化工具与脚本

API 内置了多个实用的可视化脚本（位于根目录）：

1. 俯视渲染（BEV）

python visualize_30hz_benchmark_data_on_map.py \
    --dataset_dir ./argoverse-tracking/train \
    --log_id 2bc6a872-9979-3493-82eb-fb55407473c9 \
    --experiment_prefix output

输出：每帧的 BEV 图像（含地图、LiDAR 点云、标注框）及合成视频。

2.相机图像叠加 3D 框

python cuboids_to_bboxes.py \
    --dataset-dir ./argoverse-tracking/sample \
    --log-ids 2bc6a872-9979-3493-82eb-fb55407473c9 \
    --experiment-prefix viz

为每个相机生成标注框投影图及视频。

3.地面 LiDAR 点投影

python visualize_ground_lidar_points.py \
    --dataset-dir ./argoverse-tracking/train \
    --log-ids <log_id> \
    --experiment-prefix ground_viz

1. 展示地面点的语义分割效果。

注意：使用 mayavi 进行 3D 渲染时，可能会遇到 VTK 版本问题，建议在虚拟环境中安装 mayavi==4.7.4 和 PyQt5。

---

六、评测指标与基线

Argoverse 官方为两项任务提供了标准评测：

• 3D 跟踪 ：采用 CLEAR 指标（MOTA、MOTP）、ID 切换等。官方基线：基于 AB3DMOT 的 argoverse_baselinetracker。

• 运动预测 ：最小平均位移误差（minADE）、最终位移误差（minFDE）、漏检率（MR）等。基线模型可参考 argoverse-forecasting 中的 LSTM 和基于图神经网络的模型。

若要在自己的模型上评测，API 提供了 argoverse.evaluation 子模块，例如：

from argoverse.evaluation.eval_forecasting import compute_forecasting_metrics

# 假设预测结果格式：list of dict，包含 'pred_trajectory' (50个未来点)
metrics = compute_forecasting_metrics(gt_traj, pred_traj, horizon=50, missing_tolerance=5)

七、常见问题与技巧

1. 地图加载慢怎么办？

   第一次加载时 API 会构建 shapely 几何对象并缓存为 .pkl 文件（位于 ~/.argoverse_cache）。后续加载会明显加快。如果地图数据路径改变，可删除缓存强制重建。

2. Mayavi 无法渲染？

   建议在 Linux 下使用虚拟环境安装：

   sudo apt-get install libvtk7-dev
   pip install mayavi PyQt5
   export QT_API=pyqt5

3. 如何获取路面高度信息？

   使用 avm.get_ground_height_at_xy(x, y, city_name) 可返回该点的精确高程（来自 LiDAR 建图）。

4. 跟踪数据中物体 ID 为何不连续？

   每个 log 中的物体 ID 是全局唯一的（跨帧相同物体 ID 不变），但在不同 log 之间无关联。若要提取完整轨迹，可使用 argoverse/utils/make_track_label_folders.py 生成面向物体的标签文件夹。

---

八、总结与资源链接

Argoverse API 是一个设计严谨、文档丰富的自动驾驶工具包，尤其适合以下场景：

• 需要高精地图信息的轨迹预测或规划算法

• 研究多传感器融合（LiDAR+相机+地图）的 3D 感知

• 开发基于车道拓扑的行为预测模型

尽管官方已推出新版 Argoverse 2，但原版 API 的代码简洁度、社区活跃度仍然很高，是入门自动驾驶数据处理的优秀范例。

官方资源：

• GitHub 仓库

• API 文档

• 论文（CVPR 2019）

• Argoverse 官网

希望本文能帮助你快速上手 Argoverse。如果在使用中遇到问题，欢迎在官方 GitHub 仓库提交 Issue 或在本博客评论区交流讨论。

---

作者声明：本文基于 Argoverse API 1.x 版本撰写，部分细节在未来版本可能有所调整。请以官方最新文档为准。