xdu-jjgs / rsi-semantic-segmentation

A unified PyTorch framework for semantic segmentation from remote sensing imagery.

Remote Sensing Imagery Semantic Segmentation

Read this in other languages: English | 简体中文

Table of Contents

• Project Structure
• Prerequisites
• Configurations
  • Configuration Name Format
• Supported Datasets
• Supported Models
• Usage
  • Train
  • Test
  • Inference
• License

Project Structure

rsi-semantic-segmentation
  |---- configs
  |       |---- __init__.py
  |       |---- gf2-building_deeplabv3-resnet50_ce_adam_plateau_8_0.001_40.yaml
  |       |---- massachusetts-building_deeplabv3-resnet50_dice_adam_plateau_8_0.001_40.yaml
  |
  |---- criterions
  |       |---- __init__.py
  |       |---- bce.py
  |       |---- ce.py
  |       |---- dice.py
  |
  |---- datas
  |       |---- __init__.py
  |       |---- base.py
  |       |---- gf2_building.py
  |       |---- massachusetts_building.py
  |       |---- transform.py
  |
  |---- models
  |       |---- decoders
  |       |       |---- __init__.py
  |       |       |---- deeplabv3.py
  |       |
  |       |---- encoders
  |       |       |---- __init__.py
  |       |       |---- resnet.py
  |       |
  |       |---- modules
  |       |       |---- __init__.py
  |       |       |---- aspp.py
  |       |
  |       |---- utils
  |       |       |---- init.py
  |       |
  |       |---- __init__.py
  |       |---- deeplabv3.py
  |
  |---- optimizers
  |       |---- __init__.py
  |
  |---- schedulers
  |       |---- __init__.py
  |
  |---- tools
  |       |---- datasets
  |               |---- massachusetts_building
  |                       |---- patch.py
  |
  |---- .gitignore
  |---- inference.py
  |---- LICENSE
  |---- metric.py
  |---- README.md
  |---- README_zh-CN.md
  |---- requirements.txt
  |---- test.py
  |---- train.py

Prerequisites

• NumPy for multi-dimensional data representation on CPU
• Pandas for parsing .csv files
• scikit-image for reading, writing and showing images
• tensorboardX for logging to TensorBoard
• timm for computer vision backbones in PyTorch
• PyTorch for neural network representation and calculation
• TorchVision for basic components applied in computer vision
• tqdm for drawing progress bar
• yacs for parsing .yaml configuration files

All these Python third-party packages can be easily installed through pip:

$ pip install numpy pandas scikit-image tensorboardX timm torch torchvision tqdm yacs

Configurations

dataset	method	criterion	optimizer	scheduler	batch size	LR	epochs	config
gf2-building	deeplabv3-resnet50	ce	adam	plateau	8	0.001	10	config
massachusetts-building	deeplabv3-resnet50	dice	adam	plateau	8	0.001	40	config

Configuration Name Format

{dataset}_{method}_{criterion}_{optimizer}_{scheduler}_{batch size}_{lr}_{epochs}.yaml

• {dataset}: dataset name like massachusetts-building, massachusetts-road, etc.
• {method}: method name like deeplabv3+resnet50, deeplabv3+resnet101, etc.
• {criterion}: criterion name like ce, bce, etc.
• {optimizer}: optimizer name like sgd, adam, etc.
• {scheduler}: scheduler name like poly, plateau, etc.
• {batch size}: batch size during training, e.g. 4, 8.
• {lr}: basic learning rate for training, e.g. 0.01, 0.001.
• {epochs}: epochs for training, e.g. 20, 40.

Supported Datasets

• GF2 Building
• Massachusetts Building

Supported Models

• DeepLabV3 (ArXiv'2017)

Usage

Train

$ python train.py configs/massachusetts-building_deeplabv3-resnet50_dice_adam_plateau_8_0.001_40.yaml \
                  --checkpoint ./best.pth \
                  --path ./runs/20211206-201700/ \
                  --no-validate \
                  --nodes 1 \
                  --gpus 1 \
                  --rank-node 0 \
                  --backend nccl \
                  --master-ip localhost \
                  --master-port 8888 \
                  --seed 42 \
                  --opt-level O0

• config: Configuration to be used, which must be specified.
• --checkpoint: Checkpoint to be loaded. Default: train from scratch.
• --path: Directory to save experiment output files. Default: a directory named by current time.
• --no-validate: Whether not to validate on the validation set during training. Default: do validation.
• -n / --nodes: Number of nodes / machines, should be 1 when training on a single machine. Default: 1.
• -g / --gpus: Number of GPUs per node / machine. Default: 1.
• -r / --rank-node: Ranking of the current node / machine, should be in range of 0 ~ nodes-1. Default: 0.
• --backend: Backend for PyTorch DDP. Default: nccl.
• --master-ip: Network IP of the master node / machine. Default: localhost.
• --master-port: Network port of the master process on the master node / machine. Default: 8888.
• --seed: Random seed. Default: 42.
• --opt-level: Optimizing level for nvidia/apex. Default: O0.

Test

$ python test.py configs/massachusetts-building_deeplabv3-resnet50_dice_adam_plateau_8_0.001_40.yaml \
                 ./best.pth \
                 --device cuda:0

• config: configuration to be used, which must be specified.
• checkpoint: Checkpoint to be loaded, which must be specified.
• --device: Device for testing, could be either CPU or GPU. Default: GPU #0.

Inference

$ python inference.py configs/massachusetts-building_deeplabv3-resnet50_dice_adam_plateau_8_0.001_40.yaml \
                      ./best.pth \
                      ./22828930_15.tif \
                      --output ./output.tif \
                      --device cuda:0 \
                      --no-show \
                      --no-save

• config: configuration to be used, which must be specified.
• checkpoint: Checkpoint to be loaded, which must be specified.
• input: Input image, which must be specified.
• --output: Output segmentation map. Default: output.tif
• --device: Device for inferring, could be either CPU or GPU. Default: GPU #0.
• --no-show: Whether not to show segmentation results. Default: do showing.
• --no-save: Whether not to save segmentation results. Default: do saving.

License

This project is released under the MIT license.