blockproc

Distinct block processing for image

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.

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.

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.

Examples

Create Thumbnail of Image

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;
imshow(I2);

Set Pixels in 32-by-32 Blocks to Standard Deviation

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;
imshow(I2,[]);

Switch Red and Green Bands of RGB Image

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;
imshow('grb_peppers.tif');

Convert Large TIFF Image into JPEG2000 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

A — Image to process

numeric array

Image to process, specified as a numeric array.

src_filename — Source file name

character vector | string scalar

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

adapter — Image adapter

ImageAdapter object

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.

[m n] — Block size

2-element vector

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

fun — Function handle

handle

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

character vector | string scalar | ImageAdapter object

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.

BorderSize — Border size

[0 0] (default) | 2-element vector of positive integers

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.

PadPartialBlocks — Pad partial blocks

false (default) | true

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.

PadMethod — Pad method

0 (default) | "replicate" | "symmetric" | numeric scalar

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

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

Data Types: char | string

TrimBorder — Remove border pixels

true (default) | false

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.

UseParallel — Use parallel processing

false (default) | true

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.

DisplayWaitbar — Display wait bar

true (default) | false

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

B — Processed image

numeric array

Processed image, returned as a numeric array.

More About

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:

Field	Description
border	2-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.
blockSize	2-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.
data	m-by-n or m-by-n-by-p array of block data.
imageSize	2-element vector of the form [rows cols]. The imageSize field specifies the full size of the input image.
location	2-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

Automatic Parallel Support

Accelerate code by automatically running computation in parallel using Parallel Computing Toolbox™.

Usage notes and limitations:

• This function supports automatic parallel processing (requires Parallel Computing Toolbox). To run in parallel, specify the UseParallel argument as true. For more information, see Parallel Block Processing on Large Image Files.

• Control parallel behavior with the parallel preferences, including scaling up to a cluster. See parpool (Parallel Computing Toolbox) for information on configuring your parallel environment.

• To run in parallel, this function requires a parallel pool with SPMD enabled.

• Parallel processing does not support an adapter source image.

Version History

Introduced in R2009b