1Imager::Filters(3) User Contributed Perl Documentation Imager::Filters(3)
2
6 Imager::Filters - Entire Image Filtering Operations
7
9 use Imager;
10 $img = ...;
12 $img->filter(type=>'autolevels');
14 $img->filter(type=>'autolevels', lsat=>0.2);
15 $img->filter(type=>'turbnoise')
16 # and lots of others
18 load_plugin("dynfilt/dyntest.so")
20 or die "unable to load plugin\n";
21 $img->filter(type=>'lin_stretch', a=>35, b=>200);
23 unload_plugin("dynfilt/dyntest.so")
25 or die "unable to load plugin\n";
26 $out = $img->difference(other=>$other_img);
28
30 Filters are operations that have similar calling interface.
31 filter
33 Parameters:
34 * type - the type of filter, see "Types of Filters".
36 * many other possible parameters, see "Types of Filters" below.
38 Types of Filters
40 Here is a list of the filters that are always avaliable in Imager.
42 This list can be obtained by running the "filterlist.perl" script that
43 comes with the module source.
44 Filter Arguments Default value
46 autolevels lsat 0.1
47 usat 0.1
48 skew 0
49 bumpmap bump lightx lighty
51 elevation 0
52 st 2
53 bumpmap_complex bump
55 channel 0
56 tx 0
57 ty 0
58 Lx 0.2
59 Ly 0.4
60 Lz -1
61 cd 1.0
62 cs 40.0
63 n 1.3
64 Ia (0 0 0)
65 Il (255 255 255)
66 Is (255 255 255)
67 contrast intensity
69 conv coef
71 fountain xa ya xb yb
73 ftype linear
74 repeat none
75 combine none
76 super_sample none
77 ssample_param 4
78 segments(see below)
79 gaussian stddev
81 gradgen xo yo colors
83 dist 0
84 hardinvert
86 mosaic size 20
88 noise amount 3
90 subtype 0
91 postlevels levels 10
93 radnoise xo 100
95 yo 100
96 ascale 17.0
97 rscale 0.02
98 turbnoise xo 0.0
100 yo 0.0
101 scale 10.0
102 unsharpmask stddev 2.0
104 scale 1.0
105 watermark wmark
107 pixdiff 10
108 tx 0
109 ty 0
110 All parameters must have some value but if a parameter has a default
112 value it may be omitted when calling the filter function.
113 Every one of these filters modifies the image in place.
115 If none of the filters here do what you need, the "tranform" in
117 Imager::Engines or "transform2" in Imager::Engines function may be use‐
118 ful.
119 A reference of the filters follows:
121 autolevels
123 scales the value of each channel so that the values in the image
124 will cover the whole possible range for the channel. lsat and usat
125 truncate the range by the specified fraction at the top and bottom
126 of the range respectivly.
127 # increase contrast per channel, losing little detail
129 $img->filter(type=>"autolevels")
130 or die $img->errstr;
131 # increase contrast, losing 20% of highlight at top and bottom range
133 $img->filter(type=>"autolevels", lsat=>0.2, usat=>0.2)
134 or die $img->errstr;
135 bumpmap
137 uses the channel elevation image bump as a bumpmap on your image,
138 with the light at (lightx, lightty), with a shadow length of st.
139 $img->filter(type=>"bumpmap", bump=>$bumpmap_img,
141 lightx=>10, lighty=>10, st=>5)
142 or die $img->errstr;
143 bumpmap_complex
145 uses the channel channel image bump as a bumpmap on your image. If
146 Lz<0 the three L parameters are considered to be the direction of
147 the light. If Lz>0 the L parameters are considered to be the light
148 position. Ia is the ambient colour, Il is the light colour, Is is
149 the color of specular highlights. cd is the diffuse coefficient
150 and cs is the specular coefficient. n is the shininess of the sur‐
151 face.
152 $img->filter(type=>"bumpmap_complex", bump=>$bumpmap_img)
154 or die $img->errstr;
155 contrast
157 scales each channel by intensity. Values of intensity < 1.0 will
158 reduce the contrast.
159 # higher contrast
161 $img->filter(type=>"contrast", intensity=>1.3)
162 or die $img->errstr;
163 # lower contrast
165 $img->filter(type=>"contrast", intensity=>0.8)
166 or die $img->errstr;
167 conv
169 performs 2 1-dimensional convolutions on the image using the values
170 from coef. coef should be have an odd length and the sum of the
171 coefficients must be non-zero.
172 # sharper
174 $img->filter(type=>"conv", coef=>[-0.5, 2, -0.5 ])
175 or die $img->errstr;
176 # blur
178 $img->filter(type=>"conv", coef=>[ 1, 2, 1 ])
179 or die $img->errstr;
180 fountain
182 renders a fountain fill, similar to the gradient tool in most paint
183 software. The default fill is a linear fill from opaque black to
184 opaque white. The points A(xa, ya) and B(xb, yb) control the way
185 the fill is performed, depending on the ftype parameter:
186 linear
188 the fill ramps from A through to B.
189 bilinear
191 the fill ramps in both directions from A, where AB defines the
192 length of the gradient.
193 radial
195 A is the center of a circle, and B is a point on it's circum‐
196 ference. The fill ramps from the center out to the circumfer‐
197 ence.
198 radial_square
200 A is the center of a square and B is the center of one of it's
201 sides. This can be used to rotate the square. The fill ramps
202 out to the edges of the square.
203 revolution
205 A is the centre of a circle and B is a point on it's circumfer‐
206 ence. B marks the 0 and 360 point on the circle, with the fill
207 ramping clockwise.
208 conical
210 A is the center of a circle and B is a point on it's circumfer‐
211 ence. B marks the 0 and point on the circle, with the fill
212 ramping in both directions to meet opposite.
213 The repeat option controls how the fill is repeated for some ftypes
215 after it leaves the AB range:
216 none
218 no repeats, points outside of each range are treated as if they
219 were on the extreme end of that range.
220 sawtooth
222 the fill simply repeats in the positive direction
223 triangle
225 the fill repeats in reverse and then forward and so on, in the
226 positive direction
227 saw_both
229 the fill repeats in both the positive and negative directions
230 (only meaningful for a linear fill).
231 tri_both
233 as for triangle, but in the negative direction too (only mean‐
234 ingful for a linear fill).
235 By default the fill simply overwrites the whole image (unless you
237 have parts of the range 0 through 1 that aren't covered by a seg‐
238 ment), if any segments of your fill have any transparency, you can
239 set the combine option to 'normal' to have the fill combined with
240 the existing pixels. See the description of combine in
241 Imager::Fill.
242 If your fill has sharp edges, for example between steps if you use
244 repeat set to 'triangle', you may see some aliased or ragged edges.
245 You can enable super-sampling which will take extra samples within
246 the pixel in an attempt anti-alias the fill.
247 The possible values for the super_sample option are:
249 none
251 no super-sampling is done
252 grid
254 a square grid of points are sampled. The number of points sam‐
255 pled is the square of ceil(0.5 + sqrt(ssample_param)).
256 random
258 a random set of points within the pixel are sampled. This
259 looks pretty bad for low ssample_param values.
260 circle
262 the points on the radius of a circle within the pixel are sam‐
263 pled. This seems to produce the best results, but is fairly
264 slow (for now).
265 You can control the level of sampling by setting the ssample_param
267 option. This is roughly the number of points sampled, but depends
268 on the type of sampling.
269 The segments option is an arrayref of segments. You really should
271 use the Imager::Fountain class to build your fountain fill. Each
272 segment is an array ref containing:
273 start
275 a floating point number between 0 and 1, the start of the range
276 of fill parameters covered by this segment.
277 middle
279 a floating point number between start and end which can be used
280 to push the color range towards one end of the segment.
281 end a floating point number between 0 and 1, the end of the range
283 of fill parameters covered by this segment. This should be
284 greater than start.
285 c0
287 c1 The colors at each end of the segment. These can be either
288 Imager::Color or Imager::Color::Float objects.
289 segment type
291 The type of segment, this controls the way the fill parameter
292 varies over the segment. 0 for linear, 1 for curved (unimple‐
293 mented), 2 for sine, 3 for sphere increasing, 4 for sphere
294 decreasing.
295 color type
297 The way the color varies within the segment, 0 for simple RGB,
298 1 for hue increasing and 2 for hue decreasing.
299 Don't forget to use Imager::Fountain instead of building your own.
301 Really. It even loads GIMP gradient files.
302 # build the gradient the hard way - linear from black to white,
304 # then back again
305 my @simple =
306 (
307 [ 0, 0.25, 0.5, 'black', 'white', 0, 0 ],
308 [ 0.5. 0.75, 1.0, 'white', 'black', 0, 0 ],
309 );
310 # across
311 my $linear = $img->copy;
312 $linear->filter(type => "fountain",
313 ftype => 'linear',
314 repeat => 'sawtooth',
315 segments => \@simple,
316 xa => 0,
317 ya => $linear->getheight / 2,
318 xb => $linear->getwidth - 1,
319 yb => $linear->getheight / 2)
320 or die $linear->errstr;
321 # around
322 my $revolution = $img->copy;
323 $revolution->filter(type => "fountain",
324 ftype => 'revolution',
325 segments => \@simple,
326 xa => $revolution->getwidth / 2,
327 ya => $revolution->getheight / 2,
328 xb => $revolution->getwidth / 2,
329 yb => 0)
330 or die $revolution->errstr;
331 # out from the middle
332 my $radial = $img->copy;
333 $radial->filter(type => "fountain",
334 ftype => 'radial',
335 segments => \@simple,
336 xa => $im->getwidth / 2,
337 ya => $im->getheight / 2,
338 xb => $im->getwidth / 2,
339 yb => 0)
340 or die $radial->errstr;
341 gaussian
343 performs a gaussian blur of the image, using stddev as the standard
344 deviation of the curve used to combine pixels, larger values give
345 bigger blurs. For a definition of Gaussian Blur, see:
346 http://www.maths.abdn.ac.uk/~igc/tch/mx4002/notes/node99.html
348 Values of "stddev" around 0.5 provide a barely noticable blur, val‐
350 ues around 5 provide a very strong blur.
351 # only slightly blurred
353 $img->filter(type=>"gaussian", stddev=>0.5)
354 or die $img->errstr;
355 # more strongly blurred
357 $img->filter(type=>"gaussian", stddev=>5)
358 or die $img->errstr;
359 gradgen
361 renders a gradient, with the given colors at the corresponding
362 points (x,y) in xo and yo. You can specify the way distance is
363 measured for color blending by setting dist to 0 for Euclidean, 1
364 for Euclidean squared, and 2 for Manhattan distance.
365 $img->filter(type="gradgen",
367 xo=>[ 10, 50, 10 ],
368 yo=>[ 10, 50, 50 ],
369 colors=>[ qw(red blue green) ]);
370 hardinvert
372 inverts the image, black to white, white to black. All channels
373 are inverted, including the alpha channel if any.
374 $img->filter(type=>"hardinvert")
376 or die $img->errstr;
377 mosaic
379 produces averaged tiles of the given size.
380 $img->filter(type=>"mosaic", size=>5)
382 or die $img->errstr;
383 noise
385 adds noise of the given amount to the image. If subtype is zero,
386 the noise is even to each channel, otherwise noise is added to each
387 channel independently.
388 # monochrome noise
390 $img->filter(type=>"noise", amount=>20, subtype=>0)
391 or die $img->errstr;
392 # color noise
394 $img->filter(type=>"noise", amount=>20, subtype=>1)
395 or die $img->errstr;
396 radnoise
398 renders radiant Perlin turbulent noise. The centre of the noise is
399 at (xo, yo), ascale controls the angular scale of the noise , and
400 rscale the radial scale, higher numbers give more detail.
401 $img->filter(type=>"radnoise", xo=>50, yo=>50,
403 ascale=>1, rscale=>0.02)
404 or die $img->errstr;
405 postlevels
407 alters the image to have only levels distinct level in each chan‐
408 nel.
409 $img->filter(type=>"postlevels", levels=>10)
411 or die $img->errstr;
412 turbnoise
414 renders Perlin turbulent noise. (xo, yo) controls the origin of
415 the noise, and scale the scale of the noise, with lower numbers
416 giving more detail.
417 $img->filter(type=>"turbnoise", xo=>10, yo=>10, scale=>10)
419 or die $img->errstr;
420 unsharpmask
422 performs an unsharp mask on the image. This increases the contrast
423 of edges in the image.
424 This is the result of subtracting a gaussian blurred version of the
426 image from the original. stddev controls the stddev parameter of
427 the gaussian blur. Each output pixel is: in + scale * (in -
428 blurred).
429 $img->filter(type=>"unsharpmask", stddev=>1, scale=>0.5)
431 or die $img->errstr;
432 unsharpmark has the following parameters:
434 * stddev - this is equivalent to the "Radius" value in the GIMP's
436 unsharpmask filter. This controls the size of the contrast
437 increase around edges, larger values will remove fine detail.
438 You should probably experiement on the types of images you plan
439 to work with. Default: 2.0.
440 * scale - controls the strength of the edge enhancement, equiva‐
442 lent to Amount in the GIMP's unsharp mask filter. Default:
443 1.0.
444 watermark
446 applies wmark as a watermark on the image with strength pixdiff,
447 with an origin at (tx, ty)
448 $img->filter(type=>"watermark", tx=>10, ty=>50,
450 wmark=>$wmark_image, pixdiff=>50)
451 or die $img->errstr;
452 A demonstration of most of the filters can be found at:
454 http://www.develop-help.com/imager/filters.html
456 External Filters
458 As of Imager 0.48 you can create perl or XS based filters and hook them
460 into Imager's filter() method:
461 register_filter
463 Registers a filter so it is visible via Imager's filter() method.
464 Imager->register_filter(type => 'your_filter',
466 defaults => { parm1 => 'default1' },
467 callseq => [ qw/image parm1/ ],
468 callsub => \&your_filter);
469 $img->filter(type=>'your_filter', parm1 => 'something');
470 The following parameters are needed:
472 * type - the type value that will be supplied to filter() to use
474 your filter.
475 * defaults - a hash of defaults for the filter's parameters
477 * callseq - a reference to an array of required parameter names.
479 * callsub - a code reference called to execute your filter. The
481 parameters passed to filter() are supplied as a list of parame‐
482 ter name, value ... which can be assigned to a hash.
483 The special parameters "image" and "imager" are supplied as the
485 low level image object from $self and $self itself respec‐
486 tively.
487 The function you supply must modify the image in place.
489 See Imager::Filter::Mandelbrot for an example.
491 Plugins
493 The plugin interface is deprecated. Please use the Imager API, see
495 "Imager::API" and "External Filters" for details
496 It is possible to add filters to the module without recompiling the
498 module itself. This is done by using DSOs (Dynamic shared object)
499 avaliable on most systems. This way you can maintain our own filters
500 and not have to get me to add it, or worse patch every new version of
501 the Module. Modules can be loaded AND UNLOADED at runtime. This means
502 that you can have a server/daemon thingy that can do something like:
503 load_plugin("dynfilt/dyntest.so")
505 or die "unable to load plugin\n";
506 $img->filter(type=>'lin_stretch', a=>35, b=>200);
508 unload_plugin("dynfilt/dyntest.so")
510 or die "unable to load plugin\n";
511 Someone decides that the filter is not working as it should - dyntest.c
513 modified and recompiled.
514 load_plugin("dynfilt/dyntest.so")
516 or die "unable to load plugin\n";
517 $img->filter(%hsh);
519 An example plugin comes with the module - Please send feedback to
521 addi@umich.edu if you test this.
522 Note: This seems to test ok on the following systems: Linux, Solaris,
524 HPUX, OpenBSD, FreeBSD, TRU64/OSF1, AIX. If you test this on other
525 systems please let me know.
526 load_plugin
528 This is a function, not a method, exported by default. You should
529 import this function explicitly for future compatibility if you
530 need it.
531 Accepts a single parameter, the name of a shared library file to
533 load.
534 Returns true on success. Check Imager->errstr on failure.
536 unload_plugin
538 This is a function, not a method, which is exported by default.
539 You should import this function explicitly for future compatibility
540 if you need it.
541 Accepts a single parameter, the name of a shared library to unload.
543 This library must have been previously loaded by load_plugin().
544 Returns true on success. Check Imager->errstr on failure.
546 Image Difference
548 difference
550 You can create a new image that is the difference between 2 other
551 images.
552 my $diff = $img->difference(other=>$other_img);
554 For each pixel in $img that is different to the pixel in
556 $other_img, the pixel from $other_img is given, otherwise the pixel
557 is transparent black.
558 This can be used for debugging image differences ("Where are they
560 different?"), and for optimizing animated GIFs.
561 Note that $img and $other_img must have the same number of chan‐
563 nels. The width and height of $diff will be the minimum of each of
564 the width and height of $img and $other_img.
565 Parameters:
567 * other - the other image object to compare against
569 * mindist - the difference between corresponding samples must be
571 greater than mindist for the pixel to be considered different.
572 So a value of zero returns all different pixels, not all pix‐
573 els. Range: 0 to 255 inclusive. Default: 0.
574 For large sample images this is scaled down to the range 0 ..
576 1.
577
579 Arnar M. Hrafnkelsson, Tony Cook <tony@imager.perl.org>.
580
582 Imager, Imager::Filter::Flines, Imager::Filter::Mandelbrot
583
585 $Revision: 1330 $
586perl v5.8.8 2008-03-28 Imager::Filters(3)