Quick start

This short introduction to Labelbox-Python SDK is designed mainly for new users. The example will introduce you to Labelbox-Python SDK concepts that you will use commonly. We will demonstrate a simple but common workflow of importing an image data row, setting up a project, and exporting.

Example: Import data rows to exporting from project

Before you start

We must first install the Labelbox library and then import the SDK module. It is recommended to install "labelbox[data]" over labelbox to obtain all the correct dependencies. We will also be importing the Python UUID library to generate universal unique IDs for the variety of objects that will be created with this notebook.

pip install -q "labelbox[data]"

import labelbox as lb
import uuid

Replace the value of API_KEY with a valid API key to connect to the Labelbox client.

API_KEY = None
client = lb.Client(API_KEY)

Step 1: Create dataset and import data row

Below, we will create a dataset and then attach a publicly hosted image data row. Typically, you would import data rows hosted on a cloud provider (recommended) or import them locally. For more information, visit our import image data section in our developer guides. You can find your dataset inside the Catalog section of Labelbox.

# Create dataset from client
dataset = client.create_dataset(name="Quick Start Example Dataset")

global_key = str(uuid.uuid4())  # Unique user specified ID

# Data row structure
image_data_rows = [{
    "row_data":
        "https://storage.googleapis.com/labelbox-datasets/image_sample_data/2560px-Kitano_Street_Kobe01s5s4110.jpeg",
    "global_key":
        global_key,
    "media_type":
        "IMAGE",
}]

# Bulk import data row
task = dataset.create_data_rows(image_data_rows)  # List of data rows
task.wait_till_done()
print(task.errors)  # Print any errors

Step 2: Creating an ontology

Before sending our data row to a labeling project, we must create an ontology. The example below will create a simple ontology with a bounding box tool and a checklist classification feature. For more information, visit the ontology section inside our developer guides.

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

# Checklist feature
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"),
        ],
    )
]

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

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

Step 3: Creating a project and attaching our ontology

Now that we have made our ontology, we are ready to create a project where we can label our data row.

# Create a new project
project = client.create_project(
    name="Quick Start Example Project",
    media_type=lb.MediaType.Image,
)

# Attach created ontology
project.connect_ontology(ontology)

Step 4: Sending our data row to our project by creating a batch

With our project created, we can send our data rows by creating a batch. Our data rows will start in the initial labeling queue, where labelers are able to annotate our data row. For more information on batches, review the batches section of our developer guides.

project.create_batch(
    name="Quick Start Example Batch" + str(uuid.uuid4()),
    global_keys=[
        global_key
    ],  # Global key we used earlier in this guide to create our dataset
    priority=5,
)

Step 5: Exporting from our project

We have now successfully set up a project for labeling using only the SDK!

From here, you can either label our data row directly inside the labeling queue or import annotations directly through our SDK. Below we will demonstrate the final step of this guide by exporting from our project. Since we did not label any data rows or import annotations within this guide, no labels will be presented on our data row. For a full overview of exporting, visit our export overview developer guide.

# Start export from project
export_task = project.export()
export_task.wait_till_done()

# Conditional if task has errors
if export_task.has_errors():
    export_task.get_buffered_stream(stream_type=lb.StreamType.ERRORS).start(
        stream_handler=lambda error: print(error))

if export_task.has_result():
    # Start export stream
    stream = export_task.get_buffered_stream()

    # Iterate through data rows
    for data_row in stream:
        print(data_row.json)

Clean up

This section serves as an optional clean-up step to delete the Labelbox assets created within this guide. You will need to uncomment the delete methods shown.

# project.delete()
# client.delete_unused_ontology(ontology.uid)
# dataset.delete()