torchseg 0.0.1a1

TorchSeg

TorchSeg is an actively maintained and up-to-date fork of the Segmentation Models PyTorch (torchseg).

Features

The main features of this library are:

• High level API (just two lines to create a neural network)
• 9 models architectures for binary and multi class segmentation (including legendary Unet)
• 124 available encoders (and 500+ encoders from timm)
• All encoders have pre-trained weights for faster and better convergence
• Popular losses for training routines

Example Usage

Segmentation model is just a PyTorch nn.Module, which can be created as easy as:

import torchseg

model = torchseg.Unet(
    encoder_name="resnet34",        # choose encoder, e.g. mobilenet_v2 or efficientnet-b7
    encoder_weights="imagenet",     # use `imagenet` pre-trained weights for encoder initialization
    in_channels=1,                  # model input channels (1 for gray-scale images, 3 for RGB, etc.)
    classes=3,                      # model output channels (number of classes in your dataset)
)

• see table with available model architectures
• see table with available encoders and their corresponding weights

Models

Architectures

• Unet [paper]
• Unet++ [paper]
• MAnet [paper]
• Linknet [paper]
• FPN [paper]
• PSPNet [paper]
• PAN [paper]
• DeepLabV3 [paper]
• DeepLabV3+ [paper]

Encoders

The following is a list of supported encoders in TorchSeg. Select the appropriate family of encoders and click to expand the table and select a specific encoder and its pre-trained weights (encoder_name and encoder_weights parameters).

* ssl, swsl - semi-supervised and weakly-supervised learning on ImageNet (repo).

Timm Encoders

Pytorch Image Models (a.k.a. timm) has a lot of pretrained models and interface which allows using these models as encoders in torchseg, however, not all models are supported

• not all transformer models have features_only functionality implemented that is required for encoder
• some models have inappropriate strides

Total number of supported encoders: 549

Models API

• model.encoder - pretrained backbone to extract features of different spatial resolution
• model.decoder - depends on models architecture (Unet/Linknet/PSPNet/FPN)
• model.segmentation_head - last block to produce required number of mask channels (include also optional upsampling and activation)
• model.classification_head - optional block which create classification head on top of encoder
• model.forward(x) - sequentially pass x through model`s encoder, decoder and segmentation head (and classification head if specified)

Input channels

Input channels parameter allows you to create models, which process tensors with arbitrary number of channels. If you use pretrained weights from imagenet - weights of first convolution will be reused. For 1-channel case it would be a sum of weights of first convolution layer, otherwise channels would be populated with weights like new_weight[:, i] = pretrained_weight[:, i % 3] and than scaled with new_weight * 3 / new_in_channels.

model = torchseg.FPN('resnet34', in_channels=1)
mask = model(torch.ones([1, 1, 64, 64]))

Auxiliary classification output

All models support aux_params parameters, which is default set to None. If aux_params = None then classification auxiliary output is not created, else model produce not only mask, but also label output with shape NC. Classification head consists of GlobalPooling->Dropout(optional)->Linear->Activation(optional) layers, which can be configured by aux_params as follows:

aux_params=dict(
    pooling='avg',             # one of 'avg', 'max'
    dropout=0.5,               # dropout ratio, default is None
    activation='sigmoid',      # activation function, default is None
    classes=4,                 # define number of output labels
)
model = torchseg.Unet('resnet34', classes=4, aux_params=aux_params)
mask, label = model(x)

Depth

Depth parameter specify a number of downsampling operations in encoder, so you can make your model lighter if specify smaller depth.

model = torchseg.Unet('resnet34', encoder_depth=4)