OWTChart    Home  |  Docs  |  Support  |  Bugs  |  CVS  |  Downloads

MapTools.org

How to Use OWTChart Engine

Version 1.2.0 - 2003-10-14

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

Version 1.2.0 - 2003-10-14

Note: Parameter Names and Values are not case sensitive.

Required Parameters

Optional Parameters

General Chart Options

3D Options

Value Colours

Chart Title Options

X-Axis Options

Optional Parameters

Y-Axis Options

Pie Chart Specific Options

Bar Chart Specific Options

Line Chart Specific Options

HLC (Hi-Lo-Close) Chart Specific Options

H2Bar Chart Specific Options

COMBO Chart Specific Options

Multi-Set Chart Specific Options

Required Parameters
   
Name: Chart Type     Parameter: TYPE index
Values:
Line 3DLine Combo_Line_Bar 3DCombo_Line_Bar
Area 3DArea Combo_HLC_Bar 3DCombo_HLC_Bar
Bar 3DBar Combo_Line_Area 3DCombo_Line_Area
FloatingBar 3DFloatingBar Combo_Line_Line 3DCombo_Line_Line
HiLoClose (HLC) 3DHiLoClose (HLC) Combo_HLC_Area 3DCombo_HLC_Area
Pie 3DPie Combo_HLC_Line 3DCombo_HLC_Line
HBar 3DHBar Combo_Line_HLC 3DCombo_Line_HLC
H2Bar 3DH2Bar    
 
Description: Type of Chart to be generated.  
Example: TYPE=Pie  
Name: Values     Parameters: VALS index
Values: List of Integers and/or Floats  
Description:
List of values to chart, separated by ";", "_", or "!":
(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 in the list 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)
 
Example: VALS=12.2!10.0!9.8!5.3!7.5  
Name: Number of Points     Parameter: NumPts index
Value: Integer  
Description: Number of points (values) along the X axis. Also the number of slices in a Pie chart.  
Example: NumPts=8  
   
Optional Parameters
General Chart Options
   
Name: Chart Width     Parameter: W index
Value: Integer  
Description: Width in pixels of GIF image to create. Default value is 300.  
Example: W=400  
Name: Chart Height     Parameter: H index
Value: Integer  
Description: Height in pixels of GIF image. Default value is 200.  
Example: H=300  
Name: Background Colour     Parameter: BGColor index
Value: Hexadecimal Colour  
Description: Background colour, Default value is FFFFFF (white).  
Example: BGColor=A645FF  
Name: Transparent Background     Parameter: TranspBG index
Value: Boolean (1 or 0)  
Description: Switch to make the background transparent or opaque.
0 = Opaque Background (the default value)
1 = Transparent Background 		 
Example: TranspBG=1  
Name: Line Colour     Parameter: LineColor index
Value: Hexadecimal Colour  
Description: Colour for the axes. Default value is 000000 (black).
Exception: Not available for Pie Charts. 		 
Example: LineColor=FF194A  
Name: Toggle Grid     Parameter: Grid index
Value: Boolean (1 or 0)  
Description: Switch to show or hide grid lines.
0 = hide grid
1 = show grid (Default value)
Exception: Not available for Pie Charts.		  
Example: Grid=0  
Name: Grid Colour     Parameter: GridColor index
Value: Hexadecimal Colour  
Description: Colour of Grid lines. Default value is CCCCCC (grey)
Exception: Not available for Pie Charts.		  
Example: GridColor=FFFD83  
   
3D Options
   
Name: 3D Depth     Parameter: 3DDepth index
Value: Integer  
Description: Percentage of GIF size. Default value is 10% for pie charts, and 5% for all other types.  
Example: 3DDepth=20  
Name: 3D Angle     Parameter: 3DAngle index
Value: Integer  
Description: 3D Angle, 1° to 89°. Default value is 45°.  
Example: 3DAngle=30  
   
Value Colours
   
Name: Plot Colour     Parameter: PlotColor index
Value: Hexadecimal Colour  
Description: Colour to use for plotting values. Default value is 0000FF (blue) (See also: Set Colours)  
Example: PlotColor=FF25E2  
Name: Set Colours     Parameter: SetColors index
Value: List of Hexadecimal Colours  
Description:
Colour to use for each set of data, separated by ";", "!", or "_".
Supercedes Plot Color  (See also: Extended Colours)		  
Example: SetColors=FF0000!00FF00!0000FF  
Name: Extended Colours     Parameter: ExtColors index
Value: List of Hexadecimal Colours  
Description:
Colour to use for each unit of data, separated by ";", "!", or "_".
Supercedes Set Colours.		  
Example: ExtColors=FF0000!00FF00!0000F  
Name: Volume Colour     Parameter: VolColor index
Value: List of Hexadecimal Colours  
Description:
The equivalent of Plot Colour, but applies to the second set of values in a Combo Chart separated by ";", "!", or "_" (e.g. in a Combo_Line_Bar chart Plot Colour applies to the Line set and Volume Colour applies to the Bar set.)
Supercedes SetColors.		  
Example: VolColors=FF0000!00FF00  
   
Chart Title Options
   
Name: Chart Title     Parameter: Title index
Value: String  
Description:
Main chart title. To include line breaks in the title, use a semicolon (;) anywhere in the string, and it will be replaced by line breaks. 		 
Example: Title="Mean Household Income;Urban vs. Rural Families"  
Name: Right Subtitle     Parameter: RTitle index
Value: String  
Description: For H2Bar types: Subtitle for the right side of the chart.  
Example: RTitle="Urban Families"  
Name: Left Subtitle     Parameter: LTitle index
Value: String  
Description: For H2Bar types: Subtitle for the left side of the chart.  
Example: LTitle="Rural Families"  
Name: Title Colour     Parameter: TitleColor index
Value: Hexadecimal Colour  
Description: Colour for Title, LTitle, and RTitle. Default value is the inverse of the Background Colour.  
Example: TitleColor=0F0F0F  
Name: Title Font Size     Parameter: TitleFont index
Values:
T (Tiny) S (Small) M (Medium Bold) L (Large) G (Giant)
 
Description:
Font size to use for Title, LTitle, and RTitle. Default value is M (Medium Bold).		  
Example: TitleFont=L  
   
X-Axis Options (not available for Pie Charts)
   
Name: X-Axis Toggle     Parameter: XAxis index
Value: Boolean (1 or 0)  
Description: Switch to show or hide the X-Axis.
0 = no X axis
1 = draw X axis (the default)		  
Example: XAxis=0  
Name: X-Axis Title     Parameter: XTitle index
Value: String  
Description: Title for the X-Axis  
Example: XTitle="Title for the X-Axis"  
Name: X-Axis Title Font Size     Parameter: XTitleFont index
Values:
T (Tiny) S (Small) M (Medium Bold) L (Large) G (Giant)
 
Description: Font size for X-Axis Title. Default value is M (MedBold)  
Example: XTitleFont=S  
Name: X-Axis Title Colour     Parameter: XTitleColor index
Value: Hexadecimal Colour  
Description: Colour for X-Axis Title. Default value is Plot Color.  
Example: XTitleColor=C7FCFF  
Name: X-Axis Labels     Parameter: XLabels index
Value: List of Strings  
Description:
 List of NumPts labels for the X-Axis (or for each slice in a Pie chart), separated by semicolons. 
For now, labels cannot contain semicolons... this limitation will eventually be removed. 		 
Example: XLabels="Label 1;Label 2;Label 3;Label 4"   
Name: X-Axis Label Font Size     Parameter: XLabelFont index
Values:
T (Tiny) S (Small) M (Medium Bold) L (Large) G (Giant)
 
Description: Font size for X-Axis Labels. Default value is S (Small)  
Example: XLabelFont=T  
Name: X-Axis Label Spacing     Parameter: XLabelSpacing index
Value: Integer  
Description: Number of pixels between 2 X-Axis Labels considered acceptable before the program starts taking out labels along the X-Axis. Default value is 5.  
Example: XLabelSpacing=3, meaning a minimum of 3 pixels between X-Axis Labels.  
Name: X-Axis Label Colour     Parameter: X LabelColor index
Value: Hexadecimal Colour  
Description: Colour for X-Axis Labels. Default value is LineColor.  
Example: XLabelColor=ADADAD  
   
Y-Axis Options (not available for Pie Charts)
   
Name: Y-Axis Toggle     Parameter: YAxis index
Value: Boolean (1 or 0)  
Description:
0 = no Y-Axis
1 = draw Y-Axis (the default)		  
Example: YAxis=0  
Name: Y-Axis Scale Type     Parameter: YScaleType index
 
Values: LINEAR
  LOG
 
Description: Y scale type. Default value is LINEAR scale.  
Example: YScaleType=LOG  
Name: Y-Axis Minimum Value     Parameter: YMin index
Value: Float  
Description: Minimum value for the Y-axis.  
Example: YMin=50  
Name: Y-Axis Interval     Parameter: YInterval index
Value: Float  
Description: Interval to use between values along the Y-axis. Useful in combination with YMin and YMax.  
Example: YInterval=20  
Name: Y-Axis Maximum Value     Parameter: YMax index
Value: Float  
Description: Maximum value for the Y-axis.  
Example: YMax=500  
Name: Y-Axis Title     Parameter: YTitle index
Value: String  
Description: Y-axis title.  
Example: YTitle="The Y-axis Title"  
Name: Y-Axis Title Font Size     Parameter: YTitleFont index
Values:
T (Tiny) S (Small) M (Medium Bold) L (Large) G (Giant)
 
Description: Font size for YTitle. Default value is M (Medium Bold).  
Example: YTitleFont=L  
Name: Y-Axis Title Colour     Parameter: YTitleColor index
Value: Hexadecimal Colour  
Description: Colour for YTitle. Default value is Plot Colour.  
Example: YTitleColor=717171  
Name: Y-Axis Label Font Size     Parameter: YLabelFont index
Values:
T (Tiny) S (Small) M (Medium Bold) L (Large) G (Giant)
 
Description: Font size for Y value labels. Default value is S (Small).  
Example: YLabelFont=L  
Name: Y-Axis Label Colour     Parameter: YLabelColor index
Value: Hexadecimal Colour  
Description: Colour for Y value labels. Default value is LineColor.  
Example: YLabelColor=8B8B8B  
Name: COMBO Chart Y-Axis Toggle     Parameter: YAxis2 index
Value: Boolean (1 or 0)  
Description: Draw right-hand Y-axis in COMBO charts. Default value is 1.  
Example: YAxis2=0  
Name: COMBO Chart Y-Axis Minimum Value     Parameter: YMin2 index
Value: Float  
Description: Minimum value for the secondary Y-axis (combo charts).  
Example: YMin2=50  
Name: COMBO Chart Y-Axis Maximum Value     Parameter: YMax2 index
Value: Float  
Description: Maximum value for the secondary Y-axis (combo charts).  
Example: YMax2=500  
Name: COMBO Chart Y-Axis Title     Parameter: YTitle2 index
Value: String  
Description: Right-hand Y-axis title (for COMBO types)  
Example: YTitle2="The Y-Axis Right Hand Title"  
Name: COMBO Chart Y-Axis Title Colour     Parameter: YTitle2Color index
Value: Hexadecimal Colour  
Description: Colour for YTitle2. Default value is PlotColor.  
Example: YTitle2Color=19FF11  
Name: COMBO Chart Y-Axis Label Colour     Parameter: YLabel2Color index
Value: Hexadecimal Colour  
Description: Colour for right-hand Y-Axis value labels. Default value is VolColor.  
Example: YLabel2Color=C1C1C1  
Name: COMBO Chart Primary Y-Axis Label Format     Parameter: YLabelFmt index
Value: Printf Format String  
Description: Any printf format string that applies to a floating point value.  
Examples:  
YLabelFmt=%.1f displays 22.3 (1 decimal place)
YLabelFmt=%.2f%% displays 22.26% (2 decimal places)
YLabelFmt=%.3f meters displays 22.257 meters (3 decimal places) 		 
Name: COMBO Chart Secondary Y-Axis Label Format     Parameter: YLabel2Fmt index
Value: Printf Format String  
Description: Any printf format string that applies to a floating point value.  
Examples:  
YLabel2Fmt=%.1f displays 22.3 (1 decimal place)
YLabel2Fmt=%.2f%% displays 22.26% (2 decimal places)
YLabel2Fmt=%.3f meters displays 22.257 meters (3 decimal places) 		 
   
Pie Chart Specific Options
   
Name: Position of Percentage Labels     Parameter: PiePctType index
  Values:
NONE ABOVE BELOW RIGHT LEFT
 
Description: Position of percentage labels on pie charts relative to the label itself. Default value is RIGHT.  
Example: PiePctType=BELOW  
Name: Pie Percentage Label Format     Parameter: PiePctFmt index
Value: Printf Format String  
Description: Any printf format string that applies to a floating point value.  
Examples:  
PiePctFmt=%.1f displays 22.3 (1 decimal place)
PiePctFmt=%.2f%% displays 22.26% (2 decimal places)
PiePctFmt=%.3f meters displays 22.257 meters (3 decimal places)
 
Name: Pie Radius     Parameter: PieRadius index
Value: Float  
Description: Requested pie radius. Overrides default radius based on label size, etc.  
Example: PieRadius=15  
Name: Pie Label Font Size     Parameter: PieLabelFont index
Values:
T (Tiny) S (Small) M (Medium Bold) L (Large) G (Giant)
 
Description: Font size for Pie labels. Default value is S (Small).  
Example: PieLabelFont=L  
 
   
Bar Chart Specific Options
   
Name: Stack Type     Parameter: StackType index
  Values:
DEPTH SUM BESIDE LAYER
 
Description: How to stack multiple sets of values. Default value is DEPTH.  
Example: StackType=BESIDE  
Name: Bar Width     Parameter: BarWidth index
Value: Integer  
Description: % of interval for 1 bar along X axis. Default value is 75%.  
Example: BarWidth=25  
Name: Bar Label     Parameter: BarLabels index
Value: Boolean (1 or 0)  
Description: Switch to show or not the value of each bar at the top of them.
0 = no label
1 = draw labels		  
Example: BarLabels=1  
Name: Bar Label Format     Parameter: BarLabelFmt index
Value: String  
Description: Format of the Bar Labels. Default is " %.0f ".  
Example: BarLabelFmt=--%.0f--  
   
Line Chart Specific Options
   
Name: Line Styles     Parameter: LineStyles index
Value: List of String Style Definitions  
Description:
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   "
 
Example: LineStyles="xxxxxx    !xx  !xxxxxx   xx   "  
   
HLC (Hi-Lo-Close) Chart Specific Options
   
Name: Hi-Lo-Close Style     Parameter: HLCStyle index
Value: Integer  
Description:
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
 
Example: BarWidth=25  
Name: Hi-Lo-Close Cap Width     Parameter: HLCCapWidth index
Value: Integer  
Description: For HLC charts, cap width, percentage (1-100) of available space. Default value is 25%.  
Example: HLCCapWidth=50  
   
H2Bar Chart Specific Options
   
See RTitle and LTitle in Chart Title Options. index
   
Combo Chart Specific Options
   
See YAxis2, YMin2, YMax2, YTitle2, YTitle2Color, YLabel2Color in Y Axis Options. index
   
Multi-Set Chart Specific Options
   
Name: Number of Data Sets     Parameter: NumSets index
Value: Integer  
Description:
Number of sets of values (i.e. for multiline, etc., Default value is 1)
Combo charts are only supported with NumSets=1 (i.e. 1 set for each Y-axis). 		 
Example: NumSets=3  
   
Image Type Options
   
Name: Image Type     Parameter: ImageType index
Value:
Gif Png Jpeg Wbmp
 
Description:
Determine the extension of the image. The default value is Gif
  
Example: ImageType=Gif  
Name: Jpeg Quality     Parameter: Jpeg_Quality index
Value: Integer between 1-100  
Description:
Quality of Jpeg generated. The default value is -1
  
Example: Jpeg_Quality=78  
   

 

Printer Friendly
 

Docs

OWTChart User Guide

License
 

Demo

Chart Generator
 

Related Links

GDChart Library

GD Library

PHP
 

Contact Information

OWTChart Users List
MapTools.org -- co-hosted by MapGears, and Gateway Geomatics