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