Alpha_1 User's Manual

Shape3d User's Manual

Basic Usage
- Command Line Options
Graphics Window Mouse Usage
Multi-mode Interface
Toolbar
Menus
Text View Window
Graphical Interface for Construction
X Resources

Basic Usage

Shape3d is a Tcl/Tk-based application that combines interactive 3D viewing and c_shape_edit modeling. Shape3d uses the standard input and output for the Scl interpreter the same as the c_shape_edit program does. This means shape3d can be used within emacs as your "scl-pgm" like c_shape_edit is. In emacs, you can do this by typing the following:

	M-x set-scl-pgm

When prompted, type shape3d. To make this your default, add the following lines to your ~/.emacs file:

   ;; Use new Tcl/c_shape_edit program
   (set-scl-pgm "shape3d")

Command Line Options

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

    shape3d [file.tcl] [-tcl] [-displaymode {X11|GL|OpenGl}]

The command-line options are described below:

file.tcl - This enables you to use a different GUI file than the default (which is $b$datatcl/shape3d.tcl).
-tcl - This starts up a TCL interpreter top-loop.
-displaymode mode - (Same as tk3d ), where mode is one of X11, GL, or OpenGl. 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 using -displaymode X11.

Graphics Window Mouse Usage

Shape3d uses the same controls for viewpoint manipulation and selecting objects as tk3d . However, shape3d has additional capabilities in order to support the multi-mode interface. These capabilities are employed through key and button bindings in the standard viewing window and the text view window. Shape3d's added key and mouse binding to the standard viewing window are described below:

Clicking Button3 anywhere in the viewing window will create points. The toolbar has 3 buttons that control how the points are placed in the window.
Clicking Button2 on a point in the viewing window while holding down the Shift key and dragging the mouse allows you to move the point to a new location.
Clicking Button2 on a line or curve in the viewing window while holding down the Control key and dragging the mouse allows you to move the curve or line to a new location.

Once an object has been selected, there are key bindings that may affect this object. They are described below:

Pressing the "d" key will delete the selected object. This may also be performed on multiple objects at one time. Deletions performed in this way WILL NOT PROPAGATE. This will probably cause many problems if an object is deleted in this way and is used somewhere else by another object.
Pressing the "t" key will make an objTransform of the selected object. The new object will be placed under the mouse pointer at the time 't' is pressed.
Pressing the "i" key will make an instance of the selected object. The new object will be placed under the mouse pointer at the time 'i' is pressed.
Pressing the "v" key will reverseObj the selected object. A new object is created when doing this, leaving the original object unchanged.
Pressing the "f" key will reflect a selected curve around a line. Both the curve and the line must be selected and the line must lie in the same plane as the curve.

The text view window also supports key and mouse bindings. When the mouse pointer is placed over an object name in the text view window, the following bindings will be applied to the object in the viewing window:

Pressing Button1 while holding both the Control and Shift keys will show the object in the viewing window.
Pressing Button2 while holding both the Control and Shift keys will unshow the object in the viewing window.
NOTE: If you have any text selected (anywhere) and do an unshow, shape3d will paste the text and not perform the command.

Multi-Mode Interface

Shape3d is a prototype of what is called a "multi-mode" interface. It combines graphical and command language interfaces into one application. The basic philosophy is to combine the strengths of graphical and command language interfaces, thus allowing the user to create, edit, select, etc. in whatever form is most convenient.

The current implementation is only a prototype, but below is some basic documentation on what it does. To the right is an image of the application with a very simple model being constructed.

The shape3d multi-mode interface contains four main parts. They are:

1. Toolbar and menubar.

2. Standard viewing window.

3. Scl text view window.

4. Graphical interface for constructions.

These four parts are explained in greater detail in the sections below.

Toolbar

The top part is the menubar plus the standard viewing toolbar. There are some menu additions that are in the following section. All toobar options are the same as in tk3d with three additional buttons on the far right. Below is a picture of these 3 buttons. All three buttons control how points are placed in the viewing window when Button3 is pressed. These buttons from left to right are explained below:

Points are placed in the window without connection to other points by a curve and are not added to the selected set.
Points are placed in the window without connection to other points by a curve and are added to the selected set.
Points are placed in the window connected to the previously entered points by a curve. Only the most recently entered point is in the selected set.

Shape3d Menus

Most of the menubar features are the same as tk3d . However, there are some additional options that are described below:

File Menu

The File menu options are explained below:

Read A1 file
This option reads and displays general Alpha_1 objects (not dependency graphs).
Read SCL File
This option reads Scl code from a file into the scl code window.
Restore Model
This option restores model dependency graphs from a .a1 file. This option can be used for general .a1 files also. Equivalent to Scl restoreModel command.
Save A1 file
This option is equivalent to the Scl dumpA1File command for the selected objects.
Save Model
This option is equivalent to the Scl saveModel command for the selected objects.
Save SCL
This option saves the Scl code window text to a file.
Load Model View...
This option loads a viewpoint file.
Save Model View...
This option saves the viewpoint in a file of the users choosing.
Quit...
This option exits the program.

Edit Menu

All options in the Edit menu are the same as in the tk3d Edit menu.

View Menu

All options in the Edit menu are the same as in the tk3d View menu.

Options Menu

The Options menu has the added feature of a dialog box for editing curves and three additional toggle buttons for controlling echo, demand evaluation and dependecy tracing in c_shape_edit. All other menu options are the same as in tk3d. The features new to shape3d are explained below:

Editing Curves...
Selecting the Editing Curves ... item from the Options menu pops up a dialog box. This dialog box allows manipulation of the Knot Vector, Curve End Condition and Order of a selected curve. There is also a button to show/unshow the control points of the curve. Below is a picture of the Editing Curves ... dialog box.

The Editing Curves ... dialog box options are used to manipulate the selected curve as described below:
Knot Vector
Below the Knot Vector submenu are three buttons that allow you to change the knot vector of the curve.
Curve End Condition
Below the Curve End Condition submenu are three butons that allow you to change the end conditions of the curve.
Order
Below the Order submenu is a entry box and arrow buttons that allow you to change the order of the curve. You may directly type into the entry box or use the arrow buttons to raise/lower the order of the curve.
Show Control Points
This button controls whether the control points of the curve are displayed in the viewing window or not.

SCL Demand eval
If selected, this option delays recomputing objects until required. For example, complicated objects generally will not be recomputed by dependency propagation if not shown in the viewing window.
SCL Trace Dependencies
If selected, c_shape_edit will trace all dependency changes and print them to standard output.

Objects Menu
Use the Objects menu to show the predefined objects provided in c_shape_edit.
Construct Menu
Use the Construct menu to create objects graphically. The simplest construction is to create points with the right mouse button. Other constructions require one or more objects to be selected and then a menu item chosen from the Construct menu. The Construct menu is a cascading menu with submenus for different types of constructors. Currently, there are points, anchors, lines, vectors, circles, curves, surfaces, volumes and transformations submenus.
To create a line through two points, for example, select two points in the viewing window and pick "Two points" from the Lines submenu. The new object will automatically be shown in the graphics window and its Scl code will appear at the bottom of the Scl code window.
Some constructors require text input in addition to the selected objects. For example, "Line point angle" requires a selected point and an angle. A dialog box appears to prompt for the angle. A constant or named dimension can be provided in this case. Other constructors require only text input and prompt via a dialog box.
Under the current implementation, if the objects in the selected set do not match the arguments required for the constructor, then nothing will be done. For example, if you try to create a line through two points with a line and a point in the selected set, it will not work.
Below is a list of all the constructors currently supported in the construct menu. Each is linked to its corresponding c_shape_edit command. Click on the links for more information about constructor number of arguments, argument types, etc.
Points

Two lines
Line circle
Two circles
Anchors

From point
Neg. from point
Lines

Two points
Point angle ...
Point vector
Horizontal ...
Vertical ...
Offset ...
Tangent Cir at Angle ...
Point parallel
Point circle
Vectors

Two points
Dir of line
Perp to line
Circles

Center radius ...
Two lines ...
Curves

Profile
Outline ...
Uniform Open ...
From Circle
Reverse
Open
Surfaces

Of revolution
Circular Tubing
From curves ...
Extrude
Extrude Dir
Ruled
Sweep const Width
Sweep w/Profile
Open
Open in Dir ...
Reverse in Dir ...
Volumes

Sphere
Transformations

Reverse Object
Reflect

Text View Window
The bottom section of the shape3d multi-mode interface is for viewing and editing Scl code. To the right is a picture of the Text View Window. There are three parts to this window: 1) the Scl code window, 2) the selected objects list, and 3) the Scl command input window (one line). These parts are explained below.

Scl Code Window
The Scl code window displays the Scl code for all the objects c_shape_edit knows about. (The built-in objects, unitcircle etc., are left out.) Shape3d assumes everything is constructed through the graphical interface (which includes the Scl text input windows). However, this is not a workable assumption at this point since the editing and I/O facilities for the text window are not sufficiently powerful to allow efficient editing.
The standard terminal input via emacs can be used for input and editing until the graphical interface is developed further. When the Scl is entered via emacs, the Scl code window will not show all the Scl code unless it is forced to refresh. This can be accomplished at any time by clicking the mouse in the Scl command input window and pressing Return.
The Scl code window allows editing and new constructions. Click the mouse (button 1, normally the left mouse button) in the window to begin editing. The window is line-based and assumes that each line contains a valid Scl command, so inserting new lines in the middle of statements will not work. When you are done editing a line, just press Return anywhere on the line to evaluate the changes. Arbitrary Scl can be entered this way, but side-effect functions such as show (foobar), will disappear after they are evaluated. The Scl code window only displays Scl code for constructed objects.
You can also use the Scl code window to show and unshow objects by name. This is described above in the Text View Window key and mouse bindings section.
Selected Objects List
The selected objects list shows the names and order of the objects that have been selected in the graphics window. In the above image, three circles have been selected and their names appear in the selected objects list. This provides addition feedback about what you are looking at in the graphics window. The selected objects list is also important for using the graphical interface for constructions that depend on what is selected.
Selecting objects in the graphics window also affects the Scl code window. The Scl code for the last selected object is highlighted in the Scl code window. The window is automatically scrolled to make the line visible. The Scl code for "circle3" (the last one selected) is highlighted in the Scl code window.

Scl Command Input Window
The Scl command input window allows an arbitrary line of Scl input to be entered. A semicolon is automatically added to the end. Above is a picture of the Scl command input window with a constant value being entered. To enter text, click the mouse in the entry area and type a valid line of Scl. Some of the basic emacs-like bindings apply for editing. When done, press Return to evaluate the command.
Graphical Interface for Constructions
To the right of the shape3d standard viewing window is a graphical interface to Scl constructions. A picture of the graphical interface is shown to the right. There is currently only a bare minimum of constructions available graphically. Currently, points, anchors, lines, vectors and circles are supported by the graphical interface.
These constructions require one or more objects to be selected as in the Construct menu. However, instead of choosing a menu item, you may simply click on the button in the graphical interface that corresponds to the desired constructor.
As with the Construct menu, the new object will automatically be shown in the viewing window and its Scl code will appear at the bottom of the Scl code window.
Constructors requiring text input in addition to the selected objects will bring up dialog boxes the same as with the Construct menu.
Below is a list of the c_shape_edit functions that correspond to each button in the graphical interface. The functions are listed from top to bottom in the same order as the buttons in the graphical interface. Each function is linked to the c_shape_edit function that it refers to. Click on the links for more information about argument number, argument types, etc.

Points

ptIntersect2Lines
ptIntersectCircleLines
ptIntersect2Circles
Anchors

zAnchorFromPt
negZAnchorFromPt
Lines

lineHorizontal
lineVertical
lineThru2Pts
lineOffsetFromLine
linePtAngle
linePtParallel
linePtVec
linePtCircle
lineTanCircleAtAngle
Vectors

vecFrom2Pts
dirOfLine
dirPerpLine
Circles

circleCtrRad
circleRadTan2Lines

X Window Resources
X resources can be used to configure the appearance of various elements of the user interface of shape3d. The application name "shape3d" and class name "A1wish" can be used for these. See the X/Motif3 Resources documentation for details.
Alpha_1 User's Manual Home Page
Alpha_1 User's Manual. Version 98.01.
Copyright © 1998, University of Utah
a1-web@gr.cs.utah.edu