Main Content

bigimage

(To be removed) Out-of-core processing of very large images

Since R2019b

The bigimage object will be removed in a future release. 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

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

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

Examples

collapse all

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

Figure contains an axes object. The axes object contains an object of type bigimageshow.

Create a mask at 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 = im2gray(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)

Figure contains an axes object. The axes object contains an object of type bigimageshow.

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)

Figure contains an axes object. The axes object contains an object of type bigimageshow.

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.

Version History

Introduced in R2019b

expand all

R2023b: bigimage will be removed

This object will be removed in a future release. Use the blockedImage object instead.

Code Updates

Update all instances of the bigimage object.

Discouraged UsageRecommended 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");

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

See Also