Client

import labelbox as lb
import labelbox.data.annotation_types as lb_types
client = lb.Client(api_key="<YOUR_API_KEY>")

Create an ontology

Each Tool and Classification type requires a specific value to be passed when creating the feature.

Feature	Class	Value
Bounding box	`Tool`	`BBOX`
Polygon	`Tool`	`POLYGON`
Polyline	`Tool`	`LINE`
Point	`Tool`	`POINT`
Segmentation mask	`Tool`	`RASTER_SEGMENTATION`
Relationship	`Tool`	`RELATIONSHIP`
Entity	`Tool`	`NER`
Radio	`Classification`	`RADIO`
Checklist	`Classification`	`CHECKLIST`
Text	`Classification`	`TEXT`

When you create an ontology, you must specify the media_type parameter, which represents the modality of the data rows that the ontology will be used to label. Certain features are only compatible with certain media types.

Media type	Value	Bounding box	Polygon	Polyline	Point	Segmentation mask	Relationship	Entity
Image	`IMAGE`	✔	✔	✔	✔	✔	✔
Video	`VIDEO`	✔		✔	✔	✔
Text	`TEXT`							✔
Audio	`AUDIO`
Document	`PDF`	✔					✔	✔
Geospatial		✔	✔	✔	✔
Simple tile		✔	✔	✔	✔
Conversational text	`CONVERSATIONAL`							✔
JSON	`JSON`							✔
HTML	`HTML`
DICOM	`DICOM`			✔		✔

Create from new features

object_features = [
    lb.Tool(
        tool=lb.Tool.Type.BBOX,
        name="regulatory-sign",
        color="#ff0000",
    )
]

classification_features = [
    lb.Classification(
        class_type=lb.Classification.Type.CHECKLIST,
        name="Quality Issues",
        options=[
            lb.Option(value="blurry", label="Blurry"),
            lb.Option(value="distorted", label="Distorted")
        ]
    )

]

ontology_builder = lb.OntologyBuilder(
    tools=object_features,
    classifications=classification_features
)

ontology = client.create_ontology(
  "Ontology from new features",
  ontology_builder.asdict(),
  media_type=lb.MediaType.Image
)

Create from normalized JSON format

Users can create ontologies from a JSON definition of the ontology.
Each tool type requires a specific value to be passed:

Tool	Value
Bounding box	`rectangle`
Polygon	`polygon`
Polyline	`line`
Point	`point`
Segmentation mask	`superpixel`
Entity	`named-entity`

# This will automatically create new feature schema
ontology_name = "sdk-ontology"
feature_schema_cat_normalized = {
    'tool': 'polygon',
    'name': 'cat',
    'color': 'black'
}

ontology_normalized_json = {
    "tools": [feature_schema_cat_normalized],
    "classifications": []
}
ontology = client.create_ontology(name=ontology_name,
                                  normalized=ontology_normalized_json,
                                  media_type=lb.MediaType.Image)

Create from existing features

If you already have features created, you can query them by name or by schema id.
Re-using an existing feature is highly recommended.

## Search feature by name in your org
regulatory_sign_feature_schema = next(client.get_feature_schemas("regulatory-sign"))
classification_feature = next(client.get_feature_schemas("Quality Issues"))

## Get feature by feature schema ID. You can get this from the UI
regulatory_sign_feature_schema = client.get_feature_schema("FEATURE_SCHEMA_ID")

## Or, create a new 
ontology = client.create_ontology_from_feature_schemas("Ontology from existing features", [regulatory_sign_feature_schema.uid, classification_feature.uid], media_type=MediaType.Image)

Create a nested ontology

You can create a child feature nested under a parent feature. Only classification features can be children of a nested ontology. For instance, if you want to create an ontology where a bounding box has a radio sub-classification, you will add a classificationsfield that contains a list of classification features as children.

bbox_with_sub_classfication = lb.Tool(tool=lb.Tool.Type.BBOX, name="cat", 
         classifications=[
            lb.Classification(class_type=lb.Classification.Type.RADIO, name="radio", options=[
                lb.Option(value="long-fur"),
                lb.Option(value="short-fur")
            ])
         ])

ontology_builder = lb.OntologyBuilder(tools=[
    bbox_with_sub_classfication
])

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

radio_with_sub_classification = Classification( 
      class_type=Classification.Type.RADIO, 
      instructions="radio_question_sub", 
      options=[
        Option(value="first_radio_answer",
               options=[
                   Classification(
                    class_type=Classification.Type.RADIO,
                    instructions="sub_radio_question",
                    options=[
                      Option(value="first_sub_radio_answer"),
                      Option(value="second_sub_radio_answer")
                    ]
                  ),
            ])],
    )

ontology_builder = OntologyBuilder(classifications=[
    sub_radio_classification
])

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

Get ontologies

# get by ID
ontology = client.get_ontology("<ontology_id>")

# get by name
ontology = next(client.get_ontologies("<ontology_name>"))

# get multiple ontologies by keyword
ontologies = client.get_ontologies(name_contains="<keyword>")

Check if a feature is archived in an ontology

client.is_feature_schema_archived("<ontology_id>", "<feature_schema_id>")

Get all unused ontologies

client.get_unused_ontologies()

Delete an unused ontology

client.delete_unused_ontology("<ontology_id>")

Fundamentals

Connect an ontology to a project

# get (or create) a project
project = client.get_project("<project_id>")

# get (or create) an ontology
ontology = client.get_ontology("<ontology_id>")

# the argument must be an object of the Ontology class
project.setup_editor(ontology)

Methods

Get the tools

tools = ontology.tools()

for tool in tools:
  print(tool)

Get the classifications

classifications = ontology.classifications()

for classification in classifications:
  print(classification)

Attributes

Get the basics

# name (str)
ontology.name

# description (str)
ontology.description

# updated at (datetime)
ontology.updated_at

# created at (datetime)
ontology.created_at

# normalized output of the ontology (JSON)
ontology.normalized

# count of object tools in the ontology (int)
ontology.object_schema_count

# count of classifications in the ontology (int)
ontology.classification_schema_count

# created by (relationship to User object)
user = ontology.created_by()