Crack Detection System · 裂缝智能检测系统

English | 中文

An intelligent desktop application for automatic concrete crack detection based on deep learning, integrating U-Net + Attention Gate and YOLOv8-seg dual models with automatic crack length & width measurement.

---

✨ Highlights

• Dual-model parallel detection — run U-Net and YOLOv8 side-by-side with one click and compare results directly
• Crack geometry measurement — automatic skeleton extraction (Zhang-Suen) + distance transform (EDT) for pixel-level length and width, convertible to physical dimensions with a known scale
• Modern flat UI — drag & drop image upload, background-thread inference (no UI freeze), GPU acceleration (auto CUDA detection)
• Dual evaluation modes — single-image GT evaluation and batch test-set assessment

---

Features

Feature	U-Net + Attention	YOLOv8-seg
Detection type	Pixel-level semantic segmentation	Instance segmentation + detection box
Output	Probability heatmap + overlay + area ratio	Boxes + masks + count + confidence
Geometry	Crack length + mean/max width (px)	Total length + mean/max width (px)
Best for	Fine measurement & area assessment	Fast localization, statistics & measurement

---

Model Technical Details

U-Net + Attention Gate

Encoder–decoder architecture with Attention Gates on the skip connections to suppress irrelevant background and focus on crack regions.

Level	Encoder	Decoder
Layer 1	DoubleConv(3→64) + MaxPool	ConvTranspose(128→64) + AttentionGate + DoubleConv(128→64)
Layer 2	DoubleConv(64→128) + MaxPool	ConvTranspose(256→128) + AttentionGate + DoubleConv(256→128)
Layer 3	DoubleConv(128→256) + MaxPool	ConvTranspose(512→256) + AttentionGate + DoubleConv(512→256)
Layer 4	DoubleConv(256→512) + MaxPool	ConvTranspose(1024→512) + AttentionGate + DoubleConv(1024→512)
Bottleneck	DoubleConv(512→1024)	—
Output	—	Conv2d(64→1, k=1)

• DoubleConv: Conv2d(k=3) → BatchNorm2d → ReLU → Conv2d(k=3) → BatchNorm2d → ReLU, spatial size preserved
• Downsampling: MaxPool (k=2, s=2) — spatial size halved, channels doubled
• Upsampling: ConvTranspose (k=2, s=2) — spatial size doubled, channels halved

Attention Gate mechanism: takes two inputs — encoder skip feature $x_l$ (gated) and decoder upsampled feature $g$ (gate signal):

1. $W_g(g) + W_x(x_l)$ — 1×1 conv projections to $\mathbb{R}^{F_{int}}$, element-wise addition
2. ReLU → 1×1 conv reduction → BatchNorm → Sigmoid, producing spatial attention map $\alpha \in [0,1]^{H \times W}$
3. Output $\hat{x}_l = x_l \odot \alpha$ — element-wise reweighting of skip features

Training config:

Item	Config
Input size	256 × 256
Loss	$\mathcal{L} = 0.5 \cdot \text{BCEWithLogitsLoss} + 0.5 \cdot (1 - \text{Dice})$
Optimizer	Adam, lr = 5×10⁻⁴, weight decay = 1×10⁻⁵
LR schedule	ReduceLROnPlateau, mode='min', factor=0.5, patience=10
Batch size	16
Epochs	20 (Early Stopping patience=5)
Augmentation	Random rotation (90°/180°/270°) + horizontal flip + brightness/contrast (0.8~1.2)

Composite loss: BCEWithLogitsLoss provides stable per-pixel gradients; Dice Loss directly optimizes region overlap. A 0.5/0.5 weighting balances convergence stability and region completeness.

YOLOv8-seg

YOLOv8s-seg (small variant) — adds an instance segmentation head to the YOLOv8 detector, outputting both boxes and instance masks. Fine-tuned from COCO-pretrained weights via the Ultralytics framework.

Spec	Detail
Params	~11.7M
Input size	640 × 640
Backbone	CSPDarkNet (CSP bottleneck + C2f)
Neck	PAN-FPN
Head	Decoupled detection head + mask proto head

Losses: multi-task composite, end-to-end joint optimization:

Component	Formula	Role
Box Loss	CIoU	Box regression considering overlap, center distance, aspect ratio
DFL Loss	Distribution Focal Loss	Boundary coordinates as discrete distribution, refined localization
Cls Loss	BCEWithLogitsLoss	Class classification (single class: crack)
Seg Loss	BCEWithLogitsLoss	Per-pixel binary classification between mask prototypes and GT

Training config:

Item	Config
Pretrained weights	yolov8s-seg.pt (COCO)
Input size	640 × 640
Loss	CIoU + DFL + BCE (Cls) + BCE (Seg)
Optimizer	SGD (momentum), Ultralytics defaults
LR schedule	Cosine Annealing + Warmup (3 epochs linear ramp-up)
Batch size	8
Epochs	10
Augmentation	Mosaic + MixUp + random affine (Ultralytics built-in)

Model Comparison

Dimension	U-Net + Attention	YOLOv8s-seg
Task	Semantic segmentation (pixel binary)	Instance segmentation (detect + mask)
Backbone	Hand-designed CNN encoder	CSPDarkNet (C2f)
Key mechanism	Attention Gate spatial attention	PAN-FPN multi-scale fusion
Params	~31M	~11.7M
Resolution	256×256	640×640
Loss	BCE + Dice (1:1)	CIoU + DFL + BCE (Cls) + BCE (Seg)
Optimizer	Adam (lr=5e-4)	SGD + Momentum
LR schedule	ReduceLROnPlateau	Cosine Annealing + Warmup
Strength	Precise pixel-level contours, area assessment	Multi-instance + fast inference, statistics & localization

---

System Requirements

Item	Minimum	Recommended
OS	Windows 10	Windows 10/11
RAM	8 GB	16 GB
GPU	None (CPU works)	NVIDIA GPU (CUDA)
Disk	2 GB	5 GB

---

Installation

Option A: Build the EXE from source

# 1. Install dependencies
pip install -r requirements_gui.txt

# 2. Install PyInstaller
pip install pyinstaller

# 3. Run the build script (double-click)
build_exe.bat

# 4. Output: dist\CrackDetection\

Option B: Run from source (developers)

# 1. Clone the repository
git clone https://github.com/YangKe-Lab/crack-detection.git
cd crack-detection

# 2. Install dependencies
pip install -r requirements_gui.txt

# 3. Train the U-Net model or provide your own weights (see below)

# 4. Launch the app
python crack_gui.py

Model Weights

Model	Weights	Status
U-Net + Attention	best_model.pth	Not included — train your own with crack-detection-unet-master/train.py, or place an existing weight file in crack-detection-unet-master/output_results/
YOLOv8-seg	best.pt / last.pt	Included in the repo (yolov8-crack/model/)

---

Usage

1. Launch

Double-click CrackDetection.exe or run python crack_gui.py.

2. Upload image

• Click the upload area (dashed box) to select an image
• Or drag & drop JPG/PNG/BMP files onto it
• Any resolution is supported; models preprocess automatically

3. Adjust parameters

Parameter	Model	Description	Default
Binarization threshold	U-Net	Lower → more crack pixels	0.5
Morphological denoising	U-Net	Median filter	On
Confidence threshold	YOLOv8	Detection confidence filter	0.25

4. Run detection

Click "Start Detection (U-Net + YOLOv8)" — both models run sequentially, with a progress bar showing the current stage.

5. View results

Results are displayed side-by-side, with four stat cards below:

• U-Net performance: FPS / inference time / total time
• U-Net defect features: area ratio / pixel count / length / mean width / max width
• YOLOv8 performance: FPS / inference time / total time
• YOLOv8 defect features: crack count / mean confidence / total length / mean width / max width

Length and width are measured in pixel space via Zhang-Suen skeletonization + distance transform. With a known calibration ratio (px/mm), convert to physical dimensions manually.

6. Export results

Click "Export" to save U-Net or YOLOv8 result images (PNG/JPEG).

---

Project Structure

crack-detection/
├── crack_gui.py                       # Desktop app main program (PyQt5)
├── inference_engine.py                # Unified inference engine + crack geometry measurement
├── crack_gui.spec                     # PyInstaller packaging config
├── CrackDetection.spec                # PyInstaller packaging config (backup)
├── build_exe.bat                      # One-click build script
├── requirements_gui.txt               # Python dependencies
├── README.md / README_zh.md           # Documentation
├── 插图/                              # Image assets
│   └── 示例图.png                     #   UI screenshot
│
├── crack-detection-unet-master/       # U-Net + Attention model
│   ├── unet_model.py                  #   Model definition (UNet + DoubleConv)
│   ├── dataset.py                     #   Dataset + AttentionGate
│   ├── train.py                       #   Training script
│   ├── predict.py                     #   CLI inference script
│   └── output_results/
│       └── best_model.pth             #   Trained weights (not included; train with train.py)
│
└── yolov8-crack/                      # YOLOv8-seg model
    ├── train.py                       #   Training script
    ├── predict.py                     #   CLI inference script
    ├── crack_ui.py                    #   Gradio web UI
    └── model/
        ├── best.pt                    #   Best weights
        └── last.pt                    #   Final weights

---

Crack Geometry Measurement

Step	Method	Description
Skeleton extraction	Zhang-Suen fast parallel thinning	Thin the binary crack mask to a single-pixel centerline
Length	Skeleton pixel count + scale	Total skeleton pixels = crack length
Width	Distance transform (EDT)	Euclidean distance of each crack pixel to nearest background; 2× distance on skeleton = local width

• U-Net: measured at 256×256 working resolution, then scaled to the original image size
• YOLOv8: measured per instance mask, aggregated into total length and mean width
• Unit defaults to pixels; convert manually if a physical calibration ratio is known

---

FAQ

Q: Missing DLL on startup? A: Install the Visual C++ Redistributable.

Q: Slow detection? A: Check the title bar for "GPU (CUDA)". If it shows "CPU", install CUDA and the GPU version of PyTorch.

Q: U-Net area ratio too small despite a large crack? A: Lower the binarization threshold (e.g. 0.3) or disable morphological denoising.

Q: YOLOv8 misses cracks? A: Lower the confidence threshold (e.g. 0.15), or ensure the image is sharp and evenly lit.

Q: What unit are length and width in? A: Pixels (px) by default. With a calibration ratio (e.g. 1mm = 10px), divide pixel values by the ratio to get physical dimensions.

Q: Packaged EXE won't run? A: Make sure the whole dist/CrackDetection folder is copied — don't move the .exe alone.

---

Dependencies

Package	Version	Purpose
PyQt5	>=5.15	Desktop GUI framework
torch	>=1.10	Deep learning inference
torchvision	>=0.11	Image preprocessing
ultralytics	>=8.0	YOLOv8 models
opencv-python	>=4.7	Image processing
scipy	>=1.7	Distance transform & Hungarian matching
numpy	>=1.24	Numerical computing
Pillow	>=9.0	Image loading

---

Changelog

2026.5.20

• Crack geometry measurement: Zhang-Suen skeletonization + distance transform for pixel-level length, mean & max width (both U-Net and YOLOv8)
• Dual-model parallel detection: one click runs both models, results compared side-by-side
• UI refactor: side-by-side result panels with four stat cards (U-Net + YOLOv8 performance/features)
• New DualInferenceWorker: sequential dual-model inference with real-time progress bar
• Fixes: removed duplicate CrackDetectionEngine class definition; fixed stat_labels key conflict
• Dependencies: added scipy (distance_transform_edt, linear_sum_assignment)

---

License

MIT © 2026 Ke Yang (杨珂)