Loading...
Searching...
No Matches
LatticeNavigator.h
Go to the documentation of this file.
//# LatticeNavigator.h: Abstract base class to steer lattice iterators
//# Copyright (C) 1994,1995,1996,1997,1998,1999
//# 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_LATTICENAVIGATOR_H
#define LATTICES_LATTICENAVIGATOR_H
//# Includes
#include <casacore/casa/aips.h>
namespace casacore { //# NAMESPACE CASACORE - BEGIN
//# Forward Declarations
class IPosition;
class ROTiledStManAccessor;
// <summary>
// Abstract base class to steer lattice iterators.
// </summary>
// <use visibility=local>
// <reviewed reviewer="Peter Barnes" date="1999/10/30" tests="tLatticeStepper.cc">
// </reviewed>
// <prerequisite>
// <li> <linkto class=LatticeIterator>LatticeIterator</linkto>
// <li> <linkto class=Lattice>Lattice</linkto>
// </prerequisite>
// <etymology>
// Lattice iteration can proceed with a number of different strategies -
// all of which answer the question: where do I go from here?
// You could travel through by making calculations on the lattice subscripts,
// viewing ascending planes in an image cube, for example, or you could
// travel through by making calculations on the data, viewing small
// subimage planes in order of descending brightness over the whole cube.
// Concrete classes derived from this base class implement different
// navigation strategies - but they are all "navigators".
// </etymology>
// <synopsis>
// This abstract base class defines the interface for objects which generate
// positions for LatticeIterators. This position is not just a single point
// in the Lattice but a region or "cursor" that is moved through the
// Lattice. The LatticeIterator classes actually retrieve the data in the
// cursor from the Lattice. The class decribed here (and those derived from it)
// are responsible for moving the cursor to the next position and determining
// its shape.
//
// There may eventually be a large collection of tools for traversing
// Lattices. At this writing (December 1999) there are three concrete
// classes derived from LatticeNavigator:
// <linkto class="LatticeStepper">LatticeStepper</linkto>,
// <linkto class="TiledLineStepper">TiledLineStepper</linkto>, and
// <linkto class="TileStepper">TileStepper</linkto>.
//
// The <src>LatticeStepper</src> class moves through a Lattice in fixed
// steps defined by the user specified cursor, incrementing to the next
// portion of the Lattice with each step, and wrapping around axes as
// needed. Other position generators might follow the brightest pixel,
// traverse a number of predefined subregions, or change size automatically
// when near the edges.
//
// The <src>TiledLineStepper</src> class moves a Vector cursor through a
// Lattice, until all the lines in the set of tiles along the specified
// axis have been exhausted. It then moves to the next set of tiles. This is
// a memory-efficient way to move a Vector cursor through a Lattice.
//
// The most important member functions of this class are those which move
// the cursor to the next position. These are the <src>operator++</src> and
// <src>operator--</src> member functions, (in postfix and prefix forms).
//
// The cursor shape need not be constant as it moves through the Lattice,
// but may change depending on its current position. For the LatticeStepper
// and TiledLineStepper classes , however, the cursor shape is constant
// as it steps through the Lattice.
//
// It is not possible to randomly move the cursor to an arbitrary place in
// the Lattice, although the cursor can be moved to the starting position at
// any time using the <src>reset</src> member function.
//
// The position of the cursor can be queried at any time using the
// <src>position</src> member function. This gives the position of the
// bottom left hand corner of the cursor. The position of the top right hand
// corner of the cursor is obtained using the <src>endPosition</src> member
// function, and the current cursor shape is obtained using the
// <src>cursorShape</src> member function. Note that the endPosition
// does not take an overhang into account.
//
// It is possible that for some positions of the cursor, part of it will
// "hang over" the edge of the Lattice. When this occurs the
// <src>hangOver</src> member function will return True. This will occur
// with a LatticeStepper if the Lattice shape is not a multiple of the
// cursor shape. Hangover cannot occur with the TiledLineStepper as the length
// of the Vector cursor is defined by the Lattice Shape.
//
// It may be possible (depending on the concrete LatticeNavigator actually
// used) to specify that only a region of the Lattice (defined by a top
// right hand corner, bottom left hand corner, and step increment) be
// traversed by the LatticeNavigator. This is done using the
// <src>subSection</src> member function. At any time the region can be
// redefined by calling the <src>subSection</src> function again. This
// replaces the previously defined region with the new one.
//
// Using the subSection function always sets the cursor position to the
// origin of the currently defined sub-lattice. This is a backdoor way to
// move the cursor to random locations in the Lattice.
//
// It is an error to define a sub-lattice that is bigger than the current
// Lattice. If using a LatticeStepper it may also be necessary to resize the
// cursor (using the <src>setCursorShape</src> member function) prior to
// calling the subSection function as the cursor cannot be bigger than the
// sub-Lattice on any axis.
//
// The arguments (<src>trc</src>, <src>blc</src> and <src>inc</src>)
// to the <src>subSection</src> function are always
// relative to the main Lattice. This is also true of the <src>position</src>
// and <src>endPosition</src> functions. To get the position of the cursor
// relative to the currently defined sub-Lattice use the
// <src>relativePosition</src> and <src>relativeEndPosition</src> member
// functions.
//
// Many of the LatticeIterator member functions are directly forwarded to
// virtual functions of this class, and classes derived from it. For
// instance, LatticeIterator<T>::operator++() calls
// LatticeIterInterface->operator++() which calls
// LatticeNavigator->operator++() which might resolve to
// LatticeStepper->operator++(). Other functions like this are documented in
// the <linkto class="LatticeIterator">LatticeIterator</linkto> class.
// </synopsis>
// <example>
// See the examples in the
// <linkto class="LatticeStepper">LatticeStepper</linkto> class, the
// <linkto class="TiledLineStepper">TiledLineStepper</linkto> class, and the
// <linkto class="TileStepper">TileStepper</linkto> class.
// </example>
//
// <motivation>
// Iterator classes are quite common in C++. What's novel about the design
// which includes this class is the separation of iterator mechanisms from
// traversal strategy. The iterator provides a lot of functionality: it
// provides a cursor, damage notification and tracking, and reading and
// writing to the underlying data structure. Traversal strategies can and
// should be isolated from these things. Because every LatticeIterator
// uses a Navigator, it gets the benefits of a derived concrete navigator
// without getting involved in its mechanism.
// </motivation>
//
// <todo asof="1997/31/01">
// <li> Think about how to implement Navigators which can traverse
// arbitrary shaped regions.
// </todo>
class LatticeNavigator {
public:
// Default constructor.
LatticeNavigator()
{;}
// Copy constructor.
LatticeNavigator (const LatticeNavigator&)
{;}
// Assignment.
LatticeNavigator& operator= (const LatticeNavigator&)
{ return *this; }
// A virtual destructor. A virtual is needed to ensure that derived
// classes accessed through pointers to a LatticeNavigator will scope
// their destructor to the derived class destructor.
virtual ~LatticeNavigator();
// Increment operator - increment the cursor to the next position. The
// implementation of the prefix operator calls the postfix one.
// <group>
virtual Bool operator++(int) = 0;
Bool operator++();
// </group>
// Decrement operator - decrement the cursor to the previous position. The
// implementation of the prefix operator calls the postfix one.
// <group>
virtual Bool operator--(int) = 0;
Bool operator--();
// </group>
// Function to reset the cursor to the beginning of the Lattice and
// reset the number of steps taken to zero.
virtual void reset() = 0;
// Function which returns "True" if the cursor is at the beginning of the
// Lattice, otherwise, returns "False"
virtual Bool atStart() const = 0;
// Function which returns "True" if an attempt has been made to increment
// the cursor beyond the end of the Lattice.
virtual Bool atEnd() const = 0;
// Function to return the number of steps (increments or decrements) taken
// since construction (or since last reset). This is a running count of
// all cursor movement since doing N increments followed by N decrements
// does not necessarily put the cursor back at the origin of the Lattice.
virtual uInt nsteps() const = 0;
// Functions which return the current position of the beginning of the
// cursor. The <src>position</src> function is relative to the origin in
// the main Lattice and the <src>relativePosition</src> function is
// relative to the origin and increment used in the sub-Lattice (defined
// using the <src>subSection</src> function).
// The returned IPosition will have the same number of axes as
// the underlying Lattice.
// <br>The default implementation of the <src>relativePosition</src>
// function returns <src>(position() - blc()) / increment()</src>.
// <group>
virtual IPosition position() const = 0;
virtual IPosition relativePosition() const;
// </group>
// Functions which return the current position of the end of the
// cursor. The <src>endPosition</src> function is relative to the origin in
// the main Lattice and the <src>relativeEndPosition</src> function is
// relative to the origin and increment used in the sub-Lattice (defined
// using the <src>subSection</src> function).
// The returned IPosition will have the same number of axes as
// the underlying Lattice.
// <note role=caution> It returns the end position in the lattice and
// does not take overhang into account. </note>
// <br>The default implementation of the <src>relativeEndPosition</src>
// function returns <src>(endPosition() - blc()) / increment()</src>.
// <group>
virtual IPosition endPosition() const = 0;
virtual IPosition relativeEndPosition() const;
// </group>
// 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. In the
// default implementation of this class it is not possible to use the
// <src>subsection</src> function (it throws an exception) so the default
// implementation of the <src>subLatticeShape</src> function calls the
// <src>latticeShape</src> function. The returned IPosition will always
// have the same number of axes as the underlying Lattice.
// <group>
virtual IPosition latticeShape() const = 0;
virtual IPosition subLatticeShape() const;
// </group>
// Function which returns the current shape of the cursor which is
// iterating through the Lattice. The returned IPosition will have the
// same number of axes as the underlying Lattice.
virtual IPosition cursorShape() const = 0;
// Function which returns the axes of the cursor.
// These are the axes which should not be removed by the
// iterator functions <src>vectorCursor()</src>, etc..
virtual IPosition cursorAxes() const = 0;
// Function which returns "True" if the increment/decrement operators have
// moved the cursor position such that part of the cursor is hanging over
// the edge of the Lattice. This function may always return a value of
// "False" for some iteration methods that do not move the cursor past the
// Lattice boundaries.
virtual Bool hangOver() const = 0;
// Functions which return the "bottom left corner" and the "top right corner"
// of the cursor that does not hangover. Use these functions to extract the
// valid part of the cursor when the hangover member function is true. If
// there is no hangover then hangOverBLC returns an IPosition of zero and
// hangOverTRC() returns the cursorShape - 1;
// <group>
virtual IPosition hangOverBlc() const;
virtual IPosition hangOverTrc() const;
// </group>
// Function to specify a "section" of the Lattice to Navigate 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.
// In the default implementation of this class subsectioning is not
// supported and using the <src>subsection</src> function will throw an
// exception (AipsError).
// <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. In the default
// implementation of this class sub-sectioning is not supported and these
// functions will always 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.
// See <linkto class=LatticeStepper>LatticeStepper</linkto> for a
// description and examples.
virtual const IPosition& axisPath() const = 0;
// Calculate the cache size (in tiles) for this type of access to a lattice
// in the given row of the tiled hypercube.
// A zero bucket size indicates that the data are not tiled, but in memory.
// Then a cache size of 0 is returned.
virtual uInt calcCacheSize (const IPosition& cubeShape,
const IPosition& tileShape,
uInt maxCacheSize, uInt bucketSize) const = 0;
// Function which returns a pointer to dynamic memory of an exact copy
// of this LatticeNavigator. It is the responsibility of the caller to
// release this memory.
virtual LatticeNavigator* clone() const = 0;
// Function which checks the internals of the class for consistency.
// Returns True if everything is fine otherwise returns False. The default
// implementation always returns True.
virtual Bool ok() const;
};
inline Bool LatticeNavigator::operator++()
{
return operator++(0);
}
inline Bool LatticeNavigator::operator--()
{
return operator--(0);
}
} //# NAMESPACE CASACORE - END
#endif
casacore::IPosition
Definition IPosition.h:117
casacore::LatticeNavigator::hangOverTrc
virtual IPosition hangOverTrc() const
casacore::LatticeNavigator::cursorAxes
virtual IPosition cursorAxes() const =0
Function which returns the axes of the cursor.
casacore::LatticeNavigator::cursorShape
virtual IPosition cursorShape() const =0
Function which returns the current shape of the cursor which is iterating through the Lattice.
casacore::LatticeNavigator::relativeEndPosition
virtual IPosition relativeEndPosition() const
casacore::LatticeNavigator::hangOver
virtual Bool hangOver() const =0
Function which returns "True" if the increment/decrement operators have moved the cursor position suc...
casacore::LatticeNavigator::blc
virtual IPosition blc() const
Return the bottom left hand corner (blc), top right corner (trc) or step size (increment) used by the...
casacore::LatticeNavigator::operator--
virtual Bool operator--(int)=0
Decrement operator - decrement the cursor to the previous position.
casacore::LatticeNavigator::endPosition
virtual IPosition endPosition() const =0
Functions which return the current position of the end of the cursor.
casacore::LatticeNavigator::subLatticeShape
virtual IPosition subLatticeShape() const
casacore::LatticeNavigator::hangOverBlc
virtual IPosition hangOverBlc() const
Functions which return the "bottom left corner" and the "top right corner" of the cursor that does no...
casacore::LatticeNavigator::operator++
Bool operator++()
Definition LatticeNavigator.h:352
casacore::LatticeNavigator::trc
virtual IPosition trc() const
casacore::LatticeNavigator::calcCacheSize
virtual uInt calcCacheSize(const IPosition &cubeShape, const IPosition &tileShape, uInt maxCacheSize, uInt bucketSize) const =0
Calculate the cache size (in tiles) for this type of access to a lattice in the given row of the tile...
casacore::LatticeNavigator::atStart
virtual Bool atStart() const =0
Function which returns "True" if the cursor is at the beginning of the Lattice, otherwise,...
casacore::LatticeNavigator::axisPath
virtual const IPosition & axisPath() const =0
Return the axis path.
casacore::LatticeNavigator::~LatticeNavigator
virtual ~LatticeNavigator()
A virtual destructor.
casacore::LatticeNavigator::increment
virtual IPosition increment() const
casacore::LatticeNavigator::latticeShape
virtual IPosition latticeShape() const =0
Functions which return the shape of the Lattice being iterated through.
casacore::LatticeNavigator::relativePosition
virtual IPosition relativePosition() const
casacore::LatticeNavigator::reset
virtual void reset()=0
Function to reset the cursor to the beginning of the Lattice and reset the number of steps taken to z...
casacore::LatticeNavigator::subSection
virtual void subSection(const IPosition &blc, const IPosition &trc)
Function to specify a "section" of the Lattice to Navigate over.
casacore::LatticeNavigator::LatticeNavigator
LatticeNavigator(const LatticeNavigator &)
Copy constructor.
Definition LatticeNavigator.h:187
casacore::LatticeNavigator::subSection
virtual void subSection(const IPosition &blc, const IPosition &trc, const IPosition &inc)
casacore::LatticeNavigator::operator--
Bool operator--()
Definition LatticeNavigator.h:356
casacore::LatticeNavigator::position
virtual IPosition position() const =0
Functions which return the current position of the beginning of the cursor.
casacore::LatticeNavigator::clone
virtual LatticeNavigator * clone() const =0
Function which returns a pointer to dynamic memory of an exact copy of this LatticeNavigator.
casacore::LatticeNavigator::LatticeNavigator
LatticeNavigator()
Default constructor.
Definition LatticeNavigator.h:183
casacore::LatticeNavigator::operator=
LatticeNavigator & operator=(const LatticeNavigator &)
Assignment.
Definition LatticeNavigator.h:191
casacore::LatticeNavigator::atEnd
virtual Bool atEnd() const =0
Function which returns "True" if an attempt has been made to increment the cursor beyond the end of t...
casacore::LatticeNavigator::ok
virtual Bool ok() const
Function which checks the internals of the class for consistency.
casacore::LatticeNavigator::nsteps
virtual uInt nsteps() const =0
Function to return the number of steps (increments or decrements) taken since construction (or since ...
casacore::LatticeNavigator::operator++
virtual Bool operator++(int)=0
Increment operator - increment the cursor to the next position.
casacore::ROTiledStManAccessor
Definition TiledStManAccessor.h:155
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