losses

Training criteria for detection, segmentation, and generative models.

Modules:

anchor –

Anchor-based detection losses for the voxel detectors (SECOND, PointPillars).
center –

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

Chamfer distance between batched point sets.
detr3d –

3DETR set-prediction detection loss: Hungarian query-to-object matching with per-layer aux losses.
lovasz –

Lovász-Softmax loss.
pointrcnn –

Two-stage PointRCNN detection loss: stage-1 per-point head and stage-2 ROI refinement.
sum –

Composite loss: sum of several (logits, target) losses.
transfusion –

TransFusion detection loss: Hungarian-matched query targets and a dense center-heatmap objective.
votenet –

VoteNet detection loss: deep Hough voting target assignment and multi-task objective.

Classes:

AnchorLoss –

Single-stage anchor detection loss (classification, box regression, direction).
MultiHeadAnchorLoss –

Separate-multihead anchor detection loss (per-head classification, sincos + velocity box regression).
CenterLoss –

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

Fully sparse center-based detection loss (VoxelNeXt).
DETR3DLoss –

3DETR Hungarian set-prediction detection loss.
LovaszLoss –

Lovász-Softmax loss: a smooth surrogate for the mean-IoU objective.
PointRCNNLoss –

Two-stage PointRCNN detection loss (per-point proposal head + ROI refinement head).
SumLoss –

Sum of several loss modules sharing a (logits, target) signature.
TransFusionLoss –

Query-based TransFusion detection loss (dense heatmap, matched classification, box, IoU rescore).
VoteNetLoss –

Multi-task VoteNet detection loss (vote, objectness, box, semantic).

Functions:

chamfer_distance –

Symmetric Chamfer distance between two batched point sets.

AnchorLoss ¶

AnchorLoss(
    num_classes: int,
    *,
    voxel_size: Sequence[float],
    point_cloud_range: 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

Single-stage anchor detection loss (classification, box regression, direction).

Reference: Yan et al., 2018.

The loss of the single-group anchor head used by SECOND and PointPillars. 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 channel replaced by the sine-difference encoding \(\sin(\theta_p)\cos(\theta_g)\) vs \(\cos(\theta_p)\sin(\theta_g)\) so the smooth-\(L_1\) acts on \(\sin(\theta_p - \theta_g)\).
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.
voxel_size (Sequence[float]) –

Voxel size \((v_x, v_y, v_z)\) (used with point_cloud_range to size the anchor grid).
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)\), 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 3D IoU when True, otherwise bird's-eye IoU.

Methods:

forward –

Compute the anchor detection loss and its components.

forward ¶

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

Compute the anchor detection loss and its components.

Parameters:

output (Dict[str, Tensor]) –

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)\).
batch (Dict[str, Any]) –

Ground truth: packed box \((K, 7)\) full-extent, label \((K,)\) (\(0\)-based classes) and batch_box \((K,)\) per-box scene index.

Returns:

Dict[str, Tensor] –

A dict with the scalar loss (to backprop) and detached cls_loss, box_loss, dir_loss.

MultiHeadAnchorLoss ¶

MultiHeadAnchorLoss(
    num_classes: int,
    *,
    class_groups: Sequence[Sequence[int]],
    voxel_size: Sequence[float],
    point_cloud_range: 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

Separate-multihead anchor detection loss (per-head classification, sincos + velocity box regression).

Reference: Zhu et al., 2019.

The loss of the separate-multihead anchor head used by the nuScenes SECOND and PointPillars detectors, where several RPN heads each own 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

The nuScenes ground-truth boxes carry no velocity (\((K, 7)\)), so the velocity targets are zero. Set the last two code_weights entries to \(0\) to leave the velocity branch unsupervised; the default does so.

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).
voxel_size (Sequence[float]) –

Voxel size \((v_x, v_y, v_z)\) (used with point_cloud_range to size the anchor grid).
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)\), 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 3D IoU when True, otherwise bird's-eye IoU.
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 components.

forward ¶

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

Compute the multihead anchor detection loss and its components.

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).
batch (Dict[str, Any]) –

Ground truth: packed box \((K, 7)\) full-extent, label \((K,)\) (\(0\)-based classes) and batch_box \((K,)\) per-box scene index.

Returns:

Dict[str, Tensor] –

A dict with the scalar loss (to backprop) and detached cls_loss, box_loss, dir_loss; the
Dict[str, Tensor] –

separate-multihead head carries no direction classifier, so dir_loss is always zero.

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.

DETR3DLoss ¶

DETR3DLoss(
    num_classes: int,
    num_angle_bin: int,
    *,
    matcher_cls_cost: float = 1.0,
    matcher_giou_cost: float = 2.0,
    matcher_center_cost: float = 0.0,
    matcher_objectness_cost: float = 0.0,
    loss_giou_weight: float = 0.0,
    loss_sem_cls_weight: float = 1.0,
    loss_no_object_weight: float = 0.2,
    loss_angle_cls_weight: float = 0.1,
    loss_angle_reg_weight: float = 0.5,
    loss_center_weight: float = 5.0,
    loss_size_weight: float = 1.0,
)

Bases: Module

3DETR Hungarian set-prediction detection loss.

Reference: Misra et al., 2021.

Object queries are matched to ground-truth boxes one-to-one per scene by a Hungarian assignment whose cost combines the negative predicted class probability, the negative generalized 3D IoU, the \(L_1\) center distance (in the per-scene min-max normalized frame) and the negative objectness. Every decoder layer is supervised (the last layer plus the intermediate layers as auxiliary outputs), each with the same weighted objective, and the per-layer losses are summed:

Semantic classification: per-query weighted cross-entropy over the \(C + 1\) class logits, with unmatched queries assigned the background slot and that slot down-weighted by loss_no_object_weight.
Center: \(L_1\) distance between matched query and box centers in the normalized frame.
Size: \(L_1\) distance between matched query and box sizes in the normalized frame.
Angle: cross-entropy on the heading bin plus a Huber loss on the in-bin residual, over matches.
GIoU: \(1 - \text{gIoU}_{3D}\) between matched query and box, over matches.
Cardinality: the \(L_1\) error between the count of non-background queries and the object count (logged only, never optimized).

Ground truth is read packed from the batch (full-extent \((K, 7)\) boxes with counter-clockwise headings, plus per-box classes) and densified per scene; the headings are negated into the model's native heading space before binning. The normalization uses the model's point_cloud_dims, so the loss holds no reference to the model.

Parameters:

num_classes (int) –

Number of semantic classes (the class head predicts one extra background slot).
num_angle_bin (int) –

Heading-angle bins (\(1\) for axis-aligned ScanNet, \(12\) for oriented SUN RGB-D).
matcher_cls_cost (float, default: 1.0 ) –

Matcher weight on the negative class probability.
matcher_giou_cost (float, default: 2.0 ) –

Matcher weight on the negative generalized 3D IoU.
matcher_center_cost (float, default: 0.0 ) –

Matcher weight on the normalized-center \(L_1\) distance.
matcher_objectness_cost (float, default: 0.0 ) –

Matcher weight on the negative objectness.
loss_giou_weight (float, default: 0.0 ) –

Weight of the GIoU term in the total. The reference trains with \(0\) (the GIoU drives only the matcher); note the rotated-box GIoU (scenes with non-zero headings) is computed without gradients, so a non-zero weight trains only axis-aligned scenes.
loss_sem_cls_weight (float, default: 1.0 ) –

Weight of the semantic-classification term in the total.
loss_no_object_weight (float, default: 0.2 ) –

Cross-entropy weight of the background class.
loss_angle_cls_weight (float, default: 0.1 ) –

Weight of the heading-bin classification term in the total.
loss_angle_reg_weight (float, default: 0.5 ) –

Weight of the heading-residual regression term in the total.
loss_center_weight (float, default: 5.0 ) –

Weight of the center term in the total.
loss_size_weight (float, default: 1.0 ) –

Weight of the size term in the total.

Methods:

forward –

Compute the 3DETR set-prediction loss and its components.

forward ¶

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

Compute the 3DETR set-prediction loss and its components.

Parameters:

output (Dict[str, Any]) –

A training-mode DETR3DTrainOutput: aux_outputs (a per-decoder-layer list of head dicts with sem_cls_logits, sem_cls_prob, objectness_prob, center_normalized, center_unnormalized, size_normalized, size_unnormalized, angle_logits, angle_residual_normalized, angle_continuous) and point_cloud_dims.
batch (Dict[str, Any]) –

Packed ground truth: DataKeys.BOX \((K, 7)\) full-extent boxes with counter-clockwise headings, DataKeys.LABEL \((K,)\) per-box classes and DataKeys.BATCH_BOX \((K,)\) per-box scene index.

Returns:

Dict[str, Tensor] –

A dict with the scalar loss (summed over decoder layers) and detached loss_sem_cls,
Dict[str, Tensor] –

loss_center, loss_size, loss_angle_cls, loss_angle_reg, loss_giou, loss_cardinality
Dict[str, Tensor] –

(each summed over decoder layers).

LovaszLoss ¶

LovaszLoss(
    ignore_index: int = -1,
    classes: Literal["present", "all"] = "present",
    loss_weight: float = 1.0,
)

Bases: Module

Lovász-Softmax loss: a smooth surrogate for the mean-IoU objective.

Optimizes segmentation overlap directly, and is typically summed with cross-entropy. See The Lovász-Softmax loss.

Parameters:

ignore_index (int, default: -1 ) –

Label value excluded from the loss.
classes (Literal['present', 'all'], default: 'present' ) –

"present" averages only classes present in the targets; "all" averages every class.
loss_weight (float, default: 1.0 ) –

Scalar multiplier applied to the loss.

Methods:

forward –

Compute the loss from per-point logits \((N, C)\) and labels \((N,)\).

forward ¶

forward(logits: Tensor, labels: Tensor) -> Tensor

Compute the loss from per-point logits \((N, C)\) and labels \((N,)\).

PointRCNNLoss ¶

PointRCNNLoss(
    num_classes: int,
    *,
    mean_sizes: Union[Tensor, Sequence[Sequence[float]]],
    gt_extra_width: Sequence[float] = (0.2, 0.2, 0.2),
    point_cls_weight: float = 1.0,
    point_box_weight: float = 1.0,
    point_code_weights: Sequence[float] = (1.0,) * 8,
    reg_fg_thresh: float = 0.55,
    cls_fg_thresh: float = 0.6,
    cls_bg_thresh: float = 0.45,
    rcnn_cls_weight: float = 1.0,
    rcnn_reg_weight: float = 1.0,
    rcnn_corner_weight: float = 1.0,
    rcnn_code_weights: Sequence[float] = (1.0,) * 7,
    focal_alpha: float = 0.25,
    focal_gamma: float = 2.0,
    smooth_l1_beta: float = 1.0 / 9.0,
)

Bases: Module

Two-stage PointRCNN detection loss (per-point proposal head + ROI refinement head).

Reference: Shi et al., 2019.

Stage 1 supervises the per-point head that generates proposals: every point inside a ground-truth box is foreground (points in the gap between a box and its enlarged copy are ignored), driving a sigmoid focal classification loss over the per-point class logits and a code-weighted smooth-\(L_1\) over the residual box encoding (center offset normalized by the class mean-size diagonal, log extents, \((\cos, \sin)\) heading). Stage 2 supervises the refinement head on the sampled ROIs the model forward produces: a binary cross-entropy on the confidence logit against an IoU-thresholded label, a code-weighted smooth-\(L_1\) on the ROI-canonical box residual, and an optional corner regularization (the mean smooth-\(L_1\) over the eight box corners, robust to the heading flip).

The stage-1 point targets are assigned inside the loss (points-in-box matching + mean-size residual encoding) from the packed ground truth; the stage-2 ROI-to-ground-truth matching (which is random) is done by the model forward, which passes the per-ROI max IoU and the canonically transformed matched box in its training-mode output. The loss holds no reference to the model.

Parameters:

num_classes (int) –

Number of foreground classes.
mean_sizes (Union[Tensor, Sequence[Sequence[float]]]) –

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

Per-axis enlargement of a box when marking ignored points around it.
point_cls_weight (float, default: 1.0 ) –

Weight of the stage-1 classification term.
point_box_weight (float, default: 1.0 ) –

Weight of the stage-1 box-regression term.
point_code_weights (Sequence[float], default: (1.0,) * 8 ) –

Per-code stage-1 regression weights, shape \((8,)\).
reg_fg_thresh (float, default: 0.55 ) –

ROI-to-GT IoU at or above which a ROI's box regression is supervised.
cls_fg_thresh (float, default: 0.6 ) –

ROI-to-GT IoU above which a ROI's confidence label is \(1\).
cls_bg_thresh (float, default: 0.45 ) –

ROI-to-GT IoU below which a ROI's confidence label is \(0\); the band between cls_bg_thresh and cls_fg_thresh is ignored.
rcnn_cls_weight (float, default: 1.0 ) –

Weight of the stage-2 confidence term.
rcnn_reg_weight (float, default: 1.0 ) –

Weight of the stage-2 box-regression term.
rcnn_corner_weight (float, default: 1.0 ) –

Weight of the stage-2 corner regularization (\(0\) disables it).
rcnn_code_weights (Sequence[float], default: (1.0,) * 7 ) –

Per-code stage-2 regression weights, shape \((7,)\).
focal_alpha (float, default: 0.25 ) –

Stage-1 focal-loss positive/negative balance.
focal_gamma (float, default: 2.0 ) –

Stage-1 focal-loss focusing exponent.
smooth_l1_beta (float, default: 1.0 / 9.0 ) –

Smooth-\(L_1\) transition point \(\beta\) for both regression terms.

Methods:

forward –

Compute the two-stage PointRCNN loss and its components.

forward ¶

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

Compute the two-stage PointRCNN loss and its components.

Parameters:

output (Dict[str, Tensor]) –

The model's training-mode output: stage-1 point_cls_preds \((N, C)\), point_box_preds \((N, 8)\), point_pos \((N, 3)\), point_batch \((N,)\); stage-2 rcnn_cls \((M, 1)\), rcnn_reg \((M, 7)\), rcnn_boxes \((M, 7)\), rois \((M, 7)\), gt_of_rois \((M, 7)\) (ROI-canonical matched box), gt_of_rois_src \((M, 7)\) (lidar-frame matched box) and roi_ious \((M,)\).
batch (Dict[str, Any]) –

Packed ground truth: DataKeys.BOX \((K, 7)\) full-extent, DataKeys.LABEL \((K,)\) (\(0\)-based classes) and DataKeys.BATCH_BOX \((K,)\) per-box scene index.

Returns:

Dict[str, Tensor] –

A dict with the scalar loss (to backprop) and detached point_cls_loss, point_box_loss,
Dict[str, Tensor] –

rcnn_cls_loss, rcnn_box_loss.

SumLoss ¶

SumLoss(losses: Sequence[Module])

Bases: Module

Sum of several loss modules sharing a (logits, target) signature.

Each sub-loss is evaluated on the same inputs and the results are added (e.g. cross-entropy plus Lovász). Apply per-loss weights through each module's own option (e.g. LovaszLoss(loss_weight=...)).

Parameters:

losses (Sequence[Module]) –

The loss modules to sum.

Methods:

forward –

Compute the summed loss over all sub-losses.

forward ¶

forward(logits: Tensor, target: Tensor) -> Tensor

Compute the summed loss over all sub-losses.

TransFusionLoss ¶

TransFusionLoss(
    num_classes: int,
    point_cloud_range: Sequence[float],
    voxel_size: Sequence[float],
    feature_map_stride: int,
    *,
    num_proposals: int = 200,
    gaussian_overlap: float = 0.1,
    min_radius: int = 2,
    hungarian_cls_cost: float = 0.15,
    hungarian_reg_cost: float = 0.25,
    hungarian_iou_cost: float = 0.25,
    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,
    bbox_weight: float = 0.25,
    hm_weight: float = 1.0,
    iou_weight: float = 0.5,
    focal_alpha: float = 0.25,
    focal_gamma: float = 2.0,
)

Bases: Module

Query-based TransFusion detection loss (dense heatmap, matched classification, box, IoU rescore).

Reference: Bai et al., 2022.

The head predicts a dense per-class BEV heatmap plus a fixed set of object queries, each carrying a class logit vector and a box code. Four terms are summed:

Heatmap: the ground-truth box centers are splatted onto a per-class BEV Gaussian map and the dense heatmap is supervised by the penalty-reduced center focal loss.
Classification: every scene's queries are decoded to boxes and matched to the ground truth by a per-scene Hungarian assignment (cost: focal classification + normalized center \(L_1\) + 3D IoU). The per-query class logits are then trained by sigmoid focal loss over one-hot targets (background for unmatched queries), normalized by the positive count.
Box regression: code-weighted \(L_1\) over the \(10\)-dim box code \((x, y, z + d_z / 2, \log d_x, \log d_y, \log d_z, \sin\theta, \cos\theta, v_x, v_y)\) at the matched queries.
IoU rescore: an \(L_1\) term regressing the per-query iou branch toward \(2 \cdot \text{IoU}_{3D} - 1\) between each matched query's decoded box and its ground-truth box.

The loss holds no reference to the model: the grid geometry is rebuilt from the constructor params.

Note

nuScenes ground-truth boxes carry no velocity (\((K, 7)\)), so the velocity targets are zero. The default code_weights zeroes the last two (velocity) codes to leave that branch unsupervised.

Parameters:

num_classes (int) –

Number of foreground classes (heatmap channels and query logits).
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.
num_proposals (int, default: 200 ) –

Number of object queries per scene.
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.
hungarian_cls_cost (float, default: 0.15 ) –

Weight of the focal classification term in the matching cost.
hungarian_reg_cost (float, default: 0.25 ) –

Weight of the normalized center-\(L_1\) term in the matching cost.
hungarian_iou_cost (float, default: 0.25 ) –

Weight of the 3D-IoU term in the matching cost.
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 weight, length \(10\); the last two (velocity) default to \(0\).
cls_weight (float, default: 1.0 ) –

Multiplier on the classification term.
bbox_weight (float, default: 0.25 ) –

Multiplier on the box-regression term.
hm_weight (float, default: 1.0 ) –

Multiplier on the heatmap term.
iou_weight (float, default: 0.5 ) –

Multiplier on the IoU-rescore term.
focal_alpha (float, default: 0.25 ) –

Focal positive/negative balance (classification loss and matching cost).
focal_gamma (float, default: 2.0 ) –

Focal focusing exponent (classification loss and matching cost).

Methods:

forward –

Compute the TransFusion loss and its components.

forward ¶

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

Compute the TransFusion loss and its components.

Parameters:

output (Dict[str, Tensor]) –

The head's raw output: per-query center \((B, 2, Q)\), height \((B, 1, Q)\), dim \((B, 3, Q)\), rot \((B, 2, Q)\), vel \((B, 2, Q)\), iou \((B, 1, Q)\) and heatmap \((B, C, Q)\) class logits, plus the dense dense_heatmap \((B, C, H, W)\).
batch (Dict[str, Any]) –

Packed ground truth (DataKeys.BOX \((K, 7)\) full-extent, DataKeys.LABEL \((K,)\) \(0\)-based, DataKeys.BATCH_BOX \((K,)\) per-box scene index).

Returns:

Dict[str, Tensor] –

A dict with the scalar loss (to backprop) and detached heatmap_loss, cls_loss,
Dict[str, Tensor] –

bbox_loss, iou_loss diagnostics.

VoteNetLoss ¶

VoteNetLoss(
    num_heading_bin: int,
    num_size_cluster: int,
    num_classes: int,
    mean_sizes: Union[Tensor, List[List[float]]],
    *,
    near_threshold: float = 0.3,
    far_threshold: float = 0.6,
    objectness_weights: Tuple[float, float] = (0.2, 0.8),
    loss_scale: float = 10.0,
)

Bases: Module

Multi-task VoteNet detection loss (vote, objectness, box, semantic).

Reference: Qi et al., 2019.

Proposals are matched to ground-truth objects by nearest center: a proposal is positive when its nearest GT center is within near_threshold, negative beyond far_threshold, and ignored in the band between. Positives drive the center, heading, size and semantic terms; the vote term pulls each object seed's vote toward its object center (the closest of up to three candidate votes).

Parameters:

num_heading_bin (int) –

Number of heading-angle bins (\(1\) for axis-aligned ScanNet, \(12\) for SUN RGB-D).
num_size_cluster (int) –

Number of size templates.
num_classes (int) –

Number of semantic classes.
mean_sizes (Union[Tensor, List[List[float]]]) –

Per-template mean box size, shape \((\text{num\_size\_cluster}, 3)\).
near_threshold (float, default: 0.3 ) –

Distance (meters) below which a proposal is a positive object match.
far_threshold (float, default: 0.6 ) –

Distance (meters) above which a proposal is a negative match.
objectness_weights (Tuple[float, float], default: (0.2, 0.8) ) –

Cross-entropy class weights \([\text{negative}, \text{positive}]\).
loss_scale (float, default: 10.0 ) –

Global multiplier applied to the summed loss.

Methods:

forward –

Compute the VoteNet loss and its components.

forward ¶

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

Compute the VoteNet loss and its components.

Parameters:

output (Dict[str, Tensor]) –

The model's raw output: dense head tensors (objectness_scores, center, heading_scores, heading_residuals_normalized, size_scores, size_residuals_normalized, sem_cls_scores, pos_vote_aggr) as \((B, K, \cdot)\), plus the packed pos_seed, pos_vote \((S, 3)\) and seed_indices, batch_seed, batch_vote \((S,)\).
batch (Dict[str, Any]) –

Ground truth (center_label, heading_class_label, heading_residual_label, size_class_label, size_residual_label, sem_cls_label, box_label_mask as \((B, M, \cdot)\), per-point vote_label \((B, N, 9)\), vote_label_mask \((B, N)\), and the per-point batch index). The heading labels are binned from counter-clockwise headings and re-binned internally into the model's native (negated) heading space.

Returns:

Dict[str, Tensor] –

A dict with the scalar loss (to backprop) and detached vote_loss, objectness_loss,
Dict[str, Tensor] –

box_loss, center_loss, heading_cls_loss, heading_res_loss, size_cls_loss,
Dict[str, Tensor] –

size_res_loss, sem_cls_loss and obj_acc diagnostics.

chamfer_distance ¶

chamfer_distance(
    pred: Tensor,
    target: Tensor,
    norm: Literal["l1", "l2"] = "l2",
) -> Tensor

Symmetric Chamfer distance between two batched point sets.

Set-to-set reconstruction objective introduced for point cloud generation in Fan et al., 2017 and standard for masked point modeling pretraining (the SSL pretraining models return (pred, target) group coordinates in exactly this layout). For each point the squared euclidean distance to its nearest neighbor in the other set is computed, then reduced over all points and batches:

\[\text{CD}_{\ell_2} = \frac{1}{BN} \sum \min_j \lVert p_i - q_j \rVert_2^2 + \frac{1}{BM} \sum \min_i \lVert p_i - q_j \rVert_2^2\]

\[\text{CD}_{\ell_1} = \frac{1}{2} \Big( \frac{1}{BN} \sum \min_j \lVert p_i - q_j \rVert_2 + \frac{1}{BM} \sum \min_i \lVert p_i - q_j \rVert_2 \Big)\]

The "l2" variant sums the two directed means of squared distances (no square root, no halving); the "l1" variant averages the two directed means of euclidean distances. Both follow the reference pretraining convention, so losses are comparable with published values.

Parameters:

pred (Tensor) –

Predicted point sets of shape \((B, N, 3)\).
target (Tensor) –

Target point sets of shape \((B, M, 3)\).
norm (Literal['l1', 'l2'], default: 'l2' ) –

Distance variant, "l1" (euclidean) or "l2" (squared euclidean).

Returns:

Tensor –

Scalar Chamfer distance averaged over all points and batches.

Shape

Input: \((B, N, 3)\) and \((B, M, 3)\).
Output: scalar.

Example

import torch
from torch_pointcloud.losses import chamfer_distance

pred = torch.randn(64, 32, 3, requires_grad=True)
target = torch.randn(64, 32, 3)
loss = chamfer_distance(pred, target, norm="l2")
loss.backward()
print(loss.shape)