DOCSEARCHbyAlgolia
Submit Docs

Labelbox Python SDK

repository·develop·Indexed 41 days ago

https://github.com/labelbox/labelbox-python

The Labelbox Python SDK allows developers to programmatically curate and annotate data, manage datasets, and automate workflows for computer vision and language models. It provides tools for managing projects, ontologies, and data rows, as well as importing and exporting annotations and model predictions across various data types including text, image, video, audio, and PDF.

Tokens
108.4K
Snippets
339
Records
399
Agent score
99%

What's inside Labelbox

  1. Overview of Alignerr workspace management

    develop

    The lbox-alignerr package provides tools for managing Alignerr workspaces within Labelbox. It is designed to automate and streamline the following administrative tasks:

    • Project Management: Creating and configuring Alignerr projects.
    • Taxonomy Management: Managing domains and tags used within projects.
    • Workforce Management: Handling workforce-related configurations and assignments.

  3. Understand the Labelbox SDK package organization

    develop

    The SDK source is organized into several functional modules:

    • data/: Contains code for mapping annotations (labels or pre-labels) to Python objects, and tools for NDJson serialization/deserialization.
    • orm/: Provides the Object-Relational Mapping (ORM) layer, including base classes, attribute classes (fields and relationships), and generic GraphQL queries.
    • schema/: Defines data type classes (e.g., Project, Label) using orm/ classes and contains custom GraphQL templates.
    • client.py: Contains the Client class, which serves as the primary interface for communicating with Labelbox servers.
    • exceptions.py: Contains all custom Labelbox error declarations.
    • pagination.py: Provides support for fetching paginated relationships and collections.
    • utils.py: Contains general utility functions.

  5. Configure an Ontology for Document Annotations

    develop

    Before uploading predictions, you must define an Ontology using OntologyBuilder. The ontology must include classifications (Radio, Checklist, Text) and tools (BBOX, NER) that match your model's output.

    For complex models, you can nest classifications within tools or within other classifications (e.g., a Radio classification that contains a sub-checklist).

    import labelbox as lb

ontology_builder = lb.OntologyBuilder(
    classifications=[
        lb.Classification(
            class_type=lb.Classification.Type.RADIO,
            name="radio_question",
            scope=lb.Classification.Scope.GLOBAL,
            options=[lb.Option(value="first_radio_answer")],
        ),
        # ... other classifications
    ],
    tools=[
        lb.Tool(tool=lb.Tool.Type.BBOX, name="bounding_box"),
        lb.Tool(tool=lb.Tool.Type.NER, name="named_entity"),
    ],
)

ontology = client.create_ontology(
    "Document Annotation Import Demo",
    ontology_builder.asdict(),
    media_type=lb.MediaType.Document,
)

  6. Configure an Ontology for YOLOv8 annotations

    develop

    Use lb.OntologyBuilder to define the tools (Bounding Boxes, Segmentations, Polygons) and feature names that match your YOLOv8 model's output. Then, create the ontology using client.create_ontology.

    ontology_builder = lb.OntologyBuilder(tools=[
    lb.Tool(tool=lb.Tool.Type.BBOX, name="Vehicle_bbox"),
    lb.Tool(tool=lb.Tool.Type.BBOX, name="Person_bbox"),
    lb.Tool(tool=lb.Tool.Type.RASTER_SEGMENTATION, name="Vehicle_mask"),
    lb.Tool(tool=lb.Tool.Type.RASTER_SEGMENTATION, name="Person_mask"),
    lb.Tool(tool=lb.Tool.Type.POLYGON, name="Vehicle_polygon"),
    lb.Tool(tool=lb.Tool.Type.POLYGON, name="Person_polygon"),
])

ontology = client.create_ontology(
    name="YOLOv8 Demo Ontology",
    normalized=ontology_builder.asdict(),
    media_type=lb.MediaType.Image,
)

  7. Create a Model Experiment

    develop

    A Model Experiment requires an Ontology. You can build an ontology using OntologyBuilder and then create a model associated with that ontology's UID.

    1. Define features (e.g., Classification).
    2. Use OntologyBuilder to assemble the features.
    3. Call client.create_ontology.
    4. Call client.create_model using the ontology_id.
    import labelbox as lb
import uuid

# 1. Define Ontology
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=[], classifications=classification_features)

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

# 2. Create Model
model = client.create_model(
    name=f"Model Slice Demo {str(uuid.uuid4())}",
    ontology_id=ontology.uid
)

  9. Export data rows from a project for model inference

    develop

    Use project.export() to retrieve the data rows. You can use a callback function with get_buffered_stream().start(stream_handler=...) to process each row (e.g., to collect URLs and global keys for your model).

    export_task = project.export()
export_task.wait_till_done()

url_list = []
global_keys = []

def export_callback(output: lb.BufferedJsonConverterOutput):
    data_row = output.json
    url_list.append(data_row["data_row"]["row_data"])
    global_keys.append(data_row["data_row"]["global_key"])

if export_task.has_result():
    export_task.get_buffered_stream().start(stream_handler=export_callback)

  10. Verify SLSA Level 3 Provenance for Labelbox SDK

    develop

    Labelbox SDK releases (v.3.72.2+) include SLSA Level 3 Provenance documents to ensure software supply chain security. You can verify that a downloaded wheel is authentic using the slsa-verifier.

    Example verification steps for version 3.72.2:

    export VERSION=3.72.2 # sdk release version 
export TAG=v.3.72.2 # github tag
pip download --no-deps labelbox==${VERSION}

curl --location -O \
  https://github.com/Labelbox/labelbox-python/releases/download/${TAG}/multiple.intoto.jsonl

slsa-verifier verify-artifact --source-branch develop --builder-id 'https://github.com/slsa-framework/slsa-github-generator/.github/workflows/generator_generic_slsa3.yml@refs/tags/v2.0.0' --source-uri "git+https://github.com/Labelbox/labelbox-python" --provenance-path multiple.intoto.jsonl ./labelbox-${VERSION}-py3-none-any.whl

  11. Set up a Labelbox Project with an Ontology

    develop

    To prepare a project for labeling, create the project, add a batch using global_keys from your data rows, and attach the ontology using setup_editor.

    project = client.create_project(name="YOLOv8 Demo Project", media_type=lb.MediaType.Image)

# Add the data rows to a batch
project.create_batch(name="batch 1", global_keys=[global_key])

# Attach the ontology to the project editor
project.setup_editor(ontology)

  12. Import PDF data rows into the Catalog

    develop

    To import PDF documents into a Labelbox dataset, use dataset.create_data_rows().

    Important Notes on Automatic OCR: Labelbox automatically generates a text layer using Google Document AI. This has specific constraints:

    • Maximum 15 pages per document.
    • Maximum 20 MB file size.
    • Coordinate Discrepancies: Google Document AI may rotate or optimize images (e.g., rotating landscape pages 90 degrees) before OCR. This means token coordinates in the generated text layer might differ from the original PDF coordinates.

    If you have your own text layer, you can pass a text_layer_url to bypass automatic generation.

    import uuid
import labelbox as lb

# Define your data row
global_key = "0801.3483.pdf" + str(uuid.uuid4())
img_url = {
    "row_data": {
        "pdf_url": "https://storage.googleapis.com/labelbox-datasets/arxiv-pdf/data/99-word-token-pdfs/0801.3483.pdf"
    },
    "global_key": global_key,
}

# Create dataset and import rows
dataset = client.create_dataset(name="pdf_demo_dataset")
task = dataset.create_data_rows([img_url])
task.wait_till_done()