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                            (IMAGE *in,
                                                         IMAGE *out);
int                 im_invfft                           (IMAGE *in,
                                                         IMAGE *out);
int                 im_invfftr                          (IMAGE *in,
                                                         IMAGE *out);
int                 im_freqflt                          (IMAGE *in,
                                                         IMAGE *mask,
                                                         IMAGE *out);
int                 im_disp_ps                          (IMAGE *in,
                                                         IMAGE *out);
int                 im_rotquad                          (IMAGE *in,
                                                         IMAGE *out);
int                 im_phasecor_fft                     (IMAGE *in1,
                                                         IMAGE *in2,
                                                         IMAGE *out);
int                 im_flt_image_freq                   (IMAGE *in,
                                                         IMAGE *out,
                                                         VipsMaskType flag,
                                                         ...);
int                 im_create_fmask                     (IMAGE *out,
                                                         int xsize,
                                                         int ysize,
                                                         VipsMaskType flag,
                                                         ...);
int                 im_fractsurf                        (IMAGE *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                            (IMAGE *in,
                                                         IMAGE *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                           (IMAGE *in,
                                                         IMAGE *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                          (IMAGE *in,
                                                         IMAGE *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                          (IMAGE *in,
                                                         IMAGE *mask,
                                                         IMAGE *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                          (IMAGE *in,
                                                         IMAGE *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                          (IMAGE *in,
                                                         IMAGE *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                     (IMAGE *in1,
                                                         IMAGE *in2,
                                                         IMAGE *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                   (IMAGE *in,
                                                         IMAGE *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                     (IMAGE *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 6. 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                        (IMAGE *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