# Chapter 4: Plotting Axis Systems and Titles

## 4.1 Plotting Axis Systems

An axis system defines an area on the page for plotting data. Various axis systems can be plotted to accommodate different applications. For two-dimensional graphics, a maximum of two parallel X- and Y-axes can be drawn. The axis system is scaled to fit the range of data points and can be labeled with values, names and ticks. Two-dimensional axis systems are plotted with a call to the routines GRAF or GRAFP.

G R A F

GRAF plots a two-dimensional axis system.

The call is: | CALL GRAF (XA, XE, XOR, XSTP, YA, YE, YOR, YSTP) | level 1
or: | void graf (float xa, float xe, float xor, float xstp, float ya, float ye, float yor, float ystp);

XA, XE | are the lower and upper limits of the X-axis.
XOR, XSTP | are the first X-axis label and the step between labels.
YA, YE | are the lower and upper limits of the Y-axis.
YOR, YSTP | are the first Y-axis label and the step between labels.

Additional notes:

- GRAF must be called in level 1 and automatically sets the level to 2. When plotting more than 1 axis system on a page, ENDGRF must be called in between each new set of axes in order to set the level back to 1.
- The position of the lower left corner and the size of an axis system can be changed with the routines AXSPOS and AXSLEN.
- The axis scaling is linear by default and can be changed with AXSSCL. For logarithmic scaling, the corresponding parameters in GRAF must be exponents of base 10.
- One of several label types can be chosen with the routine LABELS or user-defined with MYLAB. Single labels can be suppressed by calling AXENDS.
- The routine NAME defines axis titles.
- The number of ticks between axis labels can be changed with the routine TICKS.
- SETGRF can be used to remove a piece of or complete axis from an axis system.
- If the numerical value of the lower limit of an axis is larger than the upper limit and the label step is negative, axis scaling will be in descending order.
- The routine FRAME defines the thickness of a frame plotted around an axis system. A frame can also be plotted outside of GRAF with the statement CALL BOX2D.

The following routine GRAFP can be used to plot a polar axis system and set up a scale for polar axes.

G R A F P

The routine GRAFP plots a two-dimensional polar axis system.

The call is: | CALL GRAFP (XE, XOR, XSTP, YOR, YSTP) | level 1
or: | void grafp (float xe, float xort, float xstp, float yor, float ystp);

XE | is upper limit of the X-axis (radius coordinate).
XOR, XSTP | are the first X-axis label and the step between labels.
YOR, YSTP | are the first Y-axis label and the step between labels specified in degrees. The Y-axis is scaled from 0 to 360 degrees.

Additional notes:

- The direction and position of the angle labels can be modified with the routine POLMOD.
- GRAFP is a new name for the old routine POLAR, since polar is also a C99 function. The old routine POLAR is still in the DISLIN libraries.

G R A F R

The routine GRAFR plots a two-dimensional axis system for a Smith chart, where the non negative impedance or admittance plane is projected to a complex reflexion coefficient plane, which is displayed in the unity radius region. The projection is done by the formula r = (z - 1) / (z + 1), where z and r are complex numbers.For admittance, 1 / z is used in the formula.

The call is: | CALL GRAFR (XRAY, N, YRAY, M) | level 1
or: | void grafr (const float *xray, int n, const float *yray, int m);

XRAY | is an array of non negative real values of complex impedance or admittance data. The values are plotted as labels at the X-axis.
N | is the dimension of XRAY.
YRAY | is an array of imaginary values of complex impedance or admittance data. The values are plotted as labels at the Y-axis (unity circle).
M | is the dimension of YRAY.

Additional notes:

- The type of the Smith axis system, impedance or admittance, can be defined with the routine AXSTYP.
- The conversion routine GETRCO calculates the reflection factor r for a impedance z by the formula r = (z - 1) / (z + 1). The reverse transformation z = (1 + r) / (1 - r) is done by GETICO. For admittance, 1 / z is used for the conversions above.
- Additional grid lines in a Smith chart can be plotted with the routines GRIDRE and GRIDIM.
- A similar axis system for a Smith chart can be created with the normal GRAF routine, where the scaling is defined from -1.0 to 1.0 for both axes. For that case, values must be converted by GETRCO to reflection factors before passing them to plot routines. For GRAFR, this is done automatically in plot routines.

## 4.2 Termination of Axis Systems

E N D G R F

The routine ENDGRF terminates an axis system and sets the level back to 1.

The call is: | CALL ENDGRF | level 2, 3
or: | void endgrf (void);

Additional note:

- ENDGRF contains a call of the routine SENDBF that can be disabled with the routine BUFMOD.

## 4.3 Plotting Titles

T I T L E

This routine plots a title over an axis system. The title may contain up to four lines of text designated with TITLIN.

The call is: | CALL TITLE | level 2, 3
or: | void title (void);

Additional note:

- All lines are centred by default but can be left- or right-justified using TITJUS.

## 4.4 Plotting Grid Lines

G R I D

The routine GRID overlays a grid on an axis system.

The call is: | CALL GRID (IXGR, IYGR) | level 2, 3
or: | void grid (int ixgr, int iygr);

IXGR, IYGR | are the numbers of grid lines between labels.

Additional note:

- GRID uses automatically GRDPOL for a polar axis system.

G R D P O L

The routine GRDPOL plots a polar grid.

The call is: | CALL GRDPOL (IXGR, IYGR) | level 2, 3
or: | void grdpol (int ixgr, int iygr);

IXGR | is the numbers of circles between labels.
IYGR | is the numbers of sector lines between 360 degrees.

A X G I T

The routine AXGIT plots vertical and horizontal lines through X = 0 and Y = 0.

The call is: | CALL AXGIT | level 2, 3
or: | void axgit (void);

Additional note:

- The statement CALL XAXGIT plots only the line Y = 0 while CALL YAXGIT plots only X = 0.

C R O S S

The routine CROSS plots vertical and horizontal lines with additional ticks through X = 0 and Y = 0.

The call is: | CALL CROSS | level 2, 3
or: | void cross (void);

Additional note:

- The statement CALL XCROSS plots only the line Y = 0 while CALL YCROSS plots only X = 0.

G R I D R E

GRIDRE plots a grid line of a constant real part in a Smith chart.

The call is: | CALL GRIDRE (ZRE, ZIMG1, ZIMG2, N) | level 2
or: | void gridre (float zre, float zimg1, float zimg2, int n);

ZRE | is the constant real value of the grid line (≥ 0.0).
ZIMG1, ZIMG2 | are the start and end imaginary parts of the gird line.
N | is the resolution of the curve, which means the number of generated points between ZIMG1 and ZIMG2.

G R I D I M

GRIDIM plots a grid line of a constant imaginary part in a Smith chart.

The call is: | CALL GRIDIM (ZIMG, ZRE1, ZRE2, N) | level 2
or: | void gridim (float zimg, float zre1, float zre2, int n);

ZIMG | is the constant imaginary value of the grid line.
ZRE1, ZRE2 | are the start and end real parts of the gird line (≥ 0.0).
N | is the resolution of the curve.

## 4.5 Plotting Additional Labels

A D D L A B

Additional single labels can be plotted on an axis system with the routine ADDLAB.

The call is: | CALL ADDLAB (CSTR, V, ITIC, CAX) | level 2, 3
or: | void addlab (const char *cstr, float v, int itic, const char *cax);

CSTR | is a character string containing a label.
V | is a user coordinate that defines the axis position of the label.
ITIC | is an integer option that defines if a tick mark is plotted. ITIC = 0 means that no tick is plotted, ITIC = 1 defines a minor tick and ITICK = 2 defines a major tick.
CAX | is a character string that defines the axis. CAX can have the values 'X', 'Y', 'Z', 'XTOP' and 'YRIGHT'.

## 4.6 Secondary Axes

The following routines plot single X- and Y-axes; they are called secondary axes because they do not define or change any of the axis scaling parameters. Secondary axes can be used to add additional labels to the axis systems.

The secondary axis routines for a rectangular axis system are:

- XAXIS plots a linear X-axis
- YAXIS plots a linear Y-axis
- XAXLG plots a logarithmic X-axis
- YAXLG plots a logarithmic Y-axis

The call is: | CALL XAXIS (A, B, OR, STEP, NL, CSTR, IT, NX, NY) | level 1, 2, 3
or: | void xaxis (float a, float b, float or, float step, int nl, const char *cstr, int it, int nx, int ny);

A, B | are the lower and upper limits of the axis.
OR, STEP | are the first label and the step between labels.
NL | is the length of the axis in plot coordinates.
CSTR | is a character string containing the axis name.
IT | indicates how ticks, labels and the axis name are plotted. If IT = 0, they are plotted in a clockwise direction. If IT = 1, they are plotted in an counter-clockwise direction.
NX, NY | are the plot coordinates of the axis start point. The X-axis will be plotted from left to right and the Y-axis from bottom to top.

Analogue: | YAXIS, XAXLG, YAXLG

Additional notes:

- Secondary axes can be called from level 1, 2 or 3. Note again that secondary axes do not change the scaling of an axis system defined by GRAF. Similarly, curves cannot be plotted with only secondary axes, they require a call to GRAF.
- As in GRAF, the parameters of logarithmic axes must be exponents of base 10.
- User-defined labels may also be plotted on secondary axes with MYLAB and the argument 'MYLAB' in the routine LABELS. The number of ticks can be changed by calling TICKS.

The secondary axis routine for a polar or Smith axis system is:

- YPOLAR plots a polar Y-axis

The call is: | CALL YPOLAR (A, B, OR, STEP, CSTR, NDIST) | level 2, 3
or: | void ypolar (float a, float b, float or, float step, const char *cstr, int ndist);

NDIST | is the distance to the polar or Smith circle in plot coordinates. The other parameters have the same meaning as above.

## 4.7 Calculating Axis Parameters

G A X P A R

The routine GAXPAR calculates parameters for GRAF from a minimum and maximum of data values.

The call is: | CALL GAXPAR (V1, V2, COPT, CAX, A, B, OR, STP, NDIG) | level 1, 2, 3
or: | void gaxpar (float v1, float v2, const char *copt, const char *cax, float *a, float *b, float *or, float *stp, int *ndig);

V1, V2 | are the lower and upper limits of the axis. If V1 > V2, the calculated parameters will be in descending order.
COPT | is a character string that can have the values 'NOEXTEND' and 'EXTEND'. For COPT = 'EXTEND', the calculated axis limits can be extended to a full axis step. Otherwise, V1 and V2 are used as axis limits.
CAX | is a character string that defines the axis. CAX can have the values 'X', 'Y', and 'Z'.
A, B | are the calculated limits of the axis.
OR, STP | are the first axis label and the step between labels.
NDIG | is the calculated number of digits after the decimal point that should be set with the routine LABDIG for the labels.

Additional notes:

- The same algorithm as in SETSCL for setting automatic axis scaling is applied to GAXPAR.
- The current axis settings such as linear or logarithmic scaling are used by GAXPAR. For logarithmic scaling, the parameters V1 and V2 must be exponents of base 10.

Next | Previous | Contents