1OOGL(5gv)
5OOGL(5gv)
6NAME
9 OOGL ‐ File formats for OOGL geometric objects
10NOTE
12 The material in this manual page also appears in the
13 Geomview manual.
14DESCRIPTION
16 OOGL File Formats
17 *****************
18 The objects that you can load into Geomview are called
20OOGL objects.
21 OOGL stands for "Object Oriented Graphics Library"; it is
22the library
23 upon which Geomview is built.
24 There are many different kinds of OOGL objects. This
26chapter gives
27 syntactic descriptions of file formats for OOGL objects.
28 Examples of most file types live in Geomview’s ‘data/geom’
30 directory.
31 Conventions
33 ===========
34 Syntax Common to All OOGL File Formats
36 ‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐
37 Most OOGL object file formats are free‐format ASCII ‐‐‐
39any amount of
40 white space (blanks, tabs, newlines) may appear between
41tokens (numbers,
42 key words, etc.). Line breaks are almost always insignif‐
43icant, with a
44 couple of exceptions as noted. Comments begin with # and
45continue to
46 the end of the line; they’re allowed anywhere a newline
47is.
48 Binary formats are also defined for several objects; *Note
50Binary format::, and the individual object descriptions.
51 Typical OOGL objects begin with a key word designating ob‐
53ject type,
54 possibly with modifiers indicating presence of color in‐
55formation etc.
56 In some formats the key word is optional, for compatibili‐
57ty with file
58 formats defined elsewhere. Object type is then determined
59by
60 guessing from the file suffix (if any) or from the data
61itself.
62 Key words are case sensitive. Some have optional prefix
64letters
65 indicating presence of color or other data; in this case
66the order of
67 prefixes is significant, e.g. ‘CNMESH’ is meaningful but
68 ‘NCMESH’ is invalid.
69 File Names
72 ‐‐‐‐‐‐‐‐‐‐
73 When OOGL objects are read from disk files, the OOGL li‐
75brary uses the
76 file suffix to guess at the file type.
77 If the suffix is unrecognized, or if no suffix is avail‐
79able (e.g. for an
80Geometry Center Thu Dec 12 02:36:08 CST 1996 1
84OOGL(5) OOGL(5)
90 object being read from a pipe, or embedded in another OOGL
93object), all
94 known types of objects are tried in turn until one accepts
95the data as
96 valid.
97 Vertices
100 ‐‐‐‐‐‐‐‐
101 Several objects share a common style of representing ver‐
103tices with
104 optional per‐vertex surface‐normal and color. All ver‐
105tices within an
106 object have the same format, specified by the header key
107word.
108 All data for a vertex is grouped together (as opposed to
110e.g. giving
111 coordinates for all vertices, then colors for all ver‐
112tices, and so on).
113 The syntax is
115 ‘X Y Z’ (3‐D floating‐point vertex coordi‐
117nates) or
118 ‘X Y Z W’ (4‐D floating‐point vertex coor‐
119dinates)
120 optionally followed by
122 ‘NX NY NZ’ (normalized 3‐D surface‐normal if
124present)
125 optionally followed by
127 ‘R G B A’ (4‐component floating‐point color
129if present, each component in range 0..1. The A (al‐
130pha) component represents opacity: 0 transparent, 1
131opaque.)
132 optionally followed by
134 ‘S T’
135 ‘or’
136 ‘S T U’
137 (two or three texture‐coordinate values).
139 Values are separated by white space, and line breaks
141 are immaterial.
142 Letters in the object’s header key word must appear in a
144specific order;
145 that’s the reverse of the order in which the data is given
146for each vertex.
147 So a ‘CN4OFF’ object’s vertices contain first the 4‐compo‐
148nent space
149 position, then the 3‐component normal, finally the 4‐com‐
150ponent color.
151 You can’t change the data order by changing the header key
152word; an
153 ‘NCOFF’ is just not recognized.
154 Surface normal directions
157 ‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐
158Geometry Center Thu Dec 12 02:36:08 CST 1996 2
162OOGL(5) OOGL(5)
168 Geomview uses normal vectors to determine how an object is
171shaded.
172 The direction of the normal is significant in this calcu‐
173lation.
174 When normals are supplied with an object, the direction of
176the normal
177 is determined by the data given.
178 When normals are not supplied with the object, Geomview
180computes normal
181 vectors automatically; in this case normals point toward
182the side from
183 which the vertices appear in counterclockwise order.
184 On parametric surfaces (Bezier patches), the normal at
186point P(u,v)
187 is in the direction dP/du cross dP/dv.
188 Transformation matrices
191 ‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐
192 Some objects incorporate 4x4 real matrices for homogeneous
194object
195 transformations. These matrices act by multiplication on
196the right of
197 vectors. Thus, if p is a 4‐element row vector represent‐
198ing homogeneous
199 coordinates of a point in the OOGL object, and A is the
2004x4 matrix, then
201 the transformed point is p’ = p A. This matrix convention
202is common in
203 computer graphics; it’s the transpose of that often used
204in mathematics,
205 where points are column vectors multiplied on the right of
206matrices.
207 Thus for Euclidean transformations, the translation compo‐
210nents appear in
211 the fourth row (last four elements) of A. A’s last column
212(4th, 8th,
213 12th and 16th elements) are typically 0, 0, 0, and 1 re‐
214spectively.
215 Binary format
218 ‐‐‐‐‐‐‐‐‐‐‐‐‐
219 Many OOGL objects accept binary as well as ASCII file for‐
221mats.
222 These files begin with the usual ASCII token (e.g.
223‘CQUAD’)
224 followed by the word ‘BINARY’.
225 Binary data begins at the byte following the first newline
226after
227 ‘BINARY’. White space and a single comment may intervene,
228e.g.
229 OFF BINARY # binary‐format "OFF" data follows
231 Binary data comprise 32‐bit integers and 32‐bit IEEE‐for‐
233mat floats, both
234 in big‐endian format (i.e., with most significant byte
235first). This is
236 the native format for ’int’s and ’float’s on Sun‐3’s,
237Sun‐4’s, and
238 Irises, among others.
239 Binary data formats resemble the corresponding ASCII for‐
241mats, with ints
242 and floats in just the places you’d expect. There are
243some exceptions
244 though, specifically in the ‘QUAD’, ‘OFF’ and ‘COMMENT’
245 file formats. Details are given in the individual file
246format
247 descriptions. *Note QUAD::, *Note OFF::, and *Note COM‐
248MENT::.
249 Binary OOGL objects may be freely mixed in ASCII object
251streams:
252Geometry Center Thu Dec 12 02:36:08 CST 1996 3
256OOGL(5) OOGL(5)
262 LIST { = MESH BINARY ... bi‐
265nary data for mesh here ... } { = QUAD
266 1 0 0 0 0 1 0 1 0 0 1 0 }
267 Note that ASCII data resumes immediately following the
269last byte of
270 binary data.
271 Naturally, it’s impossible to embed comments inside a bi‐
273nary‐format OOGL
274 object, though comments may appear in the header before
275the beginning of
276 binary data.
277 Embedded objects and external‐object references
280 ‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐
281 Some object types (‘LIST’, ‘INST’) allow references to
283other
284 OOGL objects, which may appear literally in the data
285stream, be loaded
286 from named disk files, or be communicated from elsewhere
287via named
288 objects. Gcl commands also accept geometry in these
289forms.
290 The general syntax is
292 <oogl‐object> ::= [ "{" ]
294 [ "define" ‘symbolname’ ]
295[ "appearance" ‘appearance’ ] [ ["="] ‘ob‐
296ject‐keyword’ ... | "<" ‘filename’
297 | ":" ‘symbolname’ ] [
298"}" ]
299 where "quoted" items are literal strings (which appear
301without the
302 quotes), [bracketed] items are optional, and | denotes al‐
303ternatives.
304 Curly braces, when present, must match; the outermost set
305of curly
306 braces is generally required when the object is in a larg‐
307er context,
308 e.g. when it is part of a larger object or embedded in a
309Geomview
310 command stream.
311 For example, each of the following three lines:
313 { define fred QUAD 1 0 0 0 0 1 0 1 0
3141 0 0 }
315 { appearance { +edge } LIST { < "file1" } { :
317fred } }
318 VECT 1 2 0 2 0 0 0 0 1 1 2
320 is a valid OOGL object. The last example is only valid
321when it is
322 delimited unambiguously by residing in its own disk file.
323 The "<" construct causes a disk file to be read. Note
325that this isn’t a
326 general textual "include" mechanism; a complete OOGL ob‐
327ject must appear
328 in the referenced file.
329Geometry Center Thu Dec 12 02:36:08 CST 1996 4
333OOGL(5) OOGL(5)
339 Files read using "<" are sought first in the directory of
342the file which
343 referred to them, if any; failing that, the normal search
344path (set by
345 Geomview’s ‘load‐path’ command) is used. The default
346search looks
347 first in the current directory, then in the Geomview data
348directories.
349 The ":" construct allows references to symbols, created
351with
352 ‘define’. A symbol’s initial value is a null object.
353When a
354 symbol is (re)defined, all references to it are automati‐
355cally changed;
356 this is a crucial part of the support for interprocess
357communication.
358 Some future version of the documentation should explain
359this better...
360 Again, white space and line breaks are insignificant, and
362"#" comments
363 may appear anywhere.
364 Appearances
368 ‐‐‐‐‐‐‐‐‐‐‐
369 Geometric objects can have associated "appearance" infor‐
371mation,
372 specifying shading, lighting, color, wireframe vs. shaded‐
373surface
374 display, and so on. Appearances are inherited through ob‐
375ject
376 hierarchies, e.g. attaching an appearance to a ‘LIST’
377means that the
378 appearance is applied to all the ‘LIST’’s members.
379 Some appearance‐related properties are relegated to "mate‐
381rial" and
382 "lighting" substructures. Take care to note which proper‐
383ties belong to
384 which structure.
385 Here’s an example appearance structure including values
387for all
388 attributes. Order of attributes is unimportant. As usu‐
389al, white space
390 is irrelevant. Boolean attributes may be preceded by "+"
391or "‐" to turn
392 them on or off; "+" is assumed if only the attribute name
393appears.
394 Other attributes expect values.
395 A "*" prefix on any attribute, e.g. "*+edge" or
397"*linewidth 2"
398 or "material { *diffuse 1 1 .25 }", selects "override"
399status for
400 that attribute.
401 appearance { +face # (Do)
403draw faces of polygons. On by default.
404‐edge # (Don’t) draw edges of polygons
405+vect # (Do) draw VECTs. On by default.
406‐transparent # (Disable) transparency. enabling trans‐
407parency # does NOT result in a
408correct Geomview picture, # but
409alpha values are used in RenderMan snapshots.
410‐normal # (Do) draw surface‐normal vectors
411normscale 1 # ... with length 1.0 in object coordinates
412 +evert # do evert polygon normals
414where needed so as # to al‐
415ways face the camera
416 ‐texturing # (Disable) texture mapping
418 ‐backcull # (Don’t) discard clock‐
419wise‐oriented faces
420Geometry Center Thu Dec 12 02:36:08 CST 1996 5
424OOGL(5) OOGL(5)
430 ‐concave # (Don’t) expect and handle
433concave polygons ‐shadelines # (Don’t) shade
434lines as if they were lighted cylinders
435# These four are only effective where the graphics system
436 # supports them, namely on GL and
437Open GL.
438 ‐keepcolor # Normally, when N‐D positional
440coloring is enabled as # with ge‐
441omview’s (ND‐color ...) command, all
442# objects’ colors are affected. But, objects with the
443 # "+keepcolor" attribute are immune
444to N‐D coloring.
445 shading smooth # or "shading constant" or
447"shading flat" or # or "shading
448csmooth". # smooth = Gouraud
449shading, flat = faceted, #
450csmooth = smoothly interpolated but unlighted.
451 linewidth 1 # lines, points, and edges are
4531 pixel wide.
454 patchdice 10 10 # subdivide Bezier patches this
456finely in u and v
457 material { # Here’s a material definition;
459 # it could also be read from a
460file as in # "material <
461file.mat"
462 ka 1.0 # ambient reflection coeffi‐
464cient. ambient .3 .5 .3 # ambient color (red,
465green, blue components) # The
466ambient contribution to the shading is
467 # the product of ka, the ambi‐
468ent color, # and the color of
469the ambient light.
470 kd 0.8 # diffuse‐reflection coeffi‐
472cient. diffuse .9 1 .4 # diffuse color.
473 # (In "shading constant"
474mode, the surface # is col‐
475ored with the diffuse color.)
476 ks 1.0 # specular reflection coeffi‐
478cient. specular 1 1 1 # specular (highlight)
479color. shininess 25 # specular exponent;
480larger values give # sharper
481highlights.
482 backdiffuse .7 .5 0 # back‐face color for two‐
484sided surfaces # If defined,
485this field determines the diffuse
486 # color for the back side of
487a surface. # It’s implement‐
488ed by the software shader, and
489# by hardware shading on GL systems which support
490 # two‐sided lighting, and un‐
491der Open GL.
492 alpha 1.0 # opacity; 0 = transparent (in‐
494visible), 1 = opaque. # Ig‐
495nored when transparency is disabled.
496 edgecolor 1 1 0 # line & edge color
498 normalcolor 0 0 0 # color for surface‐normal
500vectors }
501Geometry Center Thu Dec 12 02:36:08 CST 1996 6
506OOGL(5) OOGL(5)
512 lighting { # Lighting model
515 ambient .3 .3 .3 # ambient light
517 replacelights # "Use only the following
519lights to # illuminate the ob‐
520jects under this # appearance."
521 # Without "replacelights", any
522lights listed # are added to
523those already in the scene.
524 # Now a collection of sample
526lights: light { color 1
527.7 .6 # light color position 1 0 .5 0
528# light position [distant light]
529 # given in homogeneous
530coordinates. # With
531fourth component = 0, #
532this means a light coming from
533 # direction (1,0,.5).
534 }
535 light { # Another light.
537 color 1 1 1 posi‐
538tion 0 0 .5 1 # light at finite position ...
539location camera # specified in camera coordinates.
540 # (Since the camera
541looks toward ‐Z, # this
542example places the light
543# .5 unit behind the eye.) # Possible "lo‐
544cation" keywords: # global light posi‐
545tion is in world (well, universe) coordinates
546# This is the default if no location specified.
547 # camera position is in the camera’s
548coordinate system # local position is
549in the coordinate system where
550# the appearance was defined
551} } # end lighting model
552texture { clamp st # or "s" or
553"t" or "none" file lump.tiff # file
554supplying texture‐map image alphafile
555mask.pgm.Z # file supplying transparency‐mask image
556 apply blend # or "modulate"
557or "decal" transform 1 0 0 0 # surface
558(s,t,0,1) * tfm ‐> texture coords
5590 1 0 0 0 0 1 0
560 .5 0 0 1
561 background 1 0 0 1 # relevant for "apply
563blend" } } # end
564appearance
565 There are rules for inheritance of appearance attributes
568when several
569 are imposed at different levels in the hierarchy.
570 For example, Geomview installs a backstop appearance which
572provides
573Geometry Center Thu Dec 12 02:36:08 CST 1996 7
577OOGL(5) OOGL(5)
583 default values for most parameters; its control panels in‐
586stall other
587 appearances which supply new values for a few attributes;
588user‐supplied
589 geometry may also contain appearances.
590 The general rule is that the child’s appearance (the one
592closest to the
593 geometric primitives) wins.
594 Further, appearance controls with "override" status
595 (e.g. *+face or material { *diffuse 1 1 0 })
596 win over those without it.
597 Geomview’s appearance controls use the "override" feature
599so as to be
600 effective even if user‐supplied objects contain their own
601appearance settings.
602 However, if a user‐supplied object contains an appearance
603field with
604 override status set, that property will be immune to Ge‐
605omview’s controls.
606 Texture Mapping
609 ‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐
610 Some platforms support texture‐mapped objects.
612 (On those which don’t, attempts to use texture mapping are
613silently
614 ignored.) A texture is specified as part of an appearance
615structure,
616 as in *Note Appearances::. Briefly, one provides a tex‐
617ture image,
618 which is considered to lie in a square in ‘(s,t)’ parame‐
619ter space in
620 the range 0 <= s <= 1, 0 <= t <= 1. Then one provides a
621geometric primitive,
622 with each vertex tagged with ‘(s,t)’ texture coordinates.
623If texturing
624 is enabled, the appropriate portion of the texture image
625is pasted onto
626 each face of the textured object.
627 There is (currently) no provision for inheritance of part
629of a texture
630 structure; if the ‘texture’ keyword is mentioned in an ap‐
631pearance,
632 it supplants any other texture specification.
633 The appearance attribute ‘texturing’ controls whether tex‐
635tures are
636 used; there’s no performance penalty for having texture {
637... } fields
638 defined when texturing is off.
639 The available fields are:
641 clamp none ‐or‐ s ‐or‐ t ‐or‐ st
643Determines the meaning of texture coordinates outside the range
6440..1. With ‘clamp none’, the default, coordinates
645are interpreted modulo 1, so (s,t) = (1.25,0),
646(.25,0), and (‐.75,0) all refer to the same point
647in texture space. With ‘s’ or ‘t’ or ‘st’, either
648or both of s‐ or t‐coordinates less than 0 or
649greater than 1 are clamped to 1 or 0, respectively.
650 file filename alphafile filename
652Specifies image file(s) containing the texture.
653The ‘file’ file’s image specifies color or lightness information;
654 the ‘alphafile’ if present, specifies a transparen‐
655cy ("alpha") mask; where the mask is zero, pixels
656are simply not drawn. Several image file formats
657are available; the file type must be
658Geometry Center Thu Dec 12 02:36:08 CST 1996 8
662OOGL(5) OOGL(5)
668 indicated by the last few characters of the file
671name: .ppm or .ppm.Z or .ppm.gz 24‐bit 3‐color
672image in PPM format .pgm or .pgm.Z or .pgm.gz
6738‐bit grayscale image in PGM format .sgi or
674.sgi.Z or .sgi.gz 8‐bit, 24‐bit, or 32‐bit SGI image
675 .tiff 8‐bit or 24‐bit TIFF image
676 .gif GIF image (Though
6774‐channel TIFF images are possible, and could rep‐
678resent both color and transparency information in one image,
679 that’s not supported in geomview at present.)
680 For this feature to work, some programs must be
681available in geomview’s search path:
682 zcat for .Z files gzip for .gz
683files tifftopnm for .tiff files
684 giftoppm for .gif files
685 If an ‘alphafile’ image is supplied, it must be the
687same size as the ‘file’ image.
688 apply modulate ‐or‐ blend ‐or‐ decal
691Indicates how the texture image is applied to the surface.
692 Here the "surface color" means the color that sur‐
693face would have in the absence of texture mapping.
694 With ‘modulate’, the default, the texture color (or
696lightness, if textured by a gray‐scale image) is
697multiplied by the surface color.
698 With ‘blend’, texture blends between the ‘back‐
700ground’ color and the surface color. The ‘file’
701parameter must specify a gray‐scale image. Where
702the texture image is 0, the surface color is unaf‐
703fected; where it’s 1, the surface is painted in the color given
704 by ‘background’; and color is interpolated for in‐
705termediate values.
706 With ‘decal’, the ‘file’ parameter must specify a
708 3‐color image. If an ‘alphafile’ parameter is
709present, its value interpolates between the surface
710color (where alpha=0) and the texture color (where
711alpha=1). Lighting does not affect the texture
712color in ‘decal’ mode; effectively the texture is
713constant‐shaded.
714 background R G B A Specifies a 4‐com‐
716ponent color, with R, G, B, and A floating‐point
717numbers normally in the range 0..1, used when ‘apply blend’
718 is selected.
719 transform ‘transformation‐matrix’ Ex‐
721pects a list of 16 numbers, or one of the other ways of repre‐
722senting a transformation (‘: handlename’ or ‘<
723filename’). The 4x4 transformation matrix is ap‐
724plied to texture coordinates, in the sense of a
7254‐component row vector (s,t,0,1) multiplied on the
726left of the matrix, to produce new coordinates (s’,t’)
727which actually index the texture.
728Geometry Center Thu Dec 12 02:36:08 CST 1996 9
733OOGL(5) OOGL(5)
739 Object File Formats
742 ===================
743 QUAD: collection of quadrilaterals
745 ‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐
746 The conventional suffix for a ‘QUAD’ file is ‘.quad’.
748 The file syntax is
750 [C][N][4]QUAD ‐or‐ [C][N][4]POLY # Key
752word VERTEX VERTEX VERTEX VERTEX # 4*N ver‐
753tices for some N VERTEX VERTEX VERTEX VERTEX
754 ...
755 The leading key word is ‘[C][N][4]QUAD’ or
757‘[C][N][4]POLY’,
758 where the optional ‘C’ and ‘N’ prefixes indicate that each
759vertex
760 includes colors and normals respectively. That is, these
761files
762 begin with one of the words
763 ‘QUAD’ ‘CQUAD’ ‘NQUAD’ ‘CNQUAD’ ‘POLY’
765 ‘CPOLY’ ‘NPOLY’ ‘CNPOLY’
766 (but not ‘NCQUAD’ or ‘NCPOLY’). ‘QUAD’ and ‘POLY’
768 are synonymous; both forms are allowed just for compati‐
769bility with
770 ChapReyes.
771 Following the key word is an arbitrary number of groups of
773four
774 vertices, each group describing a quadrilateral. See the
775Vertex syntax
776 above. The object ends at end‐of‐file, or with a close‐
777brace if
778 incorporated into an object reference (see above).
779 A ‘QUAD BINARY’ file format is accepted; *Note Binary for‐
781mat::. The
782 first word of binary data must be a 32‐bit integer giving
783the number of
784 quads in the object; following that is a series of 32‐bit
785floats,
786 arranged just as in the ASCII format.
787 MESH: rectangularly‐connected mesh
790 ‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐
791 The conventional suffix for a ‘MESH’ file is ‘.mesh’.
793 The file syntax is
795 [U][C][N][Z][4][u][v][n]MESH # Key word
797[NDIM] # Space dimension, present only if nMESH
798 NU NV # Mesh grid dimensions
799 # NU*NV vertices, in
800format specified # by
801initial key word VERTEX(u=0,v=0) VERTEX(1,0) ...
802VERTEX(NU‐1,0) VERTEX(0,1) ... VERTEX(NU‐1,1)
803 ... VERTEX(0,NV‐1) ... VERTEX(NU‐1,NV‐1)
804Geometry Center Thu Dec 12 02:36:08 CST 1996 10
808OOGL(5) OOGL(5)
814 The key word is ‘[U][C][N][Z][4][u][v][n]MESH’.
817 The optional prefix characters mean:
818 ‘U’ Each vertex includes a 3‐component texture
820space parameter. The first two components are the
821usual ‘S’ and ‘T’ texture parameters for that vertex;
822the third should be specified as zero.
823 ‘C’ Each vertex (see Vertices above) includes
824a 4‐component color.
825 ‘N’ Each vertex includes a surface normal vec‐
826tor.
827 ‘Z’ Of the 3 vertex position values, only the
828Z component is present; X and Y are omitted, and as‐
829sumed to equal the mesh (u,v) coordinate so X ranges
830from 0 .. (Nu‐1), Y from 0 .. (Nv‐1) where Nu and Nv are the mesh
831 dimensions ‐‐ see below.
832 ‘4’ Vertices are 4D, each consists of 4 float‐
833ing values. ‘Z’ and ‘4’ cannot both be present.
834 ‘u’ The mesh is wrapped in the u‐direction, so
835the (0,v)’th vertex is connected to the (NU‐1,v)’th
836for all v.
837 ‘v’ The mesh is wrapped in the v‐direction, so
838the (u,0)’th vertex is connected to the (u,NV‐1)’th
839for all u. Thus a u‐wrapped or v‐wrapped mesh is
840topologically a cylinder, while a uv‐wrapped mesh is a
841torus.
842 ‘n’ Specifies a mesh whose vertices live in a
843higher dimensional space. The dimension follows the
844"MESH" keyword. Each vertex then has NDIM compo‐
845nents.
846 Note that the order of prefix characters is significant; a
848colored,
849 u‐wrapped mesh is a ‘CuMESH’ not a ‘uCMESH’.
850 Following the mesh header are integers NU and NV,
852 the dimensions of the mesh.
853 Then follow NU*NV vertices, each in the form given by the
855header.
856 They appear in v‐major order, i.e. if we name each vertex
857by (u,v)
858 then the vertices appear in the order
859 (0,0) (1,0) (2,0) (3,0) ... (NU‐1,0)
861(0,1) (1,1) (2,1) (3,1) ... (NU‐1,1) ...
862 (0,Nv‐1) ... (NU‐1,NV‐1)
863 A ‘MESH BINARY’ format is accepted; *Note Binary format::.
865The
866 values of NU and NV are 32‐bit integers; all other values
867 are 32‐bit floats.
868 Bezier Surfaces
871 ‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐
872Geometry Center Thu Dec 12 02:36:08 CST 1996 11
876OOGL(5) OOGL(5)
882 The conventional file suffixes for Bezier surface files
885are ‘.bbp’
886 or ‘.bez’. A file with either suffix may contain either
887type of
888 patch.
889 Syntax:
891 [ST]BBP ‐or‐ [C]BEZ<NU><NV><ND>[_ST]
893 # NU, NV are u‐ and v‐direction
894 # polynomial degrees in range 1..6
895 # ND = dimension: 3‐>3‐D, 4‐>4‐D (ra‐
896tional) # (The ’<’ and ’>’ do not ap‐
897pear in the input.) # NU,NV,ND are
898each a single decimal digit. # BBP
899form implies NU=NV=ND=3 so BBP = BEZ333.
900 # Any number of patches follow the header
902 # (NU+1)*(NV+1) patch control points
903 # each 3 or 4 floats according to
904header VERTEX(u=0,v=0) VERTEX(1,0) ... VER‐
905TEX(NU,0) VERTEX(0,1) ... VER‐
906TEX(NU,1) ... VERTEX(0,NV)
907... VERTEX(NU,NV)
908 # ST texture coordinates if mentioned
910in header ‘S’(u=0,v=0) ‘T’(0,0) ‘S’(0,NV)
911‘T’(0,NV) ‘S’(NU,0) ‘T’(NU,0) ‘S’(NU,NV)
912‘T’(NU,NV)
913 # 4‐component float (0..1) R G B A
915colors # for each patch corner if men‐
916tioned in header ‘RGBA’(0,0) ‘RGBA’(0,NV)
917 ‘RGBA’(NU,0) ‘RGBA’(NU,NV)
918 These formats represent collections of Bezier surface
920patches, of
921 degrees up to 6, and with 3‐D or 4‐D (rational) vertices.
922 The header keyword has the forms ‘[ST]BBP’ or
924 ‘[C]BEZ<NU><NV><ND>[_ST]’ (the ’<’ and ’>’ are
925 not part of the keyword.
926 The ‘ST’ prefix on ‘BBP’, or ‘_ST’ suffix on
928 ‘BEZuvn’, indicates that each patch includes four pairs of
929 floating‐point texture‐space coordinates, one for each
930corner of the
931 patch.
932 The ‘C’ prefix on ‘BEZuvn’ indicates a colored patch,
934 including four sets of four‐component floating‐point col‐
935ors (red, green,
936 blue, and alpha) in the range 0..1, one color for each
937corner.
938 NU and NV, each a single digit in the range 1..6, are the
940 patch’s polynomial degree in the u and v direction respec‐
941tively.
942 ND is the number of components in each patch vertex, and
944must be
945 either ‘3’ for 3‐D or ‘4’ for homogeneous coordinates,
946that
947 is, rational patches.
948Geometry Center Thu Dec 12 02:36:08 CST 1996 12
953OOGL(5) OOGL(5)
959 ‘BBP’ patches are bicubic patches with 3‐D vertices, so
962‘BBP’
963 = ‘BEZ333’ and ‘STBBP’ = ‘BEZ333_ST’.
964 Any number of patches follow the header. Each patch com‐
966prises a series
967 of patch vertices, followed by optional (s,t) texture co‐
968ordinates,
969 followed by optional (r,g,b,a) colors.
970 Each patch has (NU+1)*(NV+1) vertices in v‐major order, so
972that if we
973 designate a vertex by its control point indices (u,v) the
974order is (0,0) (1,0) (2,0) ... (NU,0)
975 (0,1) (1,1) (2,1) ... (NU,1)
976... (0,NV) ... (NU,NV)
977 with each vertex containing either 3 or 4 floating‐point
978numbers
979 as specified by the header.
980 If the header calls for ST coordinates, four pairs of
982floating‐point
983 numbers follow: the texture‐space coordinates for the
984(0,0),
985 (NU,0), (0,NV), and (NU,NV) corners of the
986 patch, respectively.
987 If the header calls for colors, four four‐component (red,
989green, blue,
990 alpha) floating‐point colors follow, one for each patch
991corner.
992 The series of patches ends at end‐of‐file, or with a
994closebrace if
995 incorporated in an object reference.
996 Info file: geomview, ‐*‐Text‐*‐
998 produced by texinfo‐format‐buffer
999 from file: geomview.tex
1000 OFF Files
1004 ‐‐‐‐‐‐‐‐‐
1005 The conventional suffix for ‘OFF’ files is ‘.off’.
1007 Syntax:
1009 [ST][C][N][4][n]OFF # Header keyword
1011[NDIM] # Space dimension of vertices, present only if
1012nOFF NVERTICES NFACES NEDGES # NEdges not used or
1013checked
1014 X[0] Y[0] Z[0] # Vertices, possibly with nor‐
1016mals, # colors, and/or texture coordi‐
1017nates, in that order, # if the prefix‐
1018es ‘N’, ‘C’, ‘ST’ # are present.
1019 # If 4OFF, each vertex has 4 compo‐
1020nents, # including a final homogeneous
1021component. # If nOFF, each vertex has
1022NDIM components. # If 4nOFF, each
1023vertex has NDIM+1 components. ...
1024X[NVERTICES‐1] Y[NVERTICES‐1] Z[NVERTICES‐1]
1025Geometry Center Thu Dec 12 02:36:08 CST 1996 13
1029OOGL(5) OOGL(5)
1035 # Faces #
1038NV = # vertices on this face # V[0]
1039... V[NV‐1]: vertex indices #
1040in range 0..NVERTICES‐1 NV V[0] V[1] ... V[NV‐1]
1041COLORSPEC ... # COLORSPEC
1042continues past V[NV‐1] # to end‐of‐
1043line; may be 0 to 4 numbers # nothing:
1044default # integer: colormap index
1045 # 3 or 4 integers: RGB[A] values
10460..255 # 3 or 4 floats: RGB[A] values
10470..1
1048 ‘OFF’ files (name for "object file format") represent col‐
1050lections
1051 of planar polygons with possibly shared vertices, a conve‐
1052nient way to
1053 describe polyhedra. The polygons may be concave but
1054there’s no
1055 provision for polygons containing holes.
1056 An ‘OFF’ file may begin with the keyword ‘OFF’; it’s
1058 recommended but optional, as many existing files lack this
1059keyword.
1060 Three ASCII integers follow: NVERTICES, NFACES, and
1062 NEDGES. Thse are the number of vertices, faces, and
1063edges,
1064 respectively. Current software does not use nor check
1065NEDGES; it
1066 needn’t be correct but must be present.
1067 The vertex coordinates follow: dimension * NVERTICES
1069 floating‐point values. They’re implicitly numbered 0
1070through
1071 NVERTICES‐1. dimension is either 3 (default) or 4 (speci‐
1072fied by
1073 the key character ‘4’ directly before ‘OFF’ in the key‐
1074word).
1075 Following these are the face descriptions, typically writ‐
1077ten
1078 with one line per face. Each has the form N
1079VERT1 VERT2 ... VERTN [COLOR]
1080 Here N is the number of vertices on this face,
1081 and VERT1 through VERTN are indices into the list of
1082 vertices (in the range 0..NVERTICES‐1).
1083 The optional COLOR may take several forms. Line breaks
1085are
1086 significant here: the COLOR description begins after VERTN
1087 and ends with the end of the line (or the next # comment).
1088A
1089 COLOR may be:
1090 nothing the default color
1092 one integer index into "the" colormap; see be‐
1093low
1094 three or four integers RGB and possibly alpha
1095values in the range 0..255
1096 three or four floating‐point numbers RGB and
1097possibly alpha values in the range 0..1
1098 For the one‐integer case, the colormap is currently read
1100from the file
1101 ‘cmap.fmap’ in Geomview’s ‘data’ directory. Some better
1102Geometry Center Thu Dec 12 02:36:08 CST 1996 14
1106OOGL(5) OOGL(5)
1112 mechanism for supplying a colormap is likely someday.
1115 The meaning of "default color" varies. If no face of the
1117object has a
1118 color, all inherit the environment’s default material col‐
1119or. If some
1120 but not all faces have colors, the default is gray
1121(R,G,B,A=.666).
1122 A ‘[ST][C][N][n]OFF BINARY’ format is accepted; *Note Bi‐
1124nary format::. It
1125 resembles the ASCII format in almost the way you’d expect,
1126with 32‐bit
1127 integers for all counters and vertex indices and 32‐bit
1128floats for
1129 vertex positions (and texture coordinates or vertex colors
1130or normals if
1131 ‘COFF’/‘NOFF’/‘CNOFF’/‘STCNOFF’/etc. format).
1132 Exception: each face’s vertex indices are followed by an
1134integer
1135 indicating how many color components accompany it. Face
1136color
1137 components must be floats, not integer values. Thus a
1138colorless
1139 triangular face might be represented as
1140 int int int int int 3 17 5 9 0
1142 while the same face colored red might be
1144 int int int int int float float float float
11463 17 5 9 4 1.0 0.0 0.0 1.0
1147 VECT Files
1151 ‐‐‐‐‐‐‐‐‐‐
1152 The conventional suffix for ‘VECT’ files is ‘.vect’.
1154 Syntax:
1156 [4]VECT NPOLYLINES NVERTICES NCOLORS
1158 NV[0] ... NV[NPOLYLINES‐1] # number of vertices
1160 # in each
1161polyline
1162 NC[0] ... NC[NPOLYLINES‐1] # number of colors
1164supplied #
1165in each polyline
1166 VERT[0] ... VERT[NVERTICES‐1] # All the vertices
1168 # (3*NVer‐
1169tices floats)
1170 COLOR[0] ... COLOR[NCOLORS‐1] # All the colors
1172 # (4*NCol‐
1173ors floats, RGBA)
1174 ‘VECT’ objects represent lists of polylines (strings of
1176connected
1177 line segments, possibly closed). A degenerate polyline
1178can be used to
1179 represent a point.
1180 A ‘VECT’ file begins with the key word ‘VECT’ or ‘4VECT’
1182Geometry Center Thu Dec 12 02:36:08 CST 1996 15
1186OOGL(5) OOGL(5)
1192 and three integers: NLINES, NVERTICES, and NCOLORS.
1195 Here NLINES is the number of polylines in the file,
1196 NVERTICES the total number of vertices, and NCOLORS the
1197 number of colors as explained below.
1198 Next come NLINES integers
1200 NV[0] NV[1] NV[2] ... NV[NLINES‐1]
1202 giving the number of vertices in each polyline. A nega‐
1204tive number
1205 indicates a closed polyline; 1 denotes a single‐pixel
1206point. The sum
1207 (of absolute values) of the NV[I] must equal NVERTICES.
1208 Next come NLINES more integers Nc[i]: the number of colors
1210in
1211 each polyline. Normally one of three values:
1212 0 No color is specified for this polyline.
1214It’s drawn in the same color as the previous poly‐
1215line.
1216 1 A single color is specified. The entire
1217polyline is drawn in that color.
1218 abs(NV[I]) Each vertex has a color. Either
1219each segment is drawn in the corresponding color, or
1220the colors are smoothly interpolated along the line
1221segments, depending on the implementation.
1222 The sum of the NC[I] must equal NCOLORS.
1224 Next come NVERTICES groups of 3 or 4 floating‐point num‐
1226bers: the
1227 coordinates of all the vertices. If the keyword is 4VECT
1228then
1229 there are 4 values per vertex. The first abs(NV[0]) of
1230them form
1231 the first polyline, the next abs(NV[1]) form the second
1232and so on.
1233 Finally NCOLORS groups of 4 floating‐point numbers give
1235red,
1236 green, blue and alpha (opacity) values. The first NC[0]
1237of them
1238 apply to the first polyline, and so on.
1239 A VECT BINARY format is accepted; *Note Binary format::.
1241The
1242 binary format exactly follows the ASCII format, with
124332‐bit ints where
1244 integers appear, and 32‐bit floats where real values ap‐
1245pear.
1246 SKEL Files
1251 ‐‐‐‐‐‐‐‐‐‐
1252 ‘SKEL’ files represent collections of points and poly‐
1254lines, with
1255 shared vertices.
1256 The conventional suffix for ‘SKEL’ files is ‘.skel’.
1257 Syntax:
1259Geometry Center Thu Dec 12 02:36:08 CST 1996 16
1264OOGL(5) OOGL(5)
1270 [4][n]SKEL [NDIM] #
1273Vertex dimension, present only if nSKEL NVERTICES
1274NPOLYLINES
1275 X[0] Y[0] Z[0] # Vertices
1277 # (if nSKEL, each vertex has
1278NDim components) ... X[NVERTICES‐1]
1279Y[NVERTICES‐1] Z[NVERTICES‐1]
1280 # Polylines
1282 # NV = # vertices on this
1283polyline (1 = point) # V[0]
1284... V[NV‐1]: vertex indices #
1285in range 0..NVERTICES‐1 NV V[0] V[1] ... V[NV‐1]
1286[COLORSPEC] ...
1287# COLORSPEC continues past V[NV‐1]
1288 # to end‐of‐line; may be
1289nothing, or 3 or 4 numbers.
1290# nothing: default color # 3 or 4
1291floats: RGB[A] values 0..1
1292 The syntax resembles that of ‘OFF’ files, with a table of
1294vertices
1295 followed by a sequence of polyline descriptions, each re‐
1296ferring to vertices
1297 by index in the table. Each polyline has an optional col‐
1298or.
1299 For ‘nSKEL’ objects, each vertex has NDIM components.
1301 For ‘4nSKEL’ objects, each vertex has NDIM+1 components;
1302 the final component is the homogeneous divisor.
1303 No ‘BINARY’ format is implemented as yet for ‘SKEL’ ob‐
1305jects.
1306 SPHERE Files
1309 ‐‐‐‐‐‐‐‐‐‐‐‐
1310 The conventional suffix for ‘SPHERE’ files is ‘.sph’.
1312 SPHERE RADIUS XCENTER YCENTER
1314ZCENTER
1315 Sphere objects are drawn using rational Bezier patches,
1317which are diced into
1318 meshes; their smoothness, and the time taken to draw them,
1319depends on the
1320 setting of the dicing level, 10x10 by default.
1321 From Geomview, the Appearance panel, the ‘<N>ad’ keyboard
1322command, or
1323 a ‘dice nu nv’ Appearance attribute sets this.
1324 INST Files
1327 ‐‐‐‐‐‐‐‐‐‐
1328 The conventional suffix for a ‘INST’ file is ‘.inst’.
1330 There is no INST BINARY format.
1332 An ‘INST’ applies a 4x4 transformation to another OOGL ob‐
1334ject. It
1335Geometry Center Thu Dec 12 02:36:08 CST 1996 17
1339OOGL(5) OOGL(5)
1345 begins with ‘INST’ followed by these sections which may
1348appear in
1349 any order: geom OOGL‐OBJECT
1350 specifies the OOGL object to be instantiated. *Note Ref‐
1351erences::, for
1352 the syntax of an OOGL‐OBJECT. The keyword ‘unit’ is a
1353 synonym for ‘geom’. transform ["{"] ‘4x4
1354transform’ ["}"]
1355 specifies a single transformation matrix. Either the
1356 matrix may appear literally as 16 numbers, or there may be
1357 a reference to a "transform" object, i.e.
1358 "<" file‐containing‐4x4‐matrix
1359 or ":" symbol‐representing‐transform‐ob‐
1360ject>
1361 Another way to specify the transformation is
1362transforms OOGL‐OBJECT
1363 The OOGL‐OBJECT must be a ‘TLIST’ object (list of
1364 transformations) object, or a ‘LIST’ whose members are ul‐
1365timately
1366 ‘TLIST’ objects. In effect, the ‘transforms’ keyword
1367takes a
1368 collection of 4x4 matrices and replicates the ‘geom’ ob‐
1369ject, making
1370 one copy for each 4x4 matrix.
1371 If no ‘transform’ nor ‘transforms’ keyword appears, no
1373 transformation is applied (actually the identity is ap‐
1374plied). You could
1375 use this for, e.g., wrapping an appearance around an ex‐
1376ternally‐supplied
1377 object, though a single‐membered LIST would do this more
1378efficiently.
1379 *Note Transformation matrices::, for the matrix format.
1381 Two more INST fields are accepted: ‘location’ and ‘ori‐
1384gin’.
1385 location [global or camera or ndc or screen or local]
1387 Normally an INST specifies a position relative to its par‐
1388ent object;
1389 the ‘location’ field allows putting an object elsewhere.
1390 * ‘location global’ attaches the object to the global
1391(a.k.a. universe) coordinate system ‐‐ the same as
1392that in which geomview’s World objects, alien geome‐
1393try, and cameras are placed. * ‘location camera’
1394places the object relative to the camera. (Thus if
1395there are multiple views, it may appear in a different
1396spatial position in each view.) The center of the camera’s view
1397 is along its negative Z axis; positive X is right‐
1398ward, positive Y upward. Normally the units of cam‐
1399era space are the same as global coordinates. When a
1400camera is reset, the global origin is at (0,0,‐3.0). *
1401‘location ndc’ places the object relative to the normalized unit
1402 cube into which the camera’s projection (perspective
1403or orthographic) maps the visible world. X, Y, and Z
1404are each in the range from ‐1 to +1, with Z = ‐1 the
1405near and Z = +1 the far clipping plane, and X and Y
1406increasing rightward and upward respectively. Thus
1407something like INST transform 1 0 0 0 0 1 0 0
14080 0 1 0 ‐.9 ‐.9 ‐.999 1 location ndc
1409 geom < label.vect pastes ‘la‐
1410bel.vect’ onto the lower left corner of each window,
1411Geometry Center Thu Dec 12 02:36:08 CST 1996 18
1415OOGL(5) OOGL(5)
1421 and in front of nearly everything else, assuming ‘la‐
1424bel.vect’’s contents lie in the positive quadrant of
1425the X‐Y plane. It’s tempting to use ‐1 rather than
1426‐.999 as the Z component of the position, but that
1427may put the object just nearer than the near clipping
1428plane and make it (partially) invisible, due to floating‐point
1429error. * ‘location screen’ places the object in screen
1430coordinates. The range of Z is still ‐1 through +1
1431as for ndc coordinates; X and Y are measured in pix‐
1432els, and range from (0,0) at the *lower left* corner
1433of the window, increasing rightward and upward.
1434 ‘location local’ is the default; the object is positioned
1436relative
1437 to its parent.
1438 origin [global or camera or ndc or screen or local] x
1441y z
1442 The ‘origin’ field translates the contents of the INST to
1443 place the origin at the specified point of the given coor‐
1444dinate system.
1445 Unlike ‘location’, it doesn’t change the orientation, only
1446the choice
1447 of origin. Both ‘location’ and ‘origin’ can be used to‐
1448gether.
1449 So for example { INST location
1451screen origin ndc 0 0 ‐.99 geom { <
1452xyz.vect } transform { 100 0 0 0 0 100 0 0 0 0
1453‐.009 0 0 0 0 1 } }
1454 places xyz.vect’s origin in the center of the window, just
1456beyond the
1457 near clipping plane. The unit‐length X and Y edges are
1458scaled to be just 100
1459 screen units ‐‐ pixels ‐‐ long, regardless of the size of
1460the window.
1461 INST Examples .............
1463 Here are some examples of ‘INST’ files
1465 INST unit < xyz.vect
1467 transform { 1 0 0 0
1468 0 1 0 0 0 0 1 0
1469 1 3 0 1 }
1470 { appearance { +edge material { edgecolor 1 1 0 } }
1472 INST geom < mysurface.quad }
1473 {INST transform {: T} geom {<dodec.off}}
1475 { INST transforms
1477{ LIST
1478Geometry Center Thu Dec 12 02:36:08 CST 1996 19
1482OOGL(5) OOGL(5)
1488 { < some‐matrices.prj }
1491{ < others.prj } { TLIST <still more of
1492them> }
1493 } geom
1495{ # stuff replicated by all the above matrices
1496... } }
1497 This one resembles the ‘origin’ example in the section
1499above,
1500 but makes the X and Y edges be 1/4 the size of the window
1501(1/4, not 1/2,
1502 since the range of ndc X and Y coordinates is ‐1 to +1).
1503 { INST location ndc geom
1504{ < xyz.vect } transform { .5 0 0 0 0 .5 0 0 0 0
1505‐.009 0 0 0 ‐.99 1 } }
1506 LIST Files
1508 ‐‐‐‐‐‐‐‐‐‐
1509 The conventional suffix for a ‘LIST’ file is ‘.list’.
1511 A list of OOGL objects
1513 Syntax:
1515 LIST OOGL‐OBJECT
1517 OOGL‐OBJECT ...
1518 Note that there’s no explicit separation between the oogl‐
1520objects, so
1521 they should be enclosed in curly braces ({ }) for sanity.
1522Likewise
1523 there’s no explicit marker for the end of the list; unless
1524appearing
1525 alone in a disk file, the whole construct should also be
1526wrapped in
1527 braces, as in:
1528 { LIST { QUAD ... } { < xyz.quad } }
1530 A ‘LIST’ with no elements, i.e. ‘{ LIST }’, is valid, and
1532is
1533 the easiest way to create an empty object. For example,
1534to remove a
1535 symbol’s definition you might write
1536 { define somesymbol { LIST } }
1538 TLIST Files
1542 ‐‐‐‐‐‐‐‐‐‐‐
1543Geometry Center Thu Dec 12 02:36:08 CST 1996 20
1549OOGL(5) OOGL(5)
1555 The conventional suffix for a ‘TLIST’ file is ‘.grp’
1558("group")
1559 or or ‘.prj’ ("projective" matrices).
1560 Collection of 4x4 matrices, used in the ‘transforms’ sec‐
1562tion of and
1563 ‘INST’ object.
1564 Syntax:
1566 TLIST # key word
1568 <4x4 matrix (16 floats)>
1570... # Any number of 4x4 matrices
1571 ‘TLIST’s are used only within the ‘transforms’ clause of
1573an
1574 ‘INST’ object. They cause the ‘INST’s ‘geom’ object to
1575 be instantiated once under each of the transforms in the
1576‘TLIST’.
1577 The effect is like that of a ‘LIST’ of ‘INST’s each with a
1578 single transform, and all referring to the same object,
1579but is more
1580 efficient.
1581 Be aware that a ‘TLIST’ is a kind of geometry object, dis‐
1583tinct from a
1584 ‘transform’ object. Some contexts expect one type of ob‐
1585ject,
1586 some the other. For example in INST transform
1587{ : MYT } geom { ... }
1588 MYT must be a transform object, which might have been
1589 created with the gcl (read transform { define
1590myT 1 0 0 1 ... })
1591 while in INST transforms { : MYTS } geom {
1592... } or INST transforms { LIST {: MYTS} {<
1593more.prj} } geom { ... }
1594 MYTS must be a geometry object, defined e.g. with
1595 (read geometry { define MYTS { TLIST 1 0 0 1 ...
1596} })
1597 A ‘TLIST BINARY’ format is accepted. Binary data begins
1599with a
1600 32‐bit integer giving the number of transformations, fol‐
1601lowed by that
1602 number of 4x4 matrices in 32‐bit floating‐point for‐
1603mat. The order of
1604 matrix elements is the same as in the ASCII format.
1605 GROUP Files
1609 ‐‐‐‐‐‐‐‐‐‐‐
1610 This format is obsolete, but is still accepted. It com‐
1612bined the
1613 functions of ‘INST’ and ‘TLIST’, taking a series of
1614 transformations and a single Geom (‘unit’) object, and
1615replicating
1616 the object under each transformation.
1617 GROUP ... < matrices > ... unit { OOGL‐OBJECT }
1619 is still accepted and effectively translated into
1621 INST transforms { TLIST ... <matri‐
1623ces> ... }
1624Geometry Center Thu Dec 12 02:36:08 CST 1996 21
1628OOGL(5) OOGL(5)
1634 unit { OOGL‐OBJECT }
1637 DISCGRP Files
1640 ‐‐‐‐‐‐‐‐‐‐‐‐‐
1641 This format is for discrete groups, such as appear in the
1643theory of
1644 manifolds or in symmetry patterns. This format has its
1645own man page.
1646 See discgrp(5).
1647 COMMENT Objects
1650 ‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐
1651 The COMMENT object is a mechanism for encoding arbitrary
1653data within an
1654 OOGL object. It can be used to keep track of data or pass
1655data back and
1656 forth between external modules.
1657 Syntax:
1659 COMMENT # key word
1661 NAME TYPE # individual name and type specifier
1663 { ... } # arbitrary data
1664 The data, which must be enclosed by curly braces, can in‐
1666clude anything
1667 except unbalanced curly braces. The TYPE field can be
1668used to
1669 identify data of interest to a particular program through
1670naming
1671 conventions.
1672 ‘COMMENT’ objects are intended to be associated with other
1674objects
1675 through inclusion in a ‘LIST’ object. (*Note LIST::.) The
1676"#" OOGL
1677 comment syntax does not suffice for data exchange since
1678these comments
1679 are stripped when an OOGL object is read in to Geomview.
1680The
1681 ‘COMMENT’ object is preserved when loaded into Geomview
1682and is
1683 written out intact.
1684 Here is an example associating a WorldWide Web URL with a
1686piece of
1687 geometry:
1688 { LIST { < Tetrahedron}
1690{COMMENT GCHomepage HREF { http://www.geomview.org }}
1691}
1692 A binary ‘COMMENT’ format is accepted. Its format is not
1694consistent
1695 with the other OOGL binary formats. *Note Binary format::.
1696The
1697 ‘name’ and ‘type’ are followed by
1698 N BYTE1 BYTE2 ... BYTEN
1700 instead of data enclosed in curly braces.
1702Geometry Center Thu Dec 12 02:36:08 CST 1996 22
1708OOGL(5) OOGL(5)
1714 Non‐geometric objects
1717 =====================
1718 The syntax of these objects is given in the form used in
1721 *Note References::, where "quoted" items should appear
1722literally but
1723 without quotes, square bracketed ([ ]) items are optional,
1724and | separates
1725 alternative choices.
1726 Transform Objects
1728 ‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐
1729 Where a single 4x4 matrix is expected ‐‐ as in the
1731 ‘INST’ ‘transform’ field, the camera’s ‘camtoworld’ trans‐
1732form
1733 and the Geomview ‘xform*’ commands ‐‐ use a transform ob‐
1734ject.
1735 Note that a transform is distinct from a ‘TLIST’, which is
1737a type
1738 of geometry. ‘TLIST’s can contain one or more 4x4 trans‐
1739formations;
1740 "transform" objects must have exactly one.
1741 Why have both? In many places ‐‐ e.g. camera positioning
1743‐‐ it’s only
1744 meaningful to have a single transform. Using a separate
1745object type
1746 enforces this.
1747 Syntax for a transform object is
1749 <transform> ::= [ "{" ]
1751(curly brace, generally needed to make
1752 the end of the object unam‐
1753biguous.)
1754 [ "transform" ] (optional keyword; unnecessary
1756if the type is determined by
1757the context, which it usually
1758is.) [ "define" <name> ]
1759 (defines a transform named
1760<name>, setting its value from
1761the stuff which follows)
1762 <sixteen floating‐point numbers>
1764 (interpreted as a 4x4 homoge‐
1765neous transform given row by row,
1766intended to apply to a row
1767vector multiplied on its LEFT, so that e.g.
1768 Euclidean translations appear
1769in the bottom row) | "<" <file‐
1770name> (meaning: read transform from that file) |
1771 ":" <name> (meaning: use variable <name>,
1772 defined elsewhere; if unde‐
1773fined the initial value is
1774the identity transform)
1775 [ "}" ] (matching curly brace)
1777 The whole should be enclosed in { braces }. Braces are
1779not essential
1780 if exactly one of the above items is present, so e.g. a
17814x4 array of
1782 floats standing alone may but needn’t have braces.
1783Geometry Center Thu Dec 12 02:36:08 CST 1996 23
1787OOGL(5) OOGL(5)
1793 Some examples, in contexts where they might be used:
1796 # Example 1: A gcl command to define a transform
1798 # called "fred"
1799 (read transform { transform define fred
1801 1 0 0 0 0 1 0 0
1802 0 0 1 0 ‐3 0 1 1
1803 } )
1804 # Example 2: A camera object using transform
1806 # "fred" for camera positioning # Given
1807the definition above, this puts the camera at # (‐3,
18080, 1), looking toward ‐Z.
1809 { camera halfyfield 1
1811 aspect 1.33 camtoworld {
1812: fred } }
1813 cameras
1816 ‐‐‐‐‐‐‐
1817 A camera object specifies the following properties of a
1819camera:
1820 position and orientation specified by either a
1822camera‐to‐world or world‐to‐camera transformation;
1823this transformation does not include the projection, so it’s typ‐
1824ically just a combination of translation and rota‐
1825tion. Specified as a transform object, typically a
18264x4 matrix.
1827 "focus" distance Intended to suggest a typical
1828distance from the camera to the object of interest;
1829used for default camera positioning (the camera is placed at
1830 (X,Y,Z) = (0,0,focus) when reset) and for adjusting
1831field‐of‐view when switching between perspective and
1832orthographic views.
1833 window aspect ratio True aspect ratio in the
1834sense <Xsize>/<Ysize>. This normally should agree
1835with the aspect ratio of the camera’s window. Geomview
1836normally adjusts the aspect ratio of its cameras to
1837match their associated windows.
1838 near and far clipping plane distances Note
1839that both must be strictly greater than zero. Very large
1840 <far>/<near> distance ratios cause Z‐buffering to be‐
1841have badly; part of an object may be visible even if
1842somewhat more distant than another.
1843 field of view Specified in either of two
1844forms. ‘fov ’
1845 is the field of view ‐‐ in degrees if perspec‐
1847tive, or linear
1848Geometry Center Thu Dec 12 02:36:08 CST 1996 24
1852OOGL(5) OOGL(5)
1858 distance if orthographic ‐‐ in the *shorter* di‐
1861rection. ‘halfyfield ’
1862 is half the projected Y‐axis field, in world co‐
1864ordinates (not angle!), at unit distance from
1865the camera. For a perspective camera, halfyfield
1866 is related to angular field:
1867 halfyfield = tan( Y_axis_angular_field
1869/ 2 )
1870 while for an orthographic one it’s simply:
1872 halfyfield = Y_axis_linear_field /
18742
1875 This odd‐seeming definition is (a) easy to calculate
1878with and (b) well‐defined in both orthographic and
1879perspective views.
1880 The syntax for a camera is:
1883 <camera> ::=
1885 [ "camera" ] (optional keyword)
1887 [ "{" ] (opening brace, general‐
1888ly required) [ "define" <name> ]
1889 "<" <filename> |
1891 ":" <name> |
1892 (or any number of the following,
1893 in any order...)
1894 "perspective" {"0" | "1"} (default 1)
1896 (otherwise orthographic)
1897 "stereo" {"0" | "1"} (default 0)
1899 (otherwise mono)
1900 "worldtocam" <transform> (see transform syntax
1902above)
1903 "camtoworld" <transform>
1905 (no point in specifying both
1906 camtoworld and worldtocam; one
1907is constrained to be the inverse
1908of the other)
1909 "halfyfield" <half‐linear‐Y‐field‐at‐unit‐dis‐
1911tance> (default tan 40/2 degrees)
1912 "fov" (angular field‐of‐view if per‐
1914spective, linear field‐of‐view other‐
1915wise. Measured in whichever direc‐
1916tion is smaller, given the aspect ra‐
1917tio. When aspect ratio changes ‐‐
1918e.g. when a window is reshaped ‐‐
1919Geometry Center Thu Dec 12 02:36:08 CST 1996 25
1923OOGL(5) OOGL(5)
1929 "fov" is preserved.)
1932 "frameaspect" <aspect‐ratio> (X/Y) (default
19341.333)
1935 "near" <near‐clipping‐distance> (default 0.1)
1937 "far" <far‐clipping‐distance> (default
193910.0)
1940 "focus" <focus‐distance> (default 3.0)
1942 [ "}" ] (matching closebrace)
1945 window
1949 ‐‐‐‐‐‐
1950 A window object specifies size, position, and other win‐
1952dow‐system
1953 related information about a window in a device‐independent
1954way.
1955 The syntax for a window object is:
1957 window ::=
1959 [ "window" ] (optional keyword)
1961 [ "{" ] (curly brace, often required)
1962 (any of the following, in any or‐
1964der)
1965 "size" <xsize> <ysize>
1967 (size of the window)
1968 "position" <xmin> <xmax> <ymin> <ymax>
1970 (position & size)
1971 "noborder"
1974 (specifies the window should
1975 have no window border)
1976 "pixelaspect" <aspect>
1978 (specifies the true visual aspect
1979ratio of a pixel in this window
1980in the sense xsize/ysize, normal‐
1981ly 1.0. For stereo hardware
1982which stretches the display ver‐
1983tically by a factor of 2, "pixe‐
1984laspect 0.5" might do. The value
1985is used when computing the pro‐
1986jection of a camera associated with
1987 this window.)
1988 [ "}" ] (matching closebrace)
1990Geometry Center Thu Dec 12 02:36:08 CST 1996 26
1995OOGL(5) OOGL(5)
2001 Window objects are used in the Geomview ‘window’ and
2004 ‘ui‐panel’ commands to set default properties for future
2005windows or
2006 to change those of an existing window.
2007Geometry Center Thu Dec 12 02:36:08 CST 1996 27
2062