center

Center-based 3D detection losses: dense (CenterHead) and fully sparse (VoxelNeXt) heatmap objectives.

Classes:

CenterLoss –

Dense center-based detection loss (CenterHead / Voxel Mamba).
SparseCenterLoss –

Fully sparse center-based detection loss (VoxelNeXt).

CenterLoss ¶

CenterLoss(
    num_classes: int,
    point_cloud_range: Sequence[float],
    voxel_size: Sequence[float],
    feature_map_stride: int,
    *,
    code_weights: Sequence[float],
    cls_weight: float = 1.0,
    loc_weight: float = 0.25,
    iou_weight: float = 0.0,
    gaussian_overlap: float = 0.1,
    min_radius: int = 2,
    num_max_objs: int = 500,
)

Bases: Module

Dense center-based detection loss (CenterHead / Voxel Mamba).

Reference: Center-based 3D Object Detection and Tracking.

Ground-truth boxes are splatted onto a per-class BEV Gaussian heatmap and their regression code (sub-cell center offset, \(z\), log extents and \((\cos\theta, \sin\theta)\)) is recorded at each peak cell. The heatmap is supervised by the penalty-reduced center focal loss and the regression maps by a masked, code-weighted \(L_1\) read back at those cells. When the head emits an iou map an optional \(L_1\) term regresses it toward the 3D IoU (rescaled to \([-1, 1]\)) between the decoded prediction and its matched box.

Parameters:

num_classes (int) –

Number of heatmap channels.
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)\).
feature_map_stride (int) –

Stride from the voxel grid to the BEV feature map.
code_weights (Sequence[float]) –

Per-code regression weight, length \(8\) (the head predicts no velocity codes).
cls_weight (float, default: 1.0 ) –

Multiplier on the heatmap focal loss.
loc_weight (float, default: 0.25 ) –

Multiplier on the summed regression loss.
iou_weight (float, default: 0.0 ) –

Multiplier on the optional IoU-branch loss (\(0\) disables it).
gaussian_overlap (float, default: 0.1 ) –

Min-overlap passed to the Gaussian-radius solver.
min_radius (int, default: 2 ) –

Lower clamp on the integer splat radius.
num_max_objs (int, default: 500 ) –

Per-scene object-target capacity.

Methods:

forward –

Compute the dense center loss and its components.

forward ¶

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

Compute the dense center loss and its components.

Parameters:

output (Dict[str, Tensor]) –

Head maps heatmap \((B, C, H, W)\), center \((B, 2, H, W)\), center_z \((B, 1, H, W)\), dim \((B, 3, H, W)\), rot \((B, 2, H, W)\) and optionally iou \((B, 1, H, W)\).
batch (Dict[str, Any]) –

Packed GT (DataKeys.BOX, DataKeys.LABEL, DataKeys.BATCH_BOX).

Returns:

Dict[str, Tensor] –

A dict with the scalar loss and detached hm_loss, loc_loss (and iou_loss when enabled).

SparseCenterLoss ¶

SparseCenterLoss(
    class_groups: Sequence[Sequence[int]],
    point_cloud_range: Sequence[float],
    voxel_size: Sequence[float],
    feature_map_stride: int,
    *,
    code_weights: Sequence[float],
    cls_weight: float = 1.0,
    loc_weight: float = 0.25,
    gaussian_overlap: float = 0.1,
    min_radius: int = 2,
    num_max_objs: int = 500,
)

Bases: Module

Fully sparse center-based detection loss (VoxelNeXt).

Reference: VoxelNeXt.

The head predicts CenterPoint-style attributes directly on the occupied BEV voxels rather than a dense map, so targets are drawn only at those voxels: the per-class heatmap is a Gaussian in squared voxel distance and each object's regression code is anchored to its nearest occupied voxel. The heatmap is supervised by the penalty-reduced center focal loss and the gathered regression rows by a masked, code-weighted \(L_1\). Classes are split into groups, one sparse head each.

Parameters:

class_groups (Sequence[Sequence[int]]) –

Zero-based global class-index groups, one per head (e.g. [[0], [1, 2], ...]).
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)\).
feature_map_stride (int) –

Stride from the voxel grid to the BEV feature map.
code_weights (Sequence[float]) –

Per-code regression weight, length \(8 + \text{extra}\) (e.g. \(10\) with velocity).
cls_weight (float, default: 1.0 ) –

Multiplier on the heatmap focal loss.
loc_weight (float, default: 0.25 ) –

Multiplier on the summed regression loss.
gaussian_overlap (float, default: 0.1 ) –

Min-overlap passed to the Gaussian-radius solver.
min_radius (int, default: 2 ) –

Lower clamp on the integer splat radius.
num_max_objs (int, default: 500 ) –

Per-scene object-target capacity.

Methods:

forward –

Compute the sparse center loss summed over class groups.

forward ¶

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

Compute the sparse center loss summed over class groups.

Parameters:

output (Dict[str, Any]) –

A VoxelNeXtHeadOutput: per-group lists hm \((V, n_g)\), center \((V, 2)\), center_z \((V, 1)\), dim \((V, 3)\), rot \((V, 2)\), vel \((V, 2)\) and shared voxel_indices \((V, 3)\) with columns \((\text{batch}, y, x)\).
batch (Dict[str, Any]) –

Packed GT (DataKeys.BOX, DataKeys.LABEL, DataKeys.BATCH_BOX).

Returns:

Dict[str, Tensor] –

A dict with the scalar loss and detached hm_loss, loc_loss.