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 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 A reference of the filters follows:
 107
 108 =over
 109
 110 =item autolevels
 111
 112 scales the value of each channel so that the values in the image will
 113 cover the whole possible range for the channel.  I<lsat> and I<usat>
 114 truncate the range by the specified fraction at the top and bottom of
 115 the range respectivly.
 116
 117   # increase contrast, losing little detail
 118   my $levels = $img->filter(type=>"autolevels");
 119
 120   # increase contrast, losing 20% of highlight at top and bottom range
 121   my $trunc_levels = $img->filter(type=>"autolevels", lsat=>0.2, usat=>0.2);
 122
 123 =item bumpmap
 124
 125 uses the channel I<elevation> image I<bump> as a bumpmap on your
 126 image, with the light at (I<lightx>, I<lightty>), with a shadow length
 127 of I<st>.
 128
 129   my $shadowed = $img->filter(type=>"bumpmap", bump=>$bumpmap_img,
 130                               lightx=>10, lighty=>10, st=>5);
 131
 132 =item bumpmap_complex
 133
 134 uses the channel I<channel> image I<bump> as a bumpmap on your image.
 135 If Lz<0 the three L parameters are considered to be the direction of
 136 the light.  If Lz>0 the L parameters are considered to be the light
 137 position.  I<Ia> is the ambient colour, I<Il> is the light colour,
 138 I<Is> is the color of specular highlights.  I<cd> is the diffuse
 139 coefficient and I<cs> is the specular coefficient.  I<n> is the
 140 shininess of the surface.
 141
 142   my $shadowed = $img->filter(type=>"bumpmap_complex", bump=>$bumpmap_img);
 143
 144 =item contrast
 145
 146 scales each channel by I<intensity>.  Values of I<intensity> < 1.0
 147 will reduce the contrast.
 148
 149   my $high_contrast = $img->filter(type=>"contrast", intensity=>1.3);
 150   my $low_contrast = $img->filter(type=>"contrast", intensity=>0.8);
 151
 152 =item conv
 153
 154 performs 2 1-dimensional convolutions on the image using the values
 155 from I<coef>.  I<coef> should be have an odd length and the sum of the
 156 coefficients must be non-zero.
 157
 158   my $sharper = $img->filter(type=>"conv", coef=>[-0.5, 2, -0.5 ]);
 159   my $blur = $img->filter(type=>"conv", coef=>[ 1, 2, 1 ]);
 160
 161 =item fountain
 162
 163 renders a fountain fill, similar to the gradient tool in most paint
 164 software.  The default fill is a linear fill from opaque black to
 165 opaque white.  The points A(xa, ya) and B(xb, yb) control the way the
 166 fill is performed, depending on the ftype parameter:
 167
 168 =over
 169
 170 =item linear
 171
 172 the fill ramps from A through to B.
 173
 174 =item bilinear
 175
 176 the fill ramps in both directions from A, where AB defines the length
 177 of the gradient.
 178
 179 =item radial
 180
 181 A is the center of a circle, and B is a point on it's circumference.
 182 The fill ramps from the center out to the circumference.
 183
 184 =item radial_square
 185
 186 A is the center of a square and B is the center of one of it's sides.
 187 This can be used to rotate the square.  The fill ramps out to the
 188 edges of the square.
 189
 190 =item revolution
 191
 192 A is the centre of a circle and B is a point on it's circumference.  B
 193 marks the 0 and 360 point on the circle, with the fill ramping
 194 clockwise.
 195
 196 =item conical
 197
 198 A is the center of a circle and B is a point on it's circumference.  B
 199 marks the 0 and point on the circle, with the fill ramping in both
 200 directions to meet opposite.
 201
 202 =back
 203
 204 The I<repeat> option controls how the fill is repeated for some
 205 I<ftype>s after it leaves the AB range:
 206
 207 =over
 208
 209 =item none
 210
 211 no repeats, points outside of each range are treated as if they were
 212 on the extreme end of that range.
 213
 214 =item sawtooth
 215
 216 the fill simply repeats in the positive direction
 217
 218 =item triangle
 219
 220 the fill repeats in reverse and then forward and so on, in the
 221 positive direction
 222
 223 =item saw_both
 224
 225 the fill repeats in both the positive and negative directions (only
 226 meaningful for a linear fill).
 227
 228 =item tri_both
 229
 230 as for triangle, but in the negative direction too (only meaningful
 231 for a linear fill).
 232
 233 =back
 234
 235 By default the fill simply overwrites the whole image (unless you have
 236 parts of the range 0 through 1 that aren't covered by a segment), if
 237 any segments of your fill have any transparency, you can set the
 238 I<combine> option to 'normal' to have the fill combined with the
 239 existing pixels.  See the description of I<combine> in L<Imager::Fill>.
 240
 241 If your fill has sharp edges, for example between steps if you use
 242 repeat set to 'triangle', you may see some aliased or ragged edges.
 243 You can enable super-sampling which will take extra samples within the
 244 pixel in an attempt anti-alias the fill.
 245
 246 The possible values for the super_sample option are:
 247
 248 =over
 249
 250 =item none
 251
 252 no super-sampling is done
 253
 254 =item grid
 255
 256 a square grid of points are sampled.  The number of points sampled is
 257 the square of ceil(0.5 + sqrt(ssample_param)).
 258
 259 =item random
 260
 261 a random set of points within the pixel are sampled.  This looks
 262 pretty bad for low ssample_param values.
 263
 264 =item circle
 265
 266 the points on the radius of a circle within the pixel are sampled.
 267 This seems to produce the best results, but is fairly slow (for now).
 268
 269 =back
 270
 271 You can control the level of sampling by setting the ssample_param
 272 option.  This is roughly the number of points sampled, but depends on
 273 the type of sampling.
 274
 275 The segments option is an arrayref of segments.  You really should use
 276 the L<Imager::Fountain> class to build your fountain fill.  Each
 277 segment is an array ref containing:
 278
 279 =over
 280
 281 =item start
 282
 283 a floating point number between 0 and 1, the start of the range of
 284 fill parameters covered by this segment.
 285
 286 =item middle
 287
 288 a floating point number between start and end which can be used to
 289 push the color range towards one end of the segment.
 290
 291 =item end
 292
 293 a floating point number between 0 and 1, the end of the range of fill
 294 parameters covered by this segment.  This should be greater than
 295 start.
 296
 297 =item c0
 298
 299 =item c1
 300
 301 The colors at each end of the segment.  These can be either
 302 Imager::Color or Imager::Color::Float objects.
 303
 304 =item segment type
 305
 306 The type of segment, this controls the way the fill parameter varies
 307 over the segment. 0 for linear, 1 for curved (unimplemented), 2 for
 308 sine, 3 for sphere increasing, 4 for sphere decreasing.
 309
 310 =item color type
 311
 312 The way the color varies within the segment, 0 for simple RGB, 1 for
 313 hue increasing and 2 for hue decreasing.
 314
 315 =back
 316
 317 Don't forget to use Imager::Fountain instead of building your own.
 318 Really.  It even loads GIMP gradient files.
 319
 320 =item gaussian
 321
 322 performs a gaussian blur of the image, using I<stddev> as the standard
 323 deviation of the curve used to combine pixels, larger values give
 324 bigger blurs.  For a definition of Gaussian Blur, see:
 325
 326   http://www.maths.abdn.ac.uk/~igc/tch/mx4002/notes/node99.html
 327
 328 Values of C<stddev> around 0.5 provide a barely noticable blur, values
 329 around 5 provide a very strong blur.
 330
 331   my $slight_blur = $img->filter(type=>"gaussian", stddev=>0.5);
 332   my $blurry      = $img->filter(type=>"gaussian", stddev=>5);
 333
 334 =item gradgen
 335
 336 renders a gradient, with the given I<colors> at the corresponding
 337 points (x,y) in I<xo> and I<yo>.  You can specify the way distance is
 338 measured for color blending by setting I<dist> to 0 for Euclidean, 1
 339 for Euclidean squared, and 2 for Manhattan distance.
 340
 341   my $redbluegreen = $img->filter
 342     (type="gradgen", xo=>[ 10, 50, 10 ], yo=>[ 10, 50, 50 ],
 343      colors=>[ qw(red blue green) ]);
 344
 345 =item hardinvert
 346
 347 inverts the image, black to white, white to black.  All channels are
 348 inverted, including the alpha channel if any.
 349
 350   my $inverted = $img->filter(type=>"hardinvert");
 351
 352 =item mosaic
 353
 354 produces averaged tiles of the given I<size>.
 355
 356   my $mosaic = $img->filter(type=>"mosaic", size=>5);
 357
 358 =item noise
 359
 360 adds noise of the given I<amount> to the image.  If I<subtype> is
 361 zero, the noise is even to each channel, otherwise noise is added to
 362 each channel independently.
 363
 364   my $mono_noise = $img->filter(type=>"noise", amount=>20, subtype=>0);
 365   my $color_noise = $img->filter(type=>"noise", amount=>20, subtype=>1);
 366
 367 =item radnoise
 368
 369 renders radiant Perlin turbulent noise.  The centre of the noise is at
 370 (I<xo>, I<yo>), I<ascale> controls the angular scale of the noise ,
 371 and I<rscale> the radial scale, higher numbers give more detail.
 372
 373   my $radial_noise = $img->filter(type=>"radnoise", xo=>50, yo=>50,
 374                                   ascale=>1, rscale=>0.02);
 375
 376 =item postlevels
 377
 378 alters the image to have only I<levels> distinct level in each
 379 channel.
 380
 381   my $posted = $img->filter(type=>"postlevels", levels=>10);
 382
 383 =item turbnoise
 384
 385 renders Perlin turbulent noise.  (I<xo>, I<yo>) controls the origin of
 386 the noise, and I<scale> the scale of the noise, with lower numbers
 387 giving more detail.
 388
 389   my $noise = $img->filter(type=>"turbnoise", xo=>10, yo=>10, scale=>10);
 390
 391 =item unsharpmask
 392
 393 performs an unsharp mask on the image.  This is the result of
 394 subtracting a gaussian blurred version of the image from the original.
 395 I<stddev> controls the stddev parameter of the gaussian blur.  Each
 396 output pixel is: in + I<scale> * (in - blurred).
 397
 398   my $unsharp = $img->filter(type=>"unsharpmask", stddev=>1, scale=>0.5);
 399
 400 =item watermark
 401
 402 applies I<wmark> as a watermark on the image with strength I<pixdiff>,
 403 with an origin at (I<tx>, I<ty>)
 404
 405   my $marked = $img->filter(type=>"watermark", tx=>10, ty=>50,
 406                             wmark=>$wmark_image, pixdiff=>50);
 407
 408 =back
 409
 410 A demonstration of most of the filters can be found at:
 411
 412   http://www.develop-help.com/imager/filters.html
 413
 414 (This is a slow link.)
 415
 416
 417 =head2 Plugins
 418
 419 It is possible to add filters to the module without recompiling the
 420 module itself.  This is done by using DSOs (Dynamic shared object)
 421 avaliable on most systems.  This way you can maintain our own filters
 422 and not have to get me to add it, or worse patch every new version of
 423 the Module.  Modules can be loaded AND UNLOADED at runtime.  This
 424 means that you can have a server/daemon thingy that can do something
 425 like:
 426
 427   load_plugin("dynfilt/dyntest.so")
 428     or die "unable to load plugin\n";
 429
 430   $img->filter(type=>'lin_stretch', a=>35, b=>200);
 431
 432   unload_plugin("dynfilt/dyntest.so")
 433     or die "unable to load plugin\n";
 434
 435 Someone decides that the filter is not working as it should -
 436 dyntest.c modified and recompiled.
 437
 438   load_plugin("dynfilt/dyntest.so")
 439     or die "unable to load plugin\n";
 440
 441   $img->filter(%hsh);
 442
 443 An example plugin comes with the module - Please send feedback to
 444 addi@umich.edu if you test this.
 445
 446 Note: This seems to test ok on the following systems:
 447 Linux, Solaris, HPUX, OpenBSD, FreeBSD, TRU64/OSF1, AIX.
 448 If you test this on other systems please let me know.
 449
 450 =head2 Image Difference
 451
 452 You can create a new image that is the difference between 2 other images.
 453
 454   my $diff = $img->difference(other=>$other_img);
 455
 456 For each pixel in $img that is different to the pixel in $other_img,
 457 the pixel from $other_img is given, otherwise the pixel is transparent
 458 black.
 459
 460 This can be used for debugging image differences ("Where are they
 461 different?"), and for optimizing animated GIFs.
 462
 463 Note that $img and $other_img must have the same number of channels.
 464 The width and heigh of $diff will be the minimum of each of the width
 465 and height of $img and $other_img.
 466
 467 =cut