1SVG(3)                User Contributed Perl Documentation               SVG(3)
2
3
4

NAME

6       GD::SVG - Seamlessly enable SVG output from scripts written using GD
7

SYNOPSIS

9           # use GD;
10           use GD::SVG;
11
12           # my $img = GD::Image->new();
13           my $img = GD::SVG::Image->new();
14
15           # $img->png();
16           $img->svg();
17

DESCRIPTION

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

EXPORTS

26       GD::SVG exports the same methods as GD itself, overriding those
27       methods.
28

USAGE

30       In order to generate SVG output from your script using GD::SVG, you
31       will need to first
32
33         # use GD;
34         use GD::SVG;
35
36       After that, each call to the package classes that GD implements should
37       be changed to GD::SVG. Thus:
38
39         GD::Image    becomes  GD::SVG::Image
40         GD::Font     becomes  GD::SVG::Font
41

DYNAMICALLY SELECTING SVG OUTPUT

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
49         my $package = shift;
50         eval "use $package";
51         my $image_pkg = $package . '::Image';
52         my $font_pkg  = $package . '::Font';
53
54         # Creating new images thus becomes
55         my $image   = $image_pkg->new($width,$height);
56
57         # 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
65       Finally, you should change all GD::Image and GD::Font references to
66       $image_pkg-> and $font_pkg->, respectively.
67
68         GD::Image->new()   becomes   $image_pkg->new()
69         GD::Font->Large()  becomes   $font_pkg->Large()
70
71       The GD::Polygon and GD::Polyline classes work with GD::SVG without
72       modification.
73
74       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

IMPORTANT NOTES

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
87       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
94       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

PREREQUISITES

99       GD::SVG requires the Ronan Oger's SVG.pm module, Lincoln Stein's GD.pm
100       module, libgd and its dependencies.
101

GENERAL DIFFICULTIES IN TRANSLATING GD TO SVG

103       These are the primary weaknesses of GD::SVG.
104
105       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
112       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
116           See the documentation above for how to dynamically switch between
117           packages.
118
119       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
123       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
128       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
133       Tiled fills are not supported
134           Any functions passed gdTiled objects will die.
135
136       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
144       See below for a full list of methods that have not yet been
145       implemented.
146

WHEN THINGS GO WRONG

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
153       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
157       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

GD FUNCTIONS MISSING FROM GD::SVG

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
168         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
184         Image methods:
185           $gddata   = $image->gd
186           $gd2data  = $image->gd2
187           $wbmpdata = $image->wbmp([$foreground])
188
189         Color control methods:
190           $image->colorAllocateAlpha()
191           $image->colorClosest()
192           $image->colorClosestHWB()
193           $image->getPixel()
194           $image->transparent()
195
196         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
204         Drawing methods:
205           $image->dashedLine()
206           $image->fill()
207           $image->fillToBorder()
208
209         Image copying methods
210           None of the image copying methods are yet supported
211
212         Image transformation methods
213           None of the image transformation methods are yet supported
214
215         Character and string drawing methods
216            $image->stringUp()  - incompletely supported - broken
217            $image->charUp()
218            $image->stringFT()
219
220         Alpha Channels
221           $image->alphaBlending()
222           $image->saveAlpha()
223
224         Miscellaneous image methods
225           $image->isTrueColor()
226           $image->compare($image2)
227           $image->clip()
228           $image->boundsSafe()
229
230         GD::Polyline
231           Supported without modifications
232
233         Font methods:
234           $font->nchars()
235           $font->offset()
236

GROUPING FUNCTIONS GD::SVG

238       GD::SVG supports three additional methods that provides the ability to
239       recursively group objects:
240
241       $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
247       $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
255           Here is an example of using grouping in the procedural way:
256
257            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
264            $img->startGroup('circle in square');
265            $img->rectangle(100,100,400,400,$blue);
266
267            $img->startGroup('circle and boundary');
268            $img->filledEllipse(250,250,200,200,$red);
269            $img->ellipse(250,250,200,200,$black);
270
271            $img->endGroup;
272            $img->endGroup;
273
274            print $img->svg;
275
276           Here is an example of using grouping with the GD::Group object:
277
278             ...
279
280            my $g1 = $img->newGroup('circle in square');
281            $g1->rectangle(100,100,400,400,$blue);
282
283            my $g2 = $g1->startGroup('circle and boundary');
284            $g2->filledEllipse(250,250,200,200,$red);
285            $g2->ellipse(250,250,200,200,$black);
286
287            print $img->svg;
288
289           Finally, here is a fully worked example of using the GD::Simple
290           module to make the syntax cleaner:
291
292            #!/usr/bin/perl
293
294            use strict;
295            use GD::Simple;
296
297            GD::Simple->class('GD::SVG');
298
299            my $img = GD::Simple->new(500,500);
300            $img->bgcolor('white');
301            $img->fgcolor('blue');
302
303            my $g1 = $img->newGroup('circle in square');
304            $g1->rectangle(100,100,400,400);
305            $g1->moveTo(250,250);
306
307            my $g2 = $g1->newGroup('circle and boundary');
308            $g2->fgcolor('black');
309            $g2->bgcolor('red');
310            $g2->ellipse(200,200);
311
312            print $img->svg;
313

GD VERSUS GD::SVG METHODS

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

OBJECT CONSTRUCTORS: CREATING IMAGES

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
328       $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

GD::SVG::Image METHODS

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
341   Image Data Output Methods
342       GD::SVG implements a single output method, svg()!
343
344       $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
348             $svg_data = $image->svg();
349             open (DISPLAY,"| display -") || die;
350             binmode DISPLAY;
351             print DISPLAY $svg_data;
352             close DISPLAY;
353
354           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
358             $svg_data = $image->svg(-inline=>'true');
359
360           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
364   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
373       $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
380             returns: "rgb(RED,GREEN,BLUE)"
381
382       $index = $image->colorAllocateAlpha()
383           NOT IMPLEMENTED
384
385       $image->colorDeallocate($index)
386           Provided with a color index, remove it from the color table.
387
388       $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
393             Example: $apricot = $myImage->colorClosest(255,200,180);
394
395           NOT IMPLEMENTED
396
397       $index = $image->colorClosestHWB(red,green,blue)
398           NOT IMPLEMENTED
399
400       $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
404           NOT IMPLEMENTED
405
406       $index = $image->colorResolve(red,green,blue)
407           NOT IMPLEMENTED
408
409       $colors_total = $image->colorsTotal()
410           Retrieve the total number of colors indexed in the image.
411
412       $index = $image->getPixel(x,y)
413           NOT IMPLEMENTED
414
415       ($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
420       $image->transparent($colorIndex);
421           Control the transparency of individual colors.
422
423           NOT IMPLEMENTED
424
425   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
431       $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
438           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
444             # 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
451           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
460       $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
465       $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
472       gdTiled
473           NOT IMPLEMENTED
474
475       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
480       $image->setAntiAliased($color)
481           NOT IMPLEMENTED
482
483       gdAntiAliased
484           NOT IMPLEMENTED
485
486       $image->setAntiAliasedDontBlend($color,[$flag])
487           NOT IMPLEMENTED
488
489   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
495       $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
502       $image->dashedLine($x1,$y1,$x2,$y2,$color);
503           NOT IMPLEMENTED
504
505       $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
510       $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
518              GD call:
519                $img->filledRectangle($x1,$y1,$x2,$y2,$color);
520
521              SVG call:
522                $img->rectangle(x=> $x1,y=> $y1,
523                                width  => $x2-$x1,
524                                height => $y2-$y1,
525                                fill   => $color
526
527       $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
536             $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
542       $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
547             # make a polygon
548             $poly = new GD::Polygon;
549             $poly->addPt(50,0);
550             $poly->addPt(99,99);
551             $poly->addPt(0,99);
552
553             # draw the polygon, filling it with a color
554             $image->filledPolygon($poly,$peachpuff);
555
556       $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
561             # make a polygon
562             $poly = new GD::Polygon;
563             $poly->addPt(50,0);
564             $poly->addPt(99,99);
565             $poly->addPt(0,99);
566
567             # draw the polygon, filling it with a color
568             $image->filledPolygon($poly,$peachpuff);
569
570       $image->polyline(polyline,color)
571             $image->polyline($polyline,$black)
572
573           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
577           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
582       $image->polydraw(polything,color)
583                   $image->polydraw($poly,$black)
584
585           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
589       $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
598       $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
608           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
612           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
615       $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
621           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
627           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
635           Using these special styles, you can easily draw bordered ellipses
636           and circles.
637
638           # 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
642       $image->fill();
643           NOT IMPLEMENTED
644
645       $image->fillToBorder()
646           NOT IMPLEMENTED
647
648   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
653       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
659         $image->clone()
660         $image->copyMerge()
661         $image->copyMergeGray()
662         $image->copyResized()
663         $image->copyResampled()
664         $image->trueColorToPalette()
665
666   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
673         $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
684   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
691       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
702       $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
707             $myImage->string(gdSmallFont,2,10,"Peachy Keen",$peach);
708
709       $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
713       $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
721       @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
729             The arguments are as follows:
730
731             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
738           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
742           If successful, the method returns an eight-element list giving the
743           boundaries of the rendered string:
744
745             @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
750           This from the GD documentation (not yet implemented in GD::SVG):
751
752           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
757           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
767           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
771             $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
777           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
782       $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
788           NOT IMPLEMENTED
789
790   Alpha Channels
791       $image->alphaBlending($blending)
792           NOT IMPLEMENTED
793
794       $image->saveAlpha($saveAlpha)
795           NOT IMPLEMENTED
796
797   Miscellaneous Image Methods
798       $image->interlaced([$flag])
799           NOT IMPLEMENTED
800
801       ($width,$height) = $image->getBounds()
802           getBounds() returns the height and width of the image.
803
804       $is_truecolor = $image->isTrueColor()
805           NOT IMPLEMENTED
806
807       $flag = $image1->compare($image2)
808           NOT IMPLEMENTED
809
810       $image->clip($x1,$y1,$x2,$y2) ($x1,$y1,$x2,$y2) = $image->clip
811           NOT IMPLEMENTED
812
813       $flag = $image->boundsSafe($x,$y)
814           NOT IMPLEMENTED
815

GD::SVG::Polygon METHODS

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
821       $poly = GD::SVG::Polygon->new
822           Create an empty polygon with no vertices.
823
824             $poly = new GD::SVG::Polygon;
825
826       $poly->addPt($x,$y)
827           Add point (x,y) to the polygon.
828
829             $poly->addPt(0,0);
830             $poly->addPt(0,50);
831             $poly->addPt(25,25);
832
833       ($x,$y) = $poly->getPt($index)
834           Retrieve the point at the specified vertex.
835
836             ($x,$y) = $poly->getPt(2);
837
838       $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
842             $poly->setPt(2,100,100);
843
844       ($x,$y) = $poly->deletePt($index)
845           Delete the specified vertex, returning its value.
846
847             ($x,$y) = $poly->deletePt(1);
848
849       $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
853             $poly->addPt(0,0);
854             $poly->toPt(0,50);
855             $poly->toPt(25,-25);
856
857           NOT IMPLEMENTED
858
859       $vertex_count = $poly->length()
860           Return the number of vertices in the polygon.
861
862       @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
866             @vertices = $poly->vertices;
867             foreach $v (@vertices)
868                 print join(",",@$v),"\n";
869             }
870
871       @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
876             ($left,$top,$right,$bottom) = $poly->bounds;
877
878       $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
883             $poly->offset(10,30);
884
885       $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
893             # Make the polygon really tall
894             $poly->map($poly->bounds,0,0,50,200);
895
896           NOT IMPLEMENTED
897
898       $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
905           NOT IMPLEMENTED
906
907       $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
914           NOT IMPLEMENTED
915
916   GD::Polyline
917       Please see GD::Polyline for information on creating open polygons and
918       splines.
919

GD::SVG::Font METHODS

921       NOTE: The object-oriented implementation to font utilites is not yet
922       supported.
923
924       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
929       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
934       gdTinyFont
935       GD::Font->Tiny
936           This is a tiny, almost unreadable font, 5x8 pixels wide.
937
938       gdSmallFont
939       GD::Font->Small
940           This is the basic small font, "borrowed" from a well known public
941           domain 6x12 font.
942
943       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
948       gdLargeFont
949       GD::Font->Large
950           This is the basic large font, "borrowed" from a well known public
951           domain 8x16 font.
952
953       gdGiantFont
954       GD::Font->Giant
955           This is a 9x15 bold font converted by Jan Pazdziora from a sans
956           serif X11 font.
957
958       $font->nchars
959           This returns the number of characters in the font.
960
961             print "The large font contains ",gdLargeFont->nchars," characters\n";
962
963           NOT IMPLEMENTED
964
965       $font->offset()
966           This returns the ASCII value of the first character in the font
967
968       $width = $font->width
969       $height = $font->height
970           These return the width and height of the font.
971
972             ($w,$h) = (gdLargeFont->width,gdLargeFont->height);
973

REAL WORLD EXAMPLES

975       BioPerl
976           The Bio::Graphics package of the BioPerl project makes use of
977           GD::SVG to export SVG graphics.
978
979             http://www.bioperl.org/
980
981       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
986             http://www.wormbase.org/cgi-bin/gbrowse/
987
988           Further information about the Generic Genome Browser is available
989           at the Generic Model Organism Project home page:
990
991             http://www.gmod.org/
992
993       toddot
994           I've also prepared a number of comparative images at my website
995           (shameless plug, hehe):
996
997             http://www.toddot.net/projects/GD-SVG/
998

INTERNAL METHODS

1000       The following internal methods are private and documented only for
1001       those wishing to extend the GD::SVG interface.
1002
1003       _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
1012           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
1018       _reset()
1019           The _reset() method is used to restore persistent drawing settings
1020           between uses of stylized brushes. Currently, this involves
1021
1022             - restoring line thickness
1023

IMPORTANT NOTE! GD::SVG / SVG::GD

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
1031         1. Does not store an internal representation of the GD image
1032
1033         2. Does not enable JPG, PNG, OR SVG output from a single pass
1034            through data
1035
1036         3. Only occasioanally uses inherited methods from GD
1037
1038       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
1044       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
1051       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
1054       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

ACKNOWLEDGEMENTS

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

AUTHOR

1071       Todd Harris, PhD <harris@cshl.org>
1072
1074       Copyright @ 2003-2005 Todd Harris and the Cold Spring Harbor Laboratory
1075
1076       This library is free software; you can redistribute it and/or modify it
1077       under the same terms as Perl itself.
1078

SEE ALSO

1080       GD, SVG, SVG::Manual, SVG::DOM
1081
1082
1083
1084perl v5.36.0                      2022-07-22                            SVG(3)
Impressum