![]() |
![]() |
![]() |
VIPS Reference Manual | ![]() |
---|---|---|---|---|
Top | Description |
#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
);
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.
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
.
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
.
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()
.
|
set mask filename to this |
|
mask width |
|
mask height |
Returns : |
The newly-allocated mask. |
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()
.
|
set mask filename to this |
|
mask width |
|
mask height |
|
values to set for the mask |
Returns : |
The newly-allocated mask. |
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()
.
|
set mask filename to this |
|
mask width |
|
mask height |
Returns : |
The newly-allocated mask. |
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()
.
|
set mask filename to this |
|
mask width |
|
mask height |
|
values to set for the mask |
Returns : |
The newly-allocated mask. |
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()
.
|
read matrix from this file |
Returns : |
the loaded mask on success, or NULL on error. |
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()
.
|
read matrix from this file |
Returns : |
the loaded mask on success, or NULL on error. |
void im_print_imask (INTMASK *in
);
Print an imask to stdout.
See also: im_print_dmask()
.
|
mask to print |
void im_print_dmask (DOUBLEMASK *in
);
Print a dmask to stdout.
See also: im_print_imask()
.
|
mask to print |
int im_write_imask (INTMASK *in
);
Write an imask to a file.
See also: im_write_imask_name()
.
|
mask to write |
Returns : |
0 on success, or -1 on error. |
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()
.
|
mask to write |
Returns : |
0 on success, or -1 on error. |
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()
.
|
mask to write |
|
filename to write to |
Returns : |
0 on success, or -1 on error. |
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()
.
|
mask to write |
|
filename to write to |
Returns : |
0 on success, or -1 on error. |
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()
.
|
mask to free |
Returns : |
zero. |
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()
.
|
mask to free |
Returns : |
zero. |
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()
.
|
the returned mask has this set as the filename |
|
standard deviation of mask |
|
minimum amplitude |
Returns : |
the calculated mask on success, or NULL on error. |
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()
.
|
the returned mask has this set as the filename |
|
standard deviation of mask |
|
minimum amplitude |
Returns : |
the calculated mask on success, or NULL on error. |
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()
.
|
the returned mask has this set as the filename |
|
standard deviation of mask |
|
minimum amplitude |
Returns : |
the calculated mask on success, or NULL on error. |
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()
.
|
the returned mask has this set as the filename |
|
standard deviation of mask |
|
minimum amplitude |
Returns : |
the calculated mask on success, or NULL on error. |
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()
.
|
the returned mask has this set as the filename |
|
standard deviation of mask |
|
minimum amplitude |
Returns : |
the calculated mask on success, or NULL on error. |
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()
.
|
the returned mask has this set as the filename |
|
standard deviation of mask |
|
minimum amplitude |
Returns : |
the calculated mask on success, or NULL on error. |
INTMASK * im_dup_imask (INTMASK *in
,const char *filename
);
Duplicate an imask.
See also: im_dup_dmask()
.
|
mask to duplicate |
|
filename to set for the new mask |
Returns : |
the mask copy, or NULL on error. |
DOUBLEMASK * im_dup_dmask (DOUBLEMASK *in
,const char *filename
);
Duplicate a dmask.
See also: im_dup_imask()
.
|
mask to duplicate |
|
filename to set for the new mask |
Returns : |
the mask copy, or NULL on error. |
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()
.
|
mask to scale |
|
filename for returned mask |
Returns : |
the converted mask, or NULL on error. |
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 to scale |
Returns : |
0 on success, or -1 on error. |
DOUBLEMASK * im_imask2dmask (INTMASK *in
,const char *filename
);
Make a dmask from the imask.
See also: im_dmask2imask()
.
|
mask to convert |
|
filename for returned mask |
Returns : |
the converted mask, or NULL on error. |
INTMASK * im_dmask2imask (DOUBLEMASK *in
,const char *filename
);
Make an imask from the dmask, rounding to nearest.
See also: im_scale_dmask()
.
|
mask to convert |
|
filename for returned mask |
Returns : |
the converted mask, or NULL on error. |
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()
.
|
input matrix |
|
name for output matrix |
Returns : |
the result matrix on success, or NULL on error. |
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()
.
|
input matrix |
|
name for output matrix |
Returns : |
the result matrix on success, or NULL on error. |
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()
.
|
input matrix |
|
name for output matrix |
Returns : |
the result matrix on success, or NULL on error. |
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()
.
|
input matrix |
|
name for output matrix |
Returns : |
the result matrix on success, or NULL on error. |
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()
.
|
input matrix |
|
name for output matrix |
Returns : |
the result matrix on success, or NULL on error. |
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()
.
|
input matrix |
|
input matrix |
|
filename for output |
Returns : |
the joined mask on success, or NULL on error. |
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()
.
|
input matrix |
|
input matrix |
|
name for output matrix |
Returns : |
the result matrix on success, or NULL on error. |
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()
.
|
matrix to decompose |
|
name for output matrix |
Returns : |
the decomposed matrix on success, or NULL on error. |
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()
.
|
matrix to solve |
|
name for output matrix |
Returns : |
the decomposed matrix on success, or NULL on error. |
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()
.
|
matrix to invert |
|
name for output matrix |
Returns : |
the inverted matrix on success, or NULL on error. |
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()
.
|
matrix to invert |
Returns : |
0 on success, or -1 on error. |
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()
.
|
image to make the mask local to |
|
mask to local-ize |
Returns : |
the mask, or NULL on error. |
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()
.
|
image to make the mask local to |
|
mask to local-ize |
Returns : |
the mask, or NULL on error. |