Ontology

View Ontology guide page for Ontology schema definitions and details.

Create an ontology

📘

media_type will become a required field

Starting March 31, all new ontologies created with the SDK will require you to pass in a new parameter to define the media type you intend you use with the ontology (ex. Image, Pdf, etc). This will need match with the media type of the labeling project when attaching ontologies.

Create from new feature objects

This is the recommended method.

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

client = Client()

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

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

]

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

ontology = client.create_ontology("Ontology from new features", ontology_builder.asdict(), media_type=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 be passed:
ToolValue
Bounding boxrectangle
Polygonpolygon
Polylineline
Pointpoint
Segmentation masksuperpixel
Entitynamed-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=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 = Tool(tool=Tool.Type.BBOX, name="cat", 
         classifications=[
            Classification(class_type=Classification.Type.RADIO, name="radio", options=[
                Option(value="long-fur"),
                Option(value="short-fur")
            ])
         ])

ontology_builder = 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 an ontology

You can query an ontology by name or id.

## Search ontology by name in your org
ontology = next(client.get_ontologies(ontology_name))

## Get ontology by ID. You can get this from the UI
ontology = client.get_ontology("ONTOLOGY_ID")

print(ontology)

Connect an ontology to a project

project = client.create_project(name="my_new_project")
project.setup_editor(ontology)
print(project.ontology())

Delete unused ontology

Deletes an ontology if it is not used by any annotations

client.delete_unused_ontology("<Ontology_id>")