(Legacy) Create hanging protocols with DICOM Layouts

🚧

Try using the API

The following docs refer to how you can use hanging protocols by adding a formatted JSON file to every group of files you'll be importing. While this option is still supported, we've added a more flexible experience. You can use our API where you are able to explicitly name the slots within your hanging protocol. See our docs page on Slots for more information.

With a bit of preprocessing, it's now possible to import DICOM files into customisable hanging protocols in V7.

In this guide, we'll walk through the steps towards creating hanging protocols in V7, and the three different layout types that are available in the beta release of DICOM Layouts.

Create a hanging protocol

To start with an example, let's say we have the following DICOM files that relate to different sections to be displayed on screen simultaneously:

• top_left.dcm (contains 5 slices)
• top_right.dcm (contains 5 slices)
• bottom_left_1.dcm (contains 2 slices)
• bottom_left_2.dcm (contains 3 slices)
• bottom_right.dcm (contains 5 slices)

To enable V7 to display these 5 files together on screen in a 4-pane grid layout, we can follow the steps below:

1. Create a new JSON file and include the contents below, before naming the file layout.json.

{
  "name": "grid",
  "groups": [
    ["top_left.dcm"],
    ["top_right.dcm"],
    ["bottom_left_1.dcm", "bottom_left_2.dcm"],
    ["bottom_right.dcm"]
  ]
}

2. Select all 5 files DICOM files and the layout JSON on your local device. Compress them into a zip file, and change the file extension from .zip to .dcm.
3. Import the file to V7.

📘

Files hosted on external storage

When working with external storage, there's no need to download DICOM files and ZIP them. All DICOM files and layout.json can be registered by passing all relevant file keys as list keys in the payload of Register Uploading Items.
When doing so, the layout.json file has to contain the same DICOM keys instead of just filenames. For example, when one of the DICOMs is path/to/s3/top_left.dcm the layout.json has to refer to that file by quoting exactly the same path, e.g.:

{
  "name": "grid",
  "groups": [
    ["path/to/s3/top_left.dcm"],
    ["path/to/s3/top_right.dcm"],
    ["path/to/s3/bottom_left_1.dcm", "path/to/s3/bottom_left_2.dcm"],
    ["path/to/s3/bottom_right.dcm"]
  ]
}

The resulting file will be displayed in V7 as a four-pane grid with the component files in the following positions:

• The top left section will contain the slices from top_left.dcm
• The top right section will contain the slices from top_right.dcm
• The bottom left section will contain the slices from both bottom_left_1.dcm and bottom_left_2.dcm, one after the other.
• The bottom right section will contain the slices from bottom_right.dcm

🚧

Slot Names

Each pane within the hanging protocol will be assigned a slot. Using the UI, these slot names will be set automatically but can be named explicitly using the API.

Layout types

There are three supported layout types which can be added to the "name": section of the layout JSON they are:

• grid
• horizontal
• vertical

Grid

Using the grid layout will create a layout that contains multiple columns and rows. (as rows are added, the number of columns will increase. As this happens, screen real-estate becomes less available, so adding any more than 3 rows is likely to result in a tricky annotation experience).

The order in which groups (files or groups of files, referred to as groups in the layout JSON) are rendered is based on how they are added to the layout JSON. This is left to right, top to bottom. For example:

• 1-2 groups will be a single row with 2 columns.
• 3 or 4 groups will be two rows, with two columns: groups 1 and 2 in one row, followed by 3 and (optionally) 4 in the next.
• 5 or 6 groups will be 2 rows with 3 columns: groups 1,2,3, and 4 in the top 2 rows, followed by 5 and (optionally) 6 in the next.

{
  "name": "grid",
  "groups": [
    ["1.dcm"],
    ["2.dcm"],
    ["3_a.dcm", "3_b.dcm"],
    ["4.dcm"]
  ]
}

horizontal

Using the horizontal layout will create a layout with 1 row with as many columns as there are groups in the layout JSON

{
  "name": "horizontal",
  "groups": [
    ["1.dcm"],
    ["2.dcm"],
    ["3_a.dcm", "3_b.dcm"],
    ["4.dcm"]
  ]
}

vertical

Using the vertical layout will create a layout with 1 column with as many rows as there are groups in the layout JSON

{
  "name": "vertical",
  "groups": [
    ["1.dcm"],
    ["2.dcm"],
    ["3_a.dcm", "3_b.dcm"],
    ["4.dcm"]
  ]
}

🚧

Simple Layout

There is a simple layout option as well but this should not be used in hanging protocol. It is intended to denote single slotted items (a single image on screen) and should not be explicitly set.