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