Skip to content

PointRCNN

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

Classes:

  • PointRCNNLoss –

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

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.