MrViewer

From VISTA LAB WIKI

Jump to: navigation, search

mrViewer is a general-purpose GUI for viewing MRI and other neuroimaging data. It is part of the mrVista2 repository.

N.B. mrmViewer is a separate and quite different tool for viewing meshes and fiber tracks.

mrViewer consists of a display window for the data, as well as the following GUI panels:

  • A Navigation Panel for selecting what slices, orientations, and display format from the data to show;
  • An ROI Panel for selecting, editing, saving, and plotting time courses from Regions of Interest in the data;
  • A Grayscale Panel for setting the contrast and brightness of the base, underlay image;
  • An Info Panel for displaying information from the header file(s) of the data;
  • A Mesh Panel for controlling the projection of data maps and ROIs onto a 3D Mesh using mrMesh;
  • One or more Overlay Panels for displaying data such as statistical maps on top of the base image.

Each of these panels may reside in its own window, or be attached (or "docked") in the same window as the display window. The panels may also be hidden (toggled off) so as not to clutter the screen when they are not needed.

Contents

[edit] Usage

To invoke mrViewer type:

> mrViewer [filename]

or:

> mrViewer [filename] [format]

or:

> mr = mrLoad([filename], [format]);
> mrViewer(mr);

mrViewer can read data in the following formats:

  • ANALYZE format
  • NIFTI format
  • DICOM format (reads all DICOM files in a directory)
  • GE I-file (Genesis) format (reads all I-files in a directory)
  • Lucas Center P*.7.mag files (w/ E-file headers)
  • mrGray *.dat format
  • mrVista Inplane.anat format
  • mrVista Parameter Maps and corAnal.mat files
  • mrVista Time Series files
  • FS-FAST .bshort files
  • FS-FAST .bfloat files


[edit] Navigation Panel

The navigation panel is used to set the display format of the viewer (viewing a single slice at a time; viewing a montage of several slices, with a size specified by the user; and viewing the 3 planes which intersect at the current cursor location), set the displayed slices and slice orientation, zoom in and out of the MR volume, and toggle the cursor visibility. By default it resides in its own figure, initialized to the left of the screen.


[edit] ROI Panel

The ROI panel contains tools for creating, editing, and saving regions of interest (ROIs); selecting the current ROI; setting the ROI display mode (whether to hide the ROIs, show the selected ROI only, or show all ROis); and launching a Time Course UI for the selected ROI. By default it is docked to the display figure, residing just above the display.


[edit] Grayscale Panel

The Grayscale panel contains some controls for setting the brightness and contrast of the base anatomical image. The "AutoThreshold" button guesses a reasonable contrast range based on the intensity histogram of the volume. By default it resides in its own figure.


[edit] Info Panel

The Info Panel displays information for all loaded MR data, including the base anatomy, and any loaded maps. This information is derived from header information for each file. By default it is docked to the display figure, to the right of the display.


[edit] Mesh Panel

The Mesh Panel contains controls for projecting the displayed data (maps, ROIs, and cursor location) onto a 3D Surface Mesh using mrMesh, and getting ROIs created on the mesh. To work it needs a segmentation, and currently will only work if operating via an initialized mrVista session. (All other aspects of the viewer should operate on any file of the proper format, even if it hasn't been initialized in mrVista.) By default it is docked to the display figure, to the right of the display.

[edit] Projecting data onto a mesh

If you have segmented an anatomy in mrGray, you can visualize a mesh for that anatomy, and project overlays onto the mesh, without needing to initialize your data in mrVista. Instructions are on the Mesh page.

[edit] Storing and Retrieving Mesh View Settings

The angle, zoom level, and lighting conditions used when viewing a mesh can be automatically stored and retrieved using the set of controls in the middle of the mesh panel. These settings are saved in a file named 'MeshSettings.mat', which is kept in the same directory as the currently displayed mesh. To load the contents from a pre-existing file, select 'File' | 'Load' | 'Mesh Settings From File'. A list of presets will be displayed in the listbox. The four buttons underneath allow you to store, retrieve, rename, and delete settings from this list.

[edit] Overlay Panels

mrViewer can load MR data as 'maps' which are displayed on top of the base MR image (which is usually an anatomy and referred to as the underlay). If at least one map is loaded, mrViewer can open one or more overlays, in which data from a given map is shown, after applying a series of thresholds. The overlay panels provide the ability to determine how overlays are placed on top of the underlay.

[edit] Loading maps

Maps may be loaded by using the menu 'File' | 'Load' | 'MR Map...'. Any file that may be loaded by mrViewer may also be loaded as a map, provided the relationship between the map and underlay files can be determined (see Coordinate Spaces below).

[edit] Overlay panel layout

The first time a map is loaded, an overlay is automatically added to the viewer, and a new overlay panel is created. Additional overlays may be added or removed using the menu option 'View' | 'Overlay' | 'Add' or 'Remove'. For each overlay image, a separte overlay panel is created.

At the top of each panel is a popup listing all currently-loaded maps, for determining which data are displayed for this overlay. Underneath is a list of pre-set colormaps to use for the overlay. Custom colormaps can be selected by choosing the 'user' option in this popup, or else by right-clicking on the colorbar for the overlay and selecting the 'Edit...' context menu.

Beneath the color map selection is a setting for the 'color limits' or 'clip mode' of the overlay. This is an important parameter which determines how data values in the overlay are mapped to colors in the colormap. By default, the 'clim' property of an overlay is set to 'auto', meaning that, for the given values of an overlay being displayed in the viewer, the minimum value above threshold will map to the first entry of the colormap, and the max value will map to the last entry. However, for comparing many displays, it is often helpful to set manual limits on the clim property. To do this, select 'Manual' on the popup. Two new edit fieds will become visible, allowing you to determine the minimum and maximum values in the overlay. You may also programmatically set this property by setting mrViewSetOverlay(viewerHandle, 'Clim', [color lim value], [overlay #]) .

Beneath the color map options are threshold options. You may use zero through three threshold criteria for determining whether a given voxel in an overlay is displayed on top of the anatomy (more are possible by editing the 'ui' matlab struct directly).

[edit] Multiple Overlays: Dealing with Overlap

mrViewer places no limit on the number of overlays that may be displayed. (Although additional overlays can make the screen refreshes take much more time). There are also several options for dealing with regions which have multiple overlays displayed on top of each other. These options can be modified by the menu Edit | Preferences (Ctrl-comma), or by setting the preference setpref('VISTA', 'alphaMethod', [value]). The three values for the alphaMethod are:

  1. Average If a voxel has two overlays displayed, the color of that voxel will be the [R G B] average of the colors of each separate overlay. So, if one overlay would make a voxel blue -- [R G B] = [0 0 1] -- and another would make it red/purple -- [1 0 .2] -- the combined color will be [.5 0 .6]. This is the default behavior.
  2. Add and saturate The color values for two overlays combine together, maxing out at [1 1 1] or white. For instance, for two overlay colors [0 0 1] and [1 0 .2], the combined color would be [1 0 1]. Using this method and binary colormaps for each overlay can effectively show overlaps between two maps (e.g. using 'red binary' and 'green binary' will show overlap in yellow).
  3. Opaque Later overlays lay on top of, and obscure, earlier overlays. For instance, if overlay one is [0 0 1] and overlay 2 is [1 0 .2], the combined color will just be overlay 2: [1 0 .2].

[edit] Coordinate Spaces

An important aspect of mrViewer is the idea that data may be viewed according to many possible sets of coordinates. For instance, an anatomical image may displayed:

  1. according to the order in which data were collected ("Pixel Space"),
  2. in the same orientation but resampled to real-world units like millimeters ("Raw data in mm"),
  3. according to the real-world directions in the scanner in which the data were collected, revealing how the subject's head was positioned ("scanner space")
  4. rigid-body rotated such that the anterior commisure is (0, 0, 0)("AC/PC space"),
  5. flipped left/right according to neurological or radiological conventions,
  6. nonlinearly transformed to a standardized coordinate space such as Talairach space ("Talairach")

among a number of possibilities.

An overall goal of mrViewer is to allow these transformations to be done on-the-fly, without requiring a new data file to be created for each one. It is hoped that this will reduce on the number of confusing equivalent files of the same image, and retain as much information as possible about different units in each data file saved. This aspect is also discussed in the 'mr' data file page (soon to be added).

When a data file is loaded by mrViewer, as much information is extracted from the header files as possible, to allow these transformations to be used. Additional transforms may be provided by using the mrRx coregistration tool. (On-the-fly Talairaching is almost implemented, but not there just yet).

All loaded coordinate spaces are accessible under the 'Coordinates' menu in the main mrViewer display. If displaying data in a coordinate space other than the raw pixel space, the displayed slices are interpolated according to the transform information. The manner in which this transform is computed can be set using the menu 'Edit' | 'Preferences'. Currently, nearest-neighbor, linear, and bicubic methods are available. The interpolation method for the underlay image and the overlays may be specified separately.

[edit] Screenshots

MrViewer screen shot.png

Personal tools