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