]>
Commit | Line | Data |
---|---|---|
f0db69bf AMH |
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 | ||
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 | ||
29 | Filters are operations that have similar calling interface. | |
30 | ||
58a9ba58 TC |
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 | ||
f0db69bf AMH |
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 | ||
b78eba79 TC |
94 | gradgen xo yo colors |
95 | dist 0 | |
f0db69bf AMH |
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 | ||
b692658a TC |
126 | Every one of these filters modifies the image in place. |
127 | ||
f0db69bf AMH |
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 | ||
6e85a9ac | 139 | # increase contrast per channel, losing little detail |
b692658a TC |
140 | $img->filter(type=>"autolevels") |
141 | or die $img->errstr; | |
b78eba79 TC |
142 | |
143 | # increase contrast, losing 20% of highlight at top and bottom range | |
b692658a TC |
144 | $img->filter(type=>"autolevels", lsat=>0.2, usat=>0.2) |
145 | or die $img->errstr; | |
b78eba79 | 146 | |
f0db69bf AMH |
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 | ||
b692658a TC |
153 | $img->filter(type=>"bumpmap", bump=>$bumpmap_img, |
154 | lightx=>10, lighty=>10, st=>5) | |
155 | or die $img->errstr; | |
b78eba79 | 156 | |
f0db69bf AMH |
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 | ||
b692658a TC |
167 | $img->filter(type=>"bumpmap_complex", bump=>$bumpmap_img) |
168 | or die $img->errstr; | |
b78eba79 | 169 | |
f0db69bf AMH |
170 | =item contrast |
171 | ||
172 | scales each channel by I<intensity>. Values of I<intensity> < 1.0 | |
173 | will reduce the contrast. | |
174 | ||
b692658a TC |
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; | |
b78eba79 | 182 | |
f0db69bf AMH |
183 | =item conv |
184 | ||
185 | performs 2 1-dimensional convolutions on the image using the values | |
b78eba79 TC |
186 | from I<coef>. I<coef> should be have an odd length and the sum of the |
187 | coefficients must be non-zero. | |
188 | ||
b692658a TC |
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; | |
f0db69bf AMH |
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 | |
b78eba79 | 275 | existing pixels. See the description of I<combine> in L<Imager::Fill>. |
f0db69bf AMH |
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 | |
b78eba79 TC |
312 | the L<Imager::Fountain> class to build your fountain fill. Each |
313 | segment is an array ref containing: | |
f0db69bf AMH |
314 | |
315 | =over | |
316 | ||
317 | =item start | |
318 | ||
b78eba79 TC |
319 | a floating point number between 0 and 1, the start of the range of |
320 | fill parameters covered by this segment. | |
f0db69bf AMH |
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 | ||
b692658a TC |
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 | ||
f0db69bf AMH |
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 | ||
b78eba79 TC |
400 | Values of C<stddev> around 0.5 provide a barely noticable blur, values |
401 | around 5 provide a very strong blur. | |
402 | ||
b692658a TC |
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; | |
b78eba79 | 410 | |
f0db69bf AMH |
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 | |
b78eba79 | 415 | measured for color blending by setting I<dist> to 0 for Euclidean, 1 |
f0db69bf AMH |
416 | for Euclidean squared, and 2 for Manhattan distance. |
417 | ||
b692658a TC |
418 | $img->filter(type="gradgen", |
419 | xo=>[ 10, 50, 10 ], | |
420 | yo=>[ 10, 50, 50 ], | |
421 | colors=>[ qw(red blue green) ]); | |
b78eba79 | 422 | |
f0db69bf AMH |
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 | ||
b692658a TC |
428 | $img->filter(type=>"hardinvert") |
429 | or die $img->errstr; | |
b78eba79 | 430 | |
f0db69bf AMH |
431 | =item mosaic |
432 | ||
433 | produces averaged tiles of the given I<size>. | |
434 | ||
b692658a TC |
435 | $img->filter(type=>"mosaic", size=>5) |
436 | or die $img->errstr; | |
b78eba79 | 437 | |
f0db69bf AMH |
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 | ||
b692658a TC |
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; | |
b78eba79 | 451 | |
f0db69bf AMH |
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 | ||
b692658a TC |
458 | $img->filter(type=>"radnoise", xo=>50, yo=>50, |
459 | ascale=>1, rscale=>0.02) | |
460 | or die $img->errstr; | |
b78eba79 | 461 | |
f0db69bf AMH |
462 | =item postlevels |
463 | ||
464 | alters the image to have only I<levels> distinct level in each | |
465 | channel. | |
466 | ||
b692658a TC |
467 | $img->filter(type=>"postlevels", levels=>10) |
468 | or die $img->errstr; | |
b78eba79 | 469 | |
f0db69bf AMH |
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 | ||
b692658a TC |
476 | $img->filter(type=>"turbnoise", xo=>10, yo=>10, scale=>10) |
477 | or die $img->errstr; | |
b78eba79 | 478 | |
f0db69bf AMH |
479 | =item unsharpmask |
480 | ||
fcd96ade TC |
481 | performs an unsharp mask on the image. This increases the contrast of |
482 | edges in the image. | |
483 | ||
484 | This is the result of subtracting a gaussian blurred version of the | |
485 | image from the original. I<stddev> controls the stddev parameter of | |
486 | the gaussian blur. Each output pixel is: in + I<scale> * (in - | |
487 | blurred). | |
f0db69bf | 488 | |
b692658a TC |
489 | $img->filter(type=>"unsharpmask", stddev=>1, scale=>0.5) |
490 | or die $img->errstr; | |
b78eba79 | 491 | |
42feef3b TC |
492 | unsharpmark has the following parameters: |
493 | ||
494 | =over | |
495 | ||
496 | =item * | |
497 | ||
fcd96ade TC |
498 | stddev - this is equivalent to the C<Radius> value in the GIMP's |
499 | unsharpmask filter. This controls the size of the contrast increase | |
500 | around edges, larger values will remove fine detail. You should | |
501 | probably experiement on the types of images you plan to work with. | |
502 | Default: 2.0. | |
42feef3b TC |
503 | |
504 | =item * | |
505 | ||
fcd96ade TC |
506 | scale - controls the strength of the edge enhancement, equivalent to |
507 | I<Amount> in the GIMP's unsharp mask filter. Default: 1.0. | |
42feef3b TC |
508 | |
509 | =back | |
510 | ||
f0db69bf AMH |
511 | =item watermark |
512 | ||
513 | applies I<wmark> as a watermark on the image with strength I<pixdiff>, | |
514 | with an origin at (I<tx>, I<ty>) | |
515 | ||
b692658a TC |
516 | $img->filter(type=>"watermark", tx=>10, ty=>50, |
517 | wmark=>$wmark_image, pixdiff=>50) | |
518 | or die $img->errstr; | |
b78eba79 | 519 | |
f0db69bf AMH |
520 | =back |
521 | ||
522 | A demonstration of most of the filters can be found at: | |
523 | ||
524 | http://www.develop-help.com/imager/filters.html | |
525 | ||
7327d4b0 | 526 | =head2 External Filters |
f0db69bf | 527 | |
7327d4b0 TC |
528 | As of Imager 0.48 you can create perl or XS based filters and hook |
529 | them into Imager's filter() method: | |
530 | ||
531 | =over | |
532 | ||
533 | =item register_filter | |
534 | ||
535 | Registers a filter so it is visible via Imager's filter() method. | |
536 | ||
537 | Imager->register_filter(type => 'your_filter', | |
538 | defaults => { parm1 => 'default1' }, | |
539 | callseq => [ qw/image parm1/ ], | |
540 | callsub => \&your_filter); | |
541 | $img->filter(type=>'your_filter', parm1 => 'something'); | |
542 | ||
543 | The following parameters are needed: | |
544 | ||
545 | =over | |
546 | ||
547 | =item * | |
548 | ||
549 | type - the type value that will be supplied to filter() to use your | |
550 | filter. | |
551 | ||
552 | =item * | |
553 | ||
554 | defaults - a hash of defaults for the filter's parameters | |
555 | ||
556 | =item * | |
557 | ||
558 | callseq - a reference to an array of required parameter names. | |
559 | ||
560 | =item * | |
561 | ||
562 | callsub - a code reference called to execute your filter. The | |
563 | parameters passed to filter() are supplied as a list of parameter | |
564 | name, value ... which can be assigned to a hash. | |
565 | ||
566 | The special parameters C<image> and C<imager> are supplied as the low | |
567 | level image object from $self and $self itself respectively. | |
568 | ||
569 | The function you supply must modify the image in place. | |
570 | ||
571 | =back | |
572 | ||
573 | See Imager::Filter::Mandelbrot for an example. | |
574 | ||
575 | =back | |
f0db69bf AMH |
576 | |
577 | =head2 Plugins | |
578 | ||
7327d4b0 | 579 | The plugin interface is deprecated. Please use the Imager API, see |
a86b1794 | 580 | L</Imager::API> and L<External Filters> for details |
7327d4b0 | 581 | |
f0db69bf AMH |
582 | It is possible to add filters to the module without recompiling the |
583 | module itself. This is done by using DSOs (Dynamic shared object) | |
584 | avaliable on most systems. This way you can maintain our own filters | |
585 | and not have to get me to add it, or worse patch every new version of | |
586 | the Module. Modules can be loaded AND UNLOADED at runtime. This | |
587 | means that you can have a server/daemon thingy that can do something | |
588 | like: | |
589 | ||
590 | load_plugin("dynfilt/dyntest.so") | |
591 | or die "unable to load plugin\n"; | |
592 | ||
593 | $img->filter(type=>'lin_stretch', a=>35, b=>200); | |
594 | ||
595 | unload_plugin("dynfilt/dyntest.so") | |
596 | or die "unable to load plugin\n"; | |
597 | ||
598 | Someone decides that the filter is not working as it should - | |
599 | dyntest.c modified and recompiled. | |
600 | ||
601 | load_plugin("dynfilt/dyntest.so") | |
602 | or die "unable to load plugin\n"; | |
603 | ||
604 | $img->filter(%hsh); | |
605 | ||
606 | An example plugin comes with the module - Please send feedback to | |
607 | addi@umich.edu if you test this. | |
608 | ||
609 | Note: This seems to test ok on the following systems: | |
610 | Linux, Solaris, HPUX, OpenBSD, FreeBSD, TRU64/OSF1, AIX. | |
611 | If you test this on other systems please let me know. | |
612 | ||
58a9ba58 TC |
613 | =over |
614 | ||
615 | =item load_plugin | |
616 | ||
617 | This is a function, not a method, exported by default. You should | |
618 | import this function explicitly for future compatibility if you need | |
619 | it. | |
620 | ||
621 | Accepts a single parameter, the name of a shared library file to load. | |
622 | ||
623 | Returns true on success. Check Imager->errstr on failure. | |
624 | ||
625 | =item unload_plugin | |
626 | ||
627 | This is a function, not a method, which is exported by default. You | |
628 | should import this function explicitly for future compatibility if you | |
629 | need it. | |
630 | ||
631 | Accepts a single parameter, the name of a shared library to unload. | |
632 | This library must have been previously loaded by load_plugin(). | |
633 | ||
634 | Returns true on success. Check Imager->errstr on failure. | |
635 | ||
636 | =back | |
637 | ||
dff75dee TC |
638 | =head2 Image Difference |
639 | ||
58a9ba58 TC |
640 | =over |
641 | ||
642 | =item difference | |
643 | ||
dff75dee TC |
644 | You can create a new image that is the difference between 2 other images. |
645 | ||
646 | my $diff = $img->difference(other=>$other_img); | |
647 | ||
648 | For each pixel in $img that is different to the pixel in $other_img, | |
649 | the pixel from $other_img is given, otherwise the pixel is transparent | |
650 | black. | |
651 | ||
652 | This can be used for debugging image differences ("Where are they | |
653 | different?"), and for optimizing animated GIFs. | |
654 | ||
655 | Note that $img and $other_img must have the same number of channels. | |
01b84320 | 656 | The width and height of $diff will be the minimum of each of the width |
dff75dee | 657 | and height of $img and $other_img. |
f0db69bf | 658 | |
01b84320 TC |
659 | Parameters: |
660 | ||
661 | =over | |
662 | ||
663 | =item * | |
664 | ||
665 | other - the other image object to compare against | |
666 | ||
667 | =item * | |
668 | ||
669 | mindist - the difference between corresponding samples must be greater | |
670 | than I<mindist> for the pixel to be considered different. So a value | |
671 | of zero returns all different pixels, not all pixels. Range: 0 to 255 | |
672 | inclusive. Default: 0. | |
673 | ||
674 | For large sample images this is scaled down to the range 0 .. 1. | |
675 | ||
676 | =back | |
677 | ||
58a9ba58 TC |
678 | =back |
679 | ||
ea7b280d TC |
680 | =head1 AUTHOR |
681 | ||
682 | Arnar M. Hrafnkelsson, Tony Cook <tony@imager.perl.org>. | |
683 | ||
684 | =head1 SEE ALSO | |
685 | ||
686 | Imager, Imager::Filter::Flines, Imager::Filter::Mandelbrot | |
687 | ||
688 | =head1 REVISION | |
689 | ||
690 | $Revision$ | |
691 | ||
f0db69bf | 692 | =cut |