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.
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.
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.
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.
Let's reuse the examples from section 3.2 above and look at the input
files that would produce the same charts:
Note: Parameter Names and Values are not case sensitive.
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 |
|
|
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:
|
|
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:
| |
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 |
|
|
|
|