1CONVOLUTION(3) Library Functions Manual CONVOLUTION(3)
2
6 im_conv, im_conv_raw, im_convf, im_convf_raw, im_convsep, im_con‐
7 vsep_raw, im_convsepf, im_convsepf_raw, im_convsub, im_shrink - con‐
8 volves an image with a generalised mask
9
11 #include <vips/vips.h>
12 int im_conv(in, out, mask)
14 IMAGE *in, *out;
15 INTMASK *mask;
16 int im_conv_raw(in, out, mask)
18 IMAGE *in, *out;
19 INTMASK *mask;
20 int im_convf(in, out, mask)
22 IMAGE *in, *out;
23 DOUBLEMASK *mask;
24 int im_convf_raw(in, out, mask)
26 IMAGE *in, *out;
27 DOUBLEMASK *mask;
28 int im_convsep(in, out, mask)
30 IMAGE *in, *out;
31 INTMASK *mask;
32 int im_convsep_raw(in, out, mask)
34 IMAGE *in, *out;
35 INTMASK *mask;
36 int im_convsepf(in, out, mask)
38 IMAGE *in, *out;
39 DOUBLEMASK *mask;
40 int im_convsepf_raw(in, out, mask)
42 IMAGE *in, *out;
43 DOUBLEMASK *mask;
44 int im_convsub(in, out, mask, xskip, yskip)
46 IMAGE *in, *out;
47 INTMASK *mask;
48 int xskip, yskip;
49 int im_shrink(in, out, xfactor, yfactor)
51 IMAGE *in, *out;
52 double xfactor, yfactor;
53
56 These functions convolve the image in with the matrix mask and put the
57 result in the image out.
58 Input should be non-complex. The size and type of the output image are
60 the same as the size of the input. To output a larger type (for exam‐
61 ple, to output an int image from convolution of a byte image, avoiding
62 clipping), cast the input image up with im_clip2fmt().
63 If the sizes of the mask are xm and ym and the sizes of the image are
65 xs and ys, then there is a black border at the output image as follows:
66 The top ym/2 lines black, bottom ys-ym/2-ym lines black; each of the
68 remaining lines has the initial xm/2 pels blank, and the final xs-
69 xm/2-xm pels (division over 2 is integer division).
70 The output at each point is divided by scale and then the offset is
72 added. Both offset and scale are held in mask.
73 The im_conv*() functions have 'raw' versions which do not add the black
75 border: instead the output image is smaller than the input.
76 im_conv() and im_conv_raw() convolve any non-complex input image to
78 make an output image of the same type. Rounding is appropriate to the
79 image type.
80 im_convf() and im_convf_raw() convolves to float (double if the input
82 is double). The function expects a double mask.
83 im_convsep() and im_convsep_raw() carry out convolution using an 1xN or
85 Nx1 separable mask.
86 The function scales the output result by dividing it with scale*scale.
88 The scale factor should therefore be the sqrt of the scale of the
89 square NxN mask.
90 Rounding is appropriate to the image type. It works on any non-complex
92 image, and writes the output in the same format as the input. The
93 function expects integer mask.
94 im_convsepf() and im_convsepf_raw() convolves to float (double if the
96 input is double). The function expects a double mask.
97 im_convsub() convolves the byte image pointed by in and writes the
99 result as a byte output. Using this function the input image is sub‐
100 sampled on both directions by an integer factor of xskip horizontally
101 and an integer factor of yskip vertically. During the covolution, val‐
102 ues are rounded before division. Both input and output are bytes.
103 Output is clipped between 0 and 255. The function expects an integer
104 mask.
105 im_shrink() shrink the input image file by xfactor along the horizontal
107 and yfactor along the vertical direction. The function does not per‐
108 form subpixel interpolation and therefore the resultant image can
109 present aliasing especially for small x and y factors. Any size image,
110 any non-complex type, any number of bands.
111
113 The functions returns 0 on success and -1 on error.
114
116 im_read_imask(3), im_compass(3), im_fastcor(3), im_log_dmask(3),
117 im_clip2fmt(3)
118 2 May 1991 CONVOLUTION(3)