Three-dimensional data

CCATSL provides a large number of routines for plotting three-dimensional data. The simplest is XYZCurveCL which plots a sequence of points $(x_i,y_i,z_i)_{i=1}^n$. It can either plot the points individually, or it can join up the points with straight lines.

Surfaces can be plotted using the routine XYZSurfaceCL, or as a contour plot using the function XYZContourCL. If the function $z(x,y)$ is easy to define in terms of $x$ and $y$, you can use the simpler routine ContourCL, which samples $z$ appropriately. PolarContourCL performs a similar function to XYZContourCL for functions which are more naturally expressed in polar coordinates: the data is now a collection of points $(r,\theta,z(r,\theta))$ where $(r,\theta)$ lie in a (rectangular) lattice. For histograms with two independent variables, CCATSL provides the routine XYZHistogramCL.

For some of these routines, you may find it helpful to use XYZSortCL to re-order the arrays storing the $x$, $y$ and $z$-values so that the $x$ and $y$-values are in increasing order.

XYZCurveCL

This routine plots a sequence of points $(x_i,y_i,z_i)_{i=1}^n$. The points can be plotted individually using a variety of symbols (dots, plus signs, triangles etc.), or they may be joined together with straight lines.

	void XYZCurveCL (	double *xp,
		double *yp,
		double *zp,
		int npts,
		int ncols,
		DrawDataCT option,
		ColourCT colour,
		AxisModeCT axismode);

	xp		Array holding the sequence $x_1,\ldots{,}\,x_n$.
	yp		Array holding the sequence $y_1,\ldots{,}\,y_n$.
	zp		Array holding the sequence $z_1,\ldots{,}\,z_n$.
	npts		The number of points in the sequence.
	ncols		Normally ncols=1. (ncols is the size of the second dimension in the declaration of the arrays xp, yp and zp.)
	option		Specifies how the points should appear. Popular choices are JOIN, to have the points joined up with straight lines or PLUS to have each point marked with a +. You can find the full list of plot symbols here.
	colour		The colour of the graph, such as RedCC for example.
	axismode		Determines whether CCATSL should try to work out scales for the axes automatically. See the example below for the most common usage (AUTOAXES), and here for further information.

/*   /examples/chapter3/ddata3.c   */
#include <catam.h>

int MainCL(void)
{
  double x[50];
  double y[50];
  double z[50];
  int i;
  for (i=0; i<50; i++) {
    x[i]=i;
    y[i]=sin(i/5.0);
    z[i]=cos(i/5.0);
  }
  XYZCurveCL(x,y,z,50,1,PLUS,RedCC,AUTOAXES);
  return 0;
}

XYZSurfaceCL

XYZSurfaceCL produces surface or wireframe plots from a collection of points of the form $(x,y,z(x,y))$, where $(x,y)$ ranges over a rectangular lattice. If your surface is complicated, it may be better to do a contour plot, using XYZContourCL.

	void XYZSurfaceCL (	double *xp,
		double *yp,
		double *zp,
		int nx,
		int ny,
		int ncols,
		int ncolsZ,
		DrawObjectCT option,
		ColourCT upper_col,
		ColourCT lower_col,
		AxisModeCT axismode);

	xp		Array holding the sequence of $x$-values.
	yp		Array holding the sequence of $y$-values.
	zp		Array holding the $z$-values. (This will normally have been declared with the declaration double zp[nx][ny].)
	nx		The number of $x$-values.
	ny		The number of $y$-values.
	ncols		Normally ncols=1. (ncols is the size of the second dimension in the declaration of the arrays xp and yp.)
	ncolsZ		Normally ncolsZ=ny. (ncolsZ is the size of the second dimension in the declaration of the array zp.)
	option		Can be either WIREFRAME for a wireframe plot or SURFACE for a hidden line surface plot.
	upper_col		The colour for the upper side of the surface.
	lower_col		The colour for the lower side of the surface.
	axismode		Determines whether CCATSL should try to work out scales for the axes automatically. See the example below for the most common usage (AUTOAXES), and here for further information.

/*   /examples/chapter3/surface.c   */
#include <catam.h>

int MainCL(void)
{
  double x[50];
  double y[50];
  double z[50][50];
  int i;
  int j;
  for (i=0; i<50; i++) {
    x[i]=i;
    y[i]=i;
    for (j=0; j<50; j++) {
      z[i][j]=sin(i/20.0)*sin(i/20.0)*cos(j/5.0);
    }
  }
  XYZSurfaceCL(x,y,z,50,50,1,50,SURFACE,
               BlueCC,RedCC,AUTOAXES);
  return 0;
}

XYZContourCL

XYZContourCL produces contour plots from a collection of points of the form $(x,y,z(x,y))$, where $(x,y)$ ranges over a rectangular lattice.

	void XYZContourCL (	double *xp,
		double *yp,
		double *zp,
		int nx,
		int ny,
		int ncols,
		int ncolsZ,
		int ncontours,
		double zlow,
		double zhi,
		DrawObjectCT option,
		ColourCT colour,
		AxisModeCT axismode);

	xp		Array holding the sequence of $x$-values.
	yp		Array holding the sequence of $y$-values.
	zp		Array holding the $z$-values. (This will normally have been declared with the declaration double zp[nx][ny].)
	nx		The number of $x$-values.
	ny		The number of $y$-values.
	ncols		Normally ncols=1. (ncols is the size of the second dimension in the declaration of the arrays xp and yp.)
	ncolsZ		Normally ncolsZ=ny. (ncolsZ is the size of the second dimension in the declaration of the array zp.)
	ncontours		Specifies the number of contours to be drawn.
	zlow, zhi		Specify the range [zlow,zhi] of $z$-values which should produce contours. If you set both to zero, XYZContourCL will try to work out a suitable range.
	option		Either CONTOURS2D or CONTOURS3D. The first case leads to a flat `map' with contours, the other leads to three-dimensional contour plot.
	colour		The colour for the contours.
	axismode		Determines whether CCATSL should try to work out scales for the axes automatically. See the example below for the most common usage (AUTOAXES), and here for more information.

/*   /examples/chapter3/contour.c   */
#include <catam.h>

int MainCL(void)
{
  double x[50];
  double y[50];
  double z[50][50];
  int i;
  int j;
  for (i=0; i<50; i++) {
    x[i]=i;
    y[i]=i;
    for (j=0; j<50; j++) {
      z[i][j]=sin(i/10.0)*cos(j/6.0)+i*j/800.0;
    }
  }
  XYZContourCL(x,y,z,50,50,1,50,25,0,0,CONTOURS2D,
               RedCC,AUTOAXES);
  return 0;
}

ContourCL

This routine provides a simpler way than XYZContourCL of producing contour plots of a function $g(x,y)$ when $g$ is easy to evaluate.

	void ContourCL (	double (*g)(double x, double y),
		double xlow,
		double xhi,
		double ylow,
		double yhi,
		double zlow,
		double zhi,
		int ncontours,
		int gtype,
		ColourCT colour,
		AxisModeCT axismode);

	g		A user-defined function taking two double arguments and returning a double. The function should interpret the arguments as $x$ and $y$ respectively and return $g(x,y)$.
	xlow, xhi		The range [xlow, xhi] of $x$-values to plot.
	ylow, yhi		The range [ylow, yhi] of $y$-values to plot.
	zlow, zhi		The range [zlow, zhi] of $z$-values to produce contours.
	ncontours		The number of contours to plot.
	gtype		Specifies the type of contour plot: gtype=0 produces monochrome contour lines of colour colour, gtype=1 produces contour lines of different colours, gtype=2 shades the regions between contour lines, and gtype=3 draws the contour lines in colour and shades the region between contour lines.
	colour		The colour of the contours.
	axismode		Determines whether CCATSL should try to work out scales for the axes automatically. See the example below for the most common usage (AUTOAXES), and here for further information.

/*   /examples/chapter3/fncont.c   */
#include <catam.h>

double f(double x, double y)
{
  return sin(2*M_PI*x)*cos(M_PI*y)+2*x*y;
}

int MainCL(void)
{
  ContourCL(f,-2,2,-2,2,-3,5,50,3,RedCC,AUTOAXES);
  return 0;
}

PolarContourCL

PolarContourCL produces contour plots from a collection of points of the form $(r,\theta,z(r,\theta))$, for $r=r_1,r_2,\ldots{,}\,r_n$, $\theta=\theta_1,\theta_2,\ldots{,}\,\theta_n$, where $(r,\theta)$ are interpreted as polar coordinates.

	void PolarContourCL (	double *rp,
		double *tp,
		double *zp,
		int ncolsZ,
		int nr,
		int ntheta,
		double zlow,
		double zhi,
		int ncontours,
		int gtype,
		ColourCT colour,
		AxisModeCT axismode);

	rp		Array holding the sequence of $r$-values.
	tp		Array holding the sequence of $\theta$-values.
	zp		Array holding the $z$-values. (This will normally have been declared with the declaration double zp[nx][ny].)
	ncolsZ		Normally ncolsZ=ntheta. (ncolsZ is the size of the second dimension in the declaration of the array zp.)
	nr		The number of $r$-values.
	ntheta		The number of $\theta$-values.
	zlow, zhi		The range [zlow, zhi] of $z$-values to produce contours. You can set these both to zero to get CCATSL to work out a sensible range for you.
	ncontours		Specifies the number of contours to draw.
	gtype		Specifies the type of contour plot: gtype=0 produces monochrome contour lines of colour colour, gtype=1 produces contour lines of different colours, gtype=2 shades the regions between contour lines, and gtype=3 draws the contour lines in colour and shades the region between contour lines.
	colour		The colour for the contours.
	axismode		Determines whether CCATSL should try to work out scales for the axes automatically. See the example below for the most common usage (AUTOAXES), and here for further information.

/*   /examples/chapter3/polcont.c   */
#include <catam.h>

int MainCL(void)
{
  double r[50];
  double theta[50];
  double z[50][50];
  int i;
  int j;
  for (i=0; i<50; i++) {
    r[i]=i/50.0;
    for (j=0; j<50; j++) {
      theta[j]=2*M_PI*j/50.0;
      z[i][j]=r[i]*sin(3*theta[j]);
    }
  }
  PolarContourCL(r,theta,z,50,50,50,0,0,15,0,
                 RedCC,AUTOAXES);
  return 0;
}

XYZHistogramCL

This routine produces histograms for datasets with two independent variables. The data must be in the form of two sequences $(x_i)$ and $(y_i)$, and an array $H_{ij}$. The centre of the $ij$th bar will be located at $(x_i,y_i)$, and its height will be $H_{ij}$. The sequence $(x_i)$ should be monotone and equally spaced, as should the sequence $(y_j)$.

	void XYZHistogramCL (	double *xp,
		double *yp,
		double *zp,
		int nx,
		int ny,
		int nz,
		int ncols,
		int ncolsZ,
		double xwidth,
		double ywidth,
		ColourCT colour,
		AxisModeCT axismode);

	xp		Array holding the sequence of $x$-values.
	yp		Array holding the sequence of $y$-values.
	zp		Array holding $H_{ij}$-values. (This will normally have been declared with the declaration double zp[nx][ny].)
	nx		The number of $x$-values.
	ny		The number of $y$-values.
	ncols		Normally ncols=1. (ncols is the size of the second dimension in the declaration of the arrays xp and yp.)
	ncolsZ		Normally ncolsZ=ny. (ncolsZ is the size of the second dimension in the declaration of the array zp.)
	xwidth		The $x$-width of the bars as a proportion of (the common value of) $x_{i+1}-x_i$.
	ywidth		The $y$-width of the bars as a proportion of (the common value of) $y_{i+1}-y_i$.
	colour		The colour for the bars.
	axismode		Determines whether CCATSL should try to work out scales for the axes automatically. See the example below for the most common usage, and here for more information.

/*   /examples/chapter3/histo3d.c   */
#include <catam.h>

int MainCL(void)
{
  double x[10];
  double y[10];
  double z[10][10];
  int i;
  int j;
  for (i=0; i<10; i++) {
    x[i]=i;
    y[i]=i;
    for (j=0; j<10; j++) {
      z[i][j]=exp(-(i+j)/3.0);
    }
  }
  XYZHistogramCL(x,y,z,10,10,1,10,0.8,0.8,
                 YellowCC,AUTOAXES);
  return 0;
}