Main Content

blockproc

Distinct block processing for image

collapse all in page

Syntax

B = blockproc(A,[m n],fun)
B = blockproc(src_filename,[m n],fun)
B = blockproc(adapter,[m n],fun)
B = blockproc(___,Name,Value)

Description

B = blockproc(A,[m n],fun) processes the input image A by applying the function fun to each distinct block of size [m n] and concatenating the results into the output image, B.

example

B = blockproc(src_filename,[m n],fun) processes the image with file name src_filename, reading and processing one block at a time. This syntax is useful for processing large images.

example

B = blockproc(adapter,[m n],fun) processes the source image specified by adapter, an ImageAdapter object. Use this syntax if you need a custom API for reading and writing to a particular image file format.

B = blockproc(___,Name,Value) uses name-value pair arguments to control various aspects of the block behavior.

example

Examples

collapse all

Open Live Script

Read image into the workspace.

I = imread('pears.png');

Create block processing function.

fun = @(block_struct) imresize(block_struct.data,0.15);

Process the image, block-by-block.

I2 = blockproc(I,[100 100],fun);

Display the original image and the processed image.

figure;
imshow(I);

Figure contains an axes object. The hidden axes object contains an object of type image.

figure;
imshow(I2);

Figure contains an axes object. The hidden axes object contains an object of type image.

Open Live Script

Create block processing function.

fun = @(block_struct) ...
   std2(block_struct.data) * ones(size(block_struct.data));

Perform the block processing operation, specifying the input image by filename.

I2 = blockproc('moon.tif',[32 32],fun);

Display the original image and the processed version.

figure;
imshow('moon.tif');

Figure contains an axes object. The hidden axes object contains an object of type image.

figure;
imshow(I2,[]);

Figure contains an axes object. The hidden axes object contains an object of type image.

Open Live Script

Read image into the workspace.

I = imread('peppers.png');

Create block processing function.

fun = @(block_struct) block_struct.data(:,:,[2 1 3]);

Perform the block processing operation.

blockproc(I,[200 200],fun,'Destination','grb_peppers.tif');

Display original image and the processed image.

figure;
imshow('peppers.png');

Figure contains an axes object. The hidden axes object contains an object of type image.

figure;
imshow('grb_peppers.tif');

Figure contains an axes object. The hidden axes object contains an object of type image.

Note: To run this example, you must replace "largeImage.tif" with the name of your file.

Create block processing function.

fun = @(block_struct) block_struct.data;

Convert a TIFF image into a new JPEG2000 image. Replace "largeImage.tif" with the name of an actual image file.

blockproc("largeImage.tif",[1024 1024],fun,"Destination","New.jp2");

Input Arguments

collapse all

Image to process, specified as a numeric array.

Source file name, specified as a character vector or string scalar. Files must have one of these file types and must be named with one of the listed file extensions.

  • TIFF (*.tif, *.tiff)

  • JPEG2000 (*.jp2, *.jpf, *.jpx, *.j2c, *.j2k)

Data Types: char | string

Image adapter, specified as an ImageAdapter object. An ImageAdapter is a user-defined class that provides blockproc with a common API for reading and writing to a particular image file format. For more information, see Perform Block Processing on Image Files in Unsupported Formats.

Block size, specified as a 2-element vector. m is the number of rows and n is the number of columns in the block.

Function handle, specified as a handle. The function must accept a block_struct as input and return an array, vector, or scalar. If fun returns empty, then blockproc does not generate any output and returns empty after processing all blocks.

For more information about function handles, see Create Function Handle.

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: B = blockproc(A,[m,n],fun,BorderSize=[8 4]) creates a border with 8 rows and 4 columns around each block.

Before R2021a, use commas to separate each name and value, and enclose Name in quotes.

Example: B = blockproc(A,[m,n],fun,"BorderSize",[8 4]) creates a border with 8 rows and 4 columns around each block.

Destination for the output, specified as one of the following. When you specify the Destination argument, blockproc does not return the processed image as an output argument, but instead writes the output to the destination file.

  • A character vector or string scalar with a destination file name. Files must have one of these file types and must be named with one of the listed file extensions.

    • TIFF (*.tif, *.tiff)

    • JPEG2000 (*.jp2, *.j2c, *.j2k)

    If a file with this name exists, then it is overwritten.

  • An ImageAdapter object, which provides a common API for reading and writing to a particular image file format. For more information, see Perform Block Processing on Image Files in Unsupported Formats.

The Destination argument is useful when you expect your output to be too large to fit into memory. It provides a workflow for file-to-file image processing for arbitrarily large images.

Note

You cannot request an output argument when you specify the Destination argument.

Number of border pixels to add to each block, specified as a 2-element vector of positive integers, of the form [v h]. The function adds v rows above and below each block and h columns left and right of each block. The size of each resulting block is: 

[m+2*v, n+2*h]

By default, the function automatically removes the border from the result of fun. See the TrimBorder argument for more information.

The function pads blocks with borders extending beyond the image edges with zeros.

Pad partial blocks to make them full-sized, specified as false or true. Partial blocks arise when the image size is not exactly divisible by the block size. If they exist, partial blocks lie along the right and bottom edge of the image.

When set to true, blockproc pads partial blocks to make them full-sized m-by-n blocks. The default is false, meaning that the function does not pad the partial blocks, but processes them as-is. blockproc uses zeros to pad partial blocks when necessary.

Method used to pad the image boundary, specified as one of the following.

ValueDescription
"replicate"Repeat border elements.
"symmetric"Pad image with mirror reflections of itself.
numeric scalarPad image with a scalar value. By default, the image boundary is padded with the value 0.

Data Types: char | string

Remove border pixels from the output of the user function, specified as true or false. When set to true, the blockproc function removes border pixels from the output of the user function, fun. The function removes v rows from the top and bottom of the output of fun, and h columns from the left and right edges. The BorderSize argument defines v and h.

Use parallel processing, specified as false or true. If you have Parallel Computing Toolbox™ installed, when set to true, MATLAB® automatically opens a parallel pool of workers on your local machine. blockproc runs the computation across the available workers. For more information, see Parallel Block Processing on Large Image Files.

Display wait bar, specified as true or false. When set to true, blockproc displays a wait bar to indicate progress for long-running operations. To prevent blockproc from displaying a wait bar, set DisplayWaitbar to false.

Output Arguments

collapse all

Processed image, returned as a numeric array.

More About

collapse all

Block Struct

A block struct is a MATLAB structure that contains the block data and other information about the block. Fields in the block struct are:

FieldDescription
border2-element vector of the form [v h]. The border field specifies the size of the vertical and horizontal padding around the block of data. See the BorderSize argument for more information.
blockSize2-element vector of the form [rows cols]. The blockSize field specifies the size of the block data. If a border has been specified, the size does not include the border pixels.
datam-by-n or m-by-n-by-p array of block data.
imageSize2-element vector of the form [rows cols]. The imageSize field specifies the full size of the input image.
location2-element vector of the form [row col]. The location field specifies the position of the first pixel (minimum-row, minimum-column) of the block data in the input image. If a border has been specified, the location refers to the first pixel of the discrete block data, not the added border pixels.

Tips

  • Choosing an appropriate block size can significantly improve performance. For more information, see Block Size and Performance.

  • If the output image B is too large to fit into memory, then omit the output argument and instead use the Destination name-value pair argument to write the output to a file.

  • blockproc can read BigTIFF images but has limited support for writing BigTIFF images to file. If you write an image to file, then blockproc automatically selects the file type according to the size of the file. If the image is less than or equal to 4.0 Gb, then blockproc saves the image as a standard TIFF image. If the size of the file is larger than 4.0 Gb, then blockproc saves the image as a BigTIFF image.

    blockproc does not provide an argument that enables you to specify the file type as BigTIFF when the file size is less than or equal to 4.0 Gb. If you want to write a small image as a BigTIFF file, then specify a custom image adapter using the adapter argument. For more information, see TIFF, BigTIFF, and blockproc.

  • To determine whether a written TIFF file is standard TIFF or BigTIFF, query the image format signature using the imfinfo function:

    tiffinfo = imfinfo(Destination);
tiffformat = tiffinfo.FormatSignature

    If the last nonzero value of tiffformat is 42, then the file is in the standard TIFF format. If the last nonzero value is 43, then the file is in the BigTIFF format.

Extended Capabilities

Version History

Introduced in R2009b

See Also

| | |

Topics