QMG 1.1 Graphics
Graphics are used in QMG to display breps, simplicial complexes, and PDE solutions (the latter in Matlab only). Three-dimensional graphics in QMG are currently done with VRML or Matlab.

Colors in QMG

The routines for displaying breps all examine the "color" property-value pair of the brep faces. The property name is color. The value of this property should be a quadruple of the form <r g b a> where each of r, g, b, a is a decimal number between 0 and 1. (Note: the angle brackets are part of the syntax.)

The numbers r, g, b stand for red, green and blue and are the amount of that color present in the face. For instance, r=1, g=0, b=0 is pure red, whereas r=1, g=1, b=0 is yellow.

The parameter a is sometimes called "alpha" and is the degree of opacity. Thus, a=1 means the face is completely opaque and a=0 means the face is completely transparent. Somewhere in between 0 and 1 means the face is partially transparent.

Not all the graphics engines support transparency, so you may find that modifying this parameter strictly between 0 and 1 does not yield the desired result. However, it is guaranteed that a=0 will yield a completely transparent (invisible) face for any graphics engine and a=1 will yield a completely opaque face.

Having a color that stands for invisible is very useful for 3D breps, because the only way to see internal boundaries or completely interior holes is to make some exterior faces invisible.

The graphics routines are as follows.

gmrndcolor (Matlab & Tcl/Tk)

Matlab: newbrep=gmrndcolor(brep {, dim});
Tcl/Tk: gmset newbrep [gmrndcolor $brep {$dim }]
This routine produces a new brep that is the same as the old brep, except that all faces of dimension dim are colored according to a random ordering of about 20 pre-designated colors. (Just like gm_addpropval, this routine does not change its calling argument and therefore is useless without a return variable.)

The dim argument is optional; if it is not specified, then it defaults to the embedded dimension of the brep minus 1, or the intrinsic dimension, whichever is smaller.

If a face is already colored (i.e., it has a property "color" attached to it), then gmrndcolor leaves it with the color that it has.

gmviz (Matlab & Tcl/Tk)

Matlab: gmviz(obj {, colorspec, {dim {,tol}}});
Tcl/Tk: gmviz $obj {$colorspec {$dim {$tol}}}
This routine displays a brep or simplicial complex. The display is controlled by gmvizgui.

The user can control which dimension or dimensions of object to display. For instance, if the third argument is '1', this means to show the 1-dimensional faces (the edges) of the brep or simplicial complex. The third argument can also be a vector (a list in Tcl/Tk) if the user wants to display several dimensions of the object at once. If the user omits the third argument, the default is min(d-1,k) where d is the embedded dimension and k is the intrinsic dimension.

The second argument is the color to use. There must be one color per dimension; in other words, the second and third arguments to gmviz are in correspondence. For example, in Matlab, the call

gmviz(b, 'rw', [1, 2])
will render the 1- and 2-dimensional faces of b (edges and facets). The edges will be colored red and the facets will be colored white. The equivalent in Tcl/Tk is:
gmviz $b {red white} {1 2}

As mentioned above, the second argument is one or more colors, in correspondence with the dimensions. For a brep, the color specified in the gmviz call is overridden by the property-value pair color assigned to the faces. (No such option exists for simplicial complexes since they do not have property-value pairs.) If no color is specified, the default is obtained from gmvizgui.

In Matlab, there are two ways to specify color to the gmviz command. A color can either be a one-character string y, m, c, r, g, b, w, k or i standing for yellow, magenta, cyan, red, green, blue, white, black and invisible. Several such colors (one for each dimension) are concatenated together into a string as in the above example.

A color in matlab can also be specified as a matrix with four entries per row; each row is an r, g, b, a encoding as described above. The number of rows is in correspondence to the number of dimensions specified in the third argument.

In Tcl/Tk, a color can be any valid X11 color name such as "green". It can also be a four-tuple of numbers. The Tcl/Tk color-name processor looks up color names in rgb.txt. You may have to set an environment variable to tell QMG where to find rgb.txt. The readme_XXX file shipped with QMG explains this installation procedure.

The routine gmviz invokes the lower level C++ routine gm_viz, which is more general but harder to use. The arguments to gmviz are as follows. The first six arguments are the engine type, the file name, the file status (write or append), the notification option, a bounding box for the object, and a format. The file name, file status, notification and format options are meaningful only for external graphics engines. The remaining arguments are triples; each triple is a simplicial complex, a matrix of colors (the matrix has one row per simplex, and four entries per row), and the amount to "thicken" the object when plotting it.

Thus, the low level routine can plot only simplicial complexes. Therefore, gmviz is given a brep argument, it converts it to a simplicial complex using the meshgen generator gm_ldmeshgen.

Graphics engines and gmvizgui

The gm_viz routine, which is invoked by gmviz and gmplot, sends its data to a graphics engine. The selection of the engine, as well as its properties, are controlled with a graphical user interface; this interface is put up on the screen with the gmvizgui command.

Currently QMG supports two different graphics engine types, "internal" and "external". For Matlab, "internal" means a usual Matlab graphics window. For Tcl/Tk, "internal" means a Tk canvas object. The Matlab internal engine can plot in both two and three dimensions (although the 3-dimensional engine is somewhat buggy and unpleasant to use). The Tcl/Tk internal engine is for 2-dimensional objects only.

As for external engines, currently QMG supports only one, which is to write the graphics data to a file. Currently there is only one format supported for that file, which is VRML 1.0. For information about VRML, see the VRML repository. Currently the software supports automatic notification of Netscape Navigator in both Unix and Windows. "Automatic notification" means that gmviz or gmplot will cause Netscape Navigator to load the VRML image as soon as the data has written to the file in VRML format. To use notification, Netscape Navigator must running on your workstation (as a separate process) at the time the gmviz or gmplot statement is executed. You control automatic notification with buttons in in the GUI created by gmvizgui.

If you use the external engine, you can also select the file name to hold the VRML file with gmvizgui (default is test.wrl; always choose a file whose suffix is .wrl). You can also select whether that file is opened in replace-mode or append-mode. Opening the file in append mode means that successive gmplot statements will append their VRML at the end of the file, so that several different objects can appear at once in the viewer.

For Windows only, the software also supports automatic notification of Microsoft Internet Explorer. Note: the VRML add-in for Internet Explorer 3.0.1 available on the Microsoft download site seems to have a couple of glitches: (1) it won't reload a URL unless you first go to a different URL and back, and (2) it seems to soak up huge amounts of CPU time even when the object is not moving.

The notification is accomplished internally via gm_url. This routine notifies Netscape or IE to load the file using the DDE protocol under Windows. Under Unix, gm_url uses Netscape Navigator's remote control feature for automatic notification. If you have another browser that can load VRML and that supports remote control, you can customize gm_url to use your browser.

The rendering engines (both external and internal) support "thickening" options. Thickening a vertex means displaying it as a disk or sphere instead of a point. Thickening an edge means displaying it as a fat line or pipe instead of a segment. For facets you have a "push in" option, which means that that they get pushed slightly away from the outside of the object. This is useful in the case when you are plotting edges and facets at the same time. Pushing the facets in means that they won't hide the edges.

When generating VRML images, if you set the thickness of either vertices or lines to anything greater than zero, the size of the VRML file goes up substantially as does the delay in rendering the object. This is because vertices of width greater than 0 are plotted as individual spheres, whereas 0-width vertices are plotted as a point cloud. Similarly, edges of width 0 are rendered all together as an indexed line set in VRML, whereas edges of positive width are rendered individually as cylinders.

To control all of these properties, use the GUI gmvizgui. Note that when you change a setting in this GUI, it does not affect the current plot: new settings affect the next plot. If you close the GUI, then the last settings of the GUI stay in force, but as soon as you restart it again, all the settings go back to defaults. Do not start two different gmvizgui windows because they will get out of sync.

To try these features out, you can use the interactive script testviz by typing testviz in matlab or source $qmg_library2/testviz.tcl in Tcl/Tk.

The way gmvizgui works (in both Matlab and Tcl/Tk) is that the buttons are tied to global variables. Therefore, you can bypass gmvizgui completely by directly setting these global variables. Some of the test files shipped with QMG use this approach. If you change the global variables and the GUI is on the screen, then the GUI may become out of sync with the global variables. Therefore, if a script changes one of these global variables, then it should set it back to its original value upon completion.

If you are displaying a 2D object in Matlab's internal engine, the GUI provides you with six control buttons, which are as follows. `Zoom in' and `Zoom out' zoom in or out on the current center of the object. `Up', `Down', `Left', and `Right' move your viewpoint on the object.

If you are displaying a 3D object in Matlab's internal engine, the buttons `Up', `Down', `Left' and `Right' change your viewpoint as if you are sitting on the surface of a circumscribing sphere around the object.

The rendering of 3D objects unfortunately doesn't work well in Matlab. There are two things that go wrong:

Customizing internal engines

The internal engines in Tcl/Tk and Matlab are both implemented in the scripting language, and therefore are available for customization. (In particular, the sequence of invocations is as follows. The user invokes gmviz or gmplot. This in turn invokes the low-level C++ routine gm_viz. The routine gm_viz contacts the graphics engine. If the graphics engine is internal, then gm_viz invokes routines in the high-level language.)

The routines that control plotting for the internal engine are gm_vizi.m and gm_viz2_internal.tcl.

gmplot (Matlab only)

The gmplot routine displays a color picture of a 2D or surface 3D finite element solution. It is available only in Matlab. Its calling sequence is:
gmplot(scomplex, u {, solnrange {, cmap}});
where scomplex is the simplicial complex used for the finite element method, and u is the solution vector. The simplicial complex must have intrinsic dimension 2, and can have embedded dimension of either 2 or 3. The argument u is the value at each node of the simplicial complex that you want plotted. Thus, field should be a column vector with real-number entries whose number of entries is equal to the number of nodes in the simplicial complex. This is the form of the return variable from gmfem. But you can also use this function to show, for instance, the difference between two fem solutions.

In the case of 3D FEM solutions, you first have to restrict the mesh to the boundary elements with the gmboundary function. Then you have to restrict the FEM solution u to the subset of nodes in the new simplicial complex by subscripting the full FEM solution with the index-source vector returned by gmboundary. There are examples of this technique in the test cases.

The routine defaults to the current colormap, or a colormap may be explicitly specified (jet is recommended). The third argument is an optional 2-vector with upper and lower bounds on u; these bounds default to the min and max values of the vector u. If the third argument is given explicitly, this pins down the mapping from values of the field variable u to specific colors. This is useful if you are making several different plots for which you want the same absolute color scale.

Routine gmplot uses interpolated colors on each triangle in the simplicial complex. However, it does not use the interpolated-color feature that is built in to Matlab (I found that earlier versions of interpolated colors did not work on my color printer. I don't know if this has been fixed in the more recent Matlab releases). Instead, it divides each triangle into four smaller triangles and uses flat colors (that are linearly interpolated by the gmplot program) on each of the four subtriangles. Thus, the triangles you see with gmplot are actually half the side-length of the actual triangles used in the finite element solver.

The matlab command colorbar is useful in conjunction with the gmplot routine.

This documentation is written by Stephen A. Vavasis and is copyright (c) 1996 by Cornell University. Permission to reproduce this documentation is granted provided this notice remains attached. There is no warranty of any kind on this software or its documentation. See the accompanying file 'Copyright' for a full statement of the copyright.

Back to the QMG1.1 home page.

Stephen A. Vavasis, Computer Science Department, Cornell University, Ithaca, NY 14853, vavasis@cs.cornell.edu