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

    DOUBLEMASK *        im_vips2mask                        (VipsImage *in,
                                                             const char *filename);
    int                 im_mask2vips                        (DOUBLEMASK *in,
                                                             VipsImage *out);
    int                 im_copy                             (VipsImage *in,
                                                             VipsImage *out);
    int                 im_copy_set                         (VipsImage *in,
                                                             VipsImage *out,
                                                             VipsInterpretation interpretation,
                                                             float xres,
                                                             float yres,
                                                             int xoffset,
                                                             int yoffset);
    int                 im_copy_set_meta                    (VipsImage *in,
                                                             VipsImage *out,
                                                             const char *field,
                                                             GValue *value);
    int                 im_copy_morph                       (VipsImage *in,
                                                             VipsImage *out,
                                                             int bands,
                                                             VipsBandFormat format,
                                                             VipsCoding coding);
    int                 im_copy_swap                        (VipsImage *in,
                                                             VipsImage *out);
    int                 im_copy_native                      (VipsImage *in,
                                                             VipsImage *out,
                                                             gboolean is_msb_first);
    int                 im_copy_file                        (VipsImage *in,
                                                             VipsImage *out);
    int                 im_clip2fmt                         (VipsImage *in,
                                                             VipsImage *out,
                                                             VipsBandFormat fmt);
    int                 im_scale                            (VipsImage *in,
                                                             VipsImage *out);
    int                 im_msb                              (VipsImage *in,
                                                             VipsImage *out);
    int                 im_msb_band                         (VipsImage *in,
                                                             VipsImage *out,
                                                             int band);
    int                 im_c2amph                           (VipsImage *in,
                                                             VipsImage *out);
    int                 im_c2rect                           (VipsImage *in,
                                                             VipsImage *out);
    int                 im_ri2c                             (VipsImage *in1,
                                                             VipsImage *in2,
                                                             VipsImage *out);
    int                 im_c2imag                           (VipsImage *in,
                                                             VipsImage *out);
    int                 im_c2real                           (VipsImage *in,
                                                             VipsImage *out);
    int                 im_scaleps                          (VipsImage *in,
                                                             VipsImage *out);
    int                 im_falsecolour                      (VipsImage *in,
                                                             VipsImage *out);
    int                 im_gaussnoise                       (VipsImage *out,
                                                             int x,
                                                             int y,
                                                             double mean,
                                                             double sigma);
    int                 im_black                            (VipsImage *out,
                                                             int x,
                                                             int y,
                                                             int bands);
    int                 im_text                             (VipsImage *out,
                                                             const char *text,
                                                             const char *font,
                                                             int width,
                                                             int alignment,
                                                             int dpi);
    int                 im_extract_band                     (VipsImage *in,
                                                             VipsImage *out,
                                                             int band);
    int                 im_extract_bands                    (VipsImage *in,
                                                             VipsImage *out,
                                                             int band,
                                                             int nbands);
    int                 im_extract_area                     (VipsImage *in,
                                                             VipsImage *out,
                                                             int left,
                                                             int top,
                                                             int width,
                                                             int height);
    int                 im_extract_areabands                (VipsImage *in,
                                                             VipsImage *out,
                                                             int left,
                                                             int top,
                                                             int width,
                                                             int height,
                                                             int band,
                                                             int nbands);
    int                 im_embed                            (VipsImage *in,
                                                             VipsImage *out,
                                                             int type,
                                                             int x,
                                                             int y,
                                                             int width,
                                                             int height);
    int                 im_bandjoin                         (VipsImage *in1,
                                                             VipsImage *in2,
                                                             VipsImage *out);
    int                 im_gbandjoin                        (VipsImage **in,
                                                             VipsImage *out,
                                                             int n);
    int                 im_insert                           (VipsImage *main,
                                                             VipsImage *sub,
                                                             VipsImage *out,
                                                             int x,
                                                             int y);
    int                 im_insert_noexpand                  (VipsImage *main,
                                                             VipsImage *sub,
                                                             VipsImage *out,
                                                             int x,
                                                             int y);
    int                 im_insertset                        (VipsImage *main,
                                                             VipsImage *sub,
                                                             VipsImage *out,
                                                             int n,
                                                             int *x,
                                                             int *y);
    int                 im_lrjoin                           (VipsImage *left,
                                                             VipsImage *right,
                                                             VipsImage *out);
    int                 im_tbjoin                           (VipsImage *top,
                                                             VipsImage *bottom,
                                                             VipsImage *out);
    int                 im_replicate                        (VipsImage *in,
                                                             VipsImage *out,
                                                             int across,
                                                             int down);
    int                 im_grid                             (VipsImage *in,
                                                             VipsImage *out,
                                                             int tile_height,
                                                             int across,
                                                             int down);
    int                 im_wrap                             (VipsImage *in,
                                                             VipsImage *out,
                                                             int x,
                                                             int y);
    int                 im_fliphor                          (VipsImage *in,
                                                             VipsImage *out);
    int                 im_flipver                          (VipsImage *in,
                                                             VipsImage *out);
    int                 im_rot90                            (VipsImage *in,
                                                             VipsImage *out);
    int                 im_rot180                           (VipsImage *in,
                                                             VipsImage *out);
    int                 im_rot270                           (VipsImage *in,
                                                             VipsImage *out);
    int                 im_subsample                        (VipsImage *in,
                                                             VipsImage *out,
                                                             int xshrink,
                                                             int yshrink);
    int                 im_zoom                             (VipsImage *in,
                                                             VipsImage *out,
                                                             int xfac,
                                                             int yfac);
    int                 im_system                           (VipsImage *im,
                                                             const char *cmd,
                                                             char **out);
    VipsImage *         im_system_image                     (VipsImage *im,
                                                             const char *in_format,
                                                             const char *out_format,
                                                             const char *cmd_format,
                                                             char **log);

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

### im_vips2mask ()

    DOUBLEMASK *        im_vips2mask                        (VipsImage *in,
                                                             const char *filename);

Make a mask from an image. All images are cast to `IM_BANDFMT_DOUBLE` before processing. There are two cases for handling bands:

If the image has a single band, `im_vips2mask()` will write a mask the same size as the image.

If the image has more than one band, it must be one pixel high or wide. In this case the output mask uses that axis to represent band values.

See also: `im_mask2vips()`, `im_measure_area()`.

`in` : | input image
`filename` : | name for output mask
Returns : | a DOUBLEMASK with `outname` set as the name, or NULL on error

### im_mask2vips ()

    int                 im_mask2vips                        (DOUBLEMASK *in,
                                                             VipsImage *out);

Write a one-band, `IM_BANDFMT_DOUBLE` image to `out` based on mask `in`.

See also: `im_vips2mask()`.

`in` : | input mask
`out` : | output image
Returns : | 0 on success, -1 on error

### im_copy ()

    int                 im_copy                             (VipsImage *in,
                                                             VipsImage *out);

Copy an image. VIPS copies images by copying pointers, so this operation is fast, even for very large images.

See also: `im_copy()`, `im_copy_set()`, `im_copy_morph()`.

`in` : | input image
`out` : | output image
Returns : | 0 on success, -1 on error.

### im_copy_set ()

    int                 im_copy_set                         (VipsImage *in,
                                                             VipsImage *out,
                                                             VipsInterpretation interpretation,
                                                             float xres,
                                                             float yres,
                                                             int xoffset,
                                                             int yoffset);

Copy an image, changing informational header fields on the way.

See also: `im_copy()`.

`in` : | input image
`out` : | output image
`type` : | new VipsType to set
`xres` : | new Xres to set
`yres` : | new Yres to set
`xoffset` : | new Xoffset to set
`yoffset` : | new Yoffset to set
Returns : | 0 on success, -1 on error.

### im_copy_set_meta ()

    int                 im_copy_set_meta                    (VipsImage *in,
                                                             VipsImage *out,
                                                             const char *field,
                                                             GValue *value);

Copy an image, changing a metadata field. You can use this to, for example, update the ICC profile attached to an image.

See also: `im_copy()`.

`in` : | input image
`out` : | output image
`field` : | metadata field to set
`value` : | value to set for the field
Returns : | 0 on success, -1 on error.

### im_copy_morph ()

    int                 im_copy_morph                       (VipsImage *in,
                                                             VipsImage *out,
                                                             int bands,
                                                             VipsBandFormat format,
                                                             VipsCoding coding);

Copy an image, changing header fields which alter pixel addressing. The pixel data itself is unchanged, this operation just changes the header fields.

If you change the header fields such that the `sizeof()` a pixel changes, you'll get an error.

See also: `im_copy()`.

`in` : | input image
`out` : | output image
`bands` : | new number of bands
`bandfmt` : | new band format
`coding` : | new coding
Returns : | 0 on success, -1 on error.

### im_copy_swap ()

    int                 im_copy_swap                        (VipsImage *in,
                                                             VipsImage *out);

Copy an image, swapping byte order between little and big endian. This really does change image pixels and does not just alter the header.

See also: `im_copy()`, `im_amiMSBfirst()`, `im_isMSBfirst()`.

`in` : | input image
`out` : | output image
Returns : | 0 on success, -1 on error.

### im_copy_native ()

    int                 im_copy_native                      (VipsImage *in,
                                                             VipsImage *out,
                                                             gboolean is_msb_first);

Copy an image to native order, that is, the order for the executing program.

See also: `im_copy_swap()`, `im_amiMSBfirst()`.

`in` : | input image
`out` : | output image
`is_msb_first` : | `TRUE` if `in` is in most-significant first form
Returns : | 0 on success, -1 on error.

### im_copy_file ()

    int                 im_copy_file                        (VipsImage *in,
                                                             VipsImage *out);

Copy an image to a disc file, then copy again to output. If the image is already a disc file, just copy straight through.

The disc file is allocated in the same way as `im_system_image()`. The file is automatically deleted when `out` is closed.

See also: `im_copy()`, `im_system_image()`.

`in` : | input image
`out` : | output image
Returns : | 0 on success, -1 on error

### im_clip2fmt ()

    int                 im_clip2fmt                         (VipsImage *in,
                                                             VipsImage *out,
                                                             VipsBandFormat fmt);

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

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

`in` : | input image
`out` : | output image
`fmt` : | format to convert to
Returns : | 0 on success, -1 on error

### im_scale ()

    int                 im_scale                            (VipsImage *in,
                                                             VipsImage *out);

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.

See also: `im_clip2fmt()`, `im_scaleps()`.

`in` : | input image
`out` : | output image
Returns : | 0 on success, -1 on error

### im_msb ()

    int                 im_msb                              (VipsImage *in,
                                                             VipsImage *out);

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.

This operator also works for LABQ coding.

See also: `im_msb_band()`.

`in` : | input image
`out` : | output image
Returns : | 0 on success, -1 on error

### im_msb_band ()

    int                 im_msb_band                         (VipsImage *in,
                                                             VipsImage *out,
                                                             int band);

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

This operator also works for LABQ coding.

See also: `im_msb_band()`.

`in` : | input image
`out` : | output image
`band` : | select this band
Returns : | 0 on success, -1 on error

### im_c2amph ()

    int                 im_c2amph                           (VipsImage *in,
                                                             VipsImage *out);

Convert a complex image from rectangular to polar coordinates. Angles are expressed in degrees.

See also: `im_c2rect()`, `im_abs()`.

`in` : | input image
`out` : | output image
Returns : | 0 on success, -1 on error

### im_c2rect ()

    int                 im_c2rect                           (VipsImage *in,
                                                             VipsImage *out);

Convert a complex image from polar to rectangular coordinates. Angles are expressed in degrees.

See also: `im_c2amph()`.

`in` : | input image
`out` : | output image
Returns : | 0 on success, -1 on error

### im_ri2c ()

    int                 im_ri2c                             (VipsImage *in1,
                                                             VipsImage *in2,
                                                             VipsImage *out);

Compose two real images to make a complex image. If either `in1` or `in2` are `IM_BANDFMT_DOUBLE`, `out` is `IM_BANDFMT_DPCOMPLEX`. Otherwise `out` is `IM_BANDFMT_COMPLEX`. `in1` becomes the real component of `out` and `in2` the imaginary.

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.

See also: `im_c2real()`, `im_c2imag()`.

`in1` : | input image
`in2` : | input image
`out` : | output image
Returns : | 0 on success, -1 on error

### im_c2imag ()

    int                 im_c2imag                           (VipsImage *in,
                                                             VipsImage *out);

Extract the imaginary part of a complex image.

See also: `im_c2real()`.

`in` : | input image
`out` : | output image
Returns : | 0 on success, -1 on error

### im_c2real ()

    int                 im_c2real                           (VipsImage *in,
                                                             VipsImage *out);

Extract the real part of a complex image.

See also: `im_c2imag()`.

`in` : | input image
`out` : | output image
Returns : | 0 on success, -1 on error

### im_scaleps ()

    int                 im_scaleps                          (VipsImage *in,
                                                             VipsImage *out);

Scale a power spectrum. Transform with log10(1.0 + pow(x, 0.25)) + .5, then scale so max == 255.

See also: `im_scale()`.

`in` : | input image
`out` : | output image
Returns : | 0 on success, -1 on error

### im_falsecolour ()

    int                 im_falsecolour                      (VipsImage *in,
                                                             VipsImage *out);

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

See also: `im_maplut()`.

`in` : | input image
`out` : | output image
Returns : | 0 on success, -1 on error

### im_gaussnoise ()

    int                 im_gaussnoise                       (VipsImage *out,
                                                             int x,
                                                             int y,
                                                             double mean,
                                                             double sigma);

Make a one band float image of gaussian noise with the specified distribution. The noise distribution is created by averaging 12 random numbers with the appropriate weights.

See also: `im_addgnoise()`, `im_make_xy()`, `im_text()`, `im_black()`.

`out` : | output image
`x` : | output width
`y` : | output height
`mean` : | average value in output
`sigma` : | standard deviation in output
Returns : | 0 on success, -1 on error

### im_black ()

    int                 im_black                            (VipsImage *out,
                                                             int x,
                                                             int y,
                                                             int bands);

Make a black unsigned char image of a specified size.

See also: `im_make_xy()`, `im_text()`, `im_gaussnoise()`.

`out` : | output IMAGE
`x` : | output width
`y` : | output height
`bands` : | number of output bands
Returns : | 0 on success, -1 on error

### im_text ()

    int                 im_text                             (VipsImage *out,
                                                             const char *text,
                                                             const char *font,
                                                             int width,
                                                             int alignment,
                                                             int dpi);

Draw the string `text` to an image. `out` is a one-band 8-bit unsigned char image, with 0 for no text and 255 for text. Values inbetween are used for anti-aliasing.

`text` is the text to render as a UTF-8 string. It can contain Pango markup, for example "<i>The</i>Guardian".

`font` is the font to render with, selected by fontconfig. Examples might be "sans 12" or perhaps "bitstream charter bold 10".

`width` is the maximum number of pixels across to draw within. If the generated text is wider than this, it will wrap to a new line. In this case, `alignment` can be used to set the alignment style for multi-line text. 0 means left-align, 1 centre, 2 right-align.

`dpi` sets the resolution to render at. "sans 12" at 72 dpi draws characters approximately 12 pixels high.

See also: `im_make_xy()`, `im_black()`, `im_gaussnoise()`.

`out` : | output image
`text` : | utf-8 text string to render
`font` : | font to render with
`width` : | render within this many pixels across
`alignment` : | left/centre/right alignment
`dpi` : | render at this resolution
Returns : | 0 on success, -1 on error

### im_extract_band ()

    int                 im_extract_band                     (VipsImage *in,
                                                             VipsImage *out,
                                                             int band);

Extract a single band from an image. Extracting outside `in` will trigger an error.

See also: `im_bandjoin()`.

`in` : | input image
`out` : | output image
`band` : | band to extract
Returns : | 0 on success, -1 on error

### im_extract_bands ()

    int                 im_extract_bands                    (VipsImage *in,
                                                             VipsImage *out,
                                                             int band,
                                                             int nbands);

Extract a number of bands from an image. Extracting outside `in` will trigger an error.

See also: `im_bandjoin()`.

`in` : | input image
`out` : | output image
`band` : | first band to extract
`nbands` : | number of bands to extract
Returns : | 0 on success, -1 on error

### im_extract_area ()

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

Extract an area from an image. Extracting outside `in` will trigger an error.

See also: `im_embed()`, `im_insert()`, `im_extract_bands()`.

`in` : | input image
`out` : | output image
`left` : | left edge of rectangle
`top` : | top edge of rectangle
`width` : | width of rectangle
`height` : | height of rectangle
Returns : | 0 on success, -1 on error

### im_extract_areabands ()

    int                 im_extract_areabands                (VipsImage *in,
                                                             VipsImage *out,
                                                             int left,
                                                             int top,
                                                             int width,
                                                             int height,
                                                             int band,
                                                             int nbands);

Extract an area and a number of bands from an image. Bands number from zero. Extracting outside `in` will trigger an error.

See also: `im_embed()`, `im_insert()`, `im_extract_area()`, `im_extract_bands()`.

`in` : | input image
`out` : | output image
`left` : | left edge of rectangle
`top` : | top edge rectangle
`width` : | width of rectangle
`height` : | height of rectangle
`band` : | first band to extract
`nbands` : | number of bands to extract
Returns : | 0 on success, -1 on error

### im_embed ()

    int                 im_embed                            (VipsImage *in,
                                                             VipsImage *out,
                                                             int type,
                                                             int x,
                                                             int y,
                                                             int width,
                                                             int height);

The opposite of `im_extract()`: embed an image within a larger image. `type` controls what appears in the new pels:

0 | black pels (all bytes == 0)
1 | extend pels from image edge
2 | repeat image
3 | mirror image
4 | white pels (all bytes == 255)

See also: `im_extract_area()`, `im_insert()`.

`in` : | input image
`out` : | output image
`type` : | how to generate the edge pixels
`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
Returns : | 0 on success, -1 on error.

### im_bandjoin ()

    int                 im_bandjoin                         (VipsImage *in1,
                                                             VipsImage *in2,
                                                             VipsImage *out);

Join two images bandwise. If the two images have n and m bands respectively, 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 image is enlarged to match the larger by adding zero pixels along the bottom and right.

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

See also: `im_gbandjoin()`, `im_insert()`.

`in1` : | first input image
`in2` : | second input image
`out` : | output image
Returns : | 0 on success, -1 on error

### im_gbandjoin ()

    int                 im_gbandjoin                        (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: `im_bandjoin()`, `im_insert()`.

`in` : | vector of input images
`out` : | output image
`n` : | number of input images
Returns : | 0 on success, -1 on error

### im_insert ()

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

Insert one image into another. `sub` is inserted into image `main` at position `x`, `y` relative to the top LH corner of `main`. `out` is made large enough to hold both `main` and `sub`. Any areas of `out` not coming from either `main` or `sub` are set to black (binary 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: `im_insert_noexpand()`, `im_lrjoin()`.

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

### im_insert_noexpand ()

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

Insert one image into another. `sub` is inserted into image `main` at position `x`, `y` relative to the top LH corner of `main`. `out` is the same size as `main`. `sub` is clipped against the edges 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: `im_insert_noexpand()`, `im_lrjoin()`, `im_draw_image()`.

`main` : | big image
`sub` : | small image
`out` : | output image
`x` : | left position of `sub`
`y` : | top position of `sub`
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

### im_lrjoin ()

    int                 im_lrjoin                           (VipsImage *left,
                                                             VipsImage *right,
                                                             VipsImage *out);

Join `left` and `right` together, left-right. If one is taller than the other, `out` will be has high as the smaller.

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

`left` : | image to go on left
`right` : | image to go on right
`out` : | output image
Returns : | 0 on success, -1 on error

### im_tbjoin ()

    int                 im_tbjoin                           (VipsImage *top,
                                                             VipsImage *bottom,
                                                             VipsImage *out);

Join `top` and `bottom` together, up-down. If one is wider than the other, `out` will be has wide as the smaller.

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

`top` : | image to go on top
`bottom` : | image to go on bottom
`out` : | output image
Returns : | 0 on success, -1 on error

### im_replicate ()

    int                 im_replicate                        (VipsImage *in,
                                                             VipsImage *out,
                                                             int across,
                                                             int down);

Replicate an image x times horizontally and vertically.

See also: `im_embed()`, `im_copy()`.

`in` : | input image
`out` : | output image
`across` : | repeat `in` this many times across
`down` : | repeat `in` this many times down
Returns : | 0 on success, -1 on error.

### im_grid ()

    int                 im_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.

See also: `im_embed()`, `im_insert()`, `im_lrjoin()`.

`in` : | input image
`out` : | output image
`tile_height` : | chop into tiles this high
`across` : | tiles across
`down` : | tiles down
Returns : | 0 on success, -1 on error

### im_wrap ()

    int                 im_wrap                             (VipsImage *in,
                                                             VipsImage *out,
                                                             int x,
                                                             int y);

Slice an image up and move the segments about so that the pixel that was at 0, 0 is now at `x`, `y`.

See also: `im_embed()`, `im_replicate()`, `im_rotquad()`.

`in` : | input image
`out` : | output image
`x` : | horizontal displacement
`y` : | vertical displacement
Returns : | 0 on success, -1 on error

### im_fliphor ()

    int                 im_fliphor                          (VipsImage *in,
                                                             VipsImage *out);

Flips an image left-right.

See also: `im_flipver()`, `im_rot90()`.

`in` : | input image
`out` : | output image
Returns : | 0 on success, -1 on error

### im_flipver ()

    int                 im_flipver                          (VipsImage *in,
                                                             VipsImage *out);

Flips an image top-bottom.

See also: `im_fliphor()`, `im_rot90()`.

`in` : | input image
`out` : | output image
Returns : | 0 on success, -1 on error

### im_rot90 ()

    int                 im_rot90                            (VipsImage *in,
                                                             VipsImage *out);

Rotate an image 90 degrees.

See also: `im_rot180()`, `im_rot270()`, `im_affinei_all()`.

`in` : | input image
`out` : | output image
Returns : | 0 on success, -1 on error

### im_rot180 ()

    int                 im_rot180                           (VipsImage *in,
                                                             VipsImage *out);

Rotate an image 180 degrees.

See also: `im_rot90()`, `im_rot270()`, `im_affinei_all()`.

`in` : | input image
`out` : | output image
Returns : | 0 on success, -1 on error

### im_rot270 ()

    int                 im_rot270                           (VipsImage *in,
                                                             VipsImage *out);

Rotate an image 270 degrees.

See also: `im_rot180()`, `im_rot90()`, `im_affinei_all()`.

`in` : | input image
`out` : | output image
Returns : | 0 on success, -1 on error

### im_subsample ()

    int                 im_subsample                        (VipsImage *in,
                                                             VipsImage *out,
                                                             int xshrink,
                                                             int yshrink);

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

See also: `im_shrink()`, `im_affinei()`, `im_zoom()`.

`in` : | input image
`out` : | output image
`xshrink` : | horizontal shrink factor
`yshrink` : | vertical shrink factor
Returns : | 0 on success, -1 on error.

### im_zoom ()

    int                 im_zoom                             (VipsImage *in,
                                                             VipsImage *out,
                                                             int xfac,
                                                             int yfac);

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

See also: `im_affinei()`, `im_subsample()`.

`in` : | input image
`out` : | output image
`xfac` : | horizontal scale factor
`yfac` : | vertical scale factor
Returns : | 0 on success, -1 on error.

### im_system ()

    int                 im_system                           (VipsImage *im,
                                                             const char *cmd,
                                                             char **out);

`im_system()` runs a command on an image, returning the command's output as a string. The command is executed with `popen()`, the first '%`s`' in the command being substituted for a filename.

If the IMAGE is a file on disc, then the filename will be the name of the real file. If the image is in memory, or the result of a computation, then a new file is created in the temporary area called something like "vips_XXXXXX.v", and that filename given to the command. The file is deleted when the command finishes.

See `im_system_image()` for details on how VIPS selects a temporary directory.

In all cases, `log` must be freed with `im_free()`.

See also: `im_system_image()`.

`im` : | image to run command on
`cmd` : | command to run
`out` : | stdout of command is returned here
Returns : | 0 on success, -1 on error

### im_system_image ()

    VipsImage *         im_system_image                     (VipsImage *im,
                                                             const char *in_format,
                                                             const char *out_format,
                                                             const char *cmd_format,
                                                             char **log);

`im_system_image()` runs a command, passing an image in and getting an image back. The command's stdout is returned in `log`.

First, `im` is written to a file. The filename is formed by substituting something like "vips-49857-1" for the first %`s` in `in_format`, then prepending "/tmp". If the environment variable TMPDIR is defined, it can be used to set a different temporary directory. If `in_format` is something like "%`s`.png", the file will be written in PNG format.

On Windows, if the environment variable TMPDIR is not defined, VIPS calls `GetTempPath()` to get the user's preferred temporary area. If that fails, it defaults to C:\temp.

Next an output filename is created in the same way using `out_format`. The command string to run is made by substituting the first %`s` in `cmd_format` for the name of the input file and the second %`s` for the output filename.

The command is executed with `popen()` and the output captured in `log`. If the command fails, the temporary files are deleted and `im_system_image()` returns NULL. `log` is still set.

If the command succeeds, the input file is deleted, the output file opened, and returned. Closing the output image will automatically delete the file.

In all cases, `log` must be freed with `im_free()`.

For example, this call will run the ImageMagick convert program on an image, using JPEG files to pass images into and out of the convert command.

    im_system_image( in, out,
      "%s.jpg", "%s.jpg", "convert %s -swirl 45 %s",
      &log )

See also: `im_system()`.

`im` : | image to run command on
`in_format` : | write input file like this
`out_format` : | write output filename like this
`cmd_format` : | command to run
`log` : | stdout of command is returned here
Returns : | an image on success, NULL on error

## See Also

resample