CDViewer — Portable DICOM Viewer

A portable, single-executable DICOM viewer written in Rust. Designed to ship on study CDs/DVDs alongside the imaging data and run without installation on Windows, macOS, and Linux.

Not for diagnostic use. This viewer is intended for review and reference only. It must not be used as the basis for primary clinical diagnosis. A disclaimer is shown on first launch and acknowledged in config.toml.

---

Features

• Single executable — statically linked, no installer, no system dependencies on Windows/macOS. Targets a <30 MB stripped binary.
• Portable-first storage — config, annotations, and logs are written next to the executable when possible; falls back to the per-user data directory for read-only media (CD/DVD).
• CD/DVD auto-load — drop a DICOM/ folder next to the binary; on Windows, autorun.inf opens the study automatically.
• Modality support — CT, MR, CR, DX, and MG (with a 2×2 hanging protocol for RCC/LCC/RMLO/LMLO when ≥4 mammography views are present).
• Viewing tools — window/level (with presets for soft tissue, lung, bone, brain, abdomen, mediastinum), pan, zoom, rotate, flip, invert, multi-cell grid layouts (1×1 up to 4×4).
• Measurement tools — length (mm when pixel spacing is present), angle, rectangle ROI, ellipse ROI with mean/std/min/max (HU on CT).
• Annotations — persisted to a JSON sidecar, keyed by SOP Instance UID. Original DICOM files are never modified.
• Export — PNG with annotations burned in, with optional patient-data anonymisation.
• Metadata panel — full DICOM tag tree with right-click copy.
• Crash-friendly — a panic hook writes the panic location, message, and backtrace to the log file before the process aborts.

Screenshots

Add screenshots to docs/images/ and reference them here.

Install

Download a release

Pre-built binaries are attached to every GitHub Release:

Platform	Archive
Linux x86_64	dicom-viewer-vX.Y.Z-x86_64-unknown-linux-gnu.tar.gz
Linux aarch64	dicom-viewer-vX.Y.Z-aarch64-unknown-linux-gnu.tar.gz
macOS Apple Silicon	dicom-viewer-vX.Y.Z-aarch64-apple-darwin.tar.gz
Windows x86_64	dicom-viewer-vX.Y.Z-x86_64-pc-windows-msvc.zip
Windows aarch64	dicom-viewer-vX.Y.Z-aarch64-pc-windows-msvc.zip

Extract and run the binary directly. No installation step is required.

Build from source

Requires Rust 1.80+.

git clone https://github.com/pejmanS21/CDViewer.git
cd CDViewer
cargo build --release
./target/release/dicom-viewer

On Linux, the eframe wgpu backend needs a few system packages:

sudo apt-get install -y \
  libgtk-3-dev libxkbcommon-dev libxkbcommon-x11-0 \
  libwayland-dev libxcb-render0-dev libxcb-shape0-dev libxcb-xfixes0-dev \
  libssl-dev pkg-config

Usage

# Open a folder of DICOM files
dicom-viewer /path/to/study

# Or set an env var (used by the CD auto-load path)
DICOM_VIEWER_DATA=/path/to/study dicom-viewer

# Or launch empty and drag-drop a folder onto the window
dicom-viewer

When the executable lives next to a folder named DICOM/, dicom/, IMAGES/, images/, or DICOMDIR/, that folder is loaded automatically on startup.

See dist/HELP.txt for the full mouse/keyboard reference.

Distributing on CD/DVD

This viewer is designed to ship as the only software on a study disc. See dist/CD-DISTRIBUTION.md for the disc layout, auto-load rules, staging scripts (dist/make-cd.sh, dist/make-cd.ps1), and ISO-creation commands.

Documentation

• API docs (rustdoc) — generated from the source on every push to main. The crate root has the module map and architecture overview; individual items have their own pages.
• CONTRIBUTING.md — development setup, coding standards, pre-commit hooks, PR workflow.
• docs/ARCHITECTURE.md — module layout, state model, DICOM pipeline, UI composition, locked-in design decisions.
• docs/CI-CD.md — how ci.yml, release.yml, security.yml, and docs.yml work; how to cut a release.
• dist/CD-DISTRIBUTION.md — disc layout, auto-load priority, staging, ISO commands, cross-compilation.
• CHANGELOG.md — release history.

Generate the docs locally

cargo doc --no-deps --lib --open

This builds the rustdoc site (same flags as CI) and opens target/doc/dicom_viewer/index.html in your browser. Add RUSTDOCFLAGS="-D warnings" to fail on broken intra-doc links the same way the docs workflow does.

Licence

Licensed under the Apache License, Version 2.0.

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in this project shall be licensed as above, without any additional terms or conditions.

Acknowledgements

Built on top of the excellent dicom-rs ecosystem and the egui / eframe immediate-mode GUI framework.