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         my $img = Imager->new();
21         # see Imager::Files for information on the read() method
22         $img->read(file=>$file) or die $img->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 jpg 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 poly‐
51       gons, blend multiple images together in various ways, scale, crop, ren‐
52       der text and more.
53
54       Overview of documentation
55
56       ·   Imager - This document - Synopsis, Example, Table of Contents and
57           Overview.
58
59       ·   Imager::Tutorial - a brief introduction to Imager.
60
61       ·   Imager::Cookbook - how to do various things with Imager.
62
63       ·   Imager::ImageTypes - Basics of constructing image objects with
64           "new()": Direct type/virtual images, RGB(A)/paletted images,
65           8/16/double bits/channel, color maps, channel masks, image tags,
66           color quantization.  Also discusses basic image information meth‐
67           ods.
68
69       ·   Imager::Files - IO interaction, reading/writing images, format spe‐
70           cific tags.
71
72       ·   Imager::Draw - Drawing Primitives, lines, boxes, circles, arcs,
73           flood fill.
74
75       ·   Imager::Color - Color specification.
76
77       ·   Imager::Fill - Fill pattern specification.
78
79       ·   Imager::Font - General font rendering, bounding boxes and font met‐
80           rics.
81
82       ·   Imager::Transformations - Copying, scaling, cropping, flipping,
83           blending, pasting, convert and map.
84
85       ·   Imager::Engines - Programmable transformations through "trans‐
86           form()", "transform2()" and "matrix_transform()".
87
88       ·   Imager::Filters - Filters, sharpen, blur, noise, convolve etc. and
89           filter plugins.
90
91       ·   Imager::Expr - Expressions for evaluation engine used by trans‐
92           form2().
93
94       ·   Imager::Matrix2d - Helper class for affine transformations.
95
96       ·   Imager::Fountain - Helper for making gradient profiles.
97
98       ·   Imager::API - using Imager's C API
99
100       ·   Imager::APIRef - API function reference
101
102       ·   Imager::Inline - using Imager's C API from Inline::C
103
104       ·   Imager::ExtUtils - tools to get access to Imager's C API.
105
106       Basic Overview
107
108       An Image object is created with "$img = Imager->new()".  Examples:
109
110         $img=Imager->new();                         # create empty image
111         $img->read(file=>'lena.png',type=>'png') or # read image from file
112            die $img->errstr();                      # give an explanation
113                                                     # if something failed
114
115       or if you want to create an empty image:
116
117         $img=Imager->new(xsize=>400,ysize=>300,channels=>4);
118
119       This example creates a completely black image of width 400 and height
120       300 and 4 channels.
121

ERROR HANDLING

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

METHOD INDEX

147       Where to find information on methods for Imager class objects.
148
149       addcolors() -  "addcolors" in Imager::ImageTypes
150
151       addtag() -  "addtag" in Imager::ImageTypes - add image tags
152
153       align_string() - "align_string" in Imager::Draw
154
155       arc() - "arc" in Imager::Draw
156
157       bits() - "bits" in Imager::ImageTypes - number of bits per sample for
158       the image
159
160       box() - "box" in Imager::Draw
161
162       circle() - "circle" in Imager::Draw
163
164       colorcount() - "colorcount" in Imager::Draw
165
166       combines() - "combines" in Imager::Draw
167
168       compose() - "compose" in Imager::Transformations
169
170       convert() - "Color transformations" in Imager::Transformations - trans‐
171       form the color space
172
173       copy() - "copy" in Imager::Transformations
174
175       crop() - "crop" in Imager::Transformations - extract part of an image
176
177       def_guess_type() - "def_guess_type" in Imager::Files
178
179       deltag() -  "deltag" in Imager::ImageTypes - delete image tags
180
181       difference() - "Image Difference" in Imager::Filters
182
183       errstr() - "Basic Overview"
184
185       filter() - Imager::Filters
186
187       findcolor() - "findcolor" in Imager::ImageTypes - search the image pal‐
188       ette, if it has one
189
190       flip() - "flip" in Imager::Transformations
191
192       flood_fill() - "flood_fill" in Imager::Draw
193
194       getchannels() -  "getchannels" in Imager::ImageTypes
195
196       getcolorcount() -  "getcolorcount" in Imager::ImageTypes
197
198       getcolors() - "getcolors" in Imager::ImageTypes - get colors from the
199       image palette, if it has one
200
201       getcolorusage() - "getcolorusage" in Imager::ImageTypes
202
203       getcolorusagehash() - "getcolorusagehash" in Imager::ImageTypes
204
205       get_file_limits() - "Limiting the sizes of images you read" in
206       Imager::Files
207
208       getheight() - "getwidth" in Imager::ImageTypes
209
210       getmask() - "getmask" in Imager::ImageTypes
211
212       getpixel() - "getpixel" in Imager::Draw
213
214       getsamples() - "getsamples" in Imager::Draw
215
216       getscanline() - "getscanline" in Imager::Draw
217
218       getwidth() - "getwidth" in Imager::ImageTypes
219
220       img_set() - "img_set" in Imager::ImageTypes
221
222       init() - "init" in Imager::ImageTypes
223
224       is_bilevel() - "is_bilevel" in Imager::ImageTypes
225
226       line() - "line" in Imager::Draw
227
228       load_plugin() - "load_plugin" in Imager::Filters
229
230       map() - "Color Mappings" in Imager::Transformations - remap color chan‐
231       nel values
232
233       masked() -  "masked" in Imager::ImageTypes - make a masked image
234
235       matrix_transform() - "matrix_transform" in Imager::Engines
236
237       maxcolors() - "maxcolors" in Imager::ImageTypes
238
239       NC() - "NC" in Imager::Handy
240
241       NCF() - "NCF" in Imager::Handy
242
243       new() - "new" in Imager::ImageTypes
244
245       newcolor() - "newcolor" in Imager::Handy
246
247       newcolour() - "newcolour" in Imager::Handy
248
249       newfont() - "newfont" in Imager::Handy
250
251       NF() - "NF" in Imager::Handy
252
253       open() - Imager::Files - an alias for read()
254
255       parseiptc() - "parseiptc" in Imager::Files - parse IPTC data from a
256       JPEG image
257
258       paste() - "paste" in Imager::Transformations - draw an image onto an
259       image
260
261       polygon() - "polygon" in Imager::Draw
262
263       polyline() - "polyline" in Imager::Draw
264
265       read() - Imager::Files - read a single image from an image file
266
267       read_multi() - Imager::Files - read multiple images from an image file
268
269       read_types() - "read_types" in Imager::Files - list image types Imager
270       can read.
271
272       register_filter() - "register_filter" in Imager::Filters
273
274       register_reader() - "register_reader" in Imager::Filters
275
276       register_writer() - "register_writer" in Imager::Filters
277
278       rotate() - "rotate" in Imager::Transformations
279
280       rubthrough() - "rubthrough" in Imager::Transformations - draw an image
281       onto an image and use the alpha channel
282
283       scale() - "scale" in Imager::Transformations
284
285       scale_calculate() - "scale_calculate" in Imager::Transformations
286
287       scaleX() - "scaleX" in Imager::Transformations
288
289       scaleY() - "scaleY" in Imager::Transformations
290
291       setcolors() - "setcolors" in Imager::ImageTypes - set palette colors in
292       a paletted image
293
294       set_file_limits() - "Limiting the sizes of images you read" in
295       Imager::Files
296
297       setmask() - "setmask" in Imager::ImageTypes
298
299       setpixel() - "setpixel" in Imager::Draw
300
301       setsamples() - "setsamples" in Imager::Draw
302
303       setscanline() - "setscanline" in Imager::Draw
304
305       settag() - "settag" in Imager::ImageTypes
306
307       string() - "string" in Imager::Draw - draw text on an image
308
309       tags() -  "tags" in Imager::ImageTypes - fetch image tags
310
311       to_paletted() -  "to_paletted" in Imager::ImageTypes
312
313       to_rgb16() - "to_rgb16" in Imager::ImageTypes
314
315       to_rgb8() - "to_rgb8" in Imager::ImageTypes
316
317       transform() - "transform" in Imager::Engines
318
319       transform2() - "transform2" in Imager::Engines
320
321       type() -  "type" in Imager::ImageTypes - type of image (direct vs
322       paletted)
323
324       unload_plugin() - "unload_plugin" in Imager::Filters
325
326       virtual() - "virtual" in Imager::ImageTypes - whether the image has
327       it's own data
328
329       write() - Imager::Files - write an image to a file
330
331       write_multi() - Imager::Files - write multiple image to an image file.
332
333       write_types() - "read_types" in Imager::Files - list image types Imager
334       can write.
335

CONCEPT INDEX

337       animated GIF - "Writing an animated GIF" in Imager::Files
338
339       aspect ratio - "i_xres" in Imager::ImageTypes, "i_yres" in
340       Imager::ImageTypes, "i_aspect_only" in Imager::ImageTypes
341
342       blend - alpha blending one image onto another "rubthrough" in
343       Imager::Transformations
344
345       blur - "guassian" in Imager::Filters, "conv" in Imager::Filters
346
347       boxes, drawing - "box" in Imager::Draw
348
349       changes between image - "Image Difference" in Imager::Filter
350
351       color - Imager::Color
352
353       color names - Imager::Color, Imager::Color::Table
354
355       combine modes - "combine" in Imager::Fill
356
357       compare images - "Image Difference" in Imager::Filter
358
359       contrast - "contrast" in Imager::Filter, "autolevels" in Imager::Filter
360
361       convolution - "conv" in Imager::Filter
362
363       cropping - "crop" in Imager::Transformations
364
365       CUR files - "ICO (Microsoft Windows Icon) and CUR (Microsoft Windows
366       Cursor)" in Imager::Files
367
368       "diff" images - "Image Difference" in Imager::Filter
369
370       dpi - "i_xres" in Imager::ImageTypes, "Image spatial resolution" in
371       Imager::Cookbook
372
373       drawing boxes - "box" in Imager::Draw
374
375       drawing lines - "line" in Imager::Draw
376
377       drawing text - "string" in Imager::Draw, "align_string" in Imager::Draw
378
379       error message - "Basic Overview"
380
381       files, font - Imager::Font
382
383       files, image - Imager::Files
384
385       filling, types of fill - Imager::Fill
386
387       filling, boxes - "box" in Imager::Draw
388
389       filling, flood fill - "flood_fill" in Imager::Draw
390
391       flood fill - "flood_fill" in Imager::Draw
392
393       fonts - Imager::Font
394
395       fonts, drawing with - "string" in Imager::Draw, "align_string" in
396       Imager::Draw, Imager::Font::Wrap
397
398       fonts, metrics - "bounding_box" in Imager::Font, Imager::Font::BBox
399
400       fonts, multiple master - "MULTIPLE MASTER FONTS" in Imager::Font
401
402       fountain fill - "Fountain fills" in Imager::Fill, "fountain" in
403       Imager::Filters, Imager::Fountain, "gradgen" in Imager::Filters
404
405       GIF files - "GIF" in Imager::Files
406
407       GIF files, animated - "Writing an animated GIF" in Imager::File
408
409       gradient fill - "Fountain fills" in Imager::Fill, "fountain" in
410       Imager::Filters, Imager::Fountain, "gradgen" in Imager::Filters
411
412       grayscale, convert image to - "convert" in Imager::Transformations
413
414       guassian blur - "guassian" in Imager::Filter
415
416       hatch fills - "Hatched fills" in Imager::Fill
417
418       ICO files - "ICO (Microsoft Windows Icon) and CUR (Microsoft Windows
419       Cursor)" in Imager::Files
420
421       invert image - "hardinvert" in Imager::Filter
422
423       JPEG - "JPEG" in Imager::Files
424
425       limiting image sizes - "Limiting the sizes of images you read" in
426       Imager::Files
427
428       lines, drawing - "line" in Imager::Draw
429
430       matrix - Imager::Matrix2d, "Matrix Transformations" in Imager::Trans‐
431       formations, "transform" in Imager::Font
432
433       metadata, image - "Tags" in Imager::ImageTypes
434
435       mosaic - "mosaic" in Imager::Filter
436
437       noise, filter - "noise" in Imager::Filter
438
439       noise, rendered - "turbnoise" in Imager::Filter, "radnoise" in
440       Imager::Filter
441
442       paste - "paste" in Imager::Transformations, "rubthrough" in
443       Imager::Transformations
444
445       pseudo-color image - "to_paletted" in Imager::ImageTypes, "new" in
446       Imager::ImageTypes
447
448       posterize - "postlevels" in Imager::Filter
449
450       png files - Imager::Files, "PNG" in Imager::Files
451
452       pnm - "PNM (Portable aNy Map)" in Imager::Files
453
454       rectangles, drawing - "box" in Imager::Draw
455
456       resizing an image - "scale" in Imager::Transformations, "crop" in
457       Imager::Transformations
458
459       RGB (SGI) files - "SGI (RGB, BW)" in Imager::Files
460
461       saving an image - Imager::Files
462
463       scaling - "scale" in Imager::Transformations
464
465       SGI files - "SGI (RGB, BW)" in Imager::Files
466
467       sharpen - "unsharpmask" in Imager::Filters, "conv" in Imager::Filters
468
469       size, image - "getwidth" in Imager::ImageTypes, "getheight" in
470       Imager::ImageTypes
471
472       size, text - "bounding_box" in Imager::Font
473
474       tags, image metadata - "Tags" in Imager::ImageTypes
475
476       text, drawing - "string" in Imager::Draw, "align_string" in
477       Imager::Draw, Imager::Font::Wrap
478
479       text, wrapping text in an area - Imager::Font::Wrap
480
481       text, measuring - "bounding_box" in Imager::Font, Imager::Font::BBox
482
483       tiles, color - "mosaic" in Imager::Filter
484
485       unsharp mask - "unsharpmask" in Imager::Filter
486
487       watermark - "watermark" in Imager::Filter
488
489       writing an image to a file - Imager::Files
490

SUPPORT

492       The best place to get help with Imager is the mailing list.
493
494       To subscribe send a message with "subscribe" in the body to:
495
496          imager-devel+request@molar.is
497
498       or use the form at:
499
500           <http://www.molar.is/en/lists/imager-devel/>
501
502       where you can also find the mailing list archive.
503
504       You can report bugs by pointing your browser at:
505
506           <https://rt.cpan.org/NoAuth/ReportBug.html?Queue=Imager>
507
508       or by sending an email to:
509
510           bug-Imager@rt.cpan.org
511
512       Please remember to include the versions of Imager, perl, supporting
513       libraries, and any relevant code.  If you have specific images that
514       cause the problems, please include those too.
515
516       If you don't want to publish your email address on a mailing list you
517       can use CPAN::Forum:
518
519         http://www.cpanforum.com/dist/Imager
520
521       You will need to register to post.
522

CONTRIBUTING TO IMAGER

524       Feedback
525
526       I like feedback.
527
528       If you like or dislike Imager, you can add a public review of Imager at
529       CPAN Ratings:
530
531         http://cpanratings.perl.org/dist/Imager
532
533       This requires a Bitcard Account (http://www.bitcard.org).
534
535       You can also send email to the maintainer below.
536
537       If you send me a bug report via email, it will be copied to RT.
538
539       Patches
540
541       I accept patches, preferably against the main branch in subversion.
542       You should include an explanation of the reason for why the patch is
543       needed or useful.
544
545       Your patch should include regression tests where possible, otherwise it
546       will be delayed until I get a chance to write them.
547

AUTHOR

549       Tony Cook <tony@imager.perl.org> is the current maintainer for Imager.
550
551       Arnar M. Hrafnkelsson is the original author of Imager.
552
553       Many others have contributed to Imager, please see the README for a
554       complete list.
555