Using the ZeGraph library typically involves 5 steps: (1) load the library; (2) create a zegraph object; (3) create and add objects to the scene of a zegraph object; (4) set object attributes; and (5) show or save the image. When the object added to a scene is a globe, plot, light, or node, it can be used to create and add objects as well. Other objects that can be created include axis, colorbar,
line, point, polygon, and text. A color, material, texture, texture coodinate, or vertex object may be obtained from some types objects as well.
| Function |
Input |
Remark |
| zegraph(width, height[, depth)); |
integers |
Creates a ZeGraph object and sets its image width and height. It is recommended to set the optional depth parameter to a large number (e.g., 32) for a 3D graph and to a small number (e.g., 3) for a 2D graph. See example-1. |
| .enable(obj, ...) |
user |
Enables objects. This function is registered for axis, colorbar,
globe, light, line, node,
plot, point, polygon, and text. See example-1. |
| .disable(obj, ...) |
user |
Disables objects. Refer to the enable function for registerd objects. See example-1. |
| .reset() |
|
Resets transform to none. This function is registered for axis, colorbar, globe, line, node, plot, point, polygon, and text |
| .rotatex(degree) |
number |
Rotates the object around the global x-axis, which points from left to right. Refer to the reset function for registerd objects. See example-2. |
| .rotatey(degree) |
number |
Rotates the object around the global y-axis, which points from bottom to top. Refer to the reset function for registerd objects. See example-2. |
| .rotatez(degree) |
number |
Rotates the object around the global z-axis, which points toward you. Refer to the reset function for registerd objects. See example-2. |
| .scale(fx, fy, fz) |
numbers |
Scales the object along the global x-y-z axises by the given factors. Refer to the reset function for registerd objects. See example-2. |
| .translate(dx, dy, dz) |
number |
Move the object away from the global center by the given offsets in pixel unit. Refer to the reset function for registerd objects. See example-2. |
| .color(red, green, blue) |
numbers |
Sets the axis color. See example-2. |
| .font(n) |
integer |
Sets the font size to n points. See example-2. |
| .linewidth(w) |
number |
Sets the line width of axis. |
| .range(min, max) |
numbers |
Sets the axis range. The default range is (-1,1). See example-2. |
| .smooth(flag) |
boolean |
Renders smooth lines if flag is true. |
| .showticks(flag) |
boolean |
Shows (flag=true) or hides the axis ticks. See example-5. |
| .showlabels(flag) |
boolean |
Shows (flag= true) or hides the axis labels and title. See example-5. |
| .title(string) |
string |
Sets the axis title. Refer to the string function of text
for using subscript, superscript, and symbols. See example-2. |
| .tickmarks(start, end, step, minor) |
numbers |
Sets the axis tick marks, i.e., the start value, the end value, the step between major
ticks, and the number of minor tick marks between major tick marks. See example-2. |
| .ticksize(factor) |
number |
Scales up or down the tick length. See example-2. |
| .ticklabels(s1,s2,...[,center]) |
strings, boolean |
Customizes tick labels. If center=true, it puts labels between major ticks.
Refer to the string
function of text for using subscript, superscript, and symbols. See example-2. |
| .tickdigits(n[, flag]) |
integer, boolean |
Sets the number of digits for tick labels. It uses the exponential format if flag=true. See example-2. |
| .type(typename[, flag]) |
string, boolean |
Sets the axis as x-, y-, or z-axis for typename of "x", "y",
or "z" respectively. If flag=true, x-axis ticks point to the left,
y-axis ticks point down, and z-axis ticks point to the left. See example-2. |
| .add(r, g, b, a[, r, g, b, a...]) |
numbers |
Adds color data of red, green, blue and alpha. Color
data should be between 0 and 1. See example-1. |
| .add(ptr, n) |
user, integers |
Adds color data. The ptr must be a double
to n data, consisted of red, green, blue, and alpha.
Color data should be between 0 and 1. |
| .clear() |
|
Clears color data. |
| .print() |
|
Print color data |
| .add(r, g, b, v[, r, g, b, v...]) |
numbers |
Adds color data (r, g, and b) for the contour value (v). See example-7. |
| .clear() |
|
Clears colorbar data. |
| .color(r, g, b) |
numbers |
Sets the color of colorbar label and lines. |
| .discrete(flag) |
boolean |
Sets colorbar type as discrete if flag= true. See example-7. |
| .font(n) |
integer |
Sets the font size to n points. See example-2 for axis. |
| .get(value) |
number |
Returns color data for the contour value in an array: [0]=red, [1]=green,
and [2]=blue. See example-7. |
| .interpolate(n) |
integer |
Interpolates colorbar values n times to have more color values. See example-8. |
| .linewidth(w) |
number |
Sets the line width of color divider in he colorbar. See example-7. |
| .labeldigits( n[, flag]) |
number, true/false |
Sets the label digits. Uses the exponential format if flag=true. See example-7. |
| .size(width, height) |
numbers |
Sets the colorbar size. If width>height (in pixel unit) , it produces a horizontal
bar; otherwise a vertical bar. See example-7. |
| .add(typename) |
string |
Creates an object and adds it to the globe. The type name may be "line", "node", "point", "polygon", or "text". It returns the created object. |
| .add(typename, x, y, z) |
string, numbers |
Creates an object and anchors it at (x,y,z) in the globe. It returns the created object. Notes that x and y are ongitude and latitude in degree and that z is the altitude above the globe surface in the same unit as the radius. See example-3. |
| .clear() |
|
Clears all objects in the globe. |
| .ll2xyz(lon, lat) |
numbers |
Transforms longitude lon amd latitude lat in degree to x-y-z on the globe
surface and returns x-y-z in an array. See example-3. |
| .xyz2ll(x, y, z) |
numbers |
Transforms x-y-z to longitude-latitude in degree and returns the results in an array. |
| .surface(radius[, iter]) |
numbers |
Generates polygons for the globe surface. You may control the smoothness of the surface by the optional iteration number. It returns a polygon object. See example-3. |
| .texture(radius, fname[, flag]) |
number, string, boolean |
Generates polygons for the globe surface and uses the image in fname (full path to a file) as the surface texture. If the atlantic ocean is in the image center, the flag should be true. It returns a polygon object. See example-3. |
| .texture(radius, ptr, nr, nc[, flag]) |
number, user, integer, integer, boolean |
Generates polygons for the globe surface and generates image from data in ptr as the surface texture. The parameter ptr must be a double pointer to nr rows by nc columns of data. It returns a texture object. |
| .grid(deg[, w]) |
numbers |
Generates llines as the globe grid lines. It return a node object that contains the line objects. See example-3. |
| focus(x, y) |
numbers |
Sets the focus point (longitude, latitude) on the globe, e.g., rotating the globe around the z-axis and the around the x-axis. It returns the rotation angles in an array. See example-3. |
| .line(x1, y2, x2, y2) |
numbers |
Draws a line from (x1,y1) to (x2,y2) on the globe surface and returns a line object. See example-3. |
| .gshhs(fname[, lw, yn]) |
string, number |
Draws coastlines using GSHHS data in the file fname on the globe surface and returns a node object. Use the optional parameter lw to set the line width and yn to set line smoothing attribute. See example-3. |
| .light(x, y) |
numbers |
Sets the light position and returns the light object. Note that the light is directional from the globe center to the longitude x and latitude y in degree. See example-3. |
| .sun(day, hour, minute, second) |
integers |
Sets the light position according to the sun's position at the specified time and returns the light object. Note that the object must not be added to another object. See example-3. |
| .ambient(red, green, blue) |
numbers |
Sets the ambient color of light. See example-4. |
| .position(x, y, z) |
numbers |
Sets light position as if light comes in the direction of (x,y,z) to (0,0,0). See example-4. |
| .add(typename) |
string |
Creates an object and adds it to the light. The type name may be "line", "node",
"plot", "point", "polygon", or "text". It returns the created object. See example-4. |
| .clear() |
|
Clears all objects in the light. |
| .color(r, g, b[, a]) |
numbers |
Sets the default color. See example-1. |
| .color(color) |
user |
Sets the color object to the line as vertex color. |
| .color() |
|
Returns the vertex color object of the line. See example-1. |
| .vertex(vertex) |
user |
Sets vertex to the line |
| .vertex() |
|
Returns the vertex object of the line. |
| .normal(vertex) |
user |
Sets vertex object to the line as vertex normal |
| .normal() |
|
Returns the vertex normal object of the line. |
| .dot(width[, factor]) |
numbers |
Sets the line style as dot of given width. The factor determines
the length to width ratio between dots. |
| .dash(width[, factor]) |
numbers |
Sets the line style as dash of given width. The factor determines
the length to width ratio between dashes. See example-10. |
| .dotdash(width[, factor]) |
numbers |
Sets the line style as dot-dash of given width. The factor determines
the length to width ratio between dot-dashes. |
| .solid(width) |
number |
Sets the line style as solid of given width. See example-1. |
| .smooth(flag) |
true/false |
Renders smooth lines if flag=true. See example-1. |
| .type( typename) |
string |
Sets the line type. Eligible typename include "lines", "loop", "strip". |
| .contour(Z, X, nx, Y, ny, iso) |
user, user, number, user, number, number |
Adds to the line object vertex data from contouring for the iso-value
found for Z at regular grids (X, Y). It returns a vertex object. The X, Y, and Z must be double pointers of size nx, ny, and nx*ny, respectively. See example-8. |
| .contour(X, Y, Z, I, n, iso) |
user, user, user, user, number, number |
Adds object vertex data to the line from contouring for the iso-value found in triangles that are results of the delaunay() function in
the matrix library. I and n are the
pointer to triangle indices and the number of triangles, respectively. It returns
a vertex object. |
| .gshhs(file, x1, x2, y1, y2) |
string, numbers |
Adds GSHHS costline coordinate data from the file in the given longitude/latitude ranges. See example-5. |
| .vector(u, v, size) |
numbers |
Adds vertices to form a wind vector. The size parameter controls the arrow head size. See example-9. |
| .add(typename) |
string |
Creates an object and adds it to the plot. The type name may be "axis", "colorbar",
"globe", "light", "line", "node",
"plot", "point", "polygon", or "text". It returns the created object. See example-2. |
| .add(typename, x, y, z) |
string, numbers |
Creates an object and anchors it at (x,y,z) in the plot . An anchored object
will not be affected by the scaling transforms of the plot. It returns the created object. |
| .clear() |
|
Clears objects added to the plot. |
| .global(x, y, z) |
numbers |
Returns an array containing the global coordinate converted from the local
coordinate. The x-y-z ranges of the plot should be set first before calling this function. See example-2. |
| .local(x, y, z) |
numbers |
Returns an array containing the local coordinate converted from the global
coordinate. The x-y-z ranges of the plot should be set first before calling this function. |
| .clip(flag) |
true/false |
Sets the clipping flag that determines showing or hiding vertices outside the x-y-z axis ranges. |
| .xaxis(xdir, ydir, zdir) |
numbers |
Anchors the x-axis of the plot. The signs of xdir, ydir, and zdir control
the irection that the axisl moves awway from the origin. It returns the x-axis of the plot for further manipulation by axis functions. See example-2. |
| .xaxis() |
|
Returns the x-axis of the plot for further manipulation by axis functions. See example-2. |
| .yaxis(xdir, ydir, zdir) |
numbers |
Anchors the y-axis of the plot. The signs of xdir, ydir, and zdir control
the irection that the axisl moves awway from the origin. It returns the y-axis of the plot for further manipulation by axis functions. See example-2. |
| .yaxis() |
|
Returns the y-axis of the plot for further manipulation by axis functions. See example-2. |
| .zaxis(xdir, ydir, zdir) |
numbers |
Anchors the z-axis of the plot. The signs of xdir, ydir, and zdir control
the irection that the axisl moves awway from the origin. It returns the z-axis of the plot for further manipulation by axis functions. See example-2. |
| .zaxis() |
|
Returns the z-axis of the plot for further manipulation by axis functions. See example-2. |
| .color(r, g, b[, a]) |
numbers |
Sets the default color. See example-10. |
| .color(color) |
user |
Sets color object to the point object as vertex color. |
| .color() |
|
Returns the vertex color object of the point. |
| .vertex(vertex) |
user |
Sets the vertex object of the point |
| .vertex() |
|
Returns the vertex object of the point. See example-10. |
| .normal(vertex) |
user |
Sets the vertex object to the point as vertex normal |
| .normal() |
|
Returns the vertex normal object of the point. |
| .size(n) |
number |
Sets the point size in pixel. See example-10. |
| .smooth(flag) |
boolean |
Renders point as round dot if flag=true; otherwise as square. See example-10. |
| .color(r, g, b[, a]) |
numbers |
Sets the default color. |
| .color(color) |
user |
Sets the color object to the polygon as vertex color. |
| .color() |
|
Returns the vertex color object of the polygon. |
| .vertex(vertex) |
user |
Sets the vertex object of the polygon. |
| .vertex() |
|
Returns the vertex object of the polygon. See example-6. |
| .normal(vertex) |
user |
Sets the vertex object to the polygon as vertex normal. |
| .normal() |
|
Returns the vertex normal object of the polygon. |
| .texcoord(texcoord) |
user |
Sets texture coordinate object to the polygon. |
| .texcoord() |
|
Returns the texture coordinate object of the polygon. See example-6. |
| .material(obj) |
user |
Sets the material object to the polygon. |
| .material() |
|
Returns the material object of the polygon. See example-4. |
| .texture(obj) |
user |
Sets the texture object to the polygon. |
| .texture() |
|
Returns the texture object of the polygon. See example-6. |
| .fill(flag) |
number |
Renders polygon as points if flag=0, as filled polygons if flag>0, and as lines
if flag<0. |
| .type(typename) |
string |
Sets the polygon type. Eligible typename include "triangles", "trianglestrip",
"trianglefan", "quads", "quadstrip", and "polygon". See example-6. |
| .smooth(flag) |
boolean |
Renders smooth polygon edges if flag=true. |
| .pattern(str) |
string |
Sets the fill pattern of polygon. The string should be no shorter than
1024 characters with x and o marking fill and unfilled bits of a 32x32 bitmap. |
| .box(size) |
number |
Adds to vertex and normal objects to the polyson to form box surface of the size. |
| .cone(h, r) |
numbers |
Adds to vertex and normal objects to the polyson to form cone surface of radius r and height h. |
| .cylinder(h, r) |
numbers |
Adds to vertex and normal objects to the polyson to form cylinder surface. See example-4. |
| .disk(r) |
number |
Adds to vertex and normal objects to the polyson to form disk surface. |
| .sphere(r, [n, flag]) |
number, integer, true/false |
Adds to vertex and normal objects to the polyson to form a sphere surface of radius=r.
If flag=true the polygon will have texture coordinate object and n is the
degree of increment for slicing the sphere; otherwise, 0<n<=8
is the iteration number for tetrahedron tesselation. See example-3. |
| .torus(R, r) |
numbers |
Adds to vertex and normal objects to the polyson to form torus surface. See example-4. |
| .color(r, g, b) |
user, numbers |
Sets text color. See example-1. |
| .font(n) |
user |
Sets the font size to n points. See example-1. |
| .string(str[,xalign, yalign])) |
string, integers |
Sets the text string to be rendered.The optional parameters xalign and yalign determines the x-alignment (-1: left; 0: center; 1: right) and y-alignment (-1: bottom; 0: middle; 1: top). A superscript and subscript may be
marked by these pairs of tags: <sub> and </sub>, <sup>
and </sup>, respectively.
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. It return the width and height of the rendered string in an array. See example-1. |
| .image(filename,bR, bG, bB) |
string, integers |
Load image from the file to the texture object. The bR, bG, and
bB determine the alpha color. If the they are negative, the texture is opaque. It returns an array containing the texture coordinate boundary (s,t). See example-6. |
| .data(ptr, width, height, cbar) |
user, integer, integer, user |
Makes texture using data in ptr and the colorbar cbar. The parameter ptr must be a pointer to double data of width*height size. It returns an array containing the texture coordinate boundary (s,t). See example-7. |
| .add(x, y, z[, x, y, z...]) |
numbers |
Adds vertex coordinate data to the object. See example-1. |
| .add(ptr, n) |
user, integers |
Adds vertex coordinate data to the object. The ptr must be a double pointer
to n data, consisting x, y, and z coordinates. See example-10. |
| .clear() |
|
Clears data in the vertex. |
| .color(colorbar, color) |
users |
Adds colors to the input color object according to the colorbar and
the z-values of the vertex. |
| .normal(np, vertex) |
integer, user |
Adds vertices to the input vertex object to be used as vertex normal. np=1, 2, 3, or 4 indicates that the vertex data comprise points, linestrip, triangles,
or quads. |
| .print() |
|
Print vertex data |
| .ll2xyz([r]) |
number |
Transforms longitude-latitude in degree to x-y-z on a spherical
surface with radius r (default is 1). |
| .xyz2ll() |
number |
Transforms x-y-z to longitude-latitude in degree. |
| .map(x0) |
number |
Transforms longitude/latitude in degree to x-y-z on an oval-shaped map and returns an array containing x-y ranges (xmin, xmax, ymin, and ymax). The parameter x0 should be set to to the map center, e.g., 180 for the Pacific in the center. See example-5. |
| .polar(ra, po, x0) |
numbers |
Transforms longitude/latitude in degree to x-y-z on an polar-view map. The ra is the radius length from the pole po, which should be either 90 or -90, and x0, the longitude along the global y-axis. See example-5. |
| .flatten() |
|
Set all z to zero to flatten the vertex. See example-7. |
| .add(typename) |
string |
Creates an object and adds it to the scene of ZeGraph. The type name may be "axis", "colorbar",
"globe", "light", "line", "node",
"plot", "point", "polygon", or "text". It returns the created object. See example-1. |
| .color(r, g, b) |
numbers |
Sets the foreground color. See example-1. |
| .bgcolor(r, g, b) |
numbers |
Sets the background color. See example-1. |
| .font(file) |
string |
Sets the typetype font file (full path to a file) to be used by ZeGraph. |
| .lookat(ex, ey, ez, cx, cy, cz) |
numbers |
Looks at the scene from (ex,ey,ez) to (cx,cy,cz) in the global coordinate system. |
| .perspective(flag[, factor]) |
boolean, number |
Uses perspective view if flag=true. The scale factor modifies
the perspective depth. |
| .show([node, ms]) |
user, integer |
Creates a window and renders the scene in it. If the node and time interval (ms) parameters are specified, the window responds to mouse and key interactions: mouse-dragging and arrow keys rotate the node; double-clicking animate the node; and right-clicking reset the node to its initial status. See example-1. |
| .towindow(hwnd) |
user |
Renders image to the window handle. |
| .tofile(filename) |
string |
Renders image to the file. The image format is determined by the file
extension, which may be "bmp", "tif", "png",
"jpg", "gif". If the file name is "stdout" (e.g., "stdout.png") the image will be send to the standart output device, which may be useful for web application. If the file name is "stream" (e.g., "stream.png"), the function returns an array containing pointer to image stream and the number of bytes. See example-1. |
| .togifa(fname[, delay) |
string, integer |
Renders image to GIF animation with the frame rate (in 1/100s unit) controlled
by the optional delay parameter. Initially, fname should be a file name with
"gif" extension; then fname should be "add" for adding
image to the file or "end" for ending the animation. See example-11. |
