Inference

Pipeline inference

Use this when the checkpoint comes from the pipeline path and you want evaluator-compatible test-time outputs.

from simpledet import detect
from simpledet.suite import build_detector

outputs = detect(
    build=True,
    detector_spec=build_detector(
        "faster_rcnn",
        encoder="convnext_tiny.in12k_ft_in1k",
        num_classes=4,
        in_channels=3,
    ),
    data_folder="/data/project",
    result_folder="results/project",
    annot_file_train="/data/project/annotations/train.json",
    annot_file_val="/data/project/annotations/val.json",
    annot_file_test="/data/project/annotations/test.json",
    tif_channels_to_load=[1, 1, 1],
    in_channels=3,
    categories=("a", "b", "c", "d"),
)

This is the same test-time path used during evaluation. It writes the native manifest for the run and returns the prediction payload for downstream scoring.

Direct non-config inference

Use this when your dataset follows the standard project layout and you want pipeline-managed test execution without creating a config file first.

from simpledet import run_inference

result = run_inference(
    dataset_root="/data/project",
    detector_spec=build_detector(
        "faster_rcnn",
        encoder="convnext_tiny.in12k_ft_in1k",
        num_classes=4,
        in_channels=3,
    ),
    categories=("a", "b", "c", "d"),
    in_channels=3,
)

This helper executes the pipeline build and test stages directly and returns the same stage payloads the pipeline would produce.

Image prediction API

Use this for direct image-level predictions from a model object that returns boxes, scores, and labels, or from a lightweight torchvision-compatible checkpoint.

from simpledet import (
    export_predictions,
    load_checkpoint_for_inference,
    predict_batch,
    predict_image,
)

model = load_checkpoint_for_inference(
    "runs/exp001/epoch_001.pth",
    device="cpu",
    model_name="retinanet_resnet50_fpn",
    num_classes=3,
    class_names=("wake", "ship"),
    score_threshold=0.10,
    max_detections=50,
)

single = predict_image(model, "sample.png")
batch = predict_batch(model, ["a.png", "b.png"])
payload = export_predictions(batch, "predictions.json")

predict_image(...) returns boxes, scores, labels, class_names, and metadata. Metadata includes the image path, file name, channel count, height, width, and tensor shape. Missing paths raise FileNotFoundError with the path. Existing paths that cannot be decoded raise ImageLoadingError with the path. Batch prediction is fail-fast on the first unreadable image.

{
  "boxes": [[1.0, 2.0, 6.0, 8.0]],
  "scores": [0.93],
  "labels": [1],
  "class_names": ["wake"],
  "metadata": {
    "path": "sample.png",
    "file_name": "sample.png",
    "channels": 3,
    "height": 512,
    "width": 512,
    "shape": [3, 512, 512]
  }
}

export_predictions(...) returns and optionally writes {"format": "simpledet_predictions", "version": 1, "predictions": [...]}. The checkpoint loader is intentionally scoped to the lightweight checkpoint format; pipeline checkpoints should use the native project inference path above. Checkpoints are loaded with torch.load, so only load checkpoint files from trusted sources.

Which one should you use?