1SVG(3) User Contributed Perl Documentation SVG(3)
2
6 GD::SVG - Seamlessly enable SVG output from scripts written using GD
7
9 # use GD;
10 use GD::SVG;
11 # my $img = GD::Image->new();
13 my $img = GD::SVG::Image->new();
14 # $img->png();
16 $img->svg();
17
19 GD::SVG painlessly enables scripts that utilize GD to export scalable
20 vector graphics (SVG). It accomplishes this task by wrapping SVG.pm
21 with GD-styled method calls. To enable this functionality, one need
22 only change the "use GD" call to "use GD::SVG" (and initial "new"
23 method calls).
24
26 GD::SVG exports the same methods as GD itself, overriding those meth‐
27 ods.
28
30 In order to generate SVG output from your script using GD::SVG, you
31 will need to first
32 # use GD;
34 use GD::SVG;
35 After that, each call to the package classes that GD implements should
37 be changed to GD::SVG. Thus:
38 GD::Image becomes GD::SVG::Image
40 GD::Font becomes GD::SVG::Font
41
43 If you would like your script to be able to dynamically select either
44 PNG or JPEG output (via GD) or SVG output (via GD::SVG), you should
45 place your "use" statement within an eval. In the example below, each
46 of the available classes is created at the top of the script for conve‐
47 nience, as well as the image output type.
48 my $package = shift;
50 eval "use $package";
51 my $image_pkg = $package . '::Image';
52 my $font_pkg = $package . '::Font';
53 # Creating new images thus becomes
55 my $image = $image_pkg->new($width,$height);
56 # Establish the image output type
58 my $image_type;
59 if ($package = 'GD::SVG') {
60 $image_type = 'svg';
61 } else {
62 $image_type = 'png';
63 }
64 Finally, you should change all GD::Image and GD::Font references to
66 $image_pkg-> and $font_pkg->, respectively.
67 GD::Image->new() becomes $image_pkg->new()
69 GD::Font->Large() becomes $font_pkg->Large()
70 The GD::Polygon and GD::Polyline classes work with GD::SVG without mod‐
72 ification.
73 If you make heavy use of GD's exported methods, it may also be neces‐
75 sary to add () to the endo of method names to avoide bareword compila‐
76 tion errors. That's the price you pay for using exported functions!
77
79 GD::SVG does not directly generate SVG, but instead relies upon SVG.pm.
80 It is not intended to supplant SVG.pm. Furthermore, since GD::SVG is,
81 in essence an API to an API, it may not be suitable for applications
82 where speed is of the essence. In these cases, GD::SVG may provide a
83 short-term solution while scripts are re-written to enable more direct
84 output of SVG.
85 Many of the GD::SVG methods accept additional parameters (which are in
87 turn reflected in the SVG.pm API) that are not supported in GD. Look
88 through the remainder of this document for options on specific In addi‐
89 tion, several functions have yet to be mapped to SVG.pm calls. Please
90 see the section below regarding regarding GD functions that are missing
91 or altered in GD::SVG.
92 A similar module (SVG::GD) implements a similar wrapper around GD.
94 Please see the section at the bottom of this document that compares
95 GD::SVG to SVG::GD.
96
98 GD::SVG requires the Ronan Oger's SVG.pm module, Lincoln Stein's GD.pm
99 module, libgd and its dependencies.
100
102 These are the primary weaknesses of GD::SVG.
103 SVG requires unique identifiers for each element
105 Each element in an SVG image requires a unique identifier. In gen‐
106 eral, GD::SVG handles this by automatically generating unique ran‐
107 dom numbers. In addition to the typical parameters for GD methods,
108 GD::SVG methods allow a user to pass an optional id parameter for
109 naming the object.
110 Direct calls to the GD package will fail
112 You must change direct calls to the classes that GD invokes:
113 GD::Image->new() should be changed to GD::SVG::Image->new()
114 See the documentation above for how to dynamically switch between
116 packages.
117 raster fill() and fillToBorder() not supported
119 As SVG documents are not inherently aware of their canvas, the
120 flood fill methods are not currently supported.
121 getPixel() not supported.
123 Although setPixel() works as expected, its counterpart getPixel()
124 is not supported. I plan to support this method in a future
125 release.
126 No support for generation of images from filehandles or raw data
128 GD::SVG works only with scripts that generate images directly in
129 the code using the GD->new(height,width) approach. newFrom() meth‐
130 ods are not currently supported.
131 Tiled fills are not supported
133 Any functions passed gdTiled objects will die.
134 Styled and Brushed lines only partially implemented
136 Calls to the gdStyled and gdBrushed functions via a rather humorous
137 kludge (and simplification). Depending on the complexity of the
138 brush, they may behave from slightly differently to radically dif‐
139 ferently from their behavior under GD. You have been warned. See
140 the documentation sections for the methods that set these options
141 (setStyle(), setBrush(), and setTransparent()).
142 See below for a full list of methods that have not yet been imple‐
144 mented.
145
147 GD is a complicated module. Translating GD methods into those required
148 to draw in SVG are not always direct. You may or may not get the output
149 you expect. In general, some tweaking of image parameters (like text
150 height and width) may be necessary.
151 If your script doesn't work as expected, first check the list of meth‐
153 ods that GD::SVG provides. Due to differences in the nature of SVG
154 images, not all GD methods have been implemented in GD::SVG.
155 If your image doesn't look as expected, try tweaking specific aspects
157 of image generation. In particular, check for instances where you cal‐
158 culate dimensions of items on the fly like font->height. In SVG, the
159 values of fonts are defined explicitly.
160
162 The following GD functions have not yet been incorporated into GD::SVG.
163 If you attempt to use one of these functions (and you have enabled
164 debug warnings via the new() method), GD::SVG will print a warning to
165 STDERR.
166 Creating image objects:
168 GD::Image->newPalette([$width,$height])
169 GD::Image->newTrueColor([$width,$height])
170 GD::Image->newFromPng($file, [$truecolor])
171 GD::Image->newFromPngData($data, [$truecolor])
172 GD::Image->newFromJpeg($file, [$truecolor])
173 GD::Image->newFromJpegData($data, [$truecolor])
174 GD::Image->newFromXbm($file)
175 GD::Image->newFromWMP($file)
176 GD::Image->newFromGd($file)
177 GD::Image->newFromGdData($data)
178 GD::Image->newFromGd2($file)
179 GD::Image->newFromGd2Data($data)
180 GD::Image->newFromGd2Part($file,srcX,srcY,width,height)
181 GD::Image->newFromXpm($filename)
182 Image methods:
184 $gddata = $image->gd
185 $gd2data = $image->gd2
186 $wbmpdata = $image->wbmp([$foreground])
187 Color control methods:
189 $image->colorAllocateAlpha()
190 $image->colorClosest()
191 $image->colorClosestHWB()
192 $image->getPixel()
193 $image->transparent()
194 Special Colors:
196 $image->setBrush() (semi-supported, with kludge)
197 $image->setStyle() (semi-supported, with kludge)
198 gdTiled
199 $image->setAntialiased()
200 gdAntiAliased()
201 $image->setAntiAliasedDontBlend()
202 Drawing methods:
204 $image->dashedLine()
205 $image->fill()
206 $image->fillToBorder()
207 Image copying methods
209 None of the image copying methods are yet supported
210 Image transformation methods
212 None of the image transformation methods are yet supported
213 Character and string drawing methods
215 $image->stringUp() - incompletely supported - broken
216 $image->charUp()
217 $image->stringFT()
218 Alpha Channels
220 $image->alphaBlending()
221 $image->saveAlpha()
222 Miscellaneous image methods
224 $image->isTrueColor()
225 $image->compare($image2)
226 $image->clip()
227 $image->boundsSafe()
228 GD::Polyline
230 Supported without modifications
231 Font methods:
233 $font->nchars()
234 $font->offset()
235
237 All GD::SVG methods mimic the naming and interface of GD methods. As
238 such, maintenance of GD::SVG follows the development of both GD and
239 SVG. Much of the original GD documentation is replicated here for ease
240 of use. Subtle differences in the implementation of these methods
241 between GD and GD::SVG are discussed below. In particular, the return
242 value for some GD::SVG methods differs from its GD counterpart.
243
245 GD::SVG currently only supports the creation of image objects via its
246 new constructor. This is in contrast to GD proper which supports the
247 creation of images from previous images, filehandles, filenames, and
248 data.
249 $image = GD::SVG::Image->new($height,$width,$debug);
251 Create a blank GD::SVG image object of the specified dimensions in
252 pixels. In turn, this method will create a new SVG object and store
253 it internally. You can turn on debugging with the GD::SVG specific
254 $debug parameter. This should be boolean true and will cause non-
255 implemented methods to print a warning on their status to STDERR.
256
258 Once a GD::Image object is created, you can draw with it, copy it, and
259 merge two images. When you are finished manipulating the object, you
260 can convert it into a standard image file format to output or save to a
261 file.
262 Image Data Output Methods
264 GD::SVG implements a single output method, svg()!
266 $svg = $image->svg();
268 This returns the image in SVG format. You may then print it, pipe
269 it to an image viewer, or write it to a file handle. For example,
270 $svg_data = $image->svg();
272 open (DISPLAY,"⎪ display -") ⎪⎪ die;
273 binmode DISPLAY;
274 print DISPLAY $svg_data;
275 close DISPLAY;
276 if you'd like to return an inline version of the image (instead of
278 a full document version complete with the DTD), pass the svg()
279 method the 'inline' flag:
280 $svg_data = $image->svg(-inline=>'true');
282 Calling the other standard GD image output methods (eg
284 jpeg,gd,gd2,png) on a GD::SVG::Image object will cause your script
285 to exit with a warning.
286 Color Control
288 These methods allow you to control and manipulate the color table of a
290 GD::SVG image. In contrast to GD which uses color indices, GD::SVG
291 passes stringified RGB triplets as colors. GD::SVG, however, maintains
292 an internal hash structure of colors and colored indices in order to
293 map GD functions that manipulate the color table. This typically
294 requires behind-the-scenes translation of these stringified RGB
295 triplets into a color index.
296 $stringified_color = $image->colorAllocate(RED,GREEN,BLUE)
298 Unlike GD, colors need not be allocated in advance in SVG. Unlike
299 GD which returns a color index, colorAllocate returns a formatted
300 string compatible with SVG. Simultaneously, it creates and stores
301 internally a GD compatible color index for use with GD's color
302 manipulation methods.
303 returns: "rgb(RED,GREEN,BLUE)"
305 $index = $image->colorAllocateAlpha()
307 NOT IMPLEMENTED
308 $image->colorDeallocate($index)
310 Provided with a color index, remove it from the color table.
311 $index = $image->colorClosest(red,green,blue)
313 This returns the index of the color closest in the color table to
314 the red green and blue components specified. This method is inher‐
315 ited directly from GD.
316 Example: $apricot = $myImage->colorClosest(255,200,180);
318 NOT IMPLEMENTED
320 $index = $image->colorClosestHWB(red,green,blue)
322 NOT IMPLEMENTED
323 $index = $image->colorExact(red,green,blue)
325 Retrieve the color index of an rgb triplet (or -1 if it has yet to
326 be allocated).
327 NOT IMPLEMENTED
329 $index = $image->colorResolve(red,green,blue)
331 NOT IMPLEMENTED
332 $colors_total = $image->colorsTotal()
334 Retrieve the total number of colors indexed in the image.
335 $index = $image->getPixel(x,y)
337 NOT IMPLEMENTED
338 ($red,$green,$blue) = $image->rgb($index)
340 Provided with a color index, return the RGB triplet. In GD::SVG,
341 color indexes are replaced with actual RGB triplets in the form
342 "rgb($r,$g,$b)".
343 $image->transparent($colorIndex);
345 Control the transparency of individual colors.
346 NOT IMPLEMENTED
348 Special Colors
350 GD implements a number of special colors that can be used to achieve
352 special effects. They are constants defined in the GD:: namespace, but
353 automatically exported into your namespace when the GD module is
354 loaded. GD::SVG offers limited support for these methods.
355 $image->setBrush($brush) (KLUDGE ALERT)
357 gdBrushed
358 In GD, one can draw lines and shapes using a brush pattern.
359 Brushes are just images that you can create and manipulate in the
360 usual way. When you draw with them, their contents are used for
361 the color and shape of the lines.
362 To make a brushed line, you must create or load the brush first,
364 then assign it to the image using setBrush(). You can then draw in
365 that with that brush using the gdBrushed special color. It's often
366 useful to set the background of the brush to transparent so that
367 the non-colored parts don't overwrite other parts of your image.
368 # Via GD, this is how one would set a Brush
370 $diagonal_brush = new GD::Image(5,5);
371 $white = $diagonal_brush->colorAllocate(255,255,255);
372 $black = $diagonal_brush->colorAllocate(0,0,0);
373 $diagonal_brush->transparent($white);
374 $diagonal_brush->line(0,4,4,0,$black); # NE diagonal
375 GD::SVG offers limited support for setBrush (and the corresponding
377 gdBrushed methods) - currently only in the shapes of squares.
378 Internally, GD::SVG extracts the longest dimension of the image
379 using the getBounds() method. Next, it extracts the second color
380 set, assuming that to be the foreground color. It then re-calls the
381 original drawing method with these new values in place of the
382 gdBrushed. See the private _distill_gdSpecial method for the inter‐
383 nal details of this operation.
384 $image->setThickness($thickness)
386 Lines drawn with line(), rectangle(), arc(), and so forth are 1
387 pixel thick by default. Call setThickness() to change the line
388 drawing width.
389 $image->setStyle(@colors)
391 setStyle() and gdStyled() are partially supported in GD::SVG.
392 GD::SVG determines the alternating pattern of dashes, treating the
393 first unique color encountered in the array as on, the second as
394 off and so on. The first color in the array is then used to draw
395 the actual line.
396 gdTiled
398 NOT IMPLEMENTED
399 gdStyled()
401 The GD special color gdStyled is partially implemented in GD::SVG.
402 Only the first color will be used to generate the dashed pattern
403 specified in setStyle(). See setStyle() for additional information.
404 $image->setAntiAliased($color)
406 NOT IMPLEMENTED
407 gdAntiAliased
409 NOT IMPLEMENTED
410 $image->setAntiAliasedDontBlend($color,[$flag])
412 NOT IMPLEMENTED
413 Drawing Commands
415 $image->setPixel($x,$y,$color)
417 Set the corresponding pixel to the given color. GD::SVG implements
418 this by drawing a single dot in the specified color at that posi‐
419 tion.
420 $image->line(x1,y1,x2,y2,color);
422 Draw a line between the two coordinate points with the specified
423 color. Passing an optional id will set the id of that SVG element.
424 GD::SVG also supports drawing with the special brushes - gdStyled
425 and gdBrushed - although these special styles are difficult to
426 replicate precisley in GD::SVG.
427 $image->dashedLine($x1,$y1,$x2,$y2,$color);
429 NOT IMPLEMENTED
430 $image->rectangle($x1,$y1,$x2,$y2,$color);
432 This draws a rectangle with the specified color. (x1,y1) and
433 (x2,y2) are the upper left and lower right corners respectively.
434 You may also draw with the special colors gdBrushed and gdStyled.
435 $image->filledRectangle($x1,$y1,$x2,$y2,$color);
437 filledRectangle is a GD specific method with no direct equivalent
438 in SVG. GD::SVG translates this method into an SVG appropriate
439 method by passing the filled color parameter as a named 'filled'
440 parameter to SVG. Drawing with the special colors is also permit‐
441 ted. See the documentation for the line() method for additional
442 details.
443 GD call:
445 $img->filledRectangle($x1,$y1,$x2,$y2,$color);
446 SVG call:
448 $img->rectangle(x=> $x1,y=> $y1,
449 width => $x2-$x1,
450 height => $y2-$y1,
451 fill => $color
452 $image->polygon($polygon,$color);
454 This draws a polygon with the specified color. The polygon must be
455 created first (see "Polygons" below). The polygon must have at
456 least three vertices. If the last vertex doesn't close the poly‐
457 gon, the method will close it for you. Both real color indexes and
458 the special colors gdBrushed, gdStyled and gdStyledBrushed can be
459 specified. See the documentation for the line() method for addi‐
460 tional details.
461 $poly = new GD::Polygon;
463 $poly->addPt(50,0);
464 $poly->addPt(99,99);
465 $poly->addPt(0,99);
466 $image->polygon($poly,$blue);
467 $image->filledPolygon($polygon,$color);
469 This draws a polygon filled with the specified color. Drawing with
470 the special colors is also permitted. See the documentation for the
471 line() method for additional details.
472 # make a polygon
474 $poly = new GD::Polygon;
475 $poly->addPt(50,0);
476 $poly->addPt(99,99);
477 $poly->addPt(0,99);
478 # draw the polygon, filling it with a color
480 $image->filledPolygon($poly,$peachpuff);
481 $image->filledPolygon($polygon,$color);
483 This draws a polygon filled with the specified color. Drawing with
484 the special colors is also permitted. See the documentation for the
485 line() method for additional details.
486 # make a polygon
488 $poly = new GD::Polygon;
489 $poly->addPt(50,0);
490 $poly->addPt(99,99);
491 $poly->addPt(0,99);
492 # draw the polygon, filling it with a color
494 $image->filledPolygon($poly,$peachpuff);
495 $image->polyline(polyline,color)
497 $image->polyline($polyline,$black)
498 This draws a polyline with the specified color. Both real color
500 indexes and the special colors gdBrushed, gdStyled and gdStyled‐
501 Brushed can be specified.
502 Neither the polyline() method or the polygon() method are very
504 picky: you can call either method with either a GD::Polygon or a
505 GD::Polyline. The method determines if the shape is "closed" or
506 "open" as drawn, not the object type.
507 $image->polydraw(polything,color)
509 $image->polydraw($poly,$black)
510 This method draws the polything as expected (polygons are closed,
512 polylines are open) by simply checking the object type and calling
513 either $image->polygon() or $image->polyline().
514 $image->ellipse($cx,$cy,$width,$height,$color)
516 $image->filledEllipse($cx,$cy,$width,$height,$color)
517 These methods() draw ellipses. ($cx,$cy) is the center of the arc,
518 and ($width,$height) specify the ellipse width and height, respec‐
519 tively. filledEllipse() is like ellipse() except that the former
520 produces filled versions of the ellipse. Drawing with the special
521 colors is also permitted. See the documentation for the line()
522 method for additional details.
523 $image->arc($cy,$cy,$width,$height,$start,$end,$color);
525 This draws arcs and ellipses. (cx,cy) are the center of the arc,
526 and (width,height) specify the width and height, respectively. The
527 portion of the ellipse covered by the arc are controlled by start
528 and end, both of which are given in degrees from 0 to 360. Zero is
529 at the top of the ellipse, and angles increase clockwise. To spec‐
530 ify a complete ellipse, use 0 and 360 as the starting and ending
531 angles. To draw a circle, use the same value for width and height.
532 Internally, arc() calls the ellipse() method of SVG.pm. Drawing
534 with the special colors is also permitted. See the documentation
535 for the line() method for additional details.
536 Currently, true arcs are NOT supported, only those where the start
538 and end equal 0 and 360 respectively resulting in a closed arc.
539 $image->filledArc($cx,$cy,$width,$height,$start,$end,$color
541 [,$arc_style])
542 This method is like arc() except that it colors in the pie wedge
543 with the selected color. $arc_style is optional. If present it is
544 a bitwise OR of the following constants:
545 gdArc connect start & end points of arc with a rounded
547 edge gdChord connect start & end points of arc with a
548 straight line gdPie synonym for gdChord gdNoFill
549 outline the arc or chord gdEdged connect beginning and end‐
550 ing of the arc to the center
551 gdArc and gdChord are mutally exclusive. gdChord just connects the
553 starting and ending angles with a straight line, while gdArc pro-
554 duces a rounded edge. gdPie is a synonym for gdArc. gdNoFill indi-
555 cates that the arc or chord should be outlined, not filled.
556 gdEdged, used together with gdNoFill, indicates that the beginning
557 and ending angles should be connected to the center; this is a good
558 way to outline (rather than fill) a "pie slice."
559 Using these special styles, you can easily draw bordered ellipses
561 and circles.
562 # Create the filled shape:
564 $image->filledArc($x,$y,$width,$height,0,360,$fill); # Now border
565 it. $image->filledArc($x,$y,$width,$height,0,360,$color,gdNoFill);
566 $image->fill();
568 NOT IMPLEMENTED
569 $image->fillToBorder()
571 NOT IMPLEMENTED
572 Image Copying Methods
574 None of the image copying commands are implemented in GD::SVG. If your
576 script calls one of the following methods, your script will die
577 remorsefully with a warning. With sufficient demand, I might try to
578 implement some of these methods. For now, I think that they are beyond
579 the intent of GD::SVG.
580 $image->copy()
582 $image->clone()
583 $image->copyMerge()
584 $image->copyMergeGray()
585 $image->copyResized()
586 $image->copyResampled()
587 $image->trueColorToPalette()
588 Image Transfomation Commands
590 None of the image transformation commands are implemented in GD::SVG.
592 If your script calls one of the following methods, your script will die
593 remorsefully with a warning. With sufficient demand, I might try to
594 implement some of these methods. For now, I think that they are beyond
595 the intent of GD::SVG.
596 $image = $sourceImage->copyRotate90()
598 $image = $sourceImage->copyRotate180()
599 $image = $sourceImage->copyRotate270()
600 $image = $sourceImage->copyFlipHorizontal()
601 $image = $sourceImage->copyFlipVertical()
602 $image = $sourceImage->copyTranspose()
603 $image = $sourceImage->copyReverseTranspose()
604 $image->rotate180()
605 $image->flipHorizontal()
606 $image->flipVertical()
607 Character And String Drawing
609 GD allows you to draw characters and strings, either in normal horizon-
611 tal orientation or rotated 90 degrees. In GD, these routines use a
612 GD::Font object. Internally, GD::SVG mimics the behavior of GD with
613 respect to fonts in a very similar manner, using instead a
614 GD::SVG::Font object described in more detail below.
615 GD's font handling abilities are not as flexible as SVG and it does not
617 allow the dynamic creation of fonts, instead exporting five available
618 fonts as global variables: gdGiantFont, gdLargeFont, gdMediumBoldFont,
619 gdSmallFont and gdTinyFont. GD::SVG also exports these same global
620 variables but establishes them in a different manner using constant
621 variables to establish the font family, font height and width of these
622 global fonts. These values were chosen to match as closely as possible
623 GD's output. If unsatisfactory, adjust the constants at the top of
624 this file. In all subroutines below, GD::SVG passes a generic
625 GD::SVG::Font object in place of the exported font variables.
626 $image->string($font,$x,$y,$string,$color)
628 This method draws a string starting at position (x,y) in the speci-
629 fied font and color. Your choices of fonts are gdSmallFont,
630 gdMediumBoldFont, gdTinyFont, gdLargeFont and gdGiantFont.
631 $myImage->string(gdSmallFont,2,10,"Peachy Keen",$peach);
633 $image->stringUp($font,$x,$y,$string,$color)
635 Same as the previous example, except that it draws the text rotated
636 counter-clockwise 90 degrees.
637 $image->char($font,$x,$y,$char,$color)
639 $image->charUp($font,$x,$y,$char,$color)
640 These methods draw single characters at position (x,y) in the spec-
641 ified font and color. They're carry-overs from the C interface,
642 where there is a distinction between characters and strings. Perl
643 is insensible to such subtle distinctions. Neither is SVG, which
644 simply calls the string() method internally.
645 @bounds = $image->stringFT($fgcolor,$font-
647 name,$ptsize,$angle,$x,$y,$string)
648 @bounds = $image->stringFT($fgcolor,$font-
649 name,$ptsize,$angle,$x,$y,$string,\%options)
650 In GD, these methods use TrueType to draw a scaled, antialiased
651 strings using the TrueType font of your choice. GD::SVG can handle
652 this directly generating by calling the string() method internally.
653 The arguments are as follows:
655 fgcolor Color index to draw the string in
657 fontname An absolute path to the TrueType (.ttf) font file
658 ptsize The desired point size (may be fractional)
659 angle The rotation angle, in radians
660 x,y X and Y coordinates to start drawing the string
661 string The string itself
662 GD::SVG attempts to extract the name of the font from the pathname
664 supplied in the fontname argument. If it fails, Helvetica will be
665 used instead.
666 If successful, the method returns an eight-element list giving the
668 boundaries of the rendered string:
669 @bounds[0,1] Lower left corner (x,y)
671 @bounds[2,3] Lower right corner (x,y)
672 @bounds[4,5] Upper right corner (x,y)
673 @bounds[6,7] Upper left corner (x,y)
674 This from the GD documentation (not yet implemented in GD::SVG):
676 An optional 8th argument allows you to pass a hashref of options to
678 stringFT(). Two hashkeys are recognized: linespacing, if present,
679 controls the spacing between lines of text. charmap, if present,
680 sets the character map to use.
681 The value of linespacing is supposed to be a multiple of the char-
683 acter height, so setting linespacing to 2.0 will result in double-
684 spaced lines of text. However the current version of libgd
685 (2.0.12) does not do this. Instead the linespacing seems to be
686 double what is provided in this argument. So use a spacing of 0.5
687 to get separation of exactly one line of text. In practice, a
688 spacing of 0.6 seems to give nice results. Another thing to watch
689 out for is that successive lines of text should be separated by the
690 "\r\n" characters, not just "\n".
691 The value of charmap is one of "Unicode", "Shift_JIS" and "Big5".
693 The interaction between Perl, Unicode and libgd is not clear to me,
694 and you should experiment a bit if you want to use this feature.
695 $gd->stringFT($black,'/dosc/windows/Fonts/pala.ttf',40,0,20,90,
697 "hi there\r\nbye now",
698 {linespacing=>0.6,
699 charmap => 'Unicode',
700 });
701 For backward compatibility with older versions of the FreeType
703 library, the alias stringTTF() is also recognized. Also be aware
704 that relative font paths are not recognized due to problems in the
705 libgd library.
706 Alpha Channels
708 $image->alphaBlending($blending)
710 NOT IMPLEMENTED
711 $image->saveAlpha($saveAlpha)
713 NOT IMPLEMENTED
714 Miscellaneous Image Methods
716 $image->interlaced([$flag])
718 NOT IMPLEMENTED
719 ($width,$height) = $image->getBounds()
721 getBounds() returns the height and width of the image.
722 $is_truecolor = $image->isTrueColor()
724 NOT IMPLEMENTED
725 $flag = $image1->compare($image2)
727 NOT IMPLEMENTED
728 $image->clip($x1,$y1,$x2,$y2) ($x1,$y1,$x2,$y2) = $image->clip
730 NOT IMPLEMENTED
731 $flag = $image->boundsSafe($x,$y)
733 NOT IMPLEMENTED
734
736 SVG is much more adept at creating polygons than GD. That said, GD does
737 provide some rudimentary support for polygons but must be created as
738 seperate objects point by point.
739 $poly = GD::SVG::Polygon->new
741 Create an empty polygon with no vertices.
742 $poly = new GD::SVG::Polygon;
744 $poly->addPt($x,$y)
746 Add point (x,y) to the polygon.
747 $poly->addPt(0,0);
749 $poly->addPt(0,50);
750 $poly->addPt(25,25);
751 ($x,$y) = $poly->getPt($index)
753 Retrieve the point at the specified vertex.
754 ($x,$y) = $poly->getPt(2);
756 $poly->setPt($index,$x,$y)
758 Change the value of an already existing vertex. It is an error to
759 set a vertex that isn't already defined.
760 $poly->setPt(2,100,100);
762 ($x,$y) = $poly->deletePt($index)
764 Delete the specified vertex, returning its value.
765 ($x,$y) = $poly->deletePt(1);
767 $poly->toPt($dx,$dy)
769 Draw from current vertex to a new vertex, using relative (dx,dy)
770 coordinates. If this is the first point, act like addPt().
771 $poly->addPt(0,0);
773 $poly->toPt(0,50);
774 $poly->toPt(25,-25);
775 NOT IMPLEMENTED
777 $vertex_count = $poly->length()
779 Return the number of vertices in the polygon.
780 @vertices = $poly->vertices()
782 Return a list of all the verticies in the polygon object. Each
783 mem- ber of the list is a reference to an (x,y) array.
784 @vertices = $poly->vertices;
786 foreach $v (@vertices)
787 print join(",",@$v),"\n";
788 }
789 @rect = $poly->bounds()
791 Return the smallest rectangle that completely encloses the polygon.
792 The return value is an array containing the (left,top,right,bottom)
793 of the rectangle.
794 ($left,$top,$right,$bottom) = $poly->bounds;
796 $poly->offset($dx,$dy)
798 Offset all the vertices of the polygon by the specified horizontal
799 (dh) and vertical (dy) amounts. Positive numbers move the polygon
800 down and to the right. Returns the number of vertices affected.
801 $poly->offset(10,30);
803 $poly->map($srcL,$srcT,$srcR,$srcB,$destL,$dstT,$dstR,$dstB)
805 Map the polygon from a source rectangle to an equivalent position
806 in a destination rectangle, moving it and resizing it as necessary.
807 See polys.pl for an example of how this works. Both the source and
808 destination rectangles are given in (left,top,right,bottom) coordi-
809 nates. For convenience, you can use the polygon's own bounding box
810 as the source rectangle.
811 # Make the polygon really tall
813 $poly->map($poly->bounds,0,0,50,200);
814 NOT IMPLEMENTED
816 $poly->scale($sx,$sy)
818 Scale each vertex of the polygon by the X and Y factors indicated
819 by sx and sy. For example scale(2,2) will make the polygon twice
820 as large. For best results, move the center of the polygon to
821 position (0,0) before you scale, then move it back to its previous
822 position.
823 NOT IMPLEMENTED
825 $poly->transform($sx,$rx,$sy,$ry,$tx,$ty)
827 Run each vertex of the polygon through a transformation matrix,
828 where sx and sy are the X and Y scaling factors, rx and ry are the
829 X and Y rotation factors, and tx and ty are X and Y offsets. See
830 the Adobe PostScript Reference, page 154 for a full explanation, or
831 experiment.
832 NOT IMPLEMENTED
834 GD::Polyline
836 Please see GD::Polyline for information on creating open polygons and
838 splines.
839
841 NOTE: The object-oriented implementation to font utilites is not yet
842 supported.
843 The libgd library (used by the Perl GD library) has built-in support
845 for about half a dozen fonts, which were converted from public-domain X
846 Windows fonts. For more fonts, compile libgd with TrueType support and
847 use the stringFT() call.
848 GD::SVG replicates the internal fonts of GD by hardcoding fonts which
850 resemble the design and point size of the original. Each of these
851 fonts is available both as an imported global (e.g. gdSmallFont) and as
852 a package method (e.g. GD::Font->Small).
853 gdTinyFont
855 GD::Font->Tiny
856 This is a tiny, almost unreadable font, 5x8 pixels wide.
857 gdSmallFont
859 GD::Font->Small
860 This is the basic small font, "borrowed" from a well known public
861 domain 6x12 font.
862 gdMediumBoldFont
864 GD::Font->MediumBold
865 This is a bold font intermediate in size between the small and
866 large fonts, borrowed from a public domain 7x13 font;
867 gdLargeFont
869 GD::Font->Large
870 This is the basic large font, "borrowed" from a well known public
871 domain 8x16 font.
872 gdGiantFont
874 GD::Font->Giant
875 This is a 9x15 bold font converted by Jan Pazdziora from a sans
876 serif X11 font.
877 $font->nchars
879 This returns the number of characters in the font.
880 print "The large font contains ",gdLargeFont->nchars," characters\n";
882 NOT IMPLEMENTED
884 $font->offset()
886 This returns the ASCII value of the first character in the font
887 $width = $font->width
889 $height = $font->height
890 These return the width and height of the font.
891 ($w,$h) = (gdLargeFont->width,gdLargeFont->height);
893
895 BioPerl
896 The Bio::Graphics package of the BioPerl project makes use of
897 GD::SVG to export SVG graphics.
898 http://www.bioperl.org/
900 Generic Genome Browser
902 The Generic Genome Browser (GBrowse) utilizes Bio::Graphics and
903 enables SVG dumping of genomics views. You can see a real-world
904 example of SVG output from GBrowse at WormBase:
905 http://www.wormbase.org/cgi-bin/gbrowse/
907 Further information about the Generic Genome Browser is available
909 at the Generic Model Organism Project home page:
910 http://www.gmod.org/
912 toddot
914 I've also prepared a number of comparative images at my website
915 (shameless plug, hehe):
916 http://www.toddot.net/projects/GD-SVG/
918
920 The following internal methods are private and documented only for
921 those wishing to extend the GD::SVG interface.
922 _distill_gdSpecial()
924 When a drawing method is passed a stylized brush via gdBrushed, the
925 internal _distill_gdSpecial() method attempts to make sense of this
926 by setting line thickness and foreground color. Since stylized
927 brushes are GD::SVG::Image objects, it does this by fetching the
928 width of the image using the getBounds method. This width is then
929 used to setThickness. The last color set by colorAllocate is then
930 used for the foreground color.
931 In setting line thickness, GD::SVG temporarily overrides any previ‐
933 ously set line thickness. In GD, setThickness is persistent
934 through uses of stylized brushes. To accomodate this behavior,
935 _distill_gdSpecial() temporarily stores the previous line_thickness
936 in the $self->{previous_line_thickness} flag.
937 _reset()
939 The _reset() method is used to restore persistent drawing settings
940 between uses of stylized brushes. Currently, this involves
941 - restoring line thickness
943
945 A second module (SVG::GD), written by Ronan Oger also provides similar
946 functionality as this module. Ronan and I are concurrently developing
947 these modules with an eye towards integrating them in the future. In
948 principle, the primary difference is that GD::SVG aims to generate SVG
949 and SVG only. That is, it:
950 1. Does not store an internal representation of the GD image
952 2. Does not enable JPG, PNG, OR SVG output from a single pass
954 through data
955 3. Only occasioanally uses inherited methods from GD
957 Instead GD::SVG depends on the user to choose which output format they
959 would like in advance, "use"ing the appropriate module for that output.
960 As described at the start of this document, module selection between GD
961 and GD::SVG can be made dynamically using eval statements and variables
962 for the differnet classes that GD and GD::SVG create.
963 There is a second reason for not maintaining a double representation of
965 the data in GD and SVG format: SVG documents can quickly become very
966 large, especially with large datasets. In cases where scripts are pri‐
967 marily generating png images in a server environment and would only
968 occasionally need to export SVG, gernerating an SVG image in parallel
969 would result in an unacceptable performance hit.
970 Thus GD::SVG aims to be a plugin for existing configurations that
972 depend on GD but would like to take advantage of SVG output.
973 SVG::GD, on the other hand, aims to tie in the raster-editing ability
975 of GD with the power of SVG output. In part, it aims to do this by
976 inheriting many methods from GD directly and bringing them into the
977 functional space of GD. This makes SVG::GD easier to set up initially
978 (simply by adding the "use SVG::GD" below the "use GD" statement of
979 your script. GD::SVG sacrfices this initial ease-of-setup for more tar‐
980 geted applications.
981
983 Lincoln Stein, my postdoctoral mentor, author of GD.pm, and all around
984 Perl stud. Ronan Oger, author of SVG.pm conceptualized and implemented
985 another wrapper around GD at about the exact same time as this module.
986 He also provided helpful discussions on implementing GD functions into
987 SVG. Oliver Drechsel and Marc Lohse provided patches to actually make
988 the stringUP method functional.
989
991 Todd Harris, PhD <harris@cshl.org>
992
994 Copyright @ 2003-2005 Todd Harris and the Cold Spring Harbor Laboratory
995 This library is free software; you can redistribute it and/or modify it
997 under the same terms as Perl itself.
998
1000 GD, SVG, SVG::Manual, SVG::DOM
1001perl v5.8.8 2006-05-26 SVG(3)