bigimage

Out-of-core processing of very large images

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

Description

example

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 bigimage object and sets the SpatialReferencing, Channels, and ClassUnderlying properties, without initializing the image data.

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

bigimg = bigimage(___,Name,Value) uses name-value pairs to set one or more of the BlockSize, UnloadedValue, and SpatialReferencing 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

expand all

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.

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

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

expand all

Image File Properties

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

This property is read-only.

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

Image Data Properties

This property is read-only.

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

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

Data Types: char | string

This property is read-only.

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

Data Types: double

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

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

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.

This property is read-only.

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

Data Types: double

This property is read-only.

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

Data Types: double

Default pixel value for unloaded blocks, specified as a numeric scalar or a numeric array of size 1-by-1-by-Channels. The data type of UnloadedValue must match the data type specified by ClassUnderlying.

Object Functions

applyProcess blocks of big image
isequalCompare two bigimages for equality
getBlockRead block of big image
getFullLevelGet all data in one level of big image
getRegionRead arbitrary region of big image
setBlockPut data in specific block of big image
writeWrite bigimage content to new file

Examples

collapse all

Load a bigimage. This examples uses a modified version of image "tumor_091.tif" from the CAMELYON16 data set. The original image is a training image of 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 coarse 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 = bigimage('tumor_091R.tif');

Display the entire bigimage at the finest resolution level. Display a grid of the block boundaries.

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

Determine the coarsest resolution level and the spatial referencing of the bigimage at that level.

clevel = bim.CoarsestResolutionLevel;
clevelLims = bim.SpatialReferencing(clevel);

Create a mask of the coarsest resolution level by following these steps:

  1. Get a single-resolution image of the coarsest resolution level.

  2. Convert the image to grayscale.

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

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

imcoarse = getFullLevel(bim,clevel);
graycoarse = rgb2gray(imcoarse);
bwcoarse = imbinarize(graycoarse);
mask = imcomplement(bwcoarse);

Create a bigimage containing the mask. Use the same spatial referencing as the original big image.

bmask = bigimage(mask,'SpatialReferencing',clevelLims);

Display the mask.

figure
bigimageshow(bmask);

Overlay the mask on the original bigimage. To highlight all blocks that contain at least one nonzero mask pixel, specify an inclusion threshold of 0.

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

Introduced in R2019b