Main Content

volshow

Display medical volume in patient coordinates

Since R2023a

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

example

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

example

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

collapse all

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")

Figure contains an object of type images.ui.graphics3d.viewer3d.

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, Scissors icon, 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 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

collapse all

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.

3-D volume, specified as a numeric array.

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

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

Data Types: struct

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.

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 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.

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

ValueDescription
"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.

Transparency map for the volume content, specified as an n-element column vector with values in the range [0, 1]. The maximum length of the vector is 256. When viewing RGB volumes, the object uses the luminance of the voxel in the CIE 1976 L*a*b* color space to assign a transparency from the transparency map. When the AlphaData property is nonempty, the Alphamap property has no effect.

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.

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.

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

ValueDescription
"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

collapse all

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.

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

More About

collapse all

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 NameTriggerEvent DataEvent Attributes
ClippingPlanesChanging

Interactively moving an object clipping plane. This event does not execute if the clipping plane is programmatically moved.

images.ui.graphics3d.events.ClippingPlanesChangedEventData

NotifyAccess: private

ListenAccess: public

ClippingPlanesChangedCeasing to interactively move an object clipping plane. This event does not execute if the clipping plane is programmatically moved.images.ui.graphics3d.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.graphics3d.events.SlicePlanesChangedEventData

NotifyAccess: private

ListenAccess: public

SlicePlanesChangedCeasing to interactively move an object slice plane. This event does not execute if the slice plane is programmatically moved.images.ui.graphics3d.events.SlicePlanesChangedEventData

NotifyAccess: private

ListenAccess: public

DataReadStartedA 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

DataReadFinishedThe 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

expand all