• 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]

 

This SDK is built in AppForAI - AI Dev Tools.