NAME
im_conv, im_conv_raw, im_convf, im_convf_raw, im_convsep,
im_convsep_raw, im_convsepf, im_convsepf_raw, im_convsub - convolves
an image with a generalised mask
SYNOPSIS
#include <vips/vips.h>
int im_conv(in, out, mask)
IMAGE *in, *out;
INTMASK *mask;
int im_conv_raw(in, out, mask)
IMAGE *in, *out;
INTMASK *mask;
int im_convf(in, out, mask)
IMAGE *in, *out;
DOUBLEMASK *mask;
int im_convf_raw(in, out, mask)
IMAGE *in, *out;
DOUBLEMASK *mask;
int im_convsep(in, out, mask)
IMAGE *in, *out;
INTMASK *mask;
int im_convsep_raw(in, out, mask)
IMAGE *in, *out;
INTMASK *mask;
int im_convsepf(in, out, mask)
IMAGE *in, *out;
DOUBLEMASK *mask;
int im_convsepf_raw(in, out, mask)
IMAGE *in, *out;
DOUBLEMASK *mask;
int im_convsub(in, out, mask, xskip, yskip)
IMAGE *in, *out;
INTMASK *mask;
int xskip, yskip;
int im_shrink(in, out, xfactor, yfactor)
IMAGE *in, *out;
double xfactor, yfactor;
DESCRIPTION
These functions convolve the image in with the matrix mask and put the
result in the image out.
Input should be non-complex. The size and type of the output image are
the same as the size of the input. To output a larger type (for
example, to output an int image from convolution of a byte image,
avoiding clipping), cast the input image up with im_clip2fmt(3).
The output image is the same size as the input. The edge pixels are
calculated by expanding the input image using 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.
The im_conv*(3) functions have ’raw’ versions which do not add the
border: instead the output image is smaller than the input.
im_conv(3) and im_conv_raw(3) convolve any non-complex input image to
make an output image of the same type. Rounding is appropriate to the
image type.
im_convf(3) and im_convf_raw(3) convolves to float (double if the input
is double). The function expects a double mask.
im_convsep(3) and im_convsep_raw(3) carry out convolution using an 1xN
or Nx1 separable mask.
The function scales the output result by dividing it with scale*scale.
The scale factor should therefore be the sqrt of the scale of the
square NxN mask.
Rounding is appropriate to the image type. It works on any non-complex
image, and writes the output in the same format as the input. The
function expects integer mask.
im_convsepf(3) and im_convsepf_raw(3) convolves to float (double if the
input is double). The function expects a double mask.
im_convsub(3) convolves the byte image pointed by in and writes the
result as a byte output. Using this function the input image is
subsampled on both directions by an integer factor of xskip
horizontally and an integer factor of yskip vertically. During the
covolution, values are rounded before division. Both input and output
are bytes. Output is clipped between 0 and 255. The function expects
an integer mask.
RETURN VALUE
The functions returns 0 on success and -1 on error.
SEE ALSO
im_read_imask(3), im_compass(3), im_fastcor(3), im_log_dmask(3),
im_clip2fmt(3)
2 May 1991 CONVOLUTION(3)