Define a layout

A layout describes how images are presented in the viewer and can be defined for reader studies, algorithms, and archives. The layout is configured by two settings, the hanging protocol, and the view content.

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.

Placement 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'".

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" or "clientside". 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. Advanced features like overlays and annotations are not yet supported.

View content¶

With the view content, you describe which image (defined by its interface-slug) will be linked to which viewport from the hanging protocol. If you selected a hanging protocol that contains viewports "main" and "secondary", the view content will need to have these same viewports defined. For example, if you want to use the main viewport to display frontal x-rays and the secondary viewport to display lateral x-rays, you'd define your view content as:

{
    "main": ["frontal-x-ray"],
    "secondary": ["lateral-x-ray"]
}

If you want to add an overlay to a viewport, simply add it to the list of items for that viewport. E.g.:

{
    "main": ["frontal-x-ray", "frontal-overlay"],
    "secondary": ["lateral-x-ray"]
}

Neither hanging protocol nor view content is required to have a valid layout. These are the options:

• No view content, no hanging protocol. In this case, the viewer will use a default hanging protocol with a single view. The first image will be shown, optionally with an overlay if one is present. This means 3D images will get side views if there are fewer than 4 images per set. Multiresolution images will be loaded with a minimap overview if there are fewer than 3 images per set.

• No view content, but hanging protocol configured. Again, the viewer will use a single view but uses the chosen hanging protocol. The first image will be shown, optionally with an overlay if one is present. All viewports other than the main will be ignored. In the current version, it is not possible to configure the side views for 3D images or the overview for multi-resolution images.

• View content configured, no hanging protocol. The viewer will show the images as defined in the view content but will use the default hanging protocol. This means 3D images will get side views if there are fewer than 4 images per set. Multiresolution images will be loaded with a minimap overview if there are fewer than 3 images per set. The images will be loaded in a layout that will show all images at the same size.

• Both view content and hanging protocol configured. The viewer will show the images as configured in the view content and hanging protocol. In the current version, it is not possible to configure the side views for 3D images or the overview for multi-resolution images.