volshow

Display volume

Syntax

vol = volshow(V)

vol = volshow(V,config)

vol = volshow(V,Name=Value)

bVol = volshow(bim)

bVol = volshow(bim,Name=Value)

Description

Numeric Array

vol = volshow(V) creates a Volume object that displays the 3-D grayscale, RGB, or binary volume V. You can rotate and zoom in and out on the display interactively using the mouse. Use vol to query and modify properties of the Volume object after you create the object. For a list of properties, see Volume Properties.

vol = volshow(V,config) displays the 3-D volume V using the values of the Volume object properties specified by the config structure.

vol = volshow(V,Name=Value) specifies one or more property values that modify the appearance of the volume using name-value arguments. For example, volshow(V,RenderingStyle="Isosurface") displays the 3-D volume V and sets the rendering style as "Isosurface". For a list of properties, see Volume Properties.

Blocked Image Volume

Since R2023a

bVol = volshow(bim) creates a BlockedVolume object that displays the 3-D blocked image bim. You can rotate and zoom in and out on the display interactively using the mouse. Use bVol to query and modify properties of the BlockedVolume object after you create the object. For a list of properties, see BlockedVolume Properties.

bVol = volshow(bim,Name=Value) specifies one or more property values that modify the appearance of the blocked volume using name-value arguments. For example, ResolutionLevel="coarse" specifies the resolution level to display as the coarsest resolution level. For a list of properties, see BlockedVolume Properties.

Note

Medical Imaging Toolbox™ extends the functionality of the volshow (Image Processing Toolbox™) function to display a medicalVolume (Medical Imaging Toolbox) object in the patient coordinate system. For more information, see volshow (Medical Imaging Toolbox).

Examples

Visualize Volume of MRI Data

Load MRI data into the workspace and remove the singleton dimension.

load mri
V = squeeze(D);

Generate a colormap and transparency (alpha) map suitable for MRI images.

intensity = [0 20 40 120 220 1024];
alpha = [0 0 0.15 0.3 0.38 0.5];
color = [0 0 0; 43 0 0; 103 37 20; 199 155 97; 216 213 201; 255 255 255]/255;
queryPoints = linspace(min(intensity),max(intensity),256);
alphamap = interp1(intensity,alpha,queryPoints)';
colormap = interp1(intensity,color,queryPoints);

This MRI scan has a non-uniform, or anisotropic, voxel size of 1-by-1-by-2.5 mm. Specify the transformation matrix that scales the image to the correct voxel dimensions.

sx = 1;
sy= 1;
sz = 2.5;
A = [sx 0 0 0; 0 sy 0 0; 0 0 sz 0; 0 0 0 1];

Create an affinetform3d object that performs the scaling.

tform = affinetform3d(A);

View the volume with the custom colormap, transparency map, and transformation. Drag the mouse to rotate the volume. Use the scroll wheel to zoom in and out of the volume.

vol = volshow(V,Colormap=colormap,Alphamap=alphamap,Transformation=tform);

Visualize Photorealistic Volume Using Cinematic Rendering

This example uses a subset of the Medical Segmentation Decathlon data set [1]. The subset of data includes two CT chest volumes and corresponding label images, stored in the NIfTI file format.

Run this code to download the MedicalVolumNIfTIData.zip file from the MathWorks® website, then unzip the file. The size of the data file is approximately 76 MB.

zipFile = matlab.internal.examples.downloadSupportFile("medical", ...
    "MedicalVolumeNIfTIData.zip");
filepath = fileparts(zipFile);
unzip(zipFile,filepath)

The folder dataFolder contains the downloaded and unzipped data.

dataFolder = fullfile(filepath,"MedicalVolumeNIfTIData");

Specify the filenames of the volume and label image used in this example.

dataFile = fullfile(dataFolder,"lung_043.nii.gz");
labelDataFile = fullfile(dataFolder,"LabelData","lung_043.nii.gz");

Read the image data and the metadata from the image file.

V = niftiread(dataFile);
info = niftiinfo(dataFile);

Define a transparency map and color map for this volume. The values used in this example were determined using manual trial and error.

alpha = [0 0 0.7 1.0];
color = [0 0 0; 200 140 75; 231 208 141; 255 255 255] ./ 255;
intensity = [-3024 -700 -400 3071];
queryPoints = linspace(min(intensity),max(intensity),256);
alphamap = interp1(intensity,alpha,queryPoints)';
colormap = interp1(intensity,color,queryPoints);

This MRI scan has a nonuniform, or anisotropic, voxel size. Extract the voxel spacing from the file metadata, and define the transformation to display the volume with correct dimensions.

voxelSize = info.PixelDimensions;
sx = voxelSize(2);
sy= voxelSize(1);
sz = voxelSize(3);
A = [sx 0 0 0; 0 sy 0 0; 0 0 sz 0; 0 0 0 1];

Create an affinetform3d object that performs the scaling.

tform = affinetform3d(A);

View the volume as a 3-D object. Specify the rendering style as "CinematicRendering". The cinematic rendering style displays the volume based on the specified color and transparency for each voxel, with iterative postprocessing that produces photorealistic shadows and lighting.

viewer = viewer3d;
vol = volshow(V,Parent=viewer, ...
    RenderingStyle="CinematicRendering", ...
    Colormap=colormap, ...
    Alphamap=alphamap, ...
    Transformation=tform);

References

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

Visualize RGB Volume

Create an RGB volume of red, green, and blue bubbles by using the createRGBBubbles helper function. The helper function is attached to this example as a supporting file.

RGB = createRGBBubbles;

Create a viewer with a black background and a gray background gradient. Display the RGB volume in the viewer.

viewer = viewer3d(BackgroundColor=[0 0 0],GradientColor=[0.2 0.2 0.2]);
vol = volshow(RGB,Parent=viewer,RenderingStyle="GradientOpacity");

By default, volshow displays the transparency for each voxel by mapping its lightness to the Alphamap property. The lightness of a voxel is similar to the output of the rgb2lightness function for 2-D images.

Alternatively, you can specify a custom alpha channel by using the AlphaData property. If you have an RGBA volume, extract the fourth channel by using array indexing and specify the channel as the AlphaData value. For this volume, create an artificial alpha channel of the same size as the volume. The artificial channel is fully transparent for the voxel at the origin and the opacity increases as the distance between the origin and each voxel increases.

sz = 500;
val = linspace(0,1,sz);
[X,Y,Z] = meshgrid(val,val,val);
alpha = X.*Y.*Z;

vol.AlphaData = alpha;

Create Animation of Rotating Volume

Load a grayscale volume into the workspace and display the volume using volshow.

load("spiralVol.mat")
h = volshow(spiralVol);
viewer = h.Parent;
hFig = viewer.Parent;
drawnow

Specify the name of the GIF file in which to save the animation.

filename = "animatedSpiral.gif";

Aim the camera at the center of the volume.

sz = size(spiralVol);
center = sz/2 + 0.5;
viewer.CameraTarget = center;

Specify the number of frames in the animation, then create an array of camera positions in a circle around the center of the volume.

numberOfFrames = 12;
vec = linspace(0,2*pi,numberOfFrames)';
dist = sqrt(sz(1)^2 + sz(2)^2 + sz(3)^2);
myPosition = center + ([cos(vec) sin(vec) ones(size(vec))]*dist);

At each camera position, update the display and write the frame to the GIF file. You can play the file in a video viewer.

for idx = 1:length(vec)
    % Update the current view
    viewer.CameraPosition = myPosition(idx,:);
    % Capture the image using the getframe function
    I = getframe(hFig);
    [indI,cm] = rgb2ind(I.cdata,256);
    % Write the frame to the GIF file
    if idx==1
        % Do nothing. The first frame displays only the viewer, not the
        % volume.
    elseif idx == 2
        imwrite(indI,cm,filename,"gif",Loopcount=inf,DelayTime=0)
    else
        imwrite(indI,cm,filename,"gif",WriteMode="append",DelayTime=0)
    end
end

Visualize Blocked Image Volume

This example creates a large 500-by-500-by-2500 image volume. If your machine does not have enough memory to create and store the 2.5 GB volume, decrease imSize before running this example.

imSize = [500,500,2500];

Create a simulated 3-D image of bubbles, V. This can take several minutes.

V = rand(imSize,"single");
BW = false(size(V));
BW(V < 0.000001) = true;
V = bwdist(BW);
V(V <= 20) = 1;
V(V > 20) = 0;

If you try to display V directly, volshow returns an error that the volume is too large. Instead, create a blockedImage object that points to V and has a block size of 500-by-500-by-500 voxels.

bim = blockedImage(V,BlockSize=[500,500,500]);

Display the blockedImage using volshow. The volshow function reads blocks into memory one at a time and stitches individual block renderings to produce the final volume.

bVol = volshow(bim);

Input Arguments

V — Grayscale, RGB, or binary 3-D volume

m-by-n-by-p numeric array | m-by-n-by-p-by-3 numeric array | m-by-n-by-p logical array

Grayscale, RGB, or binary 3-D volume, specified as one of these options:

Volume Type	Description
Grayscale	Specify as an m-by-n-by-p numeric array with non-singleton dimensions.
RGB	Specify as an m-by-n-by-p-by-3 numeric array with non-singleton dimensions. If your data is an RGBA volume, you can specify the transparency channel by using the AlphaData property.
Binary	Specify as an m-by-n-by-p logical array with non-singleton dimensions.

If your image volume is large and might not fit in memory, or is already in the blockedImage object format, specify the bim argument.

Data Types: single | double | int8 | int16 | int32 | uint8 | uint16 | uint32 | logical

config — Rendering information

structure

Rendering information exported by Volume Viewer, specified as a structure.

Data Types: struct

bim — Blocked image volume

blockedImage object

Blocked image volume, specified as a blockedImage object that reads 3-D blocks of grayscale, RGB, or RGBA data. The blocked image can have a single resolution level or multiple resolution levels.

Name-Value Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Example: volshow(V,RenderingStyle="Isosurface") displays the 3-D volume V and sets the rendering style as "Isosurface".

Note

The properties listed here are only a subset. For a full list of in-memory volume properties, see Volume Properties. For a full list of blocked volume properties, see BlockedVolume Properties.

Parent — Parent

Viewer object

Parent of the Volume or BlockedVolume object, specified as a Viewer object. You can create a Viewer object using the viewer3d function. When you call volshow without specifying a parent, the function creates a new Viewer object and sets that object as the parent. A Volume or BlockedVolume object cannot be reparented.

RenderingStyle — Rendering style

"VolumeRendering" (default) | "CinematicRendering" | "LightScattering" | "MaximumIntensityProjection" | "MinimumIntensityProjection" | "GradientOpacity" | "Isosurface" | "SlicePlanes"

Rendering style, specified as one of the values in the table.

Value	Description
"VolumeRendering"	View the volume based on the specified color and transparency for each voxel.
"CinematicRendering"	View the volume based on the specified color and transparency for each voxel, with iterative postprocessing that produces photorealistic shadows and lighting. This rendering style is useful for displaying opaque volumes.
"LightScattering"	View the volume using a volumetric light scattering model that simulates the absorption, inscattering, and outscattering of light through the volume. This rendering style is useful for displaying translucent volumes that do not have large intensity gradients, such as smoke, fog, and clouds.
"MaximumIntensityProjection"	View the voxel with the largest intensity value for each ray projected through the data. For RGB volumes, view the voxel with the largest luminance in the CIE 1976 L*a*b* color space.
"MinimumIntensityProjection"	View the voxel with the smallest intensity value for each ray projected through the data. For RGB volumes, view the voxel with the smallest luminance in the CIE 1976 L*a*b* color space.
"GradientOpacity"	View the volume based on the specified color and transparency with an additional transparency applied if the voxel is similar in intensity (for grayscale volumes) or luminance (for RGB volumes) to the previous voxel along the viewing ray. When a volume with uniform intensity is rendered using "GradientOpacity", the internal portion of the volume appears more transparent than the "VolumeRendering" rendering style, enabling better visualization of the intensity or luminance gradients in the volume.
"Isosurface"	View an isosurface of the volume specified by the value in the IsosurfaceValue property.
"SlicePlanes"	View three orthogonal slice planes.

Transformation — Transformation applied to volume

affinetform3d object | rigidtform3d object | simtform3d object | transltform3d object

Transformation applied to the volume in the 3-D scene, specified as an affinetform3d, rigidtform3d, simtform3d, or transltform3d object. Use the Transformation property to increase the size of the volume, rotate the volume, or perform other affine transformations. The default value is an affinetform3d object that performs an identity transformation.

Alphamap — Transparency map for volume

"cubic" (default) | "linear" | "quadratic" | n-element column vector

Transparency map for the volume, specified as one of the values in the table.

The DisplayRange property determines how the values of V map to the transparency map. Values less than or equal to the minimum value of the DisplayRange map to the first value of the transparency range, and all values greater than or equal to the maximum value of the DisplayRange map to the last value of the transparency range.

When the AlphaData property is nonempty, the Alphamap value has no effect.

Value	Description
"linear" (since R2024b)	Values in Data map linearly to transparencies in the range [0, 1].
"quadratic" (since R2024b)	Values in Data map quadratically to transparencies in the range [0, 1]. This option applies a more rapid change in transparency between low and high values of Data compared to "linear".
"cubic" (since R2024b)	Values in Data map cubically to transparencies in the range [0, 1]. This option is the default value, and applies the most rapid change in transparency between low and high values of Data.
n-element column vector with values in the range [0, 1]	Values in Data map linearly to the transparency values in Alphamap.

Colormap — Colormap

gray(256) (default) | n-by-3 numeric matrix

Colormap of grayscale volume data, specified as an n-by-3 numeric matrix with values in the range [0, 1]. The maximum number of colors n is 256. This property has no effect when viewing RGB volumes.

OverlayData — Overlay data

[] (default) | numeric array | blockedImage object

Overlay data to blend with the object data during rendering, specified as one of these values:

• When displaying an in-memory volumetric array, V, specify OverlayData as a numeric array.

• When displaying a blocked image volume, bim, specify OverlayData as a blockedImage object that reads blocks of 3-D grayscale data.

The viewer shows the overlay only when the RenderingStyle property value is "SlicePlanes", "VolumeRendering", or "GradientOpacity". You can modify the appearance of the overlay by changing the OverlayRenderingStyle, OverlayColormap, and OverlayAlphamap properties.

OverlayRenderingStyle — Overlay rendering style

"LabelOverlay" (default) | "VolumeOverlay" | "GradientOverlay"

Overlay rendering style, specified as one of the values in the table.

Value	Description
"LabelOverlay"	View the overlay based on the color and transparency of each labeled region. Use this rendering style to visualize ordinal data, like binary or semantic segmentation results, on top of your data.
"VolumeOverlay"	View the overlay based on the specified color and transparency for each voxel.
"GradientOverlay"	View the overlay based on the color and transparency for each voxel with an additional transparency applied based on the difference between the current voxel and the previous voxel along the viewing ray.

Output Arguments

vol — Volume

Volume object

Volume, returned as a Volume object. For more information about modifying aspects of the volume, see Volume Properties.

bVol — Blocked volume

BlockedVolume object

Blocked volume, returned as a BlockedVolume object. For more information about modifying aspects of the volume, see BlockedVolume Properties.

More About

Events

To receive notification from a Volume or BlockedVolume object when certain events happen, set up listeners for these events. You can specify a callback function that executes when one of these events occurs. When the object notifies your application through the listener, it returns data specific to the event. Look at the event class for the specific event to see what is returned.

Event Name	Trigger	Event Data	Event Attributes
ClippingPlanesChanging	An object clipping plane is being interactively moved. This event does not execute if the clipping plane is programmatically moved.	images.ui.graphics.events.ClippingPlanesChangedEventData	NotifyAccess: private ListenAccess: public
ClippingPlanesChanged	An object clipping plane stops being interactively moved. This event does not execute if the clipping plane is programmatically moved.	images.ui.graphics.events.ClippingPlanesChangedEventData	NotifyAccess: private ListenAccess: public
SlicePlanesChanging	An object slice plane is being interactively moved. This event does not execute if the slice plane is programmatically moved.	images.ui.graphics.events.SlicePlanesChangedEventData	NotifyAccess: private ListenAccess: public
SlicePlanesChanged	An object slice plane stops being interactively moved. This event does not execute if the slice plane is programmatically moved.	images.ui.graphics.events.SlicePlanesChangedEventData	NotifyAccess: private ListenAccess: public
DataReadStarted	A BlockedVolume object is sending blocks of data to be rendered in the scene. This event is not applicable for Volume objects.	event.EventData	NotifyAccess: private ListenAccess: public
DataReadFinished	The BlockedVolume object has finished sending all blocks of data that are visible in the scene. This event is not applicable for Volume objects.	event.EventData	NotifyAccess: private ListenAccess: public

Tips

• To refresh a volume display efficiently, update properties of the Volume object returned by volshow instead of repeatedly calling the volshow function. For example, refresh the volume and overlay data by updating the Data and OverlayData properties, respectively, using dot notation. Updating an existing display avoids the memory and performance cost of creating a new parent viewer. Updating the data also preserves other settings that control the appearance of the scene, such as camera properties and the background color. This table compares approaches for updating the volume data in a volshow display.

  More Efficient	Less Efficient
  V = volshow(volIntensity); % Binarize the volume volBinary = volIntensity > 10; % Update the display to show the binary volume V.Data = volBinary;	volshow(volIntensity); % Binarize the volume volBinary = volIntensity > 10; % Create a new viewer and display the binary volume volshow(volBinary)

Version History

Introduced in R2018b

R2025a: Specify isosurface transparency, interpolation method, control whether viewer displays voxel information

As of R2025a, output Volume and BlockedVolume objects now include these properties:

• Control the transparency of volumes displayed as isosurfaces by using the new IsosurfaceAlpha property.

• Control the interpolation method for volume rendering by using the new Interpolation property.

• Control whether the parent viewer displays information about the voxel beneath the pointer by using the new Pickable property.

R2025a: New default alphamap

To better visualize the internal structure of most volumes, the default Alphamap property value has changed from "linear" to "cubic". This change affects the default appearance of volumes displayed using the volshow function. There is no requirement to update your code. To preserve the default appearance of previous releases, specify the Alphamap property value as "linear".

R2024b: Specify volume display range and transparency map

• Control the display range used to scale the volume by using the new DisplayRange and DisplayRangeMode properties.

• Control the display range used to scale the volume overlay by using the new OverlayDisplayRange and OverlayDisplayRangeMode properties.

• Specify a uniform transparency for all nonzero label values while hiding background labels by using the new OverlayAlpha property.

• For easier specification of transparency maps, the new options "linear", "quadratic", and "cubic" have been added for the Alphamap and OverlayAlphamap properties.

R2024b: New default colormap, OverlayThreshold not recommended

• To improve support for labeling workflows, the default OverlayColormap property value has changed from turbo(256) to a custom colormap that maximizes differences between adjacent colors. To apply the same colormap as in previous releases, specify the Colormap property as turbo(256).

• To apply a uniform transparency while hiding background labels, the new OverlayAlpha property is recommended over the OverlayThreshold property. There are no plans to remove support for existing instances of OverlayThreshold.

R2023b: Cinematic rendering, volumetric light scattering, and specular reflectance

The Volume object has new properties, and options for existing properties, to control the specular reflectance of the volume and display a volume using cinematic rendering or volumetric light scattering. To set any of these property values at object creation, specify them to the volshow function as name-value arguments.

• Control the amount of light reflected by a volume using the new SpecularReflectance property. Increase the specular reflectance to make a volume appear shinier.

• Specify the RenderingStyle property as "CinematicRendering" to display a photorealistic volume using iterative postprocessing. Specify the number of postprocessing iterations using the new CinematicNumIterations property.

• Specify the RenderingStyle property as "LightScattering" to display the volume with volumetric light scattering, including light absorption, inscattering, and outscattering. Specify the balance between rendering quality and speed using the new LightScatteringQuality property.

R2023a: Display blocked images

The volshow function now supports displaying large image volumes stored as a blockedImage object. When you pass a blockedImage object as input, volshow displays the volume and creates a BlockedVolume object. The BlockedVolume object properties control the appearance and behavior of the blocked image volume within a 3-D scene. For a list of these properties, see BlockedVolume Properties.

R2022b: Returns Volume object

The volshow function now returns a Volume object instead of a volshow object. The Volume object offers more rendering styles and integrates with a Viewer3D object to offer easier control of the volume visualization. The Volume object also supports web graphics.

The volshow function accepts a different set of name-value arguments based on the properties of the Volume object. For a list of these properties, see Volume Properties.

When you call volshow without specifying a parent object, the function now creates a new Viewer3D object and sets that object as the parent. Before, the function identified the current figure using the gcf function and set that figure as the parent.

If you want to reproduce the prior behavior, then use the images.compatibility.volshow.R2022a.volshow function to create a volshow object. Note that the images.compatibility.volshow.R2022a.volshow function and the volshow object will be removed in a future release.