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.
Name Value Description
The following parameters must always be set
TYPE Line
Area
Bar
FloatingBar
HiLoClose (HLC)
Pie
HBar
H2Bar
Combo_Line_Bar
Combo_HLC_Bar
Combo_Line_Area
Combo_Line_Line
Combo_HLC_Area
3DLine
3DArea
3DBar
3DFloatingBar
3DHiLoClose
3DPie
3DHBar
3DH2Bar
3DCombo_Line_Bar
3DCombo_HLC_Bar
3DCombo_Line_Area
3DCombo_Line_Line
3DCombo_HLC_Area 		Chart type.
VALS list List of values to chart, separated by ";", "_", or "!":
eg: "12.2;10.0;9.8;5.3;7.5" or "12.2!10.0!9.8!5.3!7.5"
(The advantage of using "!" as a separator is that it does not need to be escaped inside URLs, but ";" has to be escaped, and its use can increase considerably the size of a URL)

The number of values should be:

for simple charts: NumPts*NumSets
for HLC charts: NumPts*(NumSets*3) 
for H2BAR and FloatingBAR charts: NumPts*(NumSets*2)
for Combo charts: NumPts*2 (or NumPts*4 if Combo HLC)
NumPts integer Number of points (values) along the X axis.
(or number of slices in the case of a Pie chart.)
The rest of the parameters are optional
NumSets integer Number of sets of values (i.e. for multiline, etc., Default = 1)
Combo charts are only supported with NumSets=1 (i.e. 1 set for each Y axis).
W integer Width of GIF image to create (Default = 300)
H integer Height of GIF image (Default = 200)
XLabels list List of (NumPts) labels for the X axis (or for each slice in a pie chart), separated by semicolons. 
eg: "Label 1;Label 2;Label 3;Label 4"
For now, labels cannot contain semicolons... this limitation will eventually be removed.
Title string Main chart title, can contain line breaks. 
Semicolons (;) anywhere in the string will be replaced by line breaks.
eg: "Title line 1;line2;line3"
YTitle string Y Axis title
XTitle string X Axis Title
YTitle2 string Right-hand Y Axis title (for COMBO types)
LTitle string For H2BAR types: Sub-title for the left side of the chart.
RTitle string For H2BAR types: Sub-title for the right side of the chart.
BGColor color Background color, Default = white (FFFFFF)
GridColor color Grid lines color, default = grey
LineColor color Color for the axis, default = black
PlotColor color Color to use for plotting values, default=blue (0000FF)
(See also: SetColors)
SetColors list of colors Color to use for each set of data, separated by ";", "!", or "_".
Supercedes PlotColor  (See also: ExtColors)
e.g. "FF0000;00FF00;0000FF" or "FF0000!00FF00!0000FF"
ExtColors list of colors Color to use for each unit of data, separated by ";", "!", or "_".
Supercedes SetColors
e.g. "FF0000;00FF00;0000FF" or "FF0000!00FF00!0000FF"
VolColor color  
TitleColor color  Color for "Title", "LTitle", and "RTitle", default = opposite of BG.
XTitleColor color  Color for "Xtitle", default = "PlotColor".
YTitleColor color  Color for "YTitle", default = "PlotColor".
YTitle2Color color  Color for "YTitle2", default = "PlotColor".
XLabelColor color  Color for "Xlabels", default = "LineColor"
YLabelColor color  Color for Y value labels, default = "LineColor"
YLabel2Color color  Color for right-hand Y axis value labels, default = "VolColor"
YLabelFmt Format string Printf format string (using %f, %e or %g) to use for Y axis labels, default = "%g"
YLabel2Fmt Format string Printf format string (using %f, %e or %g) to use for right-hand Y axis labels, default = "%g"
TitleFont Font size

Font size to use for "Title", "LTitle", and "RTitle", default = MedBold.
Valid font sizes are:

T (Tiny), S (Small), M (MedBold), L (Large), G (Giant)
XTitleFont Font size Font size for "Xtitle", default = MedBold
YTitleFont Font size Font size for "YTitle", default = MedBold
XLabelFont Font size Font size for "XLabels", default = Small
YLabelFont Font size Font size for Y value labels, default = Small
PieLabelFont Font size Font size for Pie labels, default = Small
TranspBG boolean 0 = Opaque Background (the default)
1 = Transparent Background
Grid boolean 0 = no grid,
1 = turn grid on (the default)
XAxis boolean 0 = no X axis
1 = draw X axis (the default)
YAxis boolean 0 = no Y axis
1 = draw Y axis (the default)
YAxis2 boolean Draw right-hand Y axis in COMBO charts, default = 1
StackType DEPTH
SUM
BESIDE
LAYER 		 How to stack multiple sets of values. Default = DEPTH
3DDepth integer % of GIF size, default = 10% for pie charts, and 5% for all other types.
3DAngle integer 3D Angle, 1-89°, default = 45°
BarWidth integer % of interval for 1 bar along X axis, default = 75%
LineStyles list of style
definitions		 For 2D line chart types: contains NumSets line style definitions, separated by ";", "!", or "_".

Each line style definition is a character string in which spaces are transparent pixels, and any other character will draw a pixel of the line's color. 
Hint: The style definitions should take into account the fact that lines are drawn 2 pixels wide on a chart, so the style definition should contains twice more pixels if you want the line style to have the right width/length ratio.

Examples:

  • Short-dash line style:  "xxxxxx    " 
  • Dotted line style:  "xx  "
  • Dash-Dot line style:  "xxxxxx   xx   "
And for a chart that contains these 3 line styles, the value to pass through the "LineStyles" parameter would be:
"xxxxxx    !xx  !xxxxxx   xx   "
YScaleType  LINEAR
LOG		 Y scale type, default is LINEAR scale.
PiePctType  NONE
ABOVE
BELOW
RIGHT
LEFT
Position of percentage labels on pie charts relative to the label itself. Default = RIGHT
HLCStyle integer  For HLC (Hi-Lo-close) charts, this parameter defines the style to use.  The following values can be OR'd:
1 = Diammond (the close value is represented with a diammond)
2 = Close Connected (Can't be used with Close Connecting)
4 = Close Connecting (Can't be used with Close Connected)
8 = I Cap
HLCCapWidth integer  For HLC charts, cap width, percentage (1-100) of available space.
Default is 25%.
YMin float Minimum value for the Y axis.
YMax float Maximum value for the Y axis.
YInterval float Requested interval value for the Y axis.
YMin2 float Minimum value for the secondary Y axis (combo charts).
YMax2 float Maximum value for the secondary Y axis (combo charts).
PieRadius float Requested pie radius. Overrides default radius based on label size, etc.
     

OWTChart Home | Copyright | Usage Information
February 16, 2001
Daniel Morissette, danmo@videotron.ca