resample

resample — resample images in various ways

Stability Level

Stable, unless otherwise indicated

Functions

Types and Values

enum VipsKernel
enum VipsSize

Object Hierarchy

    GEnum
    ├── VipsKernel
    ╰── VipsSize

Includes

#include <vips/vips.h>

Description

These operations build on each other in a set of layers.

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_thumbnail() combines load and resize in one operation, and adds colour management and correct handling of alpha transparency. Because load and resize happen together, it can exploit tricks like JPEG and TIFF shrink-on-load, giving a (potentially) huge speedup. vips_thumbnail_image() is only there for emergencies, don't use it unless you really have to.

As a separate thing, `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,
             ...);

Optional arguments:

  • ceil : round-up output dimensions

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,
              ...);

Optional arguments:

  • ceil : round-up output dimensions

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,
              ...);

Optional arguments:

  • ceil : round-up output dimensions

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)

  • gap : reducing gap to use (default: 0.0)

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 gap to speed up reducing by having vips_shrink() to shrink with a box filter first. The bigger gap , the closer the result to the fair resampling. The smaller gap , the faster resizing. The default value is 0.0 (no optimization).

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

  • gap : reducing gap to use (default: 0.0)

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

Set gap to speed up reducing by having vips_shrinkh() to shrink with a box filter first. The bigger gap , the closer the result to the fair resampling. The smaller gap , the faster resizing. The default value is 0.0 (no optimization).

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)

  • gap : reducing gap to use (default: 0.0)

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

Set gap to speed up reducing by having vips_shrinkv() to shrink with a box filter first. The bigger gap , the closer the result to the fair resampling. The smaller gap , the faster resizing. The default value is 0.0 (no optimization).

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

  • fail_on : VipsFailOn, load error types to fail on

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 buffer, or vips_thumbnail_source() to thumbnail from an arbitrary byte source.

By default, libvips will only the first frame of animated or multipage images. To thumbnail all pages or frames, pass n=-1 to the loader in filename , for example "x.gif[n=-1]".

The output image will fit within a square of size width x width . You can specify a separate height with the height option. Set either width or height to a very large number to ignore that dimension.

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.

Use fail_on to control the types of error that will cause loading to fail. The default is VIPS_FAIL_ON_NONE, ie. thumbnail is permissive.

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

  • fail_on : VipsFailOn, load error types to fail on

  • 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

  • fail_on : VipsFailOn, load error types to fail on

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

  • fail_on : VipsFailOn, load error types to fail on

  • 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

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

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

  • gap : reducing gap to use (default: 2.0)

Resize an image.

Set gap to speed up downsizing by having vips_shrink() to shrink with a box filter first. The bigger gap , the closer the result to the fair resampling. The smaller gap , the faster resizing. The default value is 2.0 (very close to fair resampling while still being faster in many cases).

vips_resize() normally uses VIPS_KERNEL_LANCZOS3 for the final reduce, you can change this with kernel . Downsizing is done with centre convention.

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

  • extend : VipsExtend how to generate new pixels

  • background : VipsArrayDouble colour for new pixels

  • premultiplied : gboolean, images are already premultiplied

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.

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.

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

Convolve with a Mitchell kernel.

 

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