Gitiles

review.gerrithub.io / DU-Final / external_kissfft / cfa95dc35972f97a9186bf8f33bb1a9f87a40d42 / . / README

James Melvin | bc9274a | 2012-03-06 09:27:54 -0700 | [diff] [blame] | 1 | KISS FFT - A mixed-radix Fast Fourier Transform based up on the principle, |

2 | "Keep It Simple, Stupid." | ||||

3 | |||||

4 | There are many great fft libraries already around. Kiss FFT is not trying | ||||

5 | to be better than any of them. It only attempts to be a reasonably efficient, | ||||

6 | moderately useful FFT that can use fixed or floating data types and can be | ||||

7 | incorporated into someone's C program in a few minutes with trivial licensing. | ||||

8 | |||||

9 | USAGE: | ||||

10 | |||||

11 | The basic usage for 1-d complex FFT is: | ||||

12 | |||||

13 | #include "kiss_fft.h" | ||||

14 | |||||

15 | kiss_fft_cfg cfg = kiss_fft_alloc( nfft ,is_inverse_fft ,0,0 ); | ||||

16 | |||||

17 | while ... | ||||

18 | |||||

19 | ... // put kth sample in cx_in[k].r and cx_in[k].i | ||||

20 | |||||

21 | kiss_fft( cfg , cx_in , cx_out ); | ||||

22 | |||||

23 | ... // transformed. DC is in cx_out[0].r and cx_out[0].i | ||||

24 | |||||

25 | free(cfg); | ||||

26 | |||||

27 | Note: frequency-domain data is stored from dc up to 2pi. | ||||

28 | so cx_out[0] is the dc bin of the FFT | ||||

29 | and cx_out[nfft/2] is the Nyquist bin (if exists) | ||||

30 | |||||

31 | Declarations are in "kiss_fft.h", along with a brief description of the | ||||

32 | functions you'll need to use. | ||||

33 | |||||

34 | Code definitions for 1d complex FFTs are in kiss_fft.c. | ||||

35 | |||||

36 | You can do other cool stuff with the extras you'll find in tools/ | ||||

37 | |||||

38 | * multi-dimensional FFTs | ||||

39 | * real-optimized FFTs (returns the positive half-spectrum: (nfft/2+1) complex frequency bins) | ||||

40 | * fast convolution FIR filtering (not available for fixed point) | ||||

41 | * spectrum image creation | ||||

42 | |||||

43 | The core fft and most tools/ code can be compiled to use float, double | ||||

44 | or Q15 short samples. The default is float. | ||||

45 | |||||

46 | |||||

47 | BACKGROUND: | ||||

48 | |||||

49 | I started coding this because I couldn't find a fixed point FFT that didn't | ||||

50 | use assembly code. I started with floating point numbers so I could get the | ||||

51 | theory straight before working on fixed point issues. In the end, I had a | ||||

52 | little bit of code that could be recompiled easily to do ffts with short, float | ||||

53 | or double (other types should be easy too). | ||||

54 | |||||

55 | Once I got my FFT working, I was curious about the speed compared to | ||||

56 | a well respected and highly optimized fft library. I don't want to criticize | ||||

57 | this great library, so let's call it FFT_BRANDX. | ||||

58 | During this process, I learned: | ||||

59 | |||||

60 | 1. FFT_BRANDX has more than 100K lines of code. The core of kiss_fft is about 500 lines (cpx 1-d). | ||||

61 | 2. It took me an embarrassingly long time to get FFT_BRANDX working. | ||||

62 | 3. A simple program using FFT_BRANDX is 522KB. A similar program using kiss_fft is 18KB (without optimizing for size). | ||||

63 | 4. FFT_BRANDX is roughly twice as fast as KISS FFT in default mode. | ||||

64 | |||||

65 | It is wonderful that free, highly optimized libraries like FFT_BRANDX exist. | ||||

66 | But such libraries carry a huge burden of complexity necessary to extract every | ||||

67 | last bit of performance. | ||||

68 | |||||

69 | Sometimes simpler is better, even if it's not better. | ||||

70 | |||||

71 | FREQUENTLY ASKED QUESTIONS: | ||||

72 | Q: Can I use kissfft in a project with a ___ license? | ||||

73 | A: Yes. See LICENSE below. | ||||

74 | |||||

75 | Q: Why don't I get the output I expect? | ||||

76 | A: The two most common causes of this are | ||||

77 | 1) scaling : is there a constant multiplier between what you got and what you want? | ||||

78 | 2) mixed build environment -- all code must be compiled with same preprocessor | ||||

79 | definitions for FIXED_POINT and kiss_fft_scalar | ||||

80 | |||||

81 | Q: Will you write/debug my code for me? | ||||

82 | A: Probably not unless you pay me. I am happy to answer pointed and topical questions, but | ||||

83 | I may refer you to a book, a forum, or some other resource. | ||||

84 | |||||

85 | |||||

86 | PERFORMANCE: | ||||

87 | (on Athlon XP 2100+, with gcc 2.96, float data type) | ||||

88 | |||||

89 | Kiss performed 10000 1024-pt cpx ffts in .63 s of cpu time. | ||||

90 | For comparison, it took md5sum twice as long to process the same amount of data. | ||||

91 | |||||

92 | Transforming 5 minutes of CD quality audio takes less than a second (nfft=1024). | ||||

93 | |||||

94 | DO NOT: | ||||

95 | ... use Kiss if you need the Fastest Fourier Transform in the World | ||||

96 | ... ask me to add features that will bloat the code | ||||

97 | |||||

98 | UNDER THE HOOD: | ||||

99 | |||||

100 | Kiss FFT uses a time decimation, mixed-radix, out-of-place FFT. If you give it an input buffer | ||||

101 | and output buffer that are the same, a temporary buffer will be created to hold the data. | ||||

102 | |||||

103 | No static data is used. The core routines of kiss_fft are thread-safe (but not all of the tools directory). | ||||

104 | |||||

105 | No scaling is done for the floating point version (for speed). | ||||

106 | Scaling is done both ways for the fixed-point version (for overflow prevention). | ||||

107 | |||||

108 | Optimized butterflies are used for factors 2,3,4, and 5. | ||||

109 | |||||

110 | The real (i.e. not complex) optimization code only works for even length ffts. It does two half-length | ||||

111 | FFTs in parallel (packed into real&imag), and then combines them via twiddling. The result is | ||||

112 | nfft/2+1 complex frequency bins from DC to Nyquist. If you don't know what this means, search the web. | ||||

113 | |||||

114 | The fast convolution filtering uses the overlap-scrap method, slightly | ||||

115 | modified to put the scrap at the tail. | ||||

116 | |||||

117 | LICENSE: | ||||

118 | Revised BSD License, see COPYING for verbiage. | ||||

119 | Basically, "free to use&change, give credit where due, no guarantees" | ||||

120 | Note this license is compatible with GPL at one end of the spectrum and closed, commercial software at | ||||

121 | the other end. See http://www.fsf.org/licensing/licenses | ||||

122 | |||||

123 | A commercial license is available which removes the requirement for attribution. Contact me for details. | ||||

124 | |||||

125 | |||||

126 | TODO: | ||||

127 | *) Add real optimization for odd length FFTs | ||||

128 | *) Document/revisit the input/output fft scaling | ||||

129 | *) Make doc describing the overlap (tail) scrap fast convolution filtering in kiss_fastfir.c | ||||

130 | *) Test all the ./tools/ code with fixed point (kiss_fastfir.c doesn't work, maybe others) | ||||

131 | |||||

132 | AUTHOR: | ||||

133 | Mark Borgerding | ||||

134 | Mark@Borgerding.net |