Skip to content

Quick Start

Welcome to SAHI! This guide will get you up and running with the core features of the library, including installation, performing predictions, and using the command-line interface.

1. Installation

Install SAHI using pip. For object detection, it's recommended to also install ultralytics.

Install

PyPI - Python Version

Install or update the sahi package using pip by running pip install -U sahi. For more details on the sahi package, visit the Python Package Index (PyPI).

PyPI - Version Downloads

# Install the sahi package from PyPI
pip install sahi

You can also install sahi directly from the Sahi GitHub repository. This can be useful if you want the latest development version. Ensure you have the Git command-line tool installed, and then run:

# Install the sahi package from GitHub
pip install git+https://github.com/obss/sahi.git@main

Conda can be used as an alternative package manager to pip. For more details, visit Anaconda. The Sahi feedstock repository for updating the conda package is available at GitHub.

Conda Version Conda Downloads Conda Recipe Conda Platforms

# Install the sahi package using conda
conda install -c conda-forge sahi

Note

If you are installing in a CUDA environment, it is best practice to install ultralytics, pytorch, and pytorch-cuda in the same command. This allows the conda package manager to resolve any conflicts. Alternatively, install pytorch-cuda last to override the CPU-specific pytorch package if necessary. 

# Install all packages together using conda
conda install -c pytorch -c nvidia -c conda-forge pytorch torchvision pytorch-cuda=11.8 ultralytics

Clone the Sahi GitHub repository if you are interested in contributing to development or wish to experiment with the latest source code. After cloning, navigate into the directory and install the package in editable mode -e using pip.

GitHub last commit GitHub commit activity GitHub contributors

# Clone the sahi repository
git clone https://github.com/obss/sahi

# Navigate to the cloned directory
cd sahi

# Install the package in editable mode for development
pip install -e .

See the sahi pyproject.toml file for a list of dependencies.

2. Sliced Prediction with Python

Sliced inference is the core feature of SAHI, allowing you to detect small objects in large images. Here's a simple example using the Python API:

from sahi import AutoDetectionModel
from sahi.predict import get_sliced_prediction

# Initialize a YOLOv8 model
detection_model = AutoDetectionModel.from_pretrained(
    model_type='yolov8',
    model_path='yolov8n.pt', # or any other YOLOv8 model
    confidence_threshold=0.25,
    device="cuda:0", # or "cpu"
)

# Run sliced prediction
result = get_sliced_prediction(
    "path/to/your/image.jpg",
    detection_model,
    slice_height=512,
    slice_width=512,
    overlap_height_ratio=0.2,
    overlap_width_ratio=0.2
)

# Export visualizations
result.export_visuals(export_dir="demo_data/")

# Get predictions as a list of objects
predictions = result.object_prediction_list

3. Prediction with the CLI

SAHI also provides a powerful command-line interface for quick predictions without writing any Python code.

sahi predict --model_path yolov8n.pt --model_type yolov8 --source /path/to/images/ --slice_height 512 --slice_width 512

This command will run sliced inference on all images in the specified directory and save the results.

Next Steps

You've now seen the basics of SAHI! To dive deeper, check out these resources: