OOGL(5gv)
OOGL(5gv)
NAME
OOGL - File formats for OOGL geometric objects
NOTE
The material in this manual page also appears in the
Geomview manual.
DESCRIPTION
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.
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 insignif-
icant, 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 ob-
ject type,
possibly with modifiers indicating presence of color in-
formation etc.
In some formats the key word is optional, for compatibili-
ty 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 Names
----------
When OOGL objects are read from disk files, the OOGL li-
brary uses the
file suffix to guess at the file type.
If the suffix is unrecognized, or if no suffix is avail-
able (e.g. for an
Geometry Center Thu Dec 12 02:36:08 CST 1996 1
OOGL(5) OOGL(5)
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.
Vertices
--------
Several objects share a common style of representing ver-
tices with
optional per-vertex surface-normal and color. All ver-
tices 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 ver-
tices, and so on).
The syntax is
`X Y Z' (3-D floating-point vertex coordi-
nates) or
`X Y Z W' (4-D floating-point vertex coor-
dinates)
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 (al-
pha) 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-compo-
nent space
position, then the 3-component normal, finally the 4-com-
ponent color.
You can't change the data order by changing the header key
word; an
`NCOFF' is just not recognized.
Surface normal directions
-------------------------
Geometry Center Thu Dec 12 02:36:08 CST 1996 2
OOGL(5) OOGL(5)
Geomview uses normal vectors to determine how an object is
shaded.
The direction of the normal is significant in this calcu-
lation.
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.
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 represent-
ing 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 compo-
nents 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 re-
spectively.
Binary format
-------------
Many OOGL objects accept binary as well as ASCII file for-
mats.
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-for-
mat 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 for-
mats, 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 COM-
MENT
::.
Binary OOGL objects may be freely mixed in ASCII object
streams:
Geometry Center Thu Dec 12 02:36:08 CST 1996 3
OOGL(5) OOGL(5)
LIST { = MESH BINARY ... bi-
nary 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 bi-
nary-format OOGL
object, though comments may appear in the header before
the beginning of
binary data.
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' ] [ ["="] `ob-
ject-keyword' ... | "<" `filename'
| ":" `symbolname' ] [
"}" ]
where "quoted" items are literal strings (which appear
without the
quotes), [bracketed] items are optional, and | denotes al-
ternatives.
Curly braces, when present, must match; the outermost set
of curly
braces is generally required when the object is in a larg-
er 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 ob-
ject must appear
in the referenced file.
Geometry Center Thu Dec 12 02:36:08 CST 1996 4
OOGL(5) OOGL(5)
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 automati-
cally 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.
Appearances
-----------
Geometric objects can have associated "appearance" infor-
mation,
specifying shading, lighting, color, wireframe vs. shaded-
surface
display, and so on. Appearances are inherited through ob-
ject
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 "mate-
rial" and
"lighting" substructures. Take care to note which proper-
ties belong to
which structure.
Here's an example appearance structure including values
for all
attributes. Order of attributes is unimportant. As usu-
al, 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 trans-
parency # 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 al-
ways face the camera
-texturing # (Disable) texture mapping
-backcull # (Don't) discard clock-
wise-oriented faces
Geometry Center Thu Dec 12 02:36:08 CST 1996 5
OOGL(5) OOGL(5)
-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 ge-
omview'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 coeffi-
cient. ambient .3 .5 .3 # ambient color (red,
green, blue components) # The
ambient contribution to the shading is
# the product of ka, the ambi-
ent color, # and the color of
the ambient light.
kd 0.8 # diffuse-reflection coeffi-
cient. diffuse .9 1 .4 # diffuse color.
# (In "shading constant"
mode, the surface # is col-
ored with the diffuse color.)
ks 1.0 # specular reflection coeffi-
cient. 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 implement-
ed by the software shader, and
# by hardware shading on GL systems which support
# two-sided lighting, and un-
der Open GL.
alpha 1.0 # opacity; 0 = transparent (in-
visible), 1 = opaque. # Ig-
nored when transparency is disabled.
edgecolor 1 1 0 # line & edge color
normalcolor 0 0 0 # color for surface-normal
vectors }
Geometry Center Thu Dec 12 02:36:08 CST 1996 6
OOGL(5) OOGL(5)
lighting { # Lighting model
ambient .3 .3 .3 # ambient light
replacelights # "Use only the following
lights to # illuminate the ob-
jects 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 posi-
tion 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 "lo-
cation" keywords: # global light posi-
tion 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
Geometry Center Thu Dec 12 02:36:08 CST 1996 7
OOGL(5) OOGL(5)
default values for most parameters; its control panels in-
stall 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 Ge-
omview's controls.
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 tex-
ture image,
which is considered to lie in a square in `(s,t)' parame-
ter 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 ap-
pearance,
it supplants any other texture specification.
The appearance attribute `texturing' controls whether tex-
tures 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 transparen-
cy ("alpha") mask; where the mask is zero, pixels
are simply not drawn. Several image file formats
are available; the file type must be
Geometry Center Thu Dec 12 02:36:08 CST 1996 8
OOGL(5) OOGL(5)
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 rep-
resent 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 sur-
face 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 `back-
ground' color and the surface color. The `file'
parameter must specify a gray-scale image. Where
the texture image is 0, the surface color is unaf-
fected; where it's 1, the surface is painted in the color given
by `background'; and color is interpolated for in-
termediate 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-com-
ponent 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' Ex-
pects a list of 16 numbers, or one of the other ways of repre-
senting a transformation (`: handlename' or `<
filename'). The 4x4 transformation matrix is ap-
plied 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.
Geometry Center Thu Dec 12 02:36:08 CST 1996 9
OOGL(5) OOGL(5)
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 ver-
tices 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 compati-
bility 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 close-
brace if
incorporated into an object reference (see above).
A `QUAD BINARY' file format is accepted; *Note Binary for-
mat::. 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.
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)
Geometry Center Thu Dec 12 02:36:08 CST 1996 10
OOGL(5) OOGL(5)
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 vec-
tor.
`Z' Of the 3 vertex position values, only the
Z component is present; X and Y are omitted, and as-
sumed 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 float-
ing 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 compo-
nents.
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.
Bezier Surfaces
---------------
Geometry Center Thu Dec 12 02:36:08 CST 1996 11
OOGL(5) OOGL(5)
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 (ra-
tional) # (The '<' and '>' do not ap-
pear 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) ... VER-
TEX(NU,0) VERTEX(0,1) ... VER-
TEX(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 men-
tioned 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 col-
ors (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 respec-
tively.
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.
Geometry Center Thu Dec 12 02:36:08 CST 1996 12
OOGL(5) OOGL(5)
`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 com-
prises a series
of patch vertices, followed by optional (s,t) texture co-
ordinates,
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.
Info file: geomview, -*-Text-*-
produced by texinfo-format-buffer
from file: geomview.tex
OFF Files
---------
The conventional suffix for `OFF' files is `.off'.
Syntax:
[ST][C][N][4][n]OFF # Header keyword
[NDIM] # Space dimension of vertices, present only if
nOFF NVERTICES NFACES NEDGES # NEdges not used or
checked
X[0] Y[0] Z[0] # Vertices, possibly with nor-
mals, # colors, and/or texture coordi-
nates, in that order, # if the prefix-
es `N', `C', `ST' # are present.
# If 4OFF, each vertex has 4 compo-
nents, # including a final homogeneous
component. # If nOFF, each vertex has
NDIM components. # If 4nOFF, each
vertex has NDIM+1 components. ...
X
[NVERTICES-1] Y[NVERTICES-1] Z[NVERTICES-1]
Geometry Center Thu Dec 12 02:36:08 CST 1996 13
OOGL(5) OOGL(5)
# Faces #
NV
= # vertices on this face # V[0]
... V[NV-1]: vertex indices #
in range 0..NVERTICES-1 NV V[0] V[1] ... V[NV-1]
COLORSPEC
... # COLORSPEC
continues past V[NV-1] # to end-of-
line; may be 0 to 4 numbers # nothing:
default # integer: colormap index
# 3 or 4 integers: RGB[A] values
0..255 # 3 or 4 floats: RGB[A] values
0..1
`OFF' files (name for "object file format") represent col-
lections
of planar polygons with possibly shared vertices, a conve-
nient way to
describe polyhedra. The polygons may be concave but
there's no
provision for polygons containing holes.
An `OFF' file may begin with the keyword `OFF'; it's
recommended but optional, as many existing files lack this
keyword.
Three ASCII integers follow: NVERTICES, NFACES, and
NEDGES. Thse are the number of vertices, faces, and
edges,
respectively. Current software does not use nor check
NEDGES
; it
needn't be correct but must be present.
The vertex coordinates follow: dimension * NVERTICES
floating-point values. They're implicitly numbered 0
through
NVERTICES-1. dimension is either 3 (default) or 4 (speci-
fied by
the key character `4' directly before `OFF' in the key-
word).
Following these are the face descriptions, typically writ-
ten
with one line per face. Each has the form N
VERT1 VERT2 ... VERTN [COLOR]
Here N is the number of vertices on this face,
and VERT1 through VERTN are indices into the list of
vertices (in the range 0..NVERTICES-1).
The optional COLOR may take several forms. Line breaks
are
significant here: the COLOR description begins after VERTN
and ends with the end of the line (or the next # comment).
A
COLOR may be:
nothing the default color
one integer index into "the" colormap; see be-
low
three or four integers RGB and possibly alpha
values in the range 0..255
three or four floating-point numbers RGB and
possibly alpha values in the range 0..1
For the one-integer case, the colormap is currently read
from the file
`cmap.fmap' in Geomview's `data' directory. Some better
Geometry Center Thu Dec 12 02:36:08 CST 1996 14
OOGL(5) OOGL(5)
mechanism for supplying a colormap is likely someday.
The meaning of "default color" varies. If no face of the
object has a
color, all inherit the environment's default material col-
or. If some
but not all faces have colors, the default is gray
(R,G,B,A=.666).
A `[ST][C][N][n]OFF BINARY' format is accepted; *Note Bi-
nary format::. It
resembles the ASCII format in almost the way you'd expect,
with 32-bit
integers for all counters and vertex indices and 32-bit
floats for
vertex positions (and texture coordinates or vertex colors
or normals if
`COFF'/`NOFF'/`CNOFF'/`STCNOFF'/etc. format).
Exception: each face's vertex indices are followed by an
integer
indicating how many color components accompany it. Face
color
components must be floats, not integer values. Thus a
colorless
triangular face might be represented as
int int int int int 3 17 5 9 0
while the same face colored red might be
int int int int int float float float float
3 17 5 9 4 1.0 0.0 0.0 1.0
VECT Files
----------
The conventional suffix for `VECT' files is `.vect'.
Syntax:
[4]VECT NPOLYLINES NVERTICES NCOLORS
NV[0] ... NV[NPOLYLINES-1] # number of vertices
# in each
polyline
NC[0] ... NC[NPOLYLINES-1] # number of colors
supplied #
in each polyline
VERT[0] ... VERT[NVERTICES-1] # All the vertices
# (3*NVer-
tices floats)
COLOR[0] ... COLOR[NCOLORS-1] # All the colors
# (4*NCol-
ors floats, RGBA)
`VECT' objects represent lists of polylines (strings of
connected
line segments, possibly closed). A degenerate polyline
can be used to
represent a point.
A `VECT' file begins with the key word `VECT' or `4VECT'
Geometry Center Thu Dec 12 02:36:08 CST 1996 15
OOGL(5) OOGL(5)
and three integers: NLINES, NVERTICES, and NCOLORS.
Here NLINES is the number of polylines in the file,
NVERTICES the total number of vertices, and NCOLORS the
number of colors as explained below.
Next come NLINES integers
NV[0] NV[1] NV[2] ... NV[NLINES-1]
giving the number of vertices in each polyline. A nega-
tive number
indicates a closed polyline; 1 denotes a single-pixel
point. The sum
(of absolute values) of the NV[I] must equal NVERTICES.
Next come NLINES more integers Nc[i]: the number of colors
in
each polyline. Normally one of three values:
0 No color is specified for this polyline.
It's drawn in the same color as the previous poly-
line.
1 A single color is specified. The entire
polyline is drawn in that color.
abs(NV[I]) Each vertex has a color. Either
each segment is drawn in the corresponding color, or
the colors are smoothly interpolated along the line
segments, depending on the implementation.
The sum of the NC[I] must equal NCOLORS.
Next come NVERTICES groups of 3 or 4 floating-point num-
bers: the
coordinates of all the vertices. If the keyword is 4VECT
then
there are 4 values per vertex. The first abs(NV[0]) of
them form
the first polyline, the next abs(NV[1]) form the second
and so on.
Finally NCOLORS groups of 4 floating-point numbers give
red,
green, blue and alpha (opacity) values. The first NC[0]
of them
apply to the first polyline, and so on.
A VECT BINARY format is accepted; *Note Binary format::.
The
binary format exactly follows the ASCII format, with
32-bit ints where
integers appear, and 32-bit floats where real values ap-
pear.
SKEL Files
----------
`SKEL' files represent collections of points and poly-
lines, with
shared vertices.
The conventional suffix for `SKEL' files is `.skel'.
Syntax:
Geometry Center Thu Dec 12 02:36:08 CST 1996 16
OOGL(5) OOGL(5)
[4][n]SKEL [NDIM] #
Vertex dimension, present only if nSKEL NVERTICES
NPOLYLINES
X[0] Y[0] Z[0] # Vertices
# (if nSKEL, each vertex has
NDim components) ... X[NVERTICES-1]
Y
[NVERTICES-1] Z[NVERTICES-1]
# Polylines
# NV = # vertices on this
polyline (1 = point) # V[0]
... V[NV-1]: vertex indices #
in range 0..NVERTICES-1 NV V[0] V[1] ... V[NV-1]
[COLORSPEC] ...
# COLORSPEC continues past V[NV-1]
# to end-of-line; may be
nothing, or 3 or 4 numbers.
# nothing: default color # 3 or 4
floats: RGB[A] values 0..1
The syntax resembles that of `OFF' files, with a table of
vertices
followed by a sequence of polyline descriptions, each re-
ferring to vertices
by index in the table. Each polyline has an optional col-
or.
For `nSKEL' objects, each vertex has NDIM components.
For `4nSKEL' objects, each vertex has NDIM+1 components;
the final component is the homogeneous divisor.
No `BINARY' format is implemented as yet for `SKEL' ob-
jects.
SPHERE Files
------------
The conventional suffix for `SPHERE' files is `.sph'.
SPHERE RADIUS XCENTER YCENTER
ZCENTER
Sphere objects are drawn using rational Bezier patches,
which are diced into
meshes; their smoothness, and the time taken to draw them,
depends on the
setting of the dicing level, 10x10 by default.
From Geomview, the Appearance panel, the `<N>ad' keyboard
command, or
a `dice nu nv' Appearance attribute sets this.
INST Files
----------
The conventional suffix for a `INST' file is `.inst'.
There is no INST BINARY format.
An `INST' applies a 4x4 transformation to another OOGL ob-
ject. It
Geometry Center Thu Dec 12 02:36:08 CST 1996 17
OOGL(5) OOGL(5)
begins with `INST' followed by these sections which may
appear in
any order: geom OOGL-OBJECT
specifies the OOGL object to be instantiated. *Note Ref-
erences::, for
the syntax of an OOGL-OBJECT. The keyword `unit' is a
synonym for `geom'. transform ["{"] `4x4
transform' ["}"]
specifies a single transformation matrix. Either the
matrix may appear literally as 16 numbers, or there may be
a reference to a "transform" object, i.e.
"<" file-containing-4x4-matrix
or ":" symbol-representing-transform-ob-
ject>
Another way to specify the transformation is
transforms OOGL-OBJECT
The OOGL-OBJECT must be a `TLIST' object (list of
transformations) object, or a `LIST' whose members are ul-
timately
`TLIST' objects. In effect, the `transforms' keyword
takes a
collection of 4x4 matrices and replicates the `geom' ob-
ject, making
one copy for each 4x4 matrix.
If no `transform' nor `transforms' keyword appears, no
transformation is applied (actually the identity is ap-
plied). You could
use this for, e.g., wrapping an appearance around an ex-
ternally-supplied
object, though a single-membered LIST would do this more
efficiently.
*Note Transformation matrices::, for the matrix format.
Two more INST fields are accepted: `location' and `ori-
gin'.
location [global or camera or ndc or screen or local]
Normally an INST specifies a position relative to its par-
ent object;
the `location' field allows putting an object elsewhere.
* `location global' attaches the object to the global
(a.k.a. universe) coordinate system -- the same as
that in which geomview's World objects, alien geome-
try, and cameras are placed. * `location camera'
places the object relative to the camera. (Thus if
there are multiple views, it may appear in a different
spatial position in each view.) The center of the camera's view
is along its negative Z axis; positive X is right-
ward, positive Y upward. Normally the units of cam-
era space are the same as global coordinates. When a
camera is reset, the global origin is at (0,0,-3.0). *
`location ndc' places the object relative to the normalized unit
cube into which the camera's projection (perspective
or orthographic) maps the visible world. X, Y, and Z
are each in the range from -1 to +1, with Z = -1 the
near and Z = +1 the far clipping plane, and X and Y
increasing rightward and upward respectively. Thus
something like INST transform 1 0 0 0 0 1 0 0
0 0 1 0 -.9 -.9 -.999 1 location ndc
geom < label.vect pastes `la-
bel.vect' onto the lower left corner of each window,
Geometry Center Thu Dec 12 02:36:08 CST 1996 18
OOGL(5) OOGL(5)
and in front of nearly everything else, assuming `la-
bel.vect''s contents lie in the positive quadrant of
the X-Y plane. It's tempting to use -1 rather than
-.999 as the Z component of the position, but that
may put the object just nearer than the near clipping
plane and make it (partially) invisible, due to floating-point
error. * `location screen' places the object in screen
coordinates. The range of Z is still -1 through +1
as for ndc coordinates; X and Y are measured in pix-
els, and range from (0,0) at the *lower left* corner
of the window, increasing rightward and upward.
`location local' is the default; the object is positioned
relative
to its parent.
origin [global or camera or ndc or screen or local] x
y z
The `origin' field translates the contents of the INST to
place the origin at the specified point of the given coor-
dinate system.
Unlike `location', it doesn't change the orientation, only
the choice
of origin. Both `location' and `origin' can be used to-
gether.
So for example { INST location
screen origin ndc 0 0 -.99 geom { <
xyz.vect } transform { 100 0 0 0 0 100 0 0 0 0
-.009 0 0 0 0 1 } }
places xyz.vect's origin in the center of the window, just
beyond the
near clipping plane. The unit-length X and Y edges are
scaled to be just 100
screen units -- pixels -- long, regardless of the size of
the window.
INST Examples .............
Here are some examples of `INST' files
INST unit < xyz.vect
transform { 1 0 0 0
0 1 0 0 0 0 1 0
1 3 0 1 }
{ appearance { +edge material { edgecolor 1 1 0 } }
INST geom < mysurface.quad }
{INST transform {: T} geom {<dodec.off}}
{ INST transforms
{ LIST
Geometry Center Thu Dec 12 02:36:08 CST 1996 19
OOGL(5) OOGL(5)
{ < some-matrices.prj }
{ < others.prj } { TLIST <still more of
them> }
} geom
{ # stuff replicated by all the above matrices
... } }
This one resembles the `origin' example in the section
above,
but makes the X and Y edges be 1/4 the size of the window
(1/4, not 1/2,
since the range of ndc X and Y coordinates is -1 to +1).
{ INST location ndc geom
{ < xyz.vect } transform { .5 0 0 0 0 .5 0 0 0 0
-.009 0 0 0 -.99 1 } }
LIST Files
----------
The conventional suffix for a `LIST' file is `.list'.
A list of OOGL objects
Syntax:
LIST OOGL-OBJECT
OOGL-OBJECT ...
Note that there's no explicit separation between the oogl-
objects, so
they should be enclosed in curly braces ({ }) for sanity.
Likewise
there's no explicit marker for the end of the list; unless
appearing
alone in a disk file, the whole construct should also be
wrapped in
braces, as in:
{ LIST { QUAD ... } { < xyz.quad } }
A `LIST' with no elements, i.e. `{ LIST }', is valid, and
is
the easiest way to create an empty object. For example,
to remove a
symbol's definition you might write
{ define somesymbol { LIST } }
TLIST Files
-----------
Geometry Center Thu Dec 12 02:36:08 CST 1996 20
OOGL(5) OOGL(5)
The conventional suffix for a `TLIST' file is `.grp'
("group")
or or `.prj' ("projective" matrices).
Collection of 4x4 matrices, used in the `transforms' sec-
tion of and
`INST' object.
Syntax:
TLIST # key word
<4x4 matrix (16 floats)>
... # Any number of 4x4 matrices
`TLIST's are used only within the `transforms' clause of
an
`INST' object. They cause the `INST's `geom' object to
be instantiated once under each of the transforms in the
`TLIST'.
The effect is like that of a `LIST' of `INST's each with a
single transform, and all referring to the same object,
but is more
efficient.
Be aware that a `TLIST' is a kind of geometry object, dis-
tinct from a
`transform' object. Some contexts expect one type of ob-
ject,
some the other. For example in INST transform
{ : MYT } geom { ... }
MYT must be a transform object, which might have been
created with the gcl (read transform { define
myT 1 0 0 1 ... })
while in INST transforms { : MYTS } geom {
... } or INST transforms { LIST {: MYTS} {<
more.prj} } geom { ... }
MYTS must be a geometry object, defined e.g. with
(read geometry { define MYTS { TLIST 1 0 0 1 ...
} })
A `TLIST BINARY' format is accepted. Binary data begins
with a
32-bit integer giving the number of transformations, fol-
lowed by that
number of 4x4 matrices in 32-bit floating-point for-
mat. The order of
matrix elements is the same as in the ASCII format.
GROUP Files
-----------
This format is obsolete, but is still accepted. It com-
bined the
functions of `INST' and `TLIST', taking a series of
transformations and a single Geom (`unit') object, and
replicating
the object under each transformation.
GROUP ... < matrices > ... unit { OOGL-OBJECT }
is still accepted and effectively translated into
INST transforms { TLIST ... <matri-
ces> ... }
Geometry Center Thu Dec 12 02:36:08 CST 1996 21
OOGL(5) OOGL(5)
unit { OOGL-OBJECT }
DISCGRP Files
-------------
This format is for discrete groups, such as appear in the
theory of
manifolds or in symmetry patterns. This format has its
own man page.
See discgrp(5).
COMMENT Objects
---------------
The COMMENT object is a mechanism for encoding arbitrary
data within an
OOGL object. It can be used to keep track of data or pass
data back and
forth between external modules.
Syntax:
COMMENT # key word
NAME TYPE # individual name and type specifier
{ ... } # arbitrary data
The data, which must be enclosed by curly braces, can in-
clude anything
except unbalanced curly braces. The TYPE field can be
used to
identify data of interest to a particular program through
naming
conventions.
`COMMENT' objects are intended to be associated with other
objects
through inclusion in a `LIST' object. (*Note LIST::.) The
"#" OOGL
comment syntax does not suffice for data exchange since
these comments
are stripped when an OOGL object is read in to Geomview.
The
`COMMENT' object is preserved when loaded into Geomview
and is
written out intact.
Here is an example associating a WorldWide Web URL with a
piece of
geometry:
{ LIST { < Tetrahedron}
{COMMENT GCHomepage HREF { http://www.geomview.org }}
}
A binary `COMMENT' format is accepted. Its format is not
consistent
with the other OOGL binary formats. *Note Binary format::.
The
`name' and `type' are followed by
N BYTE1 BYTE2 ... BYTEN
instead of data enclosed in curly braces.
Geometry Center Thu Dec 12 02:36:08 CST 1996 22
OOGL(5) OOGL(5)
Non-geometric objects
=====================
The syntax of these objects is given in the form used in
*Note References::, where "quoted" items should appear
literally but
without quotes, square bracketed ([ ]) items are optional,
and | separates
alternative choices.
Transform Objects
-----------------
Where a single 4x4 matrix is expected -- as in the
`INST' `transform' field, the camera's `camtoworld' trans-
form
and the Geomview `xform*' commands -- use a transform ob-
ject.
Note that a transform is distinct from a `TLIST', which is
a type
of geometry. `TLIST's can contain one or more 4x4 trans-
formations;
"transform" objects must have exactly one.
Why have both? In many places -- e.g. camera positioning
-- it's only
meaningful to have a single transform. Using a separate
object type
enforces this.
Syntax for a transform object is
<transform> ::= [ "{" ]
(curly brace, generally needed to make
the end of the object unam-
biguous.)
[ "transform" ] (optional keyword; unnecessary
if the type is determined by
the context, which it usually
is.) [ "define" <name> ]
(defines a transform named
<name>, setting its value from
the stuff which follows)
<sixteen floating-point numbers>
(interpreted as a 4x4 homoge-
neous transform given row by row,
intended to apply to a row
vector multiplied on its LEFT, so that e.g.
Euclidean translations appear
in the bottom row) | "<" <file-
name> (meaning: read transform from that file) |
":" <name> (meaning: use variable <name>,
defined elsewhere; if unde-
fined the initial value is
the identity transform)
[ "}" ] (matching curly brace)
The whole should be enclosed in { braces }. Braces are
not essential
if exactly one of the above items is present, so e.g. a
4x4 array of
floats standing alone may but needn't have braces.
Geometry Center Thu Dec 12 02:36:08 CST 1996 23
OOGL(5) OOGL(5)
Some examples, in contexts where they might be used:
# Example 1: A gcl command to define a transform
# called "fred"
(read transform { transform define fred
1 0 0 0 0 1 0 0
0 0 1 0 -3 0 1 1
} )
# Example 2: A camera object using transform
# "fred" for camera positioning # Given
the definition above, this puts the camera at # (-3,
0, 1), looking toward -Z.
{ camera halfyfield 1
aspect 1.33 camtoworld {
: fred } }
cameras
-------
A camera object specifies the following properties of a
camera:
position and orientation specified by either a
camera-to-world or world-to-camera transformation;
this transformation does not include the projection, so it's typ-
ically just a combination of translation and rota-
tion. Specified as a transform object, typically a
4x4 matrix.
"focus" distance Intended to suggest a typical
distance from the camera to the object of interest;
used for default camera positioning (the camera is placed at
(X,Y,Z) = (0,0,focus) when reset) and for adjusting
field-of-view when switching between perspective and
orthographic views.
window aspect ratio True aspect ratio in the
sense <Xsize>/<Ysize>. This normally should agree
with the aspect ratio of the camera's window. Geomview
normally adjusts the aspect ratio of its cameras to
match their associated windows.
near and far clipping plane distances Note
that both must be strictly greater than zero. Very large
<far>/<near> distance ratios cause Z-buffering to be-
have badly; part of an object may be visible even if
somewhat more distant than another.
field of view Specified in either of two
forms. `fov '
is the field of view -- in degrees if perspec-
tive, or linear
Geometry Center Thu Dec 12 02:36:08 CST 1996 24
OOGL(5) OOGL(5)
distance if orthographic -- in the *shorter* di-
rection. `halfyfield '
is half the projected Y-axis field, in world co-
ordinates (not angle!), at unit distance from
the camera. For a perspective camera, halfyfield
is related to angular field:
halfyfield = tan( Y_axis_angular_field
/ 2 )
while for an orthographic one it's simply:
halfyfield = Y_axis_linear_field /
2
This odd-seeming definition is (a) easy to calculate
with and (b) well-defined in both orthographic and
perspective views.
The syntax for a camera is:
<camera> ::=
[ "camera" ] (optional keyword)
[ "{" ] (opening brace, general-
ly required) [ "define" <name> ]
"<" <filename> |
":" <name> |
(or any number of the following,
in any order...)
"perspective" {"0" | "1"} (default 1)
(otherwise orthographic)
"stereo" {"0" | "1"} (default 0)
(otherwise mono)
"worldtocam" <transform> (see transform syntax
above)
"camtoworld" <transform>
(no point in specifying both
camtoworld and worldtocam; one
is constrained to be the inverse
of the other)
"halfyfield" <half-linear-Y-field-at-unit-dis-
tance> (default tan 40/2 degrees)
"fov" (angular field-of-view if per-
spective, linear field-of-view other-
wise. Measured in whichever direc-
tion is smaller, given the aspect ra-
tio. When aspect ratio changes --
e.g. when a window is reshaped --
Geometry Center Thu Dec 12 02:36:08 CST 1996 25
OOGL(5) OOGL(5)
"fov" is preserved.)
"frameaspect" <aspect-ratio> (X/Y) (default
1.333)
"near" <near-clipping-distance> (default 0.1)
"far" <far-clipping-distance> (default
10.0)
"focus" <focus-distance> (default 3.0)
[ "}" ] (matching closebrace)
window
------
A window object specifies size, position, and other win-
dow-system
related information about a window in a device-independent
way.
The syntax for a window object is:
window ::=
[ "window" ] (optional keyword)
[ "{" ] (curly brace, often required)
(any of the following, in any or-
der)
"size" <xsize> <ysize>
(size of the window)
"position" <xmin> <xmax> <ymin> <ymax>
(position & size)
"noborder"
(specifies the window should
have no window border)
"pixelaspect" <aspect>
(specifies the true visual aspect
ratio of a pixel in this window
in the sense xsize/ysize, normal-
ly 1.0. For stereo hardware
which stretches the display ver-
tically by a factor of 2, "pixe-
laspect 0.5" might do. The value
is used when computing the pro-
jection of a camera associated with
this window.)
[ "}" ] (matching closebrace)
Geometry Center Thu Dec 12 02:36:08 CST 1996 26
OOGL(5) OOGL(5)
Window objects are used in the Geomview `window' and
`ui-panel' commands to set default properties for future
windows or
to change those of an existing window.
Geometry Center Thu Dec 12 02:36:08 CST 1996 27