Overview

A Label is a pair of Data Row and its associated collection of Annotations. An Annotation represents the individual feature value of a data row. You will use SDK to create Annotation objects first in order to construct a Label or Model assisted Label for a data row.

An Annotation object consists of the following parameters:

Parameter

Description

name

Feature name. A Feature with exactly the same name must be created beforehand.

value

Annotation kinds

feature_schema_id

Optionally specify Features schema id.

ClassificationAnnotation

Optionally specify nested ClassificationAnnotations. Only classification features can be children in a nested Ontology.

Here is a table of supported Annotation kinds that can be used to define an annotation. Annotation kinds are categorized into two major Feature categories - ObjectAnnotation and ClassificationAnnotation.

Annotation kind

Feature category

Feature Tool Type

Description

Mask

ObjectAnnotation

SEGMENTATION

Segmentation mask in raster format

Polygon

ObjectAnnotation

POLYGON

List of unique points forming a closed polygon

Rectangle

ObjectAnnotation

BBOX

Bounding box

Line

ObjectAnnotation

LINE

A list of unique points forming a poly line

Point

ObjectAnnotation

POINT

A single point

Checklist

ClassificationAnnotation

CHECKLIST

Multi-choice checklist

Radio

ClassificationAnnotation

RADIO

Single-choice radio

Text

ClassificationAnnotation

TEXT

Free form text

Create Typed Annotation Objects

In order to use Annotation objects for Label Import or Model-assisted Label Import, you will need to configure the right ontology for the project first. Each Annotation in your Label should match a Tool in your project ontology.

Create matching ontology for Annotations

from labelbox import OntologyBuilder, Tool, Classification, Option, Client

client = Client(api_key="<YOUR_API_KEY>")

ontology_builder = OntologyBuilder(
    tools=[
        Tool(tool=Tool.Type.POINT, name="point"),
        Tool(tool=Tool.Type.BBOX, name="box"),
        Tool(tool=Tool.Type.LINE, name="line"),
        Tool(tool=Tool.Type.POLYGON, name="polygon"),    
        Tool(tool=Tool.Type.SEGMENTATION, name="mask")],
    classifications=[
        Classification(class_type=Classification.Type.TEXT, instructions="text"),
        Classification(class_type=Classification.Type.CHECKLIST, instructions="checklist", options=[
            Option(value="first_checklist_answer"),
            Option(value="second_checklist_answer")            
        ]),
        Classification(class_type=Classification.Type.RADIO, instructions="radio", options=[
            Option(value="first_radio_answer"),
            Option(value="second_radio_answer")
        ]),                                      
])

project.setup_editor(ontology)

Create ObjectAnnotation objects

from labelbox.data.annotation_types import (
    ObjectAnnotation, Polygon, Rectangle, Line, Mask, Point
)

# Here are all possible ObjectAnnotation kinds (point, rectangle, line, polygon, and mask)
point = Point(x=100, y=100)
point_annotation = ObjectAnnotation(value=point, name="point")

rectangle = Rectangle(start=Point(x=30,y=30), end=Point(x=200,y=200))
rectangle_annotation = ObjectAnnotation(value=rectangle, name="box")

line = Line(points=[Point(x=60,y=70), Point(x=65,y=100), Point(x=80,y=130), Point(x=40,y=200)])
line_annotation = ObjectAnnotation(value=line, name="line")

array = np.zeros([128, 128, 3], dtype=np.uint8)
polygon = Polygon(points=[Point(x=100,y=100), Point(x=110,y=110), Point(x=130,y=130), Point(x=170,y=170), Point(x=220,y=220)])
polygon_annotation = ObjectAnnotation(value=polygon, name="polygon")

mask_data = MaskData(arr=array)
mask = Mask(mask=mask_data, color=(0, 0, 0))
mask_annotation = ObjectAnnotation(value=mask, name="mask")

Create ClassificationAnnotation objects

from labelbox.data.annotation_types import (
    ClassificationAnnotation, Checklist, Radio, Text, TextEntity, ClassificationAnswe
)

# Here are all possible ClassificationAnnotation kinds (text, checklist, radio)
text = Text(answer="the answer to the text question")
text_annotation = ClassificationAnnotation(value=text, name="text")

checklist = Checklist(answer=[ClassificationAnswer(name="first_checklist_answer"),ClassificationAnswer(name="second_checklist_answer")])
checklist_annotation = ClassificationAnnotation(value=checklist, name="checklist")

radio = Radio(answer = ClassificationAnswer(name = "second_radio_answer"))
radio_annotation = ClassificationAnnotation(value=radio, name="radio")

Create nested Annotation

10991099

You can also create nested Annotations. In this example, we will create a bounding box that also has a radio classification as a sub-classification.

# Here is a Ontology with the same nested structure. 
ontology_builder = OntologyBuilder(tools=[
    Tool(tool=Tool.Type.BBOX, name="cat", 
         classifications=[
          Classification(class_type=Classification.Type.RADIO, name="radio", instructions="radio", options=[
              Option(value="long-fur"),
              Option(value="short-fur")
          ])
    ])
])

ontology = client.create_ontology("Simple nested ontology", ontology_builder.asdict())
project.setup_edit(ontology)

rectangle = Rectangle(start=Point(x=30,y=30), end=Point(x=200,y=200))
radio_answer = Radio(answer = ClassificationAnswer(name = "short-fur"))
nested_annotation = ObjectAnnotation(value=rectangle, name="cat", 
                    classifications=[ClassificationAnnotation(value=radio, name="radio")])