Inspect images in the viewer

Use the embedded viewer to move through a study, adjust image presentation, read pixel values, and inspect DICOM metadata without changing the source files.

Open the dataset

Launch one or more files or directories:

dcmview ./series ./additional-image.dcm

The link that dcmview opens or prints ends in #token=…, the session’s access token. The viewer removes it from the address bar after loading and keeps it for the tab, so reloading works, but a copy of the address taken from a loaded tab does not open the viewer elsewhere.

Discovery is progressive. The viewer can show the first valid object before a large recursive scan finishes. The status bar shows how many files are loaded, and the terminal prints skipped and filtered counts when the scan completes.

Use Explorer to switch between clinical Study/Series organization and directory organization. The Study and Series view shows the DICOM hierarchy by nesting. Up/Down arrows move through the active Explorer ordering, including its current filter.

The viewer follows your operating system’s light or dark setting, or the editor’s theme inside VS Code and Cursor. The image area stays dark in both.

Move through images and frames

Related single-frame, multiframe, and concatenated objects can appear as one logical stack, and each tab shows its position in the stack. Navigation resolves each logical position back to its actual source file and zero-based source frame, so tags, caches, references, and annotations stay attached to the correct object.

Action	Input
Previous or next file in Explorer	Up/Down arrows
Previous or next logical frame	Left/Right arrows or [ / ]
Move through frames with the wheel	Mouse wheel with the Scroll tool (S)
Seek to a position	Image position scrubber
Play or pause cine	Space
Previous or next annotation item	, / .
Select cine speed and mode	Playback controls below the viewport

The Image position scrubber works with the mouse and keyboard at every viewer width; seeking pauses playback. Cine supports loop and sweep playback. Moving between frames preserves zoom and pan. Switching between open tabs keeps each tab’s view, and closing a tab discards it, so reopening starts from a fitted view.

The previous image stays on screen until the next one is ready, so the image, its overlays, and its labels change together.

Adjust image presentation

Tool	Shortcut	Behavior
Window/level	W	Drag to adjust grayscale presentation.
Pan	P	Drag the image without requesting another frame.
Zoom	Z	Drag up to zoom in and down to zoom out.
Scroll	S	Drag, or turn the wheel, to move through the logical frame stack.
ROI	R	Draw and edit rectangular ROIs.
Redact	X	Draw redaction boxes over burned-in text.
Reset	Double-click	Restore the viewport presentation.

Middle-drag pans in every tool. The wheel zooms about the pointer, a two-finger trackpad scroll pans, and Ctrl/Cmd+wheel (a trackpad pinch) zooms. In the Scroll tool the wheel steps frames instead.

Tool, frame, cine, and file shortcuts are ignored while Ctrl, Cmd, or Alt is held, so combinations such as Ctrl+Z and Ctrl+R reach the browser or the editor instead of selecting a tool. Two exceptions remain: [ and ] still step frames when typed with Option or AltGr, and Delete and Backspace still remove the selected ROI with a modifier held.

The toolbar also provides horizontal and vertical flips, 90-degree rotation, and window presets: the DICOM default, Full Dynamic, and common CT presets.

Window selection follows this order:

1. Full Dynamic uses the current frame’s minimum and maximum.
2. An explicit window/level adjustment or preset.
3. DICOM Window Center and Window Width.
4. A current-frame 1st/99th percentile fallback.

A manual drag leaves Full Dynamic and preset mode, and choosing a preset replaces a preceding drag. The HUD shows the window the frame was actually drawn with. Frames presented through a VOI LUT, and color frames, show no center/width value.

Window/level updates live while you drag on every grayscale frame, including frames with Modality or VOI LUTs, display shutters, overlay planes, and one-bit, 32-bit, or float samples. The browser windows frames up to 20 megapixels from their decoded samples. For larger frames the drag shows server-rendered previews, and the released window is then fetched. Playing cine with the W/L tool selected uses server-rendered frames with the current window; pausing returns to interactive windowing.

Read pixel values

A readout follows the cursor over the image. It shows the row, column, and frame, then:

• the stored sample, or the color components or palette index of a color image;
• the Modality value, such as HU for CT; and
• the preferred real-world value with its unit and the mapping it came from, such as a Parametric Map value or RT Dose in Gy.

When a frame’s raw samples cannot be served, the readout keeps the coordinates and says the value is unavailable.

On frames with a Real World Value Mapping or RT Dose Grid Scaling, window/level works in that unit. The HUD shows center and width in the unit, a legend shows the window’s range, and a dragged window stays in mapped units across frames and files. Some server-rendered frames cannot apply a window in a LUT mapping’s unit; they show their default window instead. See known limitations.

Show dose and map overlays

When an RT Dose or Parametric Map in the scan covers the current image in the same Frame of Reference, an Overlay bar appears above the viewport:

1. Turn on the dose or map overlay.
2. Adjust its opacity.
3. Read Gy or the map’s unit from the color bar.

A slice the volume does not reach shows a note instead of a layer. With an overlay shown, the pixel readout also reports the overlaid value under the cursor. Window/level, cine, ROIs, and zoom keep working beneath the overlay.

From an RT Dose or Parametric Map file, choose Show dose on source image or Show map on source image in its Semantic Context to open a covered image with the overlay on.

Show presentation state annotations

When a Grayscale or Color Softcopy Presentation State in the scan annotates the current image, an Annotations bar appears above the viewport. It lists the states that annotate the image. Annotations are off until you choose a state, and one state is shown at a time.

1. Choose a state to draw its graphics and text on the image.
2. Step through the state’s annotation items with the previous and next controls, or with , and ..
3. Choose the state again to turn its annotations off.

The current item is highlighted and the others are dimmed. Stepping opens the image and frame that the item references. Shapes follow zoom, pan, flips, and rotation; text and point marks stay upright. A layer’s recommended display color is used when the state declares one.

From a presentation state file, Semantic Context lists its layers and can open the state, or a single annotation item, on an annotated image.

Only the annotations are applied. The state’s window, shutter, displayed area, and rotation or flip are not, and objects positioned in DISPLAY units are counted in the bar but not drawn. See known limitations.

Inspect tags and references

Open Tags to filter the lazy tag tree, expand sequences and long values, resize columns, and copy values. Copy, sequence expansion, and value expansion are separate buttons that you can activate with Enter or Space. Binary values such as Pixel Data are represented by byte length instead of embedding the full payload.

The reference navigator shows typed DICOM relationships and refreshes as discovery progresses. When the referenced SOP instance is present in the current scan, select a validated target to open its file and frame. Unresolved references remain visible rather than being silently discarded.

Use semantic and WSI context carefully

SEG, Parametric Map, and RT Dose objects expose an opt-in semantic panel beside the unchanged stored-pixel preview. The panel can summarize declared segments, Real World Value Mappings, dose scaling, grid geometry, and resolved sources. It does not establish clinical interpretation.

For SEG, select Semantic Context to compose the mask over its resolved local source image. Explicit derivation references are preferred; declared-source patient geometry can also resolve classic single-frame source series. Compatible source and SEG matrices may differ in size because the mask is resampled through patient coordinates. Segments use their recommended display color when the SEG declares one. A FRACTIONAL SEG that stores only 0 and 1 is drawn as a binary mask with a warning.

Composition is available only when one source frame and one compatible transform are validated. When identity or geometry is missing, ambiguous, non-coplanar, or non-overlapping, the viewer explains why the overlay is unavailable instead of guessing. ROI editing, interactive window/level, and cine are disabled until you return to Pixel Preview.

For Whole Slide Microscopy, the context panel positions the selected tile within the declared Total Pixel Matrix and reports row, column, optical path, focal plane, and a minimap. Companion images are grouped as label, overview, thumbnail, volume, and other roles and open in the viewer. dcmview does not stitch adjacent tiles or reconstruct a slide-wide image.

Share your screen

Two features help when you show files on a shared or recorded screen: a masked session replaces patient identifiers in what the viewer displays, and redaction boxes cover text burned into the pixels.

Masking is not de-identification

--mask changes only what the viewer displays. Files are never modified, nothing is persisted, and burned-in pixel text, free text inside kept values, and folder and file names are not masked. Check what is on screen before you share it, and do not treat a masked session or its screenshots as de-identified data.

Start a masked session

dcmview --mask ./study

The status bar shows a Masked display badge for the whole session. Masking is fixed for the process: there is no control to turn it off, and replacements differ on every run. To see the real values, start the viewer again without --mask.

In a masked session:

• Each patient is shown as Patient 0001, Patient 0002, and so on, with a matching MASKED-0001 Patient ID. Files are shown as File 1, File 2, and so on outside the Directory view.
• Every date and date-time moves by one random offset per patient, within one year. Times of day are kept.
• Ages above 89 years show 089Y, and a birth date that implies an age over 89 is blank.
• Person names, private elements, and the attributes that the DICOM PS3.15 Basic Application Level Confidentiality Profile removes or replaces, such as institution, addresses, accession number, operators, and device serial numbers, show [masked].
• Study, series, instance, and other instance-level UIDs are replaced by hashed 2.25. UIDs. The same UID always gets the same replacement within the session, so references still resolve.
• Presentation state text is not drawn, and slide label and overview images are not shown.

Study Description, Series Description, and patient sex, age, size, and weight are kept.

What masking does not cover

• Pixels. Burned-in text stays visible. In a masked session, a file that declares Burned In Annotation shows a Burned-in text badge in the status bar. A file can carry burned-in text without declaring it, so look at the images and use redaction boxes.
• Free text inside values that are kept, such as descriptions.
• Folder and file names. Explorer’s Directory view shows them as they are on disk, under a Not masked note, and tabs follow that view while it is showing. The Study and Series view and everything else use File N.
• Anything outside the viewer page: the terminal, VS Code’s own editor tabs and Explorer, and the exported ROI CSV, which keeps real paths.

Cover burned-in text with redaction boxes

1. Press X or choose the Redact tool.
2. Drag a rectangle over the text. The region turns black.
3. Select a box to move, resize, or delete it, or to choose Current to limit it to the current frame. All makes it cover every frame again.
4. Choose Apply to series to copy the file’s boxes to every file of the series with the same image size, where a banner sits in the same place.

A box covers every frame of its file unless you limit it. Box outlines show only while the Redact tool is active. Boxes are available with or without --mask.

The server applies the boxes, so a redacted region is never sent to the browser in either the rendered or the raw frame. Boxes stay in memory until the viewer exits; they are not saved and are not part of Export ROIs.

Draw the boxes before you share your screen, since you have to see the text to cover it. After Apply to series, step through the series to confirm that each box covers the text on every image.

Recover from errors

If the page shows This viewer needs its access link or The viewer restarted instead of the viewer, it has no valid access token for the running dcmview process. Copy the full link, including #token=…, from the terminal where dcmview is running and paste it into the same tab.

If the server stops answering, the status bar shows Disconnected with a Retry action. A failed first load offers Retry too. A failed Export ROIs shows a notice in the viewer. When a layer such as a shutter or overlay fails to load, the image stays visible with a note.

Stop the viewer

Return to the launching terminal and press Ctrl+C. The HTTP server, memory caches, redaction boxes, and unexported ROI edits are discarded.

For exact controls and support states, see DICOM and pixel support and the CLI reference.