casacore
TileStepper.h
Go to the documentation of this file.
1 //# TileStepper.h: Steps a cursor optimally through a tiled Lattice
2 //# Copyright (C) 1997,1998,1999,2000
3 //# Associated Universities, Inc. Washington DC, USA.
4 //#
5 //# This library is free software; you can redistribute it and/or modify it
6 //# under the terms of the GNU Library General Public License as published by
7 //# the Free Software Foundation; either version 2 of the License, or (at your
8 //# option) any later version.
9 //#
10 //# This library is distributed in the hope that it will be useful, but WITHOUT
11 //# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
12 //# FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public
13 //# License for more details.
14 //#
15 //# You should have received a copy of the GNU Library General Public License
16 //# along with this library; if not, write to the Free Software Foundation,
17 //# Inc., 675 Massachusetts Ave, Cambridge, MA 02139, USA.
18 //#
19 //# Correspondence concerning AIPS++ should be addressed as follows:
20 //# Internet email: aips2-request@nrao.edu.
21 //# Postal address: AIPS++ Project Office
22 //# National Radio Astronomy Observatory
23 //# 520 Edgemont Road
24 //# Charlottesville, VA 22903-2475 USA
25 //#
26 //# $Id$
27 
28 #ifndef LATTICES_TILESTEPPER_H
29 #define LATTICES_TILESTEPPER_H
30 
31 //# Includes
32 #include <casacore/casa/aips.h>
33 #include <casacore/lattices/Lattices/LatticeNavigator.h>
34 #include <casacore/lattices/Lattices/LatticeIndexer.h>
35 #include <casacore/casa/Arrays/IPosition.h>
36 
37 
38 namespace casacore { //# NAMESPACE CASACORE - BEGIN
39 
40 // <summary>
41 // traverse a tiled Lattice optimally with a tile cursor
42 // </summary>
43 
44 // <use visibility=export>
45 
46 // <reviewed reviewer="Peter Barnes" date="1999/10/30" tests="tTileStepper.cc" demos="">
47 // </reviewed>
48 
49 // <prerequisite>
50 // <li> <linkto class=LatticeNavigator> LatticeNavigator </linkto>
51 // </prerequisite>
52 
53 // <etymology>
54 // TileStepper is used to step optimally through a tiled Lattice.
55 // </etymology>
56 
57 // <synopsis>
58 // When you wish to traverse a Lattice (say, a PagedArray or an Image) you
59 // will usually create a LatticeIterator. Once created, you may attach a
60 // LatticeNavigator to the iterator. A TileStepper is a concrete class
61 // derived from the abstract LatticeNavigator that allows you to step
62 // through the Lattice in a way that will minimize the amount of cache
63 // memory consumed and maximize the speed.
64 // <p>
65 // Some Lattices (in particular PagedArrays) are stored (on disk) in
66 // tiles. For an N-dimensional Lattice a tile is an N-dimensional
67 // subsection with fewer elements along each axis. For example a Lattice of
68 // shape [512,512,4,32] may have a tile shape of [32,16,4,16], and there
69 // will be 16*32*1*2 (=1024) tiles in the entire Lattice. To allow efficient
70 // access of the data in a Lattice some tiles are cached in memory. As each
71 // tile may consume a fair bit of memory (in this example 128kBytes,
72 // assuming each element consumes 4 bytes), it is desirable to minimise the
73 // number of tiles held in the cache. But it is also desirable to minimise
74 // the number of times a tiles must be read into or written from the
75 // cache as this may require a time consuming operation like disk I/O.
76 // <p>
77 // TileStepper steps through a lattice in a tile-by-tile way.
78 // This means that the cache contains 1 tile only and that a tile is
79 // accessed only once.
80 // It should be clear that traversing a lattice in this way cannot
81 // be used if an entire vector or plane is needed. It is, however, very
82 // well suited for purposes like initialising a lattice, where the
83 // order in which the lattice pixels are accessed is not important.
84 // <p>
85 // In constructing a TileStepper, you specify the Lattice shape, the
86 // tile shape and optionally the axis path. The axis path defines the order
87 // in which the tiles are fetched from the lattice. Default is the natural
88 // order (thus x-axis in the inner loop).
89 // <br>It is possible to use the function <src>subSection</src> to
90 // traverse only a subsection of the lattice.
91 // <p>
92 // The cursor position can be incremented or decremented to retrieve the next
93 // or previous tile in the Lattice. The position of the next tile in the
94 // Lattice will depend on the tile shape, and is described above.
95 // <br>Note that the cursor shape does not need to be constant when iterating
96 // through the lattice. If the lattice shape is not an integer multiple of
97 // the tile shape, the cursor will be smaller on the edges of the lattice.
98 // </synopsis>
99 
100 // <example>
101 // This example initializes a lattice with the given value.
102 // <srcblock>
103 // void init (Lattice<Complex>& cArray, Complex value)
104 // {
105 // const IPosition latticeShape = cArray.shape();
106 // const IPosition tileShape = cArray.niceCursorShape();
107 // TileStepper tsx(latticeShape, tileShape);
108 // LatticeIterator<Complex> lix(cArray, tsx);
109 // for (lix.reset();!lix.atEnd();lix++)
110 // lix.woCursor() = value;
111 // }
112 // }
113 // </srcblock>
114 // Note that a TileStepper is the default navigator for an iterator.
115 // So the code above could be made simpler like shown below.
116 // Also note that this example is a bit artificial, because the Lattice::set()
117 // function should be used to initialize a lattice.
118 // <srcblock>
119 // void init (Lattice<Complex>& cArray, Complex value)
120 // {
121 // LatticeIterator<Complex> lix(cArray);
122 // for (lix.reset();!lix.atEnd();lix++)
123 // lix.woCursor() = value;
124 // }
125 // }
126 // </srcblock>
127 // </example>
128 
129 // <motivation>
130 // This class makes it possible to traverse a lattice in the optimal way.
131 // </motivation>
132 //
133 //# <todo asof="1997/11/21">
134 //# <li>
135 //# </todo>
136 
137 
139 {
140 public:
141 
142  // Construct a TileStepper by specifying the Lattice shape, a tile shape,
143  // and an optional axis path (default is natural order).
144  // Is is nearly always advisable to make the tileShape identical
145  // to the Lattice tileShape. This can be obtained by
146  // <src>lat.niceCursorShape()</src> where <src>lat</src> is
147  // a Lattice object.
148  // <group>
150  const IPosition& tileShape);
152  const IPosition& tileShape,
153  const IPosition& axisPath);
154  // </group>
155 
156  // Copy constructor (copy semantics).
157  TileStepper (const TileStepper& other);
158 
159  ~TileStepper();
160 
161  // Assignment (copy semantics).
162  TileStepper& operator= (const TileStepper& other);
163 
164  // Increment operator (postfix or prefix version) - move the cursor
165  // forward one step. Returns True if the cursor was moved.
166  virtual Bool operator++(int);
167 
168  // Decrement operator (postfix or prefix version) - move the cursor
169  // backwards one step. Returns True if the cursor was moved.
170  virtual Bool operator--(int);
171 
172  // Function to move the cursor to the beginning of the Lattice. Also
173  // resets the number of steps (<src>nsteps</src> function) to zero.
174  virtual void reset();
175 
176  // Function which returns "True" if the cursor is at the beginning of the
177  // Lattice, otherwise, returns "False"
178  virtual Bool atStart() const;
179 
180  // Function which returns "True" if an attempt has been made to increment
181  // the cursor beyond the end of the Lattice.
182  virtual Bool atEnd() const;
183 
184  // Function to return the number of steps (increments & decrements) taken
185  // since construction (or since last reset). This is a running count of
186  // all cursor movement (operator++ or operator--), even though
187  // N-increments followed by N-decrements will always leave the cursor in
188  // the original position.
189  virtual uInt nsteps() const;
190 
191  // Function which returns the current position of the beginning of the
192  // cursor. The <src>position</src> function is relative to the origin
193  // in the main Lattice.
194  virtual IPosition position() const;
195 
196  // Function which returns the current position of the end of the
197  // cursor. The <src>endPosition</src> function is relative the origin
198  // in the main Lattice.
199  virtual IPosition endPosition() const;
200 
201  // Functions which return the shape of the Lattice being iterated
202  // through. <src>latticeShape</src> always returns the shape of the main
203  // Lattice while <src>subLatticeShape</src> returns the shape of any
204  // sub-Lattice defined using the <src>subSection</src> function.
205  // <group>
206  virtual IPosition latticeShape() const;
207  virtual IPosition subLatticeShape() const;
208  // </group>
209 
210  // Function which returns the shape of the cursor. This always includes
211  // all axes (i.e. it includes degenerates axes)
212  virtual IPosition cursorShape() const;
213 
214  // Function which returns the axes of the cursor.
215  virtual IPosition cursorAxes() const;
216 
217  // Function which returns the shape of the "tile" the cursor will iterate
218  // through before moving onto the next tile.
219  IPosition tileShape() const;
220 
221  // Function which returns "True" if the increment/decrement operators have
222  // moved the cursor position such that part of the cursor beginning or end
223  // is hanging over the edge of the Lattice. This always returns False.
224  virtual Bool hangOver() const;
225 
226  // Functions to specify a "section" of the Lattice to step over. A section
227  // is defined in terms of the Bottom Left Corner (blc), Top Right Corner
228  // (trc), and step size (inc), on ALL of its axes, including degenerate
229  // axes. The step size defaults to one if not specified.
230  // <group>
231  virtual void subSection (const IPosition& blc, const IPosition& trc);
232  virtual void subSection (const IPosition& blc, const IPosition& trc,
233  const IPosition& inc);
234  // </group>
235 
236  // Return the bottom left hand corner (blc), top right corner (trc) or
237  // step size (increment) used by the current sub-Lattice. If no
238  // sub-Lattice has been defined (with the <src>subSection</src> function)
239  // these functions return blc=0, trc=latticeShape-1, increment=1, ie. the
240  // entire Lattice.
241  // <group>
242  virtual IPosition blc() const;
243  virtual IPosition trc() const;
244  virtual IPosition increment() const;
245  // </group>
246 
247  // Return the axis path.
248  virtual const IPosition& axisPath() const;
249 
250  // Function which returns a pointer to dynamic memory of an exact copy
251  // of this instance. The pointer returned by this function must
252  // be deleted externally.
253  virtual LatticeNavigator* clone() const;
254 
255  // Function which checks the internal data of this class for correct
256  // dimensionality and consistant values.
257  // Returns True if everything is fine otherwise returns False
258  virtual Bool ok() const;
259 
260  // Calculate the cache size (in tiles) for this type of access to a lattice
261  // in the given row of the tiled hypercube.
262  virtual uInt calcCacheSize (const IPosition& cubeShape,
263  const IPosition& tileShape,
264  uInt maxCacheSize, uInt bucketSize) const;
265 
266 private:
267  // Prevent the default constructor from being used.
268  TileStepper();
269 
270 
271  IPosition itsBlc; //# Bottom Left Corner
272  IPosition itsTrc; //# Top Right Corner
273  IPosition itsInc; //# Increment
274  LatticeIndexer itsSubSection; //# The current subsection
275  LatticeIndexer itsTiler; //# For moving between tiles
276  IPosition itsTilerCursorPos; //# The current position of the iterator
277  IPosition itsTileShape; //# The tile shape (= itsTiler cursor shape)
278  IPosition itsAxisPath; //# Path for traversing
279  IPosition itsCurBlc; //# Blc of the current position.
280  IPosition itsCurTrc; //# Trc of the current position.
281  uInt itsNsteps; //# The number of iterator steps taken so far
282  Bool itsEnd; //# Is the cursor beyond the end?
283  Bool itsStart; //# Is the cursor at the beginning?
284 };
285 
286 
287 
288 } //# NAMESPACE CASACORE - END
289 
290 #endif
casacore::TileStepper::ok
virtual Bool ok() const
Function which checks the internal data of this class for correct dimensionality and consistant value...
casacore::TileStepper::subLatticeShape
virtual IPosition subLatticeShape() const
casacore::IPosition
A Vector of integers, for indexing into Array<T> objects.
Definition: IPosition.h:119
casacore::TileStepper::itsAxisPath
IPosition itsAxisPath
Definition: TileStepper.h:278
casacore::TileStepper::itsTileShape
IPosition itsTileShape
Definition: TileStepper.h:277
casacore::TileStepper::clone
virtual LatticeNavigator * clone() const
Function which returns a pointer to dynamic memory of an exact copy of this instance.
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::~TileStepper
~TileStepper()
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::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::itsTrc
IPosition itsTrc
Definition: TileStepper.h:272
casacore::TileStepper::itsSubSection
LatticeIndexer itsSubSection
Definition: TileStepper.h:274
casacore::TileStepper::atStart
virtual Bool atStart() const
Function which returns "True" if the cursor is at the beginning of the Lattice, otherwise,...
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::itsStart
Bool itsStart
Definition: TileStepper.h:283
casacore::TileStepper::increment
virtual IPosition increment() const
casacore::TileStepper::operator=
TileStepper & operator=(const TileStepper &other)
Assignment (copy semantics).
casacore::TileStepper::hangOver
virtual Bool hangOver() const
Function which returns "True" if the increment/decrement operators have moved the cursor position suc...
casacore::TileStepper::reset
virtual void reset()
Function to move the cursor to the beginning of the Lattice.
casacore::TileStepper::itsCurTrc
IPosition itsCurTrc
Definition: TileStepper.h:280
casacore::TileStepper::trc
virtual IPosition trc() const
casacore::TileStepper
traverse a tiled Lattice optimally with a tile cursor
Definition: TileStepper.h:138
casacore::TileStepper::TileStepper
TileStepper()
Prevent the default constructor from being used.
casacore::LatticeNavigator
Abstract base class to steer lattice iterators.
Definition: LatticeNavigator.h:182
casacore::TileStepper::itsCurBlc
IPosition itsCurBlc
Definition: TileStepper.h:279
casacore::uInt
unsigned int uInt
Definition: aipstype.h:51
casacore::TileStepper::position
virtual IPosition position() const
Function which returns the current position of the beginning of the cursor.
casacore::TileStepper::cursorAxes
virtual IPosition cursorAxes() const
Function which returns the axes of the cursor.
casacore::TileStepper::latticeShape
virtual IPosition latticeShape() const
Functions which return the shape of the Lattice being iterated through.
casacore::TileStepper::nsteps
virtual uInt nsteps() const
Function to return the number of steps (increments & decrements) taken since construction (or since l...
casacore
this file contains all the compiler specific defines
Definition: mainpage.dox:28
casacore::LatticeNavigator::operator--
Bool operator--()
Definition: LatticeNavigator.h:358
casacore::TileStepper::itsNsteps
uInt itsNsteps
Definition: TileStepper.h:281
casacore::LatticeNavigator::operator++
Bool operator++()
Definition: LatticeNavigator.h:354
casacore::LatticeIndexer
A helper class for stepping through Lattices.
Definition: LatticeIndexer.h:108
casacore::TileStepper::itsEnd
Bool itsEnd
Definition: TileStepper.h:282
casacore::TileStepper::itsTiler
LatticeIndexer itsTiler
Definition: TileStepper.h:275
casacore::Bool
bool Bool
Define the standard types used by Casacore.
Definition: aipstype.h:42
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::itsBlc
IPosition itsBlc
Definition: TileStepper.h:271
casacore::TileStepper::endPosition
virtual IPosition endPosition() const
Function which returns the current position of the end of the cursor.
casacore::TileStepper::cursorShape
virtual IPosition cursorShape() const
Function which returns the shape of the cursor.
casacore::TileStepper::itsInc
IPosition itsInc
Definition: TileStepper.h:273
casacore::TileStepper::axisPath
virtual const IPosition & axisPath() const
Return the axis path.
casacore::TileStepper::itsTilerCursorPos
IPosition itsTilerCursorPos
Definition: TileStepper.h:276