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
38namespace 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{
140public:
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
266private:
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
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
TileStepper & operator=(const TileStepper &other)
Assignment (copy semantics).
virtual Bool ok() const
Function which checks the internal data of this class for correct dimensionality and consistant value...
virtual IPosition cursorAxes() const
Function which returns the axes of the cursor.
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 LatticeNavigator * clone() const
Function which returns a pointer to dynamic memory of an exact copy of this instance.
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...
virtual const IPosition & axisPath() const
Return the axis path.
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