## resample

resample — resample images in various ways

## Stability Level

Stable, unless otherwise indicated

## Functions

int | vips_shrink ()
int | vips_shrinkh ()
int | vips_shrinkv ()
int | vips_reduce ()
int | vips_reduceh ()
int | vips_reducev ()
int | vips_similarity ()
int | vips_affine ()
int | vips_resize ()
int | vips_mapim ()
int | vips_quadratic ()

## Types and Values

enum | VipsKernel

## Includes

    #include <vips/vips.h>

## Description

There are three types of operation in this section.

First, `vips_affine()` applies an affine transform to an image. This is any sort of 2D transform which preserves straight lines; so any combination of stretch, sheer, rotate and translate. You supply an interpolator for it to use to generate pixels, see `vips_interpolate_new()`. It will not produce good results for very large shrinks.

Next, `vips_resize()` specialises in the common task of image reduce and enlarge. It strings together combinations of `vips_shrink()`, `vips_reduce()`, `vips_affine()` and others to implement a general, high-quality image resizer.

Finally, `vips_mapim()` can apply arbitrary 2D image transforms to an image.

## Functions

### vips_shrink ()

    int
    vips_shrink (VipsImage *in,
                 VipsImage **out,
                 double hshrink,
                 double vshrink,
                 ...);

Shrink `in` by a pair of factors with a simple box filter. For non-integer factors, `vips_shrink()` will first shrink by the integer part with a box filter, then use `vips_affine()` plus bilinear interpolation to shrink by the remaining fractional part.

This is a very low-level operation: see `vips_resize()` for a more convenient way to resize images.

This operation does not change xres or yres. The image resolution needs to be updated by the application.

See also: `vips_resize()`, `vips_affine()`.

#### Parameters

in | input image |
out | output image |
hshrink | horizontal shrink |
vshrink | vertical shrink |
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error

### vips_shrinkh ()

    int
    vips_shrinkh (VipsImage *in,
                  VipsImage **out,
                  int hshrink,
                  ...);

Shrink `in` horizontally by an integer factor. Each pixel in the output is the average of the corresponding line of `hshrink` pixels in the input.

This is a very low-level operation: see `vips_resize()` for a more convenient way to resize images.

This operation does not change xres or yres. The image resolution needs to be updated by the application.

See also: `vips_shrinkv()`, `vips_shrink()`, `vips_resize()`, `vips_affine()`.

#### Parameters

in | input image |
out | output image |
hshrink | horizontal shrink |
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error

### vips_shrinkv ()

    int
    vips_shrinkv (VipsImage *in,
                  VipsImage **out,
                  int vshrink,
                  ...);

Shrink `in` vertically by an integer factor. Each pixel in the output is the average of the corresponding column of `vshrink` pixels in the input.

This is a very low-level operation: see `vips_resize()` for a more convenient way to resize images.

This operation does not change xres or yres. The image resolution needs to be updated by the application.

See also: `vips_shrinkh()`, `vips_shrink()`, `vips_resize()`, `vips_affine()`.

#### Parameters

in | input image |
out | output image |
vshrink | vertical shrink |
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error

### vips_reduce ()

    int
    vips_reduce (VipsImage *in,
                 VipsImage **out,
                 double hshrink,
                 double vshrink,
                 ...);

Optional arguments:

- `kernel` : VipsKernel to use to interpolate (default: lanczos3)

- `centre` : `gboolean` use centre rather than corner sampling convention

Reduce `in` by a pair of factors with a pair of 1D kernels. This will not work well for shrink factors greater than three.

Set `centre` to use centre rather than corner sampling convention. Centre convention can be useful to match the behaviour of other systems.

This is a very low-level operation: see `vips_resize()` for a more convenient way to resize images.

This operation does not change xres or yres. The image resolution needs to be updated by the application.

See also: `vips_resize()`, `vips_affine()`.

#### Parameters

in | input image |
out | output image |
hshrink | horizontal shrink |
vshrink | vertical shrink |
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error

### vips_reduceh ()

    int
    vips_reduceh (VipsImage *in,
                  VipsImage **out,
                  double hshrink,
                  ...);

### vips_reducev ()

    int
    vips_reducev (VipsImage *in,
                  VipsImage **out,
                  double vshrink,
                  ...);

### vips_similarity ()

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

Optional arguments:

- `scale` : `gdouble`, scale by this factor

- `angle` : `gdouble`, rotate by this many degrees clockwise

- `interpolate` : VipsInterpolate, interpolate pixels with this

- `idx` : `gdouble`, input horizontal offset

- `idy` : `gdouble`, input vertical offset

- `odx` : `gdouble`, output horizontal offset

- `ody` : `gdouble`, output vertical offset

This operator calls `vips_affine()` for you, calculating the matrix for the affine transform from `scale` and `angle` . Other parameters are passed on to `vips_affine()` unaltered.

See also: `vips_affine()`, VipsInterpolate.

#### Parameters

in | input image |
out | output image |
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error

### vips_affine ()

    int
    vips_affine (VipsImage *in,
                 VipsImage **out,
                 double a,
                 double b,
                 double c,
                 double d,
                 ...);

Optional arguments:

- `interpolate` : VipsInterpolate, interpolate pixels with this

- `oarea` : VipsArrayInt, output rectangle

- `idx` : `gdouble`, input horizontal offset

- `idy` : `gdouble`, input vertical offset

- `odx` : `gdouble`, output horizontal offset

- `ody` : `gdouble`, output vertical offset

This operator performs an affine transform on an image using `interpolate` .

The transform is:

X = `a` * (x + `idx` ) + `b` * (y + `idy` ) + `odx` Y = `c` * (x + `idx` ) + `d` * (y + `idy` ) + `doy`

x and y are the coordinates in input image. X and Y are the coordinates in output image. (0,0) is the upper left corner.

The section of the output space defined by `oarea` is written to `out` . `oarea` is a four-element int array of left, top, width, height. By default `oarea` is just large enough to cover the whole of the transformed input image.

`interpolate` defaults to bilinear.

`idx` , `idy` , `odx` , `ody` default to zero.

This operation does not change xres or yres. The image resolution needs to be updated by the application.

See also: `vips_shrink()`, `vips_resize()`, VipsInterpolate.

#### Parameters

in | input image |
out | output image |
a | transformation matrix coefficient |
b | transformation matrix coefficient |
c | transformation matrix coefficient |
d | transformation matrix coefficient |
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error

### vips_resize ()

    int
    vips_resize (VipsImage *in,
                 VipsImage **out,
                 double scale,
                 ...);

Optional arguments:

- `vscale` : `gdouble` vertical scale factor

- `kernel` : VipsKernel to reduce with

- `centre` : `gboolean` use centre rather than corner sampling convention

Resize an image.

When downsizing, the image is block-shrunk with `vips_shrink()`, then the image is shrunk again to the target size with `vips_reduce()`. How much is done by `vips_shrink()` vs. `vips_reduce()` varies with the `kernel` setting.

vips_resize() normally uses VIPS_KERNEL_LANCZOS3 for the final reduce, you can change this with `kernel` .

Set `centre` to use centre rather than corner sampling convention. Centre convention can be useful to match the behaviour of other systems.

When upsizing (`scale` > 1), the operation uses `vips_affine()` with a VipsInterpolate selected depending on `kernel` . It will use VipsInterpolateBicubic for VIPS_KERNEL_CUBIC and above.

vips_resize() normally maintains the image apect ratio. If you set `vscale` , that factor is used for the vertical scale and `scale` for the horizontal.

This operation does not change xres or yres. The image resolution needs to be updated by the application.

See also: `vips_shrink()`, `vips_reduce()`.

#### Parameters

in | input image |
out | output image |
scale | scale factor |
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error

### vips_mapim ()

    int
    vips_mapim (VipsImage *in,
                VipsImage **out,
                VipsImage *index,
                ...);

Optional arguments:

- `interpolate` : interpolate pixels with this

This operator resamples `in` using `index` to look up pixels. `out` is the same size as `index` , with each pixel being fetched from that position in `in` . That is:

    1

    out[x, y] = in[index[x, y]]

If `index` has one band, that band must be complex. Otherwise, `index` must have two bands of any format. Coordinates in `index` are in pixels, with (0, 0) being the top-left corner of `in` , and with y increasing down the image. Use `vips_xyz()` to build index images.

`interpolate` defaults to bilinear.

This operation does not change xres or yres. The image resolution needs to be updated by the application.

See `vips_maplut()` for a 1D equivalent of this operation.

See also: `vips_xyz()`, `vips_affine()`, `vips_resize()`, `vips_maplut()`, VipsInterpolate.

#### Parameters

in | input image |
out | output image |
index | index image |
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error

### vips_quadratic ()

    int
    vips_quadratic (VipsImage *in,
                    VipsImage **out,
                    VipsImage *coeff,
                    ...);

Optional arguments:

- `interpolate` : use this interpolator (default bilinear)

This operation is unfinished and unusable, sorry.

See also: `vips_affine()`.

#### Parameters

in | input image |
out | output image |
coeff | horizontal quadratic |
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error

## Types and Values

### enum VipsKernel

The resampling kernels vips supports. See `vips_reduce()`, for example.

The Lanczos kernels vary in size with the downsampling ratio.

#### Members

VIPS_KERNEL_NEAREST | The nearest pixel to the point. |
VIPS_KERNEL_LINEAR | Calculate a pixel value using linear interpolation. |
VIPS_KERNEL_CUBIC | Calculate using a 4-element cubic kernel. |
VIPS_KERNEL_LANCZOS2 | Calculate with a two-lobe Lanczos kernel. |
VIPS_KERNEL_LANCZOS3 | Calculate with a three-lobe Lanczos kernel. |
VIPS_KERNEL_LAST |  |