casacore
LatticeApply.h
Go to the documentation of this file.
1 //# LatticeApply.h: Optimally iterate through a Lattice and apply provided function object
2 //# Copyright (C) 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_LATTICEAPPLY_H
29 #define LATTICES_LATTICEAPPLY_H
30 
31 //# Includes
32 #include <casacore/casa/aips.h>
33 #include <casacore/casa/Containers/Block.h>
34 #include <casacore/scimath/Mathematics/NumericTraits.h>
35 
36 namespace casacore { //# NAMESPACE CASACORE - BEGIN
37 
38 //# Forward Declarations
39 template <class T, class U> class TiledCollapser;
40 template <class T, class U> class LineCollapser;
41 template <class T> class Lattice;
42 template <class T> class MaskedLattice;
43 class LatticeProgress;
44 class IPosition;
45 class LatticeRegion;
46 
47 // <summary>
48 // Optimally iterate through a Lattice and apply provided function object
49 // </summary>
50 
51 // <use visibility=export>
52 
53 // <reviewed reviewer="" date="yyyy/mm/dd" tests="" demos="">
54 // </reviewed>
55 
56 // <prerequisite>
57 // <li> <linkto class=Lattice>MaskedLattice</linkto>
58 // <li> <linkto class=LineCollapser>LineCollapser</linkto>
59 // <li> <linkto class=TiledCollapser>TiledCollapser</linkto>
60 // </prerequisite>
61 
62 // <synopsis>
63 // This function iterates through a Lattice and applies a user given
64 // function object to chunks along the specified axes. Usually the
65 // function collapses the chunk to 1 or a few values (e.g. get min/max).
66 // The result of the function is written into the output Lattice(s) at the
67 // location of the collapsed chunk. The output lattice(s) must be supplied
68 // with the correct shape. E.g. when a lattice with shape [nx,ny,nz] is
69 // collapsed by calculating the mean of each y-line, the output lattice
70 // has to have shape [nx,nz]. It is also possible to have output shape
71 // [nx,1,nz], [1,nx,nz], [nx,nz,1] or even e.g. [nx,1,1,1,nz].
72 // <p>
73 // By specifying a region it is possible to apply the function object
74 // to a subset of the lattice. Of course, the shape of the output lattice(s)
75 // have to match the shape of the region.
76 // <p>
77 // The iteration is done in an optimal way. To keep memory usage down,
78 // it caches as few tiles as possible.
79 // There are 2 ways to iterate.
80 // <ol>
81 // <li> For some applications an entire line is needed. An example is
82 // the calculation of the moment. The functions <src>lineApply</src>
83 // and <src>lineMultiApply</src> can be used for that purpose.
84 // Internally they use the
85 // <linkto class=TiledLineStepper>TiledLineStepper</linkto>
86 // navigator, so only a few tiles are kept in the cache.
87 // <br> One can also think of applications where an entire plane (or cube)
88 // is needed. This is not supported, but can be implemented when needed.
89 // <li> Other applications do not care how the data are traversed,
90 // making it possible to iterate tile by tile (which is optimal).
91 // An example is the calculation of the minimum, maximum, mean of
92 // a line, plane, etc..
93 // For this purpose the function <src>tiledApply</src> can be used.
94 // This function is faster and uses less memory than <src>lineApply</src>,
95 // so whenever possible this one should be used. Another advantage of
96 // this function is that it is possible to operate per line, plane, etc.
97 // or even for the entire lattice.
98 // </ol>
99 // The user has to supply a function object derived from the abstract base
100 // class <linkto class=LineCollapser>LineCollapser</linkto> or
101 // <linkto class=TiledCollapser>TiledCollapser</linkto>, resp..
102 // The <src>process</src> function in these classes has to process
103 // the chunk of data passed in. The <src>nstepsDone</src> function
104 // in these classes can be used to monitor the progress.
105 // <p>
106 // The class is Doubly templated. Ths first template type
107 // is for the data type you are processing. The second type is
108 // for what type you want the results of the processing assigned to.
109 // For example, if you are computing sums of squares for statistical
110 // purposes, you might use higher precision (Float->Double) for this.
111 // No check is made that the template types are self-consistent.
112 // </synopsis>
113 
114 // <example>
115 // Collapse each line in the y-direction using my collapser function object.
116 // <srcblock>
117 // MyLineCollapser collapser;
118 // PagedArray<Float> latticeIn("lattice.file");
119 // IPosition shape = latticeIn.shape();
120 // shape(1) = 1;
121 // ArrayLattice<Double> latticeOut(shape);
122 // LatticeApply<Float,Double>::lineApply (latticeOut, latticeIn, collapser, 1);
123 // </srcblock>
124 // </example>
125 
126 // <motivation>
127 // This class makes it possible that a user can apply functions to
128 // a lattice in an optimal way, without having to know all the details
129 // of iterating through a lattice.
130 // </motivation>
131 
132 //# <todo asof="1997/08/01">
133 //# <li>
134 //# </todo>
135 
136 
137 template <class T, class U=T> class LatticeApply
138 {
139 public:
140 
141 // This function iterates line by line through an input lattice and applies
142 // a user supplied function object to each line along the specified axis.
143 // The scalar result of the function object is written into the output
144 // lattice at the location of the collapsed line. The output lattice must
145 // be supplied with the correct shape (the shape of the supplied region).
146 // The default region is the entire input lattice.
147 // <group>
148  static void lineApply (MaskedLattice<U>& latticeOut,
149  const MaskedLattice<T>& latticeIn,
150  LineCollapser<T,U>& collapser,
151  uInt collapseAxis,
152  LatticeProgress* tellProgress = 0);
153  static void lineApply (MaskedLattice<U>& latticeOut,
154  const MaskedLattice<T>& latticeIn,
155  const LatticeRegion& region,
156  LineCollapser<T,U>& collapser,
157  uInt collapseAxis,
158  LatticeProgress* tellProgress = 0);
159 // </group>
160 
161 // This function iterates line by line through an input lattice and applies
162 // a user supplied function object to each line along the specified axis.
163 // The vector result of the function object is written into the output
164 // lattices at the location of the collapsed line (1 value per lattice).
165 // The output lattices must be supplied with the correct shape (the shape
166 // of the supplied region).
167 // The default region is the entire input lattice.
168 // <group>
169  static void lineMultiApply (PtrBlock<MaskedLattice<U>*>& latticeOut,
170  const MaskedLattice<T>& latticeIn,
171  LineCollapser<T,U>& collapser,
172  uInt collapseAxis,
173  LatticeProgress* tellProgress = 0);
174 
175  static void lineMultiApply (PtrBlock<MaskedLattice<U>*>& latticeOut,
176  const MaskedLattice<T>& latticeIn,
177  const LatticeRegion& region,
178  LineCollapser<T,U>& collapser,
179  uInt collapseAxis,
180  LatticeProgress* tellProgress = 0);
181 // </group>
182 
183 // This function iterates tile by tile through an input lattice and applies
184 // a user supplied function object to each chunk along the specified axes.
185 // A chunk can be a line, plane, etc. which is determined by the argument
186 // <src>collapseAxes</src>. E.g. IPosition(2,1,2) means planes along
187 // axes 1 and 2 (thus y,z planes).
188 // The result of the function object is written into the output
189 // lattice at the location of the collapsed chunk. The output lattice must
190 // be supplied with the correct shape (the shape of the supplied region
191 // plus the number of values resulting from the collapse).
192 // The default region is the entire input lattice.
193 // <group>
194  static void tiledApply (MaskedLattice<U>& latticeOut,
195  const MaskedLattice<T>& latticeIn,
196  TiledCollapser<T,U>& collapser,
197  const IPosition& collapseAxes,
198  Int newOutAxis = -1,
199  LatticeProgress* tellProgress = 0);
200  static void tiledApply (MaskedLattice<U>& latticeOut,
201  const MaskedLattice<T>& latticeIn,
202  const LatticeRegion& region,
203  TiledCollapser<T,U>& collapser,
204  const IPosition& collapseAxes,
205  Int newOutAxis = -1,
206  LatticeProgress* tellProgress = 0);
207 // </group>
208 
209 // This function iterates tile by tile through an input lattice and applies
210 // a user supplied function object to each chunk along the specified axes.
211 // A chunk can be a line, plane, etc. which is determined by the argument
212 // <src>collapseAxes</src>. E.g. IPosition(2,1,2) means planes along
213 // axes 1 and 2 (thus y,z planes).
214 // The result of the function object is written into the output
215 // lattices at the location of the collapsed chunk. The output lattices must
216 // be supplied with the correct shape (the shape of the supplied region).
217 // The default region is the entire input lattice.
218 // <note role=warning>
219 // These functions are only declared, but not implemented yet.
220 // Thus they cannot be used yet.
221 // </note>
222 // <group>
223  static void tiledMultiApply (PtrBlock<MaskedLattice<U>*>& latticeOut,
224  const MaskedLattice<T>& latticeIn,
225  TiledCollapser<T,U>& collapser,
226  const IPosition& collapseAxes,
227  LatticeProgress* tellProgress = 0);
228  static void tiledMultiApply (PtrBlock<MaskedLattice<U>*>& latticeOut,
229  const MaskedLattice<T>& latticeIn,
230  const LatticeRegion& region,
231  TiledCollapser<T,U>& collapser,
232  const IPosition& collapseAxes,
233  LatticeProgress* tellProgress = 0);
234 // </group>
235 
236 
237 private:
238  // Do some checks on the given arguments.
239  // It returns an IPosition with the same length as shapeOut.
240  // It contains a mapping of output to input axes. A value of -1
241  // indicates that the axis is new (to contain the collapse result).
242  // <br>Argument newOutAxis tells the output axis to store the results.
243  // -1 means that the function has to find it out itself; it takes the
244  // first axis with a length mismatching the corresponding input axis.
245  static IPosition prepare (const IPosition& shapeIn,
246  const IPosition& shapeOut,
247  const IPosition& collapseAxes,
248  Int newOutAxis);
249 
251  uInt axis, const MaskedLattice<T>& latticeIn
252  );
253 };
254 
255 } //# NAMESPACE CASACORE - END
256 
257 #ifndef CASACORE_NO_AUTO_TEMPLATES
258 #include <casacore/lattices/LatticeMath/LatticeApply.tcc>
259 #endif //# CASACORE_NO_AUTO_TEMPLATES
260 #endif
static void tiledApply(MaskedLattice< U > &latticeOut, const MaskedLattice< T > &latticeIn, TiledCollapser< T, U > &collapser, const IPosition &collapseAxes, Int newOutAxis=-1, LatticeProgress *tellProgress=0)
This function iterates tile by tile through an input lattice and applies a user supplied function obj...
static void lineApply(MaskedLattice< U > &latticeOut, const MaskedLattice< T > &latticeIn, const LatticeRegion &region, LineCollapser< T, U > &collapser, uInt collapseAxis, LatticeProgress *tellProgress=0)
static void lineApply(MaskedLattice< U > &latticeOut, const MaskedLattice< T > &latticeIn, LineCollapser< T, U > &collapser, uInt collapseAxis, LatticeProgress *tellProgress=0)
This function iterates line by line through an input lattice and applies a user supplied function obj...
static void lineMultiApply(PtrBlock< MaskedLattice< U > * > &latticeOut, const MaskedLattice< T > &latticeIn, const LatticeRegion &region, LineCollapser< T, U > &collapser, uInt collapseAxis, LatticeProgress *tellProgress=0)
static void lineMultiApply(PtrBlock< MaskedLattice< U > * > &latticeOut, const MaskedLattice< T > &latticeIn, LineCollapser< T, U > &collapser, uInt collapseAxis, LatticeProgress *tellProgress=0)
This function iterates line by line through an input lattice and applies a user supplied function obj...
static IPosition prepare(const IPosition &shapeIn, const IPosition &shapeOut, const IPosition &collapseAxes, Int newOutAxis)
Do some checks on the given arguments.
static IPosition _chunkShape(uInt axis, const MaskedLattice< T > &latticeIn)
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)
static void tiledMultiApply(PtrBlock< MaskedLattice< U > * > &latticeOut, const MaskedLattice< T > &latticeIn, const LatticeRegion &region, TiledCollapser< T, U > &collapser, const IPosition &collapseAxes, LatticeProgress *tellProgress=0)
static void tiledMultiApply(PtrBlock< MaskedLattice< U > * > &latticeOut, const MaskedLattice< T > &latticeIn, TiledCollapser< T, U > &collapser, const IPosition &collapseAxes, LatticeProgress *tellProgress=0)
This function iterates tile by tile through an input lattice and applies a user supplied function obj...
A drop-in replacement for Block<T*>.
Definition: Block.h:814
this file contains all the compiler specific defines
Definition: mainpage.dox:28
unsigned int uInt
Definition: aipstype.h:51
int Int
Definition: aipstype.h:50