diff --git a/TODO b/TODO index 7f0968c4..cc397f8d 100644 --- a/TODO +++ b/TODO @@ -1,9 +1,10 @@ -- still to move to threadpool: im_iterate(), im_render(), maybe wait for - better performance numbers before we move them - nip2 image display does not work with threading disabled -- doing im_create_fmask() and friends +- writing docs for im_create_fmask() and friends + +- still to move to threadpool: im_iterate(), im_render(), maybe wait for + better performance numbers before we move them - try writing docs for vipsthumbnail with gtkdoc? then try header etc. diff --git a/benchmark/benchmarkn.sh b/benchmark/benchmarkn.sh index a2cff47e..903ee1a7 100755 --- a/benchmark/benchmarkn.sh +++ b/benchmark/benchmarkn.sh @@ -34,6 +34,9 @@ for cpus in 1 2 3 4 5 6 ; do echo time -p vips im_benchmarkn temp.v temp2.v $chain time -p vips im_benchmarkn temp.v temp2.v $chain time -p vips im_benchmarkn temp.v temp2.v $chain + echo time -p vips im_benchmarkn --vips-wbuffer2 temp.v temp2.v $chain + time -p vips im_benchmarkn --vips-wbuffer2 temp.v temp2.v $chain + time -p vips im_benchmarkn --vips-wbuffer2 temp.v temp2.v $chain if [ $? != 0 ]; then echo "benchmark failed -- install problem?" diff --git a/libvips/freq_filt/im_freq_mask.c b/libvips/freq_filt/im_freq_mask.c index d07fd3c8..b93df9e4 100644 --- a/libvips/freq_filt/im_freq_mask.c +++ b/libvips/freq_filt/im_freq_mask.c @@ -1,47 +1,12 @@ -/* @(#) Filter functions - * &(#) va_alist is a series of double variables - * @(#) - * @(#) Used to filter image in in the frequency domain, writes - * @(#) the result in image out - * @(#) - * @(#) int im_flt_image_freq( in, out, flag, num_args, va_alist ) - * @(#) IMAGE *in, *out; - * @(#) enum mask_type flag; - * @(#) int num_args; - * @(#) - * @(#) Returns 0 on success and -1 on error - * @(#) - * @(#) Creates a filter mask used for filtering in the frequency domain - * @(#) The resultant mask is held by image - * @(#) - * @(#) int im_create_fmask(image, xsize, ysize, flag, num_args, va_alist) - * @(#) IMAGE *image; - * @(#) int xsize, ysize; - * @(#) enum mask_type flag; - * @(#) int num_args; - * @(#) - * @(#) Returns 0 on success and -1 on error - * @(#) - * @(#) Creates a filter mask used for filtering in the frequency domain - * @(#) The resultant mask is held by image - * @(#) Function im_freq_mask() differs from im_create_fmask() in the last - * @(#) argument only: the latter accepts a va_dcl whereas the former - * @(#) accepts a va_list pointer pointing to the read arguments of va_dcl - * @(#) - * @(#) int im_freq_mask(image, xs, ys, flag, num_args, ap) - * @(#) IMAGE *image; - * @(#) int xs, ys; - * @(#) enum mask_type flag; - * @(#) int num_args; - * @(#) va_list ap; - * @(#) - * @(#) Returns 0 on success and -1 on error - * @(#) +/* Create masks and filter with them. + * * Copyright: N. Dessipris 1991, * Written on: Nov 1991 * Updated on: Dec 1991 * 20/9/95 JC * - modernised + * 22/3/10 + * - gtkdoc */ /* @@ -198,7 +163,19 @@ build_freq_mask( IMAGE *out, int xs, int ys, VipsMaskType flag, va_list ap ) return( 0 ); } -/* Create a mask, and filter an image with it. +/** + * im_flt_image_freq: + * @in: input image + * @out: output image + * @flag: mask type + * @Varargs: mask parameters + * + * Creates a mask (see im_create_fmask()) and filters an image with it (see + * im_freqflt()). + * + * See also: im_create_fmask(), im_freqflt(), + * + * Returns: 0 on success, -1 on error */ int im_flt_image_freq( IMAGE *in, IMAGE *out, VipsMaskType flag, ... ) @@ -222,7 +199,176 @@ im_flt_image_freq( IMAGE *in, IMAGE *out, VipsMaskType flag, ... ) return( 0 ); } -/* Create a filter mask. +/** + * im_create_fmask: + * @out: image to write to + * @xsize: image size + * @ysize: image size + * @flag: mask type + * @Varargs: mask parameters + * + * 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: + * + * + * 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(), + * + * Returns: 0 on success, -1 on error */ int im_create_fmask( IMAGE *out, int xsize, int ysize, VipsMaskType flag, ... ) diff --git a/libvips/freq_filt/im_phasecor_fft.c b/libvips/freq_filt/im_phasecor_fft.c index 286d2fb5..97c9d70f 100644 --- a/libvips/freq_filt/im_phasecor_fft.c +++ b/libvips/freq_filt/im_phasecor_fft.c @@ -46,15 +46,30 @@ #include #endif /*WITH_DMALLOC*/ -int im_phasecor_fft( IMAGE *in1, IMAGE *in2, IMAGE *out ){ - IMAGE *t[3]; +/** + * im_phasecor_fft: + * @in1: first input image + * @in2: second input image + * @out: output image + * + * Convert the two input images to Fourier space, calculate phase-correlation, + * back to real space. + * + * See also: im_fwfft(), im_cross_phase(), + * + * Returns: 0 on success, -1 on error + */ +int +im_phasecor_fft( IMAGE *in1, IMAGE *in2, IMAGE *out ) +{ + IMAGE *t[3]; - if( im_open_local_array( out, t, 3, "im_phasecor_fft", "p" ) || - im_fwfft( in1, t[0] ) || - im_fwfft( in2, t[1] ) || - im_cross_phase( t[0], t[1], t[2] ) || - im_invfftr( t[2], out ) ) - return -1; + if( im_open_local_array( out, t, 3, "im_phasecor_fft", "p" ) || + im_fwfft( in1, t[0] ) || + im_fwfft( in2, t[1] ) || + im_cross_phase( t[0], t[1], t[2] ) || + im_invfftr( t[2], out ) ) + return( -1 ); - return 0; + return( 0 ); }