API Reference

Slots

Introducing the concepts of slots in V7

Slots are a part of how we structure items of visual data. They allow us to render multiple files as one item on the image canvas. For example, if you create a hanging protocol layout, slots allow you to separate DICOM files into their different axial components, and display multiple views at once. Their location would be denoted by each view being assigned to different slots. You can see an example of a typical multi-slotted image below:

Example Slotted Image

In this case, each of the four parts of the hanging protocol above would be a separate slot.

Darwin JSON Example

{
  "dataset": "Example Dataset",
  "image": {
    "width": 500,
    "height": 375,
    "original_filename": "cat.jpg",
    "filename": "catjpg",
    "url": "http://darwin.v7labs/api/v2/teams/v7/files/8ca6b093-e209-464d-8e14-003955e12071/original",
    "thumbnail_url": "http://darwin.v7labs/api/v2/teams/v7/files/8ca6b093-e209-464d-8e14-003955e12071/thumbnail",
    "path": "/",
    "workview_url": "http://localhost:14000/teams/v7/items/01815d3b-9482-8734-ce8e-5e9db358a0b9/workview"
  },
  "annotations": [
    {
      "id": "d5079ea4-1231-419f-bb58-895c89f78cb0",
      "name": "cat",
      "slot_names": [
        "0"
      ],
      "tag": {}
    }
  ]
}

How to Assign a Slot
On upload, it is possible to assign a slot name. These can be any string but we recommend using numeric values to avoid any confusion.

Below is an example payload showing how to perform step 1 of the 4-step upload process using the data registration API:

import requests

url = "https://darwin.v7labs.com/api/v2/teams/example_team/items/register_upload"

payload = {
    "items": [
        {
            "path": "/",
            "slots": [
                {
                    "as_frames": False,
                    "file_name": "example_image.png",
                    "slot_name": "2"
                }
            ],
            "name": "example_item"
        }
    ],
    "dataset_slug": "example_dataset"
}
headers = {
    "Accept": "application/json",
    "Content-Type": "application/json",
    "Authorization": "ApiKey $API_KEY"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

📘

Automatic Assignment of Slots

If slots are not defined at upload then they will be automatically assigned.

Most users will only have a single slot for their items and will not have to worry about assigning them.

Hanging Protocols

Knowledge of slots will come in very handy if you are using hanging protocols. Below are some examples showing you how they can be used together.

Registering Hanging Protocol Layout using Slots

Here is an example of registering new data in a 2x2 by grid format:

import requests

url = "https://darwin.v7labs.com/api/v2/teams/example_team/items/register_upload"

payload = {
    "items": [
        {
            "path": "/",
            "slots": [
                {
                    "as_frames": False,
                    "file_name": "my_dicom_tl.dcm",
                    "slot_name": "top_left"
                },
                {
                    "as_frames": False,
                    "file_name": "my_dicom_tr.dcm",
                    "slot_name": "top_right"
                },
                {
                    "as_frames": False,
                    "file_name": "my_dicom_bl.dcm",
                    "slot_name": "bottom_left"
                },
                {
                    "as_frames": False,
                    "file_name": "my_dicom_br.dcm",
                    "slot_name": "bottom_right"
                },
                {
                    "as_frames": False,
                    "file_name": "my_dicom_br_2.dcm",
                    "slot_name": "bottom_right"
                }
            ],
            "name": "item_name"
        }
    ],
    "dataset_slug": "my-dataset"
}
headers = {
    "Accept": "application/json",
    "Content-Type": "application/json",
    "Authorization": "ApiKey $API_KEY"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

To complete the upload, you would then need to sign upload, upload your files and confirm upload. These are steps 2-4 in the upload visual annotations recipe.

📘

Merging DICOMS into a concatenated section of Hanging Protocols

To display two or more concatenated files in the same slot:

  • 1: Enter the files with the same slot_name. In the example above, this would be the case for the slot in the bottom right of the screen (my_dicom_br.dcm and my_dicom_br_2.dcm)
  • 2: Add "options": {"ignore_dicom_layout": True} to the root of the payload

Updating the Hanging Protocol Layout

Here is a simple Python script example that updates the layout that have a "new" status for all new images into a 2x2 grid:

import requests

url = "https://darwin.v7labs.com/api/v2/teams/example_team/items/layout"

payload = {
    "filters": {
        "dataset_ids": [$dataset_id],
        "statuses": ["new"]
    },
    "layout": {"slots": ["top_left", "top_right", "bottom_left", "bottom_right"],
    "type": "grid",
    "version": 1
    }
}
headers = {
    "Accept": "application/json",
    "Content-Type": "application/json",
    "Authorization": "ApiKey $API_KEY"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

There are three supported layout types which can be added to the "type":field they are:

  • grid
  • horizontal
  • vertical

🚧

Uploading multislotted items

Currently multi-slotted items should be uploaded to V7 programmatically. Although you can update layout, there will be no other visual changes in the UI.