## mask

mask — load, save and process mask (matrix) objects

## Stability Level

Stable, unless otherwise indicated

## Synopsis

    #include <vips/vips.h>

                        INTMASK;
                        DOUBLEMASK;
    INTMASK *           im_create_imask                     (const char *filename,
                                                             int xsize,
                                                             int ysize);
    INTMASK *           im_create_imaskv                    (const char *filename,
                                                             int xsize,
                                                             int ysize,
                                                             ...);
    DOUBLEMASK *        im_create_dmask                     (const char *filename,
                                                             int xsize,
                                                             int ysize);
    DOUBLEMASK *        im_create_dmaskv                    (const char *filename,
                                                             int xsize,
                                                             int ysize,
                                                             ...);
    INTMASK *           im_read_imask                       (const char *filename);
    DOUBLEMASK *        im_read_dmask                       (const char *filename);
    void                im_print_imask                      (INTMASK *in);
    void                im_print_dmask                      (DOUBLEMASK *in);
    int                 im_write_imask                      (INTMASK *in);
    int                 im_write_dmask                      (DOUBLEMASK *in);
    int                 im_write_imask_name                 (INTMASK *in,
                                                             const char *filename);
    int                 im_write_dmask_name                 (DOUBLEMASK *in,
                                                             const char *filename);
    int                 im_free_imask                       (INTMASK *in);
    int                 im_free_dmask                       (DOUBLEMASK *in);
    INTMASK *           im_log_imask                        (const char *filename,
                                                             double sigma,
                                                             double min_ampl);
    DOUBLEMASK *        im_log_dmask                        (const char *filename,
                                                             double sigma,
                                                             double min_ampl);
    INTMASK *           im_gauss_imask                      (const char *filename,
                                                             double sigma,
                                                             double min_ampl);
    INTMASK *           im_gauss_imask_sep                  (const char *filename,
                                                             double sigma,
                                                             double min_ampl);
    DOUBLEMASK *        im_gauss_dmask                      (const char *filename,
                                                             double sigma,
                                                             double min_ampl);
    DOUBLEMASK *        im_gauss_dmask_sep                  (const char *filename,
                                                             double sigma,
                                                             double min_ampl);
    INTMASK *           im_dup_imask                        (INTMASK *in,
                                                             const char *filename);
    DOUBLEMASK *        im_dup_dmask                        (DOUBLEMASK *in,
                                                             const char *filename);
    INTMASK *           im_scale_dmask                      (DOUBLEMASK *in,
                                                             const char *filename);
    void                im_norm_dmask                       (DOUBLEMASK *mask);
    DOUBLEMASK *        im_imask2dmask                      (INTMASK *in,
                                                             const char *filename);
    INTMASK *           im_dmask2imask                      (DOUBLEMASK *in,
                                                             const char *filename);
    INTMASK *           im_rotate_imask90                   (INTMASK *in,
                                                             const char *filename);
    INTMASK *           im_rotate_imask45                   (INTMASK *in,
                                                             const char *filename);
    DOUBLEMASK *        im_rotate_dmask90                   (DOUBLEMASK *in,
                                                             const char *filename);
    DOUBLEMASK *        im_rotate_dmask45                   (DOUBLEMASK *in,
                                                             const char *filename);
    DOUBLEMASK *        im_mattrn                           (DOUBLEMASK *in,
                                                             const char *filename);
    DOUBLEMASK *        im_matcat                           (DOUBLEMASK *top,
                                                             DOUBLEMASK *bottom,
                                                             const char *filename);
    DOUBLEMASK *        im_matmul                           (DOUBLEMASK *in1,
                                                             DOUBLEMASK *in2,
                                                             const char *filename);
    DOUBLEMASK *        im_lu_decomp                        (const DOUBLEMASK *mat,
                                                             const char *filename);
    int                 im_lu_solve                         (const DOUBLEMASK *lu,
                                                             double *vec);
    DOUBLEMASK *        im_matinv                           (const DOUBLEMASK *mat,
                                                             const char *filename);
    int                 im_matinv_inplace                   (DOUBLEMASK *mat);
    DOUBLEMASK *        im_local_dmask                      (struct _VipsImage *out,
                                                             DOUBLEMASK *mask);
    INTMASK *           im_local_imask                      (struct _VipsImage *out,
                                                             INTMASK *mask);

## Description

These operations load, save and process mask objects. Masks are used as paramaters to convolution and morphology operators, and to represent matrices. There are two types of matrix: integer INTMASK and double precision floating point DOUBLEMASK.

This API is horrible and clunky. Surely it will be replaced soon.

## Details

### INTMASK

    typedef struct {
    	int xsize;
    	int ysize;
    	int scale;
    	int offset;
    	int *coeff;
    	char *filename;
    } INTMASK;

An integer mask.

`scale` lets the mask represent fractional values: for example, in integer convolution (see `im_conv()`) the result of the convolution is divided by `scale` and then added to `offset` before being written to the output image.

`scale` and `offset` default to 1 and 0. Various functions, such as `im_conv()`, will fail if `scale` is zero.

You can read and write the matrix elements in `coeff`.

int `xsize`; | mask width
int `ysize`; | mask height
int `scale`; | mask scale factor
int `offset`; | mask offset
int *`coeff`; | array of mask elements
char *`filename`; | the file this mask was read from, or should be written to

### DOUBLEMASK

    typedef struct {
    	int xsize;
    	int ysize;
    	double scale;
    	double offset;
    	double *coeff;
    	char *filename;
    } DOUBLEMASK;

A floating-point mask.

As with INTMASK, in convolution (see `im_convf()`) the result of the convolution is divided by `scale` and then added to `offset` before being written to the output image.

`scale` and `offset` default to 1.0 and 0.0. Various functions, such as `im_conv()`, will fail if `scale` is zero.

You can read and write the matrix elements in `coeff`.

int `xsize`; | mask width
int `ysize`; | mask height
double `scale`; | mask scale factor
double `offset`; | mask offset
double *`coeff`; | array of mask elements
char *`filename`; | the file this mask was read from, or should be written to

### im_create_imask ()

    INTMASK *           im_create_imask                     (const char *filename,
                                                             int xsize,
                                                             int ysize);

Create an empty imask. You need to loop over `coeff` to set the values.

See also: `im_create_imaskv()`.

`filename` : | set mask filename to this
`xsize` : | mask width
`ysize` : | mask height
Returns : | The newly-allocated mask.

### im_create_imaskv ()

    INTMASK *           im_create_imaskv                    (const char *filename,
                                                             int xsize,
                                                             int ysize,
                                                             ...);

Create an imask and initialise it from the function parameter list.

See also: `im_create_imask()`.

`filename` : | set mask filename to this
`xsize` : | mask width
`ysize` : | mask height
`...` : | values to set for the mask
Returns : | The newly-allocated mask.

### im_create_dmask ()

    DOUBLEMASK *        im_create_dmask                     (const char *filename,
                                                             int xsize,
                                                             int ysize);

Create an empty dmask. You need to loop over `coeff` to set the values.

See also: `im_create_dmaskv()`, `im_vips2mask()`.

`filename` : | set mask filename to this
`xsize` : | mask width
`ysize` : | mask height
Returns : | The newly-allocated mask.

### im_create_dmaskv ()

    DOUBLEMASK *        im_create_dmaskv                    (const char *filename,
                                                             int xsize,
                                                             int ysize,
                                                             ...);

Create a dmask and initialise it from the function parameter list.

See also: `im_create_dmask()`.

`filename` : | set mask filename to this
`xsize` : | mask width
`ysize` : | mask height
`...` : | values to set for the mask
Returns : | The newly-allocated mask.

### im_read_imask ()

    INTMASK *           im_read_imask                       (const char *filename);

Reads an integer matrix from a file.

This function works exactly as `im_read_dmask()`, but the loaded matrix is checked for 'int-ness'. All coefficients must be integers, and scale and offset must be integers.

See also: `im_read_dmask()`.

`filename` : | read matrix from this file
Returns : | the loaded mask on success, or NULL on error.

### im_read_dmask ()

    DOUBLEMASK *        im_read_dmask                       (const char *filename);

Reads a matrix from a file.

Matrix files have a simple format that's supposed to be easy to create with a text editor or a spreadsheet.

The first line has four numbers for width, height, scale and offset (scale and offset may be omitted, in which case they default to 1.0 and 0.0). Scale must be non-zero. Width and height must be positive integers. The numbers are separated by any mixture of spaces, commas, tabs and quotation marks ("). The scale and offset fields may be floating-point, and must use '.' as a decimal separator.

Subsequent lines each hold one line of matrix data, with numbers again separated by any mixture of spaces, commas, tabs and quotation marks ("). The numbers may be floating-point, and must use '.' as a decimal separator.

Extra characters at the ends of lines or at the end of the file are ignored.

See also: `im_read_imask()`, `im_gauss_dmask()`.

`filename` : | read matrix from this file
Returns : | the loaded mask on success, or NULL on error.

### im_print_imask ()

    void                im_print_imask                      (INTMASK *in);

Print an imask to stdout.

See also: `im_print_dmask()`.

`in` : | mask to print

### im_print_dmask ()

    void                im_print_dmask                      (DOUBLEMASK *in);

Print a dmask to stdout.

See also: `im_print_imask()`.

`in` : | mask to print

### im_write_imask ()

    int                 im_write_imask                      (INTMASK *in);

Write an imask to a file.

See also: `im_write_imask_name()`.

`in` : | mask to write
Returns : | 0 on success, or -1 on error.

### im_write_dmask ()

    int                 im_write_dmask                      (DOUBLEMASK *in);

Write a dmask to a file. See `im_read_dmask()` for a description of the mask file format.

See also: `im_write_dmask_name()`.

`in` : | mask to write
Returns : | 0 on success, or -1 on error.

### im_write_imask_name ()

    int                 im_write_imask_name                 (INTMASK *in,
                                                             const char *filename);

Write an imask to a file. See `im_read_dmask()` for a description of the mask file format.

See also: `im_write_imask()`.

`in` : | mask to write
`filename` : | filename to write to
Returns : | 0 on success, or -1 on error.

### im_write_dmask_name ()

    int                 im_write_dmask_name                 (DOUBLEMASK *in,
                                                             const char *filename);

Write a dmask to a file. See `im_read_dmask()` for a description of the mask file format.

See also: `im_write_dmask()`.

`in` : | mask to write
`filename` : | filename to write to
Returns : | 0 on success, or -1 on error.

### im_free_imask ()

    int                 im_free_imask                       (INTMASK *in);

Free mask structure and any attached arrays. Return zero, so we can use these functions as close callbacks.

See also: `im_free_dmask()`.

`in` : | mask to free
Returns : | zero.

### im_free_dmask ()

    int                 im_free_dmask                       (DOUBLEMASK *in);

Free mask structure and any attached arrays. Return zero, so we can use these functions as close callbacks.

See also: `im_free_dmask()`.

`in` : | mask to free
Returns : | zero.

### im_log_imask ()

    INTMASK *           im_log_imask                        (const char *filename,
                                                             double sigma,
                                                             double min_ampl);

`im_log_imask()` works exactly as `im_log_dmask()`, but the returned mask is scaled so that it's maximum value it set to 100.

See also: `im_log_dmask()`, `im_gauss_imask()`, `im_conv()`.

`filename` : | the returned mask has this set as the filename
`sigma` : | standard deviation of mask
`min_ampl` : | minimum amplitude
Returns : | the calculated mask on success, or NULL on error.

### im_log_dmask ()

    DOUBLEMASK *        im_log_dmask                        (const char *filename,
                                                             double sigma,
                                                             double min_ampl);

`im_log_dmask()` creates a circularly symmetric Laplacian of Gaussian mask of radius `sigma`. The size of the mask is determined by the variable `min_ampl`; if for instance the value .1 is entered this means that the produced mask is clipped at values within 10 persent of zero, and where the change between mask elements is less than 10%.

The program uses the following equation: (from Handbook of Pattern Recognition and image processing by Young and Fu, AP 1986 pages 220-221):

H(r) = (1 / (2 * M_PI * s4)) * (2 - (r2 / s2)) * exp(-r2 / (2 * s2))

where s2 = sigma * sigma, s4 = s2 * s2, r2 = r * r.

The generated mask has odd size and its maximum value is normalised to 1.0.

See also: `im_log_imask()`, `im_gauss_dmask()`, `im_conv()`.

`filename` : | the returned mask has this set as the filename
`sigma` : | standard deviation of mask
`min_ampl` : | minimum amplitude
Returns : | the calculated mask on success, or NULL on error.

### im_gauss_imask ()

    INTMASK *           im_gauss_imask                      (const char *filename,
                                                             double sigma,
                                                             double min_ampl);

`im_gauss_imask()` works exactly as `im_gauss_dmask()`, but the returned mask is scaled so that it's maximum value it set to 100.

See also: `im_gauss_dmask()`, `im_gauss_imask_sep()`, `im_conv()`, `im_convsep()`.

`filename` : | the returned mask has this set as the filename
`sigma` : | standard deviation of mask
`min_ampl` : | minimum amplitude
Returns : | the calculated mask on success, or NULL on error.

### im_gauss_imask_sep ()

    INTMASK *           im_gauss_imask_sep                  (const char *filename,
                                                             double sigma,
                                                             double min_ampl);

`im_gauss_imask_sep()` works exactly as `im_gauss_imask()`, but returns only the central line of the mask. This is useful with `im_convsep()`.

See also: `im_gauss_dmask()`, `im_convsep()`.

`filename` : | the returned mask has this set as the filename
`sigma` : | standard deviation of mask
`min_ampl` : | minimum amplitude
Returns : | the calculated mask on success, or NULL on error.

### im_gauss_dmask ()

    DOUBLEMASK *        im_gauss_dmask                      (const char *filename,
                                                             double sigma,
                                                             double min_ampl);

`im_gauss_dmask()` creates a circularly symmetric Gaussian mask of radius `sigma`. The size of the mask is determined by the variable `min_ampl`; if for instance the value .1 is entered this means that the produced mask is clipped at values less than 10 percent of the maximum amplitude.

The program uses the following equation:

H(r) = exp( -(r * r) / (2 * sigma * sigma) )

The generated mask has odd size and its maximum value is normalised to 1.0.

See also: `im_gauss_imask()`, `im_gauss_imask_sep()`, `im_log_dmask()`, `im_conv()`.

`filename` : | the returned mask has this set as the filename
`sigma` : | standard deviation of mask
`min_ampl` : | minimum amplitude
Returns : | the calculated mask on success, or NULL on error.

### im_gauss_dmask_sep ()

    DOUBLEMASK *        im_gauss_dmask_sep                  (const char *filename,
                                                             double sigma,
                                                             double min_ampl);

`im_gauss_dmask_sep()` works exactly as `im_gauss_dmask()`, but returns only the central line of the mask. This is useful with `im_convsepf()`.

See also: `im_gauss_dmask()`, `im_convsepf()`.

`filename` : | the returned mask has this set as the filename
`sigma` : | standard deviation of mask
`min_ampl` : | minimum amplitude
Returns : | the calculated mask on success, or NULL on error.

### im_dup_imask ()

    INTMASK *           im_dup_imask                        (INTMASK *in,
                                                             const char *filename);

Duplicate an imask.

See also: `im_dup_dmask()`.

`in` : | mask to duplicate
`filename` : | filename to set for the new mask
Returns : | the mask copy, or NULL on error.

### im_dup_dmask ()

    DOUBLEMASK *        im_dup_dmask                        (DOUBLEMASK *in,
                                                             const char *filename);

Duplicate a dmask.

See also: `im_dup_imask()`.

`in` : | mask to duplicate
`filename` : | filename to set for the new mask
Returns : | the mask copy, or NULL on error.

### im_scale_dmask ()

    INTMASK *           im_scale_dmask                      (DOUBLEMASK *in,
                                                             const char *filename);

Scale the dmask to make an imask with a maximum value of 20.

See also: `im_norm_dmask()`.

`in` : | mask to scale
`filename` : | filename for returned mask
Returns : | the converted mask, or NULL on error.

### im_norm_dmask ()

    void                im_norm_dmask                       (DOUBLEMASK *mask);

Normalise the dmask. Apply the scale and offset to each element to make a mask with scale 1, offset zero.

See also: `im_scale_dmask()`.

`mask` : | mask to scale
Returns : | 0 on success, or -1 on error.

### im_imask2dmask ()

    DOUBLEMASK *        im_imask2dmask                      (INTMASK *in,
                                                             const char *filename);

Make a dmask from the imask.

See also: `im_dmask2imask()`.

`in` : | mask to convert
`filename` : | filename for returned mask
Returns : | the converted mask, or NULL on error.

### im_dmask2imask ()

    INTMASK *           im_dmask2imask                      (DOUBLEMASK *in,
                                                             const char *filename);

Make an imask from the dmask, rounding to nearest.

See also: `im_scale_dmask()`.

`in` : | mask to convert
`filename` : | filename for returned mask
Returns : | the converted mask, or NULL on error.

### im_rotate_imask90 ()

    INTMASK *           im_rotate_imask90                   (INTMASK *in,
                                                             const char *filename);

Returns a mask which is the argument mask rotated by 90 degrees. Pass the filename to set for the output.

See also: `im_rotate_imask45()`.

`in` : | input matrix
`filename` : | name for output matrix
Returns : | the result matrix on success, or `NULL` on error.

### im_rotate_imask45 ()

    INTMASK *           im_rotate_imask45                   (INTMASK *in,
                                                             const char *filename);

Returns a mask which is the argument mask rotated by 45 degrees. Pass the filename to set for the output.

See also: `im_rotate_imask90()`.

`in` : | input matrix
`filename` : | name for output matrix
Returns : | the result matrix on success, or `NULL` on error.

### im_rotate_dmask90 ()

    DOUBLEMASK *        im_rotate_dmask90                   (DOUBLEMASK *in,
                                                             const char *filename);

Returns a mask which is the argument mask rotated by 90 degrees. Pass the filename to set for the output.

See also: `im_rotate_dmask45()`.

`in` : | input matrix
`filename` : | name for output matrix
Returns : | the result matrix on success, or `NULL` on error.

### im_rotate_dmask45 ()

    DOUBLEMASK *        im_rotate_dmask45                   (DOUBLEMASK *in,
                                                             const char *filename);

Returns a mask which is the argument mask rotated by 45 degrees. Pass the filename to set for the output.

See also: `im_rotate_dmask90()`.

`in` : | input matrix
`filename` : | name for output matrix
Returns : | the result matrix on success, or `NULL` on error.

### im_mattrn ()

    DOUBLEMASK *        im_mattrn                           (DOUBLEMASK *in,
                                                             const char *filename);

Transposes the input matrix. Pass the filename to set for the output.

See also: `im_matmul()`, `im_matinv()`.

`in` : | input matrix
`filename` : | name for output matrix
Returns : | the result matrix on success, or `NULL` on error.

### im_matcat ()

    DOUBLEMASK *        im_matcat                           (DOUBLEMASK *top,
                                                             DOUBLEMASK *bottom,
                                                             const char *filename);

Matrix catenations. Returns a new matrix which is the two source matrices joined together top-bottom. They must be the same width.

See also: `im_mattrn()`, `im_matmul()`, `im_matinv()`.

`top` : | input matrix
`bottom` : | input matrix
`filename` : | filename for output
Returns : | the joined mask on success, or NULL on error.

### im_matmul ()

    DOUBLEMASK *        im_matmul                           (DOUBLEMASK *in1,
                                                             DOUBLEMASK *in2,
                                                             const char *filename);

Multiplies two DOUBLEMASKs. Result matrix is made and returned. Pass the filename to set for the output.

The scale and offset members of `in1` and `in2` are ignored.

See also: `im_mattrn()`, `im_matinv()`.

`in1` : | input matrix
`in2` : | input matrix
`filename` : | name for output matrix
Returns : | the result matrix on success, or `NULL` on error.

### im_lu_decomp ()

    DOUBLEMASK *        im_lu_decomp                        (const DOUBLEMASK *mat,
                                                             const char *filename);

This function takes any square NxN DOUBLEMASK. It returns a DOUBLEMASK which is (N+1)xN.

It calculates the PLU decomposition, storing the upper and diagonal parts of U, together with the lower parts of L, as an NxN matrix in the first N rows of the new matrix. The diagonal parts of L are all set to unity and are not stored.

The final row of the new DOUBLEMASK has only integer entries, which represent the row-wise permutations made by the permuatation matrix P.

The scale and offset members of the input DOUBLEMASK are ignored.

See:

PRESS, W. et al, 1992. Numerical Recipies in C; The Art of Scientific Computing, 2nd ed. Cambridge: Cambridge University Press, pp. 43-50.

See also: `im_mattrn()`, `im_matinv()`.

`mat` : | matrix to decompose
`filename` : | name for output matrix
Returns : | the decomposed matrix on success, or NULL on error.

### im_lu_solve ()

    int                 im_lu_solve                         (const DOUBLEMASK *lu,
                                                             double *vec);

Solve the system of linear equations Ax=b, where matrix A has already been decomposed into LU form in DOUBLEMASK *lu. Input vector b is in vec and is overwritten with vector x.

See:

PRESS, W. et al, 1992. Numerical Recipies in C; The Art of Scientific Computing, 2nd ed. Cambridge: Cambridge University Press, pp. 43-50.

See also: `im_mattrn()`, `im_matinv()`.

`lu` : | matrix to solve
`vec` : | name for output matrix
Returns : | the decomposed matrix on success, or NULL on error.

### im_matinv ()

    DOUBLEMASK *        im_matinv                           (const DOUBLEMASK *mat,
                                                             const char *filename);

Allocate, and return a pointer to, a DOUBLEMASK representing the inverse of the matrix represented in `mat`. Give it the filename member `filename`. Returns NULL on error. Scale and offset are ignored.

See also: `im_mattrn()`.

`mat` : | matrix to invert
`filename` : | name for output matrix
Returns : | the inverted matrix on success, or `NULL` on error.

### im_matinv_inplace ()

    int                 im_matinv_inplace                   (DOUBLEMASK *mat);

Invert the matrix represented by the DOUBLEMASK `mat`, and store it in the place of `mat`. Scale and offset are ignored.

See also: `im_mattrn()`.

`mat` : | matrix to invert
Returns : | 0 on success, or -1 on error.

### im_local_dmask ()

    DOUBLEMASK *        im_local_dmask                      (struct _VipsImage *out,
                                                             DOUBLEMASK *mask);

`out` takes ownership of `mask`: when `out` is closed, `mask` will be closed for you. If `im_local_dmask()` itself fails, the mask is also freed.

See also: `im_local_imask()`.

`out` : | image to make the mask local to
`mask` : | mask to local-ize
Returns : | the mask, or NULL on error.

### im_local_imask ()

    INTMASK *           im_local_imask                      (struct _VipsImage *out,
                                                             INTMASK *mask);

`out` takes ownership of `mask`: when `out` is closed, `mask` will be closed for you. If `im_local_imask()` itself fails, the mask is also freed.

See also: `im_local_dmask()`.

`out` : | image to make the mask local to
`mask` : | mask to local-ize
Returns : | the mask, or NULL on error.