This is geomview, produced by Makeinfo version 3.12h from geomview.texi.

INFO-DIR-SECTION Graphics Applications
START-INFO-DIR-ENTRY
* Geomview: (geomview).         The interactive 3D viewing program.
END-INFO-DIR-ENTRY


File: geomview,  Node: Cameras,  Next: Saving,  Prev: Lighting Panel,  Up: Interaction

Cameras
=======

   A camera in Geomview is the object that corresponds to a camera
window.  By default there is only one camera, but it is possible to
have as many as you want.  You can control certain aspects of the way
the world is drawn in each camera window via the _Cameras_ panel.  If
the target object is a camera, the _Cameras_ panel affects that camera.
If the target object is not a camera, the _Cameras_ panel affects the
"current camera".  The current camera is the camera of the window that
the mouse cursor is in, or was in most recently if the cursor is not in
a camera window.  Thus, if you use the keyboard shortcuts for the
actions in the _Cameras_ panel while the cursor is in a camera window,
the actions apply to that camera, unless you have explicitly selected
another camera.

   To create new camera windows, use the `v+' keyboard shortcut, or see
the _File_ menu on the _Main_ panel.

_Single-Buffering_
     Normally, geomview windows are _double-buffered_: geomview draws
     the next picture into a hidden window, then switches buffers to
     make it visible all at once.  On many systems, the memory for the
     hidden buffer comes from stealing half the bits in each screen
     pixel, reducing the color resolution.  When single-buffering is
     enabled, the window flickers as each scene is being drawn, but you
     may get smoother images with reduced grainy dithering artifacts.
     Single-buffering is possible if Geomview is compiled with GL or
     OpenGL, but not with plain-X graphics.

_Dither_
     Many displays offer less than the 24 bits per pixel (8 bits each
     of red, green, and blue) conventionally needed to show smooth
     gradations of color.  When trying to show a color not accurately
     available on the display, Geomview normally _dithers_, choosing
     pixel colors sometimes brighter, sometimes darker than the desired
     value, so that the average color over an area is a better
     approximation to the true color than a single pixel could be.
     Effectively this loses spatial resolution to gain color resolution.
     This isn't always desirable, though.  Turning _Dither_ off gives
     less grainy, but less accurately colored, images.

_Software Shading_
     This button controls whether Geomview does shading calculations in
     software.  The default is to let the hardware handle them, and in
     Euclidean space this is almost certainly best because it is
     faster.  In hyperbolic and spherical space, however, the shading
     calculations that the hardware does are incorrect.  Click this
     button to turn on correct but slower software shading.

_Background Color_
     This button brings up a color chooser which you can use to set the
     background color of the camera's window.

_PROJECTION_
     This browser lets you pick between perspective and orthogonal
     projection for this camera.

_Near clip_
     This determines the distance in world coordinates of the near
     clipping plane from the eye point.  It must be a positive number.

_Far clip_
     This determines the distance in world coordinates of the far
     clipping plane from the eye point.  It must be a positive number
     and in general should be larger than the _Near clip_ value.

_FOV_
     This is the camera's field of view, measured in its shorter
     direction.  In perspective mode, it is an angle in degrees.  In
     orthographic mode, it is the linear size of the field of view.
     This number can be modified with the mouse in _Cam Zoom_ mode.

_Focal Length_
     The focal length is intended to suggest the distance from the
     camera to an imaginary plane of interest.  Its value is used when
     switching between orthographic and perspective views (and during
     stereo viewing), so as to preserve apparent size of objects lying
     at the focal distance from the camera.  Focal length also affects
     interpretation of mouse-based translational motions.  Speed of
     forward motion (in translate, fly and orbit modes) is proportional
     to focal length; and objects lying at the focal distance from the
     camera translate laterally at the same rate as the mouse cursor.
     Finally, in N-D projection mode, cameras are displaced back by the
     focal distance from the 3-D projection of the world origin.

_Lines Closer_
     This number has to do with the way lines are drawn.  Normally
     Geomview's z-buffering algorithm can get confused when drawing
     lines that lie exactly on surfaces (such as the edges of an
     object); due to machine round-off error, sometimes the lines
     appear to be in front of the surface and sometimes they appear
     behind it.  The _Lines Closer_ value is a fudge factor -- Geomview
     nudges all the lines that it draws closer to the camera by this
     amount.  The number should be a small integer; try 5 or 10.  0
     turns this feature off completely.  Choosing too large a value
     will make lines visible even though they should be hidden.

_SPACE MODEL_
     This determines the model used to draw the world.  It is most
     useful in hyperbolic and spherical spaces.  You probably don't
     need to touch this browser if you stay in Euclidean space.  For
     more information about these models, *note Non-Euclidean
     Geometry::..
    _Virtual_
          This is the default model and represents the natural view
          from inside the space.

    _Projective_
          The projective model of hyperbolic and spherical space.
          Geoms move under isometries of the space, and cameras move by
          Euclidean motions.  By default in the projective model, the
          Euclidean unit sphere is drawn.  In hyperbolic space this is
          the sphere at infinity.  In Euclidean space the projective
          model is the same as the virtual model except that the sphere
          is drawn by default.

    _Conformal_
          The conformal model of hyperbolic and spherical space.  Geoms
          move under isometries of the space, and cameras move by
          Euclidean motions.  In Euclidean space, the conformal model
          amounts to inverting everything in the unit sphere.

_Draw Sphere_
     This controls whether Geomview draws the unit sphere.  By default
     the unit sphere appears in the projective and conformal models.  In
     hyperbolic space this is the sphere at infinity.  In spherical
     space it is the equatorial sphere.

_Done_
     This button dismisses the _Cameras_ panel.


File: geomview,  Node: Saving,  Next: Commands,  Prev: Cameras,  Up: Interaction

Saving your work
================

   Geomview's _Save_ panel lets you store Geomview objects and other
information in files that you can read back into Geomview or other
programs.  To use the _Save_ panel you select the desired format in the
browser next to the word _Save_, enter the name of the object you want
to save in the text field next to the word _for_, and enter the name of
the file you wish to save to in the long text field next to the word
_in_.  You can then either hit `<Enter>' or click on the _OK_ button.
When the file has been written, the _Save_ panel disappears.  If you
want to dismiss the _Save_ panel without writing a file, click the
_Cancel_ button.

   If you specify `-' as the file name, Geomview will write the file to
standard output, i.e. in the shell window from which you invoked
Geomview.

   The possible formats are given below.  The kind of object that can
be written with each format is given in parentheses.

_Commands (any object)_
     This write a file of gcl commands containing all information about
     the object.  Loading this file later will restore the object as
     well as all other information about it, such as appearance,
     transformations, etc.

_Geometry alone (geom)_
     This writes an OOGL file containing just the geometry of the
     object.

_Geometry [in world] (geom)_
     This writes an OOGL file containing just the geometry of the
     object, transformed under Geomview's current transformation for
     this object.  Use this if you have moved the object from its
     initial position and want to save the new position relative to the
     world.

_Geometry [in universe] (geom)_
     This writes an OOGL file containing just the geometry of the geom,
     transformed under both the object's transformation and the world's
     transformation.

_RMan [->tiff] (camera)_
     Writes a RenderMan file which when rendered creates a tiff image.

_RMan [->frame] (camera)_
     Writes a RenderMan file which when rendered causes an image to
     appear in a window on the screen.

_SGI snapshot (camera)_
     Write an SGI raster file.  A bell rings when the snapshot is
     complete.  Only available on SGI systems.

_PPM Screen snapshot (camera)_
     Take a snapshot of the given window and save it as a PPM image.
     If you specify a string beginning with a vertical bar (`|') as the
     file name, it's interpreted as a Bourne shell command to which the
     PPM data should be piped, as in `| pnmtotiff > snap.tiff' or `|
     convert -geometry 50% ppm:- snap.gif'.

     PPM screen snapshots are only available with GL and Open GL, not
     plain X graphics.  The window should be entirely on the screen.
     Geomview will ensure that no other windows cover it while the
     snapshot is taken.

_PPM software snapshot (camera)_
     Writes a snapshot of that window's current view, as a PPM image,
     to the given file.  The file name may be a Bourne shell command
     preceded by a vertical bar (`|'), as with the PPM screen snapshot.
     The software snapshot, though, is produced by using a built-in
     software renderer (related to the X-windows renderer).  It doesn't
     matter whether the window is visible or not, and doesn't depend on
     GL or OpenGL.  It also doesn't support some features, such as
     texture mapping.

_Postscript snapshot (camera)_
     Writes a Postscript snapshot of the camera's view.  It's made by
     breaking up the scene into lines and polygons, sorting by depth,
     and generating Postscript lines and polygons for each one.
     Advantages over pixel-based snapshot images: resolution is very
     high, so edges look sharp even on high-resolution printers, or
     comparable-resolution images are typically much more compact.
     Disadvantages: depth-sorting gives good results on some scenes,
     but can be wildly wrong as a hidden-surface removal algorithm for
     other scenes.  Also, Postscript doesn't offer smoothly
     interpolated shading, only flat shading for each facet.

_Camera (camera)_
     Writes an OOGL file of a camera.

_Transform [to world] (any object)_
     Writes an OOGL transform file giving Geomview's transform for the
     object.

_Transform [to universe] (any object)_
     Writes an OOGL transform file giving a transform which is the
     composition of Geomview's transform for the object and the
     transform for the world.

_Window (camera)_
     Writes an OOGL window file for a camera.

_Panels_
     Writes a gcl file containing commands which record the state of
     all the Geomview panels.  Loading this file later will restore the
     positions of all the panels.


File: geomview,  Node: Commands,  Next: Keyboard Shortcuts,  Prev: Saving,  Up: Interaction

The Commands Panel
==================

   The _Commands_ panel lets you type in a gcl command.  When you hit
`<Enter>', Geomview interprets the command and prints any resulting
output or error messages on standard output.  You can edit the text and
hit `<Enter>' as many times as you like, in general, whenever you hit
`<Enter>' with the cursor in the _Commands_ panel, Geomview tries to
interpret whatever text you have typed in the text field as a command.

   [Move this.]  Normalization is a kind of scaling; Geomview can scale
an object so that it fits within a certain region.  The main point of
normalization is to allow you to easily view all of an object without
having to worry about how big it is.  We are gradually replacing
Geomview's normalization feature with more robust camera positioning
features.  In general, the best way to make sure you are seeing all of
an object is to use the _Look At_ button on the _Tools_ panel.
Normalization may be completely replaced by this and other features in
a future version of Geomview.

   Normalization is a property that applies to each geom separately.
The _NORMALIZE GEOMETRY_ browser affects the normalization property of
target geom.  If the target geom is "World", it affects all geoms.

_None_
     Do no normalization.

_Individual_
     Normalize this geom to fit within a unit sphere.

_Sequence_
     This resembles "Individual", except when an object is changing.
     Then, "Individual" tightly fits the bounding box around the object
     whenever it changes and normalizes accordingly, while "Sequence"
     normalizes the union of all variants of the object and normalizes
     accordingly.

_Keep_
     This leaves the current normalization transform unchanged when the
     object changes.  It may be useful to apply "Individual" or
     "Sequence" normalization to the first version of a changing object
     to bring it in view, then switch to "Keep".


File: geomview,  Node: Keyboard Shortcuts,  Next: OOGL File Formats,  Prev: Commands,  Up: Interaction

Keyboard Shortcuts
==================

   Most actions that you can do through Geomview's panels have
equivalent keyboard shortcuts so that you can do the same action by
typing a sequence of keys on the keyboard.  This is useful for advanced
users who are familiar with Geomview's capabilities and want to work
quickly without having to have lots of panels cluttering up the screen.
Keyboard shortcuts usually are indicated in square brackets ([ ]) near
the corresponding item in a panel.  For example, the keyboard shortcut
for _Rotate_ mode is 'r'; this is indicated by "[r]" appearing before
the word "Rotate" in the _MOTION MODE_ browser.  To use this keyboard
shortcut just hit the `r' key while the mouse cursor is in any Geomview
window.  You don't need to press the `<Enter>' or `<SPACE>' keys.

   Some keyboard shortcuts consist of more than one key.  In these cases
just type the keys one after the other, with no `<Enter>' afterwards.
Keyboard shortcuts are case sensitive.  You can cancel a multi-key
keyboard shortcut that you have started by typing any invalid key, for
example the space bar.

   Keyboard commands apply while the cursor is in any camera window and
most control panels.

   Many keyboard shortcuts allow numeric arguments which you type as a
prefix to the command key(s).  For example, the shortcut for _Near
clip_ in the camera panel is `v n'.  To set the near clip plane to
`0.5', type `0.5vn'.  Commands that don't take a numeric prefix toggle
or reset the current value.

   Most commands allow one of the following selection prefixes.  If
none is provided the command applies to the target object.

`g'
     world geom

`g#'
     #'th geom

`g*'
     All geoms

`c'
     current camera

`c#'
     #'th camera

`c*'
     All cameras

   For example, `g4af' means toggle the face drawing of object _g4_.

   Simply typing a selection prefix, like `g4', doesn't yet select an
object; that only happens when a command, like `ae', follows the prefix.
To select an object as the target without doing anything else to it,
use the `p' command.  So `g3p' selects object g3.

   The text field in the upper left corner of the _Main_ panel shows
the state of the current keyboard shortcut.

   In addition to the keyboard shortcuts for the panel commands, there
is also a shortcut for picking a target object: type the short name of
the object followed by `p'.  For example, to select object _g3_, type
`g 3 p'.  This only works with the short names -- the ones that appear
in square brackets ([ ]) in the _Targets_ browser of the _Main_ panel.

   Below is a summary of all keyboard shortcuts.

Draw

    `af'
          Faces

    `ae'
          Edges

    `an'
          Normals

    `ab'
          Bounding Boxes

    `aV'
          Vectors

Shading

    `0as'
          Constant

    `1as'
          Flat

    `2as'
          Smooth

    `3as'
          Smooth, non-lighted

    `aT'
          allow transparency

    `at'
          texture mapping

Other

    `av'
          eVert normals: always face viewer

    `#aw'
          Line Width (pixels)

    `aC'
          handle concave polygons

    `#vc'
          edges Closer than faces (try 5-100)

Color

    `Cf'
          faces

    `Ce'
          edges

    `Cn'
          normals

    `Cb'
          bounding boxes

    `CB'
          background

Motions

    `r'
          rotate

    `t'
          translate

    `z'
          zoom FOV

    `f'
          fly

    `o'
          orbit

    `s'
          scale

    `w'
          recenter target

    `W'
          recenter all

    `h'
          halt

    `H'
          halt all

    `@'
          select center of motion (e.g. `g 3 @')

    `L'
          Look At object

Viewing

    `0vp'
          Orthographic view

    `1vp'
          Perspective view

    `vd'
          Draw other views' cameras

    `#vv'
          field of View

    `#vn'
          near clip distance

    `#vf'
          far clip distance

    `v+'
          add new camera

    `vx'
          cursor on/off

    `vb'
          backfacing poly cull on/off

    `#vl'
          focal length

    `v~'
          Software shading on/off

Panels

    `Pm'
          Main

    `Pa'
          Appearance

    `Pl'
          Lighting

    `Po'
          Obscure

    `Pt'
          Tools

    `Pc'
          Cameras

    `PC'
          Commands

    `Pf'
          Files

    `Ps'
          Save

    `P-'
          read commands from tty

    `PA'
          Credits ("about")

Lights

    `ls'
          show lights

    `le'
          edit lights

Space

    `me'
          Euclidean

    `mh'
          Hyperbolic

    `ms'
          Spherical

Model

    `mv'
          Virtual

    `mp'
          Projective

    `mc'
          Conformal

Other

    `0N'
          normalizaton: none

    `1N'
          normalization: each

    `2N all'
          normalization: all

    `ui'
          motion: Inertia

    `uc'
          motion: Constrain to axis

    `uo'
          motion: object's Own coordinates

    `<'

    `Pf'
          load geometry/command file

    `dd'
          delete target object

    `>'

    `Ps'
          save state to file

    `TV'
          NTSC mode toggle

    `p'
          pick as target object (e.g. `g 3 p')     With no prefix,
          selects the object under the     mouse cursor (like
          double-clicking the right mouse)


File: geomview,  Node: OOGL File Formats,  Next: Conventions,  Prev: Keyboard Shortcuts,  Up: Top

OOGL File Formats
*****************

   The objects that you can load into Geomview are called OOGL objects.
OOGL stands for "Object Oriented Graphics Library"; it is the library
upon which Geomview is built.

   There are many different kinds of OOGL objects.  This chapter gives
syntactic descriptions of file formats for OOGL objects.

   Examples of most file types live in Geomview's `data/geom' directory.

* Menu:

* Conventions::                   Conventions.
* Object File Formats::           Object File Formats.
* Non-geometric objects::         Non-geometric objects.


File: geomview,  Node: Conventions,  Next: Common syntax,  Prev: OOGL File Formats,  Up: OOGL File Formats

Conventions
===========

* Menu:

* Common syntax::                  Syntax Common to All OOGL File Formats.
* File names::                     File Names.
* Vertices::                       Vertices.
* Surface normal directions::      Surface normal directions.
* Transformation matrices::        Transformation matrices.
* Binary format::                  Binary format.
* References::                     Embedded objects and external-object references.
* Appearances::                    Appearances.


File: geomview,  Node: Common syntax,  Next: File names,  Prev: Conventions,  Up: Conventions

Syntax Common to All OOGL File Formats
--------------------------------------

   Most OOGL object file formats are free-format ASCII -- any amount of
white space (blanks, tabs, newlines) may appear between tokens (numbers,
key words, etc.).  Line breaks are almost always insignificant, with a
couple of exceptions as noted.  Comments begin with # and continue to
the end of the line; they're allowed anywhere a newline is.

   Binary formats are also defined for several objects; *Note Binary
format::, and the individual object descriptions.

   Typical OOGL objects begin with a key word designating object type,
possibly with modifiers indicating presence of color information etc.
In some formats the key word is optional, for compatibility with file
formats defined elsewhere.  Object type is then determined by guessing
from the file suffix (if any) or from the data itself.

   Key words are case sensitive.  Some have optional prefix letters
indicating presence of color or other data; in this case the order of
prefixes is significant, e.g. `CNMESH' is meaningful but `NCMESH' is
invalid.


File: geomview,  Node: File names,  Next: Vertices,  Prev: Common syntax,  Up: Conventions

File Names
----------

   When OOGL objects are read from disk files, the OOGL library uses the
file suffix to guess at the file type.

   If the suffix is unrecognized, or if no suffix is available (e.g.
for an object being read from a pipe, or embedded in another OOGL
object), all known types of objects are tried in turn until one accepts
the data as valid.


File: geomview,  Node: Vertices,  Next: Surface normal directions,  Prev: File names,  Up: Conventions

Vertices
--------

   Several objects share a common style of representing vertices with
optional per-vertex surface-normal and color.  All vertices within an
object have the same format, specified by the header key word.

   All data for a vertex is grouped together (as opposed to e.g. giving
coordinates for all vertices, then colors for all vertices, and so on).

   The syntax is

`X  Y  Z'
     (3-D floating-point vertex coordinates) or

`X  Y  Z  W'
     (4-D floating-point vertex coordinates)

   optionally followed by

`NX  NY  NZ'
     (normalized 3-D surface-normal if present)

   optionally followed by

`R  G  b  A'
     (4-component floating-point color if present, each component in
     range 0..1.  The A (alpha) component represents opacity: 0
     transparent, 1 opaque.)

     optionally followed by

`S T'

`or'

`S T U'
   (two or three texture-coordinate values).

   Values are separated by white space, and line breaks are immaterial.

   Letters in the object's header key word must appear in a specific
order; that's the reverse of the order in which the data is given for
each vertex.  So a `CN4OFF' object's vertices contain first the
4-component space position, then the 3-component normal, finally the
4-component color.  You can't change the data order by changing the
header key word; an `NCOFF' is just not recognized.


File: geomview,  Node: Surface normal directions,  Next: Transformation matrices,  Prev: Vertices,  Up: Conventions

Surface normal directions
-------------------------

   Geomview uses normal vectors to determine how an object is shaded.
The direction of the normal is significant in this calculation.

   When normals are supplied with an object, the direction of the normal
is determined by the data given.

   When normals are not supplied with the object, Geomview computes
normal vectors automatically; in this case normals point toward the
side from which the vertices appear in counterclockwise order.

   On parametric surfaces (Bezier patches), the normal at point P(u,v)
is in the direction dP/du cross dP/dv.


File: geomview,  Node: Transformation matrices,  Next: Binary format,  Prev: Surface normal directions,  Up: Conventions

Transformation matrices
-----------------------

   Some objects incorporate 4x4 real matrices for homogeneous object
transformations.  These matrices act by multiplication on the right of
vectors.  Thus, if p is a 4-element row vector representing homogeneous
coordinates of a point in the OOGL object, and A is the 4x4 matrix, then
the transformed point is p' = p A.  This matrix convention is common in
computer graphics; it's the transpose of that often used in mathematics,
where points are column vectors multiplied on the right of matrices.

   Thus for Euclidean transformations, the translation components
appear in the fourth row (last four elements) of A.  A's last column
(4th, 8th, 12th and 16th elements) are typically 0, 0, 0, and 1
respectively.


File: geomview,  Node: Binary format,  Next: References,  Prev: Transformation matrices,  Up: Conventions

Binary format
-------------

   Many OOGL objects accept binary as well as ASCII file formats.
These files begin with the usual ASCII token (e.g. `CQUAD') followed by
the word `BINARY'.  Binary data begins at the byte following the first
newline after `BINARY'.  White space and a single comment may
intervene, e.g.

     OFF BINARY	# binary-format "OFF" data follows

   Binary data comprise 32-bit integers and 32-bit IEEE-format floats,
both in big-endian format (i.e., with most significant byte first).
This is the native format for 'int's and 'float's on Sun-3's, Sun-4's,
and Irises, among others.

   Binary data formats resemble the corresponding ASCII formats, with
ints and floats in just the places you'd expect.  There are some
exceptions though, specifically in the `QUAD', `OFF' and `COMMENT' file
formats.  Details are given in the individual file format descriptions.
*Note QUAD::, *Note OFF::, and *Note COMMENT::.

   Binary OOGL objects may be freely mixed in ASCII object streams:

     LIST
     { = MESH BINARY
     ... binary data for mesh here ...
     }
     { = QUAD
     	1 0 0   0 0 1   0 1 0  0 1 0
     }

   Note that ASCII data resumes immediately following the last byte of
binary data.

   Naturally, it's impossible to embed comments inside a binary-format
OOGL object, though comments may appear in the header before the
beginning of binary data.


File: geomview,  Node: References,  Next: Appearances,  Prev: Binary format,  Up: Conventions

Embedded objects and external-object references
-----------------------------------------------

   Some object types (`LIST', `INST') allow references to other OOGL
objects, which may appear literally in the data stream, be loaded from
named disk files, or be communicated from elsewhere via named objects.
Gcl commands also accept geometry in these forms.

   The general syntax is

      <oogl-object>  ::=
     	[ "{" ]
     	    [ "define" `symbolname' ]
     	    [ "appearance" `appearance' ]
     	    [ ["="] `object-keyword' ...
     		 | "<" `filename'
     		 | ":" `symbolname' ]
     	[ "}" ]

   where "quoted" items are literal strings (which appear without the
quotes), [bracketed] items are optional, and | denotes alternatives.
Curly braces, when present, must match; the outermost set of curly
braces is generally required when the object is in a larger context,
e.g. when it is part of a larger object or embedded in a Geomview
command stream.

   For example, each of the following three lines:
     	{ define fred   QUAD 1 0 0  0 0 1  0 1 0  1 0 0 }
     
     	{ appearance { +edge } LIST { < "file1" } { : fred } }
     
     	VECT 1 2 0   2 0   0 0 0   1 1 2

is a valid OOGL object.  The last example is only valid when it is
delimited unambiguously by residing in its own disk file.

   The "<" construct causes a disk file to be read.  Note that this
isn't a general textual "include" mechanism; a complete OOGL object
must appear in the referenced file.

   Files read using "<" are sought first in the directory of the file
which referred to them, if any; failing that, the normal search path
(set by Geomview's `load-path' command) is used.  The default search
looks first in the current directory, then in the Geomview data
directories.

   The ":" construct allows references to symbols, created with
`define'.  A symbol's initial value is a null object.  When a symbol is
(re)defined, all references to it are automatically changed; this is a
crucial part of the support for interprocess communication.  Some
future version of the documentation should explain this better...

   Again, white space and line breaks are insignificant, and "#"
comments may appear anywhere.


File: geomview,  Node: Appearances,  Next: Texture Mapping,  Prev: References,  Up: Conventions

Appearances
-----------

   Geometric objects can have associated "appearance" information,
specifying shading, lighting, color, wireframe vs. shaded-surface
display, and so on.  Appearances are inherited through object
hierarchies, e.g. attaching an appearance to a `LIST' means that the
appearance is applied to all the `LIST''s members.

   Some appearance-related properties are relegated to "material" and
"lighting" substructures.  Take care to note which properties belong to
which structure.

   Here's an example appearance structure including values for all
attributes.  Order of attributes is unimportant.  As usual, white space
is irrelevant.  Boolean attributes may be preceded by "+" or "-" to turn
them on or off; "+" is assumed if only the attribute name appears.
Other attributes expect values.

   A "*" prefix on any attribute, e.g. "*+edge" or "*linewidth 2" or
"material { *diffuse 1 1 .25 }", selects "override" status for that
attribute.

     appearance {
       +face               # (Do) draw faces of polygons.  On by default.
       -edge               # (Don't) draw edges of polygons
       +vect               # (Do) draw VECTs.  On by default.
       -transparent        # (Disable) transparency. enabling transparency
                           # does NOT result in a correct Geomview picture,
                           # but alpha values are used in RenderMan snapshots.
       -normal             # (Do) draw surface-normal vectors
       normscale 1         # ... with length 1.0 in object coordinates
     
       +evert              # do evert polygon normals where needed so as
                           #   to always face the camera
     
       -texturing          # (Disable) texture mapping
       -backcull           # (Don't) discard clockwise-oriented faces
       -concave            # (Don't) expect and handle concave polygons
       -shadelines	      # (Don't) shade lines as if they were lighted cylinders
     		      # These four are only effective where the graphics system
     		      # supports them, namely on GL and Open GL.
     
       -keepcolor	      # Normally, when N-D positional coloring is enabled as
     		      # with geomview's (ND-color ...) command, all
     		      # objects' colors are affected.  But, objects with the
     		      # "+keepcolor" attribute are immune to N-D coloring.
     
       shading smooth      # or ``shading constant'' or ``shading flat'' or
                           # or ``shading csmooth''.
                           # smooth = Gouraud shading, flat = faceted,
                           # csmooth = smoothly interpolated but unlighted.
     
       linewidth 1         # lines, points, and edges are 1 pixel wide.
     
       patchdice 10 10     # subdivide Bezier patches this finely in u and v
     
       material {         # Here's a material definition;
                           # it could also be read from a file as in
                           #  ``material < file.mat''
     
           ka  1.0         # ambient reflection coefficient.
           ambient .3 .5 .3 # ambient color (red, green, blue components)
                           # The ambient contribution to the shading is
                           # the product of ka, the ambient color,
                           # and the color of the ambient light.
     
           kd  0.8         # diffuse-reflection coefficient.
           diffuse .9 1 .4 # diffuse color.
                             # (In ``shading constant'' mode, the surface
                             # is colored with the diffuse color.)
     
           ks 1.0          # specular reflection coefficient.
           specular 1 1 1  # specular (highlight) color.
           shininess  25   # specular exponent; larger values give
                           # sharper highlights.
     
           backdiffuse .7 .5 0 # back-face color for two-sided surfaces
                             # If defined, this field determines the diffuse
                             # color for the back side of a surface.
                             # It's implemented by the software shader, and
                             # by hardware shading on GL systems which support
                             # two-sided lighting, and under Open GL.
     
           alpha   1.0     # opacity; 0 = transparent (invisible), 1 = opaque.
                           # Ignored when transparency is disabled.
     
           edgecolor   1 1 0  # line & edge color
     
           normalcolor 0 0 0  # color for surface-normal vectors
       }
     
       lighting {         # Lighting model
     
           ambient  .3 .3 .3  # ambient light
     
           replacelights   # ``Use only the following lights to
                           # illuminate the objects under this
                           # appearance.''
                           # Without "replacelights", any lights listed
                           # are added to those already in the scene.
     
                           # Now a collection of sample lights:
           light {
               color  1 .7 .6      # light color
               position  1 0 .5 0  # light position [distant light]
                                   # given in homogeneous coordinates.
                                   # With fourth component = 0,
                                   # this means a light coming from
                                   # direction (1,0,.5).
           }
     
           light {                        # Another light.
               color 1 1 1
               position  0 0 .5 1  # light at finite position ...
               location camera     # specified in camera coordinates.
                                   # (Since the camera looks toward -Z,
                                   # this example places the light
                                   # .5 unit behind the eye.)
               # Possible "location" keywords:
               #  global    light position is in world (well, universe) coordinates
               #             This is the default if no location specified.
               #  camera   position is in the camera's coordinate system
               #  local    position is in the coordinate system where
               #                   the appearance was defined
           }
       }                   # end lighting model
       texture {
             clamp st               # or ``s'' or ``t'' or ``none''
             file lump.tiff         # file supplying texture-map image
             alphafile mask.pgm.Z   # file supplying transparency-mask image
             apply blend            # or ``modulate'' or ``decal''
             transform  1 0 0 0     # surface (s,t,0,1) * tfm -> texture coords
                        0 1 0 0
                        0 0 1 0
                       .5 0 0 1
     
             background 1 0 0 1     # relevant for ``apply blend''
       }
     }                     # end appearance

   There are rules for inheritance of appearance attributes when several
are imposed at different levels in the hierarchy.

   For example, Geomview installs a backstop appearance which provides
default values for most parameters; its control panels install other
appearances which supply new values for a few attributes; user-supplied
geometry may also contain appearances.

   The general rule is that the child's appearance (the one closest to
the geometric primitives) wins.  Further, appearance controls with
"override" status (e.g. *+face or material { *diffuse 1 1 0 }) win over
those without it.

   Geomview's appearance controls use the "override" feature so as to be
effective even if user-supplied objects contain their own appearance
settings.  However, if a user-supplied object contains an appearance
field with override status set, that property will be immune to
Geomview's controls.


File: geomview,  Node: Texture Mapping,  Next: Object File Formats,  Prev: Appearances,  Up: Conventions

Texture Mapping
---------------

   Some platforms support texture-mapped objects.  (On those which
don't, attempts to use texture mapping are silently ignored.)  A
texture is specified as part of an appearance structure, as in *Note
Appearances::.  Briefly, one provides a texture image, which is
considered to lie in a square in `(s,t)' parameter space in the range 0
<= s <= 1, 0 <= t <= 1.  Then one provides a geometric primitive, with
each vertex tagged with `(s,t)' texture coordinates.  If texturing is
enabled, the appropriate portion of the texture image is pasted onto
each face of the textured object.

   There is (currently) no provision for inheritance of part of a
texture structure; if the `texture' keyword is mentioned in an
appearance, it supplants any other texture specification.

   The appearance attribute `texturing' controls whether textures are
used; there's no performance penalty for having texture { ... } fields
defined when texturing is off.

   The available fields are:

     clamp	none  -or-  s  -or-  t  -or-  st
       Determines the meaning of texture coordinates outside the range 0..1.
       With `clamp none', the default, coordinates are interpreted
       modulo 1, so (s,t) = (1.25,0), (.25,0), and (-.75,0) all refer to
       the same point in texture space.  With `s' or `t' or
       `st', either or both of s- or t-coordinates less than 0 or
       greater than 1 are clamped to 1 or 0, respectively.
     
     file	filename
     alphafile	filename
       Specifies image file(s) containing the texture.
       The `file' file's image specifies color or lightness information;
       the `alphafile' if present, specifies a transparency ("alpha") mask;
       where the mask is zero, pixels are simply not drawn.
       Several image file formats are available; the file type must be
       indicated by the last few characters of the file name:
         .ppm or .ppm.Z or .ppm.gz  24-bit 3-color image in PPM format
         .pgm or .pgm.Z or .pgm.gz  8-bit grayscale image in PGM format
         .sgi or .sgi.Z or .sgi.gz  8-bit, 24-bit, or 32-bit SGI image
         .tiff 		       8-bit or 24-bit TIFF image
         .gif		       GIF image
       (Though 4-channel TIFF images are possible, and could
       represent both color and transparency information in one image,
       that's not supported in geomview at present.)
       For this feature to work, some programs must be available in
       geomview's search path:
         zcat  for .Z files
         gzip  for .gz files
         tifftopnm for .tiff files
         giftoppm for .gif files
     
       If an `alphafile' image is supplied, it must be the same size
       as the `file' image.
     
     
     apply	modulate  -or-  blend  -or-  decal
       Indicates how the texture image is applied to the surface.
       Here the "surface color" means the color that surface would have
       in the absence of texture mapping.
     
       With `modulate', the default, the texture color (or lightness,
       if textured by a gray-scale image) is multiplied by the surface color.
     
       With `blend', texture blends between the `background' color
       and the surface color.  The `file' parameter must specify a
       gray-scale image.  Where the texture image is 0, the surface color is
       unaffected; where it's 1, the surface is painted in the color given
       by `background'; and color is interpolated for intermediate values.
     
       With `decal', the `file' parameter must specify a
       3-color image.  If an `alphafile' parameter is present,
       its value interpolates between the surface color (where alpha=0)
       and the texture color (where alpha=1).  Lighting does not affect the
       texture color in `decal' mode; effectively the texture is
       constant-shaded.
     
     background  R G B A
       Specifies a 4-component color, with R, G, B, and A floating-point
       numbers normally in the range 0..1, used when `apply blend'
       is selected.
     
     transform `transformation-matrix'
       Expects a list of 16 numbers, or one of the other ways of representing
       a transformation (`: handlename' or `< filename').
       The 4x4 transformation matrix is applied to texture coordinates,
       in the sense of a 4-component row vector (s,t,0,1) multiplied on
       the left of the matrix, to produce new coordinates (s',t')
       which actually index the texture.


File: geomview,  Node: Object File Formats,  Next: QUAD,  Prev: Texture Mapping,  Up: OOGL File Formats

Object File Formats
===================

* Menu:

* QUAD::		List of quadrilaterals.
* MESH::		Rectangularly-connected mesh.
* BBP and BEZ::		List of Bezier surface patches.
* OFF::			Polyhedra: polygons with shared vertices.
* VECT::		List of points and lines.
* SKEL::		List of points and lines, with shared vertices.
* SPHERE::		Sphere
* INST::		Transformed Instance of another object.
* LIST::		List of other objects.
* TLIST::		Collection of 4x4 transformation matrices.
* GROUP::		Obsolete format for collections of objects.
* DISCGRP::             Discrete Group objects.
* COMMENT::		Comment object, for caching information.


File: geomview,  Node: QUAD,  Next: MESH,  Prev: Object File Formats,  Up: Object File Formats

QUAD: collection of quadrilaterals
----------------------------------

   The conventional suffix for a `QUAD' file is `.quad'.

   The file syntax is

        [C][N][4]QUAD  -or-  [C][N][4]POLY		   # Key word
        VERTEX  VERTEX  VERTEX  VERTEX  # 4*N vertices for some N
        VERTEX  VERTEX  VERTEX  VERTEX
        ...

   The leading key word is `[C][N][4]QUAD' or `[C][N][4]POLY', where
the optional `C' and `N' prefixes indicate that each vertex includes
colors and normals respectively.  That is, these files begin with one
of the words

   `QUAD' `CQUAD' `NQUAD' `CNQUAD' `POLY' `CPOLY' `NPOLY' `CNPOLY'

   (but not `NCQUAD' or `NCPOLY').  `QUAD' and `POLY' are synonymous;
both forms are allowed just for compatibility with ChapReyes.

   Following the key word is an arbitrary number of groups of four
vertices, each group describing a quadrilateral.  See the Vertex syntax
above.  The object ends at end-of-file, or with a closebrace if
incorporated into an object reference (see above).

   A `QUAD BINARY' file format is accepted; *Note Binary format::.  The
first word of binary data must be a 32-bit integer giving the number of
quads in the object; following that is a series of 32-bit floats,
arranged just as in the ASCII format.


File: geomview,  Node: MESH,  Next: BBP and BEZ,  Prev: QUAD,  Up: Object File Formats

MESH: rectangularly-connected mesh
----------------------------------

   The conventional suffix for a `MESH' file is `.mesh'.

   The file syntax is

     [U][C][N][Z][4][u][v][n]MESH # Key word
     [NDIM]                 # Space dimension, present only if nMESH
     NU NV            # Mesh grid dimensions
                                  # NU*NV vertices, in format specified
                                  # by initial key word
     VERTEX(u=0,v=0)  VERTEX(1,0)  ... VERTEX(NU-1,0)
     VERTEX(0,1) ...    VERTEX(NU-1,1)
     ...
     VERTEX(0,NV-1) ... VERTEX(NU-1,NV-1)

   The key word is  `[U][C][N][Z][4][u][v][n]MESH'.  The optional
prefix characters mean:

`U'
     Each vertex includes a 3-component texture space parameter.  The
     first two components are the usual `S' and `T' texture parameters
     for that vertex; the third should be specified as zero.

`C'
     Each vertex (see Vertices above) includes a 4-component color.

`N'
     Each vertex includes a surface normal vector.

`Z'
     Of the 3 vertex position values, only the Z component is present;
     X and Y are omitted, and assumed to equal the mesh (u,v)
     coordinate so X ranges from 0 .. (Nu-1), Y from 0 .. (Nv-1) where
     Nu and Nv are the mesh dimensions - see below.

`4'
     Vertices are 4D, each consists of 4 floating values.  `Z' and `4'
     cannot both be present.

`u'
     The mesh is wrapped in the u-direction, so the (0,v)'th vertex is
     connected to the (NU-1,v)'th for all v.

`v'
     The mesh is wrapped in the v-direction, so the (u,0)'th vertex is
     connected to the (u,NV-1)'th for all u.  Thus a u-wrapped or
     v-wrapped mesh is topologically a cylinder, while a uv-wrapped
     mesh is a torus.

`n'
     Specifies a mesh whose vertices live in a higher dimensional space.
     The dimension follows the "MESH" keyword.  Each vertex then has
     NDIM components.

   Note that the order of prefix characters is significant; a colored,
u-wrapped mesh is a `CuMESH' not a `uCMESH'.

   Following the mesh header are integers NU and NV, the dimensions of
the mesh.

   Then follow NU*NV vertices, each in the form given by the header.
They appear in v-major order, i.e. if we name each vertex by (u,v) then
the vertices appear in the order

     (0,0) (1,0) (2,0) (3,0) ...  (NU-1,0)
     (0,1) (1,1) (2,1) (3,1) ...  (NU-1,1)
     ...
     (0,Nv-1)		...  (NU-1,NV-1)

   A `MESH BINARY' format is accepted; *Note Binary format::.  The
values of NU and NV are 32-bit integers; all other values are 32-bit
floats.


File: geomview,  Node: BBP and BEZ,  Next: OFF,  Prev: MESH,  Up: Object File Formats

Bezier Surfaces
---------------

   The conventional file suffixes for Bezier surface files are `.bbp'
or `.bez'.  A file with either suffix may contain either type of patch.

   Syntax:

       [ST]BBP -or- [C]BEZ<NU><NV><ND>[_ST]
     			# NU, NV are u- and v-direction
     			# polynomial degrees in range 1..6
     			# ND = dimension: 3->3-D, 4->4-D (rational)
     			# (The '<' and '>' do not appear in the input.)
     			# NU,NV,ND are each a single decimal digit.
     			# BBP form implies NU=NV=ND=3 so BBP = BEZ333.
     
     		# Any number of patches follow the header
     			# (NU+1)*(NV+1) patch control points
     			# each 3 or 4 floats according to header
       VERTEX(u=0,v=0)  VERTEX(1,0) ... VERTEX(NU,0)
       VERTEX(0,1)			   ... VERTEX(NU,1)
       ...
       VERTEX(0,NV)		   ... VERTEX(NU,NV)
     
     			# ST texture coordinates if mentioned in header
       `S'(u=0,v=0)	`T'(0,0)	`S'(0,NV) `T'(0,NV)
       `S'(NU,0)	`T'(NU,0)	`S'(NU,NV) `T'(NU,NV)
     
     			# 4-component float (0..1) R G B A colors
     			# for each patch corner if mentioned in header
       `RGBA'(0,0)   `RGBA'(0,NV)
       `RGBA'(NU,0)  `RGBA'(NU,NV)

   These formats represent collections of Bezier surface patches, of
degrees up to 6, and with 3-D or 4-D (rational) vertices.

   The header keyword has the forms `[ST]BBP' or
`[C]BEZ<NU><NV><ND>[_ST]' (the '<' and '>' are not part of the keyword.

   The `ST' prefix on `BBP', or `_ST' suffix on `BEZuvn', indicates
that each patch includes four pairs of floating-point texture-space
coordinates, one for each corner of the patch.

   The `C' prefix on `BEZuvn' indicates a colored patch, including four
sets of four-component floating-point colors (red, green, blue, and
alpha) in the range 0..1, one color for each corner.

   NU and NV, each a single digit in the range 1..6, are the patch's
polynomial degree in the u and v direction respectively.

   ND is the number of components in each patch vertex, and must be
either `3' for 3-D or `4' for homogeneous coordinates, that is,
rational patches.

   `BBP' patches are bicubic patches with 3-D vertices, so `BBP' =
`BEZ333' and `STBBP' = `BEZ333_ST'.

   Any number of patches follow the header.  Each patch comprises a
series of patch vertices, followed by optional (s,t) texture
coordinates, followed by optional (r,g,b,a) colors.

   Each patch has (NU+1)*(NV+1) vertices in v-major order, so that if we
designate a vertex by its control point indices (u,v) the order is
          (0,0) (1,0) (2,0) ...  (NU,0)
          (0,1) (1,1) (2,1) ...  (NU,1)
          ...
          (0,NV)            ...  (NU,NV)

with each vertex containing either 3 or 4 floating-point numbers as
specified by the header.

   If the header calls for ST coordinates, four pairs of floating-point
numbers follow: the texture-space coordinates for the (0,0), (NU,0),
(0,NV), and (NU,NV) corners of the patch, respectively.

   If the header calls for colors, four four-component (red, green,
blue, alpha) floating-point colors follow, one for each patch corner.

   The series of patches ends at end-of-file, or with a closebrace if
incorporated in an object reference.

