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.