This is geomview, produced by Makeinfo version 3.12h from geomview.texi. INFO-DIR-SECTION Graphics Applications START-INFO-DIR-ENTRY * Geomview: (geomview). The interactive 3D viewing program. END-INFO-DIR-ENTRY  File: geomview, Node: Cameras, Next: Saving, Prev: Lighting Panel, Up: Interaction Cameras ======= A camera in Geomview is the object that corresponds to a camera window. By default there is only one camera, but it is possible to have as many as you want. You can control certain aspects of the way the world is drawn in each camera window via the _Cameras_ panel. If the target object is a camera, the _Cameras_ panel affects that camera. If the target object is not a camera, the _Cameras_ panel affects the "current camera". The current camera is the camera of the window that the mouse cursor is in, or was in most recently if the cursor is not in a camera window. Thus, if you use the keyboard shortcuts for the actions in the _Cameras_ panel while the cursor is in a camera window, the actions apply to that camera, unless you have explicitly selected another camera. To create new camera windows, use the `v+' keyboard shortcut, or see the _File_ menu on the _Main_ panel. _Single-Buffering_ Normally, geomview windows are _double-buffered_: geomview draws the next picture into a hidden window, then switches buffers to make it visible all at once. On many systems, the memory for the hidden buffer comes from stealing half the bits in each screen pixel, reducing the color resolution. When single-buffering is enabled, the window flickers as each scene is being drawn, but you may get smoother images with reduced grainy dithering artifacts. Single-buffering is possible if Geomview is compiled with GL or OpenGL, but not with plain-X graphics. _Dither_ Many displays offer less than the 24 bits per pixel (8 bits each of red, green, and blue) conventionally needed to show smooth gradations of color. When trying to show a color not accurately available on the display, Geomview normally _dithers_, choosing pixel colors sometimes brighter, sometimes darker than the desired value, so that the average color over an area is a better approximation to the true color than a single pixel could be. Effectively this loses spatial resolution to gain color resolution. This isn't always desirable, though. Turning _Dither_ off gives less grainy, but less accurately colored, images. _Software Shading_ This button controls whether Geomview does shading calculations in software. The default is to let the hardware handle them, and in Euclidean space this is almost certainly best because it is faster. In hyperbolic and spherical space, however, the shading calculations that the hardware does are incorrect. Click this button to turn on correct but slower software shading. _Background Color_ This button brings up a color chooser which you can use to set the background color of the camera's window. _PROJECTION_ This browser lets you pick between perspective and orthogonal projection for this camera. _Near clip_ This determines the distance in world coordinates of the near clipping plane from the eye point. It must be a positive number. _Far clip_ This determines the distance in world coordinates of the far clipping plane from the eye point. It must be a positive number and in general should be larger than the _Near clip_ value. _FOV_ This is the camera's field of view, measured in its shorter direction. In perspective mode, it is an angle in degrees. In orthographic mode, it is the linear size of the field of view. This number can be modified with the mouse in _Cam Zoom_ mode. _Focal Length_ The focal length is intended to suggest the distance from the camera to an imaginary plane of interest. Its value is used when switching between orthographic and perspective views (and during stereo viewing), so as to preserve apparent size of objects lying at the focal distance from the camera. Focal length also affects interpretation of mouse-based translational motions. Speed of forward motion (in translate, fly and orbit modes) is proportional to focal length; and objects lying at the focal distance from the camera translate laterally at the same rate as the mouse cursor. Finally, in N-D projection mode, cameras are displaced back by the focal distance from the 3-D projection of the world origin. _Lines Closer_ This number has to do with the way lines are drawn. Normally Geomview's z-buffering algorithm can get confused when drawing lines that lie exactly on surfaces (such as the edges of an object); due to machine round-off error, sometimes the lines appear to be in front of the surface and sometimes they appear behind it. The _Lines Closer_ value is a fudge factor -- Geomview nudges all the lines that it draws closer to the camera by this amount. The number should be a small integer; try 5 or 10. 0 turns this feature off completely. Choosing too large a value will make lines visible even though they should be hidden. _SPACE MODEL_ This determines the model used to draw the world. It is most useful in hyperbolic and spherical spaces. You probably don't need to touch this browser if you stay in Euclidean space. For more information about these models, *note Non-Euclidean Geometry::.. _Virtual_ This is the default model and represents the natural view from inside the space. _Projective_ The projective model of hyperbolic and spherical space. Geoms move under isometries of the space, and cameras move by Euclidean motions. By default in the projective model, the Euclidean unit sphere is drawn. In hyperbolic space this is the sphere at infinity. In Euclidean space the projective model is the same as the virtual model except that the sphere is drawn by default. _Conformal_ The conformal model of hyperbolic and spherical space. Geoms move under isometries of the space, and cameras move by Euclidean motions. In Euclidean space, the conformal model amounts to inverting everything in the unit sphere. _Draw Sphere_ This controls whether Geomview draws the unit sphere. By default the unit sphere appears in the projective and conformal models. In hyperbolic space this is the sphere at infinity. In spherical space it is the equatorial sphere. _Done_ This button dismisses the _Cameras_ panel.  File: geomview, Node: Saving, Next: Commands, Prev: Cameras, Up: Interaction Saving your work ================ Geomview's _Save_ panel lets you store Geomview objects and other information in files that you can read back into Geomview or other programs. To use the _Save_ panel you select the desired format in the browser next to the word _Save_, enter the name of the object you want to save in the text field next to the word _for_, and enter the name of the file you wish to save to in the long text field next to the word _in_. You can then either hit `' or click on the _OK_ button. When the file has been written, the _Save_ panel disappears. If you want to dismiss the _Save_ panel without writing a file, click the _Cancel_ button. If you specify `-' as the file name, Geomview will write the file to standard output, i.e. in the shell window from which you invoked Geomview. The possible formats are given below. The kind of object that can be written with each format is given in parentheses. _Commands (any object)_ This write a file of gcl commands containing all information about the object. Loading this file later will restore the object as well as all other information about it, such as appearance, transformations, etc. _Geometry alone (geom)_ This writes an OOGL file containing just the geometry of the object. _Geometry [in world] (geom)_ This writes an OOGL file containing just the geometry of the object, transformed under Geomview's current transformation for this object. Use this if you have moved the object from its initial position and want to save the new position relative to the world. _Geometry [in universe] (geom)_ This writes an OOGL file containing just the geometry of the geom, transformed under both the object's transformation and the world's transformation. _RMan [->tiff] (camera)_ Writes a RenderMan file which when rendered creates a tiff image. _RMan [->frame] (camera)_ Writes a RenderMan file which when rendered causes an image to appear in a window on the screen. _SGI snapshot (camera)_ Write an SGI raster file. A bell rings when the snapshot is complete. Only available on SGI systems. _PPM Screen snapshot (camera)_ Take a snapshot of the given window and save it as a PPM image. If you specify a string beginning with a vertical bar (`|') as the file name, it's interpreted as a Bourne shell command to which the PPM data should be piped, as in `| pnmtotiff > snap.tiff' or `| convert -geometry 50% ppm:- snap.gif'. PPM screen snapshots are only available with GL and Open GL, not plain X graphics. The window should be entirely on the screen. Geomview will ensure that no other windows cover it while the snapshot is taken. _PPM software snapshot (camera)_ Writes a snapshot of that window's current view, as a PPM image, to the given file. The file name may be a Bourne shell command preceded by a vertical bar (`|'), as with the PPM screen snapshot. The software snapshot, though, is produced by using a built-in software renderer (related to the X-windows renderer). It doesn't matter whether the window is visible or not, and doesn't depend on GL or OpenGL. It also doesn't support some features, such as texture mapping. _Postscript snapshot (camera)_ Writes a Postscript snapshot of the camera's view. It's made by breaking up the scene into lines and polygons, sorting by depth, and generating Postscript lines and polygons for each one. Advantages over pixel-based snapshot images: resolution is very high, so edges look sharp even on high-resolution printers, or comparable-resolution images are typically much more compact. Disadvantages: depth-sorting gives good results on some scenes, but can be wildly wrong as a hidden-surface removal algorithm for other scenes. Also, Postscript doesn't offer smoothly interpolated shading, only flat shading for each facet. _Camera (camera)_ Writes an OOGL file of a camera. _Transform [to world] (any object)_ Writes an OOGL transform file giving Geomview's transform for the object. _Transform [to universe] (any object)_ Writes an OOGL transform file giving a transform which is the composition of Geomview's transform for the object and the transform for the world. _Window (camera)_ Writes an OOGL window file for a camera. _Panels_ Writes a gcl file containing commands which record the state of all the Geomview panels. Loading this file later will restore the positions of all the panels.  File: geomview, Node: Commands, Next: Keyboard Shortcuts, Prev: Saving, Up: Interaction The Commands Panel ================== The _Commands_ panel lets you type in a gcl command. When you hit `', Geomview interprets the command and prints any resulting output or error messages on standard output. You can edit the text and hit `' as many times as you like, in general, whenever you hit `' with the cursor in the _Commands_ panel, Geomview tries to interpret whatever text you have typed in the text field as a command. [Move this.] Normalization is a kind of scaling; Geomview can scale an object so that it fits within a certain region. The main point of normalization is to allow you to easily view all of an object without having to worry about how big it is. We are gradually replacing Geomview's normalization feature with more robust camera positioning features. In general, the best way to make sure you are seeing all of an object is to use the _Look At_ button on the _Tools_ panel. Normalization may be completely replaced by this and other features in a future version of Geomview. Normalization is a property that applies to each geom separately. The _NORMALIZE GEOMETRY_ browser affects the normalization property of target geom. If the target geom is "World", it affects all geoms. _None_ Do no normalization. _Individual_ Normalize this geom to fit within a unit sphere. _Sequence_ This resembles "Individual", except when an object is changing. Then, "Individual" tightly fits the bounding box around the object whenever it changes and normalizes accordingly, while "Sequence" normalizes the union of all variants of the object and normalizes accordingly. _Keep_ This leaves the current normalization transform unchanged when the object changes. It may be useful to apply "Individual" or "Sequence" normalization to the first version of a changing object to bring it in view, then switch to "Keep".  File: geomview, Node: Keyboard Shortcuts, Next: OOGL File Formats, Prev: Commands, Up: Interaction Keyboard Shortcuts ================== Most actions that you can do through Geomview's panels have equivalent keyboard shortcuts so that you can do the same action by typing a sequence of keys on the keyboard. This is useful for advanced users who are familiar with Geomview's capabilities and want to work quickly without having to have lots of panels cluttering up the screen. Keyboard shortcuts usually are indicated in square brackets ([ ]) near the corresponding item in a panel. For example, the keyboard shortcut for _Rotate_ mode is 'r'; this is indicated by "[r]" appearing before the word "Rotate" in the _MOTION MODE_ browser. To use this keyboard shortcut just hit the `r' key while the mouse cursor is in any Geomview window. You don't need to press the `' or `' keys. Some keyboard shortcuts consist of more than one key. In these cases just type the keys one after the other, with no `' afterwards. Keyboard shortcuts are case sensitive. You can cancel a multi-key keyboard shortcut that you have started by typing any invalid key, for example the space bar. Keyboard commands apply while the cursor is in any camera window and most control panels. Many keyboard shortcuts allow numeric arguments which you type as a prefix to the command key(s). For example, the shortcut for _Near clip_ in the camera panel is `v n'. To set the near clip plane to `0.5', type `0.5vn'. Commands that don't take a numeric prefix toggle or reset the current value. Most commands allow one of the following selection prefixes. If none is provided the command applies to the target object. `g' world geom `g#' #'th geom `g*' All geoms `c' current camera `c#' #'th camera `c*' All cameras For example, `g4af' means toggle the face drawing of object _g4_. Simply typing a selection prefix, like `g4', doesn't yet select an object; that only happens when a command, like `ae', follows the prefix. To select an object as the target without doing anything else to it, use the `p' command. So `g3p' selects object g3. The text field in the upper left corner of the _Main_ panel shows the state of the current keyboard shortcut. In addition to the keyboard shortcuts for the panel commands, there is also a shortcut for picking a target object: type the short name of the object followed by `p'. For example, to select object _g3_, type `g 3 p'. This only works with the short names -- the ones that appear in square brackets ([ ]) in the _Targets_ browser of the _Main_ panel. Below is a summary of all keyboard shortcuts. Draw `af' Faces `ae' Edges `an' Normals `ab' Bounding Boxes `aV' Vectors Shading `0as' Constant `1as' Flat `2as' Smooth `3as' Smooth, non-lighted `aT' allow transparency `at' texture mapping Other `av' eVert normals: always face viewer `#aw' Line Width (pixels) `aC' handle concave polygons `#vc' edges Closer than faces (try 5-100) Color `Cf' faces `Ce' edges `Cn' normals `Cb' bounding boxes `CB' background Motions `r' rotate `t' translate `z' zoom FOV `f' fly `o' orbit `s' scale `w' recenter target `W' recenter all `h' halt `H' halt all `@' select center of motion (e.g. `g 3 @') `L' Look At object Viewing `0vp' Orthographic view `1vp' Perspective view `vd' Draw other views' cameras `#vv' field of View `#vn' near clip distance `#vf' far clip distance `v+' add new camera `vx' cursor on/off `vb' backfacing poly cull on/off `#vl' focal length `v~' Software shading on/off Panels `Pm' Main `Pa' Appearance `Pl' Lighting `Po' Obscure `Pt' Tools `Pc' Cameras `PC' Commands `Pf' Files `Ps' Save `P-' read commands from tty `PA' Credits ("about") Lights `ls' show lights `le' edit lights Space `me' Euclidean `mh' Hyperbolic `ms' Spherical Model `mv' Virtual `mp' Projective `mc' Conformal Other `0N' normalizaton: none `1N' normalization: each `2N all' normalization: all `ui' motion: Inertia `uc' motion: Constrain to axis `uo' motion: object's Own coordinates `<' `Pf' load geometry/command file `dd' delete target object `>' `Ps' save state to file `TV' NTSC mode toggle `p' pick as target object (e.g. `g 3 p') With no prefix, selects the object under the mouse cursor (like double-clicking the right mouse)  File: geomview, Node: OOGL File Formats, Next: Conventions, Prev: Keyboard Shortcuts, Up: Top OOGL File Formats ***************** The objects that you can load into Geomview are called OOGL objects. OOGL stands for "Object Oriented Graphics Library"; it is the library upon which Geomview is built. There are many different kinds of OOGL objects. This chapter gives syntactic descriptions of file formats for OOGL objects. Examples of most file types live in Geomview's `data/geom' directory. * Menu: * Conventions:: Conventions. * Object File Formats:: Object File Formats. * Non-geometric objects:: Non-geometric objects.  File: geomview, Node: Conventions, Next: Common syntax, Prev: OOGL File Formats, Up: OOGL File Formats Conventions =========== * Menu: * Common syntax:: Syntax Common to All OOGL File Formats. * File names:: File Names. * Vertices:: Vertices. * Surface normal directions:: Surface normal directions. * Transformation matrices:: Transformation matrices. * Binary format:: Binary format. * References:: Embedded objects and external-object references. * Appearances:: Appearances.  File: geomview, Node: Common syntax, Next: File names, Prev: Conventions, Up: Conventions Syntax Common to All OOGL File Formats -------------------------------------- Most OOGL object file formats are free-format ASCII -- any amount of white space (blanks, tabs, newlines) may appear between tokens (numbers, key words, etc.). Line breaks are almost always insignificant, with a couple of exceptions as noted. Comments begin with # and continue to the end of the line; they're allowed anywhere a newline is. Binary formats are also defined for several objects; *Note Binary format::, and the individual object descriptions. Typical OOGL objects begin with a key word designating object type, possibly with modifiers indicating presence of color information etc. In some formats the key word is optional, for compatibility with file formats defined elsewhere. Object type is then determined by guessing from the file suffix (if any) or from the data itself. Key words are case sensitive. Some have optional prefix letters indicating presence of color or other data; in this case the order of prefixes is significant, e.g. `CNMESH' is meaningful but `NCMESH' is invalid.  File: geomview, Node: File names, Next: Vertices, Prev: Common syntax, Up: Conventions File Names ---------- When OOGL objects are read from disk files, the OOGL library uses the file suffix to guess at the file type. If the suffix is unrecognized, or if no suffix is available (e.g. for an object being read from a pipe, or embedded in another OOGL object), all known types of objects are tried in turn until one accepts the data as valid.  File: geomview, Node: Vertices, Next: Surface normal directions, Prev: File names, Up: Conventions Vertices -------- Several objects share a common style of representing vertices with optional per-vertex surface-normal and color. All vertices within an object have the same format, specified by the header key word. All data for a vertex is grouped together (as opposed to e.g. giving coordinates for all vertices, then colors for all vertices, and so on). The syntax is `X Y Z' (3-D floating-point vertex coordinates) or `X Y Z W' (4-D floating-point vertex coordinates) optionally followed by `NX NY NZ' (normalized 3-D surface-normal if present) optionally followed by `R G b A' (4-component floating-point color if present, each component in range 0..1. The A (alpha) component represents opacity: 0 transparent, 1 opaque.) optionally followed by `S T' `or' `S T U' (two or three texture-coordinate values). Values are separated by white space, and line breaks are immaterial. Letters in the object's header key word must appear in a specific order; that's the reverse of the order in which the data is given for each vertex. So a `CN4OFF' object's vertices contain first the 4-component space position, then the 3-component normal, finally the 4-component color. You can't change the data order by changing the header key word; an `NCOFF' is just not recognized.  File: geomview, Node: Surface normal directions, Next: Transformation matrices, Prev: Vertices, Up: Conventions Surface normal directions ------------------------- Geomview uses normal vectors to determine how an object is shaded. The direction of the normal is significant in this calculation. When normals are supplied with an object, the direction of the normal is determined by the data given. When normals are not supplied with the object, Geomview computes normal vectors automatically; in this case normals point toward the side from which the vertices appear in counterclockwise order. On parametric surfaces (Bezier patches), the normal at point P(u,v) is in the direction dP/du cross dP/dv.  File: geomview, Node: Transformation matrices, Next: Binary format, Prev: Surface normal directions, Up: Conventions Transformation matrices ----------------------- Some objects incorporate 4x4 real matrices for homogeneous object transformations. These matrices act by multiplication on the right of vectors. Thus, if p is a 4-element row vector representing homogeneous coordinates of a point in the OOGL object, and A is the 4x4 matrix, then the transformed point is p' = p A. This matrix convention is common in computer graphics; it's the transpose of that often used in mathematics, where points are column vectors multiplied on the right of matrices. Thus for Euclidean transformations, the translation components appear in the fourth row (last four elements) of A. A's last column (4th, 8th, 12th and 16th elements) are typically 0, 0, 0, and 1 respectively.  File: geomview, Node: Binary format, Next: References, Prev: Transformation matrices, Up: Conventions Binary format ------------- Many OOGL objects accept binary as well as ASCII file formats. These files begin with the usual ASCII token (e.g. `CQUAD') followed by the word `BINARY'. Binary data begins at the byte following the first newline after `BINARY'. White space and a single comment may intervene, e.g. OFF BINARY # binary-format "OFF" data follows Binary data comprise 32-bit integers and 32-bit IEEE-format floats, both in big-endian format (i.e., with most significant byte first). This is the native format for 'int's and 'float's on Sun-3's, Sun-4's, and Irises, among others. Binary data formats resemble the corresponding ASCII formats, with ints and floats in just the places you'd expect. There are some exceptions though, specifically in the `QUAD', `OFF' and `COMMENT' file formats. Details are given in the individual file format descriptions. *Note QUAD::, *Note OFF::, and *Note COMMENT::. Binary OOGL objects may be freely mixed in ASCII object streams: LIST { = MESH BINARY ... binary data for mesh here ... } { = QUAD 1 0 0 0 0 1 0 1 0 0 1 0 } Note that ASCII data resumes immediately following the last byte of binary data. Naturally, it's impossible to embed comments inside a binary-format OOGL object, though comments may appear in the header before the beginning of binary data.  File: geomview, Node: References, Next: Appearances, Prev: Binary format, Up: Conventions Embedded objects and external-object references ----------------------------------------------- Some object types (`LIST', `INST') allow references to other OOGL objects, which may appear literally in the data stream, be loaded from named disk files, or be communicated from elsewhere via named objects. Gcl commands also accept geometry in these forms. The general syntax is ::= [ "{" ] [ "define" `symbolname' ] [ "appearance" `appearance' ] [ ["="] `object-keyword' ... | "<" `filename' | ":" `symbolname' ] [ "}" ] where "quoted" items are literal strings (which appear without the quotes), [bracketed] items are optional, and | denotes alternatives. Curly braces, when present, must match; the outermost set of curly braces is generally required when the object is in a larger context, e.g. when it is part of a larger object or embedded in a Geomview command stream. For example, each of the following three lines: { define fred QUAD 1 0 0 0 0 1 0 1 0 1 0 0 } { appearance { +edge } LIST { < "file1" } { : fred } } VECT 1 2 0 2 0 0 0 0 1 1 2 is a valid OOGL object. The last example is only valid when it is delimited unambiguously by residing in its own disk file. The "<" construct causes a disk file to be read. Note that this isn't a general textual "include" mechanism; a complete OOGL object must appear in the referenced file. Files read using "<" are sought first in the directory of the file which referred to them, if any; failing that, the normal search path (set by Geomview's `load-path' command) is used. The default search looks first in the current directory, then in the Geomview data directories. The ":" construct allows references to symbols, created with `define'. A symbol's initial value is a null object. When a symbol is (re)defined, all references to it are automatically changed; this is a crucial part of the support for interprocess communication. Some future version of the documentation should explain this better... Again, white space and line breaks are insignificant, and "#" comments may appear anywhere.  File: geomview, Node: Appearances, Next: Texture Mapping, Prev: References, Up: Conventions Appearances ----------- Geometric objects can have associated "appearance" information, specifying shading, lighting, color, wireframe vs. shaded-surface display, and so on. Appearances are inherited through object hierarchies, e.g. attaching an appearance to a `LIST' means that the appearance is applied to all the `LIST''s members. Some appearance-related properties are relegated to "material" and "lighting" substructures. Take care to note which properties belong to which structure. Here's an example appearance structure including values for all attributes. Order of attributes is unimportant. As usual, white space is irrelevant. Boolean attributes may be preceded by "+" or "-" to turn them on or off; "+" is assumed if only the attribute name appears. Other attributes expect values. A "*" prefix on any attribute, e.g. "*+edge" or "*linewidth 2" or "material { *diffuse 1 1 .25 }", selects "override" status for that attribute. appearance { +face # (Do) draw faces of polygons. On by default. -edge # (Don't) draw edges of polygons +vect # (Do) draw VECTs. On by default. -transparent # (Disable) transparency. enabling transparency # does NOT result in a correct Geomview picture, # but alpha values are used in RenderMan snapshots. -normal # (Do) draw surface-normal vectors normscale 1 # ... with length 1.0 in object coordinates +evert # do evert polygon normals where needed so as # to always face the camera -texturing # (Disable) texture mapping -backcull # (Don't) discard clockwise-oriented faces -concave # (Don't) expect and handle concave polygons -shadelines # (Don't) shade lines as if they were lighted cylinders # These four are only effective where the graphics system # supports them, namely on GL and Open GL. -keepcolor # Normally, when N-D positional coloring is enabled as # with geomview's (ND-color ...) command, all # objects' colors are affected. But, objects with the # "+keepcolor" attribute are immune to N-D coloring. shading smooth # or ``shading constant'' or ``shading flat'' or # or ``shading csmooth''. # smooth = Gouraud shading, flat = faceted, # csmooth = smoothly interpolated but unlighted. linewidth 1 # lines, points, and edges are 1 pixel wide. patchdice 10 10 # subdivide Bezier patches this finely in u and v material { # Here's a material definition; # it could also be read from a file as in # ``material < file.mat'' ka 1.0 # ambient reflection coefficient. ambient .3 .5 .3 # ambient color (red, green, blue components) # The ambient contribution to the shading is # the product of ka, the ambient color, # and the color of the ambient light. kd 0.8 # diffuse-reflection coefficient. diffuse .9 1 .4 # diffuse color. # (In ``shading constant'' mode, the surface # is colored with the diffuse color.) ks 1.0 # specular reflection coefficient. specular 1 1 1 # specular (highlight) color. shininess 25 # specular exponent; larger values give # sharper highlights. backdiffuse .7 .5 0 # back-face color for two-sided surfaces # If defined, this field determines the diffuse # color for the back side of a surface. # It's implemented by the software shader, and # by hardware shading on GL systems which support # two-sided lighting, and under Open GL. alpha 1.0 # opacity; 0 = transparent (invisible), 1 = opaque. # Ignored when transparency is disabled. edgecolor 1 1 0 # line & edge color normalcolor 0 0 0 # color for surface-normal vectors } lighting { # Lighting model ambient .3 .3 .3 # ambient light replacelights # ``Use only the following lights to # illuminate the objects under this # appearance.'' # Without "replacelights", any lights listed # are added to those already in the scene. # Now a collection of sample lights: light { color 1 .7 .6 # light color position 1 0 .5 0 # light position [distant light] # given in homogeneous coordinates. # With fourth component = 0, # this means a light coming from # direction (1,0,.5). } light { # Another light. color 1 1 1 position 0 0 .5 1 # light at finite position ... location camera # specified in camera coordinates. # (Since the camera looks toward -Z, # this example places the light # .5 unit behind the eye.) # Possible "location" keywords: # global light position is in world (well, universe) coordinates # This is the default if no location specified. # camera position is in the camera's coordinate system # local position is in the coordinate system where # the appearance was defined } } # end lighting model texture { clamp st # or ``s'' or ``t'' or ``none'' file lump.tiff # file supplying texture-map image alphafile mask.pgm.Z # file supplying transparency-mask image apply blend # or ``modulate'' or ``decal'' transform 1 0 0 0 # surface (s,t,0,1) * tfm -> texture coords 0 1 0 0 0 0 1 0 .5 0 0 1 background 1 0 0 1 # relevant for ``apply blend'' } } # end appearance There are rules for inheritance of appearance attributes when several are imposed at different levels in the hierarchy. For example, Geomview installs a backstop appearance which provides default values for most parameters; its control panels install other appearances which supply new values for a few attributes; user-supplied geometry may also contain appearances. The general rule is that the child's appearance (the one closest to the geometric primitives) wins. Further, appearance controls with "override" status (e.g. *+face or material { *diffuse 1 1 0 }) win over those without it. Geomview's appearance controls use the "override" feature so as to be effective even if user-supplied objects contain their own appearance settings. However, if a user-supplied object contains an appearance field with override status set, that property will be immune to Geomview's controls.  File: geomview, Node: Texture Mapping, Next: Object File Formats, Prev: Appearances, Up: Conventions Texture Mapping --------------- Some platforms support texture-mapped objects. (On those which don't, attempts to use texture mapping are silently ignored.) A texture is specified as part of an appearance structure, as in *Note Appearances::. Briefly, one provides a texture image, which is considered to lie in a square in `(s,t)' parameter space in the range 0 <= s <= 1, 0 <= t <= 1. Then one provides a geometric primitive, with each vertex tagged with `(s,t)' texture coordinates. If texturing is enabled, the appropriate portion of the texture image is pasted onto each face of the textured object. There is (currently) no provision for inheritance of part of a texture structure; if the `texture' keyword is mentioned in an appearance, it supplants any other texture specification. The appearance attribute `texturing' controls whether textures are used; there's no performance penalty for having texture { ... } fields defined when texturing is off. The available fields are: clamp none -or- s -or- t -or- st Determines the meaning of texture coordinates outside the range 0..1. With `clamp none', the default, coordinates are interpreted modulo 1, so (s,t) = (1.25,0), (.25,0), and (-.75,0) all refer to the same point in texture space. With `s' or `t' or `st', either or both of s- or t-coordinates less than 0 or greater than 1 are clamped to 1 or 0, respectively. file filename alphafile filename Specifies image file(s) containing the texture. The `file' file's image specifies color or lightness information; the `alphafile' if present, specifies a transparency ("alpha") mask; where the mask is zero, pixels are simply not drawn. Several image file formats are available; the file type must be indicated by the last few characters of the file name: .ppm or .ppm.Z or .ppm.gz 24-bit 3-color image in PPM format .pgm or .pgm.Z or .pgm.gz 8-bit grayscale image in PGM format .sgi or .sgi.Z or .sgi.gz 8-bit, 24-bit, or 32-bit SGI image .tiff 8-bit or 24-bit TIFF image .gif GIF image (Though 4-channel TIFF images are possible, and could represent both color and transparency information in one image, that's not supported in geomview at present.) For this feature to work, some programs must be available in geomview's search path: zcat for .Z files gzip for .gz files tifftopnm for .tiff files giftoppm for .gif files If an `alphafile' image is supplied, it must be the same size as the `file' image. apply modulate -or- blend -or- decal Indicates how the texture image is applied to the surface. Here the "surface color" means the color that surface would have in the absence of texture mapping. With `modulate', the default, the texture color (or lightness, if textured by a gray-scale image) is multiplied by the surface color. With `blend', texture blends between the `background' color and the surface color. The `file' parameter must specify a gray-scale image. Where the texture image is 0, the surface color is unaffected; where it's 1, the surface is painted in the color given by `background'; and color is interpolated for intermediate values. With `decal', the `file' parameter must specify a 3-color image. If an `alphafile' parameter is present, its value interpolates between the surface color (where alpha=0) and the texture color (where alpha=1). Lighting does not affect the texture color in `decal' mode; effectively the texture is constant-shaded. background R G B A Specifies a 4-component color, with R, G, B, and A floating-point numbers normally in the range 0..1, used when `apply blend' is selected. transform `transformation-matrix' Expects a list of 16 numbers, or one of the other ways of representing a transformation (`: handlename' or `< filename'). The 4x4 transformation matrix is applied to texture coordinates, in the sense of a 4-component row vector (s,t,0,1) multiplied on the left of the matrix, to produce new coordinates (s',t') which actually index the texture.  File: geomview, Node: Object File Formats, Next: QUAD, Prev: Texture Mapping, Up: OOGL File Formats Object File Formats =================== * Menu: * QUAD:: List of quadrilaterals. * MESH:: Rectangularly-connected mesh. * BBP and BEZ:: List of Bezier surface patches. * OFF:: Polyhedra: polygons with shared vertices. * VECT:: List of points and lines. * SKEL:: List of points and lines, with shared vertices. * SPHERE:: Sphere * INST:: Transformed Instance of another object. * LIST:: List of other objects. * TLIST:: Collection of 4x4 transformation matrices. * GROUP:: Obsolete format for collections of objects. * DISCGRP:: Discrete Group objects. * COMMENT:: Comment object, for caching information.  File: geomview, Node: QUAD, Next: MESH, Prev: Object File Formats, Up: Object File Formats QUAD: collection of quadrilaterals ---------------------------------- The conventional suffix for a `QUAD' file is `.quad'. The file syntax is [C][N][4]QUAD -or- [C][N][4]POLY # Key word VERTEX VERTEX VERTEX VERTEX # 4*N vertices for some N VERTEX VERTEX VERTEX VERTEX ... The leading key word is `[C][N][4]QUAD' or `[C][N][4]POLY', where the optional `C' and `N' prefixes indicate that each vertex includes colors and normals respectively. That is, these files begin with one of the words `QUAD' `CQUAD' `NQUAD' `CNQUAD' `POLY' `CPOLY' `NPOLY' `CNPOLY' (but not `NCQUAD' or `NCPOLY'). `QUAD' and `POLY' are synonymous; both forms are allowed just for compatibility with ChapReyes. Following the key word is an arbitrary number of groups of four vertices, each group describing a quadrilateral. See the Vertex syntax above. The object ends at end-of-file, or with a closebrace if incorporated into an object reference (see above). A `QUAD BINARY' file format is accepted; *Note Binary format::. The first word of binary data must be a 32-bit integer giving the number of quads in the object; following that is a series of 32-bit floats, arranged just as in the ASCII format.  File: geomview, Node: MESH, Next: BBP and BEZ, Prev: QUAD, Up: Object File Formats MESH: rectangularly-connected mesh ---------------------------------- The conventional suffix for a `MESH' file is `.mesh'. The file syntax is [U][C][N][Z][4][u][v][n]MESH # Key word [NDIM] # Space dimension, present only if nMESH NU NV # Mesh grid dimensions # NU*NV vertices, in format specified # by initial key word VERTEX(u=0,v=0) VERTEX(1,0) ... VERTEX(NU-1,0) VERTEX(0,1) ... VERTEX(NU-1,1) ... VERTEX(0,NV-1) ... VERTEX(NU-1,NV-1) The key word is `[U][C][N][Z][4][u][v][n]MESH'. The optional prefix characters mean: `U' Each vertex includes a 3-component texture space parameter. The first two components are the usual `S' and `T' texture parameters for that vertex; the third should be specified as zero. `C' Each vertex (see Vertices above) includes a 4-component color. `N' Each vertex includes a surface normal vector. `Z' Of the 3 vertex position values, only the Z component is present; X and Y are omitted, and assumed to equal the mesh (u,v) coordinate so X ranges from 0 .. (Nu-1), Y from 0 .. (Nv-1) where Nu and Nv are the mesh dimensions - see below. `4' Vertices are 4D, each consists of 4 floating values. `Z' and `4' cannot both be present. `u' The mesh is wrapped in the u-direction, so the (0,v)'th vertex is connected to the (NU-1,v)'th for all v. `v' The mesh is wrapped in the v-direction, so the (u,0)'th vertex is connected to the (u,NV-1)'th for all u. Thus a u-wrapped or v-wrapped mesh is topologically a cylinder, while a uv-wrapped mesh is a torus. `n' Specifies a mesh whose vertices live in a higher dimensional space. The dimension follows the "MESH" keyword. Each vertex then has NDIM components. Note that the order of prefix characters is significant; a colored, u-wrapped mesh is a `CuMESH' not a `uCMESH'. Following the mesh header are integers NU and NV, the dimensions of the mesh. Then follow NU*NV vertices, each in the form given by the header. They appear in v-major order, i.e. if we name each vertex by (u,v) then the vertices appear in the order (0,0) (1,0) (2,0) (3,0) ... (NU-1,0) (0,1) (1,1) (2,1) (3,1) ... (NU-1,1) ... (0,Nv-1) ... (NU-1,NV-1) A `MESH BINARY' format is accepted; *Note Binary format::. The values of NU and NV are 32-bit integers; all other values are 32-bit floats.  File: geomview, Node: BBP and BEZ, Next: OFF, Prev: MESH, Up: Object File Formats Bezier Surfaces --------------- The conventional file suffixes for Bezier surface files are `.bbp' or `.bez'. A file with either suffix may contain either type of patch. Syntax: [ST]BBP -or- [C]BEZ[_ST] # NU, NV are u- and v-direction # polynomial degrees in range 1..6 # ND = dimension: 3->3-D, 4->4-D (rational) # (The '<' and '>' do not appear in the input.) # NU,NV,ND are each a single decimal digit. # BBP form implies NU=NV=ND=3 so BBP = BEZ333. # Any number of patches follow the header # (NU+1)*(NV+1) patch control points # each 3 or 4 floats according to header VERTEX(u=0,v=0) VERTEX(1,0) ... VERTEX(NU,0) VERTEX(0,1) ... VERTEX(NU,1) ... VERTEX(0,NV) ... VERTEX(NU,NV) # ST texture coordinates if mentioned in header `S'(u=0,v=0) `T'(0,0) `S'(0,NV) `T'(0,NV) `S'(NU,0) `T'(NU,0) `S'(NU,NV) `T'(NU,NV) # 4-component float (0..1) R G B A colors # for each patch corner if mentioned in header `RGBA'(0,0) `RGBA'(0,NV) `RGBA'(NU,0) `RGBA'(NU,NV) These formats represent collections of Bezier surface patches, of degrees up to 6, and with 3-D or 4-D (rational) vertices. The header keyword has the forms `[ST]BBP' or `[C]BEZ[_ST]' (the '<' and '>' are not part of the keyword. The `ST' prefix on `BBP', or `_ST' suffix on `BEZuvn', indicates that each patch includes four pairs of floating-point texture-space coordinates, one for each corner of the patch. The `C' prefix on `BEZuvn' indicates a colored patch, including four sets of four-component floating-point colors (red, green, blue, and alpha) in the range 0..1, one color for each corner. NU and NV, each a single digit in the range 1..6, are the patch's polynomial degree in the u and v direction respectively. ND is the number of components in each patch vertex, and must be either `3' for 3-D or `4' for homogeneous coordinates, that is, rational patches. `BBP' patches are bicubic patches with 3-D vertices, so `BBP' = `BEZ333' and `STBBP' = `BEZ333_ST'. Any number of patches follow the header. Each patch comprises a series of patch vertices, followed by optional (s,t) texture coordinates, followed by optional (r,g,b,a) colors. Each patch has (NU+1)*(NV+1) vertices in v-major order, so that if we designate a vertex by its control point indices (u,v) the order is (0,0) (1,0) (2,0) ... (NU,0) (0,1) (1,1) (2,1) ... (NU,1) ... (0,NV) ... (NU,NV) with each vertex containing either 3 or 4 floating-point numbers as specified by the header. If the header calls for ST coordinates, four pairs of floating-point numbers follow: the texture-space coordinates for the (0,0), (NU,0), (0,NV), and (NU,NV) corners of the patch, respectively. If the header calls for colors, four four-component (red, green, blue, alpha) floating-point colors follow, one for each patch corner. The series of patches ends at end-of-file, or with a closebrace if incorporated in an object reference.