## File: README.md [](https://github.com/obss/sahi/actions/workflows/ci.yml) [](https://security.snyk.io/package/pip/sahi) [](https://www.codefactor.io/repository/github/onuralpszr/sahi) [](https://ieeexplore.ieee.org/document/9897990) [](https://context7.com/obss/sahi) [](https://context7.com/obss/sahi/llms.txt) [](https://deepwiki.com/obss/sahi) [](https://huggingface.co/spaces/fcakyon/sahi-yolox) ## SAHI helps developers overcome real-world challenges in object detection by enabling **sliced inference** for detecting small objects in large images. It supports various popular detection models and provides easy-to-use APIs. | Command | Description | | ----------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [predict](https://github.com/obss/sahi/blob/main/docs/cli.md#predict-command-usage) | Perform sliced/standard video/image prediction using any [ultralytics](https://github.com/ultralytics/ultralytics) / [mmdet](https://github.com/open-mmlab/mmdetection) / [huggingface](https://huggingface.co/models?pipeline_tag=object-detection&sort=downloads) / [torchvision](https://pytorch.org/vision/stable/models.html#object-detection) model, see [CLI guide](docs/cli.md#predict-command-usage) | | [predict-fiftyone](https://github.com/obss/sahi/blob/main/docs/cli.md#predict-fiftyone-command-usage) | Perform sliced/standard prediction using any supported model and explore results in [fiftyone app](https://github.com/voxel51/fiftyone), [learn more](docs/fiftyone.md) | | [coco slice](https://github.com/obss/sahi/blob/main/docs/cli.md#coco-slice-command-usage) | Automatically slice COCO annotation and image files, see [slicing utilities](docs/slicing.md) | | [coco fiftyone](https://github.com/obss/sahi/blob/main/docs/cli.md#coco-fiftyone-command-usage) | Explore multiple prediction results on your COCO dataset with [fiftyone ui](https://github.com/voxel51/fiftyone) ordered by number of misdetections | | [coco evaluate](https://github.com/obss/sahi/blob/main/docs/cli.md#coco-evaluate-command-usage) | Evaluate classwise COCO AP and AR for given predictions and ground truth, check [COCO utilities](docs/coco.md) | | [coco analyse](https://github.com/obss/sahi/blob/main/docs/cli.md#coco-analyse-command-usage) | Calculate and export many error analysis plots, see the [complete guide](docs/index.md) | | [coco yolo](https://github.com/obss/sahi/blob/main/docs/cli.md#coco-yolo-command-usage) | Automatically convert any COCO dataset to [ultralytics](https://github.com/ultralytics/ultralytics) format | ### Approved by the Community [📜 List of publications that cite SAHI (currently 600+)](https://scholar.google.com/scholar?hl=en&as_sdt=2005&sciodt=0,5&cites=14065474760484865747&scipsc=&q=&scisbd=1) [🏆 List of competition winners that used SAHI](https://github.com/obss/sahi/discussions/688) ### Approved by AI Tools SAHI's documentation is [indexed in Context7 MCP](https://context7.com/obss/sahi), providing AI coding assistants with up-to-date, version-specific code examples and API references. We also provide an [llms.txt](https://context7.com/obss/sahi/llms.txt) file following the emerging standard for AI-readable documentation. To integrate SAHI docs with your AI development workflow, check out the [Context7 MCP installation guide](https://github.com/upstash/context7#%EF%B8%8F-installation). ## ### Basic Installation ```bash pip install sahi ``` **Detailed Installation (Click to open)** - Install your desired version of pytorch and torchvision: ```console pip install torch==2.7.0 torchvision==0.22.0 --index-url https://download.pytorch.org/whl/cu126 ``` (torch 2.1.2 is required for mmdet support): ```console pip install torch==2.1.2 torchvision==0.16.2 --index-url https://download.pytorch.org/whl/cu121 ``` - Install your desired detection framework (ultralytics): ```console pip install ultralytics>=8.3.161 ``` - Install your desired detection framework (huggingface): ```console pip install transformers>=4.49.0 timm ``` - Install your desired detection framework (yolov5): ```console pip install yolov5==7.0.14 sahi==0.12.1 ``` - Install your desired detection framework (mmdet): ```console pip install mim mim install mmdet==3.3.0 ``` - Install your desired detection framework (roboflow): ```console pip install inference>=0.51.5 rfdetr>=1.6.2 ``` ## ### Learning Resources | Resource | Type | | --------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- | | [Introduction to SAHI](https://medium.com/codable/sahi-a-vision-library-for-performing-sliced-inference-on-large-images-small-objects-c8b086af3b80) | Blog Post | | [2025 Video Tutorial](https://www.youtube.com/watch?v=ILqMBah5ZvI) ⭐ | Video | | [Official Paper](https://ieeexplore.ieee.org/document/9897990) (ICIP 2022 oral) | Paper | | [Pretrained Weights & ICIP 2022 Paper Files](https://github.com/fcakyon/small-object-detection-benchmark) | Benchmark | | [Visualizing and Evaluating SAHI Predictions with FiftyOne](https://voxel51.com/blog/how-to-detect-small-objects/) | Blog Post | | [Exploring SAHI on learnopencv.com](https://learnopencv.com/slicing-aided-hyper-inference/) | Article | | [Slicing Aided Hyper Inference Explained by Encord](https://encord.com/blog/slicing-aided-hyper-inference-explained/) | Article | | [Video Tutorial: SAHI for Small Object Detection](https://www.youtube.com/watch?v=UuOJKxn-M8&t=270s) | Video | | [Satellite Object Detection](https://blog.ml6.eu/how-to-detect-small-objects-in-very-large-images-70234bab0f98) | Blog Post | | [COCO Dataset Conversion](https://medium.com/codable/convert-any-dataset-to-coco-object-detection-format-with-sahi-95349e1fe2b7) | Blog Post | | [Kaggle Notebook](https://www.kaggle.com/remekkinas/sahi-slicing-aided-hyper-inference-yv5-and-yx) | Notebook | | [Error Analysis Plots & Evaluation](https://github.com/obss/sahi/discussions/622) ⭐ | Discussion | | [Interactive Result Visualization and Inspection](https://github.com/obss/sahi/discussions/624) ⭐ | Discussion | | [Video Inference Support](https://github.com/obss/sahi/discussions/626) | Discussion | | [Slicing Operation Notebook](demo/slicing.ipynb) | Notebook | | [Complete Documentation](docs/index.md) | Docs | ### Notebooks & Demos | Framework | Notebook | Demo | | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | | YOLO26 | [](https://colab.research.google.com/github/obss/sahi/blob/main/demo/inference_for_ultralytics.ipynb) | - | | YOLO11 | [](https://colab.research.google.com/github/obss/sahi/blob/main/demo/inference_for_ultralytics.ipynb) | - | | YOLO11-OBB | [](https://colab.research.google.com/github/obss/sahi/blob/main/demo/inference_for_ultralytics.ipynb) | - | | YOLOE | [](https://colab.research.google.com/github/obss/sahi/blob/main/demo/inference_for_ultralytics_yoloe.ipynb) | - | | Roboflow / RF-DETR | [](https://colab.research.google.com/github/obss/sahi/blob/main/demo/inference_for_roboflow.ipynb) | - | | RT-DETR v2 | [](https://colab.research.google.com/github/obss/sahi/blob/main/demo/inference_for_huggingface.ipynb) | - | | RT-DETR | [](https://colab.research.google.com/github/obss/sahi/blob/main/demo/inference_for_rtdetr.ipynb) | - | | HuggingFace | [](https://colab.research.google.com/github/obss/sahi/blob/main/demo/inference_for_huggingface.ipynb) | - | | GroundingDINO | [](https://colab.research.google.com/github/obss/sahi/blob/main/demo/inference_for_groundingdino.ipynb) | - | | YOLOv5 | [](https://colab.research.google.com/github/obss/sahi/blob/main/demo/inference_for_yolov5.ipynb) | - | | MMDetection | [](https://colab.research.google.com/github/obss/sahi/blob/main/demo/inference_for_mmdetection.ipynb) | - | | Detectron2 | [](https://colab.research.google.com/github/obss/sahi/blob/main/demo/inference_for_detectron2.ipynb) | - | | TorchVision | [](https://colab.research.google.com/github/obss/sahi/blob/main/demo/inference_for_torchvision.ipynb) | - | | YOLOX | - | [](https://huggingface.co/spaces/fcakyon/sahi-yolox) | [](https://huggingface.co/spaces/fcakyon/sahi-yolox) ### Framework Agnostic Sliced/Standard Prediction Find detailed info on using `sahi predict` command in the [CLI documentation](docs/cli.md#predict-command-usage) and explore the [prediction API](docs/predict.md) for advanced usage. Find detailed info on video inference at [video inference tutorial](https://github.com/obss/sahi/discussions/626). ### Error Analysis Plots & Evaluation Find detailed info at [Error Analysis Plots & Evaluation](https://github.com/obss/sahi/discussions/622). ### Interactive Visualization & Inspection Explore [FiftyOne integration](docs/fiftyone.md) for interactive visualization and inspection. ### Other Utilities Check the [comprehensive COCO utilities guide](docs/coco.md) for YOLO conversion, dataset slicing, subsampling, filtering, merging, and splitting operations. Learn more about the [slicing utilities](docs/slicing.md) for detailed control over image and dataset slicing parameters. ## If you use this package in your work, please cite as: ```bibtex @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} } ``` ```bibtex @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} } ``` ## We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) to get started. Thank you 🙏 to all our contributors! --- ## File: docs/cli.md --- tags: - cli - inference - coco - slicing - evaluation - fiftyone --- # CLI Commands SAHI provides a comprehensive command-line interface for object detection tasks. This guide covers all available commands with detailed examples and options. ## `predict` command usage Perform object detection inference on images or videos using sliced inference for better small object detection. ### Basic Usage ```bash sahi predict --source image/file/or/folder --model_path path/to/model --model_config_path path/to/config ``` This will perform sliced inference with default parameters and export prediction visuals to `runs/predict/exp` folder. ### Video Input Support SAHI supports video inference with the same command structure: ```bash sahi predict --model_path yolo26s.pt --model_type ultralytics --source video.mp4 ``` #### Real-time Video Visualization View video rendering during inference with the `--view_video` flag: ```bash sahi predict --model_path yolo26s.pt --model_type ultralytics --source video.mp4 --view_video ``` **Keyboard Controls:** - **`D`** - Forward 100 frames - **`A`** - Rewind 100 frames - **`G`** - Forward 20 frames - **`F`** - Rewind 20 frames - **`Esc`** - Exit viewer > **Tip:** If `--view_video` is slow, add `--frame_skip_interval=20` to skip > intervals of 20 frames. ### Advanced Slicing Parameters Customize the slicing behavior for optimal detection: ```bash sahi predict --slice_width 512 --slice_height 512 \ --overlap_height_ratio 0.1 --overlap_width_ratio 0.1 \ --model_confidence_threshold 0.25 \ --source image/file/or/folder \ --model_path path/to/model \ --model_config_path path/to/config ``` #### Model Configuration **Detection Framework:** - `--model_type mmdet` - For MMDetection models - `--model_type ultralytics` - For Ultralytics/YOLOv5/YOLO11/YOLO26 models - `--model_type huggingface` - For HuggingFace models - `--model_type torchvision` - For Torchvision models **Confidence Threshold:** - `--model_confidence_threshold 0.25` - Set minimum confidence for detections #### Postprocessing Options **Postprocess Type:** - `--postprocess_type GREEDYNMM` - Greedy non-maximum merging (default) - `--postprocess_type NMS` - Standard non-maximum suppression **Match Metrics:** - `--postprocess_match_metric IOS` - Intersection over smaller area (default) - `--postprocess_match_metric IOU` - Intersection over union **Additional Options:** - `--postprocess_match_threshold 0.5` - Set matching threshold - `--postprocess_class_agnostic` - Ignore category IDs during postprocessing #### Export Options **Visual Exports:** - `--novisual` - Disable prediction visualization exports - `--visual_export_format JPG` - Set export format (JPG, PNG, etc.) **Data Exports:** - `--export_pickle` - Export prediction pickles - `--export_crop` - Export cropped detections #### Inference Modes By default, SAHI performs multi-stage inference (both standard and sliced prediction): - `--no_sliced_prediction` - Disable sliced inference (standard only) - `--no_standard_prediction` - Disable standard inference (sliced only) ### COCO Dataset Evaluation Perform prediction using a COCO annotation file for evaluation: ```bash sahi predict --dataset_json_path dataset.json \ --source path/to/coco/image/folder \ --model_path path/to/model ``` Adding `--dataset_json_path` also exports predictions as a COCO JSON file to `runs/predict/exp/result.json`. You can then use: - `sahi coco evaluate` - Calculate COCO evaluation metrics - `sahi coco analyse` - Generate detailed error analysis plots ### Progress Reporting Enable a progress bar to track inference progress: ```bash sahi predict --model_path path/to/model --source images/ \ --slice_width 512 --slice_height 512 --progress_bar ``` > **Note:** The `--progress_bar` flag controls CLI visual progress (tqdm). The > `progress_callback` parameter is available in the Python API but not exposed > as a CLI option. --- ## `predict-fiftyone` command usage Perform sliced inference and visualize results interactively using the FiftyOne App. ### Basic Usage ```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 ``` This will perform sliced inference with default parameters and launch the FiftyOne App for interactive exploration. ### Additional Parameters All parameters from the [`sahi predict`](#predict-command-usage) command are supported. --- ## `coco fiftyone` command usage Visualize and compare multiple detection results on your COCO dataset using FiftyOne UI. ### Basic Usage You need to convert your predictions to [COCO result JSON format](https://cocodataset.org/#format-results). Use [`sahi predict`](#predict-command-usage) to generate this format. ```bash sahi coco fiftyone --image_dir dir/to/images \ --dataset_json_path dataset.json \ cocoresult1.json cocoresult2.json ``` This opens a FiftyOne app that visualizes the dataset and compares 2 detection results ordered by misdetections. ### Options - `--iou_threshold 0.5` - Set IOU threshold for FP/TP classification --- ## `coco slice` command usage Slice large images and their COCO format annotations into smaller tiles. ### Basic Usage ```bash sahi coco slice --image_dir dir/to/images \ --dataset_json_path dataset.json ``` Slices images and COCO annotations, exporting them to the output folder. ### Parameters **Slice Dimensions:** - `--slice_size 512` - Set slice height and width (default: 512) **Overlap:** - `--overlap_ratio 0.2` - Set overlap ratio for height/width (default: 0.2) **Filtering:** - `--ignore_negative_samples` - Exclude images without annotations **Output:** - `--out_dir output/folder` - Specify output directory --- ## `coco yolo` command usage Convert COCO format datasets to YOLO format for training with Ultralytics. > **Windows Users:** Open Anaconda prompt or Windows CMD **as administrator** to > create symlinks properly. ### Basic Usage ```bash sahi coco yolo --image_dir dir/to/images \ --dataset_json_path dataset.json \ --train_split 0.9 ``` Converts the COCO dataset to YOLO format and exports to `runs/coco2yolo/exp` folder. ### Parameters - `--train_split 0.9` - Set training split ratio (default: 0.9) - `--out_dir output/folder` - Specify output directory --- ## `coco evaluate` command usage Calculate COCO evaluation metrics (mAP, mAR) for your predictions. ### Basic Usage You need to convert your predictions to [COCO result JSON format](https://cocodataset.org/#format-results). Use [`sahi predict`](#predict-command-usage) to generate this format. ```bash sahi coco evaluate --dataset_json_path dataset.json \ --result_json_path result.json ``` Calculates COCO evaluation metrics and exports results to the output folder. ### Parameters **Metric Type:** - `--type bbox` - Evaluate bounding box detections (default) - `--type mask` - Evaluate instance segmentation masks **Scoring Options:** - `--classwise` - Calculate per-class scores in addition to overall metrics **Detection Limits:** - `--proposal_nums "[10 100 500]"` - Set max detections per image (default: `[100, 300, 1000]`) **IOU Thresholds:** - `--iou_thrs 0.5` - Specify IOU threshold (default: 0.50:0.95 and 0.5) **Output:** - `--out_dir output/folder` - Specify output directory --- ## `coco analyse` command usage Generate detailed error analysis plots for COCO predictions. ### Basic Usage You need to convert your predictions to [COCO result JSON format](https://cocodataset.org/#format-results). Use [`sahi predict`](#predict-command-usage) to generate this format. ```bash sahi coco analyse --dataset_json_path dataset.json \ --result_json_path result.json \ --out_dir output/directory ``` Generates comprehensive error analysis plots and exports them to the specified folder. ### Parameters **Analysis Type:** - `--type bbox` - Analyze bounding box detections (default) - `--type segm` - Analyze instance segmentation masks **Additional Plots:** - `--extraplots` - Generate extra mAP bar plots and annotation area statistics **Area Regions:** - `--areas "[1024 9216 10000000000]"` - Define area regions for analysis (default: small/medium/large COCO areas) --- ## `env` command usage Display 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. ``` --- ## `version` command usage Display your currently installed SAHI version. ### Usage ```bash sahi version ``` --- ## Custom Scripts All scripts can be downloaded from the [scripts directory](https://github.com/obss/sahi/tree/main/scripts) and modified for your specific needs. After installing SAHI via pip, all scripts can be called from any directory: ```bash python script_name.py ``` --- ## Additional Resources - [Prediction Utilities](predict.md): Python API for prediction parameters and visualization - [COCO Utilities](coco.md): Python API for COCO dataset operations - [Model Integrations](guides/models.md): Framework-specific setup guides - [Interactive Notebooks](notebooks.md): Hands-on examples for all frameworks --- ## File: docs/coco.md --- tags: - coco - dataset - annotation - slicing - evaluation --- # COCO Utilities SAHI provides a full suite of tools for creating, manipulating, and converting COCO format datasets. ## Creating a Dataset ```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") ``` ### Evaluating with pycocotools ```python from pycocotools.cocoeval import COCOeval from pycocotools.coco import COCO coco_gt = COCO(annotation_file="coco_dataset.json") coco_dt = coco_gt.loadRes("coco_predictions.json") evaluator = COCOeval(coco_gt, coco_dt, "bbox") evaluator.evaluate() evaluator.accumulate() evaluator.summarize() ``` --- ## Loading a Dataset ```python from sahi.utils.coco import Coco coco = Coco.from_coco_dict_or_path("coco.json") ``` --- ## Slicing Images and Annotations Slice large images and their COCO annotations into a grid of smaller tiles: ```python 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, ) ``` --- ## Splitting into Train/Val ```python from sahi.utils.coco import Coco from sahi.utils.file import save_json coco = Coco.from_coco_dict_or_path("coco.json") result = coco.split_coco_as_train_val(train_split_rate=0.85) save_json(result["train_coco"].json, "train_split.json") save_json(result["val_coco"].json, "val_split.json") ``` --- ## Merging Datasets ```python from sahi.utils.coco import Coco from sahi.utils.file import save_json coco_1 = Coco.from_coco_dict_or_path("coco1.json", image_dir="images_1/") coco_2 = Coco.from_coco_dict_or_path("coco2.json", image_dir="images_2/") coco_1.merge(coco_2) save_json(coco_1.json, "merged_coco.json") ``` --- ## Filtering and Updating ### By categories Select specific categories and remap their IDs: ```python from sahi.utils.coco import Coco from sahi.utils.file import save_json coco = Coco.from_coco_dict_or_path("coco.json") desired_name2id = {"big_vehicle": 1, "car": 2, "human": 3} coco.update_categories(desired_name2id) save_json(coco.json, "updated_coco.json") ``` ### By annotation area ```python from sahi.utils.coco import Coco from sahi.utils.file import save_json coco = Coco.from_coco_dict_or_path("coco.json") # Filter by minimum area area_filtered = coco.get_area_filtered_coco(min=50) # Filter by min and max area area_filtered = coco.get_area_filtered_coco(min=50, max_val=10000) # Per-category area intervals intervals = { "human": {"min": 20, "max": 10000}, "vehicle": {"min": 50, "max": 15000}, } area_filtered = coco.get_area_filtered_coco(intervals_per_category=intervals) save_json(area_filtered.json, "area_filtered_coco.json") ``` ### Keep images without annotations By default, images without annotations are excluded. To keep them: ```python coco = Coco.from_coco_dict_or_path("coco.json", ignore_negative_samples=False) ``` ### Clip bounding boxes to image dimensions ```python # On load coco = Coco.from_coco_dict_or_path("coco.json", clip_bboxes_to_img_dims=True) # Or on an existing object coco = coco.get_coco_with_clipped_bboxes() ``` --- ## Sampling ### Subsample ```python from sahi.utils.coco import Coco from sahi.utils.file import save_json coco = Coco.from_coco_dict_or_path("coco.json") # Keep 1/10 of images subsampled = coco.get_subsampled_coco(subsample_ratio=10) # Subsample only images containing a specific category subsampled = coco.get_subsampled_coco(subsample_ratio=10, category_id=0) # Reduce negative samples (images without annotations) to 1/10 subsampled = coco.get_subsampled_coco(subsample_ratio=10, category_id=-1) save_json(subsampled.json, "subsampled_coco.json") ``` ### Upsample ```python from sahi.utils.coco import Coco from sahi.utils.file import save_json coco = Coco.from_coco_dict_or_path("coco.json") # Repeat each sample 10 times upsampled = coco.get_upsampled_coco(upsample_ratio=10) # Upsample only images containing a specific category upsampled = coco.get_upsampled_coco(upsample_ratio=10, category_id=0) save_json(upsampled.json, "upsampled_coco.json") ``` --- ## Converting to YOLO Format ### Single dataset with auto-split ```python from sahi.utils.coco import Coco coco = Coco.from_coco_dict_or_path("coco.json", image_dir="coco_images/") coco.export_as_yolo(output_dir="output/folder/dir", train_split_rate=0.85) ``` ### Pre-split train/val datasets ```python from sahi.utils.coco import Coco, export_coco_as_yolo train_coco = Coco.from_coco_dict_or_path("train_coco.json", image_dir="coco_images/") val_coco = Coco.from_coco_dict_or_path("val_coco.json", image_dir="coco_images/") data_yml_path = export_coco_as_yolo( output_dir="output/folder/dir", train_coco=train_coco, val_coco=val_coco, ) ``` --- ## Dataset Statistics ```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}, # } ``` --- ## Cleaning Invalid Results Remove invalid predictions from a COCO results JSON: ```python from sahi.utils.coco import remove_invalid_coco_results from sahi.utils.file import save_json coco_results = remove_invalid_coco_results("coco_result.json") save_json(coco_results, "fixed_coco_result.json") # Also filter out bboxes exceeding image dimensions coco_results = remove_invalid_coco_results("coco_result.json", "coco_dataset.json") ``` --- ## Additional Resources - [Interactive notebooks](notebooks.md): Hands-on examples including COCO dataset slicing - [CLI documentation](cli.md): Command-line operations for COCO datasets --- ## File: docs/fiftyone.md --- tags: - fiftyone - visualization - coco - dataset --- # FiftyOne Visualization [FiftyOne](https://github.com/voxel51/fiftyone) provides an interactive UI for exploring detection results, comparing predictions, and debugging model performance. Supported version: `pip install fiftyone>=0.14.2,<0.15.0` ## Explore a COCO Dataset ```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() ``` ## Visualize SAHI Predictions Run sliced inference and convert results to FiftyOne format: ```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, ) result = get_sliced_prediction( "image.jpg", detection_model, slice_height=512, slice_width=512, overlap_height_ratio=0.2, overlap_width_ratio=0.2, ) # Convert to FiftyOne detection format fiftyone_detections = result.to_fiftyone_detections() ``` ## Compare Multiple Detection Results Use the CLI to visualize a dataset alongside multiple prediction results, ordered by misdetections: ```bash sahi coco fiftyone \ --image_dir dir/to/images \ --dataset_json_path dataset.json \ cocoresult1.json cocoresult2.json ``` Set the IOU threshold for FP/TP classification: ```bash sahi coco fiftyone --iou_threshold 0.5 \ --image_dir dir/to/images \ --dataset_json_path dataset.json \ cocoresult1.json ``` ## Predict and Explore in One Step The `predict-fiftyone` CLI command runs sliced inference and opens results in FiftyOne directly: ```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 ``` --- ## File: docs/predict.md --- tags: - inference - slicing - batch-inference - visualization - object-detection - small-object-detection --- # Prediction Utilities ## Sliced inference ```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='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 ) ``` ## Standard inference ```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, ) ``` ## Batch inference ### Batch prediction over a folder or file list Use the high-level `predict` function to run sliced inference over many images at once and export results automatically: ```python 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, progress_bar=False, ) ``` ### Low-level batch inference API `perform_batch_inference` lets you run a model over multiple images in a single call and retrieve per-image prediction lists. Ultralytics YOLO models use native GPU batching; all other models fall back to sequential single-image inference with the same API. ```python import cv2 from sahi import AutoDetectionModel detection_model = AutoDetectionModel.from_pretrained( model_type="ultralytics", model_path="yolo26n.pt", confidence_threshold=0.25, device="cuda:0", ) # Load a batch of images as numpy arrays (H, W, C) in RGB images = [cv2.cvtColor(cv2.imread(p), cv2.COLOR_BGR2RGB) for p in image_paths] # Run batch inference (native GPU batching for Ultralytics) detection_model.perform_batch_inference(images) # Provide per-image shift amounts and full image sizes (use [[0, 0]] defaults # when images are not slices) shift_amount_list = [[0, 0]] * len(images) full_shape_list = [[img.shape[0], img.shape[1]] for img in images] detection_model.convert_original_predictions( shift_amount=shift_amount_list, full_shape=full_shape_list, ) # Access predictions per image for i, preds in enumerate(detection_model.object_prediction_list_per_image): print(f"Image {i}: {len(preds)} detections") for pred in preds: print(pred.category.name, pred.score.value, pred.bbox.to_xyxy()) ``` !!! note "Single-image compatibility" The existing `object_prediction_list` property is unchanged and returns predictions for the first image, so code that uses `perform_inference` + `convert_original_predictions` + `object_prediction_list` continues to work without modification. ## Progress-Bar Two options were added to control and receive progress updates when running sliced inference over many slices: - `progress_bar` (bool): When True, shows a tqdm progress bar during slice processing. Useful for visual feedback in terminals and notebooks. Default is False. - `progress_callback` (callable): A callback function that will be called after each slice (or slice group) is processed. The callback receives two integer arguments: `(current_slice_index, total_slices)`. Use this to integrate custom progress reporting (for example, update a GUI element or log progress to a file). Example using the callback: ```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 ) ``` !!! tip "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)`. ## Exclude custom classes on inference ```python 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 ) ``` ## Visualization parameters and export formats ```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 ``` !!! tip "Interactive Demos" Want to see these prediction utilities in action? Check out our [interactive notebooks](notebooks.md) with hands-on examples for every supported framework. --- ## File: docs/slicing.md --- tags: - slicing - api-reference - coco - dataset - small-object-detection --- # Slicing ## Slicing ::: sahi.slicing ### Slicing Utilities - Slice an image: ```python 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, ) ``` - Slice a COCO formatted dataset: ```python from sahi.slicing import slice_coco coco_dict, coco_path = slice_coco( coco_annotation_file_path=coco_annotation_file_path, image_dir=image_dir, slice_height=256, slice_width=256, overlap_height_ratio=0.2, overlap_width_ratio=0.2, ) ``` ### Interactive Demo Want to experiment with different slicing parameters and see their effects? Check out our [interactive notebooks](notebooks.md) for hands-on examples. --- ## File: docs/index.md --- hide: - navigation - toc tags: - getting-started - object-detection - small-object-detection - slicing - instance-segmentation --- ## What is SAHI? SAHI (Slicing Aided Hyper Inference) is an open-source framework that provides a generic slicing-aided inference and fine-tuning pipeline for small object detection. Detecting small objects and those far from the camera is a major challenge in surveillance applications, as they are represented by a small number of pixels and lack sufficient detail for conventional detectors. SAHI addresses this by applying a unique methodology that can be used with any object detector without requiring additional fine-tuning. Experimental evaluations on the Visdrone and xView aerial object detection datasets show that SAHI can increase object detection AP by up to 6.8% for FCOS, 5.1% for VFNet, and 5.3% for TOOD detectors. With slicing-aided fine-tuning, the accuracy can be further improved, resulting in a cumulative increase of 12.7%, 13.4%, and 14.5% AP, respectively. The technique has been successfully integrated with [Ultralytics YOLOv8](https://docs.ultralytics.com/models/yolov8), [Ultralytics YOLO11](https://docs.ultralytics.com/models/yolo11), [Ultralytics YOLO26](https://docs.ultralytics.com/models/yolo26), HuggingFace Transformers (detection,segmentation), RT-DETR, TorchVision, MMDetection, Detectron2, YOLOv5, YOLOE, YOLO-World, and Roboflow RF-DETR models. - :material-clock-fast:{ .lg .middle } __Getting Started__ --- Install `sahi` with pip and get up and running in minutes. [:octicons-arrow-right-24: Quickstart](quick-start.md) - :material-lightbulb-outline:{ .lg .middle } __How It Works__ --- Understand the slicing algorithm, when to use it, and how to tune it. [:octicons-arrow-right-24: Sliced Inference](guides/sliced-inference.md) - :material-puzzle-outline:{ .lg .middle } __Model Integrations__ --- Use SAHI with Ultralytics, HuggingFace, MMDetection, TorchVision, and more. [:octicons-arrow-right-24: All models](guides/models.md) - :material-image:{ .lg .middle } __Predict__ --- Predict on new images, videos, and streams with SAHI. [:octicons-arrow-right-24: Learn more](predict.md) - :material-content-cut:{ .lg .middle } __Slicing__ --- Learn how to slice large images and datasets for inference. [:octicons-arrow-right-24: Learn more](slicing.md) - :material-database:{ .lg .middle } __COCO Utilities__ --- Work with COCO format datasets, including creation, splitting, and filtering. [:octicons-arrow-right-24: Learn more](coco.md) - :material-console:{ .lg .middle } __CLI Commands__ --- Use SAHI from the command-line for prediction and dataset operations. [:octicons-arrow-right-24: Learn more](cli.md) - :material-eye:{ .lg .middle } __FiftyOne__ --- Interactively explore and compare detection results. [:octicons-arrow-right-24: Learn more](fiftyone.md) - :material-notebook:{ .lg .middle } __Notebooks__ --- Hands-on Colab notebooks for every supported framework. [:octicons-arrow-right-24: Browse notebooks](notebooks.md)