focal

Focal losses: the sigmoid focal loss of the anchor / point / query heads, the Gaussian focal loss of the heatmap heads and the Poly-1 focal loss.

Classes:

SigmoidFocalLoss –

Module form of sigmoid_focal_loss.
GaussianFocalLoss –

Module form of gaussian_focal_loss.
Poly1FocalLoss –

Module form of poly1_focal_loss, taking class indices.

SigmoidFocalLoss [source] ¶

SigmoidFocalLoss(
    alpha: float = 0.25,
    gamma: float = 2.0,
    reduction: Literal["none", "sum", "mean"] = "mean",
)

Bases: Module

Module form of sigmoid_focal_loss.

Parameters:

alpha (float, default: 0.25 ) –

Positive/negative balance \(\alpha\).
gamma (float, default: 2.0 ) –

Focusing exponent \(\gamma\).
reduction (Literal['none', 'sum', 'mean'], default: 'mean' ) –

"none" returns the per-element loss, "sum" its sum, "mean" its mean.

Example

import torch
from torch_pointcloud.losses import SigmoidFocalLoss

criterion = SigmoidFocalLoss(reduction="sum")
criterion(torch.zeros(4, 3), torch.zeros(4, 3)).shape  # torch.Size([])

Methods:

forward –

Compute the focal loss from logits \((\ldots, C)\), binary targets \((\ldots, C)\) and row weights \((\ldots)\).

forward [source] ¶

forward(
    logits: Tensor,
    targets: Tensor,
    weights: Optional[Tensor] = None,
) -> Tensor

Compute the focal loss from logits \((\ldots, C)\), binary targets \((\ldots, C)\) and row weights \((\ldots)\).

GaussianFocalLoss [source] ¶

GaussianFocalLoss(alpha: float = 2.0, gamma: float = 4.0)

Bases: Module

Module form of gaussian_focal_loss.

Takes heatmap logits and applies the sigmoid itself.

Parameters:

alpha (float, default: 2.0 ) –

Focusing exponent on the prediction.
gamma (float, default: 4.0 ) –

Down-weighting exponent on the soft negatives.

Example

import torch
from torch_pointcloud.losses import GaussianFocalLoss

criterion = GaussianFocalLoss()
criterion(torch.zeros(1, 2, 4, 4), torch.zeros(1, 2, 4, 4)).shape  # torch.Size([])

Methods:

forward –

Compute the loss from heatmap logits and the Gaussian target of the same shape.

forward [source] ¶

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

Compute the loss from heatmap logits and the Gaussian target of the same shape.

Poly1FocalLoss [source] ¶

Poly1FocalLoss(
    epsilon: float = 1.0,
    alpha: Optional[float] = 0.25,
    gamma: float = 2.0,
    reduction: Literal["none", "sum", "mean"] = "mean",
)

Bases: Module

Module form of poly1_focal_loss, taking class indices.

The targets are either class indices \((\ldots)\), one-hot encoded over the \(C\) logits, or binary targets of the logits' shape. reduction="mean" averages over every element of the \((\ldots, C)\) loss.

Parameters:

epsilon (float, default: 1.0 ) –

Weight \(\epsilon\) of the Poly-1 term.
alpha (Optional[float], default: 0.25 ) –

Positive/negative balance \(\alpha\); None disables it.
gamma (float, default: 2.0 ) –

Focusing exponent \(\gamma\).
reduction (Literal['none', 'sum', 'mean'], default: 'mean' ) –

"none" returns the per-element loss, "sum" its sum, "mean" its mean.

Example

import torch
from torch_pointcloud.losses import Poly1FocalLoss

criterion = Poly1FocalLoss()
criterion(torch.zeros(4, 3), torch.tensor([0, 1, 2, 0])).shape  # torch.Size([])

Methods:

forward –

Compute the loss from logits \((\ldots, C)\) and class indices \((\ldots)\) or binary targets \((\ldots, C)\).

forward [source] ¶

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

Compute the loss from logits \((\ldots, C)\) and class indices \((\ldots)\) or binary targets \((\ldots, C)\).

sigmoid_focal_loss [source] ¶

sigmoid_focal_loss(
    logits: Tensor,
    targets: Tensor,
    weights: Optional[Tensor] = None,
    *,
    alpha: float = 0.25,
    gamma: float = 2.0,
) -> Tensor

Sigmoid focal loss between per-class logits and binary targets (no reduction).

The classification term of Focal Loss for Dense Object Detection (Lin et al., 2017), shared by the anchor, point and query heads: binary cross-entropy on the sigmoid of each logit, scaled by \(\alpha_t (1 - p_t)^\gamma\) so confident predictions contribute little. Same math as torchvision.ops.sigmoid_focal_loss, plus an optional per-row weight.

Parameters:

logits (Tensor) –

Per-class logits, shape \((\ldots, C)\).
targets (Tensor) –

Binary (one-hot) targets of the same shape.
weights (Optional[Tensor], default: None ) –

Optional weight of every row, shape \((\ldots)\), broadcast over the class dimension.
alpha (float, default: 0.25 ) –

Positive/negative balance \(\alpha\).
gamma (float, default: 2.0 ) –

Focusing exponent \(\gamma\).

Returns:

Tensor –

The weighted per-element loss, shape \((\ldots, C)\).

Shape

logits: \((\ldots, C)\)
targets: \((\ldots, C)\)
weights: \((\ldots)\)
output: \((\ldots, C)\)

Example

>>> logits = torch.zeros(1, 2, 3)
>>> targets = torch.tensor([[[1.0, 0.0, 0.0], [0.0, 0.0, 0.0]]])
>>> sigmoid_focal_loss(logits, targets, torch.ones(1, 2)).shape
torch.Size([1, 2, 3])

gaussian_focal_loss [source] ¶

gaussian_focal_loss(
    pred: Tensor,
    target: Tensor,
    *,
    alpha: float = 2.0,
    gamma: float = 4.0,
    eps: float = 0.0001,
) -> Tensor

Penalty-reduced focal loss over a Gaussian heatmap, normalized by the number of peaks.

The heatmap objective of Objects as Points (Zhou et al., 2019), used by the center-based detection heads (CenterPoint, VoxelNeXt, TransFusion). Cells whose target is exactly \(1\) are positives with the \((1 - p)^\alpha \log p\) term; every other cell is a soft negative whose \(p^\alpha \log(1 - p)\) term is down-weighted by \((1 - y)^\gamma\), so cells near a peak barely count. The sum is divided by the number of positives (or left as is when there is none).

Parameters:

pred (Tensor) –

Predicted probabilities (post-sigmoid) of any shape; clamped to \([\varepsilon, 1 - \varepsilon]\).
target (Tensor) –

Gaussian heatmap target of the same shape, values in \([0, 1]\).
alpha (float, default: 2.0 ) –

Focusing exponent on the prediction.
gamma (float, default: 4.0 ) –

Down-weighting exponent on the soft negatives.
eps (float, default: 0.0001 ) –

Clamp keeping the logarithms finite.

Returns:

Tensor –

The scalar loss.

Shape

pred: \((\ldots)\)
target: \((\ldots)\)
output: scalar

Example

>>> target = torch.tensor([[1.0, 0.5], [0.0, 0.0]])
>>> gaussian_focal_loss(torch.full((2, 2), 0.5), target).shape
torch.Size([])

one_hot_foreground [source] ¶

one_hot_foreground(
    labels: Tensor, num_classes: int
) -> Tensor

One-hot encode per-row class labels, dropping the background column.

Ignored (\(-1\)) and background (\(0\)) rows map to an all-zero row; a foreground row with label \(\ell \ge 1\) maps to a one-hot row on class \(\ell - 1\). The target format of sigmoid_focal_loss for the anchor and point heads.

Parameters:

labels (Tensor) –

Class labels (\(-1\) ignore, \(0\) background, \(\ge 1\) foreground), shape \((\ldots)\).
num_classes (int) –

Number of foreground classes \(C\).

Returns:

Tensor –

One-hot foreground targets, shape \((\ldots, C)\).

Shape

labels: \((\ldots)\)
output: \((\ldots, C)\)

Example

>>> one_hot_foreground(torch.tensor([[2, 0, -1]]), 3).tolist()
[[[0.0, 1.0, 0.0], [0.0, 0.0, 0.0], [0.0, 0.0, 0.0]]]

poly1_focal_loss [source] ¶

poly1_focal_loss(
    logits: Tensor,
    targets: Tensor,
    *,
    epsilon: float = 1.0,
    alpha: Optional[float] = 0.25,
    gamma: float = 2.0,
) -> Tensor

Poly-1 focal loss between per-class logits and binary targets (no reduction).

The focal loss plus its first Poly-1 correction term of PolyLoss: A Polynomial Expansion Perspective of Classification Loss Functions (Leng et al., 2022), with \(p\) the sigmoid of the logit, \(p_t = p\) on the positive entries and \(1 - p\) elsewhere,

\[ \ell = \alpha_t\, (1 - p_t)^\gamma\, \mathrm{BCE}(\text{logit}, \text{target}) + \epsilon\, (1 - p_t)^{\gamma + 1} \]

Parameters:

logits (Tensor) –

Per-class logits, shape \((\ldots, C)\).
targets (Tensor) –

Binary (one-hot) targets of the same shape.
epsilon (float, default: 1.0 ) –

Weight \(\epsilon\) of the Poly-1 term.
alpha (Optional[float], default: 0.25 ) –

Positive/negative balance \(\alpha\); None disables it.
gamma (float, default: 2.0 ) –

Focusing exponent \(\gamma\).

Returns:

Tensor –

The per-element loss, shape \((\ldots, C)\).

Shape

logits: \((\ldots, C)\)
targets: \((\ldots, C)\)
output: \((\ldots, C)\)

Example

>>> logits = torch.zeros(2, 3)
>>> targets = torch.tensor([[1.0, 0.0, 0.0], [0.0, 1.0, 0.0]])
>>> poly1_focal_loss(logits, targets).shape
torch.Size([2, 3])