Skip to content

anchor

Losses of the anchor-based BEV detection heads (SECOND, PointPillars and the multi-group nuScenes variants).

Each loss reads the output dict of its head, rebuilds the anchors from the head geometry, assigns the targets with assign_anchor_targets and combines the functional primitives.

Classes:

AnchorHeadLoss [source] 

AnchorHeadLoss(
    num_classes: int,
    *,
    point_cloud_range: Sequence[float],
    voxel_size: Sequence[float],
    anchor_sizes: Sequence[Sequence[float]],
    anchor_bottom_heights: Sequence[float],
    feature_map_stride: int,
    matched_thresholds: Sequence[float],
    unmatched_thresholds: Sequence[float],
    anchor_rotations: Sequence[float] = (0.0, 1.57),
    code_weights: Sequence[float] = (
        1.0,
        1.0,
        1.0,
        1.0,
        1.0,
        1.0,
        1.0,
    ),
    cls_weight: float = 1.0,
    loc_weight: float = 2.0,
    dir_weight: float = 0.2,
    num_dir_bins: int = 2,
    dir_offset: float = 0.78539,
    dir_limit_offset: float = 0.0,
    focal_alpha: float = 0.25,
    focal_gamma: float = 2.0,
    smooth_l1_beta: float = 1.0 / 9.0,
    match_height: bool = False,
)

Bases: Module

Loss of the single-group AnchorHead (SECOND, PointPillars).

Reference: SECOND: Sparsely Embedded Convolutional Detection (Yan et al., 2018).

Per scene each class's axis-aligned anchors are matched to that class's ground-truth boxes (assign_anchor_targets) using per-class IoU thresholds, giving per-anchor class labels (\(-1\) ignore, \(0\) background, \(\ge 1\) foreground) and residual box targets. Three terms are then summed:

  • Classification: sigmoid focal loss over one-hot foreground labels, weighted so ignored anchors contribute nothing and each scene is normalized by its positive count.
  • Box regression: code-weighted smooth-\(L_1\) of the residual encodings, with the heading residual replaced by \(\sin(\theta_p - \theta_g)\) (the sine-difference encoding) so a half-turn error is not penalized as a position error.
  • Direction: weighted softmax cross-entropy over the discretized heading bin.

Anchors are rebuilt in the constructor from the same geometry the head uses (generate_anchors); the loss holds no reference to the model.

Parameters:

  • num_classes (int) –

    Number of foreground classes.

  • point_cloud_range (Sequence[float]) –

    Range \((x_\min, y_\min, z_\min, x_\max, y_\max, z_\max)\).

  • voxel_size (Sequence[float]) –

    Voxel size \((v_x, v_y, v_z)\) (used with point_cloud_range to size the anchor grid).

  • anchor_sizes (Sequence[Sequence[float]]) –

    Per-class box size \((d_x, d_y, d_z)\), one row per class.

  • anchor_bottom_heights (Sequence[float]) –

    Per-class anchor bottom \(z\), one per class.

  • feature_map_stride (int) –

    BEV feature-map stride of the head.

  • matched_thresholds (Sequence[float]) –

    Per-class IoU at or above which an anchor is a positive.

  • unmatched_thresholds (Sequence[float]) –

    Per-class IoU below which an anchor is background.

  • anchor_rotations (Sequence[float], default: (0.0, 1.57) ) –

    Yaw angles (radians) shared by all classes.

  • code_weights (Sequence[float], default: (1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0) ) –

    Per-code regression weights, shape \((7,)\).

  • cls_weight (float, default: 1.0 ) –

    Weight of the classification term in the total.

  • loc_weight (float, default: 2.0 ) –

    Weight of the box-regression term in the total.

  • dir_weight (float, default: 0.2 ) –

    Weight of the direction term in the total.

  • num_dir_bins (int, default: 2 ) –

    Number of direction bins.

  • dir_offset (float, default: 0.78539 ) –

    Direction-target angle offset.

  • dir_limit_offset (float, default: 0.0 ) –

    Offset used when wrapping the heading before binning.

  • focal_alpha (float, default: 0.25 ) –

    Focal-loss positive/negative balance.

  • focal_gamma (float, default: 2.0 ) –

    Focal-loss focusing exponent.

  • smooth_l1_beta (float, default: 1.0 / 9.0 ) –

    Smooth-\(L_1\) transition point \(\beta\).

  • match_height (bool, default: False ) –

    Match anchors to boxes by the rotated 3D IoU when True, otherwise by the bird's-eye IoU of the boxes snapped to their nearest axis-aligned orientation.

Methods:

  • forward –

    Compute the anchor detection loss and its terms.

forward [source] 

forward(
    output: AnchorHeadOutput, data: Dict[str, Any]
) -> Dict[str, Tensor]

Compute the anchor detection loss and its terms.

Parameters:

  • output (AnchorHeadOutput) –

    The head's raw output: cls \((B, H, W, A_\text{loc} \cdot C)\), box \((B, H, W, A_\text{loc} \cdot 7)\) and dir_cls \((B, H, W, A_\text{loc} \cdot 2)\).

  • data (Dict[str, Any]) –

    Ground truth: packed box \((K, 7)\) full-extent (the velocity columns of \((K, 9)\) boxes are ignored), label \((K,)\) (\(0\)-based classes) and batch_box \((K,)\) per-box scene index.

Returns:

  • Dict[str, Tensor] –

    A dict with the scalar loss and detached cls_loss, box_loss, dir_loss.

MultiGroupAnchorHeadLoss [source] 

MultiGroupAnchorHeadLoss(
    num_classes: int,
    *,
    class_groups: Sequence[Sequence[int]],
    point_cloud_range: Sequence[float],
    voxel_size: Sequence[float],
    anchor_sizes: Sequence[Sequence[float]],
    anchor_bottom_heights: Sequence[float],
    feature_map_stride: int,
    matched_thresholds: Sequence[float],
    unmatched_thresholds: Sequence[float],
    anchor_rotations: Sequence[float] = (0.0, 1.57),
    code_weights: Sequence[float] = (
        1.0,
        1.0,
        1.0,
        1.0,
        1.0,
        1.0,
        1.0,
        1.0,
        0.0,
        0.0,
    ),
    cls_weight: float = 1.0,
    loc_weight: float = 0.25,
    pos_cls_weight: float = 1.0,
    neg_cls_weight: float = 2.0,
    focal_alpha: float = 0.25,
    focal_gamma: float = 2.0,
    match_height: bool = False,
    encode_angle_by_sincos: bool = True,
)

Bases: Module

Loss of the MultiGroupAnchorHead (nuScenes SECOND, PointPillars).

Reference: Class-balanced Grouping and Sampling for Point Cloud 3D Object Detection (Zhu et al., 2019).

The separate-multihead anchor head has several RPN heads, each owning a disjoint class group over a shared feature map. Per scene each class's axis-aligned anchors are matched to that class's ground-truth boxes (assign_anchor_targets) using per-class IoU thresholds, giving per-anchor class labels (\(-1\) ignore, \(0\) background, \(\ge 1\) foreground) and residual box targets. Two terms are summed:

  • Classification: per head, sigmoid focal loss over the one-hot labels restricted to that head's class columns, with positive / negative anchors weighted by pos_cls_weight / neg_cls_weight and each scene normalized by its total positive count.
  • Box regression: per head, code-weighted \(L_1\) over the \(10\)-dim box code \((x, y, z, d_x, d_y, d_z, \cos\Delta\theta, \sin\Delta\theta, v_x, v_y)\). The heading is encoded as a \((\cos, \sin)\) residual, so no separate direction classifier is used.

Note

Ground-truth boxes of \((K, 9)\) columns carry the velocity \((v_x, v_y)\) the last two codes regress; with \((K, 7)\) boxes those targets are zero, so leave the last two code_weights at their default \(0\) to keep the velocity branch unsupervised.

Anchors are rebuilt in the constructor from the same geometry the head uses (generate_anchors), in the head's class-group order; the loss holds no reference to the model.

Parameters:

  • num_classes (int) –

    Number of foreground classes (10 for nuScenes).

  • class_groups (Sequence[Sequence[int]]) –

    Class-index groups, one per RPN head (e.g. [[0], [1, 2], ...]), matching the head's head_class_groups; the classes in each group share one head, and the flattened groups must enumerate the classes \(0 \ldots C - 1\) in ascending order (the anchor / head layout).

  • point_cloud_range (Sequence[float]) –

    Range \((x_\min, y_\min, z_\min, x_\max, y_\max, z_\max)\).

  • voxel_size (Sequence[float]) –

    Voxel size \((v_x, v_y, v_z)\) (used with point_cloud_range to size the anchor grid).

  • anchor_sizes (Sequence[Sequence[float]]) –

    Per-class box size \((d_x, d_y, d_z)\), one row per class.

  • anchor_bottom_heights (Sequence[float]) –

    Per-class anchor bottom \(z\), one per class.

  • feature_map_stride (int) –

    BEV feature-map stride of the head.

  • matched_thresholds (Sequence[float]) –

    Per-class IoU at or above which an anchor is a positive.

  • unmatched_thresholds (Sequence[float]) –

    Per-class IoU below which an anchor is background.

  • anchor_rotations (Sequence[float], default: (0.0, 1.57) ) –

    Yaw angles (radians) shared by all classes.

  • code_weights (Sequence[float], default: (1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 0.0, 0.0) ) –

    Per-code regression weights, shape \((10,)\); the last two (velocity) default to \(0\).

  • cls_weight (float, default: 1.0 ) –

    Weight of the classification term in the total.

  • loc_weight (float, default: 0.25 ) –

    Weight of the box-regression term in the total.

  • pos_cls_weight (float, default: 1.0 ) –

    Classification weight of a positive anchor.

  • neg_cls_weight (float, default: 2.0 ) –

    Classification weight of a background anchor.

  • focal_alpha (float, default: 0.25 ) –

    Focal-loss positive/negative balance.

  • focal_gamma (float, default: 2.0 ) –

    Focal-loss focusing exponent.

  • match_height (bool, default: False ) –

    Match anchors to boxes by the rotated 3D IoU when True, otherwise by the bird's-eye IoU of the boxes snapped to their nearest axis-aligned orientation.

  • encode_angle_by_sincos (bool, default: True ) –

    Encode the heading residual as \((\cos, \sin)\) (always True for this head).

Methods:

  • forward –

    Compute the multihead anchor detection loss and its terms.

forward [source] 

forward(
    output: AnchorHeadMultiOutput, data: Dict[str, Any]
) -> Dict[str, Tensor]

Compute the multihead anchor detection loss and its terms.

Parameters:

  • output (AnchorHeadMultiOutput) –

    The head's raw output: per-head cls \((B, A_g, C_g)\) and box \((B, A_g, 10)\) lists, plus multihead_label_mapping (per-head 1-based global class indices).

  • data (Dict[str, Any]) –

    Ground truth: packed box \((K, 7)\) full-extent, or \((K, 9)\) with the velocity in the last two columns, label \((K,)\) (\(0\)-based classes) and batch_box \((K,)\) per-box scene index.

Returns:

  • Dict[str, Tensor] –

    A dict with the scalar loss and detached cls_loss, box_loss.