ChimeraX docs icon

ChimeraX: DICOM Reference

Overview of ChimeraX features for working with DICOM medical imaging data:
Opening Data
Initial Display
Appearance Presets
Thresholds and Windowing
Volume Rendering Options
Cropping and Clipping
Map Icons
Virtual Reality
Sample Data

Development of these features supported in part by the NIAID. See also: DICOM in VR tutorial, ChimeraX for Medical Image Analysis

Opening Data

In ChimeraX, all of the DICOM files in a directory and its subdirectories can be opened in a single operation if the format is specified explicitly:

Menu: File... Open DICOM Folder (dialog shows Format: DICOM image), browse to location, choose directory, click Choose
– or –
Command: open  directory-pathname  format dicom

...where directory-pathname may contain * as wildcard to lessen typing, and should be enclosed in quotation marks if it includes spaces, for example:

open "~/Desktop/2-CT 5*" format dicom

Each series that is found will be opened as a separate model.

Many icons in the Toolbar across the top of the ChimeraX window are useful for working with DICOM data:

Initial Display

Only a single Z-plane is shown at first. The Volume Viewer tool with a histogram of the data is automatically shown, with plane as the chosen display style.

[this dataset provided below]
screenshot 1

For 3D volume rendering, choose volume display in Volume Viewer. This shows the full region in the transparent “image” style. The thresholds may need to be adjusted to improve the appearance after switching display styles.

For full resolution, set the step value to 1 or click the map icon . Subsampling (step > 1) decreases computational demands and may be needed for responsive rendering of large datasets, particularly in virtual reality. Step size may be adjusted automatically upon initial display or when the amount of data shown is changed.

When multiple datasets or other models are open at the same time, they can be hidden or shown individually, such as with the “eye” icons above their histograms in Volume Viewer, the eye icon checkboxes in the Model Panel, or the volume command. Many settings can be adjusted with either the Volume Viewer graphical interface or the volume command, for example: volume all style image region all step 1

Commands that are frequently useful:
For orthographic projection: camera ortho  ...or to go back to perspective projection: camera mono
To center and scale the display to fit in the graphics window: view clip false
To center and scale as above, plus reset to initial orientation: view orient clip false

[this dataset provided below]
screenshot 2

Some DICOM files contain time series that can be played with the time slider shown automatically by ChimeraX or with the vseries command.

Some DICOM files contain SEG objects (segmentations as binary maps), and these are automatically associated with the corresponding image series to synchronize plane display. They can also be displayed as isosurfaces, for example: volume # show style surf level 1 region all

Segmentations described as radiotherapy structure set (RTSTRUCT) contours are also read and displayed.


Default assignments:

left mouse button
trackpad click-drag
Mac: also trackpad 2-finger rotation if multitouch* is on
rotate VR hand controller with trigger pressed
middle mouse button
Mac: trackpad + Alt, 3-finger drag if multitouch* is on
Windows: trackpad + Ctrl-Alt
move VR hand controller with trigger pressed
mouse scroll wheel
Mac: trackpad pinch or 4-finger drag if multitouch* enabled, otherwise 2-finger drag
Windows: trackpad 2-finger drag
move VR hand controllers farther apart or closer together with both trigger buttons pressed
*Use of Mac multitouch gestures can be turned on and off in the ChimeraX Trackpad preferences

Initially, the right mouse button (= trackpad + Alt on Windows, trackpad + on Mac) is also assigned to translate  , but clicking any other Right Mouse icon reassigns it:

Buttons can also be reassigned with the mousemode command.

Appearance Presets

ChimeraX includes rough implementations of the Horos 3D presets and some of the MRIcroGL color lookup tables. They can be applied by name with the volume command appearance option, for example:

volume #1 appearance "Airways II"
volume #1 appearance CT_Muscles

The implementations are only approximate, as there may not be a direct correspondence between settings in different programs, and parts of the definition files may have been ignored. Besides a preset name, appearance initial can be used to (re)set to the colors and intensities chosen automatically when a dataset is first shown in the image style. The initial settings may be useful for single-plane display after using a 3D preset.

The map icons , , and apply the Airways II, CT_Skin, and initial settings, respectively.

[this dataset provided below]
screenshot 3

Thresholds and Windowing

Thresholds are the control points on the histogram for mapping values to colors and intensities. They can be moved by dragging in the Volume Viewer histogram, and added and deleted using the context menu (right-click or Ctrl-click depending on platform). The color of the most recently clicked threshold can be changed by clicking the color square above the left end of the histogram.

Applying a 3D preset sets thresholds and colors, among other things. Threshold levels and colors can also be set explicitly with the volume command, for example:

volume #1 level -742,0.0 level -683,0.049 level -481,0.25 level -333,0.0 color 0,61,71 color 0,61,71 color 0,61,71 color 0,61,71

A windowing mouse mode allows adjusting image display thresholds collectively:

vertical motion adjusts window level (moves all thresholds in parallel to higher or lower values), horizontal motion adjusts window width (moves thresholds symmetrically farther apart or closer together); the dominant type of motion wins out

A mouse mode can be assigned to a button as described above.

Volume Rendering Options

Additional volume command options that may be useful:

Cropping and Clipping

Cropping limits the display of a dataset to a smaller rectangular box or slab, making it easier to see features of interest while reducing the computational demands of rendering. Cropping can be done with:

A cropped slab display can be moved along an axis using the move planes mouse mode . Single planes can be viewed as described above.

In contrast, clipping may not have much effect on rendering speed, since calculations are still performed on the hidden parts. ChimeraX has near/far clipping planes that always face the viewer, plus the ability to clip/slab at any angle (so-called front/back planes). Both kinds can be controlled with the clip command or with the following mouse modes:

activate and translate front clipping plane, +Alt back plane, +Shift slab (front and back in same direction), +Alt-Shift slab thickness (front and back in opposite directions); if only near/far (fixed-orientation) planes already active, move those instead of front/back (rotatable) planes
clip rotate
activate and rotate front/back clipping planes

A mouse mode can be assigned to a button as described above.

The near/far planes can also be manipulated in the Side View (menu: Tools... General... Side View).
To turn off all clipping: clip off or ~clip

Map Icons

Icons in the Map tab of the Toolbar can be clicked to perform some action on volume models, including:

These icons act on all displayed volume models unless only specific ones are selected, such as with the hand icon checkboxes in the Model Panel.

Virtual Reality

DICOM data can be viewed in ChimeraX virtual reality. Important aspects of using VR:

See also: DICOM in VR tutorial, the VR at UCSF website, VR setup advice and observations on different systems: Windows, Mac, Linux

Sample Data – a DICOM stack representing one CT scan of many in the RIDER Lung CT collection from the Cancer Imaging Archive:

Clark K, Vendt B, Smith K, et al. The Cancer Imaging Archive (TCIA): Maintaining and Operating a Public Information Repository. Journal of Digital Imaging. 2013; 26(6): 1045-1057. doi: 10.1007/s10278-013-9622-7.

The data have been anonymized and are freely available. The folder should be unzipped and the files opened in ChimeraX as described above. Although this tutorial does not include clinical analysis, a significant feature of the scan is a tumor in the right lung.

UCSF Resource for Biocomputing, Visualization, and Informatics / May 2019