alice.mosphere.at / kissfft
this repo has no description
0
fork

Configure Feed

Select the types of activity you want to include in your feed.

no benefit to having both a README and README.md -- D.R.Y.

Mark Borgerding 0a439404 478c35e6

-230
-230
README
··· 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 - kiss_fft_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 - Q15 short or Q31 samples. The default is float. 45 - 46 - BUILDING: 47 - 48 - There are two functionally-equivalent build systems supported by kissfft: 49 - 50 - * Make (traditional Makefiles for Unix / Linux systems) 51 - * CMake (more modern and feature-rich build system developed by Kitware) 52 - 53 - To build kissfft, the following build environment can be used: 54 - 55 - * GNU build environment with GCC, Clang and GNU Make or CMake (>= 3.6) 56 - * Microsoft Visual C++ (MSVC) with CMake (>= 3.6) 57 - 58 - Additional libraries required to build and test kissfft include: 59 - 60 - * libpng for psdpng tool, 61 - * libfftw3 to validate kissfft results against it, 62 - * python 2/3 with Numpy to validate kissfft results against it. 63 - * OpenMP supported by GCC, Clang or MSVC for multi-core FFT transformations 64 - 65 - Environments like Cygwin and MinGW can be highly likely used to build kissfft 66 - targeting Windows platform, but no tests were performed to the date. 67 - 68 - Both Make and CMake builds are easily configurable: 69 - 70 - * 'KISSFFT_DATATYPE=<datatype>' (for Make) or '-DKISSFFT_DATATYPE=<datatype>' 71 - (for CMake) denote the principal datatype used by kissfft. It can be one 72 - of the following: 73 - 74 - * float (default) 75 - * double 76 - * int16_t 77 - * int32_t 78 - * SIMD (requires SSE instruction set support on target CPU) 79 - 80 - * 'KISSFFT_OPENMP=1' (for Make) or '-DKISSFFT_OPENMP=ON' (for CMake) builds kissfft 81 - with OpenMP support. Please note that a supported compiler is required and this 82 - option is turned off by default. 83 - 84 - * 'KISSFFT_STATIC=1' (for Make) or '-DKISSFFT_STATIC=ON' (for CMake) instructs 85 - the builder to create static library ('.lib' for Windows / '.a' for Unix or Linux). 86 - By default, this option is turned off and the shared library is created 87 - ('.dll' for Windows, '.so' for Linux or Unix, '.dylib' for Mac OSX) 88 - 89 - * '-DKISSFFT_TEST=OFF' (for CMake) disables building tests for kissfft. On Make, 90 - building tests is done separately by 'make testall' or 'make testsingle', so 91 - no specific setting is required. 92 - 93 - * 'KISSFFT_TOOLS=0' (for Make) or '-DKISSFFT_TOOLS=OFF' (for CMake) builds kissfft 94 - without command-line tools like 'fastconv'. By default the tools are built. 95 - 96 - * 'KISSFFT_USE_ALLOCA=1' (for Make) or '-DKISSFFT_USE_ALLOCA=ON' (for CMake) 97 - build kissfft with 'alloca' usage instead of 'malloc' / 'free'. 98 - 99 - * "PREFIX=/full/path/to/installation/prefix/directory" (for Make) or 100 - "-DCMAKE_INSTALL_PREFIX=/full/path/to/installation/prefix/directory' (for CMake) 101 - specifies the prefix directory to install kissfft into. 102 - 103 - For example, to build kissfft as a static library with 'int16_t' datatype and 104 - OpenMP support using Make, run the command from kissfft source tree: 105 - 106 - make KISSFFT_DATATYPE=int16_t KISSFFT_STATIC=1 KISSFFT_OPENMP=1 all 107 - 108 - The same configuration for CMake is: 109 - 110 - mkdir build && cd build 111 - cmake -DKISSFFT_DATATYPE=int16_t -DKISSFFT_STATIC=ON -DKISSFFT_OPENMP=ON .. 112 - make all 113 - 114 - To specify '/tmp/1234' as installation prefix directory, run: 115 - 116 - make PREFIX=/tmp/1234 KISSFFT_DATATYPE=int16_t KISSFFT_STATIC=1 KISSFFT_OPENMP=1 install 117 - 118 - or 119 - 120 - mkdir build && cd build 121 - cmake -DCMAKE_INSTALL_PREFIX=/tmp/1234 -DKISSFFT_DATATYPE=int16_t -DKISSFFT_STATIC=ON -DKISSFFT_OPENMP=ON .. 122 - make all 123 - make install 124 - 125 - TESTING: 126 - 127 - To validate the build configured as an example above, run the following command from 128 - kissfft source tree: 129 - 130 - make KISSFFT_DATATYPE=int16_t KISSFFT_STATIC=1 KISSFFT_OPENMP=1 testsingle 131 - 132 - if using Make, or: 133 - 134 - make test 135 - 136 - if using CMake. 137 - 138 - To test all possible build configurations, please run an extended testsuite from 139 - kissfft source tree: 140 - 141 - sh test/kissfft-testsuite.sh 142 - 143 - Please note that the extended testsuite takes around 20-40 minutes depending on device 144 - it runs on. This testsuite is useful for reporting bugs or testing the pull requests. 145 - 146 - BACKGROUND: 147 - 148 - I started coding this because I couldn't find a fixed point FFT that didn't 149 - use assembly code. I started with floating point numbers so I could get the 150 - theory straight before working on fixed point issues. In the end, I had a 151 - little bit of code that could be recompiled easily to do ffts with short, float 152 - or double (other types should be easy too). 153 - 154 - Once I got my FFT working, I was curious about the speed compared to 155 - a well respected and highly optimized fft library. I don't want to criticize 156 - this great library, so let's call it FFT_BRANDX. 157 - During this process, I learned: 158 - 159 - 1. FFT_BRANDX has more than 100K lines of code. The core of kiss_fft is about 500 lines (cpx 1-d). 160 - 2. It took me an embarrassingly long time to get FFT_BRANDX working. 161 - 3. A simple program using FFT_BRANDX is 522KB. A similar program using kiss_fft is 18KB (without optimizing for size). 162 - 4. FFT_BRANDX is roughly twice as fast as KISS FFT in default mode. 163 - 164 - It is wonderful that free, highly optimized libraries like FFT_BRANDX exist. 165 - But such libraries carry a huge burden of complexity necessary to extract every 166 - last bit of performance. 167 - 168 - Sometimes simpler is better, even if it's not better. 169 - 170 - FREQUENTLY ASKED QUESTIONS: 171 - Q: Can I use kissfft in a project with a ___ license? 172 - A: Yes. See LICENSE below. 173 - 174 - Q: Why don't I get the output I expect? 175 - A: The two most common causes of this are 176 - 1) scaling : is there a constant multiplier between what you got and what you want? 177 - 2) mixed build environment -- all code must be compiled with same preprocessor 178 - definitions for FIXED_POINT and kiss_fft_scalar 179 - 180 - Q: Will you write/debug my code for me? 181 - A: Probably not unless you pay me. I am happy to answer pointed and topical questions, but 182 - I may refer you to a book, a forum, or some other resource. 183 - 184 - 185 - PERFORMANCE: 186 - (on Athlon XP 2100+, with gcc 2.96, float data type) 187 - 188 - Kiss performed 10000 1024-pt cpx ffts in .63 s of cpu time. 189 - For comparison, it took md5sum twice as long to process the same amount of data. 190 - 191 - Transforming 5 minutes of CD quality audio takes less than a second (nfft=1024). 192 - 193 - DO NOT: 194 - ... use Kiss if you need the Fastest Fourier Transform in the World 195 - ... ask me to add features that will bloat the code 196 - 197 - UNDER THE HOOD: 198 - 199 - Kiss FFT uses a time decimation, mixed-radix, out-of-place FFT. If you give it an input buffer 200 - and output buffer that are the same, a temporary buffer will be created to hold the data. 201 - 202 - No static data is used. The core routines of kiss_fft are thread-safe (but not all of the tools directory). 203 - 204 - No scaling is done for the floating point version (for speed). 205 - Scaling is done both ways for the fixed-point version (for overflow prevention). 206 - 207 - Optimized butterflies are used for factors 2,3,4, and 5. 208 - 209 - The real (i.e. not complex) optimization code only works for even length ffts. It does two half-length 210 - FFTs in parallel (packed into real&imag), and then combines them via twiddling. The result is 211 - nfft/2+1 complex frequency bins from DC to Nyquist. If you don't know what this means, search the web. 212 - 213 - The fast convolution filtering uses the overlap-scrap method, slightly 214 - modified to put the scrap at the tail. 215 - 216 - LICENSE: 217 - Revised BSD License, see COPYING for verbiage. 218 - Basically, "free to use&change, give credit where due, no guarantees" 219 - Note this license is compatible with GPL at one end of the spectrum and closed, commercial software at 220 - the other end. See http://www.fsf.org/licensing/licenses 221 - 222 - TODO: 223 - *) Add real optimization for odd length FFTs 224 - *) Document/revisit the input/output fft scaling 225 - *) Make doc describing the overlap (tail) scrap fast convolution filtering in kiss_fastfir.c 226 - *) Test all the ./tools/ code with fixed point (kiss_fastfir.c doesn't work, maybe others) 227 - 228 - AUTHOR: 229 - Mark Borgerding 230 - Mark@Borgerding.net