1
2
3
4OOGL(5gv)
5OOGL(5gv)
6
7
8NAME
9       OOGL ‐ File formats for OOGL geometric objects
10
11NOTE
12       The  material  in  this  manual  page  also appears in the
13       Geomview manual.
14
15DESCRIPTION
16       OOGL File Formats
17       *****************
18
19       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
25       There are many  different  kinds  of  OOGL  objects.  This
26chapter gives
27       syntactic descriptions of file formats for OOGL objects.
28
29       Examples of most file types live in Geomview’s ‘data/geom’
30       directory.
31
32       Conventions
33       ===========
34
35       Syntax Common to All OOGL File Formats
36       ‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐
37
38       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
49       Binary formats are also defined for several objects; *Note
50Binary format::, and the individual object descriptions.
51
52       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
63       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
70
71       File Names
72       ‐‐‐‐‐‐‐‐‐‐
73
74       When OOGL objects are read from disk files, the  OOGL  li‐
75brary uses the
76       file suffix to guess at the file type.
77
78       If  the  suffix is unrecognized, or if no suffix is avail‐
79able (e.g. for an
80
81
82
83Geometry Center    Thu Dec 12 02:36:08 CST 1996                 1
84
85
86
87
88
89OOGL(5)                                                   OOGL(5)
90
91
92       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
98
99       Vertices
100       ‐‐‐‐‐‐‐‐
101
102       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
109       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
114       The syntax is
115
116       ‘X   Y   Z’             (3‐D floating‐point vertex coordi‐
117nates) or
118       ‘X  Y  Z  W’             (4‐D floating‐point vertex  coor‐
119dinates)
120
121       optionally followed by
122
123       ‘NX  NY  NZ’             (normalized 3‐D surface‐normal if
124present)
125
126       optionally followed by
127
128       ‘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
133            optionally followed by
134       ‘S T’
135       ‘or’
136       ‘S T U’
137
138       (two or three texture‐coordinate values).
139
140       Values are separated by white space, and line breaks
141       are immaterial.
142
143       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
155
156       Surface normal directions
157       ‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐
158
159
160
161Geometry Center    Thu Dec 12 02:36:08 CST 1996                 2
162
163
164
165
166
167OOGL(5)                                                   OOGL(5)
168
169
170       Geomview uses normal vectors to determine how an object is
171shaded.
172       The  direction of the normal is significant in this calcu‐
173lation.
174
175       When normals are supplied with an object, the direction of
176the normal
177       is determined by the data given.
178
179       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
185       On  parametric  surfaces  (Bezier  patches), the normal at
186point P(u,v)
187       is in the direction dP/du cross dP/dv.
188
189
190       Transformation matrices
191       ‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐
192
193       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
208
209       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
216
217       Binary format
218       ‐‐‐‐‐‐‐‐‐‐‐‐‐
219
220       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
230            OFF BINARY     # binary‐format "OFF" data follows
231
232       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
240       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
250       Binary  OOGL  objects  may be freely mixed in ASCII object
251streams:
252
253
254
255Geometry Center    Thu Dec 12 02:36:08 CST 1996                 3
256
257
258
259
260
261OOGL(5)                                                   OOGL(5)
262
263
264            LIST             { = MESH BINARY             ...  bi‐
265nary  data  for mesh here ...              }             { = QUAD
266                 1 0 0  0 0 1   0 1 0  0 1 0             }
267
268       Note that ASCII data  resumes  immediately  following  the
269last byte of
270       binary data.
271
272       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
278
279       Embedded objects and external‐object references
280       ‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐
281
282       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
291       The general syntax is
292
293               <oogl‐object>    ::=                     [  "{"  ]
294                     [ "define" ‘symbolname’  ]
295[  "appearance"  ‘appearance’ ]                      [ ["="] ‘ob‐
296ject‐keyword’  ...                           |   "<"   ‘filename’
297                        |  ":"  ‘symbolname’ ]                  [
298"}" ]
299
300       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
312       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
316                  {  appearance  { +edge } LIST { < "file1" } { :
317fred } }
318
319                 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
324       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.
329
330
331
332Geometry Center    Thu Dec 12 02:36:08 CST 1996                 4
333
334
335
336
337
338OOGL(5)                                                   OOGL(5)
339
340
341       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
350       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
361       Again, white space and line breaks are insignificant,  and
362"#" comments
363       may appear anywhere.
364
365
366
367       Appearances
368       ‐‐‐‐‐‐‐‐‐‐‐
369
370       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
380       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
386       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
396       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
402            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
413              +evert               #  do  evert  polygon  normals
414where  needed  so as                                   #   to al‐
415ways face the camera
416
417              ‐texturing           #  (Disable)  texture  mapping
418               ‐backcull                 # (Don’t) discard clock‐
419wise‐oriented faces
420
421
422
423Geometry Center    Thu Dec 12 02:36:08 CST 1996                 5
424
425
426
427
428
429OOGL(5)                                                   OOGL(5)
430
431
432              ‐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
439               ‐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
446              shading smooth       #  or  "shading  constant"  or
447"shading flat" or                                   # or "shading
448csmooth".                                    # smooth  =  Gouraud
449shading,  flat  =  faceted,                                     #
450csmooth = smoothly interpolated but unlighted.
451
452              linewidth 1         # lines, points, and edges  are
4531 pixel wide.
454
455              patchdice 10 10     # subdivide Bezier patches this
456finely in u and v
457
458              material {         # Here’s a material  definition;
459                                   # it could also be read from a
460file  as  in                                     #   "material  <
461file.mat"
462
463                   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
471                   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
477                   ks  1.0          # specular reflection coeffi‐
478cient.                    specular 1 1 1  # specular  (highlight)
479color.                      shininess   25   # specular exponent;
480larger values give                                     #  sharper
481highlights.
482
483                   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
493                  alpha   1.0     # opacity; 0 = transparent (in‐
494visible), 1 = opaque.                                      #  Ig‐
495nored when transparency is disabled.
496
497                  edgecolor   1 1 0  # line & edge color
498
499                   normalcolor  0 0 0  # color for surface‐normal
500vectors               }
501
502
503
504
505Geometry Center    Thu Dec 12 02:36:08 CST 1996                 6
506
507
508
509
510
511OOGL(5)                                                   OOGL(5)
512
513
514              lighting {         # Lighting model
515
516                  ambient  .3 .3 .3  # ambient light
517
518                   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
525                                   #  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
536                  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
562                    background 1 0 0 1     # relevant for  "apply
563blend"                 }              }                     # end
564appearance
565
566
567       There are rules for inheritance of  appearance  attributes
568when several
569       are imposed at different levels in the hierarchy.
570
571       For example, Geomview installs a backstop appearance which
572provides
573
574
575
576Geometry Center    Thu Dec 12 02:36:08 CST 1996                 7
577
578
579
580
581
582OOGL(5)                                                   OOGL(5)
583
584
585       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
591       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
598       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
607
608       Texture Mapping
609       ‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐
610
611       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
628       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
634       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
640       The available fields are:
641
642            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
651            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
658
659
660
661Geometry Center    Thu Dec 12 02:36:08 CST 1996                 8
662
663
664
665
666
667OOGL(5)                                                   OOGL(5)
668
669
670               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
686              If an ‘alphafile’ image is supplied, it must be the
687same size               as the ‘file’ image.
688
689
690            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
695              With ‘modulate’, the default, the texture color (or
696lightness,               if textured by a  gray‐scale  image)  is
697multiplied by the surface color.
698
699               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
707               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
715             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
720            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.
728
729
730
731
732Geometry Center    Thu Dec 12 02:36:08 CST 1996                 9
733
734
735
736
737
738OOGL(5)                                                   OOGL(5)
739
740
741       Object File Formats
742       ===================
743
744       QUAD: collection of quadrilaterals
745       ‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐
746
747       The conventional suffix for a ‘QUAD’ file is ‘.quad’.
748
749       The file syntax is
750
751               [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
756       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
764       ‘QUAD’ ‘CQUAD’ ‘NQUAD’ ‘CNQUAD’ ‘POLY’
765       ‘CPOLY’ ‘NPOLY’ ‘CNPOLY’
766
767       (but not ‘NCQUAD’ or ‘NCPOLY’).  ‘QUAD’ and ‘POLY’
768       are  synonymous;  both forms are allowed just for compati‐
769bility with
770       ChapReyes.
771
772       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
780       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
788
789       MESH: rectangularly‐connected mesh
790       ‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐
791
792       The conventional suffix for a ‘MESH’ file is ‘.mesh’.
793
794       The file syntax is
795
796             [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)
804
805
806
807Geometry Center    Thu Dec 12 02:36:08 CST 1996                10
808
809
810
811
812
813OOGL(5)                                                   OOGL(5)
814
815
816       The key word is  ‘[U][C][N][Z][4][u][v][n]MESH’.
817       The optional prefix characters mean:
818
819       ‘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
847       Note that the order of prefix characters is significant; a
848colored,
849       u‐wrapped mesh is a ‘CuMESH’ not a ‘uCMESH’.
850
851       Following the mesh header are integers NU and NV,
852       the dimensions of the mesh.
853
854       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
860             (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
864       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
869
870       Bezier Surfaces
871       ‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐
872
873
874
875Geometry Center    Thu Dec 12 02:36:08 CST 1996                11
876
877
878
879
880
881OOGL(5)                                                   OOGL(5)
882
883
884       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
890       Syntax:
891
892                   [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
901                       #  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
909                            # 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
914                           # 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
919       These  formats  represent  collections  of  Bezier surface
920patches, of
921       degrees up to 6, and with 3‐D or 4‐D (rational) vertices.
922
923       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
927       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
933       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
939       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
943       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.
948
949
950
951
952Geometry Center    Thu Dec 12 02:36:08 CST 1996                12
953
954
955
956
957
958OOGL(5)                                                   OOGL(5)
959
960
961       ‘BBP’ patches are bicubic patches with  3‐D  vertices,  so
962‘BBP’
963       = ‘BEZ333’ and ‘STBBP’ = ‘BEZ333_ST’.
964
965       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
971       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
981       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
988       If the header calls for colors, four four‐component  (red,
989green, blue,
990       alpha)  floating‐point  colors  follow, one for each patch
991corner.
992
993       The series of patches  ends  at  end‐of‐file,  or  with  a
994closebrace if
995       incorporated in an object reference.
996
997       Info file: geomview,    ‐*‐Text‐*‐
998       produced by texinfo‐format‐buffer
999       from file: geomview.tex
1000
1001
1002
1003       OFF Files
1004       ‐‐‐‐‐‐‐‐‐
1005
1006       The conventional suffix for ‘OFF’ files is ‘.off’.
1007
1008       Syntax:
1009
1010              [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
1015            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]
1025
1026
1027
1028Geometry Center    Thu Dec 12 02:36:08 CST 1996                13
1029
1030
1031
1032
1033
1034OOGL(5)                                                   OOGL(5)
1035
1036
1037                            #  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
1049       ‘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
1057       An ‘OFF’ file may begin with the keyword ‘OFF’; it’s
1058       recommended but optional, as many existing files lack this
1059keyword.
1060
1061       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
1068       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
1076       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
1084       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
1091       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
1099       For  the  one‐integer case, the colormap is currently read
1100from the file
1101       ‘cmap.fmap’ in Geomview’s ‘data’ directory.  Some better
1102
1103
1104
1105Geometry Center    Thu Dec 12 02:36:08 CST 1996                14
1106
1107
1108
1109
1110
1111OOGL(5)                                                   OOGL(5)
1112
1113
1114       mechanism for supplying a colormap is likely someday.
1115
1116       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
1123       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
1133       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
1141            int int int int int             3   17   5   9   0
1142
1143       while the same face colored red might be
1144
1145            int int int int int float float float float
11463  17   5       9   4   1.0   0.0   0.0   1.0
1147
1148
1149
1150       VECT Files
1151       ‐‐‐‐‐‐‐‐‐‐
1152
1153       The conventional suffix for ‘VECT’ files is ‘.vect’.
1154
1155       Syntax:
1156
1157            [4]VECT             NPOLYLINES  NVERTICES  NCOLORS
1158
1159             NV[0]  ... NV[NPOLYLINES‐1]     # number of vertices
1160                                                       # in  each
1161polyline
1162
1163             NC[0]  ...  NC[NPOLYLINES‐1]      # number of colors
1164supplied                                                        #
1165in each polyline
1166
1167             VERT[0]  ...  VERT[NVERTICES‐1]   # All the vertices
1168                                                       # (3*NVer‐
1169tices floats)
1170
1171             COLOR[0]  ...  COLOR[NCOLORS‐1]   #  All  the colors
1172                                                       # (4*NCol‐
1173ors floats, RGBA)
1174
1175       ‘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
1181       A ‘VECT’ file begins with the key word ‘VECT’ or ‘4VECT’
1182
1183
1184
1185Geometry Center    Thu Dec 12 02:36:08 CST 1996                15
1186
1187
1188
1189
1190
1191OOGL(5)                                                   OOGL(5)
1192
1193
1194       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
1199       Next come NLINES integers
1200
1201            NV[0] NV[1] NV[2] ... NV[NLINES‐1]
1202
1203       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
1209       Next come NLINES more integers Nc[i]: the number of colors
1210in
1211       each polyline.  Normally one of three values:
1212
1213       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
1223       The sum of the NC[I] must equal NCOLORS.
1224
1225       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
1234       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
1240       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
1247
1248
1249
1250       SKEL Files
1251       ‐‐‐‐‐‐‐‐‐‐
1252
1253       ‘SKEL’  files  represent  collections  of points and poly‐
1254lines, with
1255       shared vertices.
1256       The conventional suffix for ‘SKEL’ files is ‘.skel’.
1257
1258       Syntax:
1259
1260
1261
1262
1263Geometry Center    Thu Dec 12 02:36:08 CST 1996                16
1264
1265
1266
1267
1268
1269OOGL(5)                                                   OOGL(5)
1270
1271
1272            [4][n]SKEL               [NDIM]                     #
1273Vertex  dimension,  present  only  if nSKEL             NVERTICES
1274NPOLYLINES
1275
1276                 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
1281                                             #          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
1293       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
1300       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
1304       No ‘BINARY’ format is implemented as yet  for  ‘SKEL’  ob‐
1305jects.
1306
1307
1308       SPHERE Files
1309       ‐‐‐‐‐‐‐‐‐‐‐‐
1310
1311       The conventional suffix for ‘SPHERE’ files is ‘.sph’.
1312
1313            SPHERE             RADIUS             XCENTER YCENTER
1314ZCENTER
1315
1316       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
1325
1326       INST Files
1327       ‐‐‐‐‐‐‐‐‐‐
1328
1329       The conventional suffix for a ‘INST’ file is ‘.inst’.
1330
1331       There is no INST BINARY format.
1332
1333       An ‘INST’ applies a 4x4 transformation to another OOGL ob‐
1334ject.  It
1335
1336
1337
1338Geometry Center    Thu Dec 12 02:36:08 CST 1996                17
1339
1340
1341
1342
1343
1344OOGL(5)                                                   OOGL(5)
1345
1346
1347       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
1372       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
1380       *Note Transformation matrices::, for the matrix format.
1381
1382
1383       Two more INST fields are accepted:  ‘location’  and  ‘ori‐
1384gin’.
1385
1386            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,
1411
1412
1413
1414Geometry Center    Thu Dec 12 02:36:08 CST 1996                18
1415
1416
1417
1418
1419
1420OOGL(5)                                                   OOGL(5)
1421
1422
1423            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
1435       ‘location  local’ is the default; the object is positioned
1436relative
1437       to its parent.
1438
1439
1440            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
1450       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
1455       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
1462       INST Examples         .............
1463
1464       Here are some examples of ‘INST’ files
1465
1466               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
1471             { appearance { +edge  material { edgecolor 1 1 0 } }
1472                INST geom < mysurface.quad }
1473
1474            {INST transform {: T} geom {<dodec.off}}
1475
1476            { INST                   transforms
1477{ LIST
1478
1479
1480
1481Geometry Center    Thu Dec 12 02:36:08 CST 1996                19
1482
1483
1484
1485
1486
1487OOGL(5)                                                   OOGL(5)
1488
1489
1490                       {  <  some‐matrices.prj }
1491{ < others.prj }                       {  TLIST  <still  more  of
1492them> }
1493
1494                      }                    geom
1495{ # stuff replicated by all the above  matrices
1496...                       }             }
1497
1498       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
1507       LIST Files
1508       ‐‐‐‐‐‐‐‐‐‐
1509
1510       The conventional suffix for a ‘LIST’ file is ‘.list’.
1511
1512       A list of OOGL objects
1513
1514       Syntax:
1515
1516                      LIST                            OOGL‐OBJECT
1517                OOGL‐OBJECT                 ...
1518
1519       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
1529               { LIST { QUAD ... } { < xyz.quad } }
1530
1531       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
1537               { define somesymbol  { LIST } }
1538
1539
1540
1541       TLIST Files
1542       ‐‐‐‐‐‐‐‐‐‐‐
1543
1544
1545
1546
1547
1548Geometry Center    Thu Dec 12 02:36:08 CST 1996                20
1549
1550
1551
1552
1553
1554OOGL(5)                                                   OOGL(5)
1555
1556
1557       The  conventional  suffix  for  a  ‘TLIST’  file is ‘.grp’
1558("group")
1559       or or ‘.prj’ ("projective" matrices).
1560
1561       Collection of 4x4 matrices, used in the ‘transforms’  sec‐
1562tion of and
1563       ‘INST’ object.
1564
1565       Syntax:
1566
1567            TLIST               # key word
1568
1569                <4x4     matrix     (16     floats)>
1570...                 # Any number of 4x4 matrices
1571
1572       ‘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
1582       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
1598       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
1606
1607
1608       GROUP Files
1609       ‐‐‐‐‐‐‐‐‐‐‐
1610
1611       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
1618            GROUP ... < matrices > ... unit { OOGL‐OBJECT }
1619
1620       is still accepted and effectively translated into
1621
1622            INST                  transforms { TLIST ...  <matri‐
1623ces> ... }
1624
1625
1626
1627Geometry Center    Thu Dec 12 02:36:08 CST 1996                21
1628
1629
1630
1631
1632
1633OOGL(5)                                                   OOGL(5)
1634
1635
1636                 unit { OOGL‐OBJECT }
1637
1638
1639       DISCGRP Files
1640       ‐‐‐‐‐‐‐‐‐‐‐‐‐
1641
1642       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
1648
1649       COMMENT Objects
1650       ‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐
1651
1652       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
1658       Syntax:
1659
1660            COMMENT                 # key word
1661
1662             NAME  TYPE   #  individual  name  and type specifier
1663            { ... }         # arbitrary data
1664
1665       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
1673       ‘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
1685       Here is an example associating a WorldWide Web URL with  a
1686piece of
1687       geometry:
1688
1689              {  LIST                {  <  Tetrahedron}
1690{COMMENT GCHomepage HREF {  http://www.geomview.org  }}
1691}
1692
1693       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
1699            N BYTE1 BYTE2 ... BYTEN
1700
1701       instead of data enclosed in curly braces.
1702
1703
1704
1705
1706
1707Geometry Center    Thu Dec 12 02:36:08 CST 1996                22
1708
1709
1710
1711
1712
1713OOGL(5)                                                   OOGL(5)
1714
1715
1716       Non‐geometric objects
1717       =====================
1718
1719
1720       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
1727       Transform Objects
1728       ‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐
1729
1730       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
1736       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
1742       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
1748       Syntax for a transform object is
1749
1750             <transform>  ::=                 [  "{" ]
1751(curly      brace,      generally      needed       to       make
1752                                    the  end  of the object unam‐
1753biguous.)
1754
1755               [ "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
1763                       <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
1776             [ "}" ]              (matching curly brace)
1777
1778       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.
1783
1784
1785
1786Geometry Center    Thu Dec 12 02:36:08 CST 1996                23
1787
1788
1789
1790
1791
1792OOGL(5)                                                   OOGL(5)
1793
1794
1795       Some examples, in contexts where they might be used:
1796
1797             #  Example  1:  A  gcl command to define a transform
1798            # called "fred"
1799
1800              (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
1805             #  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
1810              {   camera                          halfyfield    1
1811                     aspect 1.33                     camtoworld {
1812: fred }             }
1813
1814
1815       cameras
1816       ‐‐‐‐‐‐‐
1817
1818       A camera object specifies the following  properties  of  a
1819camera:
1820
1821       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
1846                 is the field of view ‐‐ in degrees  if  perspec‐
1847tive, or linear
1848
1849
1850
1851Geometry Center    Thu Dec 12 02:36:08 CST 1996                24
1852
1853
1854
1855
1856
1857OOGL(5)                                                   OOGL(5)
1858
1859
1860                 distance if orthographic ‐‐ in the *shorter* di‐
1861rection.                    ‘halfyfield ’
1862
1863                 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
1868                           halfyfield = tan( Y_axis_angular_field
1869/ 2 )
1870
1871                 while for an orthographic one it’s simply:
1872
1873                              halfyfield = Y_axis_linear_field  /
18742
1875
1876
1877             This odd‐seeming definition is (a) easy to calculate
1878with and             (b) well‐defined in  both  orthographic  and
1879perspective views.
1880
1881
1882       The syntax for a camera is:
1883
1884            <camera> ::=
1885
1886                [  "camera"  ]                (optional  keyword)
1887                [ "{" ]                  (opening brace, general‐
1888ly required)                  [ "define" <name> ]
1889
1890                     "<"     <filename>                         |
1891                     ":"     <name>                             |
1892                                (or  any number of the following,
1893                                 in any order...)
1894
1895                 "perspective"  {"0" | "1"}          (default  1)
1896                                     (otherwise orthographic)
1897
1898                  "stereo"       {"0"  | "1"}         (default 0)
1899                                     (otherwise mono)
1900
1901                 "worldtocam" <transform> (see  transform  syntax
1902above)
1903
1904                             "camtoworld"             <transform>
1905                                (no  point  in  specifying   both
1906                                  camtoworld  and worldtocam; one
1907is                                  constrained to be the inverse
1908of                            the other)
1909
1910                  "halfyfield"  <half‐linear‐Y‐field‐at‐unit‐dis‐
1911tance>                                 (default tan 40/2 degrees)
1912
1913                 "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 ‐‐
1919
1920
1921
1922Geometry Center    Thu Dec 12 02:36:08 CST 1996                25
1923
1924
1925
1926
1927
1928OOGL(5)                                                   OOGL(5)
1929
1930
1931                            "fov" is preserved.)
1932
1933                  "frameaspect"  <aspect‐ratio>   (X/Y)  (default
19341.333)
1935
1936                 "near"  <near‐clipping‐distance>   (default 0.1)
1937
1938                 "far"     <far‐clipping‐distance>       (default
193910.0)
1940
1941                 "focus" <focus‐distance>      (default 3.0)
1942
1943
1944                 [ "}" ]                  (matching closebrace)
1945
1946
1947
1948       window
1949       ‐‐‐‐‐‐
1950
1951       A  window  object specifies size, position, and other win‐
1952dow‐system
1953       related information about a window in a device‐independent
1954way.
1955
1956       The syntax for a window object is:
1957
1958            window ::=
1959
1960                  [  "window"  ]              (optional  keyword)
1961                   [ "{" ]       (curly brace, often required)
1962
1963                                (any of the following, in any or‐
1964der)
1965
1966                             "size"         <xsize>       <ysize>
1967                                (size of the window)
1968
1969                      "position"   <xmin>  <xmax>  <ymin>  <ymax>
1970                                (position & size)
1971
1972
1973                                                       "noborder"
1974                                (specifies  the   window   should
1975                                 have no window border)
1976
1977                                "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
1989                   [ "}" ]           (matching closebrace)
1990
1991
1992
1993
1994Geometry Center    Thu Dec 12 02:36:08 CST 1996                26
1995
1996
1997
1998
1999
2000OOGL(5)                                                   OOGL(5)
2001
2002
2003       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.
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
2025
2026
2027
2028
2029
2030
2031
2032
2033
2034
2035
2036
2037
2038
2039
2040
2041
2042
2043
2044
2045
2046
2047
2048
2049
2050
2051
2052
2053
2054
2055
2056
2057
2058
2059
2060
2061Geometry Center    Thu Dec 12 02:36:08 CST 1996                27
2062
2063
2064
2065
2066
2067
2068
2069
2070
2071
2072
2073
2074
2075
2076
2077
2078
2079
2080
2081
2082
2083
2084
2085
2086
2087
2088
2089
2090
2091
2092
2093
2094
2095
2096
2097
2098
2099
2100
2101
2102
2103
2104
2105
2106
2107
2108
2109
2110
2111
2112
Impressum