Chapter 11: 3-D Colour Graphics

11.1 Introduction

This chapter presents subroutines that plot coloured surfaces in three dimensions. Coloured surfaces are easy to interpret and show the full range of data points. A data point is plotted as a coloured rectangle where the X- and Y-coordinates determine the position of the rectangle and the Z-coordinate defines the colour. Colours are calculated from a scaled colour bar which is, by default, arranged as a rainbow.

11.2 Plotting Coloured Axis Systems

G R A F 3

The routine GRAF3 plots a 3-D axis system where the Z-axis is plotted as a colour bar.

The call is: CALL GRAF3 (XA, XE, XOR, XSTP, YA, YE, YOR, YSTP, ZA, ZE, ZOR, ZSTP) level 1
or: void graf3 (float xa, float xe, float xor, float xstp, float ya, float ye, float yor, float ystp, float za, float ze, float zor, float zstp);

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.
ZA, ZE are the lower and upper limits of the Z-axis.
ZOR, ZSTP are the first Z-axis label and the step between labels.

Additional note:

11.3 Secondary Colour Bars

GRAF3 plots a vertical colour bar on the right side of a 3-D axis system which can be shifted with the routines VKXBAR and VKYBAR or suppressed with the routine NOBAR. To plot horizontal colour bars at global positions, the routines ZAXIS and ZAXLG can be used. ZAXIS plots a linearly and ZAXLG a logarithmically scaled colour bar.

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

A, B are the lower and upper limits of the colour bar.
OR, STEP are the first label and the step between labels.
NL is the length of the colour bar 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 a counter-clockwise direction.
NDIR defines the direction of the colour bar. If NDIR = 0, a vertical colour bar will be plotted; if NDIR = 1, a horizontal colour bar will be plotted.
NX, NY are the plot coordinates of the lower left corner.

Analog: ZAXLG plots a logarithmically scaled colour bar.

Additional note:

11.4 Plotting Data Points

The routines CURVE3, CURVX3, CURVY3, CRVMAT and CRVTRI plot three-dimensional data points. CURVE3 plots random points from X-, Y- and Z-arrays, CURVY3 plots points as columns, CURVX3 plots data points as rows, CRVMAT plots a coloured surface according to a matrix while while CRVTRI plots the surface of the Delaunay triangulation of the points.

The calls are: CALL CURVE3 (XRAY, YRAY, ZRAY, N) level 3
  CALL CURVX3 (XRAY, Y, ZRAY, N) level 3
  CALL CURVY3 (X, YRAY, ZRAY, N) level 3
  CALL CRVMAT (ZMAT, IXDIM, IYDIM, IXPTS, IYPTS) level 3
  CALL CRVTRI (XRAY, YRAY, ZRAY, N, I1RAY, I2RAY, I3RAY, NTRI) level 3

or: void curve3 (float *xray, float *yray, float *zray, int n); level 3
  void curvx3 (float *xray, float y, float *zray, int n); level 3
  void curvy3 (float x, float *yray, float *zray, int n); level 3
  void crvmat (float *zmat, int ixdim, int iydim, int ixpts, int iypts); level 3
  void crvtri (float *xray, float *yray, float *zray, int n, int *i1ray, int *i2ray, int *i3ray, int ntri) level 3

where

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.
X is the X-position of a column of data points.
Y is the Y-position of a row of data points.
ZMAT is a matrix of the dimension (IXDIM, IYDIM) containing Z-coordinates. The coordinates correspond to a linear grid that overlays the axis system. If XA, XE, YA and YE are the axis limits in GRAF3 or values defined with the routine SURSZE, the relationship between the grid points and the matrix elements can be described by the formula:
ZMAT(I,J) = F(X,Y) where X = XA + (I - 1) * (XE - XA) / (IXDIM - 1) , I = 1,..,IXDIM and
Y = YA + (J - 1) * (YE - YA) / (IYDIM - 1) , J = 1,..,IYDIM.
IXDIM, IYDIM define the dimension of ZMAT (>= 2).
IXPTS, IYPTS are the number of interpolation steps between grid lines (>= 1). CRVMAT can interpolate points linearly.
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.

Additional notes:

11.5 Parameter Setting Routines

S E T R E S

SETRES defines the size of rectangles plotted by CURVE3, CURVY3 and CRVMAT.

The call is: CALL SETRES (NPB, NPH) level 1, 2, 3
or: void setres (int npb, int nph);

NPB, NPH are the width and height of rectangles in plot coordinates (> 0). Default: (1,1).

A U T R E S

With a call to AUTRES, the size of coloured rectangles will be automatically calculated by GRAF3 or CRVMAT.

The call is: CALL AUTRES (IXDIM, IYDIM) level 1
or: void autres (int ixdim, int iydim);

IXDIM, IYDIM are the number of data points in the X- and Y-direction.

A X 3 L E N

The routine AX3LEN defines the axis lengths of a coloured axis system.

The call is: CALL AX3LEN (NXL, NYL, NZL) level 1, 2, 3
or: void ax3len (int nxl, int nyl, int nzl);

NXL, NYL, NZL are the axis lengths in plot coordinates.

W I D B A R

The routine WIDBAR defines the width of a colour bar.

The call is: CALL WIDBAR (NZB) level 1, 2, 3
or: void widbar (int nzb);

NZB is the width in plot coordinates. Default NZB = 85

V K X B A R

The routine VKXBAR defines horizontal shifting of colour bars. The distance between the colour bar and the axis system is, by default, 85 plot coordinates.

The call is: CALL VKXBAR (NVFX) level 1, 2, 3
or: void vkxbar (int nvfx);

NVFX is an integer that defines the shifting. If NVFX is positive, the colour bar will be shifted right; if NVFX is negative the colour bar will be shifted left. Default: NVFX = 0

V K Y B A R

The routine VKYBAR defines a vertical shifting of colour bars.

The call is: CALL VKYBAR (NVFY) level 1, 2, 3
or: void vkybar (int nvfy);

NVFY is an integer that defines the shifting. If NVFY is positive, the colour bar will be shifted up; if NVFY is negative, the colour bar will be shifted down. Default: NVFY = 0

N O B A R

The routine NOBAR instructs DISLIN to suppress the plotting of colour bars.

The call is: CALL NOBAR level 1, 2, 3
or: void nobar (void);

C O L R A N

This routine defines the range of colours used for colour bars. By default, the range is 1 to 254.

The call is: CALL COLRAN (NCA, NCE) level 1, 2, 3
or: void colran (int nca, int nce);

NCA, NCE are colour numbers in the range 1 to 254. Default: (1, 254).

N O B G D

With a call to the routine NOBGD, the plotting of points with the colour 0 will be suppressed. This reduces plotting time and the size of plotfiles.

The call is: CALL NOBGD level 1, 2, 3
or: void nobgd (void);

E X P Z L B

The routine EXPZLB expands the numbering of a logarithmically scaled Z-axis to the next order of magnitude that lies up or down the axis limits. The scaling of the colour bar will not be changed. This routine is useful if the range of the Z-axis scaling is smaller than 1 order of magnitude.

The call is: CALL EXPZLB (CSTR) level 1, 2, 3
or: void expzlb (char *cstr);

CSTR is a character string defining the expansion of the Z-axis numbering.
= 'NONE' means that the numbering will not be expanded.
= 'FIRST' means that the numbering will be expanded downwards.
= 'BOTH' means that the numbering will be expanded down- and upwards. Default: CSTR = 'NONE'.

11.6 Elementary Plot Routines

The following routines plot coloured rectangles and pie sectors. They use the hardware features of a colour graphics system or PostScript printer.

R E C F L L

The routine RECFLL plots a coloured rectangle where the position is determined by the upper left corner.

The call is: CALL RECFLL (NX, NY, NB, NH, NCOL) level 1, 2, 3
or: void recfll (int nx, int ny, int nb, int nh, int ncol);

NX, NY are the plot coordinates of the upper left corner.
NB, NH are the width and height in plot coordinates.
NCOL is a colour value.

P O I N T

The routine POINT plots a coloured rectangle where the position is determined by the centre.

The call is: CALL POINT (NX, NY, NB, NH, NCOL) level 1, 2, 3
or: void point (int nx, int ny, int nb, int nh, int ncol);

NX, NY are the plot coordinates of the centre point.
NB, NH are the width and height in plot coordinates.
NCOL is a colour value.

R L P O I N

The routine RLPOIN plots a coloured rectangle where the position is specified in user coordinates.

The call is: CALL RLPOIN (X, Y, NB, NH, NCOL) level 2, 3
or: void rlpoin (float x, float y, int nb, int nh, int ncol);

Additional note:

S E C T O R

The routine SECTOR plots coloured pie sectors.

The call is: CALL SECTOR (NX, NY, NR1, NR2, ALPHA, BETA, NCOL) level 1, 2, 3
or: void sector (int nx, int ny, int nr1, int nr2, float alpha, float beta, int ncol);

NX, NY are the plot coordinates of the centre point.
NR1 is the interior radius.
NR2 is the exterior radius.
ALPHA, BETA are the start and end angles measured in degrees in a counter-clockwise direction.
NCOL is a colour index between 0 and 255.
Example: CALL SECTOR (100, 100, 0, 50, 0., 360., NCOL) plots a circle around the centre (100,100) with the radius 50 and the colour NCOL.

R L S E C

The routine RLSEC plots coloured pie sectors where the centre and the radii are specified in user coordinates.

The call is: CALL RLSEC (X, Y, R1, R2, ALPHA, BETA, NCOL) level 2, 3
or: void rlsec (float x, float y, float r1, float r2, float alpha, float beta, int ncol);

Additional Notes:

11.7 Conversion of Coordinates

The function NZPOSN and the subroutine COLRAY convert user coordinates to colour values.

N Z P O S N

The function NZPOSN converts a Z-coordinate to a colour number.

The call is: ICLR = NZPOSN (Z) level 3
or: int nzposn (float z);

Z is an user coordinate. If Z lies outside of the axis limits and Z is smaller than the lower limit, NZPOSN returns the value 0 and the routine returns the value 255 if Z is greater than the upper limit.

C O L R A Y

The routine COLRAY converts an array of Z-coordinates to colour values.

The call is: CALL COLRAY (ZRAY, NRAY, N) level 3
or: void colray (float *zray, int *nray, int n);

ZRAY is an array of Z-coordinates.
NRAY is an array of colour numbers calculated by COLRAY.
N is the number of coordinates.

11.8 Example


Next | Previous | Contents