Zhu3D Help
Overview
With Zhu3D you interactively can view and animate functions and isosurfaces as well as an independent parametric system. The OpenGL-viewer supports
zooming, rotating and translating as well as filed lightning or surface properties. Special effects are morphing, transparency, textures, fog and motion
blur. Numerical solutions of equation systems are found with a fast and precise "Adaptive Random Search"-algorithm.
Content
Configuration
When you first start Zhu3D the layout is optimized for a screen-resolution of 1024x768. These effort is done, because a lot of people are using notebooks
or TFT's where this is default. The window-sizes, their position, the icons in the tool bar or the font are configurable to your needs however.
All current settings are automatically default - as long as you change anything again. The font and the icons are changed with "Settings/General". If you
want an individual start up-screen or benchmark, overwrite the system-files "startup.zhu" and "benchmark.zhu".
The language choosen for the menus and the help file depends on what Zhu3D finds when starting. If it finds localized versions fitting to your system
settings, it will automatically use them. If not, it will use English until you change your language settings. English is short and concise, what may
support the usage of for smaller screens.
When Zhu3D was installed from a distribution package (RPM, APT, ..) instead of compiling by yourself, you may miss write permissions for the default work-
and textures directories. Copy these to a suitable place and then reset both default directories within the menu "Settings/Directories". This is needed
too, when you have updated to a newer Zhu3D-version. It is suggested to control these directories after each installation.
Content
Important hints
Of central importance is the colored button in the lower left side. With this you can switch between functions, isosurfaces and the parametric system.
Scaling and other operations refer to the current mode respectively. All impossible or dull actions are automatically blinded out to minimize operating
errors.
Due to screen size limitations some widgets or sliders have abbreviated names or are seemingly "nameless". But things follow usual conventions: Direction
sliders are named XYZ from left to the right. For lights or surfaces you have the same for RGBA. This token stands for red, green and blue light-shares and
the alpha-channel. Consider that every widget and every slider has a tool tip that explains the details!
Content
OpenGL-basics
For newcomers who are not intimate with computer graphics: The by far most important light/surface-property is the diffuse portion, followed by the ambient
share. With these two settings you can handle the most common tasks.
Content
Animation and morphing
Internally Zhu3D does not distinguish between the static and the animation mode. All settings and interactions can be applied in both modes without any
differences. Controlling animation is done via "Editors/Animation". Under Linux the GPU/CPU-utilization reacts smooth as silk and therefore is quite
accurate. In the animation editor the progress bar reflects the GPU-utilization mainly. The morphing editor mainly indicates the CPU-utilization
however.
As well as animation morphing works transparently throughout all modes. What does morphing mean in mathematical terms? A "morph-value" is automatically
changed within user-determined limits. For isosurfaces this concretely means that the iso-value is changed. For explicit functions it is the z-value, what
leads to pumping effects in the z-direction. Parametrically systems change their z-value too, but here this leads to an automatic zoom effect.
Content
Benchmark
The benchmark runs for five seconds independent from your system. To make results comparable, all widgets are blinded out and the window-properties of the
graphics are fixed. After returning, the original state is restored automatically.
Content
Mouse handling
After a click on the viewer-window, you can use the mouse in the following ways:
- rotate the view with the left button
- move the measuring-cross with the right button
- the middle button (up/down-movement) zooms (in/out)
- both the left and right buttons translate in all directions
Content
Saving files
Saving files backs up the actual state of Zhu3D completely. When animation is turned on, its properties are stored too. Loading such a file will replay the
animation with the stored speed - at least when the computer is fast enough. The file-format is transparent: You can inspect or alter it with any
text-editor. When you do not enter a specific file extension (like .zhu, .jpg or .png), the program automatically chooses the correct one depending on the
current situation.
Content
Saving/printing pictures
The parameters are determined in "Settings/Picture". Provided that your system supports this, you can save pictures in the formats PNG, JPG, PDF or
PostScript. More settings are the picture dimension and its quality. The snapshot is initiated with "File/Save picture". The render-process may need quite
a while, especially with bigger pictures and missing hardware power. For printing the size setting is relevant only.
For PNG and JPG a quality factor of 85 is a good compromise, which is default therefore. Values from 90 to 100 will mostly blow up file sizes for no good
reason. After rendering and when re-locking the XY-values, Zhu3D resets the latter to the dimensions of the viewer-window automatically. Doing so the
proportions between height and width are preserved.
Content
Solving equations
For numerical solving of an equation system you must provide Zhu3D with a plausible starting-point for its internal calculations. This is done by moving
the measuring cross "relatively near" to a possible solution. Then click on the solver-button in the tool bar. Shortly after that you will get a detailed
solver-report. When the solution is reliable, the measuring cross will be moved to it.
In difficult cases finding a starting point can be eased when you:
- use contrasting surfaces for the functions
- scale the XY-values as needed and then scale down Z sharply
Doing so you will get a flat view of your functions, where you can find possible solutions with a glance. Beside "solver.zhu" you will find further
examples in the work-directory, which have simple solutions. When you are in parametric- or iso-mode, solving makes no sense and therefore is disabled
automatically.
The precision for solving is specified in "Settings/General" and can be up to 15 digits. If the solver fails continuously, reduce the number of
digits.
Content
Transparency
The light- and the material-editor consequently provide a slider for alpha-channel. Normally the alpha-values do not affect the view and therefore are set
to 255 by default. The exception is the view of transparent graphs. To control this effect, open the surface editor and change the alpha-values of the
diffuse light.
When the 2-sided mode is turned on globally, be aware that you may have to change the front side as well as the backside values to see an effect. To keep
things simple, you may change to the one-sided mode in the global light-editor.
Content
Special effects
Textures reside in the ./work/textures directory by default and could have one of the following formats: PNG, JPG, TIF, BMP, XBM, XPM, PPM, PBM or PGM. The
width/height dimensions must be a power of two each. You can flip textures vertically, what may be needed when viewing backgrounds or parametric systems,
where the forefront and the reverse side may switch. Currently textures are not saved within Zhu3D-files. If a file with a texture is loaded, the program
tries to find it in the default textures-directory.
Fog can be used when a graph is too bright or looks too much like a perfect computer graphic. The modes "Exp" and "Exp2" are straight forward to use, but
the "Linear" mode shows much more elaborate results. With the start/stop sliders you can define the position, density and the course of the fog very
exactly. Very helpful is the "Sync" button in the colour section. It synchronizes the fog colour with the background colour, what shows the best results
normally.
In motion blur the sliders are partially influencing each other. The more iterations are calculated, the higher can be the magnitude of the blur effect,
before the graph is getting too dark. The offset per iteration reacts independent from the former two setting.
Content
Light sources
Zhu3D has up to eight independent light sources. The initial position of the sources are the edges of the "normal-cube". The lights 0-3 you can imagine as
foreground-lights, 4-7 as background-lights. The settings should be mostly obvious and are done via "Editors/Lights".
Somehow tricky maybe the spotlight, which is depending on several factors. "Catching" this sort of light may be eased: At the beginning set the
spotlight-angle and the intensity to their maximum. Then reduce the angle slowly and try to find the raw position with the direction-sliders. After that
you can fine tune the spotlight-angle, its intensity and its position. The spotlight-setting are dependent on the general distance-slider too of course,
which determines the distance from the origin. Have a look at the example "spotlight.zhu", where the complex contexts will be visible quickly.
Within the global light the setting "Infinite" is mentionable, which moves the light sources to infinity. In this mode you can not use spotlights, the
distance-slider and the attenuation. Therefore these are turned off automatically. The mode may be useful for viewing flat graphs. If a graph is to dark,
the global ambient light is quick way to brighten it.
Content
Surface properties
Most things should be obvious. The only pitfall may be the specular light section, which is responsible for the shininess properties of the
function-surfaces. To see an effect, at least one light source must emit some sort of specular light of course!
Normally Zhu3D stores all the settings of the surface editor. When you switch your global settings from 2-sided surfaces to 1-sided ones, the editor
switches rigorous to foreground-properties however.
Content
Tips on scaling/viewing
Scaling X and Y up or down will scale each of these axes individually. Using the A(ll)-button, all axes are scaled to the same length automatically for
avoiding strains. When your graph exceeds the clipping range, scale down the Z-values sharply. The same holds true, when tessellation fails because of
border areas. Keep in mind: As your screen is two-dimensional, rotation around the Z-axis can be reached only with the corresponding Z-slider of
course.
Settings of Triangle/Quad-tessellation and the resolution of the grid will influence the viewing too. Scaling accuracy/speed is determined with the
"Settings/Scale" menu.
HINT: For quick scaling press down the mouse button instead of clicking the buttons continually.
Content
Function editor and the parser
Finish editing a new function with <Return>. If the parser finds syntax errors, you will get feedback. The input tolerates blanks and is not case
sensitive. The parser recognizes the following functions, operators and constants:
+, -, *, /, %, ^, sin(), cos(), tan(), asin(), acos(), atan(), sinh(), cosh(), tanh(), asinh(), acosh(), atanh(), cot(), csc(), sec(), int(), frac(),
floor(), ceil(), mod(a,b), exp(), pow(a,b), log(), log2(), log10(), sqrt(), abs(), sig(), rnd(interval), gamma(), min(a,b), max(a,b), $pi (=3,14..), $e
(=2,71..), $c (=299792458 m/s). A comment starts with #.
Special operators are if(a,b,c), &, |, ! <, >, <=, >= and the recursion function eval(...). The condition if(a,b,c) can be read as "If
condition a fulfilled, then expression b else expression c". The boolean operators and, or, negate (&, |, !) can be used to formulate complexer
if-conditions. Examples for conditions, special operators and recursions can be found in the "work"-directory.
In some areas Zhu3D relaxes the error handling slightly. You may view functions like sqrt(x) or 1/x without getting messages like "Negative root" or "Zero
division". In cases of doubt use syntactically correct expressions like sqrt(abs(x)) for instance.
The editor supports the clipboard functions copy, cut and paste as well as undo/redo.
Content
User defined items
To create your own functions and constants, open the menu "Editors/User defined". With this you get a simple spreadsheet, where you can enter your own
definitions. Items must have an equal sign and a unique name. Functions with the same name, but a different amount of parameters are not valid! Be careful,
when making your definitions. As they can be nested or even be recursive, it is strongly recommended to enter them in a sense-full and linear manner from
row 1 onwards. With a right mouse-click you quickly can delete blank and commentary-rows respectively insert blank rows.
HINT: Take a look at the "usrdef" example files, where you find a lot of instances ranging from simple to complex definitions.
Content
Implicit functions and isosurfaces
These have the common form 0=f(x,y,z) while for "normal" functions z=f(x,y) is valid. Implicit functions have some advantages opposite to normal functions
and parametric systems. Complex functions can be represented more straightforward for example. Implicit functions describe a three-dimensional scalar field
and create a so called isosurface. For viewing these isosurfaces Zhu3D uses different volume based algorithms. You can choose them in the menu
"Settings/General".
HINT: Denser grids may need a very long computing time.
Content
Parametric system
Especially obvious is the change of meaning. Instead of three independent functions in x and y you work with a single system with the parameters s and t,
whose values are determined by the function X(s,t), Y(s,t) and Z(s,t). The scaling receives a change of meaning too. Instead of rescaling x-values for
instance, you are doing so for the the function X(s,t) now.
The standard interval for s and t is [-1, 1], which you change by scaling X and Y. Within a parametric system you may have an infinite amount of
Z(s,t)-values, which you can imagine as pendant to the conventional Z-values. So foreground and background may merge into each other or the may even
overlap ambiguously. To avoid erroneous tessellation, reduce the scaling of X and/or Y to the necessary minimum. The A(ll)-scaling button relates to the
entire size of your graph.
Examples like the Moebius strip "moebis.zhu" will demonstrate the contexts. If you want to inspect curves, you have to switch to the point-mode. A
regarding example is "curve.zhu".
Content
Legends editor
The first three entries are reserved for xyz-labels of the axes, all others for general labels. The difference is, that the xyz-labels are shown
perspectively, the others are static however. For simplicity changing the colour of a single xyz-label changes the colours for the others and the axes
too.
Entries in the column "Size" can be double-clicked, so you can change font sizes without any keybord interaction. Click the "Lock mouse" button to move an
entry with the mouse quickly. This action, as well all others, refers to the actual row selected. For convenience you can unlock the mouse with a
right-click in the viewer too.
Content
Shortcuts
The program implements some more shortcuts in the form <Ctrl-Letter>. Independent from localization U,D,L,R,+,- are available. These letters stand
for Up, Down, Left, Right, zoom in and zoom out.
Content
Who is Zhu?
Zhu3D was named after the Chinese mathematician Zhu Shijie. Around 1300 AC he was the very first to solve a complex non-linear equation-system in a modern
way. Of course you will find Zhu's historic masterpiece in your work-directory. It's file-name is "zhu.zhu".
One remark: Shijie missed to specify the second non-trivial solution because of its negative signs. The reason for that was a limited imagination of the
numbers room, which was finally overcomed foremost hundreds of years later. With Zhu3D you can find this second solution at a glance:-)
Not very spectacular - at least from an optical point of view - is "ninebooks.zhu". This historic example is from the great "Nine Books", a mathematical
milestone published in China around 200 BC. The old folks solved this linear system with a similar algorithm, the famous mathematician Carl Friedrich Gauss
reinvented some 2000 years later.
In comparison you can study "diophant.zhu", a system that was published in the Greek textbook "Arithmetica" not before 450 years after the "Nine Books".
The solution of this simple system without coefficients was found by the well known mathematician Diophant.
Content

