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
36namespace 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{
110public:
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
230private:
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}
243inline const IPosition& LatticeIndexer::shape() const
244{
245 return itsShape;
246}
248{
249 return itsAxisInc;
250}
252{
253 return itsOffset;
254}
256{
257 return itsNdim;
258}
259inline 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.
LatticeIndexer & operator=(const LatticeIndexer &other)
The assignment operator uses copy semantics.
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.
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