casacore
Loading...
Searching...
No Matches
LatticeConvolver.h
Go to the documentation of this file.
1//# Convolver.h: this defines Convolver a class for doing convolution
2//# Copyright (C) 1996,1997,1998,1999,2000,2001,2002,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: casa-feedback@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#ifndef LATTICES_LATTICECONVOLVER_H
27#define LATTICES_LATTICECONVOLVER_H
28
29//# Includes
30#include <casacore/casa/aips.h>
31#include <casacore/scimath/Mathematics/NumericTraits.h>
32#include <casacore/lattices/Lattices/TempLattice.h>
33#include <casacore/casa/Arrays/IPosition.h>
34
35namespace casacore { //# NAMESPACE CASACORE - BEGIN
36
37//# Forward Declarations
38//template <class T> class LatticeConvolver;
39class IPosition;
40
41// <summary>Lists the different types of Convolutions that can be done</summary>
42// <synopsis>This enumerator is brought out as a separate class because g++
43// currently cannot handle enumerators in a templated class. When it can this
44// class will go away and this enumerator moved into the Convolver
45// class</synopsis>
46class ConvEnums {
47public:
48 enum ConvType {
49 // Linear convolution
50 LINEAR,
51 // Circular Convolution
53 //# Assume the point spread function is symmetric
54 //#REALSYMMETRIC
55 };
56};
57
58// <summary>A class for doing multi-dimensional convolution</summary>
59
60// <use visibility=export>
61
62// <reviewed reviewer="" date="yyyy/mm/dd" tests="tLatticeConvolver">
63// </reviewed>
64
65// <prerequisite>
66// <li> The mathematical concept of convolution
67// </prerequisite>
68//
69// <etymology>
70// The LatticeConvolver class will convolve Lattices. This class
71// complements the Convolver class which will convolve Arrays.
72// </etymology>
73//
74// <synopsis>
75// This class performs linear or circular convolution on Lattices. See the
76// <linkto class="Convolver">Convolver</linkto> class description of the
77// difference between linear and circular convolution.
78
79// This class does convolutions by multiplying the Fourier transforms of the
80// supplied Lattices and returning the inverse transform of the product. This
81// is the best algorithm to use when the point spread function is large. This
82// class does all the padding with zeros necessary to implement this
83// algorithm. Hence the
84
85// </synopsis>
86//
87// <example>
88// <srcblock>
89//
90// </srcblock>
91// </example>
92//
93// <motivation>
94// </motivation>
95//
96// <thrown>
97// <li> AipsError: if psf and model have a differing numbers of dimensions
98// </thrown>
99//
100// <todo asof="yyyy/mm/dd">
101// <li> the class should detect if the psf or image is small and do the
102// convolution directly rather than use the Fourier domain
103// <li> Allow the psf to be specified with a
104// <linkto class=Function>Function</linkto>.
105// </todo>
106
107template<class T> class LatticeConvolver
108{
109public:
110 // The default constructor creates a LatticeConvolver that will convolve your
111 // data with a point spread function (psf) that zero everywhere except at the
112 // centre where it is one. Convolving with this psf will not change your
113 // data.
115
116 // Create a convolver that is initialised to do circular convolution with the
117 // specified point spread function. It is assumed that the supplied model
118 // will be the same shape as the point spread function.
119 LatticeConvolver(const Lattice<T> & psf, Bool doFast=False);
120
121 // Create a convolver that is initialised to do linear convolution with the
122 // specified point spread function. The size of the model you will convolve
123 // with must be specified.
124 LatticeConvolver(const Lattice<T> & psf, const IPosition & modelShape,
125 Bool doFast=False);
126
127 // Create a convolver that is initialised to do the specified type of
128 // convolution with the specified point spread function. The size of the
129 // model you expect to convolve with must be specified.
130 LatticeConvolver(const Lattice<T> & psf, const IPosition & modelShape,
132
133 // The copy constructor uses reference semantics
135
136 // The assignment operator also uses reference semantics
138
139 // The destructor does nothing special.
141
142 // Perform linear convolution of the model with the previously specified
143 // psf. The supplied Lattices must be the same shape.
144 void linear(Lattice<T> & result, const Lattice<T> & model);
145
146 // Perform in-place linear convolution of the model with the previously
147 // specified psf. Return the result in the same Lattice as the
148 // model.
149 void linear(Lattice<T> & modelAndResult);
150
151 // Perform circular convolution of the model with the previously
152 // specified psf. Return the answer in result.
153 void circular(Lattice<T> & result, const Lattice<T> & model);
154
155 // Perform in-place linear convolution of the model with the previously
156 // specified psf. Return the result in the same Lattice as the model.
157 void circular(Lattice<T> & modelAndResult);
158
159 // Perform convolution on the specified model using the currently initialised
160 // convolution type (linear or circular). These functions will not resize the
161 // LatticeConvolver if the supplied Lattice is the wrong shape.
162 //
163 // If the LatticeConvolver is setup for circular Convolution then the size of
164 // the supplied model must be less than or equal to the shape returned by the
165 // fftshape() function, which is usually the same as the shape of the psf.
166 //
167 // If the LatticeConvolver is setup to do linear convolution the the
168 // input and output Lattices must have the same shape as the result from the
169 // shape() member function. The convolution may be either in-place or not.
170 // <group>
171 void convolve(Lattice<T> & modelAndResult) const;
172 void convolve(Lattice<T> & result, const Lattice<T> & model) const;
173 // </group>
174
175 // Return the psf currently used by this convolver. The supplied Lattice must
176 // be the correct shape ie., the same as returned by the psfShape member
177 // function.
178 void getPsf(Lattice<T> & psf) const;
179
180 // Resize the LatticeConvolver to do convolutions of the specified type and
181 // shape. The supplied function must always have the same number of
182 // dimensions as the internal point spread function (which can be found using
183 // the shape member function). The LatticeConvolver will be set up to do
184 // circular or linear convolutions depending on the supplied type
185 void resize(const IPosition & modelShape, ConvEnums::ConvType type);
186
187 // Returns the shape of the Lattices that the convolver will convolve. This
188 // shape will always have as many dimensions as the psf that was used to
189 // initialise the LatticeConvolver. If the LatticeConvolver is setup to do
190 // circular convolutions then every axis of the returned IPosition will be
191 // zero length. If the LatticeConvolver is setup to do linear convolutions
192 // then the returned IPosition will have a positive values on each axis that
193 // indicate the expected shape of the input model.
195
196 // Returns the shape of the point spread function that the LatticeConvolver
197 // was initialised with.
199
200 // Returns the type of convolution the LatticeConvolver is currently set up
201 // to do.
203
204 // Returns the shape of the FFT's that the LatticeConvolver will do when
205 // performing the convolution. Not really useful except as a diagnostic
206 // tool. If the shape contains a lot of poorly factorisable lengths then the
207 // convolution will be slow.
209
210 // Set usage of fast convolve with lesser flips
212
213private:
214 //# The following functions are used in various places in the code and are
215 //# documented in the .cc file. Static functions are used when the functions
216 //# do not use the object state. They ensure that implicit assumptions
217 //# about the current state and implicit side-effects are not possible
218 //# because all information must be suplied in the input arguments
219 static void pad(Lattice<T> & paddedLat, const Lattice<T> & inLat);
220 static void unpad(Lattice<T> & result, const Lattice<T> & paddedResult);
221 void makeXfr(const Lattice<T> & psf);
222 void makePsf(Lattice<T> & psf) const;
224 const IPosition & modelShape,
226
235};
236
237} //# NAMESPACE CASACORE - END
238
239#ifndef CASACORE_NO_AUTO_TEMPLATES
240#include <casacore/lattices/LatticeMath/LatticeConvolver.tcc>
241#endif //# CASACORE_NO_AUTO_TEMPLATES
242#endif
243
@ LINEAR
Linear convolution.
@ CIRCULAR
Circular Convolution.
A class for doing multi-dimensional convolution.
LatticeConvolver< T > & operator=(const LatticeConvolver< T > &other)
The assignment operator also uses reference semantics.
ConvEnums::ConvType type() const
Returns the type of convolution the LatticeConvolver is currently set up to do.
IPosition shape() const
Returns the shape of the Lattices that the convolver will convolve.
TempLattice< typename NumericTraits< T >::ConjugateType > * itsXfr
ConvEnums::ConvType itsType
LatticeConvolver(const Lattice< T > &psf, Bool doFast=False)
Create a convolver that is initialised to do circular convolution with the specified point spread fun...
void linear(Lattice< T > &modelAndResult)
Perform in-place linear convolution of the model with the previously specified psf.
void linear(Lattice< T > &result, const Lattice< T > &model)
Perform linear convolution of the model with the previously specified psf.
void makeXfr(const Lattice< T > &psf)
~LatticeConvolver()
The destructor does nothing special.
IPosition psfShape() const
Returns the shape of the point spread function that the LatticeConvolver was initialised with.
void getPsf(Lattice< T > &psf) const
Return the psf currently used by this convolver.
LatticeConvolver(const LatticeConvolver< T > &other)
The copy constructor uses reference semantics.
LatticeConvolver(const Lattice< T > &psf, const IPosition &modelShape, Bool doFast=False)
Create a convolver that is initialised to do linear convolution with the specified point spread funct...
static void unpad(Lattice< T > &result, const Lattice< T > &paddedResult)
void setFastConvolve()
Set usage of fast convolve with lesser flips.
IPosition fftShape() const
Returns the shape of the FFT's that the LatticeConvolver will do when performing the convolution.
void makePsf(Lattice< T > &psf) const
LatticeConvolver()
The default constructor creates a LatticeConvolver that will convolve your data with a point spread f...
void circular(Lattice< T > &modelAndResult)
Perform in-place linear convolution of the model with the previously specified psf.
void circular(Lattice< T > &result, const Lattice< T > &model)
Perform circular convolution of the model with the previously specified psf.
void convolve(Lattice< T > &modelAndResult) const
Perform convolution on the specified model using the currently initialised convolution type (linear o...
static void pad(Lattice< T > &paddedLat, const Lattice< T > &inLat)
void resize(const IPosition &modelShape, ConvEnums::ConvType type)
Resize the LatticeConvolver to do convolutions of the specified type and shape.
LatticeConvolver(const Lattice< T > &psf, const IPosition &modelShape, ConvEnums::ConvType type, Bool doFast=False)
Create a convolver that is initialised to do the specified type of convolution with the specified poi...
void convolve(Lattice< T > &result, const Lattice< T > &model) const
static IPosition calcFFTShape(const IPosition &psfShape, const IPosition &modelShape, ConvEnums::ConvType type)
this file contains all the compiler specific defines
Definition mainpage.dox:28
const Bool False
Definition aipstype.h:42
bool Bool
Define the standard types used by Casacore.
Definition aipstype.h:40