Main Content

blockedImage

Big or multiresolution image made from discrete blocks

Since R2021a

expand all in page

    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

    bim = blockedImage(Source)
    [bim1,bim2,...] = blockedImage(sources)
    [___] = blockedImage(___,Name=Value)
    bim = blockedImage(destination,Size,BlockSize,InitialValue,Mode="w")
    bim = blockedImage(destination,Size,BlockSize,InitialValue,Mode="w",Name=Value)

    Description

    Create Read-only Blocked Image

    bim = blockedImage(Source) creates a blockedImage object from an in-memory array, an image file, or a folder containing blocked image data. A folder must contain only data written by a previous call to the write function. Specify the Source property as the variable name, the filename, or the folder name.

    example

    [bim1,bim2,...] = blockedImage(sources) creates an array of 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(___,Name=Value) creates a blockedImage object and sets one or more of these properties by using name-value arguments: Adapter, AlternateFileSystemRoots, BlockSize, UserData, WorldStart, and WorldEnd.

    For example, bim = blockedImage(Source,BlockSize=[64 128]) specifies a block size of 64-by-128 pixels.

    Create Writable Blocked Image

    bim = blockedImage(destination,Size,BlockSize,InitialValue,Mode="w") creates a writeable blockedImage object with one or multiple resolution levels. The destination argument specifies the location of the writable data. Specify the Size and BlockSize properties as the image size and block size at each resolution level, respectively. Specify the InitialValue property as the initial value for each array element.

    bim = blockedImage(destination,Size,BlockSize,InitialValue,Mode="w",Name=Value) also sets one or more of these properties by using name-value arguments: Adapter, AlternateFileSystemRoots, UserData, WorldStart, and WorldEnd.

    For example, bim = blockedImage(destination,Size,BlockSize,InitialValue,Mode="w",Adapter=images.blocked.JPEGBlocks) specifies that the blockedImage object write each block as a JPEG file in a folder.

    Input Arguments

    expand all

    Sources of image data, specified as a cell array of character vectors, a string array, or a FileSet object.

    Use the sources input argument when you want to create multiple blockedImage objects. 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 TypeImage Format
    Folder name (without a file extension)

    The blockedImage object creates the folder and stores blocks of data as files within the folder.

    • For numeric image data, blockedImage stores each block as a binary file using the BINBlocks adapter.

    • For categorical and structure image data, blockedImage stores each block as a MAT file in the folder using the MATBlocks adapter.

    File name with TIF or TIFF file extension

    The blockedImage object stores data as a single TIFF image using the TIFF adapter.

    The initialValue must be numeric or logical with data type uint8, int8, uint16, int16,uint32, int32, single, double or logical.

    File name with H5 file extension

    The blockedImage object stores data as a single HDF5 image using the H5 adapter.

    The initialValue must be numeric with data type uint8, int8, uint16, int16, uint32, int32, single, or double.

    []

    The blockedImage object stores data as a variable in memory using the InMemory adapter.

    To specify a custom adapter for other output formats, use the Adapter property.

    Properties

    expand all

    Read and write interface for the blocked image object, specified as one of these adapter objects.

    AdapterDescription
    BINBlocksStore each block as a binary file in a folder
    GenericImage Store blocks in a single image
    GenericImageBlocksStore each block as an image file in a folder
    H5Store blocks in a single HDF5 image
    H5BlocksStore each block as an HDF5 file in a folder
    InMemoryStore blocks in a variable in main memory
    JPEG2000Read blocks of a single JPEG2000 file (since R2023a)
    JPEGBlocksStore each block as a JPEG file in a folder
    MATBlocksStore each block as a MAT file in a folder
    PNGBlocksStore each block as a PNG file in a folder
    TIFFStore 2-D blocks in a single TIFF file
    TIFF3DRead 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, 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 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 specify BlockSize with less than N dimensions. In this case, the blockedImage object pads the block size with elements from the Size property. You can change the value of the BlockSize property after you create the object by using dot notation.

    • For a writeable blockedImage, the dimensionality of the blocks must match the dimensionality of the Size property. You cannot change the value of the BlockSize 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

    Default pixel value for unloaded blocks, 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.

    For a writeable blockedImage, the data type of InitialValue sets the value of the ClassUnderlying property.

    You cannot change the value of this property after you create the blockedImage object.

    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, 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 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

    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, regardless of how the Source property stores the levels.

    You can only set this property when you create a writable blockedImage object. You cannot change the value of this property after you create the blockedImage object.

    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, 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 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:

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

    You cannot change the value of this property after you create the blockedImage object.

    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

    World coordinates of the starting 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 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

    applyProcess blocks of blocked image
    concatenateLevelsConcatenate levels from multiple blocked images
    cropCreate cropped version of blocked image
    blocksub2subConvert block subscripts to pixel subscripts
    gatherCollect blocks into current workspace
    getBlockRead specific block of blocked image
    getRegionRead arbitrary region of blocked image
    setBlockPut data in specific block of blocked image
    makeMultiLevel2D2-D multilevel blocked image
    makeMultiLevel3D3-D multilevel blocked image
    sub2blocksubConvert pixel subscripts to block subscripts
    sub2worldConvert pixel subscripts to world coordinates
    world2subConvert world coordinates to pixel subscripts
    writeWrite blocked image data to new destination

    Examples

    collapse all

    Open Script

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

    Open Script

    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]
    Open Live Script

    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)
      1x67 blockedImage array with properties:

   Read only properties
             Source: 'Various'
            Adapter: [1x1 images.blocked.GenericImage]
    ClassUnderlying: 'Various'

   Settable properties
    No properties.
    Open Script

    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
    Open Script

    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(SpatialUnits="mm");
imageshow(bim,Parent=viewer);

    Tips

    • The blockproc function is an alternative to blockedImage for processing 2-D blocks of single-resolution in-memory images.

    Version History

    Introduced in R2021a

    expand all

    See Also

    | |

    Topics