SAHI (Slicing Aided Hyper Inference)

Warnings

• breaking The `confidence_threshold` parameter in `AutoDetectionModel.from_pretrained` changed its behavior or effect. Previously, it might have only filtered detections. Newer versions (around 0.11.27 and later discussions) suggest it can also influence the bounding box size or shape, not just filter by score. Always verify expected behavior for a given SAHI version.
  Fix: Thoroughly test model outputs, especially bounding box coordinates, after upgrading or changing `confidence_threshold` values. If issues arise, convert `PredictionResult` to COCO annotations for manual plotting or analysis to verify results.
• gotcha The `BoundingBox` and `Category` objects were made immutable in versions 0.11.29 and 0.11.31 respectively. Direct modification of their attributes will now raise an error.
  Fix: Instead of modifying `BoundingBox` or `Category` objects directly, create new instances with desired values. For example, use methods like `get_shifted_box()` or create a new `BoundingBox` object.
• gotcha When working in multi-GPU environments, especially with subprocesses or certain frameworks (like Detectron2), models might default to loading on 'cuda:0' causing imbalanced GPU utilization. This was specifically addressed in 0.11.34 for subprocesses.
  Fix: Explicitly set the `device` parameter (e.g., 'cuda:1') when initializing `AutoDetectionModel` to distribute load. For versions prior to 0.11.34, custom scripts might be needed to manage GPU assignments across processes.
• gotcha SAHI significantly increases inference time due to processing multiple slices. It is generally not recommended for real-time applications where latency is critical.
  Fix: Evaluate performance needs carefully. If real-time inference is critical, consider optimizing the base object detection model or using different techniques. If accuracy on small objects outweighs speed, SAHI is appropriate.
• gotcha Some users have reported degraded performance (fewer detections, lower confidence) when applying SAHI to models that already perform well on an original dataset without slicing.
  Fix: Experiment with SAHI's slicing hyperparameters (slice_height, slice_width, overlap_ratios) and post-processing techniques (e.g., NMS thresholds) to optimize for your specific dataset and model. Slicing hyperparameters should align with the model's training input sizes.

Install

• pip install sahi Basic Installation
• pip install sahi[yolov5] For YOLOv5 Support
• pip install sahi[ultralytics] For Ultralytics (YOLOv8, etc.) Support
• pip install sahi[mmdet] For MMDetection Support
• pip install sahi[detectron2] For Detectron2 Support
• pip install sahi[huggingface] For HuggingFace Support
• pip install sahi[torchvision] For TorchVision Support

Imports

• AutoDetectionModel
  wrong:

  from sahi.models import AutoDetectionModel

  correct:

  from sahi import AutoDetectionModel

  `AutoDetectionModel` is directly available under the `sahi` package namespace.
• get_sliced_prediction

  from sahi.predict import get_sliced_prediction

• read_image_as_pil

  from sahi.utils.cv import read_image_as_pil

• download_from_url

  from sahi.utils.file import download_from_url

Quickstart

This quickstart demonstrates how to load a pre-trained model (e.g., YOLOv8s) using `AutoDetectionModel` and perform sliced inference on an image using `get_sliced_prediction`. It includes steps to download a sample image and print/visualize the detection results. Ensure you have the necessary backend (e.g., `ultralytics`) installed for the chosen `model_type`.

import os
import torch
from sahi import AutoDetectionModel
from sahi.predict import get_sliced_prediction
from sahi.utils.cv import read_image
from sahi.utils.file import download_from_url

# Download a sample image
image_url = 'https://raw.githubusercontent.com/obss/sahi/main/demo/demo_data/small-vehicles1.jpeg'
image_path = 'small-vehicles1.jpeg'
download_from_url(image_url, image_path)

# Download a YOLOv8s model (requires ultralytics installed: pip install ultralytics)
model_path = 'yolov8s.pt'
# This utility helps download; in a real scenario, you might have your own model.
if not os.path.exists(model_path):
    # You would typically download a model or use an existing path
    # For this example, we'll try to use a common Ultralytics model.
    # For a real quickstart, ensure 'ultralytics' is installed and `yolov8s.pt` is available.
    print(f"Please ensure '{model_path}' is available or install 'ultralytics' and download it.")
    # Placeholder for actual download if ultralytics is installed
    # from ultralytics import YOLO
    # model = YOLO('yolov8s.pt') # This would download it if not present
    # Then you would pass model.model.pt for model_path or the YOLO object directly to AutoDetectionModel

# Fallback or specific model path if `yolov8s.pt` is not handled by AutoDetectionModel without explicit ultralytics import
# For simplicity, assuming a yolov8s.pt is present or can be loaded by AutoDetectionModel

# Initialize the detection model
device = 'cuda:0' if torch.cuda.is_available() else 'cpu'
detection_model = AutoDetectionModel.from_pretrained(
    model_type='ultralytics', # Or 'yolov5', 'mmdet', 'huggingface', 'torchvision', etc.
    model_path=model_path, # Path to your pretrained model weights
    confidence_threshold=0.3,
    device=device
)

# Perform sliced inference
result = get_sliced_prediction(
    read_image(image_path),
    detection_model,
    slice_height=256,
    slice_width=256,
    overlap_height_ratio=0.2,
    overlap_width_ratio=0.2
)

# Print detection results
print(f"Detected {len(result.object_prediction_list)} objects.")
for i, prediction in enumerate(result.object_prediction_list):
    print(f"  Detection {i+1}: Class={prediction.category.name}, Confidence={prediction.score.value:.3f}")

# Export visuals (optional, requires opencv-python-headless or opencv-python)
output_dir = './sahi_output'
os.makedirs(output_dir, exist_ok=True)
result.export_visuals(export_dir=output_dir, file_name='prediction_visual.png')
print(f"Visualizations saved to {output_dir}/prediction_visual.png")