{"id":6865,"library":"sahi","title":"SAHI (Slicing Aided Hyper Inference)","description":"SAHI (Slicing Aided Hyper Inference) is a lightweight Python library designed to improve object detection and instance segmentation performance, especially for small objects in large or high-resolution images. It achieves this by dividing images into smaller overlapping slices, running inference on each slice, and then intelligently merging the predictions. Currently at version 0.11.36, SAHI has a frequent release cadence, often issuing patch releases to address bugs and introduce minor enhancements.","status":"active","version":"0.11.36","language":"en","source_language":"en","source_url":"https://github.com/obss/sahi","tags":["computer vision","object detection","instance segmentation","deep learning","slicing inference","small object detection","YOLO","MMDetection","Detectron2","PyTorch"],"install":[{"cmd":"pip install sahi","lang":"bash","label":"Basic Installation"},{"cmd":"pip install sahi[yolov5]","lang":"bash","label":"For YOLOv5 Support"},{"cmd":"pip install sahi[ultralytics]","lang":"bash","label":"For Ultralytics (YOLOv8, etc.) Support"},{"cmd":"pip install sahi[mmdet]","lang":"bash","label":"For MMDetection Support"},{"cmd":"pip install sahi[detectron2]","lang":"bash","label":"For Detectron2 Support"},{"cmd":"pip install sahi[huggingface]","lang":"bash","label":"For HuggingFace Support"},{"cmd":"pip install sahi[torchvision]","lang":"bash","label":"For TorchVision Support"}],"dependencies":[{"reason":"Underlying deep learning framework for most model backends.","package":"torch","optional":false},{"reason":"Often used with PyTorch models, especially for computer vision tasks.","package":"torchvision","optional":false},{"reason":"Used for image processing utilities.","package":"opencv-python","optional":false},{"reason":"Required for YOLOv8/YOLOv5 model support.","package":"ultralytics","optional":true},{"reason":"Required for MMDetection framework support.","package":"mmdet","optional":true},{"reason":"Required for Detectron2 framework support.","package":"detectron2","optional":true},{"reason":"Required for HuggingFace object detector support.","package":"transformers","optional":true},{"reason":"Required for geometric operations, especially on Windows with certain installations.","package":"shapely","optional":true}],"imports":[{"note":"`AutoDetectionModel` is directly available under the `sahi` package namespace.","wrong":"from sahi.models import AutoDetectionModel","symbol":"AutoDetectionModel","correct":"from sahi import AutoDetectionModel"},{"symbol":"get_sliced_prediction","correct":"from sahi.predict import get_sliced_prediction"},{"symbol":"read_image_as_pil","correct":"from sahi.utils.cv import read_image_as_pil"},{"symbol":"download_from_url","correct":"from sahi.utils.file import download_from_url"}],"quickstart":{"code":"import os\nimport torch\nfrom sahi import AutoDetectionModel\nfrom sahi.predict import get_sliced_prediction\nfrom sahi.utils.cv import read_image\nfrom sahi.utils.file import download_from_url\n\n# Download a sample image\nimage_url = 'https://raw.githubusercontent.com/obss/sahi/main/demo/demo_data/small-vehicles1.jpeg'\nimage_path = 'small-vehicles1.jpeg'\ndownload_from_url(image_url, image_path)\n\n# Download a YOLOv8s model (requires ultralytics installed: pip install ultralytics)\nmodel_path = 'yolov8s.pt'\n# This utility helps download; in a real scenario, you might have your own model.\nif not os.path.exists(model_path):\n    # You would typically download a model or use an existing path\n    # For this example, we'll try to use a common Ultralytics model.\n    # For a real quickstart, ensure 'ultralytics' is installed and `yolov8s.pt` is available.\n    print(f\"Please ensure '{model_path}' is available or install 'ultralytics' and download it.\")\n    # Placeholder for actual download if ultralytics is installed\n    # from ultralytics import YOLO\n    # model = YOLO('yolov8s.pt') # This would download it if not present\n    # Then you would pass model.model.pt for model_path or the YOLO object directly to AutoDetectionModel\n\n# Fallback or specific model path if `yolov8s.pt` is not handled by AutoDetectionModel without explicit ultralytics import\n# For simplicity, assuming a yolov8s.pt is present or can be loaded by AutoDetectionModel\n\n# Initialize the detection model\ndevice = 'cuda:0' if torch.cuda.is_available() else 'cpu'\ndetection_model = AutoDetectionModel.from_pretrained(\n    model_type='ultralytics', # Or 'yolov5', 'mmdet', 'huggingface', 'torchvision', etc.\n    model_path=model_path, # Path to your pretrained model weights\n    confidence_threshold=0.3,\n    device=device\n)\n\n# Perform sliced inference\nresult = get_sliced_prediction(\n    read_image(image_path),\n    detection_model,\n    slice_height=256,\n    slice_width=256,\n    overlap_height_ratio=0.2,\n    overlap_width_ratio=0.2\n)\n\n# Print detection results\nprint(f\"Detected {len(result.object_prediction_list)} objects.\")\nfor i, prediction in enumerate(result.object_prediction_list):\n    print(f\"  Detection {i+1}: Class={prediction.category.name}, Confidence={prediction.score.value:.3f}\")\n\n# Export visuals (optional, requires opencv-python-headless or opencv-python)\noutput_dir = './sahi_output'\nos.makedirs(output_dir, exist_ok=True)\nresult.export_visuals(export_dir=output_dir, file_name='prediction_visual.png')\nprint(f\"Visualizations saved to {output_dir}/prediction_visual.png\")","lang":"python","description":"This quickstart demonstrates how to load a pre-trained model (e.g., YOLOv8s) using `AutoDetectionModel` and perform sliced inference on an image using `get_sliced_prediction`. It includes steps to download a sample image and print/visualize the detection results. Ensure you have the necessary backend (e.g., `ultralytics`) installed for the chosen `model_type`."},"warnings":[{"fix":"Thoroughly test model outputs, especially bounding box coordinates, after upgrading or changing `confidence_threshold` values. If issues arise, convert `PredictionResult` to COCO annotations for manual plotting or analysis to verify results.","message":"The `confidence_threshold` parameter in `AutoDetectionModel.from_pretrained` changed its behavior or effect. Previously, it might have only filtered detections. Newer versions (around 0.11.27 and later discussions) suggest it can also influence the bounding box size or shape, not just filter by score. Always verify expected behavior for a given SAHI version.","severity":"breaking","affected_versions":">=0.11.27"},{"fix":"Instead of modifying `BoundingBox` or `Category` objects directly, create new instances with desired values. For example, use methods like `get_shifted_box()` or create a new `BoundingBox` object.","message":"The `BoundingBox` and `Category` objects were made immutable in versions 0.11.29 and 0.11.31 respectively. Direct modification of their attributes will now raise an error.","severity":"gotcha","affected_versions":">=0.11.31"},{"fix":"Explicitly set the `device` parameter (e.g., 'cuda:1') when initializing `AutoDetectionModel` to distribute load. For versions prior to 0.11.34, custom scripts might be needed to manage GPU assignments across processes.","message":"When working in multi-GPU environments, especially with subprocesses or certain frameworks (like Detectron2), models might default to loading on 'cuda:0' causing imbalanced GPU utilization. This was specifically addressed in 0.11.34 for subprocesses.","severity":"gotcha","affected_versions":"<0.11.34"},{"fix":"Evaluate performance needs carefully. If real-time inference is critical, consider optimizing the base object detection model or using different techniques. If accuracy on small objects outweighs speed, SAHI is appropriate.","message":"SAHI significantly increases inference time due to processing multiple slices. It is generally not recommended for real-time applications where latency is critical.","severity":"gotcha","affected_versions":"*"},{"fix":"Experiment with SAHI's slicing hyperparameters (slice_height, slice_width, overlap_ratios) and post-processing techniques (e.g., NMS thresholds) to optimize for your specific dataset and model. Slicing hyperparameters should align with the model's training input sizes.","message":"Some users have reported degraded performance (fewer detections, lower confidence) when applying SAHI to models that already perform well on an original dataset without slicing.","severity":"gotcha","affected_versions":"*"}],"env_vars":null,"last_verified":"2026-04-15T00:00:00.000Z","next_check":"2026-07-14T00:00:00.000Z","problems":[]}