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       rotate() - "rotate()" in Imager::Transformations
348
349       rubthrough() - "rubthrough()" in Imager::Transformations - draw an
350       image onto an image and use the alpha channel
351
352       scale() - "scale()" in Imager::Transformations
353
354       scale_calculate() - "scale_calculate()" in Imager::Transformations
355
356       scaleX() - "scaleX()" in Imager::Transformations
357
358       scaleY() - "scaleY()" in Imager::Transformations
359
360       setcolors() - "setcolors()" in Imager::ImageTypes - set palette colors
361       in a paletted image
362
363       set_file_limits() - "set_file_limits()" in Imager::Files
364
365       setmask() - "setmask()" in Imager::ImageTypes
366
367       setpixel() - "setpixel()" in Imager::Draw
368
369       setsamples() - "setsamples()" in Imager::Draw
370
371       setscanline() - "setscanline()" in Imager::Draw
372
373       settag() - "settag()" in Imager::ImageTypes
374
375       string() - "string()" in Imager::Draw - draw text on an image
376
377       tags() -  "tags()" in Imager::ImageTypes - fetch image tags
378
379       to_paletted() -  "to_paletted()" in Imager::ImageTypes
380
381       to_rgb16() - "to_rgb16()" in Imager::ImageTypes
382
383       to_rgb8() - "to_rgb8()" in Imager::ImageTypes
384
385       to_rgb_double() - "to_rgb_double()" in Imager::ImageTypes - convert to
386       double per sample image.
387
388       transform() - "transform()" in Imager::Engines
389
390       transform2() - "transform2()" in Imager::Engines
391
392       type() -  "type()" in Imager::ImageTypes - type of image (direct vs
393       paletted)
394
395       unload_plugin() - "unload_plugin()" in Imager::Filters
396
397       virtual() - "virtual()" in Imager::ImageTypes - whether the image has
398       it's own data
399
400       write() - "write()" in Imager::Files - write an image to a file
401
402       write_multi() - "write_multi()" in Imager::Files - write multiple image
403       to an image file.
404
405       write_types() - "read_types()" in Imager::Files - list image types
406       Imager can write.
407

CONCEPT INDEX

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

SUPPORT

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

CONTRIBUTING TO IMAGER

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

AUTHOR

646       Tony Cook <tonyc@cpan.org> is the current maintainer for Imager.
647
648       Arnar M. Hrafnkelsson is the original author of Imager.
649
650       Many others have contributed to Imager, please see the "README" for a
651       complete list.
652

LICENSE

654       Imager is licensed under the same terms as perl itself.
655
656       A test font, generated by the Debian packaged Fontforge,
657       FT2/fontfiles/MMOne.pfb, contains a Postscript operator definition
658       copyrighted by Adobe.  See adobe.txt in the source for license
659       information.
660