Various changes:
[imager.git] / lib / Imager / ImageTypes.pod
1 =head1 NAME
2
3 Imager::ImageTypes - image models for Imager
4
5 =head1 SYNOPSIS
6
7   use Imager;
8
9   $img = Imager->new(); #  Empty image (size is 0 by 0)
10   $img->open(file=>'lena.png',type=>'png'); # Read image from file
11
12   $img = Imager->new(xsize=>400, ysize=>300); # RGB data
13
14   $img = Imager->new(xsize=>400, ysize=>300,  # Grayscale
15                      channels=>1);            #
16
17   $img = Imager->new(xsize=>400, ysize=>300,  # RGB with alpha
18                      channels=>4);            #
19                                               
20   $img = Imager->new(xsize=>200, ysize=>200,  
21                      type=>'paletted');       # paletted image
22                                               
23   $img = Imager->new(xsize=>200, ysize=>200,  
24                      bits=>16);               # 16 bits/channel rgb
25                                               
26   $img = Imager->new(xsize=>200, ysize=>200,  
27                      bits=>'double');         # 'double' floating point
28                                               #  per channel
29
30   $img->img_set(xsize=>500, ysize=>500,       # reset the image object
31                 channels=>4);
32
33
34   # Example getting information about an Imager object
35
36   print "Image information:\n";
37   print "Width:        ", $img->getwidth(),    "\n";
38   print "Height:       ", $img->getheight(),   "\n";
39   print "Channels:     ", $img->getchannels(), "\n";
40   print "Bits/Channel: ", $img->bits(),        "\n";
41   print "Virtual:      ", $img->virtual() ? "Yes" : "No", "\n";
42   my $colorcount = $img->getcolorcount(maxcolors=>512);
43         print "Actual number of colors in image: ";
44   print defined($colorcount) ? $colorcount : ">512", "\n";
45   print "Type:         ", $img->type(),        "\n";
46
47   if ($img->type() eq 'direct') {
48     print "Modifiable Channels: ";
49     print join " ", map {
50       ($img->getmask() & 1<<$_) ? $_ : ()
51     } 0..$img->getchannels();
52     print "\n";
53   
54   } else {
55     # palette info
56     my $count = $img->colorcount;  
57     @colors = $img->getcolors();
58     print "Palette size: $count\n";
59     my $mx = @colors > 4 ? 4 : 0+@colors;
60     print "First $mx entries:\n";
61     for (@colors[0..$mx-1]) {
62       my @res = $_->rgba();
63       print "(", join(", ", @res[0..$img->getchannels()-1]), ")\n";
64     }
65   }
66   
67   my @tags = $img->tags();
68   if (@tags) {
69     print "Tags:\n";
70     for(@tags) {
71       print shift @$_, ": ", join " ", @$_, "\n";
72     }
73   } else {
74     print "No tags in image\n";
75   }
76   
77 =head1 DESCRIPTION
78
79 Imager supports two basic models of image:
80
81 =over
82
83 =item *
84
85 direct color - all samples are stored for every pixel.  eg. for an
86 8-bit/sample RGB image, 24 bits are stored for each pixel.
87
88 =item *
89
90 paletted - an index into a table of colors is stored for each pixel.
91
92 =back
93
94 Direct color or paletted images can have 1 to 4 samples per color
95 stored.  Imager treats these as follows:
96
97 =over
98
99 =item *
100
101 1 sample per color - grayscale image.
102
103 =item *
104
105 2 samples per color - grayscale image with alpha channel.
106
107 =item *
108
109 3 samples per color - RGB image.
110
111 =item *
112
113 4 samples per color - RGB image with alpha channel.
114
115 =back
116
117 Direct color images can have sample sizes of 8-bits per sample,
118 16-bits per sample or a double precision floating point number per
119 sample (64-bits on many systems).
120
121 Paletted images are always 8-bits/sample.
122
123 To query an existing image about it's parameters see the C<bits()>,
124 C<type()>, C<getwidth()>, C<getheight()>, C<getchannels()> and
125 C<virtual()> methods.
126
127 The coordinate system in Imager has the origin in the upper left
128 corner, see L<Imager::Draw> for details.
129
130 The alpha channel when one is present is considered unassociated -
131 ie. the color data has not been scaled by the alpha channel.  Note
132 that not all code follows this (recent) rule, but will over time.
133
134 =head2 Creating Imager Objects
135
136 =over
137
138 =item new
139
140   $img = Imager->new();
141   $img->read(file=>"alligator.ppm") or die $img->errstr;
142
143 Here C<new()> creates an empty image with width and height of zero.
144 It's only useful for creating an Imager object to call the read()
145 method on later.
146
147   %opts = (xsize=>300, ysize=>200);
148   $img = Imager->new(%opts); # create direct mode RGBA image
149   $img = Imager->new(%opts, channels=>4); # create direct mode RGBA image
150
151 The parameters for new are:
152
153 =over
154
155 =item *
156
157 C<xsize>, C<ysize> - Defines the width and height in pixels of the
158 image.  These must be positive.
159
160 If not supplied then only placeholder object is created, which can be
161 supplied to the C<read()> or C<img_set()> methods.
162
163 =item *
164
165 C<channels> - The number of channels for the image.  Default 3.  Valid
166 values are from 1 to 4.
167
168 =item *
169
170 C<bits> - The storage type for samples in the image.  Default: 8.
171 Valid values are:
172
173 =over
174
175 =item *
176
177 C<8> - One byte per sample.  256 discrete values.
178
179 =item *
180
181 C<16> - 16-bits per sample, 65536 discrete values.
182
183 =item *
184
185 C<double> - one C double per sample.
186
187 =back
188
189 Note: you can use any Imager function on any sample size image.
190
191 Paletted images always use 8 bits/sample.
192
193 =item *
194
195 C<type> - either C<'direct'> or C<'paletted'>.  Default: C<'direct'>.
196
197 Direct images store color values for each pixel.  
198
199 Paletted images keep a table of up to 256 colors called the palette,
200 each pixel is represented as an index into that table.
201
202 In most cases when working with Imager you will want to use the
203 C<direct> image type.
204
205 If you draw on a C<paletted> image with a color not in the image's
206 palette then Imager will transparently convert it to a C<direct>
207 image.
208
209 =item *
210
211 C<maxcolors> - the maximum number of colors in a paletted image.
212 Default: 256.  This must be in the range 1 through 256.
213
214 =back
215
216 In the simplest case just supply the width and height of the image:
217
218   # 8 bit/sample, RGB image
219   my $img = Imager->new(xsize => $width, ysize => $height);
220
221 or if you want an alpha channel:
222
223   # 8 bits/sample, RGBA image
224   my $img = Imager->new(xsize => $width, ysize => $height, channels=>4);
225
226 Note that it I<is> possible for image creation to fail, for example if
227 channels is out of range, or if the image would take too much memory.
228
229 To create paletted images, set the 'type' parameter to 'paletted':
230
231   $img = Imager->new(xsize=>200, ysize=>200, type=>'paletted');
232
233 which creates an image with a maxiumum of 256 colors, which you can
234 change by supplying the C<maxcolors> parameter.
235
236 For improved color precision you can use the bits parameter to specify
237 16 bit per channel:
238
239   $img = Imager->new(xsize=>200, ysize=>200,
240                      channels=>3, bits=>16);
241
242 or for even more precision:
243
244   $img = Imager->new(xsize=>200, ysize=>200,
245                      channels=>3, bits=>'double');
246
247 to get an image that uses a double for each channel.
248
249 Note that as of this writing all functions should work on images with
250 more than 8-bits/channel, but many will only work at only
251 8-bit/channel precision.
252
253 If you want an empty Imager object to call the read() method on, just
254 call new() with no parameters:
255
256   my $img = Imager->new;
257   $img->read(file=>$filename)
258     or die $img->errstr;
259
260 =item img_set
261
262 img_set destroys the image data in the object and creates a new one
263 with the given dimensions and channels.  For a way to convert image
264 data between formats see the C<convert()> method.
265
266   $img->img_set(xsize=>500, ysize=>500, channels=>4);
267
268 This takes exactly the same parameters as the new() method.
269
270 =back
271
272 =head2 Getting Information About an Imager Object
273
274 =over
275
276 =item getwidth
277
278   print "Image width: ", $img->getwidth(), "\n";
279
280 The C<getwidth()> method returns the width of the image.  This value
281 comes either from C<new()> with xsize,ysize parameters or from reading
282 data from a file with C<read()>.  If called on an image that has no
283 valid data in it like C<Imager-E<gt>new()> returns, the return value
284 of C<getwidth()> is undef.
285
286 =item getheight
287
288   print "Image height: ", $img->getheight(), "\n";
289
290 Same details apply as for L<getwidth>.
291
292 =item getchannels
293
294   print "Image has ",$img->getchannels(), " channels\n";
295
296 To get the number of channels in an image C<getchannels()> is used.
297
298
299 =item getcolorcount
300
301 It is possible to have Imager find the number of colors in an image by
302 with the C<getcolorcount()> method. It requires memory proportionally
303 to the number of colors in the image so it is possible to have it stop
304 sooner if you only need to know if there are more than a certain
305 number of colors in the image.  If there are more colors than asked
306 for the function return undef.  Examples:
307
308   if (defined($img->getcolorcount(maxcolors=>512)) {
309     print "Less than 512 colors in image\n";
310   }
311
312
313 =item bits
314
315 The bits() method retrieves the number of bits used to represent each
316 channel in a pixel, 8 for a normal image, 16 for 16-bit image and
317 'double' for a double/channel image.
318
319   if ($img->bits eq 8) {
320     # fast but limited to 8-bits/sample
321   }
322   else {
323     # slower but more precise
324   }
325
326 =item type
327
328 The type() method returns either 'direct' for truecolor images or
329 'paletted' for paletted images.
330
331   if ($img->type eq 'paletted') {
332     # print the palette
333     for my $color ($img->getcolors) {
334       print join(",", $color->rgba), "\n";
335     }
336   }
337
338 =item virtual
339
340 The virtual() method returns non-zero if the image contains no actual
341 pixels, for example masked images.
342
343 This may also be used for non-native Imager images in the future, for
344 example, for an Imager object that draws on an SDL surface.
345
346 =back
347
348 =head2 Direct Type Images
349
350 Direct images store the color value directly for each pixel in the
351 image.
352
353 =over
354
355 =item getmask
356
357   @rgbanames = qw( red green blue alpha );
358   my $mask = $img->getmask();
359   print "Modifiable channels:\n";
360   for (0..$img->getchannels()-1) {
361     print $rgbanames[$_],"\n" if $mask & 1<<$_;
362   }
363
364 C<getmask()> is used to fetch the current channel mask.  The mask
365 determines what channels are currently modifiable in the image.  The
366 channel mask is an integer value, if the i-th lsb is set the i-th
367 channel is modifiable.  eg. a channel mask of 0x5 means only channels
368 0 and 2 are writable.
369
370 =item setmask
371
372   $mask = $img->getmask();
373   $img->setmask(mask=>8);     # modify alpha only
374
375     ...
376
377   $img->setmask(mask=>$mask); # restore previous mask
378
379 C<setmask()> is used to set the channel mask of the image.  See
380 L<getmask> for details.
381
382 =back
383
384 =head2 Palette Type Images
385
386 Paletted images keep an array of up to 256 colors, and each pixel is
387 stored as an index into that array.
388
389 In general you can work with paletted images in the same way as RGB
390 images, except that if you attempt to draw to a paletted image with a
391 color that is not in the image's palette, the image will be converted
392 to an RGB image.  This means that drawing on a paletted image with
393 anti-aliasing enabled will almost certainly convert the image to RGB.
394
395 Palette management takes place through C<addcolors()>, C<setcolors()>,
396 C<getcolors()> and C<findcolor()>:
397
398 =over
399
400 =item addcolors
401
402 You can add colors to a paletted image with the addcolors() method:
403
404    my @colors = ( Imager::Color->new(255, 0, 0), 
405                   Imager::Color->new(0, 255, 0) );
406    my $index = $img->addcolors(colors=>\@colors);
407
408 The return value is the index of the first color added, or undef if
409 adding the colors would overflow the palette.
410
411 The only parameter is C<colors> which must be a reference to an array
412 of Imager::Color objects.
413
414 =item setcolors
415
416   $img->setcolors(start=>$start, colors=>\@colors);
417
418 Once you have colors in the palette you can overwrite them with the
419 C<setcolors()> method:  C<setcolors()> returns true on success.
420
421 Parameters:
422
423 =over
424
425 =item *
426
427 start - the first index to be set.  Default: 0
428
429 =item *
430
431 colors - reference to an array of Imager::Color objects.
432
433 =back
434
435 =item getcolors
436
437 To retrieve existing colors from the palette use the getcolors() method:
438
439   # get the whole palette
440   my @colors = $img->getcolors();
441   # get a single color
442   my $color = $img->getcolors(start=>$index);
443   # get a range of colors
444   my @colors = $img->getcolors(start=>$index, count=>$count);
445
446 =item findcolor
447
448 To quickly find a color in the palette use findcolor():
449
450   my $index = $img->findcolor(color=>$color);
451
452 which returns undef on failure, or the index of the color.
453
454 Parameter:
455
456 =over
457
458 =item *
459
460 color - an Imager::Color object.
461
462 =back
463
464 =item colorcount
465
466 Returns the number of colors in the image's palette:
467
468   my $count = $img->colorcount;
469
470 =item maxcolors
471
472 Returns the maximum size of the image's palette.
473
474   my $maxcount = $img->maxcolors;
475
476 =back
477
478 =head2 Conversion Between Image Types
479
480 Warning: if you draw on a paletted image with colors that aren't in
481 the palette, the image will be internally converted to a normal image.
482
483 =over
484
485 =item to_paletted
486
487 You can create a new paletted image from an existing image using the
488 to_paletted() method:
489
490  $palimg = $img->to_paletted(\%opts)
491
492 where %opts contains the options specified under L<Quantization options>.
493
494   # convert to a paletted image using the web palette
495   # use the closest color to each pixel
496   my $webimg = $img->to_paletted({ make_colors => 'webmap' });
497
498   # convert to a paletted image using a fairly optimal palette
499   # use an error diffusion dither to try to reduce the average error
500   my $optimag = $img->to_paletted({ make_colors => 'mediancut',
501                                     translate => 'errdiff' });
502
503 =item to_rgb8
504
505 You can convert a paletted image (or any image) to an 8-bit/channel
506 RGB image with:
507
508   $rgbimg = $img->to_rgb8;
509
510 No parameters.
511
512 =item masked
513
514 Creates a masked image.  A masked image lets you create an image proxy
515 object that protects parts of the underlying target image.
516
517 In the discussion below there are 3 image objects involved:
518
519 =over
520
521 =item *
522
523 the masked image - the return value of the masked() method.  Any
524 writes to this image are written to the target image, assuming the
525 mask image allows it.
526
527 =item *
528
529 the mask image - the image that protects writes to the target image.
530 Supplied as the C<mask> parameter to the masked() method.
531
532 =item *
533
534 the target image - the image you called the masked() method on.  Any
535 writes to the masked image end up on this image.
536
537 =back
538
539 Parameters:
540
541 =over
542
543 =item *
544
545 mask - the mask image.  If not supplied then all pixels in the target
546 image are writable.  On each write to the masked image, only pixels
547 that have non-zero in chennel 0 of the mask image will be written to
548 the original image.  Default: none, if not supplied then no masking is
549 done, but the other parameters are still honored.
550
551 =item *
552
553 left, top - the offset of writes to the target image.  eg. if you
554 attempt to set pixel (x,y) in the masked image, then pixel (x+left,
555 y+top) will be written to in the original image.
556
557 =item *
558
559 bottom, right - the bottom right of the area in the target available
560 from the masked image.
561
562 =back
563
564 Masked images let you control which pixels are modified in an
565 underlying image.  Where the first channel is completely black in the
566 mask image, writes to the underlying image are ignored.
567
568 For example, given a base image called $img:
569
570   my $mask = Imager->new(xsize=>$img->getwidth, ysize=>$img->getheight,
571                          channels=>1);
572   # ... draw something on the mask
573   my $maskedimg = $img->masked(mask=>$mask);
574
575   # now draw on $maskedimg and it will only draw on areas of $img 
576   # where $mask is non-zero in channel 0.
577
578 You can specifiy the region of the underlying image that is masked
579 using the left, top, right and bottom options.
580
581 If you just want a subset of the image, without masking, just specify
582 the region without specifying a mask.  For example:
583
584   # just work with a 100x100 region of $img
585   my $maskedimg = $img->masked(left => 100, top=>100,
586                                right=>200, bottom=>200);
587
588 =back
589
590 =head2 Tags
591
592 Image tags contain meta-data about the image, ie. information not
593 stored as pixels of the image.
594
595 At the perl level each tag has a name or code and a value, which is an
596 integer or an arbitrary string.  An image can contain more than one
597 tag with the same name or code, but having more than one tag with the
598 same name is discouraged.
599
600 You can retrieve tags from an image using the tags() method, you can
601 get all of the tags in an image, as a list of array references, with
602 the code or name of the tag followed by the value of the tag.
603
604 =over
605
606 =item tags
607
608 Retrieve tags from the image.
609
610 With no parameters, retrieves a list array references, each containing
611 a name and value: all tags in the image:
612
613   # get a list of ( [ name1 => value1 ], [ name2 => value2 ] ... )
614   my @alltags = $img->tags;
615   print $_->[0], ":", $_->[1], "\n" for @all_tags;
616
617   # or put it in a hash, but this will lose duplicates
618   my %alltags = map @$_, $img->tags;
619
620 in scalar context this returns the number of tags:
621
622   my $num_tags = $img->tags;
623
624 or you can get all tags values for the given name:
625
626   my @namedtags = $img->tags(name => $name);
627
628 in scalar context this returns the first tag of that name:
629
630   my $firstnamed = $img->tags(name => $name);
631
632 or a given code:
633
634   my @tags = $img->tags(code=>$code);
635
636 =item addtag
637
638 You can add tags using the addtag() method, either by name:
639
640   my $index = $img->addtag(name=>$name, value=>$value);
641
642 or by code:
643
644   my $index = $img->addtag(code=>$code, value=>$value);
645
646 =item deltag
647
648 You can remove tags with the deltag() method, either by index:
649
650   $img->deltag(index=>$index);
651
652 or by name:
653
654   $img->deltag(name=>$name);
655
656 or by code:
657
658   $img->deltag(code=>$code);
659
660 In each case deltag() returns the number of tags deleted.
661
662 =item settag
663
664 settag() replaces any existing tags with a new tag.  This is
665 equivalent to calling deltag() then addtag().
666
667 =back
668
669 =head2 Common Tags
670
671 Many tags are only meaningful for one format.  GIF looping information
672 is pretty useless for JPEG for example.  Thus, many tags are set by
673 only a single reader or used by a single writer.  For a complete list
674 of format specific tags see L<Imager::Files>.
675
676 Since tags are a relatively new addition their use is not wide spread
677 but eventually we hope to have all the readers for various formats set
678 some standard information.
679
680 =over
681
682 =item *
683
684 X<i_xres tag>X<i_yres tag>X<tags, i_xres>X<tags, i_yres>i_xres, i_yres
685 - The spatial resolution of the image in pixels per inch.  If the
686 image format uses a different scale, eg. pixels per meter, then this
687 value is converted.  A floating point number stored as a string.
688
689   # our image was generated as a 300 dpi image
690   $img->settag(name => 'i_xres', value => 300);
691   $img->settag(name => 'i_yres', value => 300);
692
693   # 100 pixel/cm for a TIFF image
694   $img->settag(name => 'tiff_resolutionunit', value => 3); # RESUNIT_CENTIMETER
695   # convert to pixels per inch, Imager will convert it back
696   $img->settag(name => 'i_xres', value => 100 * 2.54);
697   $img->settag(name => 'i_yres', value => 100 * 2.54);
698
699 =item *
700
701 X<i_aspect_only tag>X<tags, i_aspect_only>i_aspect_only - If this is
702 non-zero then the values in i_xres and i_yres are treated as a ratio
703 only.  If the image format does not support aspect ratios then this is
704 scaled so the smaller value is 72dpi.
705
706 =item *
707
708 X<i_incomplete tag>X<tags, i_incomplete>i_incomplete - If this tag is
709 present then the whole image could not be read.  This isn't
710 implemented for all images yet, and may not be.
711
712 =item *
713
714 X<i_lines_read tag>X<tags, i_lines_read>i_lines_read - If
715 C<i_incomplete> is set then this tag may be set to the number of
716 scanlines successfully read from the file.  This can be used to decide
717 whether an image is worth processing.
718
719 =item *
720
721 X<i_format tag>X<tags, i_format>i_format - The file format this file
722 was read from.
723
724 =back
725
726 =head2 Quantization options
727
728 These options can be specified when calling
729 L<Imager::ImageTypes/to_paletted>, write_multi() for gif files, when
730 writing a single image with the gifquant option set to 'gen', or for
731 direct calls to i_writegif_gen and i_writegif_callback.
732
733 =over
734
735 =item colors
736
737 A arrayref of colors that are fixed.  Note that some color generators
738 will ignore this.
739
740 =item transp
741
742 The type of transparency processing to perform for images with an
743 alpha channel where the output format does not have a proper alpha
744 channel (eg. gif).  This can be any of:
745
746 =over
747
748 =item none
749
750 No transparency processing is done. (default)
751
752 =item threshold
753
754 Pixels more transparent that tr_threshold are rendered as transparent.
755
756 =item errdiff
757
758 An error diffusion dither is done on the alpha channel.  Note that
759 this is independent of the translation performed on the colour
760 channels, so some combinations may cause undesired artifacts.
761
762 =item ordered
763
764 The ordered dither specified by tr_orddith is performed on the alpha
765 channel.
766
767 =back
768
769 This will only be used if the image has an alpha channel, and if there
770 is space in the palette for a transparency colour.
771
772 =item tr_threshold
773
774 The highest alpha value at which a pixel will be made transparent when
775 transp is 'threshold'. (0-255, default 127)
776
777 =item tr_errdiff
778
779 The type of error diffusion to perform on the alpha channel when
780 transp is 'errdiff'.  This can be any defined error diffusion type
781 except for custom (see errdiff below).
782
783 =item tr_orddith
784
785 The type of ordered dither to perform on the alpha channel when transp
786 is 'ordered'.  Possible values are:
787
788 =over
789
790 =item random
791
792 A semi-random map is used.  The map is the same each time.
793
794 =item dot8
795
796 8x8 dot dither.
797
798 =item dot4
799
800 4x4 dot dither
801
802 =item hline
803
804 horizontal line dither.
805
806 =item vline
807
808 vertical line dither.
809
810 =item "/line"
811
812 =item slashline
813
814 diagonal line dither
815
816 =item '\line'
817
818 =item backline
819
820 diagonal line dither
821
822 =item tiny
823
824 dot matrix dither (currently the default).  This is probably the best
825 for displays (like web pages).
826
827 =item custom
828
829 A custom dither matrix is used - see tr_map
830
831 =back
832
833 =item tr_map
834
835 When tr_orddith is custom this defines an 8 x 8 matrix of integers
836 representing the transparency threshold for pixels corresponding to
837 each position.  This should be a 64 element array where the first 8
838 entries correspond to the first row of the matrix.  Values should be
839 betweern 0 and 255.
840
841 =item make_colors
842
843 Defines how the quantization engine will build the palette(s).
844 Currently this is ignored if 'translate' is 'giflib', but that may
845 change.  Possible values are:
846
847 =over
848
849 =item *
850
851 none - only colors supplied in 'colors' are used.
852
853 =item *
854
855 webmap - the web color map is used (need url here.)
856
857 =item *
858
859 addi - The original code for generating the color map (Addi's code) is
860 used.
861
862 =item *
863
864 mediancut - Uses a mediancut algorithm, faster than 'addi', but not as good a
865 result.
866
867 =item *
868
869 mono, monochrome - a fixed black and white palette, suitable for
870 producing bi-level images (eg. facsimile)
871
872 =back
873
874 Other methods may be added in the future.
875
876 =item colors
877
878 A arrayref containing Imager::Color objects, which represents the
879 starting set of colors to use in translating the images.  webmap will
880 ignore this.  The final colors used are copied back into this array
881 (which is expanded if necessary.)
882
883 =item max_colors
884
885 The maximum number of colors to use in the image.
886
887 =item translate
888
889 The method used to translate the RGB values in the source image into
890 the colors selected by make_colors.  Note that make_colors is ignored
891 whene translate is 'giflib'.
892
893 Possible values are:
894
895 =over
896
897 =item giflib
898
899 The giflib native quantization function is used.
900
901 =item closest
902
903 The closest color available is used.
904
905 =item perturb
906
907 The pixel color is modified by perturb, and the closest color is chosen.
908
909 =item errdiff
910
911 An error diffusion dither is performed.
912
913 =back
914
915 It's possible other transate values will be added.
916
917 =item errdiff
918
919 The type of error diffusion dither to perform.  These values (except
920 for custom) can also be used in tr_errdif.
921
922 =over
923
924 =item floyd
925
926 Floyd-Steinberg dither
927
928 =item jarvis
929
930 Jarvis, Judice and Ninke dither
931
932 =item stucki
933
934 Stucki dither
935
936 =item custom
937
938 Custom.  If you use this you must also set errdiff_width,
939 errdiff_height and errdiff_map.
940
941 =back
942
943 =item errdiff_width
944
945 =item errdiff_height
946
947 =item errdiff_orig
948
949 =item errdiff_map
950
951 When translate is 'errdiff' and errdiff is 'custom' these define a
952 custom error diffusion map.  errdiff_width and errdiff_height define
953 the size of the map in the arrayref in errdiff_map.  errdiff_orig is
954 an integer which indicates the current pixel position in the top row
955 of the map.
956
957 =item perturb
958
959 When translate is 'perturb' this is the magnitude of the random bias
960 applied to each channel of the pixel before it is looked up in the
961 color table.
962
963 =back
964
965 =head1 INITIALIZATION
966
967 This documents the Imager initialization function, which you will
968 almost never need to call.
969
970 =over
971
972 =item init
973
974 This is a function, not a method.
975
976 This function is a mess, it can take the following named parameters:
977
978 =over
979
980 =item *
981
982 log - name of a log file to log Imager's actions to.  Not all actions
983 are logged, but the debugging memory allocator does log allocations
984 here.  Ignored if Imager has been built without logging support.
985
986 =item *
987
988 loglevel - the maximum level of message to log.  Default: 1.
989
990 =item *
991
992 warn_obsolete - if this is non-zero then Imager will warn when you
993 attempt to use obsoleted parameters or functionality.  This currently
994 only includes the old gif output options instead of tags.
995
996 =item *
997
998 t1log - if non-zero then T1lib will be configured to produce a log
999 file.  This will fail if there are any existing T1lib font objects.
1000
1001 =back
1002
1003 Example:
1004
1005   Imager::init(log => 'trace.log', loglevel => 9);
1006
1007 =back
1008
1009 =head1 REVISION
1010
1011 $Revision$
1012
1013 =head1 AUTHORS
1014
1015 Tony Cook, Arnar M. Hrafnkelsson
1016
1017 =head1 SEE ALSO
1018
1019 Imager(3), Imager::Files(3), Imager::Draw(3),
1020 Imager::Color(3), Imager::Fill(3), Imager::Font(3),
1021 Imager::Transformations(3), Imager::Engines(3), Imager::Filters(3),
1022 Imager::Expr(3), Imager::Matrix2d(3), Imager::Fountain(3)
1023
1024 =cut