blockedImage

Big or multiresolution image made from discrete blocks

Since R2021a

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

bim = blockedImage(Source)

[bim1,bim2,...] = blockedImage(sources)

[___] = blockedImage(___,Name=Value)

bim = blockedImage(destination,size,blockSize,initialValue,Mode="w")

bim = blockedImage(destination,size,blockSize,initialValue,Mode="w",Name=Value)

Description

Create Read-only blockedImage Object

bim = blockedImage(Source) creates a blockedImage object from an in-memory array or the name of a file or folder with image data. The source argument sets the Source property as the specified array, filename, or folder name.

[bim1,bim2,...] = blockedImage(sources) creates an array of blockedImage objects from multiple sources. The sources can be a collection of files or folders with image data. The number of blocked images is equal to the number of sources.

[___] = blockedImage(___,Name=Value) creates a blockedImage object and sets one or more of the Adapter, AlternateFileSystemRoots, BlockSize, UserData, WorldStart, WorldEnd properties using name-value arguments.

Create Writable blockedImage Object

bim = blockedImage(destination,size,blockSize,initialValue,Mode="w") creates a writeable blockedImage object at one or multiple resolution levels. destination specifies the location of the writable data. size and blockSize indicate the image size and the block size, respectively, at each resolution level. initialValue indicates the initial value for each array element. The size, blockSize, and initialValue arguments set the Size, BlockSize, and InitialValue properties, respectively.

bim = blockedImage(destination,size,blockSize,initialValue,Mode="w",Name=Value) creates a writeable blockedImage object and sets one or more of the Adapter, AlternateFileSystemRoots, UserData, WorldStart, WorldEnd properties using name-value arguments.

Input Arguments

sources — Sources of image data

cell array of character vectors | string array | FileSet object

Sources of image data, specified as an cell array of character vectors, a string array, or a FileSet object.

destination — Location to place writeable data

[] | character vector | string scalar

Location to place writable data, specified as a character vector or string scalar.

Destination Type	Image Format
Folder name (without a file extension)	The blockedImage object creates the folder and stores blocks of data as files within the folder. For numeric image data, blockedImage stores each block as a binary file using the BINBlocks adapter. For categorical and structure image data, blockedImage stores each block as a MAT file in the folder using the MATBlocks adapter.
File name with TIF or TIFF file extension	The blockedImage object stores data as a single TIFF image using the TIFF adapter. The initialValue must be numeric or logical with data type uint8, int8, uint16, int16,uint32, int32, single, double or logical.
File name with H5 file extension	The blockedImage object stores data as a single HDF5 image using the H5 adapter. The initialValue must be numeric with data type uint8, int8, uint16, int16, uint32, int32, single, or double.
[]	The blockedImage object stores data as a variable in memory using the InMemory adapter.

To specify a custom adapter for other output formats, use the Adapter property.

size — Image size at each resolution level

L-by-N matrix

Image size at each resolution level, specified as an L-by-N matrix of positive integers, where L is the number of resolution levels and N is the number of dimensions of the image. The blockedImage object always sorts size in descending order by number of pixels, irrespective of how Source stores the levels.

blockSize — Size of blocks

L-by-N matrix

Size of blocks, specified as an L-by-N matrix of positive integers, where L is the number of resolution levels and N is the number of dimensions.

If the image has multiple resolution levels, then you can specify blockSize as a 1-by-N vector to use the same block size for all resolution levels.

Example: [64 128] specifies a block size of 64-by-128 pixels for a single resolution image

Example: [128 128; 64 64; 32 32] specifies three different block sizes for three resolution levels

initialValue — Default element value for unloaded blocks

numeric scalar | categorical scalar | structure

Default pixel value for unloaded blocks, specified as one of these values. The blocked image uses this value to fill blocks which do not have data in the underlying source. The value of the initialValue argument sets the value of the InitialValue property. The data type of initialValue specifies the value of the ClassUnderlying property.

• Numeric scalar. The default value is 0.

• Categorical scalar. The default value is <undefined>.

• Structure with the same field names as the data. The default value is <undefined>.

Properties

Adapter — Read and write interface for blocked image object

InMemory object | MATBlocks object | PNGBlocks object | TIFF object | ...

Read and write interface for the blocked image object, specified as one of these adapter objects.

Adapter	Description
BINBlocks	Store each block as a binary file in a folder
GenericImage	Store blocks in a single image
GenericImageBlocks	Store each block as an image file in a folder
H5	Store blocks in a single HDF5 image
H5Blocks	Store each block as an HDF5 file in a folder
InMemory	Store blocks in a variable in main memory
JPEG2000	Read blocks of a single JPEG2000 file (since R2023a)
JPEGBlocks	Store each block as a JPEG file in a folder
MATBlocks	Store each block as a MAT file in a folder
PNGBlocks	Store each block as a PNG file in a folder
TIFF	Store blocks in a single TIFF file

You can also create your own adapter using the images.blocked.Adapter class.

When you specify Mode as "w", you cannot specify the adapter as a JPEG2000 object.

AlternateFileSystemRoots — Alternate file system path

string array

Alternate file system path for the files specified in Source, specified as a string array containing one or more rows. Each row specifies a set of equivalent root paths.

Example: ["Z:\datasets", "/mynetwork/datasets"]

Data Types: char | string | cell

BlockSize — Block size

L-by-N matrix

Block size, specified as an L-by-N matrix of positive integers, where L is the number of resolution levels and N is the number of dimensions. BlockSize serves as the default size of data that is loaded into main memory at any time for use. It is the smallest unit of data that can be manipulated with the blockedImage interface. If you specify BlockSize with less than N dimensions, then blockedImage pads the image with elements from the Size property.

You cannot specify this property when you specify Mode as "w".

Data Types: double

ClassUnderlying — Pixel data type

string array

This property is read-only.

Pixel data type, specified as a string array with L elements, where L is number of resolution levels. Each element in the array is the data type of a pixel from the corresponding resolution level. Values are: "logical", "int8", "uint8", "int16", "uint16", "int32", "uint32", "single", "double", "categorical", and "struct".

Data Types: string

InitialValue — Default pixel value for unloaded blocks

numeric scalar | categorical scalar | structure scalar

This property is read-only.

Default pixel value for unloaded blocks, specified as a scalar of the type specified by ClassUnderlying. The blockedImage object uses this value to fill blocks which do not have data in the underlying source. The default value varies by data type: 0 for numeric and logical types, <undefined> for categorical, and a scalar struct for structures.

Data Types: single | double | int8 | int16 | int32 | uint8 | uint16 | uint32 | char | categorical | struct

IOBlockSize — I/O block size of image source

numeric matrix

This property is read-only.

I/O block size of image source, specified as an L-by-N matrix of positive integers, where L is the number of resolution levels and N is the number of dimensions. IOBlockSize is the size of the underlying I/O block size the adapter uses to read from the image source. This represents the smallest unit of data that can be written or read. This property reflects the format of the underlying image source.

Note

You can set BlockSize to any value. The blockedImage object does the appropriate reading, cropping, stitching, and caching of the source I/O blocks to ensure efficient I/O.

Data Types: double

Mode — Current read or write mode

"r" (default) | "w"

Current read or write mode of the object, specified as "r" for read mode and "w" for write mode.

You can only set Mode to "w" when you create the object. You can change the value of Mode from "w" to "r", at which point no further writes are possible. You cannot change Mode from "r" to "w".

Data Types: string | char

NumDimensions — Number of dimensions in image

positive integer

This property is read-only.

Number of dimensions in the image, specified as a positive integer. For multiresolution level images that have varying number of dimensions, NumDimensions is the maximum taken across all levels. The blocked image extends other levels with singleton dimensions, if needed.

Data Types: double

NumLevels — Number of image resolution levels

positive integer

This property is read-only.

Number of image resolution levels, specified as a positive integer.

Data Types: double

Size — Image size at each level

L-by-N matrix

This property is read-only.

Image size at each level, specified as an L-by-N matrix of positive integers, where L is the number of resolution levels and N is the number of dimensions of the image. The blockedImage object always sorts Size in descending order by number of pixels, irrespective of how Source stores the levels.

Data Types: double

SizeInBlocks — Size expressed as number of blocks

L-by-N matrix

This property is read-only.

Size expressed as the number of blocks, specified as an L-by-N matrix of positive integers, where L is the number of resolution levels and N is the number of dimensions. This property is dependent on the BlockSize property. The value includes partial blocks.

Data Types: double

Source — Source of image data

numeric array | categorical array | structure array | character vector | string scalar

This property is read-only.

Source of image data, specified as an in-memory numeric, categorical, or structure array, or as a string scalar or character vector specifying a file or folder name. Blocked images support these file formats:

• Single TIFF file. If the file contains multiple Image File Directories (IFDs), the blockedImage object treats the IFDs as multiple resolution levels.

• Any image file that can be read by imread.

• Any source created by the adapters included with the toolbox, listed in Adapter.

WorldEnd — World coordinates of ending edge of image

numeric matrix

World coordinates of ending edge of the image, specified as an L-by-N numeric matrix, where L is the number of resolution levels and N is the number of dimensions. By default, the value is Size + 0.5 for each dimension and level, resulting in pixels that are one-unit wide. World coordinates of pixel centers coincide with pixel subscript locations for the first level.

Data Types: double

WorldStart — World coordinates of starting edge of image

numeric matrix

World coordinates of the starting edge of the image, specified as a L-by-N numeric matrix, where L is the number of levels and N is the number of dimensions. By default, the starting-edge value is 0.5 in each dimension and level.

Data Types: double

UserData — User data associated with the image

structure

User data associated with the image, specified as a structure. This field can be empty. You can update the value at any time. To make this value persist with the source, write the blockedImage to a file using the write function, or specify the data as parameter when you create the object.

Data Types: struct

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 block subscripts
world2sub	Convert world coordinates to pixel subscripts
write	Write blocked image data to new destination

Examples

Create and Visualize Blocked Image

Create a blocked image from a sample image included with the toolbox.

bim = blockedImage('tumor_091R.tif');

Display details of the blocked image at the command line.

disp(bim)

  blockedImage with properties:

   Read only properties
             Source: "/tmp/Bdoc23a_2213998_730379/tp86b615e7/images-ex85337066/tumor_091R.tif"
            Adapter: [1x1 images.blocked.TIFF]
               Size: [3x3 double]
       SizeInBlocks: [3x3 double]
    ClassUnderlying: [3x1 string]

   Settable properties
          BlockSize: [3x3 double]

View the blocked image in a figure window.

bigimageshow(bim)

Create Blocked Image from Workspace Variable

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: [128x128x27 uint8]
            Adapter: [1x1 images.blocked.InMemory]
               Size: [128 128 27]
       SizeInBlocks: [1 1 1]
    ClassUnderlying: "uint8"

   Settable properties
          BlockSize: [128 128 27]

Create Array of Blocked Images

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)

  1x67 blockedImage array with properties:

   Read only properties
             Source: 'Various'
            Adapter: [1x1 images.blocked.GenericImage]
    ClassUnderlying: 'Various'

   Settable properties
    No properties.

Write Data to Blocked Image and Read It Back

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: "    {5x7 uint8}..."
            Adapter: [1x1 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

Create Blocked Image Specifying Custom World Coordinates

Create a blocked image from a sample image included with the toolbox.

bim = blockedImage('tumor_091R.tif');
bigimageshow(bim)

Specify the distance between pixel centers at the finest level. This information obtained from the raw data available at https://camelyon17.grand-challenge.org/Data/.

pext = 0.000226316; % (in millimeters)

Assume the top-left edge of the first pixel starts at (0,0).

worldStart = zeros(bim.NumLevels, bim.NumDimensions);

Calculate the bottom right edge of the last pixel of the finest resolution level, using only the spatial dimensions. With the distance between each pixel center known, multiply the distance by the number of pixels.

worldEnd = bim.Size(1,:)*pext;

All resolution levels span the same world coordinates.

worldEnd = repmat(worldEnd,[bim.NumLevels,1]);

The third dimension holds the color channels, each with a pixel extent of 1. Update the world coordinates of the edges of the pixels to center them on integer values (in this case, 1, 2, and 3).

worldStart(:,3) = 0.5;
worldEnd(:,3) = 3.5;

View the image with updated coordinates.

bim = blockedImage('tumor_091R.tif', ...
    'WorldStart',worldStart,'WorldEnd',worldEnd);
figure
h = bigimageshow(bim);
title('Measured in Millimeters')

Tips

• The blockproc function is an alternative to blockedImage for processing 2-D blocks of single-resolution in-memory images.

Version History

Introduced in R2021a

R2023a: Create and combine multilevel blocked images

You can create multilevel blocked images using the makeMultiLevel2D and makeMultiLevel3D functions. These functions are particularly useful when you want to create overview levels for a very large image.

You can combine the levels of two or more blocked images using the concatenateLevels function. This function supports combining data in different formats and in different locations. To efficiently add overview levels to a very large image on disk, you can create the overview levels in memory, and then combine the original image and the overview levels using concatenateLevels.

R2023a: Support for JPEG2000 images

The JPEG2000 adapter reads blocks of a single JPEG2000 file.