Implementation:Obss Sahi Visualize Object Predictions

Knowledge Sources	SAHI SAHI Docs
Domains	Object_Detection, Computer_Vision, Visualization
Last Updated	2026-02-08 12:00 GMT

Overview

Concrete tool for rendering detection predictions (bounding boxes, masks, labels) as visual overlays on images provided by the SAHI library.

Description

visualize_object_predictions() draws detection results onto a copy of the source image using OpenCV. It supports three visualization modes:

• Standard bounding boxes: Drawn as colored rectangles with category label and confidence score
• Instance segmentation masks: Blended as semi-transparent color overlays (alpha=0.6)
• Oriented bounding boxes (OBB): Drawn as rotated polygons when the mask is a single 8-point polygon

The function auto-scales rendering parameters (line thickness, text size) based on image dimensions. It uses a predefined color palette (Colors class) for per-category coloring, or accepts a custom color. Results can be optionally exported to disk as PNG or JPG.

Usage

Use this function as the final step in any SAHI prediction pipeline to visually inspect results or export annotated images. It is called internally by PredictionResult.export_visuals() and by the CLI prediction scripts.

Code Reference

Source Location

• Repository: sahi
• File: sahi/utils/cv.py
• Lines: L473-606

Signature

def visualize_object_predictions(
    image: np.ndarray,
    object_prediction_list,
    rect_th: int | None = None,
    text_size: float | None = None,
    text_th: int | None = None,
    color: tuple | None = None,
    hide_labels: bool = False,
    hide_conf: bool = False,
    output_dir: str | None = None,
    file_name: str | None = "prediction_visual",
    export_format: str | None = "png",
) -> dict:
    """Visualize predictions on source image.

    Args:
        image: Source image as numpy array (RGB)
        object_prediction_list: List of ObjectPrediction
        rect_th: Rectangle thickness (auto-scaled if None)
        text_size: Category label text size (auto-scaled if None)
        text_th: Text thickness (auto-scaled if None)
        color: Custom annotation color as (R, G, B) tuple
        hide_labels: Hide category labels
        hide_conf: Hide confidence scores
        output_dir: Directory to save annotated image
        file_name: Output filename (without extension)
        export_format: "png" or "jpg"

    Returns:
        Dict with "image" (annotated numpy array) and "elapsed_time"
    """

Import

from sahi.utils.cv import visualize_object_predictions

I/O Contract

Inputs

Name	Type	Required	Description
image	np.ndarray	Yes	Source image as RGB numpy array
object_prediction_list	list[ObjectPrediction]	Yes	Merged predictions to visualize
rect_th	int	No	Box line thickness (auto-scaled from image size if None)
text_size	float	No	Label text size (auto-scaled if None)
text_th	int	No	Label text thickness (auto-scaled if None)
color	tuple	No	Custom (R,G,B) color; None uses per-category palette
hide_labels	bool	No	Hide category name labels (default False)
hide_conf	bool	No	Hide confidence scores (default False)
output_dir	str	No	Directory to save the annotated image
file_name	str	No	Output filename base (default "prediction_visual")
export_format	str	No	Image format: "png" or "jpg" (default "png")

Outputs

Name	Type	Description
return	dict	{"image": annotated numpy array (RGB), "elapsed_time": float seconds}

Usage Examples

Basic Visualization

from sahi.utils.cv import visualize_object_predictions
import numpy as np
from PIL import Image

# Load image
image = np.array(Image.open("image.jpg"))

# Visualize and save
result = visualize_object_predictions(
    image=image,
    object_prediction_list=predictions,
    output_dir="./output/",
    file_name="detection_result",
    export_format="png",
)

print(f"Visualization took {result['elapsed_time']:.2f}s")
# Annotated image also available as result["image"]

Custom Visualization

from sahi.utils.cv import visualize_object_predictions

result = visualize_object_predictions(
    image=image_array,
    object_prediction_list=predictions,
    rect_th=3,
    text_size=1.0,
    color=(255, 0, 0),     # All boxes in red
    hide_conf=True,          # Hide confidence scores
    output_dir="./results/",
)

Related Pages

Implements Principle

• Principle:Obss_Sahi_Result_Visualization

Requires Environment

• Environment:Obss_Sahi_Python_Image_Processing