gradio-polygonannotator 0.1.0

Interactive polygon annotation component for Gradio with multi-selection, hover effects, and customizable appearance

gradio_polygonannotator

Interactive polygon annotation component for Gradio with multi-selection, hover effects, and customizable appearance

Installation

pip install gradio_polygonannotator

Usage

import gradio as gr
from gradio_polygonannotator import PolygonAnnotator

# Example with document regions
example_data = {
    "image": "https://images.unsplash.com/photo-1544816155-12df9643f363?w=800&h=1200",
    "polygons": [
        {
            "id": "title",
            "coordinates": [[180, 150], [580, 150], [580, 200], [180, 200]],
            "color": "#FF6B6B",
            "mask_opacity": 0.15,
            "stroke_width": 1.0,
            "stroke_opacity": 0.8,
        },
        {
            "id": "paragraph_1",
            "coordinates": [[100, 400], [750, 400], [750, 600], [100, 600]],
            "color": "#4ECDC4",
            "mask_opacity": 0.15,
            "stroke_width": 0.7,
            "stroke_opacity": 0.6,
        },
        {
            "id": "paragraph_2",
            "coordinates": [[100, 650], [750, 650], [750, 950], [100, 950]],
            "color": "#4ECDC4",
            "mask_opacity": 0.15,
            "stroke_width": 0.7,
            "stroke_opacity": 0.6,
        },
        {
            "id": "signature",
            "coordinates": [[400, 1020], [650, 1020], [650, 1080], [400, 1080]],
            "color": "#FFE66D",
            "mask_opacity": 0.2,
            "stroke_width": 1.5,
            "stroke_opacity": 0.8,
        }
    ]
}

def handle_selection(data, evt: gr.SelectData):
    """Handle polygon selection and display info"""
    if evt.value and data:
        selected_ids = evt.value if isinstance(evt.value, list) else [evt.value]
        info = f"Selected {len(selected_ids)} polygon(s):\n"
        for poly_id in selected_ids:
            polygon = next((p for p in data["polygons"] if p["id"] == poly_id), None)
            if polygon:
                info += f"• {poly_id}\n"
        return info
    return "Click on polygons to select them. Use Ctrl/Cmd+Click for multi-selection."

with gr.Blocks() as demo:
    gr.Markdown("""
    # PolygonAnnotator - Interactive Polygon Selection

    Click on polygons to select them. Use **Ctrl/Cmd+Click** for multiple selections.
    Click selected polygons to deselect.
    """)

    with gr.Row():
        with gr.Column(scale=3):
            annotator = PolygonAnnotator(
                value=example_data,
                label="Document with Region Annotations",
                height=600,
            )

        with gr.Column(scale=1):
            selected_info = gr.Textbox(
                label="Selected Regions",
                lines=6,
                value="Click on polygons to select them. Use Ctrl/Cmd+Click for multi-selection."
            )

    # Handle selection events
    annotator.select(
        handle_selection,
        inputs=[annotator],
        outputs=[selected_info]
    )

if __name__ == "__main__":
    demo.launch()

PolygonAnnotator

Initialization

name	type	default	description
value	dict | None	None	Dictionary containing 'image' (FileData), 'polygons' (list with id, coordinates, color, opacities),
label	str | I18nData | None	None	Component label shown above the annotator.
every	Timer | float | None	None	Continuously calls `value` to recalculate it if `value` is a function.
inputs	Component | Sequence[Component] | set[Component] | None	None	Components used as inputs to calculate `value` if it's a function.
show_label	bool | None	None	Whether to display the label.
show_download_button	bool	True	Whether to show image download button.
height	int | str | None	None	Component height in pixels or CSS units.
width	int | str | None	None	Component width in pixels or CSS units.
container	bool	True	Whether to wrap component in a container with padding.
scale	int | None	None	Relative size compared to adjacent components.
min_width	int	160	Minimum pixel width before wrapping.
interactive	bool | None	None	Whether users can interact with polygons (selection/deselection).
visible	bool | Literal["hidden"]	True	Whether component is visible ("hidden" keeps it in DOM but invisible).
elem_id	str | None	None	HTML DOM id for CSS targeting.
elem_classes	list[str] | str | None	None	HTML DOM classes for CSS targeting.
render	bool	True	Whether to render the component immediately.
key	int | str | tuple[int | str, ...] | None	None	Key for maintaining component identity across re-renders.
preserved_by_key	list[str] | str | None	"value"	Parameters preserved across re-renders with same key.

Events

name	description
clear	This listener is triggered when the user clears the PolygonAnnotator using the clear button for the component.
change	Triggered when the value of the PolygonAnnotator changes either because of user input (e.g. a user types in a textbox) OR because of a function update (e.g. an image receives a value from the output of an event trigger). See .input() for a listener that is only triggered by user input.
upload	This listener is triggered when the user uploads a file into the PolygonAnnotator.
select	Event listener for when the user selects or deselects the PolygonAnnotator. Uses event data gradio.SelectData to carry value referring to the label of the PolygonAnnotator, and selected to refer to state of the PolygonAnnotator. See EventData documentation on how to use this event data

User function

The impact on the users predict function varies depending on whether the component is used as an input or output for an event (or both).

• When used as an Input, the component only impacts the input signature of the user function.
• When used as an output, the component only impacts the return signature of the user function.

The code snippet below is accurate in cases where the component is used as both an input and an output.

• As output: Is passed, dictionary with image path, polygon data including coordinates, colors, opacities,.
• As input: Should return, dictionary containing 'image' (file path or URL), 'polygons' (list of polygon dictionaries.

def predict(
    value: dict | None
) -> dict | None:
    return value