Sessions and viewer lifetime

A dcmview session is one temporary viewer over the files you selected. Whether you launch it from a shell, Python, VS Code, or Cursor, the result is the same browser-based inspection experience and the same research-only safety boundary.

A launch creates one session

The command-line tool starts a viewer on the machine that can read the selected DICOM paths. The Python package launches that same viewer and can either wait for it to finish or return a handle that can stop it later.

With the editor extension active, a launch from a VS Code or Cursor integrated terminal, or from a working directory inside an open workspace folder, is owned by the editor and presented in a webview. The command-line tool, Python, and terminal launches all follow this one rule. Any other launch starts an ordinary local browser viewer. See the VS Code and Cursor guide for the visible routing behavior and opt-out.

Each session has its own URL, access token, and lifetime. Starting another command does not add files to an existing browser session unless the editor integration deliberately captures that launch. If a different dcmview process later answers on the same address, an open viewer never mixes data from both: it asks for the new session’s link, because the new process has a new token, or reloads its file list when both sessions share a token fixed with DCMVIEW_TOKEN or run with --no-token.

Discovery and viewing overlap

The viewer can become available before a large directory scan finishes. Valid objects appear progressively, Explorer shows how many files have been indexed while discovery continues, and the terminal prints loaded, skipped, and filtered totals, with skipped files broken down by reason, when the scan completes.

An unreadable, filtered, metadata-only, or unsupported object does not prevent other valid objects from appearing. Startup fails when the complete selection contains no valid DICOM objects. DICOMDIR is recognized but skipped; dcmview does not traverse its file-set hierarchy.

The viewer keeps source identity visible

Explorer can organize files by Study and Series or by directory. When complete Study and Series Instance UIDs are present, related single-frame, multiframe, and concatenated objects can appear as one ordered logical stack. Incomplete identities stay independent rather than being combined speculatively.

Moving through a logical stack still selects a real source file and frame. Tags, annotations, references, and error states therefore follow the object that supplies the current frame. Geometry warnings remain visible when ordering evidence is incomplete or inconsistent.

Frame reuse is temporary

During a session, dcmview reuses recently prepared frame data so revisiting images, changing frames, and cine playback do not require every step to start from scratch. Server-rendered images and browser-side rendering have bounded memory budgets; older work can be discarded and prepared again as needed. --cache-budget lowers or raises the server’s frame cache total.

The browser uses decoded samples for responsive window/level on every grayscale frame up to 20 megapixels and reproduces the server’s presentation, including LUTs, shutters, and overlays. Color frames and larger frames use server-rendered PNGs. This choice affects responsiveness, not the selected source frame or the session’s persistence rules.

The viewer keeps the previous image on screen until the next one is ready, so the image, its overlays, its value mapping, and its labels always change together.

No frame cache is a durable copy or a promise that data stays only in memory: the browser, operating system, screenshots, downloads, logs, and network path can create their own artifacts. See Ephemeral state and network security before opening sensitive data.

Stopping ends the session

Pressing Ctrl+C, calling a Python handle’s .stop(), exiting the Python interpreter that started a non-blocking viewer, using the editor’s stop command, or reaching an idle --timeout ends the owned viewer session. Shutdown stops serving the viewer and releases its file registry, prepared frames, tag data, and unexported ROI edits.

The timeout measures request inactivity after the scan has finished, not user authorization: browser and viewer requests reset it. It is a cleanup aid, not a security control.

Source DICOM files and an input annotation CSV are read, not modified. Export ROIs is the deliberate persistence path for annotation edits and downloads a new CSV before the session ends.

For implementation ownership, executor boundaries, and cache design, see Runtime internals. The viewer’s HTTP routes require the session’s access token and are an unsupported maintainer interface, not a public integration API.