JSPlot Documentation: The plotting canvas
Tutorial
- The plotting canvas
- Plotting data
- Graph plotting styles
- Plotting functions
- Vector graphics
API reference
Introduction to the plotting canvas
JSPlot is a Javascript library for drawing graphs and simple vector graphics in web pages. Everything that JSPlot draws is placed onto a drawing canvas, represented by an instance of the JSPlot_Canvas class. This page explains how to create a canvas, put things onto it, and display it in a web page.
Including JSPlot in a web page
JSPlot depends on jQuery, which must be loaded first. Then load the JSPlot library itself, which you can download here:
<script src="jquery.min.js"></script> <script src="jsplot.min.js"></script>
Next, add an empty element to the page, which the canvas will be drawn into. The canvas takes its width from this element, so give it the width you want the plot to have:
<div id="my_plot" style="max-width: 800px;"></div>
A first plot
To draw a graph, create a JSPlot_Canvas containing a JSPlot_Graph, and then call the canvas's renderToCanvas method, passing it the element to draw into. The graph below plots a single data set, made up of a list of (x, y) points:
var canvas = new JSPlot_Canvas({
"my_graph": new JSPlot_Graph([
new JSPlot_DataSet("Square numbers", {}, [[0, 0], [1, 1], [2, 4], [3, 9], [4, 16], [5, 25]])
], {
"key": true
})
}, {});
canvas.renderToCanvas($("#tutorial_first_plot")[0]);
Because the code needs the page's elements to exist before it runs, it should be placed inside a jQuery $(function () { ... }); block, or at the end of the page. The next tutorial page, Plotting data, explains the JSPlot_Graph and JSPlot_DataSet classes in detail.
Items on the canvas
The first argument to the JSPlot_Canvas constructor is an object listing the items to draw, each with a name of your choosing. As well as graphs, a canvas can hold vector graphics objects such as text, arrows, rectangles, circles and ellipses.
Items can be added later with the addItem method, and removed by name with removeItem. After changing a canvas, call renderToCanvas again to redraw it:
var canvas = new JSPlot_Canvas({
"my_graph": new JSPlot_Graph([
new JSPlot_DataSet("Square numbers", {}, [[0, 0], [1, 1], [2, 4], [3, 9], [4, 16], [5, 25]])
], {
"width": 500,
"widthIncludesAxes": false
})
}, {});
// Add a text label in the middle of the graph. Positions on the canvas are measured in pixels.
canvas.addItem("my_label", new JSPlot_Text({
"origin": [250, -150],
"text": "Added with addItem()",
"fontSize": 18
}));
canvas.renderToCanvas($("#tutorial_canvas_items")[0]);
When items overlap, their z_index setting decides which is drawn in front: items with a higher z_index are drawn on top. All items have a z_index of 0 unless you set one.
Size and layout
Positions on the canvas are measured in pixels, with the x coordinate increasing to the right and the y coordinate increasing downwards. The canvas is automatically sized to fit everything on it, so only the positions of items relative to one another matter.
A graph's origin setting is the position of the bottom-left corner of its plotting area, and the graph extends upwards and to the right from there. By default, a graph fills the width of the element that the canvas is drawn into. Its width can instead be set in pixels, or as a percentage of the available width, such as "50%".
This example stacks two graphs on one canvas. The second graph's origin is 250 pixels above the first's:
var canvas = new JSPlot_Canvas({
"lower_graph": new JSPlot_Graph([
new JSPlot_DataSet("Square numbers", {}, [[0, 0], [1, 1], [2, 4], [3, 9], [4, 16]])
], {
"aspect": 0.25,
"key": true
}),
"upper_graph": new JSPlot_Graph([
new JSPlot_DataSet("Cube numbers", {}, [[0, 0], [1, 1], [2, 8], [3, 27], [4, 64]])
], {
"aspect": 0.25,
"key": true,
"origin": [0, -250]
})
}, {});
canvas.renderToCanvas($("#tutorial_canvas_layout")[0]);
The aspect setting is the ratio of each graph's height to its width. When the browser window is resized, the canvas is redrawn automatically to fit its new width.
Exporting plots
By default, buttons appear underneath each canvas inviting the user to download a copy of it as a PNG or SVG image. You can choose which buttons appear with the settings passed as the second argument to JSPlot_Canvas. A third button, which downloads the plotted data as a CSV file, is off by default:
var canvas = new JSPlot_Canvas(items, {
"allow_export_png": false,
"allow_export_svg": true,
"allow_export_csv": true
});
A canvas can also be rendered without displaying it. The renderToSVG method returns an SVG document as a string, and renderToCSV returns the plotted data as CSV. Both are described in the JSPlot_Canvas API reference.