[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.2 Object File Formats


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.2.1 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; See section 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.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.2.2 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; See section Binary format. The values of Nu and Nv are 32-bit integers; all other values are 32-bit floats.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.2.3 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.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.2.4 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 normals,
			# colors, and/or texture coordinates, in that order,
			# if the prefixes N, C, ST
			# are present.
			# If 4OFF, each vertex has 4 components,
			# 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]

    			# 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 collections of planar polygons with possibly shared vertices, a convenient 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 (specified by the key character 4 directly before OFF in the keyword).

Following these are the face descriptions, typically written with one line per face. Each has the form

 
N  Vert1 Vert2VertN  [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 below

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 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 color. 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; See section Binary 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

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.2.5 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*NVertices floats)

Color[0]Color[NColors-1]  # All the colors
                                           # (4*NColors 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 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 negative 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 polyline.

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 numbers: 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; See section Binary format. The binary format exactly follows the ASCII format, with 32-bit ints where integers appear, and 32-bit floats where real values appear.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.2.6 SKEL Files

SKEL files represent collections of points and polylines, with shared vertices. The conventional suffix for SKEL files is `.skel'.

Syntax:

 
[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 referring to vertices by index in the table. Each polyline has an optional color.

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 objects.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.2.7 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.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.2.8 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 object. It begins with INST followed by these sections which may appear in any order:

 
geom oogl-object

specifies the OOGL object to be instantiated. See section Embedded objects and external-object references, 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-object>

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 ultimately TLIST objects. In effect, the transforms keyword takes a collection of 4x4 matrices and replicates the geom object, making one copy for each 4x4 matrix.

If no transform nor transforms keyword appears, no transformation is applied (actually the identity is applied). You could use this for, e.g., wrapping an appearance around an externally-supplied object, though a single-membered LIST would do this more efficiently.

See section Transformation matrices, for the matrix format.

Two more INST fields are accepted: location and origin.

 
location [global or camera or ndc or screen or local]

Normally an INST specifies a position relative to its parent object; the location field allows putting an object elsewhere.

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 coordinate system. Unlike location, it doesn't change the orientation, only the choice of origin. Both location and origin can be used together.

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.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.2.8.1 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
     	{ < 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 }
}

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.2.9 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 } }

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.2.10 TLIST Files

The conventional suffix for a TLIST file is `.grp' ("group") or or `.prj' ("projective" matrices).

Collection of 4x4 matrices, used in the transforms section of and INST object.

Syntax:

 
TLIST			# key word

<4x4 matrix (16 floats)>
…				# Any number of 4x4 matrices

TLISTs are used only within the transforms clause of an INST object. They cause the INSTs geom object to be instantiated once under each of the transforms in the TLIST. The effect is like that of a LIST of INSTs 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, distinct from a transform object. Some contexts expect one type of object, 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, followed by that number of 4x4 matrices in 32-bit floating-point format. The order of matrix elements is the same as in the ASCII format.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.2.11 GROUP Files

This format is obsolete, but is still accepted. It combined 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 … <matrices> … }
	unit { oogl-object }

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.2.12 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).


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.2.13 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 include 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. (See section LIST Files.) 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. See section Binary format. The name and type are followed by

 
N Byte1 Byte2ByteN

instead of data enclosed in curly braces.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]

This document was generated on June, 24 2006 using texi2html 1.76.