Detailed Contents
Introduction
Command Line
File Format
Plot Instructions
Expressions
Curve Fitting
Three-Dimensional Plots
PostScript Files
Appendix: Line Styles
Index
In this section we summarise the basic plot instructions
available to all forms of DigiPlot. Further examples of the use
of these plot instructions are given in later sections.
| Plot instruction | Effect |
| A [iColour] | Draw the current two dimensional axes and coordinate grid, using the specified intensity. If no intensity given, then a default of 32 is assumed. Note that for printer output, the axes and associated grid or tick marks and text are always drawn in black. |
| A3 [iColour] | Draw the current three dimensional axes and coordinate grid, using the specified intensity. If no intensity given, then 255 is assumed. As with the A plot instruction, for printer output, the axes and associated grid or tick marks and text are always drawn in black. |
| 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 | Indicates that the x axis is linear for two-dimensional plotting. This is the default axis type. |
| AX LOG [xOff] | Indicates that the x axis is logarithmic for two-dimensional plotting. If xOff is not specified, then xOff defaults to zero. If xOff is specified, then xOff is subtracted from the x data prior to evaluating the logarithm. The coordinate limits are also transformed by xOff so that the axis labels still correspond to the original x data. Use X expression to transform the data only. |
| AY LINear | Indicates that the y axis is linear for two-dimensional plotting. This is the default axis type. |
| AY LOG [yOff] | Indicates that the y axis is logarithmic for two-dimensional plotting. If yOff is not specified, then yOff defaults to zero. If yOff is specified, then yOff is subtracted from the y data prior to evaluating the logarithm. The coordinate limits are also transformed by yOff so that the axis labels still correspond to the original y data. Use Y expression 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 instruction may be used to direct output to a frame buffer. Negative values have the functions outlined below.
-1 Stop plotting on frame buffer -2 Start plotting on computer monitor -3 Stop plotting on computer monitor -4 PostScript_File Start plotting in a PostScript file -5 Finish plotting with a PostScript file.Normally with DigiPlot the /B... and /P... command line options will be used to determine which buffer the plot would be produced on, and whether PostScript output is produced. The B plot instruction will override any settings made with /B or /P and will be necessary when plotting directly from DigImage. |
| C xMin xMax yMin yMax | Specify the two-dimensional coordinate system. The x coordinate is horizontal, and the y vertical. The value 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 instruction is used, the coordinate system must be redefined before plotting any additional data. |
| C3 xMin xMax yMin yMax zMin zMax Alpha Beta perspective | Specify the three-dimensional coordinate system. The specified coordinates are mapped onto a unit cube with the x and y axes lying in a nominally horizontal plane, and the z axis vertical. The unit cube is transformed by rotation about the z axis by an angle Alpha (normally negative, suggest -20), and then through an angle Beta about the original location of the x axis (normally positive, suggest 30). This gives an effective viewing position somewhat above the horizontal plane. The perspective parameter determines the degree of perspective to be used. It gives an effective viewing distance from the plane of the origin in terms of the size of the unit cube. A zero value turns perspective off. Typically a value of around 2.0 gives a reasonable perspective. Note that if the CL instruction is used, the coordinate system must be redefined before plotting any additional data. |
| CL | Clear (erase) current graphics screen. Note that the coordinate system must be redefined using the C or C3 instruction after clearing the screen before plotting any further data. |
| D | Use default two dimensional pixel coordinates. The origin is at the top left corner of the buffer with the first 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 [{xMin xMax}] 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. If the optional {xMin xMax} is specified, then the X variable will be confined to the range xMin X xMax. |
| ES [{sMin sMax}] 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. If the optional {sMin sMax} is specified, then the S variable will be confined to the range sMin S sMax. |
| EXY [{xMin xMax}] expression | This is identical to the E plot instruction. |
| EYX [{yMin yMax}] expression | This is similar to the E plot command except that x is expressed as a function of y. For example
EYX Y*Ywould plot the function x=y2 using 100 steps for y. The optional {yMin yMax} may be used to restrict the y domain. |
| F file_name | Load the image specified by file_name into the buffer, computer monitor and/or PostScript. Any graphics already rendered will be erased by the image. However, any graphics rendered after the F command will appear on top of the image. |
| G text | Produces a title for the graph using the specified text. Different fonts and superscript/subscript may be included using the following two character codes:&R Switch to Roman font (default)
&I Switch to Italic font &G Switch to Greek font &N or &- Switch to normal size (default) &H or &^ Switch to superscript &L or &_ Switch to subscript &S Switch to small size &A Switch to normal weight (default) &B Switch to bold && The ampersand (&) symbol. |
| G3 text | Produce a title for the current three dimensional graph using the specified text. Different fonts etc. may be access in the manner outlined in the G plot instruction above. |
| L [iMarkType] | Plot lines in two dimensions. This turns off the P (points) instruction. However, if the optional iMarkType is given, points (marks) will be plotted in addition to the lines. See the P [iMarkType] plot instruction for details on mark type. |
| L3 | Plot lines in three dimensions. This turns off the P3 (points) option. |
| I expression | Sets the current plotting intensity to the result of the expression specified. See section 5 for details of DigiPlot expressions. Figure 1 shows how these intensities are mapped to different line styles under the /C 0 option, figure 2 under /C 1, figure 3 under /C 2 and figure 4 under /C 3 (the plot file used to generate this figure may be found in DigImage\PostScr\LineType.PLT). There are four supplimentary forms of this instruction for specifying how the intensity is combined with the intensities already plotted. These are:IA expression The current intensity of the pixel(s) will be Anded with the result of the expression.IO expression The current intensity of the pixel(s) will be Ored with the result of the expression.IS expression Sets the pixel(s) to the result of the expression. This is the default and will occur if the intensity is specified by I expression.IX expression The current intensity of the pixel(s) will be eXclusive ored with the result of the expression.Note that when plotting on the computer monitor it is not possible to combine the intensity with what has already been plotted. Thus all the above options are equivalent to the IS plot instruction. |
| IE [expression] | Specifies the intensity to be used for the error bars selected by XE expression or YE expression. If error bars are not in use, then this instruction will be ignored. If IE is given without the optional expression, then the error bars will be plotted with the intensity determined by I expression (see above); this is the default behaviour. See section 5 for details of DigiPlot expressions. |
| KE text | Add text plus current plot type to symbol key. The text is added to the right and centred on the type of object currently used to plot the data. If error bars are in use, then they too will be displayed. Each successive call to KE produces a new line in the key table, located below the preceeding line. |
| KT x y [iFont [iColour]] text | Sets up a key table in the plot at the location specified by x and y in the plot's coordinate system. The key table consists of the title text specified here, and one or more lines under this. Each line is specified by its own KE text plot instruction. As an option, the font and font colour may be specified, as for the T plot instruction. |
| N [expression] | Force the start of a new line or new set of data in two dimensions. If the optional expression is given, then the new data set will be forced whenever expression evaluates to a nonzero value. |
| N3 [expression] | Force the start of a new line in three dimensions. If the optional expression is given, then the new data set will be forced whenever expression evaluates to a nonzero value. |
| O output_LUT | Specify the output look up table to be used from now on. This overrides the setting of the /O switch on the instruction line. |
| P iMarkType | Plot marks at specified points in two dimensions. The mark types available are:
-1 No points (ignore data) 0 Single point 1 Cross (x) 2 Plus (+) 3 Box 4 Diamond 5 Up triangle 6 Down triangle 7 Left triangle 8 Right triangle 9 Star (*) 10 Horizontal centre arrow 11 Vertical centre arrow -1 No mark plotted |
| P3 [iMarkType] | Plot marks at specified points in three dimensions. The mark types are as for the P iMarkType instruction. |
| 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. Note that in DigImage and DigiPlot, a logical false is represented by 0, while logical true by 1. Thus data will be plotted for an expression evaluating to true, and will not be plotted for false. To cancel the conditional plotting invoked by this plot instruction, issue the PC without any expression. |
| PL nPoints iFill | Fill the 2D polygon defined by the next nPoints coordinates using the intensity iFill. The edge is drawn with the current setting of intensity from the I instruction. |
| 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 instruction. |
| R [value0 value1 ...] ["string0" "string1" ...] 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 ten levels using this mechanism. Note that if the specified file is not found in the current directory, then DigiPlot will search for it in the directory specified by the [;ZP Set command file search path] option of DigImage. If the file is still not found, an error message will be generated. The entry values of the numeric and string variables may be set prior to the call, or on the line containing the plot instruction by specifying the optional value0 for !!0, value1 for !!1, etc. If fewer than ten values are given, then the corresponding variables retain their previous values. The string variables are handled in a similar manner.Both numeric and string variables are treated as local to the called plot file in a manner identical to normal command files. Values changed within file_name will be reset on return to the calling plot file. These values remain accessible, however, through the !!Pn and !Pn mechanisms.These variable scope rules may be overridden using the RA, RG, RO or RS varients of this command. |
| RA [value0 value1 ...] ["string0" "string1" ...] file_name | As for R but the numeric variables !!a to !!z are treated as global. |
| RG [value0 value1 ...] ["string0" "string1" ...] file_name | As for R but all variables (!!0 to !!9, !!a to !!z and !0 to !9) are treated as global. |
| RO [value0 value1 ...] ["string0" "string1" ...] file_name | As for R but the numeric variables !!a to !!z and the string variables !0 to !9 are treated as global. |
| RS [value0 value1 ...] ["string0" "string1" ...] file_name | As for R but the string variables !0 to !9 are treated as global. |
| RI file_name | This is identical to the R plot instruction except that any plot instructions occurring 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 themselves 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 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.DATwill 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): it ignores the X, Y and Z plot instructions. 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 The number of points!!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!!Re The mean of the weighting function.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 instruction 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 Fi = f(yi),rather than y itself. The function f(y) is quoted in terms of y (e.g. Y or LOG(Y)). The F data is then fitted by G(x) = a0g0(x) + a1g1(x) + … + am1gm1(x),where a0, a1, … are the coefficients evaluated by the least squares routine and g0(x), g1(x), ... describe the form of the fitted function G(x). In addition to being available implicitly to other plot instructions, 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 (the square root of: the residual sum of squares divided by the number of points) 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 g(..) in terms of Y. For further details, see section 6 . |
| SW [&] weighting : yExpression : expression0 : expression1 : expression2 ... | This is a variant of the SF plot instruction. As with SF we fit G(x) = a0g0(x) + a1g1(x) + … + am1gm1(x),to Fi = f(yi),but minimise the sum of the squares of the weighted residuals. Each residual ri = f(yi) G(xi) is multiplied by the weighting function weighting prior to squaring, summation and minimisation. If the weighting function evaluates to less than 1012 then it is set to zero and the corresponding data point is not used in the evaluation of the fit.The SF plot instruction is equivalent to SW with weighting set to unity (or any other positive constant). As with SF the coefficients are available in !!R0 to !!Rm (for m+1 coefficients) and the rms error in !!Rm+1. The optioan ampersand (&) may again be used to interchange x and y data. |
| SV [&] variableKey : weighting : yExpression : expression0 : expression1 : expression2 ... | 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 in user-supplied expressions.As with the other forms, the fitted coefficients are available through !!Rn variables and the data may be interchanged with the optional ampersand (&). |
| 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. By default the fitted curve will be plotted out for the entire range of x (or y, as appropriate). However, if the optional {sMin sMax} range specifier is given, the plotting will be restricted to sMinxsMax. For further details, see section 6 . |
| SE x y [intens [iFont [text]]] | Prints out the expression determined by the current least squares fit. The text is positioned at the point given by 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 asY=EXP(F); F=a+b*LOG(X); Erms=cwhere a and b are the fitted constants and c is the rms error in the fit. If the optional text argument 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, thenSE 1 1 128 1 Fitted curve: Y=would produce the text Fitted curve: Y=a+b*X+c*X*X; Erms=e |
| SG yExpression : expression0 : expression1 : .. : file_name | General (linear) least squares fit of data read from a file. This plot instruction models the column-oriented data found in file_name as x = a0z0 + a1z1 + a2z2 + …The specified yExpression is formulated using column references of the form [2 and is used to evaluate x from column data found in file_name. Similarly the zi are calculated from the corresponding expression0, expression1, …. The initially unknown ai are obtained by a linear least squares fit to the data and then returned in !!R0, !!R1, …. The ability to access the data columns directly makes SG a more general tool than SF (and related instructions) in that it provides access to a broader scope of independent variables. , but requires additional work and the data file to be re-read.Any comments, command file variables or directives found in file_name will be treated in the normal manner. Any plot instructions found in the data file will be ignored. |
| 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 [;DCT Text] and <ctrl><f5> within DigImage.Refer to the G plot instruction for details of embedded character formatting. |
| T3 x y z iFont intens Text | Prints the Text at the specified three-dimensional location given by x,y,z (this corresponds to the top-left corner of the first character cell) using the font iFont with the specified intensity intens. Details of the intensity and font are similar to the T plot instruction above. In PostScript plots the text lies on a y = const. plane in the transformed coordinate space. On the computer monitor or frame grabber the text lies in the viewing plane.Refer to the G plot instruction for details of embedded character formatting. |
| 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 Frames 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 Text directly to the output PostScript file, if opened. This enables specific PostScript commands or parameters to be set. For further details, refer to section 8 . |
| WF File_name | Appends the contents of the specified file to the PostScript output file, if opened. Refer to section 8 for further details. |
| 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. Refer to section 5 for further details. |
| 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 which may be a function of the column specifies [1, [2 etc. 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.Refer to the G plot instruction for details of embedded character formatting. |
| X3 text | Places the specified text as the title for the three-dimensional x axis.Refer to the G plot instruction for details of embedded character formatting. |
| Y expression | Specifies how the y data should be formed from the contents of the plotfile data. See above X entry and section 5 for more details. |
| YE [expression] | Specifies the y error bars for the data. Refer to XE above for further details. |
| YT text | Places the specified text as the title for the y (vertical) axis.Refer to the G plot instruction for details of embedded character formatting. |
| Y3 text | Places the specified text as the title for the three-dimensional y axis.Refer to the G plot instruction for details of embedded character formatting. |
| Z expression | Specifies how the z data should be formed from the contents of the plotfile data. See above X entry and section 5 for more details. Unlike X and Y, Z only has an effect for three dimensional plotting. |
| Z3 text | Places the specified text as the title for the three-dimensional z axis.Refer to the G plot instruction for details of embedded character formatting. |
| # 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 string variable n, where n is an integer from 0 to 9. The string variable should be initialised before use except when the file is plotted from DigImage when it can pick up the parent value from DigImage. See the System Overview for more details on DigImage string variables. |
| !!n | Use DigImage variable. See the System Overview 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 and are substituted prior to processing any plot instruction or data line containing them. |
Goto next document (Expressions)
DigImage documentation page
DigImage home page
Stuart Dalziel's home page