| rev |
line source |
|
nuclear@0
|
1 KISS FFT - A mixed-radix Fast Fourier Transform based up on the principle,
|
|
nuclear@0
|
2 "Keep It Simple, Stupid."
|
|
nuclear@0
|
3
|
|
nuclear@0
|
4 There are many great fft libraries already around. Kiss FFT is not trying
|
|
nuclear@0
|
5 to be better than any of them. It only attempts to be a reasonably efficient,
|
|
nuclear@0
|
6 moderately useful FFT that can use fixed or floating data types and can be
|
|
nuclear@0
|
7 incorporated into someone's C program in a few minutes with trivial licensing.
|
|
nuclear@0
|
8
|
|
nuclear@0
|
9 USAGE:
|
|
nuclear@0
|
10
|
|
nuclear@0
|
11 The basic usage for 1-d complex FFT is:
|
|
nuclear@0
|
12
|
|
nuclear@0
|
13 #include "kiss_fft.h"
|
|
nuclear@0
|
14
|
|
nuclear@0
|
15 kiss_fft_cfg cfg = kiss_fft_alloc( nfft ,is_inverse_fft ,0,0 );
|
|
nuclear@0
|
16
|
|
nuclear@0
|
17 while ...
|
|
nuclear@0
|
18
|
|
nuclear@0
|
19 ... // put kth sample in cx_in[k].r and cx_in[k].i
|
|
nuclear@0
|
20
|
|
nuclear@0
|
21 kiss_fft( cfg , cx_in , cx_out );
|
|
nuclear@0
|
22
|
|
nuclear@0
|
23 ... // transformed. DC is in cx_out[0].r and cx_out[0].i
|
|
nuclear@0
|
24
|
|
nuclear@0
|
25 free(cfg);
|
|
nuclear@0
|
26
|
|
nuclear@0
|
27 Note: frequency-domain data is stored from dc up to 2pi.
|
|
nuclear@0
|
28 so cx_out[0] is the dc bin of the FFT
|
|
nuclear@0
|
29 and cx_out[nfft/2] is the Nyquist bin (if exists)
|
|
nuclear@0
|
30
|
|
nuclear@0
|
31 Declarations are in "kiss_fft.h", along with a brief description of the
|
|
nuclear@0
|
32 functions you'll need to use.
|
|
nuclear@0
|
33
|
|
nuclear@0
|
34 Code definitions for 1d complex FFTs are in kiss_fft.c.
|
|
nuclear@0
|
35
|
|
nuclear@0
|
36 You can do other cool stuff with the extras you'll find in tools/
|
|
nuclear@0
|
37
|
|
nuclear@0
|
38 * multi-dimensional FFTs
|
|
nuclear@0
|
39 * real-optimized FFTs (returns the positive half-spectrum: (nfft/2+1) complex frequency bins)
|
|
nuclear@0
|
40 * fast convolution FIR filtering (not available for fixed point)
|
|
nuclear@0
|
41 * spectrum image creation
|
|
nuclear@0
|
42
|
|
nuclear@0
|
43 The core fft and most tools/ code can be compiled to use float, double,
|
|
nuclear@0
|
44 Q15 short or Q31 samples. The default is float.
|
|
nuclear@0
|
45
|
|
nuclear@0
|
46
|
|
nuclear@0
|
47 BACKGROUND:
|
|
nuclear@0
|
48
|
|
nuclear@0
|
49 I started coding this because I couldn't find a fixed point FFT that didn't
|
|
nuclear@0
|
50 use assembly code. I started with floating point numbers so I could get the
|
|
nuclear@0
|
51 theory straight before working on fixed point issues. In the end, I had a
|
|
nuclear@0
|
52 little bit of code that could be recompiled easily to do ffts with short, float
|
|
nuclear@0
|
53 or double (other types should be easy too).
|
|
nuclear@0
|
54
|
|
nuclear@0
|
55 Once I got my FFT working, I was curious about the speed compared to
|
|
nuclear@0
|
56 a well respected and highly optimized fft library. I don't want to criticize
|
|
nuclear@0
|
57 this great library, so let's call it FFT_BRANDX.
|
|
nuclear@0
|
58 During this process, I learned:
|
|
nuclear@0
|
59
|
|
nuclear@0
|
60 1. FFT_BRANDX has more than 100K lines of code. The core of kiss_fft is about 500 lines (cpx 1-d).
|
|
nuclear@0
|
61 2. It took me an embarrassingly long time to get FFT_BRANDX working.
|
|
nuclear@0
|
62 3. A simple program using FFT_BRANDX is 522KB. A similar program using kiss_fft is 18KB (without optimizing for size).
|
|
nuclear@0
|
63 4. FFT_BRANDX is roughly twice as fast as KISS FFT in default mode.
|
|
nuclear@0
|
64
|
|
nuclear@0
|
65 It is wonderful that free, highly optimized libraries like FFT_BRANDX exist.
|
|
nuclear@0
|
66 But such libraries carry a huge burden of complexity necessary to extract every
|
|
nuclear@0
|
67 last bit of performance.
|
|
nuclear@0
|
68
|
|
nuclear@0
|
69 Sometimes simpler is better, even if it's not better.
|
|
nuclear@0
|
70
|
|
nuclear@0
|
71 FREQUENTLY ASKED QUESTIONS:
|
|
nuclear@0
|
72 Q: Can I use kissfft in a project with a ___ license?
|
|
nuclear@0
|
73 A: Yes. See LICENSE below.
|
|
nuclear@0
|
74
|
|
nuclear@0
|
75 Q: Why don't I get the output I expect?
|
|
nuclear@0
|
76 A: The two most common causes of this are
|
|
nuclear@0
|
77 1) scaling : is there a constant multiplier between what you got and what you want?
|
|
nuclear@0
|
78 2) mixed build environment -- all code must be compiled with same preprocessor
|
|
nuclear@0
|
79 definitions for FIXED_POINT and kiss_fft_scalar
|
|
nuclear@0
|
80
|
|
nuclear@0
|
81 Q: Will you write/debug my code for me?
|
|
nuclear@0
|
82 A: Probably not unless you pay me. I am happy to answer pointed and topical questions, but
|
|
nuclear@0
|
83 I may refer you to a book, a forum, or some other resource.
|
|
nuclear@0
|
84
|
|
nuclear@0
|
85
|
|
nuclear@0
|
86 PERFORMANCE:
|
|
nuclear@0
|
87 (on Athlon XP 2100+, with gcc 2.96, float data type)
|
|
nuclear@0
|
88
|
|
nuclear@0
|
89 Kiss performed 10000 1024-pt cpx ffts in .63 s of cpu time.
|
|
nuclear@0
|
90 For comparison, it took md5sum twice as long to process the same amount of data.
|
|
nuclear@0
|
91
|
|
nuclear@0
|
92 Transforming 5 minutes of CD quality audio takes less than a second (nfft=1024).
|
|
nuclear@0
|
93
|
|
nuclear@0
|
94 DO NOT:
|
|
nuclear@0
|
95 ... use Kiss if you need the Fastest Fourier Transform in the World
|
|
nuclear@0
|
96 ... ask me to add features that will bloat the code
|
|
nuclear@0
|
97
|
|
nuclear@0
|
98 UNDER THE HOOD:
|
|
nuclear@0
|
99
|
|
nuclear@0
|
100 Kiss FFT uses a time decimation, mixed-radix, out-of-place FFT. If you give it an input buffer
|
|
nuclear@0
|
101 and output buffer that are the same, a temporary buffer will be created to hold the data.
|
|
nuclear@0
|
102
|
|
nuclear@0
|
103 No static data is used. The core routines of kiss_fft are thread-safe (but not all of the tools directory).
|
|
nuclear@0
|
104
|
|
nuclear@0
|
105 No scaling is done for the floating point version (for speed).
|
|
nuclear@0
|
106 Scaling is done both ways for the fixed-point version (for overflow prevention).
|
|
nuclear@0
|
107
|
|
nuclear@0
|
108 Optimized butterflies are used for factors 2,3,4, and 5.
|
|
nuclear@0
|
109
|
|
nuclear@0
|
110 The real (i.e. not complex) optimization code only works for even length ffts. It does two half-length
|
|
nuclear@0
|
111 FFTs in parallel (packed into real&imag), and then combines them via twiddling. The result is
|
|
nuclear@0
|
112 nfft/2+1 complex frequency bins from DC to Nyquist. If you don't know what this means, search the web.
|
|
nuclear@0
|
113
|
|
nuclear@0
|
114 The fast convolution filtering uses the overlap-scrap method, slightly
|
|
nuclear@0
|
115 modified to put the scrap at the tail.
|
|
nuclear@0
|
116
|
|
nuclear@0
|
117 LICENSE:
|
|
nuclear@0
|
118 Revised BSD License, see COPYING for verbiage.
|
|
nuclear@0
|
119 Basically, "free to use&change, give credit where due, no guarantees"
|
|
nuclear@0
|
120 Note this license is compatible with GPL at one end of the spectrum and closed, commercial software at
|
|
nuclear@0
|
121 the other end. See http://www.fsf.org/licensing/licenses
|
|
nuclear@0
|
122
|
|
nuclear@0
|
123 A commercial license is available which removes the requirement for attribution. Contact me for details.
|
|
nuclear@0
|
124
|
|
nuclear@0
|
125
|
|
nuclear@0
|
126 TODO:
|
|
nuclear@0
|
127 *) Add real optimization for odd length FFTs
|
|
nuclear@0
|
128 *) Document/revisit the input/output fft scaling
|
|
nuclear@0
|
129 *) Make doc describing the overlap (tail) scrap fast convolution filtering in kiss_fastfir.c
|
|
nuclear@0
|
130 *) Test all the ./tools/ code with fixed point (kiss_fastfir.c doesn't work, maybe others)
|
|
nuclear@0
|
131
|
|
nuclear@0
|
132 AUTHOR:
|
|
nuclear@0
|
133 Mark Borgerding
|
|
nuclear@0
|
134 Mark@Borgerding.net
|
