Contact: zegraph @ yahoo.com Last update: June 2020
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,[ alpha]) | 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; ("tick", number) to scale up or down the tick length; ("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(ymin, ymax, xmin, xmax) | numbers | Activates the polar map projection. Refer to example 4. |
| .lambert(ymin, ymax, xmin, xmax]) | 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(xptr, nx, yptr, ny, zptr[, iso[, np, digit]]) | user, integer, user, integer, user, number, integer, integer | Draws a contour map; or contour lines if the optional iso contour value is given. The xptr and nx sepcify the x-grid data and number of points; yptr and ny specify the y-grid data and number of points; and zptr must contain nx*ny data. The variables np and digit specify the minimal number of connected points for labeling and number of decimal digits in a formated label. |
| .contour(xptr, yptr, zptr, np, dx, dy) | user, user, user, integer, number, number | Draws a contour map. The xptr, yptr, and zptr variables are double-byte pointers to x and y coordinates and the z-values, respectively; and np is the number of data points. The dx and dy variables specify the grid sizes. |
| .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. |
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();
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();
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();
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 eckert 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(0,90,-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,90,0,360);
g.frame();
g.grid(30,30);
g.gshhs("data/gshhs_c.b");
g.show();
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();
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();
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();
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();