ultralytics 8.0.171 new SAHI guide and callbacks fix (#4748)

Co-authored-by: chuzihang <49548797+Aria-Leo@users.noreply.github.com>
Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: Sanghyun Choi <farewell518@gmail.com>
Co-authored-by: Awsome <1579093407@qq.com>
Co-authored-by: ConanQZ <49194386+ConanQZ@users.noreply.github.com>

docs/guides/index.md

@@ -1,7 +1,7 @@
 ---
 comments: true
 description: In-depth exploration of Ultralytics' YOLO. Learn about the YOLO object detection model, how to train it on custom data, multi-GPU training, exporting, predicting, deploying, and more.
-keywords: Ultralytics, YOLO, Deep Learning, Object detection, PyTorch, Tutorial, Multi-GPU training, Custom data training
+keywords: Ultralytics, YOLO, Deep Learning, Object detection, PyTorch, Tutorial, Multi-GPU training, Custom data training, SAHI, Tiled Inference
 ---
 
 # Comprehensive Tutorials to Ultralytics YOLO
@@ -16,5 +16,12 @@ Here's a compilation of in-depth guides to help you master different aspects of
 
 * [K-Fold Cross Validation](kfold-cross-validation.md) 🚀 NEW: Learn how to improve model generalization using K-Fold cross-validation technique.
 * [Hyperparameter Tuning](hyperparameter-tuning.md) 🚀 NEW: Discover how to optimize your YOLO models by fine-tuning hyperparameters using the Tuner class and genetic evolution algorithms.
+* [Using YOLOv8 with SAHI for Sliced Inference](sahi-tiled-inference.md) 🚀 NEW: Comprehensive guide on leveraging SAHI's sliced inference capabilities with YOLOv8 for object detection in high-resolution images.
 
-Note: More guides about training, exporting, predicting, and deploying with Ultralytics YOLO are coming soon. Stay tuned!
+## Contribute to Our Guides
+
+We welcome contributions from the community! If you've mastered a particular aspect of Ultralytics YOLO that's not yet covered in our guides, we encourage you to share your expertise. Writing a guide is a great way to give back to the community and help us make our documentation more comprehensive and user-friendly.
+
+To get started, please read our [Contributing Guide](https://docs.ultralytics.com/help/contributing) for guidelines on how to open up a Pull Request (PR) 🛠️. We look forward to your contributions!
+
+Let's work together to make the Ultralytics YOLO ecosystem more robust and versatile 🙏!

docs/guides/sahi-tiled-inference.md

@@ -0,0 +1,147 @@
+---
+comments: true
+description: A comprehensive guide on how to use YOLOv8 with SAHI for standard and sliced inference in object detection tasks.
+keywords: YOLOv8, SAHI, Sliced Inference, Object Detection, Ultralytics, Large Scale Image Analysis, High-Resolution Imagery
+---
+
+# Ultralytics Docs: Using YOLOv8 with SAHI for Sliced Inference
+
+Welcome to the Ultralytics documentation on how to use YOLOv8 with SAHI (Slicing Aided Hyper Inference). In this comprehensive guide, we'll discuss what SAHI is, the benefits of sliced inference, and how to use SAHI with YOLOv8 for object detection tasks.
+
+![SAHI Sliced Inference](https://raw.githubusercontent.com/obss/sahi/main/resources/sliced_inference.gif)
+
+## Table of Contents
+
+1. [Introduction to SAHI](#introduction-to-sahi)
+2. [What is Sliced Inference?](#what-is-sliced-inference)
+3. [Installation and Preparation](#installation-and-preparation)
+4. [Standard Inference with YOLOv8](#standard-inference-with-yolov8)
+5. [Sliced Inference with YOLOv8](#sliced-inference-with-yolov8)
+6. [Handling Prediction Results](#handling-prediction-results)
+7. [Batch Prediction](#batch-prediction)
+
+## Introduction to SAHI
+
+SAHI is a powerful library aimed at performing efficient and accurate object detection over slices of an image, particularly useful for large scale and high-resolution imagery. It integrates seamlessly with YOLO models and allows for a more efficient usage of computational resources.
+
+## What is Sliced Inference?
+
+Sliced Inference is a technique that divides a large image into smaller slices, performs object detection on each slice, and then aggregates the results back onto the original image. This method is especially beneficial when dealing with high-resolution images as it significantly reduces the computational load without sacrificing detection accuracy.
+
+## Installation and Preparation
+
+### Installation
+
+To get started, install the latest versions of SAHI and Ultralytics:
+
+```bash
+pip install -U ultralytics sahi
+```
+
+### Import Modules and Download Resources
+
+Here's how to import the necessary modules and download a YOLOv8 model and some test images:
+
+```python
+from sahi.utils.yolov8 import download_yolov8s_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 pathlib import Path
+from IPython.display import Image
+
+# Download YOLOv8 model
+yolov8_model_path = "models/yolov8s.pt"
+download_yolov8s_model(yolov8_model_path)
+
+# Download test images
+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')
+```
+
+## Standard Inference with YOLOv8
+
+### Instantiate the Model
+
+You can instantiate a YOLOv8 model for object detection like this:
+
+```python
+detection_model = AutoDetectionModel.from_pretrained(
+    model_type='yolov8',
+    model_path=yolov8_model_path,
+    confidence_threshold=0.3,
+    device="cpu",  # or 'cuda:0'
+)
+```
+
+### Perform Standard Prediction
+
+Perform standard inference using an image path or a numpy image.
+
+```python
+# With an image path
+result = get_prediction("demo_data/small-vehicles1.jpeg", detection_model)
+
+# With a numpy image
+result = get_prediction(read_image("demo_data/small-vehicles1.jpeg"), detection_model)
+```
+
+### Visualize Results
+
+Export and visualize the predicted bounding boxes and masks:
+
+```python
+result.export_visuals(export_dir="demo_data/")
+Image("demo_data/prediction_visual.png")
+```
+
+## Sliced Inference with YOLOv8
+
+Perform sliced inference by specifying the slice dimensions and overlap ratios:
+
+```python
+result = get_sliced_prediction(
+    "demo_data/small-vehicles1.jpeg",
+    detection_model,
+    slice_height=256,
+    slice_width=256,
+    overlap_height_ratio=0.2,
+    overlap_width_ratio=0.2
+)
+```
+
+## Handling Prediction Results
+
+SAHI provides a `PredictionResult` object, which can be converted into various annotation formats:
+
+```python
+# Access the object prediction list
+object_prediction_list = result.object_prediction_list
+
+# Convert to COCO annotation, COCO prediction, imantics, and fiftyone formats
+result.to_coco_annotations()[:3]
+result.to_coco_predictions(image_id=1)[:3]
+result.to_imantics_annotations()[:3]
+result.to_fiftyone_detections()[:3]
+```
+
+## Batch Prediction
+
+For batch prediction on a directory of images:
+
+```python
+predict(
+    model_type="yolov8",
+    model_path="path/to/yolov8n.pt",
+    model_device="cpu",  # or 'cuda:0'
+    model_confidence_threshold=0.4,
+    source="path/to/dir",
+    slice_height=256,
+    slice_width=256,
+    overlap_height_ratio=0.2,
+    overlap_width_ratio=0.2,
+)
+```
+
+That's it! Now you're equipped to use YOLOv8 with SAHI for both standard and sliced inference.

docs/integrations/index.md

@@ -59,3 +59,13 @@ We also support a variety of model export formats for deployment in different en
 | [NCNN](https://github.com/Tencent/ncnn)                            | `ncnn`            | `yolov8n_ncnn_model/`     | ✅        | `imgsz`, `half`                                     |
 
 Explore the links to learn more about each integration and how to get the most out of them with Ultralytics.
+
+## Contribute to Our Integrations
+
+We're always excited to see how the community integrates Ultralytics YOLO with other technologies, tools, and platforms! If you have successfully integrated YOLO with a new system or have valuable insights to share, consider contributing to our Integrations Docs.
+
+By writing a guide or tutorial, you can help expand our documentation and provide real-world examples that benefit the community. It's an excellent way to contribute to the growing ecosystem around Ultralytics YOLO.
+
+To contribute, please check out our [Contributing Guide](https://docs.ultralytics.com/help/contributing) for instructions on how to submit a Pull Request (PR) 🛠️. We eagerly await your contributions!
+
+Let's collaborate to make the Ultralytics YOLO ecosystem more expansive and feature-rich 🙏!