core/vnl/algo/vnl_convolve.h
Go to the documentation of this file.
00001 // This is core/vnl/algo/vnl_convolve.h
00002 #ifndef vnl_convolve_h_
00003 #define vnl_convolve_h_
00004 //:
00005 // \file
00006 // \brief Templated 1D and 2D convolution
00007 // \author Peter Vanroose
00008 // \date 22 August 2001
00009 //
00010 // This file contains function declarations for 1D and 2D convolutions,
00011 // both cyclic and non-cyclic, of vnl_vectors and vnl_matrices.
00012 // One can choose between straightforward `time-domain' implementations
00013 // or using FFT to do a `frequency-domain' calculation.
00014 
00015 #include <vnl/vnl_vector.h>
00016 
00017 //: Convolve two vnl_vector<T>'s, possibly with different base types T.
00018 //  $res[k] := \displaystyle\sum_{i=-\infty}^{+\infty} v1[k-i] \cdot v2[i]$.
00019 //
00020 //  The returned vnl_vector has base type U (the third argument).
00021 //  All calculations are done with type U, so take care!
00022 //  To specify the third argument, pass e.g. a null pointer, casted to U*.
00023 //  Thus: vnl_convolve(v1, v2, (double*)0)
00024 //  would convolve v1 and v2, and return a vnl_vector<double>.
00025 //
00026 //  This convolution is non-cyclic, and the length of the result is
00027 //  one less than the sum of the lengths of the two input vectors.
00028 //  But if one of the arguments has length 0, the result has length 0.
00029 //
00030 //  When specifying a non-zero 4th argument, FFTs are used to compute
00031 //  the result (see below), which should be identical.
00032 //  The speed of execution may of course differ.
00033 //  In this case both vectors are padded with a sufficient number of zeros,
00034 //  making the length at least that 4th argument,
00035 //  then vnl_convolve_cyclic() is applied.
00036 //
00037 template <class T1, class T2, class U>
00038 vnl_vector<U>
00039 vnl_convolve(vnl_vector<T1> const& v1, vnl_vector<T2> const& v2,
00040              U*, int use_fft = 0);
00041 
00042 
00043 //: Convolve two vnl_vector<T>'s, with the same base type T.
00044 //
00045 //  The returned vnl_vector has the same base type T, and is identical to
00046 //  the return value of the previous function when T1 = T2 = U.
00047 //
00048 //  \relatesalso vnl_vector
00049 template <class T>
00050 vnl_vector<T>
00051 vnl_convolve(vnl_vector<T> const& v1, vnl_vector<T> const& v2,
00052              int use_fft = 0);
00053 
00054 
00055 //: Cyclically convolve two vnl_vector<T>'s of the same length.
00056 //  $res[k] := \displaystyle\sum_{i=0}^{n-1} v1[k-i] \cdot v2[i]$.
00057 //
00058 //  A cyclic convolution requires that the lengths of the input vectors
00059 //  are identical.  If this is not the case, an assert failure occurs.
00060 //  The length of the returned vector equals the length of the inputs.
00061 //
00062 //  Since the convolution theorem states that a cyclic convolution followed by
00063 //  an FFT is the same as an FFT followed by a multiplication, a cyclic
00064 //  convolution can also be implemented using 3 FFTs on n points and n complex
00065 //  multiplications.
00066 //  By default, vnl_convolve_cyclic does not use FFTs.  By specifying "true" as
00067 //  the fourth argument, calculation of the convolution is done using FFTs.
00068 //  This will generally be faster for large n, especially if the vectors are
00069 //  not sparse, and/or if n is a power of 2.
00070 //
00071 //  \relatesalso vnl_vector
00072 template <class T1, class T2, class U>
00073 vnl_vector<U>
00074 vnl_convolve_cyclic(vnl_vector<T1> const& v1, vnl_vector<T2> const& v2,
00075                     U*, bool use_fft = false);
00076 
00077 // Not yet implemented
00078 template <class T1, class T2, class U>
00079 vnl_matrix<U>
00080 vnl_convolve(vnl_matrix<T1> const& v1, vnl_matrix<T2> const& v2,
00081              U*, int use_fft = 0);
00082 
00083 // Not yet implemented
00084 template <class T>
00085 vnl_matrix<T>
00086 vnl_convolve(vnl_matrix<T> const& v1, vnl_matrix<T> const& v2,
00087              int use_fft = 0);
00088 
00089 // Not yet implemented
00090 template <class T1, class T2, class U>
00091 vnl_matrix<U>
00092 vnl_convolve_cyclic(vnl_matrix<T1> const& v1, vnl_matrix<T2> const& v2,
00093                     U*, bool use_fft = false);
00094 
00095 // Not yet implemented
00096 template <class T1, class T2, class U>
00097 vnl_matrix<U>
00098 vnl_convolve(vnl_matrix<T1> const& v1, vnl_vector<T2> const& v2,
00099              U*, int use_fft = 0);
00100 
00101 // Not yet implemented
00102 template <class T>
00103 vnl_matrix<T>
00104 vnl_convolve(vnl_matrix<T> const& v1, vnl_vector<T> const& v2,
00105              int use_fft = 0);
00106 
00107 #define VNL_CONVOLVE_INSTANTIATE(T) \
00108 extern "please include vnl/algo/vnl_convolve.txx first"
00109 
00110 #endif // vnl_convolve_h_