blockedImage
Image made from discrete blocks
Description
A blockedImage
object is an image made from discrete blocks. Use
blocked images when an image or volume is too large to fit into memory. With a blocked image,
you can perform processing without running out of memory.
Creation
Syntax
Description
Create Read-only blockedImage
Objects
bim = blockedImage(
creates a
source
)blockedImage
object from the specified source. The source can be an
in-memory array or the name of a file or folder with image data.
bims = blockedImage(
creates an
array of sources
)blockedImage
objects from multiple sources. The source can be
a collection of files or folders with image data. The length of
bims
is equal to the number of sources in
sources
.
___ = blockedImage(___,
creates a Name,Value
)blockedImage
object, using one or more name-value arguments
to set object properties.
Create Writable blockedImage
Object
wbim = blockedImage(
creates a writeable destination
,size
,blockSize
,initialValue
,"Mode","w")blockedImage
object at one or multiple resolution
levels. destination
specifies the location of the writable data.
size
indicates the image size at each resolution level.
initialValue
indicates the initial value for each array
element.
Input Arguments
source
— Source of image data
numeric array | categorical array | structure array | character vector | string scalar
Source of image data, specified as a numeric array, categorical array, or structure array, or a character vector or string scalar specifying the name of a file or folder.
Blocked images supports these file formats:
Single TIFF file. If the file contains multiple Image File Directories (IFDs), the
blockedImage
object treats the IFDs as multiple resolution levels.Any image file that can be read by
imread
.Any source created by the adapters included with the toolbox, listed in
Adapter
.
sources
— Sources of image data
cell array of character vectors | string array | FileSet
object
Sources of image data, specified as an cell array of character vectors, a string
array, or a FileSet
object.
destination
— Location to place writeable data
[]
| character vector | string scalar
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
property.
size
— Image size at each resolution level
L-by-N matrix
Image size at each resolution level, specified as an
L-by-N matrix of positive integers, where
L is the number of resolution levels and N is
the number of dimensions of the image. The blockedImage
object always
sorts size
in descending order by number of pixels, irrespective
of how Source
stores the levels.
blockSize
— Size of blocks
L-by-N matrix
Size of blocks, specified as an L-by-N matrix of positive integers, where L is the number of resolution levels and N is the number of dimensions.
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.
Example: [64 128]
specifies a block size of 64-by-128 pixels for
a single resolution image
Example: [128 128; 64 64; 32 32]
specifies three different block
sizes for three resolution levels
initialValue
— Default element value for unloaded blocks
numeric scalar | categorical scalar | struct scalar
Default pixel value for unloaded blocks, specified as one of these values. The blocked image uses this value to fill blocks which do not have data in the underlying source.
Numeric scalar. The data type of
initialValue
specifies the value of theClassUnderlying
property. The default value is0
.Categorical scalar. The default value is
<undefined>
.Structure with the same field names as the data. The default value is
<undefined>
.
Properties
Adapter
— Read and write interface for blocked image object
InMemory
object | MATBlocks
object | PNGBlocks
object | TIFF
object | ...
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 |
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 blocks in a single TIFF file |
You can also create your own adapter using the images.blocked.Adapter
class.
AlternateFileSystemRoots
— Alternate file system path
string array
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
BlockSize
— Size of blocks
L-by-N matrix
Size of blocks, specified as an L-by-N matrix
of positive integers, where 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 with the
blockedImage
interface. If you specify BlockSize
with less than N dimensions, blockedImage
pads the
image with elements from the Size
property.
You cannot specify this property when you specify Mode
as
'w'
.
Data Types: double
ClassUnderlying
— Pixel data type
cell array of character vectors | string vector | structure | categorical array
This property is read-only.
Pixel data type, specified as a cell array of character vectors, string array,
structure array, or categorical array, with L elements.
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"
, and
"double"
.
Data Types: char
| string
InitialValue
— Default element value for unloaded blocks
numeric scalar | categorical
scalar | struct
This property is read-only.
Default element value for unloaded blocks, specified as a numeric scalar of the type
specified by ClassUnderlying
, a categorical
value
for categorical images, or a struct
. The
blockedImage
object uses this value to fill blocks which do not
have data in the underlying source. The default value varies by data type:
0
for numeric types, <undefined>
for
categorical, and a scalar struct
.
Data Types: single
| double
| int8
| int16
| int32
| uint8
| uint16
| uint32
| char
| categorical
| struct
IOBlockSize
— I/O block size of image source
numeric matrix
This property is read-only.
I/O block size of image source, specified as an
L-by-N matrix of positive integers, where
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 read-only 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
Mode
— Current read or write mode
'r'
(default) | 'w'
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'
.
When opening a blockedImage
in write mode, you must also specify
values for the ImageSize
, BlockSize
, and
InitialValue
properties.
Data Types: char
NumDimensions
— Number of dimensions in image
positive integer
This property is read-only.
Number of dimensions in the image, specified as a positive integer. For
multiresolution level 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
NumLevels
— Number of image resolution levels
positive integer
This property is read-only.
Number of image resolution levels, specified as a positive integer.
Data Types: double
Size
— Image size at each level
L-by-N matrix
This property is read-only.
Image size at each level, specified as an
L-by-N matrix of positive integers, where
L is the number of resolution levels and N is
the number of dimensions of the image. The blockedImage
object always
sorts Size
in descending order by number of pixels, irrespective of
how Source
stores the levels.
Data Types: double
SizeInBlocks
— Size expressed as number of blocks
L-by-N matrix
This property is read-only.
Size expressed as the number of blocks, specified as an
L-by-N matrix of positive integers, where
L is the number of resolution levels and N is
the number of dimensions. This property is dependent on the BlockSize
property. The value includes partial blocks.
Data Types: double
Source
— Source of image data
string
scalar | numeric array | categorical
array | struct
array
This property is read-only.
Source of image data, specified as an in-memory numeric,
categorical
, or struct
array, or as a
string
scalar or char
vector specifying a file
or folder name.
Data Types: string
WorldEnd
— World coordinates of ending edge of image
numeric matrix
World coordinates of ending edge of the image, specified as an
L-by-N numeric matrix, where
L is the number of resolution levels and N is
the number of dimensions. By default, the value is Size + 0.5
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.
Data Types: double
WorldStart
— World coordinates of starting edge of image
numeric matrix
World coordinates of the starting edge of the image, specified as a
L-by-N numeric matrix, where
L is the number of 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
UserData
— User data associated with the image
struct
User data associated with the image, specified as a struct
. 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 |
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 |
sub2blocksub | Convert pixel subscripts to block subscripts |
sub2world | Convert pixel subscripts to block subscripts |
world2sub | Convert world coordinates to pixel subscripts |
write | Write blocked image data to new destination |
Examples
Create and Visualize Blocked Image
Create a blocked image from a sample image included with the toolbox.
bim = blockedImage('tumor_091R.tif');
Display details of the blocked image at the command line.
disp(bim)
blockedImage with properties: Read only properties Source: "/mathworks/devel/bat/Bdoc22b/build/matlab/toolbox/images/imdata/tumor_091R.tif" Adapter: [1x1 images.blocked.TIFF] Size: [3x3 double] SizeInBlocks: [3x3 double] ClassUnderlying: [3x1 string] Settable properties BlockSize: [3x3 double]
View the blocked image in a figure window.
bigimageshow(bim)
Create Blocked Image from Workspace Variable
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: [128x128x27 uint8] Adapter: [1x1 images.blocked.InMemory] Size: [128 128 27] SizeInBlocks: [1 1 1] ClassUnderlying: "uint8" Settable properties BlockSize: [128 128 27]
Create Array of Blocked Images
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)
1x74 blockedImage array with properties: Read only properties Source: 'Various' Adapter: [1x1 images.blocked.GenericImage] ClassUnderlying: 'Various' Settable properties No properties.
Write Data to Blocked Image and Read It Back
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: [5x7 uint8] Adapter: [1x1 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
Create Blocked Image Specifying Custom World Coordinates
Create a blocked image from a sample image included with the toolbox.
bim = blockedImage('tumor_091R.tif');
bigimageshow(bim)
Specify the distance between pixel centers at the finest level. This information obtained from the raw data available at https://camelyon17.grand-challenge.org/Data/.
pext = 0.000226316; % (in millimeters)
Assume the top-left edge of the first pixel starts at (0,0).
worldStart = zeros(bim.NumLevels, bim.NumDimensions);
Calculate the bottom right edge of the last pixel of the finest resolution level, using only the spatial dimensions. With the distance between each pixel center known, multiply the distance by the number of pixels.
worldEnd = bim.Size(1,:)*pext;
All resolution levels span the same world coordinates.
worldEnd = repmat(worldEnd,[bim.NumLevels,1]);
The third dimension holds the color channels, each with a pixel extent of 1. Update the world coordinates of the edges of the pixels to center them on integer values (in this case, 1, 2, and 3).
worldStart(:,3) = 0.5; worldEnd(:,3) = 3.5;
View the image with updated coordinates.
bim = blockedImage('tumor_091R.tif', ... 'WorldStart',worldStart,'WorldEnd',worldEnd); figure h = bigimageshow(bim); title('Measured in Millimeters')
Version History
Introduced in R2021a
See Also
MATLAB コマンド
次の MATLAB コマンドに対応するリンクがクリックされました。
コマンドを MATLAB コマンド ウィンドウに入力して実行してください。Web ブラウザーは MATLAB コマンドをサポートしていません。
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)