This option allows data to be read from a file and plotted on a buffer. Here we present the basic commands. For further information, consult the DigiPlot User Guide.
The file may contain commands in addition to multiple columns of data. Format of commands in the plot file are detailed below:
r0 r1 r2 r3 ... Columns of data to be plotted (real
coordinates). Which two columns are chosen
as the horizontal and vertical coordinates
depends on the X and Y selectors and
coordinate system type (see below). The
default is for pixel coordinates using r0
and r1.
A Draw the current two dimensional axes and
coordinate grid, using intensity 32.
A iColour Draw the current two dimensional axes and
coordinate grid, using the specified
intensity.
A3 Draw the current three dimensional axes and
coordinate grid, using intensity 255.
A3 iColour Draw the current three dimensional axes and
coordinate grid, using the specified
intensity.
AV [nPoints] Average the data over the specified number
of points. This feature is turned off
if AV is specified without a numeric
argument. If nPoints>1, then a point is
plotted only once every nPoints data
which are encountered and the point
plotted is the mean of the last nPoints
data encountered. Note that if there
are not a multiple of nPoints points in
total, the last group of input data will
not be plotted.
AX LINear
AX LOG [xOff] Specifies the type of axis to be used in
the x direction in two dimensional
plotting. AX LIN forces the x axis to be
linear. AX LOG [xOff] gives a logarithmic x
axis by transforming the x data by
LOG(x-xOff) prior to plotting. If xOff is
not specified, then xOff defaults to zero.
If xOff is specified, the coordinate limits
are also transformed by xOff.
Note the use of X iColumn [xOffset
[xScale [xExponent]]] (and the Y
equivalent) to transform the data only.
AY LINear
AY LOG [yOff] Specifies the type of axis to be used in
the y direction in two dimensional
plotting. AY LIN forces the y axis to be
linear. AY LOG [yOff] gives a logarithmic y
axis by transforming the y data by
LOG(y-yOff) prior to plotting. If yOff is
not specified, then yOff defaults to zero.
If yOff is specified, the coordinate limits
are also transformed by yOff.
Note the use of Y iColumn [yOffset
[yScale [yExponent]]] (and the X
equivalent) to transform the data only.
B buffer_number Start plotting on the specified buffer
number. The specified buffer will be made
the current output buffer. A negative buffer
number will cause plotting to be suppressed.
This is of use with the DigiPlot utility
which will normally be plotting to the
computer's monitor, but with which this
command may be used to direct output to
a frame buffer. Negative values have the
following functions:
-1 Stop plotting on frame buffer.
-2 Start plotting on computer
monitor.
-3 Stop plotting on computer
monitor.
B -4 PostScript_File Start plotting in a PostScript file.
B -5 Finish plotting with a PostScript file.
C xMin xMax yMin yMax Specify two dimensional coordinate system.
The x coordinate is horizontal, and the y
vertical. xMin corresponds to the left-hand
side of the screen, xMax to the right-hand
side, yMin to the bottom and yMax to the
top. Note that if the CL command is used,
the coordinate system must be redefined
after this command.
C3 xMin xMax yMin yMax zMin zMax Alpha Beta perspective
Specify three dimensional coordinate system.
The x and y axes lie in a nominally
horizontal plane, and the z axis vertical.
The axes are mapped onto a unit cube. The
unit cube is transformed by rotation about
the z axis by an angle Alpha (normally
negative, suggest -30ø), and then through
an angle Beta about the original location
of the x axis (normally positive, suggest
20ø). This gives an effective viewing
position somewhat above the horizontal
plane. The perspective parameter determines
the degree of perspective to be used. A
zero value turns perspective off, while a
positive value gives the effective distance
of the observer from the unit cube. If the
resulting plot appears "funny" and
incomprehensible, try increasing the value
of Perspective to approximately four times
xMax-xMin. Note that if the CL command is
used, the coordinate system must be
redefined after this command.
CL Clear (erase) current graphics screen. Note
that the coordinate system must be
redefined using the C or C3 command after
clearing the screen.
D Use default two dimensional pixel
coordinates. The origin is at the top left
corner of the buffer with the first
coordinate coordinate vertically downward,
ranging from 0 to 511 (PAL) or 0 to 479
(NTSC). The second coordinate is horizontal
ranging from 0 to 511.
E expression Evaluate and plot the expression. The
expression may be any valid function of X.
For example,
E 1+X*EXP(-X)
The X variable is varied from the current
axis minimum to maximum in 100 steps.
ES x_expression : y_expression
This plot instruction may be used to plot
a parametrically defined curve. The first
expression, written in terms of the
parameter S, gives the x value and the
second expression (also given in terms of
S) gives the y value.
EXY expression This is identical to the E plot command.
EYX expression This is similar to the E plot command
except that X is expressed as a function of
Y. For example
EYX Y*Y
would plot the function x=y*y using 100
steps for y.
E {xMin xMax} expression
EXY {xMin xMax} expression
EYX {yMin yMax} expression
ES {sMin sMax} expression
Optional form for the E plot instruction.
If {xMin xMax} is stated, then the
expression will be plotted only over the
parameter range stated.
F file_name Load the image specified by file_name into
the buffer and/or computer monitor. This
command has no effect for PostScript files.
G text Will produce a title for the graph using
the specified text. Different fonts and
character sizes may be included using the
following codes:
&R Switch to Roman font (default)
&I Switch to Italic font
&G Switch to Greek font
&N or &- Normal size (default)
&H or &^ Superscript
&L or &_ Subscript
&S Small font
&A Normal weight (default)
&B Bold
&& The ampersand (&)
character.
G3 text Produces title for 3D plot. Formatting
instructions are as for the G plot
instruction above.
I expression Sets the current plotting intensity to the
result of the expression specified. See the
entry for X below for further details on
expressions.
IA expression Sets the current plotting intensity so
that the pixel will be ANDed with the
result of the expression.
IO intensity Sets the current plotting intensity so
that the pixel will be ORed with the
result of the expression.
IS intensity Sets the current plotting intensity to the
result of the expression.
IX intensity Sets the current plotting intensity so
that the pixel will be XORed with the
result of the expression.
KT x y [iFont [intens]] title
Specify the location for the key and the
text for its title
KE text Specify the text for the next entry in the
key
L [iMarkType] Plot lines in two dimensions. This turns
off the P (points) option. However, if the
optional iMarkType is given, points will
also be plotted.
L3 Plot lines in three dimensions. This turns
off the P3 (points) option.
N Force the start of a new line in two
dimensions.
N3 Force the start of a new line in three
dimensions.
O output_LUT Specify the output look up table to be used
from now on. Any integral DigImage output
look up table may be used.
P Plot points, rather than lines, in two
dimensions.
P iMarkType Plot marks at specified points in two
dimensions. The mark types available are:
-1 No mark
0 Single point
1 Cross (x)
2 Plus (+)
3 Box
4 Diamond
5 Up triangle
6 Down triangle
7 Left triangle
8 Right triangle
P3 Plot points, rather than lines, in three
dimensions.
PC expression Plot the data specified by the X, Y (and
Z) plot instructions only if the
expression specified here evaluates to a
positive (nonzero) value.
PC Plot the data unconditionally - cancels a
PC expression plot instruction.
PL nPoints iFill Fill the 2D polygon defined by the next
nPoints coordintes using the intensity
iFill. The edge is drawn with the current
setting of intensity from the I command.
PL3 nPoints iFill Fill the 3D polygon defined by the next
nPoints coordinates using the intensity
iFill. The edge is drawn with the current
setting of intensity from the I command.
R [value0 value1 ...] file_name
Read data from the file name specified. When
this file is finished, then return to the
current file. This enables data to be read
multiple times from the same file, using a
separate file to control the process. Plot
files may be nested up to a maximum of 10
levels. As with !P files, the entry values
of !!0 to !!9 may be set on the line
containing the plot instruction.
RA [value0 value1 ...] file_name
RG [value0 value1 ...] file_name
RO [value0 value1 ...] file_name
RS [value0 value1 ...] file_name
Alternate forms of the R plot instruction
determining which variables are considered
local and which global for nested plot
files. The net result of the A, G, O and S
modifiers is identical to the
corresponding modifiers for the !P
command.
RI file_name This is identical to the R plot
instruction except that any plot
instructions occuring in file_name are
ignored rather than processed. Thus RI is
suitable for processing the data of one
plot file using the instructions of
another. Because all plot instructions are
ignored, RI files will not themselve be
able to call other plot files.
R3 nx ny surface_type file_name
Plot the three dimensional surface defined
by the data contained in file_name. The data
contains nx points in the x direction, and
ny in the y direction, ordered as (x0,y0),
(x0,y1),... The x, y and z data are retrieved
using the current X, Y and Z expressions.
The type surface plotted is given by the
integer surface_type:
0 Points on surface. Colour specified by
I expression.
1 Vertical lines from base to surface.
Colour specified by the I expression.
2 Wire frame, no hidden line removal.
Colour of frame specified by the I
expression.
3 Wire frame, hidden line removal, black
surface. Colour of frame specified
by the I expression.
4 Wire frame, hidden line removal, colour
of surface specified by the I
expression.
5 Wire frame, hidden line removal, colour
of surface dependent on orientation.
6 As for 5, but without drawing the wire
frame.
R3S[+|-[+|-]] nx ny surface_type file_name
The R3 and R4 plot instructions for
reading 3D surface plot data from a file
can now sort the data using the R3S and
R4S plot instructions. By default the data
will be sorted into ascending x and y. To
sort in a different order, add a plus or
minus to the end of the R3S or R4S
instruction. For example
R3S-+ 32 32 6 TEST.DAT
will sort the data in TEST.DAT into
descending x and ascending y order before
plotting the 32x32 points using surface
oriention shading. Note that the sorting
algorithm used is relatively simple and as
a result it may take a considerable period
of time to sort some large data sets.
R4 nx ny surface_type file_name
As for the R3... plot instruction, but
assumes the x,y,z data are in columns 1, 2
and 3 (respectively). Only surface_types
0 to 4 are supported and the intensity
specified by the I plot instruction must
be a constant.
R4S[+|-[+|-]] nx ny surface_type file_name
Optional data sorting for the R4 plot
instruction. For details refer to R3S and
R4.
S [weighting] Determines the basic statistics of the
data plotted since the last N plot
instruction. The statistics returned are:
!!R0 Mean of x data
!!R1 Mean of y data
!!R2 Standard deviation of x Data
!!R3 Standard deviation of y Data
!!R4 Correlation coefficient
!!R5
!!R6 Minimum value of x
!!R7 Value of y for minimum x
value. If more than one x,
then the first y is returned.
!!R8 Maximum value of x.
!!R9 Value of y for maximum x
value. If more than one x,
then the first y is returned.
!!Ra Value of x for minimum y
value. If more than one y,
then the first x is returned.
!!Rb Minimum value of y.
!!Rc Value of x for maximum y
value. If more than one y,
then the first x is returned.
!!Rd Maximum value of y.
If the optional weighting function is
specified (as a function of X and/or Y),
then the x and y data are weighted by
this function in the calculation of the
means, standard deviations and correlation
coefficient.
SF [&] yExpression : expression0 : expression1 : expression2 ...
Evaluate the Least Squares solution to the
data plotted since the last N command using
the equation specified by the list of
expressions.
The first expression is applied to the Y
data prior to fitting. Effectively we fit
to the data
F = yExpression(Y)
rather than Y itself. yExpression is quoted
in terms of Y (eg. Y or LOG(Y)). The F data
is then fitted by
f = a0*expression0 + a1*expression1 + ...
where a0,a1,... are the coefficients
evaluated by the least squares routine.
are fitted to the remaining expressions.
For example, to fit a quadratic to data in
columns 1 and 2,
...data...
SF Y : 1.0 : X : X*X
The fitted curve will then be plotted
out using the current intensity by the
without any further transformation by the
command
SP F
In addition to being available to plot the
fit using the SP instruction and print the
equation with SE, the coefficients are
available through the !!Rn return
variables. The first coefficient is
returned in !!R0, and the last in !!Rm,
where there are m+1 coefficients. The RMS
error is returned in !!Rm+1.
If the optional ampersand (&) is
included, then the x and y data are
interchanged before fitting. In this
case the yExpression should be
quoted in terms of X and the basis
functions in terms of Y.
SW [&] weighting : yExpression : expression0 : expression1 ...
This is a variant of the SF ... plot
command. Like SF it evaluates the least
squares fit of
f = a0*expression0 + a1*expression1 + ...
but minimises the sum of the squared
weighted residuals. The weight applied to
the residual for each data point is
determined by the "weighting" function.
The SF instruction is equivalent to SW
with the weighting function set to unity
(or some other positive constant).
If the weighting function evaluates to
less than 1e-12 then the corresponding
data point will not be included in the
least squares problem.
If the optional ampersand (&) is
included, then the x and y data are
interchanged before fitting. In this
case the yExpression should be
quoted in terms of X and the basis
functions in terms of Y.
SV [&] variableKey weighting : yExpression : expression0 :
expression1 ...
This is a variant of the SW plot
instruction where the name of the x, y and
F data may be specified by the plot file.
For example, if you wish to use A instead
of X, B instead of Y and C instead of F to
describe the independent, dependent and
transformed variables (respectively), then
set variableKey to ABC. The standard SW
plot instruction is equivalent to
variableKey set to XYF.The main use of
this plot instruction is in combination
with plot files generated by DigImage,
thus allowing more appropriate names to be
given to the x and y data.
If the optional ampersand (&) is
included, then the x and y data are
interchanged before fitting. In this
case the yExpression should be
quoted in terms of the first letter
in variableKey and the basis
functions in terms of the second
letter in variableKey.
SP [{sMin sMax}] [expression]
Plots out the curve generated by the
current least squares fit AFTER a call to
SF. The optional expression, given in
terms F, is intended to undo the
transformation specified by the first
parameter of SF. For example, if we were
to fit a power law, then we wish to fit a
straight line in LN(X) to F=LN(Y). This
may be achieved by
SF LN(Y) : 1.0 : LN(X)
and then plotted out by
SP EXP(F)
If the optional range {sMin sMax} is
given, then only the portion of the curve
falling in sMin<=x<=sMax is plotted.
SE x y [intens [iFont [text]]] Prints out the current Least
Squares fit. The text is positioned at
x,y. Optionally the intensity (default
128) and font (default 1) may be
specified. Normally the expression is
written in a form determined by the SF
and SP plot instructions. For example,
the power law fit shown above would be
presented as
Y=EXP(F); F=a+b*LOG(X); Erms=c
where a and b are the fitted constants
and c is the rms error in the fit. If
the optional text arguement is given,
then the expression up to and including
the second equals (=) symbol is replaced
by the text. For example, if SF
specifies a quadratic fit,then
SE 1 1 128 1 Fitted curve: Y=
would produce the text
Fitted curve: Y=a + b*X + c*X*X
SG yExpression : expression0 : expression1 ... : file_name
Fits the column data found in file_name
with y = ax0 + bx1 + ... where y, x0, x1,
... are evaluated from [n column
references by the expressions given by the
plot instruction. Note that unlike SF and
related plot instructions, SG uses column
references instead of x y data references.
Each of the fitted expressions (here given
by x0, x1, x2) may depend on the columns
in an arbitrary manner. The fitted
coefficinets, a, b, ... are returned in
!!R0, !!R1, ...
T x y iFont intens Text Prints the Text specified at the location
given by x,y (this corresponds to the
top-left corner of the first character
cell) using the font iFont with
the specified intensity intens:
0 to 255 => set
256 to 511 => OR with intens-256
512 to 767 => AND with intens-512
The font numbers are the same as for [T
Text] and <ctrl><f5>. Different fonts and
character sizes may be included using the
following two character codes:
&R Switch to Roman font
&I Switch to Italic font
&G Switch to Greek font
&N or &- Normal size
&H or &^ Superscript
&L or &_ Subscript
&& The ampersand (&)
character.
T3 x y z iFont intens Text
As for the T plot instruction, except that
adds the text at the three dimensional
location specified by x,y,z. In PostScript
plots, the text lies on the x-z plane (on
the computer monitor or frame grabber, it
appears in the viewing plane).
VC command Send the specified command directly to the
Super VHS VTR. The syntax of the command
depends on the model of VTR used. Lists
of appropriate commands may be found in
the DOCUMENT directory (e.g. in
DOCUMENT\AG7350.DOC for the Panasonic
AG7350). These are the same commands as
can be sent from [;VZ Send command to VTR]
in DigImage. Under most circumstances you
should use the VO plot instruction instead
as this is more intellegent and
independent of the make and model of VTR.
VO [iParameter] operation
Request the attached Super VHS VTR to
perform the specified operation. Some
operations may require the optional
iParameter to control details (e.g. search
speed). A list of the standard operations
is given below: operation iParameter
Description play start playing rec put
in record-pause mode pause 0 play-pause,
record-pause, audio dub-pause or
shuttle/still as appropriate to current
mode pause <>0 play-pause regardless of
current mode freeze equivalent to pause
with iParameter set to 0 unpause start
playing, recording or audio dubbing,
depending on current mode jog/shtl put
int shuttle/still mode dub put in audio
dub-pause mode rew rewind stop stop ff
fast forward adv nFrames move forwards (or
backwards) by the specified number of
frames, moving one frame at a time
shuttle speed shuttle forwards (positive)
or backwards (negative) at the specified
speed. If speed set to zero, then put in
shuttle/still mode
VR iStartBuffer nBuffers nFields
Record a sequence on video, starting with
the contents of buffer iStartBuffer.
After this has been recorded for nFields
video fields, move to the next buffer and
record this. Repeat this process until the
contents of nBuffers buffers have been
recorded. This command may be used for
animating sequences of plots.
W Text Writes the Text directly to the output
PostScript file, if opened.
WF File_name Appends the contents of the specified file
to the PostScript output file, if opened.
X expression Specifies how the x data should be formed
from the contents of the plotfile data. The
plotfile data will typically be arranged in
a number of columns. One or more of these
columns may be accessed to generate the
plotted data. A [ character followed by an
integer value is used to indicate the data
in the corresponding column should be used.
Expressions involving columns and/or
constants may be given, for example
X [1 + [3 * 4
Expressions are evaluated from left to
right. For the above example, the contents
of column 1 will be added to column three,
the result being multiplied by four before
use as the x axis data. Allowable
operators currently include + - * / ^
(exponentation), % (logical OR), & (logical
AND), $ (logical EOR) and brackets nested
up to 10 levels. The following functions of
one arguement are also supported (not case
sensitive):
LOG(..) Logarithm, base 10
LN(..) Natural logarithm
EXP(..) Exponential
SIN(..) Sine (angle in radians)
COS(..) Cosine (angle in radians)
TAN(..) Tangent (angle in radians)
ABS(..) Absolute value
SGN(..) Sign (-1 for negative, 1 for
positive and 0 for zero)
NOT(..) Logical NOT of integer part.
The [n column specifier may also be used
to access the ordinal position of the data
line within the plot. [0 gives the number of
data lines since the last N command (even
if the PC plot condition meant they were
not actually plotted), while [-1 gives the
ordinal position based on the points
actually plotted since the last N
instruction.
XE [expression] Specifies the x error bars for the data.
The size of the error bars is calculated
for each point using the specified
expression. If no expression is given,
then x error bars are suppressed.
XT text Places the specified text as the title for
the x (horizontal) axis. Different fonts
and character sizes may be included using
the following two character codes:
&R Switch to Roman font
&I Switch to Italic font
&G Switch to Greek font
&N or &- Normal size
&H or &^ Superscript
&L or &_ Subscript
&& The ampersand (&)
character.
X3 text Adds a title for the 3D x axis. Formatting
instructions are as for the XT plot
instruction above.
Y expression Specifies how the y data should be formed
from the contents of the plotfile data. See
above X entry for more details.
YE [expression] Specifies the y error bars for the data.
The size of the error bars is calculated
for each point using the specified
expression. If no expression is given,
then y error bars are suppressed.
YT text Places the specified text as the title for
the y (vertical) axis. For formatting, see
XT above.
Y3 text Adds a title for the 3D y axis. Formatting
instructions are as for the XT plot
instruction above.
Z expression Specifies how the z data should be formed
from the contents of the plotfile data. See
above X entry for more details. This only
has an effect for three dimensional
plotting.
Z3 text Adds a title for the 3D z axis. Formatting
instructions are as for the XT plot
instruction above.
# Comment Comment which is not printed.
!^ Comment Comment which is printed on the computer's
monitor.
!$ Comment Comment which is printed on the computer's
monitor. The user is then prompted to
"Press any key to continue...".
!& delay Causes the plotting to be delayed for the
period specified in seconds by delay. If
no period is specified, the delay is for
one second.
!n Use DigImage replaceable parameter n, where
n is an integer from 0 to 9. See the
<shift><f1> help facility for more details
on DigImage replaceable parameters.
!!n Use DigImage variable. DigImage variables
are available to plot files whether or not
a command file is in use. See the
<shift><f1> general help facility for more
details on DigImage variables. Note that
all variables (!!0 to !!9 and !!a to !!z)
are treated as global by the plot file.
DigImage plot files may also be displayed on the computer's own monitor without a frame grabber using the DigiPlot utility. A complete description of this utility may be found in the DigiPlot Users Guide. The main command line options are:
DigiPlot plot_file [/O output_LUT] [/B buffer_number]
[/P PostScript_File] [/K]
where plot_file is the name of the file containing the plotting data, output_LUT is an optional output look up table specification number (integer table number) and buffer_number is the DigImage buffer on which the plot is to be produced. If no /B specification is given, then the plot will be produced only on the computer's own monitor, while if /B is given, no output will be sent to the computer monitor. If no table given, then DigImage will use table 2. Note that output LUTs are only supported for colour VGA monitors. /P may be used to create a PostScript copy of the plot in the specified file.
A third method of starting the plotting facilities is provided by the command file directive
!PR plot_file [cmd_line_opts]
where plot_file is the name of the file to be plotted and cmd_line_opts are any of the normal DigiPlot command line options.
Note that while the !PR directive may be issued from anywhere within a command file, it may have unexpected side effects if issued from within a menu option.
Encapsulated PostScript (.EPS) and Data Only PostScript (.DPS) can not be printed directly, except using DigiFile. Normally they would be included within some other package (eg. a word processor) to be printed. The .DPS file is a special version of .EPS which does not contain the normal DigImage\PostScr\Header.PS and DigImage\PostScr\GraphVDU.PS header files. These may need to be added to the PostScript prolog used by the application into which the .DPS file is inserted.
If no extension is specified, then the default PostScript type specified in [;P Printers] in CONFIGUR.EXE will be produced, and the appropriate extension added.
This file may be sent to the printer immediately by specifying PRN as the file name.
The line and colour information is rendered using the method specified by the default setting in Configur.EXE. If you wish to render the plot using a different method, either change the plot reterospectively using DigiFile, or plot the file using either DigiPlot or !PR with the appropriate /C colour_type switch.