 |
QMG Reference Manual |
|
|
QMG Reference Manual |
The categories of functionality are:
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: 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.
Matlab: 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.
Tcl/Tk: gmset newobj [gmapply mtx obj]
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: 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.
Tcl/Tk: gmset newbrep [gmcavity outerbrep innerbrep]
Matlab: [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.
Tcl/Tk: gmset {maxdev,facename,cpnum} [gmchecknormals brep]
Matlab: 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.
Tcl/Tk: gmset newbrep [gmcoarsetopo brep 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 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.
Matlab: 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).
Tcl/Tk: gmset brep [gm_cpoly verts codes]
A graphical front end to this routine is provided by
gmmouse.
Matlab: val = gm_lookup_prop(brep, 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
Tcl: gmset val [gm_lookup_prop brepl 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 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 usingbrep = gmmake_cyl(numsubdiv);Tcl:
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]
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: 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).
Tcl/Tk: gmset brep [gmmouse]
Matlab: brep=gmpolygon(nside);This routine creates a brep equal to a 2D regular n-gon. The argument is the number of sides.
Tcl/Tk: gmset brep [gmpolygon nside]
Matlab: 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.
Tcl/Tk: gmset brep [gm_polytri vertices 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: gmsummary objThis routine prints out a summary of the object, which is either a brep or simplicial complex.
Matlab: 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.
Tcl/Tk: gmset newmesh [gmboundary mesh]
Matlab: 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.
Tcl/Tk: gmset worstasp [gmchecktri brep 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: newbrep = gmdouble(brep, facelist);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, newmesh] = gmdouble(brep, facelist, mesh);
Tcl/Tk: gmset newbrep [gmdouble brep, facelist]
or: gmset {newbrep newmesh} [gmdouble brep facelist mesh];
Matlab: u = gmfem(brep, scomplex {, conductivity {, source {, userdata}}});This routine solves a boundary value problem of the form
div (c·grad u) = −f on DIt uses a piecewise linear finite element method. See the finite element documentation for information on how this function works.
u = g on B1
c·du/dn = h on B2
Matlab: 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.
Tcl: gmset compnum [gm_mcompo mesh]
Matlab: mesh = gmmeshgen(brep,opt1, val1, …, optn, 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
Tcl: gmset mesh [gmmeshgen brep opt1 val1 … optn valn]
gm_meshgen.
Matlab: [numnodes,numelts] = gmmeshsize(mesh);This routine returns the number of nodes and number of elements in a mesh.
Tcl: gmset {numnodes numelts} [gmmeshsize mesh]
Matlab: gmplot(mesh, soln {, solnrange {,cmap}})
This routine is described in the graphics documentation page.
Matlab: newbrep = gmrndcolor(brep{, dimtocolor}})
Tcl: gmset newbrep [gmrndcolor brep {dimtocolor}]
This routine is described in the graphics documentation page.
Matlab: 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.
Tcl: gmshowcolor brep {dimtoshow}
Matlab: gmviz(obj {, 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'.
or gmviz({mesh,brep} {, dimlist {, colorlist}})
Tcl: gmviz obj { dimlist { colorlist}}
or gmviz [list mesh 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: gmvizguiThis 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
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: 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.
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.
Matlab: 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.
Tcl: gmset brep [gmoffread filename]
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: brep=gmq11read(filename);This routine reads a 3D brep in QMG 1.1's Ascii format. This routine is provided for backward compatibility.
Tcl: gmset brep [gmq11read filename]
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: obj=gm_read(filename);This routine reads a brep or mesh from a file in Ascii format. The inverse operation is
Tcl: gmset obj [gm_read filename]
gm_write.
Matlab: gm_write(obj, filename);This routine writes a brep or mesh to a file in Ascii format. The inverse operation is
Tcl: gm_write obj filename
gm_read.
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.
Matlab: Tcl: gmxdr_write obj filenameThis 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.
Matlab: 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.
Tcl: gmevallog scriptfile {outputfile}
In the Tcl version, the logfile may be omitted in which case the output is printed on the console window.
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.
Tcl: gm_objtype objThis 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.
Tcl: gm_rehashThis 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.
Tcl: gmset varname valueThis 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.
Tcl: gm_url browser urlIn 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