bigimageDatastore

(Removed) Datastore to manage blocks of bigimage data

The bigimageDatastore object has been removed (since R2026a). Use the blockedImageDatastore object instead. For more information, see Version History.

Description

A bigimageDatastore object manages a collection of image blocks that belong to one or more bigimage objects. A bigimageDatastore is analogous to an imageDatastore, which manages a collection of unrelated images.

Creation

Syntax

bigds = bigimageDatastore(images)

bigds = bigimageDatastore(images,levels)

bigds = bigimageDatastore(images,levels,Name,Value)

bigds = bigimageDatastore(images,"BlockLocationSet",blockLocationSet)

bigds = bigimageDatastore(images,"BlockLocationSet",blockLocationSet,Name=Value)

Description

Create Datastore that Reads Blocks Over Entire Image

bigds = bigimageDatastore(images) creates a datastore that manages a collection of image blocks at the finest resolution level of one or more bigimage objects, Images.

bigds = bigimageDatastore(images,levels) creates a datastore that manages a collection of image blocks of one or more bigimage objects, Images, at the specified resolution levels, Levels.

bigds = bigimageDatastore(images,levels,Name,Value) also uses name-value pairs to set one or more Properties except for BlockLocationSet. You can specify multiple name-value pairs. Enclose each property name in quotes.

Example: bigimageDatastore(bigimg,3,"BlockSize",[128 128],"IncompleteBlocks","pad") creates a datastore that reads blocks of size 128-by-128 at resolution level 3 from big image bigimg and zero-pads partial edge blocks.

Create Datastore that Reads Blocks at Specified Locations

bigds = bigimageDatastore(images,"BlockLocationSet",blockLocationSet) creates a datastore that reads blocks from bigimage objects, Images, using the resolution level, block size, and block positions specified by BlockLocationSet.

bigds = bigimageDatastore(images,"BlockLocationSet",blockLocationSet,Name=Value) also uses name-value arguments to set one or more of the BorderSize, IncompleteBlocks, PadMethod, and ReadSize properties. You can specify multiple name-value arguments. Enclose each property name in quotes.

Example: bigimageDatastore(bigimg,"BlockLocationSet",bls,"ReadSize",4) creates a datastore that reads four blocks at a time from big images bigimg according to the position, block size, and resolution level specified by bls.

Properties

BlockLocationSet — Block locations

blockLocationSet object

Block locations, specified as a blockLocationSet object.

BlockOffsets — Block offsets

1-by-2 vector of positive integers

Block offsets, specified as 1-by-2 vector of positive integers of the form [numrows numcols].

The default value is equal to BlockSize. To overlap blocks during calls to read, specify a smaller value. To add a gap between blocks, specify a larger value.

BlockSize — Block size

1-by-2 vector of positive integers

Block size of read data, specified as a 1-by-2 vector of positive integers of the form [numrows numcols]. The default value is equal to the BlockSize property of the first big image in Images at the first resolution level in Levels.

BorderSize — Border size

[0 0] (default) | 1-by-2 vector of nonnegative integers

Border size, specified as a 1-by-2 vector of nonnegative integers of the form [m n]. The function adds m rows above and below each block and n columns to the left and right of each block with data from the neighboring blocks. For blocks that lie on the edge of an image, data is padded according to IncompleteBlocks. By default, the datastore does not add a border to blocks.

Images — Big images

b-element vector of bigimage objects

Big images that supply blocks for the bigimageDatastore, specified as a b-element vector of bigimage objects. To read different resolution levels from the same big image, specify the same image multiple times in the vector.

IncompleteBlocks — Method to handle edge blocks

"same" (default) | "exclude" | "pad"

Method to handle edge blocks that are smaller than BlockSize, specified as one of these values.

Value	Meaning
"same"	Return data of the same size as the edge block.
"exclude"	Do not include edge blocks in calls to read.
"pad"	Pad incomplete blocks to the same size as BlockSize using the pad method specified by PadMethod.

Levels — Resolution level

positive integer | b-element vector of positive integers

Resolution level of blocks from each big image in Images, specified as a positive integer or a b-element vector of positive integers. If you specify a scalar value, then all big images supply blocks to the datastore at the same resolution level.

Data Types: double

PadMethod — Pad method

numeric scalar | string scalar | "replicate" | "symmetric"

Pad method of incomplete edge blocks, specified as one of these values. By default, the datastore pads numeric blocks with 0 and categorical blocks with missing.

Value	Meaning
numeric scalar	Pad numeric array with elements of constant value.
string scalar	Pad categorical array with the specified class in the Classes property of the underlying bigimage.
"replicate"	Pad by repeating border elements of array.
"symmetric"	Pad array with mirror reflections of itself.

ReadSize — Number of blocks to return

1 (default) | positive integer

Number of blocks to return in each call to read, specified as a positive integer.

Object Functions

combine	Combine data from multiple datastores
countEachLabel	(Removed) Count number of pixel labels for each class of bigimageDatastore object
hasdata	Determine if data is available to read
numpartitions	Number of datastore partitions
partition	(Removed) Partition bigimageDatastore
preview	Preview subset of data in datastore
read	(Removed) Read data from bigimageDatastore
readRelative	(Removed) Read neighboring block from bigimageDatastore using relative position
reset	Reset datastore to initial state
shuffle	Shuffle data in datastore
transform	Transform datastore
isPartitionable	Determine whether datastore is partitionable
isShuffleable	Determine whether datastore is shuffleable

Examples

Read Blocks from Big Image Datastore

Create a bigimage from the sample image "tumor_091R.tif".

bim = bigimage("tumor_091R.tif");

Create a bigimageDatastore object at resolution level 1. Specify a nondefault block size. Set the datastore to read four blocks at a time.

bimds = bigimageDatastore(bim,2,"BlockSize",[512 512],"ReadSize",4)

bimds = 
  bigimageDatastore with properties:

            ReadSize: 4
          BorderSize: [0 0]
           PadMethod: 0
              Images: [1x1 bigimage]
              Levels: 2
           BlockSize: [512 512]
        BlockOffsets: [512 512]
    IncompleteBlocks: 'same'
    BlockLocationSet: [1x1 blockLocationSet]

Read one batch of data from the datastore. Notice that the third block is a partial edge block and has a smaller size than interior blocks

blocks = read(bimds);

blocks=4×1 cell array
    {512x512x3 uint8}
    {512x512x3 uint8}
    {512x316x3 uint8}
    {512x512x3 uint8}

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

R2026a: Removed

The bigimageDatastore object has been removed. Use the blockedImageDatastore object instead.

Code Updates

Update all instances of the bigimageDatastore object.

Removed	Recommended
This example creates a bigimageDatastore object. bigIm = bigimage("tumor_091R.tif"); bigDS = bigimageDatastore(bigIm);	Here is equivalent code using a blockedImageDatastore object. blockedIm = blockedImage("tumor_091R.tif"); blockedDS = blockedImageDatastore(blockedIm);
This example creates a bigimageDatastore object that reads blocks at resolution level 2. bigIm = bigimage("tumor_091R.tif"); level = 2; bigDS = bigimageDatastore(bigIm,level);	Here is equivalent code using a blockedImageDatastore object. blockedIm = blockedImage("tumor_091R.tif"); level = 2; bls = selectBlockLocations(blockedIm,Levels=level); blockedDS = blockedImageDatastore(blockedIm,BlockLocationSet=bls);

The blockedImageDatastore object supports some different properties and functions than the bigimageDatastore object. For example, the blockedImageDatastore object does not support the BlockOffset and IncompleteBlocks properties, and it adds support for the TotalNumBlocks property. The blockedImageDatastore object does not support the readRelative function.

R2024b: Warns

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

R2023b: To be removed

The bigimageDatastore object will be removed in a future release.

R2021a: Not recommended

Starting in R2021a, the bigimageDatastore object, which reads data from bigimage objects, is no longer recommended. Instead, use the blockedImageDatastore object, which reads data from blockedImage objects. The blockedImage object offers several advantages including extension to N-D processing, a simpler interface, and custom support for reading and writing nonstandard image formats.

R2020b: Mask and InclusionThreshold properties are not recommended

Starting in R2020b, the Mask and InclusionThreshold properties of bigimageDatastore are no longer recommended. Instead, first specify a mask and inclusion threshold as input arguments to the selectBlockLocations function. Then, specify the resulting blockLocationSet object as an input to bigimageDatastore.

The table shows some typical usages of bigimageDatastore and how to update your code to use selectBlockLocations.

Not Recommended	Recommended
This example creates a bigimageDatastore object and specifies the masks using the Masks name-value argument. b = bigimageDatastore(bigimg,1,"Masks",m)	Here is equivalent code using a blockLocationSet object. bls = selectBlockLocations(bigimg,"Masks",m); b = bigimageDatastore(bigimg,"BlockLocationSet",bls)
This example creates a bigimageDatastore object at resolution level 3 and specifies the masks and inclusion threshold using the Masks and InclusionThreshold name-value arguments. b = bigimageDatastore(bigimg,3,"Masks",m,"InclusionThreshold",t)	Here is equivalent code using a blockLocationSet object. bls = selectBlockLocations(bigimg,"Levels",3, ... "Masks",m,"InclusionThreshold",t); b = bigimageDatastore(bigimg,"BlockLocationSet",bls)