nuclear@0: KISS FFT - A mixed-radix Fast Fourier Transform based up on the principle, nuclear@0: "Keep It Simple, Stupid." nuclear@0: nuclear@0: There are many great fft libraries already around. Kiss FFT is not trying nuclear@0: to be better than any of them. It only attempts to be a reasonably efficient, nuclear@0: moderately useful FFT that can use fixed or floating data types and can be nuclear@0: incorporated into someone's C program in a few minutes with trivial licensing. nuclear@0: nuclear@0: USAGE: nuclear@0: nuclear@0: The basic usage for 1-d complex FFT is: nuclear@0: nuclear@0: #include "kiss_fft.h" nuclear@0: nuclear@0: kiss_fft_cfg cfg = kiss_fft_alloc( nfft ,is_inverse_fft ,0,0 ); nuclear@0: nuclear@0: while ... nuclear@0: nuclear@0: ... // put kth sample in cx_in[k].r and cx_in[k].i nuclear@0: nuclear@0: kiss_fft( cfg , cx_in , cx_out ); nuclear@0: nuclear@0: ... // transformed. DC is in cx_out[0].r and cx_out[0].i nuclear@0: nuclear@0: free(cfg); nuclear@0: nuclear@0: Note: frequency-domain data is stored from dc up to 2pi. nuclear@0: so cx_out[0] is the dc bin of the FFT nuclear@0: and cx_out[nfft/2] is the Nyquist bin (if exists) nuclear@0: nuclear@0: Declarations are in "kiss_fft.h", along with a brief description of the nuclear@0: functions you'll need to use. nuclear@0: nuclear@0: Code definitions for 1d complex FFTs are in kiss_fft.c. nuclear@0: nuclear@0: You can do other cool stuff with the extras you'll find in tools/ nuclear@0: nuclear@0: * multi-dimensional FFTs nuclear@0: * real-optimized FFTs (returns the positive half-spectrum: (nfft/2+1) complex frequency bins) nuclear@0: * fast convolution FIR filtering (not available for fixed point) nuclear@0: * spectrum image creation nuclear@0: nuclear@0: The core fft and most tools/ code can be compiled to use float, double, nuclear@0: Q15 short or Q31 samples. The default is float. nuclear@0: nuclear@0: nuclear@0: BACKGROUND: nuclear@0: nuclear@0: I started coding this because I couldn't find a fixed point FFT that didn't nuclear@0: use assembly code. I started with floating point numbers so I could get the nuclear@0: theory straight before working on fixed point issues. In the end, I had a nuclear@0: little bit of code that could be recompiled easily to do ffts with short, float nuclear@0: or double (other types should be easy too). nuclear@0: nuclear@0: Once I got my FFT working, I was curious about the speed compared to nuclear@0: a well respected and highly optimized fft library. I don't want to criticize nuclear@0: this great library, so let's call it FFT_BRANDX. nuclear@0: During this process, I learned: nuclear@0: nuclear@0: 1. FFT_BRANDX has more than 100K lines of code. The core of kiss_fft is about 500 lines (cpx 1-d). nuclear@0: 2. It took me an embarrassingly long time to get FFT_BRANDX working. nuclear@0: 3. A simple program using FFT_BRANDX is 522KB. A similar program using kiss_fft is 18KB (without optimizing for size). nuclear@0: 4. FFT_BRANDX is roughly twice as fast as KISS FFT in default mode. nuclear@0: nuclear@0: It is wonderful that free, highly optimized libraries like FFT_BRANDX exist. nuclear@0: But such libraries carry a huge burden of complexity necessary to extract every nuclear@0: last bit of performance. nuclear@0: nuclear@0: Sometimes simpler is better, even if it's not better. nuclear@0: nuclear@0: FREQUENTLY ASKED QUESTIONS: nuclear@0: Q: Can I use kissfft in a project with a ___ license? nuclear@0: A: Yes. See LICENSE below. nuclear@0: nuclear@0: Q: Why don't I get the output I expect? nuclear@0: A: The two most common causes of this are nuclear@0: 1) scaling : is there a constant multiplier between what you got and what you want? nuclear@0: 2) mixed build environment -- all code must be compiled with same preprocessor nuclear@0: definitions for FIXED_POINT and kiss_fft_scalar nuclear@0: nuclear@0: Q: Will you write/debug my code for me? nuclear@0: A: Probably not unless you pay me. I am happy to answer pointed and topical questions, but nuclear@0: I may refer you to a book, a forum, or some other resource. nuclear@0: nuclear@0: nuclear@0: PERFORMANCE: nuclear@0: (on Athlon XP 2100+, with gcc 2.96, float data type) nuclear@0: nuclear@0: Kiss performed 10000 1024-pt cpx ffts in .63 s of cpu time. nuclear@0: For comparison, it took md5sum twice as long to process the same amount of data. nuclear@0: nuclear@0: Transforming 5 minutes of CD quality audio takes less than a second (nfft=1024). nuclear@0: nuclear@0: DO NOT: nuclear@0: ... use Kiss if you need the Fastest Fourier Transform in the World nuclear@0: ... ask me to add features that will bloat the code nuclear@0: nuclear@0: UNDER THE HOOD: nuclear@0: nuclear@0: Kiss FFT uses a time decimation, mixed-radix, out-of-place FFT. If you give it an input buffer nuclear@0: and output buffer that are the same, a temporary buffer will be created to hold the data. nuclear@0: nuclear@0: No static data is used. The core routines of kiss_fft are thread-safe (but not all of the tools directory). nuclear@0: nuclear@0: No scaling is done for the floating point version (for speed). nuclear@0: Scaling is done both ways for the fixed-point version (for overflow prevention). nuclear@0: nuclear@0: Optimized butterflies are used for factors 2,3,4, and 5. nuclear@0: nuclear@0: The real (i.e. not complex) optimization code only works for even length ffts. It does two half-length nuclear@0: FFTs in parallel (packed into real&imag), and then combines them via twiddling. The result is nuclear@0: nfft/2+1 complex frequency bins from DC to Nyquist. If you don't know what this means, search the web. nuclear@0: nuclear@0: The fast convolution filtering uses the overlap-scrap method, slightly nuclear@0: modified to put the scrap at the tail. nuclear@0: nuclear@0: LICENSE: nuclear@0: Revised BSD License, see COPYING for verbiage. nuclear@0: Basically, "free to use&change, give credit where due, no guarantees" nuclear@0: Note this license is compatible with GPL at one end of the spectrum and closed, commercial software at nuclear@0: the other end. See http://www.fsf.org/licensing/licenses nuclear@0: nuclear@0: A commercial license is available which removes the requirement for attribution. Contact me for details. nuclear@0: nuclear@0: nuclear@0: TODO: nuclear@0: *) Add real optimization for odd length FFTs nuclear@0: *) Document/revisit the input/output fft scaling nuclear@0: *) Make doc describing the overlap (tail) scrap fast convolution filtering in kiss_fastfir.c nuclear@0: *) Test all the ./tools/ code with fixed point (kiss_fastfir.c doesn't work, maybe others) nuclear@0: nuclear@0: AUTHOR: nuclear@0: Mark Borgerding nuclear@0: Mark@Borgerding.net