Skip to content

Run Inference ​

SUMMARY

Load any exported Iris artifact with deploy.Model. Embedded metadata selects the runtime and default class names; each predict() call supplies thresholds, limits, prompts, post-processing, and NumPy channel order.

Inference Workflow ​

Choose an Inference Script ​

python
"""Run local RF-DETR inference on one image."""

import argparse
from pathlib import Path

import rerun as rr
from loguru import logger

from telekinesis.iris.deploy import Model, RFDETRPostprocessConfig
from telekinesis.iris.visualizer import visualize_prediction


def parse_args() -> argparse.Namespace:
    """Parse command-line arguments."""
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument("--artifact", type=Path, required=True)
    parser.add_argument("--image", type=Path, required=True)
    parser.add_argument("--class-names", nargs="+")
    parser.add_argument("--providers", nargs="+")
    parser.add_argument("--confidence-threshold", type=float, default=0.3)
    parser.add_argument("--max-detections", type=int, default=100)
    parser.add_argument("--background-class-id", type=int)
    parser.add_argument("--visualize", action=argparse.BooleanOptionalAction, default=True)
    return parser.parse_args()


def infer_rfdetr(args: argparse.Namespace) -> None:
    """Load the exported artifact and predict one image locally."""
    model = Model(
        args.artifact,
        class_names=args.class_names,
        providers=args.providers,
    )
    prediction = model.predict(
        args.image,
        confidence_threshold=args.confidence_threshold,
        max_detections=args.max_detections,
        postprocess=RFDETRPostprocessConfig(
            background_class_id=args.background_class_id,
        ),
    )
    logger.info(f"Found {len(prediction)} detections in {args.image.name}")
    for box, score, class_id, class_name in zip(
        prediction.boxes,
        prediction.scores,
        prediction.class_ids,
        prediction.class_names or map(str, prediction.class_ids),
        strict=True,
    ):
        logger.info(
            f"class={class_name} id={class_id} score={score:.3f} "
            f"box_xywh={box.round(1).tolist()}"
        )
    if args.visualize:
        rr.init("rfdetr_inference", spawn=True)
        visualize_prediction(args.image, prediction)


if __name__ == "__main__":
    infer_rfdetr(parse_args())
python
"""Run local YOLOX inference on one image."""

import argparse
from pathlib import Path

import rerun as rr
from loguru import logger

from telekinesis.iris.deploy import Model, YOLOXPostprocessConfig
from telekinesis.iris.visualizer import visualize_prediction


def parse_args() -> argparse.Namespace:
    """Parse command-line arguments."""
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument("--artifact", type=Path, required=True)
    parser.add_argument("--image", type=Path, required=True)
    parser.add_argument("--class-names", nargs="+")
    parser.add_argument("--providers", nargs="+")
    parser.add_argument("--confidence-threshold", type=float, default=0.3)
    parser.add_argument("--max-detections", type=int, default=100)
    parser.add_argument("--nms-threshold", type=float, default=0.5)
    parser.add_argument("--class-agnostic", action=argparse.BooleanOptionalAction, default=False)
    parser.add_argument("--visualize", action=argparse.BooleanOptionalAction, default=True)
    return parser.parse_args()


def infer_yolox(args: argparse.Namespace) -> None:
    """Load the exported artifact and predict one image locally."""
    model = Model(
        args.artifact,
        class_names=args.class_names,
        providers=args.providers,
    )
    prediction = model.predict(
        args.image,
        confidence_threshold=args.confidence_threshold,
        max_detections=args.max_detections,
        postprocess=YOLOXPostprocessConfig(
            nms_threshold=args.nms_threshold,
            class_agnostic=args.class_agnostic,
        ),
    )
    logger.info(f"Found {len(prediction)} detections in {args.image.name}")
    for box, score, class_id, class_name in zip(
        prediction.boxes,
        prediction.scores,
        prediction.class_ids,
        prediction.class_names or map(str, prediction.class_ids),
        strict=True,
    ):
        logger.info(
            f"class={class_name} id={class_id} score={score:.3f} "
            f"box_xywh={box.round(1).tolist()}"
        )
    if args.visualize:
        rr.init("yolox_inference", spawn=True)
        visualize_prediction(args.image, prediction)


if __name__ == "__main__":
    infer_yolox(parse_args())
python
"""Run local SAM3 LoRA inference on one image."""

import argparse
from pathlib import Path

import rerun as rr
from loguru import logger

from telekinesis.iris.deploy import Model, SAM3PostprocessConfig
from telekinesis.iris.visualizer import visualize_prediction


def parse_args() -> argparse.Namespace:
    """Parse command-line arguments."""
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument("--artifact", type=Path, required=True)
    parser.add_argument("--image", type=Path, required=True)
    parser.add_argument("--prompts", nargs="+")
    parser.add_argument("--device", help="For example: cuda, cuda:0, or cpu.")
    parser.add_argument("--confidence-threshold", type=float, default=0.5)
    parser.add_argument("--max-detections", type=int, default=100)
    parser.add_argument("--per-prompt-nms-threshold", type=float, default=0.5)
    parser.add_argument(
        "--prompt-conflict-policy",
        choices=("multi_label", "best_prompt"),
        default="multi_label",
    )
    parser.add_argument("--cross-prompt-iou-threshold", type=float, default=0.8)
    parser.add_argument("--visualize", action=argparse.BooleanOptionalAction, default=True)
    return parser.parse_args()


def infer_sam3_lora(args: argparse.Namespace) -> None:
    """Load the exported bundle and predict one image locally."""
    model = Model(args.artifact, device=args.device)
    prediction = model.predict(
        args.image,
        confidence_threshold=args.confidence_threshold,
        prompts=args.prompts,
        max_detections=args.max_detections,
        postprocess=SAM3PostprocessConfig(
            per_prompt_nms_threshold=args.per_prompt_nms_threshold,
            prompt_conflict_policy=args.prompt_conflict_policy,
            cross_prompt_iou_threshold=args.cross_prompt_iou_threshold,
        ),
    )
    logger.info(f"Found {len(prediction)} detections in {args.image.name}")
    for box, score, class_id, class_name in zip(
        prediction.boxes,
        prediction.scores,
        prediction.class_ids,
        prediction.class_names or map(str, prediction.class_ids),
        strict=True,
    ):
        logger.info(
            f"class={class_name} id={class_id} score={score:.3f} "
            f"box_xywh={box.round(1).tolist()}"
        )
    if args.visualize:
        rr.init("sam3_lora_inference", spawn=True)
        visualize_prediction(args.image, prediction)


if __name__ == "__main__":
    infer_sam3_lora(parse_args())

Run Inference ​

bash
python infer_rfdetr.py \
  --artifact artifacts/rfdetr/model.onnx \
  --image data/test-image.png
bash
python infer_yolox.py \
  --artifact artifacts/yolox/model.onnx \
  --image data/test-image.png
bash
python infer_sam3_lora.py \
  --artifact artifacts/sam3-lora/model.pt \
  --image data/test-image.png \
  --prompts "green circle" "red triangle" \
  --device cuda

Model Constructor ​

ParameterDefaultDescription
artifact_pathrequiredExported .onnx or Iris .pt deployment artifact
class_namesartifact metadataOptional sequence or integer-to-name mapping
providersCUDA then CPU when availableOrdered ONNX Runtime provider names
input_sizegraph shape(height, width) required only for an ONNX graph with dynamic spatial dimensions
devicebest availablePyTorch device for SAM3-LoRA; invalid for ONNX families

Artifact metadata, rather than the filename extension or a user-supplied model name, selects RF-DETR, YOLOX, or SAM3-LoRA.

predict() ​

python
prediction = model.predict(
    image,
    confidence_threshold=0.3,
    prompts=None,
    max_detections=300,
    postprocess=None,
    input_channel_order="rgb",
)

image may be a path or an HWC NumPy array. File inputs are decoded as RGB. For arrays, set input_channel_order to "rgb" or "bgr". Calling model(image) uses all prediction defaults.

Prediction ​

FieldContract
boxesfloat32 NumPy array (N, 4) in absolute COCO xywh source-image pixels
scoresfloat32 NumPy array (N,), values in [0, 1]
class_idsinteger NumPy array (N,)
class_namesOptional list containing one name per detection
masksOptional boolean array (N, H, W) at source-image resolution

Post-processing ​

Post-processing is request-specific and is passed to predict(). The config must match the artifact family.

RF-DETR ​

python
from telekinesis.iris.models import RFDETRPostprocessConfig

prediction = model.predict(
    image,
    postprocess=RFDETRPostprocessConfig(background_class_id=0),
)

background_class_id defaults to None; when postprocess is omitted, Iris uses the value embedded during training.

YOLOX ​

python
from telekinesis.iris.models import YOLOXPostprocessConfig

prediction = model.predict(
    image,
    postprocess=YOLOXPostprocessConfig(
        nms_threshold=0.65,
        class_agnostic=False,
    ),
)

SAM3-LoRA ​

python
from telekinesis.iris.models import SAM3PostprocessConfig

prediction = model.predict(
    image,
    prompts={1: "green circle", 2: "red triangle"},
    postprocess=SAM3PostprocessConfig(
        per_prompt_nms_threshold=0.5,
        prompt_conflict_policy="best_prompt",
        cross_prompt_iou_threshold=0.8,
    ),
)

prompt_conflict_policy="multi_label" retains cross-prompt overlaps; "best_prompt" resolves conflicts above cross_prompt_iou_threshold.

Next Steps ​