Documentation Index
Fetch the complete documentation index at: https://docs.labelbox.com/llms.txt
Use this file to discover all available pages before exploring further.
Open In Colab
GitHub
Overview
To import annotations in Labelbox, you need to create an annotations payload. In this section, we provide this payload for every supported annotation type.Annotation payload types
Labelbox supports two formats for the annotations payload:-
Python annotation types (recommended)
- Provides a seamless transition between third-party platforms, machine learning pipelines, and Labelbox.
- Allows you to build annotations locally with local file paths, numpy arrays, or URLs
- Easily convert Python Annotation Type format to NDJSON format to quickly import annotations to Labelbox
- Supports one-level nested classification (radio, checklist, or free-form text) under a tool or classification annotation.
-
JSON
- Skips formatting annotation payload in the Labelbox Python annotation type
- Supports any levels of nested classification (radio, checklist, or free-form text) under a tool or classification annotation.
Label import types
Labelbox additionally supports two types of label imports:- Model-assisted labeling (MAL)
- This workflow allows you to import computer-generated predictions (or simply annotations created outside of Labelbox) as pre-labels on an asset.
- Ground truth
- This workflow functionality allows you to bulk import your ground truth annotations from an external or third-party labeling system into Labelbox Annotate. Using the label import API to import external data is a useful way to consolidate and migrate all annotations into Labelbox as a single source of truth.
Supported annotations
The following annotations are supported for a document data row:- Radio
- Checklist
- Free-form text
- Bounding box
- Entity
- Relationship
Annotations are global and page based
Classification annotations are only supported globally while page-specific tool annotations are supported at a per page basis.Classifications
Radio (single-choice, global)
Checklist (multi-choice, global)
Free-form text (global)
Nested Classifications (global)
Tools
Bounding box (page specific)
When importing a bounding box annotation, you need to specify itsDocumentRectangle value, which defines its precise area on a document page. You can choose from the following RectangleUnit options, which determine the measurement unit used to define the dimensions and coordinates of the bounding box:
- INCHES
- PIXELS
- POINTS
- PERCENT
Entity (page specific)
textSelections is the payload required for each entity annotation. EachtextSelections item in the list requires the following fields:
- The
groupIdassociated with a group of words. - A list of
tokenIdsfor each word in the group of words. - The
pageof the document (1-indexed).
tokenIds and groupdId can extracted from the text layer URL attached to the data row. For more information on text layers, visit our import document data guide.
Tool with nested classifications (page specific)
Relationships (page specific)
Read-only relationships
Admins can mark relationships as read_only to prevent other roles from deleting them:Relationships between classifications and objects
Creating text entity annotation
For importing entity annotations, you can use your owntext_layer_url or a Labelbox-generated text_layer_url.
You can get the Labelbox-generated text_layer_url by exporting the data row. The below code snippet demonstrates this process by exporting from a data row.
Example: Import pre-labels or ground truths
The steps to import annotations as pre-labels (machine-assisted learning) are similar to those to import annotations as ground truth labels. However, they vary slightly, and we will describe the differences for each scenario.Before you start
The below imports are needed to use the code examples in this section.API_KEY with a valid API key to connect to the Labelbox client.
Step 1: Import data rows
Data rows must first be uploaded to Catalog to attach annotations. This example shows how to create a data row in Catalog by attaching it to a dataset .Step 2: Set up ontology
Your project ontology should support the tools and classifications required by your annotations. To ensure accurate schema feature mapping, the value used as thename parameter should match the value of the name field in your annotation.
For example, when we created an annotation above, we provided a nameannotation_name. Now, when we set up our ontology, we must ensure that the name of our bounding box tool is also anotations_name. The same alignment must hold true for the other tools and classifications we create in our ontology.
This example shows how to create an ontology containing all supported annotation types .
Step 3: Set Up a Labeling Project
Step 4: Send Data Rows to Project
Step 5: Create annotation payloads
For help understanding annotation payloads, see overview. To declare payloads, you can use Python annotation types (preferred) or NDJSON objects. These examples demonstrate each format and how to compose annotations into labels attached to data rows.Step 6: Import annotation payload
For prelabeled (model-assisted labeling) scenarios, pass your payload as the value of thepredictions parameter. For ground truths, pass the payload to the labels parameter.