Using clipping to make combined charts

• Introduction
• Example code
• Options available to the clip property
• Example demo pages

Introduction

Making individual charts - for example, a Bar chart or a Line chart - is well within RGraphs capabilities. As well as this, combining charts has been feasible because of the Object Registry that was introduced to RGraph many years ago which stores information about the charts that have been created and updates them when redraws are requested or are necessary. Well, the next feature that is as significant as this is the new clipping addition that has been introduced in version 6.17.

This new addition to RGraph allows you to easily restrict the drawing to a certain part of the canvas or svg making it very easy to combine charts - for example different colored Line charts like the example that's linked to at the top of this page.

The clipping option can be one of multiple formats so you can easily restrict the drawing on the canvas to a shape, half of the canvas, a percentage of the scale (for scaled charts eg Bar, Line, Scatter) or a specific scale value.

Example code

Here's some example code that produces the multi-color Line chart that's shown above.

What happens is that each of the three Line chart objects clips the canvas to a particular part of the scale so that only that part gets shown on the canvas. Each Line chart object specifies different colors so the result is that you get three colors on the Line chart because all three charts are drawn on the canvas.

new RGraph.Line({
    id: 'cvs',
    data: DATA = [
        4,8,6,3,2,4,5,4,5,6,1,9,1,2,3,5,7,4,2,2,6,2,3,4,
        4,8,6,2,3,5,18,14,19,27,28,24,23,18,7,5,6,4,5,1,2,3,4,6
    ],
    options: OPTIONS = {
        textSize: 15,
        yaxis: false,
        backgroundGridHlinesCount: 6,
        backgroundGridVlines: false,
        backgroundGridBorder: false,
        backgroundGridDashed: true,
        backgroundGridColor: 'gray',
        shadow: false,
        linewidth: 3,
        colors: ['red'],
        filled: true,
        filledColors:['#fdd'],
        marginInner: 15,
        marginLeft: 75,
        marginTop: 50,
        spline: true,
        xaxisTickmarksCount: 12,
        xaxisColor: 'gray',
        yaxisLabelsCount: 3,
        yaxisScaleUnitsPost: '%',
        textSize: 14,
        title: 'A tri-color Line chart using the RGraph clipping functions',
        titleSize: 16,
        clip: 'scale:25-max'
}
}).trace();




new RGraph.Line({
    id: 'cvs',
    data: DATA,
    options: {
        ...OPTIONS,
        xaxis: false,
        yaxis: false,
        xaxisLabels: false,
        colors: ['#cc0'],
        filledColors: ['#ffc'],
        clip: 'scale:20-25'
    }
}).trace();




new RGraph.Line({
    id: 'cvs',
    data: DATA,
    options: {
        ...OPTIONS,
        xaxis: false,
        xaxisLabels: false,
        yaxis: false,
        colors: ['green'],
        filledColors: ['#cfc'],
        clip: 'scale:min-20',
        xaxisLabels: ['Jan','Feb','Mar','Apr','May','Jun','Jul','Aug','Sep','Oct','Nov','Dec']
    }
}).trace();

Options available to the clip property

There are a few options that you can use to clip the canvas tag ranging from simple halves to entire RGraph-style paths. They are:

Clipping to the top half of the canvas

clip: 'tophalf' Restricts drawing to the top half of the canvas. Margin sizes are taken into account so if your top/bottom margins are different then the halfway point won't be the dead-center of the canvas.

Clipping to the bottom half of the canvas

clip: 'bottomhalf' Restricts drawing to the bottom half of the canvas. Margin sizes are taken into account so if your top/bottom margins are different then the halfway point won't be the dead-center of the canvas.

Clipping to the left half of the canvas

clip: 'lefthalf' Restricts drawing to the left half of the canvas. Margin sizes are taken into account so if your left/right margins are different then the halfway point won't be the dead-center of the canvas.

Clipping to the right half of the canvas

clip: 'righthalf' Restricts drawing to the right half of the canvas. Margin sizes are taken into account so if your left/right margins are different then the halfway point won't be the dead-center of the canvas.

Clipping to a rectangle (x, y, width, height)

If all you want is a rectangle that the canvas is clipped to then you can use this option - just pass an array of four numbers to the clip option. These numbers are the X-coordinate, the Y-coordinate, the width and the height of the rectangle that you want to see the canvas clipped to.

Clipping to a circle (x, y, radius)

If all you want is a circle that the canvas is clipped to then you can use this option - just give it the x and y coordinates and the radius to the clip option.

Clipping to a polygon created with the given [x, y] coordinates

Going a step beyond a basic rectangle, this option allows you to specify an array of coordinates that make up a shape that the canvas is clipped to. For example, if you wanted to you could clip the canvas to a star shape (!).

Clipping to a segment

If you want to clip the canvas to a circle or a segment of a circle then this is the option for you. The arguments (the numbers) represent the following things:

• Center X coordinate
• Center Y coordinate
• The radius
• Start angle. You can use the rad or deg suffixes to specify the units (rad for radians and deg for degrees). 0 degrees (or radians) is at the top (north)
• End angle. You can use the rad or deg suffixes to specify the units (rad for radians and deg for degrees). 0 degrees (or radians) is at the top (north)

Clipping to an RGraph path string

You can specify the clip property as an RGraph path. This is a shorthand version of a regular canvas path. If you're using an svg chart then this path is just a regular svg path string. You can read about the canvas path shorthand on this RGraph blog page. Here's an example of a canvas variant: clip: 'b a 200 200 100 0 6.29 false' and you could also combine this with RGraphs string format function like this: clip: 'b a {1} {2} {3} {4} false'.format(200,100,0,6.29) The svg charts also support the path option but instead of a custom RGraph format it uses the standard svg path syntax.

Clipping to percentages of the X-axis

The horizontal percentage options are useful for scaled charts when you want to restrict drawing to part of the chart (eg the left-half). If you use either 0% or 100% bear in mind that because the margins are ignored by these values the left or right margins may be cut off - which means that you won't see the scale. So for this reason you can use either negative percentages, percentages greater than 100% or there are two keywords: min and max, as shown by the examples here.

Clipping to percentages of the Y-axis

The vertical percentage options are useful for scaled charts when you want to restrict drawing to part of the chart (eg the top-half). If you use either 0% or 100% bear in mind that because the margins are ignored by these values the top or bottom margins may be cut off - which means that you won't see the title or the top of the scale labels. So for this reason you can use either negative percentages, percentages greater than 100% or there are two keywords: min and max, as shown by the examples here. This option will come in handy when you're making a multi-color Line chart.

Clipping to percentages of the radius

Radial percentages only work for charts that have certain properties - namely centerx centery and radius. If the chart doesn't have these then there's no point trying to use the r: option. This means that you can use this option with the following charts: Activity chart Fuel chart Gauge chart Horseshoe chart Meter chart Odometer chart Pie chart Radar chart Rose chart RScatter chart Segmented meter Semi-circular Progress bar SVG Activity meter SVG Gauge chart SVG Horseshoe meter SVG Pie chart SVG Radar chart SVG Rose chart SVG Segmented meter SVG Semi-circular Progress bar With the r: option you can restrict clipping to certain radial percentages starting from the centerx and centery coordinatates. The min and max keywords are available, though the min keyword is just the same as specifying 0%.

Clipping to values relating to the scale

For charts that have scales (most of them, but not the Pie chart) this allows you to clip to scale values. The Line chart example linked to at the top of the page shows this option. So on a scale of 0-100, you could show 0-5 in red, 5-15 in yellow and 15-100 in green. You can have any of the charts properties different so as well as the main colors you could have a different color for the background grid, axes, labels, title.

Example demo pages

These are some example demo pages of how you can use the clipping feature in your charts. You can find these demo pages in the download archive (there are more pages available - they usually end their names with clipping or clipped).

• demos/line-bar-clipped.html
• demos/line-clipping1.html
• demos/line-clipping2.html
• demos/line-clipping3.html (dynamic)
• demos/line-clipping4.html
• demos/line-effects-growpoint.html
• demos/line-filled-striped.html
• demos/svg-bar-dual-color.html
• demos/svg-bar-roundrobin.html
• demos/svg-line-clipped.html
• demos/svg-line-clipped2.html
• demos/svg-line-clipped3.html (dynamic)
• demos/svg-line-clipped4.html (dynamic)
• demos/svg-line-dual-color.html