SAHI provides a comprehensive command-line interface for object detection tasks. This guide covers all available commands with detailed examples and options.
Perform object detection inference on images or videos using sliced inference for better small object detection.
sahi predict --source image/file/or/folder --model_path path/to/model --model_config_path path/to/configThis will perform sliced inference with default parameters and export prediction visuals to runs/predict/exp folder.
SAHI supports video inference with the same command structure:
sahi predict --model_path yolo26s.pt --model_type ultralytics --source video.mp4View video rendering during inference with the --view_video flag:
sahi predict --model_path yolo26s.pt --model_type ultralytics --source video.mp4 --view_videoKeyboard Controls:
D- Forward 100 framesA- Rewind 100 framesG- Forward 20 framesF- Rewind 20 framesEsc- Exit viewer
Tip: If
--view_videois slow, add--frame_skip_interval=20to skip intervals of 20 frames.
Customize the slicing behavior for optimal detection:
sahi predict --slice_width 512 --slice_height 512 \
--overlap_height_ratio 0.1 --overlap_width_ratio 0.1 \
--model_confidence_threshold 0.25 \
--source image/file/or/folder \
--model_path path/to/model \
--model_config_path path/to/configDetection Framework:
--model_type mmdet- For MMDetection models--model_type ultralytics- For Ultralytics/YOLOv5/YOLO11 models--model_type huggingface- For HuggingFace models--model_type torchvision- For Torchvision models
Confidence Threshold:
--model_confidence_threshold 0.25- Set minimum confidence for detections
Postprocess Type:
--postprocess_type GREEDYNMM- Greedy non-maximum merging (default)--postprocess_type NMS- Standard non-maximum suppression
Match Metrics:
--postprocess_match_metric IOS- Intersection over smaller area--postprocess_match_metric IOU- Intersection over union (default)
Additional Options:
--postprocess_match_threshold 0.5- Set matching threshold--postprocess_class_agnostic- Ignore category IDs during postprocessing
Visual Exports:
--novisual- Disable prediction visualization exports--visual_export_format JPG- Set export format (JPG, PNG, etc.)
Data Exports:
--export_pickle- Export prediction pickles--export_crop- Export cropped detections
By default, SAHI performs multi-stage inference (both standard and sliced prediction):
--no_sliced_prediction- Disable sliced inference (standard only)--no_standard_prediction- Disable standard inference (sliced only)
Perform prediction using a COCO annotation file for evaluation:
sahi predict --dataset_json_path dataset.json \
--source path/to/coco/image/folder \
--model_path path/to/modelPredictions will be exported as a COCO JSON file to runs/predict/exp/results.json. You can then use:
sahi coco evaluate- Calculate COCO evaluation metricssahi coco analyse- Generate detailed error analysis plots
Enable a progress bar to track inference progress:
sahi predict --model_path path/to/model --source images/ \
--slice_width 512 --slice_height 512 --progress_barNote: The
--progress_barflag controls CLI visual progress (tqdm). Theprogress_callbackparameter is available in the Python API but not exposed as a CLI option.
Perform sliced inference and visualize results interactively using the FiftyOne App.
sahi predict-fiftyone --image_dir image/file/or/folder \
--dataset_json_path dataset.json \
--model_path path/to/model \
--model_config_path path/to/configThis will perform sliced inference with default parameters and launch the FiftyOne App for interactive exploration.
All parameters from the sahi predict command are supported.
Visualize and compare multiple detection results on your COCO dataset using FiftyOne UI.
You need to convert your predictions to COCO result JSON format. Use sahi predict to generate this format.
sahi coco fiftyone --image_dir dir/to/images \
--dataset_json_path dataset.json \
cocoresult1.json cocoresult2.jsonThis opens a FiftyOne app that visualizes the dataset and compares 2 detection results ordered by misdetections.
--iou_threshold 0.5- Set IOU threshold for FP/TP classification
Slice large images and their COCO format annotations into smaller tiles.
sahi coco slice --image_dir dir/to/images \
--dataset_json_path dataset.jsonSlices images and COCO annotations, exporting them to the output folder.
Slice Dimensions:
--slice_size 512- Set slice height and width (default: 512)
Overlap:
--overlap_ratio 0.2- Set overlap ratio for height/width (default: 0.2)
Filtering:
--ignore_negative_samples- Exclude images without annotations
Output:
--out_dir output/folder- Specify output directory
Convert COCO format datasets to YOLO format for training with Ultralytics.
Windows Users: Open Anaconda prompt or Windows CMD as administrator to create symlinks properly.
sahi coco yolo --image_dir dir/to/images \
--dataset_json_path dataset.json \
--train_split 0.9Converts the COCO dataset to YOLO format and exports to runs/coco2yolo/exp folder.
--train_split 0.9- Set training split ratio (default: 0.9)--out_dir output/folder- Specify output directory
Calculate COCO evaluation metrics (mAP, mAR) for your predictions.
You need to convert your predictions to COCO result JSON format. Use sahi predict to generate this format.
sahi coco evaluate --dataset_json_path dataset.json \
--result_json_path result.jsonCalculates COCO evaluation metrics and exports results to the output folder.
Metric Type:
--type bbox- Evaluate bounding box detections (default)--type mask- Evaluate instance segmentation masks
Scoring Options:
--classwise- Calculate per-class scores in addition to overall metrics
Detection Limits:
--proposal_nums "[10 100 500]"- Set max detections per image (default: [100, 300, 1000])
IOU Thresholds:
--iou_thrs 0.5- Specify IOU threshold (default: 0.50:0.95 and 0.5)
Output:
--out_dir output/folder- Specify output directory
Generate detailed error analysis plots for COCO predictions.
You need to convert your predictions to COCO result JSON format. Use sahi predict to generate this format.
sahi coco analyse --dataset_json_path dataset.json \
--result_json_path result.json \
--out_dir output/directoryGenerates comprehensive error analysis plots and exports them to the specified folder.
Analysis Type:
--type bbox- Analyze bounding box detections (default)--type segm- Analyze instance segmentation masks
Additional Plots:
--extraplots- Generate extra mAP bar plots and annotation area statistics
Area Regions:
--areas "[1024 9216 10000000000]"- Define area regions for analysis (default: small/medium/large COCO areas)
Display installed package versions related to SAHI.
sahi env06/19/2022 21:24:52 - INFO - sahi.utils.import_utils - torch version 2.1.2 is available.
06/19/2022 21:24:52 - INFO - sahi.utils.import_utils - torchvision version 0.16.2 is available.
06/19/2022 21:24:52 - INFO - sahi.utils.import_utils - ultralytics version 8.3.86 is available.
06/19/2022 21:24:52 - INFO - sahi.utils.import_utils - transformers version 4.49.0 is available.
06/19/2022 21:24:52 - INFO - sahi.utils.import_utils - timm version 0.9.1 is available.
06/19/2022 21:24:52 - INFO - sahi.utils.import_utils - fiftyone version 0.14.2 is available.
Display your currently installed SAHI version.
sahi version
0.11.22All scripts can be downloaded from the scripts directory and modified for your specific needs.
After installing SAHI via pip, all scripts can be called from any directory:
python script_name.pyLooking to dive deeper? Here are some helpful resources:
- Prediction Utilities Documentation - Detailed walkthrough of prediction parameters and visualization
- Slicing Utilities Guide - In-depth exploration of slicing operations
- COCO Utilities Documentation - Comprehensive examples with COCO format operations
- Interactive Demo Notebooks - Hands-on examples of CLI commands in action
- Model Documentation - Framework-specific model integration guides
These resources provide comprehensive examples and explanations to help you make the most of SAHI's command-line interface.