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