Contact: zeng  @  zegraph.com      Last update: 10 May 2011

GraphicsMagick Library

This library uses GraphicsMagick for 2D plot. The coordinate system of a new image is the Screen Coordinate System (SCS) in which the upper-left corner corresponds to point (0,0) and the bottom-right conner to (w,h) where w and h are image width and height respectively. In the SCS the x-axis points from left to right and the y-axis from top to bottom. The SCS is replaced by a plot coordinate system (PCS) once the plot function is called. In the PCS, the y-axis from bottom to top. Drawing and filling use PCS when it becomes available and use SCS otherwise. Similarly a Globel Coordinate System (GCS) or a Map Coordinate System (MCS) replaces any others once the globe or map function is called respectively.

Function Parameter Type Remark
gmagic(filename) string Loads image from a file and returns an image object. The file name extension determines the image type. Refer to GraphicsMagick for supported formats and example 1 .
gmagic(w, h) integer, integer Creates and returns an image object of width w and height h. Refer to example 1 .
.p2s(x, y) number, number Returns the screen coordinates for the specified plot coordinates.
.version()   Returns the version numbers as string. Refer to example 1.
.size()   Returns an array containing image width and height. Refer to example 1.
.save(filename) string Saves image to a file. The file name extension determines the image type. Refer to example 1 .
.show([title]) string Creates a window and display the image in it. Refer to example 1 .
Image Manipulation
.crop(x, y, w, h) integers Crops the image starting at (x,y) with width w and height h and returns an image object. It always uses screen coordinates. Refer to example 1 .
.flip()   Flips the image vertically (column). Refer to example 1 .
.flop()   Flops the image horizontally (scanline). Refer to example 1 .
.merge(img, x, y[, op]) user, integer, integer, string Merges img into the caller staring at (x,y) according to the operation op, which may be "over", "in", "atop", "xor", "plus", "minus", "add", "subtract". "difference", "multiply", "bump", "copy", "red", "green", "blue", "opacity", or "clear". Refer to example 1 .
.ptr(type) string Returns an array containing a pointer to encoded image and its size in byte. The image type may be any supported types by GraphicsMagick.
.resize(w, h) user Resizes image to with w and height h. Refer to example 1 .
.roll(ncol, nrow) integer, integer Rolls the umage for given number of rows and colums. Refer to example 1 .
.rotate(degree) number Rotates the image for the specified degrees. Refer to example 1 .
.get(r, g, b, n) user, user, user, integer Extracts image colors. The parameters r, g, b are double pointers and their size n must equal the total number of image pixels. Color values range from 0 to 1. Refer to example 1.
.set(r, g, b, n) user, user, user, integer Sets image colors. The parameters r, g, b are double pointers and their size n must equal the total number of image pixels. Color values range from 0 to 1. Refer to example 1.
Set attibute
.clip(flag) boolean Sets the clipping of plot: points outside the plot area will not be drawn if flag=true.
.color(r, g, b) numbers It is the same as calling strokecolor and fillcolor. Refer to example 2 .
.color(value) number Gets the color for the contour value and set it as the stroke and fill color.
.strokcolor(r, g, b) numbers Sets color for drawing. Refer to example 2 .
.fillcolor(r, g, b) numbers Sets color for filling. Refer to example 2 .
.pattern(img) user Sets the image img for filling.
.dash(d) user Sets dash line style. d must be a double pointer with the last element being zero. Refer to example 2 .
.linewidth(w) number Sets line width. Refer to example 2.
.font(fname[, points]) string, integer Sets font for drawing text. fname must be a valid truetype file name. Refer to example 2 .
.font(points) integer Sets font size for drawing text. Refer to example 2 .
.antialias(flag) boolean Sets the antialias flag for drawing line. Refer to example 2 .
.missing(v) number Sets the missing value to bypass drawing data (large negative numbers) in double pointers.
.transparent(r, g, b) inumbers Sets the color to be transparent for merging images. Refer to example 1.
.opacity(percentage) inumber Sets the opacity (0 to 100) for merging images. Refer to example 1 .
Drawing and filling
.angle(x1, y1, x2, y2) numbers Returns the angle of the vector (x1,y1)->(x2,y2).
.erase(r, g, b) numbers Erases the whole image with the color. Refer to example 3 .
.besier(x1, y1, x2, y2,...) numbers Draws a besier line.
.besier(xptr, yptr, n) user, user, integer Draws a besier line using data in xptr and yptr, which must be double pointers of size n..
.line(x1, y1, x2, y2) numbers Draws a line from (x1,y1) to (x2,y2). Refer to example 2.
.line(xptr, yptr, n) user, user, integer Draws a line using data in double pointers xptr and yptr of size n. Refer to example 4.
.point(x, y) numbers Draws a point at (x,y) Refer to example 2 .
.point(xptr, yptr, n) user, user, integer Draws points using data in double pointers xptr and yptr of size n. Refer to example 4.
.polygon(xptr, yptr, n) user, user, integer Draws filled polygon using data in double pointers xptr and yptr of size n. Refer to example 4.
.polygon(x, y, x, y, x, y[, x, y...]) numbers Draws filled polygon. Refer to example 2.
.text(str, x, y[, deg, xalign, yalign]) string, number, number, number, integer, integer Draws text string at (x,y) with an angle of deg degree. xalign=-1, 0, 1 specifies horizontal alignment of left, center, right respectively; and yalign=-1, 0, 1 specifies vertical alignment of bottom, middle, and top respectively. A subscript string can be enclosed in <sub> and </sub> tags; and a supperscript string in <sup> and </sup> tags. Character symbols may be embedded in string with their unicode in hexadecimal number (e.g., 0x01C1). The following symbol names may also be used between <sym> and </sym>: alpha, beta, gamma, delta, epsilon, zeta, eta, theta, iota, kappa, lambda, mu, nu, xi, pi, rho, sigma, tau, upsilon, phi, chi, psi, omega, Gamma, Delta, Theta, Lambda, Xi, Pi, Sigma, Phi, Psi, and Omega. Refer to example 2.
.circle(x, y, r) numbers Draws a circle at (x,y) with radius r in pixel unit. Refer to example 2.
.ellipse(x, y, rx, ry) numbers Draws an ellipse at (x,y) with x-radius rx and y-radius ry in pixel unit. Refer to example 2.
.rectangle(x1, y1, x2, y2) numbers Draws a rectangle with the upper-left corner at (x1,y1) and its cross corner at (x2,y2). Refer to example 2.
.pie(x, y, w, h, s, e) numbers Fills a pie starting at (x,y) with width w and height h. The start and end angles in degree are given by s and e. Refer to example 2 .
.symbol(name, xptr, yptr, n, size) string, user, user, integer, integer, integer Draws symbols of size pixels at positions given by double pointers xptr and yptr of size n. The name may be "O" for circle, "OF" for filled circle, "X" for x, "+" for cross, "*" for star, "S" for square, "SF" for filled square, "T" for triangle, "TF" for filled triangle, "D" for diamond, and "DF" for filled diamond. Refer to example 2 .
.plot(name, value[,name, value]) string, number or boolean Activates PCS 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 plot area in horizontal direction, ("yoffset", integer) to set the offset of 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 ("frame", boolean) to draw a frame around the plotting area. Refer to example 2 .
.xaxis(name, value[,name, value]) string, various Draws 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 tick labels. Refer to example 2 .
yaxis(name, value[,name, value]) string, various Draws y-axis. Refer to explanations for xaxis function for valid pairs of name and value.
globe(lat, lon) numbers Activates the GCS (call the plot function first). The input parameters specify the focus point on the globe surface. Refer to example 3 .
map(pacific) boolean Activates the MCS (call the plot function first). The pacific flag whether to put the Pacific in the map center. Refer to example 3 .
map(xmin, xmax, ymin, ymax) numbers Activates the MCS (call the plot function first). The four parameters determine the area of the map-fan. Refer to example 3 .
maxis(step[, thick]) numbers Draws map axis lines (call the map function first). Use the optional thick parameter to set axis line thickness. Refer to example 3 .
grid(dx, dy) numbers Draws grid lines. Refer to example 3 .
.palette(name, value[,name, value]) string, various Sets 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 tread the palette as gradient or discrete type. An input color array must contain four numbers for color components ( red, green, and blue) and the value that the color represents. Refer to example 5 .
.colorbar(x, y, w, h[, digit]) integers Draws color bar for 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(zptr, nr, nc) user, integer, integer Draws a contour map for data in zptr of double pointer of nr rows by nc columns.
.contour(xptr, nx, yptr, ny, zptr) user, integer, user, integer, user Draws a contour map. xptr, ypr, and zptr must be double pointers, with xptr having x-grid data of nx points, yptr having y-grid data of ny points, and zptr having data of nx*ny points on grids from yptr[0] to yptr[ny-1] and xptr[0] to xptr[nx-1]. Refer to example 5.
.contour(xptr, nx, yptr, ny, zptr, iso) user, integer, user, integer, user, number Draws contour lines for the iso value. xptr, ypr, and zptr must be double pointers, with xptr having x-grid data of nx points, yptr having y-grid data of ny points, and zptr having data of nx*ny points on grids from yptr[0] to yptr[ny-1] and xptr[0] to xptr[nx-1]. Refer to example 5.
.contour(xptr, yptr, zptr, n) user, user, user, integer Draws a contour mam for irregular grid data in xptr, ypr, and zptr of double pointers of size n.
.field(xptr, nx, yptr, ny, uptr, vptr, size) user, integer, user, integer, user, user, number Draws vectors with the given arror head size. xptr and ypr must be double pointers, with xptr having x-grid data of nx points and yptr having y-grid data of ny points, uptr and vptr must be double pointers of size nx*ny containing u and v wind data on grids from yptr[0] to yptr[ny-1] and xptr[0] to xptr[nx-1]. Refer to example 6.
.gshhs(filename) string Extracts coastlines from a GSHHS file and draw them as lines. Refer to example 3 .

Example-1

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

gm=gmagic("data/earth.png");
gm.show();

csv(gm.version());

g2=gm.crop(10,10,200,100);
g2.show();

g2=gmagic(200,100);
g2.opacity(70);
gm.merge(g2,100,50,"over");
gm.show();

g2.transparent(1,1,1);
gm.merge(g2,200,50,"over");
gm.show();

gm.flip();
gm.show();

gm.flop();
gm.show();

gm.rotate(30);
gm.show();

[w,h]=gm.size();
csv(w,h);

gm.roll(w/2,0);
gm.show();

gm.resize(w/2,h/2);
gm.show();

[w,h]=gm.size();

R=double(h,w);
[r,n]=R.ptr();
G=double(h,w);
[g,n]=G.ptr();
B=double(h,w);
[b,n]=B.ptr();

gm.get(r,g,b,n);
R.fill(0,0);
gm.set(r,g,b,n);
gm.show();

gm.save("test.tif");

Example-2

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

gm=gmagic(900,600);
gm.font(15);
gm.plot("xscale",0.7, "yscale",0.7,
        "xmin", 0, "xmax", 360,
        "ymin", -90, "ymax", 90,
        "xoffset", 20, "yoffset", 10);

gm.xaxis("title", "Longitude", "start", 0, "end", 360, "step", 30, "minor", 3, "digit", 0, "side",1);   
gm.yaxis("title", "Latitude", "start", -90, "end", 90, "step", 30, "minor", 3, "digit", 0, "side",1);

//gm.show();
//return;

gm.color(0,0,1);
gm.linewidth(2);
gm.line(0,-90,180,0);

D=double(5,2,0);
[ptr,n]=D.ptr();
gm.dash(ptr);
gm.line(180,0,360,-90);
gm.dash(false);

gm.antialias(false);
gm.linewidth(5);
gm.point(180,-60);

gm.linewidth(1);
gm.fillcolor(0,1,0);
gm.polygon(180,0,210,0,195,30);

gm.text("ABC<sub>2</sub>", 30, 0);
gm.font("SIMSUN.TTF",24);
s="日本語";
gm.text(s, 60, 0);

gm.circle(30,-30,10);

gm.ellipse(30,30,30,10);

gm.rectangle(30,30,90,60);

gm.pie(120,30,60,40,0,30);

g2=gmagic("data/earth.png");
gm.pattern(g2);
gm.polygon(180,30,210,30,195,60);

gm.show();

Example-3

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

gm=gmagic(900,600);

gm.plot("xscale",0.8, "yscale",0.8);

gm.globe(30,30);
        
gm.grid(30,30);

gm.gshhs("data/gshhs_c.b");

gm.show();

gm.erase(1,1,1);

gm.map(1);

gm.linewidth(1);

gm.grid(30,30);

gm.gshhs("data/gshhs_c.b");

gm.maxis(15);

gm.show();

gm.erase(1,1,1);

gm.map(100,160,10,60);

gm.linewidth(1);

gm.color(0,0,0);

gm.grid(10,10);

gm.gshhs("data/gshhs_c.b");

gm.maxis(10);

gm.show();

Example-4

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

gm=gmagic(600,600);

gm.plot("xscale",0.7, "yscale",0.7,
        "xmin", 0, "xmax", 10,
        "ymin", 0, "ymax", 20);

gm.xaxis("title", "X", "start", 0, "end", 10, "step", 2, "digit", 0);   
gm.yaxis("title", "Y", "start", 0, "end", 20, "step", 5, "digit", 0);        

X=double(10);
X.fill(0,1);
[Xptr, nx] = X.ptr();

Y=double(10);
Y.fill(0,1.e5);
[Yptr,ny]=Y.ptr();

V=double(10);
V.fill(0,1.e5);
[Vptr,nv]=V.ptr();

gm.missing(1.e5);

gm.fillcolor(0,1,0);

for (i=0; i<nx; i++) {
    Y[i]=2*X[i];
    V[i]=X[i];
    gm.strokecolor(0,0,1);
    gm.line(Xptr,Yptr,nx);
    gm.strokecolor(1,0,0);
    gm.point(Xptr,Vptr,nx);
    gm.symbol("d",Xptr,Yptr,nx,6);
}

gm.show();

Example-5

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

gm=gmagic(900,600);

gm.plot("xscale",0.7, "yscale",0.7,
        "xmin", 0, "xmax", 360,
        "ymin", -90, "ymax", 90,
        "xoffset", 20, "yoffset", 10,
        "frame", true);

gm.xaxis("title", "Longitude", "start", 0, "end", 360, "step", 30, "minor", 3, "digit", 0);   
gm.yaxis("title", "Latitude", "start", -90, "end", 90, "step", 30, "minor", 3, "digit", 0);        


gm.palette("color",[1,0,0,220],
           "color",[0,1,0,260],
           "color",[0,0,1,310],
           "interpolate",2,
           "gradient",true);
        
gm.colorbar(10+900*0.3/2, 600*.3/2-50, 900*0.7, 10, 1);

X=double(144);
X.fill(0,2.5);
[Xptr, nx] = X.ptr();

// y-axis data
Y=double(73);
Y.fill(-90,2.5);
[Yptr,ny]=Y.ptr();

// air temperature data
cdf=netcdf("c:/temp/ncep1/air.sig995.2006.nc");
cdf.variable("air");
S=short(73,144);
S.import(cdf[0,*,*]);
D=double(S);
D*=cdf.scale_factor;
D+=cdf.add_offset;
D.flip("r");
[Dptr,nd]=D.ptr(); 

dmin=D.min();
dmax=D.max();
dstp=(dmax-dmin)/10;

gm.contour(Xptr, nx, Yptr, ny, Dptr);

gm.color(1,1,1);

// draw contour lines
for (d=dmin+dstp; d<dmax; d+=dstp) {
	gm.contour(Xptr, nx, Yptr, ny, Dptr, d);
}
         
gm.show();

Example-6

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

gm=gmagic(900,600);

gm.plot("xscale",0.7, "yscale",0.7,
        "xmin", 0, "xmax", 360,
        "ymin", -90, "ymax", 90,
        "xoffset", 20, "yoffset", 10,
        "frame", true);

gm.xaxis("title", "Longitude", "start", 0, "end", 360, "step", 30, "minor", 3, "digit", 0);   
gm.yaxis("title", "Latitude", "start", -90, "end", 90, "step", 30, "minor", 3, "digit", 0);        


gm.palette("color",[1,0,0,0],
           "color",[0,1,0,20],
           "color",[0,0,1,40],
           "interpolate",2,
           "gradient",true);
        
gm.colorbar(10+900*0.15, 600*.15-50, 900*0.7, 10, 1);

X=double(144);
X.fill(0,2.5);
[Xptr, nx] = X.ptr();

// y-axis data
Y=double(73);
Y.fill(-90,2.5);
[Yptr,ny]=Y.ptr();

// wind data
S=short(73,144);

cdf=netcdf("data/2000010100.cdf");
cdf.variable("U995");
S.import(cdf[*]);
U=double(S);
U*= cdf.scale_factor;
U+= cdf.add_offset;
U.flip("r");
[Uptr,nd]=U.ptr(); 

cdf.variable("V995");
S.import(cdf[*]);
V=double(S);
V*=cdf.scale_factor;
V+=cdf.add_offset;
V.flip("r");
[Vptr,nd]=V.ptr(); 

// draw wind vectors
gm.field(Xptr,nx,Yptr,ny,Uptr,Vptr,2);
         
gm.show();