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