mirror/kissfft
1
0
Fork 0
mirror of https://github.com/mborgerding/kissfft.git synced 2025-12-01 23:12:49 -05:00
Code Issues Packages Projects Releases Wiki Activity

Fix up README.md

Browse Source
This commit is contained in:
Martin Rys
2025-11-28 20:24:49 +01:00
committed by Martin
parent 3573584192
commit e47824731e
1 changed files with 42 additions and 42 deletions
Download Patch File Download Diff File Expand all files Collapse all files

84
README.md
View File

@ -1,11 +1,11 @@
# KISS FFT [![Build Status](https://travis-ci.com/mborgerding/kissfft.svg?branch=master)](https://travis-ci.com/mborgerding/kissfft)
KISS FFT - A mixed-radix Fast Fourier Transform based up on the principle,
KISS FFT - A mixed-radix Fast Fourier Transform based up on the principle,
"Keep It Simple, Stupid."
There are many great fft libraries already around. Kiss FFT is not trying
to be better than any of them. It only attempts to be a reasonably efficient,
moderately useful FFT that can use fixed or floating data types and can be
to be better than any of them. It only attempts to be a reasonably efficient,
moderately useful FFT that can use fixed or floating data types and can be
incorporated into someone's C program in a few minutes with trivial licensing.
## USAGE:
@ -16,27 +16,27 @@ The basic usage for 1-d complex FFT is:
#include "kiss_fft.h"
kiss_fft_cfg cfg = kiss_fft_alloc( nfft ,is_inverse_fft ,0,0 );
while ...
... // put kth sample in cx_in[k].r and cx_in[k].i
kiss_fft( cfg , cx_in , cx_out );
... // transformed. DC is in cx_out[0].r and cx_out[0].i
... // transformed. DC is in cx_out[0].r and cx_out[0].i
kiss_fft_free(cfg);
```
- **Note**: frequency-domain data is stored from dc up to 2pi.
so cx_out[0] is the dc bin of the FFT
and cx_out[nfft/2] is the Nyquist bin (if exists)
Declarations are in "kiss_fft.h", along with a brief description of the
functions you'll need to use.
Declarations are in "kiss_fft.h", along with a brief description of the
functions you'll need to use.
Code definitions for 1d complex FFTs are in kiss_fft.c.
You can do other cool stuff with the extras you'll find in tools/
> - multi-dimensional FFTs
> - real-optimized FFTs (returns the positive half-spectrum:
> - multi-dimensional FFTs
> - real-optimized FFTs (returns the positive half-spectrum:
(nfft/2+1) complex frequency bins)
> - fast convolution FIR filtering (not available for fixed point)
> - spectrum image creation
@ -53,17 +53,17 @@ There are two functionally-equivalent build systems supported by kissfft:
To build kissfft, the following build environment can be used:
- GNU build environment with GCC, Clang and GNU Make or CMake (>= 3.6)
- Microsoft Visual C++ (MSVC) with CMake (>= 3.6)
- GNU build environment with GCC, Clang and GNU Make or CMake (>= 3.10)
- Microsoft Visual C++ (MSVC) with CMake (>= 3.10)
Additional libraries required to build and test kissfft include:
- libpng for psdpng tool,
- libfftw3 to validate kissfft results against it,
- python 2/3 with Numpy to validate kissfft results against it.
- Python 3 with Numpy to validate kissfft results against it.
- OpenMP supported by GCC, Clang or MSVC for multi-core FFT transformations
While no tests have been performed to date, kissfft can likely be built using
While no tests have been performed to date, kissfft can likely be built using
environments like Cygwin and MinGW when targeting the Windows platform.
Both Make and CMake builds are easily configurable:
@ -104,13 +104,13 @@ Both Make and CMake builds are easily configurable:
For example, to build kissfft as a static library with 'int16_t' datatype and
OpenMP support using Make, run the command from kissfft source tree:
```
```bash
make KISSFFT_DATATYPE=int16_t KISSFFT_STATIC=1 KISSFFT_OPENMP=1 all
```
The same configuration for CMake is:
```
```bash
mkdir build && cd build
cmake -DKISSFFT_DATATYPE=int16_t -DKISSFFT_STATIC=ON -DKISSFFT_OPENMP=ON ..
make all
@ -119,13 +119,13 @@ make all
To specify '/tmp/1234' as installation prefix directory, run:
```
```bash
make PREFIX=/tmp/1234 KISSFFT_DATATYPE=int16_t KISSFFT_STATIC=1 KISSFFT_OPENMP=1 install
```
or
```
```bash
mkdir build && cd build
cmake -DCMAKE_INSTALL_PREFIX=/tmp/1234 -DKISSFFT_DATATYPE=int16_t -DKISSFFT_STATIC=ON -DKISSFFT_OPENMP=ON ..
make all
@ -137,13 +137,13 @@ make install
To validate the build configured as an example above, run the following command from
kissfft source tree:
```
```bash
make KISSFFT_DATATYPE=int16_t KISSFFT_STATIC=1 KISSFFT_OPENMP=1 testsingle
```
if using Make, or:
```
```bash
make test
```
@ -152,7 +152,7 @@ if using CMake.
To test all possible build configurations, please run an extended testsuite from
kissfft source tree:
```
```bash
sh test/kissfft-testsuite.sh
```
@ -161,14 +161,14 @@ it runs on. This testsuite is useful for reporting bugs or testing the pull requ
## BACKGROUND
I started coding this because I couldn't find a fixed point FFT that didn't
use assembly code. I started with floating point numbers so I could get the
theory straight before working on fixed point issues. In the end, I had a
I started coding this because I couldn't find a fixed point FFT that didn't
use assembly code. I started with floating point numbers so I could get the
theory straight before working on fixed point issues. In the end, I had a
little bit of code that could be recompiled easily to do ffts with short, float
or double (other types should be easy too).
or double (other types should be easy too).
Once I got my FFT working, I was curious about the speed compared to
a well respected and highly optimized fft library. I don't want to criticize
a well respected and highly optimized fft library. I don't want to criticize
this great library, so let's call it FFT_BRANDX.
During this process, I learned:
@ -178,7 +178,7 @@ During this process, I learned:
> 4. FFT_BRANDX is roughly twice as fast as KISS FFT in default mode.
It is wonderful that free, highly optimized libraries like FFT_BRANDX exist.
But such libraries carry a huge burden of complexity necessary to extract every
But such libraries carry a huge burden of complexity necessary to extract every
last bit of performance.
**Sometimes simpler is better, even if it's not better.**
@ -190,11 +190,11 @@ last bit of performance.
> Q: Why don't I get the output I expect?</br>
> A: The two most common causes of this are
> 1) scaling : is there a constant multiplier between what you got and what you want?
> 2) mixed build environment -- all code must be compiled with same preprocessor
> 2) mixed build environment -- all code must be compiled with same preprocessor
> definitions for FIXED_POINT and kiss_fft_scalar
> Q: Will you write/debug my code for me?</br>
> A: Probably not unless you pay me. I am happy to answer pointed and topical questions, but
> A: Probably not unless you pay me. I am happy to answer pointed and topical questions, but
> I may refer you to a book, a forum, or some other resource.
@ -203,7 +203,7 @@ last bit of performance.
Kiss performed 10000 1024-pt cpx ffts in .63 s of cpu time.
For comparison, it took md5sum twice as long to process the same amount of data.
Transforming 5 minutes of CD quality audio takes less than a second (nfft=1024).
Transforming 5 minutes of CD quality audio takes less than a second (nfft=1024).
**DO NOT:**
- use Kiss if you need the Fastest Fourier Transform in the World
@ -211,31 +211,31 @@ Transforming 5 minutes of CD quality audio takes less than a second (nfft=1024).
## UNDER THE HOOD
Kiss FFT uses a time decimation, mixed-radix, out-of-place FFT. If you give it an input buffer
Kiss FFT uses a time decimation, mixed-radix, out-of-place FFT. If you give it an input buffer<br>
and output buffer that are the same, a temporary buffer will be created to hold the data.
No static data is used. The core routines of kiss_fft are thread-safe (but not all of the tools directory).[
No static data is used. The core routines of kiss_fft are thread-safe (but not all of the tools directory).
No scaling is done for the floating point version (for speed).
No scaling is done for the floating point version (for speed).<br>
Scaling is done both ways for the fixed-point version (for overflow prevention).
Optimized butterflies are used for factors 2,3,4, and 5.
Optimized butterflies are used for factors 2,3,4, and 5.
The real (i.e. not complex) optimization code only works for even length ffts. It does two half-length
FFTs in parallel (packed into real&imag), and then combines them via twiddling. The result is
FFTs in parallel (packed into real&imag), and then combines them via twiddling. The result is
nfft/2+1 complex frequency bins from DC to Nyquist. If you don't know what this means, search the web.
The fast convolution filtering uses the overlap-scrap method, slightly
The fast convolution filtering uses the overlap-scrap method, slightly
modified to put the scrap at the tail.
## LICENSE
Revised BSD License, see COPYING for verbiage.
Revised BSD License, see COPYING for verbiage.
Basically, "free to use&change, give credit where due, no guarantees"
Note this license is compatible with GPL at one end of the spectrum and closed, commercial software at
Note this license is compatible with GPL at one end of the spectrum and closed, commercial software at
the other end. See http://www.fsf.org/licensing/licenses
## TODO
- Add real optimization for odd length FFTs
- Add real optimization for odd length FFTs
- Document/revisit the input/output fft scaling
- Make doc describing the overlap (tail) scrap fast convolution filtering in kiss_fastfir.c
- Test all the ./tools/ code with fixed point (kiss_fastfir.c doesn't work, maybe others)