.TH IM_COMPASS 3 "2 May 1991"
.SH NAME
im_compass, im_rank_image, im_maxvalue, im_lindetect, im_gradient \- extract features from an image with
a rotating input mask
.SH SYNOPSIS
#include <vips/vips.h>

int im_rank_image(in, out, n, index)
.br
IMAGE **in;
.br
IMAGE *out;
.br
int n;
.br
int index;

int im_maxvalue(in, out, n)
.br
IMAGE **in;
.br
IMAGE *out;
.br
int n;

int im_compass(in, out, mask)
.br
IMAGE *in, *out;
.br
INTMASK *mask;

int im_lindetect(in, out, mask)
.br
IMAGE *in, *out;
.br
INTMASK *mask;

int im_gradient(in, out, mask)
.br
IMAGE *in, *out;
.br
INTMASK *mask;
.SH DESCRIPTION
.B im_rank_image()
sorts the input images pixel-wise, then outputs an image in which each pixel
is selected from the sorted list by the 
.B index
parameter. For example, if
.B index
is zero, then each output pixel will be the minimum of all the corresponding
input pixels. 
It works for any uncoded, non-complex
image type. All input images must match in size, format, and number of bands.

These functions convolve the image pointed by the image descriptor in with the
mask pointed by mask and put the result in the image pointed by out.

The mask structure INTMASK is returned by the function im_read_imask(3), for
integer mask only.  Input should be unsigned char; processing is carried out
using look-up tables. The output is integer.  coefficients.  The size of the
output image and the number of channels are the same as the corresponding of
the input.

The output image is the same size as the input. The edge pixels are calculated
by expanding the input image using
.B im_embed(3)
in mode 1 (replicating edge pixels) just enough so that the output can match
the input.

The output at each point is divided by scale and then the offset is added.
Both offset and scale are held in mask.

.B im_maxvalue()
is a convenience function: it is simply:

  im_rank_image( in, out, n, n - 1 )

.B im_compass()
convolves each point of the input byte image pointed by in with 8 masks. 
The first mask is the entered mask and the seven remaining masks are produced
by successive rotations of the entered mask by 45 degrees.  The maximum output
of all masks at each point is written to the output integer IMAGE descriptor.
The function expects as input a square mask of odd size.

.B im_lindetect()
convolves each point of the input byte image pointed by in with 4 masks. 
The first mask is the entered mask and the three remaining masks are produced
by successive rotations of the entered mask by 45 degrees.  The maximum output
of all masks at each point is written to the output integer IMAGE descriptor.
The function expects as input a square mask of odd size.

.B im_gradient()
convolves each point of the input byte image pointed by in with 2 masks;
the entered mask and with a 90 degrees rotation of the 
entered mask.  If g1, g2 are the result of each convolution then for each point
abs(g1) + abs(g2) is written to the output integer IMAGE descriptor.
The function expects as input a square mask of any size.
.SH RETURN VALUE
All functions returns 0 on success and -1 on error.
.SH SEE\ ALSO
im_readmask(3), im_conv(3).
.SH COPYRIGHT
.br
N. Dessipris
.SH AUTHOR
N. Dessipris \- 02/05/1991