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
  26 =head1 DESCRIPTION
  27
  28 Filters are operations that have similar calling interface.
  29
  30 =head2 Types of Filters
  31
  32 Here is a list of the filters that are always avaliable in Imager.
  33 This list can be obtained by running the C<filterlist.perl> script
  34 that comes with the module source.
  35
  36   Filter          Arguments   Default value
  37   autolevels      lsat        0.1
  38                   usat        0.1
  39                   skew        0
  40
  41   bumpmap         bump lightx lighty
  42                   elevation   0
  43                   st          2
  44
  45   bumpmap_complex bump
  46                   channel     0
  47                   tx          0
  48                   ty          0
  49                   Lx          0.2
  50                   Ly          0.4
  51                   Lz          -1
  52                   cd          1.0
  53                   cs          40.0
  54                   n           1.3
  55                   Ia          (0 0 0)
  56                   Il          (255 255 255)
  57                   Is          (255 255 255)
  58
  59   contrast        intensity
  60
  61   conv            coef
  62
  63   fountain        xa ya xb yb
  64                   ftype        linear
  65                   repeat       none
  66                   combine      none
  67                   super_sample none
  68                   ssample_param 4
  69                   segments(see below)
  70
  71   gaussian        stddev
  72
  73   gradgen         xo yo colors dist
  74
  75   hardinvert
  76
  77   mosaic          size         20
  78
  79   noise           amount       3
  80                   subtype      0
  81
  82   postlevels      levels       10
  83
  84   radnoise        xo           100
  85                   yo           100
  86                   ascale       17.0
  87                   rscale       0.02
  88
  89   turbnoise       xo           0.0
  90                   yo           0.0
  91                   scale        10.0
  92
  93   unsharpmask     stddev       2.0
  94                   scale        1.0
  95
  96   watermark       wmark
  97                   pixdiff      10
  98                   tx           0
  99                   ty           0
 100
 101 All parameters must have some value but if a parameter has a default
 102 value it may be omitted when calling the filter function.
 103
 104 A reference of the filters follows:
 105
 106 =over
 107
 108 =item autolevels
 109
 110 scales the value of each channel so that the values in the image will
 111 cover the whole possible range for the channel.  I<lsat> and I<usat>
 112 truncate the range by the specified fraction at the top and bottom of
 113 the range respectivly.
 114
 115 =item bumpmap
 116
 117 uses the channel I<elevation> image I<bump> as a bumpmap on your
 118 image, with the light at (I<lightx>, I<lightty>), with a shadow length
 119 of I<st>.
 120
 121 =item bumpmap_complex
 122
 123 uses the channel I<channel> image I<bump> as a bumpmap on your image.
 124 If Lz<0 the three L parameters are considered to be the direction of
 125 the light.  If Lz>0 the L parameters are considered to be the light
 126 position.  I<Ia> is the ambient colour, I<Il> is the light colour,
 127 I<Is> is the color of specular highlights.  I<cd> is the diffuse
 128 coefficient and I<cs> is the specular coefficient.  I<n> is the
 129 shininess of the surface.
 130
 131 =item contrast
 132
 133 scales each channel by I<intensity>.  Values of I<intensity> < 1.0
 134 will reduce the contrast.
 135
 136 =item conv
 137
 138 performs 2 1-dimensional convolutions on the image using the values
 139 from I<coef>.  I<coef> should be have an odd length.
 140
 141 =item fountain
 142
 143 renders a fountain fill, similar to the gradient tool in most paint
 144 software.  The default fill is a linear fill from opaque black to
 145 opaque white.  The points A(xa, ya) and B(xb, yb) control the way the
 146 fill is performed, depending on the ftype parameter:
 147
 148 =over
 149
 150 =item linear
 151
 152 the fill ramps from A through to B.
 153
 154 =item bilinear
 155
 156 the fill ramps in both directions from A, where AB defines the length
 157 of the gradient.
 158
 159 =item radial
 160
 161 A is the center of a circle, and B is a point on it's circumference.
 162 The fill ramps from the center out to the circumference.
 163
 164 =item radial_square
 165
 166 A is the center of a square and B is the center of one of it's sides.
 167 This can be used to rotate the square.  The fill ramps out to the
 168 edges of the square.
 169
 170 =item revolution
 171
 172 A is the centre of a circle and B is a point on it's circumference.  B
 173 marks the 0 and 360 point on the circle, with the fill ramping
 174 clockwise.
 175
 176 =item conical
 177
 178 A is the center of a circle and B is a point on it's circumference.  B
 179 marks the 0 and point on the circle, with the fill ramping in both
 180 directions to meet opposite.
 181
 182 =back
 183
 184 The I<repeat> option controls how the fill is repeated for some
 185 I<ftype>s after it leaves the AB range:
 186
 187 =over
 188
 189 =item none
 190
 191 no repeats, points outside of each range are treated as if they were
 192 on the extreme end of that range.
 193
 194 =item sawtooth
 195
 196 the fill simply repeats in the positive direction
 197
 198 =item triangle
 199
 200 the fill repeats in reverse and then forward and so on, in the
 201 positive direction
 202
 203 =item saw_both
 204
 205 the fill repeats in both the positive and negative directions (only
 206 meaningful for a linear fill).
 207
 208 =item tri_both
 209
 210 as for triangle, but in the negative direction too (only meaningful
 211 for a linear fill).
 212
 213 =back
 214
 215 By default the fill simply overwrites the whole image (unless you have
 216 parts of the range 0 through 1 that aren't covered by a segment), if
 217 any segments of your fill have any transparency, you can set the
 218 I<combine> option to 'normal' to have the fill combined with the
 219 existing pixels.  See the description of I<combine> in L<Imager/Fill>.
 220
 221 If your fill has sharp edges, for example between steps if you use
 222 repeat set to 'triangle', you may see some aliased or ragged edges.
 223 You can enable super-sampling which will take extra samples within the
 224 pixel in an attempt anti-alias the fill.
 225
 226 The possible values for the super_sample option are:
 227
 228 =over
 229
 230 =item none
 231
 232 no super-sampling is done
 233
 234 =item grid
 235
 236 a square grid of points are sampled.  The number of points sampled is
 237 the square of ceil(0.5 + sqrt(ssample_param)).
 238
 239 =item random
 240
 241 a random set of points within the pixel are sampled.  This looks
 242 pretty bad for low ssample_param values.
 243
 244 =item circle
 245
 246 the points on the radius of a circle within the pixel are sampled.
 247 This seems to produce the best results, but is fairly slow (for now).
 248
 249 =back
 250
 251 You can control the level of sampling by setting the ssample_param
 252 option.  This is roughly the number of points sampled, but depends on
 253 the type of sampling.
 254
 255 The segments option is an arrayref of segments.  You really should use
 256 the Imager::Fountain class to build your fountain fill.  Each segment
 257 is an array ref containing:
 258
 259 =over
 260
 261 =item start
 262
 263 a floating point number between 0 and 1, the start of the range of fill parameters covered by this segment.
 264
 265 =item middle
 266
 267 a floating point number between start and end which can be used to
 268 push the color range towards one end of the segment.
 269
 270 =item end
 271
 272 a floating point number between 0 and 1, the end of the range of fill
 273 parameters covered by this segment.  This should be greater than
 274 start.
 275
 276 =item c0
 277
 278 =item c1
 279
 280 The colors at each end of the segment.  These can be either
 281 Imager::Color or Imager::Color::Float objects.
 282
 283 =item segment type
 284
 285 The type of segment, this controls the way the fill parameter varies
 286 over the segment. 0 for linear, 1 for curved (unimplemented), 2 for
 287 sine, 3 for sphere increasing, 4 for sphere decreasing.
 288
 289 =item color type
 290
 291 The way the color varies within the segment, 0 for simple RGB, 1 for
 292 hue increasing and 2 for hue decreasing.
 293
 294 =back
 295
 296 Don't forget to use Imager::Fountain instead of building your own.
 297 Really.  It even loads GIMP gradient files.
 298
 299 =item gaussian
 300
 301 performs a gaussian blur of the image, using I<stddev> as the standard
 302 deviation of the curve used to combine pixels, larger values give
 303 bigger blurs.  For a definition of Gaussian Blur, see:
 304
 305   http://www.maths.abdn.ac.uk/~igc/tch/mx4002/notes/node99.html
 306
 307 =item gradgen
 308
 309 renders a gradient, with the given I<colors> at the corresponding
 310 points (x,y) in I<xo> and I<yo>.  You can specify the way distance is
 311 measured for color blendeing by setting I<dist> to 0 for Euclidean, 1
 312 for Euclidean squared, and 2 for Manhattan distance.
 313
 314 =item hardinvert
 315
 316 inverts the image, black to white, white to black.  All channels are
 317 inverted, including the alpha channel if any.
 318
 319 =item mosaic
 320
 321 produces averaged tiles of the given I<size>.
 322
 323 =item noise
 324
 325 adds noise of the given I<amount> to the image.  If I<subtype> is
 326 zero, the noise is even to each channel, otherwise noise is added to
 327 each channel independently.
 328
 329 =item radnoise
 330
 331 renders radiant Perlin turbulent noise.  The centre of the noise is at
 332 (I<xo>, I<yo>), I<ascale> controls the angular scale of the noise ,
 333 and I<rscale> the radial scale, higher numbers give more detail.
 334
 335 =item postlevels
 336
 337 alters the image to have only I<levels> distinct level in each
 338 channel.
 339
 340 =item turbnoise
 341
 342 renders Perlin turbulent noise.  (I<xo>, I<yo>) controls the origin of
 343 the noise, and I<scale> the scale of the noise, with lower numbers
 344 giving more detail.
 345
 346 =item unsharpmask
 347
 348 performs an unsharp mask on the image.  This is the result of
 349 subtracting a gaussian blurred version of the image from the original.
 350 I<stddev> controls the stddev parameter of the gaussian blur.  Each
 351 output pixel is: in + I<scale> * (in - blurred).
 352
 353 =item watermark
 354
 355 applies I<wmark> as a watermark on the image with strength I<pixdiff>,
 356 with an origin at (I<tx>, I<ty>)
 357
 358 =back
 359
 360 A demonstration of most of the filters can be found at:
 361
 362   http://www.develop-help.com/imager/filters.html
 363
 364 (This is a slow link.)
 365
 366
 367 =head2 Plugins
 368
 369 It is possible to add filters to the module without recompiling the
 370 module itself.  This is done by using DSOs (Dynamic shared object)
 371 avaliable on most systems.  This way you can maintain our own filters
 372 and not have to get me to add it, or worse patch every new version of
 373 the Module.  Modules can be loaded AND UNLOADED at runtime.  This
 374 means that you can have a server/daemon thingy that can do something
 375 like:
 376
 377   load_plugin("dynfilt/dyntest.so")
 378     or die "unable to load plugin\n";
 379
 380   $img->filter(type=>'lin_stretch', a=>35, b=>200);
 381
 382   unload_plugin("dynfilt/dyntest.so")
 383     or die "unable to load plugin\n";
 384
 385 Someone decides that the filter is not working as it should -
 386 dyntest.c modified and recompiled.
 387
 388   load_plugin("dynfilt/dyntest.so")
 389     or die "unable to load plugin\n";
 390
 391   $img->filter(%hsh);
 392
 393 An example plugin comes with the module - Please send feedback to
 394 addi@umich.edu if you test this.
 395
 396 Note: This seems to test ok on the following systems:
 397 Linux, Solaris, HPUX, OpenBSD, FreeBSD, TRU64/OSF1, AIX.
 398 If you test this on other systems please let me know.
 399
 400
 401 =cut