arithmetic: VIPS Reference Manual

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

## Stability Level

Stable, unless otherwise indicated

## Functions

int | vips_add ()
int | vips_sum ()
int | vips_subtract ()
int | vips_multiply ()
int | vips_divide ()
int | vips_linear ()
int | vips_linear1 ()
int | vips_remainder ()
int | vips_remainder_const ()
int | vips_remainder_const1 ()
int | vips_invert ()
int | vips_abs ()
int | vips_sign ()
int | vips_round ()
int | vips_floor ()
int | vips_ceil ()
int | vips_rint ()
int | vips_math ()
int | vips_sin ()
int | vips_cos ()
int | vips_tan ()
int | vips_asin ()
int | vips_acos ()
int | vips_atan ()
int | vips_exp ()
int | vips_exp10 ()
int | vips_log ()
int | vips_log10 ()
int | vips_complex ()
int | vips_polar ()
int | vips_rect ()
int | vips_conj ()
int | vips_complex2 ()
int | vips_cross_phase ()
int | vips_complexget ()
int | vips_real ()
int | vips_imag ()
int | vips_complexform ()
int | vips_relational ()
int | vips_equal ()
int | vips_notequal ()
int | vips_less ()
int | vips_lesseq ()
int | vips_more ()
int | vips_moreeq ()
int | vips_relational_const ()
int | vips_equal_const ()
int | vips_notequal_const ()
int | vips_less_const ()
int | vips_lesseq_const ()
int | vips_more_const ()
int | vips_moreeq_const ()
int | vips_relational_const1 ()
int | vips_equal_const1 ()
int | vips_notequal_const1 ()
int | vips_less_const1 ()
int | vips_lesseq_const1 ()
int | vips_more_const1 ()
int | vips_moreeq_const1 ()
int | vips_boolean ()
int | vips_andimage ()
int | vips_orimage ()
int | vips_eorimage ()
int | vips_lshift ()
int | vips_rshift ()
int | vips_boolean_const ()
int | vips_andimage_const ()
int | vips_orimage_const ()
int | vips_eorimage_const ()
int | vips_lshift_const ()
int | vips_rshift_const ()
int | vips_boolean_const1 ()
int | vips_andimage_const1 ()
int | vips_orimage_const1 ()
int | vips_eorimage_const1 ()
int | vips_lshift_const1 ()
int | vips_rshift_const1 ()
int | vips_math2 ()
int | vips_pow ()
int | vips_wop ()
int | vips_math2_const ()
int | vips_pow_const ()
int | vips_wop_const ()
int | vips_math2_const1 ()
int | vips_pow_const1 ()
int | vips_wop_const1 ()
int | vips_avg ()
int | vips_deviate ()
int | vips_min ()
int | vips_max ()
int | vips_stats ()
int | vips_measure ()
int | vips_find_trim ()
int | vips_getpoint ()
int | vips_hist_find ()
int | vips_hist_find_ndim ()
int | vips_hist_find_indexed ()
int | vips_hough_line ()
int | vips_hough_circle ()
int | vips_project ()
int | vips_profile ()

## Types and Values

enum | VipsOperationMath
enum | VipsOperationMath2
enum | VipsOperationRound
enum | VipsOperationRelational
enum | VipsOperationBoolean
enum | VipsOperationComplex
enum | VipsOperationComplex2
enum | VipsOperationComplexget

## Includes

    #include <vips/vips.h>

## 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 `vips_remainder_const()`, 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 VIPS_FORMAT_UCHAR images together, for example, produces a VIPS_FORMAT_USHORT image, and taking the `vips_cos()` of a VIPS_FORMAT_USHORT image produces VIPS_FORMAT_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 3. 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 range of possible values, except that int never becomes float.

## Functions

### vips_add ()

    int
    vips_add (VipsImage *left,
              VipsImage *right,
              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 format (see table Smallest common format in

arithmetic), then the

following table is used to determine the output type:

Table 4. VipsAdd 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.

Operations on integer images are performed using the processor's vector unit, if possible. Disable this with --vips-novector or IM_NOVECTOR.

See also: `vips_subtract()`, `vips_linear()`.

#### Parameters

left | input image |
right | input image |
out | output image. | [out]
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error

### vips_sum ()

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

This operation sums all images in `in` and writes the result to `out` .

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 the number of bands differs, all but one of the images must have one band. In this case, n-band images are formed from the one-band images by joining n copies of the one-band images together, and then the n-band images are operated upon.

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

arithmetic), then the

following table is used to determine the output type:

Table 5. VipsSum type promotion

input type | output type
--- | ---
uchar | uint
char | int
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: `vips_add()`.

#### Parameters

in | array of input images. | [array length=n]
out | output image. | [out]
n | number of input images |
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error

### vips_subtract ()

    int
    vips_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 format (see table Smallest common format in

arithmetic), then the

following table is used to determine the output type:

Table 6. VipsSubtract 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: `vips_add()`, `vips_linear()`.

#### Parameters

in1 | input image |
in2 | input image |
out | output image. | [out]
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error

### vips_multiply ()

    int
    vips_multiply (VipsImage *left,
                   VipsImage *right,
                   VipsImage **out,
                   ...);

This operation calculates `left` * `right` 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 format (see table Smallest common format in

arithmetic), then the

following table is used to determine the output type:

Table 7. VipsMultiply 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: `vips_add()`, `vips_linear()`.

#### Parameters

left | left-hand image |
right | right-hand image |
out | output image. | [out]
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error

### vips_divide ()

    int
    vips_divide (VipsImage *left,
                 VipsImage *right,
                 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 format (see table Smallest common format in

arithmetic), then the

following table is used to determine the output type:

Table 8. `vips_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: `vips_multiply()`, `vips_linear()`, `vips_pow()`.

#### Parameters

left | input image |
right | input image |
out | output image. | [out]
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error

### vips_linear ()

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

Optional arguments:

- `uchar` : output uchar pixels

Pass an image through a linear transform, ie. (`out` = `in` * `a` + `b` ). Output is float for integer input, double for double input, complex for complex input and double complex for double complex input. Set `uchar` to output uchar pixels.

If the arrays of constants have just one element, that constant is 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: `vips_linear1()`, `vips_add()`.

[method]

#### Parameters

in | image to transform |
out | output image. | [out]
a | array of constants for multiplication. | [array length=n]
b | array of constants for addition. | [array length=n]
n | length of constant arrays |
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error

### vips_linear1 ()

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

Optional arguments:

- `uchar` : output uchar pixels

Run `vips_linear()` with a single constant.

See also: `vips_linear()`.

[method]

#### Parameters

in | image to transform |
out | output image. | [out]
a | constant for multiplication |
b | constant for addition |
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error

### vips_remainder ()

    int
    vips_remainder (VipsImage *left,
                    VipsImage *right,
                    VipsImage **out,
                    ...);

This operation calculates `left` % `right` (remainder after integer division) and writes the result to `out` . The images may have any non-complex format. For float formats, `vips_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 format (see table Smallest common format in

arithmetic), and that format is the

result type.

See also: `vips_remainder_const()`, `vips_divide()`, `vips_round()`.

#### Parameters

left | left-hand input VipsImage |
right | right-hand input VipsImage |
out | output VipsImage. | [out]
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error

### vips_remainder_const ()

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

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

If the array of constants has just one element, that constant is used for all image bands. If the array has 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: `vips_remainder()`, `vips_divide()`, `vips_round()`.

[method]

#### Parameters

in | input image |
out | output image. | [out]
c | array of constants. | [array length=n]
n | number of constants in `c` |
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error

### vips_remainder_const1 ()

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

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

If the array of constants has just one element, that constant is used for all image bands. If the array has 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: `vips_remainder()`, `vips_divide()`, `vips_round()`.

[method]

#### Parameters

in | input image |
out | output image. | [out]
c | constant |
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error

### vips_invert ()

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

For unsigned formats, this operation calculates (max - `in` ), eg. (255 - `in` ) for uchar. For signed and float formats, this operation calculates (-1 `in` ).

For complex images, only the real part is inverted. See also `vips_conj()`.

See also: `vips_linear()`.

[method]

#### Parameters

in | input image |
out | output image. | [out]
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error

### vips_abs ()

    int
    vips_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 calculates modulus for complex types.

See also: `vips_sign()`.

[method]

#### Parameters

in | input VipsImage |
out | output VipsImage. | [out]
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error

### vips_sign ()

    int
    vips_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: `vips_abs()`.

[method]

#### Parameters

in | input image |
out | output image. | [out]
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error

### vips_round ()

    int
    vips_round (VipsImage *in,
                VipsImage **out,
                VipsOperationRound round,
                ...);

Round to an integral value.

Copy for integer types, round float and complex types.

The format of `out` is always the same as `in` , so you may wish to cast to an integer format afterwards.

See also: `vips_cast()`

[method]

#### Parameters

in | input VipsImage |
out | output VipsImage. | [out]
round | VipsOperationRound rounding operation to perform |
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error

### vips_floor ()

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

Round to an integral value with VIPS_OPERATION_ROUND_FLOOR. See `vips_round()`.

[method]

#### Parameters

in | input VipsImage |
out | output VipsImage. | [out]
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error

### vips_ceil ()

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

Round to an integral value with VIPS_OPERATION_ROUND_CEIL. See `vips_round()`.

[method]

#### Parameters

in | input VipsImage |
out | output VipsImage. | [out]
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error

### vips_rint ()

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

Round to an integral value with VIPS_OPERATION_ROUND_RINT. See `vips_round()`.

[method]

#### Parameters

in | input VipsImage |
out | output VipsImage. | [out]
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error

### vips_math ()

    int
    vips_math (VipsImage *in,
               VipsImage **out,
               VipsOperationMath math,
               ...);

Perform various functions in -lm, the maths library, on images.

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

[method]

#### Parameters

in | input VipsImage |
out | output VipsImage. | [out]
math | math operation to perform |
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error

### vips_sin ()

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

Perform VIPS_OPERATION_MATH_SIN on an image. See `vips_math()`.

[method]

#### Parameters

in | input VipsImage |
out | output VipsImage. | [out]
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error

### vips_cos ()

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

Perform VIPS_OPERATION_MATH_COS on an image. See `vips_math()`.

[method]

#### Parameters

in | input VipsImage |
out | output VipsImage. | [out]
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error

### vips_tan ()

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

Perform VIPS_OPERATION_MATH_TAN on an image. See `vips_math()`.

[method]

#### Parameters

in | input VipsImage |
out | output VipsImage. | [out]
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error

### vips_asin ()

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

Perform VIPS_OPERATION_MATH_ASIN on an image. See `vips_math()`.

[method]

#### Parameters

in | input VipsImage |
out | output VipsImage. | [out]
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error

### vips_acos ()

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

Perform VIPS_OPERATION_MATH_ACOS on an image. See `vips_math()`.

[method]

#### Parameters

in | input VipsImage |
out | output VipsImage. | [out]
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error

### vips_atan ()

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

Perform VIPS_OPERATION_MATH_ATAN on an image. See `vips_math()`.

[method]

#### Parameters

in | input VipsImage |
out | output VipsImage. | [out]
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error

### vips_exp ()

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

Perform VIPS_OPERATION_MATH_EXP on an image. See `vips_math()`.

[method]

#### Parameters

in | input VipsImage |
out | output VipsImage. | [out]
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error

### vips_exp10 ()

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

Perform VIPS_OPERATION_MATH_EXP10 on an image. See `vips_math()`.

[method]

#### Parameters

in | input VipsImage |
out | output VipsImage. | [out]
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error

### vips_log ()

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

Perform VIPS_OPERATION_MATH_LOG on an image. See `vips_math()`.

[method]

#### Parameters

in | input VipsImage |
out | output VipsImage. | [out]
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error

### vips_log10 ()

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

Perform VIPS_OPERATION_MATH_LOG10 on an image. See `vips_math()`.

[method]

#### Parameters

in | input VipsImage |
out | output VipsImage. | [out]
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error

### vips_complex ()

    int
    vips_complex (VipsImage *in,
                  VipsImage **out,
                  VipsOperationComplex cmplx,
                  ...);

Perform various operations on complex images.

Angles are expressed in degrees. The output type is complex unless the input is double or dpcomplex, in which case the output is dpcomplex.

[method]

#### Parameters

in | input VipsImage |
out | output VipsImage. | [out]
cmplx | complex operation to perform |
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error

### vips_polar ()

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

Perform VIPS_OPERATION_COMPLEX_POLAR on an image. See `vips_complex()`.

[method]

#### Parameters

in | input VipsImage |
out | output VipsImage. | [out]
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error

### vips_rect ()

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

Perform VIPS_OPERATION_COMPLEX_RECT on an image. See `vips_complex()`.

[method]

#### Parameters

in | input VipsImage |
out | output VipsImage. | [out]
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error

### vips_conj ()

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

Perform VIPS_OPERATION_COMPLEX_CONJ on an image. See `vips_complex()`.

[method]

#### Parameters

in | input VipsImage |
out | output VipsImage. | [out]
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error

### vips_complex2 ()

    int
    vips_complex2 (VipsImage *left,
                   VipsImage *right,
                   VipsImage **out,
                   VipsOperationComplex2 cmplx,
                   ...);

Perform various binary operations on complex images.

Angles are expressed in degrees. The output type is complex unless the input is double or dpcomplex, in which case the output is dpcomplex.

#### Parameters

left | input VipsImage |
right | input VipsImage |
out | output VipsImage. | [out]
cmplx | complex2 operation to perform |
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error

### vips_cross_phase ()

    int
    vips_cross_phase (VipsImage *left,
                      VipsImage *right,
                      VipsImage **out,
                      ...);

Perform VIPS_OPERATION_COMPLEX2_CROSS_PHASE on an image. See `vips_complex2()`.

#### Parameters

left | input VipsImage |
right | input VipsImage |
out | output VipsImage. | [out]
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error

### vips_complexget ()

    int
    vips_complexget (VipsImage *in,
                     VipsImage **out,
                     VipsOperationComplexget get,
                     ...);

Get components of complex images.

The output type is the same as the input type, except VIPS_FORMAT_COMPLEX becomes VIPS_FORMAT_FLOAT and VIPS_FORMAT_DPCOMPLEX becomes VIPS_FORMAT_DOUBLE.

[method]

#### Parameters

in | input VipsImage |
out | output VipsImage. | [out]
get | complex operation to perform |
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error

### vips_real ()

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

Perform VIPS_OPERATION_COMPLEXGET_REAL on an image. See `vips_complexget()`.

[method]

#### Parameters

in | input VipsImage |
out | output VipsImage. | [out]
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error

### vips_imag ()

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

Perform VIPS_OPERATION_COMPLEXGET_IMAG on an image. See `vips_complexget()`.

[method]

#### Parameters

in | input VipsImage |
out | output VipsImage. | [out]
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error

### vips_complexform ()

    int
    vips_complexform (VipsImage *left,
                      VipsImage *right,
                      VipsImage **out,
                      ...);

Compose two real images to make a complex image. If either `left` or `right` are VIPS_FORMAT_DOUBLE, `out` is VIPS_FORMAT_DPCOMPLEX. Otherwise `out` is VIPS_FORMAT_COMPLEX. `left` becomes the real component of `out` and `right` 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: `vips_complexget()`.

#### Parameters

left | input image |
right | input image |
out | output image. | [out]
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error

### vips_relational ()

    int
    vips_relational (VipsImage *left,
                     VipsImage *right,
                     VipsImage **out,
                     VipsOperationRelational relational,
                     ...);

Perform various relational operations on pairs of images.

The output type is always uchar, with 0 for FALSE and 255 for TRUE.

Less-than and greater-than for complex images compare the modulus.

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 format (see table Smallest common format in

arithmetic).

To decide if pixels match exactly, that is have the same value in every band, use `vips_bandbool()` after this operation to AND or OR image bands together.

See also: `vips_boolean()`, `vips_bandbool()`, `vips_relational_const()`.

#### Parameters

left | left-hand input VipsImage |
right | right-hand input VipsImage |
out | output VipsImage. | [out]
relational | relational operation to perform |
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error

### vips_equal ()

    int
    vips_equal (VipsImage *left,
                VipsImage *right,
                VipsImage **out,
                ...);

Perform VIPS_OPERATION_RELATIONAL_EQUAL on a pair of images. See `vips_relational()`.

#### Parameters

left | left-hand input VipsImage |
right | right-hand input VipsImage |
out | output VipsImage. | [out]
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error

### vips_notequal ()

    int
    vips_notequal (VipsImage *left,
                   VipsImage *right,
                   VipsImage **out,
                   ...);

Perform VIPS_OPERATION_RELATIONAL_NOTEQ on a pair of images. See `vips_relational()`.

#### Parameters

left | left-hand input VipsImage |
right | right-hand input VipsImage |
out | output VipsImage. | [out]
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error

### vips_less ()

    int
    vips_less (VipsImage *left,
               VipsImage *right,
               VipsImage **out,
               ...);

Perform VIPS_OPERATION_RELATIONAL_LESS on a pair of images. See `vips_relational()`.

#### Parameters

left | left-hand input VipsImage |
right | right-hand input VipsImage |
out | output VipsImage. | [out]
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error

### vips_lesseq ()

    int
    vips_lesseq (VipsImage *left,
                 VipsImage *right,
                 VipsImage **out,
                 ...);

Perform VIPS_OPERATION_RELATIONAL_LESSEQ on a pair of images. See `vips_relational()`.

#### Parameters

left | left-hand input VipsImage |
right | right-hand input VipsImage |
out | output VipsImage. | [out]
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error

### vips_more ()

    int
    vips_more (VipsImage *left,
               VipsImage *right,
               VipsImage **out,
               ...);

Perform VIPS_OPERATION_RELATIONAL_MORE on a pair of images. See `vips_relational()`.

#### Parameters

left | left-hand input VipsImage |
right | right-hand input VipsImage |
out | output VipsImage. | [out]
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error

### vips_moreeq ()

    int
    vips_moreeq (VipsImage *left,
                 VipsImage *right,
                 VipsImage **out,
                 ...);

Perform VIPS_OPERATION_RELATIONAL_MOREEQ on a pair of images. See `vips_relational()`.

#### Parameters

left | left-hand input VipsImage |
right | right-hand input VipsImage |
out | output VipsImage. | [out]
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error

### vips_relational_const ()

    int
    vips_relational_const (VipsImage *in,
                           VipsImage **out,
                           VipsOperationRelational relational,
                           double *c,
                           int n,
                           ...);

Perform various relational operations on an image and an array of constants.

The output type is always uchar, with 0 for FALSE and 255 for TRUE.

If the array of constants has just one element, that constant is used for all image bands. If the array has 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: `vips_boolean()`, `vips_relational()`.

[method]

#### Parameters

in | input image |
out | output image. | [out]
relational | relational operation to perform |
c | array of constants. | [array length=n]
n | number of constants in `c` |
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error

### vips_equal_const ()

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

Perform VIPS_OPERATION_RELATIONAL_EQUAL on an image and a constant. See `vips_relational_const()`.

[method]

#### Parameters

in | input VipsImage |
out | output VipsImage. | [out]
c | array of constants. | [array length=n]
n | number of constants in `c` |
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error

### vips_notequal_const ()

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

Perform VIPS_OPERATION_RELATIONAL_NOTEQ on an image and a constant. See `vips_relational_const()`.

[method]

#### Parameters

in | input VipsImage |
out | output VipsImage. | [out]
c | array of constants. | [array length=n]
n | number of constants in `c` |
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error

### vips_less_const ()

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

Perform VIPS_OPERATION_RELATIONAL_LESS on an image and a constant. See `vips_relational_const()`.

[method]

#### Parameters

in | input VipsImage |
out | output VipsImage. | [out]
c | array of constants. | [array length=n]
n | number of constants in `c` |
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error

### vips_lesseq_const ()

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

Perform VIPS_OPERATION_RELATIONAL_LESSEQ on an image and a constant. See `vips_relational_const()`.

[method]

#### Parameters

in | input VipsImage |
out | output VipsImage. | [out]
c | array of constants. | [array length=n]
n | number of constants in `c` |
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error

### vips_more_const ()

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

Perform VIPS_OPERATION_RELATIONAL_MORE on an image and a constant. See `vips_relational_const()`.

[method]

#### Parameters

in | input VipsImage |
out | output VipsImage. | [out]
c | array of constants. | [array length=n]
n | number of constants in `c` |
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error

### vips_moreeq_const ()

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

Perform VIPS_OPERATION_RELATIONAL_MOREEQ on an image and a constant. See `vips_relational_const()`.

[method]

#### Parameters

in | input VipsImage |
out | output VipsImage. | [out]
c | array of constants. | [array length=n]
n | number of constants in `c` |
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error

### vips_relational_const1 ()

    int
    vips_relational_const1 (VipsImage *in,
                            VipsImage **out,
                            VipsOperationRelational relational,
                            double c,
                            ...);

Perform various relational operations on an image and a constant. See `vips_relational_const()`.

See also: `vips_boolean()`, `vips_relational()`.

[method]

#### Parameters

in | input image |
out | output image. | [out]
relational | relational operation to perform |
c | constant |
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error

### vips_equal_const1 ()

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

Perform VIPS_OPERATION_RELATIONAL_EQUAL on an image and a constant. See `vips_relational_const()`.

[method]

#### Parameters

in | input image |
out | output image. | [out]
c | constant |
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error

### vips_notequal_const1 ()

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

Perform VIPS_OPERATION_RELATIONAL_NOTEQ on an image and a constant. See `vips_relational_const()`.

[method]

#### Parameters

in | input image |
out | output image. | [out]
c | constant |
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error

### vips_less_const1 ()

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

Perform VIPS_OPERATION_RELATIONAL_LESS on an image and a constant. See `vips_relational_const()`.

[method]

#### Parameters

in | input image |
out | output image. | [out]
c | constant |
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error

### vips_lesseq_const1 ()

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

Perform VIPS_OPERATION_RELATIONAL_LESSEQ on an image and a constant. See `vips_relational_const()`.

[method]

#### Parameters

in | input image |
out | output image. | [out]
c | constant |
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error

### vips_more_const1 ()

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

Perform VIPS_OPERATION_RELATIONAL_MORE on an image and a constant. See `vips_relational_const()`.

[method]

#### Parameters

in | input image |
out | output image. | [out]
c | constant |
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error

### vips_moreeq_const1 ()

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

Perform VIPS_OPERATION_RELATIONAL_MOREEQ on an image and a constant. See `vips_relational_const()`.

[method]

#### Parameters

in | input image |
out | output image. | [out]
c | constant |
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error

### vips_boolean ()

    int
    vips_boolean (VipsImage *left,
                  VipsImage *right,
                  VipsImage **out,
                  VipsOperationBoolean boolean,
                  ...);

Perform various boolean operations on pairs of images.

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

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 format (see table Smallest common format in

arithmetic).

See also: `vips_boolean_const()`.

#### Parameters

left | left-hand input VipsImage |
right | right-hand input VipsImage |
out | output VipsImage. | [out]
boolean | boolean operation to perform |
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error

### vips_andimage ()

    int
    vips_andimage (VipsImage *left,
                   VipsImage *right,
                   VipsImage **out,
                   ...);

Perform VIPS_OPERATION_BOOLEAN_AND on a pair of images. See `vips_boolean()`.

#### Parameters

left | left-hand input VipsImage |
right | right-hand input VipsImage |
out | output VipsImage. | [out]
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error

### vips_orimage ()

    int
    vips_orimage (VipsImage *left,
                  VipsImage *right,
                  VipsImage **out,
                  ...);

Perform VIPS_OPERATION_BOOLEAN_OR on a pair of images. See `vips_boolean()`.

#### Parameters

left | left-hand input VipsImage |
right | right-hand input VipsImage |
out | output VipsImage. | [out]
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error

### vips_eorimage ()

    int
    vips_eorimage (VipsImage *left,
                   VipsImage *right,
                   VipsImage **out,
                   ...);

Perform VIPS_OPERATION_BOOLEAN_EOR on a pair of images. See `vips_boolean()`.

#### Parameters

left | left-hand input VipsImage |
right | right-hand input VipsImage |
out | output VipsImage. | [out]
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error

### vips_lshift ()

    int
    vips_lshift (VipsImage *left,
                 VipsImage *right,
                 VipsImage **out,
                 ...);

Perform VIPS_OPERATION_BOOLEAN_LSHIFT on a pair of images. See `vips_boolean()`.

#### Parameters

left | left-hand input VipsImage |
right | right-hand input VipsImage |
out | output VipsImage. | [out]
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error

### vips_rshift ()

    int
    vips_rshift (VipsImage *left,
                 VipsImage *right,
                 VipsImage **out,
                 ...);

Perform VIPS_OPERATION_BOOLEAN_RSHIFT on a pair of images. See `vips_boolean()`.

#### Parameters

left | left-hand input VipsImage |
right | right-hand input VipsImage |
out | output VipsImage. | [out]
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error

### vips_boolean_const ()

    int
    vips_boolean_const (VipsImage *in,
                        VipsImage **out,
                        VipsOperationBoolean boolean,
                        double *c,
                        int n,
                        ...);

Perform various boolean operations on an image against an array of constants.

The output type is always uchar, with 0 for FALSE and 255 for TRUE.

If the array of constants has just one element, that constant is used for all image bands. If the array has 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: `vips_boolean()`, `vips_boolean_const1()`.

[method]

#### Parameters

in | input image |
out | output image. | [out]
boolean | boolean operation to perform |
c | array of constants. | [array length=n]
n | number of constants in `c` |
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error

### vips_andimage_const ()

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

Perform VIPS_OPERATION_BOOLEAN_AND on an image and an array of constants. See `vips_boolean_const()`.

See also: `vips_boolean()`, `vips_boolean_const1()`.

[method]

#### Parameters

in | input image |
out | output image. | [out]
c | array of constants. | [array length=n]
n | number of constants in `c` |
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error

### vips_orimage_const ()

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

Perform VIPS_OPERATION_BOOLEAN_OR on an image and an array of constants. See `vips_boolean_const()`.

See also: `vips_boolean()`, `vips_boolean_const1()`.

[method]

#### Parameters

in | input image |
out | output image. | [out]
c | array of constants. | [array length=n]
n | number of constants in `c` |
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error

### vips_eorimage_const ()

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

Perform VIPS_OPERATION_BOOLEAN_EOR on an image and an array of constants. See `vips_boolean_const()`.

See also: `vips_boolean()`, `vips_boolean_const1()`.

[method]

#### Parameters

in | input image |
out | output image. | [out]
c | array of constants. | [array length=n]
n | number of constants in `c` |
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error

### vips_lshift_const ()

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

Perform VIPS_OPERATION_BOOLEAN_LSHIFT on an image and an array of constants. See `vips_boolean_const()`.

See also: `vips_boolean()`, `vips_boolean_const1()`.

[method]

#### Parameters

in | input image |
out | output image. | [out]
c | array of constants. | [array length=n]
n | number of constants in `c` |
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error

### vips_rshift_const ()

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

Perform VIPS_OPERATION_BOOLEAN_LSHIFT on an image and an array of constants. See `vips_boolean_const()`.

See also: `vips_boolean()`, `vips_boolean_const1()`.

[method]

#### Parameters

in | input image |
out | output image. | [out]
c | array of constants. | [array length=n]
n | number of constants in `c` |
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error

### vips_boolean_const1 ()

    int
    vips_boolean_const1 (VipsImage *in,
                         VipsImage **out,
                         VipsOperationBoolean boolean,
                         double c,
                         ...);

Perform various boolean operations on an image with a single constant. See `vips_boolean_const()`.

See also: `vips_boolean()`, `vips_boolean_const()`.

[method]

#### Parameters

in | input image |
out | output image. | [out]
boolean | boolean operation to perform |
c | constant |
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error

### vips_andimage_const1 ()

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

Perform VIPS_OPERATION_BOOLEAN_AND on an image and a constant. See `vips_boolean_const1()`.

See also: `vips_boolean()`, `vips_boolean_const()`.

[method]

#### Parameters

in | input image |
out | output image. | [out]
c | constant |
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error

### vips_orimage_const1 ()

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

Perform VIPS_OPERATION_BOOLEAN_OR on an image and a constant. See `vips_boolean_const1()`.

See also: `vips_boolean()`, `vips_boolean_const()`.

[method]

#### Parameters

in | input image |
out | output image. | [out]
c | constant |
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error

### vips_eorimage_const1 ()

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

Perform VIPS_OPERATION_BOOLEAN_EOR on an image and a constant. See `vips_boolean_const1()`.

See also: `vips_boolean()`, `vips_boolean_const()`.

[method]

#### Parameters

in | input image |
out | output image. | [out]
c | constant |
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error

### vips_lshift_const1 ()

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

Perform VIPS_OPERATION_BOOLEAN_LSHIFT on an image and a constant. See `vips_boolean_const1()`.

See also: `vips_boolean()`, `vips_boolean_const()`.

[method]

#### Parameters

in | input image |
out | output image. | [out]
c | constant |
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error

### vips_rshift_const1 ()

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

Perform VIPS_OPERATION_BOOLEAN_RSHIFT on an image and a constant. See `vips_boolean_const1()`.

See also: `vips_boolean()`, `vips_boolean_const()`.

[method]

#### Parameters

in | input image |
out | output image. | [out]
c | constant |
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error

### vips_math2 ()

    int
    vips_math2 (VipsImage *left,
                VipsImage *right,
                VipsImage **out,
                VipsOperationMath2 math2,
                ...);

This operation calculates a 2-ary maths operation on a pair of images and writes the result to `out` . The images may have any non-complex format. `out` is float except in the case that either of `left` or `right` are double, in which case `out` is also double.

It detects division by zero, setting those pixels to zero in the output. Beware: it does this silently!

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 format (see table Smallest common format in

arithmetic), and that format is the

result type.

See also: `vips_math2_const()`.

#### Parameters

left | left-hand input VipsImage |
right | right-hand input VipsImage |
out | output VipsImage. | [out]
math2 | math operation to perform |
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error

### vips_pow ()

    int
    vips_pow (VipsImage *left,
              VipsImage *right,
              VipsImage **out,
              ...);

Perform VIPS_OPERATION_MATH2_POW on a pair of images. See `vips_math2()`.

#### Parameters

left | left-hand input VipsImage |
right | right-hand input VipsImage |
out | output VipsImage. | [out]
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error

### vips_wop ()

    int
    vips_wop (VipsImage *left,
              VipsImage *right,
              VipsImage **out,
              ...);

Perform VIPS_OPERATION_MATH2_WOP on a pair of images. See `vips_math2()`.

#### Parameters

left | left-hand input VipsImage |
right | right-hand input VipsImage |
out | output VipsImage. | [out]
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error

### vips_math2_const ()

    int
    vips_math2_const (VipsImage *in,
                      VipsImage **out,
                      VipsOperationMath2 math2,
                      double *c,
                      int n,
                      ...);

This operation calculates various 2-ary maths operations on an image and an array of constants and writes the result to `out` . The image may have any non-complex format. `out` is float except in the case that `in` is double, in which case `out` is also double.

It detects division by zero, setting those pixels to zero in the output. Beware: it does this silently!

If the array of constants has just one element, that constant is used for all image bands. If the array has 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: `vips_math2()`, `vips_math()`.

[method]

#### Parameters

in | input image |
out | output image. | [out]
math2 | math operation to perform |
c | array of constants. | [array length=n]
n | number of constants in `c` |
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error

### vips_pow_const ()

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

Perform VIPS_OPERATION_MATH2_POW on an image and a constant. See `vips_math2_const()`.

[method]

#### Parameters

in | left-hand input VipsImage |
out | output VipsImage. | [out]
c | array of constants. | [array length=n]
n | number of constants in `c` |
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error

### vips_wop_const ()

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

Perform VIPS_OPERATION_MATH2_WOP on an image and a constant. See `vips_math2_const()`.

[method]

#### Parameters

in | left-hand input VipsImage |
out | output VipsImage. | [out]
c | array of constants. | [array length=n]
n | number of constants in `c` |
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error

### vips_math2_const1 ()

    int
    vips_math2_const1 (VipsImage *in,
                       VipsImage **out,
                       VipsOperationMath2 math2,
                       double c,
                       ...);

This operation calculates various 2-ary maths operations on an image and a constant. See `vips_math2_const()`.

[method]

#### Parameters

in | input image |
out | output image. | [out]
math2 | math operation to perform |
c | constant |
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error

### vips_pow_const1 ()

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

Perform VIPS_OPERATION_MATH2_POW on an image and a constant. See `vips_math2_const()`.

[method]

#### Parameters

in | left-hand input VipsImage |
out | output VipsImage. | [out]
c | constant |
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error

### vips_wop_const1 ()

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

Perform VIPS_OPERATION_MATH2_WOP on an image and a constant. See `vips_math2_const()`.

[method]

#### Parameters

in | left-hand input VipsImage |
out | output VipsImage. | [out]
c | constant |
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error

### vips_avg ()

    int
    vips_avg (VipsImage *in,
              double *out,
              ...);

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

See also: `vips_stats()`, `vips_bandmean()`, `vips_deviate()`, `vips_rank()`

[method]

#### Parameters

in | input VipsImage |
out | output pixel average. | [out]
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error

### vips_deviate ()

    int
    vips_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 `vips_stats()` if you need to calculate an average for each band.

Non-complex images only.

See also: `vips_avg()`, `vips_stats()`..

[method]

#### Parameters

in | input VipsImage |
out | output pixel standard deviation. | [out]
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error

### vips_min ()

    int
    vips_min (VipsImage *in,
              double *out,
              ...);

Optional arguments:

- `x` : horizontal position of minimum

- `y` : vertical position of minimum

- `size` : number of minima to find

- `out_array` : return array of minimum values

- `x_array` : corresponding horizontal positions

- `y_array` : corresponding vertical positions

This operation finds the minimum value in an image.

By default it finds the single smallest value. If `size` is set >1, it will find the `size` smallest values. It will stop searching early if has found enough values. Equal values will be sorted by y then x.

It operates on all bands of the input image: use `vips_stats()` if you need to find an minimum for each band.

For complex images, this operation finds the minimum modulus.

You can read out the position of the minimum with `x` and `y` . You can read out arrays of the values and positions of the top `size` minima with `out_array` , `x_array` and `y_array` . These values are returned sorted from smallest to largest.

If there are more than `size` minima, the minima returned will be a random selection of the minima in the image.

See also: `vips_min()`, `vips_stats()`.

[method]

#### Parameters

in | input VipsImage |
out | output pixel minimum. | [out]
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error

### vips_max ()

    int
    vips_max (VipsImage *in,
              double *out,
              ...);

Optional arguments:

- `x` : horizontal position of maximum

- `y` : vertical position of maximum

- `size` : number of maxima to find

- `out_array` : return array of maximum values

- `x_array` : corresponding horizontal positions

- `y_array` : corresponding vertical positions

This operation finds the maximum value in an image.

By default it finds the single largest value. If `size` is set >1, it will find the `size` largest values. It will stop searching early if has found enough values. Equal values will be sorted by y then x.

It operates on all bands of the input image: use `vips_stats()` if you need to find an maximum for each band.

For complex images, this operation finds the maximum modulus.

You can read out the position of the maximum with `x` and `y` . You can read out arrays of the values and positions of the top `size` maxima with `out_array` , `x_array` and `y_array` . These values are returned sorted from largest to smallest.

If there are more than `size` maxima, the maxima returned will be a random selection of the maxima in the image.

See also: `vips_min()`, `vips_stats()`.

[method]

#### Parameters

in | input VipsImage |
out | output pixel maximum. | [out]
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error

### vips_stats ()

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

Find many image statistics in a single pass through the data. `out` is a one-band VIPS_FORMAT_DOUBLE image of at least 10 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, x coordinate of minimum, y coordinate of minimum, x coordinate of maximum, y coordinate of maximum. Later versions of `vips_stats()` may add more columns.

Row 0 has statistics for all bands together, row 1 has stats for band 1, and so on.

If there is more than one maxima or minima, one of them will be chosen at random.

See also: `vips_avg()`, `vips_min()`.

[method]

#### Parameters

in | image to scan |
out | image of statistics. | [out]
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error

### vips_measure ()

    int
    vips_measure (VipsImage *in,
                  VipsImage **out,
                  int h,
                  int v,
                  ...);

Optional arguments:

- `left` : area of image containing chart

- `top` : area of image containing chart

- `width` : area of image containing chart

- `height` : area of image containing chart

Analyse a grid of colour patches, producing an array 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 the chart does not fill the whole image, use the optional `left` , `top` , `width` , `height` arguments to indicate the position of the chart.

See also: `vips_avg()`, `vips_deviate()`.

[method]

#### Parameters

in | image to measure |
out | array of measurements. | [out]
h | patches across chart |
v | patches down chart |
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error

### vips_find_trim ()

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

Optional arguments:

- `threshold` : `gdouble`, background / object threshold

- `background` : VipsArrayDouble, background colour

Search `in` for the bounding box of the non-background area.

Any alpha is flattened out, then the image is median-filtered, all the row and column sums of the absolute difference from `background` are calculated in a single pass, then the first row or column in each of the four directions where the sum is greater than `threshold` gives the bounding box.

If the image is entirely background, `vips_find_trim()` returns `width` == 0 and `height` == 0.

`background` defaults to 255, or 65535 for 16-bit images. Set another value, or use `vips_getpoint()` to pick a value from an edge. You'll need to flatten before `vips_getpoint()` to get a correct background value.

`threshold` defaults to 10.

The image needs to be at least 3x3 pixels in size.

See also: `vips_getpoint()`, `vips_extract_area()`, `vips_smartcrop()`.

[method]

#### Parameters

in | image to find_trim |
left | output left edge. | [out]
top | output top edge. | [out]
width | output width. | [out]
height | output height. | [out]
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error

### vips_getpoint ()

    int
    vips_getpoint (VipsImage *in,
                   double **vector,
                   int *n,
                   int x,
                   int y,
                   ...);

Reads a single pixel on an image.

The pixel values are returned in `vector` , the length of the array in `n` . You must free the array with `g_free()` when you are done with it.

See also: `vips_draw_point()`.

[method]

#### Parameters

in | image to read from |
vector | output pixel value here. | [out][array length=n]
n | length of output vector |
x | position to read |
y | position to read |
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, or -1 on error.

### vips_hist_find ()

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

Optional arguments:

- `band` : band to equalise

Find the histogram of `in` . Find the histogram for band `band` (producing a one-band histogram), or for all bands (producing an n-band histogram) if `band` is -1.

`in` is cast to u8 or u16. `out` is always u32.

See also: `vips_hist_find_ndim()`, `vips_hist_find_indexed()`.

[method]

#### Parameters

in | input image |
out | output image. | [out]
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error

### vips_hist_find_ndim ()

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

Optional arguments:

- `bins` : number of bins to make on each axis

Make a one, two or three dimensional histogram of a 1, 2 or 3 band image. Divide each axis into `bins` bins .. ie. output is 1 x bins, bins x bins, or bins x bins x bins bands. `bins` defaults to 10.

Images are cast to uchar or ushort before histogramming.

See also: `vips_hist_find()`, `vips_hist_find_indexed()`.

[method]

#### Parameters

in | input image |
out | output image. | [out]
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error

### vips_hist_find_indexed ()

    int
    vips_hist_find_indexed (VipsImage *in,
                            VipsImage *index,
                            VipsImage **out,
                            ...);

Optional arguments:

- `combine` : VipsCombine, combine bins like this

Make a histogram of `in` , but use image `index` to pick the bins. In other words, element zero in `out` contains the combination of all the pixels in `in` whose corresponding pixel in `index` is zero.

`index` must have just one band and be u8 or u16. `in` must be non-complex. `out` always has the same size and format as `in` .

Normally, bins are summed, but you can use `combine` to set other combine modes.

This operation is useful in conjunction with `vips_labelregions()`. You can use it to find the centre of gravity of blobs in an image, for example.

See also: `vips_hist_find()`, `vips_labelregions()`.

[method]

#### Parameters

in | input VipsImage |
index | input index VipsImage |
out | output image. | [out]
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error

### vips_hough_line ()

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

Optional arguments:

- `width` : horizontal size of parameter space

- `height` : vertical size of parameter space

Find the line Hough transform for `in` . `in` must have one band. `out` has one band, with pixels being the number of votes for that line. The X dimension of `out` is the line angle in 0 - 180 degrees, the Y dimension is the distance of the closest part of that line to the origin in the top-left.

Use `width` `height` to set the size of the parameter space image (`out` ), that is, how accurate the line determination should be.

See also: `vips_hough_circle()`.

[method]

#### Parameters

in | input image |
out | output image. | [out]
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error

### vips_hough_circle ()

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

Optional arguments:

- `scale` : scale down dimensions by this much

- `min_radius` : smallest radius to search for

- `max_radius` : largest radius to search for

Find the circular Hough transform of an image. `in` must be one band, with non-zero pixels for image edges. `out` is three-band, with the third channel representing the detected circle radius. The operation scales the number of votes by circle circumference so circles of differing size are given equal weight.

Use `max_radius` and `min_radius` to set the range of radii to search for.

Use `scale` to set how `in` coordinates are scaled to `out` coordinates. A `scale` of 3, for example, will make `out` 1/3rd of the width and height of `in` , and reduce the number of radii tested (and hence the number of bands int `out` ) by a factor of three as well.

See also: `vips_hough_line()`.

[method]

#### Parameters

in | input image |
out | output image. | [out]
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error

### vips_project ()

    int
    vips_project (VipsImage *in,
                  VipsImage **columns,
                  VipsImage **rows,
                  ...);

Find the horizontal and vertical projections of an image, ie. the sum of every row of pixels, and the sum of every column of pixels. The output format is uint, int or double, depending on the input format.

Non-complex images only.

See also: `vips_hist_find()`, `vips_profile()`.

[method]

#### Parameters

in | input image |
columns | sums of columns. | [out]
rows | sums of rows. | [out]
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error

### vips_profile ()

    int
    vips_profile (VipsImage *in,
                  VipsImage **columns,
                  VipsImage **rows,
                  ...);

vips_profile() searches inward from the edge of `in` and finds the first non-zero pixel. Pixels in `columns` have the distance from the top edge to the first non-zero pixel in that column, `rows` has the distance from the left edge to the first non-zero pixel in that row.

See also: `vips_project()`, `vips_hist_find()`.

[method]

#### Parameters

in | input image |
columns | distances from top edge. | [out]
rows | distances from left edge. | [out]
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error

## Types and Values

### enum VipsOperationMath

See also: `vips_math()`.

#### Members

VIPS_OPERATION_MATH_SIN | sin(), angles in degrees |
VIPS_OPERATION_MATH_COS | cos(), angles in degrees |
VIPS_OPERATION_MATH_TAN | tan(), angles in degrees |
VIPS_OPERATION_MATH_ASIN | asin(), angles in degrees |
VIPS_OPERATION_MATH_ACOS | acos(), angles in degrees |
VIPS_OPERATION_MATH_ATAN | atan(), angles in degrees |
VIPS_OPERATION_MATH_LOG | log base e |
VIPS_OPERATION_MATH_LOG10 | log base 10 |
VIPS_OPERATION_MATH_EXP | e to the something |
VIPS_OPERATION_MATH_EXP10 | 10 to the something |
VIPS_OPERATION_MATH_LAST |  |

### enum VipsOperationMath2

See also: `vips_math()`.

#### Members

VIPS_OPERATION_MATH2_POW | pow( left, right ) |
VIPS_OPERATION_MATH2_WOP | pow( right, left ) |
VIPS_OPERATION_MATH2_LAST |  |

### enum VipsOperationRound

See also: `vips_round()`.

#### Members

VIPS_OPERATION_ROUND_RINT | round to nearest |
VIPS_OPERATION_ROUND_CEIL | the smallest integral value not less than |
VIPS_OPERATION_ROUND_FLOOR | largest integral value not greater than |
VIPS_OPERATION_ROUND_LAST |  |

### enum VipsOperationRelational

See also: `vips_relational()`.

#### Members

VIPS_OPERATION_RELATIONAL_EQUAL | == |
VIPS_OPERATION_RELATIONAL_NOTEQ | != |
VIPS_OPERATION_RELATIONAL_LESS | < |
VIPS_OPERATION_RELATIONAL_LESSEQ | <= |
VIPS_OPERATION_RELATIONAL_MORE |  |
VIPS_OPERATION_RELATIONAL_MOREEQ | = |
VIPS_OPERATION_RELATIONAL_LAST |  |

### enum VipsOperationBoolean

See also: `vips_boolean()`.

#### Members

VIPS_OPERATION_BOOLEAN_AND | & |
VIPS_OPERATION_BOOLEAN_OR | | |
VIPS_OPERATION_BOOLEAN_EOR | ^ |
VIPS_OPERATION_BOOLEAN_LSHIFT | > |
VIPS_OPERATION_BOOLEAN_RSHIFT | << |
VIPS_OPERATION_BOOLEAN_LAST |  |

### enum VipsOperationComplex

See also: `vips_complex()`.

#### Members

VIPS_OPERATION_COMPLEX_POLAR | convert to polar coordinates |
VIPS_OPERATION_COMPLEX_RECT | convert to rectangular coordinates |
VIPS_OPERATION_COMPLEX_CONJ | complex conjugate |
VIPS_OPERATION_COMPLEX_LAST |  |

### enum VipsOperationComplex2

See also: `vips_complex2()`.

#### Members

VIPS_OPERATION_COMPLEX2_CROSS_PHASE | convert to polar coordinates |
VIPS_OPERATION_COMPLEX2_LAST |  |

### enum VipsOperationComplexget

See also: `vips_complexget()`.

#### Members

VIPS_OPERATION_COMPLEXGET_REAL | get real component |
VIPS_OPERATION_COMPLEXGET_IMAG | get imaginary component |
VIPS_OPERATION_COMPLEXGET_LAST |  |