bigimage

Out-of-core processing of very large images

bigimage is not recommended. Use the blockedImage object instead. For more information, see Compatibility Considerations.

Description

A bigimage object stores information about a large TIFF image file and the image data it contains. A bigimage represents images as smaller blocks of data that can be independently loaded and processed.

Use a bigimage object to visualize and process images that are too large to fit in memory, or when processing the image requires more memory than is available. Additionally, the object can:

• Read, process, and display images at different multiple resolution levels (image pyramids).

• Read arbitrary regions of the image.

• Read, set, and write blocks of data.

For big images with multiple resolution levels, the lowest or coarsest resolution level is the level where each pixel covers the largest area. The highest or finest resolution level is the level where each pixel covers the smallest area.

Creation

Syntax

bigimg = bigimage(filename)

bigimg = bigimage(dirname)

bigimg = bigimage(varname)

bigimg = bigimage(spatialReferencing,channels,classUnderlying)

bigimg = bigimage(levelSizes,channels,classUnderlying)

bigimg = bigimage(___,'Classes',classes,'PixelLabelIDs',pixelLabelIDs)

bigimg = bigimage(___,Name,Value)

Description

bigimg = bigimage(filename) creates a bigimage object from the big image file with name filename.

bigimg = bigimage(dirname) creates a bigimage object from a directory with name dirname containing files with big image data.

bigimg = bigimage(varname) creates a bigimage object from the variable varname in the workspace.

bigimg = bigimage(spatialReferencing,channels,classUnderlying) creates a writeable bigimage object and sets the SpatialReferencing, Channels, and ClassUnderlying properties, without initializing the image data.

bigimg = bigimage(levelSizes,channels,classUnderlying) creates a writeable bigimage object and sets the LevelSizes, Channels, and ClassUnderlying properties, without initializing the image data.

bigimg = bigimage(___,'Classes',classes,'PixelLabelIDs',pixelLabelIDs) creates a bigimage object with categorical data. Specify class names using the Classes property and the mapping of image pixel label values to categorical class names using the PixelLabelIDs property.

bigimg = bigimage(___,Name,Value) uses name-value pairs to set one or more of the BlockSize, SpatialReferencing, UndefinedID, UnloadedValue properties. You can specify multiple name-value pairs. Enclose each property name in quotes.

For example, bigimage(bigfile,'BlockSize',[256 256],'UnloadedValue',128) creates a big image from file bigfile that has a block size of 256-by-256 pixels and a default pixel value of 128.

Input Arguments

filename — Name of big image file

character vector | string scalar

Name of the big image file, specified as a character vector or string scalar. Supported file formats are TIFF and BigTIFF. This argument sets the DataSource property.

dirname — Name of big image directory

character vector

Name of the big image directory, specified as a character vector or string scalar. This argument sets the DataSource property.

varname — Big image variable

numeric array

Big image variable in the workspace, specified as a numeric array of size m-by-n for a single-channel image or m-by-n-by-c for an image with c color channels.

Properties

Image File Properties

DataSource — Location of data

character vector

Location of the data backing the big image, specified as a character vector. Supported file formats are TIFF and BigTIFF.

If you create a bigimage object without specifying the name of a big image file, then the value of DataSource is ''. If you create a bigimage object from a variable in the workspace, then the value of DataSource is 'variable'.

Data Types: string

SourceDetails — Source metadata

struct

This property is read-only.

Source metadata, specified as a struct such as returned by imfinfo.

Image Data Properties

BlockSize — Block size

2-element row vector

Block size, specified as a 2-element row vector of positive integers of the form [numrows numcols]. The block size is the smallest unit of data that the bigimage object can read or write.

Data Types: double

Channels — Number of channels

positive integer

This property is read-only.

Number of color or multispectral channels, specified as a positive integer.

Data Types: double

Classes — Class names

string array | cell array of character vectors

Class names of categorical data, specified as a string array or cell array of character vectors. Classes can contain duplicate names to map multiple pixel label IDs to the same categorical class.

Data Types: char | string

ClassUnderlying — Data type of image pixels

"double" | "single" | "uint8" | "uint16" | ...

This property is read-only.

Data type of image pixels, specified as one of the following strings.

"double"	"uint8"	"int8"
"single"	"uint16"	"int16"
"logical"	"uint32"	"int32"
"categorical"

Data Types: char | string

CoarsestResolutionLevel — Coarsest resolution level

positive integer

This property is read-only.

Coarsest resolution level, specified as a positive integer. For single-resolution images, CoarsestResolutionLevel is 1.

Data Types: double

FinestResolutionLevel — Finest resolution level

positive integer

This property is read-only.

Finest resolution level, specified as a positive integer. For single-resolution images, FinestResolutionLevel is 1.

Data Types: double

LevelSizes — Image dimensions at each resolution level

r-by-2 matrix of positive integers

Image dimensions at each resolution level, specified as an r-by-2 matrix of positive integers. Each row specifies the [numrows numcols] image dimensions at one of the r resolution levels.

Data Types: double

PixelLabelIDs — Pixel label IDs

c-element numeric vector | c-by-3 numeric array of data type uint8

Pixel label IDs that map pixel label values to categorical class names, specified as one of the following.

• c-element numeric vector, where c is the number of classes.

• c-by-3 numeric array of data type uint8. Each row contains a 3-element vector representing the RGB pixel value to associate with each class name. Use this format when the pixel label data is stored as an RGB image.

If a pixel has a value that does not exist in PixelLabelIDs, then bigimage maps the pixel to the class '<undefined>'.

SpatialReferencing — Pixel locations and sizes

scalar imref2d object | r-by-1 vector of imref2d objects

Pixel locations and sizes, specified as a scalar imref2d object for a single-resolution big image or an r-by-1 vector of imref2d objects for a multi-resolution big image. Each element specifies the pixel size, image size, and world limits at one of the r resolution levels.

UndefinedID — Pixel label value for '<undefined>' categorical class

0 (default) | numeric scalar | 1-by-3 numeric vector

Pixel label value for the '<undefined>' categorical class, specified as a numeric scalar or a 1-by-3 numeric vector. Do not specify this value as any of the values in PixelLabelIDs.

UnloadedValue — Default pixel value

logical scalar | numeric scalar | 1-by-1-by-Channels numeric vector | string scalar

Default pixel value used to fill blocks that do not exist in the DataSource, specified as a value in the table. If you do not specify UnloadedValue, then bigimage uses the pixel value of 0 for numeric and logical blocks and missing for categorical blocks.

Image Data Type	Format of UnloadedValue
Logical image	Logical scalar.
Numeric image	Numeric scalar for grayscale images or a 1-by-1-by-Channels numeric vector for truecolor and multispectral images. If you specify a numeric scalar when Channels is greater than 1, then bigimage extends the value to a 1-by-1-by-Channels numeric vector. The data type of UnloadedValue must match the data type specified by ClassUnderlying
Categorical image	String scalar specifying an element of the Classes property.

Object Functions

apply	(Not recommended) Process blocks of bigimage object
isequal	(Not recommended) Compare two bigimage objects for equality
getBlock	(Not recommended) Read block of bigimage object
getFullLevel	(Not recommended) Get all data in one level of bigimage object
getRegion	(Not recommended) Read arbitrary region of bigimage object
setBlock	(Not recommended) Put data in specific block of bigimage object
write	(Not recommended) Write bigimage object content to new file

Examples

Create Single-Resolution Mask from Multiresolution Blocked Image

Create a blocked image from the sample image tumor_091R.tif. This sample image is a training image of a lymph node containing tumor tissue from the CAMELYON16 data set. The image has been modified to have three coarse resolution levels, and has been adjusted to enforce a consistent aspect ratio and to register features at each level.

bim = blockedImage('tumor_091R.tif');

Display the entire blocked image at the finest resolution level, including a grid of the block boundaries.

bshow = bigimageshow(bim,'ResolutionLevel','fine', ...
    'GridVisible','on','GridLevel',1);

Create a mask of the coarsest resolution level.

First create a single-resolution image of the coarsest resolution level. By default, the gather function gets data from the coarsest resolution level.

imcoarse = gather(bim);

Convert the coarse image to grayscale.

graycoarse = rgb2gray(imcoarse);

Binarize the grayscale image. In the binarized image, the object of interest is black and the background is white.

bwcoarse = imbinarize(graycoarse);

Take the complement of the binarized image. The resulting mask follows the convention in which the object of interest is white and the background is black.

mask = imcomplement(bwcoarse);

Create a blocked image containing the mask.

Use the same spatial referencing as the original blocked image. Determine the coarsest resolution level and capture the spatial referencing information of the blocked image at the first two dimensions at that level.

coarsestLevel = bim.NumLevels;
originalWorldStartCoarsest = bim.WorldStart(coarsestLevel,1:2);
originalWorldEndCoarsest = bim.WorldEnd(coarsestLevel,1:2);

Create the blocked image for the mask.

bmask = blockedImage(mask,'WorldStart',originalWorldStartCoarsest, ...
   'WorldEnd',originalWorldEndCoarsest);

Display the mask image.

figure
bigimageshow(bmask)

Overlay the mask on the display of the original blocked image using the showmask function. To highlight all blocks that contain at least one nonzero mask pixel, specify an inclusion threshold of 0.

showmask(bshow,bmask,'InclusionThreshold',0)

Tips

• You can write to bigimage objects that are created using the SpatialReferencing or LevelSizes syntaxes. Write to these bigimage objects by using the setBlock function. You cannot write to bigimage objects that are created using the filename, dirname, or varname syntaxes.

• A bigimage object uses the UnloadedValue property in two situations. The first situation is when you create a writeable bigimage object. Blocks of the writeable bigimage object are set to UnloadedValue until you write the block data by using the setBlock function. The second situation is when the apply function stops processing blocks of a bigimage object before all blocks are processed.

References

[1] Bejnordi, Babak Ehteshami, Mitko Veta, Paul Johannes van Diest, Bram van Ginneken, Nico Karssemeijer, Geert Litjens, Jeroen A. W. M. van der Laak, et al. “Diagnostic Assessment of Deep Learning Algorithms for Detection of Lymph Node Metastases in Women With Breast Cancer.” JAMA 318, no. 22 (December 12, 2017): 2199–2210. https://doi.org/10.1001/jama.2017.14585.

[2] Grand Challenge. https://camelyon17.grand-challenge.org/Data/.

Version History

Introduced in R2019b

R2021a: bigimage is not recommended

Starting in R2021a, the blockedImage object replaces the existing bigimage object. The new blocked image object offers these advantages:

• Extension to N-D processing

• Introduction of a documented adapter interface to enable custom support for any data source that can be chunked into blocks

• Simpler interface afforded by use of direct pixel subscripts (bigimage uses world coordinates)

• Simpler interface for single-resolution level images (default resolution level is 1)

To display blocked image data, you still use the bigimageshow function.

Code Updates

Update all instances of the bigimage object.

Discouraged Usage	Recommended Replacement
This example creates a bigimage object. bim = bigimage('tumor_091R.tif');	Here is equivalent code, replacing the bigimage object with the new blockedImage object. bim = blockedImage('tumor_091R.tif');

Other Code Updates

The blockedImage object supports some different properties and object functions than the bigimage object. For example, to retrieve image data in a blocked image at a specified resolution level, replace calls to getFullLevel with use of the gather object function.