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`
Message ranking	`Tool`	`MESSAGE_RANKING`
Single message selection	`Tool`	`MESSAGE_SINGLE_SELECTION`
Multiple message selection	`Tool`	`MESSAGE_MULTI_SELECTION`
Radio	`Classification`	`RADIO`
Checklist	`Classification`	`CHECKLIST`
Text	`Classification`	`TEXT`

When you create an ontology, 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.

🚧
Specify an ontology media type
The media_type parameter of client.create_ontology defaults to None, but it's highly recommended to specify one for validation and error handling.

The media_type parameter takes the following values:

lb.MediaType.Audio
lb.MediaType.Conversational
lb.MediaType.Document
lb.MediaType.Geospatial_Tile
lb.MediaType.Html
lb.MediaType.Image
lb.MediaType.Simple_Tile
lb.MediaType.Text
lb.MediaType.Video

Create ontology from new features

For more complex ontology creation examples, view our Ontology examples guide .

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	`raster-segmentation`
Entity	`named-entity`

# This automatically creates 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(), media_type=MediaType.Image)

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.connect_ontology(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()

Client

Create an ontology

🚧Specify an ontology media type

Create ontology from new features

Create from normalized JSON format

Create from existing features

Create a nested ontology

Get ontologies

Check if a feature is archived in an ontology

Get all unused ontologies

Delete an unused ontology

Fundamentals

Connect an ontology to a project

Methods

Get the tools

Get the classifications

Attributes

Get the basics

🚧
Specify an ontology media type