huge spelling update and spell checking patch
[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 - gray scale image.
102
103 =item *
104
105 2 samples per color - gray scale 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 You can also read a file from new():
152
153   $img = Imager->new(file => "someimage.png");
154
155 The parameters for new are:
156
157 =over
158
159 =item *
160
161 C<xsize>, C<ysize> - Defines the width and height in pixels of the
162 image.  These must be positive.
163
164 If not supplied then only placeholder object is created, which can be
165 supplied to the C<read()> or C<img_set()> methods.
166
167 =item *
168
169 C<channels> - The number of channels for the image.  Default 3.  Valid
170 values are from 1 to 4.
171
172 =item *
173
174 C<bits> - The storage type for samples in the image.  Default: 8.
175 Valid values are:
176
177 =over
178
179 =item *
180
181 C<8> - One byte per sample.  256 discrete values.
182
183 =item *
184
185 C<16> - 16-bits per sample, 65536 discrete values.
186
187 =item *
188
189 C<double> - one C double per sample.
190
191 =back
192
193 Note: you can use any Imager function on any sample size image.
194
195 Paletted images always use 8 bits/sample.
196
197 =item *
198
199 C<type> - either C<'direct'> or C<'paletted'>.  Default: C<'direct'>.
200
201 Direct images store color values for each pixel.  
202
203 Paletted images keep a table of up to 256 colors called the palette,
204 each pixel is represented as an index into that table.
205
206 In most cases when working with Imager you will want to use the
207 C<direct> image type.
208
209 If you draw on a C<paletted> image with a color not in the image's
210 palette then Imager will transparently convert it to a C<direct>
211 image.
212
213 =item *
214
215 C<maxcolors> - the maximum number of colors in a paletted image.
216 Default: 256.  This must be in the range 1 through 256.
217
218 =item *
219
220 C<file>, C<fh>, C<fd>, C<callback>, C<readcb> - specify a file name,
221 filehandle, file descriptor or callback to read image data from.  See
222 L<Imager::Files> for details.  The typical use is:
223
224   my $im = Imager->new(file => $filename);
225
226 =item *
227
228 C<filetype> - treated as the file format parameter, as for C<type>
229 with the read() method, eg:
230
231   my $im = Imager->new(file => $filename, filetype => "gif");
232
233 In most cases Imager will detect the file's format itself.
234
235 =back
236
237 In the simplest case just supply the width and height of the image:
238
239   # 8 bit/sample, RGB image
240   my $img = Imager->new(xsize => $width, ysize => $height);
241
242 or if you want an alpha channel:
243
244   # 8 bits/sample, RGBA image
245   my $img = Imager->new(xsize => $width, ysize => $height, channels=>4);
246
247 Note that it I<is> possible for image creation to fail, for example if
248 channels is out of range, or if the image would take too much memory.
249
250 To create paletted images, set the 'type' parameter to 'paletted':
251
252   $img = Imager->new(xsize=>200, ysize=>200, type=>'paletted');
253
254 which creates an image with a maximum of 256 colors, which you can
255 change by supplying the C<maxcolors> parameter.
256
257 For improved color precision you can use the bits parameter to specify
258 16 bit per channel:
259
260   $img = Imager->new(xsize=>200, ysize=>200,
261                      channels=>3, bits=>16);
262
263 or for even more precision:
264
265   $img = Imager->new(xsize=>200, ysize=>200,
266                      channels=>3, bits=>'double');
267
268 to get an image that uses a double for each channel.
269
270 Note that as of this writing all functions should work on images with
271 more than 8-bits/channel, but many will only work at only
272 8-bit/channel precision.
273
274 If you want an empty Imager object to call the read() method on, just
275 call new() with no parameters:
276
277   my $img = Imager->new;
278   $img->read(file=>$filename)
279     or die $img->errstr;
280
281 Though it's much easier now to just call new() with a C<file>
282 parameter:
283
284   my $img = Imager->new(file => $filename)
285     or die Imager->errstr;
286
287 =item img_set()
288
289 img_set destroys the image data in the object and creates a new one
290 with the given dimensions and channels.  For a way to convert image
291 data between formats see the C<convert()> method.
292
293   $img->img_set(xsize=>500, ysize=>500, channels=>4);
294
295 This takes exactly the same parameters as the new() method.
296
297 =back
298
299 =head2 Image Attribute functions
300
301 These return basic attributes of an image object.
302
303 =over
304
305 =item getwidth()
306
307   print "Image width: ", $img->getwidth(), "\n";
308
309 The C<getwidth()> method returns the width of the image.  This value
310 comes either from C<new()> with C<xsize>, C<ysize> parameters or from
311 reading data from a file with C<read()>.  If called on an image that
312 has no valid data in it like C<Imager-E<gt>new()> returns, the return
313 value of C<getwidth()> is undef.
314
315 =item getheight()
316
317   print "Image height: ", $img->getheight(), "\n";
318
319 Same details apply as for L<getwidth>.
320
321 =item getchannels()
322
323   print "Image has ",$img->getchannels(), " channels\n";
324
325 To get the number of channels in an image C<getchannels()> is used.
326
327
328 =item bits()
329
330 The bits() method retrieves the number of bits used to represent each
331 channel in a pixel, 8 for a normal image, 16 for 16-bit image and
332 'double' for a double/channel image.
333
334   if ($img->bits eq 8) {
335     # fast but limited to 8-bits/sample
336   }
337   else {
338     # slower but more precise
339   }
340
341 =item type()
342
343 The type() method returns either 'direct' for direct color images or
344 'paletted' for paletted images.
345
346   if ($img->type eq 'paletted') {
347     # print the palette
348     for my $color ($img->getcolors) {
349       print join(",", $color->rgba), "\n";
350     }
351   }
352
353 =item virtual()
354
355 The virtual() method returns non-zero if the image contains no actual
356 pixels, for example masked images.
357
358 =for stopwords SDL
359
360 This may also be used for non-native Imager images in the future, for
361 example, for an Imager object that draws on an SDL surface.
362
363 =item is_bilevel()
364
365 Tests if the image will be written as a monochrome or bi-level image
366 for formats that support that image organization.
367
368 In scalar context, returns true if the image is bi-level.
369
370 In list context returns a list:
371
372   ($is_bilevel, $zero_is_white) = $img->is_bilevel;
373
374 An image is considered bi-level, if all of the following are true:
375
376 =over
377
378 =item *
379
380 the image is a paletted image
381
382 =item *
383
384 the image has 1 or 3 channels
385
386 =item *
387
388 the image has only 2 colors in the palette
389
390 =item *
391
392 those 2 colors are black and white, in either order.
393
394 =back
395
396 If a real bi-level organization image is ever added to Imager, this
397 function will return true for that too.
398
399 =back
400
401 =head2 Direct Type Images
402
403 Direct images store the color value directly for each pixel in the
404 image.
405
406 =over
407
408 =item getmask()
409
410   @rgbanames = qw( red green blue alpha );
411   my $mask = $img->getmask();
412   print "Modifiable channels:\n";
413   for (0..$img->getchannels()-1) {
414     print $rgbanames[$_],"\n" if $mask & 1<<$_;
415   }
416
417 =for stopwords th
418
419 C<getmask()> is used to fetch the current channel mask.  The mask
420 determines what channels are currently modifiable in the image.  The
421 channel mask is an integer value, if the C<i-th> least significant bit
422 is set the C<i-th> channel is modifiable.  eg. a channel mask of 0x5
423 means only channels 0 and 2 are writable.
424
425 =item setmask()
426
427   $mask = $img->getmask();
428   $img->setmask(mask=>8);     # modify alpha only
429
430     ...
431
432   $img->setmask(mask=>$mask); # restore previous mask
433
434 C<setmask()> is used to set the channel mask of the image.  See
435 L<getmask> for details.
436
437 =back
438
439 =head2 Palette Type Images
440
441 Paletted images keep an array of up to 256 colors, and each pixel is
442 stored as an index into that array.
443
444 In general you can work with paletted images in the same way as RGB
445 images, except that if you attempt to draw to a paletted image with a
446 color that is not in the image's palette, the image will be converted
447 to an RGB image.  This means that drawing on a paletted image with
448 anti-aliasing enabled will almost certainly convert the image to RGB.
449
450 Palette management takes place through C<addcolors()>, C<setcolors()>,
451 C<getcolors()> and C<findcolor()>:
452
453 =over
454
455 =item addcolors()
456
457 You can add colors to a paletted image with the addcolors() method:
458
459    my @colors = ( Imager::Color->new(255, 0, 0), 
460                   Imager::Color->new(0, 255, 0) );
461    my $index = $img->addcolors(colors=>\@colors);
462
463 The return value is the index of the first color added, or undef if
464 adding the colors would overflow the palette.
465
466 The only parameter is C<colors> which must be a reference to an array
467 of Imager::Color objects.
468
469 =item setcolors()
470
471   $img->setcolors(start=>$start, colors=>\@colors);
472
473 Once you have colors in the palette you can overwrite them with the
474 C<setcolors()> method:  C<setcolors()> returns true on success.
475
476 Parameters:
477
478 =over
479
480 =item *
481
482 start - the first index to be set.  Default: 0
483
484 =item *
485
486 colors - reference to an array of Imager::Color objects.
487
488 =back
489
490 =item getcolors()
491
492 To retrieve existing colors from the palette use the getcolors() method:
493
494   # get the whole palette
495   my @colors = $img->getcolors();
496   # get a single color
497   my $color = $img->getcolors(start=>$index);
498   # get a range of colors
499   my @colors = $img->getcolors(start=>$index, count=>$count);
500
501 =item findcolor()
502
503 To quickly find a color in the palette use findcolor():
504
505   my $index = $img->findcolor(color=>$color);
506
507 which returns undef on failure, or the index of the color.
508
509 Parameter:
510
511 =over
512
513 =item *
514
515 color - an Imager::Color object.
516
517 =back
518
519 =item colorcount()
520
521 Returns the number of colors in the image's palette:
522
523   my $count = $img->colorcount;
524
525 =item maxcolors()
526
527 Returns the maximum size of the image's palette.
528
529   my $maxcount = $img->maxcolors;
530
531 =back
532
533 =head2 Color Distribution
534
535 =over
536
537 =item getcolorcount()
538
539 Calculates the number of colors in an image.
540
541 The amount of memory used by this is proportional to the number of
542 colors present in the image, so to avoid using too much memory you can
543 supply a maxcolors() parameter to limit the memory used.
544
545 Note: getcolorcount() treats the image as an 8-bit per sample image.
546
547 =over
548
549 =item *
550
551 X<maxcolors!getcolorcount>C<maxcolors> - the maximum number of colors to
552 return.  Default: unlimited.
553
554 =back
555
556   if (defined($img->getcolorcount(maxcolors=>512)) {
557     print "Less than 512 colors in image\n";
558   }
559
560 =item getcolorusagehash()
561
562 Calculates a histogram of colors used by the image.
563
564 =over
565
566 =item *
567
568 X<maxcolors!getcolorusagehash>C<maxcolors> - the maximum number of colors
569 to return.  Default: unlimited.
570
571 =back
572
573 Returns a reference to a hash where the keys are the raw color as
574 bytes, and the values are the counts for that color.
575
576 The alpha channel of the image is ignored.  If the image is gray scale
577 then the hash keys will each be a single character.
578
579   my $colors = $img->getcolorusagehash;
580   my $blue_count = $colors->{pack("CCC", 0, 0, 255)} || 0;
581   print "#0000FF used $blue_count times\n";
582
583 =item getcolorusage()
584
585 Calculates color usage counts and returns just the counts.
586
587 =over
588
589 =item *
590
591 X<maxcolors!getcolorusage>C<maxcolors> - the maximum number of colors
592 to return.  Default: unlimited.
593
594 =back
595
596 Returns a list of the color frequencies in ascending order.
597
598   my @counts = $img->getcolorusage;
599   print "The most common color is used $counts[0] times\n";
600
601 =back
602
603 =head2 Conversion Between Image Types
604
605 Warning: if you draw on a paletted image with colors that aren't in
606 the palette, the image will be internally converted to a normal image.
607
608 =over
609
610 =item to_paletted
611
612 You can create a new paletted image from an existing image using the
613 to_paletted() method:
614
615  $palimg = $img->to_paletted(\%opts)
616
617 where %opts contains the options specified under L<Quantization options>.
618
619   # convert to a paletted image using the web palette
620   # use the closest color to each pixel
621   my $webimg = $img->to_paletted({ make_colors => 'webmap' });
622
623   # convert to a paletted image using a fairly optimal palette
624   # use an error diffusion dither to try to reduce the average error
625   my $optimag = $img->to_paletted({ make_colors => 'mediancut',
626                                     translate => 'errdiff' });
627
628 =item to_rgb8()
629
630 You can convert a paletted image (or any image) to an 8-bit/channel
631 RGB image with:
632
633   $rgbimg = $img->to_rgb8;
634
635 No parameters.
636
637 =item to_rgb16()
638
639 You can convert a paletted image (or any image) to an 16-bit/channel
640 RGB image with:
641
642   $rgbimg = $img->to_rgb16;
643
644 No parameters.
645
646 =item masked
647
648 Creates a masked image.  A masked image lets you create an image proxy
649 object that protects parts of the underlying target image.
650
651 In the discussion below there are 3 image objects involved:
652
653 =over
654
655 =item *
656
657 the masked image - the return value of the masked() method.  Any
658 writes to this image are written to the target image, assuming the
659 mask image allows it.
660
661 =item *
662
663 the mask image - the image that protects writes to the target image.
664 Supplied as the C<mask> parameter to the masked() method.
665
666 =item *
667
668 the target image - the image you called the masked() method on.  Any
669 writes to the masked image end up on this image.
670
671 =back
672
673 Parameters:
674
675 =over
676
677 =item *
678
679 mask - the mask image.  If not supplied then all pixels in the target
680 image are writable.  On each write to the masked image, only pixels
681 that have non-zero in channel 0 of the mask image will be written to
682 the original image.  Default: none, if not supplied then no masking is
683 done, but the other parameters are still honored.
684
685 =item *
686
687 left, top - the offset of writes to the target image.  eg. if you
688 attempt to set pixel (x,y) in the masked image, then pixel (x+left,
689 y+top) will be written to in the original image.
690
691 =item *
692
693 bottom, right - the bottom right of the area in the target available
694 from the masked image.
695
696 =back
697
698 Masked images let you control which pixels are modified in an
699 underlying image.  Where the first channel is completely black in the
700 mask image, writes to the underlying image are ignored.
701
702 For example, given a base image called $img:
703
704   my $mask = Imager->new(xsize=>$img->getwidth, ysize=>$img->getheight,
705                          channels=>1);
706   # ... draw something on the mask
707   my $maskedimg = $img->masked(mask=>$mask);
708
709   # now draw on $maskedimg and it will only draw on areas of $img 
710   # where $mask is non-zero in channel 0.
711
712 You can specify the region of the underlying image that is masked
713 using the left, top, right and bottom options.
714
715 If you just want a subset of the image, without masking, just specify
716 the region without specifying a mask.  For example:
717
718   # just work with a 100x100 region of $img
719   my $maskedimg = $img->masked(left => 100, top=>100,
720                                right=>200, bottom=>200);
721
722 =back
723
724 =head2 Tags
725
726 Image tags contain meta-data about the image, ie. information not
727 stored as pixels of the image.
728
729 At the perl level each tag has a name or code and a value, which is an
730 integer or an arbitrary string.  An image can contain more than one
731 tag with the same name or code, but having more than one tag with the
732 same name is discouraged.
733
734 You can retrieve tags from an image using the tags() method, you can
735 get all of the tags in an image, as a list of array references, with
736 the code or name of the tag followed by the value of the tag.
737
738 =over
739
740 =item tags()
741
742 Retrieve tags from the image.
743
744 With no parameters, retrieves a list array references, each containing
745 a name and value: all tags in the image:
746
747   # get a list of ( [ name1 => value1 ], [ name2 => value2 ] ... )
748   my @alltags = $img->tags;
749   print $_->[0], ":", $_->[1], "\n" for @all_tags;
750
751   # or put it in a hash, but this will lose duplicates
752   my %alltags = map @$_, $img->tags;
753
754 in scalar context this returns the number of tags:
755
756   my $num_tags = $img->tags;
757
758 or you can get all tags values for the given name:
759
760   my @namedtags = $img->tags(name => $name);
761
762 in scalar context this returns the first tag of that name:
763
764   my $firstnamed = $img->tags(name => $name);
765
766 or a given code:
767
768   my @tags = $img->tags(code=>$code);
769
770 =item addtag()
771
772 You can add tags using the addtag() method, either by name:
773
774   my $index = $img->addtag(name=>$name, value=>$value);
775
776 or by code:
777
778   my $index = $img->addtag(code=>$code, value=>$value);
779
780 =item deltag()
781
782 You can remove tags with the deltag() method, either by index:
783
784   $img->deltag(index=>$index);
785
786 or by name:
787
788   $img->deltag(name=>$name);
789
790 or by code:
791
792   $img->deltag(code=>$code);
793
794 In each case deltag() returns the number of tags deleted.
795
796 =item settag()
797
798 settag() replaces any existing tags with a new tag.  This is
799 equivalent to calling deltag() then addtag().
800
801 =back
802
803 =head2 Common Tags
804
805 Many tags are only meaningful for one format.  GIF looping information
806 is pretty useless for JPEG for example.  Thus, many tags are set by
807 only a single reader or used by a single writer.  For a complete list
808 of format specific tags see L<Imager::Files>.
809
810 Since tags are a relatively new addition their use is not wide spread
811 but eventually we hope to have all the readers for various formats set
812 some standard information.
813
814 =over
815
816 =item *
817
818 X<i_xres tag>X<i_yres tag>X<tags, i_xres>X<tags, i_yres>C<i_xres>, C<i_yres>
819 - The spatial resolution of the image in pixels per inch.  If the
820 image format uses a different scale, eg. pixels per meter, then this
821 value is converted.  A floating point number stored as a string.
822
823   # our image was generated as a 300 dpi image
824   $img->settag(name => 'i_xres', value => 300);
825   $img->settag(name => 'i_yres', value => 300);
826
827   # 100 pixel/cm for a TIFF image
828   $img->settag(name => 'tiff_resolutionunit', value => 3); # RESUNIT_CENTIMETER
829   # convert to pixels per inch, Imager will convert it back
830   $img->settag(name => 'i_xres', value => 100 * 2.54);
831   $img->settag(name => 'i_yres', value => 100 * 2.54);
832
833 =item *
834
835 X<i_aspect_only tag>X<tags, i_aspect_only>C<i_aspect_only> - If this is
836 non-zero then the values in i_xres and i_yres are treated as a ratio
837 only.  If the image format does not support aspect ratios then this is
838 scaled so the smaller value is 72 DPI.
839
840 =item *
841
842 X<i_incomplete tag>X<tags, i_incomplete>C<i_incomplete> - If this tag is
843 present then the whole image could not be read.  This isn't
844 implemented for all images yet, and may not be.
845
846 =item *
847
848 X<i_lines_read tag>X<tags, i_lines_read>C<i_lines_read> - If
849 C<i_incomplete> is set then this tag may be set to the number of
850 scan lines successfully read from the file.  This can be used to decide
851 whether an image is worth processing.
852
853 =item *
854
855 X<i_format tag>X<tags, i_format>i_format - The file format this file
856 was read from.
857
858 =item *
859
860 X<i_background>X<tags, i_background>i_background - used when writing
861 an image with an alpha channel to a file format that doesn't support
862 alpha channels.  The C<write> method will convert a normal color
863 specification like "#FF0000" into a color object for you, but if you
864 set this as a tag you will need to format it like
865 C<color(>I<red>C<,>I<green>C<,>I<blue>C<)>, eg color(255,0,0).
866
867 =back
868
869 =head2 Quantization options
870
871 These options can be specified when calling
872 L<Imager::ImageTypes/to_paletted>, write_multi() for GIF files, when
873 writing a single image with the C<gifquant> option set to C<gen>, or for
874 direct calls to i_writegif_gen() and i_writegif_callback().
875
876 =over
877
878 =item *
879
880 C<colors> - An arrayref of colors that are fixed.  Note that some
881 color generators will ignore this.  If this is supplied it will be
882 filled with the color table generated for the image.
883
884 =item *
885
886 C<transp> - The type of transparency processing to perform for images
887 with an alpha channel where the output format does not have a proper
888 alpha channel (eg. GIF).  This can be any of:
889
890 =over
891
892 =item *
893
894 C<none> - No transparency processing is done. (default)
895
896 =item *
897
898 C<threshold> - pixels more transparent than C<tr_threshold> are
899 rendered as transparent.
900
901 =item *
902
903 C<errdiff> - An error diffusion dither is done on the alpha channel.
904 Note that this is independent of the translation performed on the
905 color channels, so some combinations may cause undesired artifacts.
906
907 =item *
908
909 C<ordered> - the ordered dither specified by tr_orddith is performed
910 on the alpha channel.
911
912 =back
913
914 This will only be used if the image has an alpha channel, and if there
915 is space in the palette for a transparency color.
916
917 =item *
918
919 C<tr_threshold> - the highest alpha value at which a pixel will be
920 made transparent when C<transp> is 'threshold'. (0-255, default 127)
921
922 =item *
923
924 C<tr_errdiff> - The type of error diffusion to perform on the alpha
925 channel when C<transp> is C<errdiff>.  This can be any defined error
926 diffusion type except for custom (see C<errdiff> below).
927
928 =item *
929
930 C<tr_orddith> - The type of ordered dither to perform on the alpha
931 channel when C<transp> is 'ordered'.  Possible values are:
932
933 =over
934
935 =item *
936
937 C<random> - A semi-random map is used.  The map is the same each time.
938
939 =item *
940
941 C<dot8> - 8x8 dot dither.
942
943 =item *
944
945 C<dot4> - 4x4 dot dither
946
947 =item *
948
949 C<hline> - horizontal line dither.
950
951 =item *
952
953 C<vline> - vertical line dither.
954
955 =item *
956
957 C</line>, C<slashline> - diagonal line dither
958
959 =item *
960
961 C<\line>, C<backline> - diagonal line dither
962
963 =item *
964
965 C<tiny> - dot matrix dither (currently the default).  This is probably
966 the best for displays (like web pages).
967
968 =item *
969
970 C<custom> - A custom dither matrix is used - see C<tr_map>.
971
972 =back
973
974 =item *
975
976 C<tr_map> - When tr_orddith is custom this defines an 8 x 8 matrix of
977 integers representing the transparency threshold for pixels
978 corresponding to each position.  This should be a 64 element array
979 where the first 8 entries correspond to the first row of the matrix.
980 Values should be between 0 and 255.
981
982 =item *
983
984 C<make_colors> - Defines how the quantization engine will build the
985 palette(s).  Currently this is ignored if C<translate> is C<giflib>,
986 but that may change.  Possible values are:
987
988 =over
989
990 =item *
991
992 C<none> - only colors supplied in 'colors' are used.
993
994 =item *
995
996 C<webmap> - the web color map is used (need URL here.)
997
998 =item *
999
1000 C<addi> - The original code for generating the color map (Addi's code) is
1001 used.
1002
1003 =item *
1004
1005 C<mediancut> - Uses a median-cut algorithm, faster than C<addi>, but not
1006 as good a result.
1007
1008 =item *
1009
1010 C<mono>, C<monochrome> - a fixed black and white palette, suitable for
1011 producing bi-level images (eg. facsimile)
1012
1013 =back
1014
1015 Other methods may be added in the future.
1016
1017 =item *
1018
1019 C<colors> - an arrayref containing Imager::Color objects, which
1020 represents the starting set of colors to use in translating the
1021 images.  C<webmap> will ignore this.  On return the final colors used
1022 are copied back into this array (which is expanded if necessary.)
1023
1024 =item *
1025
1026 C<max_colors> - the maximum number of colors to use in the image.
1027
1028 =item *
1029
1030 C<translate> - The method used to translate the RGB values in the
1031 source image into the colors selected by make_colors.  Note that
1032 make_colors is ignored when C<translate> is C<giflib>.
1033
1034 Possible values are:
1035
1036 =over
1037
1038 =item *
1039
1040 C<giflib> - the C<giflib> native quantization function is used.
1041
1042 =item *
1043
1044 C<closest> - the closest color available is used.
1045
1046 =item *
1047
1048 C<perturb> - the pixel color is modified by C<perturb>, and the
1049 closest color is chosen.
1050
1051 =item *
1052
1053 C<errdiff> - an error diffusion dither is performed.
1054
1055 =back
1056
1057 It's possible other C<translate> values will be added.
1058
1059 =item *
1060
1061 C<errdiff> - The type of error diffusion dither to perform.  These
1062 values (except for custom) can also be used in tr_errdif.
1063
1064 =for stopwords Floyd-Steinberg Jarvis Judice Ninke Stucki
1065
1066 =over
1067
1068 =item *
1069
1070 C<floyd> - Floyd-Steinberg dither
1071
1072 =item *
1073
1074 C<jarvis> - Jarvis, Judice and Ninke dither
1075
1076 =item *
1077
1078 C<stucki> - Stucki dither
1079
1080 =item *
1081
1082 C<custom> - custom.  If you use this you must also set C<errdiff_width>,
1083 C<errdiff_height> and C<errdiff_map>.
1084
1085 =back
1086
1087 =item *
1088
1089 C<errdiff_width>, C<errdiff_height>, C<errdiff_orig>, C<errdiff_map> -
1090 When C<translate> is C<errdiff> and C<errdiff> is C<custom> these
1091 define a custom error diffusion map.  C<errdiff_width> and
1092 C<errdiff_height> define the size of the map in the arrayref in
1093 C<errdiff_map>.  C<errdiff_orig> is an integer which indicates the
1094 current pixel position in the top row of the map.
1095
1096 =item *
1097
1098 C<perturb> - When translate is C<perturb> this is the magnitude of the
1099 random bias applied to each channel of the pixel before it is looked
1100 up in the color table.
1101
1102 =back
1103
1104 =head1 INITIALIZATION
1105
1106 This documents the Imager initialization function, which you will
1107 almost never need to call.
1108
1109 =over
1110
1111 =item init()
1112
1113 This is a function, not a method.
1114
1115 This function is a mess, it can take the following named parameters:
1116
1117 =over
1118
1119 =item *
1120
1121 C<log> - name of a log file to log Imager's actions to.  Not all actions
1122 are logged, but the debugging memory allocator does log allocations
1123 here.  Ignored if Imager has been built without logging support.
1124
1125 =item *
1126
1127 C<loglevel> - the maximum level of message to log.  Default: 1.
1128
1129 =item *
1130
1131 C<warn_obsolete> - if this is non-zero then Imager will warn when you
1132 attempt to use obsoleted parameters or functionality.  This currently
1133 only includes the old GIF output options instead of tags.
1134
1135 =item *
1136
1137 C<t1log> - if non-zero then T1lib will be configured to produce a log
1138 file.  This will fail if there are any existing T1lib font objects.
1139
1140 =back
1141
1142 Example:
1143
1144   Imager::init(log => 'trace.log', loglevel => 9);
1145
1146 =back
1147
1148 =head1 REVISION
1149
1150 $Revision$
1151
1152 =head1 AUTHORS
1153
1154 Tony Cook, Arnar M. Hrafnkelsson
1155
1156 =head1 SEE ALSO
1157
1158 Imager(3), Imager::Files(3), Imager::Draw(3),
1159 Imager::Color(3), Imager::Fill(3), Imager::Font(3),
1160 Imager::Transformations(3), Imager::Engines(3), Imager::Filters(3),
1161 Imager::Expr(3), Imager::Matrix2d(3), Imager::Fountain(3)
1162
1163 =cut