casacore
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
Public Types | Public Member Functions | Private Member Functions | Private Attributes | List of all members
casacore::LatticeStepper Class Reference

Traverse a Lattice by cursor shape. More...

#include <LatticeStepper.h>

Inheritance diagram for casacore::LatticeStepper:
casacore::LatticeNavigator

Public Types

enum  hangOverPolicy {
  PAD,
  RESIZE
}
 The hangOverPolicy enumerator is used in the constructors to indicate what this class should do when the cursor shape hangs over the edge of the Lattice. More...
 

Public Member Functions

 LatticeStepper (const IPosition &latticeShape, const IPosition &cursorShape, const uInt hangOverPolicy=PAD)
 The first argument is the shape of the Lattice to be iterated and the second argument is the shape of the cursor. More...
 
 LatticeStepper (const IPosition &latticeShape, const IPosition &cursorShape, const IPosition &axisPath, const uInt hangOverPolicy=PAD)
 Same as the above constructor except that the axis path is explicitly specified. More...
 
 LatticeStepper (const IPosition &latticeShape, const IPosition &cursorShape, const IPosition &cursorAxes, const IPosition &axisPath, const uInt hangOverPolicy=PAD)
 Same as the above constructor except that the cursor axes are explicitly specified. More...
 
 LatticeStepper (const LatticeStepper &other)
 The copy constructor uses copy semantics. More...
 
 ~LatticeStepper ()
 
LatticeStepperoperator= (const LatticeStepper &other)
 The assignment operator uses copy semantics. More...
 
virtual Bool operator++ (int)
 Increment operator (postfix version) - move the cursor forward one step. More...
 
virtual Bool operator-- (int)
 Decrement operator (postfix version) - move the cursor backwards one step. More...
 
virtual void reset ()
 Function to move the cursor to the beginning of the (sub)-Lattice. More...
 
virtual Bool atStart () const
 Function which returns "True" if the cursor is at the beginning of the (sub)-Lattice, otherwise, returns "False". More...
 
virtual Bool atEnd () const
 Function which returns "True" if an attempt has been made to increment the cursor beyond the end of the (sub)-Lattice. More...
 
virtual uInt nsteps () const
 Function to return the number of steps (increments & decrements) taken since construction (or since last reset). More...
 
virtual IPosition position () const
 Functions which return the current position of the beginning of the cursor. More...
 
virtual IPosition relativePosition () const
 
virtual IPosition endPosition () const
 Functions which return the current position of the end of the cursor. More...
 
virtual IPosition relativeEndPosition () const
 
virtual IPosition latticeShape () const
 Functions which return the shape of the Lattice being iterated through. More...
 
virtual IPosition subLatticeShape () const
 
void setCursorShape (const IPosition &cursorShape)
 Functions to change the cursor shape to a new one. More...
 
void setCursorShape (const IPosition &cursorShape, const IPosition &cursorAxes)
 
virtual IPosition cursorShape () const
 Function which returns the shape of the cursor. More...
 
virtual IPosition cursorAxes () const
 Function which returns the axes of the cursor. More...
 
virtual Bool hangOver () const
 Function which returns "True" if the increment/decrement operators have moved the cursor position such that part of the cursor beginning or end is hanging over the edge of the (sub)-Lattice. More...
 
virtual void subSection (const IPosition &blc, const IPosition &trc)
 Functions to specify a "section" of the Lattice to step over. More...
 
virtual void subSection (const IPosition &blc, const IPosition &trc, const IPosition &inc)
 
virtual IPosition blc () const
 Return the bottom left hand corner (blc), top right corner (trc) or step size (increment) used by the current sub-Lattice. More...
 
virtual IPosition trc () const
 
virtual IPosition increment () const
 
virtual const IPositionaxisPath () const
 Return the axis path. More...
 
virtual LatticeNavigatorclone () const
 Function which returns a pointer to dynamic memory of an exact copy of this instance. More...
 
virtual Bool ok () const
 Function which checks the internal data of this class for correct dimensionality and consistant values. More...
 
virtual uInt calcCacheSize (const IPosition &cubeShape, const IPosition &tileShape, uInt maxCacheSize, uInt bucketSize) const
 Calculate the cache size (in tiles) for this type of access to a lattice in the given row of the tiled hypercube. More...
 
- Public Member Functions inherited from casacore::LatticeNavigator
 LatticeNavigator ()
 Default constructor. More...
 
 LatticeNavigator (const LatticeNavigator &)
 Copy constructor. More...
 
LatticeNavigatoroperator= (const LatticeNavigator &)
 Assignment. More...
 
virtual ~LatticeNavigator ()
 A virtual destructor. More...
 
Bool operator++ ()
 
Bool operator-- ()
 
virtual IPosition hangOverBlc () const
 Functions which return the "bottom left corner" and the "top right corner" of the cursor that does not hangover. More...
 
virtual IPosition hangOverTrc () const
 

Private Member Functions

 LatticeStepper ()
 Prevent the default constructor from being used. More...
 
void padCursor ()
 Pad the cursor to the right number of dimensions. More...
 
Bool niceFit () const
 Check if the cursor shape is a factor of the Lattice shape. More...
 

Private Attributes

LatticeIndexer itsIndexer
 
IPosition itsCursorAxes
 
IPosition itsCursorShape
 
IPosition itsCursorPos
 
IPosition itsAxisPath
 
uInt itsNsteps
 
Bool itsEnd
 
Bool itsStart
 
Bool itsNiceFit
 
Bool itsHangover
 
uInt itsPolicy
 

Detailed Description

Traverse a Lattice by cursor shape.

Intended use:

Public interface

Review Status

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

Prerequisite

Etymology

LatticeStepper is so-called because it performs the calculations necessary to step through a Lattice. The next position is always one simple step forward from the current position. The step-size is calculated directly from the size of the LatticeIterator's cursor or window.

Synopsis

When you wish to traverse a Lattice (say, a PagedArray or an Image) you will usually create a LatticeIterator. Once created, you must attach a LatticeNavigator to the iterator. A LatticeStepper, is a concrete class derived from the abstract LatticeNavigator that allows you to move sequentially through the Lattice.

In constructing a LatticeStepper, you specify the Lattice shape and the shape of the "cursor" used to step through the data. The cursor position can be incremented or decremented to retrieve the next portion of the Lattice. The specified cursor shape can (and often will) have fewer dimensions that the Lattice itself. For example if we have a 4-dimensional Lattice with latticeShape = IPosition(4,64,64,4,16), then specifying a cursor of cursorShape = IPosition(1,64), will step through the hypercube row by row. When the cursor shape has fewer dimensions than the Lattice degenerate dimensions are added to the end of the cursor so that in the above example the specified cursor is assumed to mean cursorShape = IPosition(4,64,1,1,1). To access the data spectrum by spectrum (assuming the last axis is the spectral axis), you must use a 1-dimensional cursor of IPosition(4,1,1,1,16). The cursorShape function always returns a shape with as many dimensions as the underlying Lattice.

It is an error (and an exception will be thrown) if the cursor has more dimensions than the Lattice or if it is larger on any axis than the Lattice shape.
Also the cursor shape on all axes must be less than or equal to the Lattice shape on that axis. Otherwise an exception will be thrown.

In principle cursor axes with length 1 are degenerate axes. They are removed from the lattice cursor if the LatticeIterator cursor is accessed using e.g. the matrixCursor function. Using a special LatticeStepper constructor it is, however, possible to specify which cursor axes with length 1 have to be treated as normal axes. In that way one can be sure that a cursor is, for example, always 2D, even if an axis happens to have length 1.

IPosition latticeShape(4,20,16,1,4);
IPosition cursorAxes(2,1,2);
IPosition cursorShape(2,16,1);
IPosition axisPath;
LatticeStepper stepper(latticeShape, cursorShape,
cursorAxes, axisPath);

This results in a cursor with shape [1,16,1,1]. The first and last axis are degenerate, so the cursor can also be accessed using matrixCursor (with shape [16,1]). Note that the cursor shape could also be specified as [1,16,1,1].

The "path" of the cursor through the Lattice can be controlled by specifying an axisPath during construction of the class. This is an IPosition which has exactly as many elements as the Lattice dimension. Each element must contain an integer between 0 – Lattice_Dimension-1, and must be unique. For example,

axisPath = IPosition(4,0,1,2,3) or
axisPath = IPosition(4,3,1,2,0)

are valid but

axisPath = IPosition(4,1,2,3,4) or
axisPath = IPosition(4,0,1,1,3)

are not, given the latticeShape specified above. An exception is thrown if the AxisPath is bad.
The "axis path" defines which axis will be iterated through fastest as the cursor moves through the Lattice. With the above mentioned 4-dimensional Lattice and a single element cursor (cursorShape=IPosition(4,1,1,1,1)) setting an axisPath=IPosition(4,0,1,2,3) will move the cursor through all the columns, and then onto the next row, and again through all the columns in the second row. Once all the rows in the first plane have been exhausted the cursor will then iterate to the next plane, and eventually to the next spectral channel. If, however, the axisPath was axisPath=IPosition(4,3,0,1,2) then the cursor would iterate through each spectral channel first, before moving onto the next column in the first row.

The cursor never changes dimensionality as it traverses the Lattice. But it may change shape if the cursor shape is not a factor of the Lattice shape. A cursor shape is not a factor of the Lattice shape if the Lattice shape is not an integer multiple of the cursor shape on all axes. The integer multiplier need not to be the same for each axes. For example, for a Lattice of shape [10,10,10] a cursor of shape [8,5,2] is not a factor but one with a shape of [10,5,1] is.
When the cursor is not congruent with the Lattice moving the cursor through the Lattice will sometimes result in part of the cursor hanging over the edge of the Lattice. When this occurs the hangOver member function will return True. What to do in these situtations is specified by the hangOverPolicy enumerator.

  1. If the LatticeStepper::PAD option (the default) is used at construction time the cursor shape does not change. The parts of the cursor that hang over the edge of the Lattice are filled with a default value, usually zero, that is defined by the particular LatticeIterator used.
  2. If the LatticeStepper::RESIZE option is used at construction time the cursor shape does change to a smaller value when near the edge of the Lattice so that it is just big enough. For example with a Lattice shape of 10x10 and a cursor of 8x8 the cursor shape will initally be 8x8, then resize to 2x8 on the first step, then resize to 8x2 on the second step and finally resize to 2x2. The hangover function will return True for the last three steps, even though the cursor has resized.

The portion of the Lattice that the cursor will traverse can be restricted to a region defined by a top right corner, bottom left corner and a step size. This is done using the subSection function, which also resets the cursor position to the origin of the sub-Lattice. The cursor shape will remain unchanged. It is no error when the cursor shape exceeds the sub-Lattice shape (instead it is a hangover state).
If a sub-Lattice is defined then cursor positions relative to the sub-Lattice origins can be obtained using the relativePosition function rather than the position function, which always returns positions relative to the origin of the main Lattice.
To change the size of the sub-Lattice simply call the subSection function again with a different trc, blc & inc. This first clears the old sub-Lattice, then imposes the newly specified one, and finally moves the cursor to the origin of the new sub-Lattice.

Example

This example is of a global function that will iterate through a 4-dimensional Lattice. It is assumed that the axes are RA, Dec, Stokes & Frequency, and it will calculate the average flux in the I polarization on each frequency channel. Imagine it is passed a data set (ie. Lattice) of size 256 x 256 x 4 x 1024. This corresponds to 1GByte of data. However the iterator will page through this data using a cursor of size 256 x 256 (or 256kByte) and will only read (because of subsectioning) the relevant quarter of the data set. It is usually a good idea to set up the axis path as this is gives hints to data cache about which data to retrieve in advance.

void averageFluxByChannel(const Lattice<Float>& data)
{
// for convenience, get the shape into a local variable
IPosition latticeShape = data.shape();
cout << "Data has shape: " << latticeShape << endl;
// check that the data has 4 axes.
DebugAssert(latticeShape.nelements() == 4, AipsError);
// specify the cursor, or window shape. Here the cursor is a matrix
// that is the shape of the first plane of our Lattice.
// For convenience, get the first two axis lengths into local vars
uInt nCols = latticeShape(0);
uInt nRows = latticeShape(1);
IPosition cursorShape(2, nCols, nRows);
// construct a stepper, which needs to know the shape of the lattice
// and the shape of the iterator's cursor. By using cursorShape, which
// is directly determined by the lattice's shape, we can be sure
// that the cursor is a factor of the lattice, and thus that
// all elements will be picked up efficiently during the traversal.
// Because we will not be iterating through the stokes axis this axis
// is made the slowest moving one.
IPosition axisPath(4, 0, 1, 3, 2)
LatticeStepper stepper(latticeShape, cursorShape, axisPath);
// Subsection the stepper so that it only iterates through the I
// Stokes parameter (assumed to be when the third axis is zero)
uInt nFreqs = latticeShape(3);
IPosition blc(4, 0, 0, 0, 0), trc(4, nCols-1, nRows-1, 0, nFreqs-1);
stepper.subSection(blc, trc);
// construct the iterator. Since we only want to read the Data,
// use the read-only class, which disallows writing back to the cursor
// (and hence is more efficient).
RO_LatticeIterator<Float> iterator(data, stepper);
Vector<Float> spectrum(nFreqs);
spectrum = 0.0;
uInt channel = 0;
for (iterator.reset(); !iterator.atEnd(); iterator++) {
const Matrix<Float>& cursor = iterator.matrixCursor();
for (uInt col = 0; col < nCols; col++) {
for (uInt row = 0; row < nRows; row++) {
spectrum(channel) += cursor(col, row);
}
}
channel++;
} // for iterator
cout << "Average spectrum is: "
<< spectrum / cursorShape.product() << endl;
}

Motivation

Moving through a Lattice by equal sized chunks, and without regard to the nature of the data, is a basic and common procedure.

Definition at line 267 of file LatticeStepper.h.

Member Enumeration Documentation

The hangOverPolicy enumerator is used in the constructors to indicate what this class should do when the cursor shape hangs over the edge of the Lattice.

Enumerator
PAD 

PAD is the default and means that the cursor size supplied by the user is kept fixed.

But if the cursor overhangs the Lattice the part that overhangs is filled with a default value that is specified by the Iterator. Currently the default value is zero.

RESIZE 

RESIZE means that the cursor shape is adjusted whenever it approaches the edges of the Lattice so that it is always the right size to include only the parts of the Lattice that are available.

The user specified cursor shape now becomes the default and largest possible cursor shape.

Definition at line 274 of file LatticeStepper.h.

Constructor & Destructor Documentation

casacore::LatticeStepper::LatticeStepper ( const IPosition latticeShape,
const IPosition cursorShape,
const uInt  hangOverPolicy = PAD 
)

The first argument is the shape of the Lattice to be iterated and the second argument is the shape of the cursor.

The cursor will increment initially along first axis, then the second and then the third (ie. axisPath = IPosition(ndim,0,1,2,...)) The dimensionality of the cursorShape can be less than the dimensionality of the lattice. It will be padded with 1s.
The cursorShape axes with length > 1 are seen as the true cursor axes. The other axes are degenerated and are removed by the functions vectorCursor(), etc., in class (RO_)LatticeIterator.

casacore::LatticeStepper::LatticeStepper ( const IPosition latticeShape,
const IPosition cursorShape,
const IPosition axisPath,
const uInt  hangOverPolicy = PAD 
)

Same as the above constructor except that the axis path is explicitly specified.

The axis path is described in the synopsis above.

casacore::LatticeStepper::LatticeStepper ( const IPosition latticeShape,
const IPosition cursorShape,
const IPosition cursorAxes,
const IPosition axisPath,
const uInt  hangOverPolicy = PAD 
)

Same as the above constructor except that the cursor axes are explicitly specified.

This can be useful to avoid that cursor axes with length=1 are treated as degenerated axes by the Iterator classes. The following rules have to be obeyed:
- cursorAxes.nelements() <= latticeShape.nelements()
- cursorShape.nelements() == latticeShape.nelements()
or cursorShape.nelements() == cursorAxes.nelements() The latter means that the cursorShape contains the axes mentioned in cursorAxes.
See also the example in the synopsis.

casacore::LatticeStepper::LatticeStepper ( const LatticeStepper other)

The copy constructor uses copy semantics.

casacore::LatticeStepper::~LatticeStepper ( )
casacore::LatticeStepper::LatticeStepper ( )
private

Prevent the default constructor from being used.

Member Function Documentation

virtual Bool casacore::LatticeStepper::atEnd ( ) const
virtual

Function which returns "True" if an attempt has been made to increment the cursor beyond the end of the (sub)-Lattice.

Implements casacore::LatticeNavigator.

virtual Bool casacore::LatticeStepper::atStart ( ) const
virtual

Function which returns "True" if the cursor is at the beginning of the (sub)-Lattice, otherwise, returns "False".

Implements casacore::LatticeNavigator.

virtual const IPosition& casacore::LatticeStepper::axisPath ( ) const
virtual

Return the axis path.

Implements casacore::LatticeNavigator.

virtual IPosition casacore::LatticeStepper::blc ( ) const
virtual

Return the bottom left hand corner (blc), top right corner (trc) or step size (increment) used by the current sub-Lattice.

If no sub-Lattice has been defined (with the subSection function) these functions return blc=0, trc=latticeShape-1, increment=1, ie. the entire Lattice.

Reimplemented from casacore::LatticeNavigator.

virtual uInt casacore::LatticeStepper::calcCacheSize ( const IPosition cubeShape,
const IPosition tileShape,
uInt  maxCacheSize,
uInt  bucketSize 
) const
virtual

Calculate the cache size (in tiles) for this type of access to a lattice in the given row of the tiled hypercube.

Implements casacore::LatticeNavigator.

virtual LatticeNavigator* casacore::LatticeStepper::clone ( ) const
virtual

Function which returns a pointer to dynamic memory of an exact copy of this instance.

The pointer returned by this function must be deleted externally.

Implements casacore::LatticeNavigator.

virtual IPosition casacore::LatticeStepper::cursorAxes ( ) const
virtual

Function which returns the axes of the cursor.

Implements casacore::LatticeNavigator.

virtual IPosition casacore::LatticeStepper::cursorShape ( ) const
virtual

Function which returns the shape of the cursor.

This always includes all axes (ie. it includes degenerates axes)

Implements casacore::LatticeNavigator.

virtual IPosition casacore::LatticeStepper::endPosition ( ) const
virtual

Functions which return the current position of the end of the cursor.

The endPosition function is relative to the origin in the main Lattice and the relativeEndPosition function is relative to the origin and increment used in the sub-Lattice (defined using the subSection function). If no sub-Lattice is defined the two functions return identical positions.
Caution: It returns the end position in the lattice and does not take overhang into account;

Implements casacore::LatticeNavigator.

virtual Bool casacore::LatticeStepper::hangOver ( ) const
virtual

Function which returns "True" if the increment/decrement operators have moved the cursor position such that part of the cursor beginning or end is hanging over the edge of the (sub)-Lattice.

Implements casacore::LatticeNavigator.

virtual IPosition casacore::LatticeStepper::increment ( ) const
virtual

Reimplemented from casacore::LatticeNavigator.

virtual IPosition casacore::LatticeStepper::latticeShape ( ) const
virtual

Functions which return the shape of the Lattice being iterated through.

latticeShape always returns the shape of the main Lattice while subLatticeShape returns the shape of any sub-Lattice defined using the subSection function.

Implements casacore::LatticeNavigator.

Bool casacore::LatticeStepper::niceFit ( ) const
private

Check if the cursor shape is a factor of the Lattice shape.

virtual uInt casacore::LatticeStepper::nsteps ( ) const
virtual

Function to return the number of steps (increments & decrements) taken since construction (or since last reset).

This is a running count of all cursor movement (operator++ or operator--), even though N-increments followed by N-decrements will ALWAYS leave the cursor in the original position.

Implements casacore::LatticeNavigator.

virtual Bool casacore::LatticeStepper::ok ( ) const
virtual

Function which checks the internal data of this class for correct dimensionality and consistant values.

Returns True if everything is fine otherwise returns False

Reimplemented from casacore::LatticeNavigator.

virtual Bool casacore::LatticeStepper::operator++ ( int  )
virtual

Increment operator (postfix version) - move the cursor forward one step.

Returns True if the cursor was moved.

Implements casacore::LatticeNavigator.

virtual Bool casacore::LatticeStepper::operator-- ( int  )
virtual

Decrement operator (postfix version) - move the cursor backwards one step.

Returns True if the cursor was moved.

Implements casacore::LatticeNavigator.

LatticeStepper& casacore::LatticeStepper::operator= ( const LatticeStepper other)

The assignment operator uses copy semantics.

void casacore::LatticeStepper::padCursor ( )
private

Pad the cursor to the right number of dimensions.

virtual IPosition casacore::LatticeStepper::position ( ) const
virtual

Functions which return the current position of the beginning of the cursor.

The position function is relative to the origin in the main Lattice and the relativePosition function is relative to the origin and increment used in the sub-Lattice (defined using the subSection function). If no sub-Lattice is defined the two functions return identical positions.

Implements casacore::LatticeNavigator.

virtual IPosition casacore::LatticeStepper::relativeEndPosition ( ) const
virtual

Reimplemented from casacore::LatticeNavigator.

virtual IPosition casacore::LatticeStepper::relativePosition ( ) const
virtual

Reimplemented from casacore::LatticeNavigator.

virtual void casacore::LatticeStepper::reset ( )
virtual

Function to move the cursor to the beginning of the (sub)-Lattice.

Also resets the number of steps (nsteps function) to zero.

Implements casacore::LatticeNavigator.

void casacore::LatticeStepper::setCursorShape ( const IPosition cursorShape)

Functions to change the cursor shape to a new one.

They always reset the cursor to the beginning of the Lattice (and reset the number of steps to zero).

void casacore::LatticeStepper::setCursorShape ( const IPosition cursorShape,
const IPosition cursorAxes 
)
virtual IPosition casacore::LatticeStepper::subLatticeShape ( ) const
virtual

Reimplemented from casacore::LatticeNavigator.

virtual void casacore::LatticeStepper::subSection ( const IPosition blc,
const IPosition trc 
)
virtual

Functions to specify a "section" of the Lattice to step over.

A section is defined in terms of the Bottom Left Corner (blc), Top Right Corner (trc), and step size (inc), on ALL of its axes, including degenerate axes. The step size defaults to one if not specified.

Reimplemented from casacore::LatticeNavigator.

virtual void casacore::LatticeStepper::subSection ( const IPosition blc,
const IPosition trc,
const IPosition inc 
)
virtual

Reimplemented from casacore::LatticeNavigator.

virtual IPosition casacore::LatticeStepper::trc ( ) const
virtual

Reimplemented from casacore::LatticeNavigator.

Member Data Documentation

IPosition casacore::LatticeStepper::itsAxisPath
private

Definition at line 461 of file LatticeStepper.h.

IPosition casacore::LatticeStepper::itsCursorAxes
private

Definition at line 458 of file LatticeStepper.h.

IPosition casacore::LatticeStepper::itsCursorPos
private

Definition at line 460 of file LatticeStepper.h.

IPosition casacore::LatticeStepper::itsCursorShape
private

Definition at line 459 of file LatticeStepper.h.

Bool casacore::LatticeStepper::itsEnd
private

Definition at line 464 of file LatticeStepper.h.

Bool casacore::LatticeStepper::itsHangover
private

Definition at line 470 of file LatticeStepper.h.

LatticeIndexer casacore::LatticeStepper::itsIndexer
private

Definition at line 456 of file LatticeStepper.h.

Bool casacore::LatticeStepper::itsNiceFit
private

Definition at line 466 of file LatticeStepper.h.

uInt casacore::LatticeStepper::itsNsteps
private

Definition at line 462 of file LatticeStepper.h.

uInt casacore::LatticeStepper::itsPolicy
private

Definition at line 474 of file LatticeStepper.h.

Bool casacore::LatticeStepper::itsStart
private

Definition at line 465 of file LatticeStepper.h.


The documentation for this class was generated from the following file: