PYTHON API FOR PLOTICUS

Contents

Description
Installation and Usage
pyPloticus API
Example Script


Description

This software provides a python interface to the graphing library, Ploticus, written by Steve Grubb.  This Python interface is a fairly thin layer that wraps around the C API of ploticus, libploticus developed by Steve Grubb.  Using this Python interface one could use ploticus related calls in their python scripts.


Platform specifics
The software has been tested on a box running RedHat Linux Enterprise 5.3, Python-2.6 and ploticus-2.41.  

Installation Instructions

For RedHat Enterprise Linux and Python2.4 and above
1. Download the source code.
2. Unzip the tarball using
        tar xzvf pyPloticus.tgz
3. cd pyPloticus
4. Use the README file for instructions.
5. As super user, run         python setup.py install         to install the python module.
6. Test it by invoking the python interpreter and typing: import ploticus
7.  There is a test script in the tarball to test if the installation went smoothly.

pyPloticus API

The functions/methods in pyPloticus are one-to-one mapping of the functions provided by libploticus, the C API for ploticus.  So all the functions outlined behave similary to the ones outlined in libploticus.  However, the function PLGG_getimg of libploticus is yet to be implemented.  For detailed information on the methods described below one could refer to the documentation posted under libploticus.

1. ploticus_init(string output_format, string output_filename)

    This function must be called first.  The function returns an int value of 0 if the call is successful or non-zero if the call failed.  The output_format can be strings such as 'png', 'jpeg', 'eps', 'x11', etc (all the      
    above strings may not be available depending on how ploticus was built).

2. ploticus_arg ( string name, string value)

    This call helps in passing arguments - arguments that you might have passed during the command line invocation of ploticus.  The function teturns an int value of 0 if successful or non-zero value if the call
    failed.  All arguments are supported except -f, -prefab and -ver.  This call can be made only after ploticus_init call but before any other ploticus function call.

3. ploticus_begin()

    This call is used to perform further intializations after passing the arguments.  Returns an int value of 0 if successful or non-zero value if the call failed.

4. ploticus_execline(string line)

    Used for interpreting a "raw" ploticus script line.

5. ploticus_execscript(string scriptfile, int prefabflag)

    Used to interpret an entire ploticus script file.  If the prefabflag is 1, then scriptfile should be a ploticus prefab name. If prefabflag is 0, then scriptfile should be a pathname

6. ploticus_getvar(char name, char value)

    Returns the contents of ploticus variable name. Result is copied into value.
    Example: stat = ploticus_getvar( "XFINAL", xf );

7. ploticus_setvar(char name, char value)

    Set ploticus variable name to value.

8. ploticus_end()

    Finish up the graphic result (usually this involves writing it out to a file), and terminate ploticus. This must be the last ploticus function called.    

Example Script

As an example, try the following script in your python interpreter.  Invoke the python interpreter and copy and paste the script below.

Python 2.6.2 (r262:71600, Jun 26 2009, 12:32:35)
[GCC 4.1.2 20080704 (Red Hat 4.1.2-44)] on linux2
Type "help", "copyright", "credits" or "license" for more information.

import ploticus as p
k=p.ploticus_init("png","hello.png")
k=p.ploticus_arg("-scale","1.2")
k=p.ploticus_begin()
p.ploticus_execline("#proc annotate")
p.ploticus_execline("location: 2 2")
p.ploticus_execline(" text: Hello World")
p.ploticus_end()

David Sathiaraj, davids at srcc dot lsu dot edu
NOAA Southern Regional Climate Center, Louisiana State University.