anchors

Anchor-based dense detection heads for the voxel detectors (PointPillars, SECOND).

A packed-format port of the anchor head from open-mmlab/OpenPCDet.

AnchorHead: the single-stage anchor head (per-anchor class logits, box residuals and a direction bin).
MultiGroupAnchorHead: the multi-group separate-head variant (sincos + velocity box code) used by the nuScenes detectors.
prediction_branch: the per-attribute SeparateHead branch builder, also used by the Voxel Mamba center head.

The anchors themselves come from generate_anchors and their training targets from assign_anchor_targets, in ops.anchors; residuals are decoded with decode_box_residuals.

Classes:

AnchorHeadOutput –

Raw and decoded predictions of AnchorHead.
AnchorHead –

Single-stage anchor head.
AnchorHeadMultiOutput –

Predictions of MultiGroupAnchorHead.
AnchorGroupHead –

One RPN head of MultiGroupAnchorHead.
MultiGroupAnchorHead –

Multi-group anchor head, one separate head per group of classes.

Functions:

prediction_branch –

Build a prediction branch: middle conv blocks, then a plain output conv.

AnchorHeadOutput [source] ¶

Bases: TypedDict

Raw and decoded predictions of AnchorHead.

AnchorHead [source] ¶

AnchorHead(
    input_channels: int,
    num_classes: int,
    grid_size: Tuple[int, int],
    point_cloud_range: Sequence[float],
    *,
    anchor_sizes: Sequence[Sequence[float]],
    anchor_bottom_heights: Sequence[float],
    feature_map_stride: int,
    anchor_rotations: Sequence[float] = (0.0, 1.57),
    num_dir_bins: int = 2,
    dir_offset: float = 0.78539,
    dir_limit_offset: float = 0.0,
)

Bases: Module

Single-stage anchor head.

Three \(1\times1\) convs predict, per anchor, class logits, 7-DoF box residuals and a direction bin. At inference the residuals are decoded against the precomputed anchors and the predicted heading is snapped to the predicted direction bin (dir_offset / num_dir_bins).

Parameters:

input_channels (int) –

Channels of the BEV feature map fed to the head.
num_classes (int) –

Number of foreground classes.
grid_size (Tuple[int, int]) –

Full voxel grid size \((n_x, n_y)\) (before the head feature-map stride).
point_cloud_range (Sequence[float]) –

Range \((x_\min, y_\min, z_\min, x_\max, y_\max, z_\max)\).
anchor_sizes (Sequence[Sequence[float]]) –

Per-class box size \((d_x, d_y, d_z)\), shape \((\text{num\_classes}, 3)\).
anchor_bottom_heights (Sequence[float]) –

Per-class anchor bottom \(z\), shape \((\text{num\_classes},)\).
anchor_rotations (Sequence[float], default: (0.0, 1.57) ) –

Yaw angles (radians) shared by all classes.
feature_map_stride (int) –

BEV feature-map stride of the head.
num_dir_bins (int, default: 2 ) –

Number of direction bins.
dir_offset (float, default: 0.78539 ) –

Direction-classifier angle offset.
dir_limit_offset (float, default: 0.0 ) –

Offset used when wrapping the decoded heading before snapping.

Methods:

reset_parameters –

Start the class logits at the focal-loss prior of \(1\%\) foreground anchors and the box residuals near zero.
generate_predicted_boxes –

Decode raw head outputs into per-anchor class logits and absolute boxes.
decode –

Decode a forward output into raw per-anchor detections (no score threshold or NMS).

reset_parameters [source] ¶

reset_parameters() -> None

Start the class logits at the focal-loss prior of \(1\%\) foreground anchors and the box residuals near zero.

generate_predicted_boxes [source] ¶

generate_predicted_boxes(
    batch_size: int,
    cls_preds: Tensor,
    box_preds: Tensor,
    dir_cls_preds: Tensor,
) -> Tuple[Tensor, Tensor]

Decode raw head outputs into per-anchor class logits and absolute boxes.

Returns:

Tensor –

A tuple (batch_cls_preds, batch_box_preds) of shapes \((B, A, \text{num\_classes})\)
Tensor –

(raw logits, not sigmoided) and \((B, A, 7)\) where \(A\) is the number of anchors.

decode [source] ¶

decode(out: AnchorHeadOutput) -> Detection3D

Decode a forward output into raw per-anchor detections (no score threshold or NMS).

Scores each anchor by its top sigmoid class probability and labels it by the argmax class. The full per-anchor set is returned; the evaluation pipeline applies score thresholding and per-class 3D NMS via the torch_pointcloud.ops.box3d utilities (see the benchmark examples).

Returns:

Detection3D –

Packed per-anchor detections `{"boxes": (B * A, 7), "scores": (B * A,), "labels": (B * A,),
Detection3D –

"batch": (B * A,)}` (PyG layout).

AnchorHeadMultiOutput [source] ¶

Bases: TypedDict

Predictions of MultiGroupAnchorHead.

AnchorGroupHead [source] ¶

AnchorGroupHead(
    input_channels: int,
    num_classes: int,
    num_anchors_per_location: int,
    code_size: int,
    reg_list: Sequence[str],
    head_label_indices: Tensor,
    *,
    num_middle_conv: int = 1,
    num_middle_filter: int = 64,
    act: Union[str, Callable, None] = "relu",
    act_kwargs: Optional[Dict[str, Any]] = None,
    norm: Union[str, Callable, None] = "batch_norm",
    norm_kwargs: Optional[Dict[str, Any]] = None,
)

Bases: Module

One RPN head of MultiGroupAnchorHead.

A SeparateHead-style head over the shared feature: a classification branch plus one regression branch per box-code group (reg, height, size, angle, velo), whose outputs are concatenated into the per-anchor box code. Predictions are reshaped to the multihead layout \((B, A, \cdot)\) with \(A\) the anchors of this head's class group.

Parameters:

input_channels (int) –

Channels of the shared feature map.
num_classes (int) –

Number of classes handled by this head (separate-multihead).
num_anchors_per_location (int) –

Anchors per BEV cell for this head.
code_size (int) –

Box code size (e.g. 10 for sincos angle + velocity).
reg_list (Sequence[str]) –

Regression-branch spec, e.g. ["reg:2", "height:1", "size:3", "angle:2", "velo:2"].
num_middle_conv (int, default: 1 ) –

Number of middle convs per branch.
num_middle_filter (int, default: 64 ) –

Middle-conv channel width.
act (Union[str, Callable, None], default: 'relu' ) –

Activation type or callable for the middle convs.
act_kwargs (Optional[Dict[str, Any]], default: None ) –

Extra activation arguments.
norm (Union[str, Callable, None], default: 'batch_norm' ) –

Normalization type or callable for the middle convs.
norm_kwargs (Optional[Dict[str, Any]], default: None ) –

Extra normalization arguments.

Methods:

reset_parameters –

Start the class logits at the focal-loss prior of \(1\%\) foreground anchors.

reset_parameters [source] ¶

reset_parameters() -> None

Start the class logits at the focal-loss prior of \(1\%\) foreground anchors.

MultiGroupAnchorHead [source] ¶

MultiGroupAnchorHead(
    input_channels: int,
    num_classes: int,
    grid_size: Tuple[int, int],
    point_cloud_range: Sequence[float],
    *,
    anchor_sizes: Sequence[Sequence[float]],
    anchor_bottom_heights: Sequence[float],
    head_class_groups: Sequence[Sequence[int]],
    feature_map_stride: int,
    anchor_rotations: Sequence[float] = (0.0, 1.57),
    shared_conv_num_filter: int = 64,
    reg_list: Sequence[str] = (
        "reg:2",
        "height:1",
        "size:3",
        "angle:2",
        "velo:2",
    ),
    num_middle_conv: int = 1,
    num_middle_filter: int = 64,
    code_size: int = 9,
    encode_angle_by_sincos: bool = True,
    act: Union[str, Callable, None] = "relu",
    act_kwargs: Optional[Dict[str, Any]] = None,
    norm: Union[str, Callable, None] = "batch_norm",
    norm_kwargs: Optional[Dict[str, Any]] = None,
)

Bases: Module

Multi-group anchor head, one separate head per group of classes.

A shared conv feeds several AnchorGroupHeads, one per class group. Anchors (7-DoF, padded to the box-code size) are decoded with decode_box_residuals (sincos heading, velocity deltas); per-head class scores stay separate (with their global label mapping) for class-wise NMS downstream.

Parameters:

input_channels (int) –

Channels of the BEV feature map fed to the head.
num_classes (int) –

Number of foreground classes.
grid_size (Tuple[int, int]) –

Full voxel grid size \((n_x, n_y)\).
point_cloud_range (Sequence[float]) –

Range \((x_\min, y_\min, z_\min, x_\max, y_\max, z_\max)\).
anchor_sizes (Sequence[Sequence[float]]) –

Per-class box size \((d_x, d_y, d_z)\), shape \((\text{num\_classes}, 3)\).
anchor_bottom_heights (Sequence[float]) –

Per-class anchor bottom \(z\), shape \((\text{num\_classes},)\).
head_class_groups (Sequence[Sequence[int]]) –

Class-index groups, one per RPN head (e.g. [[0], [1, 2], ...]); the classes in each group share one SeparateHead.
anchor_rotations (Sequence[float], default: (0.0, 1.57) ) –

Yaw angles (radians) shared by all classes.
feature_map_stride (int) –

BEV feature-map stride of the head.
shared_conv_num_filter (int, default: 64 ) –

Channels of the shared conv.
reg_list (Sequence[str], default: ('reg:2', 'height:1', 'size:3', 'angle:2', 'velo:2') ) –

Regression-branch spec for each head.
num_middle_conv (int, default: 1 ) –

Middle convs per branch.
num_middle_filter (int, default: 64 ) –

Middle-conv channel width.
code_size (int, default: 9 ) –

Base box code size (9 for nuScenes; +1 internally for sincos).
encode_angle_by_sincos (bool, default: True ) –

Encode heading as \((\cos, \sin)\).
act (Union[str, Callable, None], default: 'relu' ) –

Activation type or callable for the shared conv and head middle convs.
act_kwargs (Optional[Dict[str, Any]], default: None ) –

Extra activation arguments.
norm (Union[str, Callable, None], default: 'batch_norm' ) –

Normalization type or callable for the shared conv and head middle convs.
norm_kwargs (Optional[Dict[str, Any]], default: None ) –

Extra normalization arguments.

Methods:

decode –

Decode a multihead forward output into raw per-anchor detections (no score threshold or NMS).

decode [source] ¶

decode(out: AnchorHeadMultiOutput) -> Detection3D

Decode a multihead forward output into raw per-anchor detections (no score threshold or NMS).

Each head scores its anchors by their top sigmoid class probability and maps the argmax to the global label; the per-head results are concatenated in head order (matching batch_box's anchor order). When the box code carries velocity deltas the decoded \((v_x, v_y)\) columns are returned under velocity. The full per-anchor set is returned; the evaluation pipeline applies score thresholding and per-class 3D NMS via the torch_pointcloud.ops.box3d utilities (see the benchmark examples).

Returns:

Detection3D –

Packed per-anchor detections `{"boxes": (B * A, 7), "scores": (B * A,), "labels": (B * A,),
Detection3D –

"batch": (B * A,)}(PyG layout), plus"velocity"` \((B \cdot A, 2)\) when the head predicts it.

prediction_branch [source] ¶

prediction_branch(
    in_channels: int,
    out_channels: int,
    num_middle_conv: int,
    num_middle_filter: int,
    *,
    act: Union[str, Callable, None] = "relu",
    act_kwargs: Optional[Dict[str, Any]] = None,
    norm: Union[str, Callable, None] = "batch_norm",
    norm_kwargs: Optional[Dict[str, Any]] = None,
    bias: bool = False,
) -> Sequential

Build a prediction branch: middle conv blocks, then a plain output conv.

The per-attribute branch of the multi-head detectors: num_middle_conv blocks of (\(3\times3\) conv, norm, act) followed by a \(3\times3\) output conv.

Parameters:

in_channels (int) –

Input channels.
out_channels (int) –

Output channels of the final conv.
num_middle_conv (int) –

Number of middle conv blocks.
num_middle_filter (int) –

Channel width of the middle convs.
act (Union[str, Callable, None], default: 'relu' ) –

Activation of the middle conv blocks.
act_kwargs (Optional[Dict[str, Any]], default: None ) –

Extra activation arguments.
norm (Union[str, Callable, None], default: 'batch_norm' ) –

Normalization of the middle conv blocks.
norm_kwargs (Optional[Dict[str, Any]], default: None ) –

Extra normalization arguments.
bias (bool, default: False ) –

Whether the middle convs carry a bias (the output conv always does).

Returns:

Sequential –

The branch as an nn.Sequential.

Shape

Input: \((B, C_\text{in}, H, W)\)
Output: \((B, C_\text{out}, H, W)\)

Example

>>> branch = prediction_branch(64, 2, num_middle_conv=1, num_middle_filter=64)
>>> branch(torch.rand(2, 64, 16, 16)).shape
torch.Size([2, 2, 16, 16])