Main Content

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

    Description

    Create Read-only blockedImage Objects

    example

    bim = blockedImage(source) creates a blockedImage object from the specified source. source is either an in-memory numeric, categorical, or struct array, or a character vector or string scalar that points to a file or folder.

    bims = blockedImage(sources) creates an array of blockedImage objects from the specified sources. sources is either a cell array of char vectors, or an a string array pointing to files, or a FileSet object. The length of bims is equal to the number of sources in sources.

    ___ = blockedImage(___,Name,Value) creates a blockedImage object, using name-value pairs to set object properties.

    Create Writable blockedImage Object

    wbim = blockedImage(destination,size,blockSize,initialValue,'Mode','w') creates a writeable blockedImage object.

    To create a writable blocked image representing a single resolution level, N-D image, specify blockSize as a 1-by-N numeric array and size as a 1-by-N numeric array specifying the image size. initialValue is a numeric scalar, categorical, or struct value representing the initial value for each array element.

    To create a writable blocked image representing a multiresolution level image, specify size as an L-by-N numeric array where L represents the number of resolution levels. The blockedImage replicates whatever you specify for blocksize for the additional levels, if needed. For struct data, initialValue must have the same field names as the data. For categorical data, initialValue must be of the same categorical type as the final data.

    The destination and initialValue arguments determine the file format used by the blockedImage:

    • Folder name (without an extension) – Blocked image creates the folder and uses the images.blocked.BINBlocks adapter to write one binary file per block, filled with the numeric initialValue. For categorical and struct values, the blocked image uses the images.blocked.MATBlocks adapter. See Adapter for more information.

    • File name with .tif or .tiff file extension – Blocked image uses the images.blocked.TIFF adapter to write a TIFF file. initialvalue must be uint8, int8,uint16,int16,uint32, int32, single, double or logical.

    • File name with .h5 extension – Blocked image uses the images.blocked.H5 adapter to write an HDF5 file. initialvalue has to be uint8, int8,uint16,int16,uint32, int32, single, or double.

    • [] (empty brackets) – Blocked image uses the images.blocked.InMemory to store image in memory.

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

    Input Arguments

    expand all

    Source of image data, specified as an in-memory numeric array, categorical array, or struct array, or a char array 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 IFDs (Image File Directories), the blockedImage 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 of image data, specified as an cell array of char vectors, a string array, or a FileSet object.

    File or folder to contain data, specified as a char vector or string scalar.

    Image size at each resolution level, specified as integer-valued L-by-N matrix, 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.

    Size of blocks, specified as a 1-by-N numeric array.

    Default pixel value for unloaded blocks, specified as a scalar type of ClassUnderlying. The blocked image uses this value to fill blocks which do not have data in the underlying source. Default value is 0 for numerical types, <undefined> for categorical, and a scalar struct for struct data.

    Properties

    expand all

    Read and write interface for the blocked image object, specified as one of these adapters. You can also create your own adapter using the images.blocked.Adapter class.

    AdapterDescription
    images.blocked.BINBlocks Store each block as a binary blob file in a folder.
    images.blocked.GenericImage Store blocks in a single image.
    images.blocked.GenericImageBlocksStore each block as an image file in a folder
    images.blocked.H5 Store blocks in a single HDF5 image
    images.blocked.H5Blocks Store each block as an HDF5 file in a folder
    images.blocked.InMemoryStore blocks in a variable in main memory
    images.blocked.JPEGBlocksStore each block as a JPEG file in a folder
    images.blocked.MATBlocks Store each block as a MAT file in a folder.
    images.blocked.PNGBlocks Store each block as a PNG file in a folder.
    images.blocked.TIFFStore blocks in a single TIFF file.

    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

    Size of blocks, specified as an integer-valued, L-by-N matrix, 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.

    This property cannot be set when Mode is set to 'w'.

    Data Types: double

    This property is read-only.

    Pixel datatype, specified as a char array, string array, struct or categorical array, with L elements. L is number of resolution levels. Each element in the array is the datatype of a pixel from the corresponding resolution level. Values are: "logical", "int8", "uint8", "int16", "uint16", "int32", "uint32", "single", and "double".

    Data Types: char | string

    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

    This property is read-only.

    I/O block size of image source, specified as an integer-valued, L-by-N matrix where N is the number of dimensions and L is the number of resolution levels. 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

    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

    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

    This property is read-only.

    Number of image resolution levels, specified as a positive integer. For single resolution images, the value is 1; for multiresolution images with L levels, the value is L.

    Data Types: double

    This property is read-only.

    Image size at each level, specified as an integer-valued L-by-N matrix, 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

    This property is read-only.

    Size expressed as the number of blocks, specified as an integer-valued L-by-N matrix, where N is the number of dimensions and L is the number of resolution levels. This property is dependent on the BlockSize property. The value includes partial blocks.

    Data Types: double

    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

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

    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

    applyProcess blocks of blocked image
    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
    sub2blocksubConvert pixel subscripts to block subscripts
    sub2worldConvert pixel subscripts to block subscripts
    world2subConvert world coordinates to pixel subscripts
    writeWrite image data to a new destination

    Examples

    collapse all

    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/Bdoc21a/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)
    

    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 a fileset 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'
    
    

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

    Compute 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 color channels. Update the world coordinates of the edges of the pixels to center them on integer values (e.g. 1, 2, and 3) with unit extents.

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

    Introduced in R2021a