- Version: 20261019
- Source Code Copyright: MIT License — lufficc/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 VGG16-SSD512 (Single Shot MultiBox Detector, 512x512 input, PyTorch), supporting Windows 11, Ubuntu Linux 24.04 and macOS 14+ (Apple Silicon). The engine (lufficc/SSD) lives under src/lufficc/ and is driven by a per-dataset YAML config (data/{dataset}/vgg_ssd512.yaml, yacs format). The example dataset steel (steel-surface defects, 4 classes: inclusion, patches, rolled_in_scale, scratches) ships with a trained checkpoint (iteration 7000) and the VGG16 base weights — inference works out of the box, on the CPU too. Training resumes from that checkpoint and realistically wants a GPU; its progress (losses, learning rate, periodic mAP) is printed to the console.
GPU: training, the periodic evaluation and inference run on an NVIDIA GPU (CUDA) on Windows and Linux and on the Apple GPU (MPS) on macOS, with automatic CPU fallback (--device auto: CUDA → MPS → CPU; the selected device is printed at startup).
[Folder Structure]
- CLAUDE.md / AGENTS.md: Program specification (identical content).
- CHANGELOG.md: Change log.
- copyright.txt: Copyright notice.
- Image-Object-Detection-VGG16-SSD512-PyTorch-Python.html: This document (usage page).
- 1512.02325.pdf: SSD reference paper.
- data/{dataset}/labels.txt: __background__ + one class per line (hand-maintained).
- data/{dataset}/vgg_ssd512.yaml: Per-dataset training/inference config (yacs: network, MAX_ITER, batch size, learning rate, OUTPUT_DIR).
- data/{dataset}/train/, val/: images/ + annotations/ (Pascal VOC XML) + train.txt/val.txt (step 05, one file name per line).
- data/{dataset}/test/: images/ + annotations/ — held-out set.
- model/{dataset}/: model_{iter}.pth (checkpoints), vgg_reducedfc.pth (VGG16 base), last_checkpoint.txt (resume pointer), log.txt (training log), inference/ (evaluation results), output/ (annotated inference results).
- src/lufficc/: Engine (train.py, inference.py, demo.py, ssd/).
- src/annotation/: Bundled aiohttp annotation server (step 04).
- tool/tools.py: Shared helpers (project_root, delete_ipynb_checkpoints, select_device: CUDA → MPS → CPU).
- src/: Wrapper entry points and launcher scripts.
- 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 01_python_install_windows.bat / 01_python_install_linux.sh / 01_python_install_mac.sh (Windows: winget; Ubuntu: apt, or the deadsnakes PPA when the Ubuntu archive has no python3.14; macOS: Homebrew).
- 02_venv_create_windows.bat / 02_venv_create_linux.sh / 02_venv_create_mac.sh create venv/ with Python 3.14 and install PyTorch 2.13.0 + torchvision 0.28.0 first (Windows/Linux: the CUDA 13.0 cu130 build from download.pytorch.org; macOS: the PyPI build, which uses the Apple GPU through MPS), then src/requirements.txt (numpy, Pillow, matplotlib, opencv-python, PyYAML, yacs, vizer, tqdm, six, aiohttp + aiohttp-jinja2 + jinja2 for the annotation server).
- GPU (Windows / Linux): an NVIDIA GPU of the Turing generation or newer (GTX 16 / RTX 20 and later) with a driver supporting CUDA 13.0+ (check nvidia-smi); no CUDA toolkit is needed. Pascal/Volta GPUs (GTX 10xx, V100) are not supported by the cu130 build (see the GPU section). Without a usable NVIDIA GPU everything runs on the CPU automatically.
- macOS: macOS 14+ on Apple Silicon (arm64); PyTorch 2.13 has no Intel-Mac wheels. Training and inference use the Apple GPU (MPS); operators MPS lacks fall back to the CPU (PYTORCH_ENABLE_MPS_FALLBACK=1, set by the wrappers).
- Inference (07–08) is fine on the CPU; training (06) realistically wants a GPU.
[Launcher Scripts]
1. 01_python_install_windows.bat / 01_python_install_linux.sh / 01_python_install_mac.sh
Install Python 3.14 (winget / apt or deadsnakes PPA, needs sudo / Homebrew). Skips the install when Python 3.14 is already present. On Windows, open a new terminal afterwards.
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 (Windows/Linux: CUDA 13.0 cu130 build; macOS: PyPI build with MPS), then src/requirements.txt. Aborts loudly if pip fails; prints whether CUDA (macOS: 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|val|test --port).
5. 05_prepare.bat / 05_prepare.sh
Write train.txt and val.txt (image file names) from the image folders.
6. 06_train.bat / 06_train.sh
Train per the dataset's YAML config on the GPU (CUDA / MPS, CPU fallback; resumes from last_checkpoint.txt; Ctrl+C to stop).
7. 07_inference.bat / 07_inference.sh
Detect in one image (default data/steel/val/images/inclusion-2.jpg, threshold 0.3).
8. 08_inference_folder.bat / 08_inference_folder.sh
Detect in every image of a folder (default the val split, threshold 0.3).
9. 99_venv_clean.bat / 99_venv_clean.sh
Delete the venv/ folder.
10. 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).
[Python Entry Points]
src/annotation_server.py
--dataset steel --split train|val|test --port 8801 [--no-browser]. Bundled Pascal-VOC-XML annotation UI; writes XML into data/{dataset}/{split}/annotations/.
src/prepare.py
--dataset steel. Writes train.txt / val.txt (one image file name per line). labels.txt is maintained by hand.
src/train.py
--dataset steel [--cfg YML] [--save-step 500] [--eval-step 500] [--device auto]. Everything else comes from the YAML config (shipped: MAX_ITER 120000, batch 4, lr 1e-3). Starts from the VGG16 base and resumes from model/{dataset}/last_checkpoint.txt (shipped: iteration 7000). Losses, lr and the per-class AP + mAP of each evaluation are printed to the console (and appended to model/{dataset}/log.txt). Stop with Ctrl+C whenever the loss is good enough.
src/inference.py
--dataset steel [--source IMAGE] [--weights PTH] [--cfg YML] [--threshold 0.3] [--show] [--device auto]. Annotated image lands in model/{dataset}/output/ (same file name).
src/inference_folder.py
--dataset steel [--source FOLDER] [--weights PTH] [--cfg YML] [--threshold 0.3] [--show] [--device auto]. Detects in every .jpg/.png of the folder; results land in model/{dataset}/output/.
--device (train, inference, inference_folder): auto (default) picks cuda (NVIDIA GPU), then mps (Apple GPU), then cpu; cuda, cuda:N, mps and cpu force a device. The selected device is printed at startup (Device: cuda).
[Quick Start]
Windows 11
src\01_python_install_windows.bat
REM open a new terminal
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 (Apple GPU via MPS)
Full workflow for your own data: 04_annotation (label train + val) → edit data/{dataset}/labels.txt and copy + adjust the YAML config (NUM_CLASSES = classes + background, OUTPUT_DIR) → 05_prepare → 06_train (watch the console, stop with Ctrl+C) → 07–08 inference.
[GPU]
The venv scripts install the GPU-capable PyTorch build directly: on Windows/Linux the CUDA 13.0 (cu130) build, which also runs without an NVIDIA GPU (CPU fallback); on macOS the PyPI build, which uses the Apple GPU through MPS. The wrappers pick the device themselves (--device auto: CUDA → MPS → CPU) and print it (Device: cuda / mps / cpu).
Device: cpu on a PC with an NVIDIA GPU means the driver is older than CUDA 13.0 (update it; nvidia-smi shows the supported CUDA version) or the GPU is older than Turing. For Pascal/Volta GPUs (GTX 10xx, V100), reinstall PyTorch from the cu126 index inside the activated venv (03_venv_activate):
python -m pip uninstall -y torch torchvision
python -m pip install torch==2.13.0 torchvision==0.28.0 --index-url https://download.pytorch.org/whl/cu126
[References]
- SSD paper (Liu et al. 2016, shipped as 1512.02325.pdf): arxiv.org/abs/1512.02325
- lufficc/SSD (engine base): github.com/lufficc/SSD
- torch-ssd on PyPI (referenced by the original readme): pypi.org/project/torch-ssd
- PyTorch install: pytorch.org/get-started/locally
- PyTorch on Apple GPUs (MPS): docs.pytorch.org/docs/stable/notes/mps.html
This SDK is built in AppForAI - AI Dev Tools.