casacore
Loading...
Searching...
No Matches
Lattices.h
Go to the documentation of this file.
1//# Lattices.h: Regular N-dimensional data structures.
2//# Copyright (C) 1996,1997,1998,1999,2003
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_LATTICES_H
29#define LATTICES_LATTICES_H
30
31
32//#include <casacore/casa/Arrays/ArrayLattice.h>
33//#include <casacore/casa/Arrays/PagedArray.h>
34//#include <casacore/casa/Arrays/TempLattice.h>
35//#include <casacore/casa/Arrays/LatticeLocker.h>
36//#include <casacore/casa/Arrays/TiledShape.h>
37
38//#include <casacore/casa/Arrays/LatticeApply.h>
39//#include <casacore/casa/Arrays/LatticeIterator.h>
40//#include <casacore/casa/Arrays/LatticeStepper.h>
41//#include <casacore/casa/Arrays/TileStepper.h>
42//#include <casacore/casa/Arrays/TiledLineStepper.h>
43
44//#include <casacore/lattices/Lattices/SubLattice.h>
45
46//#include <casacore/lattices/LRegions.h>
47//#include <casacore/lattices/LEL.h>
48//#include <casacore/lattices/LatticeMath.h>
49
50namespace casacore { //# NAMESPACE CASACORE - BEGIN
51
52// <module>
53
54// <summary>
55// Regular N-dimensional data structures.
56// </summary>
57
58// <prerequisite>
59// <li> Programmers of new Lattice classes should understand Inheritance
60// <li> Users of the Lattice classes should understand Polymorphism.
61// <li> class <linkto class=IPosition>IPosition</linkto>
62// <li> class <linkto class=Array>Array</linkto>
63// </prerequisite>
64
65// <reviewed reviewer="Peter Barnes" date="1999/10/30" demos="">
66// </reviewed>
67
68// <etymology>
69// Lattice: "A regular, periodic configuration of points, particles, or
70// objects, throughout an area of a space..." (American Heritage Directory)
71// This definition matches our own: an N-dimensional arrangement of data
72// on regular orthogonal axes.
73// <p>
74// In Casacore, we have used the ability to call many things by one generic
75// name (Lattice) to create a number of classes which have different storage
76// techniques (e.g. core memory, disk, etc...). The name Lattice should
77// make the user think of a class interface (or member functions) which all
78// Lattice objects have in common. If functions require a Lattice
79// argument, the classes described here may be used interchangeably, even
80// though their actual internal workings are very different.
81// </etymology>
82
83// <synopsis>
84// The Lattice module may be broken up into a few areas:
85// <ol>
86//
87// <li> Lattices - the actual holders of lattice-like data which all share a
88// common <linkto class="Lattice">interface</linkto>. The following items
89// are all Lattices and may be used polymorphically wherever a Lattice is
90// called for.
91// <ul>
92// <li>The <linkto class="ArrayLattice">ArrayLattice</linkto> class adds
93// the interface requirements of a Lattice to a Casacore
94// <linkto class="Array">Array</linkto>. The data inside an ArrayLattice
95// are not stored on disk. This n-dimensional array class is the simplest
96// of the Lattices. Users construct the ArrayLattice with an argument
97// which is either an IPosition which describes the array shape or a
98// previously instantiated Array object that may already contain data. In
99// the former case, some Lattice operation must be done to fill the data.
100// The ArrayLattice, like all Lattices, may be iterated through with a
101// <linkto class=LatticeIterator>LatticeIterator</linkto> (see below).
102// <br>Iteration can also be done using
103// <linkto class=LatticeApply>LatticeApply</linkto> and some helper
104// classes. It makes it possible to concentrate on the algorithm.
105// <srcblock>
106// // Make an Array of shape 3x4x5
107//
108// Array<Float> simpleArray(IPosition(3,3,4,5));
109//
110// // fill it with a gradient
111//
112// for (Int k=0; k<5; k++)
113// for (Int j=0; j<4; j++)
114// for (Int i=0; i<3; i++)
115// simpleArray(IPosition(3,i,j,k)) = i+j+k;
116//
117// // use the array to create an ArrayLattice.
118//
119// ArrayLattice<Float> lattice(simpleArray);
120// </srcblock>
121//
122// <li>The <linkto class="PagedArray">PagedArray</linkto> class stores its
123// data on disk in the Table format
124// and pages it into random access memory for use. Paging is
125// used here to describe the process of getting pieces of data small
126// enough to fit into active memory even if the whole data set is much too
127// large. This class "feels" like an array but may hold very large amounts
128// of data. The paging has an added effect: all the data may be made
129// persistent, so it stays around after the application ends.
130// When you use PagedArrays - use
131// them because you need persistent data and/or paging into large data sets.
132// <br>
133// The persistence is done using a <linkto module="Tables">Table</linkto>,
134// and uses the <linkto module="Tables:TiledStMan">tiled storage
135// manager</linkto>. This means that accessing the data along any axis is
136// equally efficient (depending on the tile shape used).
137// <br>
138// A PagedArray constructor allows previously created PagedArrays to be
139// recalled from disk. Much of the time, the PagedArray will be
140// constructed with a <linkto class=TiledShape>TiledShape</linkto>
141// argument which describes the array and tile shape
142// and a Table argument for use as the place of storage. Then the
143// PagedArray may be filled using any of the access functions of Lattices
144// (like the LatticeIterator.)
145//
146// <srcblock>
147// // Create a PagedArray from a Table already existing on disk.
148//
149// PagedArray<Float> lattice(fileName);
150//
151// // Create a LatticeIterator to access the Lattice in optimal tile
152// // shaped chunks.
153//
154// LatticeIterator<Float> iter(lattice);
155//
156// // Iterate through and do something simple; here we just
157// // sum up all the values in the Lattice
158//
159// Float dSum = 0;
160// for(iter.reset(); !iter.atEnd(); iter++) {
161// dSum += sum(iter.cursor());
162// }
163// </srcblock>
164//
165// <li>The <linkto class="HDF5Lattice">HDF5Lattice</linkto> class stores its
166// data on disk in <a href="http://www.hdfgroup.org/HDF5">HDF5</a> format.
167// It works in the same way as PagedArray.
168//
169// </ul>
170//
171// <li> <linkto class="LatticeIterator">LatticeIterator</linkto> - the
172// object which allows iteration through any Lattice's data. This comes in
173// two types: the <src>RO_LatticeIterator</src> which should be used if you
174// are not going to change the Lattice's data, and the
175// <src>LatticeIterator</src> if you need to change the data in the Lattice.
176// <br>Note that iteration can also be done using
177// <linkto class=LatticeApply>LatticeApply</linkto> and some helper
178// classes. It makes it possible to concentrate on the algorithm.
179// <ul>
180// <li> The <linkto class="RO_LatticeIterator">RO_LatticeIterator</linkto>
181// class name reflects its role as a means of iterating a "Read-Only" array
182// (hereafter refered to as a "cursor") through a Lattice based object,
183// from beginning to end. Think of a window into the Lattice that moves to
184// a new location when requested. The Lattice doesn't change but you may
185// see all or part of its data as the cursor "window" moves around. This
186// class allows optimized read-only iteration through any instance of a
187// class derived from Lattice. The cursor's shape is defined by the user and
188// moved through the Lattice in an orderly fashion also defined by the user.
189// Since the cursor is "read-only" it can only be used to "get" the data
190// out of the Lattice. RO_LatticeIterators are constructed with the Lattice
191// to be iterated as the first argument. The optional second constructor
192// argument is either an IPosition which defines the shape of the cursor
193// or a <linkto class=LatticeNavigator>LatticeNavigator</linkto> argument.
194// The IPosition argument cause the iterator
195// to move the cursor in a simple pattern; the cursor starts at the Lattice's
196// origin and moves in the direction of the x-axis, then the y-axis, then
197// the z-axis, etc.. If a LatticeNavigator argument is given, more
198// control over the cursor shape and path are available. If no second
199// argument is given, the optimal
200// <linkto class=TileStepper>TileStepper</linkto> navigator will be used.
201// <srcblock>
202// // simple route - define a cursor shape that is the xy plane of our
203// lattice.
204//
205// IPosition cursorShape(2, lattice.shape()(0), lattice.shape()(1));
206// LatticeIterator<Float> iter(lattice, cursorShape);
207// for (iter.reset(); !iter.atEnd(); iter++) {
208// minMax(iter.cursor(), min, max);
209// }
210// </srcblock>
211//
212// <li> The <linkto class="LatticeIterator">LatticeIterator</linkto> class
213// name reflects its role as a means of iterating a read and write cursor
214// through a Lattice based object. Not only does the cursor allow you to
215// inspect the Lattice data but you may also change the Lattice via
216// operations on the cursor. This class provides optimized read and write
217// iteration through any class derived from Lattice. The technique is
218// identical to the RO_LatticeIterator. But the cursor, in this case, is
219// a reference back to the data in the Lattice. This means that changes
220// made to the cursor propagate back to the Lattice. This is especially
221// useful for the PagedArray and PagedImage classes. These two classes
222// are constructed empty and need iteration to fill in the Lattice data.
223// <srcblock>
224// // make an empty PagedArray and fill it. The Table that stores the
225// // PagedArray is deleted when the PagedArray goes out of scope
226//
227// PagedArray<Float> lattice(IPosition(4,100,200,300,50));
228// LatticeIterator<Float> iter(lattice, IPosition(2, 100, 200));
229//
230// // fill each plane with the "distance" of the iterator from the origin
231//
232// for(iter.reset();!iter.atEnd(); iter++) {
233// iter.woCursor() = iter.nsteps();
234// }
235// </srcblock>
236// </ul>
237//
238// <li> LatticeNavigators - the objects which define the method and path used
239// by a LatticeIterator to move the cursor through a Lattice. Many
240// different paths are possible. We leave it you to choose the
241// <linkto class=LatticeNavigator>LatticeNavigator</linkto>
242// (method and path) when using a LatticeIterator.
243// <ul>
244// <li> The <linkto class="LatticeStepper">LatticeStepper</linkto> class
245// is used to define the steps which the cursor takes during its path
246// through the Lattice. Every element of the Lattice will be covered,
247// starting at the origin and ending at the "top right corner." This
248// class provides the information needed by a LatticeIterator to do
249// non-standard movements of the cursor during iteration. The shape of
250// the cursor is specified by the second IPosition argument of the
251// LatticeStepper. The order of the axis is important. An IPosition(1,5)
252// is a five element vector along the x-axis. An IPosition(3,1,1,5) is a
253// five element vector along the z-axis. The degenerate axes (axes with
254// lengths of one) act as place holders. The third argument in the
255// LatticeStepper constructor is the "orientation" IPosition. This
256// describes the order of the axis for the cursor to follow. Again, we
257// treat the elements, in order, of the IPosition as the designators of
258// the appropriate axis. The zeroth element indicates which axis is the
259// fastest moving, the first element indicates which axis is the second
260// fastest moving etc. eg. The IPosition(3,2,0,1) says the LatticeIterator
261// should start with the z-axis, next follow the x-axis, and finish with
262// the y-axis. A single element cursor would thus move through a cube of
263// dimension(x,y,z) from (0,0,0) up the z-axis until reaching the maximum
264// (0,0,z-1) and then start on (1,0,0) and move to (1,0,z-1), etc.
265// <srcblock>
266// // The shape of our Lattice - a 4 dimensional image of shape (x,y,z,t) -
267// // and the shape of the cursor
268//
269// IPosition latticeShape(image.shape());
270// IPosition cursorShape(3, lattticeShape(0), 1, latticeShape(2));
271//
272// // Define the path the cursor should follow, we list x and z first, even though
273// // no iterations will be done along those axes since the cursor is an
274// // integral subshape of the Lattice. The cursor will move along the y-axis
275// // and then increment the t-axis. The construct the Navigator and Iterator
276//
277// IPosition order(4,0,2,1,3);
278// LatticeStepper nav(latticeShape, cursorShape, order);
279// LatticeIterator<Float> iter(image, nav);
280// </srcblock>
281//
282// <li>
283// The <linkto class="TiledLineStepper">TiledLineStepper</linkto> class
284// allows you to iterate through a Lattice with a Vector cursor.
285// However, it steps through the Lattice in an order which is
286// optimum with regard to the I/O of the tiles with which the Lattice is
287// constructed.
288//
289// <srcblock>
290//
291// // Set up a TiledLineStepper to return profiles along the specified
292// // axis from a PagedArray (not all Lattices have the tileShape member
293// // function). Then create the iterator as well.
294//
295// TiledLineStepper nav(lattice.shape(), lattice.tileShape(), axis);
296// LatticeIterator<Complex> nav(lattice, nav);
297// </srcblock>
298//
299// <li>
300// The <linkto class="TileStepper">TileStepper</linkto> class
301// allows you to iterate through a Lattice in the optimum way.
302// It steps through the lattice tile by tile minimizing I/O and memory usage.
303// It is very well suited for pixel based operations.
304// However, its iteration order is such that it cannot be used for
305// a certain subset of pixels (e.g. a vector) is needed.
306// <br>This navigator is the default when no navigator is given when
307// constructing a (RO_)LatticeIterator.
308//
309// </ul>
310//
311// <li> <linkto class="MaskedLattice">MaskedLattice</linkto> - a
312// Lattice with a mask. It is an abstract base class for
313// various types of MaskedLattices. A MaskedLattice does not need
314// to contain a mask (see e.g. SubLattice below), although the user
315// can always ask for the mask. The function <src>isMasked()</src>
316// tells if there is really a mask. If not, users could take
317// advantage by shortcutting some code for better performance.
318// I.e. a function can test if a the MaskedLattice is really masked
319// and can take a special route if not.
320// Of course, doing that requires more coding, so it should only
321// be done where performance is a real issue.
322// <ul>
323// <li> A <linkto class="SubLattice">SubLattice</linkto> represents
324// a rectangular subset of a Lattice. The SubLattice can be a simple
325// box, but it can also be a circle, polygon, etc.
326// In the latter case the SubLattice contains a mask
327// telling which pixels in the bounding box actually belong to the
328// circle or polygon. In the case of a box there is no mask, because
329// there is no need to (because a box is already rectangular).
330// <br> A SubLattice can be constructed from any Lattice and a
331// <linkto class=LatticeRegion>LatticeRegion</linkto> telling which
332// part to take from the Lattice.
333// If the SubLattice is constructed from a <src>const Lattice</src>,
334// the SubLattice is not writable. Otherwise it is writable if the
335// lattice is writable.
336// <p>
337// There is a rich variety of <linkto class=LCRegion>region</linkto>
338// classes which can be used to define a LatticeRegion in pixel coordinates.
339// They are described in module
340// <a href="group__LRegions__module.html">LRegions</a>.
341//
342// <li> Module <a href="group__LEL__module.html">LEL</a> contains classes to
343// form a mathematical expression of lattices. All standard operators, regions,
344// and many, many <linkto class=LatticeExprNode>functions</linkto>
345// can be used in an expression.
346// </ul>
347//
348// <li> <linkto class=LatticeLocker>LatticeLocker</linkto>
349// can be used to acquire a (user) lock on a lattice.
350// The lock can be a read or write lock.
351// The destructor releases the lock when needed.
352// <br>Lattices on disk can be used (read and write) by multiple processes.
353// The Table locking/synchronization mechanism takes care that sharing
354// such a lattice is done in an orderly way.
355// Usually the default locking mechanism is sufficient.
356// LatticeLocker is useful when finer locking control is needed for a
357// disk-based lattice.
358//
359// <note role=warning> The following are listed for low-level programmers.
360// Lattice users need not understand them.</note> The Lattice directory
361// contains several files relevant only to implementation.
362//
363// <ul>
364// <li> <linkto class="LatticeBase">LatticeBase</linkto> - a non-templated
365// abstract base class defining the type-independent interface to classes
366// which must act as Lattices do.
367// <li> <linkto class="Lattice">Lattice</linkto> - a templated
368// abstract base class (derived from LatticeBase)
369// defining the interface to classes which must act as Lattices do.
370// The user simply publicly inherits from Lattice and defines the member
371// functions declared as pure abstract in the Lattice header file.
372// <li> The <linkto class="LatticeNavigator">LatticeNavigator</linkto>
373// class name defines the interface used for navigating through a Lattice
374// by iteration. This class is an abstract base. Classes derived from
375// this (currently
376// <linkto class="LatticeStepper">LatticeStepper</linkto>,
377// <linkto class="TiledLineStepper">TiledLineStepper</linkto>, and
378// <linkto class="TileStepper">TileStepper</linkto>) must
379// define the path the iterator cursor follows, the size of the movement
380// of the cursor with each iteration, and the behaviour of that cursor
381// shape as it moves through a Lattice.
382// <li> <linkto class="LatticeIndexer">LatticeIndexer</linkto> - this
383// class contains the currently defined Lattice and sub-Lattice shape. It
384// is used only by navigator classes as it contains
385// member functions for moving a cursor through a defined sub-Lattice.
386// <li> The
387// <linkto class="LatticeIterInterface">LatticeIterInterface</linkto>
388// class defines the interface for a specific Lattice's iterator. This
389// class is a base class with a default iterator implementation.
390// Lattice based classes may need to derive an iterator from
391// LatticeIterInterface to optimize for the LatticeIterator
392// internals which impact upon the new Lattice.
393// <li> <linkto class="PagedArrIter">PagedArrIter</linkto> - this class is
394// the PagedArray's optimized method of iterating. This class is a
395// "letter" utilized within the LatticeIterator "envelope" and cannot
396// be instantiated by any user.
397// <li> <linkto class="LCRegion">LCRegion</linkto> - this class is the
398// (abstract) base class for regions in pixel coordinates.
399// </ul>
400// </ol>
401// </synopsis>
402
403// <motivation>
404// Lattices allow the various holders of data to assume a general method
405// of treatment; by making interfaces in terms of the Lattice class,
406// the programmer can polymorphically operate on objects derived from the
407// Lattice class.
408// </motivation>
409
410// <todo asof="1998/10/10">
411// <li> Make MaskedIterator class?
412// </todo>
413
414// </module>
415
416
417} //# NAMESPACE CASACORE - END
418
419#endif
this file contains all the compiler specific defines
Definition mainpage.dox:28