Labelbox

labeling-api.js API Reference

The Labelbox Javascript library API reference.

Creating Custom Interfaces

You can create custom labeling interfaces to suit the needs of your labeling tasks. All of the pre-made labeling interfaces are open source.

A minimal example

<script src="https://api.labelbox.com/static/labeling-api.js"></script>
<div id="form"></div>
<script>
function label(label){
  Labelbox.setLabelForAsset(label).then(() => {
    Labelbox.fetchNextAssetToLabel();
  });
}

Labelbox.currentAsset().subscribe((asset) => {
  if (asset){
    drawItem(asset.data);
  }
})
function drawItem(dataToLabel){
  const labelForm = `
    <img src="${dataToLabel}" style="width: 300px;"></img>
    <div style="display: flex;">
      <button onclick="label('bad')">Bad Quality</button>
      <button onclick="label('good')">Good Quality</button>
    </div>
  `;
  document.querySelector('#form').innerHTML = labelForm;
}

</script>

Labelbox Pluggable Interface Architecture

Labelbox allows the use of custom labeling interfaces. Custom labeling interfaces minimally define a labeling ontology and optionally the look and feel of the labeling interface. A minimal labeling interface imports labeling-api.js and uses the fetch and submit functions to integrate with Labelbox. While Labelbox makes it simple to do basic labeling of images and text, there are a variety of other data types such as point clouds, maps, videos or medical DICOM imagery that require bespoke labeling interfaces. With this in mind, Labelbox is designed to facilitate the creation, installation, and maintenance of custom labeling frontends.

Using labeling-api.js

To develop a Labelbox frontend, import labeling-api.js and use the 2 APIs described below to fetch the next data and then submit the label against the data. Note that multiple data can be loaded in a single fetch if a row in the CSV file contains an array of data pointers.

Attach the Labelbox Client Side API

<script src="https://api.labelbox.com/static/labeling-api.js"></script>

Get a row to label

Labelbox.fetchNextAssetToLabel().then((dataToLabel) => {
  // ... draw to screen for user to view and label
});

Save the label for a row

Labelbox.setLabelForAsset(label); // labels the asset currently on the screen

Hello World Example

Try it in your browser
(The project must be setup first)

Full Example

<script src="https://api.labelbox.com/static/labeling-api.js"></script>
<div id="form"></div>
<script>
function label(label){
  Labelbox.setLabelForAsset(label).then(() => {
    Labelbox.fetchNextAssetToLabel();
  });
}

Labelbox.currentAsset().subscribe((asset) => {
  if (asset){
    drawItem(asset.data);
  }
})
function drawItem(dataToLabel){
  const labelForm = `
    <img src="${dataToLabel}" style="width: 300px;"></img>
    <div style="display: flex;">
      <button onclick="label('bad')">Bad Quality</button>
      <button onclick="label('good')">Good Quality</button>
    </div>
  `;
  document.querySelector('#form').innerHTML = labelForm;
}

</script>

Labelbox.currentAsset

Overview:

This function returns a stream of information about the currently viewed asset on the screen. Its important to have all your drawing logic behind this function so that Labelbox can tell your frontend about which asset to render.

For example, if the user opened your interface form an existing label this function would recieve the data about that asset but also its label information.

Example:

const subscription = Labelbox.currentAsset().subscribe((asset) => {
  // Asset can be undefined
  if (!asset){
    return;
  }

  console.log(asset.id); // The labelbox id for this asset
  console.log(asset.data); // This is whatever data you imported into labelbox (E.X. your image url)
  console.log(asset.label); // Undefined if the asset hasn't been labeled or whatever label you've submitted
  console.log(asset.previous); // The previous assetId in the queue (see setLabelAsCurrentAsset)
  console.log(asset.next); // The next assetId in the queu (see setLabelAsCurrentAsset)
  console.log(asset.createdAt); // Datetime for when this asset was created
  console.log(asset.createdBy); // Email for who created the label
  console.log(asset.typeName); // Labelbox has Label Schemas to improve reporting. This can either be Any or Skip at the moment
})

// If you want to stop recieving updates.
// However, I would recommend having a single subscription for your entire application.
subscription.unsubscribe();

Using predictions

If Predictions exist for an asset, then they can be used to provide an initial starting point for labelling. The asset.labelTemplates field provides an array of all the Predictions which are available for the current asset, and the asset.labelTemplateId field provides the ID of the Prediction which was created by the project's currently active prediction model (more details here).

Each entry of asset.labelTemplates has an id attribute which can be matched against asset.labelTemplateId to determine the correct prediction to show. Also, the asset.label field contains the data which the labeling interface should use as a starting point for initializing the label.
The exact schema of this data is dependent upon the labeling interface in use; for example, the Labelbox Image Labeling schema is described here. For a custom interface, you will need to ensure that the format of the labels submitted when creating predictions conform to the schema expected by the custom labeling interface.

Example:

const subscription = Labelbox.currentAsset().subscribe((asset) => {
  // Asset can be undefined
  if (!asset){
    return;
  }

  console.log(asset.labelTemplates); // A (nullable) array of the Predictions for this asset, if any exist
  console.log(asset.labelTemplateId); // A (nullable) string id of the Prediction created by the project's active prediction model, if it exists
    const labelTemplate = (asset.labelTemplates || []).find(
      (template) => template.id === asset.labelTemplateId
    ); // Gets the Prediction created by the Project's active prediction model
    console.log(labelTemplate.label); // The data to use for initializing the label
})

// If you want to stop recieving updates.
// However, I would recommend having a single subscription for your entire application.
subscription.unsubscribe();

Labelbox.enablePreloading

Overview:

Labelbox automatically preloads a labeling queue. However, you can improve the loading speed of labels by giving Labelbox a function to run on each preloaded asset. The preloading function must return a promise.

In the example below we preload images in the dom before the user sees the asset so that it will be cached by the time the user reaches that asset.

Example:

const preloadFunction = (asset: Asset) => {
  const loadImageInDom = (url: string) => {
    return new Promise((resolve) => {
      const img = document.createElement('img');
      img.src = url;
      img.onload = () => {
        img.remove();
        resolve();
      };
      img.style.display = 'none',
      img.style.width = '0px',
      img.style.height = '0px',
      document.body.appendChild(img);
    });
  }
  return loadImageInDom(asset.data);
}

Labelbox.enablePreloading({preloadFunction})

Labelbox.setLabelForAsset

Overview

This function takes a string (JSON.stringify(myJsonLabel)** and will return a promise for when the label has been saved.

Example

Labelbox.setLabelForAsset('good').then(() => console.log('Success!'));

Labelbox.fetchNextAsset

Overview

This function will set the currentAsset to be the next unlabeled asset. For example after submitting a label if you want to advance to the next unlabeled asset you can run this method and then Labelbox.currentAsset(** will emit the new asset as soon as its fetched.

Example

function label(label){
  Labelbox.setLabelForAsset(label).then(() => {
    Labelbox.fetchNextAssetToLabel();
  });
}

Labelbox.setLabelAsCurrentAsset

Overview

Labelbox will automatically emit currentAssets when a user performs some action, such as jumping through the review screen. However, if you would like to add a button to go back to a previous asset you can use this method.

Example

function goBack(){
  Labelbox.setLabelAsCurrentAsset(asset.previous)
}

Labelbox.skip

Overview

Labelbox.skip() is identical to setLabelForAsset('Skip', 'Skip'). The Label that will be seen in your export will be "Skip**

Example

Labelbox.skip().then(() => console.log('Skipped!'))

Labelbox.getTemplateCustomization

Overview

If you decide you want your template to be customizable you can use this method to recieve the customization. Customization always comes in as JSON, but may not be supported by your template. Make sure to add some error handeling here.

Example

// Your template is want customization JSON that looks like this...
{
  "instructions":"Label This",
  "tools": [{"name": "Tool one"}]
}

// You can use this function like so...

Labelbox.getTemplateCustomization().subscribe((customization) => {
  if (customization.instructions && customization.tools) {
     updateTemplateWithCustomization(customization);
  }
})

Its worth noting that this customization will also be provided everytime your template loads and not just when a user is configuring it.