(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:
- 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"]
]
}
- 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
. - 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 listkeys
in the payload of Register Uploading Items.
When doing so, thelayout.json
file has to contain the same DICOM keys instead of just filenames. For example, when one of the DICOMs ispath/to/s3/top_left.dcm
thelayout.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
andbottom_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.
Updated 10 months ago