DICOM Tag Layouts

Follow the end to end walkthrough below to learn how to set up a custom Label Editor configuration based on DICOM tags. 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 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. The following JSON file registers 3 DICOM series consisting of 4 files each.

DICOM

{
  "dicom_series": [
    {
      "title": "Patient-1",
      "objectUrl_0": "https://encord-integration.s3.eu-west-2.amazonaws.com/dicom/mammo-file0.dcm",
      "objectUrl_1": "https://encord-integration.s3.eu-west-2.amazonaws.com/dicom/mammo-file1.dcm",
      "objectUrl_2": "https://encord-integration.s3.eu-west-2.amazonaws.com/dicom/mammo-file2.dcm",
      "objectUrl_3": "https://encord-integration.s3.eu-west-2.amazonaws.com/dicom/mammo-file3.dcm",
    },
    {
      "title": "Patient-2",
      "objectUrl_0": "https://encord-integration.s3.eu-west-2.amazonaws.com/dicom/mammo-file4.dcm",
      "objectUrl_1": "https://encord-integration.s3.eu-west-2.amazonaws.com/dicom/mammo-file5.dcm",
      "objectUrl_2": "https://encord-integration.s3.eu-west-2.amazonaws.com/dicom/mammo-file6.dcm",
      "objectUrl_3": "https://encord-integration.s3.eu-west-2.amazonaws.com/dicom/mammo-file7.dcm",
    },
      {
      "title": "Patient-3",
      "objectUrl_0": "https://encord-integration.s3.eu-west-2.amazonaws.com/dicom/mammo-file8.dcm",
      "objectUrl_1": "https://encord-integration.s3.eu-west-2.amazonaws.com/dicom/mammo-file9.dcm",
      "objectUrl_2": "https://encord-integration.s3.eu-west-2.amazonaws.com/dicom/mammo-file10.dcm",
      "objectUrl_3": "https://encord-integration.s3.eu-west-2.amazonaws.com/dicom/mammo-file11.dcm",
    }
  ]
}

---

STEP 2: Register files with Encord

Create a Folder to Store Your Files

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.

---

Register Your Files

You can register your DICOM data using the JSON file you created, using the UI or the SDK.

Register data 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 3: Set up Your Project

1. Create a Dataset
2. Create an Ontology
3. Create a Project

---

STEP 4: 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 mammography files are a 2x2 grid, and 4x1 showing all files in a horizontal row.

A complete list of DICOM tags can be found here.

• 2x2 layout: https://raw.githubusercontent.com/encord-team/Annotate/refs/heads/main/editor-layouts/examples/mammo2x2.json
• 4x1 layout: https://raw.githubusercontent.com/encord-team/Annotate/refs/heads/main/editor-layouts/examples/mammo4x1.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?

2x2 Mammography Layout:

4x1 Mammography Layout: