## conversion

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

## Stability Level

Stable, unless otherwise indicated

## Synopsis

    #include <vips/vips.h>

    enum                VipsExtend;
    enum                VipsDirection;
    enum                VipsAlign;
    enum                VipsAngle;
    enum                VipsAngle45;
    int                 vips_copy                           (VipsImage *in,
                                                             VipsImage **out,
                                                             ...);
    int                 vips_tilecache                      (VipsImage *in,
                                                             VipsImage **out,
                                                             ...);
    int                 vips_linecache                      (VipsImage *in,
                                                             VipsImage **out,
                                                             ...);
    int                 vips_sequential                     (VipsImage *in,
                                                             VipsImage **out,
                                                             ...);
    int                 vips_cache                          (VipsImage *in,
                                                             VipsImage **out,
                                                             ...);
    int                 vips_copy_file                      (VipsImage *in,
                                                             VipsImage **out,
                                                             ...);
    int                 vips_embed                          (VipsImage *in,
                                                             VipsImage **out,
                                                             int x,
                                                             int y,
                                                             int width,
                                                             int height,
                                                             ...);
    int                 vips_flip                           (VipsImage *in,
                                                             VipsImage **out,
                                                             VipsDirection direction,
                                                             ...);
    int                 vips_insert                         (VipsImage *main,
                                                             VipsImage *sub,
                                                             VipsImage **out,
                                                             int x,
                                                             int y,
                                                             ...);
    int                 vips_join                           (VipsImage *main,
                                                             VipsImage *sub,
                                                             VipsImage **out,
                                                             VipsDirection direction,
                                                             ...);
    int                 vips_extract_area                   (VipsImage *input,
                                                             VipsImage **output,
                                                             int left,
                                                             int top,
                                                             int width,
                                                             int height,
                                                             ...);
    int                 vips_crop                           (VipsImage *input,
                                                             VipsImage **output,
                                                             int left,
                                                             int top,
                                                             int width,
                                                             int height,
                                                             ...);
    int                 vips_extract_band                   (VipsImage *input,
                                                             VipsImage **output,
                                                             int band,
                                                             ...);
    int                 vips_replicate                      (VipsImage *in,
                                                             VipsImage **out,
                                                             int across,
                                                             int down,
                                                             ...);
    int                 vips_grid                           (VipsImage *in,
                                                             VipsImage **out,
                                                             int tile_height,
                                                             int across,
                                                             int down,
                                                             ...);
    int                 vips_wrap                           (VipsImage *in,
                                                             VipsImage **out,
                                                             ...);
    int                 vips_rot                            (VipsImage *in,
                                                             VipsImage **out,
                                                             VipsAngle angle,
                                                             ...);
    int                 vips_rot45                          (VipsImage *in,
                                                             VipsImage **out,
                                                             ...);
    int                 vips_zoom                           (VipsImage *in,
                                                             VipsImage **out,
                                                             int xfac,
                                                             int yfac,
                                                             ...);
    int                 vips_subsample                      (VipsImage *in,
                                                             VipsImage **out,
                                                             int xfac,
                                                             int yfac,
                                                             ...);
    int                 vips_cast                           (VipsImage *in,
                                                             VipsImage **out,
                                                             VipsBandFormat format,
                                                             ...);
    int                 vips_cast_uchar                     (VipsImage *in,
                                                             VipsImage **out,
                                                             ...);
    int                 vips_cast_char                      (VipsImage *in,
                                                             VipsImage **out,
                                                             ...);
    int                 vips_cast_ushort                    (VipsImage *in,
                                                             VipsImage **out,
                                                             ...);
    int                 vips_cast_short                     (VipsImage *in,
                                                             VipsImage **out,
                                                             ...);
    int                 vips_cast_uint                      (VipsImage *in,
                                                             VipsImage **out,
                                                             ...);
    int                 vips_cast_int                       (VipsImage *in,
                                                             VipsImage **out,
                                                             ...);
    int                 vips_cast_float                     (VipsImage *in,
                                                             VipsImage **out,
                                                             ...);
    int                 vips_cast_double                    (VipsImage *in,
                                                             VipsImage **out,
                                                             ...);
    int                 vips_cast_complex                   (VipsImage *in,
                                                             VipsImage **out,
                                                             ...);
    int                 vips_cast_dpcomplex                 (VipsImage *in,
                                                             VipsImage **out,
                                                             ...);
    int                 vips_scale                          (VipsImage *in,
                                                             VipsImage **out,
                                                             ...);
    int                 vips_msb                            (VipsImage *in,
                                                             VipsImage **out,
                                                             ...);
    int                 vips_bandjoin                       (VipsImage **in,
                                                             VipsImage **out,
                                                             int n,
                                                             ...);
    int                 vips_bandjoin2                      (VipsImage *in1,
                                                             VipsImage *in2,
                                                             VipsImage **out,
                                                             ...);
    int                 vips_bandrank                       (VipsImage **in,
                                                             VipsImage **out,
                                                             int n,
                                                             ...);
    int                 vips_bandbool                       (VipsImage *in,
                                                             VipsImage **out,
                                                             VipsOperationBoolean operation,
                                                             ...);
    int                 vips_bandand                        (VipsImage *in,
                                                             VipsImage **out,
                                                             ...);
    int                 vips_bandor                         (VipsImage *in,
                                                             VipsImage **out,
                                                             ...);
    int                 vips_bandeor                        (VipsImage *in,
                                                             VipsImage **out,
                                                             ...);
    int                 vips_bandmean                       (VipsImage *in,
                                                             VipsImage **out,
                                                             ...);
    int                 vips_recomb                         (VipsImage *in,
                                                             VipsImage **out,
                                                             VipsImage *m,
                                                             ...);
    int                 vips_ifthenelse                     (VipsImage *cond,
                                                             VipsImage *in1,
                                                             VipsImage *in2,
                                                             VipsImage **out,
                                                             ...);
    int                 vips_flatten                        (VipsImage *in,
                                                             VipsImage **out,
                                                             ...);
    int                 vips_falsecolour                    (VipsImage *in,
                                                             VipsImage **out,
                                                             ...);
    int                 vips_gamma                          (VipsImage *in,
                                                             VipsImage **out,
                                                             ...);
    int                 im_insertset                        (VipsImage *main,
                                                             VipsImage *sub,
                                                             VipsImage *out,
                                                             int n,
                                                             int *x,
                                                             int *y);

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

## Details

### enum VipsExtend

    typedef enum {
    	VIPS_EXTEND_BLACK,
    	VIPS_EXTEND_COPY,
    	VIPS_EXTEND_REPEAT,
    	VIPS_EXTEND_MIRROR,
    	VIPS_EXTEND_WHITE,
    	VIPS_EXTEND_BACKGROUND,
    	VIPS_EXTEND_LAST
    } 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()`.

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

    typedef enum {
    	VIPS_DIRECTION_HORIZONTAL,
    	VIPS_DIRECTION_VERTICAL,
    	VIPS_DIRECTION_LAST
    } 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()`.

`VIPS_DIRECTION_HORIZONTAL` | left-right
`VIPS_DIRECTION_VERTICAL` | top-bottom
`VIPS_DIRECTION_LAST` |

### enum VipsAlign

    typedef enum {
    	VIPS_ALIGN_LOW,
    	VIPS_ALIGN_CENTRE,
    	VIPS_ALIGN_HIGH,
    	VIPS_ALIGN_LAST
    } 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()`.

`VIPS_ALIGN_LOW` | align low coordinate edge
`VIPS_ALIGN_CENTRE` | align centre
`VIPS_ALIGN_HIGH` | align high coordinate edge
`VIPS_ALIGN_LAST` |

### enum VipsAngle

    typedef enum {
    	VIPS_ANGLE_0,
    	VIPS_ANGLE_90,
    	VIPS_ANGLE_180,
    	VIPS_ANGLE_270,
    	VIPS_ANGLE_LAST
    } VipsAngle;

See `vips_rot()` and so on.

Fixed rotate angles.

See also: `vips_rot()`.

`VIPS_ANGLE_0` | no rotate
`VIPS_ANGLE_90` | 90 degrees anti-clockwise
`VIPS_ANGLE_180` | 180 degree rotate
`VIPS_ANGLE_270` | 90 degrees clockwise
`VIPS_ANGLE_LAST` |

### enum VipsAngle45

    typedef enum {
    	VIPS_ANGLE45_0,
    	VIPS_ANGLE45_45,
    	VIPS_ANGLE45_90,
    	VIPS_ANGLE45_135,
    	VIPS_ANGLE45_180,
    	VIPS_ANGLE45_225,
    	VIPS_ANGLE45_270,
    	VIPS_ANGLE45_315,
    	VIPS_ANGLE45_LAST
    } VipsAngle45;

`VIPS_ANGLE45_0` |
`VIPS_ANGLE45_45` |
`VIPS_ANGLE45_90` |
`VIPS_ANGLE45_135` |
`VIPS_ANGLE45_180` |
`VIPS_ANGLE45_225` |
`VIPS_ANGLE45_270` |
`VIPS_ANGLE45_315` |
`VIPS_ANGLE45_LAST` |

### vips_copy ()

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

Optional arguments:

`width`: set image width `height`: set image height `bands`: set image bands `format`: set image format `coding`: set image coding `interpretation`: set image interpretation `xres`: set image xres `yres`: set image yres `xoffset`: set image xoffset `yoffset`: set image yoffset `swap`: swap byte order

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 set any or all header fields during the copy. Some header fields, such as "xres", the horizontal resolution, are safe to change in any way, others, such as "width" will cause immediate crashes if they are not set carefully.

Setting `swap` to `TRUE` will make `vips_copy()` swap the byte ordering of pixels according to the image's format.

`in` : | input image
`out` : | output image
`...` : | `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_image_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 or VIPS_ACCESS_SEQUENTIAL_UNBUFFERED, 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()`.

`in` : | input image
`out` : | output image
`...` : | `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. If you know you will not be making any non-local access, you can save some memory and set `access` to VIPS_ACCESS_SEQUENTIAL_UNBUFFERED.

Each cache tile is made with a single call to `vips_image_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 or VIPS_ACCESS_SEQUENTIAL_UNBUFFERED, 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()`.

`in` : | input image
`out` : | output image
`...` : | `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:

`trace`: trace requests `strip_height`: height of cache strips `access`: access pattern

This operation behaves rather like `vips_copy()` between images `in` and `out`, except that it checks that pixels are only requested top-to-bottom. If a thread makes an out of order request, it is stalled until the pack catches up.

This operation is useful for loading file formats which are strictly top-to-bottom, like PNG.

If `trace` is true, the operation will print diagnostic messages for each block of pixels which are processed. This can help find the cause of non-sequential accesses.

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

`access` can be set to VIPS_ACCESS_SEQUENTIAL_UNBUFFERED, meaning don't keep a large cache behind the read point. This can save some memory.

See also: `vips_image_cache()`.

`in` : | input image
`out` : | output image
`...` : | `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.

See also: `vips_tilecache()`.

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

`in` : | input image
`out` : | output image
`...` : | `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:

`extend`: how to generate the edge pixels (default: black) `background`: colour for edge pixels

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

`in` : | input image
`out` : | output image
`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_flip ()

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

Flips an image left-right or up-down.

See also: `vips_rot()`.

`in` : | input image
`out` : | output image
`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 one image into another. `sub` is inserted into image `main` at position `x`, `y` relative to the top LH corner of `main`.

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

`main` : | big image
`sub` : | small image
`out` : | output image
`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 *main,
                                                             VipsImage *sub,
                                                             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).

See also: `vips_insert()`.

`out` : | output image
`direction` : | join horizontally or vertically
`...` : | `NULL`-terminated list of optional named arguments
Returns : | 0 on success, -1 on error

### vips_extract_area ()

    int                 vips_extract_area                   (VipsImage *input,
                                                             VipsImage **output,
                                                             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()`.

`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 *input,
                                                             VipsImage **output,
                                                             int left,
                                                             int top,
                                                             int width,
                                                             int height,
                                                             ...);

A synonym for `vips_extract_area()`.

See also: `vips_extract_bands()`.

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

    int                 vips_extract_band                   (VipsImage *input,
                                                             VipsImage **output,
                                                             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()`.

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

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

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

`in` : | input image
`out` : | output image
`...` : | `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.

See also: `vips_flip()`.

`in` : | input image
`out` : | output image
`angle` : | rotation angle
`...` : | `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:

`angle`: rotation angle

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

See also: `vips_rot()`.

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

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

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

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.

See also: `im_scale()`, `im_ri2c()`.

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

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

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

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

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

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

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

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

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

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

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

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

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

`in` : | array of input images
`out` : | output image
`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()`.

`in1` : | first input image
`in2` : | second input image
`out` : | output image
`...` : | `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 element.

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

`in` : | array of input images
`out` : | output image
`n` : | number of input images
`...` : | `NULL`-terminated list of optional named arguments
Returns : | 0 on success, -1 on error

### vips_bandbool ()

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

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

`out` : | output VipsImage
`operation` : | 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()`.

`in` : | left-hand input VipsImage
`out` : | output VipsImage
`...` : | `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()`.

`in` : | left-hand input VipsImage
`out` : | output VipsImage
`...` : | `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()`.

`in` : | left-hand input VipsImage
`out` : | output VipsImage
`...` : | `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()`

`in` : | input IMAGE
`out` : | output IMAGE
`...` : | `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()`.

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

`cond` : | condition VipsImage
`in1` : | then VipsImage
`in2` : | else VipsImage
`out` : | output VipsImage
`...` : | `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:

`background`: colour for new pixels

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

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

Useful for flattening PNG images to RGB.

See also: `pngload()`.

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

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

`in` : | input image
`out` : | output image
`...` : | `NULL`-terminated list of optional named arguments
Returns : | 0 on success, -1 on error

### im_insertset ()

    int                 im_insertset                        (VipsImage *main,
                                                             VipsImage *sub,
                                                             VipsImage *out,
                                                             int n,
                                                             int *x,
                                                             int *y);

Insert `sub` repeatedly into `main` at the positions listed in the arrays `x`, `y` of length `n`. `out` is the same size as `main`. `sub` is clipped against the edges of `main`.

This operation is fast for large `n`, but will use a memory buffer the size of `out`. It's useful for things like making scatter plots.

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: `im_insert()`, `im_lrjoin()`.

`main` : | big image
`sub` : | small image
`out` : | output image
`n` : | number of positions
`x` : | left positions of `sub`
`y` : | top positions of `sub`
Returns : | 0 on success, -1 on error

## See Also

resample