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

Tool	Purpose
Pan	Click and drag to move the image around the viewport
Zoom	Use +/− buttons or scroll to magnify the image
Window/Level	Adjust brightness and contrast to see different tissue types
Reset	Restore the image to its default zoom and position

Multi-Series Features

Feature	Purpose
Series Navigation	Switch between different anatomical series (CT, MRI, etc.)
Cine Playback	Automatically scroll through slices in a series
Grid Layout	Display multiple series side-by-side with reference lines

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.

Next Steps

See Tools for details on pan, zoom, window/level, and reset
See Multi-Series for series navigation
See Cine Playback for automatic slice animation

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
Click Fit to fit the entire image to the viewport

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:

Click the Window/Level button in the toolbar
Click and drag on the image:
- Drag horizontally → adjust window width (contrast)
- Drag vertically → adjust window center (brightness)
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 default zoom and position.

Clicking the Reset button:

Resets zoom to fit the entire image in the viewport
Removes any pan offset
Does NOT change window/level settings

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

Next Steps

See Cine Playback to automatically scroll through slices
See Default Viewport to learn about pre-setting zoom and pan

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

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

Playback Speed

The playback speed is fixed and optimized for typical medical viewing. You cannot adjust the speed in the current version.

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

Next Steps

See Multi-Series to switch between different series
See Grid Layout to compare multiple series side-by-side

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 Modes

The series selector displays in different styles based on your settings:

Mode	Appearance	Best For
Pills	Clickable buttons side-by-side	5 or fewer series
Dropdown	Single selector menu	6+ series
Auto	Pills if ≤ threshold, dropdown if > threshold	Default; adapts to content
None	No selector	Single-series studies only

Configure the default display mode in DICOM Viewer > Series Settings, or override per-viewer in the shortcode/block.

Switching Series

With pills:

Click any pill to switch to that series

With dropdown:

Click the dropdown menu
Select a series from the list

Keyboard:

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

Customizing Display Mode

Global Default

DICOM Viewer > Series Settings:

Set Series Display Mode to auto, pills, dropdown, or none
Set Auto Threshold if using auto mode

Per-Viewer Override

In shortcode:

[dicom_viewer id="123" series_display="pills"]

In Gutenberg block:

In the sidebar, set Series Display to pills, dropdown, or auto

Auto Mode Details

When Series Display Mode is set to auto:

Studies with series count ≤ threshold → show pills
Studies with series count > threshold → show dropdown

Example: If threshold is 5:

1–5 series → pills
6+ series → dropdown

This provides the best UX for most cases without manual configuration.

Series Information

Hovering over a series pill (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.

Next Steps

See Grid Layout to compare multiple series side-by-side
See Cine Playback to view slices within a series as animation

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

Mode	Behavior
Single	Show one series at a time (fullscreen viewport)
Grid	Show multiple series in a grid (2–4 columns)
Auto	Switch between single and grid based on series count

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.

Next Steps

See Multi-Series for switching between series
See Default Viewport to pre-set each pane’s zoom and pan

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:

Option	What it does
`default_series`	Which series to show first (0 = first, 1 = second, etc.)
`default_slide`	Which slice within the series (0 = first slice)
`default_zoom`	Starting zoom level (1.0 = fit to window, 2.0 = 2x zoom, etc.)
`default_pan_x`	Horizontal position offset
`default_pan_y`	Vertical position offset

Shortcode Example

[dicom_viewer
  id="123"
  default_series="1"
  default_slide="50"
  default_zoom="1.5"
]

This opens:

Series 1 (the second series)
Slice 50
Zoomed to 150%

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_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

If No Defaults Are Set

The viewer automatically loads with:

First series
First slice
Fit-to-window zoom

Next Steps

See Tools for details on zoom, pan, and window/level
See Shortcode Reference for full attribute documentation