## 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.