## freq_filt

freq_filt — fourier transforms and frequency-domin filters

## Stability Level

Stable, unless otherwise indicated

## Synopsis

    #include <vips/vips.h>

    enum                VipsMaskType;
    int                 im_fwfft                            (VipsImage *in,
                                                             VipsImage *out);
    int                 im_invfft                           (VipsImage *in,
                                                             VipsImage *out);
    int                 im_invfftr                          (VipsImage *in,
                                                             VipsImage *out);
    int                 im_freqflt                          (VipsImage *in,
                                                             VipsImage *mask,
                                                             VipsImage *out);
    int                 im_disp_ps                          (VipsImage *in,
                                                             VipsImage *out);
    int                 im_rotquad                          (VipsImage *in,
                                                             VipsImage *out);
    int                 im_phasecor_fft                     (VipsImage *in1,
                                                             VipsImage *in2,
                                                             VipsImage *out);
    int                 im_flt_image_freq                   (VipsImage *in,
                                                             VipsImage *out,
                                                             VipsMaskType flag,
                                                             ...);
    int                 im_create_fmask                     (VipsImage *out,
                                                             int xsize,
                                                             int ysize,
                                                             VipsMaskType flag,
                                                             ...);
    int                 im_fractsurf                        (VipsImage *out,
                                                             int size,
                                                             double frd);

## Description

To and from Fourier space, filter in Fourier space, convert Fourier-space images to a displayable form.

## Details

### enum VipsMaskType

    typedef enum {
            VIPS_MASK_IDEAL_HIGHPASS = 0,
            VIPS_MASK_IDEAL_LOWPASS = 1,
            VIPS_MASK_BUTTERWORTH_HIGHPASS = 2,
            VIPS_MASK_BUTTERWORTH_LOWPASS = 3,
            VIPS_MASK_GAUSS_HIGHPASS = 4,
            VIPS_MASK_GAUSS_LOWPASS = 5,

            VIPS_MASK_IDEAL_RINGPASS = 6,
            VIPS_MASK_IDEAL_RINGREJECT = 7,
            VIPS_MASK_BUTTERWORTH_RINGPASS = 8,
            VIPS_MASK_BUTTERWORTH_RINGREJECT = 9,
            VIPS_MASK_GAUSS_RINGPASS = 10,
            VIPS_MASK_GAUSS_RINGREJECT = 11,

            VIPS_MASK_IDEAL_BANDPASS = 12,
            VIPS_MASK_IDEAL_BANDREJECT = 13,
            VIPS_MASK_BUTTERWORTH_BANDPASS = 14,
            VIPS_MASK_BUTTERWORTH_BANDREJECT = 15,
            VIPS_MASK_GAUSS_BANDPASS = 16,
            VIPS_MASK_GAUSS_BANDREJECT = 17,

            VIPS_MASK_FRACTAL_FLT = 18
    } VipsMaskType;

### im_fwfft ()

    int                 im_fwfft                            (VipsImage *in,
                                                             VipsImage *out);

Transform an image to Fourier space.

VIPS uses the fftw3 or fftw2 Fourier transform libraries if possible. If they were not available when VIPS was built, it falls back to it's own FFT functions which are slow and only work for square images whose sides are a power of two.

See also: `im_invfft()`, `im_disp_ps()`.

`in` : | input image
`out` : | output image
Returns : | 0 on success, -1 on error.

### im_invfft ()

    int                 im_invfft                           (VipsImage *in,
                                                             VipsImage *out);

Transform an image from Fourier space to real space. The result is complex. If you are OK with a real result, use `im_invfftr()` instead, it's quicker.

VIPS uses the fftw3 or fftw2 Fourier transform libraries if possible. If they were not available when VIPS was built, it falls back to it's own FFT functions which are slow and only work for square images whose sides are a power of two.

See also: `im_invfftr()`, `im_fwfft()`, `im_disp_ps()`.

`in` : | input image
`out` : | output image
Returns : | 0 on success, -1 on error.

### im_invfftr ()

    int                 im_invfftr                          (VipsImage *in,
                                                             VipsImage *out);

Transform an image from Fourier space to real space, giving a real result. This is faster than `im_invfft()`, which gives a complex result.

VIPS uses the fftw3 or fftw2 Fourier transform libraries if possible. If they were not available when VIPS was built, it falls back to it's own FFT functions which are slow and only work for square images whose sides are a power of two.

See also: `im_invfft()`, `im_fwfft()`, `im_disp_ps()`.

`in` : | input image
`out` : | output image
Returns : | 0 on success, -1 on error.

### im_freqflt ()

    int                 im_freqflt                          (VipsImage *in,
                                                             VipsImage *mask,
                                                             VipsImage *out);

Filter an image in Fourier space.

`in` is transformed to Fourier space, multipled with the mask image, then transformed back to real space. If `in` is already a complex image, just multiply then inverse transform.

See also: `im_invfftr()`, `im_create_fmask()`.

`in` : | input image
`mask` : | mask image
`out` : | output image
Returns : | 0 on success, -1 on error.

### im_disp_ps ()

    int                 im_disp_ps                          (VipsImage *in,
                                                             VipsImage *out);

Make a displayable (ie. 8-bit unsigned int) power spectrum.

If `in` is non-complex, it is transformed to Fourier space. Then the absolute value is passed through `im_scaleps()`, and `im_rotquad()`.

See also: `im_scaleps()`, `im_rotquad()`.

`in` : | input image
`out` : | output image
Returns : | 0 on success, -1 on error.

### im_rotquad ()

    int                 im_rotquad                          (VipsImage *in,
                                                             VipsImage *out);

Rotate the quadrants of the image so that the point that was at the top-left is now in the centre. Handy for moving Fourier images to optical space.

See also: `im_wrap()`.

`in` : | input image
`out` : | output image
Returns : | 0 on success, -1 on error

### im_phasecor_fft ()

    int                 im_phasecor_fft                     (VipsImage *in1,
                                                             VipsImage *in2,
                                                             VipsImage *out);

Convert the two input images to Fourier space, calculate phase-correlation, back to real space.

See also: `im_fwfft()`, `im_cross_phase()`,

`in1` : | first input image
`in2` : | second input image
`out` : | output image
Returns : | 0 on success, -1 on error

### im_flt_image_freq ()

    int                 im_flt_image_freq                   (VipsImage *in,
                                                             VipsImage *out,
                                                             VipsMaskType flag,
                                                             ...);

Creates a mask (see `im_create_fmask()`) and filters an image with it (see `im_freqflt()`).

See also: `im_create_fmask()`, `im_freqflt()`,

`in` : | input image
`out` : | output image
`flag` : | mask type
`...` : | mask parameters
Returns : | 0 on success, -1 on error

### im_create_fmask ()

    int                 im_create_fmask                     (VipsImage *out,
                                                             int xsize,
                                                             int ysize,
                                                             VipsMaskType flag,
                                                             ...);

This operation creates a one-band float image of the specified size. The image must be square, and the sides must be a power of two. The image has values in the range [0, 1] and is typically used for multiplying against frequency domain images to filter them.

All masks are created with the DC component at (0, 0), so you might want to rotate the quadrants with `im_rotquad()` before viewing. The DC pixel always has the value 1.0.

The value of `flag` sets the type pf mask created, and extra parameters set the exact mask shape. All extra parameters are doubles. This table summarises the possible values:

Table 5. Parameters for `im_create_fmask()`

VipsMaskType | nargs | Parameters (all double)
--- | --- | ---
VIPS_MASK_IDEAL_HIGHPASS | 1 | frequency_cutoff
VIPS_MASK_IDEAL_LOWPASS | 1 | frequency_cutoff
VIPS_MASK_BUTTERWORTH_HIGHPASS | 3 | order, frequency_cutoff, amplitude_cutoff
VIPS_MASK_BUTTERWORTH_LOWPASS | 3 | order, frequency_cutoff, amplitude_cutoff
VIPS_MASK_GAUSS_HIGHPASS | 2 | frequency_cutoff, amplitude_cutoff
VIPS_MASK_GAUSS_LOWPASS | 2 | frequency_cutoff, amplitude_cutoff
VIPS_MASK_IDEAL_RINGPASS | 2 | frequency_cutoff, width
VIPS_MASK_IDEAL_RINGREJECT | 2 | frequency_cutoff, width
VIPS_MASK_BUTTERWORTH_RINGPASS | 4 | order, frequency_cutoff, width, amplitude_cutoff
VIPS_MASK_BUTTERWORTH_RINGREJECT | 4 | order, frequency_cutoff, width, amplitude_cutoff
VIPS_MASK_GAUSS_RINGPASS | 3 | frequency_cutoff, width, amplitude_cutoff
VIPS_MASK_GAUSS_RINGREJECT | 3 | frequency_cutoff, width, amplitude_cutoff
VIPS_MASK_IDEAL_BANDPASS | 3 | frequency_cutoffx, frequency_cutoffy, radius
VIPS_MASK_IDEAL_BANDREJECT | 3 | frequency_cutoffx, frequency_cutoffy, radius
VIPS_MASK_BUTTERWORTH_BANDPASS | 5 | order, frequency_cutoffx, frequency_cutoffy, radius, amplitude_cutoff
VIPS_MASK_BUTTERWORTH_BANDREJECT | 5 | order, frequency_cutoffx, frequency_cutoffy, radius, amplitude_cutoff
VIPS_MASK_GAUSS_BANDPASS | 4 | frequency_cutoffx, frequency_cutoffy, radius, amplitude_cutoff
VIPS_MASK_GAUSS_BANDREJECT | 4 | frequency_cutoffx, frequency_cutoffy, radius, amplitude_cutoff
VIPS_MASK_FRACTAL_FLT | 1 | fractal_dimension

Unless noted below, all parameters are expressed as percentages, scaled to [0, 1].

High-pass, low-pass masks: A high pass filter mask filters the low frequencies while allowing the high frequencies to get through. The reverse happens with a low pass filter mask.

Ring-pass, ring-reject masks: A ring filter passes or rejects a range of frequencies. The range is specified by the `frequency_cutoff` and the `width`.

Band-pass, band-reject masks: These masks are used to pass or remove spatial frequencies around a given frequency. The position of the frequency to pass or remove is given by `frequency_cutoffx` and `frequency_cutoffy`. The size of the region around the point is given by `radius`.

Ideal filters: These filters pass or reject frequencies with a sharp cutoff at the transition.

Butterworth filters: These filters use a Butterworth function to separate the frequencies (see Gonzalez and Wintz, Digital Image Processing, 1987). The shape of the curve is controlled by `order`: higher values give a sharper transition.

Gaussian filters: These filters have a smooth Gaussian shape, controlled by `amplitude_cutoff`.

VIPS_MASK_FRACTAL_FLT: This mask is handy for filtering images of gaussian noise in order to create surfaces of a given fractal dimension. `fractal_dimension` should be between 2 and 3.

See also: `im_flt_image_freq()`, `im_rotquad()`,

`out` : | image to write to
`xsize` : | image size
`ysize` : | image size
`flag` : | mask type
`...` : | mask parameters
Returns : | 0 on success, -1 on error

### im_fractsurf ()

    int                 im_fractsurf                        (VipsImage *out,
                                                             int size,
                                                             double frd);

Generate an image of size `size` and fractal dimension `frd`. The dimension should be between 2 and 3.

See also: `im_gaussnoise()`, `im_flt_image_freq()`.

`out` : | output image
`size` : | size of image to generate
`frd` : | fractal dimension
Returns : | 0 on success, -1 on error.

## See Also

image