Coordinate Systems for Blocked Images

R2026b

A blocked image is an image whose data is divided into a grid of blocks, enabling you to process each block independently. MATLAB^® represents blocked images by using the blockedImage object. A blocked image establishes a relationship between these coordinate systems.

• Pixel subscripts — Specify the row and column of each pixel in an image or block. In a blocked image, each pixel has a global pixel subscript, which defines its position in the entire image, and a local pixel subscript, which defines its position in its block.

• Block subscripts — Specify the row and column of each block in the grid of blocks.

• World coordinates — Specify locations in a continuous spatial coordinate system. This coordinate system can represent real-world units.

As these coordinate systems represent the same image data, you can use conversion functions to switch between them..

Pixel locations are expressed using subscripts of the form (row, column). For a general overview of pixel subscripts and image coordinate conventions, see Image Coordinate Systems.

Pixel Subscripts and Block Subscripts

A blockedImage object represents an image organized as a grid of discrete blocks. The object identifies each block using a set of block subscripts that specify its location in the block grid, equal in number to the number of dimensions in the original image. For example, a grayscale image might have blocks with subscripts of the form (row, column), while an RGB image might have blocks with subscripts of the form (row, column, channel). This illustration shows a 5-by-5 image divided into blocks of size 2-by-2, with blocks and their subscripts overlaid in red on the gray pixel grid.

Note

If the blocks do not fit exactly over the image, blockedImage creates partial blocks at the edges. These edge blocks might be smaller than the specified block size. When processing blocked images, you can specify whether to pad the partial blocks at the edges of images.

• When using the apply function to process a blockedImage, you can pad the partial blocks into blocks of full size by specifying the PadPartialBlocks name-value argument as true.

• A blockedImageDatastore object pads the edge blocks of blocked images you add to it by default. To prevent this behavior, set the PadPartialBlocks property of the blockedImageDatastore to false.

Unlike numeric image arrays, you cannot directly index into a blockedImage object using array syntax. For example, given a blockedimage object bim, you cannot specify bim(row,column). Instead, to access and process blocked image data, you must use blockedImage object functions such as getBlock, getRegion, setBlock, and crop. For more information about the available object functions, see blockedImage.

Note that a blocked image can be a multilevel image, which contains multiple levels where each level represents the same image at a different resolution. Each level can have its own block size. If the user specifies a single block size when creating a multilevel blocked image, this block size is applied to all levels.

Convert Between Pixel Subscripts and Block Subscripts

To determine which block contains a given pixel, use the sub2blocksub function.

For example, suppose that a blocked image, bim, corresponds to a 5-by-5 blocked image with 2-by-2 blocks. The pixel with subscripts (3, 2) lies in block (2, 1).

blockIndex = sub2blocksub(bim,[3 2])

blockIndex =

     2     1

To determine the range of pixels in a given block, use the blocksub2sub function. This function returns the subscripts of the top-left and bottom-right pixels in the block.

For example, calling blocksub2sub on bim with the block subscripts (2, 1) returns the subscripts of the pixels in the top-left corner (3, 1) and bottom-right corner (4, 2) of that block.

[pStart,pEnd] = blocksub2sub(bim,[2 1])

pStart =

     3     1


pEnd =

     4     2

For multilevel images, you can specify which resolution level the subscripts refer to when calling sub2blocksub and blocksub2sub by specifying the Level argument.

Convert Local Pixel Subscripts to Global Pixel Subscripts

When you process blocks using the apply object function, the function uses pixel subscripts local to each block. For example, if you identify a feature within the block, such as by detecting a peak, the resulting indices are pixel subscripts local to that block, not the full image.

For example, suppose that you have a 5-by-5 blocked image with 2-by-2 blocks. The pixel with global subscripts (2, 3) is in the block with subscripts (1, 2). Within that block, the same pixel has the local subscripts (2, 1).

The function you pass to apply accepts a structure that contains the data and metadata for each block. The Start field of each structure must contain the global pixel subscripts of the top-left corner of the corresponding block. To convert a local position to global pixel subscripts, add the local subscript to the block origin and subtract 1:

globalSub = blockInfo.Start + localSub - 1

For example, if the blockInfo.Start value for block (1, 2) is [1 3], and you detect a feature at local position [2 1] within the block, the global pixel subscript of that feature is [1 3] + [2 1] – [1 1] = [2 3].

Pixel Subscripts and World Coordinates

Some applications, such as measuring distances, aligning images, or locating pixels based on physical coordinates, can require you to describe image locations in continuous units rather than discrete pixel indices. In these cases, use world coordinates.

blockedImage objects express world coordinates in a continuous coordinate system using (y, x) order, where y corresponds to rows and x corresponds to columns. This order matches the (row, column) convention used for pixel subscripts. In this coordinate system, x increases from left to right and y increases from top to bottom.

Note

The order (y, x) for world coordinates differs from other functions in Image Processing Toolbox™, which use an (x, y) order for world coordinates. For more information, see Image Coordinate Systems.

World coordinates provide a continuous spatial coordinate system that is independent of the image pixel grid. You can assign physical meaning to image data by defining pixel spacing and spatial extent in real-world units.

A blockedImage object defines the mapping between pixel subscripts and world coordinates using the WorldStart and WorldEnd properties:

• WorldStart — Specifies the world coordinates of the outer boundary of the pixel at the top-left corner of the image.

• WorldEnd — Specifies the world coordinates of the outer boundary of the pixel at the bottom-right corner of the image.

For example, consider a 5-by-5 blocked image, bimworld, that represents a geographic region that spans 4 km in the y-direction and 20 km in the x-direction. The outer boundary of the top-left pixel has world coordinates (10, 100), and the outer boundary of the bottom-right pixel has world coordinates (14, 120). In this image, each pixel spans 0.8 world units in the y-direction and 4.0 world units in the x-direction. To create bimworld, use a WorldStart value of [10 100] and a WorldEnd value of [14 120].

The center of the pixel with subscripts (3, 2) in bimworld has world coordinates (12.0, 106.0). Conversely, the world coordinates (12.1, 105.0) lie within the pixel with subscripts (3, 2).

To convert between pixel subscripts and world coordinates:

• Use sub2world to convert pixel subscripts to world coordinates.

• Use world2sub to convert world coordinates to pixel subscripts.

You can use the sub2world function to compute the world coordinates worldc of the center of the pixel with subscripts (3, 2) in bimworld. Since the input array represents pixel subscripts, it must be integer-valued.

worldc = sub2world(bimworld,[3 2])

worldc =

   12.0000  106.0000

You can use the world2sub function to determine the subscripts of the pixel pixelsub that contains the world coordinates (12.1, 105.0) of bimworld.

pixelsub = world2sub(bimworld,[12.1 105])

pixelsub =

     3     2

The function world2sub rounds up world coordinate values on the edge of two pixels, except for pixels on the border, where it rounds down to the last pixel.

If you pass world coordinates that fall outside the image extent, world2sub clamps the result to valid pixel subscripts. Coordinates before WorldStart map to subscript 1, and coordinates beyond WorldEnd map to the last pixel in that dimension. The function does not error or return NaN for out-of-bounds input. For instance, for bimworld, running

pixelsub = world2sub(bimworld,[20 106])

yields

pixelsub =

     5     2

For higher-dimensional images, world coordinates extend to additional dimensions.

For multilevel images, blockedImage assumes that all levels correspond to the same real-world spatial extents, derived from the finest resolution level. Pixel subscripts map to different world coordinates at different levels because each pixel covers a greater world extent at coarser levels. While the sub2world and world2sub functions convert based on pixel subscripts at the finest resolution level by default, you can specify the Level name-value argument to specify which resolution level to use for the conversion. For information on defining the spatial referencing of your data consistently across levels, see Set Up Spatial Referencing for Blocked Images.