Display Large 3-D Images Using Blocked Volume Visualization

Display Blocked Image Volume

Create a large 500-by-500-by-2500 voxel image volume. If your machine does not have enough memory to create and store the 2.5 GB volume, decrease imSize before running this example.

imSize = [500 500 2500];

Create a simulated 3-D image of bubbles, V. This can take several minutes.

V = rand(imSize,"single");
BW = false(size(V));
BW(V < 0.000001) = true;
V = bwdist(BW);
V(V <= 20) = 1;
V(V > 20) = 0;

If you try to display V directly, volshow returns a warning and downsamples the volume before displaying it. Instead, view the full resolution volume by creating a blockedImage object that points to V and has a block size of 500-by-500-by-500 voxels. In general, a smaller block size uses less memory, but results in slower rendering times, while a large block size renders more quickly, but can exceed memory or graphics hardware limitations. For most image volumes and most hardware, a block size between 300 and 500 voxels in each dimension is appropriate.

bim = blockedImage(V,BlockSize=[500 500 500]);

Display the blockedImage using volshow. The volshow function reads blocks into memory one at a time and stitches the individual block renderings to produce the final high-resolution volume rendering. The function creates a BlockedVolume object, which you can use to query and modify display properties.

bVol = volshow(bim);

Interact with Blocked Image Volume

You can interact with the volume using the rotate, zoom, and pan tools. When you interact with the volume, the viewer temporarily switches to a lower rendering resolution while it rerenders each block in the new view. Zoom in on the volume.

Crop Blocked Volume

To focus on a region of interest and improve performance between interactions, crop the volume using a rectangular crop box. You can add a crop box interactively from the viewer toolstrip. Pause on the Add Clipping Plane icon and, from the list, select the Add Crop Box icon.

The crop box appears in the viewer. To change the size of the cropped volume, drag a face of the crop box. To move the crop box without changing its size, hold Ctrl while you drag. To undo the cropping, right-click the crop box and select Remove crop region. This image shows the viewer after dragging the top of the crop box to shorten it in the Z-direction. After cropping, the display can update faster between interactions because the viewer rerenders only the visible blocks.

Alternatively, if you know the coordinates of your desired region of interest, you can create the crop box programmatically. Specify the coordinates for the crop box as a matrix of the form [xmin ymin zmin; xmax ymax zmax]. Create a viewer containing the crop box.

cropRegion = [0 0 1000; 500 500 1500];
viewer = viewer3d;

Render the blocked volume. The volshow function renders only the blocks contained within the crop box, which is faster than rendering the full volume.

bVolCropped = volshow(bim,Parent=viewer);
viewer.CropRegion = cropRegion;

View Blocked Volume Clipping Planes

You can view inside the blocked image volume using clipping planes. To interactively add a clipping plane, in the axes toolbar, select the clipping plane button. The viewer rerenders the clipped volume at full resolution. To improve performance, volshow does not rerender any blocks that are completely cropped out by the clipping plane. To learn more about working with clipping planes, see Display Interior Labels by Clipping Volume Planes.

Display Multilevel Blocked Image Volumes

A blockedImage object can point to an image with a single resolution level or multiple resolution levels. You can create a new multilevel blockedImage object from a single resolution blockedImage object by using the makeMultiLevel3D function. Create a multilevel blockedImage object for the bubbles image. The makeMultiLevel3D function adds several lower resolution levels to the original data in bim.

multibim = makeMultiLevel3D(bim);

Update the data displayed by the BlockedVolume object bVol to the new multilevel image. For multilevel blockedImage objects, volshow defaults to dynamically selecting the resolution level to display based on the figure window size, camera positioning, and the size of the volume. This can improve rendering speed by showing lower resolution levels when the rendering is too small to see small details.

bVol = volshow(multibim,CachingStrategy=5);

You can set a fixed resolution level by setting the ResolutionLevel property of the BlockedVolume object.

bVol.ResolutionLevel = 4;

Display File-Backed Blocked Image Volumes

A file-backed blockedImage object points to an image source file saved outside of MATLAB. Use file-backed blocked images when your image is too large to read into the MATLAB workspace. The volshow function reads and renders the image data from the file one block at a time. Rendering performance is best when you read file-backed images from locally stored files. Reading files from remote servers can significantly increase rendering times.

To control whether volshow stores some, none, or all of the blocks in memory once it reads them from the file, set the CachingStrategy property. By default, the CachingStrategy is "auto", and volshow stores a subset of blocks based on the amount of memory available to MATLAB. Storing blocks in memory improves performance when you interact with the volume or update display properties, because volshow does not need to reread all of the file data while it rerenders the volume. You can also set the CachingStrategy to "none" to discard all blocks from memory after reading, or to "all" to store all blocks in memory. You can also specify CachingStrategy as a numeric scalar to allocate a specific amount of memory for block storage, in GB.

Allocate approximately 5 GB of CPU memory to visualize the blocked volume bim.

bVol = volshow(bim,CachingStrategy=5);

The volshow function scales the intensity range of a volume using the DisplayRange and DisplayRangeMode properties. By default, the DisplayRangeMode value is "auto", and volshow automatically sets the data limits for scaling. For file-backed blocked volumes that do not have a resolution level smaller than 512 voxels in all dimensions, volshow scales the data to the range of the underlying data type. For example, if the ClassUnderlying property value of the blocked image is "single", then volshow scales the data values to the range [0, 1]. Automatic scaling can result in poor visualization results. Therefore, if you know the intensity range of your blocked image volume, specify it directly using the DisplayRange property. When you specify DisplayRange, the DisplayRangeMode value automatically changes from "auto" to "manual".

bVol.DisplayRange = [0, 1];