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