0
# Image Slicing
1

2
SAHI's image slicing capabilities enable processing of large images by dividing them into smaller, overlapping patches. This approach significantly improves small object detection performance and enables processing of images that exceed memory or model input size limitations.
3

4
## Capabilities
5

6
### Slice Bounding Box Generation
7

8
Generates coordinate bounding boxes for slicing an image into overlapping crops with automatic parameter calculation.
9

10
```python { .api }
11
def get_slice_bboxes(
12
    image_height: int,
13
    image_width: int,
14
    slice_height: Optional[int] = None,
15
    slice_width: Optional[int] = None,
16
    auto_slice_resolution: Optional[bool] = True,
17
    overlap_height_ratio: Optional[float] = 0.2,
18
    overlap_width_ratio: Optional[float] = 0.2,
19
) -> List[List[int]]:
20
    """
21
    Generate bounding boxes for slicing an image into crops.
22
    
23
    Parameters:
24
    - image_height (int): Height of the original image
25
    - image_width (int): Width of the original image  
26
    - slice_height (int, optional): Height of each slice
27
    - slice_width (int, optional): Width of each slice
28
    - auto_slice_resolution (bool): Auto-calculate slice dimensions from image size
29
    - overlap_height_ratio (float): Fractional vertical overlap between slices (0-1)
30
    - overlap_width_ratio (float): Fractional horizontal overlap between slices (0-1)
31
    
32
    Returns:
33
    List[List[int]]: List of slice bounding boxes as [xmin, ymin, xmax, ymax]
34
    """
35
```
36

37
### Image Slicing
38

39
Slice an image into overlapping patches and save them with optional output directory management.
40

41
```python { .api }
42
def slice_image(
43
    image: Union[str, Image.Image],
44
    output_file_name: Optional[str] = None,
45
    output_dir: Optional[str] = None,
46
    slice_height: int = 512,
47
    slice_width: int = 512,
48
    overlap_height_ratio: float = 0.2,
49
    overlap_width_ratio: float = 0.2,
50
    auto_slice_resolution: bool = True,
51
    min_area_ratio: float = 0.1,
52
    out_ext: Optional[str] = None,
53
    verbose: bool = False,
54
) -> SliceImageResult:
55
    """
56
    Slice image into overlapping crops with automatic file management.
57
    
58
    Parameters:
59
    - image: Image path (str) or PIL Image object
60
    - output_file_name (str, optional): Base name for output files
61
    - output_dir (str, optional): Directory for saving sliced images  
62
    - slice_height (int): Height of each slice in pixels
63
    - slice_width (int): Width of each slice in pixels
64
    - overlap_height_ratio (float): Vertical overlap ratio between slices
65
    - overlap_width_ratio (float): Horizontal overlap ratio between slices
66
    - auto_slice_resolution (bool): Auto-calculate optimal slice dimensions
67
    - min_area_ratio (float): Minimum area ratio for valid slices
68
    - out_ext (str, optional): Output file extension
69
    - verbose (bool): Print slicing progress
70
    
71
    Returns:
72
    SliceImageResult: Container with sliced images and metadata
73
    """
74
```
75

76
### COCO Dataset Slicing
77

78
Slice COCO format datasets including images and annotations with proper annotation mapping and filtering.
79

80
```python { .api }
81
def slice_coco(
82
    coco_annotation_file_path: str,
83
    image_dir: str,
84
    output_coco_annotation_file_name: str = "",
85
    output_dir: Optional[str] = None,
86
    ignore_negative_samples: bool = False,
87
    slice_height: int = 512,
88
    slice_width: int = 512,
89
    overlap_height_ratio: float = 0.2,
90
    overlap_width_ratio: float = 0.2,
91
    min_area_ratio: float = 0.1,
92
    verbose: bool = False,
93
) -> str:
94
    """
95
    Slice COCO dataset including images and annotations.
96
    
97
    Parameters:
98
    - coco_annotation_file_path (str): Path to COCO format JSON file
99
    - image_dir (str): Directory containing dataset images
100
    - output_coco_annotation_file_name (str): Name for output annotation file
101
    - output_dir (str, optional): Output directory for sliced dataset
102
    - ignore_negative_samples (bool): Skip slices without annotations
103
    - slice_height (int): Height of each slice
104
    - slice_width (int): Width of each slice  
105
    - overlap_height_ratio (float): Vertical overlap between slices
106
    - overlap_width_ratio (float): Horizontal overlap between slices
107
    - min_area_ratio (float): Minimum annotation area ratio to keep
108
    - verbose (bool): Print progress information
109
    
110
    Returns:
111
    str: Path to output COCO annotation file
112
    """
113
```
114

115
### Automatic Slice Parameter Calculation
116

117
Automatically determine optimal slice parameters based on image resolution and orientation.
118

119
```python { .api }
120
def get_auto_slice_params(
121
    height: int, 
122
    width: int
123
) -> Tuple[int, int]:
124
    """
125
    Automatically calculate slice parameters from image dimensions.
126
    
127
    Parameters:
128
    - height (int): Image height
129
    - width (int): Image width
130
    
131
    Returns:
132
    Tuple[int, int]: Optimal (slice_height, slice_width)
133
    """
134
```
135

136
### Annotation Processing
137

138
Process annotations for slicing operations including coordinate transformations and filtering.
139

140
```python { .api }
141
def annotation_inside_slice(
142
    annotation: Dict,
143
    slice_bbox: List[int],
144
    min_area_ratio: float = 0.1
145
) -> bool:
146
    """
147
    Check if annotation is sufficiently inside slice boundaries.
148
    
149
    Parameters:
150
    - annotation (Dict): COCO format annotation dictionary
151
    - slice_bbox (List[int]): Slice bounding box [xmin, ymin, xmax, ymax]  
152
    - min_area_ratio (float): Minimum area ratio threshold
153
    
154
    Returns:
155
    bool: True if annotation should be included in slice
156
    """
157

158
def process_coco_annotations(
159
    coco_annotation_list: List[Dict],
160
    slice_bbox: List[int],
161
    min_area_ratio: float = 0.1,
162
    full_shape: Optional[List[int]] = None
163
) -> List[Dict]:
164
    """
165
    Process COCO annotations for a specific slice.
166
    
167
    Parameters:
168
    - coco_annotation_list: List of COCO annotation dictionaries
169
    - slice_bbox: Slice bounding box coordinates
170
    - min_area_ratio: Minimum area ratio for keeping annotations
171
    - full_shape: Original image dimensions
172
    
173
    Returns:
174
    List[Dict]: Processed annotations with updated coordinates
175
    """
176
```
177

178
### Coordinate Transformation Utilities
179

180
Utilities for shifting bounding boxes and masks between coordinate systems.
181

182
```python { .api }
183
def shift_bboxes(
184
    boxes: np.ndarray,
185
    shift_amount: List[int]
186
) -> np.ndarray:
187
    """
188
    Shift bounding boxes by specified offset.
189
    
190
    Parameters:
191
    - boxes (np.ndarray): Bounding boxes in xyxy format
192
    - shift_amount (List[int]): Shift offset [x_shift, y_shift]
193
    
194
    Returns:
195
    np.ndarray: Shifted bounding boxes
196
    """
197

198
def shift_masks(
199
    masks: List[List],
200
    shift_amount: List[int]
201
) -> List[List]:
202
    """
203
    Shift segmentation masks by specified offset.
204
    
205
    Parameters:
206
    - masks: List of COCO format segmentation masks
207
    - shift_amount: Coordinate shift [x_shift, y_shift]
208
    
209
    Returns:
210
    List[List]: Shifted segmentation masks
211
    """
212
```
213

214
## Data Structures
215

216
### SliceImageResult
217

218
Container for image slicing operation results with metadata and file paths.
219

220
```python { .api }
221
class SliceImageResult:
222
    def __init__(
223
        self, 
224
        original_image_size: List[int], 
225
        image_dir: str
226
    ):
227
        """
228
        Initialize slice result container.
229
        
230
        Parameters:
231
        - original_image_size: Original image dimensions [height, width]
232
        - image_dir: Directory containing sliced images
233
        """
234
    
235
    @property
236
    def images(self) -> List[SlicedImage]: ...
237
    
238
    @property  
239
    def starting_pixels(self) -> List[List[int]]: ...
240
```
241

242
### SlicedImage
243

244
Individual sliced image with metadata and coordinate information.
245

246
```python { .api }
247
class SlicedImage:
248
    def __init__(
249
        self, 
250
        image: Image.Image, 
251
        coco_image: CocoImage, 
252
        starting_pixel: List[int]
253
    ):
254
        """
255
        Initialize sliced image with metadata.
256
        
257
        Parameters:
258
        - image: PIL Image of the slice
259
        - coco_image: COCO format image metadata
260
        - starting_pixel: Top-left coordinate [x, y] in original image
261
        """
262
    
263
    @property
264
    def image(self) -> Image.Image: ...
265
    
266
    @property
267
    def starting_pixel(self) -> List[int]: ...
268
```
269

270
## Usage Examples
271

272
### Basic Image Slicing
273

274
```python
275
from sahi.slicing import slice_image, get_slice_bboxes
276
from PIL import Image
277

278
# Calculate slice bounding boxes
279
image = Image.open("large_image.jpg")
280
height, width = image.size
281

282
slice_bboxes = get_slice_bboxes(
283
    image_height=height,
284
    image_width=width,
285
    slice_height=640,
286
    slice_width=640,
287
    overlap_height_ratio=0.2,
288
    overlap_width_ratio=0.2
289
)
290

291
print(f"Generated {len(slice_bboxes)} slices")
292

293
# Slice image and save crops
294
result = slice_image(
295
    image="large_image.jpg",
296
    output_dir="sliced_images/",
297
    slice_height=640,
298
    slice_width=640,
299
    overlap_height_ratio=0.2,
300
    overlap_width_ratio=0.2,
301
    verbose=True
302
)
303

304
print(f"Created {len(result.images)} slice images")
305
```
306

307
### Automatic Slice Parameter Selection
308

309
```python
310
from sahi.slicing import slice_image
311

312
# Auto-calculate optimal slice dimensions
313
result = slice_image(
314
    image="very_large_image.jpg",
315
    output_dir="auto_sliced/",
316
    auto_slice_resolution=True,  # Enable auto-calculation
317
    overlap_height_ratio=0.15,
318
    overlap_width_ratio=0.15,
319
    verbose=True
320
)
321
```
322

323
### COCO Dataset Slicing
324

325
```python
326
from sahi.slicing import slice_coco
327

328
# Slice entire COCO dataset
329
output_path = slice_coco(
330
    coco_annotation_file_path="dataset/annotations.json",
331
    image_dir="dataset/images/", 
332
    output_dir="sliced_dataset/",
333
    output_coco_annotation_file_name="sliced_annotations.json",
334
    slice_height=512,
335
    slice_width=512,
336
    overlap_height_ratio=0.2,
337
    overlap_width_ratio=0.2,
338
    min_area_ratio=0.1,  # Keep annotations with >=10% area in slice
339
    ignore_negative_samples=False,  # Keep slices without annotations
340
    verbose=True
341
)
342

343
print(f"Sliced dataset saved to: {output_path}")
344
```
345

346
### Custom Annotation Processing
347

348
```python
349
from sahi.slicing import process_coco_annotations, annotation_inside_slice
350

351
# Load COCO annotations
352
annotations = [
353
    {
354
        "bbox": [100, 150, 50, 80],  # [x, y, width, height]
355
        "category_id": 1,
356
        "area": 4000,
357
        "id": 1
358
    }
359
]
360

361
# Define slice region
362
slice_bbox = [80, 120, 200, 250]  # [xmin, ymin, xmax, ymax]
363

364
# Check if annotation should be included
365
should_include = annotation_inside_slice(
366
    annotation=annotations[0],
367
    slice_bbox=slice_bbox,
368
    min_area_ratio=0.3
369
)
370

371
# Process annotations for slice
372
processed_annotations = process_coco_annotations(
373
    coco_annotation_list=annotations,
374
    slice_bbox=slice_bbox,
375
    min_area_ratio=0.1,
376
    full_shape=[1000, 1000]
377
)
378

379
print(f"Processed {len(processed_annotations)} annotations for slice")
380
```
381

382
### Advanced Slicing Configuration
383

384
```python
385
from sahi.slicing import slice_image
386

387
# Custom slicing with specific parameters
388
result = slice_image(
389
    image="satellite_image.tif",
390
    output_dir="satellite_slices/",
391
    output_file_name="satellite_slice",
392
    slice_height=1024,
393
    slice_width=1024,
394
    overlap_height_ratio=0.25,  # 25% overlap
395
    overlap_width_ratio=0.25,
396
    min_area_ratio=0.05,        # Keep small partial slices
397
    out_ext=".png",             # Convert format
398
    verbose=True
399
)
400

401
# Access individual slices
402
for i, sliced_image in enumerate(result.images):
403
    print(f"Slice {i}: starts at {sliced_image.starting_pixel}")
404
    # Process individual slice
405
    slice_pil = sliced_image.image
406
```