convolution

convolution — convolve and correlate images

Stability Level

Stable, unless otherwise indicated

Synopsis

#include <vips/vips.h>

enum                VipsPrecision;
enum                VipsCombine;
int                 vips_conv                           (VipsImage *in,
                                                         VipsImage **out,
                                                         VipsImage *mask,
                                                         ...);
int                 vips_compass                        (VipsImage *in,
                                                         VipsImage **out,
                                                         VipsImage *mask,
                                                         ...);
int                 vips_convsep                        (VipsImage *in,
                                                         VipsImage **out,
                                                         VipsImage *mask,
                                                         ...);
int                 vips_sharpen                        (VipsImage *in,
                                                         VipsImage **out,
                                                         ...);
int                 vips_gaussblur                      (VipsImage *in,
                                                         VipsImage **out,
                                                         int radius,
                                                         ...);

Description

These operations convolve an image in some way, or are operations based on simple convolution, or are useful with convolution.

Details

enum VipsPrecision

typedef enum {
	VIPS_PRECISION_INTEGER,
	VIPS_PRECISION_FLOAT,
	VIPS_PRECISION_APPROXIMATE,
	VIPS_PRECISION_LAST
} VipsPrecision;

How accurate an operation should be.

VIPS_PRECISION_INTEGER

int everywhere

VIPS_PRECISION_FLOAT

float everywhere

VIPS_PRECISION_APPROXIMATE

approximate integer output

VIPS_PRECISION_LAST


enum VipsCombine

typedef enum {
	VIPS_COMBINE_MAX,
	VIPS_COMBINE_SUM,
	VIPS_COMBINE_LAST
} VipsCombine;

VIPS_COMBINE_MAX

VIPS_COMBINE_SUM

VIPS_COMBINE_LAST


vips_conv ()

int                 vips_conv                           (VipsImage *in,
                                                         VipsImage **out,
                                                         VipsImage *mask,
                                                         ...);

Optional arguments:

precision: calculation accuracy layers: number of layers for approximation cluster: cluster lines closer than this distance

Convolution.

Perform a convolution of in with mask. Each output pixel is calculated as sigma[i]{pixel[i] * mask[i]} / scale + offset, where scale and offset are part of mask.

If precision is VIPS_PRECISION_INTEGER then the convolution is performed with integer arithmetic and the output image always has the same VipsBandFmt as the input image.

Convolutions on unsigned 8-bit images are calculated with the processor's vector unit, if possible. Disable this with --vips-novector or IM_NOVECTOR.

If precision is VIPS_PRECISION_FLOAT then the convolution is performed with floating-point arithmetic. The output image is always VIPS_FORMAT_FLOAT unless in is VIPS_FORMAT_DOUBLE, in which case out is also VIPS_FORMAT_DOUBLE.

If precision is VIPS_PRECISION_APPROXIMATE then the output image always has the same VipsBandFmt as the input image.

Larger values for layers give more accurate results, but are slower. As layers approaches the mask radius, the accuracy will become close to exact convolution and the speed will drop to match. For many large masks, such as Gaussian, n_layers need be only 10% of this value and accuracy will still be good.

Smaller values of cluster will give more accurate results, but be slower and use more memory. 10% of the mask radius is a good rule of thumb.

in :

input image

out :

output image

mask :

convolve with this mask

... :

NULL-terminated list of optional named arguments

Returns :

0 on success, -1 on error

vips_compass ()

int                 vips_compass                        (VipsImage *in,
                                                         VipsImage **out,
                                                         VipsImage *mask,
                                                         ...);


vips_convsep ()

int                 vips_convsep                        (VipsImage *in,
                                                         VipsImage **out,
                                                         VipsImage *mask,
                                                         ...);

Optional arguments:

precision: calculation accuracy layers: number of layers for approximation cluster: cluster lines closer than this distance

Perform a separable convolution of in with mask. See vips_conv() for a detailed description.

The mask must be 1xn or nx1 elements.

The image is convolved twice: once with mask and then again with mask rotated by 90 degrees. This is much faster for certain types of mask (gaussian blur, for example) than doing a full 2D convolution.

See also: vips_conv(), vips_gaussmat().

in :

input image

out :

output image

mask :

convolution mask

Returns :

0 on success, -1 on error

vips_sharpen ()

int                 vips_sharpen                        (VipsImage *in,
                                                         VipsImage **out,
                                                         ...);

Optional arguments:

radius: how large a mask to use x1: flat/jaggy threshold y2: maximum amount of brightening y3: maximum amount of darkening m1: slope for flat areas m2: slope for jaggy areas

Selectively sharpen the L channel of a LAB image. The input image is transformed to VIPS_INTERPRETATION_LABS.

The operation performs a gaussian blur of radius radius and subtracts from in to generate a high-frequency signal. This signal is passed through a lookup table formed from the five parameters and added back to in.

The lookup table is formed like this:

                      ^
                   y2 |- - - - - -----------
                      |         / 
                      |        / slope m2
                      |    .../    
              -x1     | ...   |    
  -------------------...---------------------->
              |   ... |      x1           
              |... slope m1
              /       |
             / m2     |
            /         |
           /          |
          /           |
         /            |
  ______/ _ _ _ _ _ _ | -y3
                      |

For printing, we recommend the following settings (the defaults):

   radius == 3
   x1 == 1.5
   y2 == 20         (don't brighten by more than 20 L*)
   y3 == 50         (can darken by up to 50 L*)

   m1 == 1          (some sharpening in flat areas)
   m2 == 2          (more sharpening in jaggy areas)

If you want more or less sharpening, we suggest you just change the m1 and m2 parameters.

The radius parameter changes the width of the fringe and can be adjusted according to the output printing resolution. As an approximate guideline, use 1 for 4 pixels/mm (CRT display resolution), 2 for 8 pixels/mm, 3 for 12 pixels/mm and 4 for 16 pixels/mm (300 dpi == 12 pixels/mm). These figures refer to the image raster, not the half-tone resolution.

See also: im_conv().

in :

input image

out :

output image

... :

NULL-terminated list of optional named arguments

Returns :

0 on success, -1 on error.

vips_gaussblur ()

int                 vips_gaussblur                      (VipsImage *in,
                                                         VipsImage **out,
                                                         int radius,
                                                         ...);

Optional arguments:

precision: VipsPrecision for blur

This operator runs vips_gaussmat() and vips_convsep() for you on an image.

radius is not used directly. Instead the standard deviation of vips_gaussmat() is set to radius / 2 and the minimum amplitude set to 20%. This gives a mask radius of approximately radius pixels.

See also: vips_gaussmat(), vips_conv().

in :

input image

out :

output image

radius :

how large a mask to use

... :

NULL-terminated list of optional named arguments

Returns :

0 on success, -1 on error.