.ig >>
<STYLE TYPE="text/css">
<!--
        A:link{text-decoration:none}
        A:visited{text-decoration:none}
        A:active{text-decoration:none}
        OL,UL,P,BODY,TD,TR,TH,FORM { font-family: arial,helvetica,sans-serif;; font-size:small; color: #333333; }

        H1 { font-size: x-large; font-family: arial,helvetica,sans-serif; }
        H2 { font-size: large; font-family: arial,helvetica,sans-serif; }
        H3 { font-size: medium; font-family: arial,helvetica,sans-serif; }
        H4 { font-size: small; font-family: arial,helvetica,sans-serif; }
-->
</STYLE>
<title>quisp: creating dynamic graphics and plots</title>
<body bgcolor=99cc99 vlink=0000FF>
<br>
<br>
<center>
<table cellpadding=2 bgcolor=FFFFFF width=550 ><tr>
<td align=right><a href="quisp_home.html">
<img src="img/quisp2.gif" border=0><br><small>quick server pages</a> &nbsp; &nbsp; </td></tr>
<td>
.>>

.TH creating dynamic graphics and plots TDH "13-MAY-2004   TDH scg@jax.org" 


.SH Creating dynamic graphics and plots
QUISP allows dynamic creation of data graphics, charts, and plots
using an embedded instance of the
.ig >>
<a href="http://ploticus.sourceforge.net">
.>>
\0ploticus data display engine.
.ig >>
</a>
.>>
This is done using \fBquisp_pl\fR, an graphic-enabled instance of QUISP 
(see the
.ig >>
<a href="http://quisp.sourceforge.net/download">
.>>
\0quisp download page).
.ig >>
</a>
.>>
The recommended strategy is to create a temporary image file (eg. PNG), then have the browser 
display it using \fC<img src=..>\fR.
.ig >>
<a href="#setup">
.>>
\0More about quisp_pl and getting graphics to work..
.ig >>
</a>
.>>

.ig >>
<br><br><br>
.>>

.SH #graphic - #endgraphic
Graphic specifics are encapsulated within\fC#graphic\fR and \fC#endgraphic\fR directives.
Ploticus prefabs or script code can be used.
Ploticus command line arguments may be specified using \fC#arg\fR (see examples below).
Usage:
.nf
 \0 #graphic  \fIresulttype   resultfilename\fR
 \0   #arg  \fIcommandline args 1\fR
 \0   #arg  \fIcommandline args 2\fR
 \0   ...
 \0   \fIploticus script code\fR
 \0 #endgraphic
.LP
\fIresulttype\fR is \fCpng\fR, \fCgif\fR, \fCsvgz\fR etc.
\fIresultfilename\fR is the pathname of a file where the image will be written.
The \fC#arg\fR directive (described below) supplies ploticus command line arguments.
\fC#endgraphic\fR terminates the construct; when the interpreter reaches the \fC#endgraphic\fR
line the graphic result file is actually generated and written to disk.
To display the graphic,
use an \fC<img>\fR tag (after the \fC#endgraphic\fR) 
containing a URL which references the image file.

.ig >>
<br><br>
.>>
.SH #arg
Set one
.ig >>
<a href="http://ploticus.sourceforge.net/doc/pl.1.html#options">
.>>
\0ploticus command line argument
.ig >>
</a>
.>>
or argument pair.
\fC#arg\fR must be used before any ploticus code is referenced.
All arguments are supported except \fC-f\fR and \fC-ver\fR.

.ig >>
<br><br>
.>>
.SH Examples
The
.ig >>
<a href="http://quisp.sourceforge.net/cgi-bin/quisp?rtn=index#graphic">
.>>
\0dynamic graphic demo on sourceforge
.ig >>
</a>
.>>
is a good first example.  Here are some others:
.LP
1. Invoke a ploticus prefab
.nf
  \0 #set UNIQ = $uniquename()
  \0 #set FILENAME =  @UNIQ ".png"
  \0 #graphic  png  @HTMLPATH/tmp/@FILENAME
  \0   #arg  -prefab  vbars
  \0   #arg  -scale 0.8
  \0   #arg  data=@datafile
  \0   #arg  x=1
  \0   #arg  y=2
  \0 #endgraphic
  \0 <img src="@HTMLURL/tmp/@FILENAME">
.fi
.ig >>
<br><br>
.>>

.LP
2. Execute a ploticus script via \fC#include\fR.
The ploticus script can reference \fBquisp\fR variables.
.nf
  \0 #set UNIQ = $uniquename()
  \0 #set FILENAME =  @UNIQ ".png"
  \0 #graphic  png  @HTMLPATH/tmp/@FILENAME
  \0   #arg  -scale 0.8
  \0   #include plscripts/try3.pl
  \0 #endgraphic
  \0 <img src="@HTMLURL/tmp/@FILENAME">
.fi
.ig >>
<br><br>
.>>

.LP
3. Execute an embedded ploticus script.  
The ploticus script can reference \fBquisp\fR variables (eg. \fC@datafile\fR).
The args will make debug output visible in the browser.
.nf
  \0 #set UNIQ = $uniquename()
  \0 #set FILENAME =  @UNIQ ".png"
  \0 #graphic  png  @HTMLPATH/tmp/@FILENAME
  \0   #arg -debug
  \0   #arg -diagfile stdout
  \0
  \0   #proc getdata
  \0     file: @datafile
  \0   ...
  \0   #proc areadef
  \0    rectangle: 1 1 4 4
  \0   ...
  \0   #proc pie
  \0   ...
  \0 #endgraphic
  \0 <img src="@HTMLURL/tmp/@FILENAME">
.fi

.ig >>
<br><br><br>
.>>
.ig >>
<a name=setup></a>
.>>

.SH quisp_pl build notes
.LP
In order to produce embedded graphics and charts, you'll need \fBquisp_pl\fR.
This can be built from source code or downloaded in precompiled binary form for linux and solaris.
See the
.ig >>
<a href="http://quisp.sourceforge.net/download">
.>>
\0quisp download page.
.ig >>
</a>
.>>
To \fBquisp_pl\fR use \fCMakefile_pl\fR, a simple makefile that you can edit if needed.
The executable is named \fCquisp_pl\fR by default.
.LP
\fBlibploticus\fR may be configured and built to produce PNG files, JPEG, pseudo-GIF, etc.
All except pseudo-GIF require additional libraries such as ZLIB.  This is explained on the
ploticus download page and in the ploticus \fCMakefile_api\fR.

.ig >>
<br><br><br>
.>>

.SH Getting graphics to work..
If you use graphics on your site you can use quisp_pl for all your pages, or use quisp_pl 
for graphic pages and quisp for other pages.  The size and memory footprint of the quisp_pl 
executable is several times bigger than that of the quisp executable.
.LP
Beginners should stick with the names \fCquisp\fR and \fCquisp_pl\fR but
advanced users can choose other names if necessary.
.LP
You'll need to set HTMLURL, HTMLPATH, CGIPROG and CGIPROG_PL 
explicitly in your project \fCconfig\fR file.  Here's what I used for the quisp
sourceforge web site:
.nf
  varvalue:       HTMLURL=
  varvalue:       HTMLPATH=/home/groups/q/qu/quisp/htdocs
  varvalue:       CGIPROG=/cgi-bin/quisp
  varvalue:       CGIPROG_PL=/cgi-bin/quisp_pl
.fi
.LP
Your internal HTML links must use @CGIPROG or @CGIPROG_PL when linking between 
plain and graphic-enabled pages.
.LP
The recommended approach (as used in the above examples)
is to write the PNG (or whatever) result to your project \fC./tmp\fR directory.
So that your web server can find the image file, you'll need to set up a soft link from your 
html directory to the project \fC./tmp\fR directory.  The link may be named anything,
(the canned example assumes \fCtmp\fR).


.ig >>
<br><br>
.>>

.LP
If you need to use a 
.ig >>
<a href="http://ploticus.sourceforge.net/doc/config.html">
.>>
\0ploticus config file
.ig >>
</a>
.>>
the way to do this is to set the PLOTICUS_CONFIG environment variable in your 
.ig >>
<a href="config.html">
.>>
\0quisp config file
.ig >>
</a>
.>>
like this: 
.nf
  putenv:  PLOTICUS_CONFIG=/home/john/plconfig
.fi
The ploticus config file and the quisp config file are two different things.

.ig >>
<br><br>
.>>
.LP
You can see what libploticus version you have by printing the variable \fB@PLVERSION\fR
after \fC#endgraphic\fR.


.ig >>
<br>
<br>
</td></tr>
<td align=right>
<a href="quisp_home.html">
<img src="img/quisp2.gif" border=0></a><br>
<small>quick server pages &nbsp; &nbsp;<br>
<a href="Copyright.html">Copyright Steve Grubb</a> &nbsp; &nbsp;
</td></tr>
</table>
.>>
