                            JcGraph
                Copyright 1992, Jean-Christophe Clment
                QubecNet: Jean-Christophe Clement
                Internet:clemj00@dmi.usherb.ca

Amiga, AmigaDos, WorkBench are a trademark of Commodore-Amiga Inc.
PostScript is a trademark of Adobe system corp.
Professionnal Page is a trademark of Gold Disk Inc.
PageStream is a trademark of Soft-Logik corp.
Saxon Publisher is a trademark of Saxon Industries Inc.
AegisDraw2000 is a trademark of Oxxi/Aegis Inc.
File requester: Copyright 1990 Khalid Aldosery.
Jeff Glatt's Ilbm.library has been used to save IFF ILBM.
HyperText system by Dominic Giampaolo.

Note to the purists: English is my second language.

WARNING:

This software is not public-domain and thus, cannot be copied without the
written permission from is author. Beeing a registered user by sending any
amount of money doesn't gives any distribution right. But, a demo version
which is available on request and can be freely redistributed but it should
keep its integrity. This demo is identified as is and all other copies are
illegal.

Registration:

Send 40$ Canadian dollars to:
Jean-Christophe Clement
921 rang 3 , St-Simon
Quebec,CANADA
J0H-1Y0

(resident of Country other than Canada and USA should add 7$ for delivery)
You will receive by mail a disk containing the software (JcGraph), more
graph types. I would like to have some information on your working
environment too:

1. Wich AmigaDOS version are you using ?
   a. If version < 2.0, are you planning to upgrade soon ?
2. What other major software are you using with your Amiga ?
3. (To your discretion) How old are you ?
4. Are you planning to use JcGraph on a personnal or professionnal basis ?
5. Wich model of Amiga are you using ?
6. What peripheral(s) do you have ?
7. Is it important , for you, to have JcGraph and the manual traducted in
   another dialect ?

Table of content:
-----------------

0.Introduction.
1.Required configuration, Hardware and Software.
2.JcGraph's installation.
3.Step by step example of a graph's creation.
4.Menu options summary.
5.Control panel window.
6.File format: Input.
7.File format: Output.
8.Graph's modification.
9.Keyboard equivalent.
10.TOOLTYPE and command line options.
11.The future of JcGraph.
12.JcGraph history.

0.Introduction:
---------------
a.What is JcGraph ?.

    Specialised in business graph generation, JcGraph will output your data
as Pie, line, bar, stack charts,(etc...more) in two or three dimension. You
will then be able to rotate the resulting graph in X,Y,Z axes and output
them to: EPS,Geo 3D, AegisDraw2000 or IFF ILBM.

b.Why I have created JcGraph ?

    Because, after having tried some commercial software that were "supposed"
to produce professionnal quality business graphs, I found that none  were up
to what is available for Macintosh or IBM PC compatibles. Considering the
Amiga reputation as a "Multimedia" computer, it was time for a change.

c.JcGraph's philosophy.

    The first goal of Jcgraph was to produce highest quality business
graphics with the greatest visual impact with the least effort possible.
    So, I asked myself: "What is the single most difficult thing to do when
someone is making a business graphic without any specific tool other than a
paint program ?". The answer is quite simple: "The main graphic itself!".
I mean, once the main graph is designed, the process of adding title,
annotation, graduated background, etc... is trivial.
    JcGraph reflects this reflexion; it will help you create a great looking
graphic and the flexibility of it's export modules will let you add all the
fancy details in other specialised software.

1.Required configuration, Hardware and Software:
------------------------------------------------

Minimal:
            Any Amiga (more than one is not a necessity :-).
            512k RAM.
            WorkBench 1.3.
            1 floppy disk.

Suggested:
            Accelerated Amiga.
            1-1.5 meg RAM.
            WorkBench 2.0 or more :-).
            Hard-Disk.

JcGraph has been tested and judged fully functionnal under these system
configurations:
-Amiga 500, 1 floppy, 1 meg RAM, WB 1.3, 68000.
-Amiga 2000HD, 52 Megs HD, 3 megs RAM, WB 2.0, 68000.
-Amiga 3000/16, 50 Megs HD, 2 megs RAM, WB 2.0, 68030/16Mhz

2.JcGraph's installation:
-------------------------

A-Files that SHOULD be present in archive:
------------------------------------------

JcGraph/Docs/ManuelFrancais.txt
JcGraph/Docs/EnglishManual.txt
JcGraph/Docs/Content.txt
JcGraph/Docs/README.txt
JcGraph/Docs/ManuelFrancais.txt.info
JcGraph/Docs/EnglishManual.txt.info
JcGraph/Docs/Content.txt.info
JcGraph/Docs/README.txt.info
JcGraph/libs/kd_freq.library
JcGraph/libs/ilbm.library
JcGraph/libs/FRQLIB.LZH
JcGraph/libs/ILBM.LZH
JcGraph/SampleData/3X3.asc
JcGraph/SampleData/3X1.asc
JcGraph/GraphType/2D_VP_PieChart.grf
JcGraph/GraphType/3D_Cone.grf
JcGraph/GraphType/2D_VertHistogram.grf
JcGraph/GraphType/3D_StepPlanes.grf
JcGraph/GraphType/2D_StackHistogram.grf
JcGraph/GraphType/2D_SimpleBrokenLine.grf
JcGraph/GraphType/3D_DefaultType.grf
JcGraph/GraphType/3D_BrokenPlanes.grf
JcGraph/GraphType/2D_CarresLies.grf
JcGraph/GraphType/2D_CarresIsoles.grf
JcGraph/GraphType/2D_StackArea.grf
JcGraph/GraphType/2D_StackAreaLarge.grf
JcGraph/GraphType/2D_StackAreaLarge2.grf
JcGraph/GraphType/3D_Pyramide.grf
JcGraph/GraphType/2D_SideBySideHistogram.grf
JcGraph/GraphType/3D_Cylinder.grf
JcGraph/GraphType/3D_surface2.grf
JcGraph/GraphType/3D_UnnamedPlane1.grf
JcGraph/GraphType/2D_StackAreaLarge3.grf
JcGraph/OutputSamples/2DSample.AegisDraw
JcGraph/OutputSamples/3DBlock.eps
JcGraph/OutputSamples/3DSample.ilb
JcGraph/OutputSamples/3DSample.ilb.info
JcGraph/OutputSamples/ColorLegend.eps.lgd
JcGraph/OutputSamples/Histogram.ilb
JcGraph/OutputSamples/Histogram.ilb.info
JcGraph/OutputSamples/Output3DGeo.geo
JcGraph/OutputSamples/StackArea.ilb
JcGraph/OutputSamples/StackArea.ilb.info
JcGraph/OutputSamples/StackedHistogram.ilb
JcGraph/OutputSamples/StackedHistogram.ilb.info
JcGraph/Docs.info
JcGraph/GraphType.info
JcGraph/HelpFile.info
JcGraph/Libs.info
JcGraph/OutputSamples.info
JcGraph/SampleData.info
JcGraph/Template.info
JcGraph/JcGraph
JcGraph/JcGraph.info

B-Logical assigns:
------------------

For example: If you copy JcGraph in "Work:MyJcGraph",
             add this line to the file "s:startup-sequence":
             "assign JcGraph: Work:MyJcGraph".

C-Directory and files required (After having done B):
-----------------------------------------------------
libs:icon.library               :On WB 1.3 (en ROM sous 2.0).
libs:kd_freq.library            :File-requester Library.
libs:ilbm.library               ;Library used for IFF ILBM .
JcGraph:Graphtype               :Contain all graph types.
JcGraph:Template                :Contain all Templates.
JcGraph:HelpFile                :Contain all help files.
JcGraph:HelpFile/ht             :On-line Help engine.
JcGraph:JcGraph                 :Main program.

If you haven't done so yet, go to jcgraph:libs directory and type (in a
shell) "copy #?.library libs:". Everything should be functionnal from now.

3.Step by step example of a graph's creation:
---------------------------------------------
    We will produce a graph made of 3 rows of 3 planes each and output it as
AegisDraw2000.

    The first step is data creation. To do so, use your favorite text editor.
It is important that it should not produce a file containing special control
characters that would not be recognized by JcGraph (stay ASCII international).
    After your text editor is loaded, start by entering "1002" (without the
delimiters). This sequence help JcGraph identify the file type, to be sure
that it is really compatible. Note that all value should be comma-separated.
    Next, enter the number of column that your file will contain, "3" in our
example. Do the same thing for the number of line. Follows a number which
will set the space between each cotation in the scale on the side of the
graph; for example, if your data range from 0 to 100 and you specify 25,
the cotation scale will output "0","25","50","75","100". This number use
the same value unit as the data itself.
    The next number (floating point), is the one by which every cotation
value will be multiplied ; for example, if you enter "1.24", each cotation
of the scale will be muliplied by 1.24. This permits to access floating
point value without changing the data itself. Note that only 3 decimals
positions will be kept for now and that a value of 0 will result in an
integer form (ie no decimal point).
    The next step is the value entry. As we chose to produce a 3 by 3 data
file, there will be 9 consecutive values (they can be on the same line but
should always be comma-separated).
    The 3 next value are text strings that will identify your columns (they
should always be filled). Same procedure for each line. Note that the
orientation is always the same. Rows represents variation and lines are
diferent products type.

Here is the resulting data file from the example:
1002,
3,3,10,0,
10,20,30,
50,60,60,
15,32,17,
Jan,Fev,Mar,
Gaz,Oil,Fer,

Save this result as "test3X3.asc".

    The next major step is to load this data file in JcGraph. First, run
JcGraph. Note that once JcGraph is startes, there can be a 3 to 5 second
break before you see anything happen, this is normal.
    Now, choose "Open..." from the project menu (Amiga+O)
IMPORTANT: JcGraph accepts command from the interface window only. So, every
time you want to perform an operation, you should select it (if not already
selected). It is also worth to mention that when there is no data loaded in
JcGraph, the interface's title bar will display "No Data".
    A file requester will pop up asking "Choose an ASCII data file". It's
utilisation is not described here for brievty but can get extended help by
pressing HELP or SHIFT-F1 when it is active.
    Find et select your file "test3X3.asc" and select "Open" from the lower
left corner of the file requester's window. The mouse pointer will change
for a small clock until your data file is openned. This should'nt be long.
 The title bar should now display "test3X3.asc".
    The window titled "Preview" gives an approximation of what the final
graph will look like, in this case, data is graphed as 3D blocks. For
example purpose, we will choose another type of graphic.
    Choose "Load..." (Amiga+T) from the "GraphType" menu. Another file
requester should appear. If JcGraph is correctly installed, a number of
file ending with ".grf" extension should be listed in the window. You can
now choose the type of graph that best suit your needs. For the example,
choose "3D_BrokenPlanes.grf" then "Load...". After a short period of time,
you should see the new graph type reflected in the Preview window. Note that
the wireframe representation of the preview window is used for real-time
manipulation, the final output is filled with colors.
    The actual three-dimensionnal perspective doesn't do justice to the 3D
effect, so we will rotate the graph using the interface window's gadgets.
There is two main section that divide the interface window:
1. To the left, there is two gadget labelled "Undo" and "Render". We will
discuss their respective function later.
2. To the right, there is 4 lines of gadgets. These ones control rotation
values and perspective of the graph.
    Line 1: Rotation around X.
    Line 2: Rotation around Y.
    Line 3: Rotation around Z.
    Line 4: Perspective control.

    For example purpose, we will not discuss these any further  (they are
described in section 5). For now, just select the first gadget from the top
(the rectangular one, with a "0" in it) and replace the "0" by "-30". Press
RETURN. Do the same with the next gadget, but this time, replace "0" by "30".
You will immediatly see the change in the preview window. The effect is a
lot more dynamic.
    Now, if you want to look at the final result, select the "Render" gadget
from the interface window. The mouse pointer will change for a longer period
of time. After a while, the pointer should get back to normal and you should
see the final result in the Output window. If it is obscured by another
window, just bring it to the front (but remember to click back in the
interface window in order to do any other manipulation on the graph).
    From here, there could some constatation:
1. It's nice (I hope so :-)
2. It's too small.
3. You don't like the colors.

We will solve all the problems, one at a time.
1. It's nice: That's not really a problem.
2. It's too small: Grab the sizing gadget (the one at the lower right of
the Output window) and drag it to the desired size. Now, re-press "Render"
and "voila!".
3. You don't like the colors: It is the next step.

Color choice:
Choose the "Color..." (Amiga+k) option under the "Edit" menu. A requester
named "Data color selector" should pop up. To the left, you should see all
available colors... to the right, the values to be colored. You will
probably recognize the texts associated with each line of value. There is
also two more entries named "Background" and "Floor" which will permits
respectively to change the colors of the background, behind the data and
the floor, under the data (compare with the final result for better
understanding). Select "Floor". A white rectangle will appear around the
selected area. Then, choose a color on the left. The little box at the left
of the "Floor" text should reflects the color you selected. When you are
satisfied with the color you choosed, click on the close gadget to validate
your entry (the one at the upper-left of the window). To see the result,
selct "Render" one more time.
    The final step is to save the file as "AegisDraw2000". To do so, select
"Draw2000" from sub-menu "Fromat..." from menu "Project" (Amiga+4). Then,
choose "Save as..." from "Project" (Amiga+A) that will pop up a file
requester asking for the file name of the resulting graph. Enter the name,
then press RETURN. The file should now be available for use in any
compatible software.
    For more detail on JcGraph function, go to section 4.

4.Menu options summary.
-----------------------
PROJECT
About...    :Info about JcGraph.
Open...     :Open a text file (Desciption in section 6).
Save        :Save the graph. Format is specified in "Format".
Save as...  :Same as "Save" but request a name.
Format      :Select the file output format :see section 7.
Print...    :Outputs to the printer.
             Beware, you will be asked only once if you want to "CANCEL".
Quit...     :Quit JcGraph...

EDIT
Undo        :Undo the last rotation.
Copy        :Not implemented.
Color       :Let you select color values.
            The cycle gadget at the bottom of the requester has two
            position, "Color" and "Grey scale". Grey scale will give you
            an approximation of what the printed result will look like.

TEMPLATE
Load...     :Load a template file wich contain:
             -the graph type.
             -rotation positions.
             -perspective.
Save...     :Save a template file.

GRAPHTYPE
Load...     :Charge un nouveau type de graphique 2D ou 3D.

ENVIRONMENT
Iconify     :Not implemented yet.
Notes...    :Let you leave a note on anything you want. If you
            press the icon at left, you will always be noticed of
            your note before quitting.
Arrange     :Organize windows logically on the screen.

HELP
General...  :General help system activation.
On Help...  :Activate help on using the help system.
Start Help  :Context-sensitive help. You just have to select the topic
             on wich you need help to get it. Select back the same              option (renamed Stop Helper) to stop.

5.Control panel window:
-----------------------
    The interface window (Control panel window) is the one with lots of
gadget on it.

1. The first line of gadget contain (from the right);identifier of the
rotation axis, 'X' in this case, a scroll gadget wich select the value of
the 'X' rotation and a string gadget which permits to enter the value
numerically. The two other line do the same thing but for the 'Y' and 'Z'
axes. Modification of any of the gadget updates the Preview window
automatically.
2. The slider gadget named "Perspective" will, as their name implies, will
change the perspective value; the more the cursor is sled to the left, the
more the graph will look "deformed" (like a camera with a fish-eye), to
opposite , sliding it to the right will yield in a more orthogonal-looking
graph. This effect is just for visualisation, so it, it will not be saved
in the "3D Geo" format.
5.The gadget titled "Undo" will undo the last rotation operation. Menu
option "Undo" (Amiga-Z) will do the same thing.
6.The "Render" gadget will gives you the final output on the screen.

6.File format: Input:
---------------------
    For now, JcGraph only accepts it's own file format. Depending on the
response from users (number of registration and suggestions, you know !),I
will evaluate if it is worth to make import filter/spreadsheet interface to
JcGraph.

Here is the texte file format description:

1002,                       1. Data identifier. Always 1002.
4,2,80,6.0,                 2. #Columns,#Lines,Cotation space, Multiplier
10,20,30,40,                3. First ligne
50,60,60,80,                4. Second line
Jan,Feb,Mar,Apr,            5. Text under each column.
Gaz,Oil,                    6. Text under each line.

Notes: All value may vary between -32768 and 32768.
       Data file should end with a comma.
       When the multiplier is 0, numbers take the
       integer form (ie without floating point).
       All entries should be comma separated but can be logically
       organized with "returns".

7.File format: Output:
----------------------
IFF ILBM:
File format compatible with most commercial an dpublic-domain paint program.

EPSF COLOR & GRAY:
Encapsulated PostScript file format. For now, it is the only format in wich the legend will be automatically created. Unless you have a PostScript interpreter, this file cannot be printed on printer other than PostScript compatible ones. By default, the font used is "Times-Roman". Si you want to output your graph to the printer and you possess a PostScript printer, just save it as EPSF. Then, type to a CLI/SHELL prompt "copy FileName to SER:" if your printer is hooked to the serial port or "copy FileName to PAR:" if it is hooked to the parrallel port. Select COLOR or GRAY EPSF format depending on your printer capability.

3D GEO:
Three-dimensionnal file format compatible with most 3D modeler and renderer on the market: 3DProfessionnal, VideoScape, LightWave, Vertex, etc...
Text are saved too!

Draw2000:
Structured file format compatible with the following software:
PageStream 2.2, Professionnal Page 3.0, AegisDraw2000. Will produce very
high quality graphs even on dot-matrix printer. Note that I had some problem
with the AegisDraw import module from PageStream. It seems not to recognize
JcGraph's output.I had the same problems with graphs created with Advantage
and Multiplot.

8.Graph's modification.
-----------------------
8.1 Font size.
    You can modify font size. You have to edit the graph type with an ASCII
editor. Font size for cotation is the third from the end of the ".grf" file.
Font size of the lines' text is the fourth, and the colums' the fith.
Complete description of the graph type should be available soon.

9.Keyboard equivalent.
----------------------
PROJECT
Amiga Droite+O :Open...
Amiga Droite+S :Save
Amiga Droite+A :Save as...
Amiga Droite+1 :Format IFF ILBM
Amiga Droite+2 :Format EPSF
Amiga Droite+3 :Format 3D Geo
Amiga Droite+4 :Format Draw2000
Amiga Droite+P :Print...
Amiga Droite+Q :Quit...

EDIT
Amiga Droite+Z :Undo
Amiga Droite+K :Color...

TEMPLATE
Amiga Droite+L :Load...
Amiga Droite+U :Save...

GRAPHTYPE
Amiga Droite+T :Load...

ENVIRONMENT
Amiga Droite+. :Notes...
Amiga Droite+R :Arrange...

HELP
Amiga Droite+G :General...
Amiga Droite+H :On Help...
Amiga Droite+J :Start Helper/Stop Helper

COLOR SELECTOR:
Flche droite: Select next color.
Flche gauche: Select preceding color.
Flche haut  : Select next line.
Flche bas   : Select preceding line.

NB: ESC will get you back from most requester.

10.TOOLTYPE and command line options.
-------------------------------------
SCREEN=custom       :Start JcGraph on a custom screen.
SCREEN=workbench    :Start JcGraph on the workbench.
HELPENGINE=file     :Where 'file' is the Help engine used by JcGraph.

11.The future of JcGraph:
-------------------------

    JcGraph is the first important piece of code I write for the Amiga. And
even if I spent much time to it's realisation, some features could not have
been implemented, because of a lack of time and funding (beeing a full time
student). So I privilegied quality over quantity. But, if the effort I put
in JcGraph would reflect in a high number of registration, I would probably
spend some more time upgrading it. Here is a list of what could be in a
future release:

-ProCalc, Advantage, MaxiPlan import filters...
-Full ARexx support with script for the Video-Toaster. HotLink with ADPro,
 PageStream
-Soft-Logik's HotLink support.
-Full "Amiga Interface Style Guide" compliance.
-IFF DR2D output.
-Support for Compugraphic fonts.

Any suggestion or comment can be send to:

            Jean-Christophe Clment
            921, rang 3
            St-Simon
            Qubec, CANADA
            J0H-1Y0

12.JcGraph's history:
---------------------

april 23 , 1992:(v0.90)
    -Beta release.

april 27 , 1992:(v0.901)
    -Corrected little mem alloc bug.

april 30 , 1992:(v0.902)
    -Added precision on 2D graphs.
    -Stack graph added.
    -Better support for floating point value.

may 14 , 1992:(v0.903)
    -Corrected one small problem with perspective.
