blockedImage
Description
A blockedImage object is an image made from discrete blocks. You
can use a blocked image to:
Process multiresolution (also known as multilevel or pyramidal) images.
Process images, volumes, or multidimensional images that are too large to fit into memory.
Process volumes or multidimensional images as 3-D or higher-dimensional blocks.
Perform block processing on images in nonstandard image formats.
Creation
Syntax
Description
Create Read-only Blocked Image
[bim1,bim2,...] = blockedImage(
creates an array of sources)blockedImage objects from multiple sources. The
sources can be a collection of files or folders with blocked image data. The number of
blocked images is equal to the number of sources.
[___] = blockedImage(___,
sets one or more writable properties using name-value arguments.Name=Value)
For example, bim = blockedImage(source,BlockSize=[64 128])
specifies a block size of 64-by-128 pixels.
Create Writable Blocked Image
bim = blockedImage(
creates a writable dest,imageSize,blockSize,initVal,Mode="w")blockedImage object with one or multiple resolution
levels. The dest argument specifies the location of the writable
data. Specify the imageSize and blockSize
arguments as the image size and block size at each resolution level, respectively.
Specify the initVal argument as the initial value for each array
element.
bim = blockedImage(
also sets one or more writable properties using name-value arguments.dest,imageSize,blockSize,initVal,Mode="w",Name=Value)
For example, bim =
blockedImage(dest,imageSize,blockSize,initVal,Mode="w",Adapter=images.blocked.JPEGBlocks)
specifies that the blockedImage object write each block as a JPEG file
in a folder.
Input Arguments
Name-Value Arguments
Properties
Object Functions
apply | Process blocks of blocked image |
concatenateLevels | Concatenate levels from multiple blocked images |
crop | Create cropped version of blocked image |
blocksub2sub | Convert block subscripts to pixel subscripts |
gather | Collect blocks into current workspace |
getBlock | Read specific block of blocked image |
getRegion | Read arbitrary region of blocked image |
setBlock | Put data in specific block of blocked image |
makeMultiLevel2D | 2-D multilevel blocked image |
makeMultiLevel3D | 3-D multilevel blocked image |
sub2blocksub | Convert pixel subscripts to block subscripts |
sub2world | Convert pixel subscripts to world coordinates |
world2sub | Convert world coordinates to pixel subscripts |
write | Write blocked image data to new destination |
Examples
Create a blocked image using a modified version of image tumor_091.tif from the CAMELYON16 data set. The image shows a lymph node containing tumor tissue. The original image has eight resolution levels, and the finest level has resolution 53760-by-61440. The modified image has only three resolution levels. The spatial referencing of the modified image has been adjusted to enforce a consistent aspect ratio and to register features at each level.
bim = blockedImage("tumor_091R.tif");
Display the blocked image.
imageshow(bim);
Read data into the workspace. For this example, read a sample volume that is included with the toolbox.
dmri = tiffreadVolume('mri.tif');
Create a blocked image from the volume.
bim = blockedImage(dmri);
Display details about the blocked image at the command line.
disp(bim)
blockedImage with properties:
Read only properties
Source: [128×128×27 uint8]
Adapter: [1×1 images.blocked.InMemory]
Size: [128 128 27]
SizeInBlocks: [1 1 1]
ClassUnderlying: "uint8"
Settable properties
BlockSize: [128 128 27]
Create a file set of the images in the toolbox folder of sample images.
fs = matlab.io.datastore.FileSet( ... fullfile(matlabroot,'toolbox','images','imdata'), ... "FileExtensions",{'.jpg','.png'});
Create an array of blocked images from the images in the file set.
bims = blockedImage(fs);
Display details of the array of blocked images.
disp(bims)
1×67 blockedImage array with properties:
Read only properties
Source: 'Various'
Adapter: [1×1 images.blocked.GenericImage]
ClassUnderlying: 'Various'
Settable properties
No properties.
Create a blocked image to which you can write data. You specify the format of the blocked image in the destination parameter. To write to memory, specify an empty matrix. You must also specify the size of the image and the size of the blocks into which you want the image chunked. The initial value parameter depends on the format you specified in destination. To create a writable blocked image, specify the 'Mode' parameter with the value 'w' for write mode.
destination = []; imgsize = [5 7]; blocksize = [2 2]; initval = uint8(0); bim = blockedImage(destination,imgsize,blocksize,initval, "Mode", 'w');
Write data to the specified blocks in the blocked image by using the setBlock object function. The blocksubs parameter specifies the coordinates of the block to which you want to write data. The blockdata parameter specifies the data to write to the specified block. The size of blockdata must match the block size.
blocksubs = [1 1];
blockdata = ones(2,2,"uint8");
setBlock(bim, blocksubs, blockdata)
Close the image for writing.
Switch the blocked image to read mode by setting the 'Mode' parameter to 'r' for read.
bim.Mode = 'r'
bim =
blockedImage with properties:
Read only properties
Source: " {5×7 uint8}↵"
Adapter: [1×1 images.blocked.InMemory]
Size: [5 7]
SizeInBlocks: [3 4]
ClassUnderlying: "uint8"
Settable properties
BlockSize: [2 2]
Create the full image by using the gather function to collect all the individual blocks.
fullImage = gather(bim);
Display details of the blocked image at the command line.
disp(fullImage)
1 1 0 0 0 0 0 1 1 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0
If your application requires measuring coordinates or distances in world units, you can define custom world coordinates by specifying the WorldStart and WorldEnd properties of the blockedImage object.
Create a blocked image using a modified version of image tumor_091.tif from the CAMELYON16 data set. The image shows a lymph node containing tumor tissue. The original image has eight resolution levels, and the finest level has resolution 53760-by-61440. The modified image has only three resolution levels. The spatial referencing of the modified image has been adjusted to enforce a consistent aspect ratio and to register features at each level.
bim = blockedImage("tumor_091R.tif");
Specify the pixel size, in millimeters, in the finest resolution level. For this image, the pixel size is approximately 0.22 micrometers, which is typical for 100x microscopy objectives. This information is available from the raw data on the Camelyon 17 Grand Challenge website.
pixelSpacing = 0.000226316;
Specify the position of the upper-left edge of the first pixel, assuming (0, 0) for all three resolution levels.
worldStart = zeros(bim.NumLevels, bim.NumDimensions);
Calculate the position of the lower-right edge of the last pixel of the finest resolution level. The location is the product of the number of pixels and the pixel size, in millimeters.
worldEnd = bim.Size(1,:)*pixelSpacing;
Expand the worldEnd value using repmat to specify the same position for all three resolution levels.
worldEnd = repmat(worldEnd,[bim.NumLevels,1]);
Update the WorldStart and WorldEnd property values.
bim.WorldStart = worldStart; bim.WorldEnd = worldEnd;
Display the updated blocked image. To use the correct units label, parent the image display to a Viewer object with a SpatialUnits property value of "mm". Note that the SpatialUnits property only affects the annotation label text. The world coordinates of the blockedImage object determine the values of spatial coordinates in the displayed image.
viewer = viewer2d(ScaleBar="on",ScaleBarStyle="measure",SpatialUnits="mm"); imageshow(bim,Parent=viewer);
Tips
The
blockprocfunction is an alternative toblockedImagefor processing 2-D blocks of single-resolution in-memory images.
