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 Returns the invocant ($self) on success, returns a false value on
40 failure. You can call "$self->errstr" to determine the cause of
41 the failure.
42 $self->filter(type => $type, ...)
44 or die $self->errstr;
45 Types of Filters
47 Here is a list of the filters that are always available in Imager.
48 This list can be obtained by running the "filterlist.perl" script that
49 comes with the module source.
50 Filter Arguments Default value
52 autolevels lsat 0.1
53 usat 0.1
54 autolevels_skew lsat 0.1
56 usat 0.1
57 skew 0
58 bumpmap bump lightx lighty
60 elevation 0
61 st 2
62 bumpmap_complex bump
64 channel 0
65 tx 0
66 ty 0
67 Lx 0.2
68 Ly 0.4
69 Lz -1
70 cd 1.0
71 cs 40.0
72 n 1.3
73 Ia (0 0 0)
74 Il (255 255 255)
75 Is (255 255 255)
76 contrast intensity
78 conv coef
80 fountain xa ya xb yb
82 ftype linear
83 repeat none
84 combine none
85 super_sample none
86 ssample_param 4
87 segments(see below)
88 gaussian stddev
90 gaussian2 stddevX
92 stddevY
93 gradgen xo yo colors
95 dist 0
96 hardinvert
98 hardinvertall
100 mosaic size 20
102 noise amount 3
104 subtype 0
105 postlevels levels 10
107 radnoise xo 100
109 yo 100
110 ascale 17.0
111 rscale 0.02
112 turbnoise xo 0.0
114 yo 0.0
115 scale 10.0
116 unsharpmask stddev 2.0
118 scale 1.0
119 watermark wmark
121 pixdiff 10
122 tx 0
123 ty 0
124 All parameters must have some value but if a parameter has a default
126 value it may be omitted when calling the filter function.
127 Every one of these filters modifies the image in place.
129 If none of the filters here do what you need, the "transform()" in
131 Imager::Engines or "transform2()" in Imager::Engines function may be
132 useful.
133 A reference of the filters follows:
135 "autolevels"
137 Scales the luminance of the image so that the luminance will cover
138 the possible range for the image. "lsat" and "usat" truncate the
139 range by the specified fraction at the top and bottom of the range
140 respectively.
141 # increase contrast, losing little detail
143 $img->filter(type=>"autolevels")
144 or die $img->errstr;
145 The method used here is typically called Histogram Equalization
147 <http://en.wikipedia.org/wiki/Histogram_equalization>.
148 "autolevels_skew"
150 Scales the value of each channel so that the values in the image
151 will cover the whole possible range for the channel. "lsat" and
152 "usat" truncate the range by the specified fraction at the top and
153 bottom of the range respectively.
154 # increase contrast per channel, losing little detail
156 $img->filter(type=>"autolevels_skew")
157 or die $img->errstr;
158 # increase contrast, losing 20% of highlight at top and bottom range
160 $img->filter(type=>"autolevels", lsat=>0.2, usat=>0.2)
161 or die $img->errstr;
162 This filter was the original "autolevels" filter, but it's
164 typically useless due to the significant color skew it can produce.
165 "bumpmap"
167 uses the channel "elevation" image "bump" as a bump map on your
168 image, with the light at ("lightx", "lightty"), with a shadow
169 length of "st".
170 $img->filter(type=>"bumpmap", bump=>$bumpmap_img,
172 lightx=>10, lighty=>10, st=>5)
173 or die $img->errstr;
174 "bumpmap_complex"
176 uses the channel "channel" image "bump" as a bump map on your
177 image. If "Lz < 0" the three L parameters are considered to be the
178 direction of the light. If "Lz > 0" the L parameters are
179 considered to be the light position. "Ia" is the ambient color,
180 "Il" is the light color, "Is" is the color of specular highlights.
181 "cd" is the diffuse coefficient and "cs" is the specular
182 coefficient. "n" is the shininess of the surface.
183 $img->filter(type=>"bumpmap_complex", bump=>$bumpmap_img)
185 or die $img->errstr;
186 "contrast"
188 scales each channel by "intensity". Values of "intensity" < 1.0
189 will reduce the contrast.
190 # higher contrast
192 $img->filter(type=>"contrast", intensity=>1.3)
193 or die $img->errstr;
194 # lower contrast
196 $img->filter(type=>"contrast", intensity=>0.8)
197 or die $img->errstr;
198 "conv"
200 performs 2 1-dimensional convolutions on the image using the values
201 from "coef". "coef" should be have an odd length and the sum of
202 the coefficients must be non-zero.
203 # sharper
205 $img->filter(type=>"conv", coef=>[-0.5, 2, -0.5 ])
206 or die $img->errstr;
207 # blur
209 $img->filter(type=>"conv", coef=>[ 1, 2, 1 ])
210 or die $img->errstr;
211 # error
213 $img->filter(type=>"conv", coef=>[ -0.5, 1, -0.5 ])
214 or die $img->errstr;
215 "fountain"
217 renders a fountain fill, similar to the gradient tool in most paint
218 software. The default fill is a linear fill from opaque black to
219 opaque white. The points "A(Cxa, ya)" and "B(xb, yb)" control the
220 way the fill is performed, depending on the "ftype" parameter:
221 "linear"
223 the fill ramps from A through to B.
224 "bilinear"
226 the fill ramps in both directions from A, where AB defines the
227 length of the gradient.
228 "radial"
230 A is the center of a circle, and B is a point on it's
231 circumference. The fill ramps from the center out to the
232 circumference.
233 "radial_square"
235 A is the center of a square and B is the center of one of it's
236 sides. This can be used to rotate the square. The fill ramps
237 out to the edges of the square.
238 "revolution"
240 A is the center of a circle and B is a point on its
241 circumference. B marks the 0 and 360 point on the circle, with
242 the fill ramping clockwise.
243 "conical"
245 A is the center of a circle and B is a point on it's
246 circumference. B marks the 0 and point on the circle, with the
247 fill ramping in both directions to meet opposite.
248 The "repeat" option controls how the fill is repeated for some
250 "ftype"s after it leaves the AB range:
251 "none"
253 no repeats, points outside of each range are treated as if they
254 were on the extreme end of that range.
255 "sawtooth"
257 the fill simply repeats in the positive direction
258 "triangle"
260 the fill repeats in reverse and then forward and so on, in the
261 positive direction
262 "saw_both"
264 the fill repeats in both the positive and negative directions
265 (only meaningful for a linear fill).
266 "tri_both"
268 as for triangle, but in the negative direction too (only
269 meaningful for a linear fill).
270 By default the fill simply overwrites the whole image (unless you
272 have parts of the range 0 through 1 that aren't covered by a
273 segment), if any segments of your fill have any transparency, you
274 can set the combine option to 'normal' to have the fill combined
275 with the existing pixels. See the description of combine in
276 Imager::Fill.
277 If your fill has sharp edges, for example between steps if you use
279 repeat set to 'triangle', you may see some aliased or ragged edges.
280 You can enable super-sampling which will take extra samples within
281 the pixel in an attempt anti-alias the fill.
282 The possible values for the super_sample option are:
284 "none"
286 no super-sampling is done
287 "grid"
289 a square grid of points are sampled. The number of points
290 sampled is the square of ceil(0.5 + sqrt(ssample_param)).
291 "random"
293 a random set of points within the pixel are sampled. This
294 looks pretty bad for low ssample_param values.
295 "circle"
297 the points on the radius of a circle within the pixel are
298 sampled. This seems to produce the best results, but is fairly
299 slow (for now).
300 You can control the level of sampling by setting the ssample_param
302 option. This is roughly the number of points sampled, but depends
303 on the type of sampling.
304 The segments option is an arrayref of segments. You really should
306 use the Imager::Fountain class to build your fountain fill. Each
307 segment is an array ref containing:
308 "start"
310 a floating point number between 0 and 1, the start of the range
311 of fill parameters covered by this segment.
312 "middle"
314 a floating point number between start and end which can be used
315 to push the color range towards one end of the segment.
316 "end"
318 a floating point number between 0 and 1, the end of the range
319 of fill parameters covered by this segment. This should be
320 greater than start.
321 "c0"
323 "c1"
324 The colors at each end of the segment. These can be either
325 Imager::Color or Imager::Color::Float objects.
326 segment type
328 The type of segment, this controls the way the fill parameter
329 varies over the segment. 0 for linear, 1 for curved
330 (unimplemented), 2 for sine, 3 for sphere increasing, 4 for
331 sphere decreasing.
332 color type
334 The way the color varies within the segment, 0 for simple RGB,
335 1 for hue increasing and 2 for hue decreasing.
336 Don't forget to use Imager::Fountain instead of building your own.
338 Really. It even loads GIMP gradient files.
339 # build the gradient the hard way - linear from black to white,
341 # then back again
342 my @simple =
343 (
344 [ 0, 0.25, 0.5, 'black', 'white', 0, 0 ],
345 [ 0.5. 0.75, 1.0, 'white', 'black', 0, 0 ],
346 );
347 # across
348 my $linear = $img->copy;
349 $linear->filter(type => "fountain",
350 ftype => 'linear',
351 repeat => 'sawtooth',
352 segments => \@simple,
353 xa => 0,
354 ya => $linear->getheight / 2,
355 xb => $linear->getwidth - 1,
356 yb => $linear->getheight / 2)
357 or die $linear->errstr;
358 # around
359 my $revolution = $img->copy;
360 $revolution->filter(type => "fountain",
361 ftype => 'revolution',
362 segments => \@simple,
363 xa => $revolution->getwidth / 2,
364 ya => $revolution->getheight / 2,
365 xb => $revolution->getwidth / 2,
366 yb => 0)
367 or die $revolution->errstr;
368 # out from the middle
369 my $radial = $img->copy;
370 $radial->filter(type => "fountain",
371 ftype => 'radial',
372 segments => \@simple,
373 xa => $im->getwidth / 2,
374 ya => $im->getheight / 2,
375 xb => $im->getwidth / 2,
376 yb => 0)
377 or die $radial->errstr;
378 "gaussian"
380 performs a Gaussian blur of the image, using "stddev" as the
381 standard deviation of the curve used to combine pixels, larger
382 values give bigger blurs. For a definition of Gaussian Blur, see:
383 http://www.maths.abdn.ac.uk/~igc/tch/mx4002/notes/node99.html
385 Values of "stddev" around 0.5 provide a barely noticeable blur,
387 values around 5 provide a very strong blur.
388 # only slightly blurred
390 $img->filter(type=>"gaussian", stddev=>0.5)
391 or die $img->errstr;
392 # more strongly blurred
394 $img->filter(type=>"gaussian", stddev=>5)
395 or die $img->errstr;
396 "gaussian2"
398 performs a Gaussian blur of the image, using "stddevX", "stddevY"
399 as the standard deviation of the curve used to combine pixels on
400 the X and Y axis, respectively. Larger values give bigger blurs.
401 For a definition of Gaussian Blur, see:
402 http://www.maths.abdn.ac.uk/~igc/tch/mx4002/notes/node99.html
404 Values of "stddevX" or "stddevY" around 0.5 provide a barely
406 noticeable blur, values around 5 provide a very strong blur.
407 # only slightly blurred
409 $img->filter(type=>"gaussian2", stddevX=>0.5, stddevY=>0.5)
410 or die $img->errstr;
411 # blur an image in the Y axis
413 $img->filter(type=>"gaussian", stddevX=>0, stddevY=>5 )
414 or die $img->errstr;
415 "gradgen"
417 renders a gradient, with the given colors at the corresponding
418 points (x,y) in "xo" and "yo". You can specify the way distance is
419 measured for color blending by setting "dist" to 0 for Euclidean, 1
420 for Euclidean squared, and 2 for Manhattan distance.
421 $img->filter(type="gradgen",
423 xo=>[ 10, 50, 10 ],
424 yo=>[ 10, 50, 50 ],
425 colors=>[ qw(red blue green) ]);
426 "hardinvert"
428 inverts the image, black to white, white to black. All color
429 channels are inverted, excluding the alpha channel if any.
430 $img->filter(type=>"hardinvert")
432 or die $img->errstr;
433 "hardinvertall"
435 inverts the image, black to white, white to black. All channels
436 are inverted, including the alpha channel if any.
437 $img->filter(type=>"hardinvertall")
439 or die $img->errstr;
440 "mosaic"
442 produces averaged tiles of the given "size".
443 $img->filter(type=>"mosaic", size=>5)
445 or die $img->errstr;
446 "noise"
448 adds noise of the given "amount" to the image. If "subtype" is
449 zero, the noise is even to each channel, otherwise noise is added
450 to each channel independently.
451 # monochrome noise
453 $img->filter(type=>"noise", amount=>20, subtype=>0)
454 or die $img->errstr;
455 # color noise
457 $img->filter(type=>"noise", amount=>20, subtype=>1)
458 or die $img->errstr;
459 "radnoise"
461 renders radiant Perlin turbulent noise. The center of the noise is
462 at ("xo", "yo"), "ascale" controls the angular scale of the noise ,
463 and "rscale" the radial scale, higher numbers give more detail.
464 $img->filter(type=>"radnoise", xo=>50, yo=>50,
466 ascale=>1, rscale=>0.02)
467 or die $img->errstr;
468 "postlevels"
470 alters the image to have only "levels" distinct level in each
471 channel.
472 $img->filter(type=>"postlevels", levels=>10)
474 or die $img->errstr;
475 "turbnoise"
477 renders Perlin turbulent noise. ("xo", "yo") controls the origin
478 of the noise, and "scale" the scale of the noise, with lower
479 numbers giving more detail.
480 $img->filter(type=>"turbnoise", xo=>10, yo=>10, scale=>10)
482 or die $img->errstr;
483 "unsharpmask"
485 performs an unsharp mask on the image. This increases the contrast
486 of edges in the image.
487 This is the result of subtracting a Gaussian blurred version of the
489 image from the original. "stddev" controls the "stddev" parameter
490 of the Gaussian blur. Each output pixel is:
491 in + scale * (in - blurred)
493 eg.
495 $img->filter(type=>"unsharpmask", stddev=>1, scale=>0.5)
497 or die $img->errstr;
498 "unsharpmark" has the following parameters:
500 • "stddev" - this is equivalent to the "Radius" value in the
502 GIMP's unsharp mask filter. This controls the size of the
503 contrast increase around edges, larger values will remove fine
504 detail. You should probably experiment on the types of images
505 you plan to work with. Default: 2.0.
506 • "scale" - controls the strength of the edge enhancement,
508 equivalent to Amount in the GIMP's unsharp mask filter.
509 Default: 1.0.
510 "watermark"
512 applies "wmark" as a watermark on the image with strength
513 "pixdiff", with an origin at ("tx", "ty")
514 $img->filter(type=>"watermark", tx=>10, ty=>50,
516 wmark=>$wmark_image, pixdiff=>50)
517 or die $img->errstr;
518 A demonstration of most of the filters can be found at:
520 http://www.develop-help.com/imager/filters.html
522 External Filters
524 As of Imager 0.48 you can create perl or XS based filters and hook them
525 into Imager's filter() method:
526 register_filter()
528 Registers a filter so it is visible via Imager's filter() method.
529 Imager->register_filter(type => 'your_filter',
531 defaults => { parm1 => 'default1' },
532 callseq => [ qw/image parm1/ ],
533 callsub => \&your_filter);
534 $img->filter(type=>'your_filter', parm1 => 'something');
535 The following parameters are needed:
537 • "type" - the type value that will be supplied to filter() to
539 use your filter.
540 • "defaults" - a hash of defaults for the filter's parameters
542 • "callseq" - a reference to an array of required parameter
544 names.
545 • "callsub" - a code reference called to execute your filter.
547 The parameters passed to filter() are supplied as a list of
548 parameter name, value ... which can be assigned to a hash.
549 The special parameters "image" and "imager" are supplied as the
551 low level image object from $self and $self itself
552 respectively.
553 The function you supply must modify the image in place.
555 To indicate an error, die with an error message followed by a
557 newline. filter() will store the error message as the errstr()
558 for the invocant and return false to indicate failure.
559 sub my_filter {
561 my %opts = @_;
562 _is_valid($opts{myparam})
563 or die "myparam invalid!\n";
564 # actually do the filtering...
566 }
567 See Imager::Filter::Mandelbrot for an example.
569 Plug-ins
571 The plug in interface is deprecated. Please use the Imager API, see
572 Imager::API and "External Filters" for details
573 It is possible to add filters to the module without recompiling Imager
575 itself. This is done by using DSOs (Dynamic shared object) available
576 on most systems. This way you can maintain your own filters and not
577 have to have it added to Imager, or worse patch every new version of
578 Imager. Modules can be loaded AND UNLOADED at run time. This means
579 that you can have a server/daemon thingy that can do something like:
580 load_plugin("dynfilt/dyntest.so")
582 or die "unable to load plugin\n";
583 $img->filter(type=>'lin_stretch', a=>35, b=>200);
585 unload_plugin("dynfilt/dyntest.so")
587 or die "unable to load plugin\n";
588 Someone decides that the filter is not working as it should - dyntest.c
590 can be modified and recompiled, and then reloaded:
591 load_plugin("dynfilt/dyntest.so")
593 or die "unable to load plugin\n";
594 $img->filter(%hsh);
596 Note: This has been tested successfully on the following systems:
598 Linux, Solaris, HPUX, OpenBSD, FreeBSD, TRU64/OSF1, AIX, Win32, OS X.
599 load_plugin()
601 This is a function, not a method, exported by default. You should
602 import this function explicitly for future compatibility if you
603 need it.
604 Accepts a single parameter, the name of a shared library file to
606 load.
607 Returns true on success. Check Imager->errstr on failure.
609 unload_plugin()
611 This is a function, not a method, which is exported by default.
612 You should import this function explicitly for future compatibility
613 if you need it.
614 Accepts a single parameter, the name of a shared library to unload.
616 This library must have been previously loaded by load_plugin().
617 Returns true on success. Check Imager->errstr on failure.
619 A few example plug-ins are included and built (but not installed):
621 • plugins/dyntest.c - provides the "null" (no action) filter, and
623 "lin_stretch" filters. "lin_stretch" stretches sample values
624 between "a" and "b" out to the full sample range.
625 • plugins/dt2.c - provides the "html_art" filter that writes the
627 image to the HTML fragment file supplied in "fname" as a HTML
628 table.
629 • plugins/flines.c - provides the "flines" filter that dims alternate
631 lines to emulate an old CRT display. Imager::Filter::Flines
632 provides the same functionality.
633 • plugins/mandelbrot.c - provides the "mandelbrot" filter that
635 renders the Mandelbrot set within the given range of x [-2, 0.5)
636 and y [-1.25, 1,25). Imager::Filter::Mandelbrot provides a more
637 flexible Mandelbrot set renderer.
638 Image Difference
640 difference()
641 You can create a new image that is the difference between 2 other
642 images.
643 my $diff = $img->difference(other=>$other_img);
645 For each pixel in $img that is different to the pixel in
647 $other_img, the pixel from $other_img is given, otherwise the pixel
648 is transparent black.
649 This can be used for debugging image differences ("Where are they
651 different?"), and for optimizing animated GIFs.
652 Note that $img and $other_img must have the same number of
654 channels. The width and height of $diff will be the minimum of
655 each of the width and height of $img and $other_img.
656 Parameters:
658 • "other" - the other image object to compare against
660 • "mindist" - the difference between corresponding samples must
662 be greater than "mindist" for the pixel to be considered
663 different. So a value of zero returns all different pixels,
664 not all pixels. Range: 0 to 255 inclusive. Default: 0.
665 For large sample images this is scaled down to the range 0 ..
667 1.
668 rgb_difference()
670 You can create a new image that is the difference between 2 other
671 images.
672 my $diff = $img->rgb_difference(other=>$other_img);
674 For each pixel in $img that is different to the pixel in
676 $other_img, the arithmetic difference for the value of the pixel in
677 $img from $other_img per color is given. Transparency is ignored.
678 This can be used for measuring image differences ("How much are
680 they different?").
681 Note that $img and $other_img must have the same number of
683 channels. The width and height of $diff will be the minimum of
684 each of the width and height of $img and $other_img.
685 Parameters:
687 • "other" - the other image object to compare against
689
691 Arnar M. Hrafnkelsson, Tony Cook <tonyc@cpan.org>.
692
694 Imager, Imager::Filter::Flines, Imager::Filter::Mandelbrot
695
697 $Revision$
698perl v5.36.0 2023-01-20 Imager::Filters(3)