API documentation

Image submodule

Classification

class ipyannotations.images.ClassLabeller(**kwargs: Any)[source]
clear()

Clear this widget’s data.

display(item: Any)

Display a data point.

This function calles the display function provided to the widget, and wraps it in a ipywidgets.Output widget to present the display in the right location.

Parameters

item (any) – The data point.

on_submit(callback: Callable)

Add a function to call when the user submits a value.

Parameters

callback (Callable[[Any], None]) – The function to be called when the widget is submitted.

on_undo(callback: Callable)

Provide a function that will be called when the user presses “undo”.

Parameters

callback (Callable[[], None]) – The function to be called. Takes no arguments and returns nothing.

skip(sender: Optional[Button] = None)

Skip a data point.

Parameters

sender (Optional) – The “sender” that invoked this callback. This is ignored.

submit(sender: Union[Button, Text])[source]

Trigger the submission functions.

Parameters

sender (ipywidgets.Button, ipywidgets.Text) – The widget that triggered this.

undo(sender=None)

Undo (i.e. call the functions in the undo queue.)

Parameters

sender (Optional) – The “sender” that invoked this callback. This is ignored.

class ipyannotations.images.MulticlassLabeller(**kwargs: Any)[source]
clear()

Clear this widget’s data.

display(item: Any)

Display a data point.

This function calles the display function provided to the widget, and wraps it in a ipywidgets.Output widget to present the display in the right location.

Parameters

item (any) – The data point.

on_submit(callback: Callable)

Add a function to call when the user submits a value.

Parameters

callback (Callable[[Any], None]) – The function to be called when the widget is submitted.

on_undo(callback: Callable)

Provide a function that will be called when the user presses “undo”.

Parameters

callback (Callable[[], None]) – The function to be called. Takes no arguments and returns nothing.

skip(sender: Optional[Button] = None)

Skip a data point.

Parameters

sender (Optional) – The “sender” that invoked this callback. This is ignored.

submit(sender: Optional[Any] = None)

The function that gets called by submitting an option.

This is called by the button / text field elements and shouldn’t be called directly.

Parameters

sender (Optional) – The “sender” that invoked this callback. This is ignored.

undo(sender=None)[source]

Undo the last action.

This will undo the addition of any free-text, and if none are in the queue, functions registered with on_undo are called.

Landmarks, polygons, and bounding boxes

class ipyannotations.images.PolygonAnnotator(**kwargs: Any)[source]

An annotator for drawing polygons on an image.

To draw a polygon, click anywhere you’d like to start. Continue to click along the edge of the polygon until arrive back where you started. To finish, simply click the first point (highlighted in red). It may be helpful to increase the point size if you’re struggling (using the slider).

You can change the class of a polygon using the dropdown menu while the polygon is still “open”, or unfinished. If you make a mistake, use the Undo button until the point that’s wrong has disappeared.

You can move, but not add / subtract polygon points, by clicking the “Edit” button. Simply drag a point you want to adjust. Again, if you have difficulty aiming at the points, you can increase the point size.

You can increase or decrease the contrast and brightness of the image using the sliders to make it easier to annotate. Sometimes you need to see what’s behind already-created annotations, and for this purpose you can make them more see-through using the “Opacity” slider.

You can select the class of the polygon you are creating by choosing it from the dropdown menu, or by using the hotkeys 1-0 (mapped in order in which the classes appear in the dropdown).

Parameters

  • canvas_size ((int, int), optional) – Size of the annotation canvas in pixels.

  • classes (List[str], optional) – The list of classes you want to create annotations for, by default None.

clear()

Clear this widget’s data.

property data

The annotation data, as List[ Dict ].

The format is a list of dictionaries, with the following key / value combinations:

'type'

'polygon'

'label'

<class label>

'points'

<list of xy-tuples>
display(image: Union[Image, Path])

Clear the annotations and display an image

Parameters

image (widgets.Image, pathlib.Path, np.ndarray) – The image, or the path to the image.

on_submit(callback: Callable)

Add a function to call when the user submits a value.

Parameters

callback (Callable[[Any], None]) – The function to be called when the widget is submitted.

on_undo(callback: Callable)

Provide a function that will be called when the user presses “undo”.

Parameters

callback (Callable[[], None]) – The function to be called. Takes no arguments and returns nothing.

skip(sender: Optional[Button] = None)

Skip a data point.

Parameters

sender (Optional) – The “sender” that invoked this callback. This is ignored.

submit(sender: Optional[Any] = None)

The function that gets called by submitting an option.

This is called by the button / text field elements and shouldn’t be called directly.

Parameters

sender (Optional) – The “sender” that invoked this callback. This is ignored.

undo(_: Optional[Any] = None)

Undo (i.e. call the functions in the undo queue.)

Parameters

sender (Optional) – The “sender” that invoked this callback. This is ignored.

class ipyannotations.images.PointAnnotator(**kwargs: Any)[source]

An annotator for drawing points on an image.

To add a point, select the class using the dropdown menu, and click anywhere on the image. You can undo adding points, and you can adjust the point’s position using the “Edit” button. To make this easier, you may want to adjust the point size using the appropriate slider.

You can increase or decrease the contrast and brightness of the image using the sliders to make it easier to annotate. Sometimes you need to see what’s behind already-created annotations, and for this purpose you can make them more see-through using the “Opacity” slider.

You can select the class of the point you are creating by choosing it from the dropdown menu, or by using the hotkeys 1-0 (mapped in order in which the classes appear in the dropdown).

Parameters

  • canvas_size ((int, int), optional) – Size of the annotation canvas in pixels.

  • classes (List[str], optional) – The list of classes you want to create annotations for, by default None.

clear()

Clear this widget’s data.

property data

The annotation data, as List[ Dict ].

The format is a list of dictionaries, with the following key / value combinations:

'type'

'point'

'label'

<class label>

'coordinates'

<xy-tuple>
display(image: Union[Image, Path])

Clear the annotations and display an image

Parameters

image (widgets.Image, pathlib.Path, np.ndarray) – The image, or the path to the image.

on_submit(callback: Callable)

Add a function to call when the user submits a value.

Parameters

callback (Callable[[Any], None]) – The function to be called when the widget is submitted.

on_undo(callback: Callable)

Provide a function that will be called when the user presses “undo”.

Parameters

callback (Callable[[], None]) – The function to be called. Takes no arguments and returns nothing.

skip(sender: Optional[Button] = None)

Skip a data point.

Parameters

sender (Optional) – The “sender” that invoked this callback. This is ignored.

submit(sender: Optional[Any] = None)

The function that gets called by submitting an option.

This is called by the button / text field elements and shouldn’t be called directly.

Parameters

sender (Optional) – The “sender” that invoked this callback. This is ignored.

undo(_: Optional[Any] = None)

Undo (i.e. call the functions in the undo queue.)

Parameters

sender (Optional) – The “sender” that invoked this callback. This is ignored.

class ipyannotations.images.BoxAnnotator(**kwargs: Any)[source]

An annotator for drawing boxes on an image.

To add a box, simply click on one of the corners, and drag the mouse to the corner opposite. The box will grow as you drag your mouse. To adjust the box after, you can click the “Edit” button and drag any of the corners to where you want them.

You can increase or decrease the contrast and brightness of the image using the sliders to make it easier to annotate. Sometimes you need to see what’s behind already-created annotations, and for this purpose you can make them more see-through using the “Opacity” slider.

You can select the class of the box you are creating by choosing it from the dropdown menu, or by using the hotkeys 1-0 (mapped in order in which the classes appear in the dropdown).

Parameters

  • canvas_size ((int, int), optional) – Size of the annotation canvas in pixels.

  • classes (List[str], optional) – The list of classes you want to create annotations for, by default None.

clear()

Clear this widget’s data.

property data

The annotation data, as List[ Dict ].

The format is a list of dictionaries, with the following key / value combinations:

'type'

'box'

'label'

<class label>

'xyxy'

<tuple of x0, y0, x1, y1>
display(image: Union[Image, Path])

Clear the annotations and display an image

Parameters

image (widgets.Image, pathlib.Path, np.ndarray) – The image, or the path to the image.

on_submit(callback: Callable)

Add a function to call when the user submits a value.

Parameters

callback (Callable[[Any], None]) – The function to be called when the widget is submitted.

on_undo(callback: Callable)

Provide a function that will be called when the user presses “undo”.

Parameters

callback (Callable[[], None]) – The function to be called. Takes no arguments and returns nothing.

skip(sender: Optional[Button] = None)

Skip a data point.

Parameters

sender (Optional) – The “sender” that invoked this callback. This is ignored.

submit(sender: Optional[Any] = None)

The function that gets called by submitting an option.

This is called by the button / text field elements and shouldn’t be called directly.

Parameters

sender (Optional) – The “sender” that invoked this callback. This is ignored.

undo(_: Optional[Any] = None)

Undo (i.e. call the functions in the undo queue.)

Parameters

sender (Optional) – The “sender” that invoked this callback. This is ignored.

Captions

class ipyannotations.images.FreetextAnnotator(**kwargs: Any)[source]

A widget for submitting free-text data annotations for images.

This widget presents a simple text box for data entry, and is designed for image captioning, visual descriptions or summarisation.

clear()

Clear this widget’s data.

display(item: Any)

Display a data point.

This function calles the display function provided to the widget, and wraps it in a ipywidgets.Output widget to present the display in the right location.

Parameters

item (any) – The data point.

on_submit(callback: Callable)

Add a function to call when the user submits a value.

Parameters

callback (Callable[[Any], None]) – The function to be called when the widget is submitted.

on_undo(callback: Callable)

Provide a function that will be called when the user presses “undo”.

Parameters

callback (Callable[[], None]) – The function to be called. Takes no arguments and returns nothing.

skip(sender: Optional[Button] = None)

Skip a data point.

Parameters

sender (Optional) – The “sender” that invoked this callback. This is ignored.

submit(sender: Optional[Any] = None)

The function that gets called by submitting an option.

This is called by the button / text field elements and shouldn’t be called directly.

Parameters

sender (Optional) – The “sender” that invoked this callback. This is ignored.

undo(sender=None)

Undo (i.e. call the functions in the undo queue.)

Parameters

sender (Optional) – The “sender” that invoked this callback. This is ignored.

Text submodule

Classification

class ipyannotations.text.ClassLabeller(**kwargs: Any)[source]

A text classification widget.

This widget lets you assign a single class to text.

clear()

Clear this widget’s data.

display(item: Any)

Display a data point.

This function calles the display function provided to the widget, and wraps it in a ipywidgets.Output widget to present the display in the right location.

Parameters

item (any) – The data point.

on_submit(callback: Callable)

Add a function to call when the user submits a value.

Parameters

callback (Callable[[Any], None]) – The function to be called when the widget is submitted.

on_undo(callback: Callable)

Provide a function that will be called when the user presses “undo”.

Parameters

callback (Callable[[], None]) – The function to be called. Takes no arguments and returns nothing.

skip(sender: Optional[Button] = None)

Skip a data point.

Parameters

sender (Optional) – The “sender” that invoked this callback. This is ignored.

submit(sender: Union[Button, Text])[source]

Trigger the submission functions.

Parameters

sender (ipywidgets.Button, ipywidgets.Text) – The widget that triggered this.

undo(sender=None)

Undo (i.e. call the functions in the undo queue.)

Parameters

sender (Optional) – The “sender” that invoked this callback. This is ignored.

class ipyannotations.text.MulticlassLabeller(**kwargs: Any)[source]
clear()

Clear this widget’s data.

display(item: Any)

Display a data point.

This function calles the display function provided to the widget, and wraps it in a ipywidgets.Output widget to present the display in the right location.

Parameters

item (any) – The data point.

on_submit(callback: Callable)

Add a function to call when the user submits a value.

Parameters

callback (Callable[[Any], None]) – The function to be called when the widget is submitted.

on_undo(callback: Callable)

Provide a function that will be called when the user presses “undo”.

Parameters

callback (Callable[[], None]) – The function to be called. Takes no arguments and returns nothing.

skip(sender: Optional[Button] = None)

Skip a data point.

Parameters

sender (Optional) – The “sender” that invoked this callback. This is ignored.

submit(sender: Optional[Any] = None)

The function that gets called by submitting an option.

This is called by the button / text field elements and shouldn’t be called directly.

Parameters

sender (Optional) – The “sender” that invoked this callback. This is ignored.

undo(sender=None)[source]

Undo the last action.

This will undo the addition of any free-text, and if none are in the queue, functions registered with on_undo are called.

class ipyannotations.text.SentimentLabeller(**kwargs: Any)[source]

A sentiment classification widget.

This widget presents three label options, for classifying text into one of negative, neutral, or positive sentiment.

clear()

Clear this widget’s data.

display(item: Any)

Display a data point.

This function calles the display function provided to the widget, and wraps it in a ipywidgets.Output widget to present the display in the right location.

Parameters

item (any) – The data point.

on_submit(callback: Callable)

Add a function to call when the user submits a value.

Parameters

callback (Callable[[Any], None]) – The function to be called when the widget is submitted.

on_undo(callback: Callable)

Provide a function that will be called when the user presses “undo”.

Parameters

callback (Callable[[], None]) – The function to be called. Takes no arguments and returns nothing.

skip(sender: Optional[Button] = None)

Skip a data point.

Parameters

sender (Optional) – The “sender” that invoked this callback. This is ignored.

submit(sender: Button)[source]

Submit the label.

Parameters

sender (widgets.Button) – One of the three interface buttons.

undo(sender=None)

Undo (i.e. call the functions in the undo queue.)

Parameters

sender (Optional) – The “sender” that invoked this callback. This is ignored.

Entity tagging

class ipyannotations.text.TextTagger(**kwargs: Any)[source]

A tagging widget to annotate tokens inside text.

clear()

Clear this widget’s data.

display(text: str)[source]

Display text to be tagged.

Parameters

text (str) –

on_submit(callback: Callable)

Add a function to call when the user submits a value.

Parameters

callback (Callable[[Any], None]) – The function to be called when the widget is submitted.

on_undo(callback: Callable)

Provide a function that will be called when the user presses “undo”.

Parameters

callback (Callable[[], None]) – The function to be called. Takes no arguments and returns nothing.

skip(sender: Optional[Button] = None)

Skip a data point.

Parameters

sender (Optional) – The “sender” that invoked this callback. This is ignored.

submit(sender: Optional[Any] = None)

The function that gets called by submitting an option.

This is called by the button / text field elements and shouldn’t be called directly.

Parameters

sender (Optional) – The “sender” that invoked this callback. This is ignored.

undo(sender=None)

Undo (i.e. call the functions in the undo queue.)

Parameters

sender (Optional) – The “sender” that invoked this callback. This is ignored.

Captioning

class ipyannotations.text.FreetextAnnotator(**kwargs: Any)[source]

A widget for submitting free-text data annotations for text.

This widget presents a simple text box for data entry, and is designed for text summarisation, question answering, or similar.

clear()

Clear this widget’s data.

display(item: Any)

Display a data point.

This function calles the display function provided to the widget, and wraps it in a ipywidgets.Output widget to present the display in the right location.

Parameters

item (any) – The data point.

on_submit(callback: Callable)

Add a function to call when the user submits a value.

Parameters

callback (Callable[[Any], None]) – The function to be called when the widget is submitted.

on_undo(callback: Callable)

Provide a function that will be called when the user presses “undo”.

Parameters

callback (Callable[[], None]) – The function to be called. Takes no arguments and returns nothing.

skip(sender: Optional[Button] = None)

Skip a data point.

Parameters

sender (Optional) – The “sender” that invoked this callback. This is ignored.

submit(sender: Optional[Any] = None)

The function that gets called by submitting an option.

This is called by the button / text field elements and shouldn’t be called directly.

Parameters

sender (Optional) – The “sender” that invoked this callback. This is ignored.

undo(sender=None)

Undo (i.e. call the functions in the undo queue.)

Parameters

sender (Optional) – The “sender” that invoked this callback. This is ignored.

Generic widgets

class ipyannotations.generic.ClassLabeller(**kwargs: Any)[source]

A classification widget.

This widget is designed to assign one class (a string label) to each data point. Choose a class by clicking the corresponding button, the value in the corresponding dropdown (if there isn’t space for all buttons), or by using the hotkeys 1-0. Hotkeys are mapped in the order in which the classes appear.

clear()

Clear this widget’s data.

display(item: Any)

Display a data point.

This function calles the display function provided to the widget, and wraps it in a ipywidgets.Output widget to present the display in the right location.

Parameters

item (any) – The data point.

on_submit(callback: Callable)

Add a function to call when the user submits a value.

Parameters

callback (Callable[[Any], None]) – The function to be called when the widget is submitted.

on_undo(callback: Callable)

Provide a function that will be called when the user presses “undo”.

Parameters

callback (Callable[[], None]) – The function to be called. Takes no arguments and returns nothing.

skip(sender: Optional[Button] = None)

Skip a data point.

Parameters

sender (Optional) – The “sender” that invoked this callback. This is ignored.

submit(sender: Union[Button, Text])[source]

Trigger the submission functions.

Parameters

sender (ipywidgets.Button, ipywidgets.Text) – The widget that triggered this.

undo(sender=None)

Undo (i.e. call the functions in the undo queue.)

Parameters

sender (Optional) – The “sender” that invoked this callback. This is ignored.

class ipyannotations.generic.MulticlassLabeller(**kwargs: Any)[source]

A multi-class data labelling widget.

Label an arbitrary data point with as many or as few labels as necessary. Toggle labels by either clicking on the corresponding button, or by using the hotkeys 1-0 (mapped in order in which labels are on screen). Submit by either clicking the “Submit” button, or by pressing the Enter key.

clear()

Clear this widget’s data.

display(item: Any)

Display a data point.

This function calles the display function provided to the widget, and wraps it in a ipywidgets.Output widget to present the display in the right location.

Parameters

item (any) – The data point.

on_submit(callback: Callable)

Add a function to call when the user submits a value.

Parameters

callback (Callable[[Any], None]) – The function to be called when the widget is submitted.

on_undo(callback: Callable)

Provide a function that will be called when the user presses “undo”.

Parameters

callback (Callable[[], None]) – The function to be called. Takes no arguments and returns nothing.

skip(sender: Optional[Button] = None)

Skip a data point.

Parameters

sender (Optional) – The “sender” that invoked this callback. This is ignored.

submit(sender: Optional[Any] = None)

The function that gets called by submitting an option.

This is called by the button / text field elements and shouldn’t be called directly.

Parameters

sender (Optional) – The “sender” that invoked this callback. This is ignored.

undo(sender=None)[source]

Undo the last action.

This will undo the addition of any free-text, and if none are in the queue, functions registered with on_undo are called.

class ipyannotations.generic.FreetextAnnotator(**kwargs: Any)[source]

A widget for submitting free-text data annotations.

This widget presents a simple text box for data entry, and is designed for captioning, question answering, and similar tasks.

clear()

Clear this widget’s data.

display(item: Any)

Display a data point.

This function calles the display function provided to the widget, and wraps it in a ipywidgets.Output widget to present the display in the right location.

Parameters

item (any) – The data point.

on_submit(callback: Callable)

Add a function to call when the user submits a value.

Parameters

callback (Callable[[Any], None]) – The function to be called when the widget is submitted.

on_undo(callback: Callable)

Provide a function that will be called when the user presses “undo”.

Parameters

callback (Callable[[], None]) – The function to be called. Takes no arguments and returns nothing.

skip(sender: Optional[Button] = None)

Skip a data point.

Parameters

sender (Optional) – The “sender” that invoked this callback. This is ignored.

submit(sender: Optional[Any] = None)

The function that gets called by submitting an option.

This is called by the button / text field elements and shouldn’t be called directly.

Parameters

sender (Optional) – The “sender” that invoked this callback. This is ignored.

undo(sender=None)

Undo (i.e. call the functions in the undo queue.)

Parameters

sender (Optional) – The “sender” that invoked this callback. This is ignored.