Get Started with Medical Volume Viewer

R2026b

Since R2026a

The Medical Volume Viewer app enables you to visualize 3-D medical image volumes, including label data and multimodal overlays. You can explore volumes in 3-D or as 2-D slice planes, apply and customize transparency and colormaps, and view multimodal images, such as CT and PET, together as an overlay. You can publish 2-D and 3-D snapshots and animations, and export display settings to apply outside the app.

This tutorial provides an overview of the capabilities of the Medical Volume Viewer.

Open Medical Volume Viewer App

Open the Medical Volume Viewer app from the Apps tab on the MATLAB^® Toolstrip, under Image Processing and Computer Vision. You can also load the app by using the medicalVolumeViewer command. At any time, you can start a new app session by selecting New Session in the app toolstrip. When you create a new session, this option deletes all the data currently in the app.

Import Data

You have several options for importing data. Choose the option that is convenient for you while including any metadata available from the original data source. For example, import a DICOM volume from the file, or from a medicalVolume object created from the file, rather than a 3-D numeric array containing only the voxel data. If you specify a file with limited metadata, such as a TIFF file, or a 3-D numeric array of voxel values without metadata, the app assumes default spatial referencing with voxel spacing of 1-by-1-by-1 millimeters, with the first voxel located at (1, 1, 1). The app also hides anatomical plane and direction labels.

Import Volumes Without Labels

To import unlabeled volumes into the app interactively, select Import from the Viewer tab of the app toolstrip and, under Data, select one of these options:

From File — Import NIfTI, NRRD, TIFF, DICOM, or MAT files. Each DICOM file must contain a complete volume. Each MAT file must contain a medicalVolume object or a 3-D numeric array.
From DICOM Folder — Import a folder of DICOM files that define one multi-file volume.
From Workspace — Import a medicalVolume object or a 3-D numeric array of voxel data.

Alternatively, to import an unlabeled volume programmatically, use the syntax medicalVolumeViewer(volume), where volume is a filename, DICOM folder name, medicalVolume object, or 3-D numeric array.

Import Volumes with Labels

To import a labeled volume into the app interactively, select Import from the Viewer tab of the app toolstrip and select one of these options.

Under Ground Truth, select From File — Import a MAT file that contains a groundTruthMedical object specifying the label definitions and paths to the volume and label data.
Under Ground Truth, select From Workspace — Import a groundTruthMedical object from the workspace.
Select Labels — Import labels and volume data using an interactive dialog box. In the Import Labels dialog box, select whether to import the label data from a file or from a workspace variable. Label data files can be in the NIfTI, DICOM, NRRD, or MAT format. A DICOM file must contain a complete volume. A MAT file must contain a medicalVolume object or a 3-D numeric array. If you choose to import labels from the workspace, you can pick a medicalVolume object or 3-D numeric array from the drop-down list in the Labels section. The dialog box also contains a Volume Data for Label section, in which you can optionally specify a volume to associate with the labels. If you specify a file or workspace variable, the app imports the volume with the labels. If you specify a volume already in the Data Browser, the app imports the labels and associates them with the existing copy of the volume.

For example, this image shows how to use the Labels option to import a CT volume and its labels from the workspace.

Medical Volume Viewer app window, showing options for importing volumes with and without labels, including using the Import Labels dialog box

Alternatively, to import a labeled volume programmatically, use the syntax medicalVolumeViewer(volume,labels) or medicalVolumeViewer(gTruth), where volume specifies a volume, labels specifies label data, and gTruth specifies a groundTruthMedical object in the workspace or a file that contains a groundTruthMedical object.

Organize Volumes and Labels

The Data Browser enables you to view and organize the volumes and labels loaded in an app session. The browser indicates volumes using the volume icon. All labels associated with a volume are in a collapsible list and are indicated using the label icon . To toggle the visibility of a volume or label, click the eye icon next to the filename. If you make multiple volumes visible, the app displays them as an overlay. You can delete a volume or label image from the app by right-clicking the name in the browser and selecting Delete Entry. You can categorize related volumes, such as all scans per patient or time point, using groups. By default, the app adds all volumes to Group 1. To create a new group, select Add Group. Drag filenames to move volumes between groups. You can rename a group by double-clicking the group name and typing a new name. The appearance of the app depends on whether a volume or label is selected in the browser. For example, selecting a label image makes the Labels pane and the Label Opacity slider visible, and selecting a volume makes the Window Level and Rendering Editor buttons visible.

The Labels pane displays the name and color of each label present in the visible label files. By default, the app uses standardized display colors and numbered label names starting with Label1. If you have a label definitions file for your label data with custom names and colors, which you can export from the Medical Image Labeler app, you can import it by selecting the plus icon. You can change the display color of individual labels by double-clicking the Color column for that label and selecting a new color in the dialog box. You can toggle the visibility of individual labels by clicking the eye icon in the corresponding row of the Show/Hide column.

Medical Volume Viewer app window showing the Data Browser and Labels panes with options for viewing, hiding, and organizing data

Explore Volume Data

The app displays volumes as 2-D slice planes and a 3-D volume in a four-pane view. The 2-D slices are displayed in the Transverse, Sagittal, and Coronal planes. Labels in the bottom-left corner of each slice pane indicate the slice position in world coordinates, the current slice number, and the total number of slices in that dimension. When you display multiple volumes or labels as an overlay, the app hides the slice numbers and shows only the position values. The bottom of the app window displays information about the pixel beneath the pointer, including its coordinates and intensity.

View 2-D Slices

To explore the volume, zoom in on a slice pane using the scroll wheel or the zoom controls in the top-right corner of the slice. Navigate between slices by using the scroll bar in each of the 2-D slice panes. You can also adjust these display settings in the Viewer tab of the app toolstrip:

Window Level — Change the brightness or contrast of the image. To update the display window, you can directly edit the values in the Window Level and Window Width boxes in the app toolstrip. Alternatively, adjust the window using the Window Level tool. First, select the window level button in the app toolstrip. Then, drag up and down in a 2-D view pane to increase and decrease the brightness, respectively, or left and right to increase and decrease the contrast for all of the 2-D views. Clear the window level button to deactivate the tool. To apply window level changes to all volumes within the same group in the Data Browser, select Apply to Group. To reset the brightness and contrast, click Window Level and select Reset.
Crosshair Navigation — To navigate between slices, select Crosshair Navigation and drag the crosshairs to a new position. The other slice views update automatically.
Display Markers — Toggle the visibility of 2-D and 3-D display markers. By default, the app displays anatomical display markers indicating the anterior (A), posterior (P), left (L), right (R), superior (S), and inferior (I) directions. If your volume has incomplete or oblique spatial metadata, the app displays the volume without anatomical labels. Under Display Markers, you can add scale bars to the 2-D slice views.
Preferences — By default, the app displays volumes using the Radiological display convention, with the left side of the patient on the right side of the image. To display the left side of the patient on the left side of the image, on the app toolstrip, click Preferences, and in the dialog box that opens, change Convention to Neurological.

Medical Volume Viewer window with labels showing display markers in the 2-D slice panes and toolstrip options for the 2-D display

View 3-D Volume

In the 3-D Volume pane, you can zoom using the scroll wheel or rotate the volume about its center by dragging it. You can also adjust these display settings in the app toolstrip:

Display Markers — By default, the orientation axes in the bottom-left corner indicate the spatial orientation of the volume. The scale bar in the bottom-right corner provides an indication of the volume size. To toggle the visibility of the orientation axes and scale bar, select Display Markers in the Viewer tab of the app toolstrip and select or clear the 3-D Orientation Axes and Scale Bars options under 3-D Volume, respectively.
Background — From the Render tab of the app toolstrip, you can change the background color of the 3-D volume pane by selecting Background Color and selecting a color. Clear or select the Use Background Gradient box to toggle the visibility of the background gradient. To change the gradient color, select Gradient Color and select a color.

Medical Volume Viewer window with labels showing display markers in the 3-D volume pane and toolstrip options for the 3-D display background

Refine Display

This part of the tutorial describes how to modify the appearance of the data. Using the app, you can:

Apply preset styles that apply transparency and colormaps that work well for medical data.
Change the rendering technique for the 3-D volume.
Modify the preset rendering styles by interactively modifying the intensity-opacity curve and color bar scale.
Control the visibility and color of label data.

Apply Rendering Preset

The app provides several built-in rendering presets that apply alphamaps and colormaps that work well with medical images, such as CT-Bone, MRI, and PET. To apply a preset to the currently selected volume, in the Render tab of the app toolstrip, select an option from the Rendering Presets gallery.

By default, the preset applies only to the 3-D Volume display pane. You can optionally apply the preset to the 2-D slices by opening the Rendering Editor from the app toolstrip and, under Alphamap and Colormap, selecting Apply to slices. Otherwise, the slices display with a grayscale colormap and a constant transparency that you can modify by using the Slice Opacity slider on the Viewer tab of the app toolstrip.

Apply a rendering preset to the 3-D display from the gallery, and optionally apply presets to 2-D slices from the Rendering Editor

Choose Rendering Technique

You can adjust the appearance of the 3-D Volume pane by changing the rendering technique in the Rendering Editor. To open the editor, in the Render tab of the app toolstrip, click Rendering Editor. You can choose one of these options.

Volume Rendering — View the volume based on the color and transparency for each voxel, as specified by the colormap and alphamap.
Cinematic Rendering — View the volume based on the specified color and transparency for each voxel, with iterative postprocessing that produces photorealistic shadows and lighting. This technique is useful for displaying opaque volumes, but can take longer to render.
Minimum Intensity Projection — View the voxel with the smallest intensity value for each ray projected through the data.
Maximum Intensity Projection — View the voxel with the largest intensity value for each ray projected through the data. This technique can be useful for revealing the highest-intensity structure within a volume.
Gradient Opacity — View the volume based on the specified color and transparency, with an additional transparency applied if the voxel is similar in intensity to the previous voxel along the ray projected through the data. When you render a volume with uniform intensity using this technique, the interior appears more transparent than when displayed using Volume Rendering, enabling better visualization of intensity gradients within the volume.
Isosurface — View the volume as an isosurface. The default isovalue is 0.5.
Slice Planes — View the volume as three orthogonal slice planes. You can change the position of each slice by pausing on a slice plane until it highlights, and then dragging it.

Customize Alphamap and Colormap

You can refine the preset alphamap and colormap for your data by modifying the intensity-opacity curve and colormap in the Rendering Editor.

In the Alphamap section, the intensity-opacity curve maps voxel intensity to opacity for points defined by circular sliders. For example, the alphamap for the Linear Grayscale preset has two circular sliders that map the minimum intensity to an opacity of 0 and the maximum intensity to an opacity of 1. The app interpolates opacity values for intensities between the circular sliders. You can add sliders by clicking the line plot. Change the intensity associated with a slider by dragging it left and right on the plot, or by selecting it and specifying a new value for Intensity. Change the opacity associated with a slider by dragging it up and down on the plot, or by selecting it and specifying a new value for Opacity.

In the Colormap section, the color bar scale maps voxel intensity to colors for points defined by circular sliders. For example, the Linear Grayscale preset maps the minimum intensity to black and the maximum intensity to white, interpolating colors between the sliders. You can refine the colormap by adding or editing sliders. Click the color bar to add a slider. Change the intensity of a slider by dragging it horizontally, or selecting it and specifying a new value for Intensity. You can change the mapping of a slider by clicking the Color box, selecting a new color from the Color dialog box, then clicking OK. The color under the intensity-opacity plot updates to reflect the updated colormap.

Customize the rendering technique, alphamap, and colormap in the Rendering Editor

To save your customized settings, in the Render tab of the app toolstrip, click Save Rendering . The app adds an icon for your custom preset to the gallery in the Rendering Presets section of the app toolstrip, under User Defined. You can apply the same preset or custom rendering settings to all volumes in a Data Browser group by clicking Apply To Group in the app toolstrip. To discard your customizations, select Restore Rendering.

Annotate and Measure Volume

Use annotations to explore your data and collect measurements that you can export for further analysis in MATLAB. Each annotation represents a geometric shape, such as a point, line, polygon, or cuboid, and can display a corresponding measurement value, such as distance, angle, area, or volume, or a custom text label you specify. You can view annotations in 2-D slice views and in the 3-D volume.

This table lists the measurement tools available in the Measure tab of the app toolstrip. Measurements are in world coordinates and in units specified in the volume metadata, when available.

Annotation	Description	Create and Edit
Location	Measure the coordinates of a selected point, or label a landmark with a custom text label	Click a 2-D slice to place the point. After you place a point, drag to reposition it.
Distance	Measure the distance between two points by drawing a line	Click a 2-D slice to place each end point. Hold Shift while you draw to make the line snap at 15 degree angles. After you draw a line, drag an endpoint to reposition it. To reposition the line, drag the line or hold Ctrl while you drag one of the endpoints.
Angle	Measure the angle between two lines in degrees	Click a 2-D slice to place the vertex of the angle, then click to place the endpoints that define the rays of the angle. Hold Shift while you draw to make lines snap at 15 degree angles. To resize the angle, drag the vertex or endpoints. To move the angle, hold Ctrl while you drag.
Area, Perimeter	Measure the area and perimeter of an object by drawing a polygon around it	Click a 2-D slice to place vertices. Double-click the last vertex to complete the polygon. Hold Shift while you draw to make lines snap at 15 degree angles. After you draw a polygon, reshape it by dragging a vertex. Double-click an edge to add a new vertex. Double-click an existing vertex to remove it. To move a polygon without reshaping it, hold Ctrl and drag the polygon.
Volume	Measure the volume of a cuboid you draw around an object	Click on the 3-D volume to place a cuboid. Use the interactive axes and orbit indicators to resize, move, and rotate the cuboid after you place it. Drag the shaded rectangle or point indicators to translate or resize the cuboid along a dimension, respectively. Click and drag along an orbit to rotate the cuboid.

Each annotation has a label and a value. By default, the label indicates the measurement type, such as location or distance. From the table in the Measurements pane, you can specify a custom label for an annotation, as well as toggle its visibility, change its color, or delete it. To specify a custom label, double-click the name in the first column of the table and type the new name. To toggle the visibility of just the label or just the value for one annotation, right-click the row in the table and select Hide Label or Hide Value. From the Measure tab of the app toolstrip, you can toggle the visibility of all measurement labels or all values.

To export measurement values to the workspace, from the Viewer tab of the app toolstrip, click Export and, under Measurements, select To Workspace. In the dialog box, optionally specify a name for the variable to export, and click OK. The app exports a structure with fields defining details such as the label, value, position, and color. You can import previously exported measurements in a future app session using the Import menu in the app toolstrip.

Export Snapshot Images

You can export snapshot images of 2-D and 3-D views to use outside the app. In the Viewer tab of the app toolstrip, select Export > Slices. In the Export Slices dialog box, select the views you want to export, choose whether to save images as PNG images or a PDF, and click Export. In the next dialog box, specify the location where you want to save the images. If you export images, you must specify a folder, as each snapshot is saved as a separate PNG file. If you export a PDF, you must specify a filename, as the slices are published in a single document.

Export Animations

You can generate 2-D animations that scroll through transverse, sagittal, or coronal slices, or 3-D animations of the volume rotating about a specified axis. To open the animation generator tool, in the Viewer tab of the app toolstrip, click Generate Animations. Then, in the Animations pane, select 2-D slices or 3-D Volume and specify the parameters for the animation to generate. To learn more, see Generate Animations of Medical Image Volume Data Using Apps.

Export Rendering Settings

After working in Medical Volume Viewer to achieve the best view of your data, you can save your rendering settings and camera configuration to the workspace. You can apply the saved settings to recreate the view you achieved in Medical Volume Viewer by using them to set properties of the objects created by the viewer3d and volshow functions.

To save rendering and camera configuration settings, in the Viewer tab of the app toolstrip, click Export and, under Viewer3d Settings, select To Workspace. Medical Volume Viewer creates separate structures for the settings of objects created by viewer3d and volshow. You can choose which structures to create, and either specify their names or accept the default names sceneConfig and objectConfig, respectively. When you are ready to export, click OK.

Export To Workspace dialog box

You can apply the rendering settings outside the app by using them to set properties of the objects created by viewer3d and volshow. For example, this code snippet displays a medicalVolume object ctVol in the Viewer object viewer, and applies the rendering and camera settings. The new display has the same colormap, alphamap, rendering style, background color and gradient, and camera position as the 3-D Volume pane had when you exported the settings.

viewer = viewer3d;
Volume = volshow(ctVol,Parent=viewer, ...
DisplayRangeMode="data-range", ...
OverlayData=labelVol.Voxels);

fields = fieldnames(objectConfig);
for i = 1:numel(fields)
    Volume.(fields{i}) = objectConfig.(fields{i});
end

fields = fieldnames(sceneConfig);
for i = 1:numel(fields)
viewer.(fields{i}) = sceneConfig.(fields{i});
end

References

[1] Medical Segmentation Decathlon. "Lung." Tasks. Accessed May 10, 2018. http://medicaldecathlon.com. The Lung data set is provided by the Medical Segmentation Decathlon under the CC-BY-SA 4.0 license. All warranties and representations are disclaimed.