| 8 | | |
| 9 | | [[PageOutline(2-3)]] |
| 10 | | |
| 11 | | [wiki:WikiStart-es Versión en español] |
| 12 | | |
| 13 | | = Pycha (PYthon CHArts) = |
| 14 | | |
| 15 | | Pycha is a very simple Python package for drawing charts using the great [http://www.cairographics.org Cairo] library. Its goals are: |
| 16 | | |
| 17 | | * Lightweight |
| 18 | | * Simple to use |
| 19 | | * Nice looking with default values |
| 20 | | * Customization |
| 21 | | |
| 22 | | It won't try to draw any possible chart on earth but draw the most common ones nicely. There are some other options you may want to look at like [http://bettercom.de/de/pycairochart pyCairoChart] |
| 23 | | |
| 24 | | Pycha is based on [http://solutoire.com/plotr/ Plotr] which is based on [http://www.liquidx.net/plotkit/ PlotKit]. Both libraries are written in !JavaScript and are great for client web programming. I needed the same for the server side so that's the reason I ported Plotr to Python. Now we can deliver charts to people with !JavaScript disabled or embed them in PDF reports. |
| 25 | | |
| 26 | | Pycha is distributed under the terms of the [http://www.gnu.org/licenses/lgpl.html GNU Lesser General Public License]. |
| 27 | | |
| 28 | | == Screenshots == |
| 29 | | |
| 30 | | Sample Pie Chart with the relative size of each source file: |
| 31 | | |
| 32 | | [[Image(source:/trunk/examples/piechart.png)]] |
| 33 | | |
| 34 | | Another chart with the same data. This time each bar represent the number of lines of each source file: |
| 35 | | |
| 36 | | [[Image(source:/trunk/examples/vbarchart.png)]] |
| 37 | | |
| 38 | | Now with horizontal bars: |
| 39 | | |
| 40 | | [[Image(source:/trunk/examples/hbarchart.png)]] |
| 41 | | |
| 42 | | Finally, the same information in a Line (Area) chart: |
| 43 | | |
| 44 | | [[Image(source:/trunk/examples/linechart.png)]] |
| 45 | | |
| 46 | | == Documentation == |
| 47 | | |
| 48 | | === Installation === |
| 49 | | |
| 50 | | Pycha needs !PyCairo to works since it uses the Cairo graphics library. If you use Linux you will probably already have it installed so you don't have to do anything. If you use Windows these are the recommended steps for installing !PyCairo: |
| 51 | | |
| 52 | | 1. Grab the latest !PyCairo Windows installer from http://ftp.gnome.org/pub/GNOME/binaries/win32/pycairo/ You need to use the one that matches your Python version so take the one ending in -py2.4.exe for Python 2.4 or the one ending in -py2.5.exe for Python 2.5 |
| 53 | | 1. Install it in your Python environment (just follow the installation program instructions) |
| 54 | | 1. Put the Cairo dlls inside the pycairo directory inside your site-packages directory or anywhere in your path. You can find the dlls at http://www.gimp.org/%7Etml/gimp/win32/downloads.html Go there and download the following packages: |
| 55 | | 1. cairo.zip. You just need the libcairo-2.dll file inside that zip |
| 56 | | 1. libpng.zip. You just need the libpng13.dll file inside that zip |
| 57 | | 1. zlib.zip. You just need the zlib1.dll file inside that zip |
| 58 | | |
| 59 | | Pycha is distributed as a [http://peak.telecommunity.com/DevCenter/PythonEggs Python Egg] so is quite easy to install. You just need to type the following command: |
| 60 | | |
| 61 | | {{{ |
| 62 | | easy_install pycha |
| 63 | | }}} |
| 64 | | |
| 65 | | And [http://peak.telecommunity.com/DevCenter/EasyInstall Easy Install] will go to the [http://cheeseshop.python.org/pypi/ Cheeseshop] and grab the last pycha for you. If will also install it for you at no extra cost :-) |
| 66 | | |
| 67 | | === Tutorial === |
| 68 | | |
| 69 | | Using pycha is quite simple. You always follow the same 5 simple steps: |
| 70 | | |
| 71 | | 1. Create a Cairo surface to draw the chart on |
| 72 | | 2. Build a list of data sets from which your chart will be created |
| 73 | | 3. Customize the chart options. |
| 74 | | 4. Create the chart, add the datasets and render it |
| 75 | | 5. Save the results into a file or do whatever you want with the Cairo surface |
| 76 | | |
| 77 | | To create the Cairo surface you just need to say the type of surface and its dimensions: |
| 78 | | |
| 79 | | {{{ |
| 80 | | import cairo |
| 81 | | width, height = (500, 400) |
| 82 | | surface = cairo.ImageSurface(cairo.FORMAT_ARGB32, width, height) |
| 83 | | }}} |
| 84 | | |
| 85 | | Then you should create your data set querying a database or any other data source: |
| 86 | | |
| 87 | | {{{ |
| 88 | | dataSet = ( |
| 89 | | ('dataSet 1', ((0, 1), (1, 3), (2, 2.5))), |
| 90 | | ('dataSet 2', ((0, 2), (1, 4), (2, 3))), |
| 91 | | ('dataSet 3', ((0, 5), (1, 1), (2, 0.5))), |
| 92 | | ) |
| 93 | | }}} |
| 94 | | |
| 95 | | As you can see, each data set is a tuple where the first element is the name of the data set and the second is another tuple composed by points. Each point is a two-elements tuple, the first one is the x value and the second the y value. |
| 96 | | |
| 97 | | Not every chart uses all the information of a data set. For example, the Pie chart only uses the first point of each dataset and it only uses the y value of the point. |
| 98 | | |
| 99 | | Now you may want to specify some options so the chart can be customized changing its defaults values. To see the defaults you can check the pycha.chart.Chart.!__init!__ method in the [source:/trunk/pycha/chart.py source code]. You can use regular dictionaries to define your options. For example, imagine you want to hide the legend and use a different color for the background: |
| 100 | | |
| 101 | | {{{ |
| 102 | | options = { |
| 103 | | 'legend': {'hide': True}, |
| 104 | | 'background': {'color': '#f0f0f0'}, |
| 105 | | } |
| 106 | | }}} |
| 107 | | |
| 108 | | Now we are ready to instantiate the chart, add the data set and render it: |
| 109 | | |
| 110 | | {{{ |
| 111 | | import pycha.bar |
| 112 | | chart = pycha.bar.VerticalBarChart(surface, options) |
| 113 | | chart.addDataset(dataSet) |
| 114 | | chart.render() |
| 115 | | |
| 116 | | }}} |
| 117 | | |
| 118 | | Right now you can choose among 4 different kind of charts: |
| 119 | | |
| 120 | | * Pie Charts (pycha.pie.!PieChart) |
| 121 | | * Vertical Bar Charts (pycha.bar.!VerticalBarChart) |
| 122 | | * Horizontal Bar Charts (pycha.bar.!HorizontalBarChart) |
| 123 | | * Line Charts (pycha.bar.!LineChart) |
| 124 | | |
| 125 | | Finally you can write the surface to a graphic file or anything you want using the cairo library: |
| 126 | | |
| 127 | | {{{ |
| 128 | | surface.write_to_png('output.png') |
| 129 | | }}} |
| 130 | | |
| 131 | | That's it! You can see more examples in the [source:/trunk/examples examples] directory of the source code |
| 132 | | |
| 133 | | == Documentation == |
| 134 | | |
| 135 | | Adam Przywecki has done a fantastic work writing documentation for Pycha. Check it out at http://pycha.yourwei.com/ |
| 136 | | |
| 137 | | == Development == |
| 138 | | |
| 139 | | You can get the last bleeding edge version of pycha by getting a checkout of the subversion repository: |
| 140 | | |
| 141 | | {{{ |
| 142 | | svn co http://www.lorenzogil.com/svn/pycha/trunk pycha |
| 143 | | }}} |
| 144 | | |
| 145 | | Don't forget to check the ReleaseNotes for each version to learn the new features and incompatible changes. |
| 146 | | |
| 147 | | == Contact == |
| 148 | | |
| 149 | | There is a mailing list about !PyCha at http://groups.google.com/group/pycha You can join it to ask questions about |
| 150 | | its use or simply to talk about its development. Your ideas and feedback are greatly appreciated! |
| 151 | | |
| 152 | | I work on Pycha in my free time, if you like Pycha I'd appreciate any donations: |
| 153 | | |
| 154 | | {{{ |
| 155 | | #!html |
| 156 | | <form action="https://www.paypal.com/cgi-bin/webscr" method="post"> |
| 157 | | <input type="hidden" name="cmd" value="_s-xclick"> |
| 158 | | <input type="hidden" name="encrypted" value="-----BEGIN PKCS7-----MIIHJwYJKoZIhvcNAQcEoIIHGDCCBxQCAQExggEwMIIBLAIBADCBlDCBjjELMAkGA1UEBhMCVVMxCzAJBgNVBAgTAkNBMRYwFAYDVQQHEw1Nb3VudGFpbiBWaWV3MRQwEgYDVQQKEwtQYXlQYWwgSW5jLjETMBEGA1UECxQKbGl2ZV9jZXJ0czERMA8GA1UEAxQIbGl2ZV9hcGkxHDAaBgkqhkiG9w0BCQEWDXJlQHBheXBhbC5jb20CAQAwDQYJKoZIhvcNAQEBBQAEgYAx7P72ZpRz/EIikGSfcvTFUH10+IGKv1vv/15cW24YwLyZy2k7GQbnlzLeB3vm/eBbacSFl9AtrT3xnidQiPHYM7T6aFpaKoAklYs7xFVsWNn62Iegk7fOccleEv3jA1TnEOJe8yiudQiP8dz7W03oUFYSEWdcQDb4Xc7aQISnijELMAkGBSsOAwIaBQAwgaQGCSqGSIb3DQEHATAUBggqhkiG9w0DBwQIZ35IPImZY/OAgYA0aQx++eRwkIKR+H1uraXlCE2G+QQJcRDIhuN0u3ytalJ0tqImSkEFnYJQDxHyeBpxPNBJOV0fVaeV67linCCr80D3b8AYmNPc/Y6WhWLGqZHdsvwTom6lHLdCWYBbII/Vc75oYaYBZxSyyel9x/u1V9SYGrK8DXDxe8uWIjl076CCA4cwggODMIIC7KADAgECAgEAMA0GCSqGSIb3DQEBBQUAMIGOMQswCQYDVQQGEwJVUzELMAkGA1UECBMCQ0ExFjAUBgNVBAcTDU1vdW50YWluIFZpZXcxFDASBgNVBAoTC1BheVBhbCBJbmMuMRMwEQYDVQQLFApsaXZlX2NlcnRzMREwDwYDVQQDFAhsaXZlX2FwaTEcMBoGCSqGSIb3DQEJARYNcmVAcGF5cGFsLmNvbTAeFw0wNDAyMTMxMDEzMTVaFw0zNTAyMTMxMDEzMTVaMIGOMQswCQYDVQQGEwJVUzELMAkGA1UECBMCQ0ExFjAUBgNVBAcTDU1vdW50YWluIFZpZXcxFDASBgNVBAoTC1BheVBhbCBJbmMuMRMwEQYDVQQLFApsaXZlX2NlcnRzMREwDwYDVQQDFAhsaXZlX2FwaTEcMBoGCSqGSIb3DQEJARYNcmVAcGF5cGFsLmNvbTCBnzANBgkqhkiG9w0BAQEFAAOBjQAwgYkCgYEAwUdO3fxEzEtcnI7ZKZL412XvZPugoni7i7D7prCe0AtaHTc97CYgm7NsAtJyxNLixmhLV8pyIEaiHXWAh8fPKW+R017+EmXrr9EaquPmsVvTywAAE1PMNOKqo2kl4Gxiz9zZqIajOm1fZGWcGS0f5JQ2kBqNbvbg2/Za+GJ/qwUCAwEAAaOB7jCB6zAdBgNVHQ4EFgQUlp98u8ZvF71ZP1LXChvsENZklGswgbsGA1UdIwSBszCBsIAUlp98u8ZvF71ZP1LXChvsENZklGuhgZSkgZEwgY4xCzAJBgNVBAYTAlVTMQswCQYDVQQIEwJDQTEWMBQGA1UEBxMNTW91bnRhaW4gVmlldzEUMBIGA1UEChMLUGF5UGFsIEluYy4xEzARBgNVBAsUCmxpdmVfY2VydHMxETAPBgNVBAMUCGxpdmVfYXBpMRwwGgYJKoZIhvcNAQkBFg1yZUBwYXlwYWwuY29tggEAMAwGA1UdEwQFMAMBAf8wDQYJKoZIhvcNAQEFBQADgYEAgV86VpqAWuXvX6Oro4qJ1tYVIT5DgWpE692Ag422H7yRIr/9j/iKG4Thia/Oflx4TdL+IFJBAyPK9v6zZNZtBgPBynXb048hsP16l2vi0k5Q2JKiPDsEfBhGI+HnxLXEaUWAcVfCsQFvd2A1sxRr67ip5y2wwBelUecP3AjJ+YcxggGaMIIBlgIBATCBlDCBjjELMAkGA1UEBhMCVVMxCzAJBgNVBAgTAkNBMRYwFAYDVQQHEw1Nb3VudGFpbiBWaWV3MRQwEgYDVQQKEwtQYXlQYWwgSW5jLjETMBEGA1UECxQKbGl2ZV9jZXJ0czERMA8GA1UEAxQIbGl2ZV9hcGkxHDAaBgkqhkiG9w0BCQEWDXJlQHBheXBhbC5jb20CAQAwCQYFKw4DAhoFAKBdMBgGCSqGSIb3DQEJAzELBgkqhkiG9w0BBwEwHAYJKoZIhvcNAQkFMQ8XDTA5MDQyMTE5MTcyMlowIwYJKoZIhvcNAQkEMRYEFO/U2OQKT40H5yT2J9S7SU/hSeiSMA0GCSqGSIb3DQEBAQUABIGAJcA3/erDPoDjjFJPH5EnjgorKIzb0rXx74iChLgVe6eOY0LKNPv0YCbSpFcwu3vz4bvZvj+PgU0srZstfBLKta8o8P9DR4d47AMym2Ywo45EGryp3dOKfWdCsCwl7Yn6vZryHB46nGmPse8Tal3TWB4aeS5XZgBesToonVEFwC8=-----END PKCS7----- |
| 159 | | "> |
| 160 | | <input type="image" src="https://www.paypal.com/en_US/i/btn/btn_donateCC_LG.gif" border="0" name="submit" alt="PayPal - The safer, easier way to pay online!"> |
| 161 | | <img alt="" border="0" src="https://www.paypal.com/es_ES/i/scr/pixel.gif" width="1" height="1"> |
| 162 | | </form> |
| 163 | | }}} |
