zeGraph Library

About Graphic Format

The tofile(fname) function of zeGraph supports image formats of PNG, TIFF, GIF, JPEG, JPEG2000, and BMP, and vector graphic formats of EMF. But which one to use?

PNG and TIFF are recommend if you use texture or your graph has rich colors. The compression of these two is lossless and therefore produce better printout than GIF or JPEG. GIF may gives the smallest file size, but the color is limited to 256. JPEG is not recommended if you have text in a graph. JPEG2000 is supposed to be able to produce small file size while maintaining high image quality, but applications supporting the format is limited.

The enhanced meta file (EMF) is recommended if you do not use texture and other advanced effects of OpenGL, e.g., fog, and your plot is 2D .

General

Function Parameter Type Remark
zegraph(typename, ...] string Returns a zeGraph object if only one argument is used; otherwise returns an array of zeGraph objects. Eligible type names include "axis", "blend", "color", "colorbar", "fog", "font", "light", "line", "material", "node", "point", "plot", "polygon", "render", "scene", "stencil", "texcoord", "text", "texture", and "vertex"
enable(obj, ...) user Enables objects.
disable(obj, ...) user disables objects.
zgtype(obj, typename) user, string Returns true if the caller is the named zeGraph object.
linenormal(x0, y0, z0, x1, y1, z1, x2, y2, z2) numbers Returns an array with x in [0], y in [1], and z in [2] as the line (p(x0, y0, z0), p(x1, y1, z1), p(x2, y2, z2), ) normal at (x1, y1, z1).
planenormal(x0, y0, z0, x1, y1, z1, x2, y2, z2) numbers Returns an array with x in [0], y in [1], and z in [2] as the normal of the plane determine by vectors of (x1-x0, y1-y0, z1-z0) and (x2-x0, y2-y0, z2-z0).
direction(x1, y1, z1, x2, y2, z2) numbers Returns an array with latitude in [0] and longitude in [1] that represent the vector direction from (x1, y1, z1) to (x2, y2, z2).

Axis

:angle( a) number Rotates the axis about itself for a degrees.
:font(fnt, n) user, number Sets the font object fnt to the caller and the font size to n points.
:font(n) number Sets the font size to n points.
:offset(dx,dy, dz) numbers Moves the axis off the origin of the global coordinate.
:range(min, max) numbers Sets axis range.
:smooth(flag) true/false Renders smooth lines if flag is true. It requires a preceding blend object.
:showticks(flag) true/false Shows (flag=true) or suppress ticks.
:showlabels(flag) true/false Shows (flag= true) or suppress axis labels and title.
:title(str) string Sets axis title. Refer to the string() function of text for subscript, superscript, and symbols.
:tickmarks(start, step, minor) numbers Sets axis tick marks, i.e., the start value, the step between major ticks, and the number of minor tick marks between major tick marks.
:ticksize(factor) number Scales up or down the tick length.
:ticklabels(label[, center]) string, true/false Customizes tick labels. If center = true, put labels between major ticks. Use "|", "\n", or "\r" to mark separation of labels, e.g., "1900|1901\n1902|1903". Refer to the string() function of text for subscript, superscript, and symbols.
:tickdigits(n[, flag]) user, number, integer (true/false) Sets tick number digits. Uses exponential format if flag= true.
:type(typename[, flag]) string, true/false Sets axis as x-, y-, or z-axis if typename is "x", "y", or "z". If flag=true, x-axis ticks point to the left, y-axis ticks point down, and z-axis ticks point to the left.
:width(w) number Sets the line width of axis.

Blend

:dst(factor) string Sets the destination blending factor of the blend object. The factor may be "zero", "one", "one_minus_src_color", "one_minus_dst_alpha", "one_minus_src_alpha", "src_color", "dst_alpha", or "src_alpha", corresponding to OpenGL's GL_ZERO parameters and etc.
:src(factor) string Sets the source blending factor of the blend object. The factor may be "zero", "one", "one_minus_dst_color", "one_minus_dst_alpha", "one_minus_src_alpha", "dst_color", "dst_alpha", "src_alpha", or "src_alpha_saturate", corresponding to OpenGL's GL_ZERO parameters and etc.

Color

:add(r, g, b[, a[, r, g, b, a...]]) numbers Adds data of red, green, blue and alpha to the color object. Color data should be between 0 and 1.
:add(ptr, n) number Adds data to the color object. The object ptr contains a pointer to n double data in memory, consisting red, green, blue, and alpha. Color data should be between 0 and 1.
:clear()   Clears data in the caller.
:print([fname]) string Print color data to the screen or the file.
:size()   Returns the number of color datasets in the caller.
:set(idx, r, g, b,[ a]) integer, number, number, number , number Sets r, g, b, and a to the color at idx.

Colorbar

:add(r, g, b, v) numbers Add color data for the contour value.
:clear()   Clears colorbar data.
:color(r, g, b) numbers Sets colorbar label color.
:discrete(flag) true/false Sets colorbar as discrete type if flag= true.
:font(fnt, n) user, number Sets the font object fnt to the caller and the font size to n points.
:font(n) number Sets the font size to n points.
:get(value) number Returns color data for the value in an array: [0]=red, [1]=green, and [2]=blue.
:interpolate(n) number Interpolates color data n times.
:labels(start, step, n) numbers Shows n labels with the first at the start value, the second at start + step, and etc.
:labeldigits( n[, flag]) number, true/false Sets label digits. Uses exponential format if flag=true.
:position(xoffset, yoffset, width, height) numbers Sets the color bar position. Position parameters are factor referring the the image width and height. If width > height, produces a horizontal bar; otherwise a vertical bar.

Fog

:color(r, g, b[, a]) numbers Sets fog color.
:params(density, start, end) numbers Sets parameters of GL_FOG_DENSITY, GL_FOG_START, and GL_FOG_END for OpenGL's fog function.
:linear(flag) true/false If flag=true, sets the GL_FOG_MODE parameter to GL_LINEAR; otherwise to GL_EXP.

Font

:truetype(filename) string Sets font object to use the specified truetype font.

Light

:ambient(r, g, b[, a]) numbers Sets the ambient color of light.
:diffuse(r, g, b[, a]) numbers Sets the diffuse color of light.
:specular(r, g, b[, a]) numbers Sets the specular color of light.
:attenuation(constant, linear, quadratic) numbers Sets the constant, linear, and quadratic attenuation parameters of the light.
:viewer(flag) true/false sets the GL_LIGHT_MODEL_LOCAL_VIEWER parameter to 1 if flag=true; otherwise to zero
:local(flag) true/false Sets the light as local if flag=true; otherwise directional.
:model(flag) true/false Uses light model if flag=true; otherwise uses material color.
:position(x, y, z) numbers Sets light position.
:spotdir(x, y, z) numbers Sets the spot light direction.
:spotexp(factor) number Sets the intensity distribution of the spot light.
:spotcut(cutoff) number Sets the cutoff angle of the spot light.
:oneside(flag) true/false Lights only one side of an object if flag=true.

Line

color(r, g, b[, a]) numbers Sets the default color.
:color(color) user Sets color object to the line as per vertex color.
:color()   Returns the vertex color object of the line.
: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 normal
:normal()   Returns the vertex normal object of the line.
:dot(width[, factor]) numbers Sets the line style as dot of the specified width. The factor determines length to width ratio of a dot.
:dash(width[, factor]) numbers Sets the line style as dash of the specified width. The factor determines length to width ratio of a dash.
:dotdash(width[, factor]) numbers Sets the line style as dot-dash of the specified width. The factor determines length to width ratio of dot-dash.
:solid(width) number Sets the line style as solid of the specified width.
:type( typename) string Sets the line type. Eligible typename include "lines", "loop", "strip".
:smooth(flag) true/false Renders smooth lines if flag is true. It requires a preceding blend object in the same node or plot.
:rotatex(degree) number Sets x-rotation transform
:rotatey(degree) number Sets y-rotation transform
:rotatez(degree) number Sets z-rotation transform
:scale(x, y, z) number Sets scale transform
:translate(x, y, z) number Sets translation transform
:reset()   Resets transform to none.
: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 (iso) found for Z at regular grids (X, Y). Returns a vertex object.
:contour(X, Y, Z, I, n, iso) user, user, user, user, number, number Adds to the line object vertex data from contouring for the iso-value (iso) 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. Returns a vertex object.
:contour(vertex, n, iso) user, integer, number Adds to the line object vertex data from contouring for the iso-value (iso) found in the vertex data. n must be 3 or 4, indicating whether a dataset of vertex forms a triangle or quads.

Material

:ambient(side, r, g, b[, a]) numbers Sets the ambient color of the material object. If side > 0, applies the color to the front side; if side < 0, applies the color to the back side; and if side = 0, applies the color to both sides.
:diffuse(side, r, g, b[, a]) numbers Sets the diffuse color of the material object. If side > 0, applies the color to the front side; if side < 0, applies the color to the back side; and if side = 0, applies the color to both sides.
:emission(side, r, g, b[, a]) numbers Sets the emission color of the material object. If side > 0, applies the color to the front side; if side < 0, applies the color to the back side; and if side = 0, applies the color to both sides.
:specular(side, r, g, b[, a]) numbers Sets the specular color of the material object. If side > 0, applies the color to the front side; if side < 0, applies the color to the back side; and if side = 0, applies the color to both sides.
:shininess(side, factor) numbers Sets the shininess factor (0 to 1). If side > 0, applies the factor to the front side; if side < 0, applies the factor to the back side; and if side = 0, applies the factor to both sides.

Node

:add(obj[, ...]) user Adds objects to the node.
:clear()   Clears objects from the node.
:closed(flag) true/false Sets the node as closed type, which will save all OpenGL parameters before rendering object in it and restore those parameters after rendering.
:color(r, g, b[, a]) numbers Sets the default line color.
:get(idx) integer Gets the object at idx.
:rotatex(degree) number Sets x-rotation transform.
:rotatey(degree) number Sets y-rotation transform.
:rotatez(degree) number Sets z-rotation transform.
:scale(x, y, z) number Sets scale transform.
:translate(x, y, z) number Sets translation transform.
:reset()   Resets transform to none.

Plot

add(obj[, ...]) user Adds objects to the plot.
:anchor(obj, x, y, z) user, numb, number, number Anchors the object at (x, y, z) in the plot coordinate. An anchored object will not be affected by the rotation and scaling transforms of the plot.
:anchor(obj, X, Y, Z, n) user, user, user, user, integer Anchors the object at (x, y, z) in the plot coordinate. X, Y, and Z must be pointers to n data double type.
:clear()   Clears objects added to the plot by the add and anchor functions.
:rotate(zdeg, xdeg) numbers Sets the z and x-rotation transform, i.e., rotate about z-axis first and then about the x-axis.
:scale(x, y, z) numbers Sets the scale transform
:font(fnt, n) user, number Sets the font object fnt to the caller and the font size to n points.
:font(n) number Sets the font size to n points.
:smooth(flag) true/false Enables/disables internal blending of plot, which is enabled initially for 2D plot and disabled for 3D plot.
:field(U, V, X, Y, n, size, colorbar) user, user, user, user, integer, number, user Plots 2D vector field. U, V, X, and Y must be double array pointers containing n data. U and V should have wind data scaled to produce proper size vectors. The size parameter determines the arrow head size; and the colorbar object is used to assign colors to vectors according to their size.
:field(U, V, X, nx, Y, ny, size, colorbar) user, user, user, integer, user, integer, number, user Plots 2D vector field. U and V should be double matrix pointer containing nx by ny wind data scaled to produce proper size vectors; X and Y are double array pointer containing grid coordinates. The size parameter determines the arrow head size; and the colorbar object is used to assign colors to vectors according to their size.
:field(U, V, W, X, Y, Z, n, size, colorbar) user, user, user, user, user, user, integer, number, user Plots 3D field using cones. Parameters have similar meaning to those of field(U, V, X, Y, n, size, colorbar) function.
:field(U, V, W, X, nx, Y,ny, Z, nz, size, colorbar) user, user, user, user, integer, user, integer, user, integer, number, user Plots 3D field using cones. Parameters have similar meaning to those of field(U, V, X, nx, Y, ny, size, colorbar) function.
:global(w, h, x, y, z) numbers Returns an array containing the global coordinate converted from the local coordinate (x, y, z), i.e., [0] = x, [1] = y, and [2] = z. Parameters w and h are the viewport width and height of the scene object that contains the plot.
:local(w, h, x, y, z) numbers Returns an array containing the local coordinate converted from the global coordinate (x, y, z), i.e., [0] = x, [1] = y, and [2] = z. Parameters w and h are the viewport width and height of the scene object that contains the plot.
:xaxis([xdir, ydir, zdir]) numbers Returns the x-axis of the plot for further manipulation by axis functions. If the optional parameters are given, it anchors the x-axis of the plot. The signs of xdir, ydir, and zdir control in which direction the axis will move from the origin.
:yaxis([xdir, ydir, zdir]) numbers Returns the y-axis of the plot for further manipulation by axis functions. If the optional parameters are given, it anchors the y-axis of the plot. The signs of xdir, ydir, and zdir control in which direction the axis will move from the origin.
:zaxis([xdir, ydir, zdir]) numbers Returns the z-axis of the plot for further manipulation by axis functions. If the optional parameters are given, it anchors the z-axis of the plot. The signs of xdir, ydir, and zdir control in which direction the axis will move from the origin.

Point

:color(r, g, b[, a]) numbers Sets the default color.
:color(color) user Sets color object to the point object as per vertex color.
:color()   Returns the vertex color object of the point.
:vertex(vertex) user Sets the vertex object to the point
:vertex()   Returns the vertex object of the point.
: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.
:smooth(flag) true/false Renders point as round shape if flag=true; otherwise as square.
:rotatex(degree) number Sets x-rotation transform
:rotatey(degree) number Sets y-rotation transform
:rotatez(degree) number Sets z-rotation transform
:scale(x, y, z) numbers Sets scale transform
:translate(x, y, z) numbers Sets translation transform
:reset()   Resets transform to none.
:bmp(filename[,bgR, bgG, bgB]) string, integer, integer, integer Adds to the point vertex and color objects that contains pixel coordinates (x from o to width-1; y from 0 to image height-1, z = 0) and colors of the image in the file. It returns the vertex object. If the background color is specified and range from 0 to 255, pixels with the background color will be excluded.

Polygon

:color(r, g, b[, a]) numbers Sets the default color.
:color(color) user Sets the color object to the polygon as per vertex color.
:color()   Returns the vertex color object of the polygon.
:vertex(vertex) user Sets the vertex object to the polygon.
:vertex()   Returns the vertex object of the polygon
: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.
:clockwise(flag) true/false Sets the polygon winding to clockwise if flag=true..
:cull(flag) number Set cull face to none if flag=0, to cull front if flag>0, and to cull back if flag<0.
:fill(flag) number Renders polygon as points if flag=0, as filled 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".
:smooth(flag) true/false Renders smooth lines if flag=true. It requires a preceding blend object in the same node or plot that the polygon belongs to.
:width(w) number Sets polygon line width.
:rotatex(degree) number Sets x-rotation transform
:rotatey(degree) number Sets y-rotation transform
:rotatez(degree) number Sets z-rotation transform
:scale(x, y, z) numbers Sets scale transform
:translate(x, y, z) numbers Sets translation transform
:reset()   Resets transform to none.
:isosurface(W, X, ncol, Y, nrow, Z, nlvl, iso) user, user, number, user, number, user, number, number Returns the vertex object added to the polygon. Vertex data representing triangles of iso-surfaces of 4D data W on 3D regular grids of X, Y, and Z. These user object contains double pointers to data in memory.
:mesh( X, Y, Z, I, n) user, user, user, user, number Returns the vertex object added to the polygon. Vertex data are from triangles resulted from the delaunay() function in the matrix library. I and n are the pointer to triangle indices and the number of triangles, respectively.
:mesh(Z, X, nx, Y, ny) user, user, number, user, number Returns the vertex object added to the polygon. Vertex data are from Z at regular grids (X, Y).
: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.
:sphere(r, n[, flag]) number, integer, true/false Adds to the polygon vertex and normal data for a sphere surface of radius=r; and texture coordinate data if flag > 0. If flag<=0, 0<n<=8 is the iteration number for tetrahedron tesselation; otherwise n is the degree of increment for slicing the sphere. It returns the vertex.

Render

:add(obj[, obj, ...]) user, ... Add scene objects to the render.
:clear()   Clears scene objects from the render.
:color(r, g, b) numbers Sets the background color of image.
:size(width, height[, depth]) numbers Sets the image width and height, and optionally the depth. For 3D graphics, the depth should be larger than 24 (32 by default); and for 2D graphic, a depth of 2 may be enough. A smaller depth reduces memory use significantly.
:size()   Returns the image size as an array ([0]=width and [1]=height).
:towindow(hwnd) user Renders image to the window handle in hwnd object.
: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", or "emf".
: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.
:toarray(R, G, B, n) user, user, user, number Renders image colors to R, G, and B which should be pointers to n char type data.

Scene

:color(r, g, b[, a]) numbers Sets the foreground color.
:root(node) number Sets the root node.
:viewport(x, y, w, h) numbers Sets the viewport starting at (x, y) and having width w and height h.
:perspective(flag[, factor]) true/false, number Uses perspective view if flag=true. The scale factor modifies the perspective depth.

Stencil

mask(flag) true/false Sets the mask to true or false
:depthmask(flag) true/false Sets the depth mask.
:colormask(r, g, b, a) true/false, true/false, true/false, true/false Sets the color mask of the stencil buffer.
:reference(reference) number Sets the reference parameter of the stencil buffer.
:test(property) string Sets the test property of the stencil buffer object. Eligible properties include "never", "always", "equal", "nequal", "less", "lequal", "greater", and "gequal".
:fail(property) string Sets the fail test property of the stencil buffer object. Eligible properties include "keep", "zeor", "replace", "increment", "decrement", and "invert".
:zfail(property) string Sets the zfail test property of the stencil buffer object. Eligible properties include "keep", "zeor", "replace", "increment", "decrement", and "invert".
:zpass(property) string Sets the zpass test property of the stencil buffer object. Eligible properties include "keep", "zeor", "replace", "increment", "decrement", and "invert".

Texture Coordinate

add(s, t [, s, t ...]) numbers Adds texture coordinate data to the object.
:add(ptr, n) user, number Adds texture coordinate data to the object. The object ptr contains a pointer to n double data in memory, consisting s and t data between 0 and 1.
:clear()   Clears data in the caller.
:image(filename, r, g, b) string, integer Loads the image from the file. Parameters r, g, and b determines the transparent color if they are between 0 and 255.
:print([fname]) string Print texture coordinate data to the screen or the file.
:size()   Returns the number of datasets in the caller.
:set(idx, s, t) integer, number, number Sets s and t to the texture coordinate at idx.

Text

:color(r, g, b) user, numbers Sets text color.
:font(fnt, n) user, number Sets the font object fnt to the text object and font size to n points.
:font(n) number Sets the font size to n points. Node: a large font size for a long string may result in a text texture wider than 1024, the limit of Windows's OpenGL implementation.
:string(str) string Sets the text string to be rendered. 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.
:layout(x0, y0, z0, x1, y1, z1, x2, y2, z2) numbers Sets the layout plane for the text object. The plane is determined by vectors of (x0,y0,z0)->(x1,y1,z1) and (x0,y0,z0)->(x2,y2,z2).
:size()   Return the size of the rendered text string as an array: [0] = width and [1] = height.

Texture

:image(filename,bR, bG, bB) string, numbers Load image from the file to the texture object. The bR, bG, and bB determine the alpha color. If the they are outside the range of 0 to 255, the texture is opaque.
:env(param) string Sets the texture environment parameter. Eligible properties include "modulate", "decal", and "blend".
:warps(param) string Sets the texture parameter of GL_TEXTURE_WRAP_S. Eligible properties include "clamp" and "repeat".
:warpt(param) string Sets the texture parameter of GL_TEXTURE_WRAP_T. Eligible properties include "clamp" and "repeat".
:min(param) string Sets the texture parameter of GL_TEXTURE_MIN_FILTER. Eligible properties include "linear" and "nearest".
:mag(param) string Sets the texture parameter of GL_TEXTURE_MAG_FILTER. Eligible properties include "linear" and "nearest".

Vertex

:add(x, y, z[, x, y, z...]) numbers Adds vertex coordinate data to the object.
:add(ptr, n) user, number Adds vertex coordinate data to the object. The object ptr contains a pointer to n data of double type, consisting x, y, and z data.
:clear()   Clears data in the caller.
:color(colorbar) user Returns a color object whose colors are determined by the colorbar and the z-values of the vertex.
:normal(np) integer Returns a vertex object to be used as vertex normal. np=1, np=3, np=4 indicates that the vertex data of the caller comprise points, triangles, or quads.
:print([fname]) string Print vertex data to the screen or the file.
:rotatex(degree) number Applies x-rotation transform on vertex data.
:rotatey(degree) number Applies y-rotation transform on vertex data.
:rotatez(degree) number Applies z-rotation transform on vertex data.
:scale(x, y, z) numbers Applies scale transform on vertex data.
:set(idx, x, y, z) integer, number, number, number Sets x, y, and z to the vertex at idx.
:size()   Returns the number of datasets in the caller.
:translate(x, y, z) numbers Applies translate transform on vertex data.
:xy2sphere(r) number Transforms longitude-latitude in degree in the vertex to x-y-z on a spherical surface with radius r.