- Version: 20261019
- Source Code Copyright: MIT License — qfgaohao/pytorch-ssd
- Redistribution Restriction: This source code is integrated by LEADERG INC. Please use it privately. Please DO NOT distribute it to internet.
Console/terminal pipeline for object detection with MobileNetV3-SSDLite-300 (Single Shot MultiBox Detector, PyTorch), supporting Windows 11, Ubuntu Linux 24.04 and macOS 14+ (Apple Silicon). The engine (qfgaohao/pytorch-ssd) lives under src/ssd/. The example dataset steel (steel-surface defects, 4 classes: inclusion, patches, rolled_in_scale, scratches) ships with a trained checkpoint — inference works out of the box. Training starts from scratch (the notebook's setting). Training and inference run on the GPU (CUDA on Windows/Linux, MPS on Apple Silicon) and fall back to the CPU automatically; training realistically wants a GPU. Training progress is printed to the console.
[Folder Structure]
- CLAUDE.md / AGENTS.md: Program specification (identical content).
- CHANGELOG.md: Change log.
- copyright.txt: Copyright notice.
- Image-Object-Detection-MobileNetV3-SSD300-PyTorch-Python.html: This document (usage page).
- 1905.02244.pdf: MobileNets reference paper.
- data/{dataset}/labels.txt: Comma-separated class list, written by step 05, read by training.
- data/{dataset}/voc-model-labels.txt: BACKGROUND + one class per line, written by step 05 (training regenerates it), read by inference.
- data/{dataset}/train/, valid/: image/ + annotation/ (Pascal VOC XML) + train.txt/valid.txt (step 05).
- data/{dataset}/test/: image/ + annotation/ — held-out set for inference (07–09).
- model/{dataset}/: mb3-ssd-lite-Epoch-37920.pth (trained checkpoint), output/ (annotated inference results), training checkpoints.
- src/ssd/: Engine (train_ssd.py, run_ssd_example.py, inference_folder_1.py, vision/).
- src/annotation/: Bundled aiohttp annotation server (step 04).
- tool/tools.py: Shared helpers (select_device: CUDA → MPS → CPU, ...).
- src/: Wrapper entry points, launcher scripts and requirements.txt.
- venv/: Python virtual environment, created by 02_venv_create_windows.bat / 02_venv_create_linux.sh / 02_venv_create_mac.sh.
[Prerequisites]
- Python 3.14, installed by src\01_python_install_windows.bat (winget), src/01_python_install_linux.sh (apt, deadsnakes PPA when needed; uses sudo) or src/01_python_install_mac.sh (Homebrew).
- The venv scripts install PyTorch 2.13.0 + torchvision 0.28.0 first, then src/requirements.txt (numpy, Pillow, matplotlib, opencv-python, aiohttp + aiohttp-jinja2 + jinja2 for the annotation server).
- Windows / Linux: the CUDA 13.0 (cu130) build. GPU use needs an NVIDIA Turing or newer GPU (GTX 16 / RTX 20 series and later) with a driver supporting CUDA 13.0 or newer (check nvidia-smi); without one the same build runs on the CPU.
- macOS: the PyPI build, using the Apple GPU through MPS. Apple Silicon (arm64) with macOS 14+ only; Intel Macs are not supported by PyTorch 2.13.0.
[Launcher Scripts]
1. 01_python_install_windows.bat / 01_python_install_linux.sh / 01_python_install_mac.sh
Install Python 3.14 (winget / apt + deadsnakes / Homebrew). Skips when it is already installed.
2. 02_venv_create_windows.bat / 02_venv_create_linux.sh / 02_venv_create_mac.sh
Delete the old venv/, create a fresh one with Python 3.14, install PyTorch 2.13.0 + torchvision 0.28.0 (CUDA 13.0 build on Windows/Linux, PyPI/MPS build on macOS), then src/requirements.txt. Aborts loudly if pip fails; prints whether CUDA (or MPS) is available.
3. 03_venv_activate.bat / 03_venv_activate.sh
Activate the venv. On Linux/macOS, source it: source src/03_venv_activate.sh (bash or zsh). If the project folder was renamed after the venv was created, re-create the venv with 02_venv_create_windows/linux/mac first; the other launchers do not need activation.
4. 04_annotation.bat / 04_annotation.sh
Annotation web UI on port 8801 (--dataset --split train|valid|test --port).
5. 05_prepare.bat / 05_prepare.sh
Write train.txt, valid.txt, and both label files from the images and annotations.
6. 06_train.bat / 06_train.sh
Train MobileNetV3-SSDLite-300 (from scratch; CUDA → MPS → CPU; Ctrl+C to stop).
7. 07_inference.bat / 07_inference.sh
Detect in one image (default data/steel/test/image/inclusion-9.jpg, threshold 0.6).
8. 08_inference_folder.bat / 08_inference_folder.sh
Detect in every image of a folder (default the test split, threshold 0.5).
9. 09_inference_folder_1.bat / 09_inference_folder_1.sh
Folder inference with statistics: underkill/overkill/right rates from the file-name prefixes (e.g. inclusion-9.jpg → inclusion).
10. 99_venv_clean.bat / 99_venv_clean.sh
Delete the venv/ folder.
11. 99_venv_deactivate.bat / 99_venv_deactivate.sh
Deactivate the venv in the current shell. On Linux/macOS, source it: source src/99_venv_deactivate.sh (bash or zsh).
Extra arguments are forwarded to the Python entry point, e.g. src\07_inference.bat --device cpu.
[Python Entry Points]
src/annotation_server.py
--dataset steel --split train|valid|test --port 8801 [--no-browser]. Bundled Pascal-VOC-XML annotation UI; writes XML into data/{dataset}/{split}/annotation/.
src/prepare.py
--dataset steel. Writes the image lists, labels.txt (comma-separated, read by training), and voc-model-labels.txt (BACKGROUND + one class per line, read by inference).
src/train.py
--dataset steel --epochs 200000 --batch-size 8 --learning-rate 0.01 --validation-epochs 20 --debug-steps 20 --workers 0 --device auto [--pretrained PTH] [--resume PTH]. Trains from scratch unless --resume (e.g. the shipped model/{dataset}/mb3-ssd-lite-Epoch-37920.pth) or --pretrained is given. Saves mb3-ssd-lite-Epoch-{N}-Loss-{L}.pth at every validation into model/{dataset}/. Progress (running loss, one train-loss line per epoch, validation loss) is printed to the console. --workers > 0 works on every OS, but 0 is faster for small datasets on Windows/macOS. Keep --batch-size at most the number of validation images (8 in steel). Stop with Ctrl+C whenever the validation loss is good enough.
src/inference.py
--dataset steel [--source IMAGE] [--weights PTH] [--threshold 0.6] [--device auto] [--show]. Annotated image lands in model/{dataset}/output/.
src/inference_folder.py
--dataset steel [--source FOLDER] [--weights PTH] [--threshold 0.5] [--stats] [--device auto] [--show]. With --stats, prints the underkill/overkill/right rates.
--device: auto (default) picks CUDA → MPS → CPU; cuda, cuda:N, mps or cpu forces a device. The selected device is printed at startup.
[Quick Start]
Windows 11
src\01_python_install_windows.bat
src\02_venv_create_windows.bat
src\07_inference.bat
src\06_train.bat (GPU machine)
Ubuntu 24.04
bash src/01_python_install_linux.sh
bash src/02_venv_create_linux.sh
bash src/07_inference.sh
bash src/06_train.sh (GPU machine)
macOS 14+ (Apple Silicon)
bash src/01_python_install_mac.sh
bash src/02_venv_create_mac.sh
bash src/07_inference.sh
bash src/06_train.sh
Full workflow for your own data: 04_annotation (label train + valid) → 05_prepare → 06_train (stop with Ctrl+C) → 07–09 inference with --weights model/{dataset}/mb3-ssd-lite-Epoch-{N}-Loss-{L}.pth.
[GPU]
- Device order: CUDA → MPS → CPU, overridable with --device.
- Windows / Linux: the venv scripts install the CUDA 13.0 (cu130) build directly. It needs a Turing-or-newer NVIDIA GPU and a driver supporting CUDA 13.0+. Pascal/Volta GPUs (GTX 10xx, V100) are not supported by cu130; on those, reinstall torch from the cu126 index inside the venv: pip install torch==2.13.0 torchvision==0.28.0 --index-url https://download.pytorch.org/whl/cu126 --force-reinstall
- macOS (Apple Silicon): the network runs on the Apple GPU through MPS; ops MPS lacks fall back to the CPU (PYTORCH_ENABLE_MPS_FALLBACK=1 is set by the entry scripts).
- Without a usable GPU everything runs on the CPU (inference is fast; training is very slow). Checkpoints load on any device.
[References]
- MobileNetV3 paper (Howard et al. 2019, shipped as 1905.02244.pdf): arxiv.org/abs/1905.02244
- MobileNetV3-SSD (referenced by the original readme): github.com/shaoshengsong/MobileNetV3-SSD, Compact-Version
- MobileNetV3 implementations (referenced by the original readme): xiaolai-sqlai/mobilenetv3, kuan-wang/pytorch-mobilenet-v3
- SSD paper (Liu et al. 2016): arxiv.org/abs/1512.02325
- pytorch-ssd (engine base): github.com/qfgaohao/pytorch-ssd
- PyTorch install: pytorch.org/get-started/locally
- PyTorch MPS backend: docs.pytorch.org/docs/stable/notes/mps.html
This SDK is built in AppForAI - AI Dev Tools.