OWTChart Engine

How to use OWTChart

1. Using OWTChart as a CGI application

1.1 Installation

To use OWTChart as a CGI application, simply copy the "owtchart" executable to the "cgi-bin" directory (or any other directory that allows CGI program execution), and include a URL that refers to it in your web pages.  (There are no more installation steps!!!)

This allows you to generate charts from either static HTML pages, or from any web development environment, such as PHP (http://www.php.net/), or from shell or perl CGI scripts, etc.
 

1.2 Building a chart URL

Note: If you are not familiar with CGI scripts and URLs, it might be a good idea to take some time to learn about them since this document is not intended to be a web site development tutorial.

To produce a chart, you build a URL using the "owtchart" CGI path, and you add chart parameters in the QUERY_STIRNG part of the URL. See section 5 (below) for the list of chart parameters.

OK, this probably was not very clear... the best way to learn how to use the OWTChart engine is probably to look at some examples.

The following examples assume that the "owtchart" application is installed and is accessible at the URL "http://www.host.addr/cgi-bin/owtchart".

Let's start with a simple line chart:

http://www.host.addr/cgi-bin/owtchart?Type=Line&W=300&H=200&NumSets=1&NumPts=5&Vals=2!5!4!7!5
And add a Title and labels along the X axis:

http://www.host.addr/cgi-bin/owtchart?Type=Line&W=300&H=200&NumSets=1&NumPts=5&Vals=2!5!4!7!5&Title=Chart+Title&XLabels=A;B;C;D;E
Now, turn it into a 3D bar chart:

http://www.host.addr/cgi-bin/owtchart?Type=3DBar&W=300&H=200&NumSets=1&NumPts=5&Vals=2!5!4!7!5&Title=Chart+Title&XLabels=A;B;C;D;E
And finally, add 1more set of bars, drawn in red, besides each other:

http://www.host.addr/cgi-bin/owtchart?Type=3DBar&W=300&H=200&NumSets=2&NumPts=5&Vals=2!5!4!7!5!1!4!3!3!4&Title=Chart+Title&XLabels=A;B;C;D;E&SetColors=0000FF!FF0000&StackType=Beside

1.3 Notes about building URLs

When building a chart URL manually, it is very important to remember that a URL can only contain alphanumeric characters plus a couple of others like "!", "_", ".", ....

Any other character must be escaped, the most frequent case is spaces that have to be converted to "+" characters, see RFC2396 for more details on the escaping of URLs.

Malformed URLs may work on some systems, but may not on others... it really depends on the HTTP server you are running, it has nothing to do with the OWT chart engine itself.
 
 

2. Using OWTChart as a command-line application

The same OWTChart executable can also be used as a comand-line application.  In this case, it reads the set of chart options from a text file, and the output goes to a file.  The output can optionally be sent to standard output.
  The program returns a status of 0 on success, or non-zero if an error happened.
 

2.1 Chart parameters file

The text file with the chart parameters that is used as input contains 1 line for each parameter value, as they would appear inside a URL, except that the values should not be escaped as they would be inside a URL.  See section 5 below for the list of chart parameters.

Let's reuse the examples from section 3.2 above and look at the input files that would produce the same charts:

A simple line chart:

Type=Line
W=300
H=200
NumSets=1
NumPts=5
Vals=2!5!4!7!5
Add a Title and labels along the X axis:
Type=Line
W=300
H=200
NumSets=1
NumPts=5
Vals=2!5!4!7!5
Title=Chart Title
XLabels=A;B;C;D;E
Turn it into a 3D bar chart:
Type=3DBar
W=300
H=200
NumSets=1
NumPts=5
Vals=2!5!4!7!5
Title=Chart Title
XLabels=A;B;C;D;E
Add 1 more set of bars, drawn in red, besides each other:
Type=3DBar
W=300
H=200
NumSets=2
NumPts=5
Vals=2!5!4!7!5!1!4!3!3!4
Title=Chart Title
XLabels=A;B;C;D;E
SetColors=0000FF!FF0000
StackType=Beside

3. Chart Parameters

Note: Parameter Names and Values are not case sensitive.

OWTChart Home | Copyright | Usage Information
Last update: October 14, 2003
Daniel Morissette, [email protected]