ChimeraX: DICOM Reference

Opening Data
Toolbar Icons   
Initial Display
Manipulation
Appearance Presets
Thresholds and Windowing
Volume Rendering Options
Cropping and Clipping
Virtual Reality
Sample Data

Development of these features is supported in part by the NIAID. ChimeraX can also read the NIfTI (.nii) and NRRD (.nrrd) formats often used for medical images. See also: Download DICOM, DICOM Browser, DICOM Metadata, Segmentations, Volume Viewer, ui view, DICOM in VR tutorial, DICOM segmentation 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 – in the resulting dialog, browse to location, choose directory, click Choose
– or –
click in the Medical Image tab of the Toolbar – in the resulting dialog, 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.

← Toolbar Icons

Many icons in the Toolbar across the top of the ChimeraX window are useful for working with DICOM data. The Medical Image tab contains an application-specific collection of icons:

•  open DICOM, as above
•  show/hide recent files list
•  save snapshot
•  single plane
•  tilted slab (details...)
•  orthoplanes
•  full region
•  toggle outline box
•  airways preset for image display
•  chest preset for image display
•  brain preset for image display
•  initial thresholds for image display, e.g., for single planes
•  view all, standard orientation
•  step 1, full resolution of data
•  step 2 subsample
•  2D xyz projection mode (details...)
•  3D projection mode (details...)
•  raycasting projection mode (details...)

•  crop volume box
•  view different planes of data along an axis
•  rotate slab to slice data at any angle (details...)
•  tape-measure distance measurement (details...)
•  adjust image display thresholds collectively (details...)

Mouse modes are described further in the section on manipulation.

← 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]

• To view different planes along the data Z axis, use the slider below the histogram. Pausing the cursor over the plane display shows the voxel indices and data value in a pop-up balloon.
• Planes along X, Y, or Z can be shown as follows:
  1. click to assign the move planes mouse mode to the right mouse button (= trackpad + Alt on Windows, trackpad + on Mac)
  2. click-drag with the assigned button to show different planes along the axis
  3. to switch axes:
     • show the full region of the data and its outline box by clicking the toolbar icons or using the context menu in the Volume Viewer window (right-click or Ctrl-click depending on platform)
     • reorient the box as needed
     • click the desired face of the box with the button assigned to move planes
• Planes along X, Y, and Z at the same time can be shown by choosing the orthoplanes display style in Volume Viewer or clicking the toolbar icon
• To return to Z-planes from orthoplanes or 3D rendering, choose the plane display style in Volume Viewer or click the toolbar icon

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 toolbar 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 icons above their histograms in Volume Viewer, the 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   ...or click graphics icon
To center and scale as above, plus reset to initial orientation: view orient   ...or click graphics icon

[this dataset provided below]

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 #1.1.1.1.5 show style surf level 1 region all

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

← Manipulation

Default assignments:

rotate	left mouse button
	trackpad click-drag Mac: also trackpad 2-finger rotation if multitouch* is on
	rotate VR hand controller with trigger pressed
translate	middle mouse button
	Mac: trackpad + Alt, 3-finger drag if multitouch* is on Windows: trackpad + Ctrl-Alt
	move VR hand controller with trigger pressed
zoom	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

Initially, the right mouse button (= trackpad + Alt on Windows, trackpad + on Mac) is also assigned to translate  , but can be reassigned by clicking any icon in the following tabs of the Toolbar:

• Right Mouse:   
• Markers: 

...or the last few icons in the in the Medical Image tab, as detailed above. 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.

The following presets, also available as toolbar icons, are defined in ChimeraX only:

• appearance airways – blue airways
• appearance chest – yellow bones, blue airways, some other tissues in pink
• appearance brain – yellow for fat and similar soft tissue, white of increasing intensity for brain on up to bone, blue for compact bone
• appearance initial – the same colors and intensities as chosen automatically when a dataset is first shown in the image style; may be useful for single-plane display

Users can also define their own custom appearance presets.

[this dataset provided below]

← 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:

windowing

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), and the dominant type of motion wins out; for adjusting multiple windows within a single histogram, see details

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

← Volume Rendering Options

Additional volume command options that may be useful:

• projectionMode  3d – to avoid jumps in brightness during the rotation of image displays, render using planes perpendicular to the line of sight (default for DICOM, see details...); see also toolbar icons
• planeSpacing – plane spacing for 3D projection mode (details...)
• brightness  value – scale the intensity (initial default 1) (details...)
• transparency  value – scale transparency relative to dataset thickness; approximately what fraction of dataset thickness produces the opacity values shown by the threshold heights on the histogram (initial default 0.5, range 0-1) (details...)
• dimTransparentVoxels  false – whether to scale brightness by (1–transparency), making transparent voxels dimmer; if false (initial default true), the appearance is brighter because less light is blocked (details...)
• maximumIntensityProjection  true – whether to display the the most intense color value underlying each pixel along the line of sight (initial default false); sometimes useful for enhancing detail (details...)
• colormapOnGpu, fullRegionOnGpu, colormapSize – options for rendering efficiency (details...)

← 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:

• the crop volume mouse mode
• the volume command, for example: volume #1 region 200,200,150,300,300,200
  ...to go back to the full dimensions: volume #1 region all

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:

clip	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

← Virtual Reality

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

• Rendering speed must be fast enough to avoid nauseating lags in the display when the scene or headset position changes. With large volume data, techniques to speed up rendering include subsampling (step > 1), cropping, and using the GPU.
  
  
• VR hand controllers are used for manipulation and clicking icons. Clicking the hand-controller menu button (on Vive, analogous on other systems) shows the ChimeraX user interface with icons in the headset.

  Clicking a mouse mode icon with a hand controller assigns whichever button was clicked to the corresponding function. In VR, leaving the triggers with their default assignments (rotation, translation, zooming) is recommended, but up to four other functions can be assigned, to the grip and trackpad buttons on each controller. Useful modes for DICOM in VR include move planes , crop volume , and windowing .

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

← Sample Data

4-24533.zip – a DICOM stack representing one CT scan of many in the RIDER Lung CT collection from The Cancer Imaging Archive (TCIA):

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

Evaluating variability in tumor measurements from same-day repeat CT scans of patients with non-small cell lung cancer. Zhao B, James LP, Moskowitz CS, Guo P, Ginsberg MS, Lefkowitz RA, Qin Y, Riely GJ, Kris MG, Schwartz LH. Radiology. 2009 Jul;252(1):263-72.

Zhao B, Schwartz LH, Kris, MG. (2015). Data From RIDER Lung CT. The Cancer Imaging Archive. doi: 10.7937/K9/TCIA.2015.U1X8A5NR

The data have been anonymized and are freely available. The folder should be unzipped and the files opened in ChimeraX as described above. A significant feature of this scan is a tumor in the right lung.

Note that the Download DICOM tool makes it easy to browse and download TCIA datasets from within ChimeraX.