Contact: zegraph @ yahoo.com Last update: June 2020
This library uses GD 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. That is that in SCS the x-axis points from left to right and the y-axis from top to bottom. The plot coordinate system (PCS) is available once the plot function is called. In PCS, the x-axis points from left to right and the y-axis from bottom to top. Drawing and filling functions use PCS when it becomes available and use SCS otherwise.
| Function | Parameter Type | Remark |
| gd(filename) | string | Loads image from a file and returns the object. Image type is determined by file name extension, i,e., ".gif", ".png", ".jpg", ".tif", ".bmp", "xbm", or "xpm". Refer to example 1. |
| gd(w, h[, flag]) | integer, integer, boolean | Creates an image of width w and height h and returns the object. The optional flag may be set to false to create palette image, e.g., for GIF animation. Refer to example 3. |
| .version() | Returns the version numbers. 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. Refer to example 2. |
| .show([title]) | string | Creates a window and display the image in it. The option title parameter lets you show with your own title. Refer to example 2. |
Image Manipulation |
||
| .copy(x, y, w, h) | integers | Copies 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 2. |
| .merge(img, x, y[, p]) | user, integer, integer, integer | Merges img into the caller staring at (x,y). The optional parameter p (default to100) determines the percentage of img in merging. It always uses screen coordinates. Refer to example 2. |
| .resize(w, h) | user | Resizes image to with w and height h. Refer to example 2. |
| .ptr(type) | string | Returns an array containing a pointer to encoded image and its size in byte. The image type may be "gif", "png", or "jpg". Refer to example 2. |
| .get(r, g, b, n) | user, user, user, integer | Extracts image colors. The parameters r, g, b are unsigned char pointers and their size n must equal the total number of image pixels. Color values range from 0 to 255. Refer to example 2. |
| .set(r, g, b, n) | user, user, user, integer | Sets image colors. The parameters r, g, b are unsigned byte pointers and their size n must equal the total number of image pixels. Color values range from 0 to 255. Refer to example 2. |
Drawing and filling |
||
| .color(r, g, b) | integers | Sets color for drawing and filling. Refer to example 3. |
| .color(v) | number | Sets color for drawing and filling. The color is determined by the contour value v and the paletter. |
| .brush(img) | user | Sets the image img as brush for drawing line. Refer to example 3. |
| .tile(img) | user | Sets the image img as tile for filling polygon. Refer to example 3. |
| .style(s) | string | Sets line style. s must contain only character 1 for coloring or 0 for transparency. Refer to example 3. |
| .width(w) | integer | Sets line width. Refer to example 3. |
| .clip(x, y, w, h) | integers | Sets slipping area for restricting drawing. It always uses screen coordinates. |
| .fill(x, y) | numbers | Floods a portion of the image beginning at (x,y), which are screen coordinates if plot has not been set and plot coordinates otherwise. Refer to example 3. |
| .erase(red, green, blue) | integers | Erases the whole image with the color. Refer to example 3. |
| .line(x1, y1, x2, y2) | integers | Draws a line from (x1,y1) to (x2,y2). It uses screen coordinates if plot has not been set and plot coordinates otherwise. Refer to example 3. |
| .line(x, y, n) | user, user, integer | Draws a line using data in double floating pointers x and y of size n. It uses screen coordinates if plot has not been set and plot coordinates otherwise. A number larger than 1.e15 in x or y indicates missing value and that point will not be drawn. Refer to example 4. |
| .polygon(x, y, n) | user, user, integer | Fills a polygon using data in double floating pointers x and y of size n. It uses screen coordinates if plot has not been set and plot coordinates otherwise. Refer to example 4. |
| .font(filename, point) | string, number | Sets font for drawing text. The parameter filename must be the full path to a truetype font file and point specifies the font size. The default font is arial and font size is 12pt. |
| .font(point) | number | Sets font size for drawing text. |
| .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. It uses screen coordinates if plot has not been set and plot coordinates otherwise. Note that when str contain newline characters, it will be drawn as multiple a line string and xalign and yalign should should be set to -1. Refer to example 3. |
| .arc(x, y, w, h, s, e) | integer, integer, integer, integer, integer, integer, integer | Draws an arc starting at (x,y) with width w and height h. The start and end angles in degree are given by s and e. It uses screen coordinates if plot has not been set and plot coordinates otherwise. Refer to example 3. |
| .pie(x, y, w, h, s, e) | integer, integer, integer, integer, integer, integer, integer | 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. It uses screen coordinates if plot has not been set and plot coordinates otherwise. Refer to example 3. |
| .ellipse(x, y, w, h) | integer, integer, integer, integer, integer | Fills an ellipse starting at (x,y) with width w and height h. It uses screen coordinates if plot has not been set and plot coordinates otherwise. Refer to example 3. |
| .rectangle(x1, y1, x2, y2) | integer, integer, integer, integer, integer | Fills a rectangle with the upper-left corner at (x1,y1) and its cross corner at (x2,y2). It uses screen coordinates if plot has not been set and plot coordinates otherwise. Refer to example 3. |
| .symbol(name, x, y, n, size) | string, user, user, integer, integer, integer | Draws symbols of size pixels at positions given by double floating pointer x and y 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. It uses screen coordinates if plot has not been set and plot coordinates otherwise. Refer to example 4. |
| .palette(name, value[,name, value]) | string, integer or number or array | Sets color palette for contour. Valid pairs of name and value include: ("clear", boolean) to clear or reserve existing colors, ("min", number) to set the minimal contour value, ("max", number) to set the maximal contour value, ("color",array) to add one color to the palette, ("interpolate", integer) to increase the number of palette colors by interpolating the first two colors, ("gradient", boolean) to define whether to tread the palette as gradient or discrete type in finding color for a contour value. A color array must contain three integers between 0 to 255 for color components of red, green, and blue. Note that if the function is not called, the default gradient palette has three colors: red, green, and blue for contour values of 0 to 1. Refer to example 5. |
| .colorbar(x, y, w, h, digit) | integers | Draws color bar for color palette. It uses screen coordinates. x and y define the upper-left corner of the bar; w and h define the bar width and height; and digit determines the number of digits for labels. Refer to example 5. |
| .contour(xptr, nx, yptr, ny, zptr, iso) | string, user, integer, user, integer, user, number | Draws contour lines for the iso value. xptr, ypr, and zptr must be double floating 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, kptr, n, iso) | string, user, user, user, user, integer, number | Draws contour lines for the iso value. xptr, yptr, and zptr must be double floating pointers having data on triangle grids given by kptr, which must be a integer (int) pointer of size n containing indices of x in xptr, y in yptr, and z in zptr. |
| .field(xptr, nx, yptr, ny, uptr, vptr, size) | string, user, integer, user, integer, user, user, number | Draws vectors with arror head size of size. xptr and ypr must be double floating pointers, with xptr having x-grid data of nx points and yptr having y-grid data of ny points, uptr and vptr must be pointers of double floating number with size of 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. |
| .field(xptr, yptr, uptr, vptr, n, size) | string, user, user, user, user, integer, number | Draws vectors with arrow head size of size. xptr, yptr, uptr, and vptr must be double floating pointers of size n containing data of positions and u-v winds. |
| .gshhs(file[, west, east, south, noth]) | string, numbers | Extracts coastlines from a GSHHS file and draw them as lines. The optional parameters specify the region boundary, which is -180, 180, -90, 90 degree by default. |
| .plot(name, value[,name, value]) | string, integer or number or string | Sets plot parameters and activates plot transformation. 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, and ("ymax", number) to set the y-maximum. Refer to example 4. |
| .xaxis(name, value[,name, value]) | string, integer or number or string or array | Draws x-axis. Valid pairs of name and value include: ("title", string) to draw the x-axis title; ("side", integer) to draw the x-axis on the left (negative); in the center (zero), or on the right (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; ("frame", boolean) to draw x-axis frame; ("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 4. |
| .yaxis(name, value[,name, value]) | string, integer or number or string or array | Draws y-axis. Refer to explanations for xaxis function for valid pairs of name and value. |
| .pl2scr(x, y) | numbers | Converts plot coordinates to screen coordinates and return an array with converted x and y. Refer to example 4. |
GIF animation |
||
| .begin(filename) | string | Begins GIF animation. Refer to example 7. |
| .add(filename[, s]) | string, integer | Adds a GIF animation frame. The optional s specifies the delay between frames in the unit of 1/100 second. Refer to example 7. |
| .end(filename) | string | Ends GIF animation. Refer to example 7. |
// load library
load("gd.dll");
// load image from file
gd = gd("data/earth.png");
// print version info
csv(gd.version());
// save to file
gd.save("test.jpg");
load("gd.dll", "matrix.dll");
gd = gd("data/earth.png");
// show image
gd.show();
// copy part of the image
gd2 = gd.copy(0, 0, 200, 100);
gd2.show();
// merge gd2 to gd1 half transparently
gd.merge(gd2, 100, 100, 50);
gd.show();
// get pointer to ompressed gif image for web output
[ptr, n] = gd.ptr("gif");
csv(ptr, n);
// get image size
[w, h] = gd.size();
// create matrix for extracting image color
R = uchar(h, w);
[Rptr, n] = R.ptr();
G = uchar(h, w);
[Gptr, n] = G.ptr();
B = uchar(h, w);
[Bptr, n] = B.ptr();
// get image color
gd.get(Rptr, Gptr, Bptr, n);
// remve red component
R[*] = 0;
// set color back
gd.set(Rptr, Gptr, Bptr, n);
gd.show();
// resize image
gd2 = gd.resize(200, 100);
gd2.show();
load("gd.dll", "matrix.dll");
// this example use screen coordinates
// create image
gd = gd(500, 400);
// set drawing/filling color
gd.color(0, 0, 255);
// flood fill to have blue background
gd.fill(0,0);
gd.show();
// use image to fill
gd2 = gd("data/tile.png");
gd.tile(gd2);
gd.fill(0,0);
gd.show();
// draw a thick line
gd.erase(0, 0, 255);
gd.color(255, 255, 255);
gd.width(10);
gd.line(0,0,200, 200);
gd.show();
// draw with style
gd.erase(0, 0, 255);
gd.style("1111100000");
gd.line(0,0,200, 300);
gd.show();
// use image as brush to draw line
gd.erase(0, 0, 255);
gd.brush(gd2);
gd.line(0,0,200, 200);
gd.show();
// draw text
gd.erase(0, 0, 255);
gd.color(255, 0, 0);
gd.text("ABCabc", 100, 100, 45, 0, 0);
gd.show();
// draw arc
gd.erase(0, 0, 255);
gd.width(2);
gd.arc(200, 200, 100, 50, 0, 180);
gd.show();
// draw pie
gd.erase(0, 0, 255);
gd.color(0, 255, 0);
gd.pie(300, 200, 100, 100, 0, 60);
gd.show();
// draw ellipse
gd.erase(0, 0, 255);
gd.ellipse(100, 200, 100, 50);
gd.show();
// draw rectangle
gd.erase(0, 0, 255);
gd.rectangle(100, 200, 200, 250);
gd.show();
load("gd.dll", "matrix.dll");
// this example use plot coordinates
// create image
gd = gd(500, 400);
// set drawing/filling color
gd.color(0, 0, 0);
// set plot transformation
gd.plot("xmin", 1, "xmax", 12,
"ymin", 0, "ymax", 1.5,
"xscale", 0.7, "yscale", 0.7,
"xoffset", 10, "yoffset", 10);
// draw x- y-axis
gd.xaxis("title", "Month", "between", true, "step", 1, "frame", true,
"labels", ["J","F","M","A","M","J","J","A","S","O","N","D"]);
gd.yaxis("title", "Y-Value", "minor", 3, "digit", 2, "frame", true);
// draw title
gd.text("Example", 6, 1.6, 0, 0, -1);
// draw line for data
X = double(10);
X.fill(1.5, 1);
[Xptr, n] = X.ptr();
Y = double(10);
Y.fill(0.1, 0.1);
[Yptr, n] = Y.ptr();
gd.line(Xptr, Yptr, n);
// draw symbols
gd.color(255,0,0);
gd.symbol("D", Xptr, Yptr, n, 6);
// draw fill polygon
Y[9] = 0;
gd.polygon(Xptr, Yptr, n);
gd.show();
load("gd.dll", "matrix.dll", "netcdf.dll");
// this example use plot coordinates
// create image
gd = gd(700, 400);
// set drawing/filling color
gd.color(0, 0, 0);
// set plot parameters
gd.plot("xmin", 0, "xmax", 360, "xscale", 0.7,
"ymin", -90, "ymax", 90, "yscale", 0.7);
// draw axises
gd.xaxis("title", "Longitude", "digit", 0, "minor", 3, "frame", true, "step", 30);
gd.yaxis("title", "Latitude", "digit", 0, "minor", 3, "frame", true, "step", 30);
// x-axis data
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
nc = netcdf("e:/temp/ncep1/air.2005.nc");
nc.variable("air");
S = short(73,144);
S.import(nc[0,0,*,*]);
D = double(S);
D *= nc.scale_factor;
D += nc.add_offset;
D.flip("r");
[Dptr, nd] = D.ptr();
dmin = D.min();
dmax = D.max();
dstp = (dmax-dmin)/10;
// set palette colors and draw color bar
gd.palette("min", dmin, "max", dmax, "interpolate", 2);
[w, h] = gd.size();
gd.colorbar(50, 25, w-2*50, 10, 1);
// draw contour lines
for (d=dmin+dstp; d<dmax; d+=dstp) {
gd.contour(Xptr, nx, Yptr, ny, Dptr, d);
}
gd.show();
load("gd.dll", "matrix.dll", "netcdf.dll");
// this example use plot coordinates
// create image
gd = gd(1200, 800);
// set drawing/filling color
gd.color(0, 0, 0);
// set plot parameters
gd.plot("xmin", 0, "xmax", 360, "xscale", 0.7,
"ymin", -90, "ymax", 90, "yscale", 0.7);
// draw axises
gd.xaxis("title", "Longitude", "digit", 0, "minor", 3, "frame", true, "step", 30);
gd.yaxis("title", "Latitude", "digit", 0, "minor", 3, "frame", true, "step", 30);
// x-axis data
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);
nc = netcdf("e:/temp/ncep1/uwnd.2005.nc");
nc.variable("uwnd");
S.import(nc[0,0,*,*]);
U = double(S);
U *= nc.scale_factor;
U += nc.add_offset;
U.flip("r");
[Uptr, nd] = U.ptr();
nc = netcdf("e:/temp/ncep1/vwnd.2005.nc");
nc.variable("vwnd");
S.import(nc[0,0,*,*]);
V = double(S);
V *= nc.scale_factor;
V += nc.add_offset;
V.flip("r");
[Vptr, nd] = V.ptr();
// set palette colors and draw color bar
gd.palette("min", 0, "max", 30, "interpolate", 2);
[w, h] = gd.size();
gd.colorbar(50, 25, w-2*50, 10, 1);
// draw wind vectors
gd.field(Xptr, nx, Yptr, ny, Uptr, Vptr, 2);
gd.show();
load("gd.dll");
// this example use screen coordinates
//image file name
fname = "test.gif";
// create image
gd = gd(300, 300, false);
// draw lines and save image as gif animation
gd.begin(fname);
for (i=10; i<300; i+=10) {
gd.line(0,0, 300, i);
gd.add(fname);
}
gd.end(fname);