volshow

Display medical volume in patient coordinates

Since R2023a

Syntax

vol = volshow(medVol)

vol = volshow(medVol,Name=Value)

vol = volshow(V)

vol = volshow(V,config)

vol = volshow(V,Name=Value)

bVol = volshow(bim)

bVol = volshow(bim,Name=Value)

Description

Medical Imaging Toolbox™ extends the functionality of the volshow (Image Processing Toolbox™) function to display a medicalVolume object in the patient coordinate system. The function uses the medicalVolume properties to set the Transformation property of the displayed Volume object. If you do not have Medical Imaging Toolbox installed, see volshow (Image Processing Toolbox).

Medical Volume Object

vol = volshow(medVol) creates a Volume object that displays the 3-D image volume in the medicalVolume object medVol in the patient coordinate system. You can rotate and zoom in and out on the display interactively using the mouse. Use vol to access and modify properties of the Volume object after creation. For a list of properties, see Volume Properties.

vol = volshow(medVol,Name=Value) modifies the appearance of the volume using one or more name-value arguments. For example, RenderingStyle="Isosurface" specifies the rendering style of the volume as "Isosurface".

Numeric Array

vol = volshow(V) creates a Volume object that displays the 3-D volume V. Use vol to query and modify properties of the Volume object after you create the object. For a list of properties, see Volume Properties. Use numeric array inputs to display images in file formats not supported by medicalVolume, or to view a volume in the intrinsic coordinate system.

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) modifies the appearance of the volume using one or more name-value arguments. For example, RenderingStyle="Isosurface" specifies the rendering style of the volume as "Isosurface".

Blocked Image Volume

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) modifies the appearance of the blocked volume using one or more name-value arguments. For example, ResolutionLevel="coarse" specifies the resolution level to display as the coarsest resolution level.

Examples

Display Medical Image Volume in Patient Coordinates

Display a chest CT volume saved as a directory of DICOM files. The volume is part of a data set containing three CT volumes. The size of the entire data set is approximately 81 MB.

Run this code to download the data set from the MathWorks® website and unzip the folder.

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

The dataFolder folder contains the downloaded CT scan used by this example.

dataFolder = fullfile(filepath,"MedicalVolumeDICOMData","LungCT01");

Create a medical image volume object that contains the image data and spatial referencing information for the CT volume.

medVol = medicalVolume(dataFolder);

Specify a custom colormap and transparency map that highlight the ribcage.

alpha = [0 0 0.72 1.0];
color = [0 0 0; 186 65 77; 231 208 141; 255 255 255] ./ 255;
intensity = [-3024 100 400 1499];
queryPoints = linspace(min(intensity),max(intensity),256);
alphamap = interp1(intensity,alpha,queryPoints)';
colormap = interp1(intensity,color,queryPoints);

Display the volume with the custom display settings. Specify the cinematic rendering style, which displays the volume with realistic lighting and shadows. The volshow object function displays the volume in the patient coordinate system defined by the spatial properties of medVol. The axes display indicators label the inferior/superior (S), left/right (L), and anterior/posterior (P) anatomical axes.

volshow(medVol,Colormap=colormap,Alphamap=alphamap,RenderingStyle="CinematicRendering")

Pause to apply all of the cinematic rendering iterations before updating the display in Live Editor.

pause(3.5)
drawnow

Optionally, you can clean up the viewer window by using the 3-D Scissors tool, , to remove the patient bed. For a detailed example, see Remove Objects from Volume Display Using 3-D Scissors. This image shows the final volume display after removing the patient bed and rotating to view the anterior plane.

Display Medical Image Volume in Intrinsic Coordinates

Display a chest CT volume saved as a directory of DICOM files. The volume is part of a data set containing three CT volumes. The size of the entire data set is approximately 81 MB.

Run this code to download the data set from the MathWorks® website and unzip the folder.

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

The dataFolder folder contains the downloaded CT scan.

dataFolder = fullfile(filepath,"MedicalVolumeDICOMData","LungCT01");

Create a medical volume object that contains the image data and spatial referencing information for the CT volume. The Voxels property contains a numeric array of the voxel intensities. The VoxelSpacing property indicates that the voxels are anisotropic, with a size of 0.7285-by-0.7285-by-2.5 mm in the patient coordinate system.

medVol = medicalVolume(dataFolder)

medVol = 
  medicalVolume with properties:

                 Voxels: [512×512×88 int16]
         VolumeGeometry: [1×1 medicalref3d]
           SpatialUnits: "mm"
            Orientation: "transverse"
           VoxelSpacing: [0.7285 0.7285 2.5000]
           NormalVector: [0 0 1]
       NumCoronalSlices: 512
      NumSagittalSlices: 512
    NumTransverseSlices: 88
           PlaneMapping: ["sagittal"    "coronal"    "transverse"]
               Modality: "CT"
          WindowCenters: [88×1 double]
           WindowWidths: [88×1 double]

Display the volume in the intrinsic coordinate system by using volshow with the numeric array from the Voxels property as input. The intrinsic coordinate system assumes cubic voxels with uniform dimensions. Therefore, this anisotropic volume appears squished. The x-, y- and z-axis display markers align with the first, second, and third dimensions of the image array, respectively, rather than the x-, y-, and z-axes of the patient coordinate system.

vol = volshow(medVol.Voxels,RenderingStyle="MaximumIntensityProjection");

Input Arguments

medVol — Medical volume

medicalVolume object

Medical volume, specified as a medicalVolume object. The function uses the spatial referencing information stored in the VolumeGeometry property of medVol to define the Transformation property of vol and display the image in patient coordinates.

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(medVol,RenderingStyle="Isosurface") displays the image data in medVol as an isosurface in the patient coordinate system.

AnatomicalConvention — Anatomical display orientation convention

"radiological" (default) | "neurological"

Anatomical display orientation convention, specified as one of these values:

• "radiological" — Displays the left side of the patient on the right side of the image when viewing the volume head on.

• "neurological" — Displays the left side of the patient on the left side of the image when viewing the volume head on.

Note

To use the AnatomicalConvention name-value argument, you must specify vol as a medicalVolume object.

Data Types: char | string

Note

The arguments listed below set properties of the Volume or BlockedVolume object created by volshow. This list is only a subset. For a full list of properties that you can modify after object creation, see Volume Properties or BlockedVolume Properties.

Parent — Parent

Viewer3D object

Parent of the Volume 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. You cannot reparent a Volume object.

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 you render a volume with uniform intensity using "GradientOpacity", the internal portion of the volume appears more transparent than in the "VolumeRendering" rendering style, enabling you to better visualize the intensity or luminance gradients in the volume.
"Isosurface"	View an isosurface of the volume, as specified by the value in the IsosurfaceValue property.
"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 Alphamap value has no effect.

Value	Description
n-element column vector with values in the range [0, 1]	Values in V map linearly to the transparency values in Alphamap.
"linear" (since R2024b)	Values in V map linearly to transparencies in the range [0, 1].
"quadratic" (since R2024b)	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".
"cubic" (since R2024b)	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 content, 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 a medicalVolume object vol or numeric 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 object 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 medicalVolume object inputs, volshow sets the Transformation property of vol to the 4-by-4 transformation matrix defining the patient coordinate system.

For more information about modifying aspects of the volume display, 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 the Volume object when certain events happen, set up listeners for these events. You can specify a callback function to call when one of these events occurs. When the Volume object notifies your application through the listener, MATLAB^® returns data specific to the event. Look at the event class for the specific event to see what the callback function returns.

Event Name	Trigger	Event Data	Event Attributes
ClippingPlanesChanging	Interactively moving an object clipping plane. This event does not execute if the clipping plane is programmatically moved.	images.ui.graphics.events.ClippingPlanesChangedEventData	NotifyAccess: private ListenAccess: public
ClippingPlanesChanged	Ceasing to interactively move an object clipping plane. This event does not execute if the clipping plane is programmatically moved.	images.ui.graphics.events.ClippingPlanesChangedEventData	NotifyAccess: private ListenAccess: public
SlicePlanesChanging	Interactively moving an object slice plane. This event does not execute if the slice plane is programmatically moved.	images.ui.graphics.events.SlicePlanesChangedEventData	NotifyAccess: private ListenAccess: public
SlicePlanesChanged	Ceasing to interactively move an object slice plane. 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

Version History

Introduced in R2023a

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.