This page was generated from doc/quick-start.ipynb. Interactive online version:

Quickstart

ipyannotations doesn’t have many components, so it should be fast to get up to speed.

Installation

Start by installing ipyannotations:

$ pip install ipyannotations

If you are using Jupyter Lab, rather than the old Jupyter Notebook application, you will also have to install two Jupyter Lab extensions:

$ jupyter labextension install @jupyter-widgets/jupyterlab-manager ipycanvas
$ jupyter labextension install @jupyter-widgets/jupyterlab-manager

Create a polygon annotation widget

A common use case for machine learning is to create polygon masks of objects in an image you want to be able to detect.

To do so, you have to import the PolygonAnnotator, set the classes you want to annotate, and then load your image:

from ipyannotations import PolygonAnnotator
widget = PolygonAnnotator(classes=["eye", "mouth"])
widget.display("img/baboon.png")
widget

To edit a created annoation, you can click the edit button, which allows you to drag the points around. To make this easier, you can use the “Point size” slider to increase the points for easier clicking.

Access the data you have created

There are two ways of processing the annotations you have created. One is to access the widget.data attribute, and either send your annotation to some database, or store it locally:

from IPython.display import display
display(widget.data)

[]

import json
import pathlib
pathlib.Path("img/baboon.json").write_text(json.dumps(widget.data));

Another approach is to register a “submit” function, which is called whenever a user presses the “Submit” button:

def store_annotations(data):
    pathlib.Path("img/baboon.json").write_text(json.dumps(widget.data))

widget.on_submit(store_annotations)

Create other annotation widgets

The full list of annotation widgets as of now is:

1. PolygonAnnotator

2. PointAnnotator

Planned for the future:

• a PixelAnnotator which allows you to drag over pixels to mark them all as a class

• a BoxAnnotator, which allows you to create simple bounding boxes

PolygonAnnotator

Polygons with an arbitrary number of points. Each polygon is formatted as a dictionary with the keys:

{
    'type': 'polygon',
    'label': <class label>,
    'points': <list of xy-tuples>
}

widget = PolygonAnnotator(classes=["eye", "mouth"])

widget.display("img/baboon.png")

widget

PointAnnotator

Single point annotations, formatted as dictionaries with keys:

{
    'type': 'point',
    'label': <class label>,
    'points': <xy-tuple>
}

from ipyannotations import PointAnnotator
widget = PointAnnotator(classes=["eye", "mouth"])
widget.display("img/baboon.png")
widget