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.

The following plotting routines require special graphics devices that can display a wide range of colours, such as a workstation or a PC with a VGA card. These devices will be called colour graphics systems throughout this chapter. A laserprinter with a PostScript emulation can also be used for 3-D colour graphics.

Additional notes:

11.2 X Window Terminals

X Window terminals are the usual graphics displays on workstations. In DISLIN, the X Window emulation can be activated with the keywords 'CONS', 'XWIN' and 'XWIi' in the routine METAFL where i is a window number between 1 and 5. For the keyword 'CONS', the entire screen will be used for graphics output while for the other keywords, smaller windows are created. The keywords 'XWIN' and 'XWI1' have the same meaning. By default, the position of windows depends upon the window number. Window 1 is situated in the lower right corner, window 2 in the upper right corner, window 3 in the upper left corner, window 4 in the lower left corner and window 5 in the centre of the screen. The position and size of windows can be changed with the routines WINDOW and WINSIZ.

Additional notes:

11.3 PostScript Files

PostScript files can be created from within DISLIN if the keywords 'POST' and 'PSCL' are used in METAFL. For the keyword 'POST', the greyscale table 'RGREY' will be preloaded by DISINI and the graphics will be plotted with a white background. For the keyword 'PSCL', the colour table 'RAIN' will be preloaded and the graphics will be plotted with a black background. To create a colour PostScript file with a white background, use the statement CALL SRCMOD ('REVERSE') before DISINI and the keyword 'PSCL' in METAFL.

11.4 Clearing the Screen

E R A S E

The routine ERASE clears the screen of a colour graphics system or of a graphics terminal. In general, this is done by DISINI at the beginning of a plot.

The call is:
CALL ERASE - level 1, 2, 3

11.5 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, XSTEP, YA, YE, YOR, YSTEP, ZA, ZE, ZOR, ZSTEP)

XA, XE
are the lower and upper limits of the X-axis.
XOR, XSTEP
are the first X-axis label and the step between labels.
YA, YE
are the lower and upper limits of the Y-axis.
YOR, YSTEP
are the first Y-axis label and the step between labels.
ZA, ZE
are the lower and upper limits of the Z-axis.
ZOR, ZSTEP
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.6 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

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:
The user is referred to the notes on secondary axes in chapter 4.

11.7 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:

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.8 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

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

IXDIM, IYDIM
are the number of data points in the X- and Y-direction.
S E T C L R

The routine SETCLR defines the colour used for text and lines.

The call is:
CALL SETCLR (NCOL) - level 1, 2, 3

NCOL
is a colour number in the range 0 to 255. Default: NCOL = 255 (White).
S E T R G B

The routine SETRGB defines the foreground colour specified in RGB coordinates. SETRGB sets the nearest entry in the colour table that matches the RGB coordinates. This means that a colour will not be defined exactly if it is not contained in the colour table.

The call is:
CALL SETRGB (XR, XG. XB) - level 1, 2, 3

XR, XG, XB
are the RGB coordinates of a colour in the range o to 1.
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

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

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

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

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

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
S E T V L T

SETVLT selects a colour table.

The call is:
CALL SETVLT (CVLT) - level 1, 2, 3

CVLT
is a character string that defines the colour table.
= 'SMALL'
defines a small colour table with the 8 colours:
1 = BLACK, 2 = RED, 3 = GREEN, 4 = BLUE, 5 = YELLOW, 6 = ORANGE, 7 = CYAN and 8 = MAGENTA.
= 'VGA'
defines the 16 standard colours of a VGA graphics card.
= 'RAIN'
defines 256 colours arranged in a rainbow where 0 means black and 255 means white.
= 'SPEC'
defines 256 colours arranged in a rainbow where 0 means black and 255 means white. This colour table uses more violet colours than 'RAIN'.
= 'GREY'
defines 256 grey scale colours where 0 means black and 255 is white.
= 'RRAIN'
is the reverse colour table of 'RAIN'.
= 'RSPEC'
is the reverse colour table of 'SPEC'.
= 'RGREY'
is the reverse colour table of 'GREY'.
= 'TEMP'
defines a temperature colour table.

The default colour table is 'RGREY' for PostScript files created with the keyword 'POST' in the routine METAFL, and otherwise 'RAIN'.

M Y V L T

The routine MYVLT changes the current colour table.

The call is:
CALL MYVLT (XR, XG, XB, N) - level 1, 2, 3

XR, XG, XB
are arrays containing RGB coordinates in the range 0 to 1.
N
is the number of colour entries.
S E T I N D

The routine SETIND allows the user to change the current colour table.

The call is:
CALL SETIND (INDEX, XR, XG, XB) - level 1, 2, 3

INDEX
is an index between 0 and 255.
XR, XG, XB
are the RGB coordinates of a colour in the range 0 to 1.
Sometimes, it is easier to specify colours as HSV coordinates where H is the hue, S the saturation and V the value of a colour. The following routines convert coordinates from the HSV to the RGB model and vice versa.

H S V R G B

The routine HSVRGB converts HSV coordinates to RGB coordinates.

The call is:
CALL HSVRGB (XH, XS, XV, XR, XG, XB) - level 1, 2, 3

XH, XS, XV
are the hue, saturation and value of a colour. XH must be in the range 0 to 360 degrees while XS and XV can have values between 0 and 1. In the HSV model, colours lie in a spectral order on a six-sided pyramid where red corresponds to the angle 0, green to 120 and blue to 240 degrees.
XR, XG, XB
are the RGB coordinates in the range 0 to 1 calculated by HSVRGB.
R G B H S V

The routine RGBHSV converts RGB coordinates to HSV coordinates.

The call is:
CALL RGBHSV (XR, XG, XB, XH, XS, XV) - level 1, 2, 3
R E V S C R

The routine REVSCR exchanges the colours with the indices 0 and 255.

The call is:
CALL REVSCR - level 1, 2, 3
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

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.9 Elementary Image Routines

The following routines allow transfering of image data between windows, files and arrays.

I M G I N I

The routine IMGINI initializes transfering of image data with the routines RPIXEL, RPIXLS, RPXROW, WPIXEL, WPIXLS and WPXROW.

The call is:
CALL IMGINI - level 1, 2, 3
I M G F I N

The routine IMGFIN terminates transfering of image data with the routines RPIXEL, RPIXLS, RPXROW, WPIXEL, WPIXLS and WPXROW.

The call is:
CALL IMGFIN - level 1, 2, 3
R P I X E L

The routine RPIXEL reads one pixel from memory.

The call is:
CALL RPIXEL (IX, IY, ICLR) - level 1, 2, 3

IX, IY
is the position of the pixel in screen coordinates.
ICLR
is the returned colour value of the pixel.
W P I X E L

The routine WPIXEL writes one pixel into memory.

The call is:
CALL WPIXEL (IX, IY, ICLR) - level 1, 2, 3

IX, IY
is the position of the pixel in screen coordinates.
ICLR
is the new colour value of the pixel.
R P I X L S

The routine RPIXLS copies colour values from a rectangle in memory to an array.

The call is:
CALL RPIXLS (IRAY, IX, IY, NW, NH) - level 1, 2, 3

IRAY
is a byte array containing the returned colour values.
IX, IY
contain the starting point in screen coordinates.
NW, NH
are the width and height of the rectangle in screen coordinates.
W P I X L S

The routine WPIXLS copies colour values from an array to a rectangle in memory.

The call is:
CALL WPIXLS (IRAY, IX, IY, NW, NH) - level 1, 2, 3

IRAY
is a byte array containing the colour values.
IX, IY
contain the starting point in screen coordinates.
NW, NH
are the width and height of the rectangle in screen coordinates.
R P X R O W

The routine RPXROW copies one line of colour values from memory to an array.

The call is:
CALL RPXROW (IRAY, IX, IY, N) - level 1, 2, 3

IRAY
is a byte array containing the returned colour values.
IX, IY
contain the starting point in screen coordinates.
N
is the number of image data.
W P X R O W

The routine WPXROW copies colour values from an array to a line in memory.

The call is:
CALL WPXROW (IRAY, IX, IY, N) - level 1, 2, 3

IRAY
is a byte array containing the colour values.
IX, IY
contain the starting point in screen coordinates.
N
is the number of image data.

Additional note:
IMGINI and IMGFIN must be used with the routines RPIXEL, WPIXEL, RPIXLS, WPIXLS, RPXROW and WPXROW.
R I M A G E

The routine RIMAGE copies an image from memory to a file.

The call is:
CALL RIMAGE (CFIL) - level 1, 2, 3

CFIL
is the name of the output file. A new file version will be created for existing files (see FILMOD).
Additional notes:
W I M A G E

The routine WIMAGE copies an image from a file to memory.

The call is:
CALL WIMAGE (CFIL) - level 1, 2, 3

CFIL
is the name of the input file.
R T I F F

The routine RTIFF copies an image from memory to a file. The image is stored in the device-independent TIFF format.

The call is:
CALL RTIFF (CFIL) - level 1, 2, 3

CFIL
is the name of the output file. A new file version will be created for existing files (see FILMOD).
Additional notes:
W T I F F

The routine WTIFF copies a TIFF file created by DISLIN from a file to memory.

The call is:
CALL WTIFF (CFIL) - level 1, 2, 3

CFIL
is the name of the input file.
Additional note:
T I F O R G

The routine TIFORG defines the upper left corner of the screen where the TIFF file is copied to.

The call is:
CALL TIFORG (NX, NY) - level 1, 2, 3

NX, NY
is the upper left corner in screen coordinates.
T I F W I N

The routine TIFWIN defines a clipping window of the TIFF file that can be copied with the routine WTIFF to the screen.

The call is:
CALL TIFWIN (NX, NY, NW, NH) - level 1, 2, 3

NX, NY
is the upper left corner of the clipping window in pixels.
NW, NH
are the width and height of the clipping window in pixels.
R P N G

The routine RPNG copies an image from memory to a PNG file.

The call is:
CALL RPNG (CFIL) - level 1, 2, 3

CFIL
is the name of the output file. A new file version will be created for existing files (see FILMOD).
R B F P N G

The routine RBFPNG copies an image from memory as a PNG file to a buffer.

The call is:
CALL RBFPNG (CBUF, NMAX, N) - level 1, 2, 3

CBUF
is a character buffer where the image is copied to in PNG format.
NMAX
defines how many bytes can be copied to CBUF. If NMAX = 0, the size of the PNG file is returned in N without copying the PNG file to CBUF.
N
is the returned length of the buffer. N <= 0, if an error occurs.
R P P M

The routine RPPM copies an image from memory to a PPM file.

The call is:
CALL RPPM (CFIL) - level 1, 2, 3

CFIL
is the name of the output file. A new file version will be created for existing files (see FILMOD).

11.10 Multiple Windows on X Window Terminals

The following routines allow programs to create up to 5 windows for graphics output on an X Window terminal. Note, that multiple windows can be used with X Window emulation but are not compatible with other file formats in DISLIN.

O P N W I N

The routine OPNWIN creates a new window for graphics output on the screen.

The call is:
CALL OPNWIN (ID) - level 1, 2, 3

ID
is the window number between 1 and 5. Normally, window 1 will be created in the lower right corner, window 2 in the upper right corner, window 3 in the upper left corner, window 4 in the lower left corner and window 5 in the center of the screen.
Additional notes: C L S W I N

The routine CLSWIN closes a window created with OPNWIN.

The call is:
CALL CLSWIN (ID) - level 1, 2, 3

ID
is the window number between 1 and 5.
S E L W I N

The routine SELWIN selects a window on the screen where the following graphics output will be sent to.

The call is:
CALL SELWIN (ID) - level 1, 2, 3

ID
is the window number between 1 and 5.
W I N I D

The routine WINID returns the ID of the currently selected window.

The call is:
CALL WINID (ID) - level 1, 2, 3

ID
is the returned window number.
W I N T I T

The routine WINTIT changes the window title of the currently selected window.

The call is:
CALL WINTIT (CSTR) - level 1, 2, 3

CSTR
is a character string containing the new window title.

11.11 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

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 index in the range 0 to 255.
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

NX, NY
are the plot coordinates of the centre point.
NB, NH
are the width and height in plot coordinates.
NCOL
is a colour index in the range 0 to 255.
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

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

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
Additional Notes:

11.12 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

Additional note:
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

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

11.13 Example


Next | Previous | Contents