1GD::Simple(3)         User Contributed Perl Documentation        GD::Simple(3)
2
3
4

NAME

6       GD::Simple - Simplified interface to GD library
7

SYNOPSIS

9           use GD::Simple;
10
11           # create a new image
12           $img = GD::Simple->new(400,250);
13
14           # draw a red rectangle with blue borders
15           $img->bgcolor('red');
16           $img->fgcolor('blue');
17           $img->rectangle(10,10,50,50);
18
19           # draw an empty rectangle with green borders
20           $img->bgcolor(undef);
21           $img->fgcolor('green');
22           $img->rectangle(30,30,100,100);
23
24           # move to (80,80) and draw a green line to (100,190)
25           $img->moveTo(80,80);
26           $img->lineTo(100,190);
27
28           # draw a solid orange ellipse
29           $img->moveTo(110,100);
30           $img->bgcolor('orange');
31           $img->fgcolor('orange');
32           $img->ellipse(40,40);
33
34           # draw a black filled arc
35           $img->moveTo(150,150);
36           $img->fgcolor('black');
37           $img->arc(50,50,0,100,gdNoFill|gdEdged);
38
39           # draw a string at (10,180) using the default
40           # built-in font
41           $img->moveTo(10,180);
42           $img->string('This is very simple');
43
44           # draw a string at (280,210) using 20 point
45           # times italic, angled upward 90 degrees
46           $img->moveTo(280,210);
47           $img->font('Times:italic');
48           $img->fontsize(20);
49           $img->angle(-90);
50           $img->string('This is very fancy');
51
52           # some turtle graphics
53           $img->moveTo(300,100);
54           $img->penSize(3,3);
55           $img->angle(0);
56           $img->line(20);   # 20 pixels going to the right
57           $img->turn(30);   # set turning angle to 30 degrees
58           $img->line(20);   # 20 pixel line
59           $img->line(20);
60           $img->line(20);
61           $img->turn(-90); # set turning angle to -90 degrees
62           $img->line(50);  # 50 pixel line
63
64           # draw a cyan polygon edged in blue
65           my $poly = new GD::Polygon;
66           $poly->addPt(150,100);
67           $poly->addPt(199,199);
68           $poly->addPt(100,199);
69           $img->bgcolor('cyan');
70           $img->fgcolor('blue');
71           $img->penSize(1,1);
72           $img->polygon($poly);
73
74          # convert into png data
75          print $img->png;
76

DESCRIPTION

78       GD::Simple is a subclass of the GD library that shortens many of the
79       long GD method calls by storing information about the pen color, size
80       and position in the GD object itself.  It also adds a small number of
81       "turtle graphics" style calls for those who prefer to work in polar
82       coordinates.  In addition, the library allows you to use symbolic names
83       for colors, such as "chartreuse", and will manage the colors for you.
84
85   The Pen
86       GD::Simple maintains a "pen" whose settings are used for line- and
87       shape-drawing operations.  The pen has the following properties:
88
89       fgcolor
90           The pen foreground color is the color of lines and the borders of
91           filled and unfilled shapes.
92
93       bgcolor
94           The pen background color is the color of the contents of filled
95           shapes.
96
97       pensize
98           The pen size is the width of the pen.  Larger sizes draw thicker
99           lines.
100
101       position
102           The pen position is its current position on the canvas in (X,Y)
103           coordinates.
104
105       angle
106           When drawing in turtle mode, the pen angle determines the current
107           direction of lines of relative length.
108
109       turn
110           When drawing in turtle mode, the turn determines the clockwise or
111           counterclockwise angle that the pen will turn before drawing the
112           next line.
113
114       font
115           The font to use when drawing text.  Both built-in bitmapped fonts
116           and TrueType fonts are supported.
117
118       fontsize
119           The size of the font to use when drawing with TrueType fonts.
120
121       One sets the position and properties of the pen and then draws.  As the
122       drawing progresses, the position of the pen is updated.
123
124   Methods
125       GD::Simple introduces a number of new methods, a few of which have the
126       same name as GD::Image methods, and hence change their behavior. In
127       addition to these new methods, GD::Simple objects support all of the
128       GD::Image methods. If you make a method call that isn't directly
129       supported by GD::Simple, it refers the request to the underlying
130       GD::Image object.  Hence one can load a JPEG image into GD::Simple and
131       declare it to be TrueColor by using this call, which is effectively
132       inherited from GD::Image:
133
134         my $img = GD::Simple->newFromJpeg('./myimage.jpg',1);
135
136       The rest of this section describes GD::Simple-specific methods.
137
138       $img = GD::Simple->new($x,$y [,$truecolor])
139       $img = GD::Simple->new($gd)
140           Create a new GD::Simple object. There are two forms of new(). In
141           the first form, pass the width and height of the desired canvas,
142           and optionally a boolean flag to request a truecolor image. In the
143           second form, pass a previously-created GD::Image object.
144
145       GD::Simple->class('GD');
146       GD::Simple->class('GD::SVG');
147           Select whether new() should use GD or GD::SVG internally. Call
148           GD::Simple->class('GD::SVG') before calling new() if you wish to
149           generate SVG images.
150
151           If future GD subclasses are created, this method will subport them.
152
153       $img->moveTo($x,$y)
154           This call changes the position of the pen without drawing. It moves
155           the pen to position ($x,$y) on the drawing canvas.
156
157       $img->move($dx,$dy)
158       $img->move($dr)
159           This call changes the position of the pen without drawing. When
160           called with two arguments it moves the pen $dx pixels to the right
161           and $dy pixels downward.  When called with one argument it moves
162           the pen $dr pixels along the vector described by the current pen
163           angle.
164
165       $img->lineTo($x,$y)
166           The lineTo() call simultaneously draws and moves the pen.  It draws
167           a line from the current pen position to the position defined by
168           ($x,$y) using the current pen size and color.  After drawing, the
169           position of the pen is updated to the new position.
170
171       $img->line($dx,$dy)
172       $img->line($dr)
173           The line() call simultaneously draws and moves the pen. When called
174           with two arguments it draws a line from the current position of the
175           pen to the position $dx pixels to the right and $dy pixels down.
176           When called with one argument, it draws a line $dr pixels long
177           along the angle defined by the current pen angle.
178
179       $img->clear
180           This method clears the canvas by painting over it with the current
181           background color.
182
183       $img->rectangle($x1,$y1,$x2,$y2)
184           This method draws the rectangle defined by corners ($x1,$y1),
185           ($x2,$y2). The rectangle's edges are drawn in the foreground color
186           and its contents are filled with the background color. To draw a
187           solid rectangle set bgcolor equal to fgcolor. To draw an unfilled
188           rectangle (transparent inside), set bgcolor to undef.
189
190       $img->ellipse($width,$height)
191           This method draws the ellipse centered at the current location with
192           width $width and height $height.  The ellipse's border is drawn in
193           the foreground color and its contents are filled with the
194           background color. To draw a solid ellipse set bgcolor equal to
195           fgcolor. To draw an unfilled ellipse (transparent inside), set
196           bgcolor to undef.
197
198       $img->arc($cx,$cy,$width,$height,$start,$end [,$style])
199           This method draws filled and unfilled arcs.  See GD for a
200           description of the arguments. To draw a solid arc (such as a pie
201           wedge) set bgcolor equal to fgcolor. To draw an unfilled arc, set
202           bgcolor to undef.
203
204       $img->polygon($poly)
205           This method draws filled and unfilled polygon using the current
206           settings of fgcolor for the polygon border and bgcolor for the
207           polygon fill color.  See GD for a description of creating polygons.
208           To draw a solid polygon set bgcolor equal to fgcolor. To draw an
209           unfilled polygon, set bgcolor to undef.
210
211       $img->polyline($poly)
212           This method draws polygons without closing the first and last
213           vertices (similar to GD::Image->unclosedPolygon()). It uses the
214           fgcolor to draw the line.
215
216       $img->string($string)
217           This method draws the indicated string starting at the current
218           position of the pen. The pen is moved to the end of the drawn
219           string.  Depending on the font selected with the font() method,
220           this will use either a bitmapped GD font or a TrueType font.  The
221           angle of the pen will be consulted when drawing the text. For
222           TrueType fonts, any angle is accepted.  For GD bitmapped fonts, the
223           angle can be either 0 (draw horizontal) or -90 (draw upwards).
224
225           For consistency between the TrueType and GD font behavior, the
226           string is always drawn so that the current position of the pen
227           corresponds to the bottom left of the first character of the text.
228           This is different from the GD behavior, in which the first
229           character of bitmapped fonts hangs down from the pen point.
230
231           This method returns a polygon indicating the bounding box of the
232           rendered text.  If an error occurred (such as invalid font
233           specification) it returns undef and an error message in $@.
234
235       $metrics = $img->fontMetrics
236       ($metrics,$width,$height) =
237       GD::Simple->fontMetrics($font,$fontsize,$string)
238           This method returns information about the current font, most
239           commonly a TrueType font. It can be invoked as an instance method
240           (on a previously-created GD::Simple object) or as a class method
241           (on the 'GD::Simple' class).
242
243           When called as an instance method, fontMetrics() takes no arguments
244           and returns a single hash reference containing the metrics that
245           describe the currently selected font and size. The hash reference
246           contains the following information:
247
248             xheight      the base height of the font from the bottom to the top of
249                          a lowercase 'm'
250
251             ascent       the length of the upper stem of the lowercase 'd'
252
253             descent      the length of the lower step of the lowercase 'j'
254
255             lineheight   the distance from the bottom of the 'j' to the top of
256                          the 'd'
257
258             leading      the distance between two adjacent lines
259
260       ($delta_x,$delta_y)= $img->stringBounds($string)
261           This method indicates the X and Y offsets (which may be negative)
262           that will occur when the given string is drawn using the current
263           font, fontsize and angle. When the string is drawn horizontally, it
264           gives the width and height of the string's bounding box.
265
266       $delta_x = $img->stringWidth($string)
267           This method indicates the width of the string given the current
268           font, fontsize and angle. It is the same as
269           ($img->stringBounds($string))[0]
270
271       ($x,$y) = $img->curPos
272           Return the current position of the pen.  Set the current position
273           using moveTo().
274
275       $font = $img->font([$newfont] [,$newsize])
276           Get or set the current font.  Fonts can be GD::Font objects,
277           TrueType font file paths, or fontconfig font patterns like
278           "Times:italic" (see fontconfig). The latter feature requires that
279           you have the fontconfig library installed and are using libgd
280           version 2.0.33 or higher.
281
282           As a shortcut, you may pass two arguments to set the font and the
283           fontsize simultaneously. The fontsize is only valid when drawing
284           with TrueType fonts.
285
286       $size = $img->fontsize([$newfontsize])
287           Get or set the current font size.  This is only valid for TrueType
288           fonts.
289
290       $size = $img->penSize([$newpensize])
291           Get or set the current pen width for use during line drawing
292           operations.
293
294       $angle = $img->angle([$newangle])
295           Set the current angle for use when calling line() or move() with a
296           single argument.
297
298           Here is an example of using turn() and angle() together to draw an
299           octagon.  The first line drawn is the downward-slanting top right
300           edge.  The last line drawn is the horizontal top of the octagon.
301
302             $img->moveTo(200,50);
303             $img->angle(0);
304             $img->turn(360/8);
305             for (1..8) { $img->line(50) }
306
307       $angle = $img->turn([$newangle])
308           Get or set the current angle to turn prior to drawing lines.  This
309           value is only used when calling line() or move() with a single
310           argument.  The turning angle will be applied to each call to line()
311           or move() just before the actual drawing occurs.
312
313           Angles are in degrees.  Positive values turn the angle clockwise.
314
315       $color = $img->fgcolor([$newcolor])
316           Get or set the pen's foreground color.  The current pen color can
317           be set by (1) using an (r,g,b) triple; (2) using a previously-
318           allocated color from the GD palette; or (3) by using a symbolic
319           color name such as "chartreuse."  The list of color names can be
320           obtained using color_names(). The special color name 'transparent'
321           will create a completely transparent color.
322
323       $color = $img->bgcolor([$newcolor])
324           Get or set the pen's background color.  The current pen color can
325           be set by (1) using an (r,g,b) triple; (2) using a previously-
326           allocated color from the GD palette; or (3) by using a symbolic
327           color name such as "chartreuse."  The list of color names can be
328           obtained using color_names(). The special color name 'transparent'
329           will create a completely transparent color.
330
331       $index = $img->translate_color(@args)
332           Translates a color into a GD palette or TrueColor index.  You may
333           pass either an (r,g,b) triple or a symbolic color name. If you pass
334           a previously-allocated index, the method will return it unchanged.
335
336       $index = $img->alphaColor(@args,$alpha)
337           Creates an alpha color.  You may pass either an (r,g,b) triple or a
338           symbolic color name, followed by an integer indicating its opacity.
339           The opacity value ranges from 0 (fully opaque) to 127 (fully
340           transparent).
341
342       @names = GD::Simple->color_names
343       $translate_table = GD::Simple->color_names
344           Called in a list context, color_names() returns the list of
345           symbolic color names recognized by this module.  Called in a scalar
346           context, the method returns a hash reference in which the keys are
347           the color names and the values are array references containing
348           [r,g,b] triples.
349
350       $gd = $img->gd
351           Return the internal GD::Image object.  Usually you will not need to
352           call this since all GD methods are automatically referred to this
353           object.
354
355       ($red,$green,$blue) = GD::Simple->HSVtoRGB($hue,$saturation,$value)
356           Convert a Hue/Saturation/Value (HSV) color into an RGB triple. The
357           hue, saturation and value are integers from 0 to 255.
358
359       ($hue,$saturation,$value) =
360       GD::Simple->RGBtoHSV($hue,$saturation,$value)
361           Convert a Red/Green/Blue (RGB) value into a Hue/Saturation/Value
362           (HSV) triple. The hue, saturation and value are integers from 0 to
363           255.
364

COLORS

366       This script will create an image showing all the symbolic colors.
367
368        #!/usr/bin/perl
369
370        use strict;
371        use GD::Simple;
372
373        my @color_names = GD::Simple->color_names;
374        my $cols = int(sqrt(@color_names));
375        my $rows = int(@color_names/$cols)+1;
376
377        my $cell_width    = 100;
378        my $cell_height   = 50;
379        my $legend_height = 16;
380        my $width       = $cols * $cell_width;
381        my $height      = $rows * $cell_height;
382
383        my $img = GD::Simple->new($width,$height);
384        $img->font(gdSmallFont);
385
386        for (my $c=0; $c<$cols; $c++) {
387          for (my $r=0; $r<$rows; $r++) {
388            my $color = $color_names[$c*$rows + $r] or next;
389            my @topleft  = ($c*$cell_width,$r*$cell_height);
390            my @botright = ($topleft[0]+$cell_width,$topleft[1]+$cell_height-$legend_height);
391            $img->bgcolor($color);
392            $img->fgcolor($color);
393            $img->rectangle(@topleft,@botright);
394            $img->moveTo($topleft[0]+2,$botright[1]+$legend_height-2);
395            $img->fgcolor('black');
396            $img->string($color);
397          }
398        }
399
400        print $img->png;
401

AUTHOR

403       The GD::Simple module is copyright 2004, Lincoln D. Stein.  It is
404       distributed under the same terms as Perl itself.  See the "Artistic
405       License" in the Perl source code distribution for licensing terms.
406
407       The latest versions of GD.pm are available at
408
409         http://stein.cshl.org/WWW/software/GD
410

SEE ALSO

412       GD, GD::Polyline, GD::SVG, Image::Magick
413
414
415
416perl v5.12.0                      2008-12-21                     GD::Simple(3)
Impressum