========================
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.)

========================
CODE SNIPPETS
========================
TITLE: SAHI Slicing Utilities Documentation
DESCRIPTION: Guide for slicing large images and datasets using SAHI, including examples for image and COCO dataset slicing, and a reference to an interactive demo notebook.

SOURCE: https://github.com/obss/sahi/blob/main/docs/README.md#_snippet_1

LANGUAGE: APIDOC
CODE:
```
Slicing Utilities:
  Description: Guide for slicing large images and datasets
  Features:
    - Image slicing examples
    - COCO dataset slicing examples
    - Interactive demo notebook reference
```

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

TITLE: Install SAHI and Ultralytics
DESCRIPTION: Installs the necessary Python packages, including 'torch', 'sahi', and 'ultralytics', required for running the object detection examples.

SOURCE: https://github.com/obss/sahi/blob/main/demo/inference_for_rtdetr.ipynb#_snippet_0

LANGUAGE: python
CODE:
```
!pip install -U torch sahi ultralytics
```

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

TITLE: Install SAHI Development Dependencies
DESCRIPTION: Command to install core and development dependencies for the SAHI project using `uv`.

SOURCE: https://github.com/obss/sahi/blob/main/CONTRIBUTING.md#_snippet_2

LANGUAGE: bash
CODE:
```
uv sync --extra dev
```

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

TITLE: Install Core SAHI Library
DESCRIPTION: This command installs the fundamental SAHI library using pip, providing the essential components for object detection tasks.

SOURCE: https://github.com/obss/sahi/blob/main/README.md#_snippet_1

LANGUAGE: bash
CODE:
```
pip install sahi
```

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

TITLE: Setup Environment for CI Build Failure Troubleshooting
DESCRIPTION: Commands to create and activate a virtual environment with a specific Python version, matching the one that caused a CI build failure, to aid in troubleshooting.

SOURCE: https://github.com/obss/sahi/blob/main/CONTRIBUTING.md#_snippet_7

LANGUAGE: bash
CODE:
```
uv venv --python 3.X  # Replace X with the version from CI
source .venv/bin/activate
```

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

TITLE: Install Dev Dependencies for CI Build Failure Troubleshooting
DESCRIPTION: Command to install development dependencies after setting up a specific Python environment for CI build failure resolution.

SOURCE: https://github.com/obss/sahi/blob/main/CONTRIBUTING.md#_snippet_8

LANGUAGE: bash
CODE:
```
uv sync --extra dev
```

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

TITLE: Install MMDetection Framework and MIM
DESCRIPTION: These commands install the MMDetection framework using `mim`, a necessary dependency for SAHI when working with MMDetection models and their specific requirements.

SOURCE: https://github.com/obss/sahi/blob/main/README.md#_snippet_7

LANGUAGE: console
CODE:
```
pip install mim
```

LANGUAGE: console
CODE:
```
mim install mmdet==3.3.0
```

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

TITLE: Create Python Virtual Environment with uv
DESCRIPTION: Steps to install the `uv` package manager, create a Python 3.10 virtual environment for SAHI development, and then activate it. Includes a note for Windows users.

SOURCE: https://github.com/obss/sahi/blob/main/CONTRIBUTING.md#_snippet_1

LANGUAGE: bash
CODE:
```
pip install uv
uv venv --python 3.10
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
```

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

TITLE: Install Ultralytics Detection Framework
DESCRIPTION: This command installs the Ultralytics framework, a popular choice for object detection models like YOLO, ensuring compatibility with SAHI's functionalities.

SOURCE: https://github.com/obss/sahi/blob/main/README.md#_snippet_4

LANGUAGE: console
CODE:
```
pip install ultralytics>=8.3.161
```

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

TITLE: SAHI FiftyOne Integration Documentation
DESCRIPTION: Guide for visualizing and analyzing SAHI predictions with FiftyOne, focusing on dataset visualization, result exploration, and interactive analysis.

SOURCE: https://github.com/obss/sahi/blob/main/docs/README.md#_snippet_4

LANGUAGE: APIDOC
CODE:
```
FiftyOne Integration:
  Description: Guide for visualizing and analyzing predictions with FiftyOne
  Features:
    - Dataset visualization
    - Result exploration
    - Interactive analysis
```

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

TITLE: SAHI Interactive Jupyter Notebook Examples
DESCRIPTION: Overview of interactive Jupyter notebooks complementing SAHI documentation, demonstrating slicing operations and integrations with various deep learning models like YOLOv8, YOLOv5, MMDetection, HuggingFace, TorchVision, and RT-DETR.

SOURCE: https://github.com/obss/sahi/blob/main/docs/README.md#_snippet_5

LANGUAGE: APIDOC
CODE:
```
Interactive Examples:
  Description: Jupyter notebooks for hands-on experience
  Notebooks:
    - slicing.ipynb: Slicing operations demonstration
    - inference_for_ultralytics.ipynb: YOLOv8/YOLO11/YOLO12 integration
    - inference_for_yolov5.ipynb: YOLOv5 integration
    - inference_for_mmdetection.ipynb: MMDetection integration
    - inference_for_huggingface.ipynb: HuggingFace models integration
    - inference_for_torchvision.ipynb: TorchVision models integration
    - inference_for_rtdetr.ipynb: RT-DETR integration
```

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

TITLE: SAHI COCO Utilities Documentation
DESCRIPTION: Comprehensive guide for working with COCO format datasets in SAHI, covering creation, manipulation, slicing, splitting, filtering, merging, format conversion, sampling, statistics, and validation.

SOURCE: https://github.com/obss/sahi/blob/main/docs/README.md#_snippet_2

LANGUAGE: APIDOC
CODE:
```
COCO Utilities:
  Description: Comprehensive guide for working with COCO format datasets
  Features:
    - Dataset creation and manipulation
    - Slicing COCO datasets
    - Dataset splitting (train/val)
    - Category filtering and updates
    - Area-based filtering
    - Dataset merging
    - Format conversion (COCO ↔ YOLO)
    - Dataset sampling utilities
    - Statistics calculation
    - Result validation
```

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

TITLE: Install Hugging Face Transformers and Timm
DESCRIPTION: This command installs the Hugging Face Transformers library along with Timm, enabling SAHI to integrate with various transformer-based detection models.

SOURCE: https://github.com/obss/sahi/blob/main/README.md#_snippet_5

LANGUAGE: console
CODE:
```
pip install transformers>=4.49.0 timm
```

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

TITLE: Install YOLOv5 and Compatible SAHI Version
DESCRIPTION: This command installs a specific version of YOLOv5 and a compatible SAHI version, ensuring proper functionality for object detection tasks using the YOLOv5 framework.

SOURCE: https://github.com/obss/sahi/blob/main/README.md#_snippet_6

LANGUAGE: console
CODE:
```
pip install yolov5==7.0.14 sahi==0.11.21
```

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

TITLE: Install Roboflow Inference and RFDetr
DESCRIPTION: This command installs Roboflow Inference and RFDetr, facilitating SAHI's integration with Roboflow's ecosystem for advanced object detection capabilities.

SOURCE: https://github.com/obss/sahi/blob/main/README.md#_snippet_8

LANGUAGE: console
CODE:
```
pip install inference>=0.50.3 rfdetr>=1.1.0
```

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

TITLE: SAHI Prediction Utilities Documentation
DESCRIPTION: Detailed guide for performing object detection inference with SAHI, covering standard and sliced inference, batch prediction, class exclusion, visualization, and integration with various models.

SOURCE: https://github.com/obss/sahi/blob/main/docs/README.md#_snippet_0

LANGUAGE: APIDOC
CODE:
```
Prediction Utilities:
  Description: Detailed guide for performing object detection inference
  Features:
    - Standard and sliced inference examples
    - Batch prediction usage
    - Class exclusion during inference
    - Visualization parameters and export formats
    - Interactive examples with various model integrations (YOLO11, MMDetection, etc.)
```

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

TITLE: Install PyTorch and Torchvision for CUDA 12.6
DESCRIPTION: This command installs specific versions of PyTorch and Torchvision optimized for CUDA 12.6, a common prerequisite for many deep learning frameworks.

SOURCE: https://github.com/obss/sahi/blob/main/README.md#_snippet_2

LANGUAGE: console
CODE:
```
pip install torch==2.7.0 torchvision==0.22.0 --index-url https://download.pytorch.org/whl/cu126
```

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

TITLE: Instantiate SAHI AutoDetectionModel for RTDETR
DESCRIPTION: Initializes an 'AutoDetectionModel' instance for RTDETR. It specifies the model type, path to the downloaded weights, a confidence threshold for predictions, and the device for inference (CPU in this example).

SOURCE: https://github.com/obss/sahi/blob/main/demo/inference_for_rtdetr.ipynb#_snippet_4

LANGUAGE: python
CODE:
```
detection_model = AutoDetectionModel.from_pretrained(
    model_type='rtdetr',
    model_path=rtdetr_model_path,
    confidence_threshold=0.3,
    device="cpu", # or 'cuda:0'
)
```

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

TITLE: Install PyTorch and Torchvision for CUDA 12.1 (MMDet Support)
DESCRIPTION: This command installs specific versions of PyTorch and Torchvision optimized for CUDA 12.1, explicitly required for MMDetection framework compatibility.

SOURCE: https://github.com/obss/sahi/blob/main/README.md#_snippet_3

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

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

TITLE: Pytest Example for Conditional Test Skipping in SAHI
DESCRIPTION: This Python snippet provides an example of how to write new tests for SAHI using pytest, incorporating conditional skipping. It shows how to use `pytest.mark.skipif` to skip tests based on the Python version and `pytest.importorskip` to skip if an optional dependency is not available, ensuring test robustness and compatibility across different environments.

SOURCE: https://github.com/obss/sahi/blob/main/tests/README.md#_snippet_3

LANGUAGE: python
CODE:
```
import pytest
import sys

# Skip if Python version is too old
pytestmark = pytest.mark.skipif(
    sys.version_info[:2] < (3, 9), 
    reason="Feature requires Python 3.9+"
)

def test_my_feature():
    # Skip if optional dependency is missing
    pytest.importorskip("optional_package")
    
    # Your test code here
    assert result == expected
```

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

TITLE: SAHI CLI: Display SAHI Library Version
DESCRIPTION: This command outputs the currently installed version of the SAHI library. It is useful for quickly checking the installed SAHI version, which can be important for debugging or ensuring compatibility with other tools.

SOURCE: https://github.com/obss/sahi/blob/main/docs/cli.md#_snippet_11

LANGUAGE: bash
CODE:
```
sahi version
```

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

TITLE: SAHI CLI: Display Environment Package Versions
DESCRIPTION: This command prints the versions of related Python packages installed in the current environment that SAHI utilizes. It helps in verifying dependencies and their compatibility, providing insight into the software stack.

SOURCE: https://github.com/obss/sahi/blob/main/docs/cli.md#_snippet_10

LANGUAGE: bash
CODE:
```
sahi env
```

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

TITLE: Launch FiftyOne App for COCO Dataset Exploration
DESCRIPTION: This Python snippet demonstrates how to programmatically launch and close a FiftyOne session to explore a COCO dataset. It requires the path to the COCO image directory and the COCO annotation JSON file. Ensure FiftyOne version `0.14.2` or higher is installed.

SOURCE: https://github.com/obss/sahi/blob/main/docs/fiftyone.md#_snippet_0

LANGUAGE: python
CODE:
```
from sahi.utils.fiftyone import launch_fiftyone_app

# launch fiftyone app:
session = launch_fiftyone_app(coco_image_dir, coco_json_path)

# close fiftyone app:
session.close()
```

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

TITLE: Run MMDetection Tests for SAHI (Python 3.11)
DESCRIPTION: This set of commands is specifically for testing the MMDetection integration within SAHI. It first verifies the Python version is 3.11, then installs MMDetection-specific dependencies, and finally runs either all MMDetection tests or a subset using pytest's `-k` flag. This isolation is crucial due to MMDetection's unique dependency requirements.

SOURCE: https://github.com/obss/sahi/blob/main/tests/README.md#_snippet_1

LANGUAGE: bash
CODE:
```
python --version  # Should show 3.11.x

uv sync --extra dev --extra mmdet

pytest tests/test_mmdetectionmodel.py
# Or run specific MMDet tests from test_predict.py
pytest -k "mmdet"
```

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

TITLE: Run All SAHI Tests Excluding MMDetection
DESCRIPTION: This command sequence installs core development and CI dependencies for SAHI using `uv sync`, then executes all pytest tests while explicitly excluding those related to MMDetection. This is the standard approach for general CI and local development to avoid MMDetection's specific dependency requirements.

SOURCE: https://github.com/obss/sahi/blob/main/tests/README.md#_snippet_0

LANGUAGE: bash
CODE:
```
uv sync --extra dev --extra ci

pytest -k "not mmdet"
```

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

TITLE: Perform Standard Inference with SAHI AutoDetectionModel
DESCRIPTION: This example illustrates how to perform standard, non-sliced object detection inference using the `get_prediction` function. It requires initializing an `AutoDetectionModel` and passing the image and model to the function to obtain prediction results.

SOURCE: https://github.com/obss/sahi/blob/main/docs/predict.md#_snippet_1

LANGUAGE: python
CODE:
```
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,
)
```

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

TITLE: Create and Export COCO Dataset with SAHI Utilities
DESCRIPTION: This section demonstrates the complete workflow for programmatically creating a COCO dataset. It covers importing necessary classes, initializing a Coco object, adding categories, creating and populating CocoImage objects with annotations and predictions, and finally exporting the dataset and predictions to JSON files. It also includes an example of evaluating predictions using `pycocotools`.

SOURCE: https://github.com/obss/sahi/blob/main/docs/coco.md#_snippet_0

LANGUAGE: python
CODE:
```
from sahi.utils.coco import Coco, CocoCategory, CocoImage, CocoAnnotation

from sahi.utils.coco import Coco, CocoCategory, CocoImage, CocoAnnotation

coco = Coco()

coco.add_category(CocoCategory(id=0, name='human'))
coco.add_category(CocoCategory(id=1, name='vehicle'))

coco_image = CocoImage(file_name="image1.jpg", height=1080, width=1920)

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'
  )
)

coco_image.add_prediction(
  CocoPrediction(
    score=0.864434,
    bbox=[x_min, y_min, width, height],
    category_id=0,
    category_name='human'
  )
)
coco_image.add_prediction(
  CocoPrediction(
    score=0.653424,
    bbox=[x_min, y_min, width, height],
    category_id=1,
    category_name='vehicle'
  )
)

coco.add_image(coco_image)

coco_json = coco.json

from sahi.utils.file import save_json

save_json(coco_json, "coco_dataset.json")

from sahi.utils.file import save_json

predictions_array = coco.prediction_array
save_json = save_json(predictions_array, "coco_predictions.json")

# note:- pycocotools need to be installed separately 
from pycocotools.cocoeval import COCOeval
from pycocotools.coco import COCO

coco_ground_truth = COCO(annotation_file="coco_dataset.json")
coco_predictions = coco_ground_truth.loadRes("coco_predictions.json")

coco_evaluator = COCOeval(coco_ground_truth, coco_predictions, "bbox")
coco_evaluator.evaluate()
coco_evaluator.accumulate()
coco_evaluator.summarize()
```

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

TITLE: SAHI CLI: Execute Custom Python Scripts
DESCRIPTION: This snippet demonstrates how to execute custom Python scripts that are part of the SAHI project or downloaded from its scripts directory. After installing SAHI via pip, these scripts can be run from any directory using the standard Python interpreter, allowing for flexible customization and automation.

SOURCE: https://github.com/obss/sahi/blob/main/docs/cli.md#_snippet_12

LANGUAGE: bash
CODE:
```
python script_name.py
```

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

TITLE: SAHI CLI Commands Reference
DESCRIPTION: Complete reference for SAHI command-line interface, detailing commands for prediction, FiftyOne integration, COCO dataset operations, environment info, version checking, and custom script usage.

SOURCE: https://github.com/obss/sahi/blob/main/docs/README.md#_snippet_3

LANGUAGE: APIDOC
CODE:
```
CLI Commands:
  Description: Complete reference for SAHI command-line interface
  Features:
    - Prediction commands
    - FiftyOne integration
    - COCO dataset operations
    - Environment information
    - Version checking
    - Custom script usage
```

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

TITLE: Visualize Detection Results in FiftyOne UI via SAHI CLI
DESCRIPTION: This Bash command-line snippet shows how to use the SAHI CLI to launch the FiftyOne app for visualizing a dataset and multiple detection results. It allows specifying the image directory, dataset JSON, and one or more result JSON files. An optional `--iou_threshold` argument can be used to define the IOU threshold for FP/TP calculations.

SOURCE: https://github.com/obss/sahi/blob/main/docs/fiftyone.md#_snippet_2

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

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

TITLE: Clone SAHI Repository
DESCRIPTION: Instructions to clone the SAHI repository from GitHub to your local machine and navigate into the project directory.

SOURCE: https://github.com/obss/sahi/blob/main/CONTRIBUTING.md#_snippet_0

LANGUAGE: bash
CODE:
```
git clone https://github.com/YOUR_USERNAME/sahi.git
cd sahi
```

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

TITLE: Get dataset stats
DESCRIPTION: Retrieves and displays comprehensive statistical information about a COCO dataset, including counts for images, annotations, categories, and detailed breakdowns per category and annotation area distributions.

SOURCE: https://github.com/obss/sahi/blob/main/docs/coco.md#_snippet_12

LANGUAGE: Python
CODE:
```
from sahi.utils.coco import Coco

# init Coco object
coco = Coco.from_coco_dict_or_path("coco.json")

# get dataset stats
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.037243084530985,
  'min_annotation_area': 3,
  'max_annotation_area': 328640,
  'avg_annotation_area': 2448.405738278109,
  'min_annotation_area_per_category': {'human': 3, 'vehicle': 3},
  'max_annotation_area_per_category': {'human': 72670, 'vehicle': 328640},
}
```

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

TITLE: Run SAHI Tests
DESCRIPTION: Commands to execute all tests, run a specific test file, or run tests with coverage reporting using `pytest` via `uv`.

SOURCE: https://github.com/obss/sahi/blob/main/CONTRIBUTING.md#_snippet_5

LANGUAGE: bash
CODE:
```
uv run pytest

uv run pytest tests/test_predict.py

uv run pytest --cov=sahi
```

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

TITLE: Verify Current Working Directory
DESCRIPTION: Imports the 'os' module and prints the current working directory. This is a common step to ensure scripts are run from the expected location.

SOURCE: https://github.com/obss/sahi/blob/main/demo/inference_for_rtdetr.ipynb#_snippet_1

LANGUAGE: python
CODE:
```
import os
os.getcwd()
```

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

TITLE: Exclude Custom Classes During SAHI Sliced Inference
DESCRIPTION: This example shows how to filter out specific classes from the detection results during sliced inference. Users can define classes to exclude either by their names or by their custom IDs, providing flexibility in controlling the output of the prediction.

SOURCE: https://github.com/obss/sahi/blob/main/docs/predict.md#_snippet_3

LANGUAGE: python
CODE:
```
from sahi.predict import get_sliced_prediction
from sahi import AutoDetectionModel

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

# define the class names to exclude from custom model inference
exclude_classes_by_name = ["car"]

# or exclude classes by its custom id
exclude_classes_by_id = [0]

result = get_sliced_prediction(
    image,
    detection_model,
    slice_height = 256,
    slice_width = 256,
    overlap_height_ratio = 0.2,
    overlap_width_ratio = 0.2,
    exclude_classes_by_name = exclude_classes_by_name
    # exclude_classes_by_id = exclude_classes_by_id
)
```

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

TITLE: Download RTDETR Model and Test Images
DESCRIPTION: Downloads a pre-trained RTDETR-L model to a specified path and two sample images from a URL for demonstration purposes.

SOURCE: https://github.com/obss/sahi/blob/main/demo/inference_for_rtdetr.ipynb#_snippet_3

LANGUAGE: python
CODE:
```
# download rtdetr-l model to 'models/rtdetr-l.pt'
rtdetr_model_path = "models/rtdetr-l.pt"
download_rtdetrl_model(rtdetr_model_path)

# download test images into demo_data folder
download_from_url('https://raw.githubusercontent.com/obss/sahi/main/demo/demo_data/small-vehicles1.jpeg', 'demo_data/small-vehicles1.jpeg')
download_from_url('https://raw.githubusercontent.com/obss/sahi/main/demo/demo_data/terrain2.png', 'demo_data/terrain2.png')
```

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

TITLE: Real-time Video Render during Inference
DESCRIPTION: Enables real-time visualization of the inference process on video inputs. The `--view_video` flag opens a window to display predictions as they are made, with options for frame navigation and skipping.

SOURCE: https://github.com/obss/sahi/blob/main/docs/cli.md#_snippet_2

LANGUAGE: bash
CODE:
```
>>sahi predict --model_path yolo11s.pt --model_type ultralytics --source video.mp4 --view_video
```

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

TITLE: Filter and Update COCO Dataset Categories
DESCRIPTION: This example demonstrates how to filter a COCO dataset to include only specific categories and how to remap their category IDs. It loads a COCO dataset, updates its categories based on a desired name-to-ID mapping, and then saves the modified dataset.

SOURCE: https://github.com/obss/sahi/blob/main/docs/coco.md#_snippet_3

LANGUAGE: python
CODE:
```
from sahi.utils.coco import Coco
from sahi.utils.file import save_json

# init Coco objects by specifying coco dataset paths and image folder directories
coco = Coco.from_coco_dict_or_path("coco.json")

# select only 3 categories; and map them to ids 1, 2 and 3
desired_name2id = {
  "big_vehicle": 1,
  "car": 2,
  "human": 3
}
coco.update_categories(desired_name2id)

# export updated/filtered COCO dataset
save_json(coco.json, "updated_coco.json")
```

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

TITLE: Filter COCO Dataset by Annotation Area
DESCRIPTION: This snippet shows how to filter a COCO dataset based on the area of its annotations. It provides examples for filtering by a minimum area, a range (min and max area), and category-specific area intervals, allowing fine-grained control over the dataset content.

SOURCE: https://github.com/obss/sahi/blob/main/docs/coco.md#_snippet_4

LANGUAGE: python
CODE:
```
from sahi.utils.coco import Coco
from sahi.utils.file import save_json

# init Coco objects by specifying coco dataset paths and image folder directories
coco = Coco.from_coco_dict_or_path("coco.json")

# filter out images that contain annotations with smaller area than 50
area_filtered_coco = coco.get_area_filtered_coco(min=50)
# filter out images that contain annotations with smaller area than 50 and larger area than 10000
area_filtered_coco = coco.get_area_filtered_coco(min=50, max=10000)
# filter out images with separate area intervals per category
intervals_per_category = {
  "human": {"min": 20, "max": 10000},
  "vehicle": {"min": 50, "max": 15000},
}
area_filtered_coco = coco.get_area_filtered_coco(intervals_per_category=intervals_per_category)
```

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

TITLE: Slice COCO Dataset Images and Annotations into Grids
DESCRIPTION: This example demonstrates how to slice a COCO dataset's images and their corresponding annotations into smaller, overlapping grid sections. This is useful for processing large images or for training models on smaller patches. It uses `sahi.slicing.slice_coco` with configurable slice dimensions and overlap ratios.

SOURCE: https://github.com/obss/sahi/blob/main/docs/coco.md#_snippet_1

LANGUAGE: python
CODE:
```
from sahi.slicing import slice_coco

coco_dict, coco_path = slice_coco(
    coco_annotation_file_path="coco.json",
    image_dir="source/coco/image/dir",
    slice_height=256,
    slice_width=256,
    overlap_height_ratio=0.2,
    overlap_width_ratio=0.2,
)
```

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

TITLE: BibTeX Citation for SAHI Software (Zenodo)
DESCRIPTION: This BibTeX entry provides the citation for the SAHI software library, hosted on Zenodo. It includes the authors, title, publication month, year, publisher, DOI, and URL, suitable for referencing the software itself.

SOURCE: https://github.com/obss/sahi/blob/main/README.md#_snippet_10

LANGUAGE: bibtex
CODE:
```
@software{obss2021sahi,
  author       = {Akyon, Fatih Cagatay and Cengiz, Cemil and Altinuc, Sinan Onur and Cavusoglu, Devrim and Sahin, Kadir and Eryuksel, Ogulcan},
  title        = {{SAHI: A lightweight vision library for performing large scale object detection and instance segmentation}},
  month        = nov,
  year         = 2021,
  publisher    = {Zenodo},
  doi          = {10.5281/zenodo.5718950},
  url          = {https://doi.org/10.5281/zenodo.5718950}
}
```

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

TITLE: SAHI Pull Request Workflow Commands
DESCRIPTION: Essential Git and project commands for creating a new branch, formatting code, running tests, committing changes, and pushing to origin for a pull request.

SOURCE: https://github.com/obss/sahi/blob/main/CONTRIBUTING.md#_snippet_6

LANGUAGE: bash
CODE:
```
git checkout -b feature-name
python scripts/format_code.py fix
uv run pytest
git commit -m "Add feature X"
git push origin feature-name
```

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

TITLE: Basic Sliced Inference with `sahi predict`
DESCRIPTION: Executes sliced inference on image files or folders using default parameters. The prediction visuals are automatically exported to the `runs/predict/exp` directory.

SOURCE: https://github.com/obss/sahi/blob/main/docs/cli.md#_snippet_0

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

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

TITLE: Check SAHI Code Formatting
DESCRIPTION: Commands to check code formatting and linting using `ruff` via `uv run` or by executing the convenience Python script.

SOURCE: https://github.com/obss/sahi/blob/main/CONTRIBUTING.md#_snippet_3

LANGUAGE: bash
CODE:
```
uv run ruff check .
uv run ruff format --check .
```

LANGUAGE: python
CODE:
```
python scripts/format_code.py check
```

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

TITLE: Fix Formatting for CI Build Failure Troubleshooting
DESCRIPTION: Command to fix code formatting using the Python script after setting up the environment for CI build failure resolution.

SOURCE: https://github.com/obss/sahi/blob/main/CONTRIBUTING.md#_snippet_9

LANGUAGE: python
CODE:
```
python scripts/format_code.py fix
```

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

TITLE: Slice Image using SAHI Slicing Utility
DESCRIPTION: Demonstrates how to slice a single image file into smaller overlapping patches using the `slice_image` function from SAHI. It takes the image path, desired output file name and directory, slice dimensions (height and width), and overlap ratios as input.

SOURCE: https://github.com/obss/sahi/blob/main/docs/slicing.md#_snippet_0

LANGUAGE: python
CODE:
```
from sahi.slicing import slice_image

slice_image_result = slice_image(
    image=image_path,
    output_file_name=output_file_name,
    output_dir=output_dir,
    slice_height=256,
    slice_width=256,
    overlap_height_ratio=0.2,
    overlap_width_ratio=0.2,
)
```

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

TITLE: Execute Specific SAHI Test Categories or Run in Parallel
DESCRIPTION: These commands demonstrate how to run tests for specific model integrations like Ultralytics or HuggingFace by targeting their respective test files. Additionally, `pytest -n auto` is shown for running all tests in parallel, which can significantly speed up the test execution process.

SOURCE: https://github.com/obss/sahi/blob/main/tests/README.md#_snippet_2

LANGUAGE: bash
CODE:
```
pytest tests/test_ultralyticsmodel.py

# Run only HuggingFace tests (Python 3.9+)
pytest tests/test_huggingfacemodel.py

# Run tests in parallel
pytest -n auto
```

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

TITLE: Import SAHI Modules for RTDETR Inference
DESCRIPTION: Imports essential classes and functions from the SAHI library for RTDETR model handling, image utilities, file operations, and prediction functionalities.

SOURCE: https://github.com/obss/sahi/blob/main/demo/inference_for_rtdetr.ipynb#_snippet_2

LANGUAGE: python
CODE:
```
from sahi.utils.rtdetr import (
    download_rtdetrl_model
)

from sahi import AutoDetectionModel
from sahi.utils.cv import read_image
from sahi.utils.file import download_from_url
from sahi.predict import get_prediction, get_sliced_prediction, predict
from IPython.display import Image
```

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

TITLE: BibTeX Citation for SAHI Article (ICIP 2022)
DESCRIPTION: This BibTeX entry provides the citation for the 'Slicing Aided Hyper Inference and Fine-tuning for Small Object Detection' article presented at the 2022 IEEE International Conference on Image Processing (ICIP). It includes authors, title, journal, DOI, pages, and year, suitable for academic referencing.

SOURCE: https://github.com/obss/sahi/blob/main/README.md#_snippet_9

LANGUAGE: bibtex
CODE:
```
@article{akyon2022sahi,
  title={Slicing Aided Hyper Inference and Fine-tuning for Small Object Detection},
  author={Akyon, Fatih Cagatay and Altinuc, Sinan Onur and Temizel, Alptekin},
  journal={2022 IEEE International Conference on Image Processing (ICIP)},
  doi={10.1109/ICIP46576.2022.9897990},
  pages={966-970},
  year={2022}
}
```

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

TITLE: Visualize COCO Results in FiftyOne
DESCRIPTION: Launches a FiftyOne application to visualize a specified dataset alongside one or more COCO detection result JSON files. This is useful for comparing different prediction outputs or analyzing ground truth with predictions.

SOURCE: https://github.com/obss/sahi/blob/main/docs/cli.md#_snippet_5

LANGUAGE: bash
CODE:
```
>>sahi coco fiftyone --image_dir dir/to/images --dataset_json_path dataset.json cocoresult1.json cocoresult2.json
```

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

TITLE: SAHI CLI Commands Overview
DESCRIPTION: SAHI provides a set of command-line interface (CLI) tools to perform various tasks related to object detection, including sliced inference, COCO dataset manipulation, and result evaluation. These commands simplify common workflows for large-scale vision tasks.

SOURCE: https://github.com/obss/sahi/blob/main/README.md#_snippet_0

LANGUAGE: APIDOC
CODE:
```
predict: Perform sliced or standard video/image prediction using various models (ultralytics, mmdet, huggingface, torchvision).
```

LANGUAGE: APIDOC
CODE:
```
predict-fiftyone: Perform sliced or standard prediction and explore results in the FiftyOne application.
```

LANGUAGE: APIDOC
CODE:
```
coco slice: Automatically slice COCO annotation and image files.
```

LANGUAGE: APIDOC
CODE:
```
coco fiftyone: Explore multiple prediction results on your COCO dataset with the FiftyOne UI, ordered by misdetections.
```

LANGUAGE: APIDOC
CODE:
```
coco evaluate: Evaluate class-wise COCO AP and AR for given predictions and ground truth.
```

LANGUAGE: APIDOC
CODE:
```
coco analyse: Calculate and export various error analysis plots.
```

LANGUAGE: APIDOC
CODE:
```
coco yolo: Automatically convert any COCO dataset to Ultralytics format.
```

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

TITLE: Video Inference with `sahi predict`
DESCRIPTION: Performs object detection inference on video files. This command requires specifying the model path and type, enabling `sahi` to process video streams for predictions.

SOURCE: https://github.com/obss/sahi/blob/main/docs/cli.md#_snippet_1

LANGUAGE: bash
CODE:
```
>>sahi predict --model_path yolo11s.pt --model_type ultralytics --source video.mp4
```

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

TITLE: Visualize Prediction Results
DESCRIPTION: Exports the visual representation of the prediction results (bounding boxes and masks) to a specified directory and then displays the generated image within the notebook environment.

SOURCE: https://github.com/obss/sahi/blob/main/demo/inference_for_rtdetr.ipynb#_snippet_7

LANGUAGE: python
CODE:
```
result.export_visuals(export_dir="demo_data/")

Image("demo_data/prediction_visual.png")
```

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

TITLE: Visualize Sliced Inference in FiftyOne
DESCRIPTION: Executes sliced inference and directly displays the results within the FiftyOne App for interactive visualization and analysis. This command supports all additional parameters available for the standard `sahi predict` command.

SOURCE: https://github.com/obss/sahi/blob/main/docs/cli.md#_snippet_4

LANGUAGE: bash
CODE:
```
>>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
```

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

TITLE: Fix SAHI Code Formatting
DESCRIPTION: Commands to automatically fix code formatting and linting issues using `ruff` via `uv run` or by executing the convenience Python script.

SOURCE: https://github.com/obss/sahi/blob/main/CONTRIBUTING.md#_snippet_4

LANGUAGE: bash
CODE:
```
uv run ruff check --fix .
uv run ruff format .
```

LANGUAGE: python
CODE:
```
python scripts/format_code.py fix
```

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

TITLE: Perform Batch Inference with SAHI predict Function
DESCRIPTION: This snippet demonstrates how to use the `predict` function for batch inference, allowing processing of multiple images or a folder. It provides extensive parameters for configuring the model type, path, confidence threshold, device, and options for both standard and sliced prediction within the batch process.

SOURCE: https://github.com/obss/sahi/blob/main/docs/predict.md#_snippet_2

LANGUAGE: python
CODE:
```
from sahi.predict import predict
from sahi import AutoDetectionModel

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

# get batch predict result
result = predict(
    model_type=..., # one of 'ultralytics', 'mmdet', 'huggingface'
    model_path=..., # path to model weight file
    model_config_path=..., # for mmdet models
    model_confidence_threshold=0.5,
    model_device='cpu', # or 'cuda:0'
    source=..., # image or folder path
    no_standard_prediction=True,
    no_sliced_prediction=False,
    slice_height=512,
    slice_width=512,
    overlap_height_ratio=0.2, 
    overlap_width_ratio=0.2,
    export_pickle=False,
    export_crop=False,
)
```

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

TITLE: Convert Predictions to FiftyOne Detection Format
DESCRIPTION: Converts the SAHI prediction results into the FiftyOne detection format, compatible with the FiftyOne dataset visualization and management tool. It shows the first three converted detections.

SOURCE: https://github.com/obss/sahi/blob/main/demo/inference_for_rtdetr.ipynb#_snippet_14

LANGUAGE: python
CODE:
```
result.to_fiftyone_detections()[:3]
```

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

TITLE: Slice COCO Dataset and Annotations
DESCRIPTION: Processes a COCO dataset by slicing images and their corresponding annotations into smaller segments. The sliced data is then exported to a specified output directory, with options to define slice size and overlap ratio.

SOURCE: https://github.com/obss/sahi/blob/main/docs/cli.md#_snippet_6

LANGUAGE: bash
CODE:
```
>>sahi coco slice --image_dir dir/to/images --dataset_json_path dataset.json
```

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

TITLE: Convert COCO Dataset to YOLO Format
DESCRIPTION: Converts a COCO-formatted dataset into the YOLO format, exporting the converted files to the `runs/coco2yolo/exp` folder. This command also allows for specifying a training split ratio for the output dataset.

SOURCE: https://github.com/obss/sahi/blob/main/docs/cli.md#_snippet_7

LANGUAGE: bash
CODE:
```
>>sahi coco yolo --image_dir dir/to/images --dataset_json_path dataset.json --train_split 0.9
```

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

TITLE: Perform Sliced Inference with SAHI AutoDetectionModel
DESCRIPTION: This snippet demonstrates how to perform sliced inference using `get_sliced_prediction` for processing large images. It shows how to initialize an `AutoDetectionModel` from various backends (MMDetection, Ultralytics, HuggingFace, Torchvision) and configure slice dimensions and overlap ratios for the prediction.

SOURCE: https://github.com/obss/sahi/blob/main/docs/predict.md#_snippet_0

LANGUAGE: python
CODE:
```
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/YOLO12 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

# 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
)
```

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

TITLE: Perform Standard Inference with Image Path
DESCRIPTION: Executes a standard object detection prediction using the 'get_prediction' function. It takes an image file path and the instantiated 'detection_model' as input.

SOURCE: https://github.com/obss/sahi/blob/main/demo/inference_for_rtdetr.ipynb#_snippet_5

LANGUAGE: python
CODE:
```
result = get_prediction("demo_data/small-vehicles1.jpeg", detection_model)
```