Semantic segmentation#

Functions#

kornia.losses.one_hot(labels, num_classes, device, dtype, eps=1e-6)[source]#

Convert an integer label x-D torch.Tensor to a one-hot (x+1)-D torch.Tensor.

Parameters:

  • labels (Tensor) – torch.Tensor with labels of shape \((N, *)\), where N is batch size. Each value is an integer representing correct classification.

  • num_classes (int) – number of classes in labels.

  • device (device) – the desired device of returned torch.Tensor.

  • dtype (dtype) – the desired data type of returned torch.Tensor.

  • eps (float, optional) – epsilon for numerical stability. Default: 1e-6

Return type:

Tensor

Returns:

the labels in one hot torch.Tensor of shape \((N, C, *)\),

Examples

>>> labels = torch.LongTensor([[[0, 1], [2, 0]]])
>>> one_hot(labels, num_classes=3, device=torch.device('cpu'), dtype=torch.float32)
tensor([[[[1.0000e+00, 1.0000e-06],
          [1.0000e-06, 1.0000e+00]],

         [[1.0000e-06, 1.0000e+00],
          [1.0000e-06, 1.0000e-06]],

         [[1.0000e-06, 1.0000e-06],
          [1.0000e+00, 1.0000e-06]]]])
kornia.losses.binary_focal_loss_with_logits(pred, target, alpha=0.25, gamma=2.0, reduction='none', pos_weight=None, weight=None, ignore_index=-100)[source]#

Criterion that computes Binary Focal loss.

According to [LGG+18], the Focal loss is computed as follows:

\[\text{FL}(p_t) = -\alpha_t (1 - p_t)^{\gamma} \, \text{log}(p_t)\]
Where:

  • \(p_t\) is the model’s estimated probability for each class.

Parameters:

  • pred (Tensor) – logits torch.Tensor with shape \((N, C, *)\) where C = number of classes.

  • target (Tensor) – labels torch.Tensor with the same shape as pred \((N, C, *)\) where each value is between 0 and 1.

  • alpha (Optional[float], optional) – Weighting factor \(\alpha \in [0, 1]\). Default: 0.25

  • gamma (float, optional) – Focusing parameter \(\gamma >= 0\). Default: 2.0

  • reduction (str, optional) – Specifies the reduction to apply to the output: 'none' | 'mean' | 'sum'. 'none': no reduction will be applied, 'mean': the sum of the output will be divided by the number of elements in the output, 'sum': the output will be summed. Default: "none"

  • pos_weight (Optional[Tensor], optional) – a weight of positive examples with shape \((num\_of\_classes,)\). It is possible to trade off recall and precision by adding weights to positive examples. Default: None

  • weight (Optional[Tensor], optional) – weights for classes with shape \((num\_of\_classes,)\). Default: None

  • ignore_index (Optional[int], optional) – labels with this value are ignored in the loss computation. Default: -100

Return type:

Tensor

Returns:

the computed loss.

Examples

>>> C = 3  # num_classes
>>> pred = torch.randn(1, C, 5, requires_grad=True)
>>> target = torch.randint(2, (1, C, 5))
>>> kwargs = {"alpha": 0.25, "gamma": 2.0, "reduction": 'mean'}
>>> output = binary_focal_loss_with_logits(pred, target, **kwargs)
>>> output.backward()
kornia.losses.focal_loss(pred, target, alpha, gamma=2.0, reduction='none', weight=None, ignore_index=-100)[source]#

Criterion that computes Focal loss.

According to [LGG+18], the Focal loss is computed as follows:

\[\text{FL}(p_t) = -\alpha_t (1 - p_t)^{\gamma} \, \text{log}(p_t)\]
Where:

  • \(p_t\) is the model’s estimated probability for each class.

Parameters:

  • pred (Tensor) – logits torch.Tensor with shape \((N, C, *)\) where C = number of classes.

  • target (Tensor) – labels torch.Tensor with shape \((N, *)\) where each value is an integer representing correct classification \(target[i] \in [0, C)\).

  • alpha (Optional[float]) – Weighting factor \(\alpha \in [0, 1]\).

  • gamma (float, optional) – Focusing parameter \(\gamma >= 0\). Default: 2.0

  • reduction (str, optional) – Specifies the reduction to apply to the output: 'none' | 'mean' | 'sum'. 'none': no reduction will be applied, 'mean': the sum of the output will be divided by the number of elements in the output, 'sum': the output will be summed. Default: "none"

  • weight (Optional[Tensor], optional) – weights for classes with shape \((num\_of\_classes,)\). Default: None

  • ignore_index (Optional[int], optional) – labels with this value are ignored in the loss computation. Default: -100

Return type:

Tensor

Returns:

the computed loss.

Example

>>> C = 5  # num_classes
>>> pred = torch.randn(1, C, 3, 5, requires_grad=True)
>>> target = torch.randint(C, (1, 3, 5))
>>> kwargs = {"alpha": 0.5, "gamma": 2.0, "reduction": 'mean'}
>>> output = focal_loss(pred, target, **kwargs)
>>> output.backward()
kornia.losses.dice_loss(pred, target, average='micro', eps=1e-8, weight=None, ignore_index=-100)[source]#

Criterion that computes Sørensen-Dice Coefficient loss.

According to [1], we compute the Sørensen-Dice Coefficient as follows:

\[\text{Dice}(x, class) = \frac{2 |X \cap Y|}{|X| + |Y|}\]
Where:

  • \(X\) expects to be the scores of each class.

  • \(Y\) expects to be the one-hot torch.Tensor with the class labels.

the loss, is finally computed as:

\[\text{loss}(x, class) = 1 - \text{Dice}(x, class)\]
Reference:

[1] https://en.wikipedia.org/wiki/S%C3%B8rensen%E2%80%93Dice_coefficient

Parameters:

  • pred (Tensor) – logits torch.Tensor with shape \((N, C, H, W)\) where C = number of classes.

  • target (Tensor) – labels torch.Tensor with shape \((N, H, W)\) where each value is in range \(0 ≤ targets[i] ≤ C-1\).

  • average (str, optional) – Reduction applied in multi-class scenario: - 'micro' [default]: Calculate the loss across all classes. - 'macro': Calculate the loss for each class separately and average the metrics across classes. Default: "micro"

  • eps (float, optional) – Scalar to enforce numerical stabiliy. Default: 1e-8

  • weight (Optional[Tensor], optional) – weights for classes with shape \((num\_of\_classes,)\). Default: None

  • ignore_index (Optional[int], optional) – labels with this value are ignored in the loss computation. Default: -100

Return type:

Tensor

Returns:

One-element torch.Tensor of the computed loss.

Example

>>> N = 5  # num_classes
>>> pred = torch.randn(1, N, 3, 5, requires_grad=True)
>>> target = torch.empty(1, 3, 5, dtype=torch.long).random_(N)
>>> output = dice_loss(pred, target)
>>> output.backward()
kornia.losses.tversky_loss(pred, target, alpha, beta, eps=1e-8, ignore_index=-100)[source]#

Criterion that computes Tversky Coefficient loss.

According to [SEG17], we compute the Tversky Coefficient as follows:

\[\text{S}(P, G, \alpha; \beta) = \frac{|PG|}{|PG| + \alpha |P \setminus G| + \beta |G \setminus P|}\]
Where:

  • \(P\) and \(G\) are the predicted and ground truth binary labels.

  • \(\alpha\) and \(\beta\) control the magnitude of the penalties for FPs and FNs, respectively.

Note

  • \(\alpha = \beta = 0.5\) => dice coeff

  • \(\alpha = \beta = 1\) => tanimoto coeff

  • \(\alpha + \beta = 1\) => F beta coeff

Parameters:

  • pred (Tensor) – logits tensor with shape \((N, C, H, W)\) where C = number of classes.

  • target (Tensor) – labels tensor with shape \((N, H, W)\) where each value is in range \(0 ≤ targets[i] ≤ C-1\).

  • alpha (float) – the first coefficient in the denominator.

  • beta (float) – the second coefficient in the denominator.

  • eps (float, optional) – scalar for numerical stability. Default: 1e-8

  • ignore_index (Optional[int], optional) – labels with this value are ignored in the loss computation. Default: -100

Return type:

Tensor

Returns:

the computed loss.

Example

>>> N = 5  # num_classes
>>> pred = torch.randn(1, N, 3, 5, requires_grad=True)
>>> target = torch.empty(1, 3, 5, dtype=torch.long).random_(N)
>>> output = tversky_loss(pred, target, alpha=0.5, beta=0.5)
>>> output.backward()
kornia.losses.lovasz_hinge_loss(pred, target)[source]#

Criterion that computes a surrogate binary intersection-over-union (IoU) loss.

According to [2], we compute the IoU as follows:

\[\text{IoU}(x, class) = \frac{|X \cap Y|}{|X \cup Y|}\]

[1] approximates this fomular with a surrogate, which is fully differentable.

Where:

  • \(X\) expects to be the scores of each class.

  • \(Y\) expects to be the binary tensor with the class labels.

the loss, is finally computed as:

\[\text{loss}(x, class) = 1 - \text{IoU}(x, class)\]
Reference:

[1] http://proceedings.mlr.press/v37/yub15.pdf [2] https://arxiv.org/pdf/1705.08790.pdf

Note

This loss function only supports binary labels. For multi-class labels please use the Lovasz-Softmax loss.

Parameters:

  • pred (Tensor) – logits tensor with shape \((N, 1, H, W)\).

  • target (Tensor) – labels tensor with shape \((N, H, W)\) with binary values.

Return type:

Tensor

Returns:

a scalar with the computed loss.

Example

>>> N = 1  # num_classes
>>> pred = torch.randn(1, N, 3, 5, requires_grad=True)
>>> target = torch.empty(1, 3, 5, dtype=torch.long).random_(N)
>>> output = lovasz_hinge_loss(pred, target)
>>> output.backward()
kornia.losses.lovasz_softmax_loss(pred, target, weight=None)[source]#

Criterion that computes a surrogate multi-class intersection-over-union (IoU) loss.

According to [1], we compute the IoU as follows:

\[\text{IoU}(x, class) = \frac{|X \cap Y|}{|X \cup Y|}\]

[1] approximates this fomular with a surrogate, which is fully differentable.

Where:

  • \(X\) expects to be the scores of each class.

  • \(Y\) expects to be the long tensor with the class labels.

the loss, is finally computed as:

\[\text{loss}(x, class) = 1 - \text{IoU}(x, class)\]
Reference:

[1] https://arxiv.org/pdf/1705.08790.pdf

Note

This loss function only supports multi-class (C > 1) labels. For binary labels please use the Lovasz-Hinge loss.

Parameters:

  • pred (Tensor) – logits tensor with shape \((N, C, H, W)\) where C = number of classes > 1.

  • target (Tensor) – labels tensor with shape \((N, H, W)\) where each value is in range \(0 ≤ targets[i] ≤ C-1\).

  • weight (Optional[Tensor], optional) – weights for classes with shape \((num\_of\_classes,)\). Default: None

Return type:

Tensor

Returns:

a scalar with the computed loss.

Example

>>> N = 5  # num_classes
>>> pred = torch.randn(1, N, 3, 5, requires_grad=True)
>>> target = torch.empty(1, 3, 5, dtype=torch.long).random_(N)
>>> output = lovasz_softmax_loss(pred, target)
>>> output.backward()

Modules#

class kornia.losses.BinaryFocalLossWithLogits(alpha, gamma=2.0, reduction='none', pos_weight=None, weight=None, ignore_index=-100)[source]#

Criterion that computes Focal loss.

According to [LGG+18], the Focal loss is computed as follows:

\[\text{FL}(p_t) = -\alpha_t (1 - p_t)^{\gamma} \, \text{log}(p_t)\]
torch.where:

  • \(p_t\) is the model’s estimated probability for each class.

Parameters:

  • alpha (Optional[float]) – Weighting factor \(\alpha \in [0, 1]\).

  • gamma (float, optional) – Focusing parameter \(\gamma >= 0\). Default: 2.0

  • reduction (str, optional) – Specifies the reduction to apply to the output: 'none' | 'mean' | 'sum'. 'none': no reduction will be applied, 'mean': the sum of the output will be divided by the number of elements in the output, 'sum': the output will be summed. Default: "none"

  • pos_weight (Optional[Tensor], optional) – a weight of positive examples with shape \((num\_of\_classes,)\). It is possible to trade off recall and precision by adding weights to positive examples. Default: None

  • weight (Optional[Tensor], optional) – weights for classes with shape \((num\_of\_classes,)\). Default: None

  • ignore_index (Optional[int], optional) – labels with this value are ignored in the loss computation. Default: -100

Shape:

  • Pred: \((N, C, *)\) where C = number of classes.

  • Target: the same shape as Pred \((N, C, *)\) where each value is between 0 and 1.

Examples

>>> C = 3  # num_classes
>>> pred = torch.randn(1, C, 5, requires_grad=True)
>>> target = torch.randint(2, (1, C, 5))
>>> kwargs = {"alpha": 0.25, "gamma": 2.0, "reduction": 'mean'}
>>> criterion = BinaryFocalLossWithLogits(**kwargs)
>>> output = criterion(pred, target)
>>> output.backward()
class kornia.losses.DiceLoss(average='micro', eps=1e-8, weight=None, ignore_index=-100)[source]#

Criterion that computes Sørensen-Dice Coefficient loss.

Dice-based objectives are common in medical and semantic segmentation because pixel classes are often highly imbalanced. This loss directly optimizes region-level agreement.

Parameters:

  • average (str, optional) – Reduction strategy for multi-class computation. Use “micro” to aggregate classes globally, or “macro” to average class-wise Dice scores. Default: "micro"

  • eps (float, optional) – Small constant added to the denominator for numerical stability. Default: 1e-8

  • weight (Optional[Tensor], optional) – Optional class-weight tensor of shape \((C,)\). Default: None

  • ignore_index (Optional[int], optional) – Label value to exclude from loss computation. Default: -100

Shapes:

  • pred: \((N, C, H, W)\) where C is the number of classes.

  • target: \((N, H, W)\) where each value is in the range \([0, C-1]\).

  • Output: scalar by default.

class kornia.losses.TverskyLoss(alpha, beta, eps=1e-8, ignore_index=-100)[source]#

Criterion that computes Tversky Coefficient loss.

According to [SEG17], we compute the Tversky Coefficient as follows:

\[\text{S}(P, G, \alpha; \beta) = \frac{|PG|}{|PG| + \alpha |P \setminus G| + \beta |G \setminus P|}\]
Where:

  • \(P\) and \(G\) are the predicted and ground truth binary labels.

  • \(\alpha\) and \(\beta\) control the magnitude of the penalties for FPs and FNs, respectively.

Note

  • \(\alpha = \beta = 0.5\) => dice coeff

  • \(\alpha = \beta = 1\) => tanimoto coeff

  • \(\alpha + \beta = 1\) => F beta coeff

Parameters:

  • alpha (float) – the first coefficient in the denominator.

  • beta (float) – the second coefficient in the denominator.

  • eps (float, optional) – scalar for numerical stability. Default: 1e-8

  • ignore_index (Optional[int], optional) – labels with this value are ignored in the loss computation. Default: -100

Shape:

  • Pred: \((N, C, H, W)\) where C = number of classes.

  • Target: \((N, H, W)\) where each value is \(0 ≤ targets[i] ≤ C-1\).

Examples

>>> N = 5  # num_classes
>>> criterion = TverskyLoss(alpha=0.5, beta=0.5)
>>> pred = torch.randn(1, N, 3, 5, requires_grad=True)
>>> target = torch.empty(1, 3, 5, dtype=torch.long).random_(N)
>>> output = criterion(pred, target)
>>> output.backward()
class kornia.losses.FocalLoss(alpha, gamma=2.0, reduction='none', weight=None, ignore_index=-100)[source]#

Criterion that computes Focal loss.

According to [LGG+18], the Focal loss is computed as follows:

\[\text{FL}(p_t) = -\alpha_t (1 - p_t)^{\gamma} \, \text{log}(p_t)\]
Where:

  • \(p_t\) is the model’s estimated probability for each class.

Parameters:

  • alpha (Optional[float]) – Weighting factor \(\alpha \in [0, 1]\).

  • gamma (float, optional) – Focusing parameter \(\gamma >= 0\). Default: 2.0

  • reduction (str, optional) – Specifies the reduction to apply to the output: 'none' | 'mean' | 'sum'. 'none': no reduction will be applied, 'mean': the sum of the output will be divided by the number of elements in the output, 'sum': the output will be summed. Default: "none"

  • weight (Optional[Tensor], optional) – weights for classes with shape \((num\_of\_classes,)\). Default: None

  • ignore_index (Optional[int], optional) – labels with this value are ignored in the loss computation. Default: -100

Shape:

  • Pred: \((N, C, *)\) where C = number of classes.

  • Target: \((N, *)\) where each value is an integer representing correct classification \(target[i] \in [0, C)\).

Example

>>> C = 5  # num_classes
>>> pred = torch.randn(1, C, 3, 5, requires_grad=True)
>>> target = torch.randint(C, (1, 3, 5))
>>> kwargs = {"alpha": 0.5, "gamma": 2.0, "reduction": 'mean'}
>>> criterion = FocalLoss(**kwargs)
>>> output = criterion(pred, target)
>>> output.backward()
class kornia.losses.LovaszHingeLoss[source]#

Criterion that computes a surrogate binary intersection-over-union (IoU) loss.

According to [2], we compute the IoU as follows:

\[\text{IoU}(x, class) = \frac{|X \cap Y|}{|X \cup Y|}\]

[1] approximates this fomular with a surrogate, which is fully differentable.

Where:

  • \(X\) expects to be the scores of each class.

  • \(Y\) expects to be the binary tensor with the class labels.

the loss, is finally computed as:

\[\text{loss}(x, class) = 1 - \text{IoU}(x, class)\]
Reference:

[1] http://proceedings.mlr.press/v37/yub15.pdf [2] https://arxiv.org/pdf/1705.08790.pdf

Note

This loss function only supports binary labels. For multi-class labels please use the Lovasz-Softmax loss.

Parameters:

  • pred – logits tensor with shape \((N, 1, H, W)\).

  • labels – labels tensor with shape \((N, H, W)\) with binary values.

Returns:

a scalar with the computed loss.

Example

>>> N = 1  # num_classes
>>> criterion = LovaszHingeLoss()
>>> pred = torch.randn(1, N, 3, 5, requires_grad=True)
>>> target = torch.empty(1, 3, 5, dtype=torch.long).random_(N)
>>> output = criterion(pred, target)
>>> output.backward()
class kornia.losses.LovaszSoftmaxLoss(weight=None)[source]#

Criterion that computes a surrogate multi-class intersection-over-union (IoU) loss.

According to [1], we compute the IoU as follows:

\[\text{IoU}(x, class) = \frac{|X \cap Y|}{|X \cup Y|}\]

[1] approximates this fomular with a surrogate, which is fully differentable.

Where:

  • \(X\) expects to be the scores of each class.

  • \(Y\) expects to be the binary tensor with the class labels.

the loss, is finally computed as:

\[\text{loss}(x, class) = 1 - \text{IoU}(x, class)\]
Reference:

[1] https://arxiv.org/pdf/1705.08790.pdf

Note

This loss function only supports multi-class (C > 1) labels. For binary labels please use the Lovasz-Hinge loss.

Parameters:

  • pred – logits tensor with shape \((N, C, H, W)\) where C = number of classes > 1.

  • labels – labels tensor with shape \((N, H, W)\) where each value is in range \(0 ≤ targets[i] ≤ C-1\).

  • weight (Optional[Tensor], optional) – weights for classes with shape \((num\_of\_classes,)\). Default: None

Returns:

a scalar with the computed loss.

Example

>>> N = 5  # num_classes
>>> criterion = LovaszSoftmaxLoss()
>>> pred = torch.randn(1, N, 3, 5, requires_grad=True)
>>> target = torch.empty(1, 3, 5, dtype=torch.long).random_(N)
>>> output = criterion(pred, target)
>>> output.backward()