Viewer Features

The DICOM Viewer provides a suite of professional medical imaging tools in the browser.

---

Viewer Interface

When a DICOM viewer loads, you’ll see:

• Viewport — the center area displaying the medical image
• Toolbar — buttons for pan, zoom, window/level, cine, and info
• Series selector — pills or dropdown for switching between series (if multi-series)
• Grid layout — side-by-side panes for comparing series (when enabled)

---

Core Tools

---

Multi-Series Features

---

Customization

You can customize viewer behavior by:

• Global defaults — set site-wide defaults in DICOM Viewer
• Per-viewer settings — override defaults in the Gutenberg block or shortcode
• Viewport presets — use shortcode/block attributes to pre-set zoom, pan, window/level, and series on page load

See Default Viewport for details on presets.

---

Tools

The DICOM viewer provides essential image analysis tools.

---

Pan

Move the image around the viewport.

• Click and drag the image to pan around
• Useful when zoomed in to see different areas
• Release to stop panning

---

Zoom

Magnify or shrink the image.

Using the toolbar buttons:

• Click + to zoom in (1.25x magnification per click)
• Click − to zoom out

Using scroll wheel:

• Scroll up to zoom in
• Scroll down to zoom out
• Requires cursor over the viewport

Zoom preset defaults:

You can pre-set a zoom level on page load using the default_zoom attribute:

[dicom_viewer id="123" default_zoom="2.0"]

A value of 1.0 = 100%, 2.0 = 200%, 0.5 = 50%, etc.

---

Window/Level

Adjust brightness and contrast to highlight different tissues.

Window/level is a DICOM concept for displaying different density ranges. Different tissues require different windows:

• Bone window — high contrast to see bone (narrow window)
• Soft tissue window — balanced view of organs and tissues
• Lung window — shows lung density variations

How to use:

1. Click the W/L button in the toolbar
2. Click and drag on the image:
   • Drag horizontally → adjust window width (contrast)
   • Drag vertically → adjust window center (brightness)
3. Release to apply

Tip: Start with slow, small movements. Window/level is sensitive, and large adjustments can quickly make the image unusable.

---

Reset

Restore the image to its default viewport.

Clicking the Reset button:

• Resets zoom to fit the entire image in the viewport
• Removes any pan offset
• Restores the default window/level settings

This is useful after exploring the image to quickly return to the overview.

---

Hiding Controls

Site owners can now show or hide the main front-end controls globally or per viewer:

• Pan
• Zoom
• W/L
• Next / Prev buttons
• Slice slider

This is useful if you want a simpler viewer UI on public pages while keeping more advanced controls available in other embeds.

---

Cine Playback

Cine playback automatically cycles through slices in a series, creating an animation-like effect.

---

What Is Cine Playback?

In medical imaging, a series often contains many slices (e.g., 100+ slices in a CT scan). Cine playback scrolls through these slices automatically, allowing you to view the anatomy in motion rather than one slice at a time.

---

Using Cine Playback

1. Select a series with multiple slices
2. Click the Play button (▶) in the toolbar
3. The viewer automatically scrolls through each slice in sequence
4. Click Pause (⏸) to stop the animation
5. Click Play again to resume from where you paused

---

Playback Speed

The playback speed is configurable globally in DICOM Viewer > General.

• Default: 3 slides per second
• Setting: Autoplay Speed

This controls how quickly the Play button advances through slices in multi-slice series.

---

Manual Slice Navigation

You can also scroll through slices manually without using cine playback:

• Scroll wheel — scroll to move between slices one at a time
• Arrow keys — press up/down arrow to navigate slices
• Slider (if visible) — drag the slice slider to jump to a specific slice

---

Multi-Series

A DICOM study often contains multiple series — different anatomical sequences, phases, or imaging parameters. The DICOM Viewer lets you switch between them easily.

---

What Are Series?

A series is a set of slices from a single acquisition. For example:

• A brain MRI might have: T1-weighted series, T2-weighted series, FLAIR series
• A chest CT might have: high-resolution series, standard dose series, post-contrast series

Each series is a different view of the same anatomy.

---

Series Display Behavior

In current versions, multi-series behavior is mainly controlled by layout and selector visibility:

Configure these defaults in DICOM Viewer > Series Settings, or override them per viewer in the shortcode or block.

---

Switching Series

If the series selector is enabled and the study contains more than one series:

• Use the series selector to switch to another series
• In grid mode, use the pane selector to compare more or fewer panes side-by-side

Keyboard:

• Press left/right arrow keys to move between series (varies by browser)

---

Customizing Display Mode

Global Default

DICOM Viewer > Series Settings:

• Set Multi-Series Layout to auto, single, or grid
• Set Auto-Grid Threshold if using auto mode
• Toggle Series Selector and Pane Number Selector as needed

Per-Viewer Override

In shortcode:

[dicom_viewer id="123" layout="grid" show_series_selector="true" show_pane_selector="true"]

In Gutenberg block:

• In the sidebar, adjust Grid Layout and selector settings as needed

---

Auto Mode Details

When Multi-Series Layout is set to auto:

• Studies with fewer series than the threshold stay in single-pane mode
• Studies with series count at or above the threshold switch to grid mode

Example: If the threshold is 3:

• 1–2 series → single-pane mode
• 3+ series → grid mode

This lets you keep simpler studies in a single pane while automatically opening more complex studies in grid view.

---

Legacy Note

Older shortcode or block content may still include series_display="none". That legacy value is still honored to hide the selector, but current embeds should use the selector visibility controls instead.

---

Series Information

Hovering over a series control (on desktop) may show:

• Series description (from DICOM metadata)
• Number of slices
• Image dimensions

This helps you identify the right series without opening each one.

---

Grid Layout

Grid layout displays multiple series in a side-by-side grid of panes, making it easy to compare series at the same anatomical position.

---

Grid Modes

---

Activating Grid Layout

Global Default

DICOM Viewer > Series Settings:

• Set Layout Mode to auto, single, or grid
• If using auto, set Grid Min Series Threshold (default 2)

Per-Viewer Override

In shortcode:

[dicom_viewer id="123" layout="grid" grid_cols="2"]

In Gutenberg block:

• In sidebar, set Layout to grid
• Set Grid Columns (1–4)

---

Grid Columns

Control how many columns the grid has:

• 1 column — stack series vertically (like a list)
• 2 columns — 2 series per row (most common)
• 3 columns — 3 series per row (wide displays)
• 4 columns — 4 series per row (professional workstations)

Configure in DICOM Viewer > Series Settings or per-viewer using grid_cols attribute.

---

Auto Mode Details

When Layout Mode is set to auto:

• Studies with series count < threshold → single-pane view
• Studies with series count ≥ threshold → grid view

Example: If threshold is 2:

• 1 series → single-pane
• 2+ series → grid

This is useful when your studies have varying numbers of series.

---

Reference Lines

In grid layout, reference lines show the anatomical position across panes:

• Horizontal line — shows which row of pixels you’re viewing
• Vertical line — shows which column of pixels you’re viewing
• Crosshair — intersection of both lines

Move your cursor over any pane, and the reference lines update in other panes to show the exact same anatomical position.

Enable/disable reference lines:

• DICOM Viewer > Series Settings — global default
• Shortcode: ref_lines="true" or ref_lines="false"
• Gutenberg block sidebar: toggle Show Reference Lines

Tip: Reference lines are essential for comparing series at the same location. Keep them enabled for diagnostic work.

---

Example: 4-Pane Comparison

[dicom_viewer
  id="123"
  layout="grid"
  grid_cols="2"
  default_panes="4"
  default_pane_series="0,0,1,1"
  default_slides="20,30,20,30"
]

This displays a 2×2 grid with:

• Top-left & top-right: series 0 at slices 20 and 30
• Bottom-left & bottom-right: series 1 at slices 20 and 30

Users can pan and zoom independently in each pane while reference lines help them stay oriented.

---

Performance Notes

Displaying 4 panes simultaneously requires more CPU than a single pane. On slower devices or very large images, grid layout may feel sluggish. Consider using fewer columns or the single-pane view for users on mobile devices or older computers.

---

Default Viewport

You can customize the initial state of the viewer when a page loads by choosing which series and slice to display, and at what zoom level.

---

Pre-set Zoom & Position

You can set these when inserting the viewer:

---

Shortcode Example

[dicom_viewer
  id="123"
  default_series="1"
  default_slide="50"
  default_zoom="1.5"
  default_wc="40"
  default_ww="400"
]

This opens:

• Series 1 (the second series)
• Slice 50
• Zoomed to 150%
• Window/level preset to the values you provided

---

Multi-Pane Grid Layout

For grid layout comparisons, set values for each pane (comma-separated):

[dicom_viewer
  id="123"
  layout="grid"
  grid_cols="2"
  default_panes="4"
  default_slides="20,30,20,30"
  default_zooms="1.5,1.5,1.5,1.5"
  default_wcs="40,40,40,40"
  default_wws="400,400,400,400"
  default_pane_series="0,1,0,1"
]

This opens a 2×2 grid:

• Top-left: Series 0, slice 20, zoom 1.5x
• Top-right: Series 1, slice 30, zoom 1.5x
• Bottom-left: Series 0, slice 20, zoom 1.5x
• Bottom-right: Series 1, slice 30, zoom 1.5x

---

Gutenberg Block Defaults

In the Gutenberg block, the Default View panel is populated automatically from the current editor preview. When you save or update the post, the block stores the current series, slice, zoom, pan, and window/level values for reuse on the front end.

---

If No Defaults Are Set

The viewer automatically loads with:

• First series
• First slice
• Fit-to-window zoom

---