arithmetic

arithmetic — 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_clamp ()
int vips_maxpair ()
int vips_minpair ()
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_sinh ()
int vips_cosh ()
int vips_tanh ()
int vips_asinh ()
int vips_acosh ()
int vips_atanh ()
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_atan2 ()
int vips_math2_const ()
int vips_pow_const ()
int vips_wop_const ()
int vips_atan2_const ()
int vips_math2_const1 ()
int vips_pow_const1 ()
int vips_wop_const1 ()
int vips_atan2_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 ()

Object Hierarchy

    GEnum
    ├── VipsOperationBoolean
    ├── VipsOperationComplex
    ├── VipsOperationComplex2
    ├── VipsOperationComplexget
    ├── VipsOperationMath
    ├── VipsOperationMath2
    ├── VipsOperationRelational
    ╰── VipsOperationRound

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.

After processing, use vips_cast() and friends to take then format back down again. vips_cast_uchar(), for example, will cast any image down to 8-bit unsigned.

Images have an *interpretation*: a meaning for the pixel values. With VIPS_INTERPRETATION_sRGB, for example, the first three bands will be interpreted (for example, by a saver like vips_jpegsave()) as R, G and B, with values in 0 - 255, and any fourth band will be interpreted as an alpha channel.

After arithmetic, you may wish to change the interpretation (for example to save as 16-bit PNG). Use vips_copy() to change the interpretation without changing pixels.

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.

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,
             const double *a,
             const 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,
                      const 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_clamp ()

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

Optional arguments:

  • min : gdouble, minimum value

  • max : gdouble, maximum value

This operation clamps pixel values to a range, by default 0 - 1.

Use min and max to change the range.

See also: vips_sign(), vips_abs(), vips_sdf().

[method]

Parameters

in

input VipsImage

 

out

output VipsImage.

[out]

...

NULL-terminated list of optional named arguments

 

Returns

0 on success, -1 on error


vips_maxpair ()

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

For each pixel, pick the maximum of a pair of images.

See also: vips_minpair().

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

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

For each pixel, pick the minimum of a pair of images.

See also: vips_minpair().

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

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

Perform VIPS_OPERATION_MATH_SINH 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_cosh ()

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

Perform VIPS_OPERATION_MATH_COSH 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_tanh ()

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

Perform VIPS_OPERATION_MATH_TANH 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_asinh ()

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

Perform VIPS_OPERATION_MATH_ASINH 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_acosh ()

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

Perform VIPS_OPERATION_MATH_ACOSH 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_atanh ()

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

Perform VIPS_OPERATION_MATH_ATANH 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,
                       const 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,
                  const 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,
                     const 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,
                 const 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,
                   const 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,
                 const 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,
                   const 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,
                    const 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,
                     const 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,
                    const 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,
                     const 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,
                   const 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,
                   const 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_atan2 ()

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

Perform VIPS_OPERATION_MATH2_ATAN2 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,
                  const 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,
                const 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,
                const 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_atan2_const ()

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

Perform VIPS_OPERATION_MATH2_ATAN2 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_atan2_const1 ()

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

Perform VIPS_OPERATION_MATH2_ATAN2 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

  • line_art : gboolean, enable line art mode

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

Any alpha is flattened out, then the image is median-filtered (unless line_art is set, see below). The absolute difference from background is computed and binarized according to threshold . Row and column sums of the absolute difference are calculated from this binary image and searched for the first row or column in each direction to obtain 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 detector is designed for photographic or compressed images where there is a degree of noise that needs filtering. If your images are synthetic (eg. rendered from vector art, perhaps), set line_art to disable this filtering.

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.

The result array has an element for each band. If unpack_complex is set, pixels in complex images are returned as double-length arrays.

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.

char and uchar images are cast to uchar before histogramming, all other image types are cast to ushort.

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.

char and uchar images are cast to uchar before histogramming, all other image types are cast to ushort.

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:

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.

char and uchar index images are cast to uchar before histogramming, all other image types are cast to ushort. index must have just one band.

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.

The output pixel at (x, y, band) is the strength of the circle centred on (x, y) and with radius (band).

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_SINH

sinh(), angles in radians

 

VIPS_OPERATION_MATH_COSH

cosh(), angles in radians

 

VIPS_OPERATION_MATH_TANH

tanh(), angles in radians

 

VIPS_OPERATION_MATH_ASINH

asinh(), angles in radians

 

VIPS_OPERATION_MATH_ACOSH

acosh(), angles in radians

 

VIPS_OPERATION_MATH_ATANH

atanh(), angles in radians

 

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_ATAN2

atan2(left, right)

 

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