Vips.Image.conv

### Method

# Vips Imageconv

#### Declaration [src]

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

#### Description [src]

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

By default, `precision` is `VIPS_PRECISION_FLOAT`. 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_INTEGER`, then elements of `mask` are converted to integers before convolution, using `rint()`, and the output image always has the same `VipsBandFormat` as the input image.

For `VIPS_FORMAT_UCHAR` images and `VIPS_PRECISION_INTEGER` `precision`, `vips_conv()` uses a fast vector path based on half-float arithmetic. This can produce slightly different results. Disable the vector path with `--vips-novector` or `VIPS_NOVECTOR` or `vips_vector_set_enabled()`.

If `precision` is `VIPS_PRECISION_APPROXIMATE` then, like `VIPS_PRECISION_INTEGER`, `mask` is converted to int before convolution, and the output image always has the same `VipsBandFormat` 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.

Optional arguments

- `precision`: `VipsPrecision`, calculation accuracy
- `layers`: `gint`, number of layers for approximation
- `cluster`: `gint`, cluster lines closer than this distance

See also

`vips_convsep()`.

This method is not directly available to language bindings.

#### Parameters

`out`

  Type: `VipsImage`

  Output image.

  The argument will be set by the function.
  The caller of the method takes ownership of the returned data, and is responsible for freeing it.

`mask`

  Type: `VipsImage`

  Convolve with this mask.

  The data is owned by the caller of the method.

`...`

  Type: ``

  `NULL`-terminated list of optional named arguments.

#### Return value

Type: `int`

0 on success, -1 on error.