SVG::Template::Graph - Perl extension for generating template-driven graphs with SVG
use SVG::Template::Graph; $data = [ { barGraph=>1,#<barGraph|[lineGraph]> barSpace=>20, 'title'=> '1: Trace 1', 'data' => #hash ref containing x-val and y-val array refs { 'x_val' => [50,100,150,200,250, 300,350,400,450,500,550], 'y_val' => [100,150,100,126,100, 175,100,150,120,125,100], }, 'format' => { #note that these values could change for *each* trace 'lineGraph' => 1, 'x_min' => 0, 'x_max' => 600, 'y_min' => 50, 'y_max' => 200, 'x_axis' => 1, #draw x-axis 'y_axis' => 1, #draw y-axis #define the labels that provide the data context. 'labels' => { #for year labels, we have to center the axis markers 'x_ticks' => { 'label' =>[2002,2003,2004], 'position'=>[100,300,500], }, 'y_ticks' => { #tick mark labels 'label' => [ -250, 0, 250, 500], #tick mark location in the data space 'position' => [50, 100, 150, 200], }, }, }, }, ]; #construct a new SVG::Template::Graph object with a file handle my $tt = SVG::Template::Graph->new($file); #set up the titles for the graph $tt->setGraphTitle(['Hello svg graphing world','I am a subtitle']); #generate the traces. $tt->drawTraces($data,$anchor_rectangle_id); #serialize and print print $tt->burn();
Template::Graph:SVG is a module for the generation of template-driven graphs using Scalable Vector Graphics (SVG). Using this module, it is possible to define a template SVG document with containers which are populated with correctly scaled plot images.
None by default.
Refer to the examples directory inside this distribution for working examples.
#construct a new SVG::Template::Graph object with a file handle my $tt = SVG::Template::Graph->new($file);
The constructor for the class. Takes a template file name as an argument
serialise the image. See SVG::xmlify for more details
my $svg_element_ref = $tt->setGraphTitle ($string|\@strings, %attributes)
Generate the text for the Graph Title Returns the reference to the text element
set the title of a trace
$tt->setTraceTitle( $string|\@strings, %attributes )
Generate the text for the Graph X-Axis Titles Returns the reference to the text element
$tt->setXAxisTitle($axis_number, $string, %attributes) $tt->setXAxisTitle($axis_number, \@strings, %attributes)
Generate the text for the Graph Y-Axis Titles Returns the reference to the text element
$tt->setYAxisTitle($axis_number, $string,%attributes) $tt->setYAxisTitle($axis_number, \@strings,%attributes)
Check that a group exists (is a valid, defined group in the SVG DOM) and create a group in the document if id does not exist. Return the group element This ensures that even if a designer failed to generate a group ID in the drawing, you will get a drawing with the right group names. If type is defined, an element of $type with %attributes is defined.
my $svg_element = $tt->_gg ($id) my $svg_element = $tt->_gg ($id,'rect',width=>10,height=>10, x=>10,y=>10,fill=>'none',stroke=>'red')
Internal method called by setGraphTitle and setAxisTitle to do the actual work. Not really intended to be accessed from the outside but available for advanced users.
$tt->_setAxisText ($id,$text|\@text,%attributes)
the input structure required by sub drawTraces to generate the graph. Refer to the examples included in this distribution in the examples directory for working samples.
$struct = [{ 'tracetype' => 'linegraph', 'title'=> '1: Trace 1', 'data' => #hash ref containing x-val and y-val array refs { 'x_val' => [0, 2, 4, 6, 8, 10, 12,14,16, 18,20], 'y_val' => [4, 2, 5, 3, 7, 4 , 9, 9, 2, 4, 3], }, 'format' => { 'x_max' => 600, #or for your case, the date value of the 1st point 'x_min' => 0, #or for your case, the date value of the last point 'y_max' => 0.35, 'y_min' => -0.1, 'x_title' => 'Calendar Year', 'y_title' => '% Annual Performance', 'x_axis' => 0, # do not automatically draw an x-axis 'y_axis' => 1, #automatically draw a y-axis #define the labels that provide #the data context. 'labels' => { #for year labels, we have to center the axis markers 'x_ticks' => { 'label' =>[2002,2003,2004], 'position' =>[100,300,500], }, y_ticks => { #tick mark label 'label' => [ '-10.00%', '-5.00%', '0.00%', '5.00%', '10.00%', '15.00%', '20.00%', '25.00%', '30.00%', '35.00%' ], #tick mark location in the data space 'position' => [-0.10,-0.5,0, -.5,.10,.15, .20,.25,.30, .35], }, }, }, legend_title => 'Some Interesting Data', }, ];
if $id_anchor_data is an array reference, then it uses it to describe the extents of the viewbox into which the current drawing will happen. If $id_anchor_data is a string then its associated xml element is assumed to be a rectangle and getCanvasBoxBoundaries uses the rectangle geometry.to define the plot bounding box. hash references are not supported.
Action: set the boundary box data in the object and returns the array reference:
[xmin, ymin, xmax, ymax]
returns the value of the boundary box of the data set which places the graph in the image as an array reference:
draw one or both of axes (zero-value line) of the drawing data space. Draws both axes unless one of the axes is passed as a string.
drawAxis('somegroupid','x') draws the x-axis line into group 'somegroupid'. drawAxis('somegroupid','y') draws the y-axis line indo group 'somegroupid' drawAxis('somegroupid') draws both x- and y- axis lines into group 'somegroupid'
construction detail: draws the content into a group.
given a structure describing the incoming drawing parameters, generates the SVG lines, axes, and ticks and returns the number of traces that were handled. If $anchor_id is defined and is a rectangle ID, then the drawing will take place in id.if $anchor_point is defined and it is an array of 4 real numbers, then this will be taken to be the location where the insertion box goes.
The format for the array is: [x0 y0 x1 y1]. in canvas dimension
scales the points for lines appropriately and generates the correct polyline or path or polygon element, scaled and inverted to match paper space.
if $anchor_data is defined, then it is either the id of a rectangle whose geometry will contain the results, or it is an array reference which contains the viewbox defilition [x0,y0,x1,y1] where the graph is to be placed.
this is the method in which the generation of the graph is handled
returns the reference of the polyline/path/polygon tag that was generated.
draw a line graph trace
$g->barGraph( $index, [\@x,\@y], \@canvas, $barSpace, %styling_attributes)
draw a bar graph trace
$p->drawGridLines ($target_svg_element_ref,$transformation_ref,$format_structure_ref)
draw the gridlines for a graph as defined in the formatting data structure for each trace.
$p->handleFurnishings( $orientation, $format, \%anchor_refs);
single point for handling grid lines, gridline lables, and gridline tickmarks this method is a factory method for generating vertical or horizontal furnishings for the trace the anchor hash reference contains the following keys:
line label tick
parameters
gridline orientation
$orientation = 'x' or 'y'
Gridline context-format hash reference
$format - hash reference
defines what is shown and what is not.
whose values are svg element object references where the respective entities are to be appended as children.
draw a single grid line
$p->drawTick( ['x'|'y'], $index, $tick, $args, %attrs);
tickmark-generation handler
grid lable generator
return the front and back extensions to lines based on the definition (or lack of) tickmarks in the label construct
Example of a label definition:
$label = { 'y_ticks' => { 'style' => { 'right' => '10' }, 'position' => [ '150', '100', '0', '-75' ], 'label' => [ 'Much', 'Some', 'None', 'Lost' ] }, 'x_ticks' => {} };
$self->D()
returns the SVG Document object
$self->T($name)
returns the currently invoked transformation object. Returns transformation object $name if requested by name
define the graph target (currently only rectangles are accepted) on top of which the data will be drawn
returns the current graph target
generates a reference to an array of $count+1 evenly distributed values ranging between $min and $max
$tt->autoGrid(0,100,10);
format an array of values according to formatting rules
$tt->Format \@array,$format,$format_attribute[,@more_format_attributes] $format can be 'time' or 'printf'
for 'time', uses the Time::localtime
example 1: formatting to print the verbose date
$a = [ '0', '2.75', '5.5', '8.25', '11' ]; my $b = $tt->Format($a,'time',"%a %b %e %H:%M:%S %Y");
returns
$b = [ 'Thu Jan 1 01:00:00 1970', 'Thu Jan 1 01:00:02 1970', 'Thu Jan 1 01:00:05 1970', 'Thu Jan 1 01:00:08 1970', 'Thu Jan 1 01:00:11 1970' ];
Format uses POSIX function b<strftime> Refer to POSIX for more information on time formating.
example 2: formatting to print to three decimal places using sprintf
$tt->Format([1.123,2.1234,3.12345,4.123456],'sprintf','%.3f');
example 3: formatting to print a percent sign
$tt->Format([1.123,2.1234,3.12345,4.123456],'sprintf','%%');
assign the definitions between the internal keys and the ids in the template at hand. This method need not be called as all IDs automatically get run through if the default IDs specified below are used.
To draw a graph, a template is required which contains two key datasets: a rectangle which will contain the inserted graph data and a group containing child group elements with the IDs expected by SVG::Template::Graph
The svg snippet below provides the required groups for the generation of the first trace (trace intex 0)
Because SVG uses the Painter's model, the image rendering order follows the XML document order. For the snippet below, the rendering order is the following:
data,grid,ticks, axes:x,y, axes values: x,y, axes text: x,y, axes titles: x,y
Trace generation snippet
<!-- trace insertion takes place here --> <g id="group.trace.1" fill="none" stroke="black" stroke-width="2"> <!-- draw the data below the gridlines --> <g id="group.trace.data.1" stroke="#333333" stroke-width="0.5" fill="#411DA4"/> <g id="group.trace.grid.1" stroke="gray" stroke-width="1"/> <g id="group.trace.tick.1" stroke="black" stroke-width="1.5"/> <g id="group.trace.axes.1" stroke="none" fill="black"> <g id="group.trace.axes.x.1" stroke="gray" fill="none" stroke-width="1"/> <g id="group.trace.axes.y.1" stroke="gray" fill="none" stroke-width="1"/> <g id="group.trace.axes.values.x.1" text-anchor="middle" stroke="none" fill="black" transform="translate(0,265)"/> <g id="group.trace.axes.values.y.1" stroke="none" fill="black" text-anchor="start" transform="translate(-40,0)"/> <g id="group.trace.axes.title.x.1" text-anchor="middle" transform="translate(365,370)" font-size="12" fill="#411DA4" font-weight="Bold"/> <g id="group.trace.axes.title.y.1.c" text-anchor="end" transform="translate(40,200)"> <g id="group.trace.axes.title.y.1" transform="rotate(-90)" font-weight="Bold" font-size="12" fill="#411DA4"/> </g> </g> </g> <!-- end of trace insertion 1 -->
In order to show the trace in front of the gridlines, the above snippet changes to:
<!-- trace insertion takes place here --> <g id="group.trace.1" fill="none" stroke="black" stroke-width="2"> <g id="group.trace.grid.1" stroke="gray" stroke-width="1"/> <g id="group.trace.tick.1" stroke="black" stroke-width="1.5"/> <g id="group.trace.axes.1" stroke="none" fill="black"> <g id="group.trace.axes.x.1" stroke="gray" fill="none" stroke-width="1"/> <g id="group.trace.axes.y.1" stroke="gray" fill="none" stroke-width="1"/> <g id="group.trace.axes.values.x.1" text-anchor="middle" stroke="none" fill="black" transform="translate(0,265)"/> <g id="group.trace.axes.values.y.1" stroke="none" fill="black" text-anchor="start" transform="translate(-40,0)"/> <g id="group.trace.axes.title.x.1" text-anchor="middle" transform="translate(365,370)" font-size="12" fill="#411DA4" font-weight="Bold"/> <g id="group.trace.axes.title.y.1.c" text-anchor="end" transform="translate(40,200)"> <g id="group.trace.axes.title.y.1" transform="rotate(-90)" font-weight="Bold" font-size="12" fill="#411DA4"/> </g> </g> <!-- draw the data on top of the gridlines --> <g id="group.trace.data.1" stroke="#333333" stroke-width="0.5" fill="#411DA4"/> </g> <!-- end of trace insertion 1 -->
SVG::Parser SVG::Manual Expat SAX SVG::TT:Graph Tramsform::Canvas http://www.roitsystems.com http://www.roitsystems.com
Ronan Oger, <ronan.oger@roitsystems.com<gt> http://www.roitsystems.com http://www.roitsystems.com
This library was developed and written by Ronan Oger, ROIT Systems Gmbh, under contract to Digital Craftsmen.
Copyright (C) 2004 by Ronan Oger, ROIT Systems GmbH, Zurich, Switzerland
Copyright (C) 2004 by Digital Craftsmen Ltd, London, UK
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.3 or, at your option, any later version of Perl 5 you may have available.
To install SVG::Template::Graph, copy and paste the appropriate command in to your terminal.
cpanm
cpanm SVG::Template::Graph
CPAN shell
perl -MCPAN -e shell install SVG::Template::Graph
For more information on module installation, please visit the detailed CPAN module installation guide.