# Chapter 14: Contouring

This chapter describes routines for contouring three-dimensional functions of the form Z = F(X,Y). Contours can be generated with the routine CONPTS or with other software packages and plotted with the routine CONCRV or can be calculated and plotted by DISLIN with the routines CONMAT, CONTUR, CONTUR2, CONSHD and CONSHD2.

## 14.1 Plotting Contours

C O N C R V

CONCRV plots contours generated by other software packages.

The call is: | CALL CONCRV (XRAY, YRAY, N, ZLEV) | level 2, 3
or: | void concrv (const float *xray, const float *yray, int n, float zlev);

XRAY, YRAY | are arrays containing the X- and Y-coordinates of a contour line.
N | is the number of points.
ZLEV | is a function value used for labels.

C O N T U R

The routine CONTUR calculates and plots contours of the function Z = F(X,Y).

The call is: | CALL CONTUR (XRAY, N, YRAY, M, ZMAT, ZLEV) | level 2, 3
or: | void contur (const float *xray, int n, const float *yray, int m, const float *zmat, float zlev);

XRAY | is an array containing X-coordinates.
N | is the dimension of XRAY.
YRAY | is an array containing Y-coordinates.
M | is the dimension of YRAY.
ZMAT | is a matrix of the dimension (N, M) containing function values.
ZLEV | is a function value that defines the contour line to be calculated. ZLEV can be used for labels.

C O N T U R 2

The routine CONTUR2 calculates and plots contours of the function Z = F(X,Y), where the functions values are located on a curvilinear grid.

The call is: | CALL CONTUR2 (XMAT, YMAT, ZMAT, N, M, ZLEV) | level 2, 3
or: | void contur2 (const float *xmat, const float *ymat, const float *zmat, int n, int m, float zlev);

XMAT | is a matrix of the dimension (N, M) containing the X-coordinates of the curvilinear grid.
YMAT | is a matrix of the dimension (N, M) containing the Y-coordinates of the curvilinear grid.
ZMAT | is a matrix of the dimension (N, M) containing function values.
N, M | define the dimension of XMAT, YMAT and ZMAT.
ZLEV | is a function value that defines the contour line to be calculated. ZLEV can be used for labels.

C O N M A T

The routine CONMAT plots contours of the function Z = F(X,Y). The function values correspond to a linear grid in the XY-plane.

The call is: | CALL CONMAT (ZMAT, N, M, ZLEV) | level 2, 3
or: | void conmat (const float *zmat, int n, int m, float zlev);

ZMAT | is a matrix of the dimension (N, M) containing the function values. If XA, XE, YA and YE are the axis limits in GRAF or values defined with the routine SURSZE, the connection of grid points and matrix elements can be described by the formula: ZMAT(I,J) = F(X,Y) where X = XA + (I - 1) * (XE - XA) / (N - 1) , I = 1,..,N and Y = YA + (J - 1) * (YE - YA) / (M - 1) , J = 1,..,M.
N, M | define the dimension of ZMAT.
ZLEV | is a function value that defines the contour line to be calculated. The value can be used for labels.

Additional notes:

- CONCRV, CONTUR and CONMAT use linear interpolation to connect contour points.
- Geographical projections can be defined for contouring.
- The thickness of contours can be set with THKCRV. Line styles and colours can also be defined. Legends are supported for filled and non-filled contours.
- The number of matrix points in CONTUR and CONMAT is limited to N * M <= 256000 in Fortran 77. There is no limit for the C and Fortran 90 libraries of DISLIN
- To plot contours for randomly distributed points of the form X(N), Y(N) and Z(N), the routine GETMAT can be used to calculate a function matrix, or the data can be triangulated with the routine TRIANG and contours can be plotted from the triangulation with the routine CONTRI.

C O N T R I

The routine CONTRI plots contours from triangulated data that can be calculated by the routine TRIANG from a set of irregularly distributed data points.

The call is: | CALL CONTRI (XRAY, YRAY, ZRAY, N, I1RAY, I2RAY, I3RAY, NTRI, ZLEV) | level 2, 3
or: | void contri (const float *xray, const float *yray, const float *zray, int n, const int *i1ray, const int *i2ray, const int *i3ray, int ntri, float zlev);

XRAY | is an array containing the X-coordinates of data points.
YRAY | is an array containing the Y-coordinates of data points.
ZRAY | is an array containing the Z-coordinates of data points.
N | is the number of data points.
I1RAY, I2RAY, I3RAY | is the Delaunay triangulation of the points (XRAY, YRAY) calculated by the routine TRIANG.
NTRI | is the number of triangles in I1RAY, I2RAY and I3RAY.
ZLEV | is a function value that defines the contour line to be calculated.

## 14.2 Plotting Filled Contours

C O N S H D

The routine CONSHD plots filled contours of the function Z = F(X,Y). Two algorithms can be selected for contour filling: a cell filling algorithm and a polygon filling algorithm. For a polygon filling, only closed contours can be filled. The algorithm can be defined with the routine SHDMOD.

The call is: | CALL CONSHD (XRAY, N, YRAY, M, ZMAT, ZLVRAY, NLEV) | level 2, 3
or: | void conshd (const float *xray, int n, const float *yray, int m, const float *zmat, const float *zlvray, int nlev);

XRAY | is an array containing X-coordinates.
N | is the dimension of XRAY.
YRAY | is an array containing Y-coordinates.
M | is the dimension of YRAY.
ZMAT | is a matrix of the dimension (N, M) containing function values.
ZLVRAY | is an array containing the levels. The levels must be sorted in ascending order if cell filling is selected. For polygon filling, the levels should be sorted in such a way that inner contours are plotted last.
NLEV | is the number of levels.

Additional notes:

- CONSHD may give better results for a higher resolution of ZMAT. A matrix with a higher resolution can be calculated with the routine TRFMAT.
- The colours of the filled contours are calculated from a fictive colour bar where the minimum and maximum of the contour levels are used for the lower and upper limits of the colour bar. The scaling of the colour bar can be modified with the routine ZSCALE while a colour bar can be displayed with the routine ZAXIS. If the colours of the filled contours should not be calculated from a colour bar, they can be defined directly with the routine CONCLR.
- For a cell filling, the calculation of contour colours are described in the following. The levels are sorted first in ascending order. By default, the colour of the region between two neighbouring levels is calculated from the lower value of the two levels. If you want to use the upper value, you can define it with the routine SHDMOD ('UPPER', 'COLOUR'). In default mode (SHDMOD ('LOWER', 'COLOUR'), the cells below the minimum of the levels are filled with the lowermost colour of the colour bar, the cells above the maximum of the levels are filled with the uppermost colour of the colour bar. The plotting of this regions can be suppressed with the statement CALL SHDMOD ('NONE', 'CELL').

C O N S H D 2

The routine CONSHD2 plots filled contours of the function Z = F(X,Y), where the functions values are located on a curvilinear grid.

The call is: | CALL CONSHD2 (XMAT, YMAT, ZMAT, N, M, ZLVRAY, NLEV) | level 2, 3
or: | void conshd2 (const float *xmat, const float *ymat, const float *zmat, int n, int m, const float *zlvray, int nlev);

XMAT | is a matrix of the dimension (N, M) containing the X-coordinates of the curvilinear grid.
YMAT | is a matrix of the dimension (N, M) containing the Y-coordinates of the curvilinear grid.
ZMAT | is a matrix of the dimension (N, M) containing function values.
N, M | define the dimension of XMAT, YMAT and ZMAT.
ZLVRAY | is an array containing the levels. The levels must be sorted in ascending order if cell filling is selected. For polygon filling, the levels should be sorted in such a way that inner contours are plotted last.
NLEV | is the number of levels.

C O N F L L

The routine CONFLL plots filled contours from triangulated data that can be calculated by the routine TRIANG from a set of irregularly distributed data points.

The call is: | CALL CONFLL (XRAY, YRAY, ZRAY, N, I1RAY, I2RAY, I3RAY, NTRI, ZLVRAY, NLEV) | level 2, 3
or: | void confll (const float *xray, const float *yray, const float *zray, int n, const int *i1ray, const int *i2ray, const int *i3ray, int ntri, const float *zlvray, int nlev);

XRAY | is an array containing the X-coordinates of data points.
YRAY | is an array containing the Y-coordinates of data points.
ZRAY | is an array containing the Z-coordinates of data points.
N | is the number of data points.
I1RAY, I2RAY, I3RAY | is the Delaunay triangulation of the points (XRAY, YRAY) calculated by the routine TRIANG.
NTRI | is the number of triangles in I1RAY, I2RAY and I3RAY.
ZLVRAY | is an array containing the levels.
NLEV | is the number of levels.

## 14.3 Generating Contours

C O N P T S

The routine CONPTS generates contours without plotting. Multiple curves can be returned for one contour level.

The call is: | CALL CONPTS (XRAY, N, YRAY, M, ZMAT, ZLEV, XPTRAY, YPTRAY, MAXPTS, IRAY, MAXCRV, NCURVS) | level 0, 1, 2, 3
or: | void conpts (const float *xray, int n, const float *yray, int m, const float *zmat, float zlev, float *xptray, float *yptray, int maxpts, int *iray, int maxcrv, int *ncurvs);

XRAY | is an array containing X-coordinates.
N | is the dimension of XRAY.
YRAY | is an array containing Y-coordinates.
M | is the dimension of YRAY.
ZMAT | is a matrix of the dimension (N, M) containing function values.
ZLEV | is a function value that defines the contour line to be calculated.
XPTRAY, YPTRAY | are returned arrays containing the calculated contour. The arrays can contain several curves.
MAXPTS | is the maximal number of points that can be passed to XPTRAY and YPTRAY.
IRAY | is a returned integer array that contains the number of points for each generated contour curve.
MAXCRV | is the maximal number of entries that can be passed to IRAY.
NCURVS | is the returned number of generated curves.

Example:

The following statements generate from some arrays XRAY, YRAY and ZMAT contours and plot them with the routine CURVE.

          PARAMETER (N=100, MAXPTS=1000,MAXCRV=10)
          REAL ZMAT(N,N),XRAY(N),YRAY(N),XPTS(MAXPTS),YPTS(MAXPTS)
          INTEGER IRAY(MAXCRV)
          .....
          DO I=1,12
            ZLEV=0.1+(I-1)*0.1
            CALL CONPTS(XRAY,N,YRAY,N,ZMAT,ZLEV,XPTS,YPTS,MAXPTS,
         *              IRAY,MAXCRV,NCURVS)
            K=1
            DO J=1,NCURVS
              CALL CURVE(XPTS(K),YPTS(K),IRAY(J))
              K=K+IRAY(J)
            END do
          END DO

T R I P T S

The routine TRIPTS generates contours from triangulated data without plotting. Multiple curves can be returned for one contour level.

The call is: | CALL TRIPTS (XRAY, YRAY, ZRAY, N, I1RAY, I2RAY, I3RAY, NTRI, ZLEV, XPTRAY, YPTRAY, MAXPTS, IRAY, MAXCRV, NCURVS) | level 0, 1, 2, 3
or: | void tripts (const float *xray, const float *yray, const float *zray, int n, const int *i1ray, const int *i2ray, const int *i3ray, int ntri, float zlev, float *xptray, float *yptray, int maxpts, int *iray, int maxray, int *ncurvs);

XRAY | is an array containing the X-coordinates of data points.
YRAY | is an array containing the Y-coordinates of data points.
ZRAY | is an array containing the Z-coordinates of data points.
N | is the number of data points.
I1RAY, I2RAY, I3RAY | is the Delaunay triangulation of the points (XRAY, YRAY) calculated by the routine TRIANG.
NTRI | is the number of triangles in I1RAY, I2RAY and I3RAY.
ZLEV | is a function value that defines the contour line to be calculated.
XPTRAY, YPTRAY | are returned arrays containing the calculated contour. The arrays can contain several curves.
MAXPTS | is the maximal number of points that can be passed to XPTRAY and YPTRAY.
IRAY | is a returned integer array that contains the number of points for each generated contour curve.
MAXCRV | is the maximal number of entries that can be passed to IRAY.
NCURVS | is the returned number of generated curves.

## 14.4 Parameter Setting Routines

L A B E L S

The routine LABELS defines contour labels.

The call is: | CALL LABELS (COPT, 'CONTUR') | level 1, 2, 3
or: | void labels (const char *copt, "CONTUR");

COPT | is a character string defining the labels.
= 'NONE' | means that no labels will be plotted.
= 'FLOAT' | means that the level value will be used for labels.
= 'CONLAB' | means that labels defined with the routine CONLAB will be plotted. Default: COPT = 'NONE'.

Additional note:

- The number of decimal places in contour labels can be defined with CALL LABDIG (NDIG, 'CONTUR'). The default value for NDIG is 1.

L A B T Y P

The routine LABTYP defines horizontal or vertical labels.

The call is: | CALL LABTYP \ (CTYPE, 'CONTUR') | level 1, 2, 3
or: | void labtyp (const char *ctype, "CONTUR");

CTYPE | is a character string defining the direction.
= 'HORI' | defines horizontal labels, where horizontal means that the labels have the same direction as the contour line.
= 'VERT' | defines vertical labels. Default: CTYPE = 'HORI'.

L A B D I S

The routine LABDIS defines the distance between contour labels.

The call is: | CALL LABDIS (NDIS, 'CONTUR') | level 1, 2, 3
or: | void labdis (int ndis, "CONTUR");

NDIS | is the distance between labels in plot coordinates. Default: NDIS = 500

L A B C L R

The routine LABCLR defines the colour of contour labels.

The call is: | CALL LABCLR (NCLR, 'CONTUR') | level 1, 2, 3
or: | void labclr (int nclr, "CONTUR");

NCLR | is a colour number value. If NCLR = -1, the contour labels will be plotted with the current colour. Default: NCLR = -1

C O N L A B

The routine CONLAB defines a character string which will be used for labels if the routine LABELS is called with the parameter 'CONLAB'.

The call is: | CALL CONLAB (CLAB) | level 1, 2, 3
or: | void conlab (const char *clab);

CLAB | is a character string containing the label. Default: CLAB = ' '.

C O N M O D

The routine CONMOD modifies the appearance of contour labels. By default, DISLIN suppresses the plotting of labels at a position where the contour is very curved. To measure the curvature of a contour for an interval, DISLIN calculates the ratio between the arc length and the length of the straight line between the interval limits. If the quotient is much greater than 1, the contour line is very curved in that interval.

The call is: | CALL CONMOD (XFAC, XQUOT) | level 1, 2, 3
or: | void conmod (float xfac, float xquot);

XFAC | defines the length of intervals (>= 0). The curvature of contours will be tested in intervals of the length (1 + XFAC) * W where W is the label length.
XQUOT | defines a upper limit for the quotient of arc length and length of the straight line (> 1). If the quotient is greater than XQUOT, the plotting of labels will be suppressed in the tested interval. Default: (0.5, 1.5).

C O N G A P

The routine CONGAP defines the distance between contour lines and labels.

The call is: | CALL CONGAP (XFAC) | level 1, 2, 3
or: | void congap (float xfac);

XFAC | is a real number used as a scaling factor. The distance between contour lines and labels is set to XFAC * NH where NH is the current character height. Default: XFAC = 0.5.

S H D M O D

The routine SHDMOD selects the algorithm used for contour filling, or modifies options for cell filling.

The call is: | CALL SHDMOD (COPT, CKEY) | level 1, 2, 3
or: | void shdmod (const char *copt, const char *ckey);

CKEY | is a character string containing one of the following keywords:
= 'CONTUR' | defines the algorithm used for contour filling. COPT can have the values 'CELL' and 'POLY'. The default value is COPT = 'CELL'.
= 'CELL' | modifies the cell filling algorithm. COPT can have the values 'BOTH', 'UPPER', 'LOWER' and 'NONE'. If COPT = 'NONE', the filling of the regions below and above the level limits are suppressed. If COPT = 'UPPER', the filling of the region below the lowermost level is suppressed. COPT = 'LOWER' means that the filling of the region above the uppermost level is suppressed. By default, both regions described above are filled.
= 'COLOR' | modifies the calculation of colours for cell filling. COPT can have the values 'LOWER', 'MIDDLE' and 'UPPER'. For COPT = 'LOWER', the lower value of two neighbouring levels is used for colour calculation, for COPT = 'UPPER', the upper value of two neighbouring levels is used, and for COPT = 'MIDDLE', the mean value of the two levels is used for colour calculation. The default value is COPT = 'LOWER'.

C O N C L R

The routine CONCLR defines colours for filled contour lines.

The call is: | CALL CONCLR (NCRAY, N) | level 1, 2, 3
or: | void conclr (const int *ncray, int n);

NCRAY | is an integer array containing colour numbers.
N | is the number of entries in NCRAY (<= 256).

## 14.5 Examples

- Contour Plot of f(x,y) = 2 * sin(x) * sin(y)

- Contour Plot of f(x,y) = (x**2 - 1)**2 + (y**2 - 1)**2

- Shaded Contour Plot of f(x,y) = 2 * sin(x) * sin(y)

Next | Previous | Contents