Implementation:Obss Sahi Slice Image
| Knowledge Sources | |
|---|---|
| Domains | Object_Detection, Computer_Vision, Image_Processing |
| Last Updated | 2026-02-08 12:00 GMT |
Overview
Concrete tool for partitioning high-resolution images into overlapping tiles for small object detection provided by the SAHI library.
Description
slice_image() divides a large image into a grid of smaller overlapping windows. It reads the input image (from file path or PIL Image), computes the slice grid via get_slice_bboxes(), extracts each crop as a numpy array, creates corresponding CocoImage metadata objects, and optionally exports sliced images to disk using threaded I/O.
If auto_slice_resolution=True and no explicit slice dimensions are provided, get_auto_slice_params() automatically calculates optimal slice height, width, and overlap based on the image resolution and orientation.
When coco_annotation_list is provided, annotations are clipped to each slice boundary via process_coco_annotations(), filtering out annotations whose remaining area falls below min_area_ratio.
Usage
Use this function as the second step in any SAHI sliced inference pipeline. Call it after loading the image and before running per-slice detection. Also used internally by slice_coco() for training dataset preparation.
Code Reference
Source Location
- Repository: sahi
- File: sahi/slicing.py
- Lines: L263-415
Signature
def slice_image(
image: str | Image.Image,
coco_annotation_list: list[CocoAnnotation] | None = None,
output_file_name: str | None = None,
output_dir: str | None = None,
slice_height: int | None = None,
slice_width: int | None = None,
overlap_height_ratio: float | None = 0.2,
overlap_width_ratio: float | None = 0.2,
auto_slice_resolution: bool | None = True,
min_area_ratio: float | None = 0.1,
out_ext: str | None = None,
verbose: bool | None = False,
exif_fix: bool = True,
) -> SliceImageResult:
"""Slice a large image into smaller windows.
Args:
image: File path or PIL Image to slice
coco_annotation_list: Optional COCO annotations to slice along
output_file_name: Root name for exported slice files
output_dir: Directory for exported slices
slice_height: Height of each slice (None for auto)
slice_width: Width of each slice (None for auto)
overlap_height_ratio: Fractional vertical overlap (default 0.2)
overlap_width_ratio: Fractional horizontal overlap (default 0.2)
auto_slice_resolution: Auto-calculate slice params (default True)
min_area_ratio: Min annotation area ratio to keep (default 0.1)
out_ext: Extension for saved images
verbose: Print slice info
exif_fix: Apply EXIF orientation fix
"""
Import
from sahi.slicing import slice_image
I/O Contract
Inputs
| Name | Type | Required | Description |
|---|---|---|---|
| image | str or PIL.Image | Yes | File path or PIL Image to be sliced |
| coco_annotation_list | list[CocoAnnotation] | No | COCO annotations to slice alongside image |
| output_file_name | str | No | Root filename for exported slices |
| output_dir | str | No | Directory for exported slice images |
| slice_height | int | No | Height of each slice (None = auto) |
| slice_width | int | No | Width of each slice (None = auto) |
| overlap_height_ratio | float | No | Vertical overlap fraction (default 0.2) |
| overlap_width_ratio | float | No | Horizontal overlap fraction (default 0.2) |
| auto_slice_resolution | bool | No | Auto-compute slice dimensions (default True) |
| min_area_ratio | float | No | Min annotation area ratio to retain (default 0.1) |
Outputs
| Name | Type | Description |
|---|---|---|
| return | SliceImageResult | Container with .images (list of numpy arrays), .starting_pixels (list of [x,y] offsets), .coco_images (list of CocoImage), .filenames, .original_image_height, .original_image_width |
Usage Examples
Basic Image Slicing
from sahi.slicing import slice_image
# Slice with auto-resolution (dimensions calculated from image)
result = slice_image(
image="path/to/large_image.jpg",
auto_slice_resolution=True,
)
print(f"Generated {len(result)} slices")
print(f"Original size: {result.original_image_height}x{result.original_image_width}")
# Access individual slices
for i, img in enumerate(result.images):
print(f"Slice {i}: shape={img.shape}, offset={result.starting_pixels[i]}")
Fixed-Size Slicing with Export
from sahi.slicing import slice_image
result = slice_image(
image="path/to/aerial_image.tif",
slice_height=640,
slice_width=640,
overlap_height_ratio=0.2,
overlap_width_ratio=0.2,
output_file_name="aerial_slice",
output_dir="./sliced_output/",
)
# Sliced images are saved to ./sliced_output/