QMG logo

QMG Reference Manual

This page contains a list of the QMG functions organized by categories of functionality. There are some general principles about QMG functions.

The categories of functionality are:

You may also select from the following alphabetized list of QMG functions. Some of the low-level and utility functions are not documented here.

General principles about QMG functions

QMG functions begin with the prefix gm for geometry. The lower level functions begin with gm_; these lower level functions are often accessed through higher level functions. Arguments to QMG functions are passed by value. Return values are are the actual objects rather than handles or pointers, and they have no side effects (except for I/O routines). (Note that both Matlab and Tcl implement a lazy copying scheme for efficiency, so that a return value may actually be a handle. This behavior is not visible to the user.) This functional nature simplifies the model of programming but means that there may be extra copying done in QMG.

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.

Brep constructors, modifiers, and checkers

gm_addpropval (Tcl only)

Tcl/Tk: gmset newbrep [gm_addpropval brep facenamelist proplist vallist]
This function adds new property-value pairs to a face of a brep, and returns the so-modified brep. Argument facenamelist is a list of face names in the brep (strings). An empty string in this list indicates that the property-value pair is global for the brep. Then proplist and vallist are lists of properties (string) and values (strings). All three lists have the same length. The routine adds the property whose name is taken from proplist to the face whose name is in the corresponding position of facenamelist with value taken from the corresponding position in vallist. If the property already exists, then this routine replaces its old value with the specified value. Property names and face names are not case sensitive.

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.

gmapply (C++)

Matlab: newobj=gmapply(mtx, obj);
Tcl/Tk: gmset newobj [gmapply mtx obj]
Here, obj is a brep or simplicial complex, and mtx is an affine transformation of the correct dimension. The affine transformation is applied to the object, and the transformed object is returned.

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.

gmcavity (Matlab and Tcl)

Matlab: newbrep=gmcavity(outerbrep, innerbrep);
Tcl/Tk: gmset newbrep [gmcavity outerbrep innerbrep]
This routine computes a new brep that results from making a cavity shaped like innerbrep inside outerbrep. For example, if the outer brep is a circle and the inner brep a smaller concentric circle, then the result would be an annulus. This routine does not check that the inner brep is actually inside the outer one.

gmchecknormals (C++)

Matlab: [maxdev,facename,cpnum]=gmchecknormals(brep);
Tcl/Tk: gmset {maxdev,facename,cpnum} [gmchecknormals brep]
This routine checks deviation in the normals in each topological entity. Recall that topological entities are supposed to be G1, meaning that the normal vector for patches (and normalized tangent vector for curves) should be continuous as one jumps from one geometric entity to the next. However, QMG allows deviations from the G1 condition in order to allow brep that are composed of noncoplanar flat triangular patches. The setting of the curvature control to the mesh generator must be at least as large as the largest normal discontinuity. This routine measure the largest deviation from continuous normals in all faces. The deviation is checked only at control points; it is possible (in the case of nonlinear patches) that the largest deviation does not occur at a control point. The first return value is the maximum deviation and hence is a lower bound for the curvature control in the mesh generator. The second return value is the name of the face with the worst discontinuity in the normal. The third return value is the control point index with the worst discontinuity in the normal.

gmcoarsetopo (C++)

Matlab: newbrep=gmcoarsetopo(brep, a);
Tcl/Tk: gmset newbrep [gmcoarsetopo brep a]
This routine coarsens the topology of a brep. This means that it tries to merge entities of dimension d−1, where d is the dimension (both embedded and intrinsic) of the brep. In the process of merging faces of this dimension, the routine may also delete faces of lower dimension. Faces can be merged only if their property-value pairs completely agree. Lower dimensional faces with property-value pairs are not deleted. The second argument a is the allowable deviation from G1 on any face. Merging will take place only if this allowable deviation is not exceeded. This deviation is measured in the same way that the curvature function is measured. Thus, the second argument should be a positive number.

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 G1 only at control points. In 3D, it is possible for the maximum deviation from G1 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.

gm_cpoly (Matlab and Tcl)

Matlab: brep=gm_cpoly(verts,codes);
Tcl/Tk: gmset brep [gm_cpoly verts codes]
This routine creates a 2D brep given its list of vertices in order. The vertices are held in the verts argument, which must be a matrix with two columns. Each row of this matrix is an (x,y) coordinate pair of a vertex. The codes argument is a vector of integers whose number of entries must equal the number of vertices. This argument indicates how the corresponding vertex should be interpreted. If the entry in codes is 0, this means that the vertex marks the beginning of a new loop and signals that the previous loop (if there is one) should be closed off. The first entry in codes must always be 0. A code of 1 indicates that the vertex is the start of a new topological edge. (Note that code 0 implies code 1, i.e., the start of a new loop is also the start of a topological edge. This is true for all the codes: code i implies code i+1, etc.) A code of 2 indicates that the vertex is the start of a new Bezier curve (which is part of a topological edge). Finally, a code of 3 indicates that the vertex is a Bezier control point (but is none of the above).

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

gm_lookup_prop (Matlab and Tcl)

Matlab: val = gm_lookup_prop(brep, fdim, faceind, prop);
Tcl: gmset val [gm_lookup_prop brepl fdim faceind prop]
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 by gm_obj2list).

gmmake_circ, gmmake_cyl, gmmake_torus (Matlab and Tcl)

brep = gmmake_cyl(numsubdiv);
brep = gmmake_torus(innerrad, outerrad, numsubdiv);
brep = gmmake_circ(numsubdiv);
gmset brep [gmmake_cyl numsubdiv]
gmset brep [gmmake_torus innerrad outerrad numsubdiv]
gmset brep [gmmake_circ numsubdiv]
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 argument numsubdiv (in all three routines) indicates the number of Bezier patches to use in the approximation. The cylinder routine uses degree-(3,1) quadrilateral patches on the cylinder side and degree-3 triangular patches on the ends. If you need a cylinder with a different height, width, center or orientation, you can apply a transformation using 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.

gmmouse (Matlab and Tcl)

Matlab: brep=gmmouse;
Tcl/Tk: gmset brep [gmmouse]
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).

gmpolygon (Matlab and Tcl)

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

gm_polytri (C++)

Matlab: brep=gm_polytri(vertices, edges {, tol})
Tcl/Tk: gmset brep [gm_polytri vertices edges { tol }]
This routine computes the constrained Delaunay triangulation of a polygon. It uses an O(n2 log n) algorithm that seems to be very robust (but not optimally efficient). The first argument is a list of node coordinates of the polygon. This argument is a matrix with one coordinate per row. The number of columns in the matrix is either two or three. In Matlab, this argument must be a zba. The second argument is the list of edges of the polygon. It is a matrix of integers with two columns. Each row represents an edge in the matrix, and the two entries are integer zero-based indices into the node array. The last optional argument is a tolerance. The tolerance is relevant only in 3D and indicates the allowable deviation from coplanarity of the vertices.

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.

gmsummary (Tcl only)

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

Mesh generation and finite element analysis

gmboundary (C++)

Matlab: newmesh = gmboundary(mesh);
Tcl/Tk: gmset newmesh [gmboundary mesh]
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.

gmchecktri (C++)

Matlab: worstasp = gmchecktri(brep, mesh {, checko {, tol}});
Tcl/Tk: gmset worstasp [gmchecktri brep mesh {checko { tol}}]
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.

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

gmdouble (C++)

Matlab: newbrep = gmdouble(brep, facelist);
or: [newbrep, newmesh] = gmdouble(brep, facelist, mesh);
Tcl/Tk: gmset newbrep [gmdouble brep, facelist]
or: gmset {newbrep newmesh} [gmdouble brep facelist mesh];
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.

gmfem (Matlab only)

Matlab: u = gmfem(brep, scomplex {, conductivity {, source {, userdata}}});
This routine solves a boundary value problem of the form
div (c·grad u) = −f on D
u = g on B1
c·du/dn = h on B2
It uses a piecewise linear finite element method. See the finite element documentation for information on how this function works.

gm_mcompo (C++)

Matlab: compnum = gm_mcompo(mesh);
Tcl: gmset compnum [gm_mcompo mesh]
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.

gmmeshgen (Matlab and Tcl)

Matlab: mesh = gmmeshgen(brep,opt1, val1, …, optn, valn);
Tcl: gmset mesh [gmmeshgen brep opt1 val1optn valn]
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++ routine gm_meshgen.

gmmeshsize (C++)

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


gmplot (Matlab only)

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

This routine is described in the graphics documentation page.

gmrndcolor (Matlab and Tcl)

Matlab: newbrep = gmrndcolor(brep{, dimtocolor}})
Tcl: gmset newbrep [gmrndcolor brep {dimtocolor}]

This routine is described in the graphics documentation page.

gmshowcolor (Matlab and Tcl)

Matlab: gmshowcolor(brep{, dimtoshow}})
Tcl: gmshowcolor brep {dimtoshow}
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 dimension dimtoshow in numerical order. The dimtoshow argument is optional and defaults to 1 less than the embedded dimension of the brep, or the intrinsic dimension, whichever is smaller.

gmviz (Matlab and Tcl)

Matlab: gmviz(obj {, dimlist {, colorlist}})
or gmviz({mesh,brep} {, dimlist {, colorlist}})
Tcl: gmviz obj { dimlist { colorlist}}
or gmviz [list mesh brep] { dimlist { colorlist}}
This routine plots breps or meshes. In the first calling format, obj is a brep or mesh. In the second calling format, the first argument is a mesh-brep pair, where the mesh must have been generated for the brep. The dimlist argument lists the dimensions of the object to plot. The colorlist argument is the colors to use. The list of colors is in correspondence with the list of dimensions. The colors in Matlab may be specified as a k×4 matrix, where k is the number of dimensions to plot. In this case, each row of the matrix is a color 4-tuple of the form (r,g,b,a). The colors may also be a list of k one-character color codes like 'r' or 'c'.

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.

gmvizgui (Matlab and Tcl)

Matlab: gmvizgui
Tcl: gmvizgui
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 by 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.

Input/output and format conversion

gm_list2obj (Tcl only)

Tcl: gmset obj [gm_list2obj list]
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 like lappend. The inverse operation is gm_obj2list.

gm_obj2list (Tcl only)

Tcl: gmset lvar [gm_obj2list obj]
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 like lindex. The inverse operation is gm_list2obj.

gmoffread (Matlab and Tcl)

Matlab: brep=gmoffread(filename);
Tcl: gmset brep [gmoffread filename]
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.

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.

Convex Hulls

There is no routine in QMG for computing convex hulls. However, you can obtain qhull from the Geometry Center for this purpose. Qhull can produce output in OFF format, which can then be read into QMG. If you use qhull to generate a convex hull, you must first modify the OFF file it produces. The OFF file produced by qhull begins with the number 3 as its first line (which is the dimension of the object). This line must be replaced with a line consisting of the word OFF.

gmq11read (Matlab and Tcl)

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

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.

gm_read (C++)

Matlab: obj=gm_read(filename);
Tcl: gmset obj [gm_read filename]
This routine reads a brep or mesh from a file in Ascii format. The inverse operation is gm_write.

gm_write (C++)

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

gmxdr_read (Tcl only; written in C++)

Tcl: gmset obj [gmxdr_read filename]
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 is gmxdr_write.

gmxdr_write (Tcl only; written in C++)

Matlab: Tcl: gmxdr_write obj filename
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 is gmxdr_read.

Utility functions

gmevallog (Matlab and Tcl)

Matlab: gmevallog(scriptfile, outputfile)
Tcl: gmevallog scriptfile {outputfile}
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.

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

gmhelp (Tcl only)

Tcl: gmhelp {cmdname}
The command 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.

gm_objtype (Tcl only; written in C++)

Tcl: gm_objtype obj
This routine returns the type of an object, for instance, brep or simpcomp for breps and meshes. Note that this command looks at the type name of the internal type. Therefore, if the object is not represented using the internal type (i.e., Tcl has converted it to a string) then this routine will not return the type.

gm_rehash (Tcl only)

Tcl: gm_rehash
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 prefix qmg_ and tk, which are used only during initialization.) This is useful if you are editing those files or creating new ones. Note it is recommended that you do not rely on the auto-load facility because there is a bug (in certain versions of Tcl 8.0) in auto-load that sometimes causes breps and simplicial complexes to be needless converted to string representation (possibly a very expensive conversion). Instead, QMG, source's all its Tcl files during initialization.

gmset (Tcl only; written in C++)

Tcl: gmset varname value
This is a C++ routine in QMG that is part of the Tcl interface. It is the same as the built-in Tcl command 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 varname argument may optionally be a list of variable names in curly braces. In this case, the value should be a list of the same length; this command sets each variable in the list to its corresponding list entry.

gm_url (Tcl only)

Tcl: gm_url browser url
In this call, browser and url are both strings. This command tells the browser to open the specified URL. This is used by gmviz and gmplot for notification so that 3D VRML plots appear immediately in your browser. Currently supported browsers are Netscape Navigator for Windows and Unix, and Microsoft Internet Explorer for Windows.

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