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 available in Imager.
41 This list can be obtained by running the "filterlist.perl" script that
42 comes with the module source.
43 Filter Arguments Default value
45 autolevels lsat 0.1
46 usat 0.1
47 skew 0
48 bumpmap bump lightx lighty
50 elevation 0
51 st 2
52 bumpmap_complex bump
54 channel 0
55 tx 0
56 ty 0
57 Lx 0.2
58 Ly 0.4
59 Lz -1
60 cd 1.0
61 cs 40.0
62 n 1.3
63 Ia (0 0 0)
64 Il (255 255 255)
65 Is (255 255 255)
66 contrast intensity
68 conv coef
70 fountain xa ya xb yb
72 ftype linear
73 repeat none
74 combine none
75 super_sample none
76 ssample_param 4
77 segments(see below)
78 gaussian stddev
80 gradgen xo yo colors
82 dist 0
83 hardinvert
85 hardinvertall
87 mosaic size 20
89 noise amount 3
91 subtype 0
92 postlevels levels 10
94 radnoise xo 100
96 yo 100
97 ascale 17.0
98 rscale 0.02
99 turbnoise xo 0.0
101 yo 0.0
102 scale 10.0
103 unsharpmask stddev 2.0
105 scale 1.0
106 watermark wmark
108 pixdiff 10
109 tx 0
110 ty 0
111 All parameters must have some value but if a parameter has a default
113 value it may be omitted when calling the filter function.
114 Every one of these filters modifies the image in place.
116 If none of the filters here do what you need, the "transform()" in
118 Imager::Engines or "transform2()" in Imager::Engines function may be
119 useful.
120 A reference of the filters follows:
122 autolevels
124 scales the value of each channel so that the values in the image
125 will cover the whole possible range for the channel. "lsat" and
126 "usat" truncate the range by the specified fraction at the top and
127 bottom of the range respectively.
128 # increase contrast per channel, losing little detail
130 $img->filter(type=>"autolevels")
131 or die $img->errstr;
132 # increase contrast, losing 20% of highlight at top and bottom range
134 $img->filter(type=>"autolevels", lsat=>0.2, usat=>0.2)
135 or die $img->errstr;
136 bumpmap
138 uses the channel "elevation" image "bump" as a bump map on your
139 image, with the light at ("lightx", "lightty"), with a shadow
140 length of "st".
141 $img->filter(type=>"bumpmap", bump=>$bumpmap_img,
143 lightx=>10, lighty=>10, st=>5)
144 or die $img->errstr;
145 bumpmap_complex
147 uses the channel "channel" image "bump" as a bump map on your
148 image. If "Lz < 0" the three L parameters are considered to be the
149 direction of the light. If "Lz > 0" the L parameters are
150 considered to be the light position. "Ia" is the ambient color,
151 "Il" is the light color, "Is" is the color of specular highlights.
152 "cd" is the diffuse coefficient and "cs" is the specular
153 coefficient. "n" is the shininess of the surface.
154 $img->filter(type=>"bumpmap_complex", bump=>$bumpmap_img)
156 or die $img->errstr;
157 contrast
159 scales each channel by "intensity". Values of "intensity" < 1.0
160 will reduce the contrast.
161 # higher contrast
163 $img->filter(type=>"contrast", intensity=>1.3)
164 or die $img->errstr;
165 # lower contrast
167 $img->filter(type=>"contrast", intensity=>0.8)
168 or die $img->errstr;
169 conv
171 performs 2 1-dimensional convolutions on the image using the values
172 from "coef". "coef" should be have an odd length and the sum of
173 the coefficients must be non-zero.
174 # sharper
176 $img->filter(type=>"conv", coef=>[-0.5, 2, -0.5 ])
177 or die $img->errstr;
178 # blur
180 $img->filter(type=>"conv", coef=>[ 1, 2, 1 ])
181 or die $img->errstr;
182 # error
184 $img->filter(type=>"conv", coef=>[ -0.5, 1, -0.5 ])
185 or die $img->errstr;
186 fountain
188 renders a fountain fill, similar to the gradient tool in most paint
189 software. The default fill is a linear fill from opaque black to
190 opaque white. The points "A(Cxa, ya)" and "B(xb, yb)" control the
191 way the fill is performed, depending on the "ftype" parameter:
192 "linear"
194 the fill ramps from A through to B.
195 "bilinear"
197 the fill ramps in both directions from A, where AB defines the
198 length of the gradient.
199 "radial"
201 A is the center of a circle, and B is a point on it's
202 circumference. The fill ramps from the center out to the
203 circumference.
204 "radial_square"
206 A is the center of a square and B is the center of one of it's
207 sides. This can be used to rotate the square. The fill ramps
208 out to the edges of the square.
209 "revolution"
211 A is the center of a circle and B is a point on its
212 circumference. B marks the 0 and 360 point on the circle, with
213 the fill ramping clockwise.
214 "conical"
216 A is the center of a circle and B is a point on it's
217 circumference. B marks the 0 and point on the circle, with the
218 fill ramping in both directions to meet opposite.
219 The "repeat" option controls how the fill is repeated for some
221 "ftype"s after it leaves the AB range:
222 "none"
224 no repeats, points outside of each range are treated as if they
225 were on the extreme end of that range.
226 "sawtooth"
228 the fill simply repeats in the positive direction
229 "triangle"
231 the fill repeats in reverse and then forward and so on, in the
232 positive direction
233 "saw_both"
235 the fill repeats in both the positive and negative directions
236 (only meaningful for a linear fill).
237 "tri_both"
239 as for triangle, but in the negative direction too (only
240 meaningful for a linear fill).
241 By default the fill simply overwrites the whole image (unless you
243 have parts of the range 0 through 1 that aren't covered by a
244 segment), if any segments of your fill have any transparency, you
245 can set the combine option to 'normal' to have the fill combined
246 with the existing pixels. See the description of combine in
247 Imager::Fill.
248 If your fill has sharp edges, for example between steps if you use
250 repeat set to 'triangle', you may see some aliased or ragged edges.
251 You can enable super-sampling which will take extra samples within
252 the pixel in an attempt anti-alias the fill.
253 The possible values for the super_sample option are:
255 none
257 no super-sampling is done
258 grid
260 a square grid of points are sampled. The number of points
261 sampled is the square of ceil(0.5 + sqrt(ssample_param)).
262 random
264 a random set of points within the pixel are sampled. This
265 looks pretty bad for low ssample_param values.
266 circle
268 the points on the radius of a circle within the pixel are
269 sampled. This seems to produce the best results, but is fairly
270 slow (for now).
271 You can control the level of sampling by setting the ssample_param
273 option. This is roughly the number of points sampled, but depends
274 on the type of sampling.
275 The segments option is an arrayref of segments. You really should
277 use the Imager::Fountain class to build your fountain fill. Each
278 segment is an array ref containing:
279 start
281 a floating point number between 0 and 1, the start of the range
282 of fill parameters covered by this segment.
283 middle
285 a floating point number between start and end which can be used
286 to push the color range towards one end of the segment.
287 end a floating point number between 0 and 1, the end of the range
289 of fill parameters covered by this segment. This should be
290 greater than start.
291 c0
293 c1 The colors at each end of the segment. These can be either
294 Imager::Color or Imager::Color::Float objects.
295 segment type
297 The type of segment, this controls the way the fill parameter
298 varies over the segment. 0 for linear, 1 for curved
299 (unimplemented), 2 for sine, 3 for sphere increasing, 4 for
300 sphere decreasing.
301 color type
303 The way the color varies within the segment, 0 for simple RGB,
304 1 for hue increasing and 2 for hue decreasing.
305 Don't forget to use Imager::Fountain instead of building your own.
307 Really. It even loads GIMP gradient files.
308 # build the gradient the hard way - linear from black to white,
310 # then back again
311 my @simple =
312 (
313 [ 0, 0.25, 0.5, 'black', 'white', 0, 0 ],
314 [ 0.5. 0.75, 1.0, 'white', 'black', 0, 0 ],
315 );
316 # across
317 my $linear = $img->copy;
318 $linear->filter(type => "fountain",
319 ftype => 'linear',
320 repeat => 'sawtooth',
321 segments => \@simple,
322 xa => 0,
323 ya => $linear->getheight / 2,
324 xb => $linear->getwidth - 1,
325 yb => $linear->getheight / 2)
326 or die $linear->errstr;
327 # around
328 my $revolution = $img->copy;
329 $revolution->filter(type => "fountain",
330 ftype => 'revolution',
331 segments => \@simple,
332 xa => $revolution->getwidth / 2,
333 ya => $revolution->getheight / 2,
334 xb => $revolution->getwidth / 2,
335 yb => 0)
336 or die $revolution->errstr;
337 # out from the middle
338 my $radial = $img->copy;
339 $radial->filter(type => "fountain",
340 ftype => 'radial',
341 segments => \@simple,
342 xa => $im->getwidth / 2,
343 ya => $im->getheight / 2,
344 xb => $im->getwidth / 2,
345 yb => 0)
346 or die $radial->errstr;
347 gaussian
349 performs a Gaussian blur of the image, using "stddev" as the
350 standard deviation of the curve used to combine pixels, larger
351 values give bigger blurs. For a definition of Gaussian Blur, see:
352 http://www.maths.abdn.ac.uk/~igc/tch/mx4002/notes/node99.html
354 Values of "stddev" around 0.5 provide a barely noticeable blur,
356 values around 5 provide a very strong blur.
357 # only slightly blurred
359 $img->filter(type=>"gaussian", stddev=>0.5)
360 or die $img->errstr;
361 # more strongly blurred
363 $img->filter(type=>"gaussian", stddev=>5)
364 or die $img->errstr;
365 gradgen
367 renders a gradient, with the given colors at the corresponding
368 points (x,y) in "xo" and "yo". You can specify the way distance is
369 measured for color blending by setting "dist" to 0 for Euclidean, 1
370 for Euclidean squared, and 2 for Manhattan distance.
371 $img->filter(type="gradgen",
373 xo=>[ 10, 50, 10 ],
374 yo=>[ 10, 50, 50 ],
375 colors=>[ qw(red blue green) ]);
376 hardinvert
378 inverts the image, black to white, white to black. All color
379 channels are inverted, excluding the alpha channel if any.
380 $img->filter(type=>"hardinvert")
382 or die $img->errstr;
383 hardinvertall
385 inverts the image, black to white, white to black. All channels
386 are inverted, including the alpha channel if any.
387 $img->filter(type=>"hardinvertall")
389 or die $img->errstr;
390 mosaic
392 produces averaged tiles of the given "size".
393 $img->filter(type=>"mosaic", size=>5)
395 or die $img->errstr;
396 noise
398 adds noise of the given "amount" to the image. If "subtype" is
399 zero, the noise is even to each channel, otherwise noise is added
400 to each channel independently.
401 # monochrome noise
403 $img->filter(type=>"noise", amount=>20, subtype=>0)
404 or die $img->errstr;
405 # color noise
407 $img->filter(type=>"noise", amount=>20, subtype=>1)
408 or die $img->errstr;
409 radnoise
411 renders radiant Perlin turbulent noise. The center of the noise is
412 at ("xo", "yo"), "ascale" controls the angular scale of the noise ,
413 and "rscale" the radial scale, higher numbers give more detail.
414 $img->filter(type=>"radnoise", xo=>50, yo=>50,
416 ascale=>1, rscale=>0.02)
417 or die $img->errstr;
418 postlevels
420 alters the image to have only "levels" distinct level in each
421 channel.
422 $img->filter(type=>"postlevels", levels=>10)
424 or die $img->errstr;
425 turbnoise
427 renders Perlin turbulent noise. ("xo", "yo") controls the origin
428 of the noise, and "scale" the scale of the noise, with lower
429 numbers giving more detail.
430 $img->filter(type=>"turbnoise", xo=>10, yo=>10, scale=>10)
432 or die $img->errstr;
433 unsharpmask
435 performs an unsharp mask on the image. This increases the contrast
436 of edges in the image.
437 This is the result of subtracting a Gaussian blurred version of the
439 image from the original. "stddev" controls the "stddev" parameter
440 of the Gaussian blur. Each output pixel is:
441 in + scale * (in - blurred)
443 eg.
445 $img->filter(type=>"unsharpmask", stddev=>1, scale=>0.5)
447 or die $img->errstr;
448 "unsharpmark" has the following parameters:
450 · "stddev" - this is equivalent to the "Radius" value in the
452 GIMP's unsharp mask filter. This controls the size of the
453 contrast increase around edges, larger values will remove fine
454 detail. You should probably experiment on the types of images
455 you plan to work with. Default: 2.0.
456 · "scale" - controls the strength of the edge enhancement,
458 equivalent to Amount in the GIMP's unsharp mask filter.
459 Default: 1.0.
460 watermark
462 applies "wmark" as a watermark on the image with strength
463 "pixdiff", with an origin at ("tx", "ty")
464 $img->filter(type=>"watermark", tx=>10, ty=>50,
466 wmark=>$wmark_image, pixdiff=>50)
467 or die $img->errstr;
468 A demonstration of most of the filters can be found at:
470 http://www.develop-help.com/imager/filters.html
472 External Filters
474 As of Imager 0.48 you can create perl or XS based filters and hook them
475 into Imager's filter() method:
476 register_filter()
478 Registers a filter so it is visible via Imager's filter() method.
479 Imager->register_filter(type => 'your_filter',
481 defaults => { parm1 => 'default1' },
482 callseq => [ qw/image parm1/ ],
483 callsub => \&your_filter);
484 $img->filter(type=>'your_filter', parm1 => 'something');
485 The following parameters are needed:
487 · "type" - the type value that will be supplied to filter() to
489 use your filter.
490 · "defaults" - a hash of defaults for the filter's parameters
492 · "callseq" - a reference to an array of required parameter
494 names.
495 · "callsub" - a code reference called to execute your filter.
497 The parameters passed to filter() are supplied as a list of
498 parameter name, value ... which can be assigned to a hash.
499 The special parameters "image" and "imager" are supplied as the
501 low level image object from $self and $self itself
502 respectively.
503 The function you supply must modify the image in place.
505 See Imager::Filter::Mandelbrot for an example.
507 Plug-ins
509 The plug in interface is deprecated. Please use the Imager API, see
510 Imager::API and "External Filters" for details
511 It is possible to add filters to the module without recompiling Imager
513 itself. This is done by using DSOs (Dynamic shared object) available
514 on most systems. This way you can maintain your own filters and not
515 have to have it added to Imager, or worse patch every new version of
516 Imager. Modules can be loaded AND UNLOADED at run time. This means
517 that you can have a server/daemon thingy that can do something like:
518 load_plugin("dynfilt/dyntest.so")
520 or die "unable to load plugin\n";
521 $img->filter(type=>'lin_stretch', a=>35, b=>200);
523 unload_plugin("dynfilt/dyntest.so")
525 or die "unable to load plugin\n";
526 Someone decides that the filter is not working as it should - dyntest.c
528 can be modified and recompiled, and then reloaded:
529 load_plugin("dynfilt/dyntest.so")
531 or die "unable to load plugin\n";
532 $img->filter(%hsh);
534 Note: This has been tested successfully on the following systems:
536 Linux, Solaris, HPUX, OpenBSD, FreeBSD, TRU64/OSF1, AIX, Win32, OS X.
537 load_plugin()
539 This is a function, not a method, exported by default. You should
540 import this function explicitly for future compatibility if you
541 need it.
542 Accepts a single parameter, the name of a shared library file to
544 load.
545 Returns true on success. Check Imager->errstr on failure.
547 unload_plugin()
549 This is a function, not a method, which is exported by default.
550 You should import this function explicitly for future compatibility
551 if you need it.
552 Accepts a single parameter, the name of a shared library to unload.
554 This library must have been previously loaded by load_plugin().
555 Returns true on success. Check Imager->errstr on failure.
557 A few example plug-ins are included and built (but not installed):
559 · plugins/dyntest.c - provides the "null" (no action) filter, and
561 "lin_stretch" filters. "lin_stretch" stretches sample values
562 between "a" and "b" out to the full sample range.
563 · plugins/dt2.c - provides the "html_art" filter that writes the
565 image to the HTML fragment file supplied in "fname" as a HTML
566 table.
567 · plugins/flines.c - provides the "flines" filter that dims alternate
569 lines to emulate an old CRT display. Imager::Filter::Flines
570 provides the same functionality.
571 · plugins/mandelbrot.c - provides the "mandelbrot" filter that
573 renders the Mandelbrot set within the given range of x [-2, 0.5)
574 and y [-1.25, 1,25). Imager::Filter::Mandelbrot provides a more
575 flexible Mandelbrot set renderer.
576 Image Difference
578 difference()
579 You can create a new image that is the difference between 2 other
580 images.
581 my $diff = $img->difference(other=>$other_img);
583 For each pixel in $img that is different to the pixel in
585 $other_img, the pixel from $other_img is given, otherwise the pixel
586 is transparent black.
587 This can be used for debugging image differences ("Where are they
589 different?"), and for optimizing animated GIFs.
590 Note that $img and $other_img must have the same number of
592 channels. The width and height of $diff will be the minimum of
593 each of the width and height of $img and $other_img.
594 Parameters:
596 · "other" - the other image object to compare against
598 · "mindist" - the difference between corresponding samples must
600 be greater than "mindist" for the pixel to be considered
601 different. So a value of zero returns all different pixels,
602 not all pixels. Range: 0 to 255 inclusive. Default: 0.
603 For large sample images this is scaled down to the range 0 ..
605 1.
606
608 Arnar M. Hrafnkelsson, Tony Cook <tonyc@cpan.org>.
609
611 Imager, Imager::Filter::Flines, Imager::Filter::Mandelbrot
612
614 $Revision$
615perl v5.12.3 2011-06-06 Imager::Filters(3)