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_