Contact: zeng @ zegraph.com Last update: 20 January 2010
ZeGraph uses a small number of objects to construct scenes and render them to a file, a window, or a byte stream. The figure bellow illustrates a scene structure. In summary, the minimal requirement for drawing any shape is to create a render object, create a scene object and add it to the render, create a node object and assigned it to the scene as the root node; and then create shape objects and add them to the node as leaves. The root node is optional - you can add shape objects to the scene directly.
The render object in a scene determines the image size and background color, A render may have multiple scene objects. This is equivalent to multiple sub-plots in a single plot page of other software.
A scene object determines the plotting area and default foreground color. A scene object has one and only one node object, which is the root node in a scene and may be replaced by another node object. The first time a scene is added to a render, its viewport is set to fill the whole rendering area, i.e., the viewport begins at (0,0) and has width and height of the render.
A node object may contain any number of any ZeGraph object except for render and scene. If color is set to a node, the color will becomes the default color of all objects in the node.A light object may be used to enhance 3D effect of shape objects. All objects in a light will be effected.
ZeGraph uses the same Cartesian coordinate system as that of OpenGL shown bellow. That is the positive x points to the right, the positive y to the top, and the positive z to the viewer. However, unlike most other OpenGL applications whose global x-, y-, and z-axis ranges from -1 to 1, the axes of ZeGraph correspond to the view port size and depth in pixel unit. That is, assuming the view port width and height are w and h respectively, the x-axis ranges from -w/2 to w/2; the y-axis from -h/2 to h/2; and the z-axis from -max(w,h)/2 to max(w,h)/2 in an orthogonal projection and from 1 to 1+s*(w+h) in a perspective projection, where the s-factor is determined by the user.
All shapes are presented by point, line, and polygon. Shape objects may be freely added to a node object, a light object, or a plot object. The important issue here is correctly adding data to vertex, normal, color, and texture coordinate of shapes and setting shapes to correct types. As shown below, for the same number of vertices, setting a line or polygon to different types produces different results. For a polygon, it is also important to arrange vertices in anti-clockwise order so that when a light is used, its interaction with vertex normal produces correct shading effect.
A vertex object contains x-y-z coordinates; and the same vertex object may be shared by any numbers of shape objects. If you want to have gradient colors for lines or polygons, or to have different colors for individual points, you can assign to the shape object a color object, which contains color data of red, green, blue, and alpha. When a light is used and a vertex object is used as the vertex normal of points, lines, or polygons, their degrees of illumination vary. A vertex object used as vertex normal should contains normalized coordinates, i.e., sqrt(x^2+y^2+z^2)=1.
A text object may contain a string of characters, which are presented by filled triangles in rendering. Superscript, subscript, and special symbols are supported by embedding tags of <sup></sup>, <sub></sub>, and <sym></sym> in a sting. Any langage can be rendered by setting a font object to text and setting a file name of truetype font for that language to the font obeject.
A material object may be set to a polygon object to modify its surface property. Of course, a light object should be used to illuminate the polygon.
An image may be wrapped on to a polygon by setting a texture object and a texture coordinate object to the polygon. The trick is how to calculate the texture coordinate corresponding to a vertex. It is actually very simple -- just remember that the texture coordinate ranges from 0 to 1. The following figure illustrates how to wrap a map to a globe. Note that (lon1+180) is actually (lon1-(-180)).
The global coordinate system is not convenient for scientific plot because data must be scaled properly to fit the coordinate ranges. The objects of plot, axis, and colorbar help to leverage the inconvenience.
Initially, x-, y-, and z-axis of plot is aligned with axises of the global coordinate system. The xaxis-, yaxis-, zaxis- functions are for arranging them in conventional positions.
Vertex data of objects added to plot object should be within the ranges of plot axises so that the plot object can resize objects to fit them in the plotting area properly. You may enable clipping of plot to remove objects outside axis ranges.
When a shape is intended as a symbol, e.g., a cubic box in a 3D plot, you usually want to use the plot coordinate system for its position, but want to conserve its size. In such a case, the symbol should be anchored in the plot.
Many ZeGraph objects are subject to transformations, of which rotation probably is the most difficult one for people with little experience of 3D graphics. Remember these two rules of ZeGraph: (1) transformations are conducted in reference to the global coordinate; and (2) the sequence of calling transformation functions of an object determines the sequence of transformations in rendering. For example, these code
node.rotatez(30); node.rotatex(-60);
will make the node rotate about the global z-axis for 30 degrees and then about the global x-axis for -60 degrees.
For a 3D plot, it is often necessary to rotate the plot coordinate system to have appropriate view and to move plot axises off the center of the global coordinate system, as shown in the following figures .
