tessl/pypi-sahi

A vision library for performing sliced inference on large images/small objects

—

Pending

Overview

Eval results

Files

Command Line Interface

Name: tessl/pypi-sahi
Author: tessl

SAHI provides a comprehensive command-line interface accessible through the sahi command. The CLI covers prediction, dataset processing, evaluation, format conversion, and system utilities with extensive configuration options.

Capabilities

Main CLI Structure

The SAHI CLI is organized into main commands and sub-commands using the Fire library for automatic CLI generation.

# Main command structure
sahi <command> [options]

# Available main commands:
sahi predict          # Run predictions on images/videos
sahi predict-fiftyone # Run predictions with FiftyOne integration
sahi coco            # COCO dataset operations
sahi version         # Show SAHI version
sahi env             # Show environment information

Prediction Commands

Standard Prediction

Run object detection with sliced inference on images, directories, or videos.

sahi predict \
    --model_type ultralytics \
    --model_path yolov8n.pt \
    --source path/to/image.jpg \
    --slice_height 640 \
    --slice_width 640 \
    --overlap_height_ratio 0.2 \
    --overlap_width_ratio 0.2 \
    --confidence_threshold 0.25 \
    --device cuda:0 \
    --export_visual True \
    --export_crop False \
    --export_pickle False \
    --project runs/predict \
    --name experiment_1

# Parameters:
# --model_type: Framework type (ultralytics, mmdet, detectron2, huggingface, etc.)
# --model_path: Path to model weights file
# --source: Input path (image, directory, or video)
# --slice_height: Height of each slice in pixels  
# --slice_width: Width of each slice in pixels
# --overlap_height_ratio: Vertical overlap between slices (0-1)
# --overlap_width_ratio: Horizontal overlap between slices (0-1)
# --confidence_threshold: Minimum detection confidence (0-1)
# --device: Device for inference (cpu, cuda, cuda:0, etc.)
# --export_visual: Export visualization images (True/False)
# --export_crop: Export cropped detected objects (True/False) 
# --export_pickle: Export predictions as pickle files (True/False)
# --project: Base output directory
# --name: Experiment name for output subdirectory

FiftyOne Integration

Run predictions with automatic FiftyOne dataset integration.

sahi predict-fiftyone \
    --model_type ultralytics \
    --model_path yolov8n.pt \
    --dataset_json_path dataset.json \
    --image_dir images/ \
    --slice_height 512 \
    --slice_width 512 \
    --dataset_name "my_predictions" \
    --model_name "yolov8_sahi"

# Parameters:
# --dataset_json_path: Path to COCO format dataset JSON
# --image_dir: Directory containing dataset images
# --dataset_name: Name for FiftyOne dataset
# --model_name: Model identifier in FiftyOne

COCO Dataset Operations

Comprehensive COCO dataset processing including slicing, evaluation, error analysis, and format conversion.

Dataset Slicing

Slice COCO datasets for improved small object detection performance.

sahi coco slice \
    --image_dir images/ \
    --dataset_json_path annotations.json \
    --slice_height 512 \
    --slice_width 512 \
    --overlap_height_ratio 0.2 \
    --overlap_width_ratio 0.2 \
    --min_area_ratio 0.1 \
    --ignore_negative_samples False \
    --output_dir sliced_dataset/ \
    --output_file_name sliced_annotations.json

# Parameters:
# --image_dir: Directory containing dataset images
# --dataset_json_path: Path to COCO format JSON file
# --slice_height: Height of each slice
# --slice_width: Width of each slice  
# --overlap_height_ratio: Vertical overlap between slices
# --overlap_width_ratio: Horizontal overlap between slices
# --min_area_ratio: Minimum annotation area ratio to keep (0-1)
# --ignore_negative_samples: Skip slices without annotations (True/False)
# --output_dir: Output directory for sliced dataset
# --output_file_name: Name for output annotation file

Model Evaluation

Evaluate detection models on COCO datasets with comprehensive metrics.

sahi coco evaluate \
    --dataset_json_path ground_truth.json \
    --result_json_path predictions.json \
    --out_dir evaluation_results/ \
    --type bbox \
    --areas all \
    --max_detections 100 \
    --return_dict False \
    --classwise True

# Parameters:
# --dataset_json_path: Path to ground truth COCO JSON
# --result_json_path: Path to predictions JSON  
# --out_dir: Output directory for evaluation results
# --type: Evaluation type (bbox, segm)
# --areas: Area ranges to evaluate (all, small, medium, large)
# --max_detections: Maximum detections per image
# --return_dict: Return results as dictionary (True/False)
# --classwise: Generate per-class metrics (True/False)

Error Analysis

Perform detailed error analysis on detection results to identify failure modes.

sahi coco analyse \
    --dataset_json_path ground_truth.json \
    --result_json_path predictions.json \
    --out_dir analysis_results/ \
    --type bbox \
    --classwise True \
    --max_detections 100

# Parameters:
# --dataset_json_path: Path to ground truth annotations
# --result_json_path: Path to model predictions
# --out_dir: Output directory for analysis results
# --type: Analysis type (bbox, segm)
# --classwise: Generate per-class analysis (True/False)
# --max_detections: Maximum detections to analyze per image

Format Conversion

Convert COCO datasets to other formats like YOLO.

sahi coco yolo \
    --coco_annotation_file_path annotations.json \
    --image_dir images/ \
    --output_dir yolo_dataset/ \
    --train_split_rate 0.8 \
    --numpy_seed 42

# Alias commands (same functionality):
sahi coco yolov5   # Same as 'yolo'

# Parameters:
# --coco_annotation_file_path: Path to COCO JSON file
# --image_dir: Directory containing images
# --output_dir: Output directory for YOLO format files
# --train_split_rate: Fraction for training set (0-1)  
# --numpy_seed: Random seed for reproducible splits

FiftyOne Integration

Convert COCO datasets to FiftyOne format for advanced visualization and analysis.

sahi coco fiftyone \
    --coco_annotation_file_path annotations.json \
    --image_dir images/ \
    --dataset_name "my_dataset" \
    --launch_fiftyone_app True

# Parameters:
# --coco_annotation_file_path: Path to COCO JSON file
# --image_dir: Directory containing images
# --dataset_name: Name for FiftyOne dataset
# --launch_fiftyone_app: Launch FiftyOne web app (True/False)

System Information Commands

Version Information

Display SAHI version information.

sahi version

# Output: Shows current SAHI version number

Environment Information

Display comprehensive environment and dependency information for debugging.

sahi env

# Output: Shows:
# - SAHI version
# - Python version  
# - PyTorch version
# - CUDA availability
# - System information
# - Installed dependencies

Usage Examples

Basic Object Detection

# Simple prediction on single image
sahi predict \
    --model_type ultralytics \
    --model_path yolov8n.pt \
    --source image.jpg

# Batch processing entire directory  
sahi predict \
    --model_type ultralytics \
    --model_path yolov8n.pt \
    --source images/ \
    --export_visual True

Advanced Sliced Inference

# High-resolution satellite imagery
sahi predict \
    --model_type ultralytics \
    --model_path satellite_model.pt \
    --source satellite_image.tif \
    --slice_height 1024 \
    --slice_width 1024 \
    --overlap_height_ratio 0.3 \
    --overlap_width_ratio 0.3 \
    --confidence_threshold 0.2 \
    --device cuda:0 \
    --export_visual True \
    --project satellite_results \
    --name high_res_experiment

Video Processing

# Process video with frame skipping
sahi predict \
    --model_type ultralytics \
    --model_path yolov8n.pt \
    --source video.mp4 \
    --frame_skip_interval 5 \
    --slice_height 640 \
    --slice_width 640 \
    --export_visual True

Dataset Preparation Pipeline

# 1. Slice large images dataset  
sahi coco slice \
    --image_dir original_images/ \
    --dataset_json_path annotations.json \
    --slice_height 640 \
    --slice_width 640 \
    --output_dir sliced_dataset/

# 2. Convert to YOLO format for training
sahi coco yolo \
    --coco_annotation_file_path sliced_dataset/sliced_annotations.json \
    --image_dir sliced_dataset/images/ \
    --output_dir yolo_training_data/ \
    --train_split_rate 0.8

# 3. Create FiftyOne dataset for analysis
sahi coco fiftyone \
    --coco_annotation_file_path sliced_dataset/sliced_annotations.json \
    --image_dir sliced_dataset/images/ \
    --dataset_name "sliced_training_data" \
    --launch_fiftyone_app True

Model Evaluation Workflow

# 1. Run predictions on test set
sahi predict \
    --model_type ultralytics \
    --model_path trained_model.pt \
    --source test_images/ \
    --export_format coco \
    --return_dict True \
    --project evaluation \
    --name test_predictions

# 2. Evaluate predictions
sahi coco evaluate \
    --dataset_json_path test_annotations.json \
    --result_json_path evaluation/test_predictions/predictions.json \
    --out_dir evaluation_results/ \
    --classwise True

# 3. Perform error analysis
sahi coco analyse \
    --dataset_json_path test_annotations.json \
    --result_json_path evaluation/test_predictions/predictions.json \
    --out_dir error_analysis/ \
    --classwise True

Multi-Framework Comparison

# Test different models on same dataset
for model_type in ultralytics mmdet detectron2; do
    sahi predict \
        --model_type $model_type \
        --model_path models/${model_type}_model.pt \
        --source test_images/ \
        --project comparison \
        --name ${model_type}_results \
        --export_format coco
done

# Evaluate each result
for model_type in ultralytics mmdet detectron2; do
    sahi coco evaluate \
        --dataset_json_path test_annotations.json \
        --result_json_path comparison/${model_type}_results/predictions.json \
        --out_dir comparison/${model_type}_evaluation/
done

Environment Debugging

# Check system configuration
sahi env

# Verify installation
sahi version

# Test basic functionality
sahi predict \
    --model_type ultralytics \
    --model_path yolov8n.pt \
    --source test_image.jpg \
    --device cpu

Install with Tessl CLI