Quick Run
In this chapter, we introduce users to some basic usage and commands of SSSegmentation to help users quickly get started running SSSegmentation.
Training and Testing Segmentors Integrated in SSSegmentation
SSSegmentation supports training and testing segmentation frameworks on a single machine or multiple machines (cluster) by utilizing nn.parallel.DistributedDataParallel
.
In this section, you will learn how to train and test these supported segmentors using the scripts provided by SSSegmentation.
Training and Testing on A Single Machine
1. Training a segmentor
We provide scripts/dist_train.sh
to launch training jobs on a single machine. The basic usage is as follows,
bash scripts/dist_train.sh ${NGPUS} ${CFGFILEPATH} [optional arguments]
This script accepts several optional arguments, including:
${NGPUS}
: The number of GPUS you want to use,${CFGFILEPATH}
: The config file path which is used to customize segmentors,--ckptspath
: Checkpoints you want to resume from, if you want to resume from the latest checkpoint in theSEGMENTOR_CFG['work_dir']
automatically, you can specify it asf'{work_dir}/epoch_last.pth'
,--slurm
: Please add--slurm
if you are using slurm to spawn training jobs.
Here, we provide some examples about training a segmentor on a single machine,
# train ANNNet
bash scripts/dist_train.sh 4 ssseg/configs/annnet/annnet_resnet50os16_ade20k.py
# load epoch_44.pth and then train ANNNet
bash scripts/dist_train.sh 4 ssseg/configs/annnet/annnet_resnet50os16_ade20k.py --ckptspath annnet_resnet50os16_ade20k/epoch_44.pth
# auto resume
bash scripts/dist_train.sh 4 ssseg/configs/annnet/annnet_resnet50os16_ade20k.py --ckptspath annnet_resnet50os16_ade20k/epoch_last.pth
The last command will be very useful if you are training your segmentors in an unstable environment, e.g., your program will be interrupted and restarted frequently.
2. Testing a segmentor
We provide scripts/dist_test.sh
to launch testing jobs on a single machine. The basic usage is as follows,
bash scripts/dist_test.sh ${NGPUS} ${CFGFILEPATH} ${CKPTSPATH} [optional arguments]
This script accepts several optional arguments, including:
${NGPUS}
: The number of GPUS you want to use,${CFGFILEPATH}
: The config file path which is used to customize segmentors,${CKPTSPATH}
: Checkpoints you want to resume from,--evalmode
: Used to specify evaluate mode, support server mode (only save the test results which could be submitted to the corresponding dataset’s official website to obtain the segmentation performance) and local mode (the default mode, test segmentors with the local images and annotations provided by the corresponding dataset),--slurm
: Please add--slurm
if you are using slurm to spawn testing jobs,--ema
: Please add--ema
if you want to load ema weights for segmentors.
Here, we provide some examples about testing a segmentor on a single machine,
# test ANNNet on ADE20k
bash scripts/dist_test.sh 4 ssseg/configs/annnet/annnet_resnet50os16_ade20k.py annnet_resnet50os16_ade20k/epoch_130.pth
# test ANNNet on Cityscapes
bash scripts/dist_test.sh 4 ssseg/configs/annnet/annnet_resnet50os16_cityscapes.py annnet_resnet50os16_cityscapes/epoch_220.pth
Training and Testing on Multiple Machines
Now, we only support training with multiple machines using Slurm, where Slurm is a good job scheduling system for computing clusters.
1. Training a segmentor
On a cluster managed by Slurm, you can use scripts/slurm_train.sh
to spawn training jobs. It supports both single-node and multi-node training. The basic usage is as follows,
bash scripts/slurm_train.sh ${PARTITION} ${JOBNAME} ${NGPUS} ${CFGFILEPATH} [optional arguments]
This script accepts several optional arguments, including:
${PARTITION}
: The Slurm partition you want to use,${JOBNAME}
: The job name you want to show,${NGPUS}
: The number of GPUS you want to use,${CFGFILEPATH}
: The config file path which is used to customize segmentors,--ckptspath
: Checkpoints you want to resume from, if you want to resume from the latest checkpoint in theSEGMENTOR_CFG['work_dir']
automatically, you can specify it asf'{work_dir}/epoch_last.pth'
,--slurm
: Please add--slurm
if you are using slurm to spawn training jobs.
Here is an example of using 16 GPUs to train PSPNet on Slurm partition named dev,
bash scripts/slurm_train.sh dev pspnet 16 ssseg/configs/pspnet/pspnet_resnet101os8_ade20k.py --slurm
Please note that, --slurm
is required to set for environment initialization if you are using slurm to spawn training jobs.
2. Testing a segmentor
Similar to the training task, SSSegmentation provides scripts/slurm_test.sh
to spawn testing jobs. The basic usage is as follows,
bash scripts/slurm_test.sh ${PARTITION} ${JOBNAME} ${NGPUS} ${CFGFILEPATH} ${CKPTSPATH} [optional arguments]
This script accepts several optional arguments, including:
${PARTITION}
: The Slurm partition you want to use,${JOBNAME}
: The job name you want to show,${NGPUS}
: The number of GPUS you want to use,${CFGFILEPATH}
: The config file path which is used to customize segmentors,${CKPTSPATH}
: Checkpoints you want to resume from,--evalmode
: Used to specify evaluate mode, support server mode (only save the test results which could be submitted to the corresponding dataset’s official website to obtain the segmentation performance) and local mode (the default mode, test segmentors with the local images and annotations provided by the corresponding dataset),--slurm
: Please add--slurm
if you are using slurm to spawn testing jobs,--ema
: Please add--ema
if you want to load ema weights for segmentors.
Here is an example of using 16 GPUs to test PSPNet on Slurm partition named dev,
bash scripts/slurm_test.sh dev pspnet 16 ssseg/configs/pspnet/pspnet_resnet101os8_ade20k.py pspnet_resnet101os8_ade20k/epoch_130.pth --slurm
Also, --slurm
is required to set for slurm environment initialization.
Inference with Segmentors Integrated in SSSegmentation
SSSegmentation provides pre-trained models for semantic segmentation in Model Zoo, and supports multiple standard datasets, including Pascal VOC, Cityscapes, ADE20K, etc. This section will show how to use existing pre-trained models to inference on given images.
Specifically, SSSegmentation provides scripts/inference.sh
to apply the trained segmentors to segment images. The basic usage is as follows,
bash scripts/inference.sh ${CFGFILEPATH} ${CKPTSPATH} [optional arguments]
This script accepts several optional arguments, including:
${CFGFILEPATH}
: The config file path which is used to customize segmentors,${CKPTSPATH}
: Checkpoints you want to resume from,--outputdir
: The directory used to save output image(s),--imagepath
: Image path, which means we let the segmentor inference on the given image,--imagedir
: Image directory, which means we let the segmentor inference on the images existed in the given image directory,--ema
: Please add--ema
if you want to load ema weights for segmentors.
Here are some example commands,
# inference on a given image
bash scripts/inference.sh ssseg/configs/pspnet/pspnet_resnet101os8_ade20k.py pspnet_resnet101os8_ade20k/epoch_130.pth --imagepath dog.jpg
# inference on given images
bash scripts/inference.sh ssseg/configs/pspnet/pspnet_resnet101os8_ade20k.py pspnet_resnet101os8_ade20k/epoch_130.pth --imagedir dogs
Please note that, if you specify --imagedir
and --imagepath
at the same time, only the value following --imagedir
will be used.
And the image format should be in [png, jpg, jpeg]
.