lib/Imager/Filters.pod

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