Skip to main content
The AnnotatedImage component displays a base image with colored annotations overlaid, useful for object detection and segmentation visualizations.

​
Basic usage

import gradio as gr

def detect_objects(image):
    # Returns (image, [(mask, label), ...])  
    annotations = [
        ((10, 20, 100, 150), "cat"),  # Bounding box
        ((200, 50, 300, 200), "dog")   # Bounding box
    ]
    return (image, annotations)

gr.Interface(
    fn=detect_objects,
    inputs=gr.Image(),
    outputs=gr.AnnotatedImage()
).launch()

​
Constructor

​
value
tuple[Image, list[tuple[Mask, str]]] | None
default:"None"
Tuple of (base_image, annotations) where:
  • base_image is filepath, PIL Image, or numpy array
  • Each annotation is (mask, label) tuple
  • mask can be:
    • Tuple of 4 ints (x1, y1, x2, y2) for bounding box
    • Numpy array for segmentation mask (0-1 confidence values)
​
format
str
default:"'webp'"
Image format for saving (e.g., “png”, “jpg”)
​
show_legend
bool
default:"True"
Whether to display legend of annotations
​
height
int | str | None
default:"None"
Component height
​
width
int | str | None
default:"None"
Component width
​
color_map
dict[str, str] | None
default:"None"
Dictionary mapping labels to hex colors (e.g., {"cat": "#FF0000"})

​
Events

  • select - Triggered when annotation is selected

​
Examples

​
Object detection

import gradio as gr
import numpy as np

def detect(image):
    # Simulated detections
    boxes = [
        ((50, 50, 200, 200), "person"),
        ((250, 100, 400, 300), "car")
    ]
    return (image, boxes)

gr.Interface(
    fn=detect,
    inputs=gr.Image(),
    outputs=gr.AnnotatedImage(color_map={
        "person": "#00FF00",
        "car": "#FF0000"
    })
).launch()

​
Segmentation masks

import gradio as gr
import numpy as np

def segment(image):
    # Create a segmentation mask
    h, w = image.shape[:2]
    mask = np.zeros((h, w))
    mask[50:150, 50:150] = 0.8  # Confidence mask
    
    annotations = [(mask, "object")]
    return (image, annotations)

gr.Interface(
    fn=segment,
    inputs=gr.Image(),
    outputs=gr.AnnotatedImage()
).launch()