blockedImage
Description
A blockedImage
object is an image made from discrete blocks. You
can use a blocked image to:
Process multiresolution (also known as multilevel or pyramidal) images.
Process images, volumes, or multidimensional images that are too large to fit into memory.
Process volumes or multidimensional images as 3-D or higher-dimensional blocks.
Perform block processing on images in nonstandard image formats.
Creation
Syntax
Description
Create Read-only Blocked Image
[bim1,bim2,...] = blockedImage(
creates an array of sources
)blockedImage
objects from multiple sources. The
sources can be a collection of files or folders with blocked image data. The number of
blocked images is equal to the number of sources.
[___] = blockedImage(___,
sets one or more writable properties using name-value arguments.Name=Value
)
For example, bim = blockedImage(source,BlockSize=[64 128])
specifies a block size of 64-by-128 pixels.
Create Writable Blocked Image
bim = blockedImage(
creates a writable dest
,imageSize
,blockSize
,initVal
,Mode="w")blockedImage
object with one or multiple resolution
levels. The dest
argument specifies the location of the writable
data. Specify the imageSize
and blockSize
arguments as the image size and block size at each resolution level, respectively.
Specify the initVal
argument as the initial value for each array
element.
bim = blockedImage(
also sets one or more writable properties using name-value arguments.dest
,imageSize
,blockSize
,initVal
,Mode="w",Name=Value
)
For example, bim =
blockedImage(dest,imageSize,blockSize,initVal,Mode="w",Adapter=images.blocked.JPEGBlocks)
specifies that the blockedImage
object write each block as a JPEG file
in a folder.
Input Arguments
Source of image data, specified as one of these values.
An in-memory numeric, categorical, or structure array.
A cell array of in-memory numeric, categorical, or structure arrays. When you specify a cell array,
blockedImage
creates a multilevel blocked image, where each level corresponds to one element of the cell array.A string scalar or character vector specifying the name of an image file or the name of a folder containing blocked image data. A folder must contain only data written by a previous call to the
write
function.
Blocked images support these file formats:
This argument sets the Source
property.
Sources of image data when creating multiple blocked image objects, specified as one of these values.
Each element or file of sources
sets the Source
property of the
corresponding blockedImage
object.
Location to place writable data, specified as a character vector or string scalar.
Destination Type | Image Format |
---|---|
Folder name (without a file extension) | The
|
File name with TIF or TIFF file extension | The The |
File name with H5 file extension | The The |
[] | The |
To specify a custom adapter for other output formats, use the Adapter
name-value
argument.
Image size at each resolution level for a writable blocked image, specified as an L-by-N matrix of positive integers. L is the number of resolution levels and N is the number of dimensions of the image.
This argument sets the Size
property. The
blockedImage
object always sorts the Size
property in descending order by number of pixels, regardless of how the Source
property stores
the levels.
Data Types: double
Block size for a writable blocked image, specified as an
L-by-N matrix of positive integers.
L is the number of resolution levels and N is
the number of dimensions. blockSize
serves as the default size of
data that is loaded into main memory at any time for use. It is the smallest unit of
data that can be manipulated by a blockedImage
object.
If the image has multiple resolution levels, then you can specify
blockSize
as a 1-by-N vector to use the same block size for all resolution levels.The dimensionality of the blocks must match the dimensionality of the
imageSize
argument.
For a read-only blockedImage
, you cannot specify the
blockSize
argument. Instead, use the BlockSize
name-value
argument.
This argument sets the BlockSize
property.
Example: [64 128]
specifies a block size of 64-by-128 pixels.
This value is supported for a single resolution image, or for a multilevel image when
all resolution levels have the same block size.
Example: [128 128; 64 64; 32 32]
specifies three different block
sizes for a blocked image with three resolution levels.
Data Types: double
Default pixel value for unloaded blocks of a writable blocked image, specified as one of these values.
Numeric or logical scalar. The default value is
0
.Categorical scalar. The default value is
<undefined>
.Structure with the same field names as the data. The default value is
<undefined>
.
The blockedImage
object uses the initial value to fill blocks
that do not have data in the underlying source.
This argument sets the InitialValue
property.
The data type of initVal
sets the value of the ClassUnderlying
property.
Data Types: single
| double
| int8
| int16
| int32
| uint8
| uint16
| uint32
| char
| categorical
| struct
Name-Value Arguments
Specify optional pairs of arguments as
Name1=Value1,...,NameN=ValueN
, where Name
is
the argument name and Value
is the corresponding value.
Name-value arguments must appear after other arguments, but the order of the
pairs does not matter.
Example: bim = blockedImage(source,BlockSize=[64 128])
specifies a
block size of 64-by-128 pixels.
Read and write interface for the blocked image object, specified as one of these adapter objects.
Adapter | Description |
---|---|
BINBlocks | Store each block as a binary file in a folder |
GenericImage
| Store blocks in a single image |
GenericImageBlocks | Store each block as an image file in a folder |
H5 | Store blocks in a single HDF5 image |
H5Blocks | Store each block as an HDF5 file in a folder |
InMemory | Store blocks in a variable in main memory |
JPEG2000 | Read blocks of a single JPEG2000 file (since R2023a) |
JPEGBlocks | Store each block as a JPEG file in a folder |
MATBlocks | Store each block as a MAT file in a folder |
PNGBlocks | Store each block as a PNG file in a folder |
TIFF | Store 2-D blocks in a single TIFF file |
TIFF3D | Read 3-D blocks in a single TIFF file (since R2024b) |
You can also create your own adapter using the images.blocked.Adapter
class.
For a writeable blocked image, you cannot specify the adapter as a
JPEG2000
object.
This argument sets the Adapter
property.
Alternate file system path for the files specified in Source
, specified as a
string array containing one or more rows. Each row specifies a set of equivalent
root paths.
This argument sets the AlternateFileSystemRoots
property.
Example: ["Z:\datasets", "/mynetwork/datasets"]
Data Types: char
| string
| cell
Block size for a read-only blocked image, specified as an
L-by-N matrix of positive integers.
L is the number of resolution levels and N
is the number of dimensions. BlockSize
serves as the default
size of data that is loaded into main memory at any time for use. It is the smallest
unit of data that can be manipulated by a blockedImage
object.
If the image has multiple resolution levels, then you can specify
BlockSize
as a 1-by-N vector to use the same block size for all resolution levels.You can specify
BlockSize
with less than N dimensions. In this case, theblockedImage
object pads the block size with elements from theSize
property.
For a writable blockedImage
, you cannot specify the
BlockSize
name-value argument. Instead, use the blockSize
argument.
This argument sets the BlockSize
property.
Example: [64 128]
specifies a block size of 64-by-128 pixels.
This value is supported for a single resolution image, or for a multilevel image
when all resolution levels have the same block size. This value is also supported
for a readable blocked image of one or multiple resolution levels when the
dimensionality of the Size
property is greater than
two.
Example: [128 128; 64 64; 32 32]
specifies three different
block sizes for a blocked image with three resolution levels.
Data Types: double
User data associated with the image, specified as a structure. This field can be
empty. You can update the value at any time. To make this value persist with the
source, write the blockedImage
to a file using the write
function, or specify the data as parameter when you create the object.
This argument sets the UserData
property.
Data Types: struct
World coordinates of ending edge of the image, specified as an
L-by-N numeric matrix. L
is the number of resolution levels and N is the number of
dimensions. By default, the value is
for each dimension and level, resulting in pixels that are one-unit wide. World
coordinates of pixel centers coincide with pixel subscript locations for the first
level.Size
+ 0.5
This argument sets the WorldEnd
property.
Data Types: double
World coordinates of the starting edge of the image, specified as an
L-by-N numeric matrix. L
is the number of resolution levels and N is the number of
dimensions. By default, the starting-edge value is 0.5
in each
dimension and level.
This argument sets the WorldStart
property.
Data Types: double
Properties
Read and write interface for the blocked image object, specified as one of these adapter objects.
Adapter | Description |
---|---|
BINBlocks | Store each block as a binary file in a folder |
GenericImage
| Store blocks in a single image |
GenericImageBlocks | Store each block as an image file in a folder |
H5 | Store blocks in a single HDF5 image |
H5Blocks | Store each block as an HDF5 file in a folder |
InMemory | Store blocks in a variable in main memory |
JPEG2000 | Read blocks of a single JPEG2000 file (since R2023a) |
JPEGBlocks | Store each block as a JPEG file in a folder |
MATBlocks | Store each block as a MAT file in a folder |
PNGBlocks | Store each block as a PNG file in a folder |
TIFF | Store 2-D blocks in a single TIFF file |
TIFF3D | Read 3-D blocks in a single TIFF file (since R2024b) |
You can also create your own adapter using the images.blocked.Adapter
class.
When you specify Mode
as
"w"
, you cannot specify the adapter as a JPEG2000
object.
Alternate file system path for the files specified in Source
, specified as a
string array containing one or more rows. Each row specifies a set of equivalent root
paths.
Example: ["Z:\datasets", "/mynetwork/datasets"]
Data Types: char
| string
| cell
Block size, specified as an L-by-N matrix of
positive integers. L is the number of resolution levels and
N is the number of dimensions. BlockSize
serves as the default size of data that is loaded into main memory at any time for use.
It is the smallest unit of data that can be manipulated by a
blockedImage
object.
If the image has multiple resolution levels, then you can specify
BlockSize
as a 1-by-N vector to use the same block size for all resolution levels.For a read-only
blockedImage
, you can specifyBlockSize
with less than N dimensions. In this case, theblockedImage
object pads the block size with elements from theSize
property. You can change the value of theBlockSize
property after you create the object by using dot notation.For a writable
blockedImage
, the dimensionality of the blocks must match the dimensionality of theSize
property. You cannot change the value of theBlockSize
property after you create the object.
Example: [64 128]
specifies a block size of 64-by-128 pixels. This
value is supported for a single resolution image, or for a multilevel image when all
resolution levels have the same block size. This value is also supported for a readable
blocked image of one or multiple resolution levels when the dimensionality of the
Size
property is greater than two.
Example: [128 128; 64 64; 32 32]
specifies three different block
sizes for a blocked image with three resolution levels.
Data Types: double
This property is read-only.
Pixel data type, specified as a string array with L elements,
where L is number of resolution levels. Each element in the array is
the data type of a pixel from the corresponding resolution level. Values are:
"logical"
, "int8"
, "uint8"
,
"int16"
, "uint16"
, "int32"
,
"uint32"
, "single"
, "double"
,
"categorical"
, and "struct"
.
Data Types: string
This property is read-only after object creation.
Default pixel value for unloaded blocks, returned as one of these values.
Numeric or logical scalar. The default value is
0
.Categorical scalar. The default value is
<undefined>
.Structure with the same field names as the data. The default value is
<undefined>
.
The blockedImage
object uses the initial value to fill blocks that
do not have data in the underlying source.
Data Types: single
| double
| int8
| int16
| int32
| uint8
| uint16
| uint32
| char
| categorical
| struct
This property is read-only.
I/O block size of image source, specified as an
L-by-N matrix of positive integers.
L is the number of resolution levels and N is
the number of dimensions. IOBlockSize
is the size of the underlying
I/O block size the adapter uses to read from the image source. This represents the
smallest unit of data that can be written or read. This property reflects the format of
the underlying image source.
Note
You can set BlockSize
to any value. The
blockedImage
object does the appropriate reading, cropping,
stitching, and caching of the source I/O blocks to ensure efficient I/O.
Data Types: double
Current read or write mode of the object, specified as "r"
for
read mode and "w"
for write mode.
You can only set Mode
to "w"
when you create
the object. You can change the value of Mode
from
"w"
to "r"
, at which point no further writes are
possible. You cannot change Mode
from "r"
to
"w"
.
Data Types: string
| char
This property is read-only.
Number of dimensions in the image, specified as a positive integer. For multilevel
images that have varying number of dimensions, NumDimensions
is the
maximum taken across all levels. The blocked image extends other levels with singleton
dimensions, if needed.
Data Types: double
This property is read-only.
Number of image resolution levels, specified as a positive integer.
Data Types: double
This property is read-only after object creation.
Image size at each resolution level, returned as an
L-by-N matrix of positive integers.
L is the number of resolution levels and N is
the number of dimensions of the image. The blockedImage
object always
sorts the Size
property in descending order by number of pixels,
regardless of how the Source
property stores the levels.
Data Types: double
This property is read-only.
Size expressed as the number of blocks, specified as an
L-by-N matrix of positive integers.
L is the number of resolution levels and N is
the number of dimensions. The value of SizeInBlocks
includes
partial blocks.
This property is dependent on the BlockSize
property.
Data Types: double
This property is read-only after object creation.
Source of image data, specified as one of these values.
An in-memory numeric, categorical, or structure array.
A cell array of in-memory numeric, categorical, or structure arrays. When you specify a cell array,
blockedImage
creates a multilevel blocked image, where each level corresponds to one element of the cell array.A string scalar or character vector specifying the name of an image file or the name of a folder containing blocked image data. A folder must contain only data written by a previous call to the
write
function.
Blocked images support these file formats:
World coordinates of ending edge of the image, specified as an
L-by-N numeric matrix. L is
the number of resolution levels and N is the number of dimensions. By
default, the value is
for
each dimension and level, resulting in pixels that are one-unit wide. World coordinates
of pixel centers coincide with pixel subscript locations for the first level.Size
+ 0.5
Data Types: double
World coordinates of the starting edge of the image, specified as an
L-by-N numeric matrix. L is
the number of resolution levels and N is the number of dimensions. By
default, the starting-edge value is 0.5
in each dimension and
level.
Data Types: double
User data associated with the image, specified as a structure. This field can be
empty. You can update the value at any time. To make this value persist with the source,
write the blockedImage
to a file using the write
function, or specify the data as parameter when you create the object.
Data Types: struct
Object Functions
apply | Process blocks of blocked image |
concatenateLevels | Concatenate levels from multiple blocked images |
crop | Create cropped version of blocked image |
blocksub2sub | Convert block subscripts to pixel subscripts |
gather | Collect blocks into current workspace |
getBlock | Read specific block of blocked image |
getRegion | Read arbitrary region of blocked image |
setBlock | Put data in specific block of blocked image |
makeMultiLevel2D | 2-D multilevel blocked image |
makeMultiLevel3D | 3-D multilevel blocked image |
sub2blocksub | Convert pixel subscripts to block subscripts |
sub2world | Convert pixel subscripts to world coordinates |
world2sub | Convert world coordinates to pixel subscripts |
write | Write blocked image data to new destination |
Examples
Create a blocked image using a modified version of image tumor_091.tif
from the CAMELYON16 data set. The image shows 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 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 = blockedImage("tumor_091R.tif");
Display the blocked image.
imageshow(bim);
Read data into the workspace. For this example, read a sample volume that is included with the toolbox.
dmri = tiffreadVolume('mri.tif');
Create a blocked image from the volume.
bim = blockedImage(dmri);
Display details about the blocked image at the command line.
disp(bim)
blockedImage with properties: Read only properties Source: [128×128×27 uint8] Adapter: [1×1 images.blocked.InMemory] Size: [128 128 27] SizeInBlocks: [1 1 1] ClassUnderlying: "uint8" Settable properties BlockSize: [128 128 27]
Create a file set of the images in the toolbox folder of sample images.
fs = matlab.io.datastore.FileSet( ... fullfile(matlabroot,'toolbox','images','imdata'), ... "FileExtensions",{'.jpg','.png'});
Create an array of blocked images from the images in the file set.
bims = blockedImage(fs);
Display details of the array of blocked images.
disp(bims)
1×67 blockedImage array with properties: Read only properties Source: 'Various' Adapter: [1×1 images.blocked.GenericImage] ClassUnderlying: 'Various' Settable properties No properties.
Create a blocked image to which you can write data. You specify the format of the blocked image in the destination
parameter. To write to memory, specify an empty matrix. You must also specify the size of the image and the size of the blocks into which you want the image chunked. The initial value parameter depends on the format you specified in destination. To create a writable blocked image, specify the 'Mode'
parameter with the value 'w'
for write mode.
destination = []; imgsize = [5 7]; blocksize = [2 2]; initval = uint8(0); bim = blockedImage(destination,imgsize,blocksize,initval, "Mode", 'w');
Write data to the specified blocks in the blocked image by using the setBlock
object function. The blocksubs
parameter specifies the coordinates of the block to which you want to write data. The blockdata
parameter specifies the data to write to the specified block. The size of blockdata must match the block size.
blocksubs = [1 1];
blockdata = ones(2,2,"uint8");
setBlock(bim, blocksubs, blockdata)
Close the image for writing.
Switch the blocked image to read mode by setting the 'Mode' parameter to 'r' for read.
bim.Mode = 'r'
bim = blockedImage with properties: Read only properties Source: " {5×7 uint8}↵" Adapter: [1×1 images.blocked.InMemory] Size: [5 7] SizeInBlocks: [3 4] ClassUnderlying: "uint8" Settable properties BlockSize: [2 2]
Create the full image by using the gather
function to collect all the individual blocks.
fullImage = gather(bim);
Display details of the blocked image at the command line.
disp(fullImage)
1 1 0 0 0 0 0 1 1 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0
If your application requires measuring coordinates or distances in world units, you can define custom world coordinates by specifying the WorldStart
and WorldEnd
properties of the blockedImage
object.
Create a blocked image using a modified version of image tumor_091.tif
from the CAMELYON16 data set. The image shows 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 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 = blockedImage("tumor_091R.tif");
Specify the pixel size, in millimeters, in the finest resolution level. For this image, the pixel size is approximately 0.22 micrometers, which is typical for 100x microscopy objectives. This information is available from the raw data on the Camelyon 17 Grand Challenge website.
pixelSpacing = 0.000226316;
Specify the position of the upper-left edge of the first pixel, assuming (0, 0) for all three resolution levels.
worldStart = zeros(bim.NumLevels, bim.NumDimensions);
Calculate the position of the lower-right edge of the last pixel of the finest resolution level. The location is the product of the number of pixels and the pixel size, in millimeters.
worldEnd = bim.Size(1,:)*pixelSpacing;
Expand the worldEnd
value using repmat
to specify the same position for all three resolution levels.
worldEnd = repmat(worldEnd,[bim.NumLevels,1]);
Update the WorldStart
and WorldEnd
property values.
bim.WorldStart = worldStart; bim.WorldEnd = worldEnd;
Display the updated blocked image. To use the correct units label, parent the image display to a Viewer
object with a SpatialUnits
property value of "mm"
. Note that the SpatialUnits
property only affects the annotation label text. The world coordinates of the blockedImage
object determine the values of spatial coordinates in the displayed image.
viewer = viewer2d(ScaleBar="on",ScaleBarStyle="measure",SpatialUnits="mm"); imageshow(bim,Parent=viewer);
Tips
The
blockproc
function is an alternative toblockedImage
for processing 2-D blocks of single-resolution in-memory images.
Version History
Introduced in R2021aThe new TIFF3D
adapter
supports reading blocks of 3-D TIFF files in these formats:
Image data stored in the file as individual Image File Directories (IFDs) of the same size and data type.
Image data stored as large files greater than 4GB, not of the BigTIFF format, created by ImageJ software.
You can create multilevel blocked images by specifying a cell array of in-memory
numeric, categorical, or structure arrays. Each level corresponds to one element of the cell
array. You can also create multilevel blocked images by using the makeMultiLevel2D
and makeMultiLevel3D
functions. These functions are particularly useful when you
want to create overview levels for a very large image.
You can combine the levels of two or more blocked images using the concatenateLevels
function. This function supports combining data in different
formats and in different locations. To efficiently add overview levels to a very large image
on disk, you can create the overview levels in memory, and then combine the original image
and the overview levels using concatenateLevels
.
The JPEG2000
adapter
reads blocks of a single JPEG2000 file.
MATLAB Command
You clicked a link that corresponds to this MATLAB command:
Run the command by entering it in the MATLAB Command Window. Web browsers do not support MATLAB commands.
Select a Web Site
Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .
You can also select a web site from the following list
How to Get Best Site Performance
Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.
Americas
- América Latina (Español)
- Canada (English)
- United States (English)
Europe
- Belgium (English)
- Denmark (English)
- Deutschland (Deutsch)
- España (Español)
- Finland (English)
- France (Français)
- Ireland (English)
- Italia (Italiano)
- Luxembourg (English)
- Netherlands (English)
- Norway (English)
- Österreich (Deutsch)
- Portugal (English)
- Sweden (English)
- Switzerland
- United Kingdom (English)