Imager(3pm)

1Imager(3)             User Contributed Perl Documentation            Imager(3)
2
3
4

NAME

6       Imager - Perl extension for Generating 24 bit Images
7

SYNOPSIS

9         # Thumbnail example
10
11         #!/usr/bin/perl -w
12         use strict;
13         use Imager;
14
15         die "Usage: thumbmake.pl filename\n" if !-f $ARGV[0];
16         my $file = shift;
17
18         my $format;
19
20         # see Imager::Files for information on the read() method
21         my $img = Imager->new(file=>$file)
22           or die Imager->errstr();
23
24         $file =~ s/\.[^.]*$//;
25
26         # Create smaller version
27         # documented in Imager::Transformations
28         my $thumb = $img->scale(scalefactor=>.3);
29
30         # Autostretch individual channels
31         $thumb->filter(type=>'autolevels');
32
33         # try to save in one of these formats
34         SAVE:
35
36         for $format ( qw( png gif jpeg tiff ppm ) ) {
37           # Check if given format is supported
38           if ($Imager::formats{$format}) {
39             $file.="_low.$format";
40             print "Storing image as: $file\n";
41             # documented in Imager::Files
42             $thumb->write(file=>$file) or
43               die $thumb->errstr;
44             last SAVE;
45           }
46         }
47

DESCRIPTION

49       Imager is a module for creating and altering images.  It can read and
50       write various image formats, draw primitive shapes like lines,and
51       polygons, blend multiple images together in various ways, scale, crop,
52       render text and more.
53
54   Overview of documentation
55       •   Imager - This document - Synopsis, Example, Table of Contents and
56           Overview.
57
58       •   Imager::Install - installation notes for Imager.
59
60       •   Imager::Tutorial - a brief introduction to Imager.
61
62       •   Imager::Cookbook - how to do various things with Imager.
63
64       •   Imager::ImageTypes - Basics of constructing image objects with
65           "new()": Direct type/virtual images, RGB(A)/paletted images,
66           8/16/double bits/channel, color maps, channel masks, image tags,
67           color quantization.  Also discusses basic image information
68           methods.
69
70       •   Imager::Files - IO interaction, reading/writing images, format
71           specific tags.
72
73       •   Imager::Draw - Drawing Primitives, lines, boxes, circles, arcs,
74           flood fill.
75
76       •   Imager::Color - Color specification.
77
78       •   Imager::Fill - Fill pattern specification.
79
80       •   Imager::Font - General font rendering, bounding boxes and font
81           metrics.
82
83       •   Imager::Transformations - Copying, scaling, cropping, flipping,
84           blending, pasting, convert and map.
85
86       •   Imager::Engines - Programmable transformations through
87           "transform()", "transform2()" and "matrix_transform()".
88
89       •   Imager::Filters - Filters, sharpen, blur, noise, convolve etc. and
90           filter plug-ins.
91
92       •   Imager::Expr - Expressions for evaluation engine used by
93           transform2().
94
95       •   Imager::Matrix2d - Helper class for affine transformations.
96
97       •   Imager::Fountain - Helper for making gradient profiles.
98
99       •   Imager::IO - Imager I/O abstraction.
100
101       •   Imager::API - using Imager's C API
102
103       •   Imager::APIRef - API function reference
104
105       •   Imager::Inline - using Imager's C API from Inline::C
106
107       •   Imager::ExtUtils - tools to get access to Imager's C API.
108
109       •   Imager::Security - brief security notes.
110
111       •   Imager::Threads - brief information on working with threads.
112
113   Basic Overview
114       An Image object is created with "$img = Imager->new()".  Examples:
115
116         $img=Imager->new();                         # create empty image
117         $img->read(file=>'lena.png',type=>'png') or # read image from file
118            die $img->errstr();                      # give an explanation
119                                                     # if something failed
120
121       or if you want to create an empty image:
122
123         $img=Imager->new(xsize=>400,ysize=>300,channels=>4);
124
125       This example creates a completely black image of width 400 and height
126       300 and 4 channels.
127

ERROR HANDLING

129       In general a method will return false when it fails, if it does use the
130       "errstr()" method to find out why:
131
132       errstr()
133           Returns the last error message in that context.
134
135           If the last error you received was from calling an object method,
136           such as read, call errstr() as an object method to find out why:
137
138             my $image = Imager->new;
139             $image->read(file => 'somefile.gif')
140                or die $image->errstr;
141
142           If it was a class method then call errstr() as a class method:
143
144             my @imgs = Imager->read_multi(file => 'somefile.gif')
145               or die Imager->errstr;
146
147           Note that in some cases object methods are implemented in terms of
148           class methods so a failing object method may set both.
149
150       The "Imager->new" method is described in detail in Imager::ImageTypes.
151

METHOD INDEX

153       Where to find information on methods for Imager class objects.
154
155       addcolors() - "addcolors()" in Imager::ImageTypes - add colors to a
156       paletted image
157
158       add_file_magic() - "add_file_magic()" in Imager::Files - add magic to
159       Imager's file type detector.
160
161       addtag() -  "addtag()" in Imager::ImageTypes - add image tags
162
163       add_type_extensions() - "add_file_magic()" in Imager::Files - add magic
164       for new image file types.
165
166       "add_type_extensions($type, $ext, ...)" in Imager::Files - add
167       extensions for new image file types.
168
169       align_string() - "align_string()" in Imager::Draw - draw text aligned
170       on a point
171
172       alphachannel() - "alphachannel()" in Imager::ImageTypes - return the
173       channel index of the alpha channel (if any).
174
175       arc() - "arc()" in Imager::Draw - draw a filled arc
176
177       bits() - "bits()" in Imager::ImageTypes - number of bits per sample for
178       the image
179
180       box() - "box()" in Imager::Draw - draw a filled or outline box.
181
182       check_file_limits() - "check_file_limits()" in Imager::Files
183
184       circle() - "circle()" in Imager::Draw - draw a filled circle
185
186       close_log() - "close_log()" in Imager::ImageTypes - close the Imager
187       debugging log.
188
189       colorchannels() - "colorchannels()" in Imager::ImageTypes - the number
190       of channels used for color.
191
192       colorcount() - "colorcount()" in Imager::ImageTypes - the number of
193       colors in an image's palette (paletted images only)
194
195       colormodel() - "colorcount()" in Imager::ImageTypes - how color is
196       represented.
197
198       combine() - "combine()" in Imager::Transformations - combine channels
199       from one or more images.
200
201       combines() - "combines()" in Imager::Draw - return a list of the
202       different combine type keywords
203
204       compose() - "compose()" in Imager::Transformations - compose one image
205       over another.
206
207       convert() - "convert()" in Imager::Transformations - transform the
208       color space
209
210       copy() - "copy()" in Imager::Transformations - make a duplicate of an
211       image
212
213       crop() - "crop()" in Imager::Transformations - extract part of an image
214
215       def_guess_type() - "def_guess_type()" in Imager::Files - default
216       function used to guess the output file format based on the output file
217       name
218
219       deltag() -  "deltag()" in Imager::ImageTypes - delete image tags
220
221       difference() - "difference()" in Imager::Filters - produce a difference
222       images from two input images.
223
224       errstr() - "errstr()" - the error from the last failed operation.
225
226       filter() - "filter()" in Imager::Filters - image filtering
227
228       findcolor() - "findcolor()" in Imager::ImageTypes - search the image
229       palette, if it has one
230
231       flip() - "flip()" in Imager::Transformations - flip an image,
232       vertically, horizontally
233
234       flood_fill() - "flood_fill()" in Imager::Draw - fill an enclosed or
235       same color area
236
237       getchannels() - "getchannels()" in Imager::ImageTypes - the number of
238       samples per pixel for an image
239
240       getcolorcount() - "getcolorcount()" in Imager::ImageTypes - the number
241       of different colors used by an image (works for direct color images)
242
243       getcolors() - "getcolors()" in Imager::ImageTypes - get colors from the
244       image palette, if it has one
245
246       getcolorusage() - "getcolorusage()" in Imager::ImageTypes
247
248       getcolorusagehash() - "getcolorusagehash()" in Imager::ImageTypes
249
250       get_file_limits() - "get_file_limits()" in Imager::Files
251
252       getheight() - "getheight()" in Imager::ImageTypes - height of the image
253       in pixels
254
255       getmask() - "getmask()" in Imager::ImageTypes - write mask for the
256       image
257
258       getpixel() - "getpixel()" in Imager::Draw - retrieve one or more pixel
259       colors
260
261       getsamples() - "getsamples()" in Imager::Draw - retrieve samples from a
262       row or partial row of pixels.
263
264       getscanline() - "getscanline()" in Imager::Draw - retrieve colors for a
265       row or partial row of pixels.
266
267       getwidth() - "getwidth()" in Imager::ImageTypes - width of the image in
268       pixels.
269
270       img_set() - "img_set()" in Imager::ImageTypes - re-use an Imager object
271       for a new image.
272
273       init() - "init()" in Imager::ImageTypes
274
275       is_bilevel() - "is_bilevel()" in Imager::ImageTypes - returns whether
276       image write functions should write the image in their bilevel (blank
277       and white, no gray levels) format
278
279       is_logging() - "is_logging()" in Imager::ImageTypes - test if the debug
280       log is active.
281
282       line() - "line()" in Imager::Draw - draw an interval
283
284       load_plugin() - "load_plugin()" in Imager::Filters
285
286       log() - "log()" in Imager::ImageTypes - send a message to the debugging
287       log.
288
289       make_palette() - "make_palette()" in Imager::ImageTypes - produce a
290       color palette from one or more input images.
291
292       map() - "map()" in Imager::Transformations - remap color channel values
293
294       masked() -  "masked()" in Imager::ImageTypes - make a masked image
295
296       matrix_transform() - "matrix_transform()" in Imager::Engines
297
298       maxcolors() - "maxcolors()" in Imager::ImageTypes
299
300       NC() - "NC()" in Imager::Handy
301
302       NCF() - "NCF()" in Imager::Handy
303
304       new() - "new()" in Imager::ImageTypes
305
306       newcolor() - "newcolor()" in Imager::Handy
307
308       newcolour() - "newcolour()" in Imager::Handy
309
310       newfont() - "newfont()" in Imager::Handy
311
312       NF() - "NF()" in Imager::Handy
313
314       open() - "read()" in Imager::Files - an alias for read()
315
316       open_log() - "open_log()" in Imager::ImageTypes - open the debug log.
317
318       parseiptc() - "parseiptc()" in Imager::Files - parse IPTC data from a
319       JPEG image
320
321       paste() - "paste()" in Imager::Transformations - draw an image onto an
322       image
323
324       polygon() - "polygon()" in Imager::Draw
325
326       polyline() - "polyline()" in Imager::Draw
327
328       polypolygon() - "polypolygon()" in Imager::Draw
329
330       preload() - "preload()" in Imager::Files
331
332       read() - "read()" in Imager::Files - read a single image from an image
333       file
334
335       read_multi() - "read_multi()" in Imager::Files - read multiple images
336       from an image file
337
338       read_types() - "read_types()" in Imager::Files - list image types
339       Imager can read.
340
341       register_filter() - "register_filter()" in Imager::Filters
342
343       register_reader() - "register_reader()" in Imager::Files
344
345       register_writer() - "register_writer()" in Imager::Files
346
347       rgb_difference() - "rgb_difference()" in Imager::Filters - produce a
348       difference images from two input images.
349
350       rotate() - "rotate()" in Imager::Transformations
351
352       rubthrough() - "rubthrough()" in Imager::Transformations - draw an
353       image onto an image and use the alpha channel
354
355       scale() - "scale()" in Imager::Transformations
356
357       scale_calculate() - "scale_calculate()" in Imager::Transformations
358
359       scaleX() - "scaleX()" in Imager::Transformations
360
361       scaleY() - "scaleY()" in Imager::Transformations
362
363       setcolors() - "setcolors()" in Imager::ImageTypes - set palette colors
364       in a paletted image
365
366       set_file_limits() - "set_file_limits()" in Imager::Files
367
368       setmask() - "setmask()" in Imager::ImageTypes
369
370       setpixel() - "setpixel()" in Imager::Draw
371
372       setsamples() - "setsamples()" in Imager::Draw
373
374       setscanline() - "setscanline()" in Imager::Draw
375
376       settag() - "settag()" in Imager::ImageTypes
377
378       string() - "string()" in Imager::Draw - draw text on an image
379
380       tags() -  "tags()" in Imager::ImageTypes - fetch image tags
381
382       to_paletted() -  "to_paletted()" in Imager::ImageTypes
383
384       to_rgb16() - "to_rgb16()" in Imager::ImageTypes
385
386       to_rgb8() - "to_rgb8()" in Imager::ImageTypes
387
388       to_rgb_double() - "to_rgb_double()" in Imager::ImageTypes - convert to
389       double per sample image.
390
391       transform() - "transform()" in Imager::Engines
392
393       transform2() - "transform2()" in Imager::Engines
394
395       trim() - "trim()" in Imager::Transformations - return a cropped image
396       based on border transparency or border colors.
397
398       trim_rect() - "trim_rect()" in Imager::Transformations - return how
399       much trim() would remove.
400
401       type() -  "type()" in Imager::ImageTypes - type of image (direct vs
402       paletted)
403
404       unload_plugin() - "unload_plugin()" in Imager::Filters
405
406       virtual() - "virtual()" in Imager::ImageTypes - whether the image has
407       it's own data
408
409       write() - "write()" in Imager::Files - write an image to a file
410
411       write_multi() - "write_multi()" in Imager::Files - write multiple image
412       to an image file.
413
414       write_types() - "read_types()" in Imager::Files - list image types
415       Imager can write.
416

CONCEPT INDEX

418       animated GIF - "Writing an animated GIF" in Imager::Files
419
420       aspect ratio - "i_xres", "i_yres", "i_aspect_only" in "Common Tags" in
421       Imager::ImageTypes.
422
423       blend - alpha blending one image onto another "rubthrough()" in
424       Imager::Transformations
425
426       blur - ""gaussian"" in Imager::Filters, ""conv"" in Imager::Filters
427
428       boxes, drawing - "box()" in Imager::Draw
429
430       changes between image - "Image Difference" in Imager::Filters
431
432       channels, combine into one image - "combine()" in
433       Imager::Transformations
434
435       color - Imager::Color
436
437       color names - Imager::Color, Imager::Color::Table
438
439       combine modes - "Combine Types" in Imager::Draw
440
441       compare images - "Image Difference" in Imager::Filters
442
443       contrast - ""contrast"" in Imager::Filters, ""autolevels"" in
444       Imager::Filters
445
446       convolution - ""conv"" in Imager::Filters
447
448       cropping - "crop()" in Imager::Transformations, "trim()" in
449       Imager::Transformations
450
451       CUR files - "ICO (Microsoft Windows Icon) and CUR (Microsoft Windows
452       Cursor)" in Imager::Files
453
454       "diff" images - "Image Difference" in Imager::Filters
455
456       dpi - "i_xres", "i_yres" in "Common Tags" in Imager::ImageTypes, "Image
457       spatial resolution" in Imager::Cookbook
458
459       drawing boxes - "box()" in Imager::Draw
460
461       drawing lines - "line()" in Imager::Draw
462
463       drawing text - "string()" in Imager::Draw, "align_string()" in
464       Imager::Draw
465
466       error message - "ERROR HANDLING"
467
468       files, font - Imager::Font
469
470       files, image - Imager::Files
471
472       filling, types of fill - Imager::Fill
473
474       filling, boxes - "box()" in Imager::Draw
475
476       filling, flood fill - "flood_fill()" in Imager::Draw
477
478       flood fill - "flood_fill()" in Imager::Draw
479
480       fonts - Imager::Font
481
482       fonts, drawing with - "string()" in Imager::Draw, "align_string()" in
483       Imager::Draw, Imager::Font::Wrap
484
485       fonts, metrics - "bounding_box()" in Imager::Font, Imager::Font::BBox
486
487       fonts, multiple master - "MULTIPLE MASTER FONTS" in Imager::Font
488
489       fountain fill - "Fountain fills" in Imager::Fill, ""fountain"" in
490       Imager::Filters, Imager::Fountain, ""gradgen"" in Imager::Filters
491
492       GIF files - "GIF" in Imager::Files
493
494       GIF files, animated - "Writing an animated GIF" in Imager::Files
495
496       gradient fill - "Fountain fills" in Imager::Fill, ""fountain"" in
497       Imager::Filters, Imager::Fountain, ""gradgen"" in Imager::Filters
498
499       gray scale, convert image to - "convert()" in Imager::Transformations
500
501       gaussian blur - ""gaussian"" in Imager::Filters, ""gaussian2"" in
502       Imager::Filters
503
504       hatch fills - "Hatched fills" in Imager::Fill
505
506       ICO files - "ICO (Microsoft Windows Icon) and CUR (Microsoft Windows
507       Cursor)" in Imager::Files
508
509       invert image - ""hardinvert"" in Imager::Filters, ""hardinvertall"" in
510       Imager::Filters
511
512       JPEG - "JPEG" in Imager::Files
513
514       limiting image sizes - "Limiting the sizes of images you read" in
515       Imager::Files
516
517       lines, drawing - "line()" in Imager::Draw
518
519       matrix - Imager::Matrix2d, "Matrix Transformations" in Imager::Engines,
520       "transform()" in Imager::Font
521
522       metadata, image - "Tags" in Imager::ImageTypes, Image::ExifTool
523
524       mosaic - ""mosaic"" in Imager::Filters
525
526       noise, filter - ""noise"" in Imager::Filters
527
528       noise, rendered - ""turbnoise"" in Imager::Filters, ""radnoise"" in
529       Imager::Filters
530
531       paste - "paste()" in Imager::Transformations, "rubthrough()" in
532       Imager::Transformations
533
534       pseudo-color image - "to_paletted()" in Imager::ImageTypes, "new()" in
535       Imager::ImageTypes
536
537       posterize - ""postlevels"" in Imager::Filters
538
539       PNG files - Imager::Files, "PNG" in Imager::Files
540
541       PNM - "PNM (Portable aNy Map)" in Imager::Files
542
543       rectangles, drawing - "box()" in Imager::Draw
544
545       resizing an image - "scale()" in Imager::Transformations, "crop()" in
546       Imager::Transformations
547
548       RGB (SGI) files - "SGI (RGB, BW)" in Imager::Files
549
550       saving an image - Imager::Files
551
552       scaling - "scale()" in Imager::Transformations
553
554       security - Imager::Security
555
556       SGI files - "SGI (RGB, BW)" in Imager::Files
557
558       sharpen - ""unsharpmask"" in Imager::Filters, ""conv"" in
559       Imager::Filters
560
561       size, image - "getwidth()" in Imager::ImageTypes, "getheight()" in
562       Imager::ImageTypes
563
564       size, text - "bounding_box()" in Imager::Font
565
566       tags, image metadata - "Tags" in Imager::ImageTypes
567
568       text, drawing - "string()" in Imager::Draw, "align_string()" in
569       Imager::Draw, Imager::Font::Wrap
570
571       text, wrapping text in an area - Imager::Font::Wrap
572
573       text, measuring - "bounding_box()" in Imager::Font, Imager::Font::BBox
574
575       threads - Imager::Threads
576
577       tiles, color - ""mosaic"" in Imager::Filters
578
579       transparent images - Imager::ImageTypes, "Transparent PNG" in
580       Imager::Cookbook
581
582       unsharp mask - ""unsharpmask"" in Imager::Filters
583
584       watermark - ""watermark"" in Imager::Filters
585
586       writing an image to a file - Imager::Files
587

SUPPORT

589       The best place to get help with Imager is the mailing list.
590
591       To subscribe send a message with "subscribe" in the body to:
592
593          imager-devel+request@molar.is
594
595       or use the form at:
596
597           <http://www.molar.is/en/lists/imager-devel/>
598
599       where you can also find the mailing list archive.
600
601       You can report bugs either via github at:
602
603           <https://github.com/tonycoz/imager/issues>
604
605       or at:
606
607           <https://rt.cpan.org/NoAuth/ReportBug.html?Queue=Imager>
608
609       or by sending an email to:
610
611           bug-Imager@rt.cpan.org
612
613       Please remember to include the versions of Imager, perl, supporting
614       libraries, and any relevant code.  If you have specific images that
615       cause the problems, please include those too.
616

CONTRIBUTING TO IMAGER

618   Feedback
619       I like feedback.
620
621       You can send email to the maintainer below.
622
623       If you send me a bug report via email, it will be copied to Request
624       Tracker.
625
626   Patches
627       I accept patches, preferably against the master branch in git.  Please
628       include an explanation of the reason for why the patch is needed or
629       useful.
630
631       Your patch should include regression tests where possible, otherwise it
632       will be delayed until I get a chance to write them.
633
634       To browse Imager's git repository:
635
636         https://github.com/tonycoz/imager.git
637
638       To clone:
639
640         git clone git://github.com/tonycoz/imager.git
641
642       Or you can create a fork as usual on github and submit a github pull
643       request.
644
645       Patches can either be submitted as a github pull request or by using
646       "git format-patch", for example, if you made your changes in a branch
647       from master you might do:
648
649         git format-patch -k --stdout master >my-patch.txt
650
651       and then attach that to your bug report, either by adding it as an
652       attachment in your email client, or by using the Request Tracker
653       attachment mechanism.
654

AUTHOR

656       Tony Cook <tonyc@cpan.org> is the current maintainer for Imager.
657
658       Arnar M. Hrafnkelsson is the original author of Imager.
659
660       Many others have contributed to Imager, please see the "README" for a
661       complete list.
662

LICENSE

664       Imager is licensed under the same terms as perl itself.
665
666       A test font, generated by the Debian packaged Fontforge,
667       FT2/fontfiles/MMOne.pfb, contains a Postscript operator definition
668       copyrighted by Adobe.  See adobe.txt in the source for license
669       information.
670