BlockedVolume Properties

Display blocked volume in 3-D viewer

Since R2023a

BlockedVolume properties control the appearance and behavior of a BlockedVolume object. By changing property values, you can modify certain aspects of the displayed volume. Create a BlockedVolume object using the volshow function.

Use dot notation to query and set properties. For example, these commands show how to create a BlockedVolume object for the blockedImage object bim, query the value of the Colormap property, and set the value of the Colormap property, respectively.

bVol = volshow(bim);
cmap = bVol.Colormap;
bVol.Colormap = parula;

Parent/Child

Parent — Parent

Viewer object

Parent of the BlockedVolume object, specified as a Viewer object. You can create a Viewer object using the viewer3d function. A BlockedVolume object cannot be reparented.

Blocked Image Display

ResolutionLevel — Resolution level to display

"fine" (default) | "coarse" | positive integer

Resolution level to display, specified as "fine", "coarse", or as a positive integer. If the ResolutionLevel value is "fine" or "coarse", the viewer displays the finest or coarsest resolution level, respectively. If you do not specify ResolutionLevel directly, the viewer sets the resolution level using the "auto" behavior of ResolutionLevelMode.

Example: volshow(bim,ResolutionLevel=3) displays the third resolution level in the blocked image.

ResolutionLevelMode — Resolution level mode

"auto" (default) | "manual"

Resolution level mode, specified as one of these values:

• "auto" — Automatically set the resolution level based on the parent viewer and available screen size. For example, the displayed resolution level changes when you zoom in or out.

• "manual" — Manually set a fixed resolution level using the ResolutionLevel property. Specifying the ResolutionLevel property automatically sets ResolutionLevelMode to "manual".

This property has no effect if the blocked image has only one resolution level.

CachingStrategy — Block caching strategy

"auto" (default) | "none" | "all" | positive numeric scalar

Block caching strategy, specified as "auto", "none", "all", or a positive numeric scalar. This property specifies whether the BlockedVolume object stores image blocks in memory after reading them from the file, or rereads them from the file each time you update properties or interact with the display. Storing blocks in memory generally improves rendering performance, but can cause some systems to run out of memory.

• "auto" — Store some blocks in memory. MATLAB^® automatically determines the number of blocks to store in memory based on the amount of available memory.

• "none" — Store no blocks in memory. Use this value when your system has only a small amount of CPU memory available.

• "all" — Store all blocks in memory after initially reading them from the file. Use this value only if your system has enough memory to store all blocks simultaneously. This option can cause some systems to run out of memory.

• Positive numeric scalar — Store blocks in memory up to a specific cache size, in GB.

MemoryUsed — Approximate memory used by block cache

Read-only: positive numeric scalar

This property is read-only.

Approximate memory used by the block cache, stored as a positive numeric scalar, in GB. This property provides an approximation of the memory used by the object to store image blocks. This value does not account for peak memory required when reading blocks from the file, or when copying data onto the computer graphics card. This value does not account for other memory used by MATLAB.

Data Display

Data — Volumetric blocked image data

blockedImage object

Volumetric blocked image data displayed in the viewer, specified as a blockedImage object that reads 3-D blocks of grayscale, RGB, or RGBA data. The blockedImage can have a single resolution level or multiple resolution levels. If the blockedImage object has more than one resolution level, you can specify which level to render by setting the ResolutionLevel property.

DisplayRange — Display range

2-element row vector | 3-by-2 numeric matrix

Display range used to map voxel values to the color map and transparency map, specified as one of these values:

• 2-element row vector of the form [min max] — Scale data according to the values min and max. For RGB volumes, specifying a 2-element row vector applies the same data limits to all color channels.

• 3-by-2 numeric matrix with each row of the form [min max] — Scale each RGB channel according to the values min and max in the corresponding row. The first, second, and third rows of the numeric matrix specify the data limits for the red, green, and blue color channels, respectively.

If you know the minimum and maximum values of the data in the blocked volume, specify DisplayRange to ensure accurate scaling. If you do not specify a DisplayRange value, by default, the function automatically scales the data based on the DisplayRangeMode.

DisplayRangeMode — Display range mode

"data-range" | "type-range" | "10-bit" | "12-bit" | "manual"

Display range mode, specified as one of the options in the table.

Value	Description
"type-range"	Set the display range equal to the data type range. For example, for uint8 images, the display range is [0, 255]. This is the default value when the blockedImage points to a file without a coarse resolution level. The data type is determined by the ClassUnderlying property value of the blocked image.
"data-range"	Set the display range equal to the data range of the volume. For RGB volumes, the data range is the overall minimum and maximum across channels. For example, given an RGB volume in which the minimum and maximum values of the R, G, and B channels are [2, 160], [5, 200], and [0, 140], respectively, the display range is [0, 200]. This is the default value when the blocked image volume is available in memory, or points to a file-backed volume that contains a coarse resolution level in which the largest dimension is smaller than 512 voxels.
"10-bit"	Set the display range to [0, 1023]. This value is useful for displaying medical images with 10-bit data ranges.
"12-bit"	Set the display range to [0, 4095]. This value is useful for displaying medical images with 12-bit data ranges.
"manual"	Manually set a fixed display range using the DisplayRange argument. Specifying the DisplayRange automatically sets the DisplayRangeMode property value to "manual".

Interpolation — Volume interpolation method

"bilinear" (default) | "nearest"

Since R2025a

Volume interpolation method, specified as one of the values in this table:

Value	Description
"bilinear"	The volume displays using bilinear interpolation. The value of a voxel located at (x, y, z) in the viewer world coordinates is the weighted average of the surrounding voxels in Data. This option is suitable for most volumes.
"nearest"	The volume displays using nearest-neighbor interpolation. The value of a voxel located at (x, y, z) in the viewer world coordinates is the value of the voxel closest to (x, y, z) in Data. This option can be useful when displaying categorical or ordinal volume data.

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

For RGBA volumes, the Alphamap property has no effect. The transparency of each voxel is specified by the alpha channel values.

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 content, specified as an n-by-3 numeric matrix with values in the range [0, 1]. The maximum number of colors n is 256. You can specify the colormap as a numeric matrix directly, or as the name of predefined colormap such as turbo or parula. For a complete list of colormaps, see Color and Styling. This property has no effect when viewing RGB volumes.

Visible — Object is visible

"on" (default) | on/off logical value

Object is visible in the 3-D scene, specified as "on" or "off", or as a numeric or logical 1 (true) or 0 (false). A value of "on" is equivalent to true, and "off" is equivalent to false. The value is stored as an on/off logical value of type OnOffSwitchState.

Pickable — Picking state

"visible" (default) | "on" | "off"

Since R2025a

Picking state of the blocked volume, specified as one of the strings in the table. Use this property to toggle whether the viewer information display tool shows voxel coordinates for the blocked volume. This option is useful when a viewer contains multiple volumes, and you want to view or hide voxel coordinates for certain volumes. Toggle the visibility of the information display tool from the viewer context menu, or by using the DisplayInfo property of the Viewer object.

Value	Description
"visible"	The viewer can pick the volume if it is visible in the scene, and cannot pick the volume if it is not visible. Control the visibility of the volume by using the Visible property.
"on"	The viewer can pick the volume.
"off"	The viewer cannot pick the volume.

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.

ClippingPlanes — Clipping planes

[] (default) | N-by-4 matrix

Clipping planes applied locally to the object, specified as an N-by-4 matrix where each row corresponds to the equation for a clipping plane. The maximum number of clipping planes, N, is six. Each clipping plane is specified as a 1-by-4 vector, in world coordinates, following the Hessian normal form where the first three values represent the plane's normal vector and the fourth value is the signed distance from the origin to the plane.

Volume Rendering

RenderingStyle — Rendering style

"VolumeRendering" (default) | "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.
"MaximumIntensityProjection"	View the voxel with the highest intensity value for each ray projected through the data. For RGB volumes, the luminance of the voxel in CIE 1976 L*a*b* color space.
"MinimumIntensityProjection"	View the voxel with the lowest intensity value for each ray projected through the data. For RGB volumes, the luminance of the voxel in 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 (grayscale volumes) or luminance (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 IsosurfaceValue.
"SlicePlanes"	View three orthogonal slice planes.

IsosurfaceValue — Isosurface value

0.15 (default) | numeric scalar

Isosurface value, specified as a numeric scalar in the range [0, 1]. This property affects the visualization only when the RenderingStyle property value is "Isosurface".

IsosurfaceAlpha — Isosurface transparency

1 (default) | numeric scalar

Since R2025a

Isosurface transparency, specified as a numeric scalar in the range [0, 1]. This property affects the visualization only when the RenderingStyle property value is "Isosurface".

SlicePlaneValues — Orthogonal or oblique slice planes

N-by-4 matrix

Orthogonal or oblique slice planes of the volume, specified as an N-by-4 matrix where each row corresponds to the equation for a slice plane. The maximum number of slice planes, N, in SlicePlaneValues is six. The slice planes are visible only when the RenderingStyle property is "SlicePlanes". The default value is three orthogonal planes that slice through the center of the volume. Each slice plane is specified as a 1-by-4 vector in voxel coordinates following the Hessian normal form where the first three values represent the normal vector of the plane and the fourth value is the signed distance from the origin to the plane.

GradientOpacityValue — Gradient opacity value

0.3 (default) | number in range [0, 1]

Gradient opacity value, specified as a number in the range [0, 1]. When set to 0, no gradient opacity is applied. When set to 1, the maximum amount of gradient opacity is applied. This property affects the visualization when the RenderingStyle property value is "GradientOpacity" or the OverlayRenderingStyle property value is "GradientOverlay".

Overlay

OverlayData — Overlay data

blockedImage object

Overlay data to blend with the object data during rendering, specified 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.

OverlayDisplayRange — Overlay display range

[0, 255] (default) | 2-element numeric vector

Overlay display range, specified as a 2-element numeric vector of the form [low high] that specifies the minimum and maximum of the display range. If you specify this property directly, the OverlayDisplayRangeMode property value automatically changes to "manual". If you do not specify the OverlayDisplayRange property value, the function automatically scales the data based on the OverlayDisplayRangeMode property value. In this case, the OverlayDisplayRange property value automatically updates to reflect the current display range.

OverlayDisplayRangeMode — Overlay display range mode

"8-bit" (default) | "type-range" | "data-range" | "manual"

Overlay display range mode, specified as one of the options in the table.

Value	Description
"8-bit"	Set the overlay display range to [0 255].
"type-range"	Set the overlay display range equal to the data type range for OverlayData. For example, if OverlayData is of data type double, the display range is [0 1].
"data-range"	Set the display range equal to the data range of OverlayData.
"manual"	Manually set a fixed display range using the OverlayDisplayRange property. Specifying the OverlayDisplayRange property automatically sets the OverlayDisplayRangeMode to "manual".

OverlayColormap — Overlay colormap

n-by-3 numeric matrix

Overlay colormap, specified as an n-by-3 numeric matrix with values in the range [0, 1]. The maximum number of colors n is 256. You can specify the colormap as a numeric matrix directly, or as the name of predefined colormap such as turbo or parula. For a complete list of colormaps, see Color and Styling.

This property affects the visualization only when the OverlayData property is nonempty. The default colormap maximizes color differences between adjacent colors in the colormap, which helps visually distinguish between different values in a discrete label image. When displaying continuous overlay data as a heatmap, consider specifying a colormap with gradual color changes, such as turbo or parula.

The OverlayDisplayRange property determines how values of OverlayData map to the colormap. Values less than or equal to the minimum of the OverlayDisplayRange map to the first color in OverlayColormap, and all values greater than or equal to the maximum of the OverlayDisplayRange map to the last color in OverlayColormap.

OverlayAlpha — Uniform transparency value for overlay

0.2 (default) | numeric scalar | []

Uniform transparency value for the overlay image, specified as a numeric scalar in the range [0, 1] or an empty array. Specify a numeric scalar to apply a uniform transparency to all nonzero pixels in OverlayData. Zero-valued pixels display fully transparent.

To specify a nonuniform transparency, or to apply a uniform transparency to all pixels including zero-valued pixels, specify the OverlayAlphamap property. If you specify OverlayAlphamap, then this property automatically changes to an empty matrix, [].

OverlayAlphamap — Nonuniform transparency map for overlay

n-element column vector | "linear" | "quadratic" | "cubic"

Nonuniform transparency map for the overlay image, specified as one of the values in the table. Specify this property to apply a nonuniform transparency to pixels in OverlayData. By default, OverlayAlphamap is a 256-element column vector that reflects the current OverlayAlpha value.

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

Value	Description
n-element column vector with values in the range [0, 1]	Values in OverlayData map linearly to the transparency values in OverlayAlphamap.
"linear" (since R2024b)	Values in OverlayData map linearly to transparencies in the range [0, 1].
"quadratic" (since R2024b)	Values in OverlayData 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 OverlayData compared to "linear".
"cubic" (since R2024b)	Values in OverlayData 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 OverlayData.

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 voxel and the previous voxel along the viewing ray.

Version History

Introduced in R2023a

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

• 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 mouse cursor 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 transparency map

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

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

R2024b: Specify data and overlay display range

• For consistency with other graphics objects in the toolbox, the DataLimits and DataLimitsMode properties are now called DisplayRange and DisplayRangeMode, respectively. There are no plans to remove support for existing references to the old names.

• For more clarity and granular control, in the renamed DisplayRangeMode property, the "auto" option has been replaced with the new options "type-range", "data-range", "10-bit", and "12-bit". If you specify the DisplayRangeMode as "auto", the software returns an error. To update existing code, replace "auto" with one of the new values.

• For consistency with other graphics objects in the toolbox, the OverlayDataLimits and OverlayDataLimitsMode properties are now called OverlayDisplayRange and OverlayDisplayRangeMode, respectively. There are no plans to remove support to existing references to the old names.

• For more clarity and granular control, in the renamed OverlayDisplayRangeMode property, the "auto" option has been replaced with the new options "8-bit", "type-range", and "data-range". If you specify the OverlayDisplayRangeMode as "auto", the software returns an error. To update existing code, replace "auto" with one of the new values.

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