SimpleDet Docs

Core concepts

SimpleDet makes more sense if you separate three questions: what detector am I defining, what runtime is going to execute it, and what artifacts should survive after the run finishes?

Overview Quickstart Core Concepts API Reference

Read this page when the APIs make sense individually but the architecture and artifact flow still feel unclear.

On this page: Workflow Layers Artifacts Auto-adaptation

Workflow

The repository follows one main object-detection lifecycle. The model is defined first, then attached to a dataset and runtime, then trained into a workdir that preserves checkpoints and evaluator outputs. 

dataset
  -> detector_spec
  -> native runtime
  -> training
  -> checkpoint
  -> inference
  -> evaluation
Recommended path
dataset root + COCO annotations
  -> build_detector(...)
  -> compile_native_detector_plan(...)
  -> run_training(detector_spec=...)
  -> run_evaluation(...)
Lightweight path
dataset file or folder
  -> load_dataset()
  -> train(config=...)
  -> epoch_001.pth
  -> load_model()
  -> predict()

The recommended path is the first one. The lightweight path is intentionally smaller and compatible with fewer checkpoints and behaviors.

Layers

  • Authoring layer: simpledet.suite provides DetectorSpec, builders, and native planning.
  • Runtime layer: run_training, run_inference, run_evaluation, and run_project wire data and own the workdir.
  • Compatibility helpers: simpledet.detectors.* covers lightweight training, inference, and dataset loading.

The important boundary is this: simpledet.suite decides the detector structure, while the native runtime decides how that detector is executed in a full experiment.

What gets compiled and what stays runtime-configured

Compiled from the detector spec

Backbone, neck, dense head, ROI head, transformer blocks, class count, and downstream channel interfaces.

Configured by the pipeline

Dataset paths, dataloaders, resize policy, optimizer and scheduler settings, hooks, workdir layout, and evaluator outputs.

Artifacts

  • native-manifest.json for the run summary
  • checkpoints/ for the retained checkpoint files
  • prediction records returned by the evaluation runtime

In the lightweight path, the main artifacts are epoch_001.pth and metrics.json.

This difference matters because a checkpoint from one path is not automatically interchangeable with the other. The native runtime path is the canonical execution surface for the current package.

Backbone auto-adaptation

When you build a detector with a supported timm backbone, SimpleDet can inspect the feature channels and patch downstream modules automatically.

  • neck in_channels
  • dense head channel fields
  • RPN and ROI bbox or mask heads
  • ROI extractor output channels
  • transformer embed dimensions and feature levels
  • num_classes

In practice, this means you can swap from one supported encoder to another without manually recalculating neck input channels or editing several head sections by hand.

This covers timm encoders with usable feature metadata and custom backbones only when you provide backbone_cfg plus explicit feature_channels.

Custom component mechanism

SimpleDet now exposes a suite-level customization path for registry-backed backbones, necks, heads, and decoders without dropping to handwritten low-level component wiring. 

from simpledet.suite import build_custom_encoder, build_custom_neck, build_detector

spec = build_detector(
    "retinanet",
    num_classes=2,
    encoder=build_custom_encoder(
        "MyBackbone",
        imports=("my_project.detectors.backbones",),
        feature_channels=[64, 128, 256, 512],
    ),
    neck=build_custom_neck(
        "MyNeck",
        imports=("my_project.detectors.necks",),
        out_channels=256,
    ),
)

The important contract is explicit: custom components are still registry-backed types, but the suite now carries the required imports metadata into the native build plan so those modules can be resolved at runtime.