Native object-detection toolkit with registry-first model composition and a PyTorch Lightning runtime.
SimpleDet is designed to make detector development predictable and production-friendly:
- Build detector definitions with
simpledet.suite(Encoder, Neck, Head, Decoder, Detector specs). - Compile runtime plans that adapt layer dimensions automatically from actual encoder outputs.
- Run training, inference, and evaluation through native project-oriented workflows.
- Keep experimentation reproducible with explicit CLI and config-based project execution.
| Area | What you get |
|---|---|
| Model authoring | Declarative detector specs + registry-backed component assembly |
| Execution | Native PyTorch Lightning training, inference, and evaluation path |
| Adaptation | Automatic channel/shape alignment during model compilation |
| Packaging | Project-level run orchestration and validation commands |
| Catalog support | retinanet, retina, fcos, atss, gfl, vfnet, fovea, foveabox, reppoints, yolof, centernet, rpn, fast_rcnn, faster_rcnn, mask_rcnn, cascade_rcnn, cascade_mask_rcnn, grid_rcnn, libra_rcnn, double_head_rcnn, dynamic_rcnn |
Choose the smallest install path that matches the workflow you want to run. The base package is lightweight; runtime and tooling dependencies live behind extras so imports stay fast and environments stay focused.
| Workflow | Command |
|---|---|
| Base package and CLI metadata | python -m pip install simpledet |
| CPU training, inference, and evaluation runtime | python -m pip install 'simpledet[cpu]' |
| TIMM encoder catalog support | python -m pip install 'simpledet[timm]' |
| Documentation workflow setup | python -m pip install 'simpledet[docs]' |
| Geospatial dataset helpers | python -m pip install 'simpledet[geo]' |
| Plotting utilities | python -m pip install 'simpledet[plots]' |
| Geospatial plus plotting workflows | python -m pip install 'simpledet[geo,plots]' |
| Development tooling for build, lint, and release checks | python -m pip install 'simpledet[dev]' |
| Local development with CPU runtime, TIMM validation, and release tooling | python -m pip install -e '.[cpu,timm,dev]' |
python -m pip install simpledetpython -m pip install 'simpledet[cpu]'python -m pip install 'simpledet[timm]'python -m pip install 'simpledet[docs]'python -m pip install 'simpledet[geo,plots]'python -m pip install 'simpledet[dev]'git clone https://github.com/sirbastiano/SimpleDet.git
cd SimpleDet
python -m pip install -e '.[cpu,timm,dev]'python -m simpledet --version
python -m simpledet --check-runtimeTroubleshooting starts with the installed extra set: use simpledet[cpu] before runtime imports, combine cpu,timm when validating TIMM-backed detector construction, and prefer a fresh virtual environment if wheel resolution leaves incompatible PyTorch or TorchVision builds. SimpleDet does not require MMDetection, MMEngine, or MMCV as runtime dependencies.
- Platforms: Linux, macOS, Windows
- Python: 3.10, 3.11, 3.12
- Runtime support: CPU stack via
simpledet[cpu], TIMM encoders viasimpledet[timm], geospatial helpers viasimpledet[geo], plotting viasimpledet[plots], docs workflow setup viasimpledet[docs], and development tooling viasimpledet[dev](wheel-compatible dependencies are required for supported OS/Python pairs)
simpledet.suite: author specs, compose detector graphs, and compile native plans.simpledet.native: run native PyTorch Lightning model loops.simpledet.detectors: compatibility helpers for lightweight flows.simpledet._model_resolution: runtime shape and channel adaptation internals.
- Installation guide
- Quickstart
- CLI reference
- Core concepts
- Executed showcase notebook:
notebooks/Tools/simpledet_showcase.ipynb - Create and train notebook:
notebooks/Tools/create_train_object_detector.ipynbshows explicit ResNet-18/ResNet-50/ConvNeXt backbones, FPN, dense/ROI heads, detector-plan, and CPU training glue. - Roadmap / changelog
make venv
make sync
make sync-cpu
make build
make docs-audit
make check
make release-ready
make test-cpu-smokePrepare a COCO 2017 subset for the native project runner with:
PYTHONPATH=simpledet python scripts/prepare_coco_simpledet.py \
--source-root /data/coco \
--output-root ./data/coco \
--train-limit 1000 \
--val-limit 200 \
--test-limit 200Train one CPU epoch with a custom registered backbone, neck, and dense head on COCO-format data with:
PYTHONPATH=simpledet python examples/custom_components_training.py --runmake release-ready is the final handoff gate. It rebuilds the package, runs
the unit, docs, and distribution checks, then audits release claims so detector
and head counts stay above 31 and docs stay aligned with package extras.
make test-cpu-smoke is the optional slow CPU workflow gate for checkouts with
simpledet[cpu] installed. It runs the tiny project-config smoke path through
build, one training epoch, test/evaluation, inference, manifest writing, and
prediction export.
simpledet/: Python source root used by packagingsimpledet/simpledet/: installable packagesimpledet/simpledet/native/: native Lightning runtime and model execution componentssimpledet/simpledet/suite/: detector specs, builders, and planning helperssimpledet/simpledet/_model_resolution.py: model-adaptation helperssimpledet/simpledet/detectors/: compatibility path for lightweight training/eval flowsdocs/: static documentation sitescripts/: repository verification and docs audit helperstests/: unit and packaging checks
python3 -m build
python3 -m twine check dist/*
PYTHONPATH=simpledet python3 -m unittest discover -s tests -p 'test*.py'SimpleDet is released under the MIT License.