Environment:Obss Sahi Python Image Processing
| Knowledge Sources | |
|---|---|
| Domains | Computer_Vision, Image_Processing, Infrastructure |
| Last Updated | 2026-02-08 12:00 GMT |
Overview
Python 3.8+ environment with OpenCV, Pillow, NumPy, Shapely, and tqdm for image slicing, annotation processing, and result visualization.
Description
This environment provides the image processing runtime required by SAHI's slicing engine and visualization utilities. It covers the non-ML portions of the pipeline: reading/writing images, computing geometric overlaps for annotations, slicing images into tiles, and rendering detection results as visual overlays. All packages in this environment are core dependencies (not optional) — they are always installed with SAHI.
Usage
Use this environment for any workflow that involves image slicing (`slice_image`, `slice_coco`), annotation handling (bounding box/mask manipulation), COCO dataset processing (loading, slicing, exporting), or result visualization (`visualize_object_predictions`). This is a prerequisite for both the Sliced Inference Pipeline and the COCO Dataset Slicing workflows.
System Requirements
| Category | Requirement | Notes |
|---|---|---|
| OS | Linux, macOS, Windows | All platforms supported |
| Hardware | CPU | No GPU required for image processing operations |
| Python | >= 3.8, <= 3.13 | All supported Python versions |
| Disk | ~500MB | OpenCV and NumPy wheel sizes |
Dependencies
System Packages
- No system-level packages required (all distributed as Python wheels)
Python Packages
- `opencv-python` <= 4.11.0.86
- `pillow` >= 8.2.0
- `shapely` >= 2.0.0
- `numpy` (transitive dependency via OpenCV/Pillow)
- `tqdm` >= 4.48.2
- `pybboxes` == 0.1.6
- `pyyaml`
Credentials
No credentials required for image processing operations.
Quick Install
# All image processing deps are installed with core SAHI
pip install sahi
# Or install individually
pip install "opencv-python<=4.11.0.86" "pillow>=8.2.0" "shapely>=2.0.0" "tqdm>=4.48.2" "pybboxes==0.1.6" pyyaml
Code Evidence
Shapely usage for annotation geometry from `sahi/utils/shapely.py:1-10`:
from shapely.geometry import MultiPolygon, Polygon, box
from shapely.ops import unary_union
from shapely.validation import make_valid
OpenCV usage for visualization from `sahi/utils/cv.py:1-5`:
import cv2
import numpy as np
from PIL import Image
Image slicing with Pillow from `sahi/slicing.py:52-65`:
from PIL import Image
def slice_image(
image,
coco_annotation_list=None,
output_file_name=None,
output_dir=None,
slice_height=None,
slice_width=None,
overlap_height_ratio=0.2,
overlap_width_ratio=0.2,
min_area_ratio=0.1,
...
):
Shapely annotation intersection from `sahi/slicing.py:490-497` (TopologicalError handling):
try:
annotation_polygon = shapely.wkt.loads(coco_annotation.segmentation)
except Exception:
logger.warning(f"Invalid annotation found, skipping this image: {image_path}")
continue
Common Errors
| Error Message | Cause | Solution |
|---|---|---|
| `ImportError: No module named 'cv2'` | OpenCV not installed | `pip install opencv-python<=4.11.0.86` |
| `ImportError: No module named 'shapely'` | Shapely not installed | `pip install shapely>=2.0.0` |
| `TopologicalError` (warning: Invalid annotation found, skipping) | Malformed polygon annotation in COCO dataset | Fix annotation geometry or accept that image will be skipped during slicing |
| `ValueError: GEOSGeom_createLinearRing_r returned a NULL pointer` | Invalid geometry passed to Shapely | Ensure annotation polygons have >= 3 valid points |
Compatibility Notes
- OpenCV: Upper-bounded at 4.11.0.86 to avoid breaking API changes. The `opencv-python` package includes pre-built binaries for all platforms.
- Shapely: Requires >= 2.0.0 which uses the new GEOS C library backend. Shapely 1.x is not compatible.
- NumPy: When using MMDetection backend, `numpy` < 2.0 is required due to torch 2.1.2 incompatibility. Otherwise no upper bound.
- Pillow: Minimum 8.2.0 ensures EXIF orientation handling and modern format support.