bigimage

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

The bigimage object will be removed in a future release. Use the blockedImage object instead. For more information, see Version History.

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.

example

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

`filename` — Name of big image file
string scalar | character vector

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

expand all

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

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.

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`	(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 Single-Resolution Mask from Multiresolution Big Image

Open Live Script

Create a big 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 = 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);

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

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:

Get a single-resolution image of the coarsest resolution level.
Convert the image to grayscale.
Binarize the image. In the binarized image, the object of interest is black and the background is white.
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 bigimage.

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

Display the mask.

figure
bigimageshow(bmask);

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

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

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.

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

Version History

Introduced in R2019b

expand all

R2024b: Warns

The bigimage object issues a warning that it will be removed in a future release.

R2023b: To 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 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");

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.

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.

bigimage

Description

Creation

Syntax

Description

Input Arguments

filename — Name of big image file string scalar | character vector

dirname — Name of big image directory string scalar | character vector

varname — Big image variable numeric array

Properties

Image File Properties

DataSource — Location of data character vector

SourceDetails — Source metadata struct

Image Data Properties

BlockSize — Block size 2-element row vector

Channels — Number of channels positive integer

Classes — Class names string array | cell array of character vectors

ClassUnderlying — Data type of image pixels "double" | "single" | "uint8" | "uint16" | ...

CoarsestResolutionLevel — Coarsest resolution level positive integer

FinestResolutionLevel — Finest resolution level positive integer

LevelSizes — Image dimensions at each resolution level r-by-2 matrix of positive integers

PixelLabelIDs — Pixel label IDs c-element numeric vector | c-by-3 numeric array of data type uint8

SpatialReferencing — Pixel locations and sizes scalar imref2d object | r-by-1 vector of imref2d objects

UndefinedID — Pixel label value for '<undefined>' categorical class 0 (default) | numeric scalar | 1-by-3 numeric vector

UnloadedValue — Default pixel value logical scalar | numeric scalar | 1-by-1-by-Channels numeric vector | string scalar

Object Functions

Examples

Create Single-Resolution Mask from Multiresolution Big Image

Tips

References

Version History

R2024b: Warns

R2023b: To be removed

R2021a: bigimage is not recommended

See Also

`filename` — Name of big image file
string scalar | character vector

`dirname` — Name of big image directory
string scalar | character vector

`varname` — Big image variable
numeric array

`DataSource` — Location of data
character vector

`SourceDetails` — Source metadata
struct

`BlockSize` — Block size
2-element row vector

`Channels` — Number of channels
positive integer

`Classes` — Class names
string array | cell array of character vectors

`ClassUnderlying` — Data type of image pixels
`"double"` | `"single"` | `"uint8"` | `"uint16"` | ...

`CoarsestResolutionLevel` — Coarsest resolution level
positive integer

`FinestResolutionLevel` — Finest resolution level
positive integer

`LevelSizes` — Image dimensions at each resolution level
r-by-2 matrix of positive integers

`PixelLabelIDs` — Pixel label IDs
c-element numeric vector | c-by-3 numeric array of data type `uint8`

`SpatialReferencing` — Pixel locations and sizes
scalar `imref2d` object | r-by-1 vector of `imref2d` objects

`UndefinedID` — Pixel label value for `'<undefined>'` categorical class
`0` (default) | numeric scalar | 1-by-3 numeric vector

`UnloadedValue` — Default pixel value
logical scalar | numeric scalar | 1-by-1-by-`Channels` numeric vector | string scalar

R2021a: `bigimage` is not recommended