NAME

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

SYNOPSIS

    # use GD;
    use GD::SVG;
    # my $img = GD::Image->new();
    my $img = GD::SVG::Image->new();
    # $img->png();
    $img->svg();

DESCRIPTION

GD::SVG painlessly enables scripts that utilize GD to export scalable vector graphics (SVG). It accomplishes this task by wrapping SVG.pm with GD-styled method calls. To enable this functionality, one need only change the "use GD" call to "use GD::SVG" (and initial "new" method calls).

EXPORTS

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

USAGE

In order to generate SVG output from your script using GD::SVG, you will need to first

  # use GD;
  use GD::SVG;

After that, each call to the package classes that GD implements should be changed to GD::SVG. Thus:

  GD::Image    becomes  GD::SVG::Image
  GD::Font     becomes  GD::SVG::Font

DYNAMICALLY SELECTING SVG OUTPUT

If you would like your script to be able to dynamically select either PNG or JPEG output (via GD) or SVG output (via GD::SVG), you should place your "use" statement within an eval. In the example below, each of the available classes is created at the top of the script for convenience, as well as the image output type.

  my $package = shift;
  eval "use $package";
  my $image_pkg = $package . '::Image';
  my $font_pkg  = $package . '::Font';
  # Creating new images thus becomes
  my $image   = $image_pkg->new($width,$height);
  # Establish the image output type
  my $image_type;
  if ($package = 'GD::SVG') {
    $image_type = 'svg';
  } else {
    $image_type = 'png';
  }

Finally, you should change all GD::Image and GD::Font references to $image_pkg-> and $font_pkg->, respectively.

  GD::Image->new()   becomes   $image_pkg->new()
  GD::Font->Large()  becomes   $font_pkg->Large()

The GD::Polygon and GD::Polyline classes work with GD::SVG without modification.

If you make heavy use of GD's exported methods, it may also be necessary to add () to the endo of method names to avoide bareword compilation errors. That's the price you pay for using exported functions!

IMPORTANT NOTES

GD::SVG does not directly generate SVG, but instead relies upon SVG.pm. It is not intended to supplant SVG.pm. Furthermore, since GD::SVG is, in essence an API to an API, it may not be suitable for applications where speed is of the essence. In these cases, GD::SVG may provide a short-term solution while scripts are re-written to enable more direct output of SVG.

Many of the GD::SVG methods accept additional parameters (which are in turn reflected in the SVG.pm API) that are not supported in GD. Look through the remainder of this document for options on specific In addition, several functions have yet to be mapped to SVG.pm calls. Please see the section below regarding regarding GD functions that are missing or altered in GD::SVG.

A similar module (SVG::GD) implements a similar wrapper around GD. Please see the section at the bottom of this document that compares GD::SVG to SVG::GD.

PREREQUISITES

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

GENERAL DIFFICULTIES IN TRANSLATING GD TO SVG

These are the primary weaknesses of GD::SVG.

SVG requires unique identifiers for each element

Each element in an SVG image requires a unique identifier. In general, GD::SVG handles this by automatically generating unique random numbers. In addition to the typical parameters for GD methods, GD::SVG methods allow a user to pass an optional id parameter for naming the object.

Direct calls to the GD package will fail

You must change direct calls to the classes that GD invokes:
GD::Image->new() should be changed to GD::SVG::Image->new()

See the documentation above for how to dynamically switch between packages.

raster fill() and fillToBorder() not supported

As SVG documents are not inherently aware of their canvas, the flood fill methods are not currently supported.

getPixel() not supported.

Although setPixel() works as expected, its counterpart getPixel() is not supported. I plan to support this method in a future release.

No support for generation of images from filehandles or raw data

GD::SVG works only with scripts that generate images directly in the code using the GD->new(height,width) approach. newFrom() methods are not currently supported.

Tiled fills are not supported

Any functions passed gdTiled objects will die.

Styled and Brushed lines only partially implemented

Calls to the gdStyled and gdBrushed functions via a rather humorous kludge (and simplification). Depending on the complexity of the brush, they may behave from slightly differently to radically differently from their behavior under GD. You have been warned. See the documentation sections for the methods that set these options (setStyle(), setBrush(), and setTransparent()).

See below for a full list of methods that have not yet been implemented.

WHEN THINGS GO WRONG

GD is a complicated module. Translating GD methods into those required to draw in SVG are not always direct. You may or may not get the output you expect. In general, some tweaking of image parameters (like text height and width) may be necessary.

If your script doesn't work as expected, first check the list of methods that GD::SVG provides. Due to differences in the nature of SVG images, not all GD methods have been implemented in GD::SVG.

If your image doesn't look as expected, try tweaking specific aspects of image generation. In particular, check for instances where you calculate dimensions of items on the fly like font->height. In SVG, the values of fonts are defined explicitly.

GD FUNCTIONS MISSING FROM GD::SVG

The following GD functions have not yet been incorporated into GD::SVG. If you attempt to use one of these functions (and you have enabled debug warnings via the new() method), GD::SVG will print a warning to STDERR.

  Creating image objects:
    GD::Image->newPalette([$width,$height])
    GD::Image->newTrueColor([$width,$height])
    GD::Image->newFromPng($file, [$truecolor])
    GD::Image->newFromPngData($data, [$truecolor])
    GD::Image->newFromJpeg($file, [$truecolor])
    GD::Image->newFromJpegData($data, [$truecolor])
    GD::Image->newFromXbm($file)
    GD::Image->newFromWMP($file)
    GD::Image->newFromGd($file)
    GD::Image->newFromGdData($data)
    GD::Image->newFromGd2($file)
    GD::Image->newFromGd2Data($data)
    GD::Image->newFromGd2Part($file,srcX,srcY,width,height)
    GD::Image->newFromXpm($filename)
  Image methods:
    $gddata   = $image->gd
    $gd2data  = $image->gd2
    $wbmpdata = $image->wbmp([$foreground])
  Color control methods:
    $image->colorAllocateAlpha()
    $image->colorClosest()
    $image->colorClosestHWB()
    $image->getPixel()
    $image->transparent()
  Special Colors:
    $image->setBrush() (semi-supported, with kludge)
    $image->setStyle() (semi-supported, with kludge)
    gdTiled
    $image->setAntialiased()
    gdAntiAliased()
    $image->setAntiAliasedDontBlend()
  Drawing methods:
    $image->dashedLine()
    $image->fill()
    $image->fillToBorder()
  Image copying methods
    None of the image copying methods are yet supported
  Image transformation methods
    None of the image transformation methods are yet supported
  Character and string drawing methods
     $image->stringUp()  - incompletely supported - broken
     $image->charUp()
     $image->stringFT()
  Alpha Channels
    $image->alphaBlending()
    $image->saveAlpha()
  Miscellaneous image methods
    $image->isTrueColor()
    $image->compare($image2)
    $image->clip()
    $image->boundsSafe()
  GD::Polyline
    Supported without modifications
  Font methods:
    $font->nchars()
    $font->offset()

GROUPING FUNCTIONS GD::SVG

GD::SVG supports three additional methods that provides the ability to recursively group objects:

$this->startGroup([$id,\%style]), $this->endGroup()

These methods start and end a group in a procedural manner. Once a group is started, all further drawing will be appended to the group until endGroup() is invoked. You may optionally pass a string ID and an SVG styles hash to startGroup.

$group = $this->newGroup([$id,\%style])

This method returns a GD::Group object, which has all the behaviors of a GD::SVG object except that it draws within the current group. You can invoke this object's drawing methods to draw into a group. The group is closed once the object goes out of scope. While the object is open, invoking drawing methods on the parent GD::SVG object will also draw into the group until it goes out of scope.

Here is an example of using grouping in the procedural way:

 use GD::SVG;
 my $img   = GD::SVG::Image->new(500,500);
 my $white = $img->colorAllocate(255,255,255);
 my $black = $img->colorAllocate(0,0,0);
 my $blue  = $img->colorAllocate(0,0,255);
 my $red   = $img->colorAllocate(255,0,0);
 $img->startGroup('circle in square');
 $img->rectangle(100,100,400,400,$blue);
 $img->startGroup('circle and boundary');
 $img->filledEllipse(250,250,200,200,$red);
 $img->ellipse(250,250,200,200,$black);
 $img->endGroup;
 $img->endGroup;
 
 print $img->svg;
    

Here is an example of using grouping with the GD::Group object:

  ...
 my $g1 = $img->newGroup('circle in square');
 $g1->rectangle(100,100,400,400,$blue);
 my $g2 = $g1->startGroup('circle and boundary');
 $g2->filledEllipse(250,250,200,200,$red);
 $g2->ellipse(250,250,200,200,$black);
 print $img->svg;
    

Finally, here is a fully worked example of using the GD::Simple module to make the syntax cleaner:

 #!/usr/bin/perl
    
 use strict;
 use GD::Simple;
 GD::Simple->class('GD::SVG');
 my $img = GD::Simple->new(500,500);
 $img->bgcolor('white');
 $img->fgcolor('blue');
 my $g1 = $img->newGroup('circle in square');
 $g1->rectangle(100,100,400,400);
 $g1->moveTo(250,250);
 my $g2 = $g1->newGroup('circle and boundary');
 $g2->fgcolor('black');
 $g2->bgcolor('red');
 $g2->ellipse(200,200);
 print $img->svg;
    

GD VERSUS GD::SVG METHODS

All GD::SVG methods mimic the naming and interface of GD methods. As such, maintenance of GD::SVG follows the development of both GD and SVG. Much of the original GD documentation is replicated here for ease of use. Subtle differences in the implementation of these methods between GD and GD::SVG are discussed below. In particular, the return value for some GD::SVG methods differs from its GD counterpart.

OBJECT CONSTRUCTORS: CREATING IMAGES

GD::SVG currently only supports the creation of image objects via its new constructor. This is in contrast to GD proper which supports the creation of images from previous images, filehandles, filenames, and data.

$image = GD::SVG::Image->new($height,$width,$debug);

Create a blank GD::SVG image object of the specified dimensions in pixels. In turn, this method will create a new SVG object and store it internally. You can turn on debugging with the GD::SVG specific $debug parameter. This should be boolean true and will cause non-implemented methods to print a warning on their status to STDERR.

GD::SVG::Image METHODS

Once a GD::Image object is created, you can draw with it, copy it, and merge two images. When you are finished manipulating the object, you can convert it into a standard image file format to output or save to a file.

  $image->clone()
  $image->copyMerge()
  $image->copyMergeGray()
  $image->copyResized()
  $image->copyResampled()
  $image->trueColorToPalette()

  $image = $sourceImage->copyRotate90()
  $image = $sourceImage->copyRotate180()
  $image = $sourceImage->copyRotate270()
  $image = $sourceImage->copyFlipHorizontal()
  $image = $sourceImage->copyFlipVertical()
  $image = $sourceImage->copyTranspose()
  $image = $sourceImage->copyReverseTranspose()
  $image->rotate180()
  $image->flipHorizontal()
  $image->flipVertical()

GD::SVG::Polygon METHODS

SVG is much more adept at creating polygons than GD. That said, GD does provide some rudimentary support for polygons but must be created as seperate objects point by point.

$poly = GD::SVG::Polygon->new

Create an empty polygon with no vertices.

  $poly = new GD::SVG::Polygon;
    

$poly->addPt($x,$y)

Add point (x,y) to the polygon.

  $poly->addPt(0,0);
  $poly->addPt(0,50);
  $poly->addPt(25,25);
    

($x,$y) = $poly->getPt($index)

Retrieve the point at the specified vertex.

  ($x,$y) = $poly->getPt(2);
    

$poly->setPt($index,$x,$y)

Change the value of an already existing vertex. It is an error to set a vertex that isn't already defined.

  $poly->setPt(2,100,100);
    

($x,$y) = $poly->deletePt($index)

Delete the specified vertex, returning its value.

  ($x,$y) = $poly->deletePt(1);
    

$poly->toPt($dx,$dy)

Draw from current vertex to a new vertex, using relative (dx,dy) coordinates. If this is the first point, act like addPt().

  $poly->addPt(0,0);
  $poly->toPt(0,50);
  $poly->toPt(25,-25);
    

NOT IMPLEMENTED

$vertex_count = $poly->length()

Return the number of vertices in the polygon.

@vertices = $poly->vertices()

Return a list of all the verticies in the polygon object. Each mem- ber of the list is a reference to an (x,y) array.

  @vertices = $poly->vertices;
  foreach $v (@vertices)
      print join(",",@$v),"\n";
  }
    

@rect = $poly->bounds()

Return the smallest rectangle that completely encloses the polygon. The return value is an array containing the (left,top,right,bottom) of the rectangle.

  ($left,$top,$right,$bottom) = $poly->bounds;
    

$poly->offset($dx,$dy)

Offset all the vertices of the polygon by the specified horizontal (dh) and vertical (dy) amounts. Positive numbers move the polygon down and to the right. Returns the number of vertices affected.

  $poly->offset(10,30);
    

$poly->map($srcL,$srcT,$srcR,$srcB,$destL,$dstT,$dstR,$dstB)

Map the polygon from a source rectangle to an equivalent position in a destination rectangle, moving it and resizing it as necessary. See polys.pl for an example of how this works. Both the source and destination rectangles are given in (left,top,right,bottom) coordi- nates. For convenience, you can use the polygon's own bounding box as the source rectangle.

  # Make the polygon really tall
  $poly->map($poly->bounds,0,0,50,200);
    

NOT IMPLEMENTED

$poly->scale($sx,$sy)

Scale each vertex of the polygon by the X and Y factors indicated by sx and sy. For example scale(2,2) will make the polygon twice as large. For best results, move the center of the polygon to position (0,0) before you scale, then move it back to its previous position.

NOT IMPLEMENTED

$poly->transform($sx,$rx,$sy,$ry,$tx,$ty)

Run each vertex of the polygon through a transformation matrix, where sx and sy are the X and Y scaling factors, rx and ry are the X and Y rotation factors, and tx and ty are X and Y offsets. See the Adobe PostScript Reference, page 154 for a full explanation, or experiment.

NOT IMPLEMENTED

GD::SVG::Font METHODS

NOTE: The object-oriented implementation to font utilites is not yet supported.

The libgd library (used by the Perl GD library) has built-in support for about half a dozen fonts, which were converted from public-domain X Windows fonts. For more fonts, compile libgd with TrueType support and use the stringFT() call.

GD::SVG replicates the internal fonts of GD by hardcoding fonts which resemble the design and point size of the original. Each of these fonts is available both as an imported global (e.g. gdSmallFont) and as a package method (e.g. GD::Font->Small).

gdTinyFont

GD::Font->Tiny

This is a tiny, almost unreadable font, 5x8 pixels wide.

gdSmallFont

GD::Font->Small

This is the basic small font, "borrowed" from a well known public domain 6x12 font.

gdMediumBoldFont

GD::Font->MediumBold

This is a bold font intermediate in size between the small and large fonts, borrowed from a public domain 7x13 font;

gdLargeFont

GD::Font->Large

This is the basic large font, "borrowed" from a well known public domain 8x16 font.

gdGiantFont

GD::Font->Giant

This is a 9x15 bold font converted by Jan Pazdziora from a sans serif X11 font.

$font->nchars

This returns the number of characters in the font.

  print "The large font contains ",gdLargeFont->nchars," characters\n";
    

NOT IMPLEMENTED

$font->offset()

This returns the ASCII value of the first character in the font

$width = $font->width

$height = $font->height

These return the width and height of the font.

  ($w,$h) = (gdLargeFont->width,gdLargeFont->height);
    

REAL WORLD EXAMPLES

BioPerl

The Bio::Graphics package of the BioPerl project makes use of GD::SVG to export SVG graphics.

  http://www.bioperl.org/
    

Generic Genome Browser

The Generic Genome Browser (GBrowse) utilizes Bio::Graphics and enables SVG dumping of genomics views. You can see a real-world example of SVG output from GBrowse at WormBase:

  http://www.wormbase.org/cgi-bin/gbrowse/
    

Further information about the Generic Genome Browser is available at the Generic Model Organism Project home page:

  http://www.gmod.org/
    

toddot

I've also prepared a number of comparative images at my website (shameless plug, hehe):

  http://www.toddot.net/projects/GD-SVG/
    

INTERNAL METHODS

The following internal methods are private and documented only for those wishing to extend the GD::SVG interface.

_distill_gdSpecial()

When a drawing method is passed a stylized brush via gdBrushed, the internal _distill_gdSpecial() method attempts to make sense of this by setting line thickness and foreground color. Since stylized brushes are GD::SVG::Image objects, it does this by fetching the width of the image using the getBounds method. This width is then used to setThickness. The last color set by colorAllocate is then used for the foreground color.

In setting line thickness, GD::SVG temporarily overrides any previously set line thickness. In GD, setThickness is persistent through uses of stylized brushes. To accomodate this behavior, _distill_gdSpecial() temporarily stores the previous line_thickness in the $self->{previous_line_thickness} flag.

_reset()

The _reset() method is used to restore persistent drawing settings between uses of stylized brushes. Currently, this involves

  - restoring line thickness
    

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

A second module (SVG::GD), written by Ronan Oger also provides similar functionality as this module. Ronan and I are concurrently developing these modules with an eye towards integrating them in the future. In principle, the primary difference is that GD::SVG aims to generate SVG and SVG only. That is, it:

  1. Does not store an internal representation of the GD image
  2. Does not enable JPG, PNG, OR SVG output from a single pass
     through data
  3. Only occasioanally uses inherited methods from GD

Instead GD::SVG depends on the user to choose which output format they would like in advance, "use"ing the appropriate module for that output. As described at the start of this document, module selection between GD and GD::SVG can be made dynamically using eval statements and variables for the differnet classes that GD and GD::SVG create.

There is a second reason for not maintaining a double representation of the data in GD and SVG format: SVG documents can quickly become very large, especially with large datasets. In cases where scripts are primarily generating png images in a server environment and would only occasionally need to export SVG, gernerating an SVG image in parallel would result in an unacceptable performance hit.

Thus GD::SVG aims to be a plugin for existing configurations that depend on GD but would like to take advantage of SVG output.

SVG::GD, on the other hand, aims to tie in the raster-editing ability of GD with the power of SVG output. In part, it aims to do this by inheriting many methods from GD directly and bringing them into the functional space of GD. This makes SVG::GD easier to set up initially (simply by adding the "use SVG::GD" below the "use GD" statement of your script. GD::SVG sacrfices this initial ease-of-setup for more targeted applications.

ACKNOWLEDGEMENTS

Lincoln Stein, my postdoctoral mentor, author of GD.pm, and all around Perl stud. Ronan Oger, author of SVG.pm conceptualized and implemented another wrapper around GD at about the exact same time as this module. He also provided helpful discussions on implementing GD functions into SVG. Oliver Drechsel and Marc Lohse provided patches to actually make the stringUP method functional.

AUTHOR

Todd Harris, PhD <harris@cshl.org>

COPYRIGHT AND LICENSE

Copyright @ 2003-2005 Todd Harris and the Cold Spring Harbor Laboratory

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

SEE ALSO

GD, SVG, SVG::Manual, SVG::DOM