bigimage

Out-of-core processing of very large images

expand all in page

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

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

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

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

This property is read-only.

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

Data Types: double

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

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

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

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

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.

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.

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 TypeFormat of UnloadedValue
Logical imageLogical 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 imageString scalar specifying an element of the Classes property.

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

Open Script

Create a bigimage using 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);

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.

See Also

| | |

Topics

External Websites

Introduced in R2019b

Image Processing Toolbox Documentation

Support