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