## QMG Reference Manual |

The categories of functionality are:

- Brep constructors, modifiers, and checkers
- Mesh generation and finite element analysis
- Graphics
- Reading, writing and format conversion
- Utilities and examples

- gm_addpropval
- gmapply
- gmboundary
- gmcavity
- gmchecknormals
- gmchecktri
- gmcoarsetopo
- gm_cpoly
- gmdouble
- gmevallog
- gmfem
- gmhelp
- gm_list2obj
- gm_lookup_prop
- gmmake_circ
- gmmake_cyl
- gmmake_torus
- gm_mcompo
- gmmeshgen
- gmmeshsize
- gmmouse
- gm_obj2list
- gm_objtype
- gmoffread
- gmpolygon
- gm_polytri
- gmplot
- gmq11read
- gm_read
- gm_rehash
- gmrndcolor
- gmset
- gmshowcolor
- gmsummary
- gm_url
- gmviz
- gmvizgui
- gm_write
- gmxdr_read
- gmxdr_write

In this reference manual, each routine is labeled according to whether it is written Matlab, Tcl or C++. Routines written in C++ are callable from both Matlab and Tcl. The Matlab and Tcl/Tk calling formats are both given.

Arguments in italic curly braces are optional. (Roman boldface curly braces, on the other hand, are part of the syntax.) The text describes the default values for optional arguments.

Other standard formats for arguments are as follows. Vectors and matrices in Matlab are just ordinary vectors and matrices. Vectors in Tcl are lists, and matrices in Tcl nested lists. See the Tcl syntax synopsis for an example. String literals in Matlab must be quoted with single quotes. In Tcl/Tk double quotes are used for string literals, and are optional unless the string has embedded spaces.

Tcl/Tk:This function adds new property-value pairs to a face of a brep, and returns the so-modified brep. Argumentgmsetnewbrep[gm_addpropvalbrep facenamelist proplist vallist]

To delete a property-value pair from a face, set the value to the empty string.

Note that this function does not exist in Matlab, but it is easy to obtain this functionality by directly modifying the zba cell arrays that encode a brep.

Like all QMG functions, `gm_addpropval`

does not
modify its argument, so it is useless without a return value.

Matlab:Here,Tcl/Tk:newobj=gmapply(mtx,obj);

gmsetnewobj[gmapplymtxobj]

This function, when applied to breps, assigns the same property-value lists to faces of the output brep that were assigned to the input brep.

The *mtx* argument is a matrix of
size *d*×(*d*+1), where *d* is the embedded dimension
of the object.
Partitioning *mat* as [*A,b*], where
*A*
is *d*×*d* and *b* is *d*×1,
the transformation applied is *x→Ax−b*.

Matlab:This routine computes a new brep that results from making a cavity shaped likeTcl/Tk:newbrep=gmcavity(outerbrep, innerbrep);

gmsetnewbrep[gmcavityouterbrep innerbrep]

Matlab:This routine checks deviation in the normals in each topological entity. Recall that topological entities are supposed to be[Tcl/Tk:maxdev,facename,cpnum]=gmchecknormals(brep);

gmset {maxdev,facename,cpnum} [gmchecknormalsbrep]

Matlab:This routine coarsens the topology of a brep. This means that it tries to merge entities of dimensionTcl/Tk:newbrep=gmcoarsetopo(brep, a);

gmsetnewbrep[gmcoarsetopobrep a]

The purpose of coarsening the topology is so that the mesh generator will produce fewer elements. The mesh generator must respect all topological boundaries in its mesh (and hence must subdivide its mesh more finely if there are many topological boundaries).

This routine measure deviation from *G*^{1}
only at control points. In 3D, it
is possible for the maximum deviation from *G*^{1}
to occur at an interior
point on a Bezier curve separating two patches, in which case this
routine will miss that deviation.

If the argument *a* is set (for example) to 0.6,
then the curvature-tolerance setting
for the mesh generator on the resulting new brep should not be any lower
than 0.6.

Matlab:This routine creates a 2D brep given its list of vertices in order. The vertices are held in theTcl/Tk:brep=gm_cpoly(verts,codes);

gmsetbrep[gm_cpolyverts codes]

A graphical front end to this routine is provided by
`gmmouse`

.

Matlab:This routine looks up the value assigned to a property in a brep face. The property name is the last argument (a string). The face is specified by the two middle arguments (integers). The first integer is the face's dimension, and the second is the index of the particular face of that dimension (numbered consecutively starting with 0). The value assigned to that property is return, or the empty string if there is none. In the Tcl calling format, the brep should be in list form (i.e., converted to a list byval= gm_lookup_prop(brep, fdim, faceind, prop);

Tcl:gmsetval[gm_lookup_propbrepl fdim faceind prop]

`gm_obj2list`

).
Matlab:These routines construct three standard geometric shapes. The first makes a cylinder of height 2, radius 1, centered at the origin, with the z-axis as its axis of symmetry. The argumentTcl:brep= gmmake_cyl(numsubdiv);

brep= gmmake_torus(innerrad, outerrad, numsubdiv);

brep= gmmake_circ(numsubdiv);

gmsetbrep[gmmake_cylnumsubdiv]

gmsetbrep[gmmake_torusinnerrad outerrad numsubdiv]

gmsetbrep[gmmake_circnumsubdiv]

`gmapply`

.
The second routine makes a torus out of degree-(2,2) quadrilateral patches. The torus is centered at the origin and is symmetric about the z-axis. The first argument is the inner radius (of the hole) and the second argument is the outer radius. Thus, the tube-diameter is the difference between these radii.

The third routine makes a unit circle approximation out of cubic bezier curves.

Other interesting geometric shapes (a sphere; platonic solids) have been precomputed and stored in the $QMG_ROOT/data directory.

Matlab:This routine puts up a window on the screen in which the user can click points with the mouse to create a 2D brep. The user can also create Bezier curves by selecting control points. A set of radio-buttons at the bottom of the window indicate what the next mouse click represents (either the start of a new loop, the start of a topological edge, the start of a Bezier curve, or an interior control point of a curve).brep=gmmouse;

Tcl/Tk:gmsetbrep[gmmouse]

Matlab:This routine creates a brep equal to a 2D regular n-gon. The argument is the number of sides.brep=gmpolygon(nside);

Tcl/Tk:gmsetbrep[gmpolygonnside]

Matlab:This routine computes the constrained Delaunay triangulation of a polygon. It uses an O(brep=gm_polytri(vertices, edges {, tol})

Tcl/Tk:gmsetbrep[gm_polytrivertices edges { tol }]

The return variable is a matrix of integers with three columns. Each row of this matrix is one triangle of the triangulation. Each triangle is represented by three integers, which are indices of the three nodes of that triangle.

Tcl/Tk:This routine prints out a summary of the object, which is either a brep or simplicial complex.gmsummaryobj

Matlab:This routine computes the boundary of a mesh. For instance, if the input mesh is a tetrahedral mesh in 3D, then the output of this routine would be triangular mesh embedded in 3D that triangulates the boundary faces of the original brep. The global vertex numbers are preserved.Tcl/Tk:newmesh= gmboundary(mesh);

gmsetnewmesh[gmboundarymesh]

Matlab:This routine checks that a mesh is valid for a brep. It generates a small printout with information about the mesh, such as the worst aspect ratio and the longest side length. The optional third argument tells the routine whether to check orientation of mesh elements. Allowable values are 0 (indicating that orientation should not be checked), 1 (indicating that elements should be checked for right-hand orientation) or 2 (indicating that elements should be checked for left-hand orientation). The default is 1. The optional fourth argument is a relative tolerance for the allowable distance between the real coordinates of mesh nodes that lie on boundaries and the real coordinates as computed from the parametric coordinates of that node.Tcl/Tk:worstasp= gmchecktri(brep, mesh {, checko {, tol}});

gmsetworstasp[gmchecktribrep mesh {checko { tol}}]

The return value is the worst aspect ratio among all elements, or -1 if there is an error in the mesh.

Matlab:This routine doubles an internal boundary face (i.e., replaces it with two faces with different names). In the second calling format, it also doubles the nodes of a mesh that lie on the doubled face. For more information, see the section on this topic of the finite element documentation.or:newbrep= gmdouble(brep, facelist);

[Tcl/Tk:newbrep, newmesh] = gmdouble(brep, facelist, mesh);

gmsetor:newbrep[gmdoublebrep, facelist]

gmset {newbrep newmesh} [gmdoublebrep facelist mesh];

Matlab:This routine solves a boundary value problem of the formu= gmfem(brep, scomplex {, conductivity {, source {, userdata}}});

div (It uses a piecewise linear finite element method. See the finite element documentation for information on how this function works.c·gradu) = −fonD

u=gonB1

c·du/dn=honB2

Matlab:This routine finds connected components of a mesh. It labels the nodes according to the component containing them. Thus, the return value is an integer array (a zba in Matlab) with one entry per node of the mesh; the entry is the node's component number. Components are numbered starting with 0.Tcl:compnum= gm_mcompo(mesh);

gmsetcompnum[gm_mcompomesh]

Matlab:This is the main mesh generator in QMG. Please see the mesh generation documentation. This routine is a Matlab/Tcl front end to a C++ routineTcl:mesh= gmmeshgen(brep,opt_{1},val_{1}, …,opt_{n},val_{n});

gmsetmesh[gmmeshgenbrepopt_{1}val_{1}…opt_{n}val_{n}]

`gm_meshgen`

.
Matlab:This routine returns the number of nodes and number of elements in a mesh.[Tcl:numnodes,numelts] = gmmeshsize(mesh);gmset {numnodes numelts} [gmmeshsizemesh]

Matlab:gmplot(mesh, soln {, solnrange {,cmap}})

This routine is described in the graphics documentation page.

Matlab:newbrep= gmrndcolor(brep{, dimtocolor}})

Tcl:gmsetnewbrep[gmrndcolorbrep {dimtocolor}]

This routine is described in the graphics documentation page.

Matlab:This routine displays the colors assigned to brep faces. It makes a chart with one row per face. The row indicates the face's color (shown graphically and numerically) and the face's name. The routine shows all faces of dimensiongmshowcolor(brep{, dimtoshow}})

Tcl:gmshowcolorbrep {dimtoshow}

Matlab:This routine plots breps or meshes. In the first calling format,gmviz(obj {, dimlist {, colorlist}})

orgmviz({Tcl:mesh,brep}{, dimlist {, colorlist}})

gmvizobj { dimlist { colorlist}}

orgmviz [listmesh brep]{ dimlist { colorlist}}

In Tcl/Tk, the optional third argument is either a list of X11 colors
or is a list of 4-tuples (each tuple being a list of four numbers
(*r,g,b,a*). This color argument is overridden by the
value associated with the **color** property of
a face.

The graphics engine used and some other formatting parameters are
controlled by `gmvizgui`

.

See also the page on graphics.

Matlab:This routine creates a GUI panel to control the following settings concerning graphics state: line thickness (i.e., plot segments as fat lines or cylinders rather than lines), point thickness (i.e., plot points as disks or spheres rather than points), default color to be used bygmvizgui

Tcl:gmvizgui

`gmviz`

,
number of bezier subdivisions, graphics engine selection,
the name of the VRML file, whether to notify the browser
to reload the VRML file, and whether
to append or overwrite the current VRML file.
This panel does not affect the current plot; settings in this window
affect the next plot. If the panel is dismissed, the settings are
retained until the panel is recreated.
For more information on how the settings in this panel interact
with `gmviz`

, see the graphics
documentation page.

Tcl:This routine converts a Tcl list to a geometric object (brep or mesh). List format is like Ascii format, except that parentheses are replaced by curly braces. (The actual conversion does not carry out the operation in this manner. Instead, it converts directly from the internal Tcl list format to the internal Tcl brep or mesh format.) The purpose of this command is to allow breps and meshes to be built via Tcl list creation commands likegmsetobj[gm_list2objlist]

`lappend`

. The inverse operation is
`gm_obj2list`

.
Tcl:This routine converts an object (brep or mesh) to list format. List format is like Ascii format, except that parentheses are replaced by curly braces. (The actual conversion does not carry out the operation in this manner. Instead, it converts directly from the internal Tcl brep/mesh format to the internal Tcl list format.) The purpose of this command is to allow breps and meshes to be accessed via Tcl list commands likegmsetlvar[gm_obj2listobj]

`lindex`

. The inverse operation is
`gm_list2obj`

.
Matlab:This routine reads a 3D brep in OFF format. This is a simplified format for representing a 3D brep made up entirely of flat faces.brep=gmoffread(filename);

Tcl:gmsetbrep[gmoffreadfilename]

OFF file format was designed by the Geometry Center at the University of Minnesota. This format is much simpler than QMG's Ascii format, but it also has less expressive power. With OFF format you can store only finite three-dimensional breps. No curved boundaries or internal boundaries are permitted, and each facet must be a simple polygon (no holes in a facet). No property-value pairs are stored, except colors can be stored in a restricted manner.

In OFF format, there is a header line with the string
**OFF** by itself.
The next line contains three
integers, the number of vertices, the number of facets, and the number
of edges. Say *n* is the number of vertices.
The next *n* lines
each contain three floating-point numbers which are vertex
coordinates in **R**^3.
Say *m*
is the number of facets. The next *m*
lines contain the specifications
of the facets as sequences of integers. The first integer in
a facet specification is the number of vertices in that facet, say *p*.
The next *p*
integers are the indices of the vertices in order around the
boundary of the facet. These indices are zero-based and refer to the
*n* coordinates. Following these *p*
integers, there are optionally three
real numbers between 0 and 1 which form an RGB color specification.

In the directory $QMG_ROOT/data shipped with QMG, the five Platonic solids are shipped in OFF-format.

Each polygon is regarded as a separate topological face. This may
not be the intention of the OFF file; for instance, the OFF file might
encode a single curved surfaces by many triangular faces. The command
`gmcoarsetopo`

can be used
to reduce the number of topological entities.

Note that `gmoffwrite`

(a function available in
QMG 1.1) has been discontinued
because there is no way to write curved surfaces in OFF format.

Matlab:This routine reads a 3D brep in QMG 1.1's Ascii format. This routine is provided for backward compatibility.brep=gmq11read(filename);

Tcl:gmsetbrep[gmq11readfilename]

Each face of the brep
is regarded as a separate topological face. This may
not be the intention of the file; in QMG 1.1 it was not possible
to group many triangles or quadrilaterals into a single topological
entity.
The command
`gmcoarsetopo`

can be used
to reduce the number of topological entities.

Matlab:This routine reads a brep or mesh from a file in Ascii format. The inverse operation isobj=gm_read(filename);

Tcl:gmsetobj[gm_readfilename]

`gm_write`

.
Matlab:This routine writes a brep or mesh to a file in Ascii format. The inverse operation isgm_write(obj, filename);

Tcl:gm_writeobj filename

`gm_read`

.
Tcl:This routine reads a brep or mesh from a file in XDR format. XDR format is a binary representation of the internal C data structure used for breps and meshes. XDR format is compatible across platforms (e.g., it takes care of byte-order issues). XDR is part of the HDF format from UIUC and uses Sun RPC conventions. The inverse operation isgmsetobj[gmxdr_readfilename]

`gmxdr_write`

.
Matlab: Tcl:This routine writes a brep or mesh to a file in XDR format. XDR format is a binary representation of the internal C data structure used for breps and meshes. XDR format is compatible across platforms (e.g., it takes care of byte-order issues). XDR is part of the HDF format from UIUC and uses Sun RPC conventions. The inverse operation isgmxdr_writeobj filename

`gmxdr_read`

.
Matlab:This routine evaluates a script file and prints the results in the specified log file. In addition, it writes the time at the beginning of each command in the log file.gmevallog(scriptfile, outputfile)

Tcl:gmevallogscriptfile {outputfile}

In the Tcl version, the logfile may be omitted in which case the output is printed on the console window.

Tcl:The commandgmhelp{cmdname}

`gmhelp`

alone prints a brief help message
on the console. It may optionally be followed by a function name,
in which case it prints out a help message for that function.
This function is not available in Matlab since Matlab already
provides a `help`

statement.
Tcl:This routine returns the type of an object, for instance,gm_objtypeobj

Tcl:This routine causes all the files in the QMG Tcl library directory ($QMG_ROOT/tcl) to be re-read. (The routine skips over files beginning with the prefixgm_rehash

Tcl:This is a C++ routine in QMG that is part of the Tcl interface. It is the same as the built-in Tcl commandgmsetvarname value

`set`

,
except that it does not
produce a return value. This is useful in an interactive setting, because
typically the QMG routines return breps or meshes that the user does
not want printed on the console. In addition, unlike `set`

,
this routine prevents
the conversion of objects to Ascii
when used in console mode, so it is much more efficient than
`set`

. (When used in a script or procedure, `set`

is preferable to `gmset`

although the difference
is marginal.) The Tcl:In this call,gm_urlbrowser url

This documentation is written by Stephen A. Vavasis and is copyright ©1999 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.

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