Interacting with MOAN

Contents


Getting help

While MOAN does not offer any interactive help, it provides a command-line switch which lists a summary of all the command-line switches and interaction controls.

Command-line switch Arguments Default value Function
-help None. Not applicable. Forces the moan executable to display a help screen, summarizing all command-line switches and interaction controls, and then terminate.


Quitting

To quit MOAN, just press the escape key within MOAN's window.

Key Function
Escape Terminates MOAN.


Reading and writing scene files

MOAN can only manipulate one scene at a time. Throughout a MOAN session, i.e. from the time the moan executable is invoked until it terminates, one and only one scene file may be used to read (and possibly re-read) the current scene from disk. Changes to this scene may be saved in a file whose name can be any of the following: The following command-line switches set the names of input and output scene files:

Command-line switch Arguments Default value Function
-in A string. None; switch is mandatory. Specifies the name of the input scene file.
-outs A string. The name of the input scene file. Specifies the name of the output scene file. A warning is issued if the switch is omitted, in order to inform the user that the S key will overwrite the input file.

If an incorrectly formatted scene file is supplied for input, MOAN will terminate, printing

The following keys effect scene I/O:

Key Function
U Re-reads the scene from the input scene file. MOAN attempts to retain the selection: when the new scene is loaded, the first (as encountered during a tree traversal) node of the new scene tree whose name is the same as the old selection's becomes the new selection, if any.
s Saves the scene in a file whose name is formed by appending a period and a successively increasing three-digit integer (starting with 001) to the end of the output file name.
S Saves the scene in the file whose name is the given output file name.

The format of scene files is fully documented on these pages.


Changing the selection

Scene tree navigation follows the following three rules:
  1. At any point in time, at most one node may be selected. The type and name of the selection are listed on the top line of MOAN's status bar, using the following abbreviations:

    Abbreviation Selected node
    No sel None.
    Sel cam A Camera node.
    Sel grp A Group node.
    Sel trn A Joint Transformation node which encodes a translation.
    Sel scl A Joint Transformation node which encodes a scale.
    Sel rot A Joint Transformation node which encodes a rotation.

  2. Only named nodes may be selected; unnamed nodes are completely ignored during navigation. Camera nodes are always named, while Group and Joint Transformation nodes may or may not be named. Please consult the scene file format documentation for instructions on naming nodes.

  3. The initial selection, right after the moan executable is invoked, may be specified as follows:

    Command-line switch Arguments Default value Function
    -select A string. The name of the root node, if any. Sets the initial selection to the scene tree node which has the given name, provided there is a path of named nodes leading from it up to the tree root. If multiple nodes meet this criterion, the first encountered during a tree traversal is selected.

    Within MOAN, the following keys change the selection:

    Key Function
    Right arrow Moves the selection to the next named node on the same tree level and subtree, wrapping around if necessary.
    Left arrow Moves the selection to the previous named node on the same tree level and subtree, wrapping around if necessary.
    Down arrow If pressed when the selection is a group node, it moves the selection down to the first named node (if any) of the next lower level of the tree, but still within the same subtree.
    Up arrow Moves the selection to the next higher level of the tree, onto the parent of the selection (if any).

An sample scene file on which the student may practice his/her navigational skills is
/usr/class/cs248/assignments/assignment3/examples/navigate.sc
The corresponding scene tree diagram will prove invaluable in understanding how the arrow keys modify the selection. All the nodes in the scene tree are Group nodes, and all but the very bottom one are named; in the diagram, the name of each node appears right next to, or below, the node.

Viewing the scene

The scene viewing area of the MOAN window may display either one or two views of the scene: The current configuration of the viewing area appears on the top line of MOAN's status bar: in single view mode, it is the name of a single camera - the abbreviation Dft is used for the default camera; in double view mode, it consists of two camera names separated by a slash.

MOAN can render the scene's primitives that have volume (i.e. all primitives but lines) as either

Consult the scene rendering page for the specific viewing algorithms and parameters.

The following keys control the contents of the scene viewing area:

Key Function
c If pressed when the selection is the secondary camera, it toggles between single and double view mode.

Otherwise, if the selection is another camera, it becomes the secondary camera in double view mode. The selection may be subsequently modified without any impact on the viewing area (provided the key is not pressed again).

Otherwise, the viewing area is configured to display a single view from the default camera.

w Toggles the primitive rendering mode between solid and wireframe.

The initial size of MOAN's viewing area is controlled by the following command-line switch:

Command-line switch Arguments Default value Function
-size Two positive integers. 800, 800 Sets the initial viewing area width and height.

Tip: In order to interactively view a scene from varying angles, place a Joint Transformation node near the root of the scene tree, and thus move the scene relative to the camera by editing the node. Even if interactive viewing is not desired, some transformation is necessary to move the scene away from the origin and place it within the viewing volume. Peruse the sample file

/usr/class/cs248/assignments/assignment3/examples/primitives.sc
to get acquainted with an application of such tricks.

Editing the selection

Editing transformation parameters

When a Camera or a Joint Transformation node is selected, the mouse may be used to modify the parameters of the transformation encoded in the node. Editing takes place in four steps:
  1. When moan is invoked, the user specifies the amounts by which parameter values will be modified for every pixel that the mouse is moved. The table below lists the relevant command-line switches. Parameters are grouped into three categories, namely distance, scale, and angle parameters; the third column of the table after the one below lists the category in which each parameter belongs.

    Command-line switch Arguments Default value Function
    -drate One positive real number. 0.01 Sets the amount by which distance parameters change for every pixel the mouse moves.
    -srate One positive real number. 0.01 Sets the amount by which scale parameters change for every pixel the mouse moves.
    -arate One positive real number. 0.3 Sets the amount by which angle parameters change for every pixel the mouse moves.

  2. The user selects the node whose parameters will be modified, by navigating around the scene tree.

  3. The user specifies which parameter(s) of the selected node will be modified when the mouse is moved. When a Joint Transformation node is selected, it is the parameter value for the current animation frame that is modified. The mouse's horizontal movement may modify different parameter(s) than its vertical movement, or none at all. Here are some examples:

    The table below lists which key (or activator ) the user must press in order to enable or disable editing of each parameter via the mouse's horizontal movement (fourth column), or vertical movement (fifth column).

    Node Parameter Category Horizontal editing activator Vertical editing activator
    Joint Transformation encoding translation X displacement Distance x X
    Joint Transformation encoding translation Y displacement Distance y Y
    Joint Transformation encoding translation Z displacement Distance z Z
    Joint Transformation encoding scale X scale factor Scale x X
    Joint Transformation encoding scale Y scale factor Scale y Y
    Joint Transformation encoding scale Z scale factor Scale z Z
    Joint Transformation encoding rotation Rotation angle Angle a A
    Joint Transformation encoding rotation X component of rotation axis Distance x X
    Joint Transformation encoding rotation Y component of rotation axis Distance y Y
    Joint Transformation encoding rotation Z component of rotation axis Distance z Z
    Camera encoding either perspective or orthographic projection Distance to the near clipping plane Distance n N
    Camera encoding either perspective or orthographic projection Distance to the far clipping plane Distance f F
    Camera encoding perspective projection Field of view Angle a A

    Also, the following keys may be used to disable the editing of all parameters together:

    Key Function
    r Disables editing via the mouse's horizontal movement.
    R Disables editing via the mouse's vertical movement.

    Finally, on the top line of MOAN's status bar, an indicator shows whether editing is enabled for each parameter of the selected node: either the corresponding activator appears, if editing is enabled, or a placeholder period (.) appears, otherwise.

  4. The final step of editing is actually modifying the parameter(s):

    Mouse movement Button pressed Function
    Right Middle Increases the value(s) of the parameter(s) subjected to horizontal editing.
    Left Middle Decreases the value(s) of the parameter(s) subjected to horizontal editing.
    Up Middle Increases the value(s) of the parameter(s) subjected to vertical editing.
    Down Middle Decreases the value(s) of the parameter(s) subjected to vertical editing.

Keyframe management

As stated above, when a Joint Transformation node is selected, it is the parameter value(s) for the current animation frame that are modified. As parameter values for in-between animation frames are fully determined by the nearby keyframes and the current interpolation mode, manually editing a parameter value implies that the current animation frame should become a keyframe for the selected Joint Transformation node; this is indeed what MOAN does.

The user may also wish to edit a Joint Transformation node not by manually modifying parameter value(s), but rather by requesting that the parameter values for the current animation frame be interpolated from nearby ones. In other words, the desired effect is to turn a keyframe into an in-between frame, for the selected node. This is achieved using the following key:

Key Function
Return Toggles the keyframe status of the current animation frame for the selected node. It requires that the current animation frame is neither the first nor the last one.


Setting the current animation frame

The current animation frame determines two interrelated aspects of MOAN's behavior:
  1. It affects the scene's rendering, as it determines the parameters of the transformations effected by Joint Transformation nodes.
  2. It affects editing of Joint Transformation nodes, as described above.
The bottom line of MOAN's status bar is dedicated to displaying information on the current animation frame:

The current animation frame is usually set using the mouse:

Mouse movement Button pressed Function
None Left Sets the current animation frame so that the frame bar is filled up to the same horizontal window coordinate as the cursor's position, if possible.
Right Left Increases the current animation frame by one for every pixel the mouse moves, if possible.
Left Left Decreases the current animation frame by one for every pixel the mouse moves, if possible.

More precise control over setting the current animation frame is achieved via the keyboard:

Key Function
k Increases the current animation frame by one, wrapping around if necessary.
l Decreases the current animation frame by one, wrapping around if necessary.


Animating the scene

Automatic playback

It is possible to animate the scene by hand, by repeatedly using the mouse or keyboard to manually change the current animation frame. However, MOAN may ease this repetitive task:

Key Function
p Commences animation playback in the forward (increasing animation frame) direction. When the last frame is reached, playback resumes automatically, starting with the first frame. If pressed during forward playback, it stops playback.
P Commences animation playback in the reverse (decreasing animation frame) direction. When the first frame is reached, playback resumes automatically, starting with the last frame. If pressed during reverse playback, it stops playback.

By default, MOAN renders the next frame as soon as the previous one has been displayed. It is possible, though, to configure MOAN to delay drawing the next frame until some minimum time interval has elapsed since the previous frame began rendering:

Command-line switch Arguments Default value Function
-delay One non-negative real number. 0.0 Sets the minimum time interval between renderings of successive animation frames, in units of seconds.

Keyframe interpolation

The transformation effected by Joint Transformation nodes is dependent on the current animation frame and the current keyframe interpolation mode. The latter may be either The keyframe interpolation mode is set using the keyboard:

Key Function
i Toggles the keyframe interpolation mode between linear and cubic.

Saving frames to disk

MOAN can render scenes onto disk, as well as on the viewing area. Use the following command-line switch to set the base name of the files containing the renderings:

Command-line switch Arguments Default value Function
-outf A string. frame Specifies the base name of the output frame files.

To render the scenes onto disk, use the following key:

Key Function
M Saves renderings of the scene, one per animation frame, in image files of PPM format. The names of these files are formed by appending a period, the frame number, and the string .ppm to the end of the specified base name of output frame files.

Make sure that

while animation frames are written to disk.

As the frames are written to disk, the number of the frame currently processed appears on the terminal window, thus allowing the user to monitor MOAN's progress.

The PPM format is defined by the PBMPLUS (NETPBM) image libraries. PPM files are extremely easy to generate (and parse) - see MOAN's source code.

Example

An sample scene file illustrating an animated scene is
/usr/class/cs248/assignments/assignment3/examples/planets.sc
In addition, here is an image of an articulated figure; a movie (647 KB), showing a walk cycle as filmed from a moving scene camera, is also available.


An articulated figure.

Last update: 2 July 1996 by
Apostolos "Toli" Lerios