Info file: geomview, -*-Text-*- produced by texinfo-format-buffer from file: geomview.tex  File: geomview Node: Module Installation, Prev: Example3, Up: Modules, Next: Private Module Installation Module Installation =================== This section tells how to install an external module so you can invoke it within Geomview. There are two ways to install a module: you can install a *private* module so that the module is available to you whenever you run Geomview, or you can install a *system* module so that the module is available to all users on your system whenever they run Geomview. * Menu: * Private Module Installation::. * System Module Installation::.  File: geomview Node: Private Module Installation, Prev: Module Installation, Up: Module Installation, Next: System Module Installation Private Module Installation --------------------------- The `emodule-define' command arranges for a module to appear in Geomview's *Modules* browser. `emodule-define' takes two string arguments; the first is the name that will appear in the *Modules* browser. The second is the shell command for running the module; it may include arguments. Geomview executes this command in a subshell when you click on the module's entry in the browser. For example (emodule-define "Foo" "/u/home/modules/foo -x") adds a line labeled "Foo" to the *Modules* browser which causes the command "/u/home/modules/foo -x" to be executed when selected. You may put `emodule-define' commands in your `~/.geomview' file to arrange for certain modules to be available every time you run Geomview; *Note Customization::. You can also execute `emodule-define' commands from the *Commands* panel if you want to add a module to an already running copy of Geomview. There are several other gcl commands for controlling the entries in the *Modules* browser; for details, *Note GCL::.  File: geomview Node: System Module Installation, Prev: Private Module Installation, Up: Module Installation, Next: GCL System Module Installation -------------------------- To install a module so that it is available to all Geomview users do the following 1 Create a file called `.geomview-MODULE' where `MODULE' is the name of the module. This file should contain a single line which is an `emodule-define' command for that module: (emodule-define "New Module" "newmodule") The first argument, `"New Module"' above, is the string that will appear in the *Modules* browser. The second string, `"newmodule"' above, is the shell command for invoking the module. It may include arguments, and you may assume that the module is on the $path searched by the shell. 2 Put a copy of the `.geomview-MODULE' and the module executable itself in Geomview's `modules/sgi' directory. This is a subdirectory of the Geomview distribution directory (on the Geometry Center's system the pathname is `/u/gcg/ngrap/modules/sgi'. After these steps, the new module should appear, in alphabetical position, in the *Modules* browser of Geomview's *Main* panel next time Geomview is run. The reason this works is that when Geomview is invoked it processes all the `.geomview-*' files in its `modules' directory. It also remembers the pathname of this directory and prepends that path to the $path of the shell in which it invokes such a module.  File: geomview Node: GCL, Prev: System Module Installation, Up: Top, Next: Argument Conventions 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. If you want to execute a gcl command interactively, you can bring up the *Command* 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. If you want 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 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. * Menu: * Argument Conventions:: Conventions used in describing argument types. * Gcl Reference:: Documentation for each gcl command.  File: geomview Node: Argument Conventions, Prev: GCL, Up: GCL, Next: Gcl Reference 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) `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.  File: geomview Node: Gcl Reference, Prev: Argument Conventions, Up: GCL, Next: Non-Euclidean Geometry Gcl Reference Guide =================== `!' `!' is a synonym for `shell' `?' `?' is a synonym for `help' `??' `??' is a synonym for `morehelp' `|' `|' is a synonym for `emodule-run' `(< 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. `(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. `(bbox-color GEOM-ID R G B)' Set the bounding-box color of GEOM-ID; R G B are between 0 and 1. `(bbox-draw GEOM-ID [yes|no])' Say whether GEOM-ID's bounding-box should be drawn; `yes' if omitted. `(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 } [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. `(cull-backface [on|off])' Select whether back-facing polygons should be displayed. Initially on: all polygons are displayed. When off, polygons whose vertices are arranged clockwise on the screen are hidden. Useful for simulating two-sided surface coloring. `(cursor CAM-ID {on|off} [pbmfile xorigin yorigin])' Turns the given window's graphics cursor on or off. Optionally sets the 16x16 pixel cursor glyph from the given file, which must be in binary (P4) PBM format. Can only be applied to actual windows, not e.g. `allcams' or `default'. Sorry. `(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. `(dither CAM-ID {on|off|toggle})' Turn dithering on or off in that camera. `(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. `(dice GEOM-ID N)' Dice any Bezier patches within GEOM-ID into NxN meshes; default 10. `(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 an external module named MODULENAME is known, returns the name of the program invoked when it's run as a quoted string; otherwise returns `nil'. `(echo (emodule-defined MODULENAME))' 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 is taken as gcl 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 *Modules* 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-pick {on|off})' Turn picking on or off. `(event-mode MODESTRING)' Set the mouse event (motion) mode; MODESTRING should be one of the strings that appears in the motion mode browser (including the keyboard shortcut, e.g. "[r] Rotate"). `(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)' 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 `(read ... define ...)' performs assignment as soon as the text is read. `(help [command])' Command may include "*"s as wildcards; see also `morehelp'. One-line command help; lists names only if multiple commands match. `?' is a synonym for `help'. `(hmodel CAM-ID {virtual|projective|conformal})' Set the model used to display geometry in this camera; see also `space'. `(hsphere-draw CAM-ID [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. `(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' (gcl 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 gcl file executes the commands in the file. `(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)). See also set-load-path. `(look [GEOM-ID] [CAM-ID])' Rotates the named camera to point toward the center of the bounding box of the named object (or the origin in hyperbolic or sphereical 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 [GEOM-ID] [CAM-ID] {center | origin}) [(look-encompass [GEOM-ID] [CAM-ID])] ) If GEOM-ID is not specified, it is assumed to be World. If CAM-ID is not specified, it is assumed to be targetcam. `(look-encompass [GEOM-ID] [CAM-ID])' Moves CAM-ID backwards or forwards until its field of view surrounds GEOM-ID. This routine works only in Euclidean space. If GEOM-ID is not specified, it is assumed to be the world. If CAM-ID 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 [GEOM-ID] [CAM-ID])' Translates and rotates the camera so that it is looking in the -z direction (in GEOM-ID's coordinate system) at the center of GEOM-ID'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 GEOM-ID and CAM-ID are parallel. `(look-toward [GEOM-ID] [CAM-ID] [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 GEOM-ID 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 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)'. `??' is a synonym for `morehelp' `(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. `(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)) `(ND-axes CAM-ID [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 CAM-ID [ (( [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 to be 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 color-function list. Even when coloring is enabled, objects tagged with the "keepcolor" appearance attribute are shown in their natural colors. `(ND-xform OBJECT-ID [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 * Transform = . `(NeXT)' Returns t if running on a NeXT, nil if not `(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. `(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. `(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 CAM-ID X Y)' Process a pick event in camera CAM-ID 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 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. `(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. `(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. `(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. 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)' Save a snapshot of CAM-ID in IRIS rgb image format in file FILENAME (a string). The window is popped above all other windows and redrawn before taking the snapshot. `(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 [LAYOUT] [GAPSIZE])' Configure CAM-ID as a stereo window. LAYOUT should be one of `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 usages: (time-interests .1 "(set-clock %g)" "(sleep-until %g)") (time-interests .1 "(set-clock %g)" "(sleep-until %g) (progn (set-clock %g)" ")") (time-interests .1 "(set-clock %g)" "(if (> 0 (sleep-until %g)) (" "))" `(transform OBJECT-ID CENTER-ID FRAME-ID [rotate|translate|translate-scaled|scale] X Y Z [DT [smooth]])' Apply a motion (rotation or translation) to object OBJECT-ID; that is, construct and concatenate a transformation matrix with OBJECT-ID's transform. The 3 ID's 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 CENTER-ID is the same as OBJECT-ID then it will spin around its own axes; otherwise the moving object will orbit the center object. Normally FRAME-ID, 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 uniformly by a total of that amount during approximately DT seconds, then stops. If DT is present and followed by the `smooth' keyword, the motion is animated to move the same amount but starting and stopping smoothly (using f(t)=3t^2 - 2t^3). If DT is absent, the motion is applied immediately. `(transform-incr OBJECT-ID CENTER-ID FRAME-ID [rotate|translate|translate-scaled] X Y Z [DT])' Apply continuing motion: construct a transformation matrix and concatenate it with the current transform of OBJECT-ID every refresh (sets OBJECT-ID'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 360 degrees every 10 seconds. `(transform-set OBJECT-ID CENTER-ID FRAME-ID [rotate|translate|translate-scaled] X Y Z)' Set OBJECTID's transform to the constructed transform. Same syntax as transform, except that DT animation is not supported. `(ui-center ID)' Set the center for user interface (i.e. mouse) controlled motions to object ID. `(ui-freeze [on|off])' Toggle whether user-interface panels should be updated. Off by default. Freezing, then unfreezing panels saves time when many updates are happening in quick succession, e.g. when deleting many objects. `ui-emotion-program' is an obsolete command. Use its new equivalent `emodule-define' instead. `ui-emotion-run' is an obsolete command. Use its new equivalent `emodule-start' instead. `(ui-panel PANELNAME {on|off} [ WINDOW ] )' Do or don't display the given user-interface panel. 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 *Main* 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])' 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|other ID])' write description of ID in given format to FILENAME. Last parameter chooses coordinate system for geometry & transform: `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 ID'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-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 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.  File: geomview Node: Non-Euclidean Geometry, Prev: Gcl Reference, Up: Top, Next: Mathematica Non-Euclidean Geometry ********************** Geomview supports hyperbolic and spherical geometry as well as Euclidean geometry. The three buttons at the bottom of the *Main* panel are for setting the current geometry type. In each of the three geometries, three models are supported: *Virtual*, *Projective*, and *Conformal*. You can change the current model with the *Model* browser on the *Camera* panel. Each Geomview camera has its own model setting. The default model is all three spaces is *Virtual*. This corresponds to the camera being in the same space as, and moving under the same set of transformations as, the geometry itself. In Euclidean space *Virtual* is the most useful model. The other models were implemented for hyperbolic and spherical spaces and just happen to work in Eucldiean space as well: *Projective* is the same as *Virtual* but by default displays the unit sphere, and *Conformal* displays everything inverted in the unit sphere. In hyperbolic space, the *Projective* model setting gives a view of the projective ball model of hyperbolic 3-space imbedded in Euclidean space. The camera is initially outside the unit ball. In this model, the camera moves by Euclidean motions and geometry moves by hyperbolic motions. *Conformal* model is similar but shows the conformal ball model instead. In spherical space, the *Projective* model gives a view of half of the 3-sphere imbedded in Euclidean 3-space. Spherical motions give rise to projective transformations in the *Projective* model, and to Moebius transformations in the *Conformal* model. In both of these models the camera moves by Euclidean motions. In *Projective* and *Conformal* models, the unit sphere is drawn by default. You can turn it off and on at will using the *Draw Sphere* button in the *Camera* panel. In the *Conformal* model, polygons and edges are subdivided as necessary to make them look curved. The parameters which determine this subdivision can be set with the `set-conformal-refine' gcl command. There are several sample hyperbolic space objects in the `data/geom/hyperbolic' subdirectory of the Geomview directory (`/u/gcg/ngrap/data/geom/hyperbolic' on the Geometry Center's system). Likewise, the subdirectory `data/geom/spherical' contains several sample spherical space objects.