Inference API

API reference for inference utilities.

Predictor

High-level inference predictor for running detection on images.

class objdet.inference.predictor.Predictor(model, device='cuda', confidence_threshold=0.25, nms_threshold=0.45)

Bases: object

High-level inference predictor for detection models.

Provides a simple interface for loading models and running inference on images or directories.

Parameters:

• model (BaseLightningDetector) – Detection model instance.

• device (str | device) – Device to run inference on.

• confidence_threshold (float) – Minimum confidence for predictions.

• nms_threshold (float) – IoU threshold for NMS.

Example

>>> predictor = Predictor.from_checkpoint("model.ckpt")
>>> result = predictor.predict("photo.jpg")
>>> print(f"Found {len(result['boxes'])} objects")

classmethod from_checkpoint(checkpoint_path, model_class=None, device='cuda', **kwargs)

Create predictor from a Lightning checkpoint.

Parameters:

• checkpoint_path (str | Path) – Path to .ckpt checkpoint file.

• model_class (type | None) – Optional model class. If None, tries to infer from checkpoint.

• device (str) – Device for inference.

• **kwargs (Any) – Additional arguments for Predictor.

Return type:

Predictor

Returns:

Configured Predictor instance.

predict(image, return_image=False)

Run inference on a single image.

Parameters:

• image (str | Path | Tensor | Image) – Image path, PIL Image, or tensor.

• return_image (bool) – Whether to also return the preprocessed image.

Return type:

DetectionPrediction | tuple[DetectionPrediction, Tensor]

Returns:

Prediction dict with boxes, labels, scores. If return_image, returns tuple of (prediction, image_tensor).

predict_batch(images, batch_size=8)

Run inference on multiple images.

Parameters:

• images (list[str | Path | Tensor]) – List of image paths or tensors.

• batch_size (int) – Batch size for inference.

Return type:

list[DetectionPrediction]

Returns:

List of prediction dictionaries.

predict_directory(directory, extensions=('.jpg', '.jpeg', '.png'), batch_size=8)

Run inference on all images in a directory.

Parameters:

• directory (str | Path) – Path to directory.

• extensions (tuple[str, ...]) – Image file extensions to include.

• batch_size (int) – Batch size for inference.

Return type:

dict[str, DetectionPrediction]

Returns:

Dict mapping filename to prediction.

Usage Example

from objdet.inference import Predictor

# Create from checkpoint
predictor = Predictor.from_checkpoint(
    checkpoint_path="model.ckpt",
    device="cuda",
    confidence_threshold=0.25,
)

# Single image inference
result = predictor.predict("image.jpg")
print(f"Found {len(result['boxes'])} objects")

# Batch inference
results = predictor.predict_batch(["img1.jpg", "img2.jpg"], batch_size=8)

# Directory inference
results_dict = predictor.predict_directory("./images", extensions=(".jpg", ".png"))

---

SlicedInference (SAHI)

Slicing Aided Hyper Inference for detecting small objects in large images.

class objdet.inference.sahi_wrapper.SlicedInference(predictor, slice_height=640, slice_width=640, overlap_ratio=0.2, merge_method='nms', nms_threshold=0.5, include_full_image=True)

Bases: object

Slicing Aided Hyper Inference for large images.

SAHI splits large images into overlapping tiles, runs detection on each tile, and merges the results using NMS or WBF.

Parameters:

• predictor (Predictor) – The predictor to use for inference on slices.

• slice_height (int) – Height of each slice in pixels.

• slice_width (int) – Width of each slice in pixels.

• overlap_ratio (float) – Overlap between adjacent slices (0-1).

• merge_method (str) – How to merge overlapping predictions (“nms” or “wbf”).

• nms_threshold (float) – IoU threshold for merging.

• include_full_image (bool) – Whether to also run on full image.

Example

>>> sahi = SlicedInference(predictor, slice_height=640, slice_width=640)
>>> results = sahi.predict("aerial_image.jpg")

predict(image)

Run sliced inference on a large image.

Parameters:

image (str | Path | Tensor) – Image path or tensor.

Return type:

DetectionPrediction

Returns:

Merged predictions from all slices.

Usage Example

from objdet.inference import Predictor, SlicedInference

# Create base predictor
predictor = Predictor.from_checkpoint("model.ckpt")

# Wrap with sliced inference
sahi = SlicedInference(
    predictor=predictor,
    slice_height=640,
    slice_width=640,
    overlap_ratio=0.2,
    merge_method="nms",  # or "wbf"
    include_full_image=True,
)

# Run sliced inference on large image
result = sahi.predict("large_satellite_image.jpg")

Parameters:

• predictor: Base Predictor instance for running inference on slices

• slice_height (int): Height of each slice (default: 640)

• slice_width (int): Width of each slice (default: 640)

• overlap_ratio (float): Overlap between adjacent slices (default: 0.2)

• merge_method (str): Method for merging overlapping predictions - “nms” or “wbf” (default: “nms”)

• nms_threshold (float): IoU threshold for NMS merging (default: 0.5)

• include_full_image (bool): Also run inference on full image (default: True)