Main Content

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

expand all

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

Blocked Image Display

expand all

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.

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.

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.

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

expand all

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.

Data limits used to scale the intensity and transparency of the grayscale or RGB image data, 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 DataLimits to ensure accurate scaling. If you do not specify DataLimits directly, volshow automatically scales the data using the "auto" behavior of DataLimitsMode.

Data limits mode, specified as one of these values:

  • "auto" — Scale data automatically. If the blocked image volume is available in memory or contains a coarse resolution level with a maximum dimension smaller than 512 voxels, volshow scales the display to the range of the data. If the blockedImage points to a file without a coarse resolution level, volshow scales the data to the limits of the underlying data type of the blockedImage. For example, if the ClassUnderlying property value of the blocked image is "single", then the data values scale to the range [0, 1].

  • "manual" — Scale data using limits specified by DataLimits. Specifying the DataLimits property automatically sets DataLimitsMode to "manual".

Transparency map for the volume data, specified as an n-element column vector with values in the range [0, 1]. The maximum length of the vector is 256.

  • For grayscale volumes, the intensity of each voxel controls the transparency of the voxel. The Alphamap property indicates how intensity values map to transparency values.

  • For RGB volumes, the object uses the luminance of the voxel in the CIE 1976 L*a*b* color space to control the transparency of the voxel. The Alphamap property indicates how luminance values map to transparency values.

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

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.

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.

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.

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

expand all

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

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

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.

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

expand all

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.

Data limits used to scale the overlay data, specified as a 2-element row vector of the form [min max]. The volshow function scales the overlay data to the range specified by min and max. If you know the minimum and maximum values of the overlay data, specify OverlayDataLimits to ensure accurate scaling. If you do not specify OverlayDataLimits directly, volshow scales the overlay automatically using the "auto" behavior of OverlayDataLimitsMode.

Overlay data limits mode, specified as one of these values:

  • "auto" — Scale overlay data automatically. If the blocked image volume is available in memory or contains a coarse resolution level with a maximum dimension smaller than 512 voxels, volshow scales the display to the range of the data. If the blockedImage points to a file without a coarse resolution level, volshow scales the data to the limits of the underlying data type of the blockedImage. For example, if the ClassUnderlying property value of the blocked image is "single", then the data values scale to the range [0, 1].

  • "manual" — Scale overlay data using limits specified by OverlayDataLimits. Specifying the OverlayDataLimits property automatically sets OverlayDataLimitsMode to "manual".

Overlay color, 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 affects the visualization only when the OverlayData property is nonempty.

Transparency map for the volume overlay, specified as an n-by-1 column vector with values in the range [0, 1]. The maximum number of elements is 256. This property affects the visualization only when the OverlayData property is nonempty.

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

Overlay threshold, specified as a number in the range [0, 1]. The threshold is a normalized value that defines the surface of the overlay data. You can use this value to hide background voxels in the overlay data. This property affects the visualization only when the OverlayData property is nonempty.

Version History

Introduced in R2023a