libvips/man/im_conv_raw.3

124 lines
3.5 KiB
Groff

.TH CONVOLUTION 3 "2 May 1991"
.SH NAME
im_conv, im_convf, im_convsep, im_convsepf,
im_convsub, im_shrink \- convolves an image with a generalised
mask
.SH SYNOPSIS
#include <vips/vips.h>
int im_conv(in, out, mask)
.br
IMAGE *in, *out;
.br
INTMASK *mask;
int im_convf(in, out, mask)
.br
IMAGE *in, *out;
.br
DOUBLEMASK *mask;
int im_convsep(in, out, mask)
.br
IMAGE *in, *out;
.br
INTMASK *mask;
int im_convsepf(in, out, mask)
.br
IMAGE *in, *out;
.br
DOUBLEMASK *mask;
int im_convsub(in, out, mask, xskip, yskip)
.br
IMAGE *in, *out;
.br
INTMASK *mask;
.br
int xskip, yskip;
int im_shrink(in, out, xfactor, yfactor)
.br
IMAGE *in, *out;
.br
double xfactor, yfactor;
.SH DESCRIPTION
These functions
convolve the image pointed by the image descriptor in with the file
pointed by mask and puts the result in the image pointed by out.
The mask structures INTMASK and DOUBLEMASK are
returned by the function im_read_imask(3) or im_read_dmask(3),
for integer and double masks respectively.
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 one of
the im_clip2*() functions.
If the sizes of the mask are xm and ym and the sizes of the image are xs and ys,
then there is a black border at the output image as follows:
The top ym/2 lines black, bottom ys-ym/2-ym lines black; each of the remaining
lines has the initial xm/2 pels blank, and the final
xs-xm/2-xm pels (division over 2 is integer division).
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_conv()
and
.B im_convsep()
have 'raw' versions which do not add the black border: instead the output
image is smaller than the input.
.B im_conv()
and
.B im_conv_raw()
convolve any non-complex input image to make an output image of the same
type. Rounding is appropriate to the image type.
.B im_convf()
convolves to float (double if the input is double).
The function expects a double mask.
.B im_convsep()
and
.B im_convsep_raw()
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.
.B im_convsepf()
convolves to float (double if the input is double).
The function expects a double mask.
.B im_convsub()
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.
.B im_shrink()
shrink the input image file by xfactor along the horizontal and
yfactor along the vertical direction. The function doesnot perform subpixel
interpolation and therefore the resultant image can present aliasing especially
for small x and y factors. Any size image, any non-complex type, any number of
bands.
.SH RETURN VALUE
The function returns 0 on success and -1 on error.
.SH SEE ALSO
im_read_imask(3), im_compass(3), im_fastcor(3).