GT-CrackSeg

A Modular PyTorch Framework for Crack Segmentation Research

News

• [2025-12-30] Check out our comprehensive review paper Deep Learning for Crack Detection: A Review of Learning Paradigms, Generalizability, and Datasets
• [2025-12-30] Our curated cracking paper list Awesome-Crack-Detection
• [2025-12-30] 📢 We released the first version of GT-CrackSeg!

Features

• Predefined models, losses, and training settings ready to run
• Supports popular architectures such as ResUNet, DeepLabV3, and SegFormer
• Multi-GPU training support with PyTorch DistributedDataParallel
• Built-in training with validation, checkpointing, and performance metrics

Installation

# Create the 'crackseg' environment
conda env create -f environment.yml

# Activate the environment
conda activate crackseg

Usage

# All arguments are optional
# The default model is DeepLabV3, the DeepCrack dataset, and the Dice loss function

python -m main [-c MODEL_CONFIG] [--dataset DATASET] [--loss LOSS]

Examples

# Run with the default arguments
python -m main

# Train ResUNet on DeepCrack
python -m main -c resunet.yml --dataset deepcrack

# Train DeepLabV3 on CrackTree with Dice loss
python -m main -c deeplabv3.yml --dataset cracktree --loss dice

Multi-GPU training

We support multi-GPU training via torchrun and PyTorch DistributedDataParallel

# 4 GPUs on a single node
torchrun --nproc_per_node=4 main.py -c cracksam.yml --dataset khanhha

Supported Models

Each model includes a standalone configuration file defining its architecture and training settings

Model	Config
ResUNet	resunet.yml
DeepLabV3	deeplabv3.yml
SegFormer	segformer.yml
DPT	dpt.yml
CrackFormerII	crackformerii.yml
SCSegamba	scsegamba.yml
CrackSAM	cracksam.yml

Datasets

Supported Datasets

This framework is compatible with the following crack segmentation benchmark datasets.

Download: Google Drive (all datasets)

• Please follow each dataset's original license/terms.
• After downloading, unzip into data/ so paths match the structure below.

Dataset	Example Usage
DeepCrack	--dataset deepcrack
TUT	--dataset tut
Khanhha	--dataset khanhha
CrackTree	--dataset cracktree

Select a dataset using the --dataset flag:

python -m main -c resunet.yml --dataset deepcrack

Dataset Structure

Datasets should follow this directory layout:

data/{dataset_name}/
├── Train/
│   ├── img/      # input images
│   └── anno/     # binary masks
├── Val/
│   ├── img/
│   └── anno/
└── Test/
    ├── img/
    └── anno/

• For more details, see the Dataset Guide

Program Output

When you run training, CrackSeg automatically creates an organized output directory:

logs/{model_name}_{dataset_name}/{timestamp}/
├── training.log              # Complete training logs with metrics per epoch
├── best_{model_name}.pth     # Best model checkpoint (highest validation Dice score)
└── img/                      # Visualization outputs (if save_img=True)
    ├── {image_name}_input.jpg    # Original input image
    ├── {image_name}_gt.jpg       # Ground truth mask
    └── {image_name}_pred.jpg     # Predicted mask (white=correct, red=false positive, blue=false negative)

Training Progress:

• Validation metrics printed at specified intervals
• Automatic best model checkpointing based on Dice score

Metrics Reported:

• Dice Score: Harmonic mean of precision and recall (primary metric)
• Precision: Accuracy of predicted crack pixels
• Recall: Coverage of actual crack pixels
• IoU (Intersection over Union): Overlap between prediction and ground truth
• ODS (Optimal Dataset Scale): F1-score at the optimal threshold for the entire dataset
• OIS (Optimal Image Scale): Average of per-image optimal F1-scores

Example Multiscale Prediction

Multiscale models generate side predictions and a final fused output from the original input, shown here alongside the labeled test image used as the ground truth for comparison

Release History

• 0.1
  • Initial public release

License

See LICENSE for more information