SimpleDet Docs

Examples

Practical detector patterns that match the current suite plus native runtime API.

Overview Quickstart Core Concepts API Reference

Use this page when you want a concrete starting point for a detector family instead of a generic tutorial.

Script gallery

The examples/ directory contains copyable scripts for common workflows. The construction and discovery examples run without sample data. Dataset and checkpoint examples default to examples/sample_data/... and fail with a clear message when those files are not present, so pass your own local paths when adapting them.

PYTHONPATH=simpledet python examples/quick_detector.py
PYTHONPATH=simpledet python examples/timm_retinanet.py
PYTHONPATH=simpledet python examples/registry_discovery.py --pattern retina

Detector construction

from simpledet.suite import build_detector, build_neck, compile_native_detector_plan

spec = build_detector(
    "retinanet",
    backbone="resnet18",
    neck=build_neck("FPN", out_channels=256, num_outs=4),
    num_classes=3,
    pretrained=False,
)
plan = compile_native_detector_plan(spec)

Script starting point: examples/quick_detector.py.

TIMM RetinaNet

from simpledet.suite import build_detector

spec = build_detector(
    "retinanet",
    encoder="timm:resnet18",
    num_classes=3,
    pretrained=False,
)

Script starting point: examples/timm_retinanet.py. Install simpledet[timm] before building the actual torch module.

COCO training config

PYTHONPATH=simpledet python examples/coco_training_config.py \
  --dataset-root ./data/coco \
  --workdir ./runs/coco-retinanet

PYTHONPATH=simpledet python examples/coco_training_config.py \
  --dataset-root ./data/coco \
  --workdir ./runs/coco-retinanet \
  --run

The script validates images/ and annotations/train.json, annotations/val.json, and annotations/test.json before training. For COCO 2017 source folders, create that SimpleDet layout first:

PYTHONPATH=simpledet python scripts/prepare_coco_simpledet.py \
  --source-root /data/coco \
  --output-root ./data/coco \
  --train-limit 1000 \
  --val-limit 200 \
  --test-limit 200

Custom components training

PYTHONPATH=simpledet python examples/custom_components_training.py --run

examples/custom_components.py registers ExampleTinyBackbone, ExampleTinyNeck, and ExampleTinyDenseHead. The training script wires those custom parts into a RetinaNet detector spec and runs build, one CPU training epoch, test, and inference on COCO-format data.

YOLO dataset config

PYTHONPATH=simpledet python examples/yolo_dataset_config.py \
  --dataset-root ./data/yolo

PYTHONPATH=simpledet python examples/yolo_dataset_config.py \
  --dataset-root ./data/yolo \
  --classes-file ./data/yolo/data.yaml \
  --inspect

The config expects YOLO-style images/ and labels/ directories and can use the public dataset adapter to inspect labels.

Checkpoint inference

PYTHONPATH=simpledet python examples/load_ckpt_for_inference.py \
  --checkpoint ./runs/coco-retinanet/checkpoints/model.pt \
  --model-name fasterrcnn_resnet50_fpn \
  --num-classes 2

The checkpoint loader uses torch.load, so only pass checkpoint files you trust.

Executed package showcase

notebooks/Tools/simpledet_showcase.ipynb remains the longer runnable tour for detector alias coverage, dense and ROI family routing, custom multi-band encoders, native build-plan compilation, project config templates, and optional runtime registry discovery.

Create and train notebook

notebooks/Tools/create_train_object_detector.ipynb creates a tiny COCO-format dataset, builds explicit ResNet-18, ResNet-50, ConvNeXt, FPN, RetinaHead, FCOSHead, and ROI bbox-head recipes, shows the compiled detector glue, validates the config, trains for one CPU epoch, then runs test and inference.