SVGGraph Shapes and Figures

« Return to SVGGraph page

Skip to:

• Shape format
• Coordinates
• Shape options
• SVG attributes
• Shape details
• Figures

Sometimes you might want to add some extra things to the graph to highlight certain areas or display target ranges. You could always add your elements into the SVG using an XML parser or string replacement, but the shape options should make things a bit easier.

For more complex shapes or for repeating the same shape in different places you can define figures. Figures can also be used as markers.

Supported shapes

Here is a LineGraph showing some examples of the shapes available:

All the shapes drawn on the graph above were added using the shape option, using the configuration shown below. The three red boxes with a shaded part are examples of a figure, the star is a marker and the notepad icon is an image.

$settings = array(
  'shape' => array(
    array(
      'circle',
      'cx' => 'g1',
      'cy' => 'g900',
      'r' => 10,
      'stroke-width' => 2,
      'fill' => '#66f'
    ),
    array(
      'ellipse',
      'cx' => 'g1',
      'cy' => 'g750',
      'rx' => 20,
      'ry' => 10,
      'stroke-width' => 2,
      'fill' => '#6f6'
    ),
    array(
      'rect',
      'x' => 'g2',
      'y' => 'g950',
      'width' => 'u2',
      'height' => 'u100',
      'stroke-width' => 2,
      'fill' => '#ff6'
    ),
    array(
      'line',
      'x1' => 'g2',
      'y1' => 'g800',
      'x2' => 'g4',
      'y2' => 'g700',
      'stroke-width' => 3,
      'stroke' => '#f0f'
    ),
    array(
      'polyline',
      'points' => array(
        'g0.5', 'g650',
        'g1.5', 'g600',
        'g1', 'g575',
        'g0.5', 'g600'
      ),
      'stroke-width' => 3,
      'stroke' => '#0c9'
    ),
    array(
      'polygon',
      'points' => array(
        'g0.5', 'g500',
        'g1.5', 'g450',
        'g1', 'g425',
        'g0.5', 'g450'
      ),
      'stroke-width' => 3,
      'stroke' => '#f66'
    ),
    array(
      'polygon',
      'points' => array(
        'g4.5', 'g600',
        'g11', 'g1200',
        'g12', 'g600',
        'g5', 'g300'
      ),
      'fill' => array('#f00', '#fcc'),
      'fill-opacity' => 0.9,
      'stroke' => '#00f',
      'stroke-width' => 2,
      'stroke-dasharray' => '3,2',
      'clip_to_grid' => true
    ),
    array(
      'figure',
      'x' => 'g6',
      'y' => 'g200',
      'name' => 'complex'
    ),
    array(
      'figure',
      'x' => 'g7',
      'y' => 'g180',
      'name' => 'complex'
    ),
    array(
      'figure',
      'x' => 'g8',
      'y' => 'g220',
      'name' => 'complex'
    ),
    array(
      'marker',
      'x' => 'g9',
      'y' => 'g300',
      'type' => 'star',
      'size' => 20
    ),
    array(
      'image',
      'x' => 'g9.5',
      'y' => 'g300',
      'src' => '../images/64x64/icon-05.png'
    ),
  )
);

Most of the config should be easy enough to understand. The coordinates might look a bit strange, but they are described in detail below.

Shape format

The shape option is always an array - either a single array containing the details of a single shape, or an array of different shapes, each defined by an array of options. The shapes are drawn in the order that they appear in the array (except when given a depth, described below).

The first element in the array (with index 0) is always the type of shape. This is followed by the named attributes that define the shape, options for SVGGraph to style it and any other attributes that are passed straight through to the SVG element. Here's an example with all of these attribute types:

$settings['shape'] = array(
  // type of shape
  'circle',

  // shape attributes
  'cx' => 'g10',
  'cy' => 'g200',
  'r' => 'u1x',

  // styling
  'fill' => array('#f00', 'pattern' => 'polkadot'),
  'depth' => 'above',
  'href' => '/circles/',

  // SVG attributes
  'fill-opacity' => 0.75,
  'stroke-width' => 2
);

This is the shape option for a circle, its location and size defined by the required fields cx, cy and r. The example is using grid-relative values, so it will not work on pie-type graphs.

The fill option is a red polka dot pattern, the depth specifies that the circle will be drawn on top of the bars or lines, and the href links the circle to a relative URL.

Finally, the fill-opacity and stroke-width fields are passed through into the SVG circle element without any modification. Here is the SVG fragment that SVGGraph produces from the shape option when drawn on the example graph at the top of the page:

<a xlink:href="/circles/" target="_blank">
 <circle stroke="#000" fill="url(#e3)" 
  cx="539.17" cy="308.8" r="49.917"
  fill-opacity="0.75" stroke-width="2px"/>
</a>

Coordinates

Normal SVG coordinates are in pixels, measured from the top-left of the document, going towards the right and downwards. You can use these in any of the shapes and on any graph type by simply using the numeric values. For grid-based graphs, positioning shapes on the grid or specifying a size in grid units is more useful, so SVGGraph adds some modifiers and abbreviations to make this easier.

Here is the format of the coordinate string in BNF because I can't think of any clearer way to describe it accurately:

<coordinate>             ::= <measurement> | <position>

<measurement>            ::= <number> | <unit-measurement>
<unit-measurement>       ::= "u" <number> <axis-expr>

<position>               ::= <doc-relative-position> | <grid-relative-position> | <grid-position>

<doc-relative-position>  ::= <relation> <offset>
<grid-relative-position> ::= "g" <relation> <offset>
<relation>               ::= "l" | "r" | "t" | "b" | "w" | "h" | "c"

<grid-position>          ::= "g" <position-value> <axis-expr>
<position-value>         ::= <number> | <key-value> | <relation>
<key-value>              ::= <associative-data-key> | <datetime-data-key>

<axis-expr>              ::= <axis> | <axis> <number> | ""
<axis>                   ::= "x" | "y"

<offset>                 ::= <direction> <number> <units-specifier> | ""
<direction               ::= "+" | "-"
<units-specifier>        ::= "u" | ""

For anyone not familiar with BNF, the following sections describe the format in more detail.

Measurements

These are the simplest coordinates - either a single numeric value to use pixels, or a "u" followed by a numeric value to use grid units. When using grid units you can also specify which axis units to use.

// 100 pixels
$c1 = 100;

// 100 grid units using default axis
$c2 = 'u10';

// 10 grid units using third Y axis
$c3 = 'u10y2';

Positions

Positions are either relative to the SVG document boundaries or to the grid area. Document-relative positions work on all types of graph, though grid-based positions require a graph type that uses axes.

Relative positions

These allow you to position things around the graph area relative to the document or grid area, depending on whether the “g” prefix is used or not.

l

Left side of area.

r

Right side of area.

t

Top of area

b

Bottom of area.

w

Width of area.

h

Height of area.

c

Centre of area.

The "c" position could be horizontal or vertical, depending on the context in which is is used. To override this, follow the "c" with "x" or "y".

The position can also be followed by an offset to shift the coordinate away from its normal position. The offset can be in pixels or grid units, and is always positive towards the right and bottom.

// left side of document
$c1 = 'l';

// 20 pixel from bottom of grid area
$c2 = 'gb-20';

// 30 grid units down from vertical centre of document
$c3 = 'cy+30u';

Note: unless you are doing something strange with the SVG viewport, the left and top of the document are always 0, the right and bottom are always the same as the width and height.

Grid positions

These are positions measured using the scale(s) of the grid. You can use numeric values, or if the data is associative or using date/time keys you can use those instead.

// at 10 units on default axis
$c1 = 'g10';

// at 20 units on second Y axis
$c2 = 'g20y1';

// at position where 'Peter' key is used
$c3 = 'gPeter';

// at position where 1:00pm on 28th of April occurs
$c4 = 'g2022-04-28T13:00:00';

Date/time values should use the same format as used in the data array for the best chance of working.

Options

These are the shape attributes that are purely for use by SVGGraph, or are preprocessed before being inserted into the SVG element.

depth

This specifies where in the SVG output that the shape will be included. At the moment the options are “above” to display the shape on top of the graph, or “below” to draw the shape before the bars, pie slices, etc. are drawn.

href

xlink:href

target

This wraps the shape inside an <a> element, using the link you provide. xlink:href is the actual attribute used by SVG, but SVGGraph will accept either. The target for the link defaults to “_blank“ if you do not set it.

clip_to_grid

This boolean option adds a clip-path attribute to the shape, cropping the shape at the edge of the grid area. The default is false.

autohide

Another boolean option - if enabled, the shape will be hidden when the cursor is over it. The default is false

autohide_opacity

This option specifies how opaque the shape should be when it is hidden, and optionally when it is shown again. It can either be a single value between 0 and 1 for the hidden opacity, or an array containing both the hidden and shown opacity values. The hidden opacity can be greater than the shown opacity if you want the shape to become more opaque when the cursor is over it.

The hide/show values only affect the opacity after the cursor has entered the shape and left it, the initial opacity is set with the SVG opacity attribute.

SVG attributes

I'm not going to attempt to list all the attributes available here, so you should refer to the W3C recommendation document for help with anything specific. All the multi-word SVG attributes are separated by minus signs, but SVGGraph will convert underscores to minus signs for you (so stroke_width will become stroke-width in the SVG document).

Here are some of the attributes you are likely to need:

stroke

This is the colour of the lines that make up the shape. If you don't set stroke, SVGGraph will set it to black (actually “#000”) for you. If you don't want to draw the outline of your shape, set stroke to “none“.

fill

This is the colour that the shape is filled with. By default, SVGGraph will set it to “none”, so your shape will be empty. The fill and stroke attributes both accept SVGGraph gradient and pattern options, though for stroke only the initial colour is used.

stroke-width

The thickness of the line stroke, in pixels. The default is 1.

opacity

fill-opacity

stroke-opacity

The opacity of the whole shape, the filled area, or the stroked line. The value should be in the range 0-1. The default is 1, for a fully opaque shape, and a value of 0 will be completely invisible.

stroke-dasharray

The dash pattern for the line. I've described how this works on the line graphs page.

The shapes

All the shapes supported by SVGGraph are basic SVG shapes. For complete details, refer to the W3C recommendation document.

Most of the attributes listed here are required to draw each of the shapes - SVGGraph will display an error message if they are not present. Some of the shapes have optional attributes that change how they behave.

circle

To draw a circle, provide the position of the centre and the radius.

cx

X-axis coordinate of centre of circle.

cy

Y-axis coordinate of centre of circle.

r

Radius of circle.

$settings['shape'] = array(
  'circle',
  'cx' => 100,
  'cy' => 200,
  'r' => 10
);

ellipse

The ellipse is similar to the circle, but you must provide separate radius values for the horizontal and vertical dimensions.

cx

X-axis coordinate of centre of ellipse.

cy

Y-axis coordinate of centre of ellipse.

rx

X-axis radius of ellipse.

ry

Y-axis radius of ellipse.

$settings['shape'] = array(
  'ellipse',
  'cx' => 100,
  'cy' => 200,
  'rx' => 10,
  'ry' => 20
);

rect

A rectangle is drawn from the top-left corner using a width and height.

x

X-axis coordinate of top-left of rectangle.

y

Y-axis coordinate of top-left of rectangle.

width

Width of rectangle.

height

Height of rectangle.

$settings['shape'] = array(
  'rect',
  'x' => 100,
  'y' => 200,
  'width' => 100,
  'height' => 50
);

line

The line element draws a straight line between two points.

x1

X-axis coordinate of first point.

y1

Y-axis coordinate of first point.

x2

X-axis coordinate of second point.

y2

Y-axis coordinate of second point.

$settings['shape'] = array(
  'line',
  'x1' => 100,
  'y1' => 200,
  'x2' => 200,
  'y2' => 400
);

polyline and polygon

Both of these draw a line between pairs of points. polyline ends the line with your last point, polygon closes the shape by drawing a line from the last point back to the first point.

points

An array of pairs of X and Y coordinates.

$settings['shape'] = array(
  'polygon',
  'points' => array(
    100, 200,
    200, 200,
    200, 300,
    150, 250,
    100, 300
  )
);

image

The image shape adds an <image> element to the document. This is similar to the HTML <img> element, except you must provide the x and y coordinates for where the image should appear.

x

X-axis coordinate for upper-left of image bounding box.

y

Y-axis coordinate for upper-left of image bounding box.

src

Path of image to be displayed (relative to SVG document or absolute).

width

Width of image bounding box (optional).

height

Height of image bounding box (optional).

stretch

If set to true, the image is stretched to fill the whole of the bounding box specified using width and height - otherwise, the image is scaled proportionately to fit inside the box. This attribute is optional, and defaults to false.

$settings['shape'] = array(
  'image',
  'x' => 'g9.5',
  'y' => 'g300',
  'src' => '../images/64x64/icon-05.png'
);

text

The text shape allows you to draw simple text strings on the graph. Custom labels would usually be an easier option for this, but a text shape can be used in a figure, which in turn means it can be used as a marker.

x

X-axis coordinate for text.

y

Y-axis coordinate for text.

text

Text to be displayed.

font

Font for text (optional, default is "Arial").

font_size

Font size for text (optional, default is 14).

text_align

Alignment for multi-line text, either "left", "centre" or "right" (optional, default is "left").

line_spacing

Line spacing for multi-line text (optional, default is font size).

$settings['shape'] = array(
  'text',
  'x' => 'g4.5',
  'y' => 'g80',
  'text' => "Look\nhere",
  'font' => 'Times New Roman',
  'font_size' => 36
);

marker

The marker shape allows you to position any of the standard markers on your graph, even on graph types that would not normally support them (pie graphs being the most obvious example of this).

x

X-axis coordinate for marker.

y

Y-axis coordinate for marker.

type

Type of marker to display.

size

Size of marker (optional, defaults to 10).

$settings['shape'] = array(
  'marker',
  'x' => 'g9',
  'y' => 'g300',
  'type' => 'star',
  'size' => 20
);

figure

The figure shape draws a user-defined shape or group of shapes on the graph. The attributes specify where the figure should go and the name of the figure to use. The creation of figures is described in the next section.

x

X-axis coordinate for figure.

y

Y-axis coordinate for figure.

name

Name of figure to display.

$settings['shape'] = array(
  'figure',
  'x' => 'g6',
  'y' => 'g200',
  'name' => 'complex'
);

Figures

Figures are named collections of shapes that can be used multiple times at different locations using the shape option, or as graph markers by setting the marker_type to “figure:” followed by the name of the figure.

The figure option should be an array of separate figures. Each individual figure is another array, starting with a name that you will use to refer back to it - this is just a string, and SVGGraph doesn't do anything special with it.

After the name you can add as many shapes as you want in your figure, each one of which will be in its own array. Figures can contain other figures as long as they were defined earlier in the list. You can position your shapes anywhere, but when the figure is used the point (0,0) in the figure shapes will be translated to the new position of the figure.

Note: all styling of figure shapes must be done in the figure option. You cannot change the colour, stroke width and other attributes of a figure from the shape option that references it.

Here is the configuration for the square figures in the example graph at the top of the page:

$settings = array(
  'figure' => array(
    array(
      'complex',
      array(
        'rect',
        'x' => -20,
        'y' => -20,
        'width' => 40,
        'height' => 40,
        'fill' => 'red'
      ),
      array(
        'rect',
        'x' => -10,
        'y' => -15,
        'width' => 20,
        'height' => 30, 
        'fill' => 'white',
        'transform' => 'rotate(45)'
      ),
      array(
        'rect',
        'x' => -10,
        'y' => -15,
        'width' => 20,
        'height' => 30, 
        'fill' => array('red', 'white'),
        'transform' => 'rotate(135)'
      ),
    ),
  ),
);

This figure array contains a single entry - another array that defines a single figure. The array for this individual figure contains the name I chose for it, “complex”, followed by three more arrays. Each of these arrays contains the details of a shape, three rectangles in this case.The shapes are all positioned so that their centre point is at (0,0) - this is so that when the figure is used its position on the graph will be where the middle of the figure occurs.

« Back to top of page Custom labels »

Copyright © 2022, Goat 1000