casacore
Loading...
Searching...
No Matches
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
36namespace casacore { //# NAMESPACE CASACORE - BEGIN
37
38//# Forward Declarations
39template <class T, class U> class TiledCollapser;
40template <class T, class U> class LineCollapser;
41template <class T> class Lattice;
42template <class T> class MaskedLattice;
43class LatticeProgress;
44class IPosition;
45class 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
137template <class T, class U=T> class LatticeApply
138{
139public:
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
237private:
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