# 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.

`Usage: owtchart <param_file.txt> <out_file.gif>`
- `<param_file.txt>:` the name of the text file that contains the chart parameters (see below)
- `<out_file.gif>:` the name of the GIF file to create. Passing a value of "-" will send the GIF to stdout.

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.

Required Parameters Chart Type (TYPE) Values (VALS) Number of Points (NumPts) Optional Parameters General Chart Options Chart Width (W) Chart Height (H) Background Colour (BGColor) Transparent Background (TransBG) Line Colour (LineColour) Toggle Grid (Grid) Grid Colour (GridColor) 3D Options 3D Depth (3DDepth) 3D Angle (3DAngle) Value Colours Plot Colour (PlotColor) Set Colours (SetColors) Extended Colours (ExtColors) Volume Colours (VolColors) Chart Title Options Chart Title (Title) Right Subtitle (RTitle) Left Subtitle (LTitle) Title Colour (TitleColor) Title Font Size (TitleFont) X-Axis Options X-Axis Toggle (XAxis) X-Axis Title (XTitle) X-Axis Title Font Size (XTitleFont) X-Axis Title Colour (XTitleColor) X-Axis Labels (XLabels) X-Axis Label Font Size (XLabelFont) X-Axis Label Colour (XLabelColor) | Optional Parameters Y-Axis Options Y-Axis Toggle (YAxis) Y-Axis Scale Type (YScaleType) Y-Axis Minimum Value (YMin) Y-Axis Maximum Value (YMax) Y-Axis Interval (YInterval) Y-Axis Title (YTitle) Y-Axis Title Font Size (YTitleFont) Y-Axis Title Colour (YTitleColor) Y-Axis Label Font Size (YLabelFont) Y-Axis Label Colour (YLabelColor) COMBO Chart Y-Axis Toggle (YAxis2) COMBO Chart Y-Axis Minimum Value (YMin2) COMBO Chart Y-Axis Maximum Value (YMax2) COMBO Chart Y-Axis Title (Title2) COMBO Chart Y-Axis Title Colour (YTitle2Color) COMBO Chart Y-Axis Label Colour (YLabel2Color) Pie Chart Specific Options Position of Percentage Labels (PiePctType) Pie Radius (PieRadius) Pie Label Font Size (PieLabelFont) Bar Chart Specific Options Stack Type (StackType) Bar Width (BarWidth) Bar Labels Toggle (BarLabels) Bar Label Format (BarLabelFmt) Line Chart Specific Options Line Styles (LineStyles) HLC (Hi-Lo-Close) Chart Specific Options Hi-Lo-Close Style (HLCStyle) Hi-Lo-Close Cap Width (HLCCapWidth) H2Bar Chart Specific Options See RTitle and LTitle in Chart Title Options COMBO Chart Specific Options See YAxis2, YMin2, YMax2, YTitle2, YTitle2Color, YLabel2Color in Y-Axis Options Multi-Set Chart Specific Options Number of Data Sets (NumSets)

OWTChart Home | Copyright | Usage Information

Last update: October 14, 2003