home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
The World of Computer Software
/
World_Of_Computer_Software-02-385-Vol-1of3.iso
/
t
/
triplt10.zip
/
TRIPLOT.DOC
< prev
next >
Wrap
Text File
|
1992-07-13
|
27KB
|
727 lines
=================================================================
Version 1.00 TriPlot(tm) July 13, 1992
(C) Copyright 1992, Yves Beaudoin
All Rights Reserved
DOCUMENTATION
=================================================================
TABLE OF CONTENTS
~~~~~~~~~~~~~~~~~
1. OVERVIEW . . . . . . . . . . . . . . . . . . . . . . . . . 2
2. PREPARING A DATA FILE . . . . . . . . . . . . . . . . . . 3
2.1 Title . . . . . . . . . . . . . . . . . . . . . . . 4
2.2 Output device code . . . . . . . . . . . . . . . . . 5
2.3 Output orientation . . . . . . . . . . . . . . . . . 5
2.4 Legend code . . . . . . . . . . . . . . . . . . . . 5
2.5 Corner code . . . . . . . . . . . . . . . . . . . . 6
2.6 Grid code . . . . . . . . . . . . . . . . . . . . . 6
2.7 Zonation code . . . . . . . . . . . . . . . . . . . 7
2.8 Normalization . . . . . . . . . . . . . . . . . . . 7
2.9 Bottom-edge label . . . . . . . . . . . . . . . . . 7
2.10 Left-edge label . . . . . . . . . . . . . . . . . . 7
2.11 Right-edge label . . . . . . . . . . . . . . . . . 7
2.12 Data records . . . . . . . . . . . . . . . . . . . 8
3. RUNNING TRIPLOT . . . . . . . . . . . . . . . . . . . . . 9
TriPlot(tm) Documentation Version 1.00
-----------------------------------------------------------------
1. OVERVIEW
~~~~~~~~~~~
TriPlot generates HP-GL/2 instructions for plotting
three-component data on a ternary diagram. HP-GL/2 is the new
standardized version of the Hewlett-Packard Graphics Language.
It is available, for example, with HP's series of LaserJet III
printers and DraftMaster plotters. The plot commands may be
redirected to a file for processing at a later time.
The user can specify a title and the labels for the edges of
the diagram. A legend describing the number of data points
plotted with a specified symbol and pen code can be optionally
selected. The resolution of the grid system can be selected from
five possibilities.
Currently, there are two zonation schemes built into
TriPlot, namely the soil textural zones defined by the Canadian
Soil Survey Committee (1978) and those published by Shepard
(1954). If you would like to see a particular well-established
scheme made part of TriPlot, just forward to the author the
values of the end points that make up the zone boundaries and a
diagram of the scheme.
The complete diagram can be plotted, or you can constrain
the plot to an apex. Note in passing that all line segments such
as zonation boundaries will be properly clipped for any corner
plot.
TriPlot can normalize the data to 1, 10, or 100. Normalized
data points have their component values adjusted so that their
sum is equal to 1, 10, or 100.
Each data point can have a symbol and a color/pen associated
with it. There are eight possible pen selections and eight
possible symbols. There is a ninth symbol-code available for
omitting the representation of a data point. This symbol-code
must be used when designating the end point of a line segment.
The total number of data points and line-segment end points
must not exceed 1000.
-----------------------------------------------------------------
(C) Copyright 1992, Yves Beaudoin 2
TriPlot(tm) Documentation Version 1.00
-----------------------------------------------------------------
Plot size is strictly dependent on the output media size.
The same plot file can be directed to an HP LaserJet III with
letter-size paper or to an HP DraftMaster SX+ with E-size paper
mounted. The resulting diagram will be automatically adjusted to
fit up to the hard-clip limits of the device, and, accordingly,
be expanded or contracted.
2. PREPARING A DATA FILE
~~~~~~~~~~~~~~~~~~~~~~~~
An input data file for Program TriPlot must be a DOS text
file conforming to a specific structure. There are two major
sections to any data file. The first section consists of the
plotting options and the labels for the ternary diagram. The
second section groups the data components and their display
codes.
An example is provided by TEST.DAT, one of the many data
files used to develop TriPlot. If you examine this file, you can
see the two major sections. Moreover, you'll notice that each
record has a row or column heading associated with it. Though
not required, the headings help interpret the subsequent
alphanumeric entries and, therefore, make the data file more
understandable.
To help you set up a data file, the distribution package
includes the file TEMPLATE.DAT. As suggested by its name, the
file is a data-entry template containing all the record field
headings mentioned above.
To illustrate its use, suppose that we want to set up a data
file to be called MYDATA. The first step is to use the DOS COPY
command to duplicate the contents of the template file to MYDATA.
After making the TriPlot directory the current one, enter the
following command:
COPY TEMPLATE.DAT MYDATA /V
where the /V switch instructs DOS to verify that MYDATA was
written correctly. The next step is to load MYDATA into a text
editor, such as the MS-DOS EDLIN or EDIT program, to enter the
plotting parameters and your data. Note in passing that if you
use a word processor instead, it should be configured to emulate
a text processor. The left margin must correspond to Column 1
and the right one to Column 80 or more. The top and bottom
-----------------------------------------------------------------
(C) Copyright 1992, Yves Beaudoin 3
TriPlot(tm) Documentation Version 1.00
-----------------------------------------------------------------
margins must be inactive. Headers and footers are not allowed.
Finally select a monospace font, such as Courier, to ensure that
your entries are aligned properly and remain so after you save
them to disk.
If the aforementioned operations have been carried out
successfully, the file MYDATA consists of the following twelve
lines:
Title (30 chars. max):
Output device code (0-1):
Output orientation (-90,0,90):
Legend code (0-1):
Corner code (0-3):
Grid code (0,10,20,40,50,100):
Zonation code (0-2):
Normalization code (1,10,100):
Bottom-edge label (20 chars. max):
Left-edge label (20 chars. max):
Right-edge label (20 chars. max):
Bottom---Left---Right---Symbol(0-8)---Pen(1-8)---Linkage
Each line of the data file makes up a record. Information
enclosed between parentheses represents the constraints or
admissible values for a particular record or field.
The first eleven records make up the first major section.
The first record is for the title of the plot. Records #2 to #8
are for specifying the plotting options. Records #9 to #11 are
dedicated to the labels of the diagram. For these records, input
always begins at Column 35 immediately following the colon.
The second major section begins with Record #12. This line
is present solely for providing the column headings describing
the subsequent data entry sequence. The component values and
their display codes are entered in a tabular fashion, after
Record #12.
Descriptions and constraints for each record are as follows:
2.1 Title
~~~~~~~~~
The first record is for the title of the plot that will
appear above the top apex of the diagram. There is a limit of
thirty characters.
-----------------------------------------------------------------
(C) Copyright 1992, Yves Beaudoin 4
TriPlot(tm) Documentation Version 1.00
-----------------------------------------------------------------
2.2 Output device code
~~~~~~~~~~~~~~~~~~~~~~
The second record is for specifying the output-device type.
The possible values and their corresponding meanings are:
Code | Interpretation
------+--------------------------------------------
0 | Plotter with a maximum capacity of 8 pens
1 | Monochrome printer such as a laser printer
The purpose of this option is as follows. As explained in
Section 2.12, the data points on the diagram can be distinguished
by symbol and by colour when using a plotter. If you take
advantage of this feature when you create your data file but then
send the output to a laser printer, the colour distinction will
be lost of course. With the output device code set to 1 on the
other hand, Triplot will override all colour settings to black
and adjust the legend accordingly by grouping the data points by
their symbol codes only. It is faster to change this one record
than to modify all the colour codes for the data points.
2.3 Output orientation
~~~~~~~~~~~~~~~~~~~~~~
The third record is for assigning an orientation to the
plot. The following table defines the possible rotations:
Code | Interpretation
------+--------------------------------
-90 | Rotate the plot by -90 degrees
0 | No rotation
90 | Rotate the plot by +90 degrees
This option allows you to select a portrait or a landscape
orientation to the output.
2.4 Legend code
~~~~~~~~~~~~~~~
The fourth record is for toggling the legend. The
associated code is defined as follows:
Code | Interpretation
------+-----------------
0 | No legend
1 | Draw the legend
-----------------------------------------------------------------
(C) Copyright 1992, Yves Beaudoin 5
TriPlot(tm) Documentation Version 1.00
-----------------------------------------------------------------
The legend is drawn to the left of the ternary diagram and
consists of the following features:
o the name and version number of the program,
o the date and time the plot was created,
o a listing of the coloured symbols used along with a
frequency count of the corresponding data points,
o a listing of the pens mounted in the carousel if the
output device code is set to 0.
Finally a frame is drawn which encloses the legend and the
diagram.
2.5 Corner code
~~~~~~~~~~~~~~~
Record #5 is for the corner code defined as:
Code | Interpretation
------+-----------------------------------
0 | Plot the whole diagram
1 | Plot the bottom left corner only
2 | Plot the top corner only
3 | Plot the bottom right corner only
Note in passing that when zooming in to a corner of the diagram,
all zonation boundaries, tie lines, and line segments will be
clipped accordingly.
2.6 Grid code
~~~~~~~~~~~~~
The next record is for choosing a predefined grid system.
Admissible values and their actions are:
Code | Interpretation
------+---------------------------------------------
0 | No grid
10 | Very coarse grid (10 subintervals per edge)
20 | Coarse grid (20 subintervals per edge)
40 | Medium grid (40 subintervals per edge)
50 | Fine grid (50 subintervals per edge)
100 | Very fine grid (100 subintervals per edge)
The corresponding annotation is controlled by TriPlot.
Regardless of the value of the grid code, there will always be
nine annotation labels per edge.
-----------------------------------------------------------------
(C) Copyright 1992, Yves Beaudoin 6
TriPlot(tm) Documentation Version 1.00
-----------------------------------------------------------------
2.7 Zonation code
~~~~~~~~~~~~~~~~~
The seventh record is for specifying which zonation scheme
to superimpose onto the plot:
Code | Interpretation
------+-----------------------------------------------
0 | No zonation
1 | Soil textural zones defined by the Canadian
| Soil Survey Committee (1978)
2 | Soil textural zones defined by Shepard (1954)
If you use other well-established zonation schemes, send us the
details and they will be incorporated into the next version.
2.8 Normalization
~~~~~~~~~~~~~~~~~
Record #8 allows you to indicate how the component data is
to be normalized:
Code | Interpretation
------+-----------------------------------
1 | Set the data component sum to 1
10 | Set the data component sum to 10
100 | Set the data component sum to 100
2.9 Bottom-edge label
~~~~~~~~~~~~~~~~~~~~~
Record #9 is the label for the bottom edge of the triangular
diagram: there is a maximum of twenty characters allowable.
2.10 Left-edge label
~~~~~~~~~~~~~~~~~~~~
Record #10 is the label for the left edge of the triangular
diagram: there is a maximum of twenty characters permitted.
2.11 Right-edge label
~~~~~~~~~~~~~~~~~~~~~
Record #11 is the label for the right edge of the triangular
diagram: there is a maximum of twenty characters allowable.
-----------------------------------------------------------------
(C) Copyright 1992, Yves Beaudoin 7
TriPlot(tm) Documentation Version 1.00
-----------------------------------------------------------------
2.12 Data records
~~~~~~~~~~~~~~~~~
Record #12 consists of column headings for the remaining
data records: it is provided solely to facilitate subsequent data
entry.
Record #13 is associated with the first data point. It is
made up of six numeric fields that correspond to the six headings
of Record #12. The first three fields are the coordinate
components corresponding to the bottom edge, the left edge, and
the right edge of the diagram in that order. The remaining
fields are for the symbol, pen, and linkage codes. All field
entries are separated from each other by blank spaces.
The various symbol codes will result in the following
representations of the data points:
Code | Representation
------+----------------------------------------
0 | No symbol: used in conjunction with
| the linkage code to draw line segments
1 | Circle
2 | Square
3 | Triangle
4 | Diamond
5 | Dot, i.e. filled circle
6 | Filled square
7 | Filled triangle
8 | Filled diamond
The integer pen codes designate the pen stall from which the
pen will be selected. For a plotter, the limit is normally
eight. Thus, TriPlot conforms to this maximum value. On a
monochrome output device, only "Pen #1" is available. However,
remember that TriPlot will automatically override a pen code
greater than 1 if the output device code has been set to 1. Note
that "Pen #1" is always used to draw the grid system and the
annotation.
The last record field is for an integer value (in the range
-32768 to 32767) describing the linkage code. Its purpose is to
allow tie lines and/or line segments to be included in the plot.
A linkage code value equal to zero isolates the data point. Any
two consecutive data points with the same non-zero linkage code
value are deemed to be linked by a tie line. Moreover if the
symbol codes are zero, the result will be a line segment.
-----------------------------------------------------------------
(C) Copyright 1992, Yves Beaudoin 8
TriPlot(tm) Documentation Version 1.00
-----------------------------------------------------------------
Therefore, the following entries in a data file
Bottom---Left---Right---Symbol(0-8)---Pen(1-8)---Linkage
30. 30. 40. 1 4 1
34. 25. 41. 3 4 1
will result in a tie line, that is, a line segment between the
circle symbol of the first point and the triangular
representation of the second point. On the other hand, the
entries
Bottom---Left---Right---Symbol(0-8)---Pen(1-8)---Linkage
30. 30. 40. 0 4 1
34. 25. 41. 0 4 1
will only produce a line segment. Accordingly, you can
incorporate any zonation scheme into the ternary diagram. But,
as remarked previously, the author will update TriPlot with any
well-established zonation scheme provided that a complete
description is sent.
Record #14 and subsequent records are for the remaining data
points, each structured as explained previously. Note in passing
that you can delimit groups of data records using blank lines:
these extra lines will be ignored by TriPlot.
Once you have specified all the plotting options and entered
your data, save the information back to disk overwriting the
original file, e.g., MYDATA. If you are using a word processor,
insure that the file is saved as a DOS text file. You are now
ready to process your data file.
3. RUNNING TRIPLOT
~~~~~~~~~~~~~~~~~~
There are two ways of starting the execution of Program
TriPlot, depending on where the output results are to be
directed. At the DOS command line, you can enter either
TriPlot DataFileName OutputFileName
or
TriPlot DataFileName OutputDevicePort
-----------------------------------------------------------------
(C) Copyright 1992, Yves Beaudoin 9
TriPlot(tm) Documentation Version 1.00
-----------------------------------------------------------------
where,
DataFileName is the name of the data file,
OutputFileName is the name of the file to which the results
will be written,
OutputDevicePort is the name of the device port to which the
results will be sent, e.g., COM1 for a plotter connected to
the first serial port. If required, use the DOS MODE
command beforehand to configure the port.
Note that file names may be prefixed with a path specification.
The following names are reserved for the operating system
devices:
Name | Device
------+-------------------------------
AUX | Communications port (COM1)
COM1 | Communications port
CON | Keyboard and screen
ERR | Standard error output (screen)
LINE | Communications port (COM1)
LPT1 | Printer
NUL | Null device
PRN | Printer (LPT1)
USER | Keyboard and screen
The connection is always to the device, even if a disk file with
the same name already exists, regardless of its extension.
Consult your DOS manual for more information if these port
designations are unfamiliar.
As an example of the output file name usage, the command
TRIPLOT TEST.DAT B:TEST.PLT
instructs TriPlot to retrieve the data file TEST.DAT on the
current logged-on drive and to store the resulting HP-GL/2
commands into the file TEST.PLT on Drive B:. If TEST.PLT exists
beforehand, TriPlot would seek your permission to overwrite with
the new output results. On the other hand, to process the data
file MYDATA and to direct the results to a laser printer
connected through the first parallel port, the following command
would be issued:
-----------------------------------------------------------------
(C) Copyright 1992, Yves Beaudoin 10
TriPlot(tm) Documentation Version 1.00
-----------------------------------------------------------------
TRIPLOT MYDATA LPT1
If your HP laser printer should generate a "21 PRINT OVERRUN"
error message, you'll have to set the "Page Protection" feature
(see the printer's user manual for more details). Once page
composition is finished, you must issue a form-feed command.
As TriPlot sequently reads and processes the data file, the
various options will be echoed to the screen. Wherever
applicable, short interpretations will also be included.
Many error traps have been built into TriPlot to detect
erroneous entries in the data file or problems with disk-related
operations. Corresponding messages will be printed to the
screen. TriPlot will continuously update the total number of
data records successfully read. Thus the location of an
incorrect record can be inferred readily. During debugging, you
can direct the output to NUL, the black-hole of DOS device-
drivers, to suppress plotting or to CON to see the resulting HP-
GL/2 commands.
If everything goes smoothly, you'll see the message "Done!"
appear as the last line on the screen.
-----------------------------------------------------------------
(C) Copyright 1992, Yves Beaudoin 11