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 viewport main that can be made full-size and a smaller view (secondary) that will be shown in the top right corner. See the existing protocols for examples of the most common hanging protocols.

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

  • viewport_name (Required): Identifier of the viewport. Currently this must follow this naming scheme "main", "secondary", "tertiary", etc respectively for each viewport.
  • label (Optional): Label that is shown in the top-right of the viewport.
  • 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.
  • fullsizable (Optional): Adds a fullscreen toggle button to the viewport.
  • draggable (Optional): Allows the user to drag the viewport to change its position.
  • 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.
  • opacity (Optional): Value between 0 and 1 to indicate the opacity of the viewport.
  • selectable (Optional): Makes the viewport selectable.
  • order (Optional): Number that indicates the order of the viewports. The lowest value will be the most in the foreground.
  • show_current_slice (Optional): Toggle visibility of current slice. (Red box, see below)
  • show_mouse_coordinate (Optional) : Toggle visibility of coordinates of mouse cursor. (Green box, see below)
  • show_mouse_voxel_value (Optional): Toggle visibility of the value of the voxel under the mouse cursor. (Blue box, see below)

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).

Some restrictions that are in the current version: - It is not possible to configure the side views for 3D images or the overview for multi-resolution images. - Pathology images are not yet supported. - At most 10 viewports can be defined

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 an 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 or view content are 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 less than 4 images per set. Multiresolution images will be loaded with a minimap overview if there are less 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 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 less than 4 images per set. Multiresolution images will be loaded with a minimap overview if there are less 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.