casacore
LatticeIndexer.h
Go to the documentation of this file.
1 //# LatticeIndexer.h: A helper class for stepping through Lattices
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_LATTICEINDEXER_H
29 #define LATTICES_LATTICEINDEXER_H
30 
31 //# Includes
32 #include <casacore/casa/aips.h>
33 #include <casacore/casa/Arrays/IPosition.h>
34 
35 
36 namespace casacore { //# NAMESPACE CASACORE - BEGIN
37 
38 // <summary>
39 // A helper class for stepping through Lattices.
40 // </summary>
41 
42 // <use visibility=local>
43 
44 // <reviewed reviewer="Peter Barnes" date="1999/10/30" tests="tLatticeIndexer">
45 // </reviewed>
46 
47 // <prerequisite>
48 // <li> <linkto class="Lattice"> Lattice </linkto>
49 // <li> <linkto class="IPosition"> IPosition </linkto>
50 // </prerequisite>
51 
52 // <etymology>
53 // This class does various calculations involved with indexing in
54 // Lattices. LatticeIndexer is not a good name, but it is
55 // better than the previous name of LatticeLayout.
56 // </etymology>
57 
58 // <synopsis>
59 // A LatticeIndexer contains all the information necessary to define the
60 // shape of a Lattice or sub-Lattice. It is currently a repository of
61 // functions that provide indexing calculations.
62 // <p>
63 // A sub-Lattice is a section of a Lattice defined by a bottom left corner
64 // (blc), a top right corner (trc), and a step size or increment on each
65 // axis. The blc and trc pixels will always be included in the sub-Lattice
66 // if the step increment is one. If the step increment is greater than one,
67 // the pixel in top right corner may not be included in the sub-Lattice.
68 // <p>
69 // This class knows the shape of the parent Lattice (including all
70 // degenerate axes), and allows the user to specify a sub-Lattice that is
71 // embedded in the parent Lattice. The default sub-Lattice, if none is
72 // specified, is one identical in shape to the main Lattice.
73 // <p>
74 // A sub-Lattice can be defined on the Lattice by specifying a trc, blc,
75 // and step increment using the <src>subSection</src> function, or the
76 // appropriate constructor. A sub-Lattice must be smaller than (or the same
77 // size as) the Lattice that it is derived from. A sub-Lattice can be further
78 // created from an already existing sub-Lattice eg.
79 // <br>
80 // If we have a 128 by 128 Lattice, we can specify the centre quarter by
81 // using blc=[32,32] and trc=[95,95]. Then specifying a sub-Lattice of
82 // blc=[0,0] and trc = [31,31] results in a sub-Lattice that has a blc
83 // of [32,32] and trc of [63,63] with respect to the parent Lattice.
84 // <p>
85 // The only way to increase the size of a sub-Lattice is to first revert to
86 // the parent Lattice (using the <src>fullSize</src> function) and then
87 // generate the new, bigger sub-Lattice.
88 // <p>
89 // Indexing calculations (eg. the <src>tiledCursorMove</src> or the
90 // <src>isInside</src> function) are performed on the specified sub-Lattice.
91 // <p>
92 // The role of this class is to centralise the information and functions
93 // needed to operate on sub-Lattices. It will normally be used by other
94 // Lattice classes, and is currently used by navigator classes like
95 // <linkto class="LatticeStepper">LatticeStepper</linkto>.
96 // </synopsis>
97 
98 // <motivation>
99 // The shape, structure or geometry of a lattice is quite separable from
100 // its actual contents, and the operations you can do on the contents. Also,
101 // there are operations which apply only to the layout such as subsectioning.
102 // </motivation>
103 
104 //# <todo asof="1997/01/12">
105 //# </todo>
106 
107 
109 {
110 public:
111  // Default constructor (one dimensional, unit-length instance).
113 
114  // Specify the size of the Lattice. Assume a full size sub-Lattice.
115  explicit LatticeIndexer (const IPosition& shape);
116 
117  // Specify a Lattice and define a sub-Lattice within it.
119  const IPosition& trc, const IPosition& inc);
120 
121  // The copy constructor uses copy semantics.
123 
125 
126  // The assignment operator uses copy semantics.
128 
129  // Function to change the shape of the Lattice. Resets the sub-Lattice to
130  // fullsize.
131  void resize (const IPosition& newShape);
132 
133  // Returns the length of each axis (or the requested one) in the parent
134  // Lattice.
135  // <group>
136  const IPosition& fullShape() const;
137  uInt fullShape (uInt axis) const;
138  // </group>
139 
140  // Returns the length of each axis (or the requested one) in the sub-Lattice.
141  // <group>
142  const IPosition& shape() const;
143  uInt shape (uInt axis) const;
144  // </group>
145 
146  // Function to return the increments along each axis (or the requested
147  // one) of the Lattice.
148  // <group>
149  const IPosition& increment() const;
150  uInt increment (uInt axis) const;
151  // </group>
152 
153  // Function to return the offset (on a specified axis) between the
154  // sub-Lattice and the parent one.
155  // <group>
156  const IPosition& offset() const;
157  uInt offset (uInt axis) const;
158  // </group>
159 
160  // Function which returns the number of dimensions in the Lattice (or
161  // sub-Lattice).
162  uInt ndim() const;
163 
164  // Revert from a sub-Lattice description back to the main Lattice. This is
165  // the only way to "increase" the the size of the sub-Lattice used by the
166  // LatticeIndexer.
167  void fullSize();
168 
169  // Function which returns the number of elements in the sub-Lattice;
170  // this value is equal to the product of shape().
171  size_t nelements() const;
172 
173  // Function which increments (incr=True) or decrements (incr=False) the
174  // cursor position (the first IPosition argument) by a cursor shape (the
175  // second IPosition argument), tiling to the next/previous axis if
176  // necessary. The path of movement is based upon the third IPosition
177  // argument (a cursor heading) that is zero-based e.g. IPosition(3,0,2,1)
178  // implies starting movement along the x-axis, then the z-axis, and then
179  // the y-axis. Returns a value of False if the beginning/end of the
180  // sub-Lattice is reached. The cursorPosition is relative to the origin of
181  // the sub-Lattice. To get its location relative to the main Lattice use
182  // the absolutePosition() function.
183  Bool tiledCursorMove (Bool incr, IPosition& cursorPos,
184  const IPosition& cursorShape,
185  const IPosition& cursorHeading) const;
186 
187  // Function which returns a value of True if the IPosition argument
188  // is within the sub-Lattice. Returns False if the IPosition argument is
189  // outside the sub-Lattice or if the argument doesn't conform to the
190  // data members.
191  // <note role=warning> Due to zero-origins, an index argument equal to the
192  // shape of this sub-Lattice lies outside and returns False.
193  // </note>
194  Bool isInside (const IPosition& index) const;
195 
196  // Function which subsections a LatticeIndexer. The argument IPositions
197  // specify "bottom left" and "upper right" corners and axis increments
198  // (which default to one). The origins are cumulative. i.e. specifying a
199  // blc of (2,2), and then (1,1) results in the sub-Lattice having an
200  // origin at pixel (3,3) in the parent Lattice. Similarly the increment is
201  // cumulative, i.e. an increment of 2 on top of an increment of 3 results
202  // in a total increment of 6. This function can only decrease the size of
203  // the sub-Lattice (i.e. blc >= 0, and trc <= shape(), and inc >= 1). The
204  // fullSize() function should be used to revert back to the maximum
205  // possible Lattice size. Also note that the trc might not be used if an
206  // integral number of increments does not end on the trc (in which case
207  // the last position below the trc will be used).
208  // <group>
209  void subSection (const IPosition& blc, const IPosition& trc,
210  const IPosition& inc);
211  void subSection (const IPosition& blc, const IPosition& trc);
212  // </group>
213 
214  // Function which returns an IPosition in the parent Lattice given an
215  // IPostion in the sub-Lattice. Accounting is taken of any offsets and
216  // increments caused by subSectioning. No checks are made to ensure the
217  // supplied IPosition or the returned one are within the bounds of the
218  // Lattice(s).
219  IPosition absolutePosition (const IPosition& position) const;
220 
221  //# function which returns True if all the elements in this
222  //# LatticeIndexer, or LatticeIndexer subsection, are arranged contiguously,
223  //# i.e. without any gaps caused by increments or subSectioning.
224 //# Bool isContiguous() const;
225 
226  // Is this LatticeIndexer consistent, i.e. are the class invariants valid?
227  // Returns True if every thing is fine otherwise returns False
228  Bool ok() const;
229 
230 private:
231  IPosition itsFullShape; //# Size of the main-Lattice.
232  uInt itsNdim; //# Number of dimensions in the main/sub-Lattice
233  IPosition itsShape; //# Shape of the sub-Lattice
234  IPosition itsAxisInc; //# Increment along each axis of main Lattice
235  IPosition itsOffset; //# Offset between a sub-Lattice and the main one.
236 };
237 
238 
240 {
241  return itsFullShape;
242 }
243 inline const IPosition& LatticeIndexer::shape() const
244 {
245  return itsShape;
246 }
248 {
249  return itsAxisInc;
250 }
251 inline const IPosition& LatticeIndexer::offset() const
252 {
253  return itsOffset;
254 }
256 {
257  return itsNdim;
258 }
259 inline size_t LatticeIndexer::nelements() const
260 {
261  return itsShape.product();
262 }
263 
264 
265 
266 
267 } //# NAMESPACE CASACORE - END
268 
269 #endif
long long product() const
Returns 0 if nelements() == 0, otherwise it returns the product of its elements.
LatticeIndexer()
Default constructor (one dimensional, unit-length instance).
void fullSize()
Revert from a sub-Lattice description back to the main Lattice.
const IPosition & shape() const
Returns the length of each axis (or the requested one) in the sub-Lattice.
const IPosition & fullShape() const
Returns the length of each axis (or the requested one) in the parent Lattice.
Bool tiledCursorMove(Bool incr, IPosition &cursorPos, const IPosition &cursorShape, const IPosition &cursorHeading) const
Function which increments (incr=True) or decrements (incr=False) the cursor position (the first IPosi...
LatticeIndexer(const LatticeIndexer &other)
The copy constructor uses copy semantics.
void resize(const IPosition &newShape)
Function to change the shape of the Lattice.
const IPosition & offset() const
Function to return the offset (on a specified axis) between the sub-Lattice and the parent one.
LatticeIndexer(const IPosition &shape, const IPosition &blc, const IPosition &trc, const IPosition &inc)
Specify a Lattice and define a sub-Lattice within it.
uInt fullShape(uInt axis) const
size_t nelements() const
Function which returns the number of elements in the sub-Lattice; this value is equal to the product ...
uInt ndim() const
Function which returns the number of dimensions in the Lattice (or sub-Lattice).
LatticeIndexer(const IPosition &shape)
Specify the size of the Lattice.
uInt offset(uInt axis) const
IPosition absolutePosition(const IPosition &position) const
Function which returns an IPosition in the parent Lattice given an IPostion in the sub-Lattice.
void subSection(const IPosition &blc, const IPosition &trc)
const IPosition & increment() const
Function to return the increments along each axis (or the requested one) of the Lattice.
Bool isInside(const IPosition &index) const
Function which returns a value of True if the IPosition argument is within the sub-Lattice.
LatticeIndexer & operator=(const LatticeIndexer &other)
The assignment operator uses copy semantics.
void subSection(const IPosition &blc, const IPosition &trc, const IPosition &inc)
Function which subsections a LatticeIndexer.
Bool ok() const
Is this LatticeIndexer consistent, i.e.
uInt increment(uInt axis) const
uInt shape(uInt axis) const
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