avila-fft

Pure Rust FFT library with zero dependencies - Fast Fourier Transform, Short-Time Fourier Transform (STFT), 2D FFT for images, spectral analysis, and digital filters.

Features

• ✅ Zero external dependencies - Pure Rust implementation
• ✅ Generic float support - Works with f32 and f64
• ✅ 1D FFT - Recursive and iterative in-place algorithms (10-40x faster)
• ✅ Real FFT (RFFT) - Optimized for real signals (~50% faster)
• ✅ 2D FFT - Row-column algorithm for images
• ✅ STFT/ISTFT - Short-Time Fourier Transform with overlap-add reconstruction
• ✅ Spectrogram - Time-frequency analysis with spectral features
• ✅ Window functions - Hamming, Hann, Blackman, Blackman-Harris, Bartlett
• ✅ Spatial filters - Ideal and Gaussian lowpass/highpass/bandpass
• ✅ Spectral analysis - Centroid, bandwidth, flatness, rolloff
• ✅ Scientific tests - 35+ tests validating correctness
• ✅ Benchmarks - Performance comparison suite

Quick Start

Add to your Cargo.toml:

[dependencies]
avila-fft = "0.1"

Basic FFT Example

use avila_fft::*;

fn main() {
    // Create input signal
    let input: Vec<Complex<f64>> = (0..8)
        .map(|i| Complex::new(i as f64, 0.0))
        .collect();

    // Fast FFT with planner (recommended)
    let planner = FftPlanner::new(8, false).unwrap();
    let output = planner.process(&input).unwrap();

    println!("FFT result: {:?}", output);
}

STFT Example

use avila_fft::timefreq::*;

fn main() {
    let sample_rate = 8192.0;
    let signal: Vec<f64> = (0..8192)
        .map(|i| {
            let t = i as f64 / sample_rate;
            (2.0 * std::f64::consts::PI * 440.0 * t).sin() // 440 Hz tone
        })
        .collect();

    // Configure STFT with 75% overlap
    let config = OverlapConfig::overlap_75(512);
    let processor = StftProcessor::new(config, WindowType::Hann).unwrap();
    
    // Compute spectrogram
    let spec = processor.process(&signal, sample_rate).unwrap();
    
    // Spectral features
    let centroid = spec.spectral_centroid();
    let bandwidth = spec.spectral_bandwidth();
    let flatness = spec.spectral_flatness();
    
    println!("Spectral centroid: {:?}", centroid);
}

2D FFT Example

use avila_fft::fft2d::*;

fn main() {
    // Create 8x8 image
    let data: Vec<f64> = (0..64).map(|i| i as f64).collect();
    let image = Image2D::from_real(8, 8, data).unwrap();
    
    // 2D FFT
    let freq = fft2d(&image).unwrap();
    
    // Apply Gaussian lowpass filter
    let sigma = 2.0;
    let filtered = GaussianFilter::lowpass(sigma).apply(&freq).unwrap();
    
    // Inverse FFT
    let result = ifft2d(&filtered).unwrap();
}

API Overview

Core FFT Functions

• fft() / ifft() - Recursive Cooley-Tukey algorithm
• FftPlanner - Iterative in-place FFT with twiddle factor caching (10-40x faster)
• rfft() / irfft() - Real FFT optimized for real signals

STFT Module (timefreq)

• StftProcessor - STFT/ISTFT processor with configurable overlap
• Spectrogram - Time-frequency representation with analysis methods
• OverlapConfig - Overlap configuration (50%, 75%, custom)
• WindowType - Window function selection

Spectral Analysis Methods

• spectral_centroid() - Center of mass of spectrum (brightness)
• spectral_bandwidth() - Dispersion around centroid
• spectral_flatness() - Tonality vs noise (0=tonal, 1=noise)
• spectral_rolloff(%) - Frequency below which X% of energy lies

2D FFT Module (fft2d)

• Image2D - 2D complex image structure
• fft2d() / ifft2d() - 2D FFT using row-column algorithm
• Fft2DPlanner - Cached 2D FFT planner
• IdealFilter - Ideal lowpass/highpass/bandpass/bandreject filters
• GaussianFilter - Smooth Gaussian filters (no ringing)
• convolve2d() - 2D convolution via FFT

Window Functions (window)

• hann() - Hann window (good frequency resolution)
• hamming() - Hamming window (reduced sidelobes)
• blackman() - Blackman window (excellent sidelobe suppression)
• blackman_harris() - 4-term Blackman-Harris (best sidelobe suppression)
• bartlett() - Bartlett (triangular) window
• rectangular() - Rectangular (no windowing)

Examples

Run the included examples:

# Spectral analysis with windowing
cargo run --release --example spectral_analysis

# Performance benchmark
cargo run --release --example benchmark

# Image processing with 2D FFT
cargo run --release --example image_processing

# Audio analysis with STFT
cargo run --release --example audio_analysis

Performance

Benchmarks on Intel Core i7 (N=1024):

The iterative in-place algorithm with twiddle factor caching is 10-40x faster than the recursive implementation.

Testing

Run all tests:

cargo test

Run benchmarks:

cargo test --release -- --ignored bench

Scientific Correctness

All algorithms are validated with rigorous scientific tests:

• ✅ Parseval's theorem - Energy conservation (error < 1e-15)
• ✅ Reversibility - Perfect reconstruction (RMS error < 1e-16)
• ✅ Linearity - Linear transform property
• ✅ Separability - 2D FFT via 1D transforms
• ✅ Hermitian symmetry - Real signals produce conjugate-symmetric spectra
• ✅ STFT reversibility - ISTFT reconstruction (SNR > 300 dB)

Zero Dependencies

This library has zero external dependencies (only std). All algorithms are implemented from scratch in pure Rust for:

• ✅ Security and auditability
• ✅ Easy integration
• ✅ Minimal binary size
• ✅ Full control over implementation
• ✅ No dependency conflicts

Use Cases

• 🎵 Audio processing - Spectral analysis, pitch detection, effects
• 📷 Image processing - Frequency domain filtering, compression
• 📊 Signal analysis - Time-frequency analysis, spectrograms
• 🔬 Scientific computing - Fourier analysis, convolution
• 📡 Communications - Signal processing, modulation analysis
• 🎙️ Speech processing - Formant analysis, voice recognition

License

Licensed under either of:

• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)
• Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)

at your option.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Author

Nícolas Ávila - nicolas@avila.inc