resample: libvips Reference Manual

## 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_thumbnail ()
int | vips_thumbnail_buffer ()
int | vips_thumbnail_image ()
int | vips_thumbnail_source ()
int | vips_similarity ()
int | vips_rotate ()
int | vips_affine ()
int | vips_resize ()
int | vips_mapim ()
int | vips_quadratic ()

## Types and Values

enum | VipsKernel
enum | VipsSize

## 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: you'll see aliasing.

vips_reduce() is like `vips_affine()`, but it can only shrink images, it can't enlarge, rotate, or skew. It's very fast and uses an adaptive kernel for interpolation.

vips_shrink() is a fast block shrinker. It can quickly reduce images by large integer factors. It will give poor results for small size reductions: again, you'll see aliasing.

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_reduce()` 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_reduce()`.

[method]

#### Parameters

in | input image |
out | output image. | [out]
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()`.

[method]

#### Parameters

in | input image |
out | output image. | [out]
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()`.

[method]

#### Parameters

in | input image |
out | output image. | [out]
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)

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

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

[method]

#### Parameters

in | input image |
out | output image. | [out]
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,
                  ...);

Optional arguments:

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

Reduce `in` horizontally by a float factor. The pixels in `out` are interpolated with a 1D mask generated by `kernel` .

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_shrink()`, `vips_resize()`, `vips_affine()`.

[method]

#### Parameters

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

#### Returns

0 on success, -1 on error

### vips_reducev ()

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

Optional arguments:

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

Reduce `in` vertically by a float factor. The pixels in `out` are interpolated with a 1D mask generated by `kernel` .

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_shrink()`, `vips_resize()`, `vips_affine()`.

[method]

#### Parameters

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

#### Returns

0 on success, -1 on error

### vips_thumbnail ()

    int
    vips_thumbnail (const char *filename,
                    VipsImage **out,
                    int width,
                    ...);

Optional arguments:

- `height` : `gint`, target height in pixels

- `size` : VipsSize, upsize, downsize, both or force

- `no_rotate` : `gboolean`, don't rotate upright using orientation tag

- `crop` : VipsInteresting, shrink and crop to fill target

- `linear` : `gboolean`, perform shrink in linear light

- `import_profile` : `gchararray`, fallback import ICC profile

- `export_profile` : `gchararray`, export ICC profile

- `intent` : VipsIntent, rendering intent

Make a thumbnail from a file. Shrinking is done in three stages: using any shrink-on-load features available in the file import library, using a block shrink, and using a lanczos3 shrink. At least the final 200% is done with lanczos3. The output should be high quality, and the operation should be quick.

See `vips_thumbnail_buffer()` to thumbnail from a memory source.

The output image will fit within a square of size `width` x `width` . You can specify a separate height with the `height` option.

If you set `crop` , then the output image will fill the whole of the `width` x `height` rectangle, with any excess cropped away. See `vips_smartcrop()` for details on the cropping strategy.

Normally the operation will upsize or downsize as required to fit the image inside or outside the target size. If `size` is set to VIPS_SIZE_UP, the operation will only upsize and will just copy if asked to downsize. If `size` is set to VIPS_SIZE_DOWN, the operation will only downsize and will just copy if asked to upsize. If `size` is VIPS_SIZE_FORCE, the image aspect ratio will be broken and the image will be forced to fit the target.

Normally any orientation tags on the input image (such as EXIF tags) are interpreted to rotate the image upright. If you set `no_rotate` to `TRUE`, these tags will not be interpreted.

Shrinking is normally done in sRGB colourspace. Set `linear` to shrink in linear light colourspace instead. This can give better results, but can also be far slower, since tricks like JPEG shrink-on-load cannot be used in linear space.

If you set `export_profile` to the filename of an ICC profile, the image will be transformed to the target colourspace before writing to the output. You can also give an `import_profile` which will be used if the input image has no ICC profile, or if the profile embedded in the input image is broken.

Use `intent` to set the rendering intent for any ICC transform. The default is VIPS_INTENT_RELATIVE.

See also: `vips_thumbnail_buffer()`.

#### Parameters

filename | file to read from |
out | output image. | [out]
width | target width in pixels |
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error.

### vips_thumbnail_buffer ()

    int
    vips_thumbnail_buffer (void *buf,
                           size_t len,
                           VipsImage **out,
                           int width,
                           ...);

Optional arguments:

- `height` : `gint`, target height in pixels

- `size` : VipsSize, upsize, downsize, both or force

- `no_rotate` : `gboolean`, don't rotate upright using orientation tag

- `crop` : VipsInteresting, shrink and crop to fill target

- `linear` : `gboolean`, perform shrink in linear light

- `import_profile` : `gchararray`, fallback import ICC profile

- `export_profile` : `gchararray`, export ICC profile

- `intent` : VipsIntent, rendering intent

- `option_string` : `gchararray`, extra loader options

Exactly as `vips_thumbnail()`, but read from a memory buffer. One extra optional argument, `option_string` , lets you pass options to the underlying loader.

See also: `vips_thumbnail()`.

#### Parameters

buf | memory area to load. | [array length=len][element-type guint8]
len | size of memory area. | [type gsize]
out | output image. | [out]
width | target width in pixels |
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error.

### vips_thumbnail_image ()

    int
    vips_thumbnail_image (VipsImage *in,
                          VipsImage **out,
                          int width,
                          ...);

Optional arguments:

- `height` : `gint`, target height in pixels

- `size` : VipsSize, upsize, downsize, both or force

- `no_rotate` : `gboolean`, don't rotate upright using orientation tag

- `crop` : VipsInteresting, shrink and crop to fill target

- `linear` : `gboolean`, perform shrink in linear light

- `import_profile` : `gchararray`, fallback import ICC profile

- `export_profile` : `gchararray`, export ICC profile

- `intent` : VipsIntent, rendering intent

Exactly as `vips_thumbnail()`, but read from an existing image.

This operation is not able to exploit shrink-on-load features of image load libraries, so it can be much slower than ``vips_thumbnail()`` and produce poorer quality output. Only use it if you really have to.

See also: `vips_thumbnail()`.

[method]

#### Parameters

in | input image |
out | output image. | [out]
width | target width in pixels |
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error.

### vips_thumbnail_source ()

    int
    vips_thumbnail_source (VipsSource *source,
                           VipsImage **out,
                           int width,
                           ...);

Optional arguments:

- `height` : `gint`, target height in pixels

- `size` : VipsSize, upsize, downsize, both or force

- `no_rotate` : `gboolean`, don't rotate upright using orientation tag

- `crop` : VipsInteresting, shrink and crop to fill target

- `linear` : `gboolean`, perform shrink in linear light

- `import_profile` : `gchararray`, fallback import ICC profile

- `export_profile` : `gchararray`, export ICC profile

- `intent` : VipsIntent, rendering intent

- `option_string` : `gchararray`, extra loader options

Exactly as `vips_thumbnail()`, but read from a source. One extra optional argument, `option_string` , lets you pass options to the underlying loader.

See also: `vips_thumbnail()`.

#### Parameters

source | source to thumbnail |
out | output image. | [out]
width | target width in pixels |
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error.

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

- `background` : VipsArrayDouble colour for new pixels

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

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

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

- `ody` : `gdouble`, output vertical 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.

[method]

#### Parameters

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

#### Returns

0 on success, -1 on error

### vips_rotate ()

    int
    vips_rotate (VipsImage *in,
                 VipsImage **out,
                 double angle,
                 ...);

Optional arguments:

- `interpolate` : VipsInterpolate, interpolate pixels with this

- `background` : VipsArrayDouble colour for new pixels

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

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

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

- `ody` : `gdouble`, output vertical 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.

[method]

#### Parameters

in | input image |
out | output image. | [out]
angle | `gdouble`, rotate by this many degrees clockwise |
... | `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

- `extend` : VipsExtend how to generate new pixels

- `background` : VipsArrayDouble colour for new pixels

- `premultiplied` : `gboolean`, images are already premultiplied

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

The transform is:

    1
    2
    3
    4
    5
    6
    7
    X = @a * (x + @idx) + @b * (y + @idy) + @odx
    Y = @c * (x + @idx) + @d * (y + @idy) + @doy

    where:
      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.

By default, new pixels are filled with `background` . This defaults to zero (black). You can set other extend types with `extend` . VIPS_EXTEND_COPY is better for image upsizing.

`interpolate` defaults to bilinear.

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

Image are normally treated as unpremultiplied, so this operation can be used directly on PNG images. If your images have been through `vips_premultiply()`, set `premultiplied` .

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.

[method]

#### Parameters

in | input image |
out | output image. | [out]
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

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. Downsizing is done with centre convention.

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

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. It adds a 0.5 pixel displacement to the input pixels to get centre convention scaling.

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

If either axis would drop below 1px in size, the shrink in that dimension is limited. This breaks the image aspect ratio, but prevents errors due to fractional pixel sizes.

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

This operation does not premultiply alpha. If your image has an alpha channel, you should use `vips_premultiply()` on it first.

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

[method]

#### Parameters

in | input image |
out | output image. | [out]
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.

[method]

#### Parameters

in | input image |
out | output image. | [out]
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()`.

[method]

#### Parameters

in | input image |
out | output image. | [out]
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.

#### Members

VIPS_KERNEL_NEAREST | The nearest pixel to the point. |
VIPS_KERNEL_LINEAR | Convolve with a triangle filter. |
VIPS_KERNEL_CUBIC | Convolve with a cubic filter. |
VIPS_KERNEL_MITCHELL |  |
VIPS_KERNEL_LANCZOS2 | Convolve with a two-lobe Lanczos kernel. |
VIPS_KERNEL_LANCZOS3 | Convolve with a three-lobe Lanczos kernel. |
VIPS_KERNEL_LAST |  |

### enum VipsSize

Controls whether an operation should upsize, downsize, both up and downsize, or force a size.

See also: `vips_thumbnail()`.

#### Members

VIPS_SIZE_BOTH | size both up and down |
VIPS_SIZE_UP | only upsize |
VIPS_SIZE_DOWN | only downsize |
VIPS_SIZE_FORCE | force size, that is, break aspect ratio |
VIPS_SIZE_LAST |  |