Terminal DICOM Viewer

A command-line DICOM medical image viewer for the terminal, rendering medical images as ASCII art.

About

This is a lightweight terminal-based viewer for DICOM medical images built with C++, ITK, and ncurses. It allows radiologists and researchers to quickly inspect medical imaging data (CT, MRI, etc.) directly from the command line without needing heavyweight GUI applications. The viewer supports multi-planar viewing, adjustable contrast/brightness (window/level), and multiple ASCII character density options for optimal detail visualization. Perfect for remote environments, scripting pipelines, or quick image inspection workflows.

Features

• Multi-plane support: View axial, coronal, and sagittal slices
• Multiple intensity scales: 8, 10, 16, or 32-character ASCII representations
• Interactive window/level controls: Adjust contrast and brightness for different tissue types
• Vim-style keybindings: Efficient navigation using familiar key combinations
• State-change rendering: Only updates display when needed for responsiveness

Requirements

• C++17 compiler
• CMake 3.16+
• ITK (Insight Segmentation and Registration Toolkit) with GDCM support
• ncurses

Building

mkdir build
cd build
cmake ..
make

Make sure ITK is installed or adjust the ITK_DIR in CMakeLists.txt to point to your ITK build directory.

Usage

./build/terminal-viewer /path/to/dicom/directory

The viewer expects a directory containing DICOM files from a single series.

Keyboard Controls

Navigation

• k/j: Move to previous/next slice
• a: Switch to axial plane
• c: Switch to coronal plane
• s: Switch to sagittal plane

Settings Menu

• m: Open unified settings menu (j/k to navigate, Enter to apply, ESC to cancel)
  • Window/Level Presets: CT Lung, CT Mediastinum, CT Bone, CT Brain, CT Soft Tissue, MR Brain, MR Spine
  • Custom Window: Enter custom window width value
  • Custom Level: Enter custom window level value
  • Intensity Scale: 8-char, 10-char, 16-char, 32-char
  • All Planes: Toggle 3-column view (Axial | Coronal | Sagittal) for simultaneous multi-planar viewing

General

• q: Quit the viewer

How It Works

1. DICOM Loading: Uses ITK's ImageSeriesReader with GDCM backend to load DICOM files into a 3D volume
2. Slice Extraction: Extracts 2D slices from the 3D volume along the selected axis
3. Window/Level: Applies medical imaging window/level adjustment to enhance contrast
4. Downsampling: Scales the image to fit the terminal size using nearest-neighbor sampling
5. ASCII Rendering: Maps pixel intensities to ASCII characters using the selected scale
6. Display: Renders the ASCII representation with an info bar showing current settings

Character Scales

The viewer uses progressively denser ASCII characters to represent intensity levels:

• 8-char: .:-=+*#%
• 10-char: .:-=+*#%@
• 16-char: .:-=+*#%@&$XM
• 32-char: .-_~:;!=|/()[]{}+*#%@&$XMWQB8`

Higher character counts provide better detail but may be harder to read at a distance.

Default Window/Level Values

The viewer defaults to CT imaging parameters:

• Window Width: 400
• Window Level: 40

Adjust these based on your imaging modality and clinical needs.

Example

# View a CT scan
./build/terminal-viewer ~/dicom_data/ct_chest/

# Then:
# - Press 's' to see sagittal view
# - Press '4' for best detail (32-char scale)
# - Press 'w' to adjust window width
# - Press 'l' to adjust level

Implementation Notes

• Single-threaded event loop for simplicity
• ncurses in raw/noecho/nodelay mode for responsive keyboard input
• Efficient state-change-only rendering to avoid unnecessary redraws
• Supports any terminal size (minimum 40×10 characters recommended)