# Surface Evolver Documentation

Back to top of Surface Evolver documentation. Index.

# Surface Evolver graphics

## Contents

- Overview
- Screen graphics.
- OpenGL graphics.
- Geomview graphics.
- Graphics prompt commands.
- View matrix.
- Multiple view transforms.
- Picking elements with the mouse.
- Clip view - see inside your surface!
- Slice view - 2D section of 3D surface.
- PostScript output - for publications, movie frames, web site images, etc.
- Other graphics related features.

## 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, built-in Evolver graphics of various qualities on various platforms,
- Interface to the Geomview 3D viewer, for Unix/Linux users without OpenGL/GLUT graphics compiled into Evolver,
- PostScript files, for everybody wanting to make 2D images for publications, web sites, etc.

## 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:

- `s` for starting screen graphics and entering graphics command mode
- `D` or `autodisplay` for toggling automatic redraw when the surface changes. Default is automatic redraw.
- `close_show` for ending 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:

- `geomview` or `P 8` to start geomview
- `P 9` to end geomview
- `geompipe` to pipe geomview input someplace else
- `geomview` string to send user commands to geomview
- `gv_binary` toggle to control interface mode
- `view_4D` to toggle sending 3D or 4D info to geomview
- D or autodisplay for toggling automatic redraw when the surface changes. Default is automatic redraw when geomview is started.

## 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:

- edge color
- facet color, frontcolor, and backcolor
- edge show expression
- facet show expression
- facet shading toggle
- facet brightness
- facet_colors toggle
- view matrix
- view transform expression
- transforms toggle
- torus model display mode: raw_cells, clipped, or connected
- surface thickness
- show_inner and show_outer toggles
- background color
- window_aspect_ratio variable

Datafile features that are relevant to graphics are:

- edge color
- facet color, frontcolor, and backcolor
- view transforms
- view transform generators
- viewing matrix

Main prompt commands that are relevant to all graphics are:

- `show`, `showq`, and `show_expr` for controlling which elements are displayed.
- `set edge color`
- `set facet color, frontcolor, backcolor`
- `transforms` toggle
- `transform_expr`
- `thickness`
- torus model display mode toggles: `raw_cells`, `clipped`, or `connected`
- `show_inner` and `show_outer` toggles
- `display_text`
- `delete_text`
- detorus

Back to top of Surface Evolver documentation. Index.