Surface Evolver Documentation

Back to top of Surface Evolver documentation.       Index.

Surface Evolver graphics

Contents

Overview

Surface Evolver graphics consists of drawing edges and facets. There is a single graphics driver routine which produces colored edges and facets in 3D and sends them to a set of display routines. There are three main sets of display routines:

Native screen graphics

The Surface Evolver has the ability to produce its own screen graphics directly. The Windows version has nice OpenGL/GLUT graphics, which should also be available on any Unix/Linux/Mac OSX system. The Mac OS 9 version has some simple graphics, and there is a primitive X-windows graphics module for Unix/Linux systems that for some reason can't do OpenGL. Those compiling unix versions must link in the appropriate graphics module.

Screen graphics appear in their own window but can be controlled by typing graphics commands at the "graphics command: " prompt in the main window. OpenGL graphics can also be controlled by mouse and keyboard actions in the graphics window.

Main prompt commands relevant to screen graphics:

The native screen graphics view is controlled by a view transformation matrix, which may be specified in the datafile, and which is dumped by the d or list topinfo commands. The view matrix may be changed with graphics mode commands. The view matrix elements may be read or set at runtime by view_matrix[i][j], where the indices start at 1. In particular, one can write command scripts to save and reload particular view matrices; see saveview.cmd in the distribution package. The view matrix does not affect geomview.

The display consists entirely of facets and edges. Special edges (fixed edges, boundary edges, constraint edges, triple edges, bare edges) are always shown, unless you make their color CLEAR. The individual facet edges can be toggled with the graphics mode command `e'.

Graphics mode commands

When the native graphics display is invoked by the 's' command or the various `show' commands, the Evolver enters graphics mode, with the prompt `Graphics command: '. A graphics command is a string of letters followed by RETURN. Each letter causes an action. Some commands may be preceded by an integer count of how many repetitions to do. Example command: 15u2z, which does 'u' 15 times and 'z' twice. Rotation commands may be preceded by a real number giving the degrees of rotation; an integer will give a repetition count with the default angle of 6 degrees. A real number is indicated by including a decimal point.

Repeatable commands:

u Graphics mode command. Tip up. Rotates image about horizontal axis, default 6 degrees. Example: `15u' does 90 degree rotation, `15.0u' does 15 degree rotation.
d Graphics mode command. Tip down. Rotates image other way, default 6 degrees. Example: `15d' does 90 degree rotation, `15.0d' does 15 degree rotation.
r Graphics mode command. Rotate right. Rotates about vertical axis, default 6 degrees. Example: `15r' does 90 degree rotation, `15.0r' does 15 degree rotation.
l Graphics mode command. Rotate left. Rotates about vertical axis, default 6 degrees. Example: `15l' does 90 degree rotation, `15.0l' does 15 degree rotation.
c Graphics mode command. Rotate clockwise about center of screen, default 6 degrees. Example: `15c' does 90 degree rotation, `15.0c' does 15 degree rotation.
C Graphics mode command. Rotate counterclockwise about center of screen, default 6 degrees. Example: `15C' does 90 degree rotation, `15.0C' does 15 degree rotation.
z Graphics mode command. Zoom. Expands image by factor, default 1.2. Examples: `z' zooms by 1.2, `2z' zooms by 1.44, '2.0z' zooms by 2.
s Graphics mode command. Shrink. Contracts image by factor, default 1.2.
arrow keys Graphics mode command. Move image in appropriate direction. May be prefixed by a real number, which is multiple of thirds of screen width to move. Default move is 1/12 screen width. May not work on all terminals.

Non-repeatable commands:

R Graphics mode command. Reset viewing angles to original defaults and rescale the image to fit the viewing window.
m Graphics mode command. Center image in viewing window.
e Graphics mode command. Toggle showing all the facet edges.
h Graphics mode command. Toggle hiding hidden surfaces. When ON, takes longer to display images, but looks better.
b Graphics mode command. Toggles display of bounding box. Useful for visualizing orientation. In the native graphics window, the 'o' key does the same thing. The color of the bounding box can be changed by setting the bounding_box_color variable.
t Graphics mode command. Reset mode of displaying torus model. Choice of raw unit cell, clipped unit cell, or connected bodies.
w Graphics mode command. Toggles display of facets entirely on constraints. For a one-sided constraint, applies to facets whose vertices all hit the constraint. "w" stands for "wall".
B Graphics mode command. Toggles display of facets on boundaries or equality constraints.
v Graphics mode command. Toggles showing of convex and concave edges in different colors. "v" stands for "valleys".
+ Graphics mode command. Increments color number used for facet edges.
- Graphics mode command. Decrements color number used for facet edges.
? Graphics mode command. Prints help screen for graphics commands.
q,x Graphics mode command. Exit from graphics mode, and return to main command mode.

OpenGL graphics

Ideally, you have a version of the Evolver that uses OpenGL/GLUT for its screen graphics. OpenGL is standard on Mac OSX, most unix systems, and Microsoft Windows. Tbe graphics display is invoked with the 's' main prompt command, which leaves you at the graphics prompt, which you should quit 'q' right away since graphics commands are better given in the graphics window. Or you can use the `showq' command, which automatically returns to the main prompt.

Left mouse button:

Dragging the mouse with the left mouse button down moves the surface in various ways. The mode of the left button can be changed by hitting the keys t (translate), r (rotate), z (zoom), or c (clockwise spin). Default is r mode.

Right mouse button:

By default, the right button does picking of vertices, edges, and facets. If you hit the `M' key in the graphics window, the right button brings down a graphics window menu.

Graphics window key commands:

h Print a help screen on the console window.
r Rotate mode for left mouse button.
t Translate mode for left mouse button.
z Zoom mode for left mouse button (and use F to focus on particular vertex).
c Clockwise/counterclockwise spin mode for left mouse button.
+ Widen edges.
- Narrow edges.
b Decrement edge front bias by .001.
B Increment edge front bias by .001 (to show edges more clearly).
R Reset the view.
m Center the image.
M Have the right mouse button bring up a menu instead of picking.
P Have the right mouse button do picking instead of menu (default).
p Toggle orthogonal/perspective projection.
s Toggle cross-eyed stereo.
e Toggle showing edges, regardless of "show edge" condition.
f Toggle showing facets obeying "show facet" condition or no facets.
F Move the rotate/zoom origin to the last picked vertex.
G Start another graphics window with independent camera.
o Toggle drawing a bounding box.
g Toggle Gourard (smooth) shading.
l Enable clipping plane in translation mode.
L Disable clipping plane.
k Enable clipping plane in rotation mode.
x Close the graphics window.
arrow keys Translate a bit.
And some more advanced commands most users will never use, but are listed here for completeness:
H Print advanced help.
a Toggle using OpenGL element arrays.
i Toggle interleaved elements in OpenGL arrays.
I Toggle indexed OpenGL arrays.
S Toggle OpenGL triangle strips.
Y Toggle strip coloring (I was curious as to what OpenGL triangle strips would look like). Original colors are restored when toggled off. Implicitly invokes 'S'
D Toggle using a display list.
Q Toggle printing drawing statistics.

Geomview graphics

Excellent screen graphics on Unix systems can be done through the free 3D viewing program geomview. Geomview can be started with the P command, option 8. One caution: geomview does not deal well with object sizes below 1e-5, so displaying micron-size objects using MKS units is ill-advised.

Main prompt commands relevant to geomview:

The View Matrix

The mapping of coordinates from ambient space to the graphics display is done by a matrix called the view matrix. The matrix uses homogeneous coordinates, thus is a square matrix whose size is one larger than the dimension of the ambient space. The view matrix can be initialized in the top of the datafile, or its elements may be read or set at runtime by view_matrix[i][j], where the indices start at 1. In particular, one can write command scripts to save and reload particular view matrices; see saveview.cmd in the distribution package. The view matrix is saved in dump files.

The file saveview.cmd in the fe subdirectory of the Evolver distribution package has a script saveview which writes out the current values of the view matrix in a format that can be read back in to restore a view. Example: 

   Enter command: read "saveview.cmd"
   Enter command: saveview >>> "thisview.cmd"
   ...
   Enter command: read "thisview.cmd"

Multiple view transforms.

Evolver can display multiple transformations of a surface simultaneously, for all of the possible graphics displays. Each transform is defined by a matrix in homogeneous coordinates, which for a 3D surface means 4x4 matrix which has a 3x3 rotation matrix in the upper left, a translation vector in the last column, and a row (0,0,0,1) on the bottom. There are two ways to specify the transform matrices:
  1. List each matrix individually in the datafile; see view_transforms.
  2. List a set of transforms in the datafile (see view_transform_generators) and use the transform_expr command at run time to generate a set of transforms. I much prefer the second way.
The final list of transforms may be accessed by the matrix view_transforms[][][]. Because some transformations may reverse the front and back sides of surfaces, transforms can be made to swap frontcolor and backcolor attributes of facets; see view_transforms or view_transform_generators) for syntax. The read-only array view_transform_swap_colors[] has a 1 entry for the transforms that do swap

Transforms may be turned into actual copies of the surface with the detorus command.

Picking elements.

One of the big advantages of using geomview or the OpenGL version is that you can pick vertices, edges, and facets in the geomview window by right-mouse-clicking, and the id numbers of the picked objects will be printed in the main window. Be careful when picking; it does not always work as you might hope. It may be necessary to zoom in on the surface to get a clear shot at the element you want.

Picked vertex, edge, and facet numbers are stored in the internal variables pickvnum, pickenum, and pickfnum, respectively. The 'F' key command on the graphics window sets the rotation and scaling center to the pickvnum vertex. Pickvnum is settable with ordinary assignment commands, so the user can zoom in on any vertex desired.

Be wary that pick output can confuse things a bit in the command window, particularly if you partially type a command, then pick, then try to complete the command.

Clip view of surface

It is possible to have the graphics display clip the surface with multiple clipping planes. A clipping plane is defined by a plane of the form ax + by + cz = d. The visible volume is ax + by + cz <= d. Up to 10 clipping planes may be stored in the array clip_coeff[][], with the first plane coefficientsa,b,c,d stored in clip_coeff[1][1] through clip_coeff[1][4], etc. The user does not have to create clip_coeff[][]. To use clip view, first set the coefficients of however many clip planes you want and then use the clip_view toggle. For example, to get a vertical clipping plane parallel to the y and z axes and a little in front of them: 
   clip_coeff[1][1] := 1;
   clip_coeff[1][2] := 0;
   clip_coeff[1][3] := 0;
   clip_coeff[1][4] := .2;
   clip_view;
With OpenGL graphics, the first clip plane plane can be varied interactively by hitting the 'l' key (lower case L) in the graphics window and dragging the mouse horizontally. The 'k' key will make mouse dragging change the orientation of the clip plane. Hit 'r' or 'c' or 't' to get back to another mouse mode. 'L' will turn off clip_view.

Clip view works separately, and after, torus model viewing modes such as clipped and connected, so it is no problem to have them together.

In case clip_view and slice_view are both in effect, slice_view operates instead of clip_view.

Slice view of surface

It is possible to plot a cross-sectional slice of a surface. The slice is defined by a plane of the form ax + by + cz = d. The coefficients a,b,c,d are stored in the array slice_coeff[] (which the user does not have to create). To use slice view, first set the coefficients and then use the slice_view toggle. For example, to get a vertical slice parallel to the x and y axes and a little in front of them: 
   slice_coeff[1] := 1;
   slice_coeff[2] := 0;
   slice_coeff[3] := 0;
   slice_coeff[4] ;= .2;
   slice_view;
The cross-section will be in the form of line segments of the same color as the facets they are sections of. With OpenGL graphics, the slice plane can be varied interactively by hitting the 'l' key (lower case 'L') in the graphics window and dragging the mouse horizontally. The 'k' key will make mouse dragging change the orientation of the clip plane. Hit 'r' or 'c' or 't' to get back to another mouse mode. 'L' will turn off slice_view.

Slice view works separately, and after, torus model viewing modes such as clipped and connected, so it is no problem to have them together.

In case slice_view and clip_view are both in effect, slice_view operates instead of clip_view.

PostScript files

The Surface Evolver can generate PostScript files by either the postscript command or the P command option 3, or just "P 3". The image is the same one shown with the native screen graphics, so one should use the s command and graphics mode commands to get the image looking as desired. The variable brightness can be used to set the median gray level. The PostScript image is put into an 8 inch square at the lower left of the page.

With the P command, you will be prompted for options.

Show grid lines?
This is asked if you are graphing a 2D surface. If you reply 'y', all triangle edges will be plotted. If 'n', only special edges will be plotted (triple junctions, borders, etc.; this can be controlled with the show edges command). Default 'n'. The postscript command uses the ps_gridflag toggle to control this.
Do colors?
If you reply 'y', edges and facets will be plotted with their color attributes and shading (if activated). If 'n', then all edges are plotted as black, and all facets as white with shading. Default 'n'. The postscript command uses the ps_colorflag toggle to control this.
Do crossings?
This is asked if the surface is 1-dimensional (the string model) and the dimension of space is at least 3. If you reply 'y', a 3D effect will be created by plotting edges back to front, with each edge plotted first as a thick white line and then as a thin black line. This creates a broken back line and continuous foreground line at each crossing. Default 'n'. The postscript command uses the ps_crossingflag toggle to control this.
Do labels? (i for ids, o for originals)
This PostScript P 3 command subprompt gives you a chance to put numeric labels on vertices, edges, and facets, which is useful for debugging or modifying a datafile. Edge labels are slightly displaced toward the head of the edge, and facet labels are signed according to which side of the facet is visible. Choose 'i' or 'y' for the current element id, or 'o' for the original element number. If you don't want any labels, just hit RETURN. The postscript command uses the ps_labelflag toggle to control this. The relative size of the labels can be controlled with the ps_labelsize variable, whose default value is 3.0.
Enter file name (.ps will be added):
Give the name of the PostScript output file. A ".ps" extension will be added if ".ps" or ".eps" is missing. Not a good idea to just hit RETURN, since that will produce the file ".ps".
The linewidth of PostScript edges may be controlled by the user. Widths are relative to the image size, which is 3 units square. If the real-valued edge extra attribute ps_linewidth is defined, that value is used as the edge width. Otherwise some internal read-write variables are consulted for various types of edges, in order:
ps_stringwidth - edges in the string model, default 0.002
ps_bareedgewidth - "bare" edges, no adjacent facets, default 0.0025
ps_fixededgewidth - "fixed" edges, default 0.002
ps_conedgewidth - edges on constraints or boundaries, default 0.002
ps_tripleedgewidth - edges with three or more adjacent facets, default 0.0015
ps_gridedgewidth - other edges, default 0.001

The bounding box listed in the PostScript file is normally the actual extent of the surface in the window (i.e. the bounding box is never bigger than the window, but may be smaller). The full_bounding_box toggle will force the bounding box to be the full window. This is useful in controlling the image size while making a series of images of different views or evolution stages of a surface. The color of the bounding box can be changed by setting the bounding_box_color variable.

Visibility testing. PostScript files of complicated surfaces may contain a high proportion of facets not visible in the final image. This takes much extra file space and rendering time. There is an option to process the list of PostScript facets to eliminate the non-visible facets, the visibility_test option command. For my own debugging purposes, there is a visibility_debug toggle, which causes printing of verbose information; don't use it.

Other graphics related features.

This section has links to other topics you should consult.

Internal Evolver state information relevant to graphics:

Datafile features that are relevant to graphics are: Main prompt commands that are relevant to all graphics are:
Back to top of Surface Evolver documentation.       Index.