CascadePSP Documentation

The testing script requires a specific directory structure for input images, ground-truth masks, and predicted segmentations. Each image in the test set must have a corresponding ground-truth and segmentation file following these naming conventions:

• imagename_gt.png: Ground-truth segmentation.
• imagename_seg.png: Input segmentation (should be in binary format, i.e., one object at a time).
• imagename_im.jpg: The original RGB image.

All files for a single sample should reside in the same testset_directory.

+ testset_directory
  - imagename_gt.png
  - imagename_seg.png
  - imagename_im.jpg

Use the segmentation_refinement.Refiner class to perform high-resolution segmentation refinement. You can specify the computation device (e.g., 'cuda:0' or 'cpu') during initialization. The .refine() method takes an input image and an existing mask to produce a refined output.

import cv2
import segmentation_refinement as refine

image = cv2.imread('test/aeroplane.jpg')
mask = cv2.imread('test/aeroplane.png', cv2.IMREAD_GRAYSCALE)

# Initialize the refiner on a specific device
refiner = refine.Refiner(device='cuda:0')

# Perform refinement
# fast=False enables both Global and Local steps
# L controls the scale/resolution (smaller L uses less memory and is faster)
output = refiner.refine(image, mask, fast=False, L=900)

cv2.imwrite('output.png', output)

To refine low-resolution segmentations while skipping the Local step, use the --global_only flag. Note that using both steps does not deteriorate results, but this mode is useful for specific low-resolution use cases.

# From CascadePSP/
python eval.py \
    --dir testset_directory \
    --model model_name \
    --output output_directory \
    --global_only

Start training by executing train.py from the CascadePSP/ root directory. You must provide a unique identifier for the training session.

You can customize training by passing arguments, such as changing the batch size with the -b flag. For a full list of available hyperparameter options, refer to util/hyper_para.py.

# From CascadePSP/
# Basic training with a unique ID
python train.py some_unique_id

# Training with a specific batch size (e.g., 10)
python train.py -b 10 some_unique_id

CascadePSP requires PyTorch (tested on version 1.0) and several other dependencies. It is recommended to use the Anaconda distribution to manage these dependencies.

To install the specific required packages, use the following commands:

• progressbar2 via pip
• cv2 via conda
• tensorboard for logging purposes.

pip install progressbar2
conda install cv2

The Refiner class is used to refine binary input segmentations of an image. It automatically downloads pre-trained models upon initialization. You can specify the computation device (e.g., 'cuda:0' or 'cpu').

To perform refinement, use the .refine() method which accepts an image and its corresponding binary mask.

import cv2
import segmentation_refinement as refine

image = cv2.imread('test/aeroplane.jpg')
mask = cv2.imread('test/aeroplane.png', cv2.IMREAD_GRAYSCALE)

# Initialize the refiner
refiner = refine.Refiner(device='cuda:0')

# Refine the mask
output = refiner.refine(image, mask, fast=False, L=900)

Testing on scene parsing datasets requires a multi-step pipeline to handle the complexity of scene-level segmentation. The process involves obtaining initial segmentations, breaking the scene into individual components, processing those components with CascadePSP, and finally recombining them.

The Pipeline Workflow:

1. Obtain initial segmentations: Use segmentations from other models.
2. Component Breakdown: Break the scene parse into individual components (as described in the CascadePSP paper).
3. Component Processing: Run CascadePSP on each individual component.
4. Recombination: Combine the processed components into a final scene parse.

Shortcut: You can skip steps 1 and 2 by using the pre-processed dataset provided in the repository's dataset.md documentation.

To evaluate the accuracy of your segmentation results using metrics like IoU (Intersection over Union) and mBA, run the eval_post.py script pointing to your output directory.

# From CascadePSP/
python eval_post.py \
    --dir output_directory

You can install the package via pip or by installing the local repository in editable mode.

# Via pip
pip install segmentation-refinement

# Or locally
pip install -e .

CascadePSP provides two main model checkpoints for segmentation tasks. Depending on your requirements, you can choose between the original model used in the research paper or the newly trained version optimized for the current repository structure.

Both checkpoints are approximately 259MB in size.

Use the provided script to download and merge the MSRA-10K, DUT-OMRON, ECSSD, and FSS-1000 datasets. Run this script from the CascadePSP/scripts/ directory.

The script creates a CascadePSP/data/ directory with the following structure:

• DUTS-TE/
• DUTS-TR/
• ecssd/
• fss/ (organized by class_name/)
• MSRA_10K/

# From CascadePSP/scripts/
python download_training_dataset.py

The BIG dataset is a high-resolution segmentation dataset hand-annotated for evaluation. It contains 50 validation objects and 100 test objects with resolutions ranging from 2048x1600 to 5000x3600.

Note: Images are collected from Flickr; please do not use this dataset for commercial purposes. The authors do not hold the license for the RGB images.

Download Links:

• Google Drive
• Google Drive (Backup)