or is a list of 4-tuples (each tuple being a list of four numbers
(<em>r,g,b,a</em>).  This color argument is overridden by the 
value associated with the <strong>color</strong> property of 
a face.

<p>
The graphics engine used and some other formatting parameters are
controlled by <a href="#gmvizgui"><code>gmvizgui</code></a>.
<p>
See also the page on <a href="graphics.html">graphics</a>.


<h3><a name="gmvizgui">gmvizgui (Matlab and Tcl)</a></h3>
<blockquote>
Matlab:
<strong>
gmvizgui
</strong>
<br>
Tcl:
<strong>
gmvizgui
</strong>
</blockquote>
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 <a href="#gmviz"><code>gmviz</code></a>,
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.

<p>
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 <code>gmviz</code>, see the <a href="graphics.html">graphics
documentation page.</a>

<h2><a name="io">Input/output and format conversion</a></h2>

<h3><a name="gm_list2obj">gm_list2obj (Tcl only)</a></h3>
<blockquote>
Tcl:
<strong>
gmset <em>obj</em> [gm_list2obj <em>list</em>]
</strong>
</blockquote>

This routine converts a Tcl list to a geometric
object (brep or mesh).
List format is like <a href="geom.html#asciirep">Ascii format</a>, 
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 <code>lappend</code>.   The inverse operation is
<a href="#gm_obj2list"><code>gm_obj2list</code></a>.


<h3><a name="gm_obj2list">gm_obj2list (Tcl only)</a></h3>
<blockquote>
Tcl:
<strong>
gmset <em>lvar</em> [gm_obj2list <em>obj</em>]
</strong>
</blockquote>

This routine converts an object (brep or mesh) to list
format.  List format is like <a href="geom.html#asciirep">Ascii format</a>, 
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 <code>lindex</code>.   The inverse operation is
<a href="#gm_list2obj"><code>gm_list2obj</code></a>.

<h3><a name="gmoffread">gmoffread (Matlab and Tcl)</a></h3>
<blockquote>
Matlab:
<strong>
<em>brep</em>=gmoffread(<em>filename</em>);
</strong>
<br>
Tcl:
<strong>
gmset <em>brep</em> [gmoffread <em>filename</em>]
</strong>
</blockquote>
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.  

<p>
OFF file format was designed by the <a href="http://www.geom.umn.edu/">Geometry
Center</a> 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.

<p>
In OFF format, there is a header line with the string
<strong>OFF</strong> by itself.
The next line contains three
integers, the number of vertices, the number of facets, and the number
of edges.  Say <em>n</em> is the number of vertices.  
The next <em>n</em> lines
each contain three floating-point numbers which are vertex
coordinates in <strong>R</strong>^3.  
Say <em>m</em> 
is the number of facets.  The next <em>m</em> 
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 <em>p</em>.
The next <em>p</em> 
integers are the indices of the vertices in order around the
boundary of the facet.  These indices are zero-based and refer to the
<em>n</em> coordinates.  Following these <em>p</em> 
integers, there are optionally three
real numbers between 0 and 1 which form an RGB color specification.

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

<p>
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
<a href="#gmcoarsetopo"><code>gmcoarsetopo</code></a> can be used
to reduce the number of topological entities.

<p>
Note that <code>gmoffwrite</code> (a function available in
QMG 1.1) has been discontinued
because there is no way to write curved surfaces in OFF format.

<h3>Convex Hulls</h3>
There is no routine in QMG for computing convex hulls.  However,
you can obtain <strong>qhull</strong>
 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 <strong>3</strong>
 as its first line (which is the dimension of
the object).  This line must be replaced with a line consisting of
the word <strong>OFF</strong>.


<h3><a name="gmq11read">gmq11read (Matlab and Tcl)</a></h3>
<blockquote>
Matlab:
<strong>
<em>brep</em>=gmq11read(<em>filename</em>);
</strong>
<br>
Tcl:
<strong>
gmset <em>brep</em> [gmq11read <em>filename</em>]
</strong>
</blockquote>
This routine reads a 3D brep in QMG 1.1's Ascii format.   This
routine is provided for backward compatibility.  

<p>
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
<a href="#gmcoarsetopo"><code>gmcoarsetopo</code></a> can be used
to reduce the number of topological entities.


<h3><a name="gm_read">gm_read (C++)</a></h3>
<blockquote>
Matlab:
<strong>
<em>obj</em>=gm_read(<em>filename</em>);
</strong>
<br>
Tcl:
<strong>
gmset <em>obj</em> [gm_read <em>filename</em>]
</strong>
</blockquote>
This routine reads a brep or mesh
from a file in <a href="geom.html#asciirep">Ascii
format</a>.  The inverse operation is 
<a href="#gm_write"><code>gm_write</code></a>.

<h3><a name="gm_write">gm_write (C++)</a></h3>
<blockquote>
Matlab:
<strong>
gm_write(<em>obj, filename</em>);
</strong>
<br>
Tcl:
<strong>
gm_write <em>obj filename</em>
</strong>
</blockquote>
This routine writes a brep or mesh to a
 file in <a href="geom.html#asciirep">Ascii
format</a>.  The inverse operation is 
<a href="#gm_read"><code>gm_read</code></a>.

<h3><a name="gmxdr_read">gmxdr_read (Tcl only; written in C++)</a></h3>
<blockquote>
Tcl:
<strong>
gmset <em>obj</em> [gmxdr_read <em>filename</em>]
</strong>
</blockquote>
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 <a href="http://hdf.ncsa.uiuc.edu/">HDF</a>
format from UIUC and uses Sun RPC conventions.
The inverse operation is 
<a href="#gmxdr_write"><code>gmxdr_write</code></a>.


<h3><a name="gmxdr_write">gmxdr_write (Tcl only; written in C++)</a></h3>
<blockquote>
Matlab:
Tcl:
<strong>
gmxdr_write <em>obj filename</em>
</strong>
</blockquote>
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 <a href="http://hdf.ncsa.uiuc.edu/">HDF</a>
format from UIUC and uses Sun RPC conventions.
The inverse operation is 
<a href="#gmxdr_read"><code>gmxdr_read</code></a>.


<h2><a name="util">Utility functions</a></h2>

<h3><a name="gmevallog">gmevallog (Matlab and Tcl)</a></h3>
<blockquote>
Matlab:
<strong>
gmevallog(<em>scriptfile, outputfile</em>)</strong><br>
Tcl:
<strong>
gmevallog <em>scriptfile {outputfile}</em> 
</strong>
</blockquote>

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.

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

<h3><a name="gmhelp">gmhelp (Tcl only)</a></h3>
<blockquote>
Tcl:
<strong>
gmhelp <em>{cmdname}</em>
</strong>
</blockquote>
The command <code>gmhelp</code> 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 <code>help</code> statement.

<h3><a name="gm_objtype">gm_objtype (Tcl only; written in C++)</a></h3>
<blockquote>
Tcl:
<strong>
gm_objtype <em>obj</em>
</strong>
</blockquote>
This routine returns the type of an object, for instance, 
<strong>brep</strong> or <strong>simpcomp</strong> 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.

<h3><a name="gm_rehash">gm_rehash (Tcl only)</a></h3>
<blockquote>
Tcl:
<strong>
gm_rehash
</strong>
</blockquote>
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 <strong>qmg_</strong>
and <strong>tk</strong>, 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.

<h3><a name="gmset">gmset (Tcl only; written in C++)</a></h3>
<blockquote>
Tcl:
<strong>
gmset <em> varname value</em>
</strong>
</blockquote>
This is a C++ routine in QMG that is part of the Tcl interface.  It
is the same as the built-in Tcl command <code>set</code>, 
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 <code>set</code>,
this routine prevents
the conversion of objects to Ascii
when used in console mode, so it is much more efficient than
<code>set</code>.  (When used in a script or procedure, <code>set</code>
is preferable to <code>gmset</code> although the difference
is marginal.)  The <em>varname</em> argument may optionally
be a list of variable names in curly braces.  In this case, the
<em>value</em> should be a list of the same length; this command
sets each variable in the list to its corresponding list entry.


<h3><a name="gm_url">gm_url (Tcl only)</a></h3>
<blockquote>
Tcl:
<strong>
gm_url <em>browser url</em>
</strong>
</blockquote>
In this call, <em>browser</em> and <em>url</em> 
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.


<hr>
<p>
This documentation is written by 
<a href="http://www.cs.cornell.edu/home/vavasis/vavasis.html">Stephen A. 
Vavasis</a> and is
copyright &#169;1999 by <a href="http://www.info.cornell.edu/CUHomePage.html">Cornell 
University</a>.
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
<a href="copyright.html">'copyright'</a>
for a full statement of the copyright.
<p>
<address>
Stephen A. Vavasis, Computer Science Department, Cornell University,
Ithaca, NY 14853, vavasis@cs.cornell.edu
</address>
</body>
</html>