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. The operation will block changes which make the image size grow, see VIPS_IMAGE_SIZEOF_IMAGE().

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

vips_tilecache ()

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

Optional arguments:

tile_width : width of tiles in cache tile_height : height of tiles in cache max_tiles : maximum number of tiles to cache access : hint expected access pattern VipsAccess threaded : allow many threads persistent : don't drop cache at end of computation

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

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

When the cache fills, a tile is chosen for reuse. If access is VIPS_ACCESS_RANDOM, then the least-recently-used tile is reused. If access is VIPS_ACCESS_SEQUENTIAL 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().

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

When the cache fills, a tile is chosen for reuse. If access is VIPS_ACCESS_RANDOM, then the least-recently-used tile is reused. If access is VIPS_ACCESS_SEQUENTIAL 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().

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_cache(), vips_linecache(), vips_tilecache().

vips_cache ()

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

Optional arguments:

tile_width : width of tiles in cache tile_height : height of tiles in cache max_tiles : maximum number of tiles to cache

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

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

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

See also: vips_tilecache().

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

vips_embed ()

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

Optional arguments:

extend : VipsExtend to generate the edge pixels (default: black) background : VipsArrayDouble 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().

vips_flip ()

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

Flips an image left-right or up-down.

See also: vips_rot().

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

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

vips_join ()

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

Optional arguments:

expand : TRUE to expand the output image to hold all of the input pixels shim : space between images, in pixels background : background ink colour align : low, centre or high alignment

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

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

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

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

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

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

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

See also: vips_insert().

vips_extract_area ()

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

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

See also: vips_extract_bands().

vips_crop ()

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

A synonym for vips_extract_area().

See also: vips_extract_bands().

vips_extract_band ()

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

Optional arguments:

n : number of bands to extract

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

See also: vips_extract_area().

vips_replicate ()

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

Repeats an image many times.

See also: vips_extract_area().

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

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

vips_rot ()

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

Rotate in by a multiple of 90 degrees.

See also: vips_flip().

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

vips_autorot_get_angle ()

VipsAngle
vips_autorot_get_angle (VipsImage *im);

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

See also: vips_autorot().

vips_autorot ()

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

Optional arguments:

angle : output VipsAngle the image was rotated by

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

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

See also: vips_rot().

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

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

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: vips_scale(), vips_complexform(), vips_real(), vips_imag(), vips_cast_uchar().

vips_cast_uchar ()

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

Convert in to VIPS_FORMAT_UCHAR. See vips_cast().

vips_cast_char ()

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

Convert in to VIPS_FORMAT_CHAR. See vips_cast().

vips_cast_ushort ()

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

Convert in to VIPS_FORMAT_USHORT. See vips_cast().

vips_cast_short ()

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

Convert in to VIPS_FORMAT_SHORT. See vips_cast().

vips_cast_uint ()

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

Convert in to VIPS_FORMAT_UINT. See vips_cast().

vips_cast_int ()

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

Convert in to VIPS_FORMAT_INT. See vips_cast().

vips_cast_float ()

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

Convert in to VIPS_FORMAT_FLOAT. See vips_cast().

vips_cast_double ()

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

Convert in to VIPS_FORMAT_DOUBLE. See vips_cast().

vips_cast_complex ()

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

Convert in to VIPS_FORMAT_COMPLEX. See vips_cast().

vips_cast_dpcomplex ()

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

Convert in to VIPS_FORMAT_DPCOMPLEX. See vips_cast().

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

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

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

See also: vips_insert().

vips_bandjoin2 ()

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

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

vips_bandrank ()

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

Optional arguments:

index : pick this index from list of sorted values

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

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

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

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

Smaller input images are expanded by adding black pixels.

See also: vips_rank().

vips_bandbool ()

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

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

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

The output image always has one band.

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

See also: vips_boolean_const().

vips_bandand ()

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

Perform VIPS_OPERATION_BOOLEAN_AND on an image. See vips_bandbool().

vips_bandor ()

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

Perform VIPS_OPERATION_BOOLEAN_OR on an image. See vips_bandbool().

vips_bandeor ()

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

Perform VIPS_OPERATION_BOOLEAN_EOR on an image. See vips_bandbool().

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

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

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

vips_flatten ()

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

Optional arguments:

background : VipsArrayDouble 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 - MAX for integer images and 0 - 1 for float images, where MAX means 100% image and 0 means 100% background. Non-complex images only. background defaults to zero (black). MAX is the largest possible positive value for that int type.

Useful for flattening PNG images to RGB.

See also: pngload().

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

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

enum VipsExtend

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

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

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

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

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

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

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

VIPS_EXTEND_BACKGROUND --- colour set from the background property

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

See also: vips_embed().

enum VipsDirection

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

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

See also: vips_flip(), vips_join().

enum VipsAlign

See vips_join() and so on.

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

See also: vips_join().

enum VipsAngle

See vips_rot() and so on.

Fixed rotate angles.

See also: vips_rot().

enum VipsAngle45

See vips_rot45() and so on.

Fixed rotate angles.

See also: vips_rot45().