conversion

conversion — convert images in some way: change band format, change header, insert, extract, join

Stability Level

Stable, unless otherwise indicated

Functions

int vips_copy ()
int vips_tilecache ()
int vips_linecache ()
int vips_sequential ()
int vips_cache ()
int vips_copy_file ()
int vips_embed ()
int vips_gravity ()
int vips_flip ()
int vips_insert ()
int vips_join ()
int vips_arrayjoin ()
int vips_extract_area ()
int vips_crop ()
int vips_smartcrop ()
int vips_extract_band ()
int vips_replicate ()
int vips_grid ()
int vips_transpose3d ()
int vips_wrap ()
int vips_rot ()
int vips_rot90 ()
int vips_rot180 ()
int vips_rot270 ()
int vips_rot45 ()
VipsAngle vips_autorot_get_angle ()
void vips_autorot_remove_angle ()
int vips_autorot ()
int vips_zoom ()
int vips_subsample ()
int vips_cast ()
int vips_cast_uchar ()
int vips_cast_char ()
int vips_cast_ushort ()
int vips_cast_short ()
int vips_cast_uint ()
int vips_cast_int ()
int vips_cast_float ()
int vips_cast_double ()
int vips_cast_complex ()
int vips_cast_dpcomplex ()
int vips_scale ()
int vips_msb ()
int vips_byteswap ()
int vips_bandjoin ()
int vips_bandjoin2 ()
int vips_bandjoin_const ()
int vips_bandjoin_const1 ()
int vips_bandrank ()
int vips_bandfold ()
int vips_bandunfold ()
int vips_bandbool ()
int vips_bandand ()
int vips_bandor ()
int vips_bandeor ()
int vips_bandmean ()
int vips_recomb ()
int vips_ifthenelse ()
int vips_flatten ()
int vips_addalpha ()
int vips_premultiply ()
int vips_unpremultiply ()
int vips_composite ()
int vips_composite2 ()
int vips_falsecolour ()
int vips_gamma ()

Includes

#include <vips/vips.h>

Description

These operations convert an image in some way. They can be split into a two main groups.

The first set of operations change an image's format in some way. You can change the band format (for example, cast to 32-bit unsigned int), form complex images from real images, convert images to matrices and back, change header fields, and a few others.

The second group move pixels about in some way. You can flip, rotate, extract, insert and join pairs of images in various ways.

Functions

vips_copy ()

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

Optional arguments:

Copy an image, optionally modifying the header. VIPS copies images by copying pointers, so this operation is instant, even for very large images.

You can optionally change any or all header fields during the copy. You can make any change which does not change the size of a pel, so for example you can turn a 4-band uchar image into a 2-band ushort image, but you cannot change a 100 x 100 RGB image into a 300 x 100 mono image.

See also: vips_byteswap(), vips_bandfold(), vips_bandunfold().

[method]

Parameters

in

input image

 

out

output image.

[out]

...

NULL-terminated list of optional named arguments

 

Returns

0 on success, -1 on error.


vips_tilecache ()

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

Optional arguments:

  • tile_width : width of tiles in cache

  • tile_height : height of tiles in cache

  • max_tiles : maximum number of tiles to cache

  • access : hint expected access pattern VipsAccess

  • threaded : allow many threads

  • persistent : don't drop cache at end of computation

This operation behaves rather like vips_copy() between images in and out , except that it keeps a cache of computed pixels. This cache is made of up to max_tiles tiles (a value of -1 means any number of tiles), and each tile is of size tile_width by tile_height pixels.

Each cache tile is made with a single call to vips_region_prepare().

When the cache fills, a tile is chosen for reuse. If access is VIPS_ACCESS_RANDOM, then the least-recently-used tile is reused. If access is VIPS_ACCESS_SEQUENTIAL the top-most tile is reused.

By default, tile_width and tile_height are 128 pixels, and the operation will cache up to 1,000 tiles. access defaults to VIPS_ACCESS_RANDOM.

Normally, only a single thread at once is allowed to calculate tiles. If you set threaded to TRUE, vips_tilecache() will allow many threads to calculate tiles at once, and share the cache between them.

Normally the cache is dropped when computation finishes. Set persistent to TRUE to keep the cache between computations.

See also: vips_cache(), vips_linecache().

[method]

Parameters

in

input image

 

out

output image.

[out]

...

NULL-terminated list of optional named arguments

 

Returns

0 on success, -1 on error.


vips_linecache ()

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

Optional arguments:

  • access : hint expected access pattern VipsAccess

  • tile_height : height of tiles in cache

  • threaded : allow many threads

This operation behaves rather like vips_copy() between images in and out , except that it keeps a cache of computed scanlines.

The number of lines cached is enough for a small amount of non-local access.

Each cache tile is made with a single call to vips_region_prepare().

When the cache fills, a tile is chosen for reuse. If access is VIPS_ACCESS_RANDOM, then the least-recently-used tile is reused. If access is VIPS_ACCESS_SEQUENTIAL, then the top-most tile is reused. access defaults to VIPS_ACCESS_RANDOM.

tile_height can be used to set the size of the strips that vips_linecache() uses. The default is 1 (a single scanline).

Normally, only a single thread at once is allowed to calculate tiles. If you set threaded to TRUE, vips_linecache() will allow many threads to calculate tiles at once and share the cache between them.

See also: vips_cache(), vips_tilecache().

[method]

Parameters

in

input image

 

out

output image.

[out]

...

NULL-terminated list of optional named arguments

 

Returns

0 on success, -1 on error.


vips_sequential ()

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

Optional arguments:

  • strip_height : height of cache strips

This operation behaves rather like vips_copy() between images in and out , except that it checks that pixels on in are only requested top-to-bottom. This operation is useful for loading file formats which are strictly top-to-bottom, like PNG.

strip_height can be used to set the size of the tiles that vips_sequential() uses. The default value is 1.

See also: vips_cache(), vips_linecache(), vips_tilecache().

[method]

Parameters

in

input image

 

out

output image.

[out]

...

NULL-terminated list of optional named arguments

 

Returns

0 on success, -1 on error.


vips_cache ()

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

Optional arguments:

  • tile_width : width of tiles in cache

  • tile_height : height of tiles in cache

  • max_tiles : maximum number of tiles to cache

This operation behaves rather like vips_copy() between images in and out , except that it keeps a cache of computed pixels. This cache is made of up to max_tiles tiles (a value of -1 means any number of tiles), and each tile is of size tile_width by tile_height pixels. By default it will cache 250 128 x 128 pixel tiles, enough for two 1920 x 1080 images.

This operation is a thin wrapper over vips_sink_screen(), see the documentation for that operation for details.

It uses a set of background threads to calculate pixels and the various active cache operations coordinate so as not to overwhelm your system. When a request is made for an area of pixels, the operation will block until all of those pixels have been calculated. Pixels are calculated with a set of threads.

See also: vips_tilecache().

[method]

Parameters

in

input image

 

out

output image.

[out]

...

NULL-terminated list of optional named arguments

 

Returns

0 on success, -1 on error.


vips_copy_file ()

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

A simple convenience function to copy an image to a file, then copy again to output. If the image is already a file, just copy straight through.

The file is allocated with vips_image_new_temp_file(). The file is automatically deleted when out is closed.

See also: vips_copy(), vips_image_new_temp_file().

[method]

Parameters

in

input image

 

out

output image.

[out]

...

NULL-terminated list of optional named arguments

 

Returns

0 on success, -1 on error


vips_embed ()

int
vips_embed (VipsImage *in,
            VipsImage **out,
            int x,
            int y,
            int width,
            int height,
            ...);

Optional arguments:

The opposite of vips_extract_area(): embed in within an image of size width by height at position x , y .

extend controls what appears in the new pels, see VipsExtend.

See also: vips_extract_area(), vips_insert().

[method]

Parameters

in

input image

 

out

output image.

[out]

x

place in at this x position in out

 

y

place in at this y position in out

 

width

out should be this many pixels across

 

height

out should be this many pixels down

 

...

NULL-terminated list of optional named arguments

 

Returns

0 on success, -1 on error.


vips_gravity ()

int
vips_gravity (VipsImage *in,
              VipsImage **out,
              VipsCompassDirection direction,
              int width,
              int height,
              ...);

Optional arguments:

The opposite of vips_extract_area(): place in within an image of size width by height at a certain gravity.

extend controls what appears in the new pels, see VipsExtend.

See also: vips_extract_area(), vips_insert().

Parameters

in

input image

 

out

output image

 

direction

place in at this direction in out

 

width

out should be this many pixels across

 

height

out should be this many pixels down

 

...

NULL-terminated list of optional named arguments

 

Returns

0 on success, -1 on error.


vips_flip ()

int
vips_flip (VipsImage *in,
           VipsImage **out,
           VipsDirection direction,
           ...);

Flips an image left-right or up-down.

See also: vips_rot().

[method]

Parameters

in

input image

 

out

output image.

[out]

direction

flip horizontally or vertically

 

...

NULL-terminated list of optional named arguments

 

Returns

0 on success, -1 on error


vips_insert ()

int
vips_insert (VipsImage *main,
             VipsImage *sub,
             VipsImage **out,
             int x,
             int y,
             ...);

Optional arguments:

  • expand : expand output to hold whole of both images

  • background : colour for new pixels

Insert sub into main at position x , y .

Normally out shows the whole of main . If expand is TRUE then out is made large enough to hold all of main and sub . Any areas of out not coming from either main or sub are set to background (default 0).

If sub overlaps main , sub will appear on top of main .

If the number of bands differs, one of the images must have one band. In this case, an n-band image is formed from the one-band image by joining n copies of the one-band image together, and then the two n-band images are operated upon.

The two input images are cast up to the smallest common type (see table Smallest common format in

arithmetic).

See also: vips_join(), vips_embed(), vips_extract_area().

[method]

Parameters

main

big image

 

sub

small image

 

out

output image.

[out]

x

left position of sub

 

y

top position of sub

 

...

NULL-terminated list of optional named arguments

 

Returns

0 on success, -1 on error


vips_join ()

int
vips_join (VipsImage *in1,
           VipsImage *in2,
           VipsImage **out,
           VipsDirection direction,
           ...);

Optional arguments:

  • expand : TRUE to expand the output image to hold all of the input pixels

  • shim : space between images, in pixels

  • background : background ink colour

  • align : low, centre or high alignment

Join in1 and in2 together, left-right or up-down depending on the value of direction .

If one is taller or wider than the other, out will be has high as the smaller. If expand is TRUE, then the output will be expanded to contain all of the input pixels.

Use align to set the edge that the images align on. By default, they align on the edge with the lower value coordinate.

Use background to set the colour of any pixels in out which are not present in either in1 or in2 .

Use shim to set the spacing between the images. By default this is 0.

If the number of bands differs, one of the images must have one band. In this case, an n-band image is formed from the one-band image by joining n copies of the one-band image together, and then the two n-band images are operated upon.

The two input images are cast up to the smallest common type (see table Smallest common format in

arithmetic).

If you are going to be joining many thousands of images in a regular grid, vips_arrayjoin() is a better choice.

See also: vips_arrayjoin(), vips_insert().

Parameters

in1

first input image

 

in2

second input image

 

out

output image.

[out]

direction

join horizontally or vertically

 

...

NULL-terminated list of optional named arguments

 

Returns

0 on success, -1 on error


vips_arrayjoin ()

int
vips_arrayjoin (VipsImage **in,
                VipsImage **out,
                int n,
                ...);

Optional arguments:

  • across : gint, number of images per row

  • shim : gint, space between images, in pixels

  • background : VipsArrayDouble, background ink colour

  • halign : VipsAlign, low, centre or high alignment

  • valign : VipsAlign, low, centre or high alignment

  • hspacing : gint, horizontal distance between images

  • vspacing : gint, vertical distance between images

Lay out the images in in in a grid. The grid is across images across and however high is necessary to use up all of in . Images are set down left-to-right and top-to-bottom. across defaults to n .

Each input image is placed with a box of size hspacing by vspacing pixels and cropped. These default to the largest width and largest height of the input images.

Space between images is filled with background . This defaults to 0 (black).

Images are positioned within their hspacing by vspacing box at low, centre or high coordinate values, controlled by halign and valign . These default to left-top.

Boxes are joined and separated by shim pixels. This defaults to 0.

If the number of bands in the input images differs, all but one of the images must have one band. In this case, an n-band image is formed from the one-band image by joining n copies of the one-band image together, and then the n-band images are operated upon.

The input images are cast up to the smallest common type (see table Smallest common format in

arithmetic).

See also: vips_join(), vips_insert().

Parameters

in

array of input images.

[array length=n][transfer none]

out

output image.

[out]

n

number of input images

 

...

NULL-terminated list of optional named arguments

 

Returns

0 on success, -1 on error


vips_extract_area ()

int
vips_extract_area (VipsImage *in,
                   VipsImage **out,
                   int left,
                   int top,
                   int width,
                   int height,
                   ...);

Extract an area from an image. The area must fit within in .

See also: vips_extract_bands(), vips_smartcrop().

[method]

Parameters

in

input image

 

out

output image.

[out]

left

left edge of area to extract

 

top

top edge of area to extract

 

width

width of area to extract

 

height

height of area to extract

 

...

NULL-terminated list of optional named arguments

 

Returns

0 on success, -1 on error.


vips_crop ()

int
vips_crop (VipsImage *in,
           VipsImage **out,
           int left,
           int top,
           int width,
           int height,
           ...);

A synonym for vips_extract_area().

See also: vips_extract_bands(), vips_smartcrop().

[method]

Parameters

in

input image

 

out

output image.

[out]

left

left edge of area to extract

 

top

top edge of area to extract

 

width

width of area to extract

 

height

height of area to extract

 

...

NULL-terminated list of optional named arguments

 

Returns

0 on success, -1 on error.


vips_smartcrop ()

int
vips_smartcrop (VipsImage *in,
                VipsImage **out,
                int width,
                int height,
                ...);

Optional arguments:

Crop an image down to a specified width and height by removing boring parts.

Use interesting to pick the method vips uses to decide which bits of the image should be kept.

You can test xoffset / yoffset on out to find the location of the crop within the input image.

See also: vips_extract_area().

[method]

Parameters

in

input image

 

out

output image.

[out]

width

width of area to extract

 

height

height of area to extract

 

...

NULL-terminated list of optional named arguments

 

Returns

0 on success, -1 on error.


vips_extract_band ()

int
vips_extract_band (VipsImage *in,
                   VipsImage **out,
                   int band,
                   ...);

Optional arguments:

  • n : number of bands to extract

Extract a band or bands from an image. Extracting out of range is an error.

See also: vips_extract_area().

[method]

Parameters

in

input image

 

out

output image.

[out]

band

band to extract

 

...

NULL-terminated list of optional named arguments

 

Returns

0 on success, -1 on error.


vips_replicate ()

int
vips_replicate (VipsImage *in,
                VipsImage **out,
                int across,
                int down,
                ...);

Repeats an image many times.

See also: vips_extract_area().

[method]

Parameters

in

input image

 

out

output image.

[out]

across

repeat input this many times across

 

down

repeat input this many times down

 

...

NULL-terminated list of optional named arguments

 

Returns

0 on success, -1 on error


vips_grid ()

int
vips_grid (VipsImage *in,
           VipsImage **out,
           int tile_height,
           int across,
           int down,
           ...);

Chop a tall thin image up into a set of tiles, lay the tiles out in a grid.

The input image should be a very tall, thin image containing a list of smaller images. Volumetric or time-sequence images are often laid out like this. This image is chopped into a series of tiles, each tile_height pixels high and the width of in . The tiles are then rearranged into a grid across tiles across and down tiles down in row-major order.

Supplying tile_height , across and down is not strictly necessary, we only really need two of these. Requiring three is a double-check that the image has the expected geometry.

See also: vips_embed(), vips_insert(), vips_join().

[method]

Parameters

in

input image

 

out

output image.

[out]

tile_height

chop into tiles this high

 

across

tiles across

 

down

tiles down

 

...

NULL-terminated list of optional named arguments

 

Returns

0 on success, -1 on error


vips_transpose3d ()

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

Optional arguments:

page_height : gint, size of each input page

Transpose a volumetric image.

Volumetric images are very tall, thin images, with the metadata item VIPS_META_PAGE_HEIGHT set to the height of each sub-image.

This operation swaps the two major dimensions, so that page N in the output contains the Nth scanline, in order, from each input page.

You can override the VIPS_META_PAGE_HEIGHT metadata item with the optional page_height parameter.

VIPS_META_PAGE_HEIGHT in the output image is the number of pages in the input image.

See also: vips_grid().

[method]

Parameters

in

input image

 

out

output image.

[out]

...

NULL-terminated list of optional named arguments

 

Returns

0 on success, -1 on error


vips_wrap ()

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

Optional arguments:

  • x : horizontal displacement

  • y : vertical displacement

Slice an image up and move the segments about so that the pixel that was at 0, 0 is now at x , y . If x and y are not set, they default to the centre of the image.

See also: vips_embed(), vips_replicate().

[method]

Parameters

in

input image

 

out

output image.

[out]

...

NULL-terminated list of optional named arguments

 

Returns

0 on success, -1 on error


vips_rot ()

int
vips_rot (VipsImage *in,
          VipsImage **out,
          VipsAngle angle,
          ...);

Rotate in by a multiple of 90 degrees.

Use vips_similarity() to rotate by an arbitary angle. vips_rot45() is useful for rotating convolution masks by 45 degrees.

See also: vips_flip(), vips_similarity(), vips_rot45().

[method]

Parameters

in

input image

 

out

output image.

[out]

angle

rotation angle

 

...

NULL-terminated list of optional named arguments

 

Returns

0 on success, -1 on error


vips_rot90 ()

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

Rotate in by 90 degress clockwise. A convenience function over vips_rot().

See also: vips_rot().

Parameters

in

input image

 

out

output image

 

...

NULL-terminated list of optional named arguments

 

Returns

0 on success, -1 on error


vips_rot180 ()

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

Rotate in by 180 degress. A convenience function over vips_rot().

See also: vips_rot().

[method]

Parameters

in

input image

 

out

output image.

[out]

...

NULL-terminated list of optional named arguments

 

Returns

0 on success, -1 on error


vips_rot270 ()

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

Rotate in by 270 degress clockwise. A convenience function over vips_rot().

See also: vips_rot().

[method]

Parameters

in

input image

 

out

output image.

[out]

...

NULL-terminated list of optional named arguments

 

Returns

0 on success, -1 on error


vips_rot45 ()

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

Optional arguments:

Rotate in by a multiple of 45 degrees. Odd-length sides and square images only.

This operation is useful for rotating convolution masks. Use vips_similarity() to rotate images by arbitrary angles.

See also: vips_rot(), vips_similarity().

[method]

Parameters

in

input image

 

out

output image.

[out]

...

NULL-terminated list of optional named arguments

 

Returns

0 on success, -1 on error


vips_autorot_get_angle ()

VipsAngle
vips_autorot_get_angle (VipsImage *image);

Examine the metadata on im and return the VipsAngle to rotate by to turn the image upright.

See also: vips_autorot().

Parameters

image

image to fetch orientation from

 

Returns

the VipsAngle to rotate by to make the image upright.


vips_autorot_remove_angle ()

void
vips_autorot_remove_angle (VipsImage *image);

Remove the orientation tag on image . Also remove any exif orientation tags.

See also: vips_autorot_get_angle().

[method]

Parameters

image

image to remove orientation from

 

vips_autorot ()

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

Optional arguments:

  • angle : output VipsAngle the image was rotated by

Look at the image metadata and rotate the image to make it upright. The VIPS_META_ORIENTATION tag is removed from out to prevent accidental double rotation.

Read angle to find the amount the image was rotated by.

vips only supports the four simple rotations, it does not support the various mirror modes.

See also: vips_autorot_get_angle(), vips_autorot_remove_angle(), vips_rot().

[method]

Parameters

in

input image

 

out

output image.

[out]

...

NULL-terminated list of optional named arguments

 

Returns

0 on success, -1 on error


vips_zoom ()

int
vips_zoom (VipsImage *in,
           VipsImage **out,
           int xfac,
           int yfac,
           ...);

Zoom an image by repeating pixels. This is fast nearest-neighbour zoom.

See also: vips_affine(), vips_subsample().

[method]

Parameters

in

input image

 

out

output image.

[out]

xfac

horizontal scale factor

 

yfac

vertical scale factor

 

...

NULL-terminated list of optional named arguments

 

Returns

0 on success, -1 on error.


vips_subsample ()

int
vips_subsample (VipsImage *in,
                VipsImage **out,
                int xfac,
                int yfac,
                ...);

Optional arguments:

  • point : turn on point sample mode

Subsample an image by an integer fraction. This is fast, nearest-neighbour shrink.

For small horizontal shrinks, this operation will fetch lines of pixels from in and then subsample that line. For large shrinks it will fetch single pixels.

If point is set, in will always be sampled in points. This can be faster if the previous operations in the pipeline are very slow.

See also: vips_affine(), vips_shrink(), vips_zoom().

[method]

Parameters

in

input image

 

out

output image.

[out]

xfac

horizontal shrink factor

 

yfac

vertical shrink factor

 

...

NULL-terminated list of optional named arguments

 

Returns

0 on success, -1 on error.


vips_cast ()

int
vips_cast (VipsImage *in,
           VipsImage **out,
           VipsBandFormat format,
           ...);

Optional arguments:

  • shift : gboolean, integer values are shifted

Convert in to format . You can convert between any pair of formats. Floats are truncated (not rounded). Out of range values are clipped.

Casting from complex to real returns the real part.

If shift is TRUE, integer values are shifted up and down. For example, casting from unsigned 8 bit to unsigned 16 bit would shift every value left by 8 bits. The bottom bit is copied into the new bits, so 255 would become 65535.

See also: vips_scale(), vips_complexform(), vips_real(), vips_imag(), vips_cast_uchar(), vips_msb().

[method]

Parameters

in

input image

 

out

output image.

[out]

format

format to convert to

 

...

NULL-terminated list of optional named arguments

 

Returns

0 on success, -1 on error


vips_cast_uchar ()

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

Convert in to VIPS_FORMAT_UCHAR. See vips_cast().

[method]

Parameters

in

input image

 

out

output image.

[out]

...

NULL-terminated list of optional named arguments

 

Returns

0 on success, -1 on error


vips_cast_char ()

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

Convert in to VIPS_FORMAT_CHAR. See vips_cast().

[method]

Parameters

in

input image

 

out

output image.

[out]

...

NULL-terminated list of optional named arguments

 

Returns

0 on success, -1 on error


vips_cast_ushort ()

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

Convert in to VIPS_FORMAT_USHORT. See vips_cast().

[method]

Parameters

in

input image

 

out

output image.

[out]

...

NULL-terminated list of optional named arguments

 

Returns

0 on success, -1 on error


vips_cast_short ()

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

Convert in to VIPS_FORMAT_SHORT. See vips_cast().

[method]

Parameters

in

input image

 

out

output image.

[out]

...

NULL-terminated list of optional named arguments

 

Returns

0 on success, -1 on error


vips_cast_uint ()

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

Convert in to VIPS_FORMAT_UINT. See vips_cast().

[method]

Parameters

in

input image

 

out

output image.

[out]

...

NULL-terminated list of optional named arguments

 

Returns

0 on success, -1 on error


vips_cast_int ()

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

Convert in to VIPS_FORMAT_INT. See vips_cast().

[method]

Parameters

in

input image

 

out

output image.

[out]

...

NULL-terminated list of optional named arguments

 

Returns

0 on success, -1 on error


vips_cast_float ()

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

Convert in to VIPS_FORMAT_FLOAT. See vips_cast().

[method]

Parameters

in

input image

 

out

output image.

[out]

...

NULL-terminated list of optional named arguments

 

Returns

0 on success, -1 on error


vips_cast_double ()

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

Convert in to VIPS_FORMAT_DOUBLE. See vips_cast().

[method]

Parameters

in

input image

 

out

output image.

[out]

...

NULL-terminated list of optional named arguments

 

Returns

0 on success, -1 on error


vips_cast_complex ()

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

Convert in to VIPS_FORMAT_COMPLEX. See vips_cast().

[method]

Parameters

in

input image

 

out

output image.

[out]

...

NULL-terminated list of optional named arguments

 

Returns

0 on success, -1 on error


vips_cast_dpcomplex ()

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

Convert in to VIPS_FORMAT_DPCOMPLEX. See vips_cast().

[method]

Parameters

in

input image

 

out

output image.

[out]

...

NULL-terminated list of optional named arguments

 

Returns

0 on success, -1 on error


vips_scale ()

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

Optional arguments:

  • log : log scale pixels

  • exp : exponent for log scale

Search the image for the maximum and minimum value, then return the image as unsigned 8-bit, scaled so that the maximum value is 255 and the minimum is zero.

If log is set, transform with log10(1.0 + pow(x, exp )) + .5, then scale so max == 255. By default, exp is 0.25.

See also: vips_cast().

[method]

Parameters

in

input image

 

out

output image.

[out]

...

NULL-terminated list of optional named arguments

 

Returns

0 on success, -1 on error


vips_msb ()

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

Optional arguments:

  • band : gint, msb just this band

Turn any integer image to 8-bit unsigned char by discarding all but the most significant byte. Signed values are converted to unsigned by adding 128.

Use band to make a one-band 8-bit image.

This operator also works for LABQ coding.

See also: vips_scale(), vips_cast().

[method]

Parameters

in

input image

 

out

output image.

[out]

...

NULL-terminated list of optional named arguments

 

Returns

0 on success, -1 on error.


vips_byteswap ()

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

Swap the byte order in an image.

See also: vips_rawload().

[method]

Parameters

in

input image

 

out

output image.

[out]

...

NULL-terminated list of optional named arguments

 

Returns

0 on success, -1 on error.


vips_bandjoin ()

int
vips_bandjoin (VipsImage **in,
               VipsImage **out,
               int n,
               ...);

Join a set of images together, bandwise.

If the images have n and m bands, then the output image will have n + m bands, with the first n coming from the first image and the last m from the second.

If the images differ in size, the smaller images are enlarged to match the larger by adding zero pixels along the bottom and right.

The input images are cast up to the smallest common type (see table Smallest common format in

arithmetic).

See also: vips_insert().

Parameters

in

array of input images.

[array length=n][transfer none]

out

output image.

[out]

n

number of input images

 

...

NULL-terminated list of optional named arguments

 

Returns

0 on success, -1 on error


vips_bandjoin2 ()

int
vips_bandjoin2 (VipsImage *in1,
                VipsImage *in2,
                VipsImage **out,
                ...);

Join a pair of images together, bandwise. See vips_bandjoin().

Parameters

in1

first input image

 

in2

second input image

 

out

output image.

[out]

...

NULL-terminated list of optional named arguments

 

Returns

0 on success, -1 on error


vips_bandjoin_const ()

int
vips_bandjoin_const (VipsImage *in,
                     VipsImage **out,
                     double *c,
                     int n,
                     ...);

Append a set of constant bands to an image.

See also: vips_bandjoin().

[method]

Parameters

in

input image

 

out

output image.

[out]

c

array of constants to append.

[array length=n]

n

number of constants

 

...

NULL-terminated list of optional named arguments

 

Returns

0 on success, -1 on error


vips_bandjoin_const1 ()

int
vips_bandjoin_const1 (VipsImage *in,
                      VipsImage **out,
                      double c,
                      ...);

Append a single constant band to an image.

[method]

Parameters

in

input image

 

out

output image.

[out]

c

constant to append

 

...

NULL-terminated list of optional named arguments

 

Returns

0 on success, -1 on error


vips_bandrank ()

int
vips_bandrank (VipsImage **in,
               VipsImage **out,
               int n,
               ...);

Optional arguments:

  • index : pick this index from list of sorted values

Sorts the images in band-element-wise, then outputs an image in which each band element is selected from the sorted list by the index parameter. For example, if index is zero, then each output band element will be the minimum of all the corresponding input band elements.

By default, index is -1, meaning pick the median value.

It works for any uncoded, non-complex image type. Images are cast up to the smallest common-format.

Any image can have either 1 band or n bands, where n is the same for all the non-1-band images. Single band images are then effectively copied to make n-band images.

Smaller input images are expanded by adding black pixels.

See also: vips_rank().

Parameters

in

array of input images.

[array length=n]

out

output image.

[out]

n

number of input images

 

...

NULL-terminated list of optional named arguments

 

Returns

0 on success, -1 on error


vips_bandfold ()

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

Optional arguments:

  • factor : fold by this factor

Fold up an image horizontally: width is collapsed into bands. Use factor to set how much to fold by: factor 3, for example, will make the output image three times narrower than the input, and with three times as many bands. By default the whole of the input width is folded up.

See also: vips_csvload(), vips_bandunfold().

[method]

Parameters

in

input image

 

out

output image.

[out]

...

NULL-terminated list of optional named arguments

 

Returns

0 on success, -1 on error.


vips_bandunfold ()

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

Optional arguments:

  • factor : unfold by this factor

Unfold image bands into x axis. Use factor to set how much to unfold by: factor 3, for example, will make the output image three times wider than the input, and with one third as many bands. By default, all bands are unfolded.

See also: vips_csvload(), vips_bandfold().

[method]

Parameters

in

input image

 

out

output image.

[out]

...

NULL-terminated list of optional named arguments

 

Returns

0 on success, -1 on error.


vips_bandbool ()

int
vips_bandbool (VipsImage *in,
               VipsImage **out,
               VipsOperationBoolean boolean,
               ...);

Perform various boolean operations across the bands of an image. For example, a three-band uchar image operated on with VIPS_OPERATION_BOOLEAN_AND will produce a one-band uchar image where each pixel is the bitwise and of the band elements of the corresponding pixel in the input image.

The output image is the same format as the input image for integer types. Float types are cast to int before processing. Complex types are not supported.

The output image always has one band.

This operation is useful in conjuction with vips_relational(). You can use it to see if all image bands match exactly.

See also: vips_boolean_const().

[method]

Parameters

in

left-hand input VipsImage

 

out

output VipsImage.

[out]

boolean

boolean operation to perform

 

...

NULL-terminated list of optional named arguments

 

Returns

0 on success, -1 on error


vips_bandand ()

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

Perform VIPS_OPERATION_BOOLEAN_AND on an image. See vips_bandbool().

[method]

Parameters

in

left-hand input VipsImage

 

out

output VipsImage.

[out]

...

NULL-terminated list of optional named arguments

 

Returns

0 on success, -1 on error


vips_bandor ()

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

Perform VIPS_OPERATION_BOOLEAN_OR on an image. See vips_bandbool().

[method]

Parameters

in

left-hand input VipsImage

 

out

output VipsImage.

[out]

...

NULL-terminated list of optional named arguments

 

Returns

0 on success, -1 on error


vips_bandeor ()

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

Perform VIPS_OPERATION_BOOLEAN_EOR on an image. See vips_bandbool().

[method]

Parameters

in

left-hand input VipsImage

 

out

output VipsImage.

[out]

...

NULL-terminated list of optional named arguments

 

Returns

0 on success, -1 on error


vips_bandmean ()

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

This operation writes a one-band image where each pixel is the average of the bands for that pixel in the input image. The output band format is the same as the input band format. Integer types use round-to-nearest averaging.

See also: vips_add(), vips_avg(), vips_recomb()

[method]

Parameters

in

input image

 

out

output image.

[out]

...

NULL-terminated list of optional named arguments

 

Returns

0 on success, -1 on error


vips_recomb ()

int
vips_recomb (VipsImage *in,
             VipsImage **out,
             VipsImage *m,
             ...);

This operation recombines an image's bands. Each pixel in in is treated as an n-element vector, where n is the number of bands in in , and multipled by the n x m matrix m to produce the m-band image out .

out is always float, unless in is double, in which case out is double too. No complex images allowed.

It's useful for various sorts of colour space conversions.

See also: vips_bandmean().

[method]

Parameters

in

input image

 

out

output image.

[out]

m

recombination matrix

 

...

NULL-terminated list of optional named arguments

 

Returns

0 on success, -1 on error


vips_ifthenelse ()

int
vips_ifthenelse (VipsImage *cond,
                 VipsImage *in1,
                 VipsImage *in2,
                 VipsImage **out,
                 ...);

Optional arguments:

  • blend : blend smoothly between in1 and in2

This operation scans the condition image cond and uses it to select pixels from either the then image in1 or the else image in2 . Non-zero means in1 , 0 means in2 .

Any image can have either 1 band or n bands, where n is the same for all the non-1-band images. Single band images are then effectively copied to make n-band images.

Images in1 and in2 are cast up to the smallest common format. cond is cast to uchar.

If the images differ in size, the smaller images are enlarged to match the largest by adding zero pixels along the bottom and right.

If blend is TRUE, then values in out are smoothly blended between in1 and in2 using the formula:

out = (cond / 255) * in1 + (1 - cond / 255) * in2

See also: vips_equal().

Parameters

cond

condition VipsImage

 

in1

then VipsImage

 

in2

else VipsImage

 

out

output VipsImage.

[out]

...

NULL-terminated list of optional named arguments

 

Returns

0 on success, -1 on error


vips_flatten ()

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

Optional arguments:

Take the last band of in as an alpha and use it to blend the remaining channels with background .

The alpha channel is 0 - max_alpha , where 1 means 100% image and 0 means 100% background. Non-complex images only. background defaults to zero (black).

max_alpha has the default value 255, or 65535 for images tagged as VIPS_INTERPRETATION_RGB16 or VIPS_INTERPRETATION_GREY16.

Useful for flattening PNG images to RGB.

See also: vips_premultiply(), vips_pngload().

[method]

Parameters

in

input image

 

out

output image.

[out]

...

NULL-terminated list of optional named arguments

 

Returns

0 on success, -1 on error


vips_addalpha ()

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

Append an alpha channel.

See also: vips_image_hasalpha().

[method]

Parameters

in

input image

 

out

output image.

[out]

...

NULL-terminated list of optional named arguments

 

Returns

0 on success, -1 on error


vips_premultiply ()

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

Optional arguments:

  • max_alpha : gdouble, maximum value for alpha

Premultiplies any alpha channel. The final band is taken to be the alpha and the bands are transformed as:

1
2
3
alpha = clip( 0, in[in.bands - 1], @max_alpha ); 
norm = alpha / @max_alpha; 
out = [in[0] * norm, ..., in[in.bands - 1] * norm, alpha];

So for an N-band image, the first N - 1 bands are multiplied by the clipped and normalised final band, the final band is clipped. If there is only a single band, the image is passed through unaltered.

The result is VIPS_FORMAT_FLOAT unless the input format is VIPS_FORMAT_DOUBLE, in which case the output is double as well.

max_alpha has the default value 255, or 65535 for images tagged as VIPS_INTERPRETATION_RGB16 or VIPS_INTERPRETATION_GREY16.

Non-complex images only.

See also: vips_unpremultiply(), vips_flatten().

[method]

Parameters

in

input image

 

out

output image.

[out]

...

NULL-terminated list of optional named arguments

 

Returns

0 on success, -1 on error


vips_unpremultiply ()

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

Optional arguments:

  • max_alpha : gdouble, maximum value for alpha

Unpremultiplies any alpha channel. The final band is taken to be the alpha and the bands are transformed as:

1
2
3
4
5
6
alpha = (int) clip( 0, in[in.bands - 1], @max_alpha ); 
norm = (double) alpha / @max_alpha; 
if( alpha == 0 )
	out = [0, ..., 0, alpha];
else
	out = [in[0] / norm, ..., in[in.bands - 1] / norm, alpha];

So for an N-band image, the first N - 1 bands are divided by the clipped and normalised final band, the final band is clipped. If there is only a single band, the image is passed through unaltered.

The result is VIPS_FORMAT_FLOAT unless the input format is VIPS_FORMAT_DOUBLE, in which case the output is double as well.

max_alpha has the default value 255, or 65535 for images tagged as VIPS_INTERPRETATION_RGB16 or VIPS_INTERPRETATION_GREY16.

Non-complex images only.

See also: vips_premultiply(), vips_flatten().

[method]

Parameters

in

input image

 

out

output image.

[out]

...

NULL-terminated list of optional named arguments

 

Returns

0 on success, -1 on error


vips_composite ()

int
vips_composite (VipsImage **in,
                VipsImage **out,
                int n,
                int *mode,
                ...);

Optional arguments:

Composite an array of images together.

Images are placed in a stack, with in [0] at the bottom and in [n - 1] at the top. Pixels are blended together working from the bottom upwards, with the blend mode at each step being set by the corresponding VipsBlendMode in mode .

Images are transformed to a compositing space before processing. This is VIPS_INTERPRETATION_sRGB, VIPS_INTERPRETATION_B_W, VIPS_INTERPRETATION_RGB16, or VIPS_INTERPRETATION_GREY16 by default, depending on how many bands and bits the input images have. You can select any other space, such as VIPS_INTERPRETATION_LAB or VIPS_INTERPRETATION_scRGB.

The output image is in the compositing space. It will always be VIPS_FORMAT_FLOAT unless one of the inputs is VIPS_FORMAT_DOUBLE, in which case the output will be double as well.

Complex images are not supported.

The output image will always have an alpha band. A solid alpha is added to any input missing an alpha.

The images do not need to match in size or format. They will be expanded to the smallest common size and format in the usual way. Images are positioned using the x and y parameters, if set.

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 .

See also: vips_insert().

[method]

Parameters

in

array of input images.

[array length=n][transfer none]

out

output image.

[out]

n

number of input images

 

mode

array of (n - 1) VipsBlendMode

 

...

NULL-terminated list of optional named arguments

 

Returns

0 on success, -1 on error


vips_composite2 ()

int
vips_composite2 (VipsImage *base,
                 VipsImage *overlay,
                 VipsImage **out,
                 VipsBlendMode mode1,
                 ...);

Optional arguments:

  • compositing_space : VipsInterpretation to composite in

  • premultiplied : gboolean, images are already premultiplied

  • x : gint, position of overlay

  • y : gint, position of overlay

Composite overlay on top of base with mode . See vips_composite().

[method]

Parameters

base

first input image

 

overlay

second input image

 

out

output image.

[out]

mode

composite with this blend mode

 

...

NULL-terminated list of optional named arguments

 

Returns

0 on success, -1 on error


vips_falsecolour ()

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

Force in to 1 band, 8-bit, then transform to a 3-band 8-bit image with a false colour map. The map is supposed to make small differences in brightness more obvious.

See also: vips_maplut().

[method]

Parameters

in

input image

 

out

output image.

[out]

...

NULL-terminated list of optional named arguments

 

Returns

0 on success, -1 on error


vips_gamma ()

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

Optional arguments:

  • exponent : gamma, default 1.0 / 2.4

Calculate in ** (1 / exponent ), normalising to the maximum range of the input type. For float types use 1.0 as the maximum.

See also: vips_identity(), vips_pow_const1(), vips_maplut()

[method]

Parameters

in

input image

 

out

output image.

[out]

...

NULL-terminated list of optional named arguments

 

Returns

0 on success, -1 on error

Types and Values

enum VipsExtend

See vips_embed(), vips_conv(), vips_affine() and so on.

When the edges of an image are extended, you can specify how you want the extension done.

VIPS_EXTEND_BLACK --- new pixels are black, ie. all bits are zero.

VIPS_EXTEND_COPY --- each new pixel takes the value of the nearest edge pixel

VIPS_EXTEND_REPEAT --- the image is tiled to fill the new area

VIPS_EXTEND_MIRROR --- the image is reflected and tiled to reduce hash edges

VIPS_EXTEND_WHITE --- new pixels are white, ie. all bits are set

VIPS_EXTEND_BACKGROUND --- colour set from the background property

We have to specify the exact value of each enum member since we have to keep these frozen for back compat with vips7.

See also: vips_embed().

Members

VIPS_EXTEND_BLACK

extend with black (all 0) pixels

 

VIPS_EXTEND_COPY

copy the image edges

 

VIPS_EXTEND_REPEAT

repeat the whole image

 

VIPS_EXTEND_MIRROR

mirror the whole image

 

VIPS_EXTEND_WHITE

extend with white (all bits set) pixels

 

VIPS_EXTEND_BACKGROUND

extend with colour from the background property

 

VIPS_EXTEND_LAST

   

enum VipsCompassDirection

A direction on a compass. Used for vips_gravity(), for example.

Members

VIPS_COMPASS_DIRECTION_CENTRE

centre

 

VIPS_COMPASS_DIRECTION_NORTH

north

 

VIPS_COMPASS_DIRECTION_EAST

east

 

VIPS_COMPASS_DIRECTION_SOUTH

south

 

VIPS_COMPASS_DIRECTION_WEST

west

 

VIPS_COMPASS_DIRECTION_NORTH_EAST

north-east

 

VIPS_COMPASS_DIRECTION_SOUTH_EAST

south-east

 

VIPS_COMPASS_DIRECTION_SOUTH_WEST

south-west

 

VIPS_COMPASS_DIRECTION_NORTH_WEST

north-west

 

VIPS_COMPASS_DIRECTION_LAST

   

enum VipsDirection

See vips_flip(), vips_join() and so on.

Operations like vips_flip() need to be told whether to flip left-right or top-bottom.

See also: vips_flip(), vips_join().

Members

VIPS_DIRECTION_HORIZONTAL

left-right

 

VIPS_DIRECTION_VERTICAL

top-bottom

 

VIPS_DIRECTION_LAST

   

enum VipsAlign

See vips_join() and so on.

Operations like vips_join() need to be told whether to align images on the low or high coordinate edge, or centre.

See also: vips_join().

Members

VIPS_ALIGN_LOW

align low coordinate edge

 

VIPS_ALIGN_CENTRE

align centre

 

VIPS_ALIGN_HIGH

align high coordinate edge

 

VIPS_ALIGN_LAST

   

enum VipsAngle

See vips_rot() and so on.

Fixed rotate angles.

See also: vips_rot().

Members

VIPS_ANGLE_D0

no rotate

 

VIPS_ANGLE_D90

90 degrees clockwise

 

VIPS_ANGLE_D180

180 degree rotate

 

VIPS_ANGLE_D270

90 degrees anti-clockwise

 

VIPS_ANGLE_LAST

   

enum VipsAngle45

See vips_rot45() and so on.

Fixed rotate angles.

See also: vips_rot45().

Members

VIPS_ANGLE45_D0

no rotate

 

VIPS_ANGLE45_D45

45 degrees clockwise

 

VIPS_ANGLE45_D90

90 degrees clockwise

 

VIPS_ANGLE45_D135

135 degrees clockwise

 

VIPS_ANGLE45_D180

180 degrees

 

VIPS_ANGLE45_D225

135 degrees anti-clockwise

 

VIPS_ANGLE45_D270

90 degrees anti-clockwise

 

VIPS_ANGLE45_D315

45 degrees anti-clockwise

 

VIPS_ANGLE45_LAST

   

enum VipsInteresting

Pick the algorithm vips uses to decide image "interestingness". This is used by vips_smartcrop(), for example, to decide what parts of the image to keep.

See also: vips_smartcrop().

Members

VIPS_INTERESTING_NONE

do nothing

 

VIPS_INTERESTING_CENTRE

just take the centre

 

VIPS_INTERESTING_ENTROPY

use an entropy measure

 

VIPS_INTERESTING_ATTENTION

look for features likely to draw human attention

 

VIPS_INTERESTING_LAST

   

enum VipsBlendMode

The various Porter-Duff and PDF blend modes. See vips_composite(), for example.

The Cairo docs have a nice explanation of all the blend modes:

https://www.cairographics.org/operators

The non-separable modes are not implemented.

Members

VIPS_BLEND_MODE_CLEAR

where the second object is drawn, the first is removed

 

VIPS_BLEND_MODE_SOURCE

the second object is drawn as if nothing were below

 

VIPS_BLEND_MODE_OVER

the image shows what you would expect if you held two semi-transparent slides on top of each other

 

VIPS_BLEND_MODE_IN

the first object is removed completely, the second is only drawn where the first was

 

VIPS_BLEND_MODE_OUT

the second is drawn only where the first isn't

 

VIPS_BLEND_MODE_ATOP

this leaves the first object mostly intact, but mixes both objects in the overlapping area

 

VIPS_BLEND_MODE_DEST

leaves the first object untouched, the second is discarded completely

 

VIPS_BLEND_MODE_DEST_OVER

like OVER, but swaps the arguments

 

VIPS_BLEND_MODE_DEST_IN

like IN, but swaps the arguments

 

VIPS_BLEND_MODE_DEST_OUT

like OUT, but swaps the arguments

 

VIPS_BLEND_MODE_DEST_ATOP

like ATOP, but swaps the arguments

 

VIPS_BLEND_MODE_XOR

something like a difference operator

 

VIPS_BLEND_MODE_ADD

a bit like adding the two images

 

VIPS_BLEND_MODE_SATURATE

a bit like the darker of the two

 

VIPS_BLEND_MODE_MULTIPLY

at least as dark as the darker of the two inputs

 

VIPS_BLEND_MODE_SCREEN

at least as light as the lighter of the inputs

 

VIPS_BLEND_MODE_OVERLAY

multiplies or screens colors, depending on the lightness

 

VIPS_BLEND_MODE_DARKEN

the darker of each component

 

VIPS_BLEND_MODE_LIGHTEN

the lighter of each component

 

VIPS_BLEND_MODE_COLOUR_DODGE

brighten first by a factor second

 

VIPS_BLEND_MODE_COLOUR_BURN

darken first by a factor of second

 

VIPS_BLEND_MODE_HARD_LIGHT

multiply or screen, depending on lightness

 

VIPS_BLEND_MODE_SOFT_LIGHT

darken or lighten, depending on lightness

 

VIPS_BLEND_MODE_DIFFERENCE

difference of the two

 

VIPS_BLEND_MODE_EXCLUSION

somewhat like DIFFERENCE, but lower-contrast

 

VIPS_BLEND_MODE_LAST

   

See Also

resample