3 Imager::Filters - Entire Image Filtering Operations
11 $img->filter(type=>'autolevels');
12 $img->filter(type=>'autolevels', lsat=>0.2);
13 $img->filter(type=>'turbnoise')
17 load_plugin("dynfilt/dyntest.so")
18 or die "unable to load plugin\n";
20 $img->filter(type=>'lin_stretch', a=>35, b=>200);
22 unload_plugin("dynfilt/dyntest.so")
23 or die "unable to load plugin\n";
25 $out = $img->difference(other=>$other_img);
29 Filters are operations that have similar calling interface.
41 type - the type of filter, see L</Types of Filters>.
45 many other possible parameters, see L</Types of Filters> below.
51 =head2 Types of Filters
53 Here is a list of the filters that are always avaliable in Imager.
54 This list can be obtained by running the C<filterlist.perl> script
55 that comes with the module source.
57 Filter Arguments Default value
62 bumpmap bump lightx lighty
115 unsharpmask stddev 2.0
123 All parameters must have some value but if a parameter has a default
124 value it may be omitted when calling the filter function.
126 Every one of these filters modifies the image in place.
128 If none of the filters here do what you need, the
129 L<Imager::Engines/tranform> or L<Imager::Engines/transform2> function
132 A reference of the filters follows:
138 scales the value of each channel so that the values in the image will
139 cover the whole possible range for the channel. I<lsat> and I<usat>
140 truncate the range by the specified fraction at the top and bottom of
141 the range respectivly.
143 # increase contrast per channel, losing little detail
144 $img->filter(type=>"autolevels")
147 # increase contrast, losing 20% of highlight at top and bottom range
148 $img->filter(type=>"autolevels", lsat=>0.2, usat=>0.2)
153 uses the channel I<elevation> image I<bump> as a bumpmap on your
154 image, with the light at (I<lightx>, I<lightty>), with a shadow length
157 $img->filter(type=>"bumpmap", bump=>$bumpmap_img,
158 lightx=>10, lighty=>10, st=>5)
161 =item bumpmap_complex
163 uses the channel I<channel> image I<bump> as a bumpmap on your image.
164 If Lz<0 the three L parameters are considered to be the direction of
165 the light. If Lz>0 the L parameters are considered to be the light
166 position. I<Ia> is the ambient colour, I<Il> is the light colour,
167 I<Is> is the color of specular highlights. I<cd> is the diffuse
168 coefficient and I<cs> is the specular coefficient. I<n> is the
169 shininess of the surface.
171 $img->filter(type=>"bumpmap_complex", bump=>$bumpmap_img)
176 scales each channel by I<intensity>. Values of I<intensity> < 1.0
177 will reduce the contrast.
180 $img->filter(type=>"contrast", intensity=>1.3)
184 $img->filter(type=>"contrast", intensity=>0.8)
189 performs 2 1-dimensional convolutions on the image using the values
190 from I<coef>. I<coef> should be have an odd length and the sum of the
191 coefficients must be non-zero.
194 $img->filter(type=>"conv", coef=>[-0.5, 2, -0.5 ])
198 $img->filter(type=>"conv", coef=>[ 1, 2, 1 ])
203 renders a fountain fill, similar to the gradient tool in most paint
204 software. The default fill is a linear fill from opaque black to
205 opaque white. The points A(xa, ya) and B(xb, yb) control the way the
206 fill is performed, depending on the ftype parameter:
212 the fill ramps from A through to B.
216 the fill ramps in both directions from A, where AB defines the length
221 A is the center of a circle, and B is a point on it's circumference.
222 The fill ramps from the center out to the circumference.
226 A is the center of a square and B is the center of one of it's sides.
227 This can be used to rotate the square. The fill ramps out to the
232 A is the centre of a circle and B is a point on it's circumference. B
233 marks the 0 and 360 point on the circle, with the fill ramping
238 A is the center of a circle and B is a point on it's circumference. B
239 marks the 0 and point on the circle, with the fill ramping in both
240 directions to meet opposite.
244 The I<repeat> option controls how the fill is repeated for some
245 I<ftype>s after it leaves the AB range:
251 no repeats, points outside of each range are treated as if they were
252 on the extreme end of that range.
256 the fill simply repeats in the positive direction
260 the fill repeats in reverse and then forward and so on, in the
265 the fill repeats in both the positive and negative directions (only
266 meaningful for a linear fill).
270 as for triangle, but in the negative direction too (only meaningful
275 By default the fill simply overwrites the whole image (unless you have
276 parts of the range 0 through 1 that aren't covered by a segment), if
277 any segments of your fill have any transparency, you can set the
278 I<combine> option to 'normal' to have the fill combined with the
279 existing pixels. See the description of I<combine> in L<Imager::Fill>.
281 If your fill has sharp edges, for example between steps if you use
282 repeat set to 'triangle', you may see some aliased or ragged edges.
283 You can enable super-sampling which will take extra samples within the
284 pixel in an attempt anti-alias the fill.
286 The possible values for the super_sample option are:
292 no super-sampling is done
296 a square grid of points are sampled. The number of points sampled is
297 the square of ceil(0.5 + sqrt(ssample_param)).
301 a random set of points within the pixel are sampled. This looks
302 pretty bad for low ssample_param values.
306 the points on the radius of a circle within the pixel are sampled.
307 This seems to produce the best results, but is fairly slow (for now).
311 You can control the level of sampling by setting the ssample_param
312 option. This is roughly the number of points sampled, but depends on
313 the type of sampling.
315 The segments option is an arrayref of segments. You really should use
316 the L<Imager::Fountain> class to build your fountain fill. Each
317 segment is an array ref containing:
323 a floating point number between 0 and 1, the start of the range of
324 fill parameters covered by this segment.
328 a floating point number between start and end which can be used to
329 push the color range towards one end of the segment.
333 a floating point number between 0 and 1, the end of the range of fill
334 parameters covered by this segment. This should be greater than
341 The colors at each end of the segment. These can be either
342 Imager::Color or Imager::Color::Float objects.
346 The type of segment, this controls the way the fill parameter varies
347 over the segment. 0 for linear, 1 for curved (unimplemented), 2 for
348 sine, 3 for sphere increasing, 4 for sphere decreasing.
352 The way the color varies within the segment, 0 for simple RGB, 1 for
353 hue increasing and 2 for hue decreasing.
357 Don't forget to use Imager::Fountain instead of building your own.
358 Really. It even loads GIMP gradient files.
360 # build the gradient the hard way - linear from black to white,
364 [ 0, 0.25, 0.5, 'black', 'white', 0, 0 ],
365 [ 0.5. 0.75, 1.0, 'white', 'black', 0, 0 ],
368 my $linear = $img->copy;
369 $linear->filter(type => "fountain",
371 repeat => 'sawtooth',
372 segments => \@simple,
374 ya => $linear->getheight / 2,
375 xb => $linear->getwidth - 1,
376 yb => $linear->getheight / 2)
377 or die $linear->errstr;
379 my $revolution = $img->copy;
380 $revolution->filter(type => "fountain",
381 ftype => 'revolution',
382 segments => \@simple,
383 xa => $revolution->getwidth / 2,
384 ya => $revolution->getheight / 2,
385 xb => $revolution->getwidth / 2,
387 or die $revolution->errstr;
388 # out from the middle
389 my $radial = $img->copy;
390 $radial->filter(type => "fountain",
392 segments => \@simple,
393 xa => $im->getwidth / 2,
394 ya => $im->getheight / 2,
395 xb => $im->getwidth / 2,
397 or die $radial->errstr;
401 performs a gaussian blur of the image, using I<stddev> as the standard
402 deviation of the curve used to combine pixels, larger values give
403 bigger blurs. For a definition of Gaussian Blur, see:
405 http://www.maths.abdn.ac.uk/~igc/tch/mx4002/notes/node99.html
407 Values of C<stddev> around 0.5 provide a barely noticable blur, values
408 around 5 provide a very strong blur.
410 # only slightly blurred
411 $img->filter(type=>"gaussian", stddev=>0.5)
414 # more strongly blurred
415 $img->filter(type=>"gaussian", stddev=>5)
420 renders a gradient, with the given I<colors> at the corresponding
421 points (x,y) in I<xo> and I<yo>. You can specify the way distance is
422 measured for color blending by setting I<dist> to 0 for Euclidean, 1
423 for Euclidean squared, and 2 for Manhattan distance.
425 $img->filter(type="gradgen",
428 colors=>[ qw(red blue green) ]);
432 inverts the image, black to white, white to black. All channels are
433 inverted, including the alpha channel if any.
435 $img->filter(type=>"hardinvert")
440 produces averaged tiles of the given I<size>.
442 $img->filter(type=>"mosaic", size=>5)
447 adds noise of the given I<amount> to the image. If I<subtype> is
448 zero, the noise is even to each channel, otherwise noise is added to
449 each channel independently.
452 $img->filter(type=>"noise", amount=>20, subtype=>0)
456 $img->filter(type=>"noise", amount=>20, subtype=>1)
461 renders radiant Perlin turbulent noise. The centre of the noise is at
462 (I<xo>, I<yo>), I<ascale> controls the angular scale of the noise ,
463 and I<rscale> the radial scale, higher numbers give more detail.
465 $img->filter(type=>"radnoise", xo=>50, yo=>50,
466 ascale=>1, rscale=>0.02)
471 alters the image to have only I<levels> distinct level in each
474 $img->filter(type=>"postlevels", levels=>10)
479 renders Perlin turbulent noise. (I<xo>, I<yo>) controls the origin of
480 the noise, and I<scale> the scale of the noise, with lower numbers
483 $img->filter(type=>"turbnoise", xo=>10, yo=>10, scale=>10)
488 performs an unsharp mask on the image. This increases the contrast of
491 This is the result of subtracting a gaussian blurred version of the
492 image from the original. I<stddev> controls the stddev parameter of
493 the gaussian blur. Each output pixel is: in + I<scale> * (in -
496 $img->filter(type=>"unsharpmask", stddev=>1, scale=>0.5)
499 unsharpmark has the following parameters:
505 stddev - this is equivalent to the C<Radius> value in the GIMP's
506 unsharpmask filter. This controls the size of the contrast increase
507 around edges, larger values will remove fine detail. You should
508 probably experiement on the types of images you plan to work with.
513 scale - controls the strength of the edge enhancement, equivalent to
514 I<Amount> in the GIMP's unsharp mask filter. Default: 1.0.
520 applies I<wmark> as a watermark on the image with strength I<pixdiff>,
521 with an origin at (I<tx>, I<ty>)
523 $img->filter(type=>"watermark", tx=>10, ty=>50,
524 wmark=>$wmark_image, pixdiff=>50)
529 A demonstration of most of the filters can be found at:
531 http://www.develop-help.com/imager/filters.html
533 =head2 External Filters
535 As of Imager 0.48 you can create perl or XS based filters and hook
536 them into Imager's filter() method:
540 =item register_filter
542 Registers a filter so it is visible via Imager's filter() method.
544 Imager->register_filter(type => 'your_filter',
545 defaults => { parm1 => 'default1' },
546 callseq => [ qw/image parm1/ ],
547 callsub => \&your_filter);
548 $img->filter(type=>'your_filter', parm1 => 'something');
550 The following parameters are needed:
556 type - the type value that will be supplied to filter() to use your
561 defaults - a hash of defaults for the filter's parameters
565 callseq - a reference to an array of required parameter names.
569 callsub - a code reference called to execute your filter. The
570 parameters passed to filter() are supplied as a list of parameter
571 name, value ... which can be assigned to a hash.
573 The special parameters C<image> and C<imager> are supplied as the low
574 level image object from $self and $self itself respectively.
576 The function you supply must modify the image in place.
580 See Imager::Filter::Mandelbrot for an example.
586 The plugin interface is deprecated. Please use the Imager API, see
587 L</Imager::API> and L<External Filters> for details
589 It is possible to add filters to the module without recompiling the
590 module itself. This is done by using DSOs (Dynamic shared object)
591 avaliable on most systems. This way you can maintain our own filters
592 and not have to get me to add it, or worse patch every new version of
593 the Module. Modules can be loaded AND UNLOADED at runtime. This
594 means that you can have a server/daemon thingy that can do something
597 load_plugin("dynfilt/dyntest.so")
598 or die "unable to load plugin\n";
600 $img->filter(type=>'lin_stretch', a=>35, b=>200);
602 unload_plugin("dynfilt/dyntest.so")
603 or die "unable to load plugin\n";
605 Someone decides that the filter is not working as it should -
606 dyntest.c modified and recompiled.
608 load_plugin("dynfilt/dyntest.so")
609 or die "unable to load plugin\n";
613 An example plugin comes with the module - Please send feedback to
614 addi@umich.edu if you test this.
616 Note: This seems to test ok on the following systems:
617 Linux, Solaris, HPUX, OpenBSD, FreeBSD, TRU64/OSF1, AIX.
618 If you test this on other systems please let me know.
624 This is a function, not a method, exported by default. You should
625 import this function explicitly for future compatibility if you need
628 Accepts a single parameter, the name of a shared library file to load.
630 Returns true on success. Check Imager->errstr on failure.
634 This is a function, not a method, which is exported by default. You
635 should import this function explicitly for future compatibility if you
638 Accepts a single parameter, the name of a shared library to unload.
639 This library must have been previously loaded by load_plugin().
641 Returns true on success. Check Imager->errstr on failure.
645 =head2 Image Difference
651 You can create a new image that is the difference between 2 other images.
653 my $diff = $img->difference(other=>$other_img);
655 For each pixel in $img that is different to the pixel in $other_img,
656 the pixel from $other_img is given, otherwise the pixel is transparent
659 This can be used for debugging image differences ("Where are they
660 different?"), and for optimizing animated GIFs.
662 Note that $img and $other_img must have the same number of channels.
663 The width and height of $diff will be the minimum of each of the width
664 and height of $img and $other_img.
672 other - the other image object to compare against
676 mindist - the difference between corresponding samples must be greater
677 than I<mindist> for the pixel to be considered different. So a value
678 of zero returns all different pixels, not all pixels. Range: 0 to 255
679 inclusive. Default: 0.
681 For large sample images this is scaled down to the range 0 .. 1.
689 Arnar M. Hrafnkelsson, Tony Cook <tony@imager.perl.org>.
693 Imager, Imager::Filter::Flines, Imager::Filter::Mandelbrot