Source code for torchocr.losses

"""Loss functions for training torchocr models."""

import torch
from torch import Tensor, nn
from torch.nn import functional as F

from .models.detection import DBNetOutput


[docs] class DBLoss(nn.Module): """Differentiable Binarization training loss. Combines the three components of Liao et al. (AAAI 2020): 1. **Probability-map BCE with online hard example mining (OHEM).** OHEM keeps every positive pixel plus the ``negative_ratio * n_pos`` hardest negatives, preventing the background class from drowning the loss. 2. **Threshold-map L1 loss** restricted to the boundary band where the GT threshold is non-zero. 3. **Approximate-binary Dice loss** computed on ``B_hat = sigmoid(k * (P - T))``. The factor ``k`` controls how sharply this differentiable form approximates the true Heaviside step ``P > T``: as ``k -> infinity`` ``B_hat`` becomes a step function, but its gradient also vanishes away from the decision boundary. The paper's ``k = 50`` is a tested compromise -- a tight transition (``~0.04`` units in ``P - T``) that still leaves backprop signal. Lower ``k`` flattens the step toward ``0.5``; higher ``k`` starves the gradients. Total loss: ``Lp + binary_weight * Lb + threshold_weight * Lt``. Args: k: Steepness of the differentiable binarization. Default 50. threshold_weight: Multiplier on the threshold-map L1 loss. Default 10, matching the paper's beta. binary_weight: Multiplier on the dice loss over the approximate binary map. Default 1, matching the paper's alpha. Set to 0 to disable the binary term entirely. negative_ratio: Negatives-to-positives ratio for the OHEM sampling in the probability BCE. Default 3.0. eps: Numerical-stability epsilon for BCE clamping and Dice. """ def __init__( self, k: float = 50.0, threshold_weight: float = 10.0, binary_weight: float = 1.0, negative_ratio: float = 3.0, eps: float = 1e-6, ) -> None: super().__init__() if k <= 0: raise ValueError(f"k must be positive; got {k}.") if negative_ratio <= 0: raise ValueError(f"negative_ratio must be positive; got {negative_ratio}.") self.k = k self.threshold_weight = threshold_weight self.binary_weight = binary_weight self.negative_ratio = negative_ratio self.eps = eps
[docs] def forward( self, prediction: DBNetOutput, gt_probability: Tensor, gt_threshold: Tensor, training_mask: Tensor | None = None, ) -> dict[str, Tensor]: """Compute DB loss components and their weighted sum. Args: prediction: Output of :class:`DBNet` for one batch. gt_probability: ``(B, 1, H, W)`` 0/1 (or soft) text mask. gt_threshold: ``(B, 1, H, W)`` float threshold-map target. training_mask: Optional ``(B, 1, H, W)`` boolean tensor of valid pixels. ``False`` entries are excluded from all three losses (use this to ignore "don't care" regions such as overlapping or illegible text). Returns: ``{"loss", "probability", "threshold", "binary"}``. Call ``.backward()`` on the ``"loss"`` entry; log the others. """ prob = prediction.probability thresh = prediction.threshold if prob.shape != gt_probability.shape or thresh.shape != gt_threshold.shape: raise ValueError( f"Predictions and targets must share shape; got prob {tuple(prob.shape)} vs " f"{tuple(gt_probability.shape)}, threshold {tuple(thresh.shape)} vs " f"{tuple(gt_threshold.shape)}." ) if training_mask is None: mask = torch.ones_like(gt_probability, dtype=torch.bool) else: mask = training_mask.to(torch.bool) prob_loss = self._bce_ohem(prob, gt_probability, mask) thresh_loss = self._threshold_l1(thresh, gt_threshold, mask) binary_loss = self._dice(prob, thresh, gt_probability, mask) total = ( prob_loss + self.binary_weight * binary_loss + self.threshold_weight * thresh_loss ) return { "loss": total, "probability": prob_loss, "threshold": thresh_loss, "binary": binary_loss, }
def _bce_ohem(self, pred: Tensor, target: Tensor, mask: Tensor) -> Tensor: clamped = pred.clamp(min=self.eps, max=1.0 - self.eps) losses = F.binary_cross_entropy(clamped, target, reduction="none") positives = (target > 0.5) & mask negatives = (target <= 0.5) & mask n_pos = int(positives.sum().item()) n_neg_cap = int(negatives.sum().item()) n_neg = int(min(n_neg_cap, max(n_pos, 1) * self.negative_ratio)) if n_pos == 0 and n_neg == 0: return (losses * mask).sum() / mask.sum().clamp(min=1) pos_loss = losses[positives].sum() if n_pos > 0 else losses.new_zeros(()) if n_neg > 0: neg_losses = losses[negatives] if neg_losses.numel() > n_neg: neg_loss = neg_losses.topk(n_neg)[0].sum() else: neg_loss = neg_losses.sum() else: neg_loss = losses.new_zeros(()) return (pos_loss + neg_loss) / max(n_pos + n_neg, 1) def _threshold_l1(self, pred: Tensor, target: Tensor, mask: Tensor) -> Tensor: active = mask & (target > 0) if not active.any(): return pred.new_zeros(()) return F.l1_loss(pred[active], target[active]) def _dice(self, prob: Tensor, thresh: Tensor, target: Tensor, mask: Tensor) -> Tensor: binary = torch.sigmoid(self.k * (prob - thresh)) valid = mask.to(binary.dtype) binary = binary * valid target = target * valid intersection = (binary * target).sum() return 1.0 - (2.0 * intersection + self.eps) / (binary.sum() + target.sum() + self.eps)
[docs] class CRNNLoss(nn.Module): """Wrapper around :class:`torch.nn.CTCLoss` for CRNN-style logits. Applies ``log_softmax`` to the recognizer's logits before delegating to ``nn.CTCLoss``, which expects log probabilities. The blank index defaults to 0, matching :class:`CTCGreedyDecoder`. Args: blank_index: CTC blank class index. Default 0. reduction: Reduction passed to ``nn.CTCLoss`` -- 'mean', 'sum', or 'none'. Default 'mean'. zero_infinity: Whether to zero out infinite losses (caused by input lengths shorter than target lengths). Default True for training stability. """ def __init__( self, blank_index: int = 0, reduction: str = "mean", zero_infinity: bool = True, ) -> None: super().__init__() self.ctc = nn.CTCLoss( blank=blank_index, reduction=reduction, zero_infinity=zero_infinity, )
[docs] def forward( self, logits: Tensor, targets: Tensor, input_lengths: Tensor, target_lengths: Tensor, ) -> Tensor: """Compute the CTC loss. Args: logits: ``(T, B, num_classes)`` raw recognizer outputs. targets: Either ``(B, S_max)`` padded or ``(sum(target_lengths),)`` concatenated label tensor, per ``nn.CTCLoss`` convention. input_lengths: ``(B,)`` int tensor giving each sequence's effective length in time-steps. target_lengths: ``(B,)`` int tensor giving each target's length. """ if logits.ndim != 3: raise ValueError( f"Expected logits of shape (T, B, num_classes); got {tuple(logits.shape)}." ) log_probs = logits.log_softmax(dim=-1) return self.ctc(log_probs, targets, input_lengths, target_lengths)