1CONVOLUTION(3) Library Functions Manual CONVOLUTION(3)
2
6 im_conv, im_convf, im_convsep, im_convsepf, im_convsub, im_shrink -
7 convolves an image with a generalised mask
8
10 #include <vips/vips.h>
11 int im_conv(in, out, mask)
13 IMAGE *in, *out;
14 INTMASK *mask;
15 int im_convf(in, out, mask)
17 IMAGE *in, *out;
18 DOUBLEMASK *mask;
19 int im_convsep(in, out, mask)
21 IMAGE *in, *out;
22 INTMASK *mask;
23 int im_convsepf(in, out, mask)
25 IMAGE *in, *out;
26 DOUBLEMASK *mask;
27 int im_convsub(in, out, mask, xskip, yskip)
29 IMAGE *in, *out;
30 INTMASK *mask;
31 int xskip, yskip;
32 int im_shrink(in, out, xfactor, yfactor)
34 IMAGE *in, *out;
35 double xfactor, yfactor;
36
39 These functions convolve the image pointed by the image descriptor in
40 with the file pointed by mask and puts the result in the image pointed
41 by out. The mask structures INTMASK and DOUBLEMASK are returned by the
42 function im_read_imask(3) or im_read_dmask(3), for integer and double
43 masks respectively.
44 Input should be non-complex. The size and type of the output image are
46 the same as the size of the input. To output a larger type (for exam‐
47 ple, to output an int image from convolution of a byte image, avoiding
48 clipping), cast the input image up with one of the im_clip2*() func‐
49 tions.
50 If the sizes of the mask are xm and ym and the sizes of the image are
52 xs and ys, then there is a black border at the output image as follows:
53 The top ym/2 lines black, bottom ys-ym/2-ym lines black; each of the
55 remaining lines has the initial xm/2 pels blank, and the final xs-
56 xm/2-xm pels (division over 2 is integer division).
57 The output at each point is divided by scale and then the offset is
59 added. Both offset and scale are held in mask.
60 im_conv() and im_convsep() have 'raw' versions which do not add the
62 black border: instead the output image is smaller than the input.
63 im_conv() and im_conv_raw() convolve any non-complex input image to
65 make an output image of the same type. Rounding is appropriate to the
66 image type.
67 im_convf() convolves to float (double if the input is double). The
69 function expects a double mask.
70 im_convsep() and im_convsep_raw() carry out convolution using an 1xN or
72 Nx1 separable mask.
73 The function scales the output result by dividing it with scale*scale.
75 The scale factor should therefore be the sqrt of the scale of the
76 square NxN mask.
77 Rounding is appropriate to the image type. It works on any non-complex
79 image, and writes the output in the same format as the input. The
80 function expects integer mask.
81 im_convsepf() convolves to float (double if the input is double). The
83 function expects a double mask.
84 im_convsub() convolves the byte image pointed by in and writes the
86 result as a byte output. Using this function the input image is sub‐
87 sampled on both directions by an integer factor of xskip horizontally
88 and an integer factor of yskip vertically. During the covolution, val‐
89 ues are rounded before division. Both input and output are bytes.
90 Output is clipped between 0 and 255. The function expects an integer
91 mask.
92 im_shrink() shrink the input image file by xfactor along the horizontal
94 and yfactor along the vertical direction. The function doesnot perform
95 subpixel interpolation and therefore the resultant image can present
96 aliasing especially for small x and y factors. Any size image, any non-
97 complex type, any number of bands.
98
100 The function returns 0 on success and -1 on error.
101
103 im_read_imask(3), im_compass(3), im_fastcor(3).
104 2 May 1991 CONVOLUTION(3)