File: LatticeApply.h

package info (click to toggle)
casacore 3.0.0-4
  • links: PTS, VCS
  • area: main
  • in suites: buster
  • size: 44,728 kB
  • sloc: cpp: 455,618; fortran: 16,301; ansic: 7,403; yacc: 4,547; lex: 2,327; sh: 1,679; python: 704; perl: 523; sed: 499; csh: 34; makefile: 24
file content (260 lines) | stat: -rw-r--r-- 11,007 bytes parent folder | download | duplicates (5)
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
//# LatticeApply.h: Optimally iterate through a Lattice and apply provided function object
//# Copyright (C) 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_LATTICEAPPLY_H
#define LATTICES_LATTICEAPPLY_H

//# Includes
#include <casacore/casa/aips.h>
#include <casacore/casa/Containers/Block.h>
#include <casacore/scimath/Mathematics/NumericTraits.h>

namespace casacore { //# NAMESPACE CASACORE - BEGIN

//# Forward Declarations
template <class T, class U> class TiledCollapser;
template <class T, class U> class LineCollapser;
template <class T> class Lattice;
template <class T> class MaskedLattice;
class LatticeProgress;
class IPosition;
class LatticeRegion;

// <summary>
// Optimally iterate through a Lattice and apply provided function object
// </summary>

// <use visibility=export>

// <reviewed reviewer="" date="yyyy/mm/dd" tests="" demos="">
// </reviewed>

// <prerequisite>
//   <li> <linkto class=Lattice>MaskedLattice</linkto>
//   <li> <linkto class=LineCollapser>LineCollapser</linkto>
//   <li> <linkto class=TiledCollapser>TiledCollapser</linkto>
// </prerequisite>

// <synopsis>
// This function iterates through a Lattice and applies a user given
// function object to chunks along the specified axes. Usually the
// function collapses the chunk to 1 or a few values (e.g. get min/max).
// The result of the function is written into the output Lattice(s) at the
// location of the collapsed chunk.  The output lattice(s) must be supplied
// with the correct shape. E.g. when a lattice with shape [nx,ny,nz] is
// collapsed by calculating the mean of each y-line, the output lattice
// has to have shape [nx,nz]. It is also possible to have output shape
// [nx,1,nz], [1,nx,nz], [nx,nz,1] or even e.g. [nx,1,1,1,nz].
// <p>
// By specifying a region it is possible to apply the function object
// to a subset of the lattice. Of course, the shape of the output lattice(s)
// have to match the shape of the region.
// <p>
// The iteration is done in an optimal way. To keep memory usage down,
// it caches as few tiles as possible.
// There are 2 ways to iterate.
// <ol>
// <li> For some applications an entire line is needed. An example is
// the calculation of the moment. The functions <src>lineApply</src>
// and <src>lineMultiApply</src> can be used for that purpose.
// Internally they use the
// <linkto class=TiledLineStepper>TiledLineStepper</linkto>
// navigator, so only a few tiles are kept in the cache.
// <br> One can also think of applications where an entire plane (or cube)
// is needed. This is not supported, but can be implemented when needed.
// <li> Other applications do not care how the data are traversed,
// making it possible to iterate tile by tile (which is optimal).
// An example is the calculation of the minimum, maximum, mean of
// a line, plane, etc..
// For this purpose the function <src>tiledApply</src> can be used.
// This function is faster and uses less memory than <src>lineApply</src>,
// so whenever possible this one should be used. Another advantage of
// this function is that it is possible to operate per line, plane, etc.
// or even for the entire lattice.
// </ol>
// The user has to supply a function object derived from the abstract base
// class <linkto class=LineCollapser>LineCollapser</linkto> or 
// <linkto class=TiledCollapser>TiledCollapser</linkto>, resp..
// The <src>process</src> function in these classes has to process
// the chunk of data passed in. The <src>nstepsDone</src> function
// in these classes can be used to monitor the progress.
// <p>
// The class is Doubly templated.  Ths first template type
// is for the data type you are processing.  The second type is
// for what type you want the results of the processing assigned to.
// For example, if you are computing sums of squares for statistical
// purposes, you might use higher precision (Float->Double) for this.
// No check is made that the template types are self-consistent.
// </synopsis>

// <example>
// Collapse each line in the y-direction using my collapser function object.
// <srcblock>
//    MyLineCollapser collapser;
//    PagedArray<Float> latticeIn("lattice.file");
//    IPosition shape = latticeIn.shape();
//    shape(1) = 1;
//    ArrayLattice<Double> latticeOut(shape);
//    LatticeApply<Float,Double>::lineApply (latticeOut, latticeIn, collapser, 1);
// </srcblock>
// </example>

// <motivation>
// This class makes it possible that a user can apply functions to
// a lattice in an optimal way, without having to know all the details
// of iterating through a lattice.
// </motivation>

//# <todo asof="1997/08/01">   
//#   <li> 
//# </todo>

 
template <class T, class U=T> class LatticeApply
{
public:

// This function iterates line by line through an input lattice and applies
// a user supplied function object to each line along the specified axis.
// The scalar result of the function object is written into the output
// lattice at the location of the collapsed line. The output lattice must
// be supplied with the correct shape (the shape of the supplied region).
// The default region is the entire input lattice.
// <group>
    static void lineApply (MaskedLattice<U>& latticeOut, 
			   const MaskedLattice<T>& latticeIn,
			   LineCollapser<T,U>& collapser,
			   uInt collapseAxis,
			   LatticeProgress* tellProgress = 0);
    static void lineApply (MaskedLattice<U>& latticeOut, 
			   const MaskedLattice<T>& latticeIn,
			   const LatticeRegion& region,
			   LineCollapser<T,U>& collapser,
			   uInt collapseAxis,
			   LatticeProgress* tellProgress = 0);
// </group>
    
// This function iterates line by line through an input lattice and applies
// a user supplied function object to each line along the specified axis.
// The vector result of the function object is written into the output
// lattices at the location of the collapsed line (1 value per lattice).
// The output lattices must be supplied with the correct shape (the shape
// of the supplied region).
// The default region is the entire input lattice.
// <group>
    static void lineMultiApply (PtrBlock<MaskedLattice<U>*>& latticeOut, 
				const MaskedLattice<T>& latticeIn,
				LineCollapser<T,U>& collapser,
				uInt collapseAxis,
				LatticeProgress* tellProgress = 0);

    static void lineMultiApply (PtrBlock<MaskedLattice<U>*>& latticeOut, 
				const MaskedLattice<T>& latticeIn,
				const LatticeRegion& region,
				LineCollapser<T,U>& collapser,
				uInt collapseAxis,
				LatticeProgress* tellProgress = 0);
// </group>

// This function iterates tile by tile through an input lattice and applies
// a user supplied function object to each chunk along the specified axes.
// A chunk can be a line, plane, etc. which is determined by the argument
// <src>collapseAxes</src>. E.g. IPosition(2,1,2) means planes along
// axes 1 and 2 (thus y,z planes).
// The result of the function object is written into the output
// lattice at the location of the collapsed chunk. The output lattice must
// be supplied with the correct shape (the shape of the supplied region
// plus the number of values resulting from the collapse).
// The default region is the entire input lattice.
// <group>
    static void tiledApply (MaskedLattice<U>& latticeOut,
			    const MaskedLattice<T>& latticeIn,
			    TiledCollapser<T,U>& collapser,
			    const IPosition& collapseAxes,
			    Int newOutAxis = -1,
			    LatticeProgress* tellProgress = 0);
    static void tiledApply (MaskedLattice<U>& latticeOut,
			    const MaskedLattice<T>& latticeIn,
			    const LatticeRegion& region,
			    TiledCollapser<T,U>& collapser,
			    const IPosition& collapseAxes,
			    Int newOutAxis = -1,
			    LatticeProgress* tellProgress = 0);
// </group>

// This function iterates tile by tile through an input lattice and applies
// a user supplied function object to each chunk along the specified axes.
// A chunk can be a line, plane, etc. which is determined by the argument
// <src>collapseAxes</src>. E.g. IPosition(2,1,2) means planes along
// axes 1 and 2 (thus y,z planes).
// The result of the function object is written into the output
// lattices at the location of the collapsed chunk. The output lattices must
// be supplied with the correct shape (the shape of the supplied region).
// The default region is the entire input lattice.
// <note role=warning>
// These functions are only declared, but not implemented yet.
// Thus they cannot be used yet.
// </note>
// <group>
    static void tiledMultiApply (PtrBlock<MaskedLattice<U>*>& latticeOut, 
				 const MaskedLattice<T>& latticeIn,
				 TiledCollapser<T,U>& collapser,
				 const IPosition& collapseAxes,
				 LatticeProgress* tellProgress = 0);
    static void tiledMultiApply (PtrBlock<MaskedLattice<U>*>& latticeOut, 
				 const MaskedLattice<T>& latticeIn,
				 const LatticeRegion& region,
				 TiledCollapser<T,U>& collapser,
				 const IPosition& collapseAxes,
				 LatticeProgress* tellProgress = 0);
// </group>


private:
    // Do some checks on the given arguments.
    // It returns an IPosition with the same length as shapeOut.
    // It contains a mapping of output to input axes. A value of -1
    // indicates that the axis is new (to contain the collapse result).
    // <br>Argument newOutAxis tells the output axis to store the results.
    // -1 means that the function has to find it out itself; it takes the
    // first axis with a length mismatching the corresponding input axis.
    static IPosition prepare (const IPosition& shapeIn,
			      const IPosition& shapeOut,
			      const IPosition& collapseAxes,
			      Int newOutAxis);

    static IPosition _chunkShape(
        uInt axis, const MaskedLattice<T>& latticeIn
    );
};

} //# NAMESPACE CASACORE - END

#ifndef CASACORE_NO_AUTO_TEMPLATES
#include <casacore/lattices/LatticeMath/LatticeApply.tcc>
#endif //# CASACORE_NO_AUTO_TEMPLATES
#endif