ClientMetadata Layouts

Follow the end to end walkthrough below to learn how to set up a custom Label Editor configuration based on client metadata. This End-to-end example assumes you configure the Label Editor so that two files are displayed at a given time.

This end-to-end example assumes that your files are stored in cloud storage.

STEP 1: Create Metadata Schema

Use the Encord SDK to import a metadata schema into Encord. The fields encord-LayoutGroup and encord-EditorGridPosition are the key client metadata used later for configuring the Label Editor layout. If you need to add additional client metadata to your schema, include them in the script below.

Read more about metadata schemas here.

Metadata schema import example

# Import dependencies
from encord import EncordUserClient
from encord.metadata_schema import MetadataSchema

SSH_PATH = "/Users/chris-encord/ssh-private-key.txt"

# Authenticate with Encord using the path to your private key
user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
    ssh_private_key_path=SSH_PATH
)

# Create the schema
metadata_schema = user_client.metadata_schema()

# Add display parameters for data appearing in custom editor layouts
metadata_schema.add_scalar("encord-LayoutGroup", data_type="varchar")
metadata_schema.add_scalar("encord-EditorGridPosition", data_type="varchar")

STEP 2: Create JSON file for Data Registration

Before registering your cloud data to Encord you must first create a JSON file specifying the files you want to register.

When the audioMetadata, imageMetadata, or videoMetadata flags are present in the JSON file, we directly use the supplied metadata without performing any additional validation, and do not store the file on our servers. It is crucial that the metadata you provide is accurate. For most applications these flags can be omitted.

All of the following examples import 4 objects with the following client metadata:

• encord-EditorGridPosition: Can take the values A or B. A and B are the two possible positions inside the Label Editor.
• encord-LayoutGroup: Files with the same encord-LayoutGroup values are displayed concurrently in the Label Editor

Images

{
  "images": [
    {
      "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/image_file_001.jpg",
      "title": "my-custom-image-file-001.jpg",
      "imageMetadata": {
        "mimeType": "image/jpg",
        "fileSize": 124,
        "width": 640,
        "height": 480
      },
      "clientMetadata": {"encord-EditorGridPosition": "A", "encord-LayoutGroup": "1"}
    },
    {
      "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/image_file_002.jpg",
      "title": "my-custom-image-file-002.jpg",
      "imageMetadata": {
        "mimeType": "image/jpg",
        "fileSize": 124,
        "width": 640,
        "height": 480
      },
      "clientMetadata": {"encord-EditorGridPosition": "B", "encord-LayoutGroup": "1"}
    },
    {
      "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/image_file_003.jpg",
      "title": "my-custom-image-file-003.jpg",
      "imageMetadata": {
        "mimeType": "image/jpg",
        "fileSize": 124,
        "width": 640,
        "height": 480
      },
      "clientMetadata": {"encord-EditorGridPosition": "A", "encord-LayoutGroup": "2"}
    },
    {
      "objectUrl": "https://encord-integration.s3.eu-west-2.amazonaws.com/images/image_file_004.jpg",
      "title": "my-custom-image-file-004.jpg",
      "imageMetadata": {
        "mimeType": "image/jpg",
        "fileSize": 124,
        "width": 640,
        "height": 480
      },
      "clientMetadata": {"encord-EditorGridPosition": "B", "encord-LayoutGroup": "2"}
    }
  ],
  "skip_duplicate_urls": true
}

---

STEP 3: Register or Import Files to Encord

Create a Folder

All files in Encord must be stored within folders. Therefore, you need to create a folder before registering any data with Encord. To create a folder:

1. Navigate to Files under the Index heading in the Encord platform.
2. Click the + New folder button to create a new folder. A dialog to create a new folder appears.

3. Give the folder a meaningful name and description.

4. Click Create to create the folder. The folder is listed in Files.

---

Import / Register Your Files

Using the JSON file you created you can import or register your audio data, using the UI or the SDK.

Import data using in the UI

To ensure smoother uploads and faster completion times, and avoid hitting absolute file limits, we recommend adding smaller batches of data. Limit uploads to 100 videos or up to 1,000 images at a time. You can also create multiple Datasets, all of which can be linked to a single Project. Familiarize yourself with our limits and best practices for data import/registration before adding data to Encord.

1. Navigate to Files section of Index in the Encord platform.
2. Click into a Folder.
3. Click + Upload files. A dialog appears.

4. Click Import from cloud data.

We recommend turning on the Ignore individual file errors feature. This ensures that individual file errors do not lead to the whole upload process being aborted.

6. Click Add JSON or CSV files to add a JSON or CSV file specifying cloud data that is to be added.

Register data using in the SDK

To use your data in Encord, it must be uploaded to the Encord Files storage. Once uploaded, your data can be reused across multiple Projects and contain no labels or annotations themselves. Files stores your data, while Projects store your labels. The following script creates a folder in Files and uses your AWS integration to register data in that folder.

The following script creates a new folder in Files and initiates uploads from AWS. It works for all file types.

If Upload is still in progress, try again later! is returned, use the script to check the upload status to see whether the upload has finished.

Ensure that you:

• Replace <private_key_path> with the path to your private key.
• Replace <integration_title> with the title of the integration you want to use.
• Replace <folder_name> with the folder name. The scripts assume that the specified folder name is unique.
• Replace path/to/json/file.json with the path to a JSON file specifying which cloud storage files should be uploaded.
• Replace A folder to store my files with a meaningful description for your folder.
• Replace "my": "folder_metadata" with any metadata you want to add to the folder.

The script has several possible outputs:

• “Upload is still in progress, try again later!”: The registration has not finished. Run this script again later to check if the data registration has finished.
• “Upload completed”: The registration completed. If any files failed to upload, the URLs are listed.
• “Upload failed”: The entire registration failed, and not just individual files. Ensure your JSON file is formatted correctly.

Create folder and register cloud data

# Import dependencies
from encord import EncordUserClient
from encord.orm.dataset import LongPollingStatus  # Ensure correct import path

# Instantiate user client. Replace <private_key_path> with the path to your private key
user_client = EncordUserClient.create_with_ssh_private_key(
    ssh_private_key_path="<private_key_path>"
)

# Specify the integration you want to use
integrations = user_client.get_cloud_integrations()
integration_idx = [i.title for i in integrations].index("<integration_title>")
integration = integrations[integration_idx].id

# Create a storage folder
folder_name = "<folder_name>"
folder_description = "A folder to store my files"
folder_metadata = {"my": "folder_metadata"}
storage_folder = user_client.create_storage_folder(
    folder_name, folder_description, client_metadata=folder_metadata
)

# Initiate cloud data registration
upload_job_id = storage_folder.add_private_data_to_folder_start(
    integration_id=integration, private_files="path/to/json/file.json", ignore_errors=True
)

# Check upload status
res = storage_folder.add_private_data_to_folder_get_result(upload_job_id, timeout_seconds=5)
print(f"Execution result: {res}")

if res.status == LongPollingStatus.PENDING:
    print("Upload is still in progress, try again later!")
elif res.status == LongPollingStatus.DONE:
    print("Upload completed")
    if res.unit_errors:
        print("The following URLs failed to upload:")
        for e in res.unit_errors:
            print(e.object_urls)
else:
    print(f"Upload failed: {res.errors}")

---

STEP 4: Set up your Project

1. Create a Dataset

   1. Click the New dataset button in the Datasets section in Annotate.

   

   2. Give your Dataset a meaningful title and description. A clear title and description keeps your data organized.

   Toggle Looking to create a mirrored dataset? to create a Mirrored Dataset.

   

   3. Click Create dataset to create the Dataset.

   Attach files

   You can add data to Datasets from the Files or the Datasets screens.

   To ensure smoother uploads and faster completion times, and avoid hitting absolute file limits, we recommend adding smaller batches of data. Limit uploads to 100 videos or up to 1,000 images at a time. You can also create multiple Datasets, all of which can be linked to a single Project. Familiarize yourself with our limits and best practices for data import/registration before adding data to Encord.

   1. Navigate to the Datasets section under the Annotate heading.
   2. Click the Dataset you want to attach data to.
   3. Click +Attach existing files.

   If the files you want have not been uploaded into Encord yet, click +Upload files to upload new files.

   

   4. Select the folders containing the files you want to attach to the Dataset. To select individual files, double-click a folder to see its contents, and select the files you want to add to the Dataset.

   5. Click Attach data to attach the selected files to the Dataset.

2. Create an Ontology

   We recommend learning about Ontology structure in Encord before creating Ontologies.

   1. Click the New ontology button in the Ontologies section to create a new Ontology.

   

   2. Give your Ontology a meaningful title and description. A clear title and description keeps your Ontologies organized.

   3. Click Next to continue.

   

   4. Define your Ontology structure. See our documentation on Ontology structure for more information on the various types of objects, classifications, and attributes.

   To add objects:

   Ensure that you add Audio Region objects for audio files and Text Region objects for text files.

   

   1. Click Add object to create a new object.
   2. Give the object a name. For example “Apple”.
   3. Select a shape for the object. For example polygon.
   4. Optionally, enable the Required toggle to mark the object as Required.
   5. Optionally, add attributes to the object.
   6. Repeat these steps for as many objects as necessary.

   To add attributes to an object:

   You can add attributes to objects that define the object’s characteristics. For example the object “Apple” can have an attribute “Color”.

   

   1. Click the arrow icon next to an object to add attributes to the object.

   2. Give the attribute a name. For example “Color”.

   3. Click the attribute type to change the attribute type. The default attribute type is a text field.

   4. Click Add option to add an option, if you have chosen a radio button or checklist attribute.

   5. Enter a name for the attribute option. For example, the attribute “Color” can have the options “Red”, “Green”, and “Yellow”.

   6. Click the Back to parent button to return the Ontology creation view.

   To add a classification:

   

   1. Click Add classification to create a new classification.
   2. Give the classification a name. For example, “Time of day”.
   3. Optionally, configure the classification. The default classification type is a text field.
   4. Optionally, enable the Required toggle to mark the object as Required.
   5. Repeat these steps for as many classifications as necessary.

   Configure classifications:

   You can configure classifications to change the classification type, and to add classification options to radio buttons and check lists.

   

   1. Click the arrow icon next to an object to configure the classification.

   

   2. Click the classification type to change the classification type. The default classification type is a text field.
   3. Click Add option to add an option if you have selected a radio button or check list classification.
   4. Enter a name for the classification option. For example, the classification “Time of day” can have the options “Night” and “Day”.
   5. Click the Back to parent button to return the Ontology creation view.
3. Create a Project

   1. In the Encord platform, select Projects under Annotate.
   2. Click the + New annotation project button to create a new Project.

   

   3. Give the Project a meaningful title and description.

   

   If you are part of an Organization, an optional Project tags drop-down is visible. Project tags are useful for categorizing and finding your Projects. Select as many tags as are relevant for your Project.

   4. Click the Attach ontology button.

   5. Select the Ontology you created previously from the list using the Select button.

   

   6. Click OK to attach the Ontology to the Project.

   7. Click the Attach datasets button.

   8. Select the Dataset you created previously from the list using the Attach button.

   

   9. Click OK to attach the Dataset(s) to the Project.

   

   10. Click the Load from template button to use a Workflow template.

   

   11. Select the template you want to use and click Load template.

   12. Click Create project to finish creating the Project.

   

   We recommend learning about Ontology structure in Encord before creating Ontologies.

   1. Click the New ontology button in the Ontologies section to create a new Ontology.

   

   2. Give your Ontology a meaningful title and description. A clear title and description keeps your Ontologies organized.

   3. Click Next to continue.

   

   4. Define your Ontology structure. See our documentation on Ontology structure for more information on the various types of objects, classifications, and attributes.

   To add objects:

   Ensure that you add Audio Region objects for audio files and Text Region objects for text files.

   

   1. Click Add object to create a new object.
   2. Give the object a name. For example “Apple”.
   3. Select a shape for the object. For example polygon.
   4. Optionally, enable the Required toggle to mark the object as Required.
   5. Optionally, add attributes to the object.
   6. Repeat these steps for as many objects as necessary.

   To add attributes to an object:

   You can add attributes to objects that define the object’s characteristics. For example the object “Apple” can have an attribute “Color”.

   

   1. Click the arrow icon next to an object to add attributes to the object.

   2. Give the attribute a name. For example “Color”.

   3. Click the attribute type to change the attribute type. The default attribute type is a text field.

   4. Click Add option to add an option, if you have chosen a radio button or checklist attribute.

   5. Enter a name for the attribute option. For example, the attribute “Color” can have the options “Red”, “Green”, and “Yellow”.

   6. Click the Back to parent button to return the Ontology creation view.

   To add a classification:

   

   1. Click Add classification to create a new classification.
   2. Give the classification a name. For example, “Time of day”.
   3. Optionally, configure the classification. The default classification type is a text field.
   4. Optionally, enable the Required toggle to mark the object as Required.
   5. Repeat these steps for as many classifications as necessary.

   Configure classifications:

   You can configure classifications to change the classification type, and to add classification options to radio buttons and check lists.

   

   1. Click the arrow icon next to an object to configure the classification.

   

   2. Click the classification type to change the classification type. The default classification type is a text field.
   3. Click Add option to add an option if you have selected a radio button or check list classification.
   4. Enter a name for the classification option. For example, the classification “Time of day” can have the options “Night” and “Day”.
   5. Click the Back to parent button to return the Ontology creation view.

---

STEP 5: Create Custom Editor Layout

After creating your Project, import a custom layout for the Label Editor. Start by creating a JSON file that determines the layout.

Create a JSON for the Layout

Common layouts for two tasks displayed simultaneously are Side by Side and Stacked (On top of one another).

Side by Side Layout

{
  "grid": [
    [0, 1],
  ],
  "gridContent": {
    "0": {
      "client_metadata_query": {
        "or_conditions": [
          {
            "key": "encord-EditorGridPosition",
            "operator": "=",
            "value": "A"
          },
          {
            "key": "encord-EditorGridPosition",
            "operator": "=",
            "value": "B"
          }
        ]
      }
    },
    "1": {
      "client_metadata_query": {
        "or_conditions": [
          {
            "key": "encord-EditorGridPosition",
            "operator": "=",
            "value": "A"
          },
          {
            "key": "encord-EditorGridPosition",
            "operator": "=",
            "value": "B"
          }
        ]
      }
    }
  },
  "topLevelGridFilter": {
    "client_metadata": {
      "key": "encord-LayoutGroup",
      "operator": "="
    }
  },
  "$schema": "https://raw.githubusercontent.com/encord-team/Annotate/main/editor-layouts/editor_layout_schema.json"
}

Import the custom layout

1. Navigate to the Project settings.
2. Click on Editor Layouts.
3. Click Upload JSON.
4. Select the JSON file containing the layout you want the Label Editor to have.

What do the Layouts Look Like?

The Side By Side layout:

The Stacked layout: