SVGGraph background image support

« Return to SVGGraph page

Skip to:

From version 2.2, SVGGraph supports using an image for the graph background. The examples on this page demonstrate what can be done with it.

Setting the background image

This should be a really simple option, but it can be a bit confusing. The option to set is back_image and you must set it to the location of the image to display. The important point to remember about this is that the image file is referenced in the SVG code's <image> element in the same way that the <img> element's src attribute works in HTML.

Absolute URI

// absolute URI
$settings['back_image'] = 'http://www.my-domain.com/images/background.png';

// SVGGraph output:
<image xlink:href="http://www.my-domain.com/images/background.png" ... />

In the example above I set the image to a fully-qualified URI - this should work wherever your SVG output ends up (as long as whatever is reading the SVG supports images).

Absolute path

// absolute path
$settings['back_image'] = '/images/background.png';

// SVGGraph output:
<image xlink:href="/images/background.png" ... />

This time I used an absolute path for the image location. This should work as long as the SVG is rendered from a website to a browser. If you save the SVG document out or pass it to an external program, the image will probably not be found.

Relative path

// relative path
$settings['back_image'] = 'images/background.png';

// SVGGraph output:
<image xlink:href="images/background.png" ... />

This time a relative path has been used - the image must be in a (real or virtual) subdirectory called "images" beneath the path of the SVG document. Here are a few examples of where your images should be to work properly:

Example 1: index.php uses <embed> to load graph.php from the same directory. The graph.php script calls SVGGraph using 'images/backgroumd.png' as the back_image option.

index.php
graph.php (loaded using <embed>)
images/background.png

Example 2: the graph.php file has been moved into a subdirectory called svg. Still using embed to load the script, the background image is now expected to be in a subdirectory of svg called images:

index.php
svg/graph.php (loaded using <embed>)
svg/images/background.png

Example 3: the graph.php file is now an include, loaded into index.php and run to insert the SVG into the HTML of the main page. The background image is now relative to the index.php page.

index.php
svg/graph.php (included and run)
images/background.png

Dude, where's my image?

The examples above should cover the most common cases, but if you have trouble with the location of your images check the browser console and / or web server log. There should be a "404 not found" error message that will tell you where the browser is trying to find the missing image.

Opacity

The back_image_opacity option modifies the opacity of the background image. The "SVGGraph" image used in these examples is a PNG with an alpha channel and a predominantly transparent background. The value given for the SVGGraph back_colour (in this case '#333') shows through the transparent areas.

DoughRayMeSoFarLard01020304050
back_image_opacity = 1.0
(default value)
DoughRayMeSoFarLard01020304050
back_image_opacity = 0.3

Modes

There are three different modes available for how the image will be scaled and/or stretched. The first and default mode is auto:

Auto

DoughRayMeSoFarLard01020304050
back_image_mode = auto

When back_image_mode is set to auto, the image is shown using the correct aspect ratio, and fitted within a box with dimensions set by the back_image_width and back_image_height options. This box may be positioned using the back_image_left and back_image_top options.

DoughRayMeSoFarLard01020304050
back_image_mode = auto
(default mode)
DoughRayMeSoFarLard01020304050
back_image_width = 100
DoughRayMeSoFarLard01020304050
back_image_width = 100
back_image_left = 50
back_image_top = 60

For simplicity these captions are using pseudocode - values should be properly specified as elements of the settings array passed into the SVGGraph constructor, e.g. $settings['back_image_mode'] = 'auto';

The second background image mode is stretch:

Stretch

DoughRayMeSoFarLard01020304050
back_image_mode = stretch

With back_image_mode set to stretch, the image is stretched non-uniformly to fit the whole rectangle specifed by the back_image_width and back_image_height options. As with auto mode, the position of the box is controlled by the back_image_left and back_image_top options.

DoughRayMeSoFarLard01020304050
back_image_mode = stretch
DoughRayMeSoFarLard01020304050
back_image_mode = stretch
back_image_width = 100
DoughRayMeSoFarLard01020304050
back_image_mode = stretch
back_image_width = 100
back_image_left = 50
back_image_top = 60

And finally tile mode:

Tile

DoughRayMeSoFarLard01020304050
back_image_mode = tile

As with auto mode, the image is uniformly stretched to fit the box specified with the back_image_width and back_image_height options. The box is then used in an SVG <pattern> to tile the image across the whole of the background.

The back_image_left and back_image_top options may be used to offset the image box, as in the third example below.

DoughRayMeSoFarLard01020304050
back_image_mode = tile
DoughRayMeSoFarLard01020304050
back_image_mode = tile
back_image_height = 60
DoughRayMeSoFarLard01020304050
back_image_mode = tile
back_image_width = 100
back_image_height = 60
back_image_left = 50
back_image_top = 30

In the first example above, no tiling takes place - this is because neither the width or height have been specified, therefore the image box takes up the whole of the SVG document.

In the second example above, the image height has been set so that the image is tiled vertically, and in the third example both width and height are set to tile the image in both directions.

« Back to top of page Responsive design »