---------------------------------------------------------------------------- LAPLOT.TXT ---------------------------------------------------------------------------- Descriptions of the arguments and subroutines in subroutine suite LAPLOT ---------------------------------------------------------------------------- COMPUTER : Digital PDP 11 with serial interface PLOTTER : Apple LaserWriter LANGUAGE : RT11 Fortran IV and Macro AUTHOR : Chris Bertram Centre for Biomedical Engineering, University of New South Wales, Australia ----------------------------------------------------------------------------- HISTORY:- Plotting routines by Neil Bacon of the C.S.I.R.O. were used by Rupert K.C. Mok of the C for BME to generate a subroutine suite called WAPLOT for use with a Watanabe WX4675 pen plotter. The suite was subsequently modified by C.D.B., then used as the basis of a similar suite for the LaserWriter, to the extent that the low-level operations use the Watanabe code numbers, e.g. I for relative draw. It was intended that the two suites be similar except at the lowest levels, but the project involved a re-writing of the existing low-level routines for the Watanabe which has not happened, and the LAPLOT suite now includes features (e.g. symbols) which were not present in WAPLOT. SPECIFICATIONS:- (1) Number of axes: a maximum of 8 in either direction (horizontal or vertical), or any combination giving a total number less than 9, can be drawn. (e.g. 4 vertical axes and 2 horizontal axes giving a total of 4*2=8) (2) Number of waveforms: a maximum of 8 waveforms can be plotted on each pair of axes. (3) Time scale: is always on the x-axis; if 'time' (xtimod(i)) is less than 0. (no specified value), a normalised range from 0.0 to 1.0 is assumed. [see also the description of xtimod below] The latest version allows X-Y & T-Y plots on the same graph (piece of paper) but not on the same axes. (4) X-Y plot: {a}. on each pair of axes, a maximum of 8 pairs of different x-y plots can be obtained; the channels chosen for x or y can be interchanged and repeated between x and y. {b}. if more than one waveform is plotted in one set of axes, the upper and lower bounds are the overall values for all waveforms which share the same axis. (5) In one LAPLOT subroutine call, both X-Y plots and T-Y plots can be chosen for different pairs of axes on the one piece of paper. (6) Each pair of axes is assigned to a particular number in such a way that the left hand upper corner is no. 1, the one below it is no. 2, and so on. The number is increased downward and then further increased when it goes to the next row. ------------------------------------------------------------------------------ SUBROUTINE CALL:- call laplv (nax,nay,xtimod,wave,npnt,join,ixchn, & iychn,xtil,ytil,gtil,curtil,isym) ---------------------------------------------------------------------------- DIMENSIONS:- xtil(i,j), ytil(i,j), gtil(j) i: the assigned axes number j: buffer capacity for the titles ixchn(i,k), iychn(i,k), join(i,k), curtil(k), npta(i,k), isym(i,k) i: the assigned axes number k: the plotted waveform number e.g. ixchn(2,4)=7; in the 2nd pair of axes, the 4th plotted waveform is chosen from channel 7 in the array 'wave' for x axis. n.b. curtil is a double precision array xtimod(i) i: the number of the x-axis wave(l,m) is a single-precision (double in WAPLOV) real virtual array l: the channel number m: storage capacity of that channel m can be modified according to the amount of memory available. If m is changed, subroutine MXNPNT (VXNPNT for virtual arrays) also has to be modified accordingly. Note: Do not confuse m with the axes number i, the waveform number k and the channel number l. Each pair of axes can have up to eight waveforms. Each waveform is made up of one channel of data in a T-Y plot or 2 channels of data in an X-Y plot. At present, the dimensions are i = 8 j = 7 (10 in gtil) k = 8 l = 8 m = 1281 (641 in WAPLOV) so that the necessary dimension statements in the calling program are:- virtual wave(8,1281) real*8 curtil(8) real*4 xtil(8,7),ytil(8,7),gtil(10),xtimod(8) integer*2 ixchn(8,8),iychn(8,8),join(8,8),npta(8,8),isym(8,8) where dimension can replace real*4 and integer*2 in the above according to taste. The subroutine LAPLXY is an alternative to LAPLV in which these dimensions are varied to allow up to 16 different curves, each with a different symbol type, on one XY-plot. Whereas WAPLOT and its derivatives as far as LAPLV are intended to be incorporated into the user's own program, a calling program called XYPLOT is provided for use with LAPLXY where data are to be entered manually. ---------------------------------------------------------------------------- ARGUMENTS:- nax,nay The total number of axes on horizontal and vertical axes respectively; nax times nay must be less than or equal to 8. For the LaserWriter, nax must be negative, requesting an A4 size plot. By default, the longer axis is the horizontal one; a negative value for nay requests a plot with the longer axis vertical. xtimod A real array, the element of which indicates the mode of operation on the x axis designated by the array argument. = 0. : X-Y plot = t.(constant): T-Y plot; t is divided into 5 to form labels for the sub-divisions on the time axis. =-1. : T-Y plot; standard or normalised time axis, where the time axis is labeled from 0.0 to 1.0 wave Storage of 8 channels of data points. Each channel can have a maximum of 1281 points currently (641 in version WAPLOV). npnt Number of points which are to be plotted on the specified pair of axes, i.e. one can have different numbers of data points plotted on different pairs of axes, but the number of points must be the same for waveforms which share the same axes. This restriction in LAPLOV has been removed in LAPLV, in which npnt has been replaced by the array npta(i,k), organised as described above for join, etc. join Its contents indicate the width and the type (solid or dashed) of lines for the specified waveform; it is a 2 digit number. [see the description of subroutine PEN for details] ixchn,iychn (1) Their contents indicate the chosen x & y channels resp. for the specified waveforms. (2) If the content is zero, a previous channel number is assumed. (3) If 'time' .ne. 0., all the contents of ixchn must be zeroes, therefore in a time-y plot program, one does not have to assign any data values to ixchn. (4) They correspond one to one, e.g. ixchn(1,1),ixchn(1,2),ixchn(1,3) /1,2,3/ iychn(1,1),iychn(1,2),iychn(1,3) /4,5,6/ means that in the 1st pair of axes, waveform 1 is ch.1 vs ch.4 waveform 2 is ch.2 vs ch.5 waveform 3 is ch.3 vs ch.6 if '5' & '6' are replaced by 0s, then the y-axis has all 3 waveforms from ch.4. To avoid confusion it is better to put /4,4,4/ than /4,0,0/ (5) The channel numbers can be interchanged and repeated between and within both axes. xtil,ytil Titles on the x- & y-axis respectively. (1) If the first element of the title in a particular pair of axes is '1'-- only numerical labels are printed on that axis '0'--neither numerical labels nor title are printed (2) Maximum 28 characters for each axis title (3) Auto scaling of characters' size is programmed, therefore it is recommended that the same number of characters are used in a multi-axes plot. Note that a ' ' is also counted as one character. (4) If (say) the first and third elements are assigned characters but the second is not, the third will be printed in the place of the second. gtil Graph title, plotted at the top of a page; the maximum number of characters is 40 and a fixed size is programmed. curtil Curve (or waveform) title, printed on the right hand corner of each pair of axes with a sample of the corresponding solid or dotted line. This can be suppressed by assigning the string '12345678' to the appropriate element(s) of the array. Remember to break up the total title string in (e.g.) gtil by data-statement punctuation as normal, respecting the array dimensions and element lengths! isym Each element is a three-digit integer prescribing the symbol type, size and fill for the corresponding curve by the units, tens and hundreds digits respectively. Thus type can take the values 1 (circle), 2 (diamond), 3 (square), 4 (triangle), 5 (inverted triangle). Fill may have the values 0 (outline only), 1 (filled, i.e. black) and 2 (half-filled). If isym(i,k) is negative, lines between the symbols are omitted. If isym(i,k) is zero, symbols are omitted. -------------------------------------------------------------------------------- SUBROUTINES CALLED BY LAPLV:- (1) GRID (nax,nay,ixdim,iydim,ixo,iyo,ia,iv,ixgap,iygap, ixstt,ityn,itxn,iystt,lxoffx,lyoffx,lxoffy,lyoffy, iszn,insetx,insety,icusiz,length,iyspc,iszct,iszgt) specifies the device-dependent (LaserWriter or Digi-Plot) co-ordinate grid limits. See the comments within GRID for explanation of the arguments. Ideally(!) only this subroutine and the low-level SEND would require changing to convert the whole subroutine suite for use with another plotter device. In practice this has not been realized, due mainly to differences in start-up procedures and command syntax. (2) MXNPNT (wave,nptchn,rmax,rmin) finds the max. and min. values for each channel in array 'wave'. {a}. 'nptchn(j)' is the number of points (starting from 1) from 'wave', to be plotted; within this range, the max. & min. are found. j is the channel number as in 'wave' nptchn(j)=n, n must be less than or equal to the dimension m of array 'wave' (currently 161 in WAPLOT and MXNPNT, 641 in WAPLOV and VXNPNT. {b}. ll channels' max. & min. values are stored in array 'rmax(8)' & 'rmin(8)'; 0s are assigned if the channel no. is not called (i.e. nptchn(j)=0 ). {c}. Version VXYPNT instead of VXNPNT is called by LAPLXY. (3) IOVIR is called if TSX+ is running to change the mapped I/O page from the last 4k words of low memory (PAR 7) to the penultimate 4k (PAR 6) to avoid a clash with the use of PAR 7 for handling Fortran virtual arrays under TSX+. (4) SENDL - see below (5) EXTREM (rmax,rmin,rup,rlo,ntic,tico,ticp,ticlen,ialgm) given as input the maximum and minimum of the axis data, finds rounded-off upper and lower bounds for the axis, the no. of ticks, length between ticks, and the values for the first and the last (lowest and uppermost) ticks. Subroutine ROUNF is called to find the above values for positive max. and min. inputs; EXTREM adjusts the input and output values to suit 3 cases: max. min. positive negative positive positive negative negative In the first case subroutine TICKS is also called by EXTREM. {a}. rmax- input maximum {b}. rmin- input minimum {c}. rup - round-off upper value {d}. rlo - round-off lower value {e}. ntic- number of ticks on the axes {f}. tico- value for the lowest tick {g}. ticp- value for the uppermost tick {h}. ticlen- length between the uppermost and lowest ticks {i}. ialgm - equal to either 1 or 2, the algorithm which is used to determine the number of ticks. EXTREM and its subroutines were written by R.M. to provide a better solution than the usual algorithms to the problem of providing round- number axis graduations without large amounts of wasted space at the extremities of the data and without resorting to large numbers of graduations. The resulting algorithm is complex, and the code is hard to follow. Occasionally the algorithm chooses a way of dividing the axis that seems idiosyncratic, but problems of this nature can be overcome by plotting isolated well-chosen data points that force the algorithm to recalculate. Caveat: the algorithm is not fool-proof; it is expected that the user will plot data in units that allow a data range between about one and a few thousand. (6) LINTYP (ilnpen) ilnpen is a two-digit integer. The ten digit denotes line type (0-9) 0: solid line 1-9: broken line, half-pitch = (1-9)*10 units The unit digit denotes pen no., i.e. line width (1-6) (7) LADRAW (ibit1,ibit2,ixp1,iyp1,ixp2,iyp2,mode,iasc,iarq,isym, inter,rumbr,char4,char8,log) is a multi-function subroutine to command the operations of the plotter. ibit1 ibit2 operation 1 operation 2 to 1st coord. to 2nd coord. 0 0 abs. move abs. draw 0 1 " rel. " 1 0 rel. move abs. draw 1 1 " rel. " 2 2 abs. draw abs. move 2 3 " rel. " 3 2 rel. draw abs. move 3 3 " rel. " 4 0 abs. move to 1st coord. 5 0 rel. move " 6 0 abs. draw " 7 0 rel. draw " mode 1: mark with different symbol (isym = 1 to 6) 2: print number with an integer input, field: i5 3: print number with a real no. input, field: f5.0 4: print number with a real no. input, field: f5.1 5: print number with a real no. input, field: f5.2 6: print characters with Real*4 as input (normal form) 7: print characters with Real*8 as input (double precision) 8: print characters with Logical*1 as input iasc, iarq are the scale and rotation of characters, which must be specified for modes 6-8. inter stores the numerical labels (mode 2); rumbr stores the numerical labels (mode 3-5). char4 stores the title for mode 6; char8 stores the title for mode 7; log stores the title for mode 8. LADRW is a later version of LADRAW which calls subroutine ASMBL. (7) AXISLW (ixy,intlen,intnos,ixorn,iyorn) draws an x or y axis from the specifed origin. {a}. ixy=0 draw y axis 1 draw x axis {b}. ixorn,iyorn is the start origin {c}. intlen is the length of interval between ticks {d}. intnos is the number of intervals (no. of ticks=intnos+1) (8) PARSE (tchar,mxchr,nchar) rearranges the characters in a title so that no more than one space separates words, and returns the total number of characters up to the last non-space. The parameter nchar must be supplied when the routine is called; it should be minimised by prior use of 'len', as in LAPLV. -------------------------------------------------------------------------------- LOWER-LEVEL SUBROUTINES:- (1) DIGIT (reval,baseln,idig) finds each digit of the input real value 'reval', storing them in the array 'idig', and baseln, the multiplier of the first digit of the real input number (e.g. baseln = 10 for reval = -15.7). (2) ROUNF (rmax,rmin,iaxdig,iindig,raxbas,rinbas,rup,rlo,ntic,tico, ticp,ticlen,ilogm) is called by EXTREM to find upper, lower values of the axes and the ticks; also finds the no. of ticks and the length between upper & lower ticks by assuming rmax and rmin are positive. (3) TICKS adjusts the no. of ticks according to the distance between them (4) ROTAT (ntimes) rotates characters anticlockwise by 90 degrees ntimes (0-3) w.r.t. the x-axis. The coordinate frame stays rotated until ROTAT is called again with the corresponding negative argument. (5) SIZ (isize) sets the size of characters according to the supplied integer (0-15) (6) LPR (text,n) prints the given text on the LaserWriter page (7) PEN, BROK PEN (iwhich) sets line width according to the supplied integer (1-6) BROK (lpitch,lgap) receives broken line pitch and mark/space ratio in 0.1mm units, which are converted to 1/72" units. (8) ASMBL (ismbl,ix,iy) draws a data symbol at the point ix,iy according to the instructions supplied by the ismbl digits: iwhich (1-5) isize (0-9) ifill (0 1 or 2) For example ismbl = 152 means fill a size-5 diamond. ismbl is set negative by the subroutine to indicate that a symbol procedure has been defined and can be used subsequently. The argument ismbl encodes all but idone of the arguments iwhich, idone, isize and ifill for the earlier routine SSMBL, which was itself a version of SMBL using Postscript procedure definitions. (9) IEVEN, IRND are statement functions which return the nearest round or even integer to the real number supplied. (10) AXL (ixy,lseg,nseg) draws an axis on the Laserwriter page. The arguments are specified as for the corresponding WX4675 command. (11) HMARK draws a horizontal subdivision of the vertical axis being produced by AXL, which calls this routine. VMARK draws a vertical subdivision of a horizontal axis. (12) IDIGT (input,iunit,itens,ihund,ithou) returns the values of the digits making up the supplied integer, currently up to a maximum size for input of 9999. It is called by ASMBL to decode the argument ismbl. (13) LGO (how,ix,iy) is a graphical primitive for the LaserWriter. The variable 'how' is encoded as for the Watanabe plotter. how = 'M' move to absolute ix,iy how = 'R' move to relative ix,iy how = 'D' line to absolute ix,iy how = 'I' line to relative ix,iy (14) SENDL (pltcmd,nchar) transfers the commands through the interface to the plotter, and tests the transfer & receive operations {a}. pltcmd- the array of command characters {b}. nchar - the number of characters to be transferred --------------------------------------------------------------------- END ---------------------------------------------------------------------