Main Content

volshow

Display volume

    Description

    example

    vol = volshow(V) creates a Volume object that displays the 3-D grayscale 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 grayscale 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, volshow(V,RenderingStyle="Isosurface") displays the 3-D grayscale volume V and sets the rendering style as "Isosurface".

    Examples

    collapse all

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

    load mri
    V = squeeze(D);

    Generate a colormap and transparency (alpha) map suited 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);

    View the volume with the custom colormap and transparency map. 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);

    This example uses 3-D volumetric human chest CT scan data. To run this example, you must download the sample data from MathWorks® using the Add-On Explorer. See Install Sample Data Using Add-On Explorer.

    Load the data into the workspace.

    load chestVolume

    Create a colormap and transparency map suited for CT images.

    intensity = [-3024,-16.45,641.38,3071];
    alpha = [0, 0, 0.72, 0.72];
    color = [0 0 0; 186 65 77; 231 208 141; 255 255 255]/255;
    queryPoints = linspace(min(intensity),max(intensity),256);
    alphamap = interp1(intensity,alpha,queryPoints)';
    colormap = interp1(intensity,color,queryPoints);

    View the volume with the custom colormap and transparency map. 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);

    Programatically set the camera position and camera target of the scene to see a different view of the volume.

    scene = vol.Parent;
    scene.CameraPosition = [275 75 140];
    scene.CameraTarget = [256 256 160];
    scene.CameraUpVector = [0 0 1];

    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

    animatedSpiral.gif

    Input Arguments

    collapse all

    3-D grayscale volume, specified as a numeric array.

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

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

    Data Types: struct

    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 grayscale volume V and sets the rendering style as "Isosurface".

    Note

    The properties listed here are only a subset. For a full list, see Volume 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. A Volume object cannot be reparented.

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

    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 be blended with the object data during rendering, specified as a numeric array. 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 more information about modifying aspects of the volume, see Volume 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 that executes when one of these events occurs. When the Volume 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 NameTriggerEvent DataEvent Attributes
    ClippingPlanesChanging

    An object clipping plane is being interactively moved. This event does not execute if the clipping plane is programmatically moved.

    images.ui.graphics3d.events.ClippingPlanesChangedEventData

    NotifyAccess: private

    ListenAccess: public

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

    NotifyAccess: private

    ListenAccess: public

    SlicePlanesChangedAn object slice plane stops being interactively moved. This event does not execute if the slice plane is programmatically moved.images.ui.graphics3d.events.SlicePlanesChangedEventData

    NotifyAccess: private

    ListenAccess: public

    Version History

    Introduced in R2018b

    expand all