1Imager::Filters(3)    User Contributed Perl Documentation   Imager::Filters(3)
2
3
4

NAME

6       Imager::Filters - Entire Image Filtering Operations
7

SYNOPSIS

9         use Imager;
10
11         $img = ...;
12
13         $img->filter(type=>'autolevels');
14         $img->filter(type=>'autolevels', lsat=>0.2);
15         $img->filter(type=>'turbnoise')
16
17         # and lots of others
18
19         load_plugin("dynfilt/dyntest.so")
20           or die "unable to load plugin\n";
21
22         $img->filter(type=>'lin_stretch', a=>35, b=>200);
23
24         unload_plugin("dynfilt/dyntest.so")
25           or die "unable to load plugin\n";
26
27         $out = $img->difference(other=>$other_img);
28

DESCRIPTION

30       Filters are operations that have similar calling interface.
31
32       filter()
33           Parameters:
34
35           ·   type - the type of filter, see "Types of Filters".
36
37           ·   many other possible parameters, see "Types of Filters" below.
38
39           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
43             $self->filter(type => $type, ...)
44               or die $self->errstr;
45
46   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
51         Filter          Arguments   Default value
52         autolevels      lsat        0.1
53                         usat        0.1
54
55         autolevels_skew lsat        0.1
56                         usat        0.1
57                         skew        0
58
59         bumpmap         bump lightx lighty
60                         elevation   0
61                         st          2
62
63         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
77         contrast        intensity
78
79         conv            coef
80
81         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
89         gaussian        stddev
90
91         gaussian2       stddevX
92                         stddevY
93
94         gradgen         xo yo colors
95                         dist         0
96
97         hardinvert
98
99         hardinvertall
100
101         mosaic          size         20
102
103         noise           amount       3
104                         subtype      0
105
106         postlevels      levels       10
107
108         radnoise        xo           100
109                         yo           100
110                         ascale       17.0
111                         rscale       0.02
112
113         turbnoise       xo           0.0
114                         yo           0.0
115                         scale        10.0
116
117         unsharpmask     stddev       2.0
118                         scale        1.0
119
120         watermark       wmark
121                         pixdiff      10
122                         tx           0
123                         ty           0
124
125       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
128       Every one of these filters modifies the image in place.
129
130       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
134       A reference of the filters follows:
135
136       "autolevels"
137           Scales the luminosity of the image so that the luminosity will
138           cover the possible range for the image.  "lsat" and "usat" truncate
139           the range by the specified fraction at the top and bottom of the
140           range respectively.
141
142             # increase contrast, losing little detail
143             $img->filter(type=>"autolevels")
144               or die $img->errstr;
145
146           The method used here is typically called Histogram Equalization
147           <http://en.wikipedia.org/wiki/Histogram_equalization>.
148
149       "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
155             # increase contrast per channel, losing little detail
156             $img->filter(type=>"autolevels_skew")
157               or die $img->errstr;
158
159             # 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
163           This filter was the original "autolevels" filter, but it's
164           typically useless due to the significant color skew it can produce.
165
166       "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
171             $img->filter(type=>"bumpmap", bump=>$bumpmap_img,
172                          lightx=>10, lighty=>10, st=>5)
173               or die $img->errstr;
174
175       "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
184             $img->filter(type=>"bumpmap_complex", bump=>$bumpmap_img)
185               or die $img->errstr;
186
187       "contrast"
188           scales each channel by "intensity".  Values of "intensity" < 1.0
189           will reduce the contrast.
190
191             # higher contrast
192             $img->filter(type=>"contrast", intensity=>1.3)
193               or die $img->errstr;
194
195             # lower contrast
196             $img->filter(type=>"contrast", intensity=>0.8)
197               or die $img->errstr;
198
199       "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
204             # sharper
205             $img->filter(type=>"conv", coef=>[-0.5, 2, -0.5 ])
206               or die $img->errstr;
207
208             # blur
209             $img->filter(type=>"conv", coef=>[ 1, 2, 1 ])
210               or die $img->errstr;
211
212             # error
213             $img->filter(type=>"conv", coef=>[ -0.5, 1, -0.5 ])
214               or die $img->errstr;
215
216       "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
222           "linear"
223               the fill ramps from A through to B.
224
225           "bilinear"
226               the fill ramps in both directions from A, where AB defines the
227               length of the gradient.
228
229           "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
234           "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
239           "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
244           "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
249           The "repeat" option controls how the fill is repeated for some
250           "ftype"s after it leaves the AB range:
251
252           "none"
253               no repeats, points outside of each range are treated as if they
254               were on the extreme end of that range.
255
256           "sawtooth"
257               the fill simply repeats in the positive direction
258
259           "triangle"
260               the fill repeats in reverse and then forward and so on, in the
261               positive direction
262
263           "saw_both"
264               the fill repeats in both the positive and negative directions
265               (only meaningful for a linear fill).
266
267           "tri_both"
268               as for triangle, but in the negative direction too (only
269               meaningful for a linear fill).
270
271           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
278           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
283           The possible values for the super_sample option are:
284
285           "none"
286               no super-sampling is done
287
288           "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
292           "random"
293               a random set of points within the pixel are sampled.  This
294               looks pretty bad for low ssample_param values.
295
296           "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
301           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
305           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
309           "start"
310               a floating point number between 0 and 1, the start of the range
311               of fill parameters covered by this segment.
312
313           "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
317           "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
322           "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
327           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
333           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
337           Don't forget to use Imager::Fountain instead of building your own.
338           Really.  It even loads GIMP gradient files.
339
340             # 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
379       "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
384             http://www.maths.abdn.ac.uk/~igc/tch/mx4002/notes/node99.html
385
386           Values of "stddev" around 0.5 provide a barely noticeable blur,
387           values around 5 provide a very strong blur.
388
389             # only slightly blurred
390             $img->filter(type=>"gaussian", stddev=>0.5)
391               or die $img->errstr;
392
393             # more strongly blurred
394             $img->filter(type=>"gaussian", stddev=>5)
395               or die $img->errstr;
396
397       "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
403             http://www.maths.abdn.ac.uk/~igc/tch/mx4002/notes/node99.html
404
405           Values of "stddevX" or "stddevY" around 0.5 provide a barely
406           noticeable blur, values around 5 provide a very strong blur.
407
408             # only slightly blurred
409             $img->filter(type=>"gaussian2", stddevX=>0.5, stddevY=>0.5)
410               or die $img->errstr;
411
412             # blur an image in the Y axis
413             $img->filter(type=>"gaussian", stddevX=>0, stddevY=>5 )
414               or die $img->errstr;
415
416       "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
422             $img->filter(type="gradgen",
423                          xo=>[ 10, 50, 10 ],
424                          yo=>[ 10, 50, 50 ],
425                          colors=>[ qw(red blue green) ]);
426
427       "hardinvert"
428           inverts the image, black to white, white to black.  All color
429           channels are inverted, excluding the alpha channel if any.
430
431             $img->filter(type=>"hardinvert")
432               or die $img->errstr;
433
434       "hardinvertall"
435           inverts the image, black to white, white to black.  All channels
436           are inverted, including the alpha channel if any.
437
438             $img->filter(type=>"hardinvertall")
439               or die $img->errstr;
440
441       "mosaic"
442           produces averaged tiles of the given "size".
443
444             $img->filter(type=>"mosaic", size=>5)
445               or die $img->errstr;
446
447       "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
452             # monochrome noise
453             $img->filter(type=>"noise", amount=>20, subtype=>0)
454               or die $img->errstr;
455
456             # color noise
457             $img->filter(type=>"noise", amount=>20, subtype=>1)
458               or die $img->errstr;
459
460       "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
465             $img->filter(type=>"radnoise", xo=>50, yo=>50,
466                          ascale=>1, rscale=>0.02)
467               or die $img->errstr;
468
469       "postlevels"
470           alters the image to have only "levels" distinct level in each
471           channel.
472
473             $img->filter(type=>"postlevels", levels=>10)
474               or die $img->errstr;
475
476       "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
481             $img->filter(type=>"turbnoise", xo=>10, yo=>10, scale=>10)
482               or die $img->errstr;
483
484       "unsharpmask"
485           performs an unsharp mask on the image.  This increases the contrast
486           of edges in the image.
487
488           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
492             in + scale * (in - blurred)
493
494           eg.
495
496             $img->filter(type=>"unsharpmask", stddev=>1, scale=>0.5)
497               or die $img->errstr;
498
499           "unsharpmark" has the following parameters:
500
501           ·   "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
507           ·   "scale" - controls the strength of the edge enhancement,
508               equivalent to Amount in the GIMP's unsharp mask filter.
509               Default: 1.0.
510
511       "watermark"
512           applies "wmark" as a watermark on the image with strength
513           "pixdiff", with an origin at ("tx", "ty")
514
515             $img->filter(type=>"watermark", tx=>10, ty=>50,
516                          wmark=>$wmark_image, pixdiff=>50)
517               or die $img->errstr;
518
519       A demonstration of most of the filters can be found at:
520
521         http://www.develop-help.com/imager/filters.html
522
523   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
527       register_filter()
528           Registers a filter so it is visible via Imager's filter() method.
529
530             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
536           The following parameters are needed:
537
538           ·   "type" - the type value that will be supplied to filter() to
539               use your filter.
540
541           ·   "defaults" - a hash of defaults for the filter's parameters
542
543           ·   "callseq" - a reference to an array of required parameter
544               names.
545
546           ·   "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
550               The special parameters "image" and "imager" are supplied as the
551               low level image object from $self and $self itself
552               respectively.
553
554               The function you supply must modify the image in place.
555
556               To indicate an error, die with an error message followed by a
557               newline. "filter()" will store the error message as the
558               "errstr()" for the invocant and return false to indicate
559               failure.
560
561                 sub my_filter {
562                   my %opts = @_;
563                   _is_valid($opts{myparam})
564                     or die "myparam invalid!\n";
565
566                   # actually do the filtering...
567                 }
568
569           See Imager::Filter::Mandelbrot for an example.
570
571   Plug-ins
572       The plug in interface is deprecated.  Please use the Imager API, see
573       Imager::API and "External Filters" for details
574
575       It is possible to add filters to the module without recompiling Imager
576       itself.  This is done by using DSOs (Dynamic shared object) available
577       on most systems.  This way you can maintain your own filters and not
578       have to have it added to Imager, or worse patch every new version of
579       Imager.  Modules can be loaded AND UNLOADED at run time.  This means
580       that you can have a server/daemon thingy that can do something like:
581
582         load_plugin("dynfilt/dyntest.so")
583           or die "unable to load plugin\n";
584
585         $img->filter(type=>'lin_stretch', a=>35, b=>200);
586
587         unload_plugin("dynfilt/dyntest.so")
588           or die "unable to load plugin\n";
589
590       Someone decides that the filter is not working as it should - dyntest.c
591       can be modified and recompiled, and then reloaded:
592
593         load_plugin("dynfilt/dyntest.so")
594           or die "unable to load plugin\n";
595
596         $img->filter(%hsh);
597
598       Note: This has been tested successfully on the following systems:
599       Linux, Solaris, HPUX, OpenBSD, FreeBSD, TRU64/OSF1, AIX, Win32, OS X.
600
601       load_plugin()
602           This is a function, not a method, exported by default.  You should
603           import this function explicitly for future compatibility if you
604           need it.
605
606           Accepts a single parameter, the name of a shared library file to
607           load.
608
609           Returns true on success.  Check Imager->errstr on failure.
610
611       unload_plugin()
612           This is a function, not a method, which is exported by default.
613           You should import this function explicitly for future compatibility
614           if you need it.
615
616           Accepts a single parameter, the name of a shared library to unload.
617           This library must have been previously loaded by load_plugin().
618
619           Returns true on success.  Check Imager->errstr on failure.
620
621       A few example plug-ins are included and built (but not installed):
622
623       ·   plugins/dyntest.c - provides the "null" (no action) filter, and
624           "lin_stretch" filters.  "lin_stretch" stretches sample values
625           between "a" and "b" out to the full sample range.
626
627       ·   plugins/dt2.c - provides the "html_art" filter that writes the
628           image to the HTML fragment file supplied in "fname" as a HTML
629           table.
630
631       ·   plugins/flines.c - provides the "flines" filter that dims alternate
632           lines to emulate an old CRT display.  Imager::Filter::Flines
633           provides the same functionality.
634
635       ·   plugins/mandelbrot.c - provides the "mandelbrot" filter that
636           renders the Mandelbrot set within the given range of x [-2, 0.5)
637           and y [-1.25, 1,25).  Imager::Filter::Mandelbrot provides a more
638           flexible Mandelbrot set renderer.
639
640   Image Difference
641       difference()
642           You can create a new image that is the difference between 2 other
643           images.
644
645             my $diff = $img->difference(other=>$other_img);
646
647           For each pixel in $img that is different to the pixel in
648           $other_img, the pixel from $other_img is given, otherwise the pixel
649           is transparent black.
650
651           This can be used for debugging image differences ("Where are they
652           different?"), and for optimizing animated GIFs.
653
654           Note that $img and $other_img must have the same number of
655           channels.  The width and height of $diff will be the minimum of
656           each of the width and height of $img and $other_img.
657
658           Parameters:
659
660           ·   "other" - the other image object to compare against
661
662           ·   "mindist" - the difference between corresponding samples must
663               be greater than "mindist" for the pixel to be considered
664               different.  So a value of zero returns all different pixels,
665               not all pixels.  Range: 0 to 255 inclusive.  Default: 0.
666
667               For large sample images this is scaled down to the range 0 ..
668               1.
669

AUTHOR

671       Arnar M. Hrafnkelsson, Tony Cook <tonyc@cpan.org>.
672

SEE ALSO

674       Imager, Imager::Filter::Flines, Imager::Filter::Mandelbrot
675

REVISION

677       $Revision$
678
679
680
681perl v5.32.0                      2020-07-28                Imager::Filters(3)
Impressum