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