Loading...
Searching...
No Matches
TileStepper.h
Go to the documentation of this file.
//# TileStepper.h: Steps a cursor optimally through a tiled Lattice
//# Copyright (C) 1997,1998,1999,2000
//# Associated Universities, Inc. Washington DC, USA.
//#
//# This library is free software; you can redistribute it and/or modify it
//# under the terms of the GNU Library General Public License as published by
//# the Free Software Foundation; either version 2 of the License, or (at your
//# option) any later version.
//#
//# This library is distributed in the hope that it will be useful, but WITHOUT
//# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
//# FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public
//# License for more details.
//#
//# You should have received a copy of the GNU Library General Public License
//# along with this library; if not, write to the Free Software Foundation,
//# Inc., 675 Massachusetts Ave, Cambridge, MA 02139, USA.
//#
//# Correspondence concerning AIPS++ should be addressed as follows:
//# Internet email: casa-feedback@nrao.edu.
//# Postal address: AIPS++ Project Office
//# National Radio Astronomy Observatory
//# 520 Edgemont Road
//# Charlottesville, VA 22903-2475 USA
#ifndef LATTICES_TILESTEPPER_H
#define LATTICES_TILESTEPPER_H
//# Includes
#include <casacore/casa/aips.h>
#include <casacore/lattices/Lattices/LatticeNavigator.h>
#include <casacore/lattices/Lattices/LatticeIndexer.h>
#include <casacore/casa/Arrays/IPosition.h>
namespace casacore { //# NAMESPACE CASACORE - BEGIN
// <summary>
// traverse a tiled Lattice optimally with a tile cursor
// </summary>
// <use visibility=export>
// <reviewed reviewer="Peter Barnes" date="1999/10/30" tests="tTileStepper.cc" demos="">
// </reviewed>
// <prerequisite>
// <li> <linkto class=LatticeNavigator> LatticeNavigator </linkto>
// </prerequisite>
// <etymology>
// TileStepper is used to step optimally through a tiled Lattice.
// </etymology>
// <synopsis>
// When you wish to traverse a Lattice (say, a PagedArray or an Image) you
// will usually create a LatticeIterator. Once created, you may attach a
// LatticeNavigator to the iterator. A TileStepper is a concrete class
// derived from the abstract LatticeNavigator that allows you to step
// through the Lattice in a way that will minimize the amount of cache
// memory consumed and maximize the speed.
// <p>
// Some Lattices (in particular PagedArrays) are stored (on disk) in
// tiles. For an N-dimensional Lattice a tile is an N-dimensional
// subsection with fewer elements along each axis. For example a Lattice of
// shape [512,512,4,32] may have a tile shape of [32,16,4,16], and there
// will be 16*32*1*2 (=1024) tiles in the entire Lattice. To allow efficient
// access of the data in a Lattice some tiles are cached in memory. As each
// tile may consume a fair bit of memory (in this example 128kBytes,
// assuming each element consumes 4 bytes), it is desirable to minimise the
// number of tiles held in the cache. But it is also desirable to minimise
// the number of times a tiles must be read into or written from the
// cache as this may require a time consuming operation like disk I/O.
// <p>
// TileStepper steps through a lattice in a tile-by-tile way.
// This means that the cache contains 1 tile only and that a tile is
// accessed only once.
// It should be clear that traversing a lattice in this way cannot
// be used if an entire vector or plane is needed. It is, however, very
// well suited for purposes like initialising a lattice, where the
// order in which the lattice pixels are accessed is not important.
// <p>
// In constructing a TileStepper, you specify the Lattice shape, the
// tile shape and optionally the axis path. The axis path defines the order
// in which the tiles are fetched from the lattice. Default is the natural
// order (thus x-axis in the inner loop).
// <br>It is possible to use the function <src>subSection</src> to
// traverse only a subsection of the lattice.
// <p>
// The cursor position can be incremented or decremented to retrieve the next
// or previous tile in the Lattice. The position of the next tile in the
// Lattice will depend on the tile shape, and is described above.
// <br>Note that the cursor shape does not need to be constant when iterating
// through the lattice. If the lattice shape is not an integer multiple of
// the tile shape, the cursor will be smaller on the edges of the lattice.
// </synopsis>
// <example>
// This example initializes a lattice with the given value.
// <srcblock>
// void init (Lattice<Complex>& cArray, Complex value)
// {
// const IPosition latticeShape = cArray.shape();
// const IPosition tileShape = cArray.niceCursorShape();
// TileStepper tsx(latticeShape, tileShape);
// LatticeIterator<Complex> lix(cArray, tsx);
// for (lix.reset();!lix.atEnd();lix++)
// lix.woCursor() = value;
// }
// }
// </srcblock>
// Note that a TileStepper is the default navigator for an iterator.
// So the code above could be made simpler like shown below.
// Also note that this example is a bit artificial, because the Lattice::set()
// function should be used to initialize a lattice.
// <srcblock>
// void init (Lattice<Complex>& cArray, Complex value)
// {
// LatticeIterator<Complex> lix(cArray);
// for (lix.reset();!lix.atEnd();lix++)
// lix.woCursor() = value;
// }
// }
// </srcblock>
// </example>
// <motivation>
// This class makes it possible to traverse a lattice in the optimal way.
// </motivation>
//
//# <todo asof="1997/11/21">
//# <li>
//# </todo>
class TileStepper: public LatticeNavigator
{
public:
// Construct a TileStepper by specifying the Lattice shape, a tile shape,
// and an optional axis path (default is natural order).
// Is is nearly always advisable to make the tileShape identical
// to the Lattice tileShape. This can be obtained by
// <src>lat.niceCursorShape()</src> where <src>lat</src> is
// a Lattice object.
// <group>
TileStepper (const IPosition& latticeShape,
const IPosition& tileShape);
TileStepper (const IPosition& latticeShape,
const IPosition& tileShape,
const IPosition& axisPath);
// </group>
// Copy constructor (copy semantics).
TileStepper (const TileStepper& other);
~TileStepper();
// Assignment (copy semantics).
TileStepper& operator= (const TileStepper& other);
// Increment operator (postfix or prefix version) - move the cursor
// forward one step. Returns True if the cursor was moved.
virtual Bool operator++(int);
// Decrement operator (postfix or prefix version) - move the cursor
// backwards one step. Returns True if the cursor was moved.
virtual Bool operator--(int);
// Function to move the cursor to the beginning of the Lattice. Also
// resets the number of steps (<src>nsteps</src> function) to zero.
virtual void reset();
// Function which returns "True" if the cursor is at the beginning of the
// Lattice, otherwise, returns "False"
virtual Bool atStart() const;
// Function which returns "True" if an attempt has been made to increment
// the cursor beyond the end of the Lattice.
virtual Bool atEnd() const;
// 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.
virtual uInt nsteps() const;
// Function which returns the current position of the beginning of the
// cursor. The <src>position</src> function is relative to the origin
// in the main Lattice.
virtual IPosition position() const;
// Function which returns the current position of the end of the
// cursor. The <src>endPosition</src> function is relative the origin
// in the main Lattice.
virtual IPosition endPosition() const;
// Functions which return the shape of the Lattice being iterated
// through. <src>latticeShape</src> always returns the shape of the main
// Lattice while <src>subLatticeShape</src> returns the shape of any
// sub-Lattice defined using the <src>subSection</src> function.
// <group>
virtual IPosition latticeShape() const;
virtual IPosition subLatticeShape() const;
// </group>
// Function which returns the shape of the cursor. This always includes
// all axes (i.e. it includes degenerates axes)
virtual IPosition cursorShape() const;
// Function which returns the axes of the cursor.
virtual IPosition cursorAxes() const;
// Function which returns the shape of the "tile" the cursor will iterate
// through before moving onto the next tile.
IPosition tileShape() 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 Lattice. This always returns False.
virtual Bool hangOver() const;
// 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.
// <group>
virtual void subSection (const IPosition& blc, const IPosition& trc);
virtual void subSection (const IPosition& blc, const IPosition& trc,
const IPosition& inc);
// </group>
// 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 <src>subSection</src> function)
// these functions return blc=0, trc=latticeShape-1, increment=1, ie. the
// entire Lattice.
// <group>
virtual IPosition blc() const;
virtual IPosition trc() const;
virtual IPosition increment() const;
// </group>
// Return the axis path.
virtual const IPosition& axisPath() const;
// 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.
virtual LatticeNavigator* clone() const;
// Function which checks the internal data of this class for correct
// dimensionality and consistant values.
// Returns True if everything is fine otherwise returns False
virtual Bool ok() const;
// Calculate the cache size (in tiles) for this type of access to a lattice
// in the given row of the tiled hypercube.
virtual uInt calcCacheSize (const IPosition& cubeShape,
const IPosition& tileShape,
uInt maxCacheSize, uInt bucketSize) const;
private:
// Prevent the default constructor from being used.
TileStepper();
IPosition itsBlc; //# Bottom Left Corner
IPosition itsTrc; //# Top Right Corner
IPosition itsInc; //# Increment
LatticeIndexer itsSubSection; //# The current subsection
LatticeIndexer itsTiler; //# For moving between tiles
IPosition itsTilerCursorPos; //# The current position of the iterator
IPosition itsTileShape; //# The tile shape (= itsTiler cursor shape)
IPosition itsAxisPath; //# Path for traversing
IPosition itsCurBlc; //# Blc of the current position.
IPosition itsCurTrc; //# Trc of the current position.
uInt itsNsteps; //# The number of iterator steps taken so far
Bool itsEnd; //# Is the cursor beyond the end?
Bool itsStart; //# Is the cursor at the beginning?
};
} //# NAMESPACE CASACORE - END
#endif
casacore::IPosition
Definition IPosition.h:117
casacore::LatticeIndexer
Definition LatticeIndexer.h:107
casacore::LatticeNavigator::LatticeNavigator
LatticeNavigator()
Default constructor.
Definition LatticeNavigator.h:183
casacore::TileStepper::itsCurBlc
IPosition itsCurBlc
Definition TileStepper.h:277
casacore::TileStepper::endPosition
virtual IPosition endPosition() const
Function which returns the current position of the end of the cursor.
casacore::TileStepper::itsSubSection
LatticeIndexer itsSubSection
Definition TileStepper.h:272
casacore::TileStepper::itsTilerCursorPos
IPosition itsTilerCursorPos
Definition TileStepper.h:274
casacore::TileStepper::TileStepper
TileStepper(const IPosition &latticeShape, const IPosition &tileShape)
Construct a TileStepper by specifying the Lattice shape, a tile shape, and an optional axis path (def...
casacore::TileStepper::itsBlc
IPosition itsBlc
Definition TileStepper.h:269
casacore::TileStepper::increment
virtual IPosition increment() const
casacore::TileStepper::itsInc
IPosition itsInc
Definition TileStepper.h:271
casacore::TileStepper::cursorShape
virtual IPosition cursorShape() const
Function which returns the shape of the cursor.
casacore::TileStepper::atStart
virtual Bool atStart() const
Function which returns "True" if the cursor is at the beginning of the Lattice, otherwise,...
casacore::TileStepper::reset
virtual void reset()
Function to move the cursor to the beginning of the Lattice.
casacore::TileStepper::calcCacheSize
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 tile...
casacore::TileStepper::tileShape
IPosition tileShape() const
Function which returns the shape of the "tile" the cursor will iterate through before moving onto the...
casacore::TileStepper::itsAxisPath
IPosition itsAxisPath
Definition TileStepper.h:276
casacore::TileStepper::itsTrc
IPosition itsTrc
Definition TileStepper.h:270
casacore::TileStepper::itsNsteps
uInt itsNsteps
Definition TileStepper.h:279
casacore::TileStepper::itsEnd
Bool itsEnd
Definition TileStepper.h:280
casacore::TileStepper::hangOver
virtual Bool hangOver() const
Function which returns "True" if the increment/decrement operators have moved the cursor position suc...
casacore::TileStepper::subLatticeShape
virtual IPosition subLatticeShape() const
casacore::TileStepper::operator=
TileStepper & operator=(const TileStepper &other)
Assignment (copy semantics).
casacore::TileStepper::ok
virtual Bool ok() const
Function which checks the internal data of this class for correct dimensionality and consistant value...
casacore::TileStepper::cursorAxes
virtual IPosition cursorAxes() const
Function which returns the axes of the cursor.
casacore::TileStepper::TileStepper
TileStepper()
Prevent the default constructor from being used.
casacore::TileStepper::position
virtual IPosition position() const
Function which returns the current position of the beginning of the cursor.
casacore::TileStepper::itsCurTrc
IPosition itsCurTrc
Definition TileStepper.h:278
casacore::TileStepper::itsTiler
LatticeIndexer itsTiler
Definition TileStepper.h:273
casacore::TileStepper::~TileStepper
~TileStepper()
casacore::TileStepper::subSection
virtual void subSection(const IPosition &blc, const IPosition &trc, const IPosition &inc)
casacore::TileStepper::trc
virtual IPosition trc() const
casacore::TileStepper::nsteps
virtual uInt nsteps() const
Function to return the number of steps (increments & decrements) taken since construction (or since l...
casacore::TileStepper::clone
virtual LatticeNavigator * clone() const
Function which returns a pointer to dynamic memory of an exact copy of this instance.
casacore::TileStepper::itsTileShape
IPosition itsTileShape
Definition TileStepper.h:275
casacore::TileStepper::subSection
virtual void subSection(const IPosition &blc, const IPosition &trc)
Functions to specify a "section" of the Lattice to step over.
casacore::TileStepper::latticeShape
virtual IPosition latticeShape() const
Functions which return the shape of the Lattice being iterated through.
casacore::TileStepper::operator++
virtual Bool operator++(int)
Increment operator (postfix or prefix version) - move the cursor forward one step.
casacore::TileStepper::blc
virtual IPosition blc() const
Return the bottom left hand corner (blc), top right corner (trc) or step size (increment) used by the...
casacore::TileStepper::atEnd
virtual Bool atEnd() const
Function which returns "True" if an attempt has been made to increment the cursor beyond the end of t...
casacore::TileStepper::axisPath
virtual const IPosition & axisPath() const
Return the axis path.
casacore::TileStepper::TileStepper
TileStepper(const TileStepper &other)
Copy constructor (copy semantics).
casacore::TileStepper::TileStepper
TileStepper(const IPosition &latticeShape, const IPosition &tileShape, const IPosition &axisPath)
casacore::TileStepper::operator--
virtual Bool operator--(int)
Decrement operator (postfix or prefix version) - move the cursor backwards one step.
casacore::TileStepper::itsStart
Bool itsStart
Definition TileStepper.h:281
casacore
this file contains all the compiler specific defines
Definition mainpage.dox:28
casacore::uInt
unsigned int uInt
Definition aipstype.h:49
casacore::Bool
bool Bool
Define the standard types used by Casacore.
Definition aipstype.h:40