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
"""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())"""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())"""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
python infer_rfdetr.py \
--artifact artifacts/rfdetr/model.onnx \
--image data/test-image.pngpython infer_yolox.py \
--artifact artifacts/yolox/model.onnx \
--image data/test-image.pngpython infer_sam3_lora.py \
--artifact artifacts/sam3-lora/model.pt \
--image data/test-image.png \
--prompts "green circle" "red triangle" \
--device cudaModel Constructor
| Parameter | Default | Description |
|---|---|---|
artifact_path | required | Exported .onnx or Iris .pt deployment artifact |
class_names | artifact metadata | Optional sequence or integer-to-name mapping |
providers | CUDA then CPU when available | Ordered ONNX Runtime provider names |
input_size | graph shape | (height, width) required only for an ONNX graph with dynamic spatial dimensions |
device | best available | PyTorch 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()
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
| Field | Contract |
|---|---|
boxes | float32 NumPy array (N, 4) in absolute COCO xywh source-image pixels |
scores | float32 NumPy array (N,), values in [0, 1] |
class_ids | integer NumPy array (N,) |
class_names | Optional list containing one name per detection |
masks | Optional 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
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
from telekinesis.iris.models import YOLOXPostprocessConfig
prediction = model.predict(
image,
postprocess=YOLOXPostprocessConfig(
nms_threshold=0.65,
class_agnostic=False,
),
)SAM3-LoRA
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.