Binary semantic segmentation pipeline built on PyTorch Lightning and segmentation_models_pytorch. Covers dataset preparation, training, ONNX export, and inference.
The model architecture is configurable: any encoder-decoder combination supported by segmentation_models_pytorch (UNet, FPN, DeepLabV3+, etc.) can be selected from configs/config.yaml without touching the code.
segmentation-pytorch/
configs/
config.yaml # all settings (model, training, data paths, augmentation)
scripts/
train.py # training entrypoint
predict.py # PyTorch inference (batch or single image)
split_dataset.py # manual dataset split (optional)
onnx/
convert_to_onnx.py # export trained model to ONNX
onnx_predict.py # ONNX inference
src/segmentation/
models/unet.py # LightningModule (model, loss, metrics, optimizer)
data/dataset.py # PyTorch Dataset
data/datamodule.py # LightningDataModule (loaders, augmentation)
utils/dataset_utils.py # split logic, config loading, augmentation preview
utils/utils.py # model loading helper for inference
Requires Python 3.11 or 3.12.
Python 3.14 is not currently supported by this repository because some pinned dependencies do not reliably provide prebuilt wheels for it on Windows.
git clone <repo-url>
cd segmentation-pytorch
py -3.11 -m venv .venv
.venv\Scripts\activate
python -m pip install --upgrade pip
pip install -r requirements.txtrequirements.txt is configured to install PyTorch wheels for CUDA 11.8 directly from the official PyTorch package index, so pip install -r requirements.txt is enough on a compatible machine.
If you need CPU-only PyTorch or a different CUDA version, update the first line of requirements.txt and the pinned torch / torchvision / torchaudio versions accordingly.
Everything is driven by configs/config.yaml. The shipped config contains absolute paths that you must update to match your machine.
model:
input_size: [512, 512] # resize dimensions (height, width)
architecture: fpn # any smp architecture: unet, fpn, deeplabv3plus, ...
backbone: resnet34 # any timm / smp encoder: resnet34, efficientnet-b0, ...
in_channels: 3 # input channels (3 for RGB)
out_classes: 1 # output classes (1 for binary segmentation)training:
epochs: 550
batch_size: 1
lr: 0.001
num_workers: 2data:
splits_dir: path/to/dataset_creation # folder with train/, val/, test/
images_dir: path/to/raw_dataset/images # only for initial split
masks_dir: path/to/raw_dataset/masks # only for initial split
split_ratios:
train: 0.7
val: 0.15
test: 0.15images_dir and masks_dir are only used by the split step. Once the splits exist, only splits_dir matters.
output:
checkpoint_dir: checkpoints/
checkpoint_name: best_model
monitor: valid_loss
save_top_k: 1
mode: mininference:
model_path: checkpoints/best_model.ckpt
input_images_dir: path/to/your/test/images
outputs_dir: outputs
threshold: 0.5
resize_strategy: resize_then_thresholdresize_strategy controls how the final binary mask is produced:
resize_then_threshold: resizes probabilities first and thresholds afterwards. This is the recommended default because it minimizes stair-step artifacts on mask borders.threshold_then_resize: thresholds at model resolution first and then upsamples the binary mask with nearest-neighbour. This intentionally produces more pixelated edges.
The augmentation pipeline is defined declaratively in the config using Albumentations transform names. Transforms are applied in order; OneOf and nested Compose blocks are supported.
augmentation:
- name: HorizontalFlip
p: 0.9
- name: OneOf
transforms:
- name: RandomBrightnessContrast
p: 0.6
- name: RandomGamma
p: 0.4
p: 0.8
- name: Blur
p: 0.5
- name: GridDropout
p: 0.2
ratio: 0.3
unit_size_range: [10, 20]
fill: random_uniformAny Albumentations transform can be added by name with its parameters. See the comments inside config.yaml for more examples.
Set show_augmentation_samples: true in the config to display a visual preview of augmented image/mask pairs before training starts.
After splitting, the data directory should look like this:
splits_dir/
train/
images/
masks/
val/
images/
masks/
test/
images/
masks/
Mask filenames must match the corresponding image filenames. All images are expected to be .png.
Splitting is performed automatically the first time you run scripts/train.py (if the split folders don't exist yet).
You can also split manually:
python scripts/split_dataset.pyThe ratios and paths are read from config.yaml.
python scripts/train.pyThe script reads configs/config.yaml, splits the dataset if needed, optionally shows augmentation samples, and starts training. The best checkpoint is saved according to the output section of the config.
Ground-truth masks are resized with nearest-neighbour interpolation to preserve binary labels during training. If a checkpoint was trained before this fix, retraining is recommended to get the full benefit.
Exports the trained model to ONNX with a fixed spatial resolution (from model.input_size) and dynamic batch size:
python onnx/convert_to_onnx.pyThe checkpoint path is read from inference.model_path in the config. The output .onnx file is saved under onnx/.
# batch: process all images in the configured input_images_dir
python scripts/predict.py
# single image
python scripts/predict.py --mode single --image "path/to/image.png"Both modes read inference.model_path, inference.input_images_dir, and inference.outputs_dir from the config. You can override the config path with --config path/to/other_config.yaml.
PyTorch inference restores the prediction to the original image size before saving. The final mask behavior is controlled by inference.threshold and inference.resize_strategy.
python onnx/onnx_predict.py --onnx_model onnx/model.onnxOptional arguments:
| Flag | Default | Description |
|---|---|---|
--config |
../configs/config.yaml |
Path to config file |
--onnx_model |
unet_resnet34.onnx |
Path to the .onnx model |
--images_dir |
from config | Override input images directory |
--outputs_dir |
./onnx_outputs |
Output directory |
ONNX inference uses the same post-processing logic as PyTorch inference and writes masks at the original image resolution.
- Mask filenames must match image filenames exactly.
- The DataModule loads data directly from the split folders, not from
.txtfile lists. - The split logic in
src/segmentation/utils/dataset_utils.pyis reusable outside the training script.
For questions or issues, open an issue on the repository.