GridIndexer2D

Purpose and Use

Two-dimensional Images in Java/ImageJ are typically stored as 1D arrays of pixels arranged in row-major order, i.e., pixels in a horizontal line are stored next to each other. The purpose of GridIndexer2D is to perform efficient transformation between 2D image coordinates and indexes into the associated 1D pixel array, taking care of out-of-bounds pixel coordinates. The key method of GridIndexer2D is

int getIndex(int u, int v)

This is a simple task if the specified pixel coordinates are inside the underlying image: for an image of size $w \times h$, the 1D pixel index for some position $(u,v)$ is $$i = w \cdot v + u,$$ given $0 \leq u < w$ and $0 \leq v < h$.

For positions outside the image the result depends on the specified OutOfBoundsStrategy, implemented by the concrete subclasses of GridIndexer2D. For any coordinates $(u,v)$ outside the image bounds,

• DefaultValueIndexer: returns index $-1$, indicating that a default pixel value (typ. zero) should be used;
• NearestBorderIndexer: returns the index of the closest pixel on the image border;
• MirrorImageIndexer: returns the index of the pixel mirrored at the image border;
• PeriodicImageIndexer: returns the index of a repetitive image (periodic in x/y);
• ExceptionIndexer: throws an exception.

Creating a GridIndexer2D

Given an image in the form of an ImageJ ImageProcessor object ip and some OutOfBoundsStrategy obs, the associated indexer is created by

GridIndexer2D indexer = GridIndexer2D.create(ip, obs);

Possible values for obs (enum type OutOfBoundsStrategy) are DefaultValue, NearestBorder, MirrorImage, PeriodicImage and ThrowException. The argument to obs may be null, in which case the default strategy (OutOfBoundsStrategy.NearestBorder) is used.

Example

import imagingbook.common.image.GridIndexer2D;
...
ImageProcessor ip = new ByteProcessor(500, 400);
GridIndexer2D indexer = GridIndexer2D.create(ip, OutOfBoundsStrategy.MirrorImage);
int i = indexer.getIndex(503, -10);   // always yields a valid pixel index
int p = ((int[]) ip.getPixels())[i];  // access the 1D pixel array

Notes

A given image may be associated with multiple indexers. Instances of GridIndexer2D do not hold any image data themselves, they just perform the indexing task. This is used, for example, inside class PixelPack, which serves as a universal image container.

See Also

• OutOfBoundsStrategy
• ImageAccessor
• PixelPack