casacore
LatticeNavigator.h
Go to the documentation of this file.
1 //# LatticeNavigator.h: Abstract base class to steer lattice iterators
2 //# Copyright (C) 1994,1995,1996,1997,1998,1999
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_LATTICENAVIGATOR_H
29 #define LATTICES_LATTICENAVIGATOR_H
30 
31 
32 //# Includes
33 #include <casacore/casa/aips.h>
34 
35 namespace casacore { //# NAMESPACE CASACORE - BEGIN
36 
37 //# Forward Declarations
38 class IPosition;
39 class ROTiledStManAccessor;
40 
41 
42 // <summary>
43 // Abstract base class to steer lattice iterators.
44 // </summary>
45 
46 // <use visibility=local>
47 
48 // <reviewed reviewer="Peter Barnes" date="1999/10/30" tests="tLatticeStepper.cc">
49 // </reviewed>
50 
51 // <prerequisite>
52 // <li> <linkto class=LatticeIterator>LatticeIterator</linkto>
53 // <li> <linkto class=Lattice>Lattice</linkto>
54 // </prerequisite>
55 
56 // <etymology>
57 // Lattice iteration can proceed with a number of different strategies -
58 // all of which answer the question: where do I go from here?
59 // You could travel through by making calculations on the lattice subscripts,
60 // viewing ascending planes in an image cube, for example, or you could
61 // travel through by making calculations on the data, viewing small
62 // subimage planes in order of descending brightness over the whole cube.
63 // Concrete classes derived from this base class implement different
64 // navigation strategies - but they are all "navigators".
65 // </etymology>
66 
67 // <synopsis>
68 // This abstract base class defines the interface for objects which generate
69 // positions for LatticeIterators. This position is not just a single point
70 // in the Lattice but a region or "cursor" that is moved through the
71 // Lattice. The LatticeIterator classes actually retrieve the data in the
72 // cursor from the Lattice. The class decribed here (and those derived from it)
73 // are responsible for moving the cursor to the next position and determining
74 // its shape.
75 //
76 // There may eventually be a large collection of tools for traversing
77 // Lattices. At this writing (December 1999) there are three concrete
78 // classes derived from LatticeNavigator:
79 // <linkto class="LatticeStepper">LatticeStepper</linkto>,
80 // <linkto class="TiledLineStepper">TiledLineStepper</linkto>, and
81 // <linkto class="TileStepper">TileStepper</linkto>.
82 //
83 // The <src>LatticeStepper</src> class moves through a Lattice in fixed
84 // steps defined by the user specified cursor, incrementing to the next
85 // portion of the Lattice with each step, and wrapping around axes as
86 // needed. Other position generators might follow the brightest pixel,
87 // traverse a number of predefined subregions, or change size automatically
88 // when near the edges.
89 //
90 // The <src>TiledLineStepper</src> class moves a Vector cursor through a
91 // Lattice, until all the lines in the set of tiles along the specified
92 // axis have been exhausted. It then moves to the next set of tiles. This is
93 // a memory-efficient way to move a Vector cursor through a Lattice.
94 //
95 // The most important member functions of this class are those which move
96 // the cursor to the next position. These are the <src>operator++</src> and
97 // <src>operator--</src> member functions, (in postfix and prefix forms).
98 //
99 // The cursor shape need not be constant as it moves through the Lattice,
100 // but may change depending on its current position. For the LatticeStepper
101 // and TiledLineStepper classes , however, the cursor shape is constant
102 // as it steps through the Lattice.
103 //
104 // It is not possible to randomly move the cursor to an arbitrary place in
105 // the Lattice, although the cursor can be moved to the starting position at
106 // any time using the <src>reset</src> member function.
107 //
108 // The position of the cursor can be queried at any time using the
109 // <src>position</src> member function. This gives the position of the
110 // bottom left hand corner of the cursor. The position of the top right hand
111 // corner of the cursor is obtained using the <src>endPosition</src> member
112 // function, and the current cursor shape is obtained using the
113 // <src>cursorShape</src> member function. Note that the endPosition
114 // does not take an overhang into account.
115 //
116 // It is possible that for some positions of the cursor, part of it will
117 // "hang over" the edge of the Lattice. When this occurs the
118 // <src>hangOver</src> member function will return True. This will occur
119 // with a LatticeStepper if the Lattice shape is not a multiple of the
120 // cursor shape. Hangover cannot occur with the TiledLineStepper as the length
121 // of the Vector cursor is defined by the Lattice Shape.
122 //
123 // It may be possible (depending on the concrete LatticeNavigator actually
124 // used) to specify that only a region of the Lattice (defined by a top
125 // right hand corner, bottom left hand corner, and step increment) be
126 // traversed by the LatticeNavigator. This is done using the
127 // <src>subSection</src> member function. At any time the region can be
128 // redefined by calling the <src>subSection</src> function again. This
129 // replaces the previously defined region with the new one.
130 //
131 // Using the subSection function always sets the cursor position to the
132 // origin of the currently defined sub-lattice. This is a backdoor way to
133 // move the cursor to random locations in the Lattice.
134 //
135 // It is an error to define a sub-lattice that is bigger than the current
136 // Lattice. If using a LatticeStepper it may also be necessary to resize the
137 // cursor (using the <src>setCursorShape</src> member function) prior to
138 // calling the subSection function as the cursor cannot be bigger than the
139 // sub-Lattice on any axis.
140 //
141 // The arguments (<src>trc</src>, <src>blc</src> and <src>inc</src>)
142 // to the <src>subSection</src> function are always
143 // relative to the main Lattice. This is also true of the <src>position</src>
144 // and <src>endPosition</src> functions. To get the position of the cursor
145 // relative to the currently defined sub-Lattice use the
146 // <src>relativePosition</src> and <src>relativeEndPosition</src> member
147 // functions.
148 //
149 // Many of the LatticeIterator member functions are directly forwarded to
150 // virtual functions of this class, and classes derived from it. For
151 // instance, LatticeIterator<T>::operator++() calls
152 // LatticeIterInterface->operator++() which calls
153 // LatticeNavigator->operator++() which might resolve to
154 // LatticeStepper->operator++(). Other functions like this are documented in
155 // the <linkto class="LatticeIterator">LatticeIterator</linkto> class.
156 // </synopsis>
157 
158 // <example>
159 // See the examples in the
160 // <linkto class="LatticeStepper">LatticeStepper</linkto> class, the
161 // <linkto class="TiledLineStepper">TiledLineStepper</linkto> class, and the
162 // <linkto class="TileStepper">TileStepper</linkto> class.
163 // </example>
164 //
165 // <motivation>
166 // Iterator classes are quite common in C++. What's novel about the design
167 // which includes this class is the separation of iterator mechanisms from
168 // traversal strategy. The iterator provides a lot of functionality: it
169 // provides a cursor, damage notification and tracking, and reading and
170 // writing to the underlying data structure. Traversal strategies can and
171 // should be isolated from these things. Because every LatticeIterator
172 // uses a Navigator, it gets the benefits of a derived concrete navigator
173 // without getting involved in its mechanism.
174 // </motivation>
175 //
176 // <todo asof="1997/31/01">
177 // <li> Think about how to implement Navigators which can traverse
178 // arbitrary shaped regions.
179 // </todo>
180 
181 
183 public:
184  // Default constructor.
186  {;}
187 
188  // Copy constructor.
190  {;}
191 
192  // Assignment.
194  { return *this; }
195 
196  // A virtual destructor. A virtual is needed to ensure that derived
197  // classes accessed through pointers to a LatticeNavigator will scope
198  // their destructor to the derived class destructor.
199  virtual ~LatticeNavigator();
200 
201  // Increment operator - increment the cursor to the next position. The
202  // implementation of the prefix operator calls the postfix one.
203  // <group>
204  virtual Bool operator++(int) = 0;
205  Bool operator++();
206  // </group>
207 
208  // Decrement operator - decrement the cursor to the previous position. The
209  // implementation of the prefix operator calls the postfix one.
210  // <group>
211  virtual Bool operator--(int) = 0;
212  Bool operator--();
213  // </group>
214 
215  // Function to reset the cursor to the beginning of the Lattice and
216  // reset the number of steps taken to zero.
217  virtual void reset() = 0;
218 
219  // Function which returns "True" if the cursor is at the beginning of the
220  // Lattice, otherwise, returns "False"
221  virtual Bool atStart() const = 0;
222 
223  // Function which returns "True" if an attempt has been made to increment
224  // the cursor beyond the end of the Lattice.
225  virtual Bool atEnd() const = 0;
226 
227  // Function to return the number of steps (increments or decrements) taken
228  // since construction (or since last reset). This is a running count of
229  // all cursor movement since doing N increments followed by N decrements
230  // does not necessarily put the cursor back at the origin of the Lattice.
231  virtual uInt nsteps() const = 0;
232 
233  // Functions which return the current position of the beginning of the
234  // cursor. The <src>position</src> function is relative to the origin in
235  // the main Lattice and the <src>relativePosition</src> function is
236  // relative to the origin and increment used in the sub-Lattice (defined
237  // using the <src>subSection</src> function).
238  // The returned IPosition will have the same number of axes as
239  // the underlying Lattice.
240  // <br>The default implementation of the <src>relativePosition</src>
241  // function returns <src>(position() - blc()) / increment()</src>.
242  // <group>
243  virtual IPosition position() const = 0;
244  virtual IPosition relativePosition() const;
245  // </group>
246 
247  // Functions which return the current position of the end of the
248  // cursor. The <src>endPosition</src> function is relative to the origin in
249  // the main Lattice and the <src>relativeEndPosition</src> function is
250  // relative to the origin and increment used in the sub-Lattice (defined
251  // using the <src>subSection</src> function).
252  // The returned IPosition will have the same number of axes as
253  // the underlying Lattice.
254  // <note role=caution> It returns the end position in the lattice and
255  // does not take overhang into account. </note>
256  // <br>The default implementation of the <src>relativeEndPosition</src>
257  // function returns <src>(endPosition() - blc()) / increment()</src>.
258  // <group>
259  virtual IPosition endPosition() const = 0;
261  // </group>
262 
263  // Functions which return the shape of the Lattice being iterated
264  // through. <src>latticeShape</src> always returns the shape of the main
265  // Lattice while <src>subLatticeShape</src> returns the shape of any
266  // sub-Lattice defined using the <src>subSection</src> function. In the
267  // default implementation of this class it is not possible to use the
268  // <src>subsection</src> function (it throws an exception) so the default
269  // implementation of the <src>subLatticeShape</src> function calls the
270  // <src>latticeShape</src> function. The returned IPosition will always
271  // have the same number of axes as the underlying Lattice.
272  // <group>
273  virtual IPosition latticeShape() const = 0;
274  virtual IPosition subLatticeShape() const;
275  // </group>
276 
277  // Function which returns the current shape of the cursor which is
278  // iterating through the Lattice. The returned IPosition will have the
279  // same number of axes as the underlying Lattice.
280  virtual IPosition cursorShape() const = 0;
281 
282  // Function which returns the axes of the cursor.
283  // These are the axes which should not be removed by the
284  // iterator functions <src>vectorCursor()</src>, etc..
285  virtual IPosition cursorAxes() const = 0;
286 
287  // Function which returns "True" if the increment/decrement operators have
288  // moved the cursor position such that part of the cursor is hanging over
289  // the edge of the Lattice. This function may always return a value of
290  // "False" for some iteration methods that do not move the cursor past the
291  // Lattice boundaries.
292  virtual Bool hangOver() const = 0;
293 
294  // Functions which return the "bottom left corner" and the "top right corner"
295  // of the cursor that does not hangover. Use these functions to extract the
296  // valid part of the cursor when the hangover member function is true. If
297  // there is no hangover then hangOverBLC returns an IPosition of zero and
298  // hangOverTRC() returns the cursorShape - 1;
299  // <group>
300  virtual IPosition hangOverBlc() const;
301  virtual IPosition hangOverTrc() const;
302  // </group>
303 
304 
305  // Function to specify a "section" of the Lattice to Navigate over. A
306  // section is defined in terms of the Bottom Left Corner (blc), Top Right
307  // Corner (trc), and step size (inc), on ALL of its axes, including
308  // degenerate axes. The step size defaults to one if not specified.
309  // In the default implementation of this class subsectioning is not
310  // supported and using the <src>subsection</src> function will throw an
311  // exception (AipsError).
312  // <group>
313  virtual void subSection(const IPosition& blc, const IPosition& trc);
314  virtual void subSection(const IPosition& blc, const IPosition& trc,
315  const IPosition& inc);
316  // </group>
317 
318  // Return the bottom left hand corner (blc), top right corner (trc) or
319  // step size (increment) used by the current sub-Lattice. In the default
320  // implementation of this class sub-sectioning is not supported and these
321  // functions will always return blc=0, trc=latticeShape-1, increment=1,
322  // ie. the entire Lattice.
323  // <group>
324  virtual IPosition blc() const;
325  virtual IPosition trc() const;
326  virtual IPosition increment() const;
327  // </group>
328 
329  // Return the axis path.
330  // See <linkto class=LatticeStepper>LatticeStepper</linkto> for a
331  // description and examples.
332  virtual const IPosition& axisPath() const = 0;
333 
334  // Calculate the cache size (in tiles) for this type of access to a lattice
335  // in the given row of the tiled hypercube.
336  // A zero bucket size indicates that the data are not tiled, but in memory.
337  // Then a cache size of 0 is returned.
338  virtual uInt calcCacheSize (const IPosition& cubeShape,
339  const IPosition& tileShape,
340  uInt maxCacheSize, uInt bucketSize) const = 0;
341 
342  // Function which returns a pointer to dynamic memory of an exact copy
343  // of this LatticeNavigator. It is the responsibility of the caller to
344  // release this memory.
345  virtual LatticeNavigator* clone() const = 0;
346 
347  // Function which checks the internals of the class for consistency.
348  // Returns True if everything is fine otherwise returns False. The default
349  // implementation always returns True.
350  virtual Bool ok() const;
351 };
352 
353 
355 {
356  return operator++(0);
357 }
359 {
360  return operator--(0);
361 }
362 
363 
364 
365 } //# NAMESPACE CASACORE - END
366 
367 #endif
virtual LatticeNavigator * clone() const =0
Function which returns a pointer to dynamic memory of an exact copy of this LatticeNavigator.
virtual IPosition hangOverTrc() const
virtual IPosition cursorAxes() const =0
Function which returns the axes of the cursor.
virtual IPosition cursorShape() const =0
Function which returns the current shape of the cursor which is iterating through the Lattice.
virtual IPosition relativeEndPosition() const
virtual Bool hangOver() const =0
Function which returns "True" if the increment/decrement operators have moved the cursor position suc...
virtual IPosition blc() const
Return the bottom left hand corner (blc), top right corner (trc) or step size (increment) used by the...
virtual Bool operator--(int)=0
Decrement operator - decrement the cursor to the previous position.
virtual IPosition endPosition() const =0
Functions which return the current position of the end of the cursor.
virtual IPosition subLatticeShape() const
virtual IPosition hangOverBlc() const
Functions which return the "bottom left corner" and the "top right corner" of the cursor that does no...
virtual IPosition trc() const
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...
virtual Bool atStart() const =0
Function which returns "True" if the cursor is at the beginning of the Lattice, otherwise,...
virtual ~LatticeNavigator()
A virtual destructor.
virtual IPosition increment() const
virtual IPosition latticeShape() const =0
Functions which return the shape of the Lattice being iterated through.
virtual IPosition relativePosition() const
virtual void reset()=0
Function to reset the cursor to the beginning of the Lattice and reset the number of steps taken to z...
virtual void subSection(const IPosition &blc, const IPosition &trc)
Function to specify a "section" of the Lattice to Navigate over.
LatticeNavigator(const LatticeNavigator &)
Copy constructor.
virtual void subSection(const IPosition &blc, const IPosition &trc, const IPosition &inc)
virtual IPosition position() const =0
Functions which return the current position of the beginning of the cursor.
LatticeNavigator & operator=(const LatticeNavigator &)
Assignment.
LatticeNavigator()
Default constructor.
virtual const IPosition & axisPath() const =0
Return the axis path.
virtual Bool atEnd() const =0
Function which returns "True" if an attempt has been made to increment the cursor beyond the end of t...
virtual Bool ok() const
Function which checks the internals of the class for consistency.
virtual uInt nsteps() const =0
Function to return the number of steps (increments or decrements) taken since construction (or since ...
virtual Bool operator++(int)=0
Increment operator - increment the cursor to the next position.
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