Hanging protocol

With the hanging protocol, you can define views, identified by a viewport. You find the hanging protocols here.

Each view describes the size and position of the view and some of the options for that view. For instance, you can define a view with two equally sized viewports, either horizontally or vertically, or a large viewport that can be made full-size with a smaller viewport that will be shown in the top right corner:

The hanging protocol is defined as a JSON object that contains a list of objects for each viewport. Each viewport can have the following fields:

  • viewport_name (Required): Identifier of the viewport. This must follow the naming scheme "main", "secondary", "tertiary", etc. for each viewport.

General settings:

  • x (Optional): Horizontal position of the viewport.
  • y (Optional): Vertical position of the viewport.
  • w (Optional): Width of the viewport.
  • h (Optional): Height of the viewport.
  • opacity (Optional): Value between 0 and 1 to indicate the opacity of the viewport.
  • order (Optional): Number that indicates the order of the viewports. The lowest value will be the most in the foreground.
  • orientation (Required when using specialized_view "3D-sideview", otherwise optional): Initial orientation of the viewport, if not specified the default orientation from the viewer configuration will be used. Options are "'axial'", "'coronal'" , or "'sagittal'".
  • relative_start_position (Optional): The relative start position within a 3D volume along the viewing axis selected with orientation. A value of 0.0 means the first slice and 1.0 the last slice. 0.5 is the default if not specified and starts a view at the center of a volume.

Display information settings:

  • label (Optional): Label that is shown in the top-right of the viewport.
  • slice_plane_indicator (Optional): viewport_name of another viewport in the definition. This will show the plane indicator in the current viewport indicating the shown slice of the other viewport, based on the world coordinates.
  • slice_plane_indicator_fade_ms (Optional): Fine-tuning the fade for the visibility of the slice-plane indicator (set to 0 to disable the fade completely).
  • show_current_slice (Optional, default: True): Set visibility of current slice. (Red box, see below)
  • show_mouse_coordinate (Optional, default: True) : Set visibility of coordinates of mouse cursor. (Green box, see below)
  • show_mouse_voxel_value (Optional, default: True): Set visibility of the value of the voxel under the mouse cursor. (Blue box, see below)

Allowed interactions:

  • fullsizable (Optional, default: True): Adds a fullscreen toggle button to the viewport.
  • draggable (Optional, default: False): Allows the user to drag the viewport to change its position.
  • selectable (Optional, default: True): Makes the viewport selectable.
  • linkable (Optional, default: True): Makes the viewport be part of linked interactions.

Additional settings:

  • specialized_view (Optional): makes the viewport act in a specific way. Options are "3D-sideview", "minimap", "clientside", or "intensity-over-time-chart". See below for details.
  • parent_id (Optional): viewport_name of another viewport in the definition. This is used when draggable=True to limit moving of the draggable viewport inside the parent viewport, or in combination with the specialized_views "3D-sideview" and "minimap".

The x, y, w and h fields are required to be set on all viewitems or on none of them. They must contain a number that indicates the position and size of the viewports. The numbers are relative, so for example a layout with 2 viewports with x: 0, y: 0, w: 5, h:5 and x: 2, y: 2, w: 1, h:1 will contain one large viewport that spans the entire layout and a small viewport on top of it that is exactly in the center. If the values are not set, each viewport will be placed on a single row with equal width. During editing of the JSON a preview of the hanging protocol layout is shown.

The hanging protocol can be chosen in the settings of an archive, algorithm or reader study. This will make it load the hanging protocol when viewing an archive item (loaded by going to Archive -> View Items -> Open Archive Item in Viewer), algorithm job (Algorithm -> Results -> Open Result in Viewer) or reader study (Reader Study -> Launch this Reader Study).

At most 20 viewports can be defined.

Specialized Views

It is possible to configure a specialized view to have the particular viewport act in a certain way. These are the current options:

3D-sideview

The specialized view '3D-sideview' gives a side view in a specific orientation and shows plane indicators indicating the major axes. The required additional fields are parent_id and orientation.

A minimum example would be:

[
  {
    "viewport_name": "main"
  },
  {
    "viewport_name": "secondary",
    "specialized_view": "3D-sideview",
    "parent_id": "main",
    "orientation": "axial"
  },
  {
    "viewport_name": "tertiary",
    "specialized_view": "3D-sideview",
    "parent_id": "main",
    "orientation": "sagittal"
  },
  {
    "viewport_name": "quaternary",
    "specialized_view": "3D-sideview",
    "parent_id": "main",
    "orientation": "coronal"
  } 
]
Minimaps

The specialized view 'minimap' provides a birds-eye view of the parent viewport and is a click-navigable map. The required additional field is parent_id.

A minimum example would be:

[
  {
    "viewport_name": "main"
  },
  {
     "viewport_name": "secondary",
     "specialized_view": "minimap",
     "parent_id": "main"
  }
]
Clientside

The specialized view 'clientside' creates a client-side rendered view item. It is currently an experimental feature that only works for pathology images. It will render the pathology image on the client allowing for a more responsive experience. It currently only supports simple tool interactions like zoom and pan and supports linked viewitems. Basic support for polygon annotations and overlays has been implemented.

An example for 2 images side by side would be:

[
  {
    "h": 10,
    "w": 10,
    "x": 0,
    "y": 0,
    "order": 0,
    "viewport_name": "main",
    "specialized_view": "clientside"
  },
  {
    "h": 10,
    "w": 10,
    "x": 10,
    "y": 0,
    "order": 0,
    "viewport_name": "secondary",
    "specialized_view": "clientside"
  }
]
Intensity-over-time chart

The specialized view 'intensity-over-time-chart' creates a client-side rendered chart that plots how the relative intensity changes over time in a region. The user can select the region of interest in the 'parent_id' over time and the plot will update with the means of all voxels found in that region.

A minimum example would be:

[
  {
    "viewport_name": "main"
  },
  {
     "viewport_name": "secondary",
     "specialized_view": "intensity-over-time-chart",
     "parent_id": "main"
  }
]
Previous section
Next section