Interacting with MOAN

Contents

• Getting help.
• Quitting.
• Reading and writing scene files.
• Changing the selection.
• Viewing the scene.
• Editing the selection.
• Setting the current animation frame.
• Animating the scene.

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.

Key	Function
Escape	Terminates MOAN.

• The same as the input scene file name; thus, the input file is replaced by the saved file.
• An arbitrary, user-specified, string.
• The result of concatenating either a user-specified string, or the input scene file name, to a system-generated extension.

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 number of the line in the input file which failed to parse, in square brackets, and
• a (hopefully helpful) error message, possibly including
• the input token whose value was deemed invalid.

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.

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).

/usr/class/cs248/assignments/assignment3/examples/navigate.sc

• When a single view is drawn, it may be rendered from the point of view of either the default camera or a user-specified Camera node, called the secondary camera.
• When two views are drawn, separated by a narrow vertical bar, the left view is rendered from the default camera's viewpoint, while the right view is rendered from the viewpoint of the secondary camera.

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

• lit solids, a slow operation which produces realistic images - this is the default -, or as
• unlit wireframes, a fast operation which produces rough sketches of the scene.

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

Editing transformation parameters

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:
   • Horizontal movement modifies the X displacement of a translation, and vertical movement modifies the Y displacement. Thus, the mouse appears to drag the object.
   • Both horizontal and vertical movement modify the angle of a rotation. Thus, diagonal movement of the mouse will alter the angle twice as fast as purely horizontal or vertical movement.
   • Horizontal movement modifies the X scale factor, while vertical movement modifies nothing. Thus, a single parameter may be precisely tweaked.
   • Horizontal movement modifies both the distance to the near clipping plane, and the distance to the far clipping plane. Thus, as the mouse moves, different slices of the scene become visible.

   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

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.

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.

• On the left, the frame number is displayed as an integer ranging from 0 up to a maximum value. This maximum value is one less that the total number of animation frames, which is determined by the user when moan is invoked:

  Command-line switch	Arguments	Default value	Function
  -frames	One integer strictly greater than 1.	301	Sets the total number of animation frames.

• Most of the line is occupied by the frame bar, a thermometer-like visual indicator of the current animation frame: when it's empty (fully green), the first animation frame is the current one, and when it's full (fully red), the last animation frame becomes current.

• On the far right, a red square may appear if a Joint Transformation node is selected. Its presence indicates that the current animation frame is a keyframe for this node.

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.

Automatic playback

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

• linear interpolation, indicated by an L on the top left of MOAN's status bar, or
• cubic (or Hermite) interpolation, indicated by a C, and providing an ease-in-ease-out effect.

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

Saving frames to disk

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

• the MOAN window is not obscured by any other window, and that
• you do not resize the MOAN window

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

/usr/class/cs248/assignments/assignment3/examples/planets.sc

An articulated figure.