Documentation Center

  • Trials
  • Product Updates

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)
blockproc(___,Name,Value,...)

Description

B = blockproc(A,[M N],fun) processes the image A by applying the function fun to each distinct M-by-N block of A and concatenating the results into B, the output matrix. fun is a function handle to a function that accepts a block struct as input and returns a matrix, vector, or scalar Y. For example, Y = fun(block_struct). (For more information about a block struct, see the Definition section below.) For each block of data in the input image, A, blockproc passes the block in a block struct to the user function, fun, to produce Y, the corresponding block in the output image. If Y is empty, blockproc does not generate any output and returns empty after processing all blocks. Choosing an appropriate block size can significantly improve performance. For more information, see Choosing Block Size in the Image Processing Toolbox™ documentation.

B = blockproc(src_filename,[M N],fun) processes the image src_filename, reading and processing one block at a time. This syntax is useful for processing very large images since only one block of the image is read into memory at a time. If the output matrix B is too large to fit into memory, omit the output argument and instead use the 'Destination' parameter/value pair to write the output to a file.

B = blockproc(adapter,[M N],fun) processes the source image specified by adapter, 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 Working with Data in Unsupported Formats in the Image Processing Toolbox documentation.

blockproc(___,Name,Value,...) processes the input image, specifying parameters and corresponding values that control various aspects of the block behavior. Parameter names are not case sensitive.

Input Arguments

A

Input image.

[M N]

Block size of A.

fun

Function handle to a function that accepts a block struct as input and returns a matrix, vector, or scalar.

src_filename

Input image.

adapter

A user-defined class that provides blockproc with a common API for reading and writing to a particular image file format.

Name-Value Pair Arguments

Specify optional comma-separated pairs of Name,Value arguments. Name is the argument name and Value is the corresponding value. Name must appear inside single quotes (' '). You can specify several name and value pair arguments in any order as Name1,Value1,...,NameN,ValueN.

'BorderSize'

A two-element vector, [V H], specifying the amount of border pixels to add to each block. 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 will be:

[M + 2*V, N + 2*H]

By default, the function automatically removes the border from the result of fun. See the 'TrimBorder' parameter for more information. The function pads blocks with borders extending beyond the image edges with zeros.

Default: [0 0] (no border)

'Destination'

The destination for the output of blockproc. When you specify the 'Destination' parameter, blockproc does not return the processed image as an output argument, but instead writes the output to the 'Destination'. (You cannot request an output argument when the 'Destination' parameter is specified.)

Valid 'Destination' parameters are:

  • TIFF filename: A string filename ending with '.tif'. If a file with this name already exists, it will be overwritten.

  • ImageAdapter object: An instance of an ImageAdapter class. ImageAdapters provide an interface for reading and writing to arbitrary image file formats.

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

'PadPartialBlocks'

A logical scalar. When set to true, blockproc pads partial blocks to make them full-sized (M-by-N) blocks. 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. 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.

Default: false

'PadMethod'

The 'PadMethod' determines how blockproc will pad the image boundary. Options are:

  • X: Pads the image with a scalar (X) pad value. By default X == 0.

  • 'replicate': Repeats border elements of image A.

  • 'symmetric': Pads image A with mirror reflections of itself.

'TrimBorder'

A logical scalar. When set to true, the blockproc function trims off 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' parameter defines V and H. The default is true, meaning that the blockproc function automatically removes borders from the fun output.

Default: true

'UseParallel'

A logical scalar. Enabling this mode of image processing requires the Parallel Computing Toolbox™. When set to true, blockproc will attempt to run in parallel mode, distributing the processing across multiple workers (MATLAB® sessions) in an open MATLAB pool. In parallel mode, the input image cannot be an ImageAdapter object. See the documentation for parpool for information on configuring your parallel environment.

Default: false

File Format Support: Input and output files for blockproc (as specified by src_filename and the 'Destination' parameter) must have one of the following file types and must be named with one of the listed file extensions:

  • Read/Write File Formats: TIFF (*.tif, *.tiff), JPEG2000 (*.jp2, *.j2c, *.j2k)

  • Read-Only File Formats: JPEG2000 (*.jpf, *.jpx)

Output Arguments

B

Output matrix.

Definitions

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

  • block_struct.border: A two-element vector, [V H], that specifies the size of the vertical and horizontal padding around the block of data. (See the 'BorderSize' parameter in the Inputs section.)

  • block_struct.blockSize: A two-element vector, [rows cols], that specifies the size of the block data. If a border has been specified, the size does not include the border pixels.

  • block_struct.data: M-by-N or M-by-N-by-P matrix of block data

  • block_struct.imageSize: A two-element vector, [rows cols], that specifies the full size of the input image.

  • block_struct.location: A two-element vector, [row col], that 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.

Examples

Generate an image thumbnail:

fun = @(block_struct) imresize(block_struct.data,0.15);
I = imread('pears.png');
I2 = blockproc(I,[100 100],fun);
figure;
imshow(I);
figure;
imshow(I2);

 

Set the pixels in each 32-by-32 block to the standard deviation of the elements in that block:

fun = @(block_struct) ...
   std2(block_struct.data) * ones(size(block_struct.data));
I2 = blockproc('moon.tif',[32 32],fun);
figure;
imshow('moon.tif');
figure;
imshow(I2,[]);

 

Switch the red and green bands of an RGB image and write the results to a new TIFF file:

I = imread('peppers.png');
fun = @(block_struct) block_struct.data(:,:,[2 1 3]);
blockproc(I,[200 200],fun,'Destination','grb_peppers.tif');
figure;
imshow('peppers.png');
figure;
imshow('grb_peppers.tif');

 

Convert a TIFF image into a new JPEG2000 image. Replace 'largeImage.tif' in the example below with the name of your file:

fun = @(block_struct) block_struct.data;
blockproc('largeImage.tif',[1024 1024],fun,...
   'Destination','New.jp2');

See Also

| | |

Was this topic helpful?