geomview

title: geomview(5gv)

text:
# geomview(5gv)

Geomview(5gv) Geomview(5gv)

NAME

Geomview - Geomview command language

NOTE

The material in this manual page also appears in the

Geomview manual.

DESCRIPTION

gcl: the Geomview Command Language

**********************************

Gcl has the syntax of lisp -- i.e. an expression of the form (f a b ...) means pass the values of a, b, ... to the function f.

Gcl is very limited and is by no means an implementation of lisp. It

is simply a language for expressing commands to be executed in the order

given, rather than a programming language. It does not support variable

or function definition.

Gcl is the language that Geomview understands for files that it loads

as well as for communication with other programs.

To execute a gcl command interactively, you can bring up the

*Commands* panel which lets you type in a command; Geomview

executes the command when you hit the return key. Output from such

commands is printed to standard output. Alternately, you can invoke

Geomview as `geomview -c -' which causes it to read gcl commands

from standard input.

Gcl functions return a value, and you can nest function calls in ways

which use this returned value. For example (f (g a b))

evaluates `(g a b)' and then evaluates `(f x)' where `x'

is the result returned by `(g a b)'. Geomview maintains these

return values internally but does not normally print them out.

To print out a return value pass it to the `echo' function.

For example the `geomview-version' function returns a string

representing the version of Geomview that is running, and (echo (geomview-version))

prints out this string.

Many functions simply return `t' for success or `nil' for

failure; this is the case if the documentation for the function does not

indicate otherwise. These are the lisp symbols for true and false,

respectively. (They correspond to the C variables `Lt' and

`Lnil' which you are likely to see if you look at the source code

for Geomview or some of the external modules.)

In the descriptions of the commands below several references are made to

"OOGL" formats. OOGL is the data description language that Geomview

uses for describing geometry, cameras, appearances, and other basic

objects. For details of the OOGL formats, *Note OOGL File Formats::.

(Or equivalently, see the oogl(5) manual page, distributed with Geomview

in the file man/cat5/oogl.5.

The gcl commands and argument types are listed below. Most

Geometry Center Thu Dec 12 02:41:23 CST 1996 1

Geomview(5) Geomview(5)

of the documentation in this section of the manual is available within

Geomview via the `?' and `??' commands. The command `(?

COMMAND)' causes Geomview to print out a one-line summary of the

syntax of COMMAND, and `(?? COMMAND)' prints out an

explanation of what COMMAND does. You can include the wild-card

character `*' in COMMAND to print information for a group of

commands matching a pattern. For example, `(?? *emodule*)' will

print all information about all commands containing the string

`emodule'. `(? *)' will print a short list of all commands.

Conventions Used In Describing Argument Types

=============================================

The following symbols are used to describe argument types

in the documentation for gcl functions.

`APPEARANCE' is an OOGL appearance specification.

`CAM-ID' is an ID that refers to a camera.

`CAMERA' is an OOGL camera specification.

`GEOM-ID' is an ID that refers to a geometry.

`GEOMETRY' is an OOGL geometry specification.

`ID' is a string which names a geometry or camera. Besides those you create, valid ones are:

``World, world, worldgeom, g0'' the collection of all geom's

`target' selected target object (cam or geom)

`center' selected center-of-motion object

`targetcam' last selected target camera

`targetgeom' last selected target geom

`focus' camera where cursor is (or most recently was)

Geometry Center Thu Dec 12 02:41:23 CST 1996 2

Geomview(5) Geomview(5)

`allgeoms' all geom objects

`allcams' all cameras

``default, defaultcam, prototype'' future cameras inherit default's settings

The following IDs are used to name coordinate systems, e.g. in `pick' and `write' commands:

``World, world, worldgeom, g0'' the world, within which all other geoms live.

`universe ' the universe, in which the World, lights and cameras live. Cameras' world2cam transforms might better be called universe2cam, etc.

`self' "this Geomview object". Transform from an object to `self' is the identity; writing its geometry gives the object itself with no enclosing transform; picked points appear in the object's coordinates.

`primitive' (for `pick' only) Picked points appear in the coordinate system of the lowest-level OOGL primitive.

A name is also an acceptable id. Given names are made unique by appending numbers if necessary (i.e. `foo<2>'). Every geom is also named g[n] and every camera is also named c[n] (`g0' is always the worldgeom): this name is used as a prefix to keyboard commands and can also be used as a gcl id. Numbers are reused after an object is deleted. Both names are shown in the Object browser.

`STATEMENT' represents a function call. Function calls have the form `(func arg1 arg2 ... )', where `func' is the name of the function and `arg1', `arg2', ... are the arguments.

`TRANSFORM' is an OOGL 4x4 transformation matrix.

`WINDOW' is an OOGL winddow specification.

Gcl Reference Guide

===================

Geometry Center Thu Dec 12 02:41:23 CST 1996 3

Geomview(5) Geomview(5)

`! is a synonym for `shell''

`(< EXPR1 EXPR2)' Returns t if EXPR1 is less than EXPR2. EXPR1 and EXPR2 should be either both integers or floats, or both strings.

`(= EXPR1 EXPR2)' Returns t if EXPR1 is equal to EXPR2. EXPR1 and EXPR2 should be either both integers or floats, or both strings.

`(> EXPR1 EXPR2)' Returns t if EXPR1 is greater than EXPR2. EXPR1 and EXPR2 should be either both integers or floats, or both strings.

`(? [command])' Gives one-line usage summary for `command'. Command may include `*'s as wildcards; see also `??' One-line command help; lists names only if multiple commands match. ? is a synonym for `help'

`(?? command) `command' may include `*' wildcards' Prints more info than `(? command)'. ?? is a synonym for `morehelp'.

`| is a synonym for `emodule-run'.'

`(all geometry) returns a list of names of all geometry objects.' Use e.g. `(echo (all geometry))' to print such a list.

`(all camera) returns a list of names of all cameras.'

`(all emodule defined) returns a list of all defined external modules.'

`(all emodule running) returns a list of all running external modules.'

`(ap-override [on|off])' Selects whether appearance controls should override objects' own settings. On by default. With no arguments, returns current setting.

`(backcolor CAM-ID R G B)' Set the background color of CAM-ID; R G B are numbers between 0 and 1.

`(background-image CAM-ID [FILENAME])' Use the given image as the background of camera CAM-ID (which must be a real camera, not `default' or `allcams'). Centers the image on the window area. Works only with GL and OpenGL graphics. Use "" for filename to remove background. With no filename argument, returns name of that window's current background image, or "". Any file type acceptable as a texture is allowed, e.g. .ppm.gz, .sgi, etc.

`(bbox-color GEOM-ID R G B)' Set the bounding-box color of GEOM-ID; R G B are numbers between 0 and 1.

`(bbox-draw GEOM-ID [yes|no])' Say whether GEOM-ID's bounding-box should be drawn; `yes' if omitted.

Geometry Center Thu Dec 12 02:41:23 CST 1996 4

Geomview(5) Geomview(5)

`(camera CAM-ID [CAMERA])' Specify data for CAM-ID; CAMERA is a string giving an OOGL camera specification. If no camera CAM-ID exists, it is created; in this case, the second argument is optional, and if omitted, a default camera is used. See also: new-camera.

`(camera-draw CAM-ID [yes|no])' Say whether or not cameras should be drawn in CAM-ID; `yes' if omitted.

`(camera-prop { geometry object } [projective])' Specify the object to be shown when drawing other cameras. By default, this object is drawn with its origin at the camera, and with the camera looking toward the object's -Z axis. With the `projective' keyword, the camera's viewing projection is also applied to the object; this places the object's Z=-1 and Z=+1 at near and far clipping planes, with the viewing area -1<={X,Y}<=+1. Example: (camera-prop { < cube } projective)

`(camera-reset CAM-ID)' Reset CAM-ID to its default value.

`(car LIST)' returns the first element of LIST.

`(cdr LIST)' returns the list obtained by removing the first element of LIST.

`(clock)' Returns the current time, in seconds, as shown by this stream's clock. See also set-clock and sleep-until.

`(command INFILE [OUTFILE])' Read commands from INFILE; send corresponding responses (e.g. anything written to filename `-') to OUTFILE, stdout by default.

`(copy [ID] [name])' Copies an object or camera. If ID is not specified, it is assumed to be targetgeom. If name is not specified, it is assumed to be the same as the name of ID.

`(cursor-still [INT])' Sets the number of microseconds for which the cursor must not move to register as holding still. If INT is not specified, the value will be reset to the default.

`(cursor-twitch [INT])' Sets the distance which the cursor must not move (in x or y) to register as holding still. If INT is not specified, the value will be reset to the default.

`(delete ID)' Delete object or camera ID.

Geometry Center Thu Dec 12 02:41:23 CST 1996 5

Geomview(5) Geomview(5)

`(dice GEOM-ID N)' Dice any Bezier patches within GEOM-ID into NxN meshes; default 10. See also the appearance attribute `dice', which makes this command obsolete.

`(dimension [N])' Sets or reads the space dimension for N-dimensional viewing. (Since calculations are done using homogeneous coordinates, this means matrices are (N+1)x(N+1).) With no arguments, returns the current dimension, or 0 if N-dimensional viewing has not been enabled.

`(dither CAM-ID {on|off|toggle})' Turn dithering on or off in that camera.

`(draw CAM-ID)' Draw the view in CAM-ID, if it needs redrawing. See also `redraw'.

`(echo ...)' Write the given data to the special file `-'. Strings are written literally; lisp expressions are evaluated and their values written. If received from an external program, `echo' sends to the program's input. Otherwise writes to geomview's own standard output (typically the terminal).

`(emodule-clear)' Clears the geomview application (external module) browser.

`(emodule-define NAME SHELL-COMMAND ...)' Define an external module called NAME, which then appears in the external-module browser. The SHELL-COMMAND string is a UNIX shell command which invokes the module. See emodule-run for discussion of external modules.

`(emodule-defined `modulename')' If the given external-module name is known, returns the name of the program invoked when it's run as a quoted string; otherwise returns nil. `(echo (emodule-defined `name'))' prints the string.

`(emodule-isrunning NAME)' Returns Lt if the emodule NAME is running, or Lnil if it is not running. NAME is searched for in the names as they appear in the browser and in the shell commands used to execute the external modules (not including arguments).

`(emodule-path)' Returns the current search path for external modules. Note: to actually see the value returned by this function you should wrap it in a call to echo: (echo (emodule-path)). See also set-emodule-path.

`(emodule-run SHELL-COMMAND ARGS...)' Runs the given SHELL-COMMAND (a string containing a UNIX shell command) as an external module. The module's standard output

Geometry Center Thu Dec 12 02:41:23 CST 1996 6

Geomview(5) Geomview(5)

is taken as geomview commands; responses (written to filename `-') are sent to the module's standard input. The shell command is interpreted by /bin/sh, so e.g. I/O redirection may be used; a program which prompts the user for input from the terminal could be run with: (emodule-run yourprogram <&2) If not already set, the environment variable $MACHTYPE is set to the name of the machine type. Input and output connections to geomview are dropped when the shell command terminates. Clicking on a running program's module-browser entry sends the signal SIGHUP to the program. For this to work, programs should avoid running in the background; those using FORMS or GL should call foreground() before the first FORMS or winopen() call. See also emodule-define, emodule-start.

`(emodule-sort)' Sorts the modules in the application browser alphabetically.

`(emodule-start NAME)' Starts the external module NAME, defined by emodule-define. Equivalent to clicking on the corresponding module-browser entry.

`(emodule-transmit NAME LIST)' Places LIST into external module NAME's standard input. NAME is searched for in the names of the modules as they appear in the External Modules browser and then in the shell commands used to execute the external modules. Does nothing if modname is not running.

`(escale GEOM-ID FACTOR)' Same as scale but multiplies by exp(scale). Obsolete.

`(event-keys {on|off})' Turn keyboard events on or off to enable/disable keyboard shortcuts.

`(event-mode MODESTRING)' Set the mouse event (motion) mode; MODESTRING should be one of the following strings:

1. "[r] Rotate"

2. "[t] Translate"

3. "[z] Cam Zoom"

4. "[s] Geom Scale"

5. "[f] Cam Fly"

6. "[o] Cam Orbit"

7. "[le] Edit Lights"

`(event-pick {on|off})' Turn picking on or off.

`(evert GEOM-ID [yes|no])' Set the normal eversion state of GEOM-ID. If the second argument is omitted, toggle the eversion state.

`(exit)' Terminates geomview.

`(ezoom GEOM-ID FACTOR)' Same as zoom but multiplies by exp(zoom). Obsolete.

`(freeze CAM-ID)'

Geometry Center Thu Dec 12 02:41:23 CST 1996 7

Geomview(5) Geomview(5)

Freeze CAM-ID; drawing in this camera's window is turned off until it is explicitly redrawn with `(redraw CAM-ID)', after which time drawing resumes as normal.

`(geometry GEOM-ID [GEOMETRY])' Specify the geometry for GEOM-ID. GEOMETRY is a string giving an OOGL geometry specification. If no object called GEOM-ID exists, it is created; in this case the GEOMETRY argument is optional, and if omitted, the new object GEOM-ID is given an empty geometry.

`(geomview-version)' Returns a string representing the version of geomview that is running.

`(hdefine `geometry'|`camera'|`transform'|`window' name value)' Sets the value of a handle of a given type. (hdefine <type> <name> <value>) is generally equivalent to (read <type> { define <name> <value> }) except that the assignment is done when hdefine is executed, (possibly not at all if inside a conditional statement), while the `read ... define' performs assignment as soon as the text is read.

`(help [command])' Command may include `*'s as wildcards; see also `??' One-line command help; lists names only if multiple commands match.

`(hmodel CAMID {virtual|projective|conformal})' Set the model used to display geometry in this camera; see also `space'.

`(hsphere-draw CAMID [yes|no])' Say whether to draw a unit sphere: the sphere at infinity in hyperbolic space, and a reference sphere in Euclidean and spherical spaces. If the second argument is omitted, `yes' is assumed.

`(if TEST EXPR1 [EXPR2])' Evaluates TEST; if TEST returns a non-nil value, returns the value of EXPR1. If TEST returns nil, returns the value of EXPR2 if EXPR2 is present, otherwise returns nil.

`(inhibit-warning STRING)' Inhibit warning inhbits geomview from displaying a particular warning message determined by STRING. At present there are no warning messages that this applies to, so this command is rather useless.

`(input-translator "#prefix_string" "Bourne-shell-command")' Defines an external translation program for special input types. When asked to read a file which begins with the specified string, geomview invokes that program with standard input coming from the given file.

Geometry Center Thu Dec 12 02:41:23 CST 1996 8

Geomview(5) Geomview(5)

The program is expected to emit OOGL geometric data to its standard output. In this implementation, only prefixes beginning with # are recognized. Useful as in (input-translator "#VRML" "vrml2oogl")

`(interest (COMMAND [args]))'

Allows you to express interest in a command. When geomview executes that command in the future it will echo it to the communication pool from which the interest command came. COMMAND can be any command. Args specify restrictions on the values of the arguments; if args are present in the interest command, geomview will only echo calls to the command in which the arguments match those given in the interest command. Two special argument values may appear in the argument list. `*' matches any value. `nil' matches any value but supresses the reporting of that value; its value is reported as `nil'.

The purpose of the interest command is to allow external modules to find out about things happening inside geomview. For example, a module interested in knowing when a geom called `foo' is deleted could say `(interest (delete foo))' and would receive the string `(delete foo)' when foo is deleted.

Picking is a special case of this. For most modules interested in pick events the command `(interest (pick world))' is sufficient. This causes geomview to send a string of the form `(pick world ...)' every time a pick event (right mouse double click). See the `pick' command for details.

`(lines-closer CAM-ID DIST)' Draw lines (including edges) closer to the camera than polygons by DIST / 10^5 of the Z-buffer range. DIST = 3.0 by default. If DIST is too small, a line lying on a surface may be dotted or invisible, depending on the viewpoint. If DIST is too large, lines may appear in front of surfaces that they actually lie behind. Good values for DIST vary with the scene, viewpoint, and distance between near and far clipping planes. This feature is a kludge, but can be helpful.

`(load filename [command|geometry|camera])' Loads the given file into geomview. The optional second argument specifies the type of data it contains, which may be `command' (geomview commands), `geometry' (OOGL geometric data), or `camera' (OOGL camera definition). If omitted, attempts to guess about the file's contents. Loading geometric data creates a new visible object; loading a camera opens a new window; loading a command file executes those commands.

`(load-path)' Returns the current search path for command, geometry, etc. files. Note: to actually see the value returned by this function you should wrap it in a call to echo: (echo (load-path)).

Geometry Center Thu Dec 12 02:41:23 CST 1996 9

Geomview(5) Geomview(5)

See also set-load-path.

`(look [objectID] [cameraID])' Rotates the named camera to point toward the center of the bounding box of the named object (or the origin in hyperbolic or spherical space). In Euclidean space, moves the camera forward or backward until the object appears as large as possible while still being entirely visible. Equivalent to progn ( (look-toward [objectID] [cameraID] {center | origin}) [(look-encompass [objectID] [cameraID])] ) If objectID is not specified, it is assumed to be World. If cameraID is not specified, it is assumed to be targetcam.

`(look-encompass [objectID] [cameraID])' Moves cameraID backwards or forwards until its field of view surrounds objectID. This routine works only in Euclidean space. If objectID is not specified, it is assumed to be the world. If cameraID is not specified, it is assumed to be the targetcam. See also (look-encompass-size).

`(look-encompass-size [view-fraction clip-ratio near-margin far-margin])' Sets/returns parameters used by (look-encompass). view-fraction is the portion of the camera window filled by the object, clip-ratio is the max allowed ratio of near-to-far clipping planes. The near clipping plane is 1/near-margin times closer than the near edge of the object, and the far clipping plane is far-margin times further away. Returns the list of current values. Defaults: .75 100 0.1 4.0

`(look-recenter [objectID] [cameraID])' Translates and rotates the camera so that it is looking in the -z direction (in objectID's coordinate system) at the center of objectID's bounding box (or the origin of the coordinate system in non-Eudlidean space). In Euclidean space, the camera is also moved as close as possible to the object while allowing the entire object to be visible. Also makes sure that the y-axes of objectID and cameraID are parallel.

`(look-toward [objectID] [cameraID] [origin | center])' Rotates the named camera to point toward the origin of the object's coordinate system, or the center of the object's bounding box (in non-Euclidean space, the origin will be used automatically). Default objectID is the world, default camera is targetcam, default location to point towards is the center of the bounding box.

`(merge {window|camera} CAM-ID { WINDOW or CAMERA ... } )' Modify the given window or camera, changing just those properties specified in the last argument. E.g. (merge camera `Camera' { far 20 }) sets Camera's far clipping plane to 20 while leaving

Geometry Center Thu Dec 12 02:41:23 CST 1996 10

Geomview(5) Geomview(5)

other attributes untouched.

`(merge-ap GEOM-ID APPEARANCE)' Merge in some appearance characteristics to GEOM-ID. Appearance parameters include surface and line color, shading style, line width, and lighting.

`merge-base-ap is a synonym for merge-baseap.'

`(merge-baseap APPEARANCE)' Merge in some appearance characteristics to the base default appearance (applied to every geom before its own apperance). Lighting is typically included in the base appearance.

`(morehelp command)' `command' may include `*' wildcards. Prints more info than `(help command)'.

`(name-object ID NAME)' Assign a new NAME (a string) to ID. A number is appended if that name is in use (for example, `foo' -> `foo<2>'). The new name, possibly with number appended, may be used as object's id thereafter.

`(ND-axes CAMID [CLUSTERNAME [Xindex Yindex Zindex]])' In our model for N-D viewing (enabled by (dimension)), objects in N-space are viewed by N-dimensional *camera clusters*. Each real camera window belongs to some cluster, and shows & manipulates a 3-D axis-aligned projected subspace of the N-space seen by its cluster. Moving one camera in a cluster affects its siblings.

The ND-axes command configures all this. It specifies a camera's cluster membership, and the set of N-space axes which become the 3-D camera's X, Y, and Z axes. Axes are specified by their indices, from 0 to N-1 for an N-dimensional space. Cluster CLUSTERNAME is implicitly created if not previously known. To read a camera's configuration, use `(echo (ND-axes CAMID))'.

`(ND-color CAMID' [ (( [ID] (x0 x1 x2 ... xn) v r g b a v r g b a ... ) ((x0 ... xn) v r g b a v r g b a ...) ...)] ) Specifies a function, applied to each N-D vertex, which determines the colors of N-dimensional objects as shown in camera CAMID. Each coloring function is defined by a vector (in ID's coordinate system) [x0 x1 ... xn] and by a sequence of value (v)/color(r g b a) tuples, ordered by increasing v. The inner product v = P.[x] is linearly interpolated in this table to give a color. If ID is omitted, the (xi) vector is assumed in universe coordinates. The ND-color command specifies a list of such functions; each vertex is colored by their sum (so e.g. green intensity could indicate projection along one axis while red indicated another. An empty list, as in (ND-color CAMID ()), suppresses coloring. With no second argument, (ND-color CAMID) returns that camera's

Geometry Center Thu Dec 12 02:41:23 CST 1996 11

Geomview(5) Geomview(5)

color-function list. Even when coloring is enabled, objects tagged with the `keepcolor' appearance attribute are shown in their natural colors.

`(ND-xform OBJID [ntransform { idim odim ... }])' Sets or returns the N-D transform of the given object. In dimension N, this is an (N+1)x(N+1) matrix. Note that all cameras in a camera-cluster have the same N-D transform.

`(ND-xform-get ID [from-ID])' Returns the N-D transform of the given object in the coordinate system of from-ID (default `universe'), in the sense <point-in-ID-coords> * Transform = <point-in-from-ID-coords>

`(new-alien name [GEOMETRY])' Create a new alien (geom not in the world) with the given name (a string). GEOMETRY is a string giving an OOGL geometry specification. If GEOMETRY is omitted, the new alien is given an empty geometry. If an object with that name already exists, the new alien is given a unique name. The light beams that are used to move around the lights are an example of aliens. They're drawn but are not controllable the way ordinary objects are: they don't appear in the object browser and the user can't move them with the normal motion modes.

`(new-camera name [CAMERA])' Create a new camera with the given name (a string). If a camera with that name already exists, the new object is given a unique name. If CAMERA is omitted a default camera is used.

`(new-center [id])' Stop id, then set id's transform to the identity. Default id is target. Also, if the id is a camera, calls (look-recenter World id). The main function of the call to (look-recenter) is to place the camera so that it is pointing parallel to the z axis toward the center of the world.

`(new-geometry name [GEOMETRY])' Create a new geom with the given name (a string). GEOMETRY is a string giving an OOGL geometry specification. If GEOMETRY is omitted, the new object is given an empty geometry. If an object with that name already exists, the new object is given a unique name.

`(new-reset)' Equivalent to (progn (new-center ALLGEOMS)(new-center ALLCAMS))

`(NeXT)' Returns t if running on a NeXT, nil if not

Geometry Center Thu Dec 12 02:41:23 CST 1996 12

Geomview(5) Geomview(5)

`(normalization GEOM-ID {each|none|all|keep})' Set the normalization status of GEOM-ID. `none' suppresses all normalization. `each' normalizes the object's bounding box to fit into the unit sphere, with the center of its bounding box translated to the origin. The box is scaled such that its long diagonal, sqrt((xmax-xmin)^2 + (ymax-ymin)^2 + (zmax-zmin)^2), is 2. `all' resembles `each', except when an object is changing (e.g. when its geometry is being changed by an external program). Then, `each' tightly fits the bounding box around the object whenever it changes and normalizes accordingly, while `all' normalizes the union of all variants of the object and normalizes accordingly. `keep' leaves the current normalization transform unchanged when the object changes. It may be useful to apply `each' or `all' normalization apply to the first version of a changing object to bring it in view, then switch to `keep'.

`(pick COORDSYS GEOMID G V E F P VI EI FI)' The pick command is executed internally in response to pick events (right mouse double click).

COORDSYS = coordinate system in which coordinates of the following arguments are specified. This can be: world: world coord sys self: coord sys of the picked geom (GEOMID) primitive: coord sys of the actual primitive within the picked geom where the pick occurred. GEOMID = id of picked geom G = picked point (actual intersection of pick ray with object) V = picked vertex, if any E = picked edge, if any F = picked face P = path to picked primitive [0 or more] VI = index of picked vertex in primitive EI = list of indices of endpoints of picked edge, if any FI = index of picked face

External modules can find out about pick events by registering interest in calls to `pick' via the `interest' command.

`(pick-invisible [yes|no])' Selects whether picks should be sensitive to objects whose appearance makes them invisible; default yes. With no arguments, returns current status.

`(pickable GEOM-ID {yes|no})' Say whether or not GEOM-ID is included in the pool of objects that could be returned from the pick command.

Geometry Center Thu Dec 12 02:41:23 CST 1996 13

Geomview(5) Geomview(5)

`(position objectID otherID)' Set the transform of objectID to that of otherID.

`(position-at objectID otherID [center | origin])' Translate objectID to the center of the bounding box or the origin of the coordinate system of otherID (parallel translation). Default is center.

`(position-toward objectID otherID [center | origin])' Rotate objectID so that the center of the bounding box or the origin of the coordinate system of the otherID lies on the positive z-axis of the first object. Default is the center of the bounding box.

`(progn STATEMENT [ ... ])' evaluates each STATEMENT in order and returns the value of the last one. Use progn to group a collection of commands together, forcing them to be treated as a single command.

`quit is a synonym for `exit''

`(quote EXPR)' returns the symbolic lisp expression EXPR without evaluating it.

`(rawevent dev val x y t)' Enter the specified raw event into the event queue. The arguments directly specify the members of the event structure used internally by geomview. This is the lowest level event handler and is not intended for general use.

`(rawpick CAMID X Y)' Process a pick event in camera CAMID at location (X,Y) given in integer pixel coordinates. This is a low-level procedure not intended for external use.

`(read {geometry|camera|transform|command} {GEOMETRY or CAMERA or ...})' Read and interpret the text in ... as containing the given type of data. Useful for defining objects using OOGL reference syntax, e.g.

(geometry thing { INST transform : T geom : fred }) (read geometry { define fred QUAD 1 0 0 0 1 0 0 0 1 1 0 0 }) (read transform { define T <myfile})

`(real-id ID)' Returns a string canonically identifying the given ID, or `nil' if the object does not exist. Examples: (if (real-id fred) (delete fred)) deletes `fred' if it exists but reports no error if it doesn't, and (if (= (real-id targetgeom) (real-id World)) () (delete targetgeom)) deletes `targetgeom' if it is different from the World.

`(redraw CAM-ID)'

Geometry Center Thu Dec 12 02:41:23 CST 1996 14

Geomview(5) Geomview(5)

States that the view in CAM-ID should be redrawn on the next pass through the main loop or the next invocation of `draw'.

`(regtable) --- shows the registry table'

`(rehash-emodule-path)' Rebuilds the application (external module) browser by reading all .geomview-* files in all directories on the emodule-path. Primarily intended for internal use; any applications defined by (emodule-define ...) commands outside of the .geomview-* files on the emodule-path will be lost. Does not sort the entries in the brower; see (emodule-sort) for that.

`(replace-geometry GEOM-ID PART-SPECIFICATION GEOMETRY)' Replace a part of the geometry for GEOM-ID.

`(rib-display [frame|tiff] FILEPREFIX)' Set Renderman display to framebuffer (popup screen window) or a TIFF format disk file. FILEPREFIX is used to construct names of the form `prefixNNNN.suffix'. (i.e. foo0000.rib) The number is incremented on every call to `rib-snapshot' and reset to 0000 when `rib-display' is called. TIFF files are given the same prefix and number as the RIB file (i.e. foo0004.rib generates foo0004.tiff). The default FILEPREFIX is `geom' and the default format is TIFF. (Note that geomview just generates a RIB file, which must then be rendered.)

`(rib-snapshot CAM-ID [filename])' Write Renderman snapshot (in RIB format) of CAM-ID to <filename>. If no filename specified, see `rib-display' for explanation of the filename used.

`(scale GEOM-ID FACTOR [FACTORY FACTORZ])' Scale GEOM-ID, multiplying its size by FACTOR. The factors should be positive numbers. If FACTORY and FACTORZ are present and non-zero, the object is scaled by FACTOR in x, by FACTORY in y, and by FACTORZ in z. If only FACTOR is present, the object is scaled by FACTOR in x, y, and z. Scaling only really makes sense in Euclidean space. Mouse-driven scaling in other spaces is not allowed; the scale command may be issued in other spaces but should be used with caution because it may cause the data to extend beyond the limits of the space.

`(scene CAM-ID [GEOMETRY])' Make CAM-ID look at GEOMETRY instead of at the universe.

`(set-clock TIME)' Adjusts the clock for this command stream to read TIME (in seconds) as of the moment the command is received. See also sleep-until, clock.

`(set-conformal-refine CMX [N [SHOWEDGES]])' Sets the parameters for the refinement algorithm used in drawing in the conformal model. CMX is the cosine of the maximum angle an edge can bend before it is refined. Its value should be between

Geometry Center Thu Dec 12 02:41:23 CST 1996 15

Geomview(5) Geomview(5)

-1 and 1; the default is 0.95; decreasing its value will cause less refinement. N is the maximum number of iterations of refining; the default is 6. SHOWEDGES, which should be `no' or `yes', determines whether interior edges in the refinement are drawn.

`(set-emodule-path (PATH1 ... PATHN))' Sets the search path for external modules. The PATHi should be pathnames of directories containing, for each module, the module's executable file and a .geomview-<modulename> file which contains an (emodule-define ...) command for that module. This command implicitly calls (rehash-emodule-path) to rebuild the application brower from the new path setting. The special directory name `+' is replaced by the existing path, so e.g. (set-emodule-path (mydir +)) prepends mydir to the path.

`(set-load-path (PATH1 ... PATHN))' Sets search path for command, geometry, etc. files. The PATHi are strings giving the pathnames of directories to be searched. The special directory name `+' is replaced by the existing path, so e.g. (set-load-path (mydir +)) prepends mydir to the path.

`(set-motionscale X)' Set the motion scale factor to X (default value 0.5). These commands scale their motion by an amount which depends on the distance from the frame to the center and on the size of the frame. Specifically, they scale by dist + scaleof(frame) * motionscale where dist is the distance from the center to the frame and motionscale is the motion scale factor set by this function. Scaleof(frame) measures the size of the frame object.

`(setenv name string) sets the environment variable `name' to the value'

STRING; the name is visible to geomview (as in pathnames containing `$name') and to processes it creates, e.g. external modules.

`(sgi)' Returns t if running on an sgi machine, nil if not

`(shell SHELL-COMMAND)' Execute the given UNIX SHELL-COMMAND using /bin/sh. Geomview waits for it to complete and will be unresponsive until it does. A synonym is `!'.

`(sleep-for TIME)' Suspend reading commands from this stream for TIME seconds. Commands already read will still be executed; `sleep-for' inside `progn' won't delay execution of the rest of the progn's contents.

`(sleep-until TIME)' Suspend reading commands from this stream until TIME (in seconds). Commands already read will still be executed; `sleep-until' inside `progn' won't delay execution of the rest of the progn's contents.

Geometry Center Thu Dec 12 02:41:23 CST 1996 16

Geomview(5) Geomview(5)

Time is measured according to this stream's clock, as set by `set-clock'; if never set, the first sleep-until sets it to 0 (so initially (sleep-until TIME) is the same as (sleep-for TIME)). Returns the number of seconds until TIME.

`(snapshot CAM-ID FILENAME [FORMAT [XSIZE [YSIZE]]])' Save a snapshot of CAM-ID in the FILENAME (a string). The FORMAT argument is optional; it may be `ppmscreen', `sgi', `ps', or `ppm'. A `ppmscreen' snapshot is created by reading the image directly from the given window; the window is popped above other windows and redrawn first, then its contents are written as a PPM format image. With `ps', dumps a Postscript picture representing the view from that window; hidden-surface removal might be incorrect. With `ppm', dumps a PPM-format image produced by geomview's internal software renderer; this may be of arbitrary size. If the FILENAME argument begins with the vertical bar `|', it's interpreted as a /bin/sh command to which the PPM or PS data should be piped. Optional XSIZE and YSIZE values are relevant only for `ppm' format, and render to a window of that size (or scaled to that size, with aspect fixed, if only XSIZE is given)

`(soft-shader CAM-ID {on|off|toggle})' Select whether to use software or hardware shading in that camera.

`(space {euclidean|hyperbolic|spherical})' Set the space associated with the world.

`(stereowin CAM-ID [no|horizontal|vertical|colored] [gapsize])' Configure CAM-ID as a stereo window. no: entire window is a single pane, stereo disabled horizontal: split left/right: left is stereo eye#0, right is #1. vertical: split top/bottom: bottom is eye#0, top is #1. colored: panes overlap, red is stereo eye#0, cyan is #1.

A gap of `gapsize' pixels is left between subwindows; if omitted, subwindows are adjacent. If both layout and gapsize are omitted, e.g. (stereowin CAM-ID), returns current settings as a `(stereowin ...)' command list. This command doesn't set stereo projection; use `merge camera' or `camera' to set the stereyes transforms, and `merge window' or `window' to set the pixel aspect ratio & window position if needed.

`(time-interests deltatime initial prefix [suffix])' Indicates that all interest-related messages, when separated by at least `deltatime' seconds of real time, should be preceded by the string `prefix' and followed by `suffix'; the first message is preceded by `initial'. All three are printf format strings, whose argument is the current clock time (in seconds) on that stream. A `deltatime' of zero timestamps every message. Typical usage: (time-interests .1 `(set-clock %g)' `(sleep-until %g)') or (time-interests .1 `(set-clock %g)' "(sleep-until %g) (progn (set-clock %g)" ")") or (time-interests .1 "(set-clock %g)" "(if (> 0 (sleep-until %g)) (" "))".

Geometry Center Thu Dec 12 02:41:23 CST 1996 17

Geomview(5) Geomview(5)

`(transform objectID centerID frameID [rotate|translate|translate-scaled|scale] x y z [dt] [`smooth'])' Apply a motion (rotation, translation, scaling) to object `objectID'; that is, construct and concatenate a transformation matrix with objectID's transform The 3 IDs involved are the object that moves, the center of motion, and the frame of reference in which to apply the motion. The center is easiest understood for rotations: if centerID is the same as objectID then it will spin around its own axes; otherwise the moving object will orbit the center object. Normally frameID, in whose coordinate system the (mouse) motions are interpreted, is `focus', the current camera. Translations can be scaled proportional to the distance between the target and the center. Support for spherical and hyperbolic as well as Euclidean space is built-in: use the `space' command to change spaces. With type `rotate' x, y, and z are floats specifying angles in RADIANS. For types `translate' and `translate-scaled' x, y, and z are floats specifying distances in the coordinate system of the center object. The optional `dt' field allows a simple form of animation; if present, the object moves by just that amount during approximately `dt' seconds, then stops. If present and followed by the `smooth' keyword, the motion is animated with a 3t^2-2t^3 function, so as to start and stop smoothly. If absent, the motion is applied immediately.

`(transform-incr objectID centerID frameID [rotate|translate|translate-scaled|scale] x y z [dt])' Apply continuing motion: construct a transformation matrix and concatenate it with the current transform of objectID every refresh (sets objectID's incremental transform). Same syntax as transform. If optional `dt' argument is present, the object is moved at each time step such that its average motion equals one instance of the motion per `dt' seconds. E.g. (transform-incr World World World rotate 6.28318 0 0 10.0) rotates the World about its X axis at 1 turn (2pi radians) per 10 seconds.

`(transform-set objectID centerID frameID [rotate|translate|translate-scaled|scale] x y z)' Set objectID's transform to the constructed transform. Same syntax as transform.

`(ui-center ID)' Set the center for user interface (i.e. mouse) controlled motions to object ID.

`ui-emotion-program is an obsolete command.' Use its new eqivalent `emodule-define' instead.

`ui-emotion-run is an obsolete command.' Use its new eqivalent `emodule_start' instead.

`(ui-freeze [on|off])' Toggle updating user interface panels. Off by default.

`(ui-panel PANELNAME {on|off} [ WINDOW ] )' Do or don't display the given user-interface panel.

Geometry Center Thu Dec 12 02:41:23 CST 1996 18

Geomview(5) Geomview(5)

Case is ignored in panel names. Current PANELNAMEs are: geomview main panel tools motion controls appearance appearance controls cameras camera controls lighting lighting controls obscure obscure controls materials material properties controls command command entry box credits geomview credits By default, the `geomview' and `tools' panels appear when geomview starts. If the optional Window is supplied, a `position' clause (e.g. (ui-panel obscure on { position xmin xmax ymin ymax }) sets the panel's default position. (Only xmin and ymin values are actually used.) A present but empty Window, e.g. `(ui-panel obscure on {})' causes interactive positioning.

`(ui-target ID [yes|no])' Set the target of user actions (the selected line of the target object browser) to ID. The second argument specifies whether to make ID the current object regardless of its type. If `no', then ID becomes the current object of its type (geom or camera). The default is `yes'. This command may result in a change of motion modes based on target choice.

`(uninterest (COMMAND [args]))' Undoes the effect of an `interest' command. (COMMAND [args]) must be identical to those used in the `interest' command.

`(update [timestep_in_seconds])' Apply each incremental motion once. Uses timestep if it's present and nonzero; otherwise motions are proportional to elapsed real time.

`(update-draw CAM-ID [timestep_in_seconds])' Apply each incremental motion once and then draw CAM-ID. Applies `timestep' seconds' worth of motion, or uses elapsed real time if `timestep' is absent or zero.

`(window CAM-ID WINDOW)' Specify attributes for the window of CAM-ID, e.g. its size or initial position, in the OOGL Window syntax. The special CAM-ID `default' specifies properties of future windows (created by `camera' or `new-camera').

`(winenter CAM-ID)' Tell geomview that the mouse cursor is in the window of CAM-ID. This function is for development purposes and is not intended for general use.

`(write {command,geometry,camera,transform,window} FILENAME [ID|(ID ...)] [self|world|universe|otherID])' write description of ID in given format to FILENAME. Last parameter chooses coordinate system for geometry & transform:

Geometry Center Thu Dec 12 02:41:23 CST 1996 19

Geomview(5) Geomview(5)

self: just the object, no transformation or appearance (geometry only) world: the object as positioned within the World. universe: object's position in universal coordinates; includes Worldtransform other ID: the object transformed to otherID's coordinate system.

A filename of `-' is a special case: data are written to the stream from which the 'write' command was read. For external modules, the data are sent to the module's standard input. For commands not read from an external program, `-' means geomview's standard output. (See also the `command' command.)

The ID can either be a single id or a parenthesized list of ids, like `g0' or `(g2 g1 dodec.off)'.

`(write-comments FILENAME GEOMID PICKPATH)' write OOGL COMMENT objects in the GEOMID hierarchy at the level of the pick path to FILENAME. Specifically, COMMENTS at level (a b c ... f g) will match pick paths of the form (a b c ... f *) where * includes any value of g, and also any values of possible further indices h,i,j, etc. The pick path (returned in the `pick' command) is a list of integer counters specifying a subpart of a hierarchical OOGL object. Descent into a complex object (LIST or INST) adds a new integer to the path. Traversal of simple objects increments the counter at the current level. Individual COMMENTS are enclosed by curly braces, and the entire string of zero, one, or more COMMENTS (written in the order in which they are encountered during hierarchy traversal) is enclosed by parentheses.

Note that arbitrary data can only be passed through the OOGL libraries as full-fledged OOGL COMMENT objects, which can be attached to other OOGL objects via the LIST type as described above. Ordinary comments in OOGL files (i.e. everything after '#' on a line) are ignored at when the file is loaded and cannot be returned.

`(write-sexpr FILENAME LISPOBJECT)' Writes the given LISPOBJECT to FILENAME. This function is intended for internal debugging use only.

`(xform ID TRANSFORM)' Concatenate TRANSFORM with the current transform of the object (apply TRANSFORM to object ID).

`(xform-incr ID TRANSFORM)' Apply continual motion: concatenate TRANSFORM with the current transform of the object every refresh (set object ID's incremental transform to TRANSFORM).

`(xform-set ID TRANSFORM)' Overwrite the current object transform with TRANSFORM (set

Geometry Center Thu Dec 12 02:41:23 CST 1996 20

Geomview(5) Geomview(5)

object ID's transform to TRANSFORM).

`(zoom CAM-ID FACTOR)' Zoom CAM-ID, multiplying its field of view by FACTOR. FACTOR should be a positive number.

Info file: geomview, -*-Text-*-

produced by texinfo-format-buffer

from file: geomview.tex

Geometry Center Thu Dec 12 02:41:23 CST 1996 21


oogl

package: geomview

title: oogl(5gv)

text:
# oogl(5gv)

OOGL(5gv) OOGL(5gv)

NAME

OOGL - File formats for OOGL geometric objects

NOTE

The material in this manual page also appears in the

Geomview manual.

DESCRIPTION

OOGL File Formats

*****************

The objects that you can load into Geomview are called OOGL objects.

OOGL stands for "Object Oriented Graphics Library"; it is the library

upon which Geomview is built.

There are many different kinds of OOGL objects. This chapter gives

syntactic descriptions of file formats for OOGL objects.

Examples of most file types live in Geomview's `data/geom'

directory.

Conventions

===========

Syntax Common to All OOGL File Formats

--------------------------------------

Most OOGL object file formats are free-format ASCII --- any amount of

white space (blanks, tabs, newlines) may appear between tokens (numbers,

key words, etc.). Line breaks are almost always 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 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

Geometry Center Thu Dec 12 02:36:08 CST 1996 1

OOGL(5) OOGL(5)

object being read from a pipe, or embedded in another OOGL object), all

known types of objects are tried in turn until one accepts the data as

valid.

Vertices

--------

Several objects share a common style of representing 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.

Surface normal directions

-------------------------

Geometry Center Thu Dec 12 02:36:08 CST 1996 2

OOGL(5) OOGL(5)

Geomview uses normal vectors to determine how an object is shaded.

The direction of the normal is significant in this 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.

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.

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:

Geometry Center Thu Dec 12 02:36:08 CST 1996 3

OOGL(5) OOGL(5)

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.

Embedded objects and external-object references

-----------------------------------------------

Some object types (`LIST', `INST') allow references to other

OOGL objects, which may appear literally in the data stream, be loaded

from named disk files, or be communicated from elsewhere via named

objects. Gcl commands also accept geometry in these forms.

The general syntax is

<oogl-object> ::= [ "{" ] [ "define" `symbolname' ] [ "appearance" `appearance' ] [ ["="] `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.

Geometry Center Thu Dec 12 02:36:08 CST 1996 4

OOGL(5) OOGL(5)

Files read using "<" are sought first in the directory of the file which

referred to them, if any; failing that, the normal search path (set by

Geomview's `load-path' command) is used. The default search looks

first in the current directory, then in the Geomview data directories.

The ":" construct allows references to symbols, created with

`define'. A symbol's initial value is a null object. When a

symbol is (re)defined, all references to it are 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.

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

Geometry Center Thu Dec 12 02:36:08 CST 1996 5

OOGL(5) OOGL(5)

-concave # (Don't) expect and handle concave polygons -shadelines # (Don't) shade lines as if they were lighted cylinders # These four are only effective where the graphics system # supports them, namely on GL and Open GL.

-keepcolor # Normally, when N-D positional coloring is enabled as # with 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 }

Geometry Center Thu Dec 12 02:36:08 CST 1996 6

OOGL(5) OOGL(5)

lighting { # Lighting model

ambient .3 .3 .3 # ambient light

replacelights # "Use only the following lights to # illuminate the 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

Geometry Center Thu Dec 12 02:36:08 CST 1996 7

OOGL(5) OOGL(5)

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.

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

Geometry Center Thu Dec 12 02:36:08 CST 1996 8

OOGL(5) OOGL(5)

indicated by the last few characters of the file name: .ppm or .ppm.Z or .ppm.gz 24-bit 3-color image in PPM format .pgm or .pgm.Z or .pgm.gz 8-bit grayscale image in PGM format .sgi or .sgi.Z or .sgi.gz 8-bit, 24-bit, or 32-bit SGI image .tiff 8-bit or 24-bit TIFF image .gif GIF image (Though 4-channel TIFF images are possible, and could 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.

Geometry Center Thu Dec 12 02:36:08 CST 1996 9

OOGL(5) OOGL(5)

Object File Formats

===================

QUAD: collection of quadrilaterals

----------------------------------

The conventional suffix for a `QUAD' file is `.quad'.

The file syntax is

[C][N][4]QUAD -or- [C][N][4]POLY # Key word VERTEX VERTEX VERTEX VERTEX # 4*N 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.

MESH: rectangularly-connected mesh

----------------------------------

The conventional suffix for a `MESH' file is `.mesh'.

The file syntax is

[U][C][N][Z][4][u][v][n]MESH # Key word [NDIM] # Space dimension, present only if nMESH NU NV # Mesh grid dimensions # NU*NV vertices, in format specified # by initial key word VERTEX(u=0,v=0) VERTEX(1,0) ... VERTEX(NU-1,0) VERTEX(0,1) ... VERTEX(NU-1,1) ... VERTEX(0,NV-1) ... VERTEX(NU-1,NV-1)

Geometry Center Thu Dec 12 02:36:08 CST 1996 10

OOGL(5) OOGL(5)

The key word is `[U][C][N][Z][4][u][v][n]MESH'.

The optional prefix characters mean:

`U' Each vertex includes a 3-component texture space parameter. The first two components are the usual `S' and `T' texture parameters for that vertex; the third should be specified as zero.

`C' Each vertex (see Vertices above) includes a 4-component color.

`N' Each vertex includes a surface normal 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.

Bezier Surfaces

---------------

Geometry Center Thu Dec 12 02:36:08 CST 1996 11

OOGL(5) OOGL(5)

The conventional file suffixes for Bezier surface files are `.bbp'

or `.bez'. A file with either suffix may contain either type of

patch.

Syntax:

[ST]BBP -or- [C]BEZ<NU><NV><ND>[_ST] # NU, NV are u- and v-direction # polynomial degrees in range 1..6 # ND = dimension: 3->3-D, 4->4-D (rational) # (The '<' and '>' do not appear in the input.) # NU,NV,ND are each a single decimal digit. # BBP form implies NU=NV=ND=3 so BBP = BEZ333.

\# Any number of patches follow the header # (NU+1)*(NV+1) patch control points # each 3 or 4 floats according to header VERTEX(u=0,v=0) VERTEX(1,0) ... VERTEX(NU,0) VERTEX(0,1) ... VERTEX(NU,1) ... VERTEX(0,NV) ... VERTEX(NU,NV)

\# ST texture coordinates if mentioned in header `S'(u=0,v=0) `T'(0,0) `S'(0,NV) `T'(0,NV) `S'(NU,0) `T'(NU,0) `S'(NU,NV) `T'(NU,NV)

\# 4-component float (0..1) R G B A colors # for each patch corner if mentioned in header `RGBA'(0,0) `RGBA'(0,NV) `RGBA'(NU,0) `RGBA'(NU,NV)

These formats represent collections of Bezier surface patches, of

degrees up to 6, and with 3-D or 4-D (rational) vertices.

The header keyword has the forms `[ST]BBP' or

`[C]BEZ<NU><NV><ND>[_ST]' (the '<' and '>' are

not part of the keyword.

The `ST' prefix on `BBP', or `_ST' suffix on

`BEZuvn', indicates that each patch includes four pairs of

floating-point texture-space coordinates, one for each corner of the

patch.

The `C' prefix on `BEZuvn' indicates a colored patch,

including four sets of four-component floating-point colors (red, green,

blue, and alpha) in the range 0..1, one color for each corner.

NU and NV, each a single digit in the range 1..6, are the

patch's polynomial degree in the u and v direction respectively.

ND is the number of components in each patch vertex, and must be

either `3' for 3-D or `4' for homogeneous coordinates, that

is, rational patches.

Geometry Center Thu Dec 12 02:36:08 CST 1996 12

OOGL(5) OOGL(5)

`BBP' patches are bicubic patches with 3-D vertices, so `BBP'

= `BEZ333' and `STBBP' = `BEZ333_ST'.

Any number of patches follow the header. Each patch 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.

Info file: geomview, -*-Text-*-

produced by texinfo-format-buffer

from file: geomview.tex

OFF Files

---------

The conventional suffix for `OFF' files is `.off'.

Syntax:

[ST][C][N][4][n]OFF # Header keyword [NDIM] # Space dimension of vertices, present only if nOFF NVERTICES NFACES NEDGES # NEdges not used or checked

X[0] Y[0] Z[0] # Vertices, possibly with normals, # colors, and/or texture coordinates, in that order, # if the prefixes `N', `C', `ST' # are present. # If 4OFF, each vertex has 4 components, # including a final homogeneous component. # If nOFF, each vertex has NDIM components. # If 4nOFF, each vertex has NDIM+1 components. ... X[NVERTICES-1] Y[NVERTICES-1] Z[NVERTICES-1]

Geometry Center Thu Dec 12 02:36:08 CST 1996 13

OOGL(5) OOGL(5)

\# Faces # NV = # vertices on this face # V[0] ... V[NV-1]: vertex indices # in range 0..NVERTICES-1 NV V[0] V[1] ... V[NV-1] COLORSPEC ... # COLORSPEC continues past V[NV-1] # to end-of-line; may be 0 to 4 numbers # nothing: default # integer: colormap index # 3 or 4 integers: RGB[A] values 0..255 # 3 or 4 floats: RGB[A] values 0..1

`OFF' files (name for "object file format") represent collections

of planar polygons with possibly shared vertices, a convenient way to

describe polyhedra. The polygons may be concave but there's no

provision for polygons containing holes.

An `OFF' file may begin with the keyword `OFF'; it's

recommended but optional, as many existing files lack this keyword.

Three ASCII integers follow: NVERTICES, NFACES, and

NEDGES. Thse are the number of vertices, faces, and edges,

respectively. Current software does not use nor check NEDGES; it

needn't be correct but must be present.

The vertex coordinates follow: dimension * NVERTICES

floating-point values. They're implicitly numbered 0 through

NVERTICES-1. dimension is either 3 (default) or 4 (specified by

the key character `4' directly before `OFF' in the keyword).

Following these are the face descriptions, typically written

with one line per face. Each has the form N VERT1 VERT2 ... VERTN [COLOR]

Here N is the number of vertices on this face,

and VERT1 through VERTN are indices into the list of

vertices (in the range 0..NVERTICES-1).

The optional COLOR may take several forms. Line breaks are

significant here: the COLOR description begins after VERTN

and ends with the end of the line (or the next # comment). A

COLOR may be:

nothing the default color

one integer index into "the" colormap; see below

three or four integers RGB and possibly alpha values in the range 0..255

three or four floating-point numbers RGB and possibly alpha values in the range 0..1

For the one-integer case, the colormap is currently read from the file

`cmap.fmap' in Geomview's `data' directory. Some better

Geometry Center Thu Dec 12 02:36:08 CST 1996 14

OOGL(5) OOGL(5)

mechanism for supplying a colormap is likely someday.

The meaning of "default color" varies. If no face of the object has a

color, all inherit the environment's default material color. If some

but not all faces have colors, the default is gray (R,G,B,A=.666).

A `[ST][C][N][n]OFF BINARY' format is accepted; *Note Binary format::. It

resembles the ASCII format in almost the way you'd expect, with 32-bit

integers for all counters and vertex indices and 32-bit floats for

vertex positions (and texture coordinates or vertex colors or normals if

`COFF'/`NOFF'/`CNOFF'/`STCNOFF'/etc. format).

Exception: each face's vertex indices are followed by an integer

indicating how many color components accompany it. Face color

components must be floats, not integer values. Thus a colorless

triangular face might be represented as

int int int int int 3 17 5 9 0

while the same face colored red might be

int int int int int float float float float 3 17 5 9 4 1.0 0.0 0.0 1.0

VECT Files

----------

The conventional suffix for `VECT' files is `.vect'.

Syntax:

[4]VECT NPOLYLINES NVERTICES NCOLORS

NV[0] ... NV[NPOLYLINES-1] # number of vertices # in each polyline

NC[0] ... NC[NPOLYLINES-1] # number of colors supplied # in each polyline

VERT[0] ... VERT[NVERTICES-1] # All the vertices # (3*NVertices floats)

COLOR[0] ... COLOR[NCOLORS-1] # All the colors # (4*NColors floats, RGBA)

`VECT' objects represent lists of polylines (strings of connected

line segments, possibly closed). A degenerate polyline can be used to

represent a point.

A `VECT' file begins with the key word `VECT' or `4VECT'

Geometry Center Thu Dec 12 02:36:08 CST 1996 15

OOGL(5) OOGL(5)

and three integers: NLINES, NVERTICES, and NCOLORS.

Here NLINES is the number of polylines in the file,

NVERTICES the total number of vertices, and NCOLORS the

number of colors as explained below.

Next come NLINES integers

NV[0] NV[1] NV[2] ... NV[NLINES-1]

giving the number of vertices in each polyline. A negative number

indicates a closed polyline; 1 denotes a single-pixel point. The sum

(of absolute values) of the NV[I] must equal NVERTICES.

Next come NLINES more integers Nc[i]: the number of colors in

each polyline. Normally one of three values:

0 No color is specified for this polyline. It's drawn in the same color as the previous polyline.

1 A single color is specified. The entire polyline is drawn in that color.

abs(NV[I]) Each vertex has a color. Either each segment is drawn in the corresponding color, or the colors are smoothly interpolated along the line segments, depending on the implementation.

The sum of the NC[I] must equal NCOLORS.

Next come NVERTICES groups of 3 or 4 floating-point numbers: the

coordinates of all the vertices. If the keyword is 4VECT then

there are 4 values per vertex. The first abs(NV[0]) of them form

the first polyline, the next abs(NV[1]) form the second and so on.

Finally NCOLORS groups of 4 floating-point numbers give red,

green, blue and alpha (opacity) values. The first NC[0] of them

apply to the first polyline, and so on.

A VECT BINARY format is accepted; *Note Binary format::. The

binary format exactly follows the ASCII format, with 32-bit ints where

integers appear, and 32-bit floats where real values appear.

SKEL Files

----------

`SKEL' files represent collections of points and polylines, with

shared vertices.

The conventional suffix for `SKEL' files is `.skel'.

Syntax:

Geometry Center Thu Dec 12 02:36:08 CST 1996 16

OOGL(5) OOGL(5)

[4][n]SKEL [NDIM] # Vertex dimension, present only if nSKEL NVERTICES NPOLYLINES

X[0] Y[0] Z[0] # Vertices # (if nSKEL, each vertex has NDim components) ... X[NVERTICES-1] Y[NVERTICES-1] Z[NVERTICES-1]

\# Polylines # NV = # vertices on this polyline (1 = point) # V[0] ... V[NV-1]: vertex indices # in range 0..NVERTICES-1 NV V[0] V[1] ... V[NV-1] [COLORSPEC] ... # COLORSPEC continues past V[NV-1] # to end-of-line; may be nothing, or 3 or 4 numbers. # nothing: default color # 3 or 4 floats: RGB[A] values 0..1

The syntax resembles that of `OFF' files, with a table of vertices

followed by a sequence of polyline descriptions, each referring to vertices

by index in the table. Each polyline has an optional color.

For `nSKEL' objects, each vertex has NDIM components.

For `4nSKEL' objects, each vertex has NDIM+1 components;

the final component is the homogeneous divisor.

No `BINARY' format is implemented as yet for `SKEL' objects.

SPHERE Files

------------

The conventional suffix for `SPHERE' files is `.sph'.

SPHERE RADIUS XCENTER YCENTER ZCENTER

Sphere objects are drawn using rational Bezier patches, which are diced into

meshes; their smoothness, and the time taken to draw them, depends on the

setting of the dicing level, 10x10 by default.

From Geomview, the Appearance panel, the `<N>ad' keyboard command, or

a `dice nu nv' Appearance attribute sets this.

INST Files

----------

The conventional suffix for a `INST' file is `.inst'.

There is no INST BINARY format.

An `INST' applies a 4x4 transformation to another OOGL object. It

Geometry Center Thu Dec 12 02:36:08 CST 1996 17

OOGL(5) OOGL(5)

begins with `INST' followed by these sections which may appear in

any order: geom OOGL-OBJECT

specifies the OOGL object to be instantiated. *Note References::, for

the syntax of an OOGL-OBJECT. The keyword `unit' is a

synonym for `geom'. transform ["{"] `4x4 transform' ["}"]

specifies a single transformation matrix. Either the

matrix may appear literally as 16 numbers, or there may be

a reference to a "transform" object, i.e. "<" file-containing-4x4-matrix

or ":" symbol-representing-transform-object>

Another way to specify the transformation is transforms OOGL-OBJECT

The OOGL-OBJECT must be a `TLIST' object (list of

transformations) object, or a `LIST' whose members are ultimately

`TLIST' objects. In effect, the `transforms' keyword takes a

collection of 4x4 matrices and replicates the `geom' object, making

one copy for each 4x4 matrix.

If no `transform' nor `transforms' keyword appears, no

transformation is applied (actually the identity is applied). You could

use this for, e.g., wrapping an appearance around an externally-supplied

object, though a single-membered LIST would do this more efficiently.

*Note Transformation matrices::, for the matrix format.

Two more INST fields are accepted: `location' and `origin'.

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

Normally an INST specifies a position relative to its parent object;

the `location' field allows putting an object elsewhere. * `location global' attaches the object to the global (a.k.a. universe) coordinate system -- the same as that in which geomview's World objects, alien geometry, and cameras are placed. * `location camera' places the object relative to the camera. (Thus if there are multiple views, it may appear in a different spatial position in each view.) The center of the camera's view is along its negative Z axis; positive X is rightward, positive Y upward. Normally the units of camera space are the same as global coordinates. When a camera is reset, the global origin is at (0,0,-3.0). * `location ndc' places the object relative to the normalized unit cube into which the camera's projection (perspective or orthographic) maps the visible world. X, Y, and Z are each in the range from -1 to +1, with Z = -1 the near and Z = +1 the far clipping plane, and X and Y increasing rightward and upward respectively. Thus something like INST transform 1 0 0 0 0 1 0 0 0 0 1 0 -.9 -.9 -.999 1 location ndc geom < label.vect pastes `label.vect' onto the lower left corner of each window,

Geometry Center Thu Dec 12 02:36:08 CST 1996 18

OOGL(5) OOGL(5)

and in front of nearly everything else, assuming `label.vect''s contents lie in the positive quadrant of the X-Y plane. It's tempting to use -1 rather than -.999 as the Z component of the position, but that may put the object just nearer than the near clipping plane and make it (partially) invisible, due to floating-point error. * `location screen' places the object in screen coordinates. The range of Z is still -1 through +1 as for ndc coordinates; X and Y are measured in pixels, and range from (0,0) at the *lower left* corner of the window, increasing rightward and upward.

`location local' is the default; the object is positioned relative

to its parent.

origin [global or camera or ndc or screen or local] x y z

The `origin' field translates the contents of the INST to

place the origin at the specified point of the given coordinate system.

Unlike `location', it doesn't change the orientation, only the choice

of origin. Both `location' and `origin' can be used together.

So for example { INST location screen origin ndc 0 0 -.99 geom { < xyz.vect } transform { 100 0 0 0 0 100 0 0 0 0 -.009 0 0 0 0 1 } }

places xyz.vect's origin in the center of the window, just beyond the

near clipping plane. The unit-length X and Y edges are scaled to be just 100

screen units -- pixels -- long, regardless of the size of the window.

INST Examples .............

Here are some examples of `INST' files

INST unit < xyz.vect transform { 1 0 0 0 0 1 0 0 0 0 1 0 1 3 0 1 }

{ appearance { +edge material { edgecolor 1 1 0 } } INST geom < mysurface.quad }

{INST transform {: T} geom {<dodec.off}}

{ INST transforms { LIST

Geometry Center Thu Dec 12 02:36:08 CST 1996 19

OOGL(5) OOGL(5)

{ < some-matrices.prj } { < others.prj } { TLIST <still more of them> }

} geom { # stuff replicated by all the above matrices ... } }

This one resembles the `origin' example in the section above,

but makes the X and Y edges be 1/4 the size of the window (1/4, not 1/2,

since the range of ndc X and Y coordinates is -1 to +1). { INST location ndc geom { < xyz.vect } transform { .5 0 0 0 0 .5 0 0 0 0 -.009 0 0 0 -.99 1 } }

LIST Files

----------

The conventional suffix for a `LIST' file is `.list'.

A list of OOGL objects

Syntax:

LIST OOGL-OBJECT OOGL-OBJECT ...

Note that there's no explicit separation between the oogl-objects, so

they should be enclosed in curly braces ({ }) for sanity. Likewise

there's no explicit marker for the end of the list; unless appearing

alone in a disk file, the whole construct should also be wrapped in

braces, as in:

{ LIST { QUAD ... } { < xyz.quad } }

A `LIST' with no elements, i.e. `{ LIST }', is valid, and is

the easiest way to create an empty object. For example, to remove a

symbol's definition you might write

{ define somesymbol { LIST } }

TLIST Files

-----------

Geometry Center Thu Dec 12 02:36:08 CST 1996 20

OOGL(5) OOGL(5)

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

or or `.prj' ("projective" matrices).

Collection of 4x4 matrices, used in the `transforms' section of and

`INST' object.

Syntax:

TLIST # key word

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

`TLIST's are used only within the `transforms' clause of an

`INST' object. They cause the `INST's `geom' object to

be instantiated once under each of the transforms in the `TLIST'.

The effect is like that of a `LIST' of `INST's each with a

single transform, and all referring to the same object, but is more

efficient.

Be aware that a `TLIST' is a kind of geometry object, distinct from a

`transform' object. Some contexts expect one type of object,

some the other. For example in INST transform { : MYT } geom { ... }

MYT must be a transform object, which might have been

created with the gcl (read transform { define myT 1 0 0 1 ... })

while in INST transforms { : MYTS } geom { ... } or INST transforms { LIST {: MYTS} {< more.prj} } geom { ... }

MYTS must be a geometry object, defined e.g. with (read geometry { define MYTS { TLIST 1 0 0 1 ... } })

A `TLIST BINARY' format is accepted. Binary data begins with a

32-bit integer giving the number of transformations, followed by that

number of 4x4 matrices in 32-bit floating-point format. The order of

matrix elements is the same as in the ASCII format.

GROUP Files

-----------

This format is obsolete, but is still accepted. It combined the

functions of `INST' and `TLIST', taking a series of

transformations and a single Geom (`unit') object, and replicating

the object under each transformation.

GROUP ... < matrices > ... unit { OOGL-OBJECT }

is still accepted and effectively translated into

INST transforms { TLIST ... <matrices> ... }

Geometry Center Thu Dec 12 02:36:08 CST 1996 21

OOGL(5) OOGL(5)

unit { OOGL-OBJECT }

DISCGRP Files

-------------

This format is for discrete groups, such as appear in the theory of

manifolds or in symmetry patterns. This format has its own man page.

See discgrp(5).

COMMENT Objects

---------------

The COMMENT object is a mechanism for encoding arbitrary data within an

OOGL object. It can be used to keep track of data or pass data back and

forth between external modules.

Syntax:

COMMENT # key word

NAME TYPE # individual name and type specifier { ... } # arbitrary data

The data, which must be enclosed by curly braces, can include anything

except unbalanced curly braces. The TYPE field can be used to

identify data of interest to a particular program through naming

conventions.

`COMMENT' objects are intended to be associated with other objects

through inclusion in a `LIST' object. (*Note LIST::.) The "#" OOGL

comment syntax does not suffice for data exchange since these comments

are stripped when an OOGL object is read in to Geomview. The

`COMMENT' object is preserved when loaded into Geomview and is

written out intact.

Here is an example associating a WorldWide Web URL with a piece of

geometry:

{ LIST { < Tetrahedron} {COMMENT GCHomepage HREF { http://www.geomview.org }} }

A binary `COMMENT' format is accepted. Its format is not consistent

with the other OOGL binary formats. *Note Binary format::. The

`name' and `type' are followed by

N BYTE1 BYTE2 ... BYTEN

instead of data enclosed in curly braces.

Geometry Center Thu Dec 12 02:36:08 CST 1996 22

OOGL(5) OOGL(5)

Non-geometric objects

=====================

The syntax of these objects is given in the form used in

*Note References::, where "quoted" items should appear literally but

without quotes, square bracketed ([ ]) items are optional, and | separates

alternative choices.

Transform Objects

-----------------

Where a single 4x4 matrix is expected -- as in the

`INST' `transform' field, the camera's `camtoworld' transform

and the Geomview `xform*' commands -- use a transform object.

Note that a transform is distinct from a `TLIST', which is a type

of geometry. `TLIST's can contain one or more 4x4 transformations;

"transform" objects must have exactly one.

Why have both? In many places -- e.g. camera positioning -- it's only

meaningful to have a single transform. Using a separate object type

enforces this.

Syntax for a transform object is

<transform> ::= [ "{" ] (curly brace, generally needed to make the end of the object unambiguous.)

[ "transform" ] (optional keyword; unnecessary if the type is determined by the context, which it usually is.) [ "define" <name> ] (defines a transform named <name>, setting its value from the stuff which follows)

<sixteen floating-point numbers> (interpreted as a 4x4 homogeneous transform given row by row, intended to apply to a row vector multiplied on its LEFT, so that e.g. Euclidean translations appear in the bottom row) | "<" <filename> (meaning: read transform from that file) | ":" <name> (meaning: use variable <name>, defined elsewhere; if undefined the initial value is the identity transform)

[ "}" ] (matching curly brace)

The whole should be enclosed in { braces }. Braces are not essential

if exactly one of the above items is present, so e.g. a 4x4 array of

floats standing alone may but needn't have braces.

Geometry Center Thu Dec 12 02:36:08 CST 1996 23

OOGL(5) OOGL(5)

Some examples, in contexts where they might be used:

\# Example 1: A gcl command to define a transform # called "fred"

(read transform { transform define fred 1 0 0 0 0 1 0 0 0 0 1 0 -3 0 1 1 } )

\# Example 2: A camera object using transform # "fred" for camera positioning # Given the definition above, this puts the camera at # (-3, 0, 1), looking toward -Z.

{ camera halfyfield 1 aspect 1.33 camtoworld { : fred } }

cameras

-------

A camera object specifies the following properties of a camera:

position and orientation specified by either a camera-to-world or world-to-camera transformation; this transformation does not include the projection, so it's typically just a combination of translation and rotation. Specified as a transform object, typically a 4x4 matrix.

"focus" distance Intended to suggest a typical distance from the camera to the object of interest; used for default camera positioning (the camera is placed at (X,Y,Z) = (0,0,focus) when reset) and for adjusting field-of-view when switching between perspective and orthographic views.

window aspect ratio True aspect ratio in the sense <Xsize>/<Ysize>. This normally should agree with the aspect ratio of the camera's window. Geomview normally adjusts the aspect ratio of its cameras to match their associated windows.

near and far clipping plane distances Note that both must be strictly greater than zero. Very large <far>/<near> distance ratios cause Z-buffering to behave badly; part of an object may be visible even if somewhat more distant than another.

field of view Specified in either of two forms. `fov '

is the field of view -- in degrees if perspective, or linear

Geometry Center Thu Dec 12 02:36:08 CST 1996 24

OOGL(5) OOGL(5)

distance if orthographic -- in the *shorter* direction. `halfyfield '

is half the projected Y-axis field, in world coordinates (not angle!), at unit distance from the camera. For a perspective camera, halfyfield is related to angular field:

halfyfield = tan( Y_axis_angular_field / 2 )

while for an orthographic one it's simply:

halfyfield = Y_axis_linear_field / 2

This odd-seeming definition is (a) easy to calculate with and (b) well-defined in both orthographic and perspective views.

The syntax for a camera is:

<camera> ::=

[ "camera" ] (optional keyword) [ "{" ] (opening brace, generally required) [ "define" <name> ]

"<" <filename> | ":" <name> | (or any number of the following, in any order...)

"perspective" {"0" | "1"} (default 1) (otherwise orthographic)

"stereo" {"0" | "1"} (default 0) (otherwise mono)

"worldtocam" <transform> (see transform syntax above)

"camtoworld" <transform> (no point in specifying both camtoworld and worldtocam; one is constrained to be the inverse of the other)

"halfyfield" <half-linear-Y-field-at-unit-distance> (default tan 40/2 degrees)

"fov" (angular field-of-view if perspective, linear field-of-view otherwise. Measured in whichever direction is smaller, given the aspect ratio. When aspect ratio changes -- e.g. when a window is reshaped --

Geometry Center Thu Dec 12 02:36:08 CST 1996 25

OOGL(5) OOGL(5)

"fov" is preserved.)

"frameaspect" <aspect-ratio> (X/Y) (default 1.333)

"near" <near-clipping-distance> (default 0.1)

"far" <far-clipping-distance> (default 10.0)

"focus" <focus-distance> (default 3.0)

[ "}" ] (matching closebrace)

window

------

A window object specifies size, position, and other window-system

related information about a window in a device-independent way.

The syntax for a window object is:

window ::=

[ "window" ] (optional keyword) [ "{" ] (curly brace, often required)

(any of the following, in any order)

"size" <xsize> <ysize> (size of the window)

"position" <xmin> <xmax> <ymin> <ymax> (position & size)

"noborder" (specifies the window should have no window border)

"pixelaspect" <aspect> (specifies the true visual aspect ratio of a pixel in this window in the sense xsize/ysize, normally 1.0. For stereo hardware which stretches the display vertically by a factor of 2, "pixelaspect 0.5" might do. The value is used when computing the projection of a camera associated with this window.)

[ "}" ] (matching closebrace)

Geometry Center Thu Dec 12 02:36:08 CST 1996 26

OOGL(5) OOGL(5)

Window objects are used in the Geomview `window' and

`ui-panel' commands to set default properties for future windows or

to change those of an existing window.

Geometry Center Thu Dec 12 02:36:08 CST 1996 27