A helper class for stepping through Lattices. More...

#include <LatticeIndexer.h>

Public Member Functions
	LatticeIndexer ()
	Default constructor (one dimensional, unit-length instance).
	LatticeIndexer (const IPosition &shape)
	Specify the size of the 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.
const IPosition &	fullShape () const
	Returns the length of each axis (or the requested one) in the parent Lattice.
uInt	fullShape (uInt axis) const
const IPosition &	shape () const
	Returns the length of each axis (or the requested one) in the sub-Lattice.
uInt	shape (uInt axis) const
const IPosition &	increment () const
	Function to return the increments along each axis (or the requested one) of the Lattice.
uInt	increment (uInt axis) const
const IPosition &	offset () const
	Function to return the offset (on a specified axis) between the sub-Lattice and the parent one.
uInt	offset (uInt axis) const
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.
size_t	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.
Bool	isInside (const IPosition &index) const
	Function which returns a value of True if the IPosition argument is within the sub-Lattice.
void	subSection (const IPosition &blc, const IPosition &trc, const IPosition &inc)
	Function which subsections a LatticeIndexer.
void	subSection (const IPosition &blc, const IPosition &trc)
IPosition	absolutePosition (const IPosition &position) const
	Function which returns an IPosition in the parent Lattice given an IPostion in the sub-Lattice.
Bool	ok () const
	Is this LatticeIndexer consistent, i.e.
Private Attributes
IPosition	itsFullShape
uInt	itsNdim
IPosition	itsShape
IPosition	itsAxisInc
IPosition	itsOffset

Detailed Description

A helper class for stepping through Lattices.

Intended use:

Internal

Review Status

Reviewed By:: Peter Barnes
Date Reviewed:: 1999/10/30
Test programs:: tLatticeIndexer

Prerequisite

Etymology

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.

Definition at line 108 of file LatticeIndexer.h.

Constructor & Destructor Documentation

casa::LatticeIndexer::LatticeIndexer ( )

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

casa::LatticeIndexer::LatticeIndexer ( const IPosition & shape ) [explicit]

Specify the size of the Lattice.

Assume a full size sub-Lattice.

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

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

casa::LatticeIndexer::LatticeIndexer ( const LatticeIndexer & other )

The copy constructor uses copy semantics.

casa::LatticeIndexer::~LatticeIndexer ( )

Member Function Documentation

IPosition casa::LatticeIndexer::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).

const IPosition & casa::LatticeIndexer::fullShape ( ) const [inline]

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

Definition at line 239 of file LatticeIndexer.h.

References itsFullShape.

uInt casa::LatticeIndexer::fullShape ( uInt axis ) const

void casa::LatticeIndexer::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.

const IPosition & casa::LatticeIndexer::increment ( ) const [inline]

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

Definition at line 247 of file LatticeIndexer.h.

References itsAxisInc.

uInt casa::LatticeIndexer::increment ( uInt axis ) const

Bool casa::LatticeIndexer::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.
Warning: Due to zero-origins, an index argument equal to the shape of this sub-Lattice lies outside and returns False;

uInt casa::LatticeIndexer::ndim ( ) const [inline]

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

Definition at line 255 of file LatticeIndexer.h.

References itsNdim.

size_t casa::LatticeIndexer::nelements ( ) const [inline]

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

Definition at line 259 of file LatticeIndexer.h.

References itsShape, and casa::IPosition::product().

const IPosition & casa::LatticeIndexer::offset ( ) const [inline]

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

Definition at line 251 of file LatticeIndexer.h.

References itsOffset.

uInt casa::LatticeIndexer::offset ( uInt axis ) const

Bool casa::LatticeIndexer::ok ( ) const

Is this LatticeIndexer consistent, i.e.

are the class invariants valid? Returns True if every thing is fine otherwise returns False

LatticeIndexer& casa::LatticeIndexer::operator= ( const LatticeIndexer & other )

The assignment operator uses copy semantics.

void casa::LatticeIndexer::resize ( const IPosition & newShape )

Function to change the shape of the Lattice.

Resets the sub-Lattice to fullsize.

const IPosition & casa::LatticeIndexer::shape ( ) const [inline]

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

Definition at line 243 of file LatticeIndexer.h.

References itsShape.

uInt casa::LatticeIndexer::shape ( uInt axis ) const

void casa::LatticeIndexer::subSection	(	const IPosition &	blc,
		const IPosition &	trc,
		const IPosition &	inc
	)

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).

void casa::LatticeIndexer::subSection	(	const IPosition &	blc,
		const IPosition &	trc
	)

Bool casa::LatticeIndexer::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.