Contact: zeng  @  zegraph.com      Last update: August 2014

ZeGraph Library

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.

In the default screen coordinate system (SCS) of ZeGraph with image width w and height h, x varies from -w/2 to w/2, y from -h/2 to h/2; and z from the smaller of -w/2 and -h/2 to the larger of w/2 and h/2. Without rotation, the x-axis of SCS points from left to right, y-axis from bottom to top, and z-axis toward you. Objects in a plot use the plot coordinate system (PCS) determined by the plot's primary x-y-z axises. And objects in a globe use the globe coordinate system (GCS) determined by the globe's radius.

General

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.

Axis

.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.

Color

.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

Colorbar

.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.

Globe

.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.

Light

.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.

Line

.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.

Material

.ambient(r, g, b[, a]) numbers Sets the ambient color of the material object. See example-4.
.diffuse(r, g, b[, a]) numbers Sets the diffuse color of the material object. See example-4.
.emission(r, g, b[, a]) numbers Sets the emission color of the material object. See example-4.
.specular(r, g, b[, a]) numbers Sets the specular color of the material object. See example-4.
.shininess(factor) numbers Sets the shininess factor (0 to 1). See example-4.

Node

.add(typename) string Creates an object and adds it to the node. The type name may be "axis", "colorbar", "globe", "light", "line", "node", "plot", "point", "polygon", or "text". It returns the created object. See example-4.
.clear()   Removes all objects added to the node.
.color(r, g, b[, a]) numbers Sets the default color for objects in the node..
.remove(obj) use Removes the specified object from the node.

Plot

.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.

Point

.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.

Polygon

.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.

Texture Coordinate

.add(s, t [, s, t ...]) numbers Adds texture coordinate data to the object. See example-6.
.add(ptr, n) user, integers Adds texture coordinate data to the object. The ptr must be a double pointer to n data, consisting s and t texture coordinates between 0 and 1.
.clear()   Clears texture coordinate data.
.print()   Print texture coordinate data

Text

.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.

Texture

.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.

Vertex

.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.

ZeGraph

.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.