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 gradgen xo yo colors
92 dist 0
93 hardinvert
95 hardinvertall
97 mosaic size 20
99 noise amount 3
101 subtype 0
102 postlevels levels 10
104 radnoise xo 100
106 yo 100
107 ascale 17.0
108 rscale 0.02
109 turbnoise xo 0.0
111 yo 0.0
112 scale 10.0
113 unsharpmask stddev 2.0
115 scale 1.0
116 watermark wmark
118 pixdiff 10
119 tx 0
120 ty 0
121 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 Every one of these filters modifies the image in place.
126 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 A reference of the filters follows:
132 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 # increase contrast, losing little detail
140 $img->filter(type=>"autolevels")
141 or die $img->errstr;
142 The method used here is typically called Histogram Equalization
144 <http://en.wikipedia.org/wiki/Histogram_equalization>.
145 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 # increase contrast per channel, losing little detail
153 $img->filter(type=>"autolevels_skew")
154 or die $img->errstr;
155 # 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 This filter was the original "autolevels" filter, but it's
161 typically useless due to the significant color skew it can produce.
162 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 $img->filter(type=>"bumpmap", bump=>$bumpmap_img,
169 lightx=>10, lighty=>10, st=>5)
170 or die $img->errstr;
171 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 $img->filter(type=>"bumpmap_complex", bump=>$bumpmap_img)
182 or die $img->errstr;
183 contrast
185 scales each channel by "intensity". Values of "intensity" < 1.0
186 will reduce the contrast.
187 # higher contrast
189 $img->filter(type=>"contrast", intensity=>1.3)
190 or die $img->errstr;
191 # lower contrast
193 $img->filter(type=>"contrast", intensity=>0.8)
194 or die $img->errstr;
195 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 # sharper
202 $img->filter(type=>"conv", coef=>[-0.5, 2, -0.5 ])
203 or die $img->errstr;
204 # blur
206 $img->filter(type=>"conv", coef=>[ 1, 2, 1 ])
207 or die $img->errstr;
208 # error
210 $img->filter(type=>"conv", coef=>[ -0.5, 1, -0.5 ])
211 or die $img->errstr;
212 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 "linear"
220 the fill ramps from A through to B.
221 "bilinear"
223 the fill ramps in both directions from A, where AB defines the
224 length of the gradient.
225 "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 "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 "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 "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 The "repeat" option controls how the fill is repeated for some
247 "ftype"s after it leaves the AB range:
248 "none"
250 no repeats, points outside of each range are treated as if they
251 were on the extreme end of that range.
252 "sawtooth"
254 the fill simply repeats in the positive direction
255 "triangle"
257 the fill repeats in reverse and then forward and so on, in the
258 positive direction
259 "saw_both"
261 the fill repeats in both the positive and negative directions
262 (only meaningful for a linear fill).
263 "tri_both"
265 as for triangle, but in the negative direction too (only
266 meaningful for a linear fill).
267 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 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 The possible values for the super_sample option are:
281 none
283 no super-sampling is done
284 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 random
290 a random set of points within the pixel are sampled. This
291 looks pretty bad for low ssample_param values.
292 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 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 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 start
307 a floating point number between 0 and 1, the start of the range
308 of fill parameters covered by this segment.
309 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 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 c0
319 c1 The colors at each end of the segment. These can be either
320 Imager::Color or Imager::Color::Float objects.
321 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 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 Don't forget to use Imager::Fountain instead of building your own.
333 Really. It even loads GIMP gradient files.
334 # 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 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 http://www.maths.abdn.ac.uk/~igc/tch/mx4002/notes/node99.html
380 Values of "stddev" around 0.5 provide a barely noticeable blur,
382 values around 5 provide a very strong blur.
383 # only slightly blurred
385 $img->filter(type=>"gaussian", stddev=>0.5)
386 or die $img->errstr;
387 # more strongly blurred
389 $img->filter(type=>"gaussian", stddev=>5)
390 or die $img->errstr;
391 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 $img->filter(type="gradgen",
399 xo=>[ 10, 50, 10 ],
400 yo=>[ 10, 50, 50 ],
401 colors=>[ qw(red blue green) ]);
402 hardinvert
404 inverts the image, black to white, white to black. All color
405 channels are inverted, excluding the alpha channel if any.
406 $img->filter(type=>"hardinvert")
408 or die $img->errstr;
409 hardinvertall
411 inverts the image, black to white, white to black. All channels
412 are inverted, including the alpha channel if any.
413 $img->filter(type=>"hardinvertall")
415 or die $img->errstr;
416 mosaic
418 produces averaged tiles of the given "size".
419 $img->filter(type=>"mosaic", size=>5)
421 or die $img->errstr;
422 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 # monochrome noise
429 $img->filter(type=>"noise", amount=>20, subtype=>0)
430 or die $img->errstr;
431 # color noise
433 $img->filter(type=>"noise", amount=>20, subtype=>1)
434 or die $img->errstr;
435 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 $img->filter(type=>"radnoise", xo=>50, yo=>50,
442 ascale=>1, rscale=>0.02)
443 or die $img->errstr;
444 postlevels
446 alters the image to have only "levels" distinct level in each
447 channel.
448 $img->filter(type=>"postlevels", levels=>10)
450 or die $img->errstr;
451 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 $img->filter(type=>"turbnoise", xo=>10, yo=>10, scale=>10)
458 or die $img->errstr;
459 unsharpmask
461 performs an unsharp mask on the image. This increases the contrast
462 of edges in the image.
463 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 in + scale * (in - blurred)
469 eg.
471 $img->filter(type=>"unsharpmask", stddev=>1, scale=>0.5)
473 or die $img->errstr;
474 "unsharpmark" has the following parameters:
476 · "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 · "scale" - controls the strength of the edge enhancement,
484 equivalent to Amount in the GIMP's unsharp mask filter.
485 Default: 1.0.
486 watermark
488 applies "wmark" as a watermark on the image with strength
489 "pixdiff", with an origin at ("tx", "ty")
490 $img->filter(type=>"watermark", tx=>10, ty=>50,
492 wmark=>$wmark_image, pixdiff=>50)
493 or die $img->errstr;
494 A demonstration of most of the filters can be found at:
496 http://www.develop-help.com/imager/filters.html
498 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 register_filter()
504 Registers a filter so it is visible via Imager's filter() method.
505 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 The following parameters are needed:
513 · "type" - the type value that will be supplied to filter() to
515 use your filter.
516 · "defaults" - a hash of defaults for the filter's parameters
518 · "callseq" - a reference to an array of required parameter
520 names.
521 · "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 The special parameters "image" and "imager" are supplied as the
527 low level image object from $self and $self itself
528 respectively.
529 The function you supply must modify the image in place.
531 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 sub my_filter {
538 my %opts = @_;
539 _is_valid($opts{myparam})
540 or die "myparam invalid!\n";
541 # actually do the filtering...
543 }
544 See Imager::Filter::Mandelbrot for an example.
546 Plug-ins
548 The plug in interface is deprecated. Please use the Imager API, see
549 Imager::API and "External Filters" for details
550 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 load_plugin("dynfilt/dyntest.so")
559 or die "unable to load plugin\n";
560 $img->filter(type=>'lin_stretch', a=>35, b=>200);
562 unload_plugin("dynfilt/dyntest.so")
564 or die "unable to load plugin\n";
565 Someone decides that the filter is not working as it should - dyntest.c
567 can be modified and recompiled, and then reloaded:
568 load_plugin("dynfilt/dyntest.so")
570 or die "unable to load plugin\n";
571 $img->filter(%hsh);
573 Note: This has been tested successfully on the following systems:
575 Linux, Solaris, HPUX, OpenBSD, FreeBSD, TRU64/OSF1, AIX, Win32, OS X.
576 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 Accepts a single parameter, the name of a shared library file to
583 load.
584 Returns true on success. Check Imager->errstr on failure.
586 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 Accepts a single parameter, the name of a shared library to unload.
593 This library must have been previously loaded by load_plugin().
594 Returns true on success. Check Imager->errstr on failure.
596 A few example plug-ins are included and built (but not installed):
598 · 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 · 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 · 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 · 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 Image Difference
617 difference()
618 You can create a new image that is the difference between 2 other
619 images.
620 my $diff = $img->difference(other=>$other_img);
622 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 This can be used for debugging image differences ("Where are they
628 different?"), and for optimizing animated GIFs.
629 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 Parameters:
635 · "other" - the other image object to compare against
637 · "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 For large sample images this is scaled down to the range 0 ..
644 1.
645
647 Arnar M. Hrafnkelsson, Tony Cook <tonyc@cpan.org>.
648
650 Imager, Imager::Filter::Flines, Imager::Filter::Mandelbrot
651
653 $Revision$
654perl v5.30.1 2020-01-30 Imager::Filters(3)