CLI reference

Installed console script

Discovery commands

Use these before direct execution if you do not want to guess supported architecture, component, or dataset names.

python -m simpledet list-detectors
python -m simpledet list-heads --kind dense
python -m simpledet list-backbones --pattern resnet
python -m simpledet list-necks
python -m simpledet list-datasets
python -m simpledet doctor
python -m simpledet doctor --strict --workdir /data/project/runs
python -m simpledet --show-detector-help retinanet

--list-detectors prints name, family, and native_validation columns, so entries such as cascade_rcnn and grid_rcnn show runtime_validated when the native runtime extra is available. simpledet list-detectors is equivalent to the flag form.

list-heads, list-backbones, list-necks, and list-datasets print name, kind, validation_status, and required_extra. These commands are safe in a base install; for example TIMM-backed backbone rows still print and show timm in required_extra instead of importing TIMM.

doctor prints the Python version, SimpleDet version, optional extra status, individual dependency availability, install hints, and whether the selected workdir is writable. Missing optional extras are warnings by default; add --strict when setup diagnostics should return non-zero. Use --check-runtime when you specifically want the older CPU runtime-only gate.

--show-detector-help prints the detector family, a short summary, and a few encoder suggestions for the selected architecture.

Direct non-config workflow

Use these commands when your dataset follows the standard project layout and you want native execution without creating a project file.

python -m simpledet --train-root /data/project \
  --categories car building ship \
  --in-channels 3 \
  --detector retinanet \
  --encoder resnet18.a1_in1k \
  --batch-size 2 \
  --max-epochs 30

python -m simpledet --infer-root /data/project \
  --categories car building ship \
  --in-channels 3 \
  --detector retinanet \
  --encoder resnet18.a1_in1k

python -m simpledet --eval-root /data/project \
  --categories car building ship \
  --in-channels 3 \
  --detector retinanet \
  --encoder resnet18.a1_in1k

Direct execution currently requires --categories, --in-channels, and a high-level detector selection.

python -m simpledet --train-root /data/project \
  --categories car building ship \
  --in-channels 3 \
  --detector retinanet \
  --encoder resnet18.a1_in1k \
  --batch-size 2 \
  --max-epochs 30

Use one of these model-definition paths:

• --detector with optional --encoder and --num-classes for suite-backed high-level model selection

Direct CLI execution uses the native Lightning backend automatically when you use one of the supported architectures, for example --detector retinanet, --detector vfnet, --detector centernet, or --detector faster_rcnn.

Optional runtime flags include --tif-channels-to-load, --result-folder, --resize, --batch-size, --max-epochs, --learning-rate, and --no-validate.

Project config workflow

Use a JSON or TOML file when you want a repeatable operational entrypoint for the native runtime.

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

A reusable example can be created with --init-project and then adjusted for your dataset root and output folder. When --stages is omitted, the runner uses the stages list from the config file, or build train test when the file does not set one.

stages = ["build", "train", "test"]
workdir = "/tmp/simpledet-runs"
seed = 71

[detector]
name = "retinanet"
num_classes = 1
backbone = "resnet18"
pretrained = false

[dataset]
format = "coco"
root = "/data/project"
train = "Annotations/train_annotations.json"
val = "Annotations/val_annotations.json"
test = "Annotations/test_annotations.json"
data_prefix = "imgs/"
classes = ["wake"]
in_channels = 3

[runtime]
batch_size = 2
max_epochs = 12

[optimizer]
name = "AdamW"
learning_rate = 0.001

[scheduler]
name = "step"
step_size = 2
gamma = 0.5

[checkpoint]
path = "/tmp/simpledet-runs/checkpoints/last.ckpt"

[export]
formats = ["json"]

The runner validates the dataset root, image directory, and train/validation/test annotation files before it creates the workdir or enters training. Successful project runs write run-manifest.json in the workdir with the normalized detector, dataset, optimizer, scheduler, runtime, checkpoint, export, selected stages, and child native results.

simpledet.train

Public Python callable, not a shell executable.

train(*, config=None, pipeline=None, build=True, **pipeline_kwargs)

• config=... uses the lightweight torchvision path
• Forwarded runtime kwargs map to the native execution helpers
• detector_spec=... is the supported high-level model input

simpledet.detect

detect(*, pipeline=None, build=True, **pipeline_kwargs)

Runs the package inference helper for the current native runtime. This is separate from load_model() plus predict().

simpledet.evaluate

evaluate(*, pipeline=None, build=True, **pipeline_kwargs)

Currently a thin wrapper around the same native evaluation path used by run_evaluation(...).

Lightweight inference helpers

load_checkpoint_for_inference(checkpoint, *, device="cpu", model_name=None, num_classes=None, class_names=None, score_threshold=0.05, max_detections=None)
predict_image(model, image_path, *, class_names=None, device="cpu", score_threshold=None, max_detections=None, metadata=None)
predict_batch(model, image_paths, *, class_names=None, device="cpu", score_threshold=None, max_detections=None, metadata=None)
export_predictions(predictions, output_path=None, *, indent=2)