Contact: zegraph  @      Last update: January 2020

ZeGraph Concept

Scene Structure

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 zegraph object, create a scene object and add it to the zegraph, 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 zegraph (also called render) object in a plot determines the image size and the background color, A zegraph may have multiple scene objects. This is equivalent to multiple sub-plots in a single plot page of other software.

A object determines the plotting area and the 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 scene and root node object are automatically added to a zegraph object when it is created.

A node object may contain any number of any objects except for render and scene types. If a 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. 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 is 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 normals produces correct shading effect.

A vertex object contains the x-y-z coordinates of a shape; 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. 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)).

Scientific Plot

The global coordinate system is not convenient for scientific plot because data must be scaled properly to fit the coordinate ranges. The objects of zeplot and axis help to leverage the inconvenience.

Initially, x-, y-, and z-axis of zeplot is aligned with axises of the global coordinate system. The xaxis-, yaxis-, zaxis- functions can be used to arrange them in conventional positions.

Vertex data of objects added to zeplot object should be within the ranges of zeplot axises so that the plot object can resize objects to fit them in the plotting area properly. You may enable the clipping property of zeplot to remove objects outside its 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 a 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


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 an appropriate view and to move plot axises off the center of the global coordinate system, as shown in the following figures .