Scripting Interface

GeoZui3D runs a Tcl/Tk interpreter in a separate text window (or under Linux, the shell from which GeoZui3D was launched). This interface provides a way of controlling certain aspects of GeoZui3D in a command-line mode, or from a separate script file. For more information about Tcl/Tk, check out the official developer web site at http://dev.scriptics.com (there's a "Getting Started" tab for those who would like to learn more about using Tcl/Tk).

Scripting Basics
Advanced Concepts

How to Execute Commands

There are several ways of executing Tcl/Tk commands from GeoZui3D.

Enter commands directly on the GeoZui3D command line (pictured for Windows platforms above).
Source a script file that contains the commands you wish to execute. To do this, type the following on the GeoZui3D command line (where "myscript.tcl" is the name of your script file): source "myscript.tcl"
Add the name of a script file to the end of a project (.sdv) file, and load the project file. GeoZui3D will automatically source this file once the project has been loaded.
Use the < Script> syntax in the XML Scene (.gzx) format. you can either specify a file to be sourced by using filename= inside the Script tag, or by entering script commands between the < Script> and < /Script> tags.
Name your script file "user.tcl" and place it in the GeoZui3D/bin directory. If present, this script will is executed every time GeoZui3D is launched.

Selected GeoZui3D Variables

The following are global variables accessible to any command (you may need to call them out as global, i.e. "global stereoflag").

currentProjection String holding the name of the projection under which GeoZui3D is operating. This is set automatically when an object with projection information is loaded. If no projection is set, the value of this string is "<unknown>"

dominantEye Controls which eye the one-eyed cursor is displayed in (0 is left, 1 is right).

drewLowRes This is set to 0 if a redisplay is in progress, and 1 otherwise.

GeoZuiVersion The floating point number representing the current version of GeoZui3D (read-only).

GeoZuiDescriptor A read-only string with information about the current build (empty for a normal distribution).

highResMutexHolder If a window is currently drawing in high-res, this variable holds a value that is unique to that window. Only one window can draw in high-res at a time. If no window is currently drawing in high-res, this variable's value is 0.

interactivityHint A number between 0.0 and 1.0 indicating what balance between resolution and interactivity GeoZui3D should try to achieve. A value of 0.0 gives resolution the highest precedence during interaction, while a value of 1.0 gives interactivity the highest precedence. Currently, the variable is only recognized by GUTM objects.

numEditedObjects The number of objects that have been edited but not saved (read-only).

oneEyedFlag Controls whether or not the one-eyed cursor is enabled (0 is off, 1 is on).

recorderResolution Specifies the resolution at which the recorder synchronizes (in milliseconds). Higher resolutions (smaller values for recorderResolution) make for a larger files, but are more flexible at playback time. Slower machines may not respect high resolutions at record time.

recordingState Specifies whether or not GeoZui3D is currently recording (0 is off, 1 is recording).

stereoflag Controls stereo mode (-1 is off, 1 is on).

subWindowCount Usually holds the number of subwindows created since GeoZui3D was launched.

toglPath An array that holds the Tcl/Tk path for a given 3D rendering window. For example, $toglPath(main) and $toglPath(sub0) would usually return .glwindow and .sub0.innards.togl, respectively (these can be used for the commands described in the next section of this page).

translateRate Determines the speed at which translation occurs using the middle mouse button. The speed is given as a percentage of the distance to the selected location covered roughly every 1/25th of a second. The default value is 25. A value of 100 corresponds to instantaneous motion, while a value of 0 corresponds to no movement.

widgetCompass Determines whether or not the compass appears on the widgets (0 is off, 1 is on).

widgetHScale Determines whether or not the horizontal scale appears on the widgets (0 is off, 1 is on).

widgetPickHeight Sets the maximum y-distance a mouse-click can be from a widget component and still activate that component. Defaults to 1.5.

widgetPickWidth Sets the maximum x-distance a mouse-click can be from a widget component and still activate that component. Defaults to 1.5.

widgetVisible Determines whether or not the widgets are visible (-1 is off, 1 is on).

widgetVScale Determines whether or not the vertical scale appears on the widgets (0 is off, 1 is on).

xPlacement An array that holds the x coordinate of a given window. For example, $xPlacement(main) or $xPlacement(sub1).

xSize An array that holds the width of a given window. For example, $xSize(main) or $xSize(sub1).

yPlacement An array that holds the y coordinate of a given window. For example, $yPlacement(main) or $yPlacement(sub1).

ySize An array that holds the height of a given window. For example, $ySize(main) or $ySize(sub1).

zoomInRate Determines the rate at which zooming in occurs using the middle mouse button. The rate is given as a percentage zoom factor, applied roughly every 1/25th of a second. The default value is 8. A value of 0 corresponds to no zooming, while a value of 40 causes extremely fast zooming.

zoomInterface Selects which mouse behavior to expect for zooming (the menu items in the Zooming Interface Menu have the values 1, 2, and 4, respectively... 3, 5, and 6 are also valid).

zoomOutRate Determines the rate at which zooming out occurs using the middle mouse button. The rate is given as a percentage zoom factor, applied roughly every 1/25th of a second. The default value is 8. A value of 0 corresponds to no zooming, while a value of 40 causes extremely fast zooming.

Selected Global Procedures

The following are global procedures accessible to any command.

appendObjectInfo arg Add arg to the text in the Information Frame of the Object Panel.

attributePanel object [show | hide | close] Control the attribute panel associated with object. The "show" command causes a panel to be shown (created if did not exist, or shown if created but hidden). The "hide" command hides an existing panel. The "close" command destroys an existing panel, regardless of whether it is shown or hidden.

clearObjectInfo Clear any text currently in the Information Frame of the Object Panel.

disableBindings Turn off mouse and keyboard input to the main window and CLUT editor.

enableBindings Allow the main window and CLUT editor to accept mouse and keyboard input.

loadobj filename Load filename into GeoZui3D.

newobj type label [x y z] Create new object. The type may be its type (ex: DataTriangles) or extension (ex: .gdt). The x y z values represent the objects GeoReferencing point.

pauseRecording Pause any currently recording or playing script.

recordAndExecMaybe arg Record arg in the recording script and execute arg as a command, as well.

recordAndExecMaybe arg If GeoZui3D is currently recording, record arg in the recording script. Regardless, execute arg as a command, as well.

recordMaybe arg If GeoZui3D is currently recording, record arg in the recording script. (arg is not executed.)

recordTimestampMaybe [arg] If GeoZui3D is currently recording, record a timestamp in the recording script. If arg is present, attach it to the timestamp as a comment.

redisplay Redraw the main window.

stopRecording Stop any currently recording or playing script.

subtogl path args The user can redefine this function to provide different defaults to the creation of GeoZui3D subwindows. The redefined function should be a permutation of the following code. return [eval "subwindow $windowPath $args -contents 3D"] "-contents 3D" is an example of a default being specified. Other valid attributes besides -contents are -height, -width, -titleheight, -borderwidth, -resizewidth, -parent, -x, -y, (the next four are boolean switches) -overview, -showtitle, -setbuttons, -lockbuttons, and any normal Tcl/Tk options for frames.

subwindowDisableBindings win Turn off mouse and keyboard input to the subwindow win.

subwindowEnableBindings win Allow the subwindow win to accept mouse and keyboard input.

subwindowPlace win x y width height 1 Move and resize the subwindow win accordingly.

subwindowRaise win Bring the subwindow win to the front.

subwindowTitle win titletext Set the title for win to titletext and show the title bar if it is not already showing. If titletext is empty (""), then the titlebar is removed.

subwindowVerifyList Returns a list of all subwindows currently in existence.

Selected Togl Subcommands

The following are procedures accessible only through Togl objects, such as the main window, the CLUT editor, and subwindows. For example, "$toglPath(sub0) minimize" or ".glwindow useHeightExaggeration 3.5".

bgcolor color	Sets the background color for all windows to the RGB color specified in the 6 hex digits of color.
keyboard x y mod key state keysym	Generate a keyboard event to the Togl object, with the mouse at position (x, y). mod indicates what modifier keys are currently held down (Shift=0x01, CapsLock=0x02, Control=0x04, NumLock=0x08, ScrollLock=0x20, Alt=0x20000). key is the printable value for the character, such as "w". state is the whether the key is being pressed (0) or released (1). Keysym is the Tcl/Tk keysym for the key (special keys such as the arrow keys are up in the 0xFF00's.
motion x y mod type	Generate a mouse motion event to the Togl object, with the mouse at position (x, y). mod indicates what modifier keys are currently held down (Shift=0x01, CapsLock=0x02, Control=0x04, NumLock=0x08, ScrollLock=0x20, Alt=0x20000). type is -1 for a leaving-window event, 1 for an entering-window event, and 0 otherwise.
mouse x y mod button state	Generate a mouse button event to the Togl object, with the mouse at position (x, y). mod indicates what modifier keys are currently held down (Shift=0x01, CapsLock=0x02, Control=0x04, NumLock=0x08, ScrollLock=0x20, Alt=0x20000). button is a number from 1 to 3 (left, middle, right), and state is the whether the mouse button is being pressed (0) or released (1).
recorder option [filename]	Control the recording and playback functions. Valid options are file (which selects the file on which future play or record commands will work), pause, play, record, and stop. For the file option, filename must be present. The play and record options may have a filename as an optional argument. If no filename is given, then the last assigned name (or the default name) is used.

Selected Togl-Window Subcommands

The following are procedures accessible only through Togl-Window objects, such as the main window and subwindows (not the CLUT editor). For example, "$toglPath(sub0) minimize" or ".glwindow useHeightExaggeration 3.5".

createSubwindow	Creates a subwindow with a center matching this window's center.
*clippingPlane plane* [OFF \| normal-x normal-y distance]**	Modifies the clipping plane specified by plane (0 or 1) for this window. If OFF is specified, the clipping plane is disabled. Otherwise, the selected plane is enabled as a vertical plane (with respect to world coordinates) with normal (normal-x, normal-y) at a distance of distance from the center of workspace for the window (in world coordinates). The clipping plane appears to move toward and away from the center of workspace as the window is scaled out and in, respectively.
*distanceToFarPlane [value]*	If no value is given, returns the current (relative) distance from the eyepoint to the farplane in this window. If a value is given, the distance from the eyepoint to the farplane is set to this value. While at a scale around 1, the distance may appear to be in meters, other changes in the frustum make any units relatively meaningless.
getHeightExaggeration	Returns the current height exaggeration, as displayed in the Height Exaggeration Frame.
*inParent {proxy\|tethers\|flagpole\|eyepoint\|center} {show\|pick\|strength} [val]*	Determines how the proxy and tethers for this window will appear and/or interact. "pick" is only valid with "proxy", and "strength" is not valid with "eyepoint". For "show" the selected item is hidden if val is 0, and is shown otherwise. For "strength" the transparency of the selected item is set, with fully opaque being 1.0 and fully transparent being 0.0. For "pick", determines whether or not the mouse can be used to drag the proxy. The "proxy" item designates essentially the whole proxy, with "strength" applying to anything not covered by other items. The "tethers" item applies to the lines connecting the window to its proxy in its parent window. The "flagpole" item designates the scale-dependent post (with the "Z" on top). The "eyepoint" item designates the yellow box that represents the eyepoint for the window, as well as the drop line emanating from it. Finally, the "center" item is the central crosshair of the proxy that represents where the widgets for this window are.
limitScale min max	Limits the scale on this window to be between min and max. A value of 0.0 on either removes the limitation.
*localHeightExaggeration [value]*	Sets the height exaggeration for this window only. Returns the current height exaggeration (after assignment), which is different from the one globally displayed in the Height Exaggeration Frame. Setting a value of 0 returns the window to using the global height exaggeration.
lockTo posable type	Locks this window to the object or window specified by posable. type is a concatenation of any of the following: (t)T - (Delta-)Lock translation (h)H - (Delta-)Lock heading (p)P - (Delta-)Lock pitch (r)R - (Delta-)Lock roll (s)S - (Delta-)Lock scale l - Localized-relative lock (apply scale, orientation to translation) + - Two-way lock (changes in either will affect either) < - One-way lock from window to posable (changes in window affect posable) For instance: "THPR" or "Thpr" or "T" or "th".
overview	Shows the overview window for this window.
perspective [0 \| 1]	If no value is given, returns 1 if the window is using a perspective projection and 0 if it is using orthogonal. If 0 is passed, sets the projection for this window to orthogonal. If 1 is passed, set the projection to perspective.
*plotPoint {world\|screen} x y* {z\|depth}**	Plots a point in the window. If "world" is specified, returns the screen coordinates of the passed x, y, and z values. If "screen" is specified, returns the world coordinates of the passed x, y, and depth values. A depth of -1 indicates that the z-buffer should be used at that point to get the depth value.
restoreSubwindows	Restores all hidden subwindows of this window.
setHeightExaggeration value	Sets height exaggeration in all windows to value. This is equivalent to hitting the "Test" button in the Height Exaggeration Frame.
useHeightExaggeration value	Sets height exaggeration in all windows to value and recalculate the lighting normals for all objects. This is equivalent to hitting the "Apply" button in the Height Exaggeration Frame.
*wireframe [value]*	Causes all objects to be rendered in wireframe within this window if value is 1, otherwise renders normally. Returns the current state (after assignment).

Selected Subwindow Subcommands

The following are procedures accessible only through subwindows, (not the CLUT editor or the main window). For example, "$toglPath(sub0) minimize".

minimize	Hides this window from view, leaving only its proxy in in its parent window.
restore	Restores this window if it is hidden.
view_get_*	The * can be one of scale, position, rotate_x (pitch), or rotate_y (yaw). Causes the specified attribute of this window to be set equal to the value in the parent window.
view_lock_* state	The * can be one of scale, position, rotate_x (pitch), or rotate_y (yaw). If state is 1 establishes the specified lock to a parent; if 0, disables the lock.
view_set_*	The * can be one of scale, position, rotate_x (pitch), or rotate_y (yaw). Causes the specified attribute of the parent to be set equal to the value in this window.

Selected Color Key Subcommands

The following are procedures accessible only through the color key, which is a special kind of CLUT editor. It also has some properties of subwindows, in that it responds to global commands such as subwindowPlace. The color key can be accessed in two ways, either "$toglPath(key) keydisplay ..." or "$colorKey keydisplay ...", for instance "$colorKey keydisplay align 1".

*align [value]*	Aligns the color labels with the boundaries between two colors if value is 1, and disregards these boundaries if 0. Returns the current behavior (after the assignment, if applicable).
*bg [value]*	Sets the level of grey for the background. 0.0 indicates black, while 1.0 indicates white. Returns the current color (after any assignment).
*fg [value]*	Sets the level of grey for the label text and tick marks. 0.0 indicates black, while 1.0 indicates white. Returns the current color (after any assignment).
*max [value]*	Sets the maximum CLUT height for which a labeled color can appear (part of the CLUT above this value may still appear). Returns the maximum (after any assignment).
*midtics [value]*	Sets the number of labeled tics between the top and bottom labels, regardless of any max, min, or step settings. If value is -1, restores the display to respect the max, min, and step settings. Returns the current behavior (after any assignment).
*min [value]*	Sets the minimum CLUT height for which a labeled color can appear (part of the CLUT above this value may still appear). Returns the minimum (after any assignment).
*step [value]*	Sets the CLUT height-step to be used in generating labels and tics. Tics are started from the minimum and work toward the maximum. Returns the current behavior (after any assignment).
*units [value]*	Determines whether or not the color labels include units at the end (currently, only meters--"m"--are supported). Returns the current behavior (after any assignment).

Selected gz Subcommands

A special command called "gz" has been created to provide a way to control GeoZui3D directly. Subcommands that themselves have elaborate syntaxes are described in their own section. gz subcommands must always be preceded by "gz", for example "gz clearScene" or "gz getOrigin X".

address option [args]	This command is described in the section called The GeoZui3D Address Hierarchy.
animator option [args]	This command is described in the section Animators.
clearScene	Clears the scene by unloading all objects from GeoZui3D and restoring the main window to the home position.
getObjectTypes	Returns a list of all object types implemented by GeoZui3D.
getObjectExtensions	Returns a list of all object extensions recognized by GeoZui3D in the same order as the respective values returned in getObjectTypes.
getOrigin dimension	Returns a component of the origin used by GeoZui3D for the posable command. The component returned is specified by dimension, which is one of X, Y, or Z (case insensitive).
posable option [posable [type [args]]]	This weighty command is described in the section Posables.
projection option [projection [args]]	This command is described in the section Projections.
setTransparentBlendThreshold value	Sets the threshold at which transparent textures blend with the background colors to become opaque. value must be between 0.0 and 1.0. Lower values make a transparently textured object appear more gossamer from afar, while higher values make them appear more embossed. A value between 0.2 and 0.5 is recommended.
tellObject address args	Passes a command along to entity at the given address. If the address is not fully-qualified (starting with a dot--"."), then the address is first assumed to be under .Posable.Object, and if it is not found there, .Posable. Valid messages are type-specific, although all entities recognize the "list" command.
tellSelectedObject	Passes a message along to the most recently clicked-on object (usually by right mouse button). Valid messages are object-specific, although all objects recognize certain commands.

The GeoZui3D Address Hierarchy

GeoZui3D maintains a named hierarchy for accessing various internal entities, including windows, objects, animators, and projections. The address of an entity is composed of the names of each node from the root of the tree to the leaf, separated by periods (dots). The root of the tree has no name, so all fully qualified names start with a dot. For instance, ".Posable.Window.main" is the fully qualified name of the main window's posable. "Posable" is a top-level address just below the root, and is a parent node of "Window", which in turn is a parent node of "main". The "gz" command has many options that require addresses, but not all of these addresses need to be fully qualified. Many commands assume an address prefix, such as ".Posable.Object.", if the given address does not begin with a dot. However, all addresses that do begin with a dot are considered to be fully qualified, and are never resolved against a prefix.

Address Subcommand Options

The "address" subcommand has several options that allow reorganization of the address hierarchy. Addresses can be created and destroyed, and they can be made children of one another. The tree nature of the address hierarchy is not strictly enforced, which means it is possible to introduce cycles into the hierarchy. However, GeoZui3D scripting commands will become unstable if an address that is part of a cycle is deleted. Every address has only one designated parent and therefor only one path to the root by which a fully qualified name is produced. In the following commands, it will sometimes make sense to make reference to the unnamed root address. In these instances, the token "toplevel" can be used to represent the root. For instance: "gz address create toplevel MyAddress".

gz address addchild parent-address child-address	Makes child-address a child of parent-address, without changing the designated parent of child-address.
gz address create parent new-name	Creates a new address node named new-name under parent. If "topelevel" is specified, the new address is created directly beneath the root.
gz address delete address	Deletes address if it has no children. If children exist, an error is generated. Using the delete option on addresses created by GeoZui3D or on children with multiple addresses will cause GeoZui3D to become unstable or crash.
*gz address list [address]*	Returns a list of fully-qualified addresses that are children of address. If no address argument is given, returns the toplevel addresses.
gz address numchildren address	Returns a the number of children under address.
gz address removechild parent child	Removes child from under its parent.
gz address reparent address new-parent	Moves address from under its current parent to be parented by new-parent, while removing address from under its former parent.
gz address type address	Returns the type of item represented at address.

Posables

A posable is informaiton about the current position, orientation, and scale of an item. The user of a posable is something that can be translated, rotated, and/or scaled. In GeoZui3D, every window and object is considered to be a posable user. The various attributes of a posable can be altered or examined through the gz subcommand "posable". In order to reference a posable through this command, it is necessary to know its address. The posable namespace is arranged as a hierarchy. The address of a leaf (posable) is composed of the names of each node from the root to the leaf, separated by periods (dots). For instance, the address of the posable of the main window is ".Posable.Window.main", while the address of the posable of lighting within subwindow sub0 is ".Posable.Window.sub0.Light". Every window has a child called "Light", which controls the lighting direction (vector formed by position), and a child called "perspective", which controls the viewing frustum for the the window (currently only scale is supported). While objects don't start with children, they can have child nodes created beneath them. All objects are currently children of ".Posable.Object".

Posable Subcommand Options

The "posable" subcommand accepts addresses without the leading ".Posable." prefix (you can use Object.nonan_gutm or Window.main, for instance). There are several options to the "posable" subcommand, each of which is described along with its respective syntax below. The possible values of type are described in the next subsection. The possible values of posable-type are under the gz posable type description.

gz posable couple posable to source-posable coupling-type	Couples posable to source-posable, using a coupling of type coupling-type. Any changes in source-posable that are specified by coupling-type are automatically propogated to posable. If a coupling already exists between the two posables, it is used. Otherwise a new coupling is created. The address of the coupling used is returned. coupling-type is a concatenation of any of the following characters: (t)T - (Relative-)Couple translation (h)H - (Relative-)Couple heading (p)P - (Relative-)Couple pitch (r)R - (Relative-)Couple roll (s)S - (Relative-)Couple scale l - Localized-relative coupling (apply scale, orientation to translation) + - Two-way coupling (changes in either will affect either) < - Reverse coupling (changes in posable affect source-posable) For instance: "THPR" or "Thpr" or "T" or "th". Dislaimer: Not all combinations of couplings are guaranteed to work as one might expect, especially if a window is used as a source-posable.
gz posable create parent new-name posable-type	Creates a new posable named new-name under the address parent (which may or may not be in the .Posable hierarchy) with a mechanism of type posable-type. The new posable is not attached to an object or window in any way. The originating purpose of such posables is to act as control interfaces to animators.
*gz posable decouple posable* and source-posable [coupling-type]**	Decouples posable and source-posable, decoupling only in attributes specified by coupling-type if given, or decoupling completely otherwise. Does not delete a coupling even if all attributes are decoupled. See "gz posable couple" for valid values of coupling-type.
gz posable delete posable	Deletes a posable, disabling any associated couplings (but not assiciated animators, although deleted posables are removed from animator operands and resultants).
gz posable get posable type	Returns a list of values for posable corresponding to the specifications of type.
*gz posable list [posable]*	Returns a list of fully-qualified (from the root Posable) addresses that are children of posable. If no posable argument is given, returns the children of "Posable".
gz posable offset posable type args	Increments the values for posable corresponding to the specifications of type by using each of the args in turn.
gz posable set posable type args	Sets the values for posable corresponding to the specifications of type using each of the args in turn.
gz posable substitute posable posable-type	Substitutes a posable mechanism of type posable-type for the mechanism currently used by posable. This is useful for endowing objects with new or different behaviors for characteristics such as rotation or scale. For instance, the "exaggerate" type allows an object to be stretched by applying scale in the z-direction only.
gz posable type posable	Returns the name of the posable mechanism used by posable. Currently, three types are available: object, translate, translate_wrapper, and exaggerate. The "object" type allows for normal rotation, orientation, and scale operations, as well as home, minimum, and maximum values. The "translate" type only allows for translation, and is a resource-conserving posable mechanism. The "translate_wrapper" type is similar, except that its values are provided by the object to which the wrapper is attached (see Wrappers). The "exaggerate" type is like the "translate" type, except that scale information is also used (this scale is only applied in the z-direction).
gz posable unset posable type	Invalidates the values for posable corresponding to the specifications of type. For limiting attributes such as minimums and maximums, this eliminates the limit. For normal attributes, values are set to 0.

Posable Subcommand Types

Four forms of the "posable" subcommand that require a type argument. This type is composed of one or more characters indicating the sort of information that is requested or is being changed. Note: positions returned for x, y, and z are all relative to GeoZui3D's current origin. This origin can be determined by using the Togl-Window subcommand "getOrigin".

h	Heading.
p	Pitch.
r	Roll.
s	Scale.
x	X-Position.
y	Y-Position.
z	Z-Position.

The type may optionally also contain one of the following "class" characters.

C	"Current", or normal value. This is the default if no class character is present.
H	"Home" value. For windows, this is usually the value at the time of window creation. For objects, this is usually the value at object-load time.
m	Minimum value. This is a lower limit on the "current" value, below which GeoZui3D will not allow the "current" value to fall.
M	Maximum value. This is an upper limit on the "current" value, above which GeoZui3D will not allow the "current" value to rise.

Examples

Where is the main window is currently situated:

gz posable get Window.main xyz -71.433716 -461.997955 -1085.000000

Rotate the main window into plan view:

gz posable set Window.main p 90

Keep the main window from zooming in too far:

gz posable set Window.main Ms 40

Keep the main window from zooming out too far:

gz posable set Window.main ms .01

Remove the limit we just set:

gz posable unset Window.main ms

List which objects are currently in the scene

gz posable list Object .Posable.Object.nonan_gutm .Posable.Object.r509_gutm .Posable.Object.ROV4_tube .Posable.Object.cropped509_img

Move an object up by 25 meters:

gz posable offset Object.nonan_gutm z 25

Move an object over a bit in x and y:

gz posable offset Object.nonan_gutm xy -15 30

Put the object back where it belongs:

eval "gz posable set Object.nonan_gutm xyz [gz posable get Object.nonan_gutm Hxyz]"

Exaggerate the height of an object by a factor of 4

gz posable substitute Object.nonan_gutm exaggerate; gz posable set Object.nonan_gutm s 4

Valid Posable tellObject Options

While posables do not directly respond to many commands through the "gz tellObject" message interface, they pass on any commands they do not understand on to their respective users (such as the corresponding object or window). As with any addressable object, "gz tellObject posable list" will enumerate the supported commands (in this case both the commands the posable supports, and those of the user object). The commands in the following table would all appear after "gz tellObject posable", where posable is the target of the command.

Posable Commands
attribute count	Returns the number of attributes that the posable can access in its user.
attribute index name	Returns the attribute index for the given name, or -1 if name is not a valid attribute. Note that different versions of GeoZui3D may have different index values for a given name, and some objects may even have different index values across object instances. Indexes are intended for use when an attribute is going to be accessed many times or when one doesn't care what the attribute is particularly (such as generic attribute editors).
attribute name index	Returns the attribute name for the given index.
attribute panel {show \| hide \| close}	Shows, hides, or closes the attribute panel associated with this posable.
*attribute value index-or-name* [value]**	If value is given, sets attribute reference by index-or-name to value. Otherwise, returns the value of the attribute. To force GeoZui3D to interpret a value to be set as a certain type, use a designator character and a colon before the value. Designator characters are as follows: Integer is 'i' or 'I'; Float is 'f', 'F', or '%'; String is 's', 'S', or '$'; Pointer is 'p', 'P', or '@'. For example, "attribute value index0 F:1.2" to set a value of 1.2 as a float, or "attribute value index0 $:1.2" to set a value of 1.2 as a string.
continuousChange [0 \| 1]	If passed 1, bumps up the count of requests to put the posable in a state of continuous change (if the posable is used by a window, that windows will not render in high-res). If passed 0, cancels such a request (although other requests may still cause the posable to be in a state of continuous change). This command returns the current state (after the change in state, if any).
objectType	Returns the type of the assocated object.
Shared Commands Among Objects
clutMode [$TEXTURE_COORD_POSABLE \| $TEXTURE_COORD_GEOREF \| $TEXTURE_COORD_NONE]	Sets the way in which the object associated with this posable handles cluts. If $TEXTURE_COORD_POSABLE, moving an object up and down has the effect that the same (x,y) position will cycle through the clut according to the z-value at that point at the time of rendering. If $TEXTURE_COORD_GEOREF, moving an object up and down will not appear to have any effect on the object in terms of color--the z-value used for the clut is the one that would have been valid if the object were not moved. The mode $TEXTURE_COORD_NONE, is generally not useful. This command returns the current mode (after the change in mode, if any).
delete	Deletes the object associated with this posable from the scene (also deletes the posable).
edit [0 \| 1]	If passed 1, allows the object's posable to display edit handles and be edited. If passed 0, disallows such editing. Returns the current editing state (after the change in state, if any).
hide	Hides the object associated with this posable.
info	Posts information about the object associated with this posable to the Information Frame.
reload	Reloads the object associated with this posable.
respondToPress [0 \| 1]	If passed 1, causes the associated object to respond to a mouse-button-1 press event as if it were a click event. If passed 0, reacts normally. Returns the current respondToPress state (after the change, if any).
respondToPress2 [-1 \| 0 \| 1]	If passed 1, causes the associated object to respond to a mouse-button-2 press event in such a way as it allows the current view to be "attached" to the object. If passed 0, the object will not be rendered for picking for the "attachment" behavior of the middle mouse button to work on it. If an object moves at all, it is automatically set to respond to mouse-button-2 events. Therefore, to keep a moving object from being "attachable", the respondToPress2 command must be passed something other than 0 or 1 (such as -1, which is stored internally as 255). Returns the current respondToPress state (after the change, if any).
show	Unhides the object associated with this posable.
wireframe [0 \| 1]	If passed 1, causes the object associated with this posable to render in wireframe mode. If passed 0, renders normally. Returns the current wireframe state (after the change, if any).
Gutm (.gutm) Commands
fuse	Fuses the associated GUTM with any other overlapping GUTM's in the scene.
getat x y	Returns the (interpolated) height at the passed x and y coordinates for the associated GUTM.
*highres [on \| size* \| off]**	Sets the size of the high-res zone (displayed during interaction) for the associated GUTM. The size is roughly the width of the high-res zone in number of pixels when viewing the GUTM in plan view. Using "on" or giving a size puts the rendering of all GUTMs into a mode where the high-res zone is used. Using "off" returns all GUTMs to using the rendering mode that does not use a high-res zone.
normals {precomputed \| onTheFly}	Causes the normals for all GUTMs to be calculated as specified. Precomputed normals can potentially speed interactive rendering, while onTheFly normals do not require any time to recalculate when changing height exaggeration.
restore	Restores all holes created by a prior fuse in the associated GUTM.
texture ensureBuilt	Makes sure that this GUTM's texture is built, so that there is no pause later to build the texture.
TextureCollection (.img) Commands
image activate index	Displays the image at index, loading it if necessary (indicies start with 0, and are in the order in which they appear in the .img file).
image deactivate index	Displays a wire-frame panel at index.
image nopyramid index	Hides the viewing frustum for the image at index
image pyramid index	Shows the viewing frustum for the image at index
image reload index	Displays the image at index after reloading it.
TextureScreen (.screen) Commands
loop [0 \| 1]	If 1 is passed or no argument is given, tells the associated screen to loop through its video upon reaching then end. If 0 is passed, the screen should stop updating upon reaching the end.
pause	Stop updating temporarily, and do not rewind.
play	Start or continue playing the video clip.
stop	Stop playing the video clip, and rewind. The screen retains the last frame shown before the stop command was executed.
Vip (.vip) Commands
truncateTail index	If rendering as a torpedo-shaped vehicle, only show index segments of tail (previous positions).
XYZStream (.sss) Commands
hidequad	Hides the quadtree visualization for the associated XYZStream.
pause	Pauses the insertion of new poits from disk.
showquad	Displays the quadtree visualization for the associated XYZStream.
unpause	Resumes the insertion of new poits from disk.

Wrappers

A wrapper has the interface of a posable without actually having any of its own position, orientation, or scale information. Wrappers are capable of opening conceptual "windows" into certain objects so that you can "peek" inside them as well as make changes. They do this by holding index information that is understood by the object to which they are attached. For instance, a wrapper could be attached to a .gdl (lines) object. As the index on the wrapper is changed, the position, orientation, and scale attributes reported by the wrapper are updated to reflect individual points within the .gdl object. If changes are made to an attribute of the wrapper, they are reflected in the object itself (allowing you to edit points that are not posables and would otherwise be inaccessible). Only certain objects support attachment by wrappers (in fact, only the .gdl and .gdp object types current support such attachment, although .gdt and .gutm objects are likely to in the future, if requested). Wrappers are created and manipulated through the "gz posable" commands explained in the Posables section, as well as the "gz tellObject" subcommands listed here.

Valid Wrapper tellObject Options

Wrappers support a number of commands through the "gz tellObject" message interface, in addition to the commands supported by Posables in general. As with any addressable object, "gz tellObject wrapper list" will enumerate these commands. The commands in the following table would all appear after "gz tellObject wrapper", where wrapper is the target of the command.

attachTo posable	Attaches this wrapper to the user of the passed posable. Generates an error if the user object does not support wrapper attachment.
*delete [dimension]*	Deletes the index at the current position in the passed dimension (dimension 0 is assumed if no dimension is given). Does not update the current index value (even if the value becomes invalid).
detachFrom posable	Detaches this wrapper from the user of the passed posable.
freeze	Delays notification of any changes in the wrapper index so that multiple indices can be changed atomically. Notification is resumed using the "thaw" subcommand.
*index dimensions [numDimensions]*	If numDimensions is present, sets the number of index dimensions to this value. If no argument is given, returns the number of dimensions in use.
*index [dimension] get [type]*	Returns the value at the passed dimension, (or the type if "type" is specified: "String", "Integer", or "Float"). If no dimension is given, dimension 0 is assumed.
*index [dimension] set value* [as {String \| Integer \| Float}]**	Sets the value at the passed dimension to value. If no dimension is given, dimension 0 is assumed. If no type is given, the type is assumed to remain the same as before (all uninitialized indecies start as type Integer with value 0).
*insert [after] [dimension]*	Inserts an index at the current position in the passed dimension (dimension 0 is assumed if no dimension is given). If "after" is used, the index is inserted after the current position; otherwise the index is inserted before the current position. Does not update the current index value.
thaw	Resumes notification wrapper index changes after a freeze.

Composite Objects

A composite object is an aggregate object that combine the position, orientation, and/or scale information from multiple posables, and store the result in its own posable (we refer to composite objects as frame-of-reference operations or FoR-ops in some of our papers). A composite object can "manage" its constituent objects in an essentially unordered list, updating the result posable whenever one of its "managed" posables changes. Since the result of composite objects is itself a posable, this result can be managed by other composite objects, and it can be coupled-to by windows and other objects. Currently, the only two composite objects that exist are the AveragingOverview (.avov), the ProximityHighlighter (.proximity), and the Boundary (.boundary). The result posable of an AveragingOverview maintains a position that is at the center of the box bounding the managed posables, an orientation that is the average of the managed posables, and a scale that allows an attached window to contain all of the managed posable positions in it's central region. The ProximityHighlighter does the same thing for only the two closest managed posables, and generates events as proximity thresholds are crossed. The Boundary object does not update its pose, but does generate an event whenever a managed posable crosses the plane passing through the position of the Boundary pose, where the plane is normal to the heading/pitch/roll of the Boundary pose. Composite Objects are loaded like any other object (although the file formats are not yet documented).

Valid Composite Object tellObject Options

Composite objects support a number of commands through the "gz tellObject" message interface, in addition to the commands supported by Objects in general. As with any addressable object, "gz tellObject compositeObject list" will enumerate these commands. The commands in the following table would all appear after "gz tellObject compositeObject", where compositeObject is the target of the command.

Shared Commands Among Composite Objects
listManaged	Returns a Tcl list containing the addresses of each object managed by this composite object.
manage posable	Adds the passed posable to the list of this composite object's managed objects.
numManaging	Returns the number of objects currently managed by this composite object.
relinquish posable	Removes the passed posable from the list of this composite object's managed objects.
replace oldPosable newPosable	Replaces oldPosable with newPosable in the list of this composite object's managed objects.
Boundary Commands
*heightRatio [height]*	If passed a height, sets the ratio of the displayed height of the boundary to its width. The width is controlled by the Boundary posable's scale. Returns the current heightRatio (after the change in height, if any).
*inWhen [not] above [object]*	If passed an object other than an empty string {}, uses that objects as an additional lower boundary (or upper boundary if "not" is used). If an empty string is passed, any existing object boundary is removed. In either case, the normal planar portion of the boundary is always in effect. Returns the current object (after the change, if any).
regionOf posable	Returns "in" if the passed posable is "inside" the boundary (toward the Boundary posable's heading from the plane), or "out" if it is "outside" the boundary (in the opposite direction of the heaing).
ProximityHighlighter Commands
debug [0 \| 1]	If passed 1, causes this ProximityHighlighter to display its bounding region regardless of its alert (proximity) status. If passed 0, only draws the bounding region when two of its managed objects are in proximity or close-proximity (determined by the threshold below). Returns the current debug state (after the change in debug state, if any).
*threshold [distance]*	If passed a distance, sets the proximity threshold to this distance. If any two managed objects are within this threshold, they are considered to be in proximity. If they are within half of this threshold, they are considere to be in close-proximity. Returns the current threshold (after the change in threshold, if any).

Time

GeoZui3D is aware of the passage of time, and therefore supports synchronized playback of temporally registered data or animations. The term temporally registered simply means that an object has a start time and end time in which it is valid, and may have different states at different times in between. One example would be a special type of GUTM that changes depths with the tides over the course of a few days. Another example would be a DataLines (.gdl) object with an attribute treated as time in conjuction with a PathAnimator--together the DataLines object and the PathAnimator can be used to move a vehicle object to replay the progress of a recorded journey, or simulate the progress of a planed journey. GeoZui3D provides mechanisms for speeding up and slowing down the internal notion of time passing, as well as playing it in reverse and stopping it. The Time Control Panel provides the visual infterface to cotrolling GeoZiu3D time, and in fact makes use of the scripting commands described below.

Selected gztime Subcommands

A special command called "gztime" has been created to provide a way to control the internal notion of the flow of time in GeoZui3D. Each of the subcommands described below must always be preceded by "gztime", for example "gztime play" or "gztime multscale 5".

multscale factor	Speeds up time by the given factor. Negative values reverse the flow of time, and values between 0 and 1 slow the flow of time, while values greater than 1 speed the flow of time. A factor of 0 stops time.
play	Sets the flow of time to normal (1 second in GeoZui3D equals one second on the wall clock).
rev	Reverses the flow of GeoZui3D time (equivalent to multscale -1).
stop	Halts the flow of GeoZui3D time (equivalent to multscale 0).
timescale time_fraction	Sets the current GeoZui3D time to the time corresponding to time_fraction on the Time Control Panel slider. This slider is usually set such that it starts at the earliest time-bound for any loaded object (corresponding to a time_fraction of 0) and ends at the latest time-bound for an object (corresponding to 1).

Animators

An animator is something that incrementally transforms a "resultant" posable's components, potentially using information from operand posables and from user input. Animator support is minimal at this time (there is only one kind of animator, and there is no mechanism for controlling how user input is interpreted). The animators types available currently are the ImitatingAnimator, the PathAnimator, and the VectorAnimator. An ImitatingAnimator animates a posable toward a "base" posable, potentially modified by an "offset" posable. The PathAnimator updates the index of a wrapper in one dimension, allowing for the animation of a posables along predetermined paths (an offset posable is allowed to provide a way of adding simple deviations from the path). Animation under both types occurs at a constant speed, but this speed is potentially controlled through the up- and down-arrow keys, the joystick, or through the "gz tellObject" subcommand. The VectorAnimator updates a posable in the direction of a "direction" posable's position (as a vector--if the vector is all zeros, the heading and pitch of the posable are used to determine the vector), at a speed controlled by a "speed" posable's scale.

Animator Subcommand Options

The "animator" subcommand accepts addresses without the leading ".Animator" prefix. There are several options to the "animator" subcommand, each of which is described along with its respective syntax below. The possible values of type are described in the next subsection. The possible values of animator-type are under the gz animator type description.

gz animator create parent new-name animator-type [resultant {operand}]*	Creates a new animator named new-name under the address parent (which may or may not be in the .Animator hierarchy) with a mechanism of type animator-type. If a resultant and/or operands are given, the new animator is assigned these posables appropriately. The only way to change the resultant or operands after creation is through the "gz tellObject" command.
gz animator delete animator	Deletes animator, terminating any associated animation.
*gz animator list [animator]*	Returns a list of fully-qualified (from the root Animator) addresses that are children of animator. If no animator argument is given, returns the children of "Animator".
gz animator types	Returns a list of animator mechanisms. Currently, the types available are ImitatingAnimator, PathAnimator, and VectorAnimator.

Examples

List the types of animators available:

gz animator types ImitatingAnimator PathAnimator VectorAnimator

Create an animator that moves a subwindow toward the origin of an object:

gz animator create .Animator myAnimator ImitatingAnimator Window.sub0 Object.r509_gutm

Cause the animator to actually start moving the object:

gz tellObject .Animator.myAnimator effect xyz

List the animators under .Animator:

gz animator list .Animator.myAnimator

Delete our animator:

gz animator delete myAnimator .Animator.myAnimator

Valid Animator tellObject Options

Animators support a number of commands through the "gz tellObject" message interface. As with any addressable object, "gz tellObject animator list" will enumerate these commands. The commands in the following table would all appear after "gz tellObject animator", where animator is the target of the command.

Shared Commands
activate [0 \| 1]	If 1 is passed in or no arguments are given, causes the animator to take effect. If 0 is passed, causes the animator to suspend its normal operation.
animate	Causes this animator to execute a cycle of animation.
effect type	Sets the attributes that this animator should effect in the resultant. The type is a subset of the Posable Subcommand Types. Currently, this subset consists of the lettes in the following string: "xyzhprs" (X, Y, Z, heading, pitch, roll, and scale).
operand add posable	Adds posable to the list of operands. Some animators have maximum operand capacities (the ImitatingAnimator only supports up to two operands, for instace). If adding an operand would exceed such a capacity, an error is generated.
*operand remove {at index* \| old-pose}**	Removes the specified posable from the list of operands. No error is generated if the index is invalid or the posable is not an operand of this animator.
operand replace {at index \| old-pose} new-pose	Replaces the specified posable in the list of operands with new-pose. No error is generated if the index is invalid or old-pose is not an operand of this animator.
resultant posable	Sets the resultant for the animator to posable
*speed {value* \| usage}**	Sets the speed for the animator to value. Until time streams are fully implemented in GeoZui3D, value is unitless and may mean different speeds for different machines/CPU-loads. Some animators support additional syntax for the speed keyword. To discover such syntax, one can use the "usage" keyword.
ImitatingAnimator Commands
base posable	Sets the base operand (index 0) for the animator to posable
offset posable	Sets the offset operand (index 1) for the animator to posable
scalespeed {0 \| 1}	Determines if the translation speed should be scaled by the current scale of the result posable.
PathAnimator Commands
*advanceLine [numLines]*	Advances the wrapper target by numLines lines and begins tracing the line at index 0. If using a timeAttribute, resets the time bounds appropriately and resets GeoZui3D time to the beginning of those bounds.
*headingAttribute name [attribute* \| -]**	Without an argument after "name", returns the name of the attribute being used in the wrapper target as the object of interpolation with respect to heading. If attribute is given, sets the name of the attribute and causes the heading to take on the interpolated value of that attribute. If the '-' symbol is given, resets the name of the attribute and calculates the heading based on the difference between the current position and the previous position (this is the default behavior).
keyboard [0 \| 1]	Tells the animator whether or not it should respond to the arrow keys for controlling speed. If 1 is passed, it responds; if 0 is passed, it ignores keyboard input. If no arguments are given, the current state is returned.
offset posable	Sets the offset operand (index 1) for the animator to posable
*pitchAttribute name [attribute* \| -]**	Without an argument after "name", returns the name of the attribute being used in the wrapper target as the object of interpolation with respect to pitch. If attribute is given, sets the name of the attribute and causes the pitch to take on the interpolated value of that attribute. If the '-' symbol is given, resets the name of the attribute and calculates the pitch based on the difference between the current position and the previous position (this is the default behavior).
scaleAttribute asExponent [0 \| 1]	Without an argument after "asExponent", returns the current setting. If '1' is given, treats scale attribute data values as base-2 exponents. This matches well with the "AS_EXPONENTIAL" designation in GeoData files. If '0' is given, treats scale attribute data values literally, without exponential transformation (this is the default behavior).
scaleAttribute invert [0 \| 1]	Without an argument after "invert", returns the current setting. If '1' is given, treats scale attribute data values as inverted (1/n). If both "asExponent" and "invert" are set to 1, values are exponentiated first, then inverted. Inversion is necessary if a window is being coupled to a non-window posable, and this posable is the target of the PathAnimator. If '0' is given, treats scale attribute data values literally, without inversion (this is the default behavior).
*scaleAttribute name [attribute* \| -]**	Without an argument after "name", returns the name of the attribute being used in the wrapper target as the object of interpolation with respect to scale. If attribute is given, sets the name of the attribute and causes the scale to take on the interpolated value of that attribute. If the '-' symbol is given, resets the name of the attribute and leaves scale unchanged (this is the default behavior).
*speed {usage \| {[idle \| negativeFactor] [value]}}*	Sets the speed according to the arguments passed (or returns the usage if "usage" is passed as an argument). "idle" and "negativeFactor" control the effects that the joystick has on speed, idle controlling what speed should be used when the joystick is neutral, and negativeFactor controlling what factor should be multiplied by the speed when the joystick is pulled backward. If neither "idle" nor "negativeFactor" are used, the base speed is effected or returned. The current associated value in use is returned (unless "usage" is the argument).
stayabove object-pose z-offset	Causes this animator to force the resultant to be at least z-offset meters above object-pose at the particular (x, y) position the resultant sits at each moment. object-pose must be the address for the posable of an Object (generally a GUTM).
*timeAttribute name [attribute* \| -]**	Without an argument after "name", returns the name of the attribute being used in the wrapper target as the object of interpolation with respect to time. If attribute is given, sets the name of the attribute and advances the wrapper according to the progress of GeoZui3D time. If the '-' symbol is given, resets the name of the attribute and advances the wrapper whenever GeoZui3D is idle (this is the default behavior).
*timeAttribute offset [startingTime* \| now]**	Without an argument after "offset", returns the time offset being used between the current time and the values used in the time attribute. The offset is given in floating-point number of seconds. If startingTime is given, sets the time offset to this value (given as number of seconds since the beginning of 1970). If "now" is given, sets the time offset to the current time (useful when the attribute is zero-based).
*timeAttribute scale [timeScale]*	Without an argument after "scale", returns the scale factor being used between the current speed of the GeoZui3D second and the values used in the time attribute. If timeScale is given, sets the time scale factor to this value.
wrapper posable	Sets the wrapper operand (index 0) for the animator to posable
VectorAnimator Commands
direction posable	Sets the direction operand (index 0) for the animator to posable
*speed {usage \| posable}*	Sets the speed operand (index 1) for the animator to posable (or returns the usage if "usage" is passed as an argument).

Events, Event Mediators, Interactors, and Event Handlers

GeoZui3D uses the concept of an event to handle both user input (key press, mouse motion, joystick motion, etc.) and internal events (posable has changed, scene height-exaggeration has changed, etc.). Internal events can be listed under by exploring the ".Event" hierarchy ("gz address list .Event"), while user-input events are only documented here. Events are processed through a number of different "streams" which we call event mediators. Event mediators maintain an ordered list of items that respond to events. The items that respond to events are called interactors. When an event mediator is triggered on an event, the mediator first gives the event to the interactor on the top of its stack. That interactor can then ignore or handle the event, and tell the mediator one of three actions to take: 1) Pass the event through (to the next interactor on the stack), 2) Sink the event (keep the event from being handled by any other interactor on the stack), or 3) Remove the interactor and sink the event. Event mediators are considered to be interactors, and therefore can be put on the stacks of other event mediators.

To make these concepts clearer, we use an illustration based on a stream metaphor. Consider that GeoZui3D has a main river of events flowing through it regularly (.EventMediator.internal). Regular interactors act like filters on this river that catch certain kinds of events, and each branch of the river either remerges with its source or ends abruptly at a black drain (sink). The oneEyedCursor handles mouse motion events, but then allows them to continue down the river. The toolPallette handles certain keyboard key-presses, placing other interactors at the source of the river and keeping the particular key-press events from continuing downstream. Every event mediator has a priority mediator, which is like a small rivlet that filters certain events before they are allowed to continue (only the priority mediator for .EventMediator.internal is shown here). This is useful for catching or transforming events before the regular interactors have a chance to see them. For instance, .Interactor.doubleClick looks for a button#Down followed by a button#Up without much mouseMotion in between. Once it encounters this sequence, it generates a click event, and modifies the next button#Down and button#Up event indicating that a double-click might be coming.

Near the end of the main river, the event stream is essentially diverted to .EventMediator.Window. This river has a branch for each window that is present at any given time (.EventMediator.Window.main is always present). Each window has the same set of core interactors set up on it, as shown here for .EventMediator.Window.main. The window itself is generally the last interactor on the list (such as .Interactor.Window.main), to handle special keys specific to the window, for instance.

Interactors can trigger new events, and these events do not necessarily start in the main river. For an example, consider .EventMediator.joystick. When it encounters an idle event (from being an interactor on .EventMediator.internal), it generates one or more joystick events in its own event stream--like a mountain spring. Initially, .EventMediator.joystick has no interactors in its list, but interactors can be added to catch joystick events. Certain other interactors may trigger events on .EventMediator.internal or on .EventMediator.user (for higher-level and user-created events).

Sometimes it is useful for an interactor to have a partial presence at more than one place on the event stream. This is the case for pointHandle, which is the interactor that allows you to edit the positions and orientations of points, lines, and objects. The pointHandle normally gets pushed at the top of the stream when a mouse button in pressed on one of the pointHandle's widgets, but it needs to respond to keyboard and idle events even when the mouse button has not been pressed. Its keyGrabber tentacle allows these events to be passed on to the pointHandle even when pointHandle is not on the event stream. Duplicate events are avoided by keeping track of the serial number of the event.

Finally, we introduce the concept of an event handler. An event handler is simply an interactor that is not integrated into GeoZui3D. Handlers can be created to invoke scripts for handling certain events, and they may be placed on any number of event mediators.

Event Subcommand Options

The "event" subcommands accept addresses without the leading prefix appropriate for each subcommand. For instance, when using the "event handler" subcommand, the ".Interactor.Handler" prefix is assumed. There are several options to the "event" subcommand, each of which is described along with its respective syntax below. Additional usage details are also described in sections that follow.

gz event create name	Creates a new event named name under the address .Event. Returns the address of the new event.
gz event delete event	Deletes event if it was created with the "gz event create" command (otherwise produces an error). This command assumes the .Event prefix.
gz event handler create name [for event] script	Creates a new event handler named name under the address .Interactor.Handler. When the handler encounters an event, it invokes script with information as detailed in the Event Formatting section. If the "for event" clause is present, the handler is pre-tuned to only invoking the script on encountering event. A list of system events can be found in the Event Types section. Returns the address of the new handler.
gz event handler delete handler	Deletes handler, removing it from the purview of any event mediators. This command assumes the .Interactor.Handler prefix.
gz event mediator create name	Creates a new event mediator named name under the address .EventMediator. Returns the address of the new event mediator.
gz event mediator delete mediator	Deletes event if it was created with the "gz event mediator create" command (otherwise produces an error). This command assumes the .EventMediator prefix.
gz event tentacle create name	Creates a new event tentacle named name under the address .Interactor. Returns the address of the new tentacle.
gz event tentacle delete tentacle	Deletes tentacle. This command assumes the .Interactor prefix.

Valid Event-related tellObject Options

While all interactors support support the "gz tellObject" message interface, only certain interactors and event mediators support any commands other than "list" ("gz tellObject interactor list"). The commands in the following table would all appear after "gz tellObject interactor", where interactor is the target of the command.

Event Mediator Commands
listOrder	Returns a Tcl list containing the addresses of each interactor on the event mediator's list, starting from the front of the stream and moving toward the sink (represented as "{}"). Unnamed interactors may also appear as "{}".
moveToTop interactor	Removes the passed interactor from the event mediator's list and pushes it back to the front of the list.
pop interactor	Removes the passed interactor from the front of the event mediator's list (only if it is at the front of the list).
push interactor	Pushes the passed interactor to the front of the event mediator's list. This interactor will then be the first to receive events on this mediator (after anything on the priority mediator, of course).
remove interactor	Removes the passed interactor from the event mediator's list regardless of its position in the list.
*trigger event* [type-flag [value [type-flag2 modifier]]]**	Triggers the passed event in this event mediator. If a type-flag is given (a dash followed by a type character, such as "-i" or "-a"), the %t field is set accordingly. If a value is given, the %V field is set according to the type. If type-flag2 and modifier, the %M field is set according to this information.
Joystick Event Mediator Commands
continuouslyGenerate axis [0 \| 1]	If 1 is passed in, causes this joystick event mediator to generate joystick events even when no change has occurred in the joystick state. If 0 is passed in, joystick events are only generated when there is a change. Returns the current setting (after the change, if any).
Tentacle Commands
filter {set \| add \| remove} basic-event	Modifies the filter for the tentacle, with the effect of passing the events specified in the filter on to the owner. Only basic user-input events can be specified.
ignore serial-number	Informs the tentacle that it should not pass any events along to its owner that have serial numbers less than or equal to the passed serial-number. The serial number of an event can be obtained using the %S value character.
owner interactor	Sets the owner of this tentacle. The owner is the recipient of any events that the filter specifies. Defaults to looking in the .Interactor hierarchy for the interactor.

Event Formatting

Scripts that are registered with handlers at creation can contain special sequences of characters to allow information about the event being handled to be inserted into the script before it is run. The special sequences all begin with the percent charcter (%), and are filled in a way similar to printf in C/C++ or the event bindings in Tcl (meaning unrecognized character sequences are passed through without change). After the '%' character, there is an optional "type" character and one or more "value" characters.

Type Characters

i	Interpret value as an integer
l	Interpret value as a long integer
d	Interpret value as a double (floating point)
a	Interpret value as a GeoZui3D address (such as .Posable.Window.main)
s	Interpret value as a string
p	Interpret value as a pointer (using @-hex notation, such as "@1c35b12").

Value Characters

Substitute the address of the event mediator in which this event was triggered.

Treat the primary value (usually accessed using %V or %J) as an event information record, and use the next character to determine what should be substituted in. For instance "%IS" would substitute the serial number of an event structure passed as the primary value. "%II" or anything nested even deeper is not allowed.

Substitute a piece of information from the primary value of the event, interpreted as joystick information. Must be immediately followed by one of the strings of characters below (to form a string like "%JA2").

A#	Substitute the value of axis #, where # is a number between 1 and 9. Values will be between -32768 and 32767. If # is not present (some other character is present than 1 through 9), then substitue the number of supported axes instead (depends on the joystick).
B#	Substitute the value of button #, where # is a number between 1 and 9. Values will be 1 if the button is depressed and 0 otherwised. If # is not present, then substitue the number of supported buttons instead (depends on the joystick).
H#	Substitute the value of hat #, where # is a number between 1 and 9. Values will be between 0 and 12, skipping 5, 7, 10, and 11. Centered is 0, up is 1, right is 2, down is 4, and left is 8. Combination directions simply add values together. If # is not present, then substitue the number of supported hats instead (depends on the joystick).

Substitute the "modifier" value associate with the event.

Substitute the number of "extra" fields that are valid in the event structure (accessed by %0 through %9).

Substitute the serial number of the event. Each event has a unique integer associated with it so that similar events can be distinguished, or stored events can be ordered.

Substitute the name (major type) of the event. System types are listed in the Event Types section.

Substitute the type (minor type) of the event's values. Returns one of the type characters or the empty list: "{}". This is useful for learning what type another value has been substituted as when a type was unspecified.

Substitute the primary value associated with the event (for instance, the key pressed for a keyPress event).

Substitute a 1 if the event was generated internally, or a 0 if the event was generated due to user input (keyboard, mouse).

Substitute the address of the window in which this event was generated. An empty list is substituted if no window information is present.

Substitute the x value associate with the event (usually in window coordinates).

Substitute the y value associate with the event (usually in window coordinates).

Substitute the z value associate with the event (usually in window coordinates).

Substitute the value of the "extra" field of the event at index #, where # is a number between 0 and 9.

Substitute a single '%' symbol.

Event Types

There are two classes of events: user-input and internal. Within the class of user-input events there are basic user-input events from the keyboard and mouse, and joystick user-input events. Within the class of internal events, there are those that exist from the initialization of GeoZui3D, and those that are created during a GeoZui3D session (including events created by the user). We list each of the user-input and initial internal events below, indicating what fields contain useful information using the special character sequences outlined in Event Formatting (All events support %E, %S, %T, %t, and %v).

Basic User-Input Event Types

All of these events are triggered in .EventMediator.internal.

idle	%t yields {}	Triggered by Tcl whenever the Tcl interpreter is not processing anything else.
keyDown, keyUp	%t yields i (integer) %M, %V, %W, %X, %Y	Triggered whenever a keyboard key is pressed, released. %V yields the chacter ASCII value (or a keysym), while %M yields a number indicating the state of the modifier keys such as shift and alt.
mouse#Down, mouse#Up	%t yields i (integer) %M, %V, %W, %X, %Y	Triggered whenever mouse button # is pressed, released, where # is between 1 and 3. %V yields the number of the button pressed, while %M yields a number indicating the state of the modifier keys such as shift and alt.
mouseEnter, mouseLeave, mouseMotion	%t yields i (integer) %M, %W, %X, %Y	Triggered whenever the mouse enters a window, leaves a window, moves within a window. %M yields a number indicating the state of the modifier keys such as shift and alt.

Joystick User-Input Event Types

All of these events are triggered in .EventMediator.joystick.

joystick#Axis	%t yields {} %J*,	Triggered whenever the value of joystick axis # changes (the joystick is pushed in some direction or a throttle is moved), where # is a number between 1 and 4, or the string "Other". All joystick fields are valid.
joystick#Down, joystick#Up	%t yields {} %J*,	Triggered whenever the button # is pressed, released, where # is a number between 1 and 4, or the string "Other". All joystick fields are valid.
joystickHat	%t yields {} %J*,	Triggered whenever a joystick hat is moved. All joystick fields are valid.

Initial Internal Event Types

Internal event types can be listed by invoking "gz address list .Event" at any time. Unless otherwise noted, all of these events are triggered in .EventMediator.internal.

addObject	%t yields {}	Triggered when an object is added to the scene, either by loading it or creating it on the fly.
beginIdle	%t yields {}	Triggered at the beginning of an idle cycle (before the "idle" event is triggered).
boundaryCrossedIn	%t yields a (address) %M, %V	Triggered in .EventMediator.user when a posable monitored by a Boundary (.boundary object) crosses the plane defined by that Boundary (on the side in which the normal vector is pointing). %V yields the address of the boundary, while %M yields the address of the posable that crossed the boundary.
boundaryCrossedOut	%t yields a (address) %M, %V	Triggered in .EventMediator.user when a posable monitored by a Boundary (.boundary object) crosses the plane defined by that Boundary (on the opposite side of the direction in which the normal vector is pointing). %V yields the address of the boundary, while %M yields the address of the posable that crossed the boundary.
break	%t yields {}	Triggered at break conditions (usually the user hitting the escape key while some tool is in effect).
click	%t yields p (pointer) %IE, %IM, %IS, %IT, %It, %IV, %Iv, %IW, %IX, %IY	Triggered when a mouse button is pressed and depressed without moving the mouse too much (when the user clicks a mouse button). Most information about the event is obtained through %I*, since the primary value (usually obtaned through %V) is actually a pointer to the event information structure for the mouse#Up event that caused the click to be triggered.
clutChanged	%t yields p (pointer) %V	Triggered when the bounds of a clut change (minimum or maximum height value in the clut). %V yields a pointer to the particular texture, which is of little use currently. In the future, cluts and textures may become addressable items, in which case %V will likely yield an address rather than a pointer.
doubleClick	%t yields p (pointer) %IE, %IM, %IS, %IT, %It, %IV, %Iv, %IW, %IX, %IY	Triggered when a mouse button is pressed and depressed twice without moving the mouse too much (when the user clicks a mouse button twice). Most information about the event is obtained through %I*, since the primary value (usually obtaned through %V) is actually a pointer to the event information structure for the mouse#Up event that caused the doubleClick to be triggered.
endIdle	%t yields {}	Triggered at the end of an idle cycle (after the "idle" event is triggered and handled).
imitationStabilized	%t yields a (address) %M, %V	Triggered in .EventMediator.user when an ImitatingAnimator was animating a posable, but did not change that posable in the last cycle (because it reached its target). %V yields the address of the animator, while %M yields the address of the resultant posable that was being moved.
inCloseProximity	%t yields a (address) %M, %V	Triggered in .EventMediator.user when two posables monitored by a ProximityHighlighter (.proximity object) get within one-half of that ProximityHighlighter's threshold. %M and %V yield the addresses of the two posables in close proximity (%V is always an object that was added to the managed list of the ProximityHighlighter before %M was).
inProximity	%t yields a (address) %M, %V	Triggered in .EventMediator.user when two posables monitored by a ProximityHighlighter (.proximity object) get within that ProximityHighlighter's threshold. %M and %V yield the addresses of the two posables in proximity (%V is always an object that was added to the managed list of the ProximityHighlighter before %M was).
interactorDestroyed	%t yields a (address) %V	Triggered in .EventMediator.interactor when an interactor is in the process of being destroyed (deleted). %V yields the address of the disappearing interactor.
interpolationBounds	%t yields a (address) %iM, %V	Triggered in .EventMediator.user whenever a wrapper's index goes outside the bounds of the object it is attached to, where the object provides interpolation support (such as .gdl objects). %V yields the address of the offending wrapper, while %iM yields the integer "name" of the bounds reached. For instance, with a .gdl file, %iM is 0 when there are no more points on a line, but there are more lines, and %iM is 2 when there are no more lines left (triggered when the number of points are exceeded on the last line, as opposed to when the number of lines is exceeded).
objectChanged	%t yields {}	Triggered whenever an object changes in the way it will be rendered. Causes a redisplay at the next idle cycle.
objectPoseChanged	%t yields a (address) %iM, %V	Triggered in .EventMediator.user whenever an object's position, orientation, or scale changes for any reason. %V yields the address of the posable that was changed. %iM yields an integer bitfield with information about what changed.
objectSelected	%t yields a (address) %iM, %V	Triggered in .EventMediator.user whenever an object is selected by a user click. %V yields the address of the selected object, while %iM yields the index of the selected piece of the object (or -1 if no specific piece was selected).
objectStabilized	%t yields a (address) %V	Triggered in .EventMediator.user whenever an object's position, orientation, or scale was continuously changing but has now finished changing. %V yields the address of the posable that had been changing.
outOfCloseProximity	%t yields a (address) %M, %V	Triggered in .EventMediator.user when two posables monitored by a ProximityHighlighter (.proximity object) get further away from each other than one-half of that ProximityHighlighter's threshold. %M and %V yield the addresses of the two posables that have left proximity (%V is always an object that was added to the managed list of the ProximityHighlighter before %M was).
outOfProximity	%t yields a (address) %M, %V	Triggered in .EventMediator.user when two posables monitored by a ProximityHighlighter (.proximity object) get further away from each other than ProximityHighlighter's threshold. %M and %V yield the addresses of the two posables that have left proximity (%V is always an object that was added to the managed list of the ProximityHighlighter before %M was).
posableDeleted	%t yields a (address) %V	Triggered when a posable is in the process of being destroyed (deleted). %V yields the address of the disappearing posable.
sceneChanged	%t yields {}	Triggered whenever something effects the way more than one object displays in at least one window (such as changing the light direction or clearing the scene). Causes an immediate redisplay.
sceneReset	%t yields {}	Triggered whenever the scene list becomes empty.
spaceWarped	%t yields {}	Triggered whenever height exaggeration is changed.
textureScreen	%t yields s (string) %M, %aV	Triggered in .EventMediator.user whenever the state of a .screen object has changed. %aV yields the address of the selected object, while %M yields the "play", "stop", or "pause".
viewChanged	%t yields l (long) %M	Triggered in a window event mediator whenever a its view has changed in some way. Causes a redisplay in the parent window at the next idle cycle, and causes the position and heading information about the window to be updated in the Tcl interface. %M yields an integer bitfield with information about what changed. %pV holds potentially useful information for future expansion (not useful yet).
viewStabilized	%t yields {}	Triggered in a window event mediator whenever its view is no longer continuously changing. %pV holds potentially useful information for future expansion (not useful yet).
windowChanged	%t yields {}	Triggered in parent window event mediator whenever a subwindow changes its view in some way. Causes a redisplay in the parent window at the next idle cycle.

Projections

A GeoZui3D projection is function that transforms between latitude-longitude coordinates and euclidean coordinates (XYZ meters) under certain assumptions. Currently, three broad categories of transformations are supported: Mercator, polar, and UTM. Projections are used by Conversion Grids to perform their conversions, but they also can be used to perform conversions within the scripting interface. New projections can be specified, which can in turn be used by Conversion Grids or other scripts. (Note: the names of projections are all upper-case so as to work properly with Conversion Grids. If a new projection is made, it should have a name that is completely upper-case if it is to be used with a Conversion Grid.)

Projection Subcommand Options

The "projection" subcommand accepts addresses without the leading ".PROJECTION" prefix. There are several options to the "projection" subcommand, each of which is described along with its respective syntax below. Some commands require that "gz projection init" be called before they can be used effectively.

gz projection apply projection longitude latitude	Applies projection to (longitude, latitude), yielding an (easting, northing) pair as a Tcl (space-delimited) list.
gz projection create parent new-name type center-long cetner-lat	Creates a new projection named new-name under the address parent (which may or may not be in the .PROJECTION hierarchy). The new projection uses the assumptions of type, which must be one of "UTM", "Mercator", or "Polar". center-long and center-lat are the center latitude and longitude of the projection.
gz projection delete projection	Deletes projection. An error is generated if projection is one of the built-in (read-only) projections.
gz projection init	Populates the .PROJECTION hierarchy. The .PROJECTION hierarchy is originally empty due to the extra space used and the time resources required to create it.
gz projection invert projection easting northing	Applies the inverse of projection to (easting, northing), yielding a (longitude, latitude) pair as a Tcl (space-delimited) list.
*gz projection list [projection]*	Returns a list of fully-qualified (from the root .PROJECTION) addresses that are children of projection. If no projection argument is given, returns the children of ".PROJECTION". This command requires that some other projection command has been called first (such as "gz projection init") at some point since GeoZui3D was last launched.

Examples

List the types of animators available:

gz projection init; gz projection list .PROJECTION.IDENTITY .PROJECTION.UTM .PROJECTION.MERCATOR .PROJECTION.POLAR

Apply a projection:

gz projection apply UTM.ZONE32 0 60 -961.400395 6685590.887944

Invert a projection:

gz projection invert UTM.ZONE32 -961.400395 6685590.887944 -0.000014 60.000000

Create a projection:

gz projection create MERCATOR NORTHWEST Mercator -60 45 .PROJECTION.MERCATOR.NORTHWEST

Delete our projection:

gz projection delete MERCATOR.NORTHWEST

currentProjection	String holding the name of the projection under which GeoZui3D is operating. This is set automatically when an object with projection information is loaded. If no projection is set, the value of this string is "<unknown>"
dominantEye	Controls which eye the one-eyed cursor is displayed in (0 is left, 1 is right).
drewLowRes	This is set to 0 if a redisplay is in progress, and 1 otherwise.
GeoZuiVersion	The floating point number representing the current version of GeoZui3D (read-only).
GeoZuiDescriptor	A read-only string with information about the current build (empty for a normal distribution).
highResMutexHolder	If a window is currently drawing in high-res, this variable holds a value that is unique to that window. Only one window can draw in high-res at a time. If no window is currently drawing in high-res, this variable's value is 0.
interactivityHint	A number between 0.0 and 1.0 indicating what balance between resolution and interactivity GeoZui3D should try to achieve. A value of 0.0 gives resolution the highest precedence during interaction, while a value of 1.0 gives interactivity the highest precedence. Currently, the variable is only recognized by GUTM objects.
numEditedObjects	The number of objects that have been edited but not saved (read-only).
oneEyedFlag	Controls whether or not the one-eyed cursor is enabled (0 is off, 1 is on).
recorderResolution	Specifies the resolution at which the recorder synchronizes (in milliseconds). Higher resolutions (smaller values for recorderResolution) make for a larger files, but are more flexible at playback time. Slower machines may not respect high resolutions at record time.
recordingState	Specifies whether or not GeoZui3D is currently recording (0 is off, 1 is recording).
stereoflag	Controls stereo mode (-1 is off, 1 is on).
subWindowCount	Usually holds the number of subwindows created since GeoZui3D was launched.
toglPath	An array that holds the Tcl/Tk path for a given 3D rendering window. For example, $toglPath(main) and $toglPath(sub0) would usually return .glwindow and .sub0.innards.togl, respectively (these can be used for the commands described in the next section of this page).
translateRate	Determines the speed at which translation occurs using the middle mouse button. The speed is given as a percentage of the distance to the selected location covered roughly every 1/25th of a second. The default value is 25. A value of 100 corresponds to instantaneous motion, while a value of 0 corresponds to no movement.
widgetCompass	Determines whether or not the compass appears on the widgets (0 is off, 1 is on).
widgetHScale	Determines whether or not the horizontal scale appears on the widgets (0 is off, 1 is on).
widgetPickHeight	Sets the maximum y-distance a mouse-click can be from a widget component and still activate that component. Defaults to 1.5.
widgetPickWidth	Sets the maximum x-distance a mouse-click can be from a widget component and still activate that component. Defaults to 1.5.
widgetVisible	Determines whether or not the widgets are visible (-1 is off, 1 is on).
widgetVScale	Determines whether or not the vertical scale appears on the widgets (0 is off, 1 is on).
xPlacement	An array that holds the x coordinate of a given window. For example, $xPlacement(main) or $xPlacement(sub1).
xSize	An array that holds the width of a given window. For example, $xSize(main) or $xSize(sub1).
yPlacement	An array that holds the y coordinate of a given window. For example, $yPlacement(main) or $yPlacement(sub1).
ySize	An array that holds the height of a given window. For example, $ySize(main) or $ySize(sub1).
zoomInRate	Determines the rate at which zooming in occurs using the middle mouse button. The rate is given as a percentage zoom factor, applied roughly every 1/25th of a second. The default value is 8. A value of 0 corresponds to no zooming, while a value of 40 causes extremely fast zooming.
zoomInterface	Selects which mouse behavior to expect for zooming (the menu items in the Zooming Interface Menu have the values 1, 2, and 4, respectively... 3, 5, and 6 are also valid).
zoomOutRate	Determines the rate at which zooming out occurs using the middle mouse button. The rate is given as a percentage zoom factor, applied roughly every 1/25th of a second. The default value is 8. A value of 0 corresponds to no zooming, while a value of 40 causes extremely fast zooming.

appendObjectInfo arg	Add arg to the text in the Information Frame of the Object Panel.
*attributePanel object* [show \| hide \| close]**	Control the attribute panel associated with object. The "show" command causes a panel to be shown (created if did not exist, or shown if created but hidden). The "hide" command hides an existing panel. The "close" command destroys an existing panel, regardless of whether it is shown or hidden.
clearObjectInfo	Clear any text currently in the Information Frame of the Object Panel.
disableBindings	Turn off mouse and keyboard input to the main window and CLUT editor.
enableBindings	Allow the main window and CLUT editor to accept mouse and keyboard input.
loadobj filename	Load filename into GeoZui3D.
*newobj type* label [x y z]**	Create new object. The type may be its type (ex: DataTriangles) or extension (ex: .gdt). The x y z values represent the objects GeoReferencing point.
pauseRecording	Pause any currently recording or playing script.
recordAndExecMaybe arg	Record arg in the recording script and execute arg as a command, as well.
recordAndExecMaybe arg	If GeoZui3D is currently recording, record arg in the recording script. Regardless, execute arg as a command, as well.
recordMaybe arg	If GeoZui3D is currently recording, record arg in the recording script. (arg is not executed.)
*recordTimestampMaybe [arg]*	If GeoZui3D is currently recording, record a timestamp in the recording script. If arg is present, attach it to the timestamp as a comment.
redisplay	Redraw the main window.
stopRecording	Stop any currently recording or playing script.
subtogl path args	The user can redefine this function to provide different defaults to the creation of GeoZui3D subwindows. The redefined function should be a permutation of the following code. return [eval "subwindow $windowPath $args -contents 3D"] "-contents 3D" is an example of a default being specified. Other valid attributes besides -contents are -height, -width, -titleheight, -borderwidth, -resizewidth, -parent, -x, -y, (the next four are boolean switches) -overview, -showtitle, -setbuttons, -lockbuttons, and any normal Tcl/Tk options for frames.
subwindowDisableBindings win	Turn off mouse and keyboard input to the subwindow win.
subwindowEnableBindings win	Allow the subwindow win to accept mouse and keyboard input.
*subwindowPlace win x y width height* 1**	Move and resize the subwindow win accordingly.
subwindowRaise win	Bring the subwindow win to the front.
subwindowTitle win titletext	Set the title for win to titletext and show the title bar if it is not already showing. If titletext is empty (""), then the titlebar is removed.
subwindowVerifyList	Returns a list of all subwindows currently in existence.

Scripting Interface