## arithmetic

arithmetic — operations which perform pixel arithmetic, trig, log, statistics

## Stability Level

Stable, unless otherwise indicated

## Synopsis

    #include <vips/vips.h>

    DOUBLEMASK *        im_measure_area                     (VipsImage *im,
                                                             int left,
                                                             int top,
                                                             int width,
                                                             int height,
                                                             int h,
                                                             int v,
                                                             int *sel,
                                                             int nsel,
                                                             const char *name);
    DOUBLEMASK *        im_stats                            (VipsImage *in);
    int                 im_max                              (VipsImage *in,
                                                             double *out);
    int                 im_min                              (VipsImage *in,
                                                             double *out);
    int                 im_avg                              (VipsImage *in,
                                                             double *out);
    int                 im_deviate                          (VipsImage *in,
                                                             double *out);
    int                 im_maxpos                           (VipsImage *in,
                                                             int *xpos,
                                                             int *ypos,
                                                             double *out);
    int                 im_minpos                           (VipsImage *in,
                                                             int *xpos,
                                                             int *ypos,
                                                             double *out);
    int                 im_maxpos_avg                       (VipsImage *im,
                                                             double *xpos,
                                                             double *ypos,
                                                             double *out);
    int                 im_maxpos_vec                       (VipsImage *im,
                                                             int *xpos,
                                                             int *ypos,
                                                             double *maxima,
                                                             int n);
    int                 im_minpos_vec                       (VipsImage *im,
                                                             int *xpos,
                                                             int *ypos,
                                                             double *minima,
                                                             int n);
    int                 im_bandmean                         (VipsImage *in,
                                                             VipsImage *out);
    int                 im_add                              (VipsImage *in1,
                                                             VipsImage *in2,
                                                             VipsImage *out);
    int                 im_subtract                         (VipsImage *in1,
                                                             VipsImage *in2,
                                                             VipsImage *out);
    int                 im_invert                           (VipsImage *in,
                                                             VipsImage *out);
    int                 im_lintra                           (double a,
                                                             VipsImage *in,
                                                             double b,
                                                             VipsImage *out);
    int                 im_lintra_vec                       (int n,
                                                             double *a,
                                                             VipsImage *in,
                                                             double *b,
                                                             VipsImage *out);
    int                 im_multiply                         (VipsImage *in1,
                                                             VipsImage *in2,
                                                             VipsImage *out);
    int                 im_divide                           (VipsImage *in1,
                                                             VipsImage *in2,
                                                             VipsImage *out);
    int                 im_remainder                        (VipsImage *in1,
                                                             VipsImage *in2,
                                                             VipsImage *out);
    int                 im_remainder_vec                    (VipsImage *in,
                                                             VipsImage *out,
                                                             int n,
                                                             double *c);
    int                 im_remainderconst                   (VipsImage *in,
                                                             VipsImage *out,
                                                             double c);
    int                 im_recomb                           (VipsImage *in,
                                                             VipsImage *out,
                                                             DOUBLEMASK *recomb);
    int                 im_sign                             (VipsImage *in,
                                                             VipsImage *out);
    int                 im_abs                              (VipsImage *in,
                                                             VipsImage *out);
    int                 im_floor                            (VipsImage *in,
                                                             VipsImage *out);
    int                 im_rint                             (VipsImage *in,
                                                             VipsImage *out);
    int                 im_ceil                             (VipsImage *in,
                                                             VipsImage *out);
    int                 im_linreg                           (VipsImage **ins,
                                                             VipsImage *out,
                                                             double *xs);
    int                 im_point                            (VipsImage *im,
                                                             VipsInterpolate *interpolate,
                                                             double x,
                                                             double y,
                                                             int band,
                                                             double *out);
    int                 im_point_bilinear                   (VipsImage *im,
                                                             double x,
                                                             double y,
                                                             int band,
                                                             double *out);
    int                 im_powtra                           (VipsImage *in,
                                                             VipsImage *out,
                                                             double e);
    int                 im_powtra_vec                       (VipsImage *in,
                                                             VipsImage *out,
                                                             int n,
                                                             double *e);
    int                 im_exptra                           (VipsImage *in,
                                                             VipsImage *out);
    int                 im_exp10tra                         (VipsImage *in,
                                                             VipsImage *out);
    int                 im_expntra                          (VipsImage *in,
                                                             VipsImage *out,
                                                             double e);
    int                 im_expntra_vec                      (VipsImage *in,
                                                             VipsImage *out,
                                                             int n,
                                                             double *e);
    int                 im_logtra                           (VipsImage *in,
                                                             VipsImage *out);
    int                 im_log10tra                         (VipsImage *in,
                                                             VipsImage *out);
    int                 im_sintra                           (VipsImage *in,
                                                             VipsImage *out);
    int                 im_costra                           (VipsImage *in,
                                                             VipsImage *out);
    int                 im_tantra                           (VipsImage *in,
                                                             VipsImage *out);
    int                 im_asintra                          (VipsImage *in,
                                                             VipsImage *out);
    int                 im_acostra                          (VipsImage *in,
                                                             VipsImage *out);
    int                 im_atantra                          (VipsImage *in,
                                                             VipsImage *out);
    int                 im_cross_phase                      (VipsImage *a,
                                                             VipsImage *b,
                                                             VipsImage *out);

## Description

These operations perform pixel arithmetic, that is, they perform an arithmetic operation, such as addition, on every pixel in an image or a pair of images. All (except in a few cases noted below) will work with images of any type or any mixture of types, of any size and of any number of bands.

For binary operations, 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.

In the same way, for operations that take an array constant, such as `im_remainder_vec()`, you can mix single-element arrays or single-band images freely.

Arithmetic operations try to preserve precision by increasing the number of bits in the output image when necessary. Generally, this follows the ANSI C conventions for type promotion, so multiplying two `IM_BANDFMT_UCHAR` images together, for example, produces a `IM_BANDFMT_USHORT` image, and taking the `im_costra()` of a `IM_BANDFMT_USHORT` image produces `IM_BANDFMT_FLOAT` image.

For binary arithmetic operations, type promotion occurs in two stages. First, the two input images are cast up to the smallest common format, that is, the type with the smallest range that can represent the full range of both inputs. This conversion can be represented as a table:

Table 1. Smallest common format

`in2`/`in1` | uchar | char | ushort | short | uint | int | float | double | complex | double complex
--- | --- | --- | --- | --- | --- | --- | --- | --- | --- | ---
uchar | ushort | short | ushort | short | uint | int | float | double | complex | double complex
char | short | short | short | short | int | int | float | double | complex | double complex
ushort | ushort | short | ushort | short | uint | int | float | double | complex | double complex
short | short | short | short | short | int | int | float | double | complex | double complex
uint | uint | int | uint | int | uint | int | float | double | complex | double complex
int | int | int | int | int | int | int | float | double | complex | double complex
float | float | float | float | float | float | float | float | double | complex | double complex
double | double | double | double | double | double | double | double | double | double complex | double complex
complex | complex | complex | complex | complex | complex | complex | complex | double complex | complex | double complex
double complex | double complex | double complex | double complex | double complex | double complex | double complex | double complex | double complex | double complex | double complex

In the second stage, the operation is performed between the two identical types to form the output. The details vary between operations, but generally the principle is that the output type should be large enough to represent the whole rage of possible values, except that int never becomes float.

## Details

### im_measure_area ()

    DOUBLEMASK *        im_measure_area                     (VipsImage *im,
                                                             int left,
                                                             int top,
                                                             int width,
                                                             int height,
                                                             int h,
                                                             int v,
                                                             int *sel,
                                                             int nsel,
                                                             const char *name);

Analyse a grid of colour patches, producing a DOUBLEMASK of patch averages. The mask has a row for each measured patch, and a column for each image band. The operations issues a warning if any patch has a deviation more than 20% of the mean. Only the central 50% of each patch is averaged. If `sel` is `NULL` then all patches are measured.

Example: 6 band image of 4x2 block of colour patches.

1 | 2 | 3 | 4
5 | 6 | 7 | 8

Then call im_measure( im, box, 4, 2, { 2, 4 }, 2, "fred" ) makes a mask "fred" which has 6 columns, two rows. The first row contains the averages for patch 2, the second for patch 4.

See also: `im_avg()`, `im_deviate()`, `im_stats()`.

`im` : | image to measure
`left` : | area of image containing chart
`top` : | area of image containing chart
`width` : | area of image containing chart
`height` : | area of image containing chart
`h` : | patches across chart
`v` : | patches down chart
`sel` : | array of patch numbers to measure (numbered from 1 in row-major order)
`nsel` : | length of patch number array
`name` : | name to give to returned `DOUBLEMASK`
Returns : | DOUBLEMASK of measurements.

### im_stats ()

    DOUBLEMASK *        im_stats                            (VipsImage *in);

Find many image statistics in a single pass through the data. Returns a DOUBLEMASK of 6 columns by n + 1 (where n is number of bands in image `in`) rows. Columns are statistics, and are, in order: minimum, maximum, sum, sum of squares, mean, standard deviation. Row 0 has statistics for all bands together, row 1 has stats for band 1, and so on.

See also: `im_maxpos()`, `im_min()`, `im_deviate()`.

`in` : | image to scan
Returns : | 0 on success, -1 on error

### im_max ()

    int                 im_max                              (VipsImage *in,
                                                             double *out);

Finds the the maximum value of image in and returns it at the location pointed by out. If input is complex, the max modulus is returned. `im_max()` finds the maximum of all bands: if you want to find the maximum of each band separately, use `im_stats()`.

See also: `im_maxpos()`, `im_min()`, `im_stats()`.

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

### im_min ()

    int                 im_min                              (VipsImage *in,
                                                             double *out);

Finds the the minimum value of image in and returns it at the location pointed by `out`. If input is complex, the min modulus is returned. `im_min()` finds the minimum of all bands: if you want to find the minimum of each band separately, use `im_stats()`.

See also: `im_minpos()`, `im_min()`, `im_stats()`.

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

### im_avg ()

    int                 im_avg                              (VipsImage *in,
                                                             double *out);

This operation finds the average value in an image. It operates on all bands of the input image: use `im_stats()` if you need to calculate an average for each band. For complex images, return the average modulus.

See also: `im_stats()`, `im_bandmean()`, `im_deviate()`, `im_rank()`

`in` : | input IMAGE
`out` : | output pixel average
Returns : | 0 on success, -1 on error

### im_deviate ()

    int                 im_deviate                          (VipsImage *in,
                                                             double *out);

This operation finds the standard deviation of all pixels in `in`. It operates on all bands of the input image: use `im_stats()` if you need to calculate an average for each band.

Non-complex images only.

See also: `im_stats()`, `im_bandmean()`, `im_avg()`, `im_rank()`

`in` : | input IMAGE
`out` : | output pixel standard deviation
Returns : | 0 on success, -1 on error

### im_maxpos ()

    int                 im_maxpos                           (VipsImage *in,
                                                             int *xpos,
                                                             int *ypos,
                                                             double *out);

Function to find the maximum of an image. Works for any image type. Returns a double and the location of max. For complex images, finds the pixel with the highest modulus.

See also: `im_minpos()`, `im_min()`, `im_stats()`, `im_maxpos_avg()`, `im_maxpos_subpel()`, `im_maxpos_vec()`.

`in` : | image to search
`xpos` : | returned x position of maximum
`ypos` : | returned y position of maximum
`out` : | returned pixel value at that position
Returns : | 0 on success, -1 on error

### im_minpos ()

    int                 im_minpos                           (VipsImage *in,
                                                             int *xpos,
                                                             int *ypos,
                                                             double *out);

Function to find the minimum of an image. Works for any image type. Returns a double and the location of min. For complex images, finds the pixel with the smallest modulus.

See also: `im_maxpos()`, `im_min()`, `im_stats()`, `im_maxpos_avg()`.

`in` : | image to search
`xpos` : | returned x position of minimum
`ypos` : | returned y position of minimum
`out` : | returned pixel value at that position
Returns : | 0 on success, -1 on error

### im_maxpos_avg ()

    int                 im_maxpos_avg                       (VipsImage *im,
                                                             double *xpos,
                                                             double *ypos,
                                                             double *out);

Function to find the maximum of an image. Returns coords and value at double precision. In the event of a draw, returns average of all drawing coords.

See also: `im_maxpos()`, `im_min()`, `im_stats()`.

`im` : | image to scan
`xpos` : | returned X position
`ypos` : | returned Y position
`out` : | returned value
Returns : | 0 on success, -1 on error

### im_maxpos_vec ()

    int                 im_maxpos_vec                       (VipsImage *im,
                                                             int *xpos,
                                                             int *ypos,
                                                             double *maxima,
                                                             int n);

Find the coordinates and values of the `n` `maxima` of an image.

For 8 and 16-bit images, it's much faster to find the histogram and then calculate a threshold from that. See `im_mpercent()`.

See also: `im_minpos()`, `im_min()`, `im_stats()`, `im_maxpos_avg()`.

`im` : | image to scan
`xpos` : | array to return x positions
`ypos` : | array to return y positions
`maxima` : | array to return values
`n` : | number of maxima to search for
Returns : | 0 on success, -1 on error

### im_minpos_vec ()

    int                 im_minpos_vec                       (VipsImage *im,
                                                             int *xpos,
                                                             int *ypos,
                                                             double *minima,
                                                             int n);

Find the coordinates and values of the `n` `minima` of an image.

For 8 and 16-bit images, it's much faster to find the histogram and then calculate a threshold from that. See `im_mpercent()`.

See also: `im_minpos()`, `im_min()`, `im_stats()`, `im_maxpos_avg()`.

`im` : | image to scan
`xpos` : | array to return x positions
`ypos` : | array to return y positions
`minima` : | array to return values
`n` : | number of minima to search for
Returns : | 0 on success, -1 on error

### im_bandmean ()

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

`im_bandmean()` 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: `im_add()`, `im_avg()`, `im_recomb()`

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

### im_add ()

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

### im_subtract ()

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

This operation calculates `in1` - `in2` and writes the result to `out`.

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

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), then the following table is used to determine the output type:

Table 2. `im_subtract()` type promotion

input type | output type
--- | ---
uchar | short
char | short
ushort | int
short | int
uint | int
int | int
float | float
double | double
complex | complex
double complex | double complex

In other words, the output type is just large enough to hold the whole range of possible values.

See also: `im_add()`, `im_lintra()`.

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

### im_invert ()

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

this operation calculates (255 - `in`). The operation works on uchar images only. The input can have any no of channels.

This is not a generally useful program -- it is included as an example of a very simple new-style IO function. See `im_exptra()` for an example of a VIPS function which can process any input image type.

See also: `im_exptra()`, `im_lintra()`.

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

### im_lintra ()

    int                 im_lintra                           (double a,
                                                             VipsImage *in,
                                                             double b,
                                                             VipsImage *out);

Pass an image through a linear transform - ie. `out` = `in` * `a` + `b`. Output is always float for integer input, double for double input, complex for complex input and double complex for double complex input.

See also: `im_add()`, `im_lintra_vec()`.

`a` : | constant for multiplication
`in` : | image to transform
`b` : | constant for addition
`out` : | output image
Returns : | 0 on success, -1 on error

### im_lintra_vec ()

    int                 im_lintra_vec                       (int n,
                                                             double *a,
                                                             VipsImage *in,
                                                             double *b,
                                                             VipsImage *out);

Pass an image through a linear transform - ie. `out` = `in` * `a` + `b`. Output is always float for integer input, double for double input, complex for complex input and double complex for double complex input.

If the arrays of constants have just one element, that constant are used for all image bands. If the arrays have more than one element and they have the same number of elements as there are bands in the image, then one array element is used for each band. If the arrays have more than one element and the image only has a single band, the result is a many-band image where each band corresponds to one array element.

See also: `im_add()`, `im_lintra()`.

`n` : | array size
`a` : | array of constants for multiplication
`in` : | image to transform
`b` : | array of constants for addition
`out` : | output image
Returns : | 0 on success, -1 on error

### im_multiply ()

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

This operation calculates `in1` * `in2` and writes the result to `out`.

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

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), then the following table is used to determine the output type:

Table 3. `im_multiply()` type promotion

input type | output type
--- | ---
uchar | ushort
char | short
ushort | uint
short | int
uint | uint
int | int
float | float
double | double
complex | complex
double complex | double complex

In other words, the output type is just large enough to hold the whole range of possible values.

See also: `im_divide()`, `im_lintra()`.

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

### im_divide ()

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

This operation calculates `in1` / `in2` and writes the result to `out`. If any pixels in `in2` are zero, the corresponding pixel in `out` is also zero.

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

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), then the following table is used to determine the output type:

Table 4. `im_divide()` type promotion

input type | output type
--- | ---
uchar | float
char | float
ushort | float
short | float
uint | float
int | float
float | float
double | double
complex | complex
double complex | double complex

In other words, the output type is just large enough to hold the whole range of possible values.

See also: `im_multiply()`, `im_lintra()`.

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

### im_remainder ()

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

This operation calculates `in1` % `in2` (remainder after division) and writes the result to `out`. The images may have any non-complex format. For float formats, `im_remainder()` calculates `in1` - `in2` * floor (`in1` / `in2`).

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

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), and that format is the result type.

See also: `im_remainderconst()`, `im_divide()`.

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

### im_remainder_vec ()

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

This operation calculates `in` % `c` (remainder after division by constant) and writes the result to `out`. The image may have any non-complex format. For float formats, `im_remainder()` calculates `in` - `c` * floor (`in` / `c`).

If the number of image bands end array elements differs, one of them must have one band. Either the image is up-banded by joining n copies of the one-band image together, or the array is upbanded by copying the single element n times.

See also: `im_remainder()`, `im_remainderconst()`, `im_divide()`.

`in` : | input IMAGE
`out` : | output IMAGE
`n` : | number of elements in array
`c` : | array of constants
Returns : | 0 on success, -1 on error

### im_remainderconst ()

    int                 im_remainderconst                   (VipsImage *in,
                                                             VipsImage *out,
                                                             double c);

This operation calculates `in` % `c` (remainder after division by constant) and writes the result to `out`. The image must be one of the integer types.

See also: `im_remainder_vec()`, `im_divide()`.

`in` : | input IMAGE
`out` : | output IMAGE
`c` : | constant
Returns : | 0 on success, -1 on error

### im_recomb ()

    int                 im_recomb                           (VipsImage *in,
                                                             VipsImage *out,
                                                             DOUBLEMASK *recomb);

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 `recomb` 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.

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

### im_sign ()

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

Finds the unit vector in the direction of the pixel value. For non-complex images, it returns a signed char image with values -1, 0, and 1 for negative, zero and positive pixels. For complex images, it returns a complex normalised to length 1.

See also: `im_abs()`, `im_cmulnorm()`, `im_c2amph()`.

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

### im_abs ()

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

This operation finds the absolute value of an image. It does a copy for unsigned integer types, negate for negative values in signed integer types, `fabs(3)` for float types, and calculate modulus for complex types.

See also: `im_exp10tra()`, `im_sign()`.

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

### im_floor ()

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

For each pixel, find the largest integral value not less than. Copy for integer types, call ``floor()`` for float and complex types. Output type == input type.

See also: `im_ceil()`, `im_rint()`, `im_clip2fmt()`

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

### im_rint ()

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

Finds the nearest integral value. Copy for integer types, call `IM_RINT()` for float and complex types. Output type == input type.

`IM_RINT()` is a pseudo-round-to-nearest. It is much faster than `rint`(3), but does not give the same result for negative integral values.

See also: `im_ceil()`, `im_floor()`, `im_clip2fmt()`

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

### im_ceil ()

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

For each pixel, find the smallest integral value not less than. Copy for integer types, call `ceil(3)` for float and complex types. Output type == input type.

See also: `im_floor()`, `im_rint()`, `im_clip2fmt()`

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

### im_linreg ()

    int                 im_linreg                           (VipsImage **ins,
                                                             VipsImage *out,
                                                             double *xs);

Function to find perform pixelwise linear regression on an array of single band images. The output is a seven-band douuble image

TODO: figure out how this works and fix up these docs!

`ins` : | NULL-terminated array of input images
`out` : | results of analysis
`xs` : | X position of each image (pixel value is Y)

### im_point ()

    int                 im_point                            (VipsImage *im,
                                                             VipsInterpolate *interpolate,
                                                             double x,
                                                             double y,
                                                             int band,
                                                             double *out);

Find the value at (`x`, `y`) in given band of image. Non-integral values are calculated using the supplied `interpolate`.

See also: `im_avg()`, VipsInterpolate

`im` : | image to read from
`interpolate` : | interpolator to sample points with
`x` : | x position to interpolate
`y` : | y position to interpolate
`band` : | band to read
`out` : | return interpolated value
Returns : | 0 on success, -1 on error

### im_point_bilinear ()

    int                 im_point_bilinear                   (VipsImage *im,
                                                             double x,
                                                             double y,
                                                             int band,
                                                             double *out);

Find the value at (`x`,`y`) in given band of image. Use bilinear interpolation if `x` or `y` are non-integral.

See also: `im_avg()`, `im_point()`.

`im` : | image to read from
`x` : | x position to interpolate
`y` : | y position to interpolate
`band` : | band to read
`out` : | return interpolated value
Returns : | 0 on success, -1 on error

### im_powtra ()

    int                 im_powtra                           (VipsImage *in,
                                                             VipsImage *out,
                                                             double e);

`im_powtra()` transforms element x of input to `pow`(x, `e`) in output. It detects division by zero, setting those pixels to zero in the output. Beware: it does this silently!

See also: `im_logtra()`, `im_powntra_vec()`

`in` : | input IMAGE
`out` : | output IMAGE
`e` : | exponent
Returns : | 0 on success, -1 on error

### im_powtra_vec ()

    int                 im_powtra_vec                       (VipsImage *in,
                                                             VipsImage *out,
                                                             int n,
                                                             double *e);

`im_powtra_vec()` transforms element x of input to `pow`(x, `b`) in output. It detects division by zero, setting those pixels to zero in the output. Beware: it does this silently!

If the array of constants has one element, that constant is used for each image band. If the array has more than one element, it must have the same number of elements as there are bands in the image, and one array element is used for each band.

See also: `im_logtra()`, `im_expntra_vec()`

`in` : | input IMAGE
`out` : | output IMAGE
`n` : | number of elements in array
`e` : | array of constants
Returns : | 0 on success, -1 on error

### im_exptra ()

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

`im_exptra()` transforms element x of input to `pow`(e, x) in output. It detects division by zero, setting those pixels to zero in the output. Beware: it does this silently!

See also: `im_logtra()`, `im_powtra()`

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

### im_exp10tra ()

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

`im_exptra()` transforms element x of input to `pow`(10, x) in output. It detects division by zero, setting those pixels to zero in the output. Beware: it does this silently!

See also: `im_logtra()`, `im_powtra()`

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

### im_expntra ()

    int                 im_expntra                          (VipsImage *in,
                                                             VipsImage *out,
                                                             double e);

`im_expntra()` transforms element x of input to `pow`(`e`, x) in output. It detects division by zero, setting those pixels to zero in the output. Beware: it does this silently!

See also: `im_logtra()`, `im_powtra()`

`in` : | input IMAGE
`out` : | output IMAGE
`e` : | base
Returns : | 0 on success, -1 on error

### im_expntra_vec ()

    int                 im_expntra_vec                      (VipsImage *in,
                                                             VipsImage *out,
                                                             int n,
                                                             double *e);

`im_expntra_vec()` transforms element x of input to `pow`(`b`, x) in output. It detects division by zero, setting those pixels to zero in the output. Beware: it does this silently!

If the array of constants has one element, that constant is used for each image band. If the array has more than one element, it must have the same number of elements as there are bands in the image, and one array element is used for each band.

See also: `im_logtra()`, `im_powtra()`

`in` : | input IMAGE
`out` : | output IMAGE
`n` : | number of elements in array
`e` : | array of constants
Returns : | 0 on success, -1 on error

### im_logtra ()

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

For each pixel, call `log(3)` (natural logarithm). The output type is float, unless the input is double, in which case the output is double. Non-complex images only.

See also: `im_exp10tra()`, `im_logntra()`, `im_sintra()`.

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

### im_log10tra ()

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

For each pixel, call `log10(3)` (base 10 logarithm). The output type is float, unless the input is double, in which case the output is double. Non-complex images only.

See also: `im_exp10tra()`, `im_logntra()`, `im_sintra()`.

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

### im_sintra ()

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

For each pixel, call `sin(3)` (sine). Angles are expressed in degrees. The output type is float, unless the input is double, in which case the output is double. Non-complex images only.

See also: `im_asintra()`, `im_costra()`, `im_tantra()`.

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

### im_costra ()

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

For each pixel, call `cos(3)` (cosine). Angles are expressed in degrees. The output type is float, unless the input is double, in which case the output is double. Non-complex images only.

See also: `im_acostra()`, `im_sintra()`, `im_tantra()`.

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

### im_tantra ()

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

For each pixel, call `tan(3)` (tangent). Angles are expressed in degrees. The output type is float, unless the input is double, in which case the output is double. Non-complex images only.

See also: `im_atantra()`, `im_sintra()`, `im_tantra()`.

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

### im_asintra ()

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

For each pixel, call `asin(3)` (arc, or inverse sine). Angles are expressed in degrees. The output type is float, unless the input is double, in which case the output is double. Non-complex images only.

See also: `im_asintra()`, `im_costra()`, `im_tantra()`.

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

### im_acostra ()

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

For each pixel, call `acos(3)` (arc or inverse cosine). Angles are expressed in degrees. The output type is float, unless the input is double, in which case the output is double. Non-complex images only.

See also: `im_costra()`, `im_asintra()`, `im_atantra()`.

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

### im_atantra ()

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

For each pixel, call `atan(3)` (arc or inverse tangent). Angles are expressed in degrees. The output type is float, unless the input is double, in which case the output is double. Non-complex images only.

See also: `im_tantra()`, `im_asintra()`, `im_atantra()`.

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

### im_cross_phase ()

    int                 im_cross_phase                      (VipsImage *a,
                                                             VipsImage *b,
                                                             VipsImage *out);

Find the phase of the cross power spectrum of two complex images, expressed as a complex image where the modulus of each pixel is one.

I.E. find (a.b*)/|a.b*| where . represents complex multiplication * represents the complex conjugate || represents the complex modulus

See also: `im_multiply()`, `im_sign()`.

`a` : | input IMAGE 1
`b` : | input IMAGE 2
`out` : | output IMAGE
Returns : | 0 on success, -1 on error

## See Also

boolean