A developer guide for creating, modifying, and connecting ontologies via the Python SDK.
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 classifications
field 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()