0. Introduction

This project is focused on using STL containers in order to graph data on a one-dimensional and two-dimensional (and if time allows, 3D!) plot. The plot would be written in an svg image, compliant with the W3C standard. The goals of the project are as follows:

• To provide an easy syntax for graphing data
• To let users produce a simple plot with minimal intervention by using sane defaults
• To demonstrate how to incorporate SVG images into Boost documentation
• To allow users to easily customize graphs to their heart's content
• To allow the user to talk with the svg_graph class using coordinate units instead of pixels or other arbitrary measures

I have only a student's grasp of C++, so if you have a suggestion to help me with design or implementation, either leave them here or email me at jakevoytko [at] gmail [dot] com

1. User Interface

Example

vector<double> experiment_data;

// fill experiment_data here

svg_plot my_plot("./image.svg");

my_plot<< image_size(500, 500) << x_scale(0, 10) << y_scale(0, 10)
        << line_color(BLACK) << draw_axis();

my_plot<< plot_range(experiment_data.begin(), experiment_data.end()) << write();

Output

---

2. Design Decisions

2.1 svg_graph class

Currently supported operations of the form my_plot << function():

• x_scale(double, double) and y_scale(double, double)
  • Allows the user to set the bottom, top, left, and right edge of the graph

• image_size(int, int)
  • This sizes the border of the image. The default right now is up in the air. 100x100 is perhaps unreasonably small for someone with a 1280x1024 monitor, but maybe 300x300 is unreasonably large for someone with 800x600 screen resolution

• set_start(double)
  • Allows the user to set the x-axis location of the first data point. This is important currently because the interface does not yet support coordinate pair<,>s, and so the user is stuck defining the interval with which the data is input. Obviously not all data has a uniform distribution, and they'll be able to pass an STL container of pair<,>s in the future to alleviate this problem.

• set_interval(double)
  • This allows the user to set the interval between data points that are being graphed. Again, this is necessary until we allow the user to put in coordinate pair<,>s, and will remain necessary after that for users who do not have data in coordinates

• plot_range(std::vector<double>::iterator, std::vector<double>::iterator)
  • Will be the made generic
  • Allows the user to input a begin and an end, and have the user plot the data in between

• draw_axis()
  • The user specifies that s/he would like the axis drawn in the image.

Inherited from svg. I am only including the ones it makes sense to include. In the current prototype code, it inherits handling for a few functions that are not only illogical, but produce unexpected results! This will be taken care of.

• write()
  • Since it would be too much work (and sometimes impossible) to maintain the file without intervention, this function acts as a 'commit'.
  • The user can be sure that whenever they have executed this command, the full output is written to the stream they have specified.

• line_color(svg_color c)
  • Allows users to define a color
  • point_color() will soon be supported
  • Users will be able to define custom colors soon

2.2 svg Class

The internal architecture of this class (as far as being a data structure for storing a SVG document) is as follows: One can consider a <g> tag as the branch element of a document. Not currently (but soon!) the <g> element will store full information on the styles of all elements that are listed underneath it. Each <g> element has a Boost.ptr_vector of tag elements, and soon this will allow (theoretically) infinite branching of the <g> tags, much as the standard would allow. This stores the document XML tree in a literal tree data structure, which I feel makes more sense. A more specific implementation of the internals will most likely come at a date in the near future.

---

3. To Do List

3.1 Near Future

• Set up codebase in SVN Completed
• Clean up demo code. Comment better, cement next draft of architecture (focus on single axis first)Completed
• Fully support chaining of the overloaded input operator Completed

3.2 Medium Future

• Expand to two-dimensional graphs
• Explore size-saving of the output file (I currently don't take advantage of things like paths that the svg model has to offer)
• Allow pairs of data to be input
• Explore hover features in the SVG format as a potential way to label data
• Allow any STL-compliant container to be input (I have a hunch this will be more complicated than I'd like, so June 8th is tentative.)
• Consider STL containers that don't directly fit in the straightforward container model (like maps)

3.3 Not So Near Future

• Support 3-D graphs

3.4 Minor Features (No ETA as of May 28)

• Full Color Support
• Add handling for -NAN and other double error codes

4. Suggestions (No ETA as of May 28)

By Matias Capaletto:

• Be able to choose a log scale for either the X or the Y axis
• Proposal to include a plugable extractor to plot_range()

In general, containers will store other things than double. Starting simple, I want to be able to plot std::vector<int>. This is very easy to support. Add a function:

template<class Iter, class DoubleExtractor >
plot& plot_range( Iter start, Iter end, DoubleExtractor double_extractor)
{
    return your_old_plot_range(
       boost::make_transform_iterator(start, double_extractor),
       boost::make_transform_iterator(end  , double_extractor)
    );
}

This have other implications, for example if we have list<Human> hl, and struct get_age_functor { ... }; We can:

svg << plot_range( hl.begin(), hl.end(), get_age_functor() ); // fun stuff :)

By Paul Bristow

• Customize background color of plot
• Customize the background border color
• Customize the "axis area" background color
• Title
  • Customize font
  • Customize font color
• Axis
  • Customize line colors
  • Customize line thickness
  • Define labels for axis
  • Major ticks width, length, color
  • Minor ticks width, length, color
  • Reasonable defaults for ticks
  • Axis marker labels
  • Consider the axis for data where the origin is not in the view window
  • Consider auto-scaling
  • Grid lines
• Data representation
  • Allow different data representation points
  • Allow appropriate customization of data points
  • Consider labels for data points (combined with exploration of hover-text features of SVG mentioned above)
  • Consider how to concisely represent the scale of data points
  • Multiple data series
• Legend
  • Border
  • color
  • position
  • border thickness
  • background colors
• Unicode strings