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:

GRAF3 must be called from level 1 and sets the level to 3. For additional notes, the user is referred to the routine GRAF in chapter 4.

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, const 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.

Analogue: ZAXLG plots a logarithmically scaled colour bar.

Additional note:

The user is referred to the notes on secondary axes in chapter 4.

11.4 Plotting Data Points

The routines CURVE3, CURVX3, CURVY3, CRVMAT, CRVTRI and CRVQDR 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 and CRVMAT plots a coloured surface according to a matrix. The routines CRVTRI and CRVQDR plot triangles and quadrangles as they are often used in finite element methods.

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

CALL CRVQDR (XRAY, YRAY, ZRAY, N) level 3

or: void curve3 (const float *xray, const float *yray, const float *zray, int n); level 3

void curvx3 (const float *xray, float y, const float *zray, int n); level 3

void curvy3 (float x, const float *yray, const float *zray, int n); level 3

void crvmat (const float *zmat, int ixdim, int iydim, int ixpts, int iypts); level 3

void crvtri (const float *xray, const float *yray, const float *zray, int n, const int *i1ray, const int *i2ray, const int *i3ray, int ntri) level 3

void crvqdr (const float *xray, const float *yray, const float *zray, int n); 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 a triangulation of the points (XRAY, YRAY). A Delaunay triangulation of data poins can for example calculated with the routine TRIANG.

NTRI is the number of triangles in I1RAY, I2RAY and I3RAY.

Additional notes:

CURVE3, CURVY3 and CRVMAT must be called after GRAF3 from level 3.
The size of coloured rectangles can be defined with the routine SETRES or calculated automatically by DISLIN using the routine AUTRES.
CURVE3, CURVX3, CURVY3 and CRVMAT can plot rectangles, pixels and symbols. The mode can be selected with SHDMOD.
CRVMAT supports mesh lines defined by SURMSH.
Z-coordinates that lie outside of the axis scaling will be plotted with the colour 0 if they are smaller than the lower limit, or with the colour 255 if they are greater than the upper limit. To reduce computing time and the size of plot files, the plotting of points with the colour 0 can be suppressed with the routine NOBGD.
The routines CRVTRI and CRVQDR can plot smooth surfaces with interpolated colours if the statement CALL SHDMOD ('SMOOTH', 'SURFACE') is used before. For this case, a raster format must be defined with METAFL.
For CRVQDR, the data points describe the corners of the quadrangles: the first four points the first quadrangle, the next four points the next quadrangle, and so on. The number of quadrangles is N / 4.
The routines CONMAT and SURMAT are analogy to CRVMAT and plot contours and surfaces of space.

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, 2, 3

or: void autres (int ixdim, int iydim);

IXDIM, IYDIM are the number of data points in the X- and Y-direction, or (0, 0). If IXDIM = 0 and IYDIM = 0, CRVMAT plots rectangles between neighbouring data points. This is useful for logarithmic axes, where the rectangles should have a different size. A negative value can be used for a logartithmic axis scaling, where the matrix in CRVMAT contains already a logarithmic grid.

S H D M O D

Normally, the routines CURVE3, CURVX3, CURVY3 and CRVMAT plot coloured rectangles, but a symbol or pixel mode can be enabled with the routine SHDMOD. The symbols used by the routines above and the size of the symbols can be set with the routines MARKER and HSYMBL. Pixel mode can only be used for screen and image output.

The call is: CALL SHDMOD (COPT, 'CURVE') level 1

or: void shdmod (const char *copt, "CURVE");

COPT is a character string that can have the values 'RECT', 'SYMB' and 'PIXE'. Default: COPT = 'RECT'.

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.

P O S B A R

The routine POSBAR sets the position of colour bars. By default, colour bars are plotted in a vertical direction near the right Y-axis of an axis system.

The call is: CALL POSBAR (COPT) level 1, 2, 3

or: void posbar (const char *copt);

COPT is a character value defining the position of colour bars.

= 'FIXED' means that the colour bar is plotted in a vertical direction near the right Y-axis.

= 'RIGHT' has nearly the same meaning as the keyword 'FIXED', but the colour bar is automatically moved if labels and an axis title is plotted at the right Y-axis.

= 'TOP' means that the colour bar is plotted above the axis system in a horizontal direction.

= 'BOTTOM' means that the colour bar is plotted below the axis system in a horizontal direction.

= 'LEFT' means that the colour bar is plotted on the left side of the axis system. Default: COPT = 'FIXED'.

J U S B A R

JUSBAR defines alignment of colour bars.

The call is: CALL JUSBAR (COPT) level 1, 2, 3

or: void jusbar (const char *copt);

COPT is a character value defining the alignment of colour bars.

= 'START' means that the colour bar is plotted at the beginning of the X- or Y-axis.

= 'CENTER' means that the colour bar is centred at the X- or Y-axis.

= 'END' means that the colour bar is justified at the end of the X- or Y-axis. Default: COPT = 'START'.

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

F R M B A R

The routine FRMBAR defines the thickness of frames around colour bars.

The call is: CALL FRMBAR (N) level 1, 2, 3

or: void frmbar (int n);

N is the thickness in plot coordinates. Default N = 0

S P C B A R

The routine SPCBAR defines the space between colour bars and axis systems.

The call is: CALL SPCBAR (N) level 1, 2, 3

or: void spcbar (int n);

N is the space in plot coordinates. Default N = 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 plot files.

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 (const 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:

RLPOIN clips rectangles at the borders of an axis system.

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:

For the conversion of the radii to plot coordinates, the scaling of the X-axis is used.
Sectors plotted by RLSEC will not be cut off at the borders of an axis system.

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 a 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 (const 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

3-D Colour Plot

Next | Previous | Contents

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.

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, const 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.

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
	CALL CRVQDR (XRAY, YRAY, ZRAY, N)	level 3

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

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 a triangulation of the points (XRAY, YRAY). A Delaunay triangulation of data poins can for example calculated with the routine TRIANG.
NTRI	is the number of triangles in I1RAY, I2RAY and I3RAY.

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

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

The call is:	CALL SHDMOD (COPT, 'CURVE')	level 1
or:	void shdmod (const char *copt, "CURVE");

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

The call is:	CALL POSBAR (COPT)	level 1, 2, 3
or:	void posbar (const char *copt);

COPT	is a character value defining the position of colour bars.
= 'FIXED'	means that the colour bar is plotted in a vertical direction near the right Y-axis.
= 'RIGHT'	has nearly the same meaning as the keyword 'FIXED', but the colour bar is automatically moved if labels and an axis title is plotted at the right Y-axis.
= 'TOP'	means that the colour bar is plotted above the axis system in a horizontal direction.
= 'BOTTOM'	means that the colour bar is plotted below the axis system in a horizontal direction.
= 'LEFT'	means that the colour bar is plotted on the left side of the axis system. Default: COPT = 'FIXED'.

The call is:	CALL JUSBAR (COPT)	level 1, 2, 3
or:	void jusbar (const char *copt);

COPT	is a character value defining the alignment of colour bars.
= 'START'	means that the colour bar is plotted at the beginning of the X- or Y-axis.
= 'CENTER'	means that the colour bar is centred at the X- or Y-axis.
= 'END'	means that the colour bar is justified at the end of the X- or Y-axis. Default: COPT = 'START'.

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

The call is:	CALL FRMBAR (N)	level 1, 2, 3
or:	void frmbar (int n);

The call is:	CALL SPCBAR (N)	level 1, 2, 3
or:	void spcbar (int n);

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

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

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

The call is:	CALL EXPZLB (CSTR)	level 1, 2, 3
or:	void expzlb (const 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'.

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.

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.

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);

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.