BEV：MapTR

一、论文背景与核心贡献

传统方法

• 原理：先做分割，再通过聚类、骨架提取、曲线拟合得到地图矢量
• 优点：实现简单、监督密集、适合快速做 baseline
• 缺点：后处理复杂，实例恢复和几何一致性不稳定，训练目标和最终矢量地图输出不完全一致
  MapTR
• 原理：把地图元素表示成点序列，用 Transformer 直接做集合预测，并处理序列的排列等价性
• 优点：端到端、输出直接是矢量地图、结构更清晰、目标更对齐
• 缺点：训练和实现更复杂，对表示设计和 BEV 特征质量更敏感，复杂拓扑场景仍有挑战

---

二、整体架构

多相机图像 (6 cameras, 1600×900)

│

▼

┌─────────────────┐

│ Image Backbone │ (ResNet50, frozen stage1)

│ + FPN Neck │ → 1级特征图 (256维)

└────────┬────────┘

│

▼

┌──────────────────────────────────────────────┐

│ BEV Encoder (BEVFormerEncoder, 1层) │

│ │

│ BEV Queries (200×100, learnable) │

│ ├─→ Temporal Self-Attn │ ← prev_bev

│ ├─→ Norm │

│ ├─→ Geometry Spatial Cross-Attn │ ← 多相机特征

│ ├─→ Norm → FFN → Norm │

│ │

│ 输出: BEV Feature (bs, 20000, 256) │

└────────┬─────────────────────────────────────┘

│ (可选: + LiDAR特征 Fuse)

▼

┌──────────────────────────────────────────────┐

│ MapTR Decoder (×6 layers, iterative) │

│ │

│ Hierarchical Queries: │

│ 50 instance embeds + 20 point embeds │

│ = 1000 queries (50×20) │

│ │ │

│ ├─→ Self-Attention (query间交互) │

│ ├─→ Norm │

│ ├─→ Deformable Cross-Attn on BEV │

│ ├─→ Norm → FFN → Norm │

│ │ │

│ └─→ Regression Branch → 点坐标 delta │

│ Reference Points 迭代更新 │

│ │

│ 输出: 50个地图元素 × 20个点 × 2坐标 │

└──────────────────────────────────────────────┘

│

├─→ Classification: 3类 (divider/ped_crossing/boundary)

├─→ Points: [50, 20, 2] 矢量化地图元素

└─→ BBox: [50, 4] (从点集minmax推导)

---

三、核心技术模块详解

代码流程demo：

import torch
import torch.nn as nn
import torch.nn.functional as F

torch.manual_seed(42)

"""
MapTR 原理学习版代码
====================
这份代码的目标不是复现论文，而是把核心数据流讲清楚。
按下面顺序理解：
1. 训练时需要什么输入
2. 图像特征如何变成 BEV 表征
3. 为什么要有 map queries
4. decoder 之后每个 query 输出什么
5. prediction 如何和 GT 对齐
6. loss 为什么分成分类损失和点集损失

这份代码只保留主干逻辑：
图像特征 -> BEV特征 -> queries -> decoder -> 分类/点集输出 -> matching -> loss
"""

# ============================================================
# Step 0. 提前准备好的输入
# 基础参数
# ============================================================
B = 1
N_cam = 2
C = 8
N_query = 3
N_levels = 2
N_pts = 5
N_cls = 3   # lane_divider / road_boundary / no_object

print("目标：演示从多视角图像特征 -> BEV特征 -> map query -> 点集输出 -> loss 的主流程")
# 1) 图像特征：这里直接把 backbone + FPN 的输出当作输入
img_feats = [
    torch.randn(B, N_cam, C, 4, 4),
    torch.randn(B, N_cam, C, 2, 2),
]

# 2) 人工标注 GT：每个地图实例 = 类别 + 固定 N_pts 个点
# 真实项目里通常是原始 polyline 先重采样成固定点数，这里直接给重采样后的结果
#    这里的两个 GT 可以理解成：
#    - GT0: 一条 lane divider
#    - GT1: 一条 road boundary
gt_labels = torch.tensor([[0, 1]])
# [B, N_gt]，0=lane_divider, 1=road_boundary

gt_points = torch.tensor([
    [
        [[0.10, 0.20], [0.20, 0.20], [0.35, 0.25], [0.50, 0.35], [0.65, 0.45]],
        [[0.15, 0.70], [0.28, 0.72], [0.40, 0.75], [0.55, 0.78], [0.72, 0.82]],
    ]
], dtype=torch.float32)
# [B, N_gt, N_pts, 2]，这里的坐标已经归一化到 [0,1]

print(f"img_feats: {[x.shape for x in img_feats]}")
print(f"gt_labels: {gt_labels.shape}  [B, N_gt]")
print(f"gt_points: {gt_points.shape}  [B, N_gt, N_pts, 2]")
print("说明：MapTR 训练时监督的不是像素 mask，而是地图实例的类别和点集坐标。")

print("\n【Step 1】多视角图像特征编码为 BEV 特征")
def bev_encoder(img_feats):
    """
    这里只做一个非常简化的 BEV encoder：
    - 对每个 FPN level 做全局平均池化
    - 再把多层特征相加

    真实 MapTR / BEVFormer 里这里会更复杂：
    - 图像 backbone
    - FPN
    - view transform / BEV attention

    这一阶段的核心目标只有一个：
    把前视/侧视等多相机图像，变成一个统一的鸟瞰图表示，
    这样后面的 query 就能在同一个 BEV 空间里寻找地图元素。
    """
    pooled = []
    for feat in img_feats:
        # feat: [B, N_cam, C, H, W]
        p = feat.mean(dim=(-1, -2))   # [B, N_cam, C]
        pooled.append(p)

    bev = sum(pooled) / len(pooled)   # [B, N_cam, C]
    bev = bev.mean(dim=1)             # [B, C]
    return bev

bev_feat = bev_encoder(img_feats)
print(f"bev_feat: {bev_feat.shape}  [B, C]")
print("理解重点：BEV feature 负责提供场景级上下文。")

print("\n【Step 2】初始化 map queries")
# 每个 query 尝试去表示一个地图实例
# 可以把它理解成：
# "我准备了 N_query 个候选槽位，每个槽位都尝试去解释一个地图元素。"
query_embed = nn.Parameter(torch.randn(N_query, C))
print(f"query_embed: {query_embed.shape}  [N_query, C]")
print("理解重点：query 数通常多于真实 GT 数，未匹配的 query 会学成 no_object。")

print("\n【Step 3】decoder 让 query 和 BEV 特征交互")
def map_decoder(query_embed, bev_feat):
    """
    教学版简化：
    - 把全局 BEV 特征 broadcast 给每个 query
    - query + bev 做一次融合，得到实例级表示

    真实实现里这里通常是 Transformer decoder：
    - self attention
    - cross attention
    - FFN

    这一阶段结束后，每个 query 都会变成一个"实例级特征"。
    后续所有输出头，都是基于这个实例级特征再做预测。
    """
    bev_expand = bev_feat.unsqueeze(1).expand(B, N_query, C)     # [B, N_query, C]
    query_expand = query_embed.unsqueeze(0).expand(B, N_query, C)
    decoded = query_expand + bev_expand
    return decoded

decoded_feat = map_decoder(query_embed, bev_feat)
print(f"decoded_feat: {decoded_feat.shape}  [B, N_query, C]")
print("理解重点：decoded feature 已经不再是纯 query，而是带有场景信息的实例表示。")

print("\n【Step 4】分类头 + 点集回归头")
# instance level：预测每个 query 属于哪个类别
cls_head = nn.Linear(C, N_cls)

# point level：预测每个 query 的 N_pts 个二维点
pts_head = nn.Linear(C, N_pts * 2)

pred_logits = cls_head(decoded_feat)                     # [B, N_query, N_cls]
pred_points = pts_head(decoded_feat).sigmoid()          # [B, N_query, N_pts*2]
pred_points = pred_points.view(B, N_query, N_pts, 2)    # [B, N_query, N_pts, 2]

print(f"pred_logits: {pred_logits.shape}  [B, N_query, N_cls]")
print(f"pred_points: {pred_points.shape}  [B, N_query, N_pts, 2]")

print("\n每个 query 的输出含义：")
print("  1. pred_logits[q] -> 该 query 是 lane_divider / road_boundary / no_object 的概率")
print("  2. pred_points[q] -> 该 query 对应地图实例的固定点集坐标")
print("理解重点：MapTR 的输出不是检测框，而是'类别 + 有序点集'。")

print("\n【Step 5】prediction 和 GT 做 bipartite matching")
def match_cost_single(pred_logit, pred_pts, gt_label, gt_pts):
    """
    一个 query 和一个 GT 的匹配代价 = 分类代价 + 点回归代价

    这样设计的原因：
    - 如果类别对，但几何形状不对，也不能算好匹配
    - 如果几何接近，但类别错了，也不能算好匹配

    所以 MapTR 的 matching 是语义和几何联合决定的。
    """
    cls_cost = -F.log_softmax(pred_logit, dim=-1)[gt_label]
    pts_cost = F.l1_loss(pred_pts, gt_pts, reduction='mean')
    return cls_cost + pts_cost

# 教学版：手写一个 cost matrix
N_gt = gt_labels.shape[1]
cost_matrix = torch.zeros(N_query, N_gt)
for q in range(N_query):
    for g in range(N_gt):
        cost_matrix[q, g] = match_cost_single(
            pred_logits[0, q],
            pred_points[0, q],
            gt_labels[0, g],
            gt_points[0, g],
        )

print(f"cost_matrix: {cost_matrix.shape}  [N_query, N_gt]")
print(cost_matrix.detach())
print("理解重点：每一行表示一个 query 和所有 GT 的匹配代价。")

# 这里不展开 Hungarian 具体实现，只直接假设匹配结果：
# query0 -> gt0, query1 -> gt1, query2 -> no_object
matched_gt_inds = torch.tensor([0, 1, -1])
print(f"matched_gt_inds: {matched_gt_inds.tolist()}")
print("理解重点：匹配的目的，是把'无序的 query 输出'变成'可监督的实例对齐关系'。")

print("\n【Step 6】根据匹配结果计算 loss")
cls_losses = []
pts_losses = []
for q in range(N_query):
    gt_idx = matched_gt_inds[q].item()
    if gt_idx >= 0:
        # 1) 匹配成功：分类监督 + 点坐标监督
        target_label = gt_labels[0, gt_idx]
        loss_cls = F.cross_entropy(pred_logits[0, q].unsqueeze(0), target_label.unsqueeze(0))
        loss_pts = F.l1_loss(pred_points[0, q], gt_points[0, gt_idx], reduction='mean')
        cls_losses.append(loss_cls)
        pts_losses.append(loss_pts)
        print(f"query{q} 匹配 GT{gt_idx}: cls_loss={loss_cls.item():.4f}, pts_loss={loss_pts.item():.4f}")
    else:
        # 2) 未匹配成功：监督为 no_object，只算分类损失
        no_obj_label = torch.tensor([2])
        loss_cls = F.cross_entropy(pred_logits[0, q].unsqueeze(0), no_obj_label)
        cls_losses.append(loss_cls)
        print(f"query{q} 未匹配: cls_loss(no_object)={loss_cls.item():.4f}")

loss_cls = torch.stack(cls_losses).mean()
loss_pts = torch.stack(pts_losses).mean()
loss = loss_cls + 5.0 * loss_pts

print(f"\n最终损失:")
print(f"  loss_cls = {loss_cls.item():.4f}")
print(f"  loss_pts = {loss_pts.item():.4f}")
print(f"  total    = {loss.item():.4f}")
print("理解重点：")
print("  - 分类损失负责学'这是什么实例'")
print("  - 点集损失负责学'这个实例长什么样、在哪里'")
print("  - 未匹配 query 学成 no_object，避免所有 query 都乱预测前景")

print("\n【Step 7】一句话总结数据流")
print("图像特征 -> BEV特征 -> map queries -> decoder -> 分类/点集输出 -> matching -> 分类loss+点loss")

print("\n【适合写技术文档的总结】")
print("1. MapTR 把地图元素建模为'实例类别 + 固定长度点集'。")
print("2. 多视角图像先被编码成统一的 BEV 特征。")
print("3. 一组 map queries 在 decoder 中与 BEV 特征交互，得到实例级表示。")
print("4. 分类头负责实例语义预测，点集头负责地图几何预测。")
print("5. 训练时通过 bipartite matching，把 query 输出和 GT 实例一一对齐。")
print("6. 最终联合优化分类损失和点集回归损失。")

1. Permutation-Equivalent Modeling --- 最核心的创新

问题: 地图元素用有序点集表示，但同一条线有多种等价表示：

一条闭合多边形 (如人行横道):

P1→P2→P3→P4→P1 等价于

P2→P3→P4→P1→P2 等价于

P3→P4→P1→P2→P3 ... (共 N 种循环移位)

一条开放折线 (如车道线):

P1→P2→P3→P4 等价于

P4→P3→P2→P1 (正向/反向，共 2 种)

如果只用一种固定顺序做GT，模型预测另一种等价顺序时会被错误惩罚。

代码实现 (nuscenes_map_dataset.py:205-240):

LiDARInstanceLines.shift_fixed_num_sampled_points
  for fixed_num_pts in fixed_num_sampled_points:
      is_poly = fixed_num_pts[0].equal(fixed_num_pts[-1])  # 起点==终点 → 多边形

      if is_poly:
          # 多边形: 生成所有循环移位 (20个点 → 20种排列)
          for shift_right_i in range(fixed_num):
              shift_pts_list.append(fixed_num_pts.roll(shift_right_i, 0))
      else:
          # 开放折线: 正向 + 反向 (2种排列)
          shift_pts_list.append(fixed_num_pts)
          shift_pts_list.append(fixed_num_pts.flip(0))

输出 shape: [num_instances, num_shifts, fixed_num, 2]

例如: [15个地图元素, 20种排列, 20个点, 2坐标]

"MapTR的核心创新是置换等价建模。地图元素本质是点集，一条闭合多边形有N种等价的循环排列，一条开放折线有正反2种。训练时，我们为每个GT元素生成所有等价排列，在匹配阶段找到与预测最接近的排列来计算loss。这使得loss对点序置换不变，大幅稳定了训练。"

2. Hierarchical Query Design --- 层级查询

代码 (maptr_head.py:182-188):

  if self.query_embed_type == 'instance_pts':
Instance-level: 50个地图元素的嵌入
   self.instance_embedding = nn.Embedding(num_vec, embed_dims * 2)     # [50, 512]
Point-level: 20个点位置的嵌入
   self.pts_embedding = nn.Embedding(num_pts_per_vec, embed_dims * 2)  # [20, 512]

  组合方式 (maptr_head.py:226-228):

  pts_embeds = self.pts_embedding.weight.unsqueeze(0)       # [1, 20, 512]
  instance_embeds = self.instance_embedding.weight.unsqueeze(1)  # [50, 1, 512]
广播相加: [50, 20, 512] → flatten → [1000, 512]
  object_query_embeds = (pts_embeds + instance_embeds).flatten(0, 1)

"MapTR用层级query设计：50个instance embedding表示'哪个地图元素'，20个point embedding表示'元素中的第几个点'。两者相加组合后展平为1000个query（50×20）。这种设计让模型能同时建模元素级语义和点级几何，且参数只需要50+20=70个embedding，远少于naive的1000个独立embedding。"

• instance level 表示一个地图元素实例及其语义属性：负责回答这是什么对象
• point level 表示这个实例的几何形状，由一组矢量坐标点来刻画：负责回答：这个对象长什么样、在哪里

---

3. MapTR Assigner --- 带置换等价的匈牙利匹配

核心代码 (maptr_assigner.py:90-195):

  def assign(self, bbox_pred, cls_pred, pts_pred, gt_bboxes, gt_labels, gt_pts):
gt_pts shape: [num_gt, num_orders, num_pts, 2]
例如: [15, 20, 20, 2] → 15个GT, 每个20种排列, 每种20个点

Step 1: 分类代价
   cls_cost = self.cls_cost(cls_pred, gt_labels)  # [num_query, num_gt]

Step 2: BBox L1代价 (权重=0，实际不使用)
   reg_cost = self.reg_cost(bbox_pred[:, :4], normalized_gt_bboxes[:, :4])

Step 3: 点坐标代价 (核心!)
计算预测与所有GT排列的匹配代价
   pts_cost_ordered = self.pts_cost(pts_pred, normalized_gt_pts)
shape: [num_query, num_gt * num_orders]
   pts_cost_ordered = pts_cost_ordered.view(num_bboxes, num_gts, num_orders)

关键：找到每对(query, gt)的最佳排列
   pts_cost, order_index = torch.min(pts_cost_ordered, dim=2)
pts_cost: [num_query, num_gt] --- 最小代价
order_index: [num_query, num_gt] --- 最佳排列索引

Step 4: 总代价
   cost = cls_cost + reg_cost + iou_cost + pts_cost

Step 5: 匈牙利匹配
   matched_row_inds, matched_col_inds = linear_sum_assignment(cost)

   return AssignResult(...), order_index  # 返回最佳排列索引!

"匹配过程分两层优化：内层对每个(prediction, GT)对，遍历GT的所有等价排列找到代价最小的排列；外层对所有预测和GT做匈牙利匹配找全局最优分配。这保证了loss对排列不变性。"

---

4. Loss函数设计

目标回归 (maptr_head.py:565-596):

1. 使用匹配时选定的最佳排列作为target
  pts_targets[pos_inds] = gt_shifts_pts[pos_assigned_gt_inds, assigned_shift, :, :]
↑ 选定GT    ↑ 选定排列

2. 点坐标L1 Loss (weight=5.0, 主要loss)
  loss_pts = self.loss_pts(pts_preds, normalized_pts_targets, pts_weights)

3. 方向余弦Loss (weight=0.005, 辅助loss)
计算相邻点构成的方向向量
  denormed_pts_preds_dir = pts_preds[:, 1:, :] - pts_preds[:, :-1, :]
  pts_targets_dir = pts_targets[:, 1:, :] - pts_targets[:, :-1, :]
  loss_dir = self.loss_dir(denormed_pts_preds_dir, pts_targets_dir)

  总Loss权重 (来自config):

  total_loss = 2.0 × loss_cls (FocalLoss)
             + 0.0 × loss_bbox (L1, 实际禁用)
             + 0.0 × loss_iou  (GIoU, 实际禁用)
             + 5.0 × loss_pts  (PtsL1Loss, 核心)
             + 0.005 × loss_dir (PtsDirCosLoss, 辅助)

"Loss设计上，bbox loss被设为0因为它冗余（bbox可从点集推导），核心是点坐标L1 loss（weight=5）。此外有一个方向余弦loss（weight=0.005），确保预测曲线的走向和GT一致------光有坐标loss不够，两条点序相反的线坐标loss可能相同但方向完全反了。"

---

5. Head输出：点集→分类

代码 (maptr_head.py:284-286):

分类: 将同一元素的20个点特征取平均后做分类
  outputs_class = self.cls_branches[lvl](
      hs[lvl].view(bs, num_vec, num_pts_per_vec, -1).mean(2))
reshape为 [bs, 50, 20, 256] → 在点维度mean → [bs, 50, 256]

回归: 每个点独立预测2D坐标
  tmp = self.reg_branches[lvl](hs[lvl])  # [bs, 1000, 2]

  点集→BBox (maptr_head.py:320-348):

  def transform_box(self, pts):
      pts_reshape = pts.view(bs, num_vec, num_pts_per_vec, 2)  # [bs, 50, 20, 2]
      xmin = pts_x.min(dim=2)   # 所有点的最小x
      xmax = pts_x.max(dim=2)
      ymin = pts_y.min(dim=2)
      ymax = pts_y.max(dim=2)
      bbox = cat([xmin, ymin, xmax, ymax])  # [bs, 50, 4]
      bbox = bbox_xyxy_to_cxcywh(bbox)
      return bbox, pts_reshape

五、问题与回答

Q1: 为什么不直接用语义分割做地图构建？

答：语义分割输出栅格化的像素级结果，需要复杂的后处理（骨架化、矢量化、拓扑重建）才能得到矢量地图，过程中会累积误

差且不可微。MapTR是端到端的，直接输出矢量化点集，训练和推理都更高效，且可以端到端优化。

Q2: 为什么分类用点特征的平均而不是其他聚合方式？

答：同一个地图元素的20个点共享同一个类别，所以对20个点特征取均值后分类是自然的。这等价于对整条线的特征做全局池化

。也可以用max pooling或attention聚合，但mean简单有效，论文中没有发现更复杂聚合方式有显著提升。

Q3: MapTR和MapTRv2的主要区别？

答：MapTRv2 主要引入了：

1. 解耦的self-attention（instance-level和point-level分别做，降低计算量）；
2. 更多的地图元素类别（增加了中心线等）；
3. 辅助的one-to-many matching加速收敛；

Q4：人工标注的GT怎么转为采样的N个点？

答：先根据人工标注给出原始折线/多边形顶点计算曲线总长度，然后沿曲线按弧长均匀取 N 个位置，最后用线性插值得到 N 个点。