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