SimpleDet Docs

Quickstart

This tutorial is the shortest path through the current repository. It explains not only what to run, but why the repo is split into a detector-definition step and a native-runtime execution step.

Overview Quickstart Core Concepts API Reference

Use this page when you want one guided path from install to detector definition, training, and evaluation.

1. Install and verify

Install the package and CPU runtime first, then verify the command-line surface before working through the examples.

python -m pip install -e .
python -m pip install ".[cpu]"
python -m simpledet --check-runtime

2. Bootstrap a project config

If you want a repeatable operational workflow, start by creating a project file and validating it before launching training.

python -m simpledet --init-project project.toml
python -m simpledet --project-validate project.toml

3. Build a detector

A DetectorSpec is the repo’s high-level model description. It says which detector family you want, which backbone it should use, and how many classes it must predict. The planner then turns that high-level description into a native build plan.

python - <<'PY'
from pprint import pprint
from simpledet.suite import build_detector, compile_native_detector_plan

spec = build_detector(
    "retinanet",
    encoder="resnet18.a1_in1k",
    num_classes=2,
    in_channels=3,
)
plan = compile_native_detector_plan(spec)

print(spec.family)
pprint(plan.encoder)
pprint(plan.neck)
pprint(plan.head)
PY

Expected output shape:

dense
NativeEncoderPlan(type='TimmEncoder', ...)
NativeNeckPlan(type='FPN', ...)
NativeHeadPlan(type='RetinaHead', ...)

The key concept is that you are not writing the full model dictionary by hand. SimpleDet inspects the backbone, infers feature channels, and patches the neck and head interfaces for you.

4. Train through the native runtime

The runtime owns everything that is not intrinsic to the detector itself: dataset locations, annotation files, image resize, logging, checkpointing, evaluator outputs, and operational validation.

from simpledet import run_training
from simpledet.suite import build_detector

detector_spec = build_detector(
    "retinanet",
    encoder="resnet18.a1_in1k",
    num_classes=2,
    in_channels=3,
)

result = run_training(
    dataset_root="/path/to/dataset_root",
    detector_spec=detector_spec,
    categories=("object_a", "object_b"),
    in_channels=3,
    tif_channels_to_load=[1, 2, 3],
    resize=768,
    batch_size=2,
    learning_rate=0.001,
    max_epochs=10,
    validate=True,
)
print(result["backend"])

The runtime helper assumes the conventional imgs/ and Annotations/*_annotations.json layout. It validates dataset wiring, assembles the model from the detector spec, and executes the requested native training stages.

5. Run without a config file or explicit pipeline object

If you want the operational pipeline behavior but do not want to create a project config or hold a pipeline instance yourself, use the direct execution helpers.

from simpledet import run_training, run_evaluation

train_result = run_training(
    dataset_root="/path/to/dataset_root",
    detector_spec=detector_spec,
    categories=("object_a", "object_b"),
    in_channels=3,
    batch_size=2,
    max_epochs=10,
)

metrics = run_evaluation(
    dataset_root="/path/to/dataset_root",
    detector_spec=detector_spec,
    categories=("object_a", "object_b"),
    in_channels=3,
)

These helpers still use the same project-layout conventions and native runtime internals. They just remove the config-file step and the explicit project execution call.

6. Evaluate

Evaluation is not a standalone subsystem in this repo. It reuses the native runtime test path so the evaluator, output files, and dataset metadata remain consistent with training.

from simpledet import run_evaluation

metrics = run_evaluation(
    dataset_root="/path/to/dataset_root",
    detector_spec=detector_spec,
    categories=("object_a", "object_b"),
    in_channels=3,
)
print(metrics["backend"])

Expected artifacts:

native-manifest.json
checkpoints/
prediction records returned by the runtime

7. Run the same workflow from a config file

Once the experiment shape stabilizes, move the same settings into a project config and execute the package through the CLI.

python -m simpledet --project-run project.toml --stages build train test

What to remember

DetectorSpec

Describes the detector architecture you want to run.

Compiled build plan

Is the native runtime plan generated from that high-level spec.

Runtime

Attaches runtime concerns such as datasets, workdir layout, hooks, and evaluators.

8. Use structured configs when the project grows

The project helpers are the fastest way to start. When experiments become more complex, move to structured config objects so dataset wiring, runtime knobs, and optimization settings are kept separate.

from simpledet import (
    ProjectConfig,
    DatasetConfig,
    RuntimeConfig,
    OptimizationConfig,
    run_project,
)

dataset = DatasetConfig(
    data_root="/path/to/dataset_root",
    annot_file_train="/path/to/annotations/train.json",
    annot_file_val="/path/to/annotations/val.json",
    annot_file_test="/path/to/annotations/test.json",
    categories=("object_a", "object_b"),
    in_channels=3,
)
runtime = RuntimeConfig(result_folder="/path/to/results", resize=768, batch_size=2)
optimization = OptimizationConfig(learning_rate=0.001, optimizer_choice="AdamW")

project = ProjectConfig(
    dataset=dataset,
    runtime=runtime,
    optimization=optimization,
    detector_spec=detector_spec,
)
run_project(project)