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
casacore::LatticeNavigator::nsteps
virtual uInt nsteps() const =0
Function to return the number of steps (increments or decrements) taken since construction (or since ...
casacore::LatticeNavigator::trc
virtual IPosition trc() const
casacore::IPosition
Definition: IPosition.h:120
casacore::LatticeNavigator::blc
virtual IPosition blc() const
Return the bottom left hand corner (blc), top right corner (trc) or step size (increment) used by the...
casacore::LatticeNavigator::LatticeNavigator
LatticeNavigator()
Default constructor.
Definition: LatticeNavigator.h:185
casacore::LatticeNavigator::operator++
virtual Bool operator++(int)=0
Increment operator - increment the cursor to the next position.
casacore::LatticeNavigator::axisPath
virtual const IPosition & axisPath() const =0
Return the axis path.
casacore::LatticeNavigator::calcCacheSize
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...
casacore::LatticeNavigator::cursorShape
virtual IPosition cursorShape() const =0
Function which returns the current shape of the cursor which is iterating through the Lattice.
casacore::LatticeNavigator::clone
virtual LatticeNavigator * clone() const =0
Function which returns a pointer to dynamic memory of an exact copy of this LatticeNavigator.
casacore::LatticeNavigator::operator--
virtual Bool operator--(int)=0
Decrement operator - decrement the cursor to the previous position.
casacore::LatticeNavigator::subSection
virtual void subSection(const IPosition &blc, const IPosition &trc, const IPosition &inc)
casacore::LatticeNavigator::latticeShape
virtual IPosition latticeShape() const =0
Functions which return the shape of the Lattice being iterated through.
casacore::LatticeNavigator
Definition: LatticeNavigator.h:182
casacore::LatticeNavigator::endPosition
virtual IPosition endPosition() const =0
Functions which return the current position of the end of the cursor.
casacore::uInt
unsigned int uInt
Definition: aipstype.h:51
casacore::LatticeNavigator::subSection
virtual void subSection(const IPosition &blc, const IPosition &trc)
Function to specify a "section" of the Lattice to Navigate over.
casacore::LatticeNavigator::position
virtual IPosition position() const =0
Functions which return the current position of the beginning of the cursor.
casacore::LatticeNavigator::relativeEndPosition
virtual IPosition relativeEndPosition() const
casacore::LatticeNavigator::increment
virtual IPosition increment() const
casacore
this file contains all the compiler specific defines
Definition: mainpage.dox:28
casacore::LatticeNavigator::operator--
Bool operator--()
Definition: LatticeNavigator.h:358
casacore::LatticeNavigator::subLatticeShape
virtual IPosition subLatticeShape() const
casacore::LatticeNavigator::operator++
Bool operator++()
Definition: LatticeNavigator.h:354
casacore::LatticeNavigator::ok
virtual Bool ok() const
Function which checks the internals of the class for consistency.
casacore::LatticeNavigator::hangOverBlc
virtual IPosition hangOverBlc() const
Functions which return the "bottom left corner" and the "top right corner" of the cursor that does no...
casacore::LatticeNavigator::~LatticeNavigator
virtual ~LatticeNavigator()
A virtual destructor.
casacore::LatticeNavigator::relativePosition
virtual IPosition relativePosition() const
casacore::LatticeNavigator::operator=
LatticeNavigator & operator=(const LatticeNavigator &)
Assignment.
Definition: LatticeNavigator.h:193
casacore::LatticeNavigator::atEnd
virtual Bool atEnd() const =0
Function which returns "True" if an attempt has been made to increment the cursor beyond the end of t...
casacore::LatticeNavigator::hangOver
virtual Bool hangOver() const =0
Function which returns "True" if the increment/decrement operators have moved the cursor position suc...
casacore::LatticeNavigator::cursorAxes
virtual IPosition cursorAxes() const =0
Function which returns the axes of the cursor.
casacore::LatticeNavigator::atStart
virtual Bool atStart() const =0
Function which returns "True" if the cursor is at the beginning of the Lattice, otherwise,...
casacore::Bool
bool Bool
Define the standard types used by Casacore.
Definition: aipstype.h:42
casacore::LatticeNavigator::hangOverTrc
virtual IPosition hangOverTrc() const
casacore::LatticeNavigator::reset
virtual void reset()=0
Function to reset the cursor to the beginning of the Lattice and reset the number of steps taken to z...
casacore::LatticeNavigator::LatticeNavigator
LatticeNavigator(const LatticeNavigator &)
Copy constructor.
Definition: LatticeNavigator.h:189