AnnotatedImage[source]

An interactive image viewer that supports drawing, selecting, and styling geometric shapes (polygons, rectangles, points...) as annotations.

Under the hood, we use Konva to render the image and its annotations.

Examples

from pret import component, create_store, use_store_snapshot, use_event_callback
from pret.ui.metanno import AnnotatedImage
import time

# Reactive store holding the annotation list
img_state = create_store([
    {
        "id": "1",
        "type": "polygon",
        "points": [10, 10, 50, 20],
        "label": "OBJ",
        "style": "primary",
    }
])

# Style preset referenced from the annotation above
img_annotation_styles = {
    "primary": {
        "strokeColor": "red",
        "strokeWidth": 2,
        "fillColor": "rgba(255,0,0,0.5)",
        "labelPosition": "center",
        "align": "center",
        "verticalAlign": "top",
    },
    "secondary": {
        "strokeColor": "blue",
        "strokeWidth": 2,
        "fillColor": "#0000ff80",
        "textColor": "white",
    }
}

@component
def MyImage():
    tracked_state = use_store_snapshot(img_state)

    @use_event_callback
    def on_mouse_select(modkeys, shapes):
        # Toggle 'mouseSelected' flag
        for shp in shapes:
            img_state.append({
                "id": str(time.time()),
                "points": shp["points"],
                "label": "OBJ",
                "style": "primary",
            })

    @use_event_callback
    def on_click(shape_idx, modkeys):
        if shape_idx is None:
            img_state.clear()
        else:
            old_style = img_state[shape_idx].get("style", "primary")
            new_style = "secondary" if old_style == "primary" else "primary"
            img_state[shape_idx]["style"] = new_style

    return AnnotatedImage(
        image="https://picsum.photos/400/300",
        annotations=tracked_state,
        annotation_styles=img_annotation_styles,
        on_mouse_select=on_mouse_select,
        on_click=on_click,
    )

MyImage()

Parameters

PARAMETER	DESCRIPTION
`annotations`	List of annotation objects drawn on top of the image. Each annotation must contain the geometric `type` and `points` fields (defining the shape) plus optional metadata such as: `id`: Optional unique identifier. `label`: Human-readable text shown next to the shape. `style`: Key that looks up visual properties in `annotation_styles`. `selected` / `highlighted` / `mouseSelected`: Booleans used by the component when rendering interaction state. TYPE: `Any`
`annotation_styles`	Named style presets referenced by the `style` field of an annotation. Each preset may define properties such as stroke color, fill color, opacity, font size, and label alignment, using the following properties: `strokeColor` (str): Color of the shape's stroke (e.g. `"#ff0000"`). `strokeWidth` (int): Width of the shape's stroke in pixels. `fillColor` (str): Background color of the shape (e.g. `"#0000ff80"`). `opacity` (float): Opacity of the shape's fill (0.0 to 1.0). `shape` (str): Shape type, e.g. `"polygon"`, `"rectangle"`, `"circle"`, etc. `fontSize` (int): Font size for the label text. `align` ("left" \| "center" \| "right"): Horizontal alignment of the label text. `verticalAlign` ("top" \| "middle" \| "bottom"): Vertical alignment of the label text. TYPE: `Any`
`image`	Source URL or base-64 data URI of the image to annotate. TYPE: `str`
`mouse_selection`	Temporary shapes being drawn by the user while the mouse button is held down. Supplied back to `on_mouse_select` when the gesture ends. TYPE: `Any`
`style`	Inline CSS-compatible style overrides for the root element of the component. TYPE: `Any`
`actions`	Optional imperative handles (e.g. `actions["scroll_to_shape"](idx)`) that the parent may call. Reserved for future expansion. TYPE: `Any`
`key`	React key for stable reconciliation. TYPE: `Union[str, int]`
`on_click`	Invoked when the user clicks on an existing shape. `shape_id` – Identifier of the clicked annotation `modkeys` – List of pressed modifier keys (e.g. `["Shift"]`) TYPE: `Any`
`on_key_press`	Invoked when the component has focus and the user presses a key. `key` – The key name (`"Escape"`, `"Delete"` …) `modkeys` – Concurrently pressed modifier keys TYPE: `Any`
`on_mouse_enter_shape`	Hover callbacks fired when the mouse pointer enters or leaves a shape. TYPE: `Any`
`on_mouse_select`	Fired after the user completes a drag selection. `modkeys` – Modifier keys pressed during selection `shapes` – All shapes inside the lasso / rectangle TYPE: `Any`