Contact: zeng  @  zegraph.com      Last update: September 2016

Cairo Library

This library uses Cairo for scientific plot. The coordinate system of a new image is the Screen Coordinate System (SCS) in which the top-left corner corresponds to point (0,0) and the bottom-right conner to (image_width, image_height) respectively. The SCS is replaced by a plot or projection coordinate system (PCS) once the plot function or a projection function is called.

Function Parameter Type Remark
cario(fname) string Loads a PNG image and returns a graph object. Refer to example 1.
cario(w, h[, type]) integer, integer, string Creates and returns a graph object of width w and height h in pixel unit. The optional type parameter may be "pdf", "eps", or "svg" to indicates a vector graph format other than a bitmap image. The type also may be "win" for displaying a plot. Refer to example 1.
.save([fname]) string Saves the graph to a file if the file name fname is given; otherwise returns an array containing a pointer to the graph data and an integer indicating the data size in byte. Refer to example 1.
.show()   Shows the graph in a window. Refer to example 1.
.size()   Returns an array containing graph width and height. Refer to example 1.
.version()   Returns the cairo library version as a string.
Image Manipulation
.clip([z]) number Sets the clipping parameter for the plot area. The optional parameter z specifies the z-plane in a 3D plot. Refer to example 8.
.unclip()   Resets the clipping parameter.
.color(r, g, b) numbers Sets the stroke and fill color. Refer to example 1.
.color(value) number Sets the stroke and fill colors corresponding to the contour value.
.bgcolor(r, g, b]) numbers Sets the background color. Refer to example 1.
.linear(x1, y1, r1, g1, b1, x2, y2, r2, g2, b2[, z]) numbers Creates a linear-fill pattern. The parameters x1 and y1 are the starting position and r1, g1, and b1 are the first color. The parameters x2 and y2 are the end position and r2, g2, and b2 are the second color. The optional parameter z specifies the z-plane in a 3D plot. Refer to example 4.
.radial(cx1, cy1, cr1, r1, g1, b1, cx2, cy2, cr2, r2, g2, b2[, z]) numbers Creates a radial-fill pattern. The parameters cx1 and cy1 are the starting center; cr1 the center radius; and r1, g1, and b1 are the first color. The parameters cx2 and cy2 are the end center; cr2 the center radius, and r2, g2, and b2 are the second color. The optional parameter z specifies the z-plane in a 3D plot. Refer to example 4.
.vertex(x1,cy1, r1, g1, b1, x2, y2, r2, g2, b2, x3, y3, r3, g3, b3[, z]) numbers Creates a mesh fill pattern in the triangle defined by (x1,y1), (x2,y2), and (x3,y3) with gradient colors defined by (r1,g1,b1), (r2,g2,b2), and (r3,g3,b3). The optional parameter z specifies the z-plane in a 3D plot.
.vertex(x1,cy1, r1, g1, b1, x2, y2, r2, g2, b2, x3, y3, r3, g3, b3, x4, y4, r4, g4, b4[, z]) numbers Creates a mesh fill pattern in the rectagle defined by (x1,y1), (x2,y2), (x3,y3), and (x4,y4)with gradient colors defined by (r1,g1,b1), (r2,g2,b2), (r3,g3,b3), and (r4,g4,b4). The optional parameter z specifies the z-plane in a 3D plot.
.font(points) integer Sets the font size for drawing text. Refer to example 2.
.font(file_name) string Sets the font face for drawing text.
.lwidth(w) number Sets the line width. Refer to example 1.
.lstyle(ptr, n) user, integer Sets the line style. The ptr argument must be double pointer to n points, containing positive values for the lengths of "on" and "off". Refer to example 1.
Drawing and painting
.line(x1, y1, x2, y2) numbers Draws a line from (x1,y1) to (x2,y2). Refer to example 1.
.line3D(x1, y1, z1, x2, y2, z2) numbers Draws a line from (x1,y1,z1) to (x2,y2,z2) in a 3D plot.
.line(xptr, yptr, n) user, user, integer Draws a line using data in double pointers xptr and yptr of size n.
.line3D(xptr, yptr, zptr, n) user, user, user, integer Draws a line in a 3D plot.
.curve(x0, y0,x1,y1, x2, y2, x3, y3) numbers Draws a cubic Bézier spline to the path from (x0,y0) to (x3,y3) using (x1, y1) and (x2, y2) as the control points. Refer to example 2.
.curve3D(x0, y0, z0, x1, y1, z1, x2, y2, z2, x3, y3, z3) numbers Draws a cubic Bézier spline to the path from (x0,y0,z0) to (x3,y3,z3) using (x1, y1,z1) and (x2, y2,z2) as the control points.
.polygon(x1, y1, x2, y2, x3, y3,...) numbers Draws a filled polygon for coordinates of (x1,y1), (x2,y2), (x3,y3), and etc. Refer to example 2.
.polygon3D(x1, y1, z1, x2, y2, z2, x3, y3, z3,...) numbers Draws a filled polygon in a 3D plot.
.polygon(xptr, yptr, n) user, user, integer Draws a filled polygon using data in double pointers xptr and yptr of size n.
.polygon3D(xptr, yptr, zptr, n) user, user, user, integer Draws a filled polygon in a 3D plot.
.circle(x, y, r[, fill]) numbers, boolean Draws a circle at (x,y) with radius r in pixel unit. The optional parameter fill sepcecifies whether to fill the shape. Refer to example 2.
.circle3D(x, y, z, r[, fill]) numbers, boolean Draws a circle in a 3D plot.
.arc(x, y, r, a1, a2[, fill]) numbers, boolean

Draws an arc from angle a1 to a2 at (x,y) with radius r in pixel unit. The unit of angle is degree. Refer to example 2.

.arc3D(x, y, z, r, a1, a2[, fill]) numbers, boolean Draws an arc in a 3D plot.
.diamond(x, y, r [, fill]) numbers, boolean Draws an diamond at (x,y) with half diagonal size of r in pixel unit.
.diamond3D(x, y, z, r[, fill]) numbers, boolean Draws an diamond in a 3D plot.
.square(x, y, r [, fill]) numbers, boolean Draws an square at (x,y) with half diagonal size of r in pixel unit.
.square3D(x, y, z, r[, fill]) numbers, boolean Draws an arc in a 3D plot.
.triangle(x, y, r [, fill]) numbers, boolean Draws an triangle at (x,y) with half diagonal size of r in pixel unit.
.triangle3D(x, y, z, r[, fill]) numbers, boolean Draws an triangle in a 3D plot.
.arrow(x, y, u, v[, size]) numbers Draws an arrow at (x,y) pointing to (u,v), like a wind vector. Refer to example 2.
.arrow3D(x, y, z, u, v[, size]) numbers Draws an arrow in a 3D plot.
.symbol(name, x, y) string, number, number Draws a symbol of the name character at (x,y). The name may includes UTF-8 code (refer to the text function for more details). You may change the symbol size by the font function. If the default system font file does not have the character, you can use one of Google's NOTO font, which include all languages.
.symbol(name, xptr, yptr, n) string, user, user, integer Draws symbols at positions given by double pointers xptr and yptr of size n. Refer to example 8.
.symbol3D(name, x, y, z) string, number, number, number Draws a symbol in a 3D plot.
.symbol3D(name, xptr, yptr, zptr, n) string, user, user, user, integer Draws symbols in a 3D plot.
.text(str, x, y[, deg, xalign, yalign, xoff, yoff]) string, number, number, number, integer, integer, number, number Draws a UTF-8 string at (x,y) with an angle of deg degree. xalign=-1, 0, or 1 indicates horizontal alignment of left, center, right respectively; and yalign=-1, 0, ro 1 indicates vertical alignment of bottom, middle, and top respectively. The xoff and yoff specify the offset in pixle from (x,y). You may use \x??\x?? to embed a special character. Refer to example 2.
.text3D(str, x, y, z[, deg, xalign, yalign]) string, number, number, number, number, integer, integer Draws a UTF-8 string in a 3D plot.
Projection
.plot(name, value[,name, value]) string, number or boolean Activates the plot coordinate system and sets plot parameters. Valid pairs of name and value include: ("xscale", number) to set the scale factor of x-axis length to image width, ("yscale", number) to set the scale factor of y-axis length to image width, ("xoffset", integer) to set the offset of the plot area in horizontal direction, ("yoffset", integer) to set the offset of the plot area in vertical direction, ("xmin", number) to set the x-minimum, ("ymin", number) to set the y-minimum, ("xmax", number) to set the x-maximum, ("ymax", number) to set the y-maximum, and ("zrotate", number) or ("xrotate", number) to activate 3D plot transform and rotate the plot about the z-axis or x-axis. Refer to example 3.
.xaxis(name, value[,name, value]) string, various Draws an x-axis (call the plot function first). Valid pairs of name and value include: ("title", string) to draw the x-axis title; ("side", integer) to draw the x-axis at the bottom (negative), in the middle (zero), or on the top (positive); ("start", number) to specify the first x-axis tick; ("end", number) to specify the last x-axis tick; ("step", number) to specify the interval between major ticks; ("minor", integer) to specify the number of minor ticks between major ticks; ("digit", integer) to specify the number of digits for tick labels, ("angle", number) to specify text angle of tick labels; ("labels", array) to draw custom tick labels using strings in the array; and ("between", boolean) to force drawing tick labels between major ticks. Refer to example 3.
.yaxis(name, value[,name, value]) string, various Draws y-axis. Refer to example 3.
.zaxis(name, value[,name, value]) string, various Draws z-axis. Refer to example 3.
.globe(lat, lon) numbers Activates the spherical projection. The input parameters latitude and longitude (in degree unit) specify the focus point on the globe surface. Refer to example 4.
.polar(xmin, xmax[, ymin, ymax]) numbers Activates the polar map projection. Refer to example 4.
.lambert(xmin, xmax[, ymin, ymax]) numbers Activates the Lambert map projection. Refer to example 4.
.hammer(pacific) numbers Activates the Hammer map projection. Refer to example 4.
.frame([fill]) boolean Draws a frame for around the plot area. Sets the optinal fill flag to true to fill and plot area as well. Refer to example 4.
.grid(dx, dy) numbers Draws grid lines. Refer to example 4.
.gshhs(filename[, fill, type]) string Extracts map data from a GSHHS file and draw them as lines or filled polygons. The optional parameters fill, and type are for setting the fill flag and the type of map data, of which 1 indicates land, 2 indicates lake, 3 indicates island in lake, and 4 indicates pond in island in lake. Refer to example 4.
.palette(name, value[,name, value]) string, various Sets a color palette for contour. Valid pairs of name and value include: ("color",array) to add one color to the palette, ("interpolate", integer) to increase the number of palette colors by interpolating the added colors, and ("gradient", boolean) to define whether to treat the palette as gradient or discrete type. An input color array must contain four numbers for color components ( red, green, and blue) and the contour value that the color represents. Refer to example 5.
.colorbar(x, y, w, h[, digit]) integers Draws a color bar for the color palette. x and y are the lower-left corner of the bar in screen coordinate; w and h are the bar width and height in pixel respectively; and digit determines the number of digits for labels. Refer to example 5.
.contour(x0, dx nx, y0, dy, ny, ptr[, iso[, np, digit]]) number, number, integer, number, number, integer, user, numver, integer, integer Draws a contour map; or contour lines if the optional iso contour value is given. The variables np and digit specify the minimal number of connected points for labeling and number of decimal digits in a formated label. The variable ptr must be a double pointer to data on nx*ny grid points with (x0,y0) as the first grid and (x0+nx*dx,y0+dy*ny) as the last. Refer to example 5.
.field(x0, dx nx, y0, dy, ny, uptr, vptr[, size]) number, number, integer, number, number, integer, user, user, number Draws wind vectors. The longitudinal grids are specified by x0, dx, and nx; and the latitudinal grids by y0, dy, and ny. U-wind and V-wind in uptr and vptr, which must be double pointers of size nx*ny, should be scaled properly. The first row of data must be for latitude=y0 and longtitude from x0 to x0+nx*dx. The optional parameter size sets the arrow head size. Refer to example 6.
.image(fname[,x, y]) string, number, number Paint the image in fname on the plot area. The optional parameters x and y may be used to sepcify the position when no plot transform is used. The image must be in PNG. It returns the image weight and height in an array. Refer to example 7.

Example-1


load("cairo.dll");

// load an image and draw on it
g=cairo("data/earth.png");
[w,h]=g.size();
g.color(1,1,1);
g.line(0,0,w,h);
g.save("test.png");

// create an image with alpha channel
g=cairo(w,h);
g.color(0,0,1);
g.line(0,0,w,h);
g.save("test2.png");

// create a pdf
g=cairo(w,h,"pdf");
// paint the background in white
g.bgcolor(1,1,1);
g.color(0,0,1);
// draw a blue line
g.line(0,0,w,h);
g.save("test.pdf");

// create an EPS
g=cairo(w,h,"eps");
g.bgcolor(1,1,1);
g.color(0,0,1);
g.line(0,0,w,h);
g.save("test.eps");

// create a SVG
g=cairo(w,h,"svg");
g.bgcolor(1,1,1);
g.color(0,0,1);
g.line(0,0,w,h);
g.save("test.svg");

// create an image for image for show in a window
g=cairo(w,h,"win");
g.bgcolor(1,1,1);
g.color(0,0,1);
g.line(0,0,w,h);
g.show();

Example-2

load("cairo.dll");

w=600;
h=600;
g=cairo(w,h,"win");

// test text angle and alignment
g.bgcolor(1,1,1);
g.color(0,0,0);
g.line(0,h/2,w,h/2);
g.line(w/2,0,w/2,h);
g.text("Square meter (m\xc2\xb2)",w/2,h/2,30,0,0);
g.show();

// test basic drawings
g.bgcolor(1,1,1);
g.color(0,0,0);
g.polygon(10,50, 50,50, 50,10, 10,10);
g.curve(25.6,128.0, 102.4,230.4, 153.6,25.6, 230.4,128.0);
g.color(1,0,0);
g.circle(w/2,h/2,50,false);
g.color(0,1,0);
g.arc(w/2,h/2,50,0,90);
g.arrow(w/2,h/2,100,100);
g.show();

Example-3

load("cairo.dll");

w=1000;
h=1000;

g=cairo(w,h,"win");
g.bgcolor(1,1,1);
g.color(0,0,0);
g.lwidth(1.5);

xmin=0.0;
xmax=10.0;
ymin=-20.0;
ymax=100.0;
zmin=0.0;
zmax=500.0;
g.plot( "xmin",xmin,"xmax",xmax,"xscale",0.5,
		"ymin",ymin,"ymax",ymax,"yscale",0.5,"yoffset",100,
		"zmin",zmin,"zmax",zmax,"zscale",0.5,"zrotate",30);

g.xaxis("title","X-axis","start",2,"end",xmax,"step",2);
g.yaxis("title","Y-axis","start",ymin,"end",ymax,"step",20);
g.zaxis("title","Z-axis","start",100,"end",zmax,"step",100);

g.line3D(xmin,ymin,zmin,xmax,ymax,zmax);
g.line3D(xmin,ymax,zmin,xmax,ymax,zmin);
g.line3D(xmax,ymax,zmin,xmax,ymax,zmax);

g.line(xmin,ymin,xmax,ymax);

g.show();

Example-4

load("cairo.dll");

w=900;
h=600;
g=cairo(w,h,"win");
g.bgcolor(1,1,1);
g.color(0,0,0);
g.plot("xscale",0.7,"yscale",0.7);
g.plot("xmin",-180,"xmax",180);
g.plot("ymin",-90,"ymax",90);
g.linear(0,-90,0.4,0.5,0.5, 0,90,0.8,1,1);
g.color(0,0,0);
g.frame();
g.grid(30,30);
g.gshhs("data/gshhs_c.b");
g.show();

// test globe projection
g.bgcolor(1,1,1);
g.color(0,0,0);
g.globe(45,80);
g.radial(80,50,5,.8,1,1, 80,50,300,.4,.5,.5);
g.frame(true);
g.color(0,0,0);
g.lwidth(.5);
g.frame();
g.grid(30,30);
g.gshhs("data/gshhs_c.b");
g.show();

// test hammer projection
g.bgcolor(1,1,1);
g.color(0,0,0);
g.hammer(false);
g.frame();
g.grid(30,30);
g.gshhs("data/gshhs_c.b");
g.show();

// test polar projection
g.bgcolor(1,1,1);
g.color(0,0,0);
g.eckert(true);
g.frame();
g.grid(30,30);
g.gshhs("data/gshhs_c.b");
g.show();

// test polar projection
g.bgcolor(1,1,1);
g.color(0,0,0);
g.polar(-180,180);
g.frame();
g.grid(30,30);
g.gshhs("data/gshhs_c.b");
g.show();

// test lambert projection
g.bgcolor(1,1,1);
g.color(0,0,0);
g.lambert(0,360);
g.frame();
g.grid(30,30);
g.gshhs("data/gshhs_c.b");
g.show();

Example-5

load("cairo.dll","netcdf.dll","matrix.dll");

cdf=netcdf("data/2000010100.cdf");

cdf.variable("Lat");
nr=cdf.dims();
Y=double(nr);
Y.import(cdf[*]);
ymin=Y.min();
ymax=Y.max();
dy=abs(Y[1]-Y[0]);

cdf.variable("Lon");
nc=cdf.dims();
X=double(nr);
X.import(cdf[*]);
xmin=X.min();
xmax=xmin+360;
dx=X[1]-X[0];

cdf.variable("T995");
S=short(nr,nc);
S.import(cdf[*]);
D=double(S);
D*=cdf.scale_factor;
D+=cdf.add_offset;

dmin=D.min();
dmax=D.max();
d=0.1*(dmax-dmin);
dmin+=d;
dmax-=d;

w=1000;
h=600;
xscale=0.7;
yscale=0.7;

g=cairo(w,h,"win");
g.bgcolor(1,1,1);
g.color(0,0,0);

g.plot("xscale",xscale,"yscale",yscale);
g.plot("xmin",xmin,"xmax",xmax);
g.plot("ymin",ymin,"ymax",ymax);
g.xaxis("title","Longitude","start",xmin,"end",xmax,"step",30,"digit",0);
g.yaxis("title","Latitude","start",ymin,"end",ymax,"step",30,"digit",0);

g.palette(
	"color",[0,0,1,dmin],
	"color",[0,1,0,0.5*(dmin+dmax)],
	"color",[1,0,0,dmax],
	"interpolate",2,
	"gradient",true);
	
g.colorbar(w-w*(1-xscale)/2+20,h-h*(1-yscale)/2,10,h*yscale);

[ptr,n]=D.ptr();
g.contour(xmin,dx,nc,ymin,dy,nr,ptr);
g.lwidth(3);
g.contour(xmin,dx,nc,ymin,dy,nr,ptr,0.5*(dmin+dmax));

g.lwidth(1);
g.gshhs("data/gshhs_c.b");
g.grid(30,30);
g.frame();
g.show();

Example-6

load("cairo.dll","netcdf.dll","matrix.dll");

cdf=netcdf("data/2000010100.cdf");

cdf.variable("Lat");
nr=cdf.dims();
Y=double(nr);
Y.import(cdf[*]);
ymin=Y.min();
ymax=Y.max();
dy=abs(Y[1]-Y[0]);

cdf.variable("Lon");
nc=cdf.dims();
X=double(nr);
X.import(cdf[*]);
xmin=X.min();
xmax=xmin+360;
dx=X[1]-X[0];

cdf.variable("U995");
S=short(nr,nc);
S.import(cdf[*]);
U=double(S);
U*=cdf.scale_factor;
U+=cdf.add_offset;

cdf.variable("V995");
S.import(cdf[*]);
V=double(S);
V*=cdf.scale_factor;
V+=cdf.add_offset;

D=sqrt(U*U+V*V);

dmin=D.min();
dmax=D.max();
d=0.1*(dmax-dmin);
dmin+=d;
dmax-=d;

w=1000;
h=600;
xscale=0.7;
yscale=0.7;

g=cairo(w,h,"win");
g.bgcolor(1,1,1);
g.color(0,0,0);

g.plot("xscale",xscale,"yscale",yscale);
g.plot("xmin",xmin,"xmax",xmax);
g.plot("ymin",ymin,"ymax",ymax);
g.xaxis("title","Longitude","start",xmin,"end",xmax,"step",30,"digit",0);
g.yaxis("title","Latitude","start",ymin,"end",ymax,"step",30,"digit",0);

g.palette(
	"color",[0,0,1,dmin],
	"color",[0,1,0,0.5*(dmin+dmax)],
	"color",[1,0,0,dmax],
	"interpolate",2,
	"gradient",true);
	
g.colorbar(w-w*(1-xscale)/2+20,h-h*(1-yscale)/2,10,h*yscale);

[uptr,n]=U.ptr();
[vptr,n]=V.ptr();
g.field(xmin,dx,nc,ymin,dy,nr,uptr,vptr,5);

g.lwidth(1);
g.gshhs("data/gshhs_c.b");
g.grid(30,30);
g.frame();
g.show();

Example-7

load("cairo.dll");

w=800;
h=600;
xscale=0.7;
yscale=0.7;

g=cairo(w,h,"win");
g.bgcolor(1,1,1);
g.color(0,0,0);

xmin=0.0;
xmax=360.0;
ymin=-90.0;
ymax=90.0;
zmin=-1.0;
zmax=1.0;

g.plot("xscale",xscale,"yscale",yscale);
g.plot("xmin",xmin,"xmax",xmax);
g.plot("ymin",ymin,"ymax",ymax);
g.plot("zmin",zmin,"zmax",zmax,"zrotate",30);
g.xaxis("title","Longitude","start",xmin,"end",xmax,"step",30,"digit",0);
g.yaxis("title","Latitude","start",ymin,"end",ymax,"step",30,"digit",0);

g.image("data/earth.png");

g.grid(30,30);
g.frame();
g.show();

Example-8

load("cairo.dll","matrix.dll");

w=800;
h=600;
xscale=0.7;
yscale=0.7;

g=cairo(w,h,"win");
g.bgcolor(1,1,1);
g.color(0,0,0);

xmin=0.0;
xmax=10.0;
ymin=0.0;
ymax=5.0;

X=double(1,2,3,4,5,6,7,8,9);
[xptr,n]=X.ptr();
Y=double(1,2,3,4,4.5,4,3,2,1);
[yptr,n]=Y.ptr();

g.plot("xscale",xscale,"yscale",yscale,
	   "xmin",xmin,"xmax",xmax,
       "ymin",ymin,"ymax",ymax);

g.xaxis("title","X","start",xmin,"end",xmax);
g.yaxis("title","Y","start",ymin,"end",ymax);

g.symbol("o",xptr,yptr,n);
g.show();

g.clip(true);

g.color(0,0,0);
g.symbol("+",xptr,yptr,n);
g.show();

g.bgcolor(1,1,1);
g.color(0,0,0);
g.symbol("x",xptr,yptr,n);
g.show();