Loading...
Searching...
No Matches
LatticeIndexer.h
Go to the documentation of this file.
//# LatticeIndexer.h: A helper class for stepping through Lattices
//# 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_LATTICEINDEXER_H
#define LATTICES_LATTICEINDEXER_H
//# Includes
#include <casacore/casa/aips.h>
#include <casacore/casa/Arrays/IPosition.h>
namespace casacore { //# NAMESPACE CASACORE - BEGIN
// <summary>
// A helper class for stepping through Lattices.
// </summary>
// <use visibility=local>
// <reviewed reviewer="Peter Barnes" date="1999/10/30" tests="tLatticeIndexer">
// </reviewed>
// <prerequisite>
// <li> <linkto class="Lattice"> Lattice </linkto>
// <li> <linkto class="IPosition"> IPosition </linkto>
// </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.
// </etymology>
// <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.
// <p>
// 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.
// <p>
// 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.
// <p>
// A sub-Lattice can be defined on the Lattice by specifying a trc, blc,
// and step increment using the <src>subSection</src> 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.
// <br>
// 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.
// <p>
// The only way to increase the size of a sub-Lattice is to first revert to
// the parent Lattice (using the <src>fullSize</src> function) and then
// generate the new, bigger sub-Lattice.
// <p>
// Indexing calculations (eg. the <src>tiledCursorMove</src> or the
// <src>isInside</src> function) are performed on the specified sub-Lattice.
// <p>
// 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
// <linkto class="LatticeStepper">LatticeStepper</linkto>.
// </synopsis>
// <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.
// </motivation>
//# <todo asof="1997/01/12">
//# </todo>
class LatticeIndexer
{
public:
// Default constructor (one dimensional, unit-length instance).
LatticeIndexer();
// Specify the size of the Lattice. Assume a full size sub-Lattice.
explicit LatticeIndexer (const IPosition& shape);
// Specify a Lattice and define a sub-Lattice within it.
LatticeIndexer (const IPosition& shape, const IPosition& blc,
const IPosition& trc, const IPosition& inc);
// The copy constructor uses copy semantics.
LatticeIndexer (const LatticeIndexer& other);
~LatticeIndexer();
// The assignment operator uses copy semantics.
LatticeIndexer& operator= (const LatticeIndexer& other);
// Function to change the shape of the Lattice. Resets the sub-Lattice to
// fullsize.
void resize (const IPosition& newShape);
// Returns the length of each axis (or the requested one) in the parent
// Lattice.
// <group>
const IPosition& fullShape() const;
uInt fullShape (uInt axis) const;
// </group>
// Returns the length of each axis (or the requested one) in the sub-Lattice.
// <group>
const IPosition& shape() const;
uInt shape (uInt axis) const;
// </group>
// Function to return the increments along each axis (or the requested
// one) of the Lattice.
// <group>
const IPosition& increment() const;
uInt increment (uInt axis) const;
// </group>
// Function to return the offset (on a specified axis) between the
// sub-Lattice and the parent one.
// <group>
const IPosition& offset() const;
uInt offset (uInt axis) const;
// </group>
// Function which returns the number of dimensions in the Lattice (or
// sub-Lattice).
uInt ndim() const;
// 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.
void fullSize();
// Function which returns the number of elements in the sub-Lattice;
// this value is equal to the product of shape().
size_t nelements() 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 tiledCursorMove (Bool incr, IPosition& cursorPos,
const IPosition& cursorShape,
const IPosition& cursorHeading) 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.
// <note role=warning> Due to zero-origins, an index argument equal to the
// shape of this sub-Lattice lies outside and returns False.
// </note>
Bool isInside (const IPosition& index) const;
// 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).
// <group>
void subSection (const IPosition& blc, const IPosition& trc,
const IPosition& inc);
void subSection (const IPosition& blc, const IPosition& trc);
// </group>
// 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).
IPosition absolutePosition (const IPosition& position) const;
//# function which returns True if all the elements in this
//# LatticeIndexer, or LatticeIndexer subsection, are arranged contiguously,
//# i.e. without any gaps caused by increments or subSectioning.
//# Bool isContiguous() const;
// Is this LatticeIndexer consistent, i.e. are the class invariants valid?
// Returns True if every thing is fine otherwise returns False
Bool ok() const;
private:
IPosition itsFullShape; //# Size of the main-Lattice.
uInt itsNdim; //# Number of dimensions in the main/sub-Lattice
IPosition itsShape; //# Shape of the sub-Lattice
IPosition itsAxisInc; //# Increment along each axis of main Lattice
IPosition itsOffset; //# Offset between a sub-Lattice and the main one.
};
inline const IPosition& LatticeIndexer::fullShape() const
{
return itsFullShape;
}
inline const IPosition& LatticeIndexer::shape() const
{
return itsShape;
}
inline const IPosition& LatticeIndexer::increment() const
{
return itsAxisInc;
}
inline const IPosition& LatticeIndexer::offset() const
{
return itsOffset;
}
inline uInt LatticeIndexer::ndim() const
{
return itsNdim;
}
inline size_t LatticeIndexer::nelements() const
{
return itsShape.product();
}
} //# NAMESPACE CASACORE - END
#endif
casacore::IPosition
Definition IPosition.h:117
casacore::LatticeIndexer::itsAxisInc
IPosition itsAxisInc
Definition LatticeIndexer.h:232
casacore::LatticeIndexer::LatticeIndexer
LatticeIndexer()
Default constructor (one dimensional, unit-length instance).
casacore::LatticeIndexer::~LatticeIndexer
~LatticeIndexer()
casacore::LatticeIndexer::fullSize
void fullSize()
Revert from a sub-Lattice description back to the main Lattice.
casacore::LatticeIndexer::operator=
LatticeIndexer & operator=(const LatticeIndexer &other)
The assignment operator uses copy semantics.
casacore::LatticeIndexer::shape
const IPosition & shape() const
Returns the length of each axis (or the requested one) in the sub-Lattice.
Definition LatticeIndexer.h:241
casacore::LatticeIndexer::fullShape
const IPosition & fullShape() const
Returns the length of each axis (or the requested one) in the parent Lattice.
Definition LatticeIndexer.h:237
casacore::LatticeIndexer::tiledCursorMove
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 IPosi...
casacore::LatticeIndexer::LatticeIndexer
LatticeIndexer(const LatticeIndexer &other)
The copy constructor uses copy semantics.
casacore::LatticeIndexer::resize
void resize(const IPosition &newShape)
Function to change the shape of the Lattice.
casacore::LatticeIndexer::offset
const IPosition & offset() const
Function to return the offset (on a specified axis) between the sub-Lattice and the parent one.
Definition LatticeIndexer.h:249
casacore::LatticeIndexer::LatticeIndexer
LatticeIndexer(const IPosition &shape, const IPosition &blc, const IPosition &trc, const IPosition &inc)
Specify a Lattice and define a sub-Lattice within it.
casacore::LatticeIndexer::itsFullShape
IPosition itsFullShape
Definition LatticeIndexer.h:229
casacore::LatticeIndexer::fullShape
uInt fullShape(uInt axis) const
casacore::LatticeIndexer::itsShape
IPosition itsShape
Definition LatticeIndexer.h:231
casacore::LatticeIndexer::nelements
size_t nelements() const
Function which returns the number of elements in the sub-Lattice; this value is equal to the product ...
Definition LatticeIndexer.h:257
casacore::LatticeIndexer::ndim
uInt ndim() const
Function which returns the number of dimensions in the Lattice (or sub-Lattice).
Definition LatticeIndexer.h:253
casacore::LatticeIndexer::LatticeIndexer
LatticeIndexer(const IPosition &shape)
Specify the size of the Lattice.
casacore::LatticeIndexer::offset
uInt offset(uInt axis) const
casacore::LatticeIndexer::absolutePosition
IPosition absolutePosition(const IPosition &position) const
Function which returns an IPosition in the parent Lattice given an IPostion in the sub-Lattice.
casacore::LatticeIndexer::subSection
void subSection(const IPosition &blc, const IPosition &trc)
casacore::LatticeIndexer::increment
const IPosition & increment() const
Function to return the increments along each axis (or the requested one) of the Lattice.
Definition LatticeIndexer.h:245
casacore::LatticeIndexer::itsOffset
IPosition itsOffset
Definition LatticeIndexer.h:233
casacore::LatticeIndexer::isInside
Bool isInside(const IPosition &index) const
Function which returns a value of True if the IPosition argument is within the sub-Lattice.
casacore::LatticeIndexer::subSection
void subSection(const IPosition &blc, const IPosition &trc, const IPosition &inc)
Function which subsections a LatticeIndexer.
casacore::LatticeIndexer::ok
Bool ok() const
Is this LatticeIndexer consistent, i.e.
casacore::LatticeIndexer::increment
uInt increment(uInt axis) const
casacore::LatticeIndexer::shape
uInt shape(uInt axis) const
casacore::LatticeIndexer::itsNdim
uInt itsNdim
Definition LatticeIndexer.h:230
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