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 
160 
161  // Assignment (copy semantics).
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.
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.
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
virtual IPosition endPosition() const
Function which returns the current position of the end of the cursor.
LatticeIndexer itsSubSection
Definition: TileStepper.h:274
IPosition itsTilerCursorPos
Definition: TileStepper.h:276
TileStepper(const IPosition &latticeShape, const IPosition &tileShape)
Construct a TileStepper by specifying the Lattice shape, a tile shape, and an optional axis path (def...
virtual IPosition increment() const
TileStepper & operator=(const TileStepper &other)
Assignment (copy semantics).
virtual IPosition cursorShape() const
Function which returns the shape of the cursor.
virtual Bool atStart() const
Function which returns "True" if the cursor is at the beginning of the Lattice, otherwise,...
virtual void reset()
Function to move the cursor to the beginning of the Lattice.
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...
IPosition tileShape() const
Function which returns the shape of the "tile" the cursor will iterate through before moving onto the...
virtual Bool hangOver() const
Function which returns "True" if the increment/decrement operators have moved the cursor position suc...
virtual IPosition subLatticeShape() const
virtual Bool ok() const
Function which checks the internal data of this class for correct dimensionality and consistant value...
virtual const IPosition & axisPath() const
Return the axis path.
virtual IPosition cursorAxes() const
Function which returns the axes of the cursor.
virtual LatticeNavigator * clone() const
Function which returns a pointer to dynamic memory of an exact copy of this instance.
TileStepper()
Prevent the default constructor from being used.
virtual IPosition position() const
Function which returns the current position of the beginning of the cursor.
LatticeIndexer itsTiler
Definition: TileStepper.h:275
virtual void subSection(const IPosition &blc, const IPosition &trc, const IPosition &inc)
virtual IPosition trc() const
virtual uInt nsteps() const
Function to return the number of steps (increments & decrements) taken since construction (or since l...
virtual void subSection(const IPosition &blc, const IPosition &trc)
Functions to specify a "section" of the Lattice to step over.
virtual IPosition latticeShape() const
Functions which return the shape of the Lattice being iterated through.
virtual Bool operator++(int)
Increment operator (postfix or prefix version) - move the cursor forward one step.
virtual IPosition blc() const
Return the bottom left hand corner (blc), top right corner (trc) or step size (increment) used by the...
virtual Bool atEnd() const
Function which returns "True" if an attempt has been made to increment the cursor beyond the end of t...
TileStepper(const TileStepper &other)
Copy constructor (copy semantics).
TileStepper(const IPosition &latticeShape, const IPosition &tileShape, const IPosition &axisPath)
virtual Bool operator--(int)
Decrement operator (postfix or prefix version) - move the cursor backwards one step.
this file contains all the compiler specific defines
Definition: mainpage.dox:28
unsigned int uInt
Definition: aipstype.h:51
bool Bool
Define the standard types used by Casacore.
Definition: aipstype.h:42