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
27 methods.
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
47 convenience, 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
72 modification.
73 If you make heavy use of GD's exported methods, it may also be
75 necessary to add () to the endo of method names to avoide bareword
76 compilation errors. That's the price you pay for using exported
77 functions!
78
80 GD::SVG does not directly generate SVG, but instead relies upon SVG.pm.
81 It is not intended to supplant SVG.pm. Furthermore, since GD::SVG is,
82 in essence an API to an API, it may not be suitable for applications
83 where speed is of the essence. In these cases, GD::SVG may provide a
84 short-term solution while scripts are re-written to enable more direct
85 output of SVG.
86 Many of the GD::SVG methods accept additional parameters (which are in
88 turn reflected in the SVG.pm API) that are not supported in GD. Look
89 through the remainder of this document for options on specific In
90 addition, several functions have yet to be mapped to SVG.pm calls.
91 Please see the section below regarding regarding GD functions that are
92 missing or altered in GD::SVG.
93 A similar module (SVG::GD) implements a similar wrapper around GD.
95 Please see the section at the bottom of this document that compares
96 GD::SVG to SVG::GD.
97
99 GD::SVG requires the Ronan Oger's SVG.pm module, Lincoln Stein's GD.pm
100 module, libgd and its dependencies.
101
103 These are the primary weaknesses of GD::SVG.
104 SVG requires unique identifiers for each element
106 Each element in an SVG image requires a unique identifier. In
107 general, GD::SVG handles this by automatically generating unique
108 random numbers. In addition to the typical parameters for GD
109 methods, GD::SVG methods allow a user to pass an optional id
110 parameter for naming the object.
111 Direct calls to the GD package will fail
113 You must change direct calls to the classes that GD invokes:
114 GD::Image->new() should be changed to GD::SVG::Image->new()
115 See the documentation above for how to dynamically switch between
117 packages.
118 raster fill() and fillToBorder() not supported
120 As SVG documents are not inherently aware of their canvas, the
121 flood fill methods are not currently supported.
122 getPixel() not supported.
124 Although setPixel() works as expected, its counterpart getPixel()
125 is not supported. I plan to support this method in a future
126 release.
127 No support for generation of images from filehandles or raw data
129 GD::SVG works only with scripts that generate images directly in
130 the code using the GD->new(height,width) approach. newFrom()
131 methods are not currently supported.
132 Tiled fills are not supported
134 Any functions passed gdTiled objects will die.
135 Styled and Brushed lines only partially implemented
137 Calls to the gdStyled and gdBrushed functions via a rather humorous
138 kludge (and simplification). Depending on the complexity of the
139 brush, they may behave from slightly differently to radically
140 differently from their behavior under GD. You have been warned. See
141 the documentation sections for the methods that set these options
142 (setStyle(), setBrush(), and setTransparent()).
143 See below for a full list of methods that have not yet been
145 implemented.
146
148 GD is a complicated module. Translating GD methods into those required
149 to draw in SVG are not always direct. You may or may not get the output
150 you expect. In general, some tweaking of image parameters (like text
151 height and width) may be necessary.
152 If your script doesn't work as expected, first check the list of
154 methods that GD::SVG provides. Due to differences in the nature of SVG
155 images, not all GD methods have been implemented in GD::SVG.
156 If your image doesn't look as expected, try tweaking specific aspects
158 of image generation. In particular, check for instances where you
159 calculate dimensions of items on the fly like font->height. In SVG, the
160 values of fonts are defined explicitly.
161
163 The following GD functions have not yet been incorporated into GD::SVG.
164 If you attempt to use one of these functions (and you have enabled
165 debug warnings via the new() method), GD::SVG will print a warning to
166 STDERR.
167 Creating image objects:
169 GD::Image->newPalette([$width,$height])
170 GD::Image->newTrueColor([$width,$height])
171 GD::Image->newFromPng($file, [$truecolor])
172 GD::Image->newFromPngData($data, [$truecolor])
173 GD::Image->newFromJpeg($file, [$truecolor])
174 GD::Image->newFromJpegData($data, [$truecolor])
175 GD::Image->newFromXbm($file)
176 GD::Image->newFromWMP($file)
177 GD::Image->newFromGd($file)
178 GD::Image->newFromGdData($data)
179 GD::Image->newFromGd2($file)
180 GD::Image->newFromGd2Data($data)
181 GD::Image->newFromGd2Part($file,srcX,srcY,width,height)
182 GD::Image->newFromXpm($filename)
183 Image methods:
185 $gddata = $image->gd
186 $gd2data = $image->gd2
187 $wbmpdata = $image->wbmp([$foreground])
188 Color control methods:
190 $image->colorAllocateAlpha()
191 $image->colorClosest()
192 $image->colorClosestHWB()
193 $image->getPixel()
194 $image->transparent()
195 Special Colors:
197 $image->setBrush() (semi-supported, with kludge)
198 $image->setStyle() (semi-supported, with kludge)
199 gdTiled
200 $image->setAntialiased()
201 gdAntiAliased()
202 $image->setAntiAliasedDontBlend()
203 Drawing methods:
205 $image->dashedLine()
206 $image->fill()
207 $image->fillToBorder()
208 Image copying methods
210 None of the image copying methods are yet supported
211 Image transformation methods
213 None of the image transformation methods are yet supported
214 Character and string drawing methods
216 $image->stringUp() - incompletely supported - broken
217 $image->charUp()
218 $image->stringFT()
219 Alpha Channels
221 $image->alphaBlending()
222 $image->saveAlpha()
223 Miscellaneous image methods
225 $image->isTrueColor()
226 $image->compare($image2)
227 $image->clip()
228 $image->boundsSafe()
229 GD::Polyline
231 Supported without modifications
232 Font methods:
234 $font->nchars()
235 $font->offset()
236
238 GD::SVG supports three additional methods that provides the ability to
239 recursively group objects:
240 $this->startGroup([$id,\%style]), $this->endGroup()
242 These methods start and end a group in a procedural manner. Once a
243 group is started, all further drawing will be appended to the group
244 until endGroup() is invoked. You may optionally pass a string ID
245 and an SVG styles hash to startGroup.
246 $group = $this->newGroup([$id,\%style])
248 This method returns a GD::Group object, which has all the behaviors
249 of a GD::SVG object except that it draws within the current group.
250 You can invoke this object's drawing methods to draw into a group.
251 The group is closed once the object goes out of scope. While the
252 object is open, invoking drawing methods on the parent GD::SVG
253 object will also draw into the group until it goes out of scope.
254 Here is an example of using grouping in the procedural way:
256 use GD::SVG;
258 my $img = GD::SVG::Image->new(500,500);
259 my $white = $img->colorAllocate(255,255,255);
260 my $black = $img->colorAllocate(0,0,0);
261 my $blue = $img->colorAllocate(0,0,255);
262 my $red = $img->colorAllocate(255,0,0);
263 $img->startGroup('circle in square');
265 $img->rectangle(100,100,400,400,$blue);
266 $img->startGroup('circle and boundary');
268 $img->filledEllipse(250,250,200,200,$red);
269 $img->ellipse(250,250,200,200,$black);
270 $img->endGroup;
272 $img->endGroup;
273 print $img->svg;
275 Here is an example of using grouping with the GD::Group object:
277 ...
279 my $g1 = $img->newGroup('circle in square');
281 $g1->rectangle(100,100,400,400,$blue);
282 my $g2 = $g1->startGroup('circle and boundary');
284 $g2->filledEllipse(250,250,200,200,$red);
285 $g2->ellipse(250,250,200,200,$black);
286 print $img->svg;
288 Finally, here is a fully worked example of using the GD::Simple
290 module to make the syntax cleaner:
291 #!/usr/bin/perl
293 use strict;
295 use GD::Simple;
296 GD::Simple->class('GD::SVG');
298 my $img = GD::Simple->new(500,500);
300 $img->bgcolor('white');
301 $img->fgcolor('blue');
302 my $g1 = $img->newGroup('circle in square');
304 $g1->rectangle(100,100,400,400);
305 $g1->moveTo(250,250);
306 my $g2 = $g1->newGroup('circle and boundary');
308 $g2->fgcolor('black');
309 $g2->bgcolor('red');
310 $g2->ellipse(200,200);
311 print $img->svg;
313
315 All GD::SVG methods mimic the naming and interface of GD methods. As
316 such, maintenance of GD::SVG follows the development of both GD and
317 SVG. Much of the original GD documentation is replicated here for ease
318 of use. Subtle differences in the implementation of these methods
319 between GD and GD::SVG are discussed below. In particular, the return
320 value for some GD::SVG methods differs from its GD counterpart.
321
323 GD::SVG currently only supports the creation of image objects via its
324 new constructor. This is in contrast to GD proper which supports the
325 creation of images from previous images, filehandles, filenames, and
326 data.
327 $image = GD::SVG::Image->new($height,$width,$debug);
329 Create a blank GD::SVG image object of the specified dimensions in
330 pixels. In turn, this method will create a new SVG object and store
331 it internally. You can turn on debugging with the GD::SVG specific
332 $debug parameter. This should be boolean true and will cause non-
333 implemented methods to print a warning on their status to STDERR.
334
336 Once a GD::Image object is created, you can draw with it, copy it, and
337 merge two images. When you are finished manipulating the object, you
338 can convert it into a standard image file format to output or save to a
339 file.
340 Image Data Output Methods
342 GD::SVG implements a single output method, svg()!
343 $svg = $image->svg();
345 This returns the image in SVG format. You may then print it, pipe
346 it to an image viewer, or write it to a file handle. For example,
347 $svg_data = $image->svg();
349 open (DISPLAY,"| display -") || die;
350 binmode DISPLAY;
351 print DISPLAY $svg_data;
352 close DISPLAY;
353 if you'd like to return an inline version of the image (instead of
355 a full document version complete with the DTD), pass the svg()
356 method the 'inline' flag:
357 $svg_data = $image->svg(-inline=>'true');
359 Calling the other standard GD image output methods (eg
361 jpeg,gd,gd2,png) on a GD::SVG::Image object will cause your script
362 to exit with a warning.
363 Color Control
365 These methods allow you to control and manipulate the color table of a
366 GD::SVG image. In contrast to GD which uses color indices, GD::SVG
367 passes stringified RGB triplets as colors. GD::SVG, however, maintains
368 an internal hash structure of colors and colored indices in order to
369 map GD functions that manipulate the color table. This typically
370 requires behind-the-scenes translation of these stringified RGB
371 triplets into a color index.
372 $stringified_color = $image->colorAllocate(RED,GREEN,BLUE)
374 Unlike GD, colors need not be allocated in advance in SVG. Unlike
375 GD which returns a color index, colorAllocate returns a formatted
376 string compatible with SVG. Simultaneously, it creates and stores
377 internally a GD compatible color index for use with GD's color
378 manipulation methods.
379 returns: "rgb(RED,GREEN,BLUE)"
381 $index = $image->colorAllocateAlpha()
383 NOT IMPLEMENTED
384 $image->colorDeallocate($index)
386 Provided with a color index, remove it from the color table.
387 $index = $image->colorClosest(red,green,blue)
389 This returns the index of the color closest in the color table to
390 the red green and blue components specified. This method is
391 inherited directly from GD.
392 Example: $apricot = $myImage->colorClosest(255,200,180);
394 NOT IMPLEMENTED
396 $index = $image->colorClosestHWB(red,green,blue)
398 NOT IMPLEMENTED
399 $index = $image->colorExact(red,green,blue)
401 Retrieve the color index of an rgb triplet (or -1 if it has yet to
402 be allocated).
403 NOT IMPLEMENTED
405 $index = $image->colorResolve(red,green,blue)
407 NOT IMPLEMENTED
408 $colors_total = $image->colorsTotal()
410 Retrieve the total number of colors indexed in the image.
411 $index = $image->getPixel(x,y)
413 NOT IMPLEMENTED
414 ($red,$green,$blue) = $image->rgb($index)
416 Provided with a color index, return the RGB triplet. In GD::SVG,
417 color indexes are replaced with actual RGB triplets in the form
418 "rgb($r,$g,$b)".
419 $image->transparent($colorIndex);
421 Control the transparency of individual colors.
422 NOT IMPLEMENTED
424 Special Colors
426 GD implements a number of special colors that can be used to achieve
427 special effects. They are constants defined in the GD:: namespace, but
428 automatically exported into your namespace when the GD module is
429 loaded. GD::SVG offers limited support for these methods.
430 $image->setBrush($brush) (KLUDGE ALERT)
432 gdBrushed
433 In GD, one can draw lines and shapes using a brush pattern.
434 Brushes are just images that you can create and manipulate in the
435 usual way. When you draw with them, their contents are used for
436 the color and shape of the lines.
437 To make a brushed line, you must create or load the brush first,
439 then assign it to the image using setBrush(). You can then draw in
440 that with that brush using the gdBrushed special color. It's often
441 useful to set the background of the brush to transparent so that
442 the non-colored parts don't overwrite other parts of your image.
443 # Via GD, this is how one would set a Brush
445 $diagonal_brush = new GD::Image(5,5);
446 $white = $diagonal_brush->colorAllocate(255,255,255);
447 $black = $diagonal_brush->colorAllocate(0,0,0);
448 $diagonal_brush->transparent($white);
449 $diagonal_brush->line(0,4,4,0,$black); # NE diagonal
450 GD::SVG offers limited support for setBrush (and the corresponding
452 gdBrushed methods) - currently only in the shapes of squares.
453 Internally, GD::SVG extracts the longest dimension of the image
454 using the getBounds() method. Next, it extracts the second color
455 set, assuming that to be the foreground color. It then re-calls the
456 original drawing method with these new values in place of the
457 gdBrushed. See the private _distill_gdSpecial method for the
458 internal details of this operation.
459 $image->setThickness($thickness)
461 Lines drawn with line(), rectangle(), arc(), and so forth are 1
462 pixel thick by default. Call setThickness() to change the line
463 drawing width.
464 $image->setStyle(@colors)
466 setStyle() and gdStyled() are partially supported in GD::SVG.
467 GD::SVG determines the alternating pattern of dashes, treating the
468 first unique color encountered in the array as on, the second as
469 off and so on. The first color in the array is then used to draw
470 the actual line.
471 gdTiled
473 NOT IMPLEMENTED
474 gdStyled()
476 The GD special color gdStyled is partially implemented in GD::SVG.
477 Only the first color will be used to generate the dashed pattern
478 specified in setStyle(). See setStyle() for additional information.
479 $image->setAntiAliased($color)
481 NOT IMPLEMENTED
482 gdAntiAliased
484 NOT IMPLEMENTED
485 $image->setAntiAliasedDontBlend($color,[$flag])
487 NOT IMPLEMENTED
488 Drawing Commands
490 $image->setPixel($x,$y,$color)
491 Set the corresponding pixel to the given color. GD::SVG implements
492 this by drawing a single dot in the specified color at that
493 position.
494 $image->line(x1,y1,x2,y2,color);
496 Draw a line between the two coordinate points with the specified
497 color. Passing an optional id will set the id of that SVG element.
498 GD::SVG also supports drawing with the special brushes - gdStyled
499 and gdBrushed - although these special styles are difficult to
500 replicate precisley in GD::SVG.
501 $image->dashedLine($x1,$y1,$x2,$y2,$color);
503 NOT IMPLEMENTED
504 $image->rectangle($x1,$y1,$x2,$y2,$color);
506 This draws a rectangle with the specified color. (x1,y1) and
507 (x2,y2) are the upper left and lower right corners respectively.
508 You may also draw with the special colors gdBrushed and gdStyled.
509 $image->filledRectangle($x1,$y1,$x2,$y2,$color);
511 filledRectangle is a GD specific method with no direct equivalent
512 in SVG. GD::SVG translates this method into an SVG appropriate
513 method by passing the filled color parameter as a named 'filled'
514 parameter to SVG. Drawing with the special colors is also
515 permitted. See the documentation for the line() method for
516 additional details.
517 GD call:
519 $img->filledRectangle($x1,$y1,$x2,$y2,$color);
520 SVG call:
522 $img->rectangle(x=> $x1,y=> $y1,
523 width => $x2-$x1,
524 height => $y2-$y1,
525 fill => $color
526 $image->polygon($polygon,$color);
528 This draws a polygon with the specified color. The polygon must be
529 created first (see "Polygons" below). The polygon must have at
530 least three vertices. If the last vertex doesn't close the
531 polygon, the method will close it for you. Both real color indexes
532 and the special colors gdBrushed, gdStyled and gdStyledBrushed can
533 be specified. See the documentation for the line() method for
534 additional details.
535 $poly = new GD::Polygon;
537 $poly->addPt(50,0);
538 $poly->addPt(99,99);
539 $poly->addPt(0,99);
540 $image->polygon($poly,$blue);
541 $image->filledPolygon($polygon,$color);
543 This draws a polygon filled with the specified color. Drawing with
544 the special colors is also permitted. See the documentation for the
545 line() method for additional details.
546 # make a polygon
548 $poly = new GD::Polygon;
549 $poly->addPt(50,0);
550 $poly->addPt(99,99);
551 $poly->addPt(0,99);
552 # draw the polygon, filling it with a color
554 $image->filledPolygon($poly,$peachpuff);
555 $image->filledPolygon($polygon,$color);
557 This draws a polygon filled with the specified color. Drawing with
558 the special colors is also permitted. See the documentation for the
559 line() method for additional details.
560 # make a polygon
562 $poly = new GD::Polygon;
563 $poly->addPt(50,0);
564 $poly->addPt(99,99);
565 $poly->addPt(0,99);
566 # draw the polygon, filling it with a color
568 $image->filledPolygon($poly,$peachpuff);
569 $image->polyline(polyline,color)
571 $image->polyline($polyline,$black)
572 This draws a polyline with the specified color. Both real color
574 indexes and the special colors gdBrushed, gdStyled and
575 gdStyledBrushed can be specified.
576 Neither the polyline() method or the polygon() method are very
578 picky: you can call either method with either a GD::Polygon or a
579 GD::Polyline. The method determines if the shape is "closed" or
580 "open" as drawn, not the object type.
581 $image->polydraw(polything,color)
583 $image->polydraw($poly,$black)
584 This method draws the polything as expected (polygons are closed,
586 polylines are open) by simply checking the object type and calling
587 either $image->polygon() or $image->polyline().
588 $image->ellipse($cx,$cy,$width,$height,$color)
590 $image->filledEllipse($cx,$cy,$width,$height,$color)
591 These methods() draw ellipses. ($cx,$cy) is the center of the arc,
592 and ($width,$height) specify the ellipse width and height,
593 respectively. filledEllipse() is like ellipse() except that the
594 former produces filled versions of the ellipse. Drawing with the
595 special colors is also permitted. See the documentation for the
596 line() method for additional details.
597 $image->arc($cy,$cy,$width,$height,$start,$end,$color);
599 This draws arcs and ellipses. (cx,cy) are the center of the arc,
600 and (width,height) specify the width and height, respectively. The
601 portion of the ellipse covered by the arc are controlled by start
602 and end, both of which are given in degrees from 0 to 360. Zero is
603 at the top of the ellipse, and angles increase clockwise. To
604 specify a complete ellipse, use 0 and 360 as the starting and
605 ending angles. To draw a circle, use the same value for width and
606 height.
607 Internally, arc() calls the ellipse() method of SVG.pm. Drawing
609 with the special colors is also permitted. See the documentation
610 for the line() method for additional details.
611 Currently, true arcs are NOT supported, only those where the start
613 and end equal 0 and 360 respectively resulting in a closed arc.
614 $image->filledArc($cx,$cy,$width,$height,$start,$end,$color
616 [,$arc_style])
617 This method is like arc() except that it colors in the pie wedge
618 with the selected color. $arc_style is optional. If present it is
619 a bitwise OR of the following constants:
620 gdArc connect start & end points of arc with a rounded
622 edge gdChord connect start & end points of arc with a
623 straight line gdPie synonym for gdChord gdNoFill
624 outline the arc or chord gdEdged connect beginning and
625 ending of the arc to the center
626 gdArc and gdChord are mutally exclusive. gdChord just connects the
628 starting and ending angles with a straight line, while gdArc pro-
629 duces a rounded edge. gdPie is a synonym for gdArc. gdNoFill indi-
630 cates that the arc or chord should be outlined, not filled.
631 gdEdged, used together with gdNoFill, indicates that the beginning
632 and ending angles should be connected to the center; this is a good
633 way to outline (rather than fill) a "pie slice."
634 Using these special styles, you can easily draw bordered ellipses
636 and circles.
637 # Create the filled shape:
639 $image->filledArc($x,$y,$width,$height,0,360,$fill); # Now border
640 it. $image->filledArc($x,$y,$width,$height,0,360,$color,gdNoFill);
641 $image->fill();
643 NOT IMPLEMENTED
644 $image->fillToBorder()
646 NOT IMPLEMENTED
647 Image Copying Methods
649 The basic copy() command is implemented in GD::SVG. You can copy one
650 GD::SVG into another GD::SVG, or copy a GD::Image or GD::Simple object
651 into a GD::SVG, thereby embedding a pixmap image into the SVG image.
652 All other image copying methods are unsupported, and if your script
654 calls one of the following methods, your script will die remorsefully
655 with a warning. With sufficient demand, I might try to implement some
656 of these methods. For now, I think that they are beyond the intent of
657 GD::SVG.
658 $image->clone()
660 $image->copyMerge()
661 $image->copyMergeGray()
662 $image->copyResized()
663 $image->copyResampled()
664 $image->trueColorToPalette()
665 Image Transfomation Commands
667 None of the image transformation commands are implemented in GD::SVG.
668 If your script calls one of the following methods, your script will die
669 remorsefully with a warning. With sufficient demand, I might try to
670 implement some of these methods. For now, I think that they are beyond
671 the intent of GD::SVG.
672 $image = $sourceImage->copyRotate90()
674 $image = $sourceImage->copyRotate180()
675 $image = $sourceImage->copyRotate270()
676 $image = $sourceImage->copyFlipHorizontal()
677 $image = $sourceImage->copyFlipVertical()
678 $image = $sourceImage->copyTranspose()
679 $image = $sourceImage->copyReverseTranspose()
680 $image->rotate180()
681 $image->flipHorizontal()
682 $image->flipVertical()
683 Character And String Drawing
685 GD allows you to draw characters and strings, either in normal horizon-
686 tal orientation or rotated 90 degrees. In GD, these routines use a
687 GD::Font object. Internally, GD::SVG mimics the behavior of GD with
688 respect to fonts in a very similar manner, using instead a
689 GD::SVG::Font object described in more detail below.
690 GD's font handling abilities are not as flexible as SVG and it does not
692 allow the dynamic creation of fonts, instead exporting five available
693 fonts as global variables: gdGiantFont, gdLargeFont, gdMediumBoldFont,
694 gdSmallFont and gdTinyFont. GD::SVG also exports these same global
695 variables but establishes them in a different manner using constant
696 variables to establish the font family, font height and width of these
697 global fonts. These values were chosen to match as closely as possible
698 GD's output. If unsatisfactory, adjust the constants at the top of
699 this file. In all subroutines below, GD::SVG passes a generic
700 GD::SVG::Font object in place of the exported font variables.
701 $image->string($font,$x,$y,$string,$color)
703 This method draws a string starting at position (x,y) in the speci-
704 fied font and color. Your choices of fonts are gdSmallFont,
705 gdMediumBoldFont, gdTinyFont, gdLargeFont and gdGiantFont.
706 $myImage->string(gdSmallFont,2,10,"Peachy Keen",$peach);
708 $image->stringUp($font,$x,$y,$string,$color)
710 Same as the previous example, except that it draws the text rotated
711 counter-clockwise 90 degrees.
712 $image->char($font,$x,$y,$char,$color)
714 $image->charUp($font,$x,$y,$char,$color)
715 These methods draw single characters at position (x,y) in the spec-
716 ified font and color. They're carry-overs from the C interface,
717 where there is a distinction between characters and strings. Perl
718 is insensible to such subtle distinctions. Neither is SVG, which
719 simply calls the string() method internally.
720 @bounds = $image->stringFT($fgcolor,$font-
722 name,$ptsize,$angle,$x,$y,$string)
723 @bounds = $image->stringFT($fgcolor,$font-
724 name,$ptsize,$angle,$x,$y,$string,\%options)
725 In GD, these methods use TrueType to draw a scaled, antialiased
726 strings using the TrueType font of your choice. GD::SVG can handle
727 this directly generating by calling the string() method internally.
728 The arguments are as follows:
730 fgcolor Color index to draw the string in
732 fontname An absolute path to the TrueType (.ttf) font file
733 ptsize The desired point size (may be fractional)
734 angle The rotation angle, in radians
735 x,y X and Y coordinates to start drawing the string
736 string The string itself
737 GD::SVG attempts to extract the name of the font from the pathname
739 supplied in the fontname argument. If it fails, Helvetica will be
740 used instead.
741 If successful, the method returns an eight-element list giving the
743 boundaries of the rendered string:
744 @bounds[0,1] Lower left corner (x,y)
746 @bounds[2,3] Lower right corner (x,y)
747 @bounds[4,5] Upper right corner (x,y)
748 @bounds[6,7] Upper left corner (x,y)
749 This from the GD documentation (not yet implemented in GD::SVG):
751 An optional 8th argument allows you to pass a hashref of options to
753 stringFT(). Two hashkeys are recognized: linespacing, if present,
754 controls the spacing between lines of text. charmap, if present,
755 sets the character map to use.
756 The value of linespacing is supposed to be a multiple of the char-
758 acter height, so setting linespacing to 2.0 will result in double-
759 spaced lines of text. However the current version of libgd
760 (2.0.12) does not do this. Instead the linespacing seems to be
761 double what is provided in this argument. So use a spacing of 0.5
762 to get separation of exactly one line of text. In practice, a
763 spacing of 0.6 seems to give nice results. Another thing to watch
764 out for is that successive lines of text should be separated by the
765 "\r\n" characters, not just "\n".
766 The value of charmap is one of "Unicode", "Shift_JIS" and "Big5".
768 The interaction between Perl, Unicode and libgd is not clear to me,
769 and you should experiment a bit if you want to use this feature.
770 $gd->stringFT($black,'/dosc/windows/Fonts/pala.ttf',40,0,20,90,
772 "hi there\r\nbye now",
773 {linespacing=>0.6,
774 charmap => 'Unicode',
775 });
776 For backward compatibility with older versions of the FreeType
778 library, the alias stringTTF() is also recognized. Also be aware
779 that relative font paths are not recognized due to problems in the
780 libgd library.
781 $hasfontconfig = $image->useFontConfig($flag)
783 Call useFontConfig() with a value of 1 in order to enable support
784 for fontconfig font patterns (see stringFT). Regardless of the
785 value of $flag, this method will return a true value if the
786 fontconfig library is present, or false otherwise.
787 NOT IMPLEMENTED
789 Alpha Channels
791 $image->alphaBlending($blending)
792 NOT IMPLEMENTED
793 $image->saveAlpha($saveAlpha)
795 NOT IMPLEMENTED
796 Miscellaneous Image Methods
798 $image->interlaced([$flag])
799 NOT IMPLEMENTED
800 ($width,$height) = $image->getBounds()
802 getBounds() returns the height and width of the image.
803 $is_truecolor = $image->isTrueColor()
805 NOT IMPLEMENTED
806 $flag = $image1->compare($image2)
808 NOT IMPLEMENTED
809 $image->clip($x1,$y1,$x2,$y2) ($x1,$y1,$x2,$y2) = $image->clip
811 NOT IMPLEMENTED
812 $flag = $image->boundsSafe($x,$y)
814 NOT IMPLEMENTED
815
817 SVG is much more adept at creating polygons than GD. That said, GD does
818 provide some rudimentary support for polygons but must be created as
819 seperate objects point by point.
820 $poly = GD::SVG::Polygon->new
822 Create an empty polygon with no vertices.
823 $poly = new GD::SVG::Polygon;
825 $poly->addPt($x,$y)
827 Add point (x,y) to the polygon.
828 $poly->addPt(0,0);
830 $poly->addPt(0,50);
831 $poly->addPt(25,25);
832 ($x,$y) = $poly->getPt($index)
834 Retrieve the point at the specified vertex.
835 ($x,$y) = $poly->getPt(2);
837 $poly->setPt($index,$x,$y)
839 Change the value of an already existing vertex. It is an error to
840 set a vertex that isn't already defined.
841 $poly->setPt(2,100,100);
843 ($x,$y) = $poly->deletePt($index)
845 Delete the specified vertex, returning its value.
846 ($x,$y) = $poly->deletePt(1);
848 $poly->toPt($dx,$dy)
850 Draw from current vertex to a new vertex, using relative (dx,dy)
851 coordinates. If this is the first point, act like addPt().
852 $poly->addPt(0,0);
854 $poly->toPt(0,50);
855 $poly->toPt(25,-25);
856 NOT IMPLEMENTED
858 $vertex_count = $poly->length()
860 Return the number of vertices in the polygon.
861 @vertices = $poly->vertices()
863 Return a list of all the verticies in the polygon object. Each
864 mem- ber of the list is a reference to an (x,y) array.
865 @vertices = $poly->vertices;
867 foreach $v (@vertices)
868 print join(",",@$v),"\n";
869 }
870 @rect = $poly->bounds()
872 Return the smallest rectangle that completely encloses the polygon.
873 The return value is an array containing the (left,top,right,bottom)
874 of the rectangle.
875 ($left,$top,$right,$bottom) = $poly->bounds;
877 $poly->offset($dx,$dy)
879 Offset all the vertices of the polygon by the specified horizontal
880 (dh) and vertical (dy) amounts. Positive numbers move the polygon
881 down and to the right. Returns the number of vertices affected.
882 $poly->offset(10,30);
884 $poly->map($srcL,$srcT,$srcR,$srcB,$destL,$dstT,$dstR,$dstB)
886 Map the polygon from a source rectangle to an equivalent position
887 in a destination rectangle, moving it and resizing it as necessary.
888 See polys.pl for an example of how this works. Both the source and
889 destination rectangles are given in (left,top,right,bottom) coordi-
890 nates. For convenience, you can use the polygon's own bounding box
891 as the source rectangle.
892 # Make the polygon really tall
894 $poly->map($poly->bounds,0,0,50,200);
895 NOT IMPLEMENTED
897 $poly->scale($sx,$sy)
899 Scale each vertex of the polygon by the X and Y factors indicated
900 by sx and sy. For example scale(2,2) will make the polygon twice
901 as large. For best results, move the center of the polygon to
902 position (0,0) before you scale, then move it back to its previous
903 position.
904 NOT IMPLEMENTED
906 $poly->transform($sx,$rx,$sy,$ry,$tx,$ty)
908 Run each vertex of the polygon through a transformation matrix,
909 where sx and sy are the X and Y scaling factors, rx and ry are the
910 X and Y rotation factors, and tx and ty are X and Y offsets. See
911 the Adobe PostScript Reference, page 154 for a full explanation, or
912 experiment.
913 NOT IMPLEMENTED
915 GD::Polyline
917 Please see GD::Polyline for information on creating open polygons and
918 splines.
919
921 NOTE: The object-oriented implementation to font utilites is not yet
922 supported.
923 The libgd library (used by the Perl GD library) has built-in support
925 for about half a dozen fonts, which were converted from public-domain X
926 Windows fonts. For more fonts, compile libgd with TrueType support and
927 use the stringFT() call.
928 GD::SVG replicates the internal fonts of GD by hardcoding fonts which
930 resemble the design and point size of the original. Each of these
931 fonts is available both as an imported global (e.g. gdSmallFont) and as
932 a package method (e.g. GD::Font->Small).
933 gdTinyFont
935 GD::Font->Tiny
936 This is a tiny, almost unreadable font, 5x8 pixels wide.
937 gdSmallFont
939 GD::Font->Small
940 This is the basic small font, "borrowed" from a well known public
941 domain 6x12 font.
942 gdMediumBoldFont
944 GD::Font->MediumBold
945 This is a bold font intermediate in size between the small and
946 large fonts, borrowed from a public domain 7x13 font;
947 gdLargeFont
949 GD::Font->Large
950 This is the basic large font, "borrowed" from a well known public
951 domain 8x16 font.
952 gdGiantFont
954 GD::Font->Giant
955 This is a 9x15 bold font converted by Jan Pazdziora from a sans
956 serif X11 font.
957 $font->nchars
959 This returns the number of characters in the font.
960 print "The large font contains ",gdLargeFont->nchars," characters\n";
962 NOT IMPLEMENTED
964 $font->offset()
966 This returns the ASCII value of the first character in the font
967 $width = $font->width
969 $height = $font->height
970 These return the width and height of the font.
971 ($w,$h) = (gdLargeFont->width,gdLargeFont->height);
973
975 BioPerl
976 The Bio::Graphics package of the BioPerl project makes use of
977 GD::SVG to export SVG graphics.
978 http://www.bioperl.org/
980 Generic Genome Browser
982 The Generic Genome Browser (GBrowse) utilizes Bio::Graphics and
983 enables SVG dumping of genomics views. You can see a real-world
984 example of SVG output from GBrowse at WormBase:
985 http://www.wormbase.org/cgi-bin/gbrowse/
987 Further information about the Generic Genome Browser is available
989 at the Generic Model Organism Project home page:
990 http://www.gmod.org/
992 toddot
994 I've also prepared a number of comparative images at my website
995 (shameless plug, hehe):
996 http://www.toddot.net/projects/GD-SVG/
998
1000 The following internal methods are private and documented only for
1001 those wishing to extend the GD::SVG interface.
1002 _distill_gdSpecial()
1004 When a drawing method is passed a stylized brush via gdBrushed, the
1005 internal _distill_gdSpecial() method attempts to make sense of this
1006 by setting line thickness and foreground color. Since stylized
1007 brushes are GD::SVG::Image objects, it does this by fetching the
1008 width of the image using the getBounds method. This width is then
1009 used to setThickness. The last color set by colorAllocate is then
1010 used for the foreground color.
1011 In setting line thickness, GD::SVG temporarily overrides any
1013 previously set line thickness. In GD, setThickness is persistent
1014 through uses of stylized brushes. To accomodate this behavior,
1015 _distill_gdSpecial() temporarily stores the previous line_thickness
1016 in the $self->{previous_line_thickness} flag.
1017 _reset()
1019 The _reset() method is used to restore persistent drawing settings
1020 between uses of stylized brushes. Currently, this involves
1021 - restoring line thickness
1023
1025 A second module (SVG::GD), written by Ronan Oger also provides similar
1026 functionality as this module. Ronan and I are concurrently developing
1027 these modules with an eye towards integrating them in the future. In
1028 principle, the primary difference is that GD::SVG aims to generate SVG
1029 and SVG only. That is, it:
1030 1. Does not store an internal representation of the GD image
1032 2. Does not enable JPG, PNG, OR SVG output from a single pass
1034 through data
1035 3. Only occasioanally uses inherited methods from GD
1037 Instead GD::SVG depends on the user to choose which output format they
1039 would like in advance, "use"ing the appropriate module for that output.
1040 As described at the start of this document, module selection between GD
1041 and GD::SVG can be made dynamically using eval statements and variables
1042 for the differnet classes that GD and GD::SVG create.
1043 There is a second reason for not maintaining a double representation of
1045 the data in GD and SVG format: SVG documents can quickly become very
1046 large, especially with large datasets. In cases where scripts are
1047 primarily generating png images in a server environment and would only
1048 occasionally need to export SVG, gernerating an SVG image in parallel
1049 would result in an unacceptable performance hit.
1050 Thus GD::SVG aims to be a plugin for existing configurations that
1052 depend on GD but would like to take advantage of SVG output.
1053 SVG::GD, on the other hand, aims to tie in the raster-editing ability
1055 of GD with the power of SVG output. In part, it aims to do this by
1056 inheriting many methods from GD directly and bringing them into the
1057 functional space of GD. This makes SVG::GD easier to set up initially
1058 (simply by adding the "use SVG::GD" below the "use GD" statement of
1059 your script. GD::SVG sacrfices this initial ease-of-setup for more
1060 targeted applications.
1061
1063 Lincoln Stein, my postdoctoral mentor, author of GD.pm, and all around
1064 Perl stud. Ronan Oger, author of SVG.pm conceptualized and implemented
1065 another wrapper around GD at about the exact same time as this module.
1066 He also provided helpful discussions on implementing GD functions into
1067 SVG. Oliver Drechsel and Marc Lohse provided patches to actually make
1068 the stringUP method functional.
1069
1071 Todd Harris, PhD <harris@cshl.org>
1072
1074 Copyright @ 2003-2005 Todd Harris and the Cold Spring Harbor Laboratory
1075 This library is free software; you can redistribute it and/or modify it
1077 under the same terms as Perl itself.
1078
1080 GD, SVG, SVG::Manual, SVG::DOM
1081perl v5.28.0 2009-05-10 SVG(3)