Alpha_1 User's Manual

Tk3d User's Manual

Basic Usage
- Command Line Options
- Client/Server Network Connections
Graphics Window Mouse Usage
Toolbar
Menus
X Window Resources

Basic Usage

Tk3d is a new Tcl/Tk-based interactive 3D viewing program for Alpha_1 models. It is meant to replace both viewa1 and motif3d. Tk3d merges the functionality of viewa1 and motif3d into one application that can read and view .a1 files and also connect to c_shape_edit and a client viewing process.

Command Line Options

Tk3d may be started from the Unix prompt by typing the following:

    tk3d [-displaymode {X11|GL|OpenGl}] [-connect] [[-o objname] ...] [[-a file.a1] ...]

Command-line options are explained below:

-displaymode mode - This option may be used on a SGI machine when the X DISPLAY variable is set to a remote host that is not an SGI. This is done by typing -displaymode X11. Other valid modes are GL and OpenGL, in which tk3d will use the hardware assisted GL display driver on the SGI machines.
-connect - This option connects tk3d to c_shape_edit. This is the old motif3d behavior.
-o objname - This option reads and displays the given named object.
-a filename - This option reads and displays the objects in the given .a1 file.

Client/Server Network Connections

Tk3d makes a network connection to a running c_shape_edit application if the -c option is given. If no c_shape_edit application can be found, an error message is printed and the program exits. Tk3d and c_shape_edit need not be run on the same host, but that is the default. If the c_shape_edit is running on a remote host, the environment variable A1SHOST must be set to the remote hostname so tk3d knows where to find the c_shape_edit. To set the remote hostname, type the following at the prompt.

        csh 1> setenv A1SHOST another-machine

Then type the following to connect tk3d to the c_shape_edit process on the remote machine.

        csh 2> tk3d -connect &

Graphics Window Mouse Usage

The mouse is used in the graphics window to manipulate the viewpoint and to manipulate the selected set of objects. The set of selected objects is relevant for some of the operations on the menus.

Viewpoint Manipulation

To manipulate the viewpoint hold down the middle mouse button and drag the mouse. The viewpoint is updated according to the current view mode until the mouse button is released. See Toolbar for detailed descriptions of the various viewing modes.

Selecting Objects

By default, the selected set of objects is drawn in red. To select an object, click the left mouse button on any part of the object. This operation deselects any other objects that were selected. To add objects to the selected set, hold down the Control key while clicking the left mouse button on the desired object. Clicking the left mouse on a selected object will remove it from the selected set. Clicking the left mouse away from any object will deselect everything. There is a menu item on the View menu to select all the objects in the viewing window.

Toolbar

The standard menubar and toolbar is shown below. The toolbar is the lower portion consisting of many buttons. These buttons control viewing modes and standard views. The buttons from left to right are described below

To remove the toolbar from the viewing window allowing added screen space, click a button in the Options menu.

Viewing Modes

Scale - This mode allows global scaling of displayed objects. Move the mouse left to zoom out and right to zoom in.
Pan and Zoom - This mode moves the point where the mouse is clicked to the center of the screen. Objects are then scaled as the mouse is dragged, the same as in Scale mode.
XY Pan - This mode applies X and Y translations according to mouse movement.
XY Rotate - This mode applies X and Y rotations according to mouse movement. This makes the mouse act similar to a trackball or joystick. By moving the mouse left and right, objects rotate around the Y axis. Moving the mouse up and down rotates the objects about the X axis.
X Rotate - This mode rotates displayed objects around the X axis. Moving the mouse to the right causes a positive rotation and moving to the left causes a negative rotation.
Y Rotate - This mode rotates displayed objects around the Y axis. Moving the mouse to the right causes a positive rotation and moving to the left causes a negative rotation.
Z Rotate - This mode rotates displayed objects around the Z axis. Moving the mouse to the right causes a positive rotation and moving to the left causes a negative rotation.

Standard Views

Reset - This option sets the viewing transformation to the default. (Front view with the origin at the center and unit length visible in the X & Y directions.)

Center - This option centers all the objects in the viewing window.

Center Selected - This option only centers objects in the selected set.

Front View - This option sets the viewpoint to "front". This shows the XY plane so you are looking at the objects in the negative Z direction.

Back View - This option sets the viewpoint to "back". This shows the XY plane so you are looking at the objects in the positive Z direction.

Top View - This option sets the viewpoint to the "top". This shows the XZ plane so you are looking at the objects in the negative Y direction.

Bottom View - This option sets the viewpoint to "bottom". This shows the XZ plane so you are looking at the objects in the positive Y direction.

Left View - This option sets the viewpoint to "left". This shows the YZ plane so you are looking at the objects in the positive X direction.

Right View - This option sets the viewpoint to "right". This shows the YZ plane so you are looking at the objects in the negative X direction.

Menus

The menus have basically the same set of options as motif3d/viewa1, although some are in different places or have slightly different names. One new feature of the Tcl/Tk menubar is that the menus are tear-off menus. Each menu has a dashed line at the top. If you select this line, the menu is torn off and presented in a separate window that persists. For example, here is the View menu "torn off":

Tk3d menus and menu options are described below.

File Menu

The File menu options are explained below:

Read A1 File...
This option reads objects from a file and displays them.
Save A1 File...
This option saves objects to a file.
Save View Matrix
This option saves the current view transformation (viewpoint) in a file named mat.a1.
Save View Matrix As...
This option saves the viewpoint in a file of the your choosing.
Print...
This option prints the contents of the window using Postscript.
Read Model View...
This option reads a viewpoint file
Save Model View...
This option saves the viewpoint to a file of the users choosing.
Quit...
This option exits the program.

Edit Menu

The Edit menu options are described below:

Undo
Undo the previously performed operation.
Redo
Redo the previously performed operation.
Save
Saves the current viewpoint.
Restore
Restores the previously saved viewpoint.

View Menu

The View menu options are explained below:

Clear
This option clears the viewing window of all objects.
Unshow
This option unshows the selected objects.
Select All
This option selects all objects in the viewing window.
Viewing Modes
The viewing modes are the same as in the toolbar with the addition of:

Zoom - This mode enables zooming using a specified bounding box.
Hither - This mode moves the "hither" (near) clipping plane. Objects are clipped against two planes parallel to the XY plane. Moving the mouse to the right moves the plane closer to the viewer, left moves it away from the viewer.
Yon - This mode moves the "yon" (far) clipping plane in the same manner as the Hither clipping plane.

Standard Views
The standard views are the same as in the toolbar
Viewing Options

Perspective - This option turns perspective on or off.
Continuous - This option turns continuous drawing on or off. Normally, when the middle mouse is dragged, the window is redrawn continuously (as fast as possible) until the mouse button is let up. If performance is a problem, continuous display can be turned off. This will cause the window to be redrawn only when the mouse button is let up.
Fast Display - This option turns fast display on or off. When on, all objects are displayed as bounding boxes during continuous viewing operations to speed up the display. This can actually cause worse performance in many instances.
Depthcueing - This option turns depthcueing on or off. When on, objects will appear to fade away as they are distanced from the viewpoint.
Note: Continuous and fast display performance options are rarely required on current workstations except for extremely complicated models.

Options Menu

The Options menu options are described below:

Curve & Surface Properties ...

Selecting the Curve & Surface Properties ... item from the Options menu pops up a dialog box. This dialog box allows editing of curve and surface properties. The dialog box looks like this:

Options in the dialog box are explained below:
Curve Properties

Curve - This option displays curves as smooth lines.
Curve Polygons - This option displays the control polygons of curves.
Curve Fineness - (5.0) This option sets the fineness value for smooth curve display. Smaller values will produce smoother curves (more line segments) and larger values will produce coarser representations (fewer line segments). This also affects isoparametric lines. Use the slider bar to modify fineness values.
Surface Properties

Surface Isolines - This option displays isoparametric lines of surfaces.
Surface Meshes - This option displays the control meshes of surfaces.
Surface Normals - This option displays normals near the four corners of a surface as arrows in the direction of the normal with base on the surface. This can be useful for checking orientation of surfaces.
Surface Shading - This option allows display of shaded surfaces (SGI machines only).
Surface Fineness - (30.0) This option sets the fineness value for the spacing of isoparametric lines in surface display. Smaller values will produce more isoparametric lines and larger values will produce a coarser representation with fewer isoparametric lines. Use the slider bar to modify fineness values.

Ok
Clicking on this button will apply any changes and close the dialog box.
Apply
Clicking on this button will apply any changes but leave the dialog box open.
Cancel
Clicking on this button won't apply any changes and will close the dialog box.

Preview Animation ...

Selecting the Preview Animation ... item from the Options menu pops up a dialog box. This dialog box allows animation previewing of group and instance structures. Every animated instance that is currently displayed will be included in the preview. The dialog box has a VCR-like interface and looks is shown below:

Time Counter: The top of the dialog box is the time counter. This displays the current time with reference to the animation being previewed.
VCR-like buttons: The top row of buttons beneath the time counter are VCR-like buttons that control the animation. From left to right they are: Rewind, Reverse Play, Stop, Play, and Fast Forward.
Time Interval and Number of Frames: Beneath these VCR-like buttons are two entry boxes that control the Interval of time between steps and the number of Frames to be displayed. The two buttons to the left and right of these entry boxes may be used to control both the Interval and Frames values together.
Controlling animation play: To the far right of the Preview Animation ... dialog box are three buttons that control how the animation is played. Once corresponds to one time through the animation. Loop will cause the animation to play continuously when Play is pushed. Step allows you to step through the animation at the time interval set as described above.
Reset: Clicking on this button will reset the time counter to zero.
First: Clicking on this button will set the time counter to the first frame of the animation being previewed.
Last: Clicking on this button will set the time counter to the last frame of the animation being previewed.
OK: Clicking on this button will close the dialog box and end the animation preview.
Rescan Objects: Clicking on this button will rescan the objects animation instances fr

Toolbar

This option removes/adds the toolbar from the top of the viewing window.

X Window Resources

X resources can be used to configure the appearance of various elements of the user interface of Tk3d. The application name "tk3d" and class name "A1wish" can be used for these. See the X/Motif3 Resources documentation for details.

Alpha_1 User's Manual Home Page

a1-web@gr.cs.utah.edu