## relational

relational — relational comparisons between pairs of images and images and constants

## Stability Level

Stable, unless otherwise indicated

## Synopsis

    #include <vips/vips.h>

    int                 im_equal                            (VipsImage *in1,
                                                             VipsImage *in2,
                                                             VipsImage *out);
    int                 im_notequal                         (VipsImage *in1,
                                                             VipsImage *in2,
                                                             VipsImage *out);
    int                 im_less                             (VipsImage *in1,
                                                             VipsImage *in2,
                                                             VipsImage *out);
    int                 im_lesseq                           (VipsImage *in1,
                                                             VipsImage *in2,
                                                             VipsImage *out);
    int                 im_more                             (VipsImage *in1,
                                                             VipsImage *in2,
                                                             VipsImage *out);
    int                 im_moreeq                           (VipsImage *in1,
                                                             VipsImage *in2,
                                                             VipsImage *out);
    int                 im_equal_vec                        (VipsImage *in,
                                                             VipsImage *out,
                                                             int n,
                                                             double *c);
    int                 im_notequal_vec                     (VipsImage *in,
                                                             VipsImage *out,
                                                             int n,
                                                             double *c);
    int                 im_less_vec                         (VipsImage *in,
                                                             VipsImage *out,
                                                             int n,
                                                             double *c);
    int                 im_lesseq_vec                       (VipsImage *in,
                                                             VipsImage *out,
                                                             int n,
                                                             double *c);
    int                 im_more_vec                         (VipsImage *in,
                                                             VipsImage *out,
                                                             int n,
                                                             double *c);
    int                 im_moreeq_vec                       (VipsImage *in,
                                                             VipsImage *out,
                                                             int n,
                                                             double *c);
    int                 im_equalconst                       (VipsImage *in,
                                                             VipsImage *out,
                                                             double c);
    int                 im_notequalconst                    (VipsImage *in,
                                                             VipsImage *out,
                                                             double c);
    int                 im_lessconst                        (VipsImage *in,
                                                             VipsImage *out,
                                                             double c);
    int                 im_lesseqconst                      (VipsImage *in,
                                                             VipsImage *out,
                                                             double c);
    int                 im_moreconst                        (VipsImage *in,
                                                             VipsImage *out,
                                                             double c);
    int                 im_moreeqconst                      (VipsImage *in,
                                                             VipsImage *out,
                                                             double c);
    int                 im_ifthenelse                       (VipsImage *c,
                                                             VipsImage *a,
                                                             VipsImage *b,
                                                             VipsImage *out);
    int                 im_blend                            (VipsImage *c,
                                                             VipsImage *a,
                                                             VipsImage *b,
                                                             VipsImage *out);

## Description

These operations perform comparison operations, such as equals, on every pixel in an image or pair of images. All will work with images of any type or any mixture of types of any size and of any number of bands.

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

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

The output type is always unsigned char, with 255 for every band element for which the condition is true, and 0 for every other element. For complex images, the operations calculate and compare the modulus.

For binary operations on pairs of images, the images must match in size.

## Details

### im_equal ()

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

This operation calculates `in1` == `in2` (image element equals image element) and writes the result to `out`.

See also: `im_notequal()`.

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

### im_notequal ()

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

This operation calculates `in1` != `in2` (image element does not equal image element) and writes the result to `out`.

See also: `im_notequal()`.

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

### im_less ()

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

This operation calculates `in1` < `in2` (image element is less than image element) and writes the result to `out`.

See also: `im_more()`.

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

### im_lesseq ()

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

This operation calculates `in1` <= `in2` (image element is less than or equal to image elemment) and writes the result to `out`.

See also: `im_more()`.

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

### im_more ()

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

This operation calculates `in1` > `in2` (image element is greater than image elemment) and writes the result to `out`.

See also: `im_less()`.

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

### im_moreeq ()

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

This operation calculates `in1` >= `in2` (image element is greater than or equal to image element) and writes the result to `out`.

See also: `im_more()`.

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

### im_equal_vec ()

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

This operation calculates `in` == `c` (image element equals constant array `c`) and writes the result to `out`.

See also: `im_equal()`, `im_equalconst()`.

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

### im_notequal_vec ()

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

This operation calculates `in` != `c` (image element is not equal to constant array `c`) and writes the result to `out`.

See also: `im_equal()`, `im_equal_vec()`.

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

### im_less_vec ()

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

This operation calculates `in` < `c` (image element is less than constant array `c`) and writes the result to `out`.

See also: `im_less()`, `im_lessconst()`.

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

### im_lesseq_vec ()

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

This operation calculates `in` <= `c` (image element is less than or equal to constant array `c`) and writes the result to `out`.

See also: `im_lesseq()`, `im_lesseqconst()`.

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

### im_more_vec ()

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

This operation calculates `in` > `c` (image element is greater than constant array `c`) and writes the result to `out`.

See also: `im_lesseq()`, `im_lesseqconst()`.

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

### im_moreeq_vec ()

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

This operation calculates `in` >= `c` (image element is greater than or equal to constant array `c`) and writes the result to `out`.

See also: `im_lesseq()`, `im_lesseqconst()`.

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

### im_equalconst ()

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

This operation calculates `in` == `c` (image element is equal to constant `c`) and writes the result to `out`.

See also: `im_lesseq()`, `im_lesseqconst()`.

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

### im_notequalconst ()

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

This operation calculates `in` != `c` (image element is not equal to constant `c`) and writes the result to `out`.

See also: `im_lesseq()`, `im_lesseqconst()`.

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

### im_lessconst ()

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

This operation calculates `in` < `c` (image element is less than constant `c`) and writes the result to `out`.

See also: `im_lesseq()`, `im_lesseqconst()`.

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

### im_lesseqconst ()

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

This operation calculates `in` = `c` (image element is less than or equal to constant `c`) and writes the result to `out`.

See also: `im_lesseq()`, `im_lesseqconst()`.

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

### im_moreconst ()

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

This operation calculates `in` = `c` (image element is more than constant `c`) and writes the result to `out`.

See also: `im_lesseq()`, `im_lesseqconst()`.

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

### im_moreeqconst ()

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

This operation calculates `in` = `c` (image element is more than or equal to constant `c`) and writes the result to `out`.

See also: `im_lesseq()`, `im_lesseqconst()`.

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

### im_ifthenelse ()

    int                 im_ifthenelse                       (VipsImage *c,
                                                             VipsImage *a,
                                                             VipsImage *b,
                                                             VipsImage *out);

This operation scans the condition image `c` and uses it to select pixels from either the then image `a` or the else image `b`. Non-zero means `a`, 0 means `b`.

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

Images `a` and `b` are cast up to the smallest common format.

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

See also: `im_blend()`, `im_equal()`.

`c` : | condition IMAGE
`a` : | then IMAGE
`b` : | else IMAGE
`out` : | output IMAGE
Returns : | 0 on success, -1 on error

### im_blend ()

    int                 im_blend                            (VipsImage *c,
                                                             VipsImage *a,
                                                             VipsImage *b,
                                                             VipsImage *out);

This operation scans the condition image `c` and uses it to blend pixels from either the then image `a` or the else image `b`. 255 means `a` only, 0 means `b` only, and intermediate values are a mixture.

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

Images `a` and `b` are cast up to the smallest common format.

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

See also: `im_ifthenelse()`, `im_equal()`.

`c` : | condition IMAGE
`a` : | then IMAGE
`b` : | else IMAGE
`out` : | output IMAGE
Returns : | 0 on success, -1 on error

## See Also

arithmetic