@thi.ng/dsp/fft.d.ts

Composable signal generators, oscillators, filters, FFT, spectrum, windowing & related DSP utils

import type { FnN3, NumericArray } from "@thi.ng/api";
import type { ComplexArray } from "./api.js";
/**
 * Returns a new tuple of real/img F64 buffers of given size.
 *
 * @param n -
 */
export declare const complexArray: (n: number) => ComplexArray;
/**
 * Creates a deep copy of given {@link ComplexArray}.
 *
 * @param complex -
 */
export declare const copyComplex: (complex: ComplexArray) => ComplexArray;
/**
 * If given a {@link ComplexArray}, computes the complex conjugate, concatenates
 * it in mirrored order to input (excluding bin 0) and returns it as new
 * (complex) array.
 *
 * @remarks
 * The length of the input buffer(s) is assumed to be a power of 2.
 *
 * If given a
 * [`NumericArray`](https://docs.thi.ng/umbrella/api/types/NumericArray.html),
 * the `isImg` arg chooses from one of the following operations: If `true`
 * (default), returns new array with *negated* values concatenated in reverse
 * order. If `false`, returns new array with *original* values concatenated in
 * reverse order.
 *
 * @example
 * ```ts tangle:../export/conjugate1.ts
 * import { conjugate } from "@thi.ng/dsp";
 *
 * console.log(
 *   conjugate([0, 3, 2, 1], true)
 * );
 * // Float64Array [ 0, 3, 2, 1, 0, -1, -2, -3 ]
 *
 * console.log(
 *   conjugate([0, 3, 2, 1], false)
 * );
 * // Float64Array [ 0, 3, 2, 1, 0, 1, 2, 3 ]
 *
 * console.log(
 *   conjugate([[0, 1, 0, 1], [0, -0.5, 0, -0.25]])
 * );
 * // [
 * //   Float64Array [ 0, 1, 0, 1, 0, 1, 0, 1 ],
 * //   Float64Array [ 0, -0.5, 0, -0.25, 0, 0.25, 0, 0.5 ]
 * // ]
 * ```
 *
 * @example
 * ```ts tangle:../export/conjugate2.ts
 * import { conjugate, ifft } from "@thi.ng/dsp";
 *
 * // generate single-period sine (window size = 16)
 * console.log(
 *   ifft(conjugate([0, -8, 0, 0, 0, 0, 0, 0]))[0]
 * );
 * // [
 * //   0, 0.383, 0.707, 0.924,
 * //   1, 0.924, 0.707, 0.383,
 * //   0, -0.384, -0.707, -0.924,
 * //   -1, -0.924, -0.707, -0.383
 * // ]
 * ```
 *
 * @param src -
 * @param isImg -
 */
export declare function conjugate(src: NumericArray, isImg?: boolean): NumericArray;
export declare function conjugate(complex: ComplexArray): ComplexArray;
/**
 * Computes in-place forward FFT for given real/imaginary component
 * buffers (each MUST be pow2 length), optionally with windowing.
 *
 * @remarks
 * If `window` is given, the `real` array will be pre-multiplied with
 * the `window`.
 *
 * No result scaling / normalization is performed. Use
 * {@link normalizeFFT} for that purpose.
 *
 * - https://www.earlevel.com/main/2002/08/31/a-gentle-introduction-to-the-fft/
 * - https://www.earlevel.com/main/2019/04/30/waveutils-updated/
 * - https://betterexplained.com/articles/an-interactive-guide-to-the-fourier-transform/
 * - http://toxi.co.uk/p5/fftDebug/fft4amit.pde
 *
 * @param complex -
 * @param window -
 */
export declare const fft: (complex: NumericArray | ComplexArray, window?: NumericArray) => ComplexArray;
/**
 * Inverse FFT via computing forward transform with swapped real/imaginary
 * components. Expects denormalized inputs (i.e. the same as the result of
 * {@link fft}).
 *
 * @remarks
 *
 * - https://www.dsprelated.com/showarticle/800.php (method #3)
 *
 * @param complex -
 */
export declare const ifft: (src: NumericArray | ComplexArray) => ComplexArray;
export declare const scaleFFT: (complex: ComplexArray, scale: number) => ComplexArray;
/**
 * Normalizes the complex FFT array by scaling each complex bin value with given
 * scale factor (or, if given as array, the scale factor derived from these
 * window function samples).
 *
 * @remarks
 * By default assumes a rectangular window and the resulting scale factor of 2 /
 * N.
 *
 * Reference:
 * https://holometer.fnal.gov/GH_FFT.pdf
 *
 * @param complex -
 * @param window -
 */
export declare const normalizeFFT: (complex: ComplexArray, window?: number | NumericArray) => ComplexArray;
/**
 * Inverse operation of {@link normalizeFFT}. De-normalizes the complex FFT
 * array by scaling each complex bin value with given scale factor (or, if given
 * as array, the scale factor derived from these window function samples).
 *
 * @remarks
 * By default assumes a rectangular window and the resulting scale factor of N /
 * 2.
 *
 * Reference:
 * https://holometer.fnal.gov/GH_FFT.pdf
 *
 * @param complex -
 * @param window -
 */
export declare const denormalizeFFT: (complex: ComplexArray, window?: number | NumericArray) => ComplexArray;
/**
 * Computes the magnitude of each FFT bin and if less than given `eps`
 * threshold, sets that bin to zero. Returns input FFT array.
 *
 * @remarks
 * It's recommended to apply this function prior computing
 * {@link spectrumPhase}. The `eps` value might have to be adjusted and should
 * be approx. `max(spectrumMag(fft))/10000`.
 *
 * Reference:
 * https://www.gaussianwaves.com/2015/11/interpreting-fft-results-obtaining-magnitude-and-phase-information/
 *
 * @param complex -
 * @param eps -
 */
export declare const thresholdFFT: (complex: ComplexArray, eps?: number) => ComplexArray;
/**
 * Computes magnitude spectrum for given FFT: y(i) = abs(c(i)). By default only
 * the first N/2 values are returned.
 *
 * @param complex - FFT result
 * @param n - bin count
 * @param out - result array
 */
export declare const spectrumMag: (complex: ComplexArray, n?: number, out?: NumericArray) => NumericArray;
/**
 * Computes power spectrum (optionally as dBFS) for the given FFT result arrays
 * (length = N) and optional `window`. Writes result to `out` or a new array.
 *
 * @remarks
 * If `window` is given (scale factor or array), it will be used as (if number)
 * or to compute the scaling factor (if array) for each FFT bin's value. The
 * default (`window=1`) is the equivalent to a rectangular window (i.e. a
 * no-op). If windowing was used to compute the FFT, the same should be provided
 * to this function for correct results.
 *
 * **IMPORTANT:** If the FFT result has already been normalized using
 * {@link normalizeFFT}, the scaling factor (`window` arg) MUST be set 1.0.
 *
 * By default only the first N/2 values are returned. If `db` is true, the
 * spectrum values are converted to dBFS.
 *
 * - https://holometer.fnal.gov/GH_FFT.pdf
 * - https://dsp.stackexchange.com/a/32080
 * - https://dsp.stackexchange.com/a/14935
 * - https://www.kvraudio.com/forum/viewtopic.php?t=276092
 *
 * @param complex -
 * @param db -
 * @param window -
 * @param n -
 * @param out -
 */
export declare const spectrumPow: (complex: ComplexArray, db?: boolean, window?: number | NumericArray, n?: number, out?: NumericArray) => NumericArray;
/**
 * Computes phase spectrum for given FFT and writes results to `out`. By default
 * only the first N/2 values are returned.
 *
 * @remarks
 * Consider applying {@link thresholdFFT} prior to computing the phase spectrum
 * to avoid exploding floating point error magnitudes.
 *
 * @param complex - FFT result
 * @param n - bin count
 * @param out - result array
 */
export declare const spectrumPhase: (complex: ComplexArray, n?: number, out?: NumericArray) => NumericArray;
/**
 * Returns FFT bin index for given frequency, sample rate and window
 * size. See {@link binFreq} for reverse op.
 *
 * @param f - frequency
 * @param fs - sample rate
 * @param n - window size
 */
export declare const freqBin: FnN3;
/**
 * Returns frequency for given FFT bin index, sample rate and window
 * size. See {@link freqBin} for reverse op.
 *
 * @param bin - bin
 * @param fs - sample rate
 * @param n - window size
 */
export declare const binFreq: FnN3;
/**
 * Returns array of bin center frequencies for given FFT window size and sample
 * rate. By default only the first N/2+1 values are returned (`m` and including
 * 0Hz).
 *
 * @param n - window size
 * @param fs - sample rate
 * @param m - number of result values
 */
export declare const fftFreq: (n: number, fs: number, m?: number) => Float64Array<ArrayBuffer>;
//# sourceMappingURL=fft.d.ts.map