AXIS - MSU CHEMISTRY AXIS DRAWING ROUTINE T. V. Atkinson Department of Chemistry Michigan State University East Lansing, MI 48824 1. Introduction 2. Common Features 3. AXIS Functionality 4. Tick Mark Placement 5. Tick Mark Lable Format 6. Exceptions 7. AXIS - Calling Program Interface AXIS.DOC (15-NOV-82) PAGE 2 1.0 INTRODUCTION AXIS is a FORTRAN callable subroutine for drawing a large variety of axes on any graphic device supported by the MSU CHEMISTRY graphics routine VECTOR. The compiled object of AXIS is contained in the library MSULIB.OLB. A graph is often used to illustrate relationships among a set of points specified in some original frame of reference. Such graphs are constructed by mapping the original set of points into a new set of points arranged on the drawing surface: a piece of paper or a graphics terminal screen. Each point drawn is identified by the cartesian coordinates of the point in the frame of reference of the drawing surface. The coordinates of a point are given in units of inches or centimeters and are relative to the origin of the drawing surface. A mathematical function describes how the points in the original frame of reference are mapped into the frame of reference of the drawing surface. For convenience, this transformation is divided into two stages. The first provides a functional transformation of the data. The choice of this mapping function is the perogative of the person generating the plot and will depend on which aspects of the data is to be emphasised. x' = ax + b A.1 x' = k/x A.2 x' = logm x A.3 where x represents one coordinate of the point in the original frame of reference, x' is the transformed coordinate in the plotting frame of reference, a, b, and k are constants, and "logm" indicates the logarithm of a given base. The second transformation is linear and maps the coordinate onto the physical drawing surface. The following is such a transformation for the x-coordinate. x" = cx' + d A.4 where x" will be in the space of the drawing surface, c and d are constants. For the remainder of this document, only one coordinate of the points will be considered. The second coordinate can be handled independently in an analogous manner. In actual fact, one transformation could be derived to accomplish the mapping from the logical to the physical frames. The separation into two transformations was done for convenience in this discussion and to more closely reflect the internal algorithms used in AXIS. This discussion will follow the common practice of referring to the original frame of reference as the "logical" frame. The frame of reference resulting from the application of mapping functions such as shown in line A.1, A.2, and A.3 will be refered to as the AXIS.DOC (15-NOV-82) PAGE 3 "intermediate" frame. Finally, the frame of the drawing surface will be referred to as the "physical" frame. An important part of any graph is the axes that help the viewer identify the points with respect to the original frame of reference. This is accomplished with tick marks which are distributed along the axis at points corresponding to convenient intervals in the original frame of reference. Each axis drawn by AXIS consists of a straight line drawn between two points defined in the physical space of the plotting surface. The axis is embellished with two varieties, major and minor, of tick marks which are distributed along the axis in such a way as to meter the logical data space. The major tick marks can be labeled with the logical value associated with the tick mark. This document describes the use of AXIS to produce a large variety of axes. Such a description must take place on different levels. All users will need to know the mechanics of getting AXIS to produce the desired graphical constructions once a program is built and running. In addition, programmers will need to know how to integrate AXIS with their programming. To serve these varied needs, some parts of this document will focus on the integration of AXIS into a program and are of little value to those users who are using existing programming. These sections will be marked (PROGRAMMERS ONLY). In the discussion of AXIS, reference will be made to the various parameters used to control the construction of axes by AXIS. Section 7.1 contains the complete list of these parameters. 2.0 COMMON FEATURES This section will discuss the axis and tick mark features that are common to all axes drawn by AXIS regardless of mapping function. Figure A.1 illustrates many pertainent features of axes drawn by AXIS. The axis is drawn from one point(APBEG(1),APBEG(2)) in the physical space of the drawing surface to a second point(APEND(1),APEND(2)) also in the physical space. This inherent directionality of the axis is utilized in the specification of some of the tick mark and tick mark label attributes. The right hand side of the axis is that of an observer standing on the beginning of the axis and looking towards the end of the axis. Since the axis is to meter the logical data space that is being mapped into the physical drawing space, the logical values of the beginning, ALBEG, and the end, ALEND, must also be specified. The independence of the physical and logical direction of an axis can be seen by comparing Figures A.1 and A.2 which differ only in the fact that the values of ALBEG and ALEND have been interchanged. AXIS.DOC (15-NOV-82) PAGE 4 FIGURE A.1 In the example shown in Figure A.1 major tick marks were drawn at points corresponding to 10, 15, 20, 25, and 30 in the logical data space. Each major tick interval is subdivided into five minor tick intervals by four minor tick marks drawn at points corresponding to 9, 11, 12, 13, 14, 16, ... in the logical data space. FIGURE A.2 All axes used as illustrations in this document were drawn horizontally from left to right. This was done only for convenience and should in no way obscure the flexibility with which AXIS can be used to place axes. The figure at the beginning of AXIS.DOC illustrates this flexibility. Figure A.3, an enlargement of part of Figure A.1, AXIS.DOC (15-NOV-82) PAGE 5 illustrates several physical aspects of the tick marks common to all axes drawn by AXIS. FIGURE A.3 Notice that there are actually four types of tick marks: major ticks to the right and left of the axis and minor tick marks to the right and left of the axis. The lengths(in inches) of these tick marks are controlled by the four parameters TIXLR, TIXLL, TIXSR, AND TIXSL. Figure A.4 shows the axis of A.1 along with three other variations differing only in the values of the four tick mark length parameters. AXIS.DOC (15-NOV-82) PAGE 6 FIGURE A.4 These four parameters must be positive but can be of any size. In fact, the tick marks can extend across the whole data plotting surface resulting in "graph paper" (See Figure S.1 in SYMPLT.DOC). The line width of the axis, the major tick marks, and the minor tick marks, and tick mark labels are indepently ajustable with the parameters contained in the array NIB (See section 7.1). The line patterns of the first three of these features are controlled with the contents of the array IPATTX (See section 7.1). Finally, the space between the major tick marks and their labels is controlled by the parameter SPACE. 3.0 AXIS FUNCTIONALITY AXIS is capable of drawing axes with three different mapping functions: linear, reciprocal, and logarithmic as illustrated in Figure A.5. The choice of mapping function is controlled by the parameter IFUNC. AXIS.DOC (15-NOV-82) PAGE 7 FIGURE A.5 For linear axes, the physical distance along the axis is linearly related to distances in the logical frame of reference. For reciprocal axes, the physical distance along the axis is related to the reciprocal of distances in the logical frame of reference. For logarithmic axes, the relationship is logarithmic. Specifically, XT = (XL - ALBEG) A.5 XT = (1.0/ALBEG - 1.0/XL) A.6 XT = LOGM(XL) - LOGM(ALBEG) A.7 where XL is the coordinate of the point in the logical frame of reference, XT is the intermediate value, and LOGM(y) represents the logarithm of the number "y" with the base of the logarithm being BASLOG. XT will range from 0.0 at the begining of the axis to the transformed value of ALEND. The AXIS.DOC (15-NOV-82) PAGE 8 axis is then mapped into the drawing surface in such a way as to place the beginning and end of the axis on the physical points defined for the ends of the axis. The details of this last transformation is of no consequence to this discussion. 4.0 TICK MARK PLACEMENT 4.1 LINEAR Once ALBEG and ALEND are specified, the placement of the tick marks is governed by the values of the parameters TLFRST, TLLAST, DELLTX, and DELSTX. TLFRST is the value (in logical units) at which the first logical tick mark is drawn. Starting at TLFRST, the major tick marks occur at intervals of DELLTX (logical units) until the end of the axis. Note that only if TLFRST is equal to ALBEG, will there be a major tick mark at the beginning of the axis. In addition, a major tick mark falls at the end of the axis only if the distance (logical units) between TLFRST and ALEND is an integral number of intervals of the length DELLTX. Each major tick interval is subdivided into minor intervals of length DELSTX (logical units). All minor tick intervals within a given major tick interval will be equal only if DELLTX is an integral multiple of DELSTX. As can be seen in Figure A.1, there does not have to be tick marks, of either kind, at the ends of an axis. TLLAST is used to control the role of TLFRST in tick mark placement. If TLLAST is equal to 0.0, then the value of TLFRST is ignored and the value of ALBEG is used as the position of the first major tick mark. 4.2 RECIPROCAL The same considerations apply for reciprocal axes with the exception that the tick mark intervals will not be of equal physical size when drawn. 4.3 LOGARITHMIC The rules governing tick mark placement is considerably different for logarithmic axes. First, the major tick marks are always forced to occur at integral powers of the base, BASLOG. TLFRST and TLLAST are ignored. ALBEG and ALEND AXIS.DOC (15-NOV-82) PAGE 9 provide the primary user control of tick mark placement. The first major tick mark is placed at the point corresponding to the next power of the base along the axis after ALBEG. DELLTX and DELSTX also have different meanings for logarithmic axes. FIGURE A.6 As can be seen in Figure A.6, (IFIX(DELLTX) - 1) powers of the base are skipped before the next major tick mark occurs, where the concept of the FORTRAN function "IFIX" is used to illustrate that only the interal portion of DELLTX is utilized. Figure A.6 contrasts this with the use of NLABEL. Minor tick marks are not drawn unless the base of the logarithm is 10, DELLTX = 1, and DELSTX is greater than 0.0. Thus, DELSTX can be used to turn off minor ticks when base 10 logaritmic axes are being generated. Such being the only logarithmic axis with minor ticks. When those criteria are met, the minor tick marks occur at 2, 3, 4, 5, 6, 7, 8, and 9 times the value of the next lower major tick mark as shown in Figure A.5 and A.6. 5.0 TICK MARK LABELS AXIS labels the major tick marks with the logical value associated with the tick mark. The format of the labels is chosen by the user from a variety of choices. Essentially, the labels are drawn in ways analogous to formatted FORTRAN AXIS.DOC (15-NOV-82) PAGE 10 writes of decimal integers, octal integers, decimal real numbers, or decimal real numbers with exponential notation. Figure A.7 illustrates some of the choices available. FIGURE A.7 The user chooses the presentation with a string in the array TLFORM of the following form. (fff ... ) A.7 where "fff ..." is any valid FORTRAN format for a single number. The parentheses must be included in the string. For real formats, the logical value associated with the tick mark is encoded into a character string according to the format contained in TLFORM. If, however, the format is for a FORTRAN integer, the logical value of the tick mark is first converted to an integer value. The resultant integer is then encoded into a character string using the format in TLFORM. In either case the string is compressed by removing all leading blanks and the string is drawn. The placement of the string is governed by the parameters IMODE (see Figure A.8) and SPACE (see Figure A.3). Regardless of orientation and placement the label string is centered on the line containing the tick mark being annotated. AXIS.DOC (15-NOV-82) PAGE 11 FIGURE A.8 Since all leading blanks are removed, many formats are actually equivalent. In the top example in Figure A.7, "I3", "I4", "I5", "I6", "I7", ... would all have produced identical results. Likewise, "F6.0", "F7.0", "F8.0", "F9.0", "F10.0", ... would all produce axes identical to the third example from the top in Figure A.7. In fact, "I8", "O8", "F15.n", or "E15.n" will cover the effective range of label formats. No others are needed. The choice of number of decimal places in real labels as chosen by the integer "n" in the last two formats is the only variations the user need consider. The symbol parameters (see SYMPLT.DOC) controlling the characters used in the labels are contained in the array CPARAM and the fourth element of the array NIB. The tick mark labels are drawn with the SYMPLT library "0". The user must be careful that the appropriate library has been so defined (see SYMPLT.DOC). 6.0 EXCEPTIONS Errors detected by AXIS have the following general form and are reported by the routine ERRPRT. ERROR AXIS: tttttttttttttttt nnnn AXIS.DOC (15-NOV-82) PAGE 12 where "ttt ... " is one of the following error message is and "nnnn" is the octal error number. 1. "NO ")" in FORMAT" - Format statement is missing the right parenthesis. 2. "ILLEGAL MODE " - IMODE is equal to a value other than 0, 1, 2, or 3. 3. "ILLEGAL LOG BASE" - BASELOG is less than or equal to zero. 4. "ILLEGAL FUNCTION" - IFUNC is equal to a value other than 1, 2, or 3 5. "ILLEGAL PHYS. AX" - The distance between APBEG and APEND is zero. 6. "ALBEG = ALEND " - The axis is of zero logical length. 7. "ILLEGAL TLFRST " - TLFRST is outside the interval from ALBEG to ALBEG plus DELLTX. AXIS.DOC (15-NOV-82) PAGE 13 7.0 AXIS - CALLING PROGRAM INTERFACE (PROGRAMMERS ONLY) 7.1 CALLING SEQUENCE SUBROUTINE AXIS (APBEG,APEND,ALBEG,ALEND,TLFRST,TLLAST,TIXLNG, 1 LPATTX,DELLTX,DELSTX,NLABEL,TLFORM,CPARAM, 2 ANGLAB,SPACE,NIB,IMODE,IDISAB,IFUNC,BASLOG, 3 IERR) C==================================================================== C C TITLE: AXIS - SUBROUTINE TO DRAW AXES C C AUTHOR: T V ATKINSON C DEPARTMENT OF CHEMISTRY C MICHIGAN STATE UNIVERSITY C EAST LANSING, MI 48824 C C DATE: 12-JAN-82 C C-------------------------------------------------------------------- C C ARGUMENT LIST: C C APBEG(2) ; COORDINATES(X,Y) OF THE BEGINNING C ; OF THE AXIS. THE POINT (X,Y) C ; IS IN PHYSICAL SPACE. C C APEND(2) ; COORDINATES(X,Y) OF THE END OF THE AXIS. THE C ; POINT (X,Y) IS IN PHYSICAL SPACE. C C ALBEG ; LOGICAL VALUE ASSOCIATED WITH THE BEGINNING C ; OF THE AXIS. C C ALEND ; LOGICAL VALUE OF ASSOCIATED WITH THE END C ; OF THE AXIS C C TLFRST ; LOGICAL VALUE ASSOCIATED WITH THE FIRST C ; MAJOR TICK MARK. C C TLLAST ; IF .NE. 0, THEN TLFRST WILL BE USED TO SET C ; FIRST MAJOR TICK MARK C C TIXLNG(4) ; REAL ARRAY OF THE LENGTH(PHYSICAL UNITS) OF C ; OF TICK MARKS: (1) -> TIXLR, (2) -> TIXLL C ; (3) -> TIXSR, (4) -> TIXSL C C LPATTX(4) ; INTEGER ARRAY CONTAINING VERSATEC LINE C ; PATTERN. (1) -> TIXLR, (2) -> TIXLL, C ; (3) -> TIXSR, (4) -> TIXSL C AXIS.DOC (15-NOV-82) PAGE 14 C DELLTX ; LENGTH OF LARGE TICK MARK INTERVALS (LOGICAL C ; UNITS C ; FOR LOGARITHMIC AXES, MAJOR TICK MARKS WILL C ; BE DRAWN AT EVERY DELLTX'TH POWER OF THE C ; BASE C C DELSTX ; LENGTH OF SMALL TICK MARK INTERVALS (LOGICAL C ; UNITS) C ; FOR LOGARITHMIC AXES, MINOR TICK MARKS WILL C ; BE DRAWN ONLY FOR BASLOG = 10.0, DELLTX = 1, C ; DELSTX .GT. 0. DELSTX SERVES ONLY TO ENABLE C ; OR DISABLE THE MINOR TICK MARKS. C C NLABEL ; LABELS WILL BE PLACED ON EVERY "NLABEL'TH" C ; MAJOR TICK MARKS. C C TLFORM(20) ; BYTE ARRAY CONTAINING FORMAT C ; TO BE USED IN GENERATING TICK MARK LABELS. C ; E, F, G, I, OR O FORMATS WITH FIELDS LESS C ; THAN OR EQUAL 20 ARE ALLOWED. THE C ; FORMAT MUST BE ENCLOSED IN PARENTHESES. C C CPARAM(5) ; CHARACTER PARAMETERS: C C ; (1): WIDTH(PHYSICAL UNITS) OF THE SYMBOLS C ; USED IN THE TICK LABELS C C ; (2): HEIGHT(PHYSICAL UNITS) OF THE SYMBOLS C ; USED IN THE TICK LABELS C C ; (3): VERTICAL DISTANCE BETWEEN LINES OF C ; SYMBOLS C C ; (4): HORIZONTAL SPACE BETWEEN SYMBOLS C C ; (5): SLANT ANGLE(DEGREES) OF THE SYMBOLS C ; USED IN THE TICK LABELS C C ANGLAB ; FOR MODES 2 AND 3 THE TICKMARK LABELS C ; WILL BE DRAWN AT AN ANGLE OF ANGLAB(DEGREES) C ; FROM THE AXIS C C SPACE ; SPACE(PHYSICAL UNITS) BETWEEN MAJOR TICK C ; MARK AND LABEL C C NIB(4) ; VERSATEC NIB SELECTION C ; (1) -> AXIS C ; (2) -> MAJOR TICK MARKS C ; (3) -> MINOR TICK MARKS C ; (4) -> TICK MARK LABELS C C IMODE ; TICK MARK LABEL PLACEMENT: C ; =0 -> LABELS WILL BE TO RIGHT OF AND C ; PARALLEL TO THE AXIS C ; =1 -> LABELS WILL BE TO LEFT OF AND AXIS.DOC (15-NOV-82) PAGE 15 C ; PARALLEL TO THE AXIS C ; =2 -> LABELS WILL BE TO RIGHT OF AND C ; PERPENDICULAR TO THE AXIS C ; =3 -> LABELS WILL BE TO LEFT OF AND C ; PERPENDICULAR TO THE AXIS C C C IDISAB ; DISABLE FLAG (SUM OF THE FOLLOWING): C ; 1 -> DISABLE DRAWING AXIS C ; 2 -> DISABLE DRAWING TICK MARK LABELS C ; 4 -> DISABLE DRAWING TICK MARKS C C IFUNC ; FUNCTION FLAG C ; 1 -> LINEAR AXIS C ; 2 -> RECIPRICAL AXIS C ; 3 -> LOG AXIS C C BASLOG ; BASE OF LOGARITHM USED IN LOG AXIS C C IERR ; ERROR FLAG: =0 -> NO ERROR C C==================================================================== C 7.2 COMMON AREAS COMMON/SABORT/LABORT,LDUM(4) LABORT L*1 1 Asynchronous flag for terminating AXIS before completion. When set .TRUE. by an AST routine such as KBCHEK, AXIS will abort. A check of LABORT is made as each tick mark is processed. LDUM L*1 4 NOT USED BY AXIS COMMON/ERROR/LUNEL LUNEL I*2 1 Error messages and other messages from AXIS are made on the logical unit number which is contained in LUNEL In addition, the COMMON areas used by VECTOR and SYMPLT must be handled appropriately. This is true even when AXIS is the only MSU graphics routine used directly by the user. See AXIS.DOC (15-NOV-82) PAGE 16 VECTOR.DOC and SYMPLT.DOC for a discussion of these common areas. 7.3 LOGICAL UNIT USAGE The only LUN used by AXIS is LUNEL which is utilized for reporting error messages. 7.4 SAMPLE USE OF AXIS The program AXIS.TST illustrates the use of the subroutine AXIS. This program can be built using AXIS.CMD which also uses AXISTKB.CMD.