LatticeIndexer.h

This class does various calculations involved with indexing in Lattices. LatticeIndexer is not a good name, but it is better than the previous name of LatticeLayout.

Synopsis

A LatticeIndexer contains all the information necessary to define the shape of a Lattice or sub-Lattice. It is currently a repository of functions that provide indexing calculations.

A sub-Lattice is a section of a Lattice defined by a bottom left corner (blc), a top right corner (trc), and a step size or increment on each axis. The blc and trc pixels will always be included in the sub-Lattice if the step increment is one. If the step increment is greater than one, the pixel in top right corner may not be included in the sub-Lattice.

This class knows the shape of the parent Lattice (including all degenerate axes), and allows the user to specify a sub-Lattice that is embedded in the parent Lattice. The default sub-Lattice, if none is specified, is one identical in shape to the main Lattice.

A sub-Lattice can be defined on the Lattice by specifying a trc, blc, and step increment using the subSection function, or the appropriate constructor. A sub-Lattice must be smaller than (or the same size as) the Lattice that it is derived from. A sub-Lattice can be further created from an already existing sub-Lattice eg.
If we have a 128 by 128 Lattice, we can specify the centre quarter by using blc=[32,32] and trc=[95,95]. Then specifying a sub-Lattice of blc=[0,0] and trc = [31,31] results in a sub-Lattice that has a blc of [32,32] and trc of [63,63] with respect to the parent Lattice.

The only way to increase the size of a sub-Lattice is to first revert to the parent Lattice (using the fullSize function) and then generate the new, bigger sub-Lattice.

Indexing calculations (eg. the tiledCursorMove or the isInside function) are performed on the specified sub-Lattice.

The role of this class is to centralise the information and functions needed to operate on sub-Lattices. It will normally be used by other Lattice classes, and is currently used by navigator classes like LatticeStepper.

Motivation

The shape, structure or geometry of a lattice is quite separable from its actual contents, and the operations you can do on the contents. Also, there are operations which apply only to the layout such as subsectioning.

Member Description

LatticeIndexer()

Default constructor (one dimensional, unit-length instance).

explicit LatticeIndexer (const IPosition& shape)

Specify the size of the Lattice. Assume a full size sub-Lattice.

LatticeIndexer (const IPosition& shape, const IPosition& blc, const IPosition& trc, const IPosition& inc)

Specify a Lattice and define a sub-Lattice within it.

LatticeIndexer (const LatticeIndexer& other)

The copy constructor uses copy semantics.

~LatticeIndexer()

LatticeIndexer& operator= (const LatticeIndexer& other)

The assignment operator uses copy semantics.

void resize (const IPosition& newShape)

Function to change the shape of the Lattice. Resets the sub-Lattice to fullsize.

const IPosition& fullShape() const
uInt fullShape (uInt axis) const

Returns the length of each axis (or the requested one) in the parent Lattice.

const IPosition& shape() const
uInt shape (uInt axis) const

Returns the length of each axis (or the requested one) in the sub-Lattice.

const IPosition& increment() const
uInt increment (uInt axis) const

Function to return the increments along each axis (or the requested one) of the Lattice.

const IPosition& offset() const
uInt offset (uInt axis) const

Function to return the offset (on a specified axis) between the sub-Lattice and the parent one.

uInt ndim() const

Function which returns the number of dimensions in the Lattice (or sub-Lattice).

void fullSize()

Revert from a sub-Lattice description back to the main Lattice. This is the only way to "increase" the the size of the sub-Lattice used by the LatticeIndexer.

uInt nelements() const

Function which returns the number of elements in the sub-Lattice; this value is equal to the product of shape().

Bool tiledCursorMove (Bool incr, IPosition& cursorPos, const IPosition& cursorShape, const IPosition& cursorHeading) const

Function which increments (incr=True) or decrements (incr=False) the cursor position (the first IPosition argument) by a cursor shape (the second IPosition argument), tiling to the next/previous axis if necessary. The path of movement is based upon the third IPosition argument (a cursor heading) that is zero-based e.g. IPosition(3,0,2,1) implies starting movement along the x-axis, then the z-axis, and then the y-axis. Returns a value of False if the beginning/end of the sub-Lattice is reached. The cursorPosition is relative to the origin of the sub-Lattice. To get its location relative to the main Lattice use the absolutePosition() function.

Bool isInside (const IPosition& index) const

Function which returns a value of True if the IPosition argument is within the sub-Lattice. Returns False if the IPosition argument is outside the sub-Lattice or if the argument doesn't conform to the data members.

Due to zero-origins, an index argument equal to the shape of this sub-Lattice lies outside and returns False.

void subSection (const IPosition& blc, const IPosition& trc, const IPosition& inc)
void subSection (const IPosition& blc, const IPosition& trc)

Function which subsections a LatticeIndexer. The argument IPositions specify "bottom left" and "upper right" corners and axis increments (which default to one). The origins are cumulative. i.e. specifying a blc of (2,2), and then (1,1) results in the sub-Lattice having an origin at pixel (3,3) in the parent Lattice. Similarly the increment is cumulative, i.e. an increment of 2 on top of an increment of 3 results in a total increment of 6. This function can only decrease the size of the sub-Lattice (i.e. blc >= 0, and trc <= shape(), and inc >= 1). The fullSize() function should be used to revert back to the maximum possible Lattice size. Also note that the trc might not be used if an integral number of increments does not end on the trc (in which case the last position below the trc will be used).

IPosition absolutePosition (const IPosition& position) const

Function which returns an IPosition in the parent Lattice given an IPostion in the sub-Lattice. Accounting is taken of any offsets and increments caused by subSectioning. No checks are made to ensure the supplied IPosition or the returned one are within the bounds of the Lattice(s).

Bool ok() const

Is this LatticeIndexer consistent, i.e. are the class invariants valid? Returns True if every thing is fine otherwise returns False