1 // This is core/vnl/algo/vnl_convolve.h 2 #ifndef vnl_convolve_h_ 3 #define vnl_convolve_h_ 4 //: 5 // \file 6 // \brief Templated 1D and 2D convolution 7 // \author Peter Vanroose 8 // \date 22 August 2001 9 // 10 // This file contains function declarations for 1D and 2D convolutions, 11 // both cyclic and non-cyclic, of vnl_vectors and vnl_matrices. 12 // One can choose between straightforward `time-domain' implementations 13 // or using FFT to do a `frequency-domain' calculation. 14 15 #include <vnl/vnl_vector.h> 16 #include <vnl/algo/vnl_algo_export.h> 17 18 //: Convolve two vnl_vector<T>'s, possibly with different base types T. 19 // $res[k] := \displaystyle\sum_{i=-\infty}^{+\infty} v1[k-i] \cdot v2[i]$. 20 // 21 // The returned vnl_vector has base type U (the third argument). 22 // All calculations are done with type U, so take care! 23 // To specify the third argument, pass e.g. a null pointer, casted to U*. 24 // Thus: vnl_convolve(v1, v2, (double*)0) 25 // would convolve v1 and v2, and return a vnl_vector<double>. 26 // 27 // This convolution is non-cyclic, and the length of the result is 28 // one less than the sum of the lengths of the two input vectors. 29 // But if one of the arguments has length 0, the result has length 0. 30 // 31 // When specifying a non-zero 4th argument, FFTs are used to compute 32 // the result (see below), which should be identical. 33 // The speed of execution may of course differ. 34 // In this case both vectors are padded with a sufficient number of zeros, 35 // making the length at least that 4th argument, 36 // then vnl_convolve_cyclic() is applied. 37 // 38 template <class T1, class T2, class U> 39 VNL_EXPORT 40 vnl_vector<U> 41 vnl_convolve(vnl_vector<T1> const& v1, vnl_vector<T2> const& v2, 42 U*, int use_fft = 0); 43 44 45 //: Convolve two vnl_vector<T>'s, with the same base type T. 46 // 47 // The returned vnl_vector has the same base type T, and is identical to 48 // the return value of the previous function when T1 = T2 = U. 49 // 50 // \relatesalso vnl_vector 51 template <class T> 52 VNL_EXPORT 53 vnl_vector<T> 54 vnl_convolve(vnl_vector<T> const& v1, vnl_vector<T> const& v2, 55 int use_fft = 0); 56 57 58 //: Cyclically convolve two vnl_vector<T>'s of the same length. 59 // $res[k] := \displaystyle\sum_{i=0}^{n-1} v1[k-i] \cdot v2[i]$. 60 // 61 // A cyclic convolution requires that the lengths of the input vectors 62 // are identical. If this is not the case, an assert failure occurs. 63 // The length of the returned vector equals the length of the inputs. 64 // 65 // Since the convolution theorem states that a cyclic convolution followed by 66 // an FFT is the same as an FFT followed by a multiplication, a cyclic 67 // convolution can also be implemented using 3 FFTs on n points and n complex 68 // multiplications. 69 // By default, vnl_convolve_cyclic does not use FFTs. By specifying "true" as 70 // the fourth argument, calculation of the convolution is done using FFTs. 71 // This will generally be faster for large n, especially if the vectors are 72 // not sparse, and/or if n is a power of 2. 73 // 74 // \relatesalso vnl_vector 75 76 template <class T1, class T2, class U> 77 VNL_EXPORT 78 vnl_vector<U> 79 vnl_convolve_cyclic(vnl_vector<T1> const& v1, vnl_vector<T2> const& v2, 80 U*, bool use_fft = false); 81 82 // Not yet implemented 83 template <class T1, class T2, class U> 84 vnl_matrix<U> 85 vnl_convolve(vnl_matrix<T1> const& v1, vnl_matrix<T2> const& v2, 86 U*, int use_fft = 0); 87 88 // Not yet implemented 89 template <class T> 90 vnl_matrix<T> 91 vnl_convolve(vnl_matrix<T> const& v1, vnl_matrix<T> const& v2, 92 int use_fft = 0); 93 94 // Not yet implemented 95 template <class T1, class T2, class U> 96 vnl_matrix<U> 97 vnl_convolve_cyclic(vnl_matrix<T1> const& v1, vnl_matrix<T2> const& v2, 98 U*, bool use_fft = false); 99 100 // Not yet implemented 101 template <class T1, class T2, class U> 102 vnl_matrix<U> 103 vnl_convolve(vnl_matrix<T1> const& v1, vnl_vector<T2> const& v2, 104 U*, int use_fft = 0); 105 106 // Not yet implemented 107 template <class T> 108 vnl_matrix<T> 109 vnl_convolve(vnl_matrix<T> const& v1, vnl_vector<T> const& v2, 110 int use_fft = 0); 111 112 #define VNL_CONVOLVE_INSTANTIATE(T) \ 113 extern "please include vnl/algo/vnl_convolve.hxx first" 114 115 #endif // vnl_convolve_h_ 116