nuscenes

Mask of boxes whose BEV center distance from the sensor origin is strictly below their class range.

Parameters:

• boxes (Tensor) –

  Boxes \((N, 7)\) or \((N, 9)\) of \((c_x, c_y, c_z, d_x, d_y, d_z, \theta[, v_x, v_y])\).

• labels (Tensor) –

  Per-box class index into ranges, shape \((N,)\).

• ranges (Sequence[float]) –

  Maximum BEV range per class index, in the coordinate unit.

Returns:

• Tensor –

  Boolean keep mask of shape \((N,)\).

>>> boxes = torch.tensor([[3.0, 4, 0, 4, 2, 1.5, 0], [0, 41, 0, 0.5, 0.5, 1, 0]])
>>> filter_boxes_by_range(boxes, torch.tensor([0, 1]), ranges=[50.0, 40.0])
tensor([ True, False])

The nuScenes detection metrics: per-class AP, mAP, the five TP errors and the NDS.

Follows the official protocol of the nuScenes benchmark (nuScenes: A Multimodal Dataset for Autonomous Driving). Predictions are matched per sample and class by BEV center distance: in descending score order each prediction greedily takes the closest still-unmatched ground-truth box strictly below the threshold. AP interpolates precision at 101 recall points \(0.00, 0.01, \ldots, 1.00\), drops recalls up to min_recall, subtracts min_precision, clamps at \(0\), averages and rescales by the remaining precision span; mAP averages over class_names and dist_thresholds. The TP errors ATE (BEV center distance), ASE ($1 - $ IoU of center- and yaw-aligned boxes), AOE (absolute yaw difference, modulo \(\pi\) for barrier), AVE (L2 xy-velocity difference) and AAE ($1 - $ attribute accuracy) average the cumulative-mean error curve of the tp_threshold matches from min_recall to the highest achieved recall; a class without matches scores the full error of \(1\). The officially excluded pairs (traffic_cone: AOE/AVE/AAE, barrier: AVE/AAE) are left out of the per-metric means, and \(\text{NDS} = (5 \cdot \text{mAP} + \sum_\text{tp} (1 - \min(1, \text{err}))) / 10\).

Boxes are filtered before scoring: each sample keeps its max_boxes_per_sample highest-scoring predictions, boxes farther from the sensor origin (BEV) than their class range are dropped on both sides, and ground-truth boxes with gt_num_points == 0 are removed. When velocity columns or attributes are absent (on either side), AVE / AAE fall back to the full penalty of \(1.0\) per class.

Parameters:

• preds (Detection3D) –

  Predicted boxes \((M, 7)\) of \((c_x, c_y, c_z, d_x, d_y, d_z, \theta)\), or \((M, 9)\) with \((v_x, v_y)\) velocity columns appended, with their scores, labels (class index into class_names) and batch (sample index), each \((M,)\).

• target (Boxes3D) –

  Ground-truth boxes \((K, 7)\) or \((K, 9)\), like the predictions, with their labels and batch, each \((K,)\).

• class_names (Sequence[str]) –

  Class name per label index; barrier and traffic_cone get their official special handling by name.

• gt_num_points (Optional[Tensor], default: None ) –

  Optional per-box point count, shape \((K,)\); boxes with exactly \(0\) points are removed (unknown counts of \(-1\) are kept).

• pred_attributes (Optional[Tensor], default: None ) –

  Optional per-box attribute id, shape \((M,)\). Without it AAE is \(1.0\).

• gt_attributes (Optional[Tensor], default: None ) –

  Optional per-box attribute id, shape \((K,)\); a negative id marks a box without an attribute, which is skipped in the AAE mean. Without it AAE is \(1.0\).

• class_ranges (Optional[Mapping[str, float]], default: None ) –

  Maximum BEV evaluation range per class name; defaults to the official ranges (50 m car/truck/bus/trailer/construction_vehicle, 40 m pedestrian/motorcycle/bicycle, 30 m traffic_cone/barrier). A name missing from the mapping is not range-filtered.

• dist_thresholds (Sequence[float], default: (0.5, 1.0, 2.0, 4.0) ) –

  Matching thresholds in meters the AP is averaged over.

• tp_threshold (float, default: 2.0 ) –

  Matching threshold in meters of the TP-error metrics.

• max_boxes_per_sample (int, default: 500 ) –

  Per-sample cap on scored predictions (highest scores kept).

• min_recall (float, default: 0.1 ) –

  Recall up to which the AP and TP-error curves are clipped.

• min_precision (float, default: 0.1 ) –

  Precision subtracted before the AP mean.

Returns:

• Dict[str, float] –

  A flat dict with AP/<class> (averaged over dist_thresholds), mAP, mATE, mASE, mAOE,

• Dict[str, float] –

  mAVE, mAAE and NDS.

>>> zero = torch.tensor([0])
>>> preds = {
...     "boxes": torch.tensor([[0.25, 0.0, 0.0, 4.0, 2.0, 1.5, 0.0]]),
...     "scores": torch.tensor([0.9]),
...     "labels": zero,
...     "batch": zero,
... }
>>> target = {"boxes": torch.tensor([[0.0, 0.0, 0.0, 4.0, 2.0, 1.5, 0.0]]), "labels": zero, "batch": zero}
>>> metrics = nuscenes_detection_metrics(preds, target, class_names=["car"])
>>> f"{metrics['AP/car']:.2f} {metrics['mATE']:.2f} {metrics['NDS']:.3f}"
'1.00 0.25 0.775'

Derive per-box nuScenes attribute ids from predicted velocities (the standard speed heuristic).

A box moving faster than speed_threshold (BEV speed, m/s) gets its class's moving attribute, a slower box the parked / stopped / standing default; barrier and traffic_cone carry no attribute (id \(-1\)). The returned ids index the official 8-entry attribute table (attribute.json order), the id space of the pred_attributes / gt_attributes arguments of nuscenes_detection_metrics.

Parameters:

• labels (Tensor) –

  Per-box class index into class_names, shape \((M,)\) long.

• velocity (Tensor) –

  Per-box BEV velocity \((v_x, v_y)\), shape \((M, 2)\).

• class_names (Sequence[str]) –

  Class name per label index (the official 10 detection class names).

• speed_threshold (float, default: 1.0 ) –

  BEV speed in m/s above which a box counts as moving.

Returns:

• Tensor –

  Per-box attribute id, shape \((M,)\) long, \(-1\) for classes without attributes.

>>> labels = torch.tensor([0, 0, 1])
>>> velocity = torch.tensor([[3.0, 0.0], [0.5, 0.0], [2.0, 0.0]])
>>> nuscenes_velocity_attributes(labels, velocity, class_names=("car", "barrier")).tolist()
[0, 2, -1]