volshow
Display volume
Syntax
Description
Numeric Array
creates a vol
= volshow(V
)Volume
object that displays the 3-D 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.
modifies the appearance of the volume using one or more name-value arguments. For example,
vol
= volshow(V
,Name=Value
)volshow(V,RenderingStyle="Isosurface")
displays the 3-D volume
V
and sets the rendering style as
"Isosurface"
.
Blocked Image Volume
Since R2023a
creates a bVol
= volshow(bim
)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.
modifies the appearance of the blocked volume using one or more name-value arguments. For
example, bVol
= volshow(bim
,Name=Value
)ResolutionLevel="coarse"
specifies the resolution level to
display as the coarsest resolution level.
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);
Pause to apply all postprocessing iterations before updating the display in Live Editor.
pause(3) drawnow
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.
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
— 3-D volume
numeric array
3-D volume, specified as a numeric array.
Data Types: single
| double
| int8
| int16
| int32
| uint8
| uint16
| uint32
| logical
| char
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
Viewer3D
object
Parent of the Volume
or BlockedVolume
object,
specified as a Viewer3D
object. You can create a Viewer3D
object
using the viewer3d
function. When you call volshow
without specifying a parent, the
function creates a new Viewer3D
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 |
"Isosurface" | View an isosurface of the volume specified by the value in the
|
"SlicePlanes" | View three orthogonal slice planes. |
Alphamap
— Transparency map for volume content
linspace(0,1,256)'
(default) | n-element column vector | "linear"
| "quadratic"
| "cubic"
Transparency map for the volume, specified as one of the values in the table.
The DisplayRange
property determines how values of
V
map to the transparency map. Values less than or equal to the
minimum of the DisplayRange
map to the first value of the
transparency range, and all values greater than or equal to the maximum of the
DisplayRange
map to the last value of the transparency
range.
When the AlphaData
property is nonempty, the
value has no effect.Alphamap
Value | Description |
---|---|
n-element column vector with values in the range [0, 1] | Values in V map linearly to the transparency
values in Alphamap . |
| Values in V map linearly to transparencies in the
range [0, 1]. |
| Values in V map quadratically to transparencies in
the range [0, 1]. Use this option to apply a more rapid change in
transparency between low and high values of V compared
to "linear" . |
| Values in V map cubically to transparencies in the
range [0, 1]. Use this option to apply the most rapid change in transparency
between low and high values of V . |
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:
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
Version History
Introduced in R2018bR2024b: Specify volume display range and transparency map
Control the display range used to scale the volume by using the new
DisplayRange
andDisplayRangeMode
properties.Control the display range used to scale the volume overlay by using the new
OverlayDisplayRange
andOverlayDisplayRangeMode
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 theAlphamap
andOverlayAlphamap
properties.
R2024b: New default colormap, OverlayThreshold
not recommended
To improve support for labeling workflows, the default
OverlayColormap
property value has changed fromturbo(256)
to a custom colormap that maximizes differences between adjacent colors. To apply the same colormap as in previous releases, specify theColormap
property asturbo(256)
.To apply a uniform transparency while hiding background labels, the new
OverlayAlpha
property is recommended over theOverlayThreshold
property. There are no plans to remove support for existing instances ofOverlayThreshold
.
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 newCinematicNumIterations
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 newLightScatteringQuality
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.
See Also
Volume
Viewer | Volume Properties | BlockedVolume Properties | viewer3d
| Surface
| isosurface
| slice
| obliqueslice
Topics
- Display Volume Using Cinematic Rendering
- Display Interior Labels by Clipping Volume Planes
- Display Interior Labels by Adjusting Volume Overlay Properties
- Remove Objects from Volume Display Using 3-D Scissors
- Display Large 3-D Images Using Blocked Volume Visualization
- Display Translucent Volume with Advanced Light Scattering
MATLAB Command
You clicked a link that corresponds to this MATLAB command:
Run the command by entering it in the MATLAB Command Window. Web browsers do not support MATLAB commands.
Select a Web Site
Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .
You can also select a web site from the following list:
How to Get Best Site Performance
Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.
Americas
- América Latina (Español)
- Canada (English)
- United States (English)
Europe
- Belgium (English)
- Denmark (English)
- Deutschland (Deutsch)
- España (Español)
- Finland (English)
- France (Français)
- Ireland (English)
- Italia (Italiano)
- Luxembourg (English)
- Netherlands (English)
- Norway (English)
- Österreich (Deutsch)
- Portugal (English)
- Sweden (English)
- Switzerland
- United Kingdom (English)