95b7de0441a10dfb78887925cb960d86fea8ca53
[imager.git] / lib / Imager / Files.pod
1 =head1 NAME
2
3 Imager::Files - working with image files
4
5 =head1 SYNOPSIS
6
7   my $img = ...;
8   $img->write(file=>$filename, type=>$type)
9     or die "Cannot write: ",$img->errstr;
10
11   $img = Imager->new;
12   $img->read(file=>$filename, type=>$type)
13     or die "Cannot read: ", $img->errstr;
14
15   Imager->write_multi({ file=> $filename, ... }, @images)
16     or die "Cannot write: ", Imager->errstr;
17
18   my @imgs = Imager->read_multi(file=>$filename)
19     or die "Cannot read: ", Imager->errstr;
20
21   Imager->set_file_limits(width=>$max_width, height=>$max_height)
22
23 =head1 DESCRIPTION
24
25 You can read and write a variety of images formats, assuming you have
26 the appropriate libraries, and images can be read or written to/from
27 files, file handles, file descriptors, scalars, or through callbacks.
28
29 To see which image formats Imager is compiled to support the following
30 code snippet is sufficient:
31
32   use Imager;
33   print join " ", keys %Imager::formats;
34
35 This will include some other information identifying libraries rather
36 than file formats.
37
38 Reading writing to and from files is simple, use the C<read()>
39 method to read an image:
40
41   my $img = Imager->new;
42   $img->read(file=>$filename, type=>$type)
43     or die "Cannot read $filename: ", $img->errstr;
44
45 and the C<write()> method to write an image:
46
47   $img->write(file=>$filename, type=>$type)
48     or die "Cannot write $filename: ", $img->errstr;
49
50 If you're reading from a format that supports multiple images per
51 file, use the C<read_multi()> method:
52
53   my @imgs = Imager->read_multi(file=>$filename, type=>$type)
54     or die "Cannot read $filename: ", Imager->errstr;
55
56 and if you want to write multiple images to a single file use the
57 C<write_multi()> method:
58
59   Imager->write_multi({ file=> $filename, type=>$type }, @images)
60     or die "Cannot write $filename: ", Imager->errstr;
61
62 If the I<filename> includes an extension that Imager recognizes, then
63 you don't need the I<type>, but you may want to provide one anyway.
64 See L</Guessing types> for information on controlling this
65 recognition.
66
67 The C<type> parameter is a lowercase representation of the file type,
68 and can be any of the following:
69
70   bmp   Windows BitMaP (BMP)
71   gif   Graphics Interchange Format (GIF)
72   jpeg  JPEG/JFIF
73   png   Portable Network Graphics (PNG)
74   pnm   Portable aNyMap (PNM)
75   raw   Raw
76   rgb   SGI .rgb files
77   tga   TARGA
78   tiff  Tagged Image File Format (TIFF)
79
80 When you read an image, Imager may set some tags, possibly including
81 information about the spatial resolution, textual information, and
82 animation information.  See L<Imager::ImageTypes/Tags> for specifics.
83
84 The open() method is a historical alias for the read() method.
85
86 =head2 Input and output
87
88 When reading or writing you can specify one of a variety of sources or
89 targets:
90
91 =over
92
93 =item file
94
95 The C<file> parameter is the name of the image file to be written to
96 or read from.  If Imager recognizes the extension of the file you do
97 not need to supply a C<type>.
98
99 =item fh
100
101 C<fh> is a file handle, typically either returned from
102 C<<IO::File->new()>>, or a glob from an C<open> call.  You should call
103 C<binmode> on the handle before passing it to Imager.
104
105 Imager will set the handle to autoflush to make sure any buffered data
106 is flushed , since Imager will write to the file descriptor (from
107 fileno()) rather than writing at the perl level.
108
109 =item fd
110
111 C<fd> is a file descriptor.  You can get this by calling the
112 C<fileno()> function on a file handle, or by using one of the standard
113 file descriptor numbers.
114
115 If you get this from a perl file handle, you may need to flush any
116 buffered output, otherwise it may appear in the output stream after
117 the image.
118
119 =item data
120
121 When reading data, C<data> is a scalar containing the image file data,
122 when writing, C<data> is a reference to the scalar to save the image
123 file data too.  For GIF images you will need giflib 4 or higher, and
124 you may need to patch giflib to use this option for writing.
125
126 =item callback
127
128 Imager will make calls back to your supplied coderefs to read, write
129 and seek from/to/through the image file.
130
131 When reading from a file you can use either C<callback> or C<readcb>
132 to supply the read callback, and when writing C<callback> or
133 C<writecb> to supply the write callback.
134
135 When writing you can also supply the C<maxbuffer> option to set the
136 maximum amount of data that will be buffered before your write
137 callback is called.  Note: the amount of data supplied to your
138 callback can be smaller or larger than this size.
139
140 The read callback is called with 2 parameters, the minimum amount of
141 data required, and the maximum amount that Imager will store in it's C
142 level buffer.  You may want to return the minimum if you have a slow
143 data source, or the maximum if you have a fast source and want to
144 prevent many calls to your perl callback.  The read data should be
145 returned as a scalar.
146
147 Your write callback takes exactly one parameter, a scalar containing
148 the data to be written.  Return true for success.
149
150 The seek callback takes 2 parameters, a I<POSITION>, and a I<WHENCE>,
151 defined in the same way as perl's seek function.
152
153 You can also supply a C<closecb> which is called with no parameters
154 when there is no more data to be written.  This could be used to flush
155 buffered data.
156
157 =back
158
159 =head2 Guessing types
160
161 Imager uses the code reference in $Imager::FORMATGUESS to guess the
162 file type when you don't supply a C<type>.  The code reference is
163 called with a single parameter, the filename of the file.  The code
164 reference is only called if a C<file> parameter is supplied to the
165 file access method.
166
167 Return either a valid Imager file type, or undef.
168
169   # I'm writing jpegs to weird filenames
170   local $Imager::FORMATGUESS = sub { 'jpeg' };
171
172 =head2 Limiting the sizes of images you read
173
174 In some cases you will be receiving images from an untested source,
175 such as submissions via CGI.  To prevent such images from consuming
176 large amounts of memory, you can set limits on the dimensions of
177 images you read from files:
178
179 =over
180
181 =item *
182
183 width - limit the width in pixels of the image
184
185 =item *
186
187 height - limit the height in pixels of the image
188
189 =item *
190
191 bytes - limits the amount of storage used by the image.  This depends
192 on the width, height, channels and sample size of the image.  For
193 paletted images this is calculated as if the image was expanded to a
194 direct color image.
195
196 =back
197
198 To set the limits, call the class method set_file_limits:
199
200   Imager->set_file_limits(width=>$max_width, height=>$max_height);
201
202 You can pass any or all of the limits above, any limits you do not
203 pass are left as they were.
204
205 Any limit of zero is treated as unlimited.
206
207 By default, all of the limits are zero, or unlimited.
208
209 You can reset all of the limited to their defaults by passing in the
210 reset parameter as a true value:
211
212   # no limits
213   Imager->set_file_limits(reset=>1);
214
215 This can be used with the other limits to reset all but the limit you
216 pass:
217
218   # only width is limited
219   Imager->set_file_limits(reset=>1, width=>100);
220
221   # only bytes is limited
222   Imager->set_file_limits(reset=>1, bytes=>10_000_000);
223
224 You can get the current limits with the get_file_limits() method:
225
226   my ($max_width, $max_height, $max_bytes) =
227      Imager->get_file_limits();
228
229
230 =head1 TYPE SPECIFIC INFORMATION
231
232 The different image formats can write different image type, and some have
233 different options to control how the images are written.
234
235 When you call C<write()> or C<write_multi()> with an option that has
236 the same name as a tag for the image format you're writing, then the
237 value supplied to that option will be used to set the corresponding
238 tag in the image.  Depending on the image format, these values will be
239 used when writing the image.
240
241 This replaces the previous options that were used when writing GIF
242 images.  Currently if you use an obsolete option, it will be converted
243 to the equivalent tag and Imager will produced a warning.  You can
244 suppress these warnings by calling the C<Imager::init()> function with
245 the C<warn_obsolete> option set to false:
246
247   Imager::init(warn_obsolete=>0);
248
249 At some point in the future these obsolete options will no longer be
250 supported.
251
252 =head2 PNM (Portable aNy Map)
253
254 Imager can write PGM (Portable Gray Map) and PPM (Portable PixMaps)
255 files, depending on the number of channels in the image.  Currently
256 the images are written in binary formats.  Only 1 and 3 channel images
257 can be written, including 1 and 3 channel paletted images.
258
259   $img->write(file=>'foo.ppm') or die $img->errstr;
260
261 Imager can read both the ASCII and binary versions of each of the PBM
262 (Portable BitMap), PGM and PPM formats.
263
264   $img->read(file=>'foo.ppm') or die $img->errstr;
265
266 PNM does not support the spatial resolution tags.
267
268 =head2 JPEG
269
270 You can supply a C<jpegquality> parameter (0-100) when writing a JPEG
271 file, which defaults to 75%.  Only 1 and 3 channel images
272 can be written, including 1 and 3 channel paletted images.
273
274   $img->write(file=>'foo.jpg', jpegquality=>90) or die $img->errstr;
275
276 Imager will read a grayscale JPEG as a 1 channel image and a color
277 JPEG as a 3 channel image.
278
279   $img->read(file=>'foo.jpg') or die $img->errstr;
280
281 PNM does not support the spatial resolution tags.
282
283 =head2 GIF (Graphics Interchange Format)
284
285 When writing one of more GIF images you can use the same
286 L<Quantization Options|Imager::ImageTypes> as you can when converting
287 an RGB image into a paletted image.
288
289 When reading a GIF all of the sub-images are combined using the screen
290 size and image positions into one big image, producing an RGB image.
291 This may change in the future to produce a paletted image where possible.
292
293 When you read a single GIF with C<$img-E<gt>read()> you can supply a
294 reference to a scalar in the C<colors> parameter, if the image is read
295 the scalar will be filled with a reference to an anonymous array of
296 L<Imager::Color> objects, representing the palette of the image.  This
297 will be the first palette found in the image.  If you want the
298 palettes for each of the images in the file, use C<read_multi()> and
299 use the C<getcolors()> method on each image.
300
301 GIF does not support the spatial resolution tags.
302
303 Imager will set the following tags in each image when reading, and can
304 use most of them when writing to GIF:
305
306 =over
307
308 =item gif_left
309
310 the offset of the image from the left of the "screen" ("Image Left
311 Position")
312
313 =item gif_top
314
315 the offset of the image from the top of the "screen" ("Image Top Position")
316
317 =item gif_interlace
318
319 non-zero if the image was interlaced ("Interlace Flag")
320
321 =item gif_screen_width
322
323 =item gif_screen_height
324
325 the size of the logical screen. When writing this is used as the
326 minimum.  If any image being written would extend beyond this the
327 screen size is extended.  ("Logical Screen Width", "Logical Screen
328 Height").
329
330 When writing this is used as a minimum, if the combination of the
331 image size and the image's C<gif_left> and C<gif_top> is beyond this
332 size then the screen size will be expanded.
333
334 =item gif_local_map
335
336 Non-zero if this image had a local color map.  If set for an image
337 when writing the image is quantized separately from the other images
338 in the file.
339
340 =item gif_background
341
342 The index in the global colormap of the logical screen's background
343 color.  This is only set if the current image uses the global
344 colormap.  You can set this on write too, but for it to choose the
345 color you want, you will need to supply only paletted images and set
346 the C<gif_eliminate_unused> tag to 0.
347
348 =item gif_trans_index
349
350 The index of the color in the colormap used for transparency.  If the
351 image has a transparency then it is returned as a 4 channel image with
352 the alpha set to zero in this palette entry.  This value is not used
353 when writing. ("Transparent Color Index")
354
355 =item gif_trans_color
356
357 A reference to an Imager::Color object, which is the colour to use for
358 the palette entry used to represent transparency in the palette.  You
359 need to set the transp option (see L<Quantization options>) for this
360 value to be used.
361
362 =item gif_delay
363
364 The delay until the next frame is displayed, in 1/100 of a second. 
365 ("Delay Time").
366
367 =item gif_user_input
368
369 whether or not a user input is expected before continuing (view dependent) 
370 ("User Input Flag").
371
372 =item gif_disposal
373
374 how the next frame is displayed ("Disposal Method")
375
376 =item gif_loop
377
378 the number of loops from the Netscape Loop extension.  This may be zero.
379
380 =item gif_comment
381
382 the first block of the first gif comment before each image.
383
384 =item gif_eliminate_unused
385
386 If this is true, when you write a paletted image any unused colors
387 will be eliminated from its palette.  This is set by default.
388
389 =back
390
391 Where applicable, the ("name") is the name of that field from the GIF89 
392 standard.
393
394 The following gif writing options are obsolete, you should set the
395 corresponding tag in the image, either by using the tags functions, or
396 by supplying the tag and value as options.
397
398 =over
399
400 =item gif_each_palette
401
402 Each image in the gif file has it's own palette if this is non-zero.
403 All but the first image has a local colour table (the first uses the
404 global colour table.
405
406 Use C<gif_local_map> in new code.
407
408 =item interlace
409
410 The images are written interlaced if this is non-zero.
411
412 Use C<gif_interlace> in new code.
413
414 =item gif_delays
415
416 A reference to an array containing the delays between images, in 1/100
417 seconds.
418
419 Use C<gif_delay> in new code.
420
421 =item gif_positions
422
423 A reference to an array of references to arrays which represent screen
424 positions for each image.
425
426 New code should use the C<gif_left> and C<gif_top> tags.
427
428 =item gif_loop_count
429
430 If this is non-zero the Netscape loop extension block is generated,
431 which makes the animation of the images repeat.
432
433 This is currently unimplemented due to some limitations in giflib.
434
435 =back
436
437 You can supply a C<page> parameter to the C<read()> method to read
438 some page other than the first.  The page is 0 based:
439
440   # read the second image in the file
441   $image->read(file=>"example.gif", page=>1)
442     or die "Cannot read second page: ",$image->errstr,"\n";
443
444 Before release 0.46, Imager would read multi-image GIF image files
445 into a single image, overlaying each of the images onto the virtual
446 GIF screen.
447
448 As of 0.46 the default is to read the first image from the file, as if
449 called with C<< page => 0 >>.
450
451 You can return to the previous behaviour by calling read with the
452 C<gif_consolidate> parameter set to a true value:
453
454   $img->read(file=>$some_gif_file, gif_consolidate=>1);
455
456 =head2 TIFF (Tagged Image File Format)
457
458 Imager can write images to either paletted or RGB TIFF images,
459 depending on the type of the source image.  Currently if you write a
460 16-bit/sample or double/sample image it will be written as an
461 8-bit/sample image.  Only 1 or 3 channel images can be written.
462
463 If you are creating images for faxing you can set the I<class>
464 parameter set to C<fax>.  By default the image is written in fine
465 mode, but this can be overridden by setting the I<fax_fine> parameter
466 to zero.  Since a fax image is bi-level, Imager uses a threshold to
467 decide if a given pixel is black or white, based on a single channel.
468 For greyscale images channel 0 is used, for color images channel 1
469 (green) is used.  If you want more control over the conversion you can
470 use $img->to_paletted() to product a bi-level image.  This way you can
471 use dithering:
472
473   my $bilevel = $img->to_paletted(colors=>[ NC(0,0,0), NC(255,255,255) ],
474                                   make_colors => 'none',
475                                   translate => 'errdiff',
476                                   errdiff => 'stucki');
477
478 =over
479
480 =item class
481
482 If set to 'fax' the image will be written as a bi-level fax image.
483
484 =item fax_fine
485
486 By default when I<class> is set to 'fax' the image is written in fine
487 mode, you can select normal mode by setting I<fax_fine> to 0.
488
489 =back
490
491 Imager should be able to read any TIFF image you supply.  Paletted
492 TIFF images are read as paletted Imager images, since paletted TIFF
493 images have 16-bits/sample (48-bits/color) this means the bottom
494 8-bits are lost, but this shouldn't be a big deal.  Currently all
495 direct color images are read at 8-bits/sample.
496
497 TIFF supports the spatial resolution tags.  See the
498 C<tiff_resolutionunit> tag for some extra options.
499
500 The following tags are set in a TIFF image when read, and can be set
501 to control output:
502
503 =over
504
505 =item tiff_resolutionunit
506
507 The value of the ResolutionUnit tag.  This is ignored on writing if
508 the i_aspect_only tag is non-zero.
509
510 The C<i_xres> and C<i_yres> tags are expressed in pixels per inch no
511 matter tha value of this tag, they will be converted to/from the value
512 stored in the TIFF file.
513
514 =item tiff_resolutionunit_name
515
516 This is set when reading a TIFF file to the name of the unit given by
517 C<tiff_resolutionunit>.  Possible results include C<inch>,
518 C<centimeter>, C<none> (the C<i_aspect_only> tag is also set reading
519 these files) or C<unknown>.
520
521 =item tiff_bitspersample
522
523 Bits per sample from the image.  This value is not used when writing
524 an image, it is only set on a read image.
525
526 =item tiff_photometric
527
528 Value of the PhotometricInterpretation tag from the image.  This value
529 is not used when writing an image, it is only set on a read image.
530
531 =item tiff_documentname
532
533 =item tiff_imagedescription
534
535 =item tiff_make
536
537 =item tiff_model
538
539 =item tiff_pagename
540
541 =item tiff_software
542
543 =item tiff_datetime
544
545 =item tiff_artist
546
547 =item tiff_hostcomputer
548
549 Various strings describing the image.  tiff_datetime must be formatted
550 as "YYYY:MM:DD HH:MM:SS".  These correspond directly to the mixed case
551 names in the TIFF specification.  These are set in images read from a
552 TIFF and saved when writing a TIFF image.
553
554 You can supply a C<page> parameter to the C<read()> method to read
555 some page other than the first.  The page is 0 based:
556
557   # read the second image in the file
558   $image->read(file=>"example.tif", page=>1)
559     or die "Cannot read second page: ",$image->errstr,"\n";
560
561 =back
562
563 =head2 BMP (BitMaP)
564
565 Imager can write 24-bit RGB, and 8, 4 and 1-bit per pixel paletted
566 Windows BMP files.  Currently you cannot write compressed BMP files
567 with Imager.
568
569 Imager can read 24-bit RGB, and 8, 4 and 1-bit perl pixel paletted
570 Windows BMP files.  There is some support for reading 16-bit per pixel
571 images, but I haven't found any for testing.
572
573 BMP has no support for multi-image files.
574
575 BMP files support the spatial resolution tags, but since BMP has no
576 support for storing only an aspect ratio, if C<i_aspect_only> is set
577 when you write the C<i_xres> and C<i_yres> values are scaled so the
578 smaller is 72 DPI.
579
580 The following tags are set when you read an image from a BMP file:
581
582 =over
583
584 =item bmp_compression
585
586 The type of compression, if any.  This can be any of the following
587 values:
588
589 =over
590
591 =item BI_RGB (0)
592
593 Uncompressed.
594
595 =item BI_RLE8 (1)
596
597 8-bits/pixel paletted value RLE compression.
598
599 =item BI_RLE4 (2)
600
601 4-bits/pixel paletted value RLE compression.
602
603 =item BI_BITFIELDS (3)
604
605 Packed RGB values.
606
607 =back
608
609 =item bmp_compression_name
610
611 The bmp_compression value as a BI_* string
612
613 =item bmp_important_colors
614
615 The number of important colors as defined by the writer of the image.
616
617 =item bmp_used_colors
618
619 Number of color used from the BMP header
620
621 =item bmp_filesize
622
623 The file size from the BMP header
624
625 =item bmp_bit_count
626
627 Number of bits stored per pixel. (24, 8, 4 or 1)
628
629 =back
630
631 =head2 TGA (TarGA)
632
633 When storing targa images rle compression can be activated with the
634 'compress' parameter, the 'idstring' parameter can be used to set the
635 targa comment field and the 'wierdpack' option can be used to use the
636 15 and 16 bit targa formats for rgb and rgba data.  The 15 bit format
637 has 5 of each red, green and blue.  The 16 bit format in addition
638 allows 1 bit of alpha.  The most significant bits are used for each
639 channel.
640
641
642 Tags:
643
644 =over
645
646 =item tga_idstring
647
648 =item tga_bitspp
649
650 =item compressed
651
652 =back
653
654 =head2 RAW
655
656 When reading raw images you need to supply the width and height of the
657 image in the xsize and ysize options:
658
659   $img->read(file=>'foo.raw', xsize=>100, ysize=>100)
660     or die "Cannot read raw image\n";
661
662 If your input file has more channels than you want, or (as is common),
663 junk in the fourth channel, you can use the datachannels and
664 storechannels options to control the number of channels in your input
665 file and the resulting channels in your image.  For example, if your
666 input image uses 32-bits per pixel with red, green, blue and junk
667 values for each pixel you could do:
668
669   $img->read(file=>'foo.raw', xsize=>100, ysize=>100, datachannels=>4,
670              storechannels=>3)
671     or die "Cannot read raw image\n";
672
673 Normally the raw image is expected to have the value for channel 1
674 immediately following channel 0 and channel 2 immediately following
675 channel 1 for each pixel.  If your input image has all the channel 0
676 values for the first line of the image, followed by all the channel 1
677 values for the first line and so on, you can use the interleave option:
678
679   $img->read(file=>'foo.raw', xsize=100, ysize=>100, interleave=>1)
680     or die "Cannot read raw image\n";
681
682 =head2 PNG
683
684 There are no PNG specific tags.
685
686 =head1 EXAMPLES
687
688 =head2 Producing an image from a CGI script
689
690 Once you have an image the basic mechanism is:
691
692 =over
693
694 =item 1.
695
696 set STDOUT to autoflush
697
698 =item 2.
699
700 output a content-type header, and optionally a content-length header
701
702 =item 3.
703
704 put STDOUT into binmode
705
706 =item 4.
707
708 call write() with the C<fd> or C<fh> parameter.  You will need to
709 provide the C<type> parameter since Imager can't use the extension to
710 guess the file format you want.
711
712 =back
713
714   # write an image from a CGI script
715   # using CGI.pm
716   use CGI qw(:standard);
717   $| = 1;
718   binmode STDOUT;
719   print header(-type=>'image/gif');
720   $img->write(type=>'gif', fd=>fileno(STDOUT))
721     or die $img->errstr;
722
723 If you want to send a content length you can send the output to a
724 scalar to get the length:
725
726   my $data;
727   $img->write(type=>'gif', data=>\$data)
728     or die $img->errstr;
729   binmode STDOUT;
730   print header(-type=>'image/gif', -content_length=>length($data));
731   print $data;
732
733 =head2 Writing an animated GIF
734
735 The basic idea is simple, just use write_multi():
736
737   my @imgs = ...;
738   Imager->write_multi({ file=>$filename, type=>'gif' }, @imgs);
739
740 If your images are RGB images the default quantization mechanism will
741 produce a very good result, but can take a long time to execute.  You
742 could either use the standard webmap:
743
744   Imager->write_multi({ file=>$filename, 
745                         type=>'gif',
746                         make_colors=>'webmap' },
747                       @imgs);
748
749 or use a median cut algorithm to built a fairly optimal color map:
750
751   Imager->write_multi({ file=>$filename,
752                         type=>'gif',
753                         make_colors=>'mediancut' },
754                       @imgs);
755
756 By default all of the images will use the same global colormap, which
757 will produce a smaller image.  If your images have significant color
758 differences, you may want to generate a new palette for each image:
759
760   Imager->write_multi({ file=>$filename,
761                         type=>'gif',
762                         make_colors=>'mediancut',
763                         gif_local_map => 1 },
764                       @imgs);
765
766 which will set the C<gif_local_map> tag in each image to 1.
767 Alternatively, if you know only some images have different colors, you
768 can set the tag just for those images:
769
770   $imgs[2]->settag(name=>'gif_local_map', value=>1);
771   $imgs[4]->settag(name=>'gif_local_map', value=>1);
772
773 and call write_multi() without a C<gif_local_map> parameter, or supply
774 an arrayref of values for the tag:
775
776   Imager->write_multi({ file=>$filename,
777                         type=>'gif',
778                         make_colors=>'mediancut',
779                         gif_local_map => [ 0, 0, 1, 0, 1 ] },
780                       @imgs);
781
782 Other useful parameters include C<gif_delay> to control the delay
783 between frames and C<transp> to control transparency.
784
785 =head2 Reading tags after reading an image
786
787 This is pretty simple:
788
789   # print the author of a TIFF, if any
790   my $img = Imager->new;
791   $img->read(file=>$filename, type='tiff') or die $img->errstr;
792   my $author = $img->tags(name=>'tiff_author');
793   if (defined $author) {
794     print "Author: $author\n";
795   }
796
797 =head1 BUGS
798
799 When saving Gif images the program does NOT try to shave of extra
800 colors if it is possible.  If you specify 128 colors and there are
801 only 2 colors used - it will have a 128 colortable anyway.
802
803 =head1 SEE ALSO
804
805 Imager(3)
806
807 =cut