API Reference

mmseg.apis

mmseg.core

seg

mmseg.core.seg.build_pixel_sampler(cfg, **default_args)

Build pixel sampler for segmentation map.

class mmseg.core.seg.BasePixelSampler(**kwargs)

Base class of pixel sampler.

sample(seg_logit, seg_label)

Placeholder for sample function.

class mmseg.core.seg.OHEMPixelSampler(context, thresh=None, min_kept=100000)

Online Hard Example Mining Sampler for segmentation.

Parameters:

• context (nn.Module) – The context of sampler, subclass of BaseDecodeHead.
• thresh (float, optional) – The threshold for hard example selection. Below which, are prediction with low confidence. If not specified, the hard examples will be pixels of top min_kept loss. Default: None.
• min_kept (int, optional) – The minimum number of predictions to keep. Default: 100000.

sample(seg_logit, seg_label)

Sample pixels that have high loss or with low prediction confidence.

Parameters:

• seg_logit (torch.Tensor) – segmentation logits, shape (N, C, H, W)
• seg_label (torch.Tensor) – segmentation label, shape (N, 1, H, W)

Returns:

segmentation weight, shape (N, H, W)

Return type:

torch.Tensor

evaluation

class mmseg.core.evaluation.EvalHook(*args, by_epoch=False, efficient_test=False, **kwargs)

Single GPU EvalHook, with efficient test support.

Parameters:

• by_epoch (bool) – Determine perform evaluation by epoch or by iteration. If set to True, it will perform by epoch. Otherwise, by iteration. Default: False.
• efficient_test (bool) – Whether save the results as local numpy files to save CPU memory during evaluation. Default: False.

Returns:

The prediction results.

Return type:

list

class mmseg.core.evaluation.DistEvalHook(*args, by_epoch=False, efficient_test=False, **kwargs)

Distributed EvalHook, with efficient test support.

Parameters:

• by_epoch (bool) – Determine perform evaluation by epoch or by iteration. If set to True, it will perform by epoch. Otherwise, by iteration. Default: False.
• efficient_test (bool) – Whether save the results as local numpy files to save CPU memory during evaluation. Default: False.

Returns:

The prediction results.

Return type:

list

mmseg.core.evaluation.mean_dice(results, gt_seg_maps, num_classes, ignore_index, nan_to_num=None, label_map={}, reduce_zero_label=False)

Calculate Mean Dice (mDice)

Parameters:

• results (list[ndarray] | list[str]) – List of prediction segmentation maps or list of prediction result filenames.
• gt_seg_maps (list[ndarray] | list[str]) – list of ground truth segmentation maps or list of label filenames.
• num_classes (int) – Number of categories.
• ignore_index (int) – Index that will be ignored in evaluation.
• nan_to_num (int, optional) – If specified, NaN values will be replaced by the numbers defined by the user. Default: None.
• label_map (dict) – Mapping old labels to new labels. Default: dict().
• reduce_zero_label – Wether ignore zero label. Default: False.

mmseg.core.evaluation.mean_iou(results, gt_seg_maps, num_classes, ignore_index, nan_to_num=None, label_map={}, reduce_zero_label=False)

Calculate Mean Intersection and Union (mIoU)

Parameters:

• results (list[ndarray] | list[str]) – List of prediction segmentation maps or list of prediction result filenames.
• gt_seg_maps (list[ndarray] | list[str]) – list of ground truth segmentation maps or list of label filenames.
• num_classes (int) – Number of categories.
• ignore_index (int) – Index that will be ignored in evaluation.
• nan_to_num (int, optional) – If specified, NaN values will be replaced by the numbers defined by the user. Default: None.
• label_map (dict) – Mapping old labels to new labels. Default: dict().
• reduce_zero_label – Wether ignore zero label. Default: False.

mmseg.core.evaluation.mean_fscore(results, gt_seg_maps, num_classes, ignore_index, nan_to_num=None, label_map={}, reduce_zero_label=False, beta=1)

Calculate Mean Intersection and Union (mIoU)

Parameters:

• results (list[ndarray] | list[str]) – List of prediction segmentation maps or list of prediction result filenames.
• gt_seg_maps (list[ndarray] | list[str]) – list of ground truth segmentation maps or list of label filenames.
• num_classes (int) – Number of categories.
• ignore_index (int) – Index that will be ignored in evaluation.
• nan_to_num (int, optional) – If specified, NaN values will be replaced by the numbers defined by the user. Default: None.
• label_map (dict) – Mapping old labels to new labels. Default: dict().
• reduce_zero_label (bool) – Wether ignore zero label. Default: False.
• beta – Determines the weight of recall in the combined score. Default: False.

mmseg.core.evaluation.eval_metrics(results, gt_seg_maps, num_classes, ignore_index, metrics=['mIoU'], nan_to_num=None, label_map={}, reduce_zero_label=False, beta=1)

Calculate evaluation metrics :param results: List of prediction segmentation

maps or list of prediction result filenames.

Parameters:

• gt_seg_maps (list[ndarray] | list[str]) – list of ground truth segmentation maps or list of label filenames.
• num_classes (int) – Number of categories.
• ignore_index (int) – Index that will be ignored in evaluation.
• metrics (list[str] | str) – Metrics to be evaluated, ‘mIoU’ and ‘mDice’.
• nan_to_num (int, optional) – If specified, NaN values will be replaced by the numbers defined by the user. Default: None.
• label_map (dict) – Mapping old labels to new labels. Default: dict().
• reduce_zero_label – Wether ignore zero label. Default: False.

mmseg.core.evaluation.get_classes(dataset)

Get class names of a dataset.

mmseg.core.evaluation.get_palette(dataset)

Get class palette (RGB) of a dataset.

utils

mmseg.core.utils.add_prefix(inputs, prefix)

Add prefix for dict.

Parameters:

• inputs (dict) – The input dict with str keys.
• prefix (str) – The prefix to add.

Returns:

The dict with keys updated with prefix.

Return type:

dict

mmseg.datasets

datasets

pipelines

mmseg.models

segmentors

backbones

decode_heads

losses

mmseg.models.losses.accuracy(pred, target, topk=1, thresh=None)

Calculate accuracy according to the prediction and target.

Parameters:

• pred (torch.Tensor) – The model prediction, shape (N, num_class, …)
• target (torch.Tensor) – The target of each prediction, shape (N, , …)
• topk (int | tuple[int], optional) – If the predictions in topk matches the target, the predictions will be regarded as correct ones. Defaults to 1.
• thresh (float, optional) – If not None, predictions with scores under this threshold are considered incorrect. Default to None.

Returns:

If the input topk is a single integer,

the function will return a single float as accuracy. If topk is a tuple containing multiple integers, the function will return a tuple containing accuracies of each topk number.

Return type:

float | tuple[float]

class mmseg.models.losses.Accuracy(topk=(1, ), thresh=None)

Accuracy calculation module.

forward(pred, target)

Forward function to calculate accuracy.

Parameters:

• pred (torch.Tensor) – Prediction of models.
• target (torch.Tensor) – Target for each prediction.

Returns:

The accuracies under different topk criterions.

Return type:

tuple[float]

mmseg.models.losses.cross_entropy(pred, label, weight=None, class_weight=None, reduction='mean', avg_factor=None, ignore_index=-100)

The wrapper function for F.cross_entropy()

mmseg.models.losses.binary_cross_entropy(pred, label, weight=None, reduction='mean', avg_factor=None, class_weight=None, ignore_index=255)

Calculate the binary CrossEntropy loss.

Parameters:

• pred (torch.Tensor) – The prediction with shape (N, 1).
• label (torch.Tensor) – The learning label of the prediction.
• weight (torch.Tensor, optional) – Sample-wise loss weight.
• reduction (str, optional) – The method used to reduce the loss. Options are “none”, “mean” and “sum”.
• avg_factor (int, optional) – Average factor that is used to average the loss. Defaults to None.
• class_weight (list[float], optional) – The weight for each class.
• ignore_index (int | None) – The label index to be ignored. Default: 255

Returns:

The calculated loss

Return type:

torch.Tensor

mmseg.models.losses.mask_cross_entropy(pred, target, label, reduction='mean', avg_factor=None, class_weight=None, ignore_index=None)

Calculate the CrossEntropy loss for masks.

Parameters:

• pred (torch.Tensor) – The prediction with shape (N, C), C is the number of classes.
• target (torch.Tensor) – The learning label of the prediction.
• label (torch.Tensor) – label indicates the class label of the mask’ corresponding object. This will be used to select the mask in the of the class which the object belongs to when the mask prediction if not class-agnostic.
• reduction (str, optional) – The method used to reduce the loss. Options are “none”, “mean” and “sum”.
• avg_factor (int, optional) – Average factor that is used to average the loss. Defaults to None.
• class_weight (list[float], optional) – The weight for each class.
• ignore_index (None) – Placeholder, to be consistent with other loss. Default: None.

Returns:

The calculated loss

Return type:

torch.Tensor

class mmseg.models.losses.CrossEntropyLoss(use_sigmoid=False, use_mask=False, reduction='mean', class_weight=None, loss_weight=1.0)

CrossEntropyLoss.

Parameters:

• use_sigmoid (bool, optional) – Whether the prediction uses sigmoid of softmax. Defaults to False.
• use_mask (bool, optional) – Whether to use mask cross entropy loss. Defaults to False.
• reduction (str, optional) – . Defaults to ‘mean’. Options are “none”, “mean” and “sum”.
• class_weight (list[float] | str, optional) – Weight of each class. If in str format, read them from a file. Defaults to None.
• loss_weight (float, optional) – Weight of the loss. Defaults to 1.0.

forward(cls_score, label, weight=None, avg_factor=None, reduction_override=None, **kwargs)

Forward function.

mmseg.models.losses.reduce_loss(loss, reduction)

Reduce loss as specified.

Parameters:

• loss (Tensor) – Elementwise loss tensor.
• reduction (str) – Options are “none”, “mean” and “sum”.

Returns:

Reduced loss tensor.

Return type:

Tensor

mmseg.models.losses.weight_reduce_loss(loss, weight=None, reduction='mean', avg_factor=None)

Apply element-wise weight and reduce loss.

Parameters:

• loss (Tensor) – Element-wise loss.
• weight (Tensor) – Element-wise weights.
• reduction (str) – Same as built-in losses of PyTorch.
• avg_factor (float) – Avarage factor when computing the mean of losses.

Returns:

Processed loss values.

Return type:

Tensor

mmseg.models.losses.weighted_loss(loss_func)

Create a weighted version of a given loss function.

To use this decorator, the loss function must have the signature like loss_func(pred, target, **kwargs). The function only needs to compute element-wise loss without any reduction. This decorator will add weight and reduction arguments to the function. The decorated function will have the signature like loss_func(pred, target, weight=None, reduction=’mean’, avg_factor=None, **kwargs).

Example:

>>> import torch
>>> @weighted_loss
>>> def l1_loss(pred, target):
>>>     return (pred - target).abs()

>>> pred = torch.Tensor([0, 2, 3])
>>> target = torch.Tensor([1, 1, 1])
>>> weight = torch.Tensor([1, 0, 1])

>>> l1_loss(pred, target)
tensor(1.3333)
>>> l1_loss(pred, target, weight)
tensor(1.)
>>> l1_loss(pred, target, reduction='none')
tensor([1., 1., 2.])
>>> l1_loss(pred, target, weight, avg_factor=2)
tensor(1.5000)

class mmseg.models.losses.LovaszLoss(loss_type='multi_class', classes='present', per_image=False, reduction='mean', class_weight=None, loss_weight=1.0)

LovaszLoss.

This loss is proposed in The Lovasz-Softmax loss: A tractable surrogate for the optimization of the intersection-over-union measure in neural networks.

Parameters:

• loss_type (str, optional) – Binary or multi-class loss. Default: ‘multi_class’. Options are “binary” and “multi_class”.
• classes (str | list[int], optional) – Classes chosen to calculate loss. ‘all’ for all classes, ‘present’ for classes present in labels, or a list of classes to average. Default: ‘present’.
• per_image (bool, optional) – If per_image is True, compute the loss per image instead of per batch. Default: False.
• reduction (str, optional) – The method used to reduce the loss. Options are “none”, “mean” and “sum”. This parameter only works when per_image is True. Default: ‘mean’.
• class_weight (list[float] | str, optional) – Weight of each class. If in str format, read them from a file. Defaults to None.
• loss_weight (float, optional) – Weight of the loss. Defaults to 1.0.

forward(cls_score, label, weight=None, avg_factor=None, reduction_override=None, **kwargs)

Forward function.

class mmseg.models.losses.DiceLoss(smooth=1, exponent=2, reduction='mean', class_weight=None, loss_weight=1.0, ignore_index=255, **kwards)

DiceLoss.

This loss is proposed in V-Net: Fully Convolutional Neural Networks for Volumetric Medical Image Segmentation.

Parameters:

• loss_type (str, optional) – Binary or multi-class loss. Default: ‘multi_class’. Options are “binary” and “multi_class”.
• smooth (float) – A float number to smooth loss, and avoid NaN error. Default: 1
• exponent (float) – An float number to calculate denominator value: sum{x^exponent} + sum{y^exponent}. Default: 2.
• reduction (str, optional) – The method used to reduce the loss. Options are “none”, “mean” and “sum”. This parameter only works when per_image is True. Default: ‘mean’.
• class_weight (list[float] | str, optional) – Weight of each class. If in str format, read them from a file. Defaults to None.
• loss_weight (float, optional) – Weight of the loss. Default to 1.0.
• ignore_index (int | None) – The label index to be ignored. Default: 255.

forward(pred, target, avg_factor=None, reduction_override=None, **kwards)

Defines the computation performed at every call.

Should be overridden by all subclasses.

Note

Although the recipe for forward pass needs to be defined within this function, one should call the Module instance afterwards instead of this since the former takes care of running the registered hooks while the latter silently ignores them.