1.9.1 web.image.graph -- Create graphs

##
1.9.1 `web.image.graph` -- Create graphs

`html2tuple`( | htmlColorCode)

  Returns a colour tuple of `(R, G, B)` in hex from an HTML colour code such as `#ffffff`. The return value from this function can be used to specify colours in the `graph` module.
  htmlColorCode
    The html colour code to convert.

The `web.image.graph` module is used to create PNG or similar graphs for use on web pages.

Currently the module only works with positive values for the axes and requires the presence of the Arial.ttf font by default. This modules should be considered an early implementation. You should ensure the values you choose produce a nice looking graph because there is very little error checking and the values you choose may not result in the graph displaying correctly.

Here as an example showing the useage of the three main classes:

    #!/usr/bin/env python

    import sys; sys.path.append('../../../') # show python where the modules are
    import web.image.graph

    graph = web.image.graph.ScatterGraph(
        xAxis={'max':200, 'unit':20, 'label':'Value 1 /cm^2'},
        yAxis={'max':200, 'unit':20, 'label':'Value 2 /cm^2'},
        points=[(0,0),(13,68),(200,200)],
        size=(500, 300),
        bgColor=(240,240,240),
        title='Test Graph'
    )
    graph.save('scatter.ps')

    graph = web.image.graph.BarGraph(
        xAxis={'max':200, 'unit':20, 'label':'Value 1 /cm^2'},
        yAxis={'max':200, 'unit':20, 'label':'Value 2 /cm^2'},
        points=[10,20,40,50,200,89, 30, 60, 70, 60],
        size=(500, 300),
        bgColor=(240,240,240),
        title='Test Graph'
    )
    graph.save('bar.png')

    graph = web.image.graph.PieChart(
        points={
            'food':10,
            'numbers':20,
            'numbers2':30,
        },
        size=(500, 300),
        bgColor=(240,240,240),
        title='Test Graph'
    )
    graph.save('pie.jpg')

    graph = web.image.graph.BarGraph(
        xAxis={'max':200, 'unit':20, 'label':'Value 1 /cm^2'},
        yAxis={'max':200, 'unit':20, 'label':'Value 2 /cm^2'},
        points=[10,20,40,50,200,89, 30, 60, 70, 60],
        size=(500, 300),
        bgColor=web.image.html2tuple('#F0F0F0'),
        title='Test Graph'
    )
    fp = open('string.pdf','wb')
    fp.write(graph.toString('pdf'))
    fp.close()

Note: The format of the image saved depends on the extension used. Currently supported are `'.png'`, `'.jpg'`, `'.ps'`. JPEG is a lossy compression method and so the graphics produced as JPEGs may not be as good quality as the others. The receommended format to use is `'.png'`. ust save your files with a `.png` extension to have PNG output.

It is useful to be able to produce graphs in a script and then return them. The example below generates a graph. It can be used in an HTML tage like this `<img src="webserver-web-image-graph.py" alt="Graph" />`.

    #!/usr/bin/env python

    """Graph Generation Example.
    <img src="webserver-web-image-graph-web.py" alt="Graph" />"""

    # show python where the web modules are
    import sys, os
    sys.path.append('../')
    sys.path.append('../../../')

    import web.error; web.error.handle()
    import web.image, web.image.graph

    graph = web.image.graph.BarGraph(
        xAxis={'max':10, 'unit':1, 'label':'Days Since Send'},
        yAxis={'max':10, 'unit':1, 'label':'Number of Page Views'},
        points=[1,5,7,8,4,3,6,8,0,1],
        size=(500, 300),
        bgColor=web.image.html2tuple('#ffffff'),
        barColor=web.image.html2tuple('#000080'),
        title='Page View Rate For Newsletter',
    )
    print web.header('image/png'), graph.toString('png')

You can test this example by starting the test webserver in scripts/webserver.py and visiting http://localhost:8080/doc/src/lib/webserver-web-image-graph.py on your local machine. You will need the `Arial.ttf` font somewhere on your system where Python can find it.