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

AUTHOR

647       Arnar M. Hrafnkelsson, Tony Cook <tonyc@cpan.org>.
648

SEE ALSO

650       Imager, Imager::Filter::Flines, Imager::Filter::Mandelbrot
651

REVISION

653       $Revision$
654
655
656
657perl v5.28.1                      2014-04-12                Imager::Filters(3)
Impressum