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:

Navigate to Files under the Index heading in the Encord platform.
Click the + New folder button to create a new folder. Select the type of folder you want to create.

Give the folder a meaningful name and description.
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.

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.


# 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

Create a Dataset

Create an Ontology

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.

Import the custom layout

Navigate to the Project settings.
Click on Editor Layouts.
Click Upload JSON.
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:

Getting Started with Encord

Modalities

Features

Benchmark QA Workflow

DICOM Tag Layouts

STEP 1: Create JSON File for Data Registration