SAHI - Slicing Aided Hyper Inference

https://github.com/obss/sahi
Admin
A unified vision library providing a common API for multiple object detection and instance...
Tokens:59,422
Snippets:383
Trust Score:7.9
License:MIT
Update:2 weeks ago
Show doc for...
Tokens:
Raw
================
LIBRARY RULES
================
- Use AutoDetectionModel.from_pretrained() to load any model - switch between Ultralytics/HuggingFace/Roboflow/MMDetection models by only changing model_type and model_path
- SAHI provides unified API across frameworks - same predict() function works with YOLO11/YOLO12, Roboflow Universe models, HuggingFace models like ustc-community/dfine-small-coco without code changes
- When using AutoDetectionModel.from_pretrained(): use 'model_path' parameter for file-based models (Ultralytics, HuggingFace), use 'model' parameter for Roboflow Universe models
- For academic papers requiring high mAP: use postprocess_type='NMS', postprocess_match_metric='IOU', and confidence_threshold=0.01
- For real-world applications: use postprocess_type='GREEDYNMM', postprocess_match_metric='IOS' for better performance with fewer false positives
- If getting many false positives in sliced inference, increase slice_height and slice_width values
- If getting multiple predictions on same object, decrease overlap_height_ratio and overlap_width_ratio (try 0.1 instead of 0.2)
- Use no_sliced_prediction=True to disable slicing and only perform standard inference (useful for large objects)
- Use no_standard_prediction=True to disable full-image inference and only use sliced predictions (saves computation when all objects are small)
- Cannot set both no_standard_prediction=True and no_sliced_prediction=True simultaneously
- Auto-slice resolution: if slice_height/slice_width not specified, SAHI automatically calculates optimal values based on image size
- For drone/satellite imagery: typically use slice_size=512-1024 with 0.2-0.3 overlap ratio
- SAHI is beneficial even without slicing - provides unified API, COCO utilities, visualization tools across all detection frameworks
- Use min_area_ratio parameter (default 0.1) to filter out partial objects at slice boundaries - lower values keep more edge objects
- For COCO datasets, always validate annotations with coco.stats before training or evaluation
- Export results in COCO format using dataset_json_path parameter for standardized evaluation
- Use visual_bbox_thickness, visual_text_size parameters to customize prediction visualizations
- Use 'sahi predict-fiftyone' command to visualize predictions interactively and sort by false positives
- Use 'sahi coco fiftyone' to compare multiple model predictions side-by-side in FiftyOne app
- Use 'sahi coco evaluate' for comprehensive COCO metrics with classwise AP/AR and custom IoU thresholds
- Use 'sahi coco analyse' to generate error analysis plots showing C75/C50/Localization/Similar/Other/Background/FalseNegative errors
- For error analysis: plots show performance breakdown by object size (small/medium/large) and error types
- Export predictions as cropped images using export_crop=True for dataset creation or further analysis
- For video inference: use frame_skip_interval to speed up processing, view_video=True for real-time display
- Supports latest models: YOLO11/YOLO12 via model_type='ultralytics', Roboflow Universe models (e.g., RF-DETR) via model_type='roboflow', HuggingFace models like 'ustc-community/dfine-small-coco' via model_type='huggingface'
- For YOLO11/YOLO12 OBB (oriented bounding box) models, SAHI automatically handles rotated box predictions and only supports NMS postprocessing
- Example model loading: model_type='ultralytics' with model_path='yolo11n.pt', model_type='huggingface' with model_path='ustc-community/dfine-small-coco', model_type='roboflow' with model='rfdetr-base'
- Roboflow Universe models: use simple string IDs like 'rfdetr-base' with model_type='roboflow' for easy access to pre-trained models
- Complete example: model = AutoDetectionModel.from_pretrained(model_type='roboflow', model='rfdetr-base', confidence_threshold=0.5)
- All models follow same API pattern: AutoDetectionModel.from_pretrained() → get_prediction() or get_sliced_prediction() → visualize results
- For models without built-in category mappings, provide category_mapping parameter (e.g., COCO_CLASSES from rfdetr.util.coco_classes)
- COCO utilities: merge datasets with coco.merge(), split train/val with split_coco_as_train_val(), filter by categories with update_categories()
- Filter COCO annotations by area using get_area_filtered_coco() - useful for focusing on specific object sizes
- Convert between formats: export_as_yolo() for YOLO format, use 'sahi coco yolo' command for batch conversion
- Use Coco.stats to get comprehensive dataset statistics before training (num annotations, area distribution, etc.)
- Import logger from 'from sahi.logging import logger' instead of creating redundant logging configurations - centralized logging system eliminates duplicate imports across codebase
- For SAHI documentation, direct users to https://obss.github.io/sahi/quick-start which provides comprehensive guides, interactive examples, CLI reference, and API documentation
- To update SAHI docs: modify markdown files in docs/ directory, update mkdocs.yml for navigation changes, ensure .github/workflows/publish_docs.yml deploys correctly to GitHub Pages

================
CODE SNIPPETS
================
### Basic Installation: pip install sahi

Source: https://github.com/obss/sahi/blob/main/README.md

Installs the SAHI library via pip. This is the standard installation command for most users.

```bash
pip install sahi
```

--------------------------------

### Install Detectron2

Source: https://github.com/obss/sahi/blob/main/docs/guides/models.md

Install the Detectron2 package.

```bash
pip install detectron2
```

--------------------------------

### Detailed Installation: ultralytics detection framework

Source: https://github.com/obss/sahi/blob/main/README.md

Installs the ultralytics detection framework with a minimum version of 8.3.161.

```console
pip install ultralytics>=8.3.161
```

--------------------------------

### Install TorchVision

Source: https://github.com/obss/sahi/blob/main/docs/guides/models.md

Install torch and torchvision to use built-in detection models.

```bash
pip install torch torchvision
```

--------------------------------

### Detailed Installation: huggingface detection framework

Source: https://github.com/obss/sahi/blob/main/README.md

Installs the huggingface transformers library (>=4.49.0) and timm for detection support.

```console
pip install transformers>=4.49.0 timm
```

--------------------------------

### Install HuggingFace dependencies

Source: https://github.com/obss/sahi/blob/main/docs/guides/models.md

Install the required transformers and timm libraries via pip.

```bash
pip install transformers timm
```

--------------------------------

### Install Ultralytics

Source: https://github.com/obss/sahi/blob/main/docs/guides/models.md

Install the ultralytics package to enable support for YOLO models.

```bash
pip install ultralytics
```

--------------------------------

### Install SAHI with Ultralytics support

Source: https://github.com/obss/sahi/blob/main/docs/quick-start.md

Install the SAHI package with the ultralytics extra to enable support for YOLO models.

```bash
pip install "sahi[ultralytics]"
```

--------------------------------

### Install MMDetection dependencies

Source: https://github.com/obss/sahi/blob/main/docs/guides/models.md

Install the required packages for MMDetection support.

```bash
pip install mmdet mmcv mmengine
```

--------------------------------

### Detailed Installation: yolov5 detection framework

Source: https://github.com/obss/sahi/blob/main/README.md

Installs yolov5 version 7.0.14 and sahi version 0.12.1 for yolov5 support.

```console
pip install yolov5==7.0.14 sahi==0.12.1
```

--------------------------------

### Install YOLOv5 Package

Source: https://github.com/obss/sahi/blob/main/docs/guides/models.md

Install the yolov5 package to enable support for classic YOLOv5 models.

```bash
pip install yolov5
```

--------------------------------

### Install Roboflow RF-DETR

Source: https://github.com/obss/sahi/blob/main/docs/guides/models.md

Install the rfdetr package.

```bash
pip install rfdetr
```

--------------------------------

### Install LibreYOLO

Source: https://github.com/obss/sahi/blob/main/docs/guides/models.md

Install the LibreYOLO package to access MIT-licensed YOLO models.

```bash
pip install libreyolo
```

--------------------------------

### Clone SAHI repository and run notebooks locally

Source: https://github.com/obss/sahi/blob/main/docs/notebooks.md

Commands to clone the SAHI repository, install development dependencies with uv, and launch Jupyter notebooks from the demo directory.

```bash
git clone https://github.com/obss/sahi.git
cd sahi
uv sync --group dev
jupyter notebook demo/
```

--------------------------------

### Example output of sahi env

Source: https://github.com/obss/sahi/blob/main/docs/cli.md

Example output from the sahi env command, showing the versions of torch, torchvision, ultralytics, transformers, timm, and fiftyone.

```text
06/19/2022 21:24:52 - INFO - sahi.utils.import_utils -   torch version 2.1.2 is available.
06/19/2022 21:24:52 - INFO - sahi.utils.import_utils -   torchvision version 0.16.2 is available.
06/19/2022 21:24:52 - INFO - sahi.utils.import_utils -   ultralytics version 8.3.86 is available.
06/19/2022 21:24:52 - INFO - sahi.utils.import_utils -   transformers version 4.49.0 is available.
06/19/2022 21:24:52 - INFO - sahi.utils.import_utils -   timm version 0.9.1 is available.
06/19/2022 21:24:52 - INFO - sahi.utils.import_utils -   fiftyone version 0.14.2 is available.
```

--------------------------------

### Detailed Installation: mmdet detection framework

Source: https://github.com/obss/sahi/blob/main/README.md

Installs mmdet version 3.3.0 using the mim package manager.

```console
pip install mim
mim install mmdet==3.3.0
```

--------------------------------

### Detailed Installation: PyTorch and torchvision (CUDA 13.0)

Source: https://github.com/obss/sahi/blob/main/README.md

Installs PyTorch 2.13.0 and torchvision 0.28.0 from the PyTorch index for CUDA 13.0. This is part of the detailed installation steps.

```console
pip install torch==2.13.0 torchvision==0.28.0 --index-url https://download.pytorch.org/whl/cu130
```

--------------------------------

### Detailed Installation: roboflow detection framework

Source: https://github.com/obss/sahi/blob/main/README.md

Installs the roboflow inference library (>=0.51.5) and rfdetr (>=1.6.2) for detection support.

```console
pip install inference>=0.51.5 rfdetr>=1.6.2
```

--------------------------------

### Install and run SAHI COCO evaluation with ultrafast backend

Source: https://github.com/obss/sahi/blob/main/docs/coco.md

Installs the optional ultrafast-pycocotools backend and runs the SAHI evaluation command with the ultrafast backend. Requires version 0.1.11 or newer.

```bash
pip install "sahi[ultrafast]"
sahi coco evaluate --dataset_json_path coco_dataset.json \
  --result_json_path coco_predictions.json --backend ultrafast
```

--------------------------------

### Run sahi env to display package versions

Source: https://github.com/obss/sahi/blob/main/docs/cli.md

Displays installed package versions related to SAHI. The output shows the versions of torch, torchvision, ultralytics, transformers, timm, and fiftyone.

```bash
sahi env
```

--------------------------------

### Check SAHI version with CLI

Source: https://github.com/obss/sahi/blob/main/docs/cli.md

Run this command to display the currently installed SAHI version.

```bash
sahi version
```

--------------------------------

### sahi env

Source: https://github.com/obss/sahi/blob/main/docs/cli.md

Displays installed package versions related to SAHI.

```APIDOC
## sahi env

### Description
Displays installed package versions related to SAHI.

### Usage
```bash
sahi env
```

### Example Output
```text
06/19/2022 21:24:52 - INFO - sahi.utils.import_utils -   torch version 2.1.2 is available.
06/19/2022 21:24:52 - INFO - sahi.utils.import_utils -   torchvision version 0.16.2 is available.
06/19/2022 21:24:52 - INFO - sahi.utils.import_utils -   ultralytics version 8.3.86 is available.
06/19/2022 21:24:52 - INFO - sahi.utils.import_utils -   transformers version 4.49.0 is available.
06/19/2022 21:24:52 - INFO - sahi.utils.import_utils -   timm version 0.9.1 is available.
06/19/2022 21:24:52 - INFO - sahi.utils.import_utils -   fiftyone version 0.14.2 is available.
```
```

--------------------------------

### Run a custom SAHI script

Source: https://github.com/obss/sahi/blob/main/docs/cli.md

After installing SAHI via pip, run any script from the scripts directory from any directory using Python.

```bash
python script_name.py
```

--------------------------------

### Detailed Installation: PyTorch and torchvision (CUDA 12.1) for mmdet

Source: https://github.com/obss/sahi/blob/main/README.md

Installs PyTorch 2.1.2 and torchvision 0.16.2 from the PyTorch index for CUDA 12.1. This version is required for mmdet support.

```console
pip install torch==2.1.2 torchvision==0.16.2 --index-url https://download.pytorch.org/whl/cu121
```

--------------------------------

### Pin torchvision backend for a full inference run

Source: https://github.com/obss/sahi/blob/main/docs/postprocess/backends.md

Example of pinning the torchvision backend for a full inference run using AutoDetectionModel and get_sliced_prediction. Use this when running on a CUDA or Apple Silicon machine to leverage GPU-accelerated postprocessing.

```python
from sahi import AutoDetectionModel
from sahi.predict import get_sliced_prediction
from sahi.postprocess.backends import set_postprocess_backend

# Use GPU-accelerated postprocessing when running on a CUDA or Apple Silicon machine
set_postprocess_backend("torchvision")

detection_model = AutoDetectionModel.from_pretrained(
    model_type="ultralytics",
    model_path="yolo26n.pt",
    confidence_threshold=0.25,
    device="cuda:0",
)

result = get_sliced_prediction(
    "image.jpg",
    detection_model,
    slice_height=512,
    slice_width=512,
    overlap_height_ratio=0.2,
    overlap_width_ratio=0.2,
)
```

--------------------------------

### get_sliced_prediction with progress options

Source: https://github.com/obss/sahi/blob/main/docs/predict.md

Example showing how to use progress_bar and progress_callback parameters when calling get_sliced_prediction to receive progress updates during sliced inference.

```APIDOC
## get_sliced_prediction

### Description
Runs sliced inference over an image and supports progress reporting via a tqdm bar and/or a custom callback function.

### Parameters
- **progress_bar** (bool) - Optional - When True, shows a tqdm progress bar during slice processing. Default is False.
- **progress_callback** (callable) - Optional - A callback function called after each slice (or slice group) is processed. Receives two integer arguments: (current_slice_index, total_slices).

### Request Example
```python
from sahi.predict import get_sliced_prediction
from sahi import AutoDetectionModel

# init model
detection_model = AutoDetectionModel.from_pretrained(...)

def my_progress_callback(current, total):
    print(f"Processed {current}/{total} slices")

result = get_sliced_prediction(
    image,
    detection_model,
    slice_height=512,
    slice_width=512,
    overlap_height_ratio=0.2,
    overlap_width_ratio=0.2,
    progress_bar=False,           # disable tqdm bar
    progress_callback=my_progress_callback,  # use callback to receive updates
)
```

### Notes
- `progress_bar` and `progress_callback` can be used together. When both are provided, the tqdm bar will display and the callback will be called after each slice group is processed.
- The `progress_callback` is called with 1-based indices, so the first call will be `(1, total)`.
```

--------------------------------

### Pass a pre-loaded YOLO model to AutoDetectionModel.from_pretrained

Source: https://github.com/obss/sahi/blob/main/docs/guides/models.md

Use this snippet when you already have a YOLO model instance and want to pass it directly to AutoDetectionModel.from_pretrained() instead of a model path. The example sets confidence_threshold to 0.25 and device to 'cuda:0'.

```python
from ultralytics import YOLO

yolo_model = YOLO("yolo26n.pt")
# ... customize the model ...

detection_model = AutoDetectionModel.from_pretrained(
    model_type="ultralytics",
    model=yolo_model,
    confidence_threshold=0.25,
    device="cuda:0",
)
```

--------------------------------

### get_prediction and result export methods

Source: https://github.com/obss/sahi/blob/main/docs/predict.md

Demonstrates how to get a prediction and export results with custom visualization parameters and in various formats.

```APIDOC
## get_prediction

### Description
Runs prediction on an image using a detection model and returns a result object that can be exported in various formats.

### Method
Function call

### Endpoint
from sahi.predict import get_prediction

### Parameters
#### Function Parameters
- **image** (Image) - Required - Input image
- **detection_model** (AutoDetectionModel) - Required - Detection model initialized via AutoDetectionModel.from_pretrained

### Request Example
```python
from sahi.predict import get_prediction
from sahi import AutoDetectionModel
from PIL import Image

# init a model
detection_model = AutoDetectionModel.from_pretrained(...)

# get prediction result
result = get_prediction(
    image,
    detection_model,
)
```

### Response
Returns a prediction result object.

## result.export_visuals

### Description
Exports the prediction result as a visual image with custom visualization parameters.

### Method
Method call

### Endpoint
result.export_visuals(export_dir, text_size, rect_th, hide_labels, hide_conf, file_name)

### Parameters
#### Method Parameters
- **export_dir** (str) - Required - Directory to export the visual
- **text_size** (float) - Optional - Size of the class label text (default 1.0)
- **rect_th** (int) - Optional - Thickness of bounding box lines (default 2)
- **hide_labels** (bool) - Optional - Set True to hide class labels (default False)
- **hide_conf** (bool) - Optional - Set True to hide confidence scores (default False)
- **file_name** (str) - Optional - Name of the exported file (default "custom_visualization")

### Request Example
```python
result.export_visuals(
    export_dir="outputs/",
    text_size=1.0,
    rect_th=2,
    hide_labels=False,
    hide_conf=False,
    file_name="custom_visualization",
)
```

### Response
Exports the visual to the specified directory.

## result.to_coco_annotations

### Description
Exports the prediction result as COCO format annotations.

### Method
Method call

### Endpoint
result.to_coco_annotations()

### Request Example
```python
coco_annotations = result.to_coco_annotations()
```

### Response
Returns a list of COCO annotation dictionaries. Example output: [{'image_id': None, 'bbox': [x, y, width, height], 'category_id': 0, 'area': width*height, ...}]

## result.to_coco_predictions

### Description
Exports the prediction result as COCO predictions, including confidence scores.

### Method
Method call

### Endpoint
result.to_coco_predictions(image_id)

### Parameters
#### Method Parameters
- **image_id** (int) - Required - Image ID for the predictions

### Request Example
```python
coco_predictions = result.to_coco_predictions(image_id=1)
```

### Response
Returns a list of COCO prediction dictionaries. Example output: [{'image_id': 1, 'bbox': [x, y, width, height], 'score': 0.98, 'category_id': 0, ...}]

## result.to_imantics_annotations

### Description
Exports the prediction result in imantics format for use with the imantics library.

### Method
Method call

### Endpoint
result.to_imantics_annotations()

### Request Example
```python
imantics_annotations = result.to_imantics_annotations()
```

### Response
Returns imantics annotations.

## result.to_fiftyone_detections

### Description
Exports the prediction result for FiftyOne visualization.

### Method
Method call

### Endpoint
result.to_fiftyone_detections()

### Request Example
```python
fiftyone_detections = result.to_fiftyone_detections()
```

### Response
Returns FiftyOne detections.
```

--------------------------------

### Using progress_callback with get_sliced_prediction

Source: https://github.com/obss/sahi/blob/main/docs/predict.md

Example of using the progress_callback parameter in get_sliced_prediction to receive progress updates. The callback receives 1-based indices (current, total). progress_bar is set to False to disable the tqdm bar, but both can be used together.

```python
from sahi.predict import get_sliced_prediction
from sahi import AutoDetectionModel

# init model
detection_model = AutoDetectionModel.from_pretrained(...)

def my_progress_callback(current, total):
    print(f"Processed {current}/{total} slices")

result = get_sliced_prediction(
    image,
    detection_model,
    slice_height=512,
    slice_width=512,
    overlap_height_ratio=0.2,
    overlap_width_ratio=0.2,
    progress_bar=False,           # disable tqdm bar
    progress_callback=my_progress_callback,  # use callback to receive updates
)
```

--------------------------------

### Sliced inference with get_sliced_prediction

Source: https://github.com/obss/sahi/blob/main/docs/predict.md

Initialize a detection model with AutoDetectionModel.from_pretrained for various model types (mmdet, ultralytics, huggingface, torchvision, rtdetr, librelyolo, yoloe, yolov5, yolo-world, roboflow) and then call get_sliced_prediction with slice dimensions and overlap ratios. The example uses slice_height=256, slice_width=256, and overlap ratios of 0.2.

```python
from sahi.predict import get_sliced_prediction
from sahi import AutoDetectionModel

# init any model
detection_model = AutoDetectionModel.from_pretrained(model_type='mmdet',...) # for MMDetection models
detection_model = AutoDetectionModel.from_pretrained(model_type='ultralytics',...) # for YOLOv8/YOLO11/YOLO26 models
detection_model = AutoDetectionModel.from_pretrained(model_type='huggingface',...) # for HuggingFace detection models
detection_model = AutoDetectionModel.from_pretrained(model_type='torchvision',...) # for Torchvision detection models
detection_model = AutoDetectionModel.from_pretrained(model_type='rtdetr',...) # for RT-DETR models
detection_model = AutoDetectionModel.from_pretrained(model_type='libreyolo',...) # for LibreYOLO models
detection_model = AutoDetectionModel.from_pretrained(model_type='yoloe',...) # for YOLOE models
detection_model = AutoDetectionModel.from_pretrained(model_type='yolov5',...) # for YOLOv5 models
detection_model = AutoDetectionModel.from_pretrained(model_type='yolo-world',...) # for YOLOWorld models
detection_model = AutoDetectionModel.from_pretrained(model_type='roboflow',...) # for Roboflow RFDETR detection/segmentation models

# get sliced prediction result
result = get_sliced_prediction(
    image,
    detection_model,
    slice_height = 256,
    slice_width = 256,
    overlap_height_ratio = 0.2,
    overlap_width_ratio = 0.2
)

```

--------------------------------

### Using NMSPostprocess, GreedyNMMPostprocess, and NMMPostprocess

Source: https://github.com/obss/sahi/blob/main/docs/postprocess/backends.md

Shows how to instantiate and use the three postprocessors. NMSPostprocess keeps the best box and discards the rest, with match_threshold and match_metric parameters; class_agnostic=True means per-category suppression is disabled. GreedyNMMPostprocess merges overlapping boxes quickly, and NMMPostprocess performs transitive merging. The class_agnostic=False option makes each postprocessor run independently per category.

```python
from sahi.postprocess.combine import NMSPostprocess, NMMPostprocess, GreedyNMMPostprocess

# NMS, keep the best box, discard the rest
postprocessor = NMSPostprocess(
    match_threshold=0.5,
    match_metric="IOU",
    class_agnostic=True,   # False → per-category
)
filtered = postprocessor(object_prediction_list)

# Greedy NMM, merge overlapping boxes (fast)
postprocessor = GreedyNMMPostprocess(match_threshold=0.5)
merged = postprocessor(object_prediction_list)

# Full NMM, transitive merging
postprocessor = NMMPostprocess(match_threshold=0.5)
merged = postprocessor(object_prediction_list)
```

--------------------------------

### Initialize GroundingDINO model with text labels

Source: https://github.com/obss/sahi/blob/main/docs/guides/models.md

Configure a GroundingDINO model with specific text labels for zero-shot detection.

```python
detection_model = AutoDetectionModel.from_pretrained(
    model_type="huggingface",
    model_path="IDEA-Research/grounding-dino-tiny",
    confidence_threshold=0.25,
    text_threshold=0.20,
    text_labels=["car", "truck", "person"],
    device="cuda:0",
)
```

--------------------------------

### Launch FiftyOne app for COCO dataset

Source: https://github.com/obss/sahi/blob/main/docs/fiftyone.md

Use launch_fiftyone_app from sahi.utils.fiftyone to open a FiftyOne session for a COCO dataset. Requires fiftyone>=0.14.2,<0.15.0. Close the session when done.

```python
from sahi.utils.fiftyone import launch_fiftyone_app

# Launch the FiftyOne app with your COCO dataset
session = launch_fiftyone_app(coco_image_dir, coco_json_path)

# When done, close the session
session.close()
```

--------------------------------

### Initialize and run HuggingFace detection model

Source: https://github.com/obss/sahi/blob/main/docs/guides/models.md

Load a pretrained HuggingFace model and perform sliced prediction on an image.

```python
detection_model = AutoDetectionModel.from_pretrained(
    model_type="huggingface",
    model_path="facebook/detr-resnet-50",
    confidence_threshold=0.3,
    device="cuda:0",
)

result = get_sliced_prediction(
    "image.jpg",
    detection_model,
    slice_height=512,
    slice_width=512,
)
```

--------------------------------

### Initialize Roboflow Universe model

Source: https://github.com/obss/sahi/blob/main/docs/guides/models.md

Configure a Roboflow Universe model using an API key.

```python
detection_model = AutoDetectionModel.from_pretrained(
    model_type="roboflow",
    model="rfdetr-base",  # Universe model id
    api_key="YOUR_API_KEY",  # or set ROBOFLOW_API_KEY
    confidence_threshold=0.3,
    device="cuda:0",
)
```

--------------------------------

### Load and Run Ultralytics Model

Source: https://github.com/obss/sahi/blob/main/docs/guides/models.md

Initialize an Ultralytics model using AutoDetectionModel and perform sliced prediction on an image.

```python
from sahi import AutoDetectionModel
from sahi.predict import get_sliced_prediction

detection_model = AutoDetectionModel.from_pretrained(
    model_type="ultralytics",
    model_path="yolo26n.pt",
    confidence_threshold=0.25,
    device="cuda:0",  # or "cpu"
)

result = get_sliced_prediction(
    "image.jpg",
    detection_model,
    slice_height=512,
    slice_width=512,
    overlap_height_ratio=0.2,
    overlap_width_ratio=0.2,
)
```

--------------------------------

### Run Detectron2 sliced inference

Source: https://github.com/obss/sahi/blob/main/docs/guides/models.md

Initialize the Detectron2 model and perform sliced prediction.

```python
detection_model = AutoDetectionModel.from_pretrained(
    model_type="detectron2",
    model_path="path/to/model_final.pth",
    config_path="path/to/config.yaml",
    confidence_threshold=0.25,
    device="cuda:0",
)

result = get_sliced_prediction(
    "image.jpg",
    detection_model,
    slice_height=512,
    slice_width=512,
)
```

--------------------------------

### Initialize local Roboflow model

Source: https://github.com/obss/sahi/blob/main/docs/guides/models.md

Configure a local RF-DETR model using local weights and category mapping.

```python
detection_model = AutoDetectionModel.from_pretrained(
    model_type="roboflow",
    model="RFDETRSegMedium",  # RF-DETR class name, or the class/instance itself
    model_path="checkpoint.pth",  # your locally trained weights
    category_mapping={"0": "cat", "1": "dog"},  # required for custom classes
    image_size=640,  # must match the training resolution
    confidence_threshold=0.3,
    device="cuda:0",
)
```

--------------------------------

### Initialize and run HuggingFace segmentation

Source: https://github.com/obss/sahi/blob/main/docs/guides/models.md

Configure the AutoDetectionModel with a HuggingFace checkpoint and perform sliced inference using get_sliced_prediction.

```python
from sahi.models.huggingface_segmentation import SegmentationType

detection_model = AutoDetectionModel.from_pretrained(
    model_type="huggingface_segmentation",
    model_path="facebook/mask2former-swin-tiny-coco-instance",
    confidence_threshold=0.5,
    device="cuda:0",
    segmentation_type=SegmentationType.INSTANCE_SEGMENTATION,
)

result = get_sliced_prediction(
    "image.jpg",
    detection_model,
    slice_height=512,
    slice_width=512,
)
```

--------------------------------

### Run YOLO-World Sliced Prediction

Source: https://github.com/obss/sahi/blob/main/docs/guides/models.md

Initialize the YOLO-World zero-shot detection model and perform sliced prediction.

```python
detection_model = AutoDetectionModel.from_pretrained(
    model_type="yolo-world",
    model_path="yolov8s-worldv2.pt",
    confidence_threshold=0.1,
    device="cuda:0",
)

result = get_sliced_prediction(
    "image.jpg",
    detection_model,
    slice_height=512,
    slice_width=512,
)
```

--------------------------------

### NMM variants: greedy_nmm, nmm, batched_greedy_nmm

Source: https://github.com/obss/sahi/blob/main/docs/postprocess/backends.md

Shows how to merge overlapping boxes instead of discarding them. greedy_nmm merges only direct neighbours (fast, tight boxes), nmm performs transitive merging (A merges B, B merges C -> A gets all three), and batched_greedy_nmm does per-category greedy merging. All use match_metric='IOU' and match_threshold=0.5.

```python
from sahi.postprocess.combine import greedy_nmm, nmm, batched_greedy_nmm

# Greedy NMM: each kept box merges only its direct neighbours (fast, tight boxes)
keep_to_merge = greedy_nmm(predictions, match_metric="IOU", match_threshold=0.5)
# {kept_index: [merged_index, ...], ...}

# Full NMM: transitive merging (A merges B, B merges C → A gets all three)
keep_to_merge = nmm(predictions, match_metric="IOU", match_threshold=0.5)

# Per-category greedy NMM
keep_to_merge = batched_greedy_nmm(predictions, match_threshold=0.5)
```

--------------------------------

### Predict and explore in one step with predict-fiftyone

Source: https://github.com/obss/sahi/blob/main/docs/fiftyone.md

Run sliced inference and open results in FiftyOne directly using the predict-fiftyone CLI command.

```bash
sahi predict-fiftyone \
  --image_dir images/ \
  --dataset_json_path dataset.json \
  --model_path yolo26n.pt \
  --model_type ultralytics \
  --slice_height 512 \
  --slice_width 512
```

--------------------------------

### NMS and batched NMS with numpy predictions

Source: https://github.com/obss/sahi/blob/main/docs/postprocess/backends.md

Shows how to run global NMS and per-category NMS on an (N, 6) numpy array. The predictions array is defined inline. Global NMS makes all categories compete together, while batched_nms treats each category independently. Both use match_metric='IOU' and match_threshold=0.5.

```python
import numpy as np
from sahi.postprocess.combine import nms, batched_nms

predictions = np.array([
    [100, 100, 200, 200, 0.95, 0],
    [105, 105, 205, 205, 0.80, 0],
    [300, 300, 400, 400, 0.90, 1],
])

# Global NMS, all categories compete together
keep = nms(predictions, match_metric="IOU", match_threshold=0.5)
print(predictions[keep])

# Per-category NMS, class 0 and class 1 are treated independently
keep = batched_nms(predictions, match_metric="IOU", match_threshold=0.5)
print(predictions[keep])
```

--------------------------------

### Run sliced inference with FiftyOne visualization

Source: https://github.com/obss/sahi/blob/main/docs/cli.md

Basic usage of `sahi predict-fiftyone` to perform sliced inference with default parameters and launch the FiftyOne App for interactive exploration.

```bash
sahi predict-fiftyone --image_dir image/file/or/folder \
  --dataset_json_path dataset.json \
  --model_path path/to/model \
  --model_config_path path/to/config
```

--------------------------------

### Run LibreYOLO Sliced Inference

Source: https://github.com/obss/sahi/blob/main/docs/guides/models.md

Initialize the LibreYOLO detection model and perform sliced prediction on an image.

```python
detection_model = AutoDetectionModel.from_pretrained(
    model_type="libreyolo",
    model_path="LibreYOLO9t.pt",
    confidence_threshold=0.3,
    device="cuda:0",
)

result = get_sliced_prediction(
    "image.jpg",
    detection_model,
    slice_height=512,
    slice_width=512,
)
```

--------------------------------

### Run YOLOv5 Sliced Prediction

Source: https://github.com/obss/sahi/blob/main/docs/guides/models.md

Initialize the YOLOv5 detection model and perform sliced prediction on an image.

```python
detection_model = AutoDetectionModel.from_pretrained(
    model_type="yolov5",
    model_path="yolov5s.pt",
    confidence_threshold=0.25,
    device="cuda:0",
)

result = get_sliced_prediction(
    "image.jpg",
    detection_model,
    slice_height=512,
    slice_width=512,
)
```

--------------------------------

### Create COCO dataset with categories, annotations, and predictions

Source: https://github.com/obss/sahi/blob/main/docs/coco.md

Initializes a COCO dataset, adds categories, an image, ground-truth annotations, and a prediction, then exports the dataset and predictions as JSON files.

```python
from sahi.utils.coco import Coco, CocoCategory, CocoImage, CocoAnnotation, CocoPrediction
from sahi.utils.file import save_json

# Initialize a COCO dataset and add categories
coco = Coco()
coco.add_category(CocoCategory(id=0, name="human"))
coco.add_category(CocoCategory(id=1, name="vehicle"))

# Create an image entry
coco_image = CocoImage(file_name="image1.jpg", height=1080, width=1920)

# Add ground-truth annotations
coco_image.add_annotation(
    CocoAnnotation(bbox=[x_min, y_min, width, height], category_id=0, category_name="human")
)
coco_image.add_annotation(
    CocoAnnotation(bbox=[x_min, y_min, width, height], category_id=1, category_name="vehicle")
)

# Add model predictions (with confidence scores)
coco_image.add_prediction(
    CocoPrediction(score=0.86, bbox=[x_min, y_min, width, height], category_id=0, category_name="human")
)

# Add the image to the dataset
coco.add_image(coco_image)

# Export as JSON
save_json(coco.json, "coco_dataset.json")

# Export predictions in COCO result format
save_json(coco.prediction_array, "coco_predictions.json")
```

--------------------------------

### AutoDetectionModel.from_pretrained (HuggingFace)

Source: https://github.com/obss/sahi/blob/main/docs/guides/models.md

Loads a HuggingFace object detection model for use with SAHI. Supports DETR, Deformable DETR, DETA, GroundingDINO, etc.

```APIDOC
## AutoDetectionModel.from_pretrained

### Description
Loads a HuggingFace object detection model for use with SAHI. Supports DETR, Deformable DETR, DETA, GroundingDINO, etc.

### Method
from_pretrained

### Parameters
#### Common Parameters
- **model_type** (string) - Required - Set to "huggingface"
- **model_path** (string) - Required - HuggingFace model identifier or path
- **confidence_threshold** (float) - Optional - Minimum confidence score for detections
- **device** (string) - Optional - Device to run inference on (e.g., "cuda:0")

#### Zero-shot Parameters (GroundingDINO)
- **text_labels** (list[str]) - Optional - Fixed categories to detect, e.g. ["car", "truck"]. Each gets a stable category id; phrases outside this list are dropped
- **text_prompt** (string) - Optional - Free-form prompt (e.g. "a car. a truck.") used when text_labels is not set; returned phrases become categories dynamically
- **text_threshold** (float) - Optional - Minimum score for matching a box to a text token (default: 0.25)

### Request Example
```python
detection_model = AutoDetectionModel.from_pretrained(
    model_type="huggingface",
    model_path="facebook/detr-resnet-50",
    confidence_threshold=0.3,
    device="cuda:0",
)
```

### Response
Returns a detection model object that can be passed to get_sliced_prediction.

```

--------------------------------

### Run TorchVision Sliced Inference

Source: https://github.com/obss/sahi/blob/main/docs/guides/models.md

Initialize a TorchVision detection model and perform sliced prediction on an image.

```python
detection_model = AutoDetectionModel.from_pretrained(
    model_type="torchvision",
    model_path="fasterrcnn_resnet50_fpn",
    confidence_threshold=0.3,
    device="cuda:0",
)

result = get_sliced_prediction(
    "image.jpg",
    detection_model,
    slice_height=512,
    slice_width=512,
)
```

--------------------------------

### Standard inference with get_prediction

Source: https://github.com/obss/sahi/blob/main/docs/predict.md

Initializes a detection model with AutoDetectionModel.from_pretrained and runs standard (non-sliced) prediction on a single image using get_prediction. The model initialization requires a pretrained model specification.

```python
from sahi.predict import get_prediction
from sahi import AutoDetectionModel

# init a model
detection_model = AutoDetectionModel.from_pretrained(...)

# get standard prediction result
result = get_prediction(
    image,
    detection_model,
)

```

--------------------------------

### Run MMDetection sliced inference

Source: https://github.com/obss/sahi/blob/main/docs/guides/models.md

Initialize the MMDetection model and perform sliced prediction.

```python
detection_model = AutoDetectionModel.from_pretrained(
    model_type="mmdet",
    model_path="path/to/checkpoint.pth",
    config_path="path/to/config.py",
    confidence_threshold=0.25,
    device="cuda:0",
)

result = get_sliced_prediction(
    "image.jpg",
    detection_model,
    slice_height=512,
    slice_width=512,
)
```

--------------------------------

### Run YOLOE Sliced Prediction

Source: https://github.com/obss/sahi/blob/main/docs/guides/models.md

Initialize the YOLOE detection model and perform sliced prediction on an image.

```python
detection_model = AutoDetectionModel.from_pretrained(
    model_type="yoloe",
    model_path="yoloe-v8l-seg.pt",
    confidence_threshold=0.25,
    device="cuda:0",
)

result = get_sliced_prediction(
    "image.jpg",
    detection_model,
    slice_height=512,
    slice_width=512,
)
```

--------------------------------

### Run sliced prediction with Python

Source: https://github.com/obss/sahi/blob/main/docs/quick-start.md

Downloads a sample image and performs sliced inference using an Ultralytics model on the CPU.

```python
from sahi import AutoDetectionModel
from sahi.predict import get_sliced_prediction
from sahi.utils.file import download_from_url

download_from_url(
    "https://raw.githubusercontent.com/obss/sahi/main/demo/demo_data/small-vehicles1.jpeg",
    "demo_data/small-vehicles1.jpeg",
)

detection_model = AutoDetectionModel.from_pretrained(
    model_type="ultralytics",
    model_path="yolo26n.pt",
    confidence_threshold=0.25,
    device="cpu",  # or "cuda:0"
)

result = get_sliced_prediction(
    "demo_data/small-vehicles1.jpeg",
    detection_model,
    slice_height=512,
    slice_width=512,
    overlap_height_ratio=0.2,
    overlap_width_ratio=0.2,
)
```

--------------------------------

### Basic predict command

Source: https://github.com/obss/sahi/blob/main/docs/cli.md

Performs sliced inference with default parameters and exports prediction visuals to `runs/predict/exp` folder.

```bash
sahi predict --source image/file/or/folder --model_path path/to/model --model_config_path path/to/config
```

--------------------------------

### AutoDetectionModel.from_pretrained (huggingface_segmentation)

Source: https://github.com/obss/sahi/blob/main/docs/guides/models.md

Initializes a HuggingFace segmentation model for use with SAHI. Supports instance, semantic, and panoptic segmentation depending on the checkpoint and segmentation_type parameter.

```APIDOC
## AutoDetectionModel.from_pretrained

### Description
Initializes a HuggingFace segmentation model for use with SAHI. Supports instance, semantic, and panoptic segmentation depending on the checkpoint and segmentation_type parameter.

### Method
from_pretrained

### Parameters
#### Model Parameters
- **model_type** (string) - Required - Set to "huggingface_segmentation"
- **model_path** (string) - Required - HuggingFace model identifier (e.g., "facebook/mask2former-swin-tiny-coco-instance")
- **confidence_threshold** (float) - Optional - Confidence threshold for predictions (e.g., 0.5)
- **device** (string) - Optional - Device to run inference on (e.g., "cuda:0")
- **segmentation_type** (SegmentationType) - Optional - INSTANCE_SEGMENTATION (default), SEMANTIC_SEGMENTATION, or PANOPTIC_SEGMENTATION
- **min_segment_area** (int) - Optional - Drop segments smaller than this many pixels (default: 100)
- **overlap_mask_area_threshold** (float) - Optional - Merge/discard disconnected parts within a mask (default: 0.8)
- **label_ids_to_fuse** (list[int]) - Optional - Panoptic only, fuses all instances of these labels into one segment
- **token** (string) - Optional - HuggingFace access token for gated/private models (falls back to $HF_TOKEN)

### Request Example
```python
from sahi.models.huggingface_segmentation import SegmentationType

detection_model = AutoDetectionModel.from_pretrained(
    model_type="huggingface_segmentation",
    model_path="facebook/mask2former-swin-tiny-coco-instance",
    confidence_threshold=0.5,
    device="cuda:0",
    segmentation_type=SegmentationType.INSTANCE_SEGMENTATION,
)
```

### Response
Returns a detection model object that can be used with get_sliced_prediction for inference.
```

--------------------------------

### Compare multiple detection results with CLI

Source: https://github.com/obss/sahi/blob/main/docs/fiftyone.md

Use the sahi coco fiftyone CLI command to visualize a dataset with multiple prediction results, ordered by misdetections.

```bash
sahi coco fiftyone \
  --image_dir dir/to/images \
  --dataset_json_path dataset.json \
  cocoresult1.json cocoresult2.json
```

--------------------------------

### Real-time video visualization predict command

Source: https://github.com/obss/sahi/blob/main/docs/cli.md

Enables video rendering during inference with the `--view_video` flag. Keyboard controls: D (forward 100), A (rewind 100), G (forward 20), F (rewind 20), Esc (exit). Tip: add `--frame_skip_interval=20` if slow.

```bash
sahi predict --model_path yolo26s.pt --model_type ultralytics --source video.mp4 --view_video
```

--------------------------------

### NMSPostprocess

Source: https://github.com/obss/sahi/blob/main/docs/postprocess/backends.md

Non-Maximum Suppression postprocessor that keeps the best box and discards overlapping ones. It can be configured with a match threshold, match metric, and class-agnostic behavior.

```APIDOC
## NMSPostprocess

### Description
Non-Maximum Suppression (NMS) postprocessor that keeps the best box and discards the rest. It can be configured with a match threshold, match metric, and class-agnostic behavior.

### Constructor
`NMSPostprocess(match_threshold=0.5, match_metric="IOU", class_agnostic=True)`

### Parameters
- **match_threshold** (float) - Optional - Threshold for matching boxes. Default is 0.5.
- **match_metric** (str) - Optional - Metric used for matching, e.g., "IOU". Default is "IOU".
- **class_agnostic** (bool) - Optional - If True, suppression is class-agnostic; if False, per-category. Default is True.

### Call
`postprocessor(object_prediction_list)`

### Returns
Filtered object prediction list.
```

--------------------------------

### AutoDetectionModel.from_pretrained()

Source: https://github.com/obss/sahi/blob/main/docs/guides/models.md

Loads a detection model from a path or a pre-loaded model instance. Accepts common parameters such as model_type, model_path, confidence_threshold, device, and more.

```APIDOC
## AutoDetectionModel.from_pretrained()

### Description
Loads a detection model from a path or a pre-loaded model instance. Accepts common parameters such as model_type, model_path, confidence_threshold, device, and more.

### Method
from_pretrained

### Parameters

#### Common Parameters
- **model_type** (str) - Required - Framework name (e.g., ultralytics, mmdet, etc.)
- **model_path** (str) - Optional - Path to weights file or model name. Required if not passing a pre-loaded model.
- **config_path** (str) - Optional - Config file path (for MMDetection, Detectron2)
- **confidence_threshold** (float) - Optional - Minimum score to keep a detection (default: 0.3)
- **device** (str) - Optional - Device to use: "cpu", "cuda:0", "mps", etc.
- **category_mapping** (dict) - Optional - Map category IDs to names, keys are strings: {"0": "car", "1": "person"}
- **category_remapping** (dict) - Optional - Remap category names after inference
- **image_size** (int) - Optional - Override model input resolution
- **load_at_init** (bool) - Optional - Load weights immediately (default: True)

#### Pre-loaded Model
- **model** (object) - Optional - A pre-loaded model instance (e.g., YOLO) to use instead of a path.

### Request Example
```python
from ultralytics import YOLO

yolo_model = YOLO("yolo26n.pt")
# ... customize the model ...

detection_model = AutoDetectionModel.from_pretrained(
    model_type="ultralytics",
    model=yolo_model,
    confidence_threshold=0.25,
    device="cuda:0",
)
```

### Response
Returns a detection model instance ready for inference.
```

--------------------------------

### NMMPostprocess

Source: https://github.com/obss/sahi/blob/main/docs/postprocess/backends.md

Full Non-Maximum Merging postprocessor that performs transitive merging of overlapping boxes. It uses a match threshold.

```APIDOC
## NMMPostprocess

### Description
Full Non-Maximum Merging (NMM) postprocessor that performs transitive merging of overlapping boxes. It uses a match threshold.

### Constructor
`NMMPostprocess(match_threshold=0.5)`

### Parameters
- **match_threshold** (float) - Optional - Threshold for matching boxes. Default is 0.5.

### Call
`postprocessor(object_prediction_list)`

### Returns
Merged object prediction list.
```

--------------------------------

### Visualize and export prediction results

Source: https://github.com/obss/sahi/blob/main/docs/predict.md

Shows how to generate predictions and export them using custom visualization parameters or convert them into standard formats like COCO, imantics, and FiftyOne.

```python
from sahi.predict import get_prediction
from sahi import AutoDetectionModel
from PIL import Image

# init a model
detection_model = AutoDetectionModel.from_pretrained(...)

# get prediction result
result = get_prediction(
    image,
    detection_model,
)

# Export with custom visualization parameters
result.export_visuals(
    export_dir="outputs/",
    text_size=1.0,  # Size of the class label text
    rect_th=2,      # Thickness of bounding box lines
    hide_labels=False,  # Set True to hide class labels
    hide_conf=False,    # Set True to hide confidence scores
    file_name="custom_visualization",
)

# Export as COCO format annotations
coco_annotations = result.to_coco_annotations()
# Example output: [{'image_id': None, 'bbox': [x, y, width, height], 'category_id': 0, 'area': width*height, ...}]

# Export as COCO predictions (includes confidence scores)
coco_predictions = result.to_coco_predictions(image_id=1)
# Example output: [{'image_id': 1, 'bbox': [x, y, width, height], 'score': 0.98, 'category_id': 0, ...}]

# Export as imantics format
imantics_annotations = result.to_imantics_annotations()
# For use with imantics library: https://github.com/jsbroks/imantics

# Export for FiftyOne visualization
fiftyone_detections = result.to_fiftyone_detections()
# For use with FiftyOne: https://github.com/voxel51/fiftyone
```

--------------------------------

### Run RT-DETR Sliced Inference

Source: https://github.com/obss/sahi/blob/main/docs/guides/models.md

Initialize the RT-DETR detection model and perform sliced prediction on an image.

```python
detection_model = AutoDetectionModel.from_pretrained(
    model_type="rtdetr",
    model_path="rtdetr-l.pt",
    confidence_threshold=0.3,
    device="cuda:0",
)

result = get_sliced_prediction(
    "image.jpg",
    detection_model,
    slice_height=512,
    slice_width=512,
)
```

--------------------------------

### NMS with IOS match metric

Source: https://github.com/obss/sahi/blob/main/docs/postprocess/backends.md

Shows how to use the Intersection over Smaller area (IOS) match metric with NMS. Useful when one box is much smaller than another. Uses match_metric='IOS' and match_threshold=0.5.

```python
keep = nms(predictions, match_metric="IOS", match_threshold=0.5)
```

--------------------------------

### Compute COCO Dataset Statistics with Coco.from_coco_dict_or_path

Source: https://github.com/obss/sahi/blob/main/docs/coco.md

Loads a COCO JSON file and prints dataset statistics including image counts, annotation counts, and area distributions. The output shows the structure of the stats dictionary.

```python
from sahi.utils.coco import Coco

coco = Coco.from_coco_dict_or_path("coco.json")

print(coco.stats)
# {
#   'num_images': 6471,
#   'num_annotations': 343204,
#   'num_categories': 2,
#   'num_negative_images': 0,
#   'num_images_per_category': {'human': 5684, 'vehicle': 6323},
#   'num_annotations_per_category': {'human': 106396, 'vehicle': 236808},
#   'min_num_annotations_in_image': 1,
#   'max_num_annotations_in_image': 902,
#   'avg_num_annotations_in_image': 53.04,
#   'min_annotation_area': 3,
#   'max_annotation_area': 328640,
#   'avg_annotation_area': 2448.41,
#   'min_annotation_area_per_category': {'human': 3, 'vehicle': 3},
#   'max_annotation_area_per_category': {'human': 72670, 'vehicle': 328640},
# }
```
Tokens:
Raw