There is a scripting interface as well as the interactive user interface. The scripting interface is usable from the Jython Console module. See the Modelzilla Framework Scripting Interface.
This documentation describes how to use the interactive user interface at the general, non application specific level. The user interface described here is actually itself an application module, called the StandardModule in the current distribution. The Modelzilla framework does not have any intrinsic user interface other than 3D viewports and data flow views. Because the general user interface is an application module, it could be replaced with another set of controls for doing the same things. The general framework wouldn’t know the difference.
The StandardModule is a user interfaces for controlling the following:
To load an application select it the list and hit the "Load" button. This causes the applications special initialization function to be called, which will place the application’s user interface wherever desires. The user interface is usually placed in the tab area of the main tall and skinny Modelzilla frame.
To unload in application, selected in the list and hit the "Unload" button. This tells the selected application to remove its user interface and do any cleanup it needs to. However, if the application has created any existing elements in the repository, it cannot truly be unloaded.
An application will be loaded automatically whenever Modelzilla is started if you turn on the "Auto Load" checkbox.
If application does not have a stub-file a in the stub-files directory, you can simply
enter the complete package and class name of its initialization class in the text field called
"Module package name", and hit the “Load” button. It is also possible to run a macro
from this control panel, by entering the macro name in the top text field and hitting the
"Run Macro" button. (This will invoke the Module.execute() function.)
The current state of a model, created by any number of application modules, can
be saved to and recall from a special proprietary file format called MVG. (MVG stands
for Modelzilla Virtual Graphics.) It is textural version of the Modelzilla repository,
following the XML standard. Note that it is not the graphics or the geometry that is saved
here, but the top level information from which graphics and geometry are computed. This
is why Modelzilla must use a proprietary file format. Each application module has its
own feature set that does not correspond one-to-one with the feature set of other software
like AutoCAD or RasMol. The Modelzilla repository system is however general enough
to be able to hold information from any application, and its structure is uniform enough
to allow the framework to save and load these MVG files with out knowing how the
information is really used.
The "Save" function will save the model with already associated filename.
“SaveAs” enable you to enter a new filename if the model already has an associated
filename. The new file name is used in subsequent saves. “Save” will invoke “SaveAs”
if the model has no filename.
The repository editor is structured as a graphical tree of rectangles that mirrors the
actual structure of the repository. In the editor, every repository node is represented by a
rectangle. If a node has children, children’s rectangles appear inside the rectangle of their
parents. The node’s type is printed in square brackets to the right of the red x. In the
Modelzilla repository, some sub nodes enjoy a guaranteed existence within the scope of
their parent, while others come and go according to the desire of the user. We call nodes
with a guaranteed existence “property nodes”, or “input nodes”, or “field nodes”,
interchangeably. Property nodes are listed horizontally in the repository editor. Each of
these nodes is represented by a rectangle with a gray area on the top indicating the node’s
name, and an area on the bottom that is a summary of the node’s current value. This
system is intended to mirror the idea of a two dimensional table. If every node with
properties in the repository had exactly the same type, each of these nodes appear as a
row in the table. In fact it would be an interesting idea to collect all of these nodes of the
same type and display them together in the repository editor. Then the repository would
look like a database of tables.
A node is expanded to show children by a clicking on the small + sign under the
nodes name. A node is contracted by clicking on the - sign. This follows the convention
of a typical graphical file browser (where each node is a file or directory). The big + sign
under the small + sign does a deep expand – it expands to show children recursively
down the tree. To expand a property node to show it’s children, click on the its name
area. The interface is not displayed + to avoid clutter. When a property node is
expanded, it moves down to the position of a regular node to give room to show the
children.
A node can be renamed by clicking on it’s white name area. This causes a small
text editor to be is placed on top of the node's name. Type in the new name and hit enter.
Property nodes cannot be renamed.
To delete a node, click on the red X to the right of the node’s name. Property
nodes cannot be deleted. (They cannot be deleted from their parent. The parent can
however be deleted.)
A node that is visible in the view port, because it has associate geometry, can be
automatically shown in top of the repository editor by right clicking on it in the view port,
then choosing the show in tree option.
To change the value of a property node, click on the value area and under the
name. This will put up a window for editing the value.
To move a node from one parent to another, go to the node’s display in the right
side area and click on the up arrow. This will cause the node to start blinking. And then
go to the left side area, and click on the node you wish parent it to. The node and should
now be removed from the old parent and added to the new parent.
To see what a node is currently linked to, if it is linked to anything, click the
node’s right pointing arrow. This will cause the right side area to scroll to show the
source node to the right of the destination node (the link target). There should be line
pointing from the link target to the link source. (Linking a node to another allows many
nodes to all follow the value of one. Some application modules automatically link newly
create nodes to a common node. For example CAD-Zilla does this with color properties.)
To unlink a node that is currently following the value of another node, click on the
star sign in the node’s title bar. The star sign is intended to reflect the de-reference
operator in the C programming language.
To link a node to another node, whether not is already linked, first find the desired
source node in the right hand view of the repository editor. Click on the & sign of the
source node - it will start blinking. Then find the node you want to point to the left hand
area, and click on its value area. The two nodes must have compatible types, or
Modelzilla will complain that is not possible link these nodes.
To assign the value of one node to another without linking them, find the node
that will be the source of the assignment in the right hand view, an click on the = sign.
The node will start blinking. Go to the right hand view and click on the node you wish to
assign to.
The default mode of operation for Modelzilla is object selection. If no other
function is taking input, there is a background function that enables the user to build a
selection set. This set is visible in the Basic Controls->Selection panel. If a function is
started that requires a selection, it may offer one or more separate selection sets. A
general pattern is that for functions that require object selections as input, it is possible to
select the objects before or after invoking the function. Objects selected via the default
selection mode are applied to the object selection specification of the function, if it has
one. It the object selection is the only specification for the function, the function will do
its job without asking for further specification. For example, this allows one to delete
objects by first selecting them and then starting the delete function. The delete function
will simply do the delete and be done. This is faster then starting the delete function,
selecting the objects, then hitting the OK button. Its like using an RPN calculator versus
a calculator with an = button.
The delete function has the option of exploding the input instead of simply
removing it from the repository. The explode option causes all of the free children of the
selected objects to placed in the repository. This is useful if you have by some operation
created an object that is taking its input as children, and now need to free up the children
to be used for some other purpose. Or, instead of doing an explode, is also possible to
selected children and copy them out.
Another way to delete an object is to right click on it in the viewport to get the
context menu up and chose the "Delete" option. Yet another way to delete an object is to
hit the red x on its repository editor representation. And often an application’s modules
will offer a more convenient way to delete members of the group of objects it is
particularly concerned with. Thus, the general delete function isn't actually used that
often.
There are two options regarding where to put the newly created copies. If the
"Current Group" check box made true, the newly created copies are placed as children of
the current grouping node. Otherwise, copies are placed as siblings of the source objects.
One way is to find the object and repository editor, and locate the property to
change within the object’s properties that are listed horizontal with a gray bar indicating
each properties name. To locate the object in the repository editor, right click on the
object and chose the "Show in Tree" function. It will appear at the top of the repository
editor. Find the property in the objects listed properties, click on its value area and a little
window will pop up for setting this type of value.
Another way to edit an object’s properties, is to right-click on the object in the
viewport and choose the “Edit Properties” option. This will put up a window that has the
object’s properties listed on the top half, and a small user interface for setting the property
currently selected the list on the bottom half. Find property in the list, click the right
mouse button on it, and then use the editor and on the bottom to set the value.
If you wish to edit the properties of multiple objects that all have a property with
same name, first select all these objects, then go to BasicControls->Objects->Edit
Properties. This function puts up a window similar to the one described above, except it
shows the union of all the properties of the selected objects. As before, select the
property to change in the list, and then change it in the property editor device that appears
below. The value you choose is distributed to the properties of the same name in every
selected object.
Yet another way to set the properties of an object, is to use the special editor
offered by and some application modules. For example some application modules reuse
the general property editor and interface, inserted within their own interface to provide an
easy way for editing the properties of the objects of its particular concern.
It is also possible to use the Show/Hide functions to control of visibility of
multiple objects together. Go to BasicControls->Objects->Show/Hide. To use these
functions, simply select the objects you want to show or hide in and then hit the show or
hide button.
The rotation center is controllable and will be described below.
Exactly how the rotation term is changed according to the motion of the mouse is
controlled by the global setting, "mouseRotationMode". The default value for this setting
is "Rack and Pinion Rotation". In this mode, the viewpoint is rotated as if there is a big
ball at the rotation center, and there is a large, flat board aligned with the viewport plane
resting on the top of the ball. The board moves with the same motion as the mouse
cursor, and by doing so it rotates the ball and the viewpoint. The board is the rack, and
the ball is the pinion, as is the rack and pinion mechanism used by the automobile
steering system, except in this case that the rack and pinion each have two degrees of
freedom, and the rack is moving the pinion rather than vice versa. The other option for
the global setting, “mouseRotationMode” is "Virtual Trackball". The virtual trackball
method works in a way comparable to the rack and pinion method described above,
except that the mouse cursor is in direct contact with the ball instead of going through the
planar rack. The math tracks a point projected from the viewport plane to a point on the
surface of the ball. If you move from right to left, near the vertical center of the ball, the
viewpoint will rotate to the left. If you move from higher to lower, near the horizontal
center of the ball, the viewpoint will rotate down. If you drag the mouse in the area
outside the radius of the ball, the math is computed differently. Here, it is as if you
dragging a saucer on the outside of teacup is been turned upside-down. Such a drag will
cause the viewpoint to twist about the center of the saucer. The main advantage of the
virtual trackball rotation mode is the ability to twist about the z-axis. To achieve the
same effect in rack-and-pinion mode, you must go through a series of twirling motions.
If the normal behavior of a left mouse button drag has been overridden by some
other specialized viewpoint motion, rotation behavior is restored with the Basic Controls-
>Eye->Rotate function.
To rotate the viewpoint about the z-axis without going through the virtual
trackball and without making a series of twirling motions, use the Eye->Rot-Z function.
This will cause the next mouse drag made in the viewport to be interpreted as a z-rotation
motion.
It is also possible to do a viewpoint translation without holding down the shift key
by using the Eye->Pan function. This will cause the next mouse drag to be interpreted as
a translation. After the drag viewpoint will be back to the field rotation mode.
To translate the viewpoint in and out in depth, use the Eye->Pan-Z function. This
causes the next mouse drag to be interpreted as a translation in z.
The scaling center is controllable and will be described below.
Exactly how the mouse motions are interpreted to control the viewpoint scaling is
controlled by the global setting, “mouseScaleMode”. If this setting is set to "Legacy
Zoom" the zoom factor simply gets bigger with an up-drag and smaller with a down-drag
at a rate this seems to be reasonable. If this setting is set to "Radial Zoom" the scale
factor is computed so that if you drag the mouse radially from the scaling center point,
any graphical entities under the mouse will stay under the mouse.
It is possible to make changes to the viewpoint translation factor by dragging the
red box in the x-y abstract picture. This is the box that appears in the lower right-hand
corner of the viewport with a red and green rectangle. It shows an abstract version of the
viewport. The green rectangle represents the viewport bounds. The red rectangle
represents the objects within the viewport. You can click and drag the red rectangle with
in this box. The viewpoint translation factor will change to match.
It is also possible to make changes to the translation factor in the z direction by
dragging a red box in the z abstract picture. This is the box that appears in the lower
right-hand corner of the viewport with a red box and yellow and white lines. It shows an
abstract for some the viewport z dimension. The red box represents the object bounds.
The yellow bars represent the when front and back depth-cue points. The white lines
represent front and back clipping planes. Click and drag the red box, and the viewpoint
translation factor will change to match.
This function is considered the precise a translator because it works with a
precisely defined coordinate system. This enables you to limit your translations to the xy-
plane of the UCS. This will enable you to draw out translation vectors interactively. The
entry of the head and tail of the vector are dependent on factors such as the grid snap and
geometrical point snaps. The available point snaps are application and context
dependent.
You are also given the option of copying the translated objects new objects. The
"No Copy" will translate the selected objects themselves. The "Copy" option will
translate an independent, deep copy of the selected objects. The "Link" option will
translate a linked copy of the selected objects.
Enabling the “multiple” option will cause the function to cycle back to the vector
entry start point after the translation of the selected objects is complete. New copies are
made according to the copy option.
It is also possible to specify the mirroring plane in three dimensions by using the
Use Basic Controls->Transformations->Mirror3D function. To use this function, first
select the objects to mirror, and then enter the three points defining the missing plane.
The objects are mirrored across the plane passing through the three points.
The small objects in the upper right hand corner of the viewport are graphical
avatars of lighting objects. They tell you what type of lights are being applied, the
direction they are facing, where they are placed, and what color they are. If you don't
want to see them, go to the viewport settings and disable the "showLights" property.
The lighting objects are applied on a per model basis. Each model has a set of
lights associated with it that are applied to all objects in the model. Although the lower
level graphics subsystem of Modelzilla is capable of applying different lights to every
object independently, this ability is not offered by the graphical user interface. It is
however be possible to do this through to scripting interface. Someday the GUI may
offer this ability.
If multiple models are displayed in a viewport, the lights from one model do not
affect the objects from other models. The lighting avatars for all the models are displayed
in the upper right corner.
Usually geometrical objects have a property for controlling their color. This
property is divided into sub-properties for controlling the response to ambient and diffuse
light. The ambient color property of the object effects it’s response to the directionless
ambient light of the scene, that comes from everywhere. The diffuse color property of
object effects it’s response to all other lights. Generally, changing an object’s diffuse
color property will have the greatest effect.
The settings for ambient lights appear in the lower half of the lighting control
panel went the light is selected in the light list. The main setting you care about here is
the color.
The settings for ambient lights appear on the lower lighting control panel when
the light is selected in the light list.
color - This is the color of the light. It affects objects as described above.
direction - This is the direction of the light, expressed as a three-dimensional
vector. This vector is in the viewport coordinate system. That directional lights are
therefore stationery within a viewport. If you the point of view a different part of the
model is lit by these lights, which have changed direction with respect to the model. To
change the direction, select the direction property in the properties list, and type in a new
vector. The viewport coordinate system has the X dimension going to the right, the Y
dimension going up, and is the Z dimension coming out of the screen. You want to keep
the Z dimension negative, for the lights. This will cause them to face the front side to
objects .
enable - Change this value to false to disable the light. The light will then have
no effect on the graphics.
modelLight - Set this to true to make the lighting direction be computed in the
global coordinate system instead of the viewport coordinate system. This will make the
light stationery with respect to the model as the viewpoint is changed.
The settings for point lights appear on the lower half of the lighting control panel
when the light is selected in the light list.
color - This is the color of the light. It affects objects as described above.
position - This is the position of the light in global coordinates.
linearAttenuation - This controls how much the light diminishes in strength as
the subject moves further away. This value is multiplied by the inverse of the distance,
which then multiplies the total affect of the light.
quadAttenuation - This controls how much the light diminishes in strength as the
subject moves further away. This value is multiplied by the inverse of the distance
squared, which then multiplies the total affect of the light.
enable - Change this value to false to disable the light. The light will then have
no affect on the graphics.
Other settings are considered self explanatory.
Saving and Loading MVG files
Saveing a model
Go to Basic Controls -> Model Files -> SaveAs. This starts a dialog box. The
only information you need to enter in this box is the filename of the model to save. If you
leave the “Save Image” check box turned on, a small snapshot of the model will be saved
with the MVG file, and displayed when browsing MVG files to open to help you
remember which model is which. You can also type in a textural description in the white
box labeled "Description". If the "Save Compressed" check box is turned on, the model
file will be compressed in ZIP format. Hit the OK button to write the file.
Opening a model
Go to Basic Controls -> Model Files -> Open. This starts a dialog box, with the
same file selector widget used in the model saver dialog. Selecting any MVG file in the
current directory causes the image of the model is displayed in the grey box to the right,
and the models textural description is displayed as one. Note that model file is not being
fully evaluated to display the small image – it is simply scanned for the image that was
taken in the previous save. The "Viewport" choice box enables you to choose what is
done with the model when it is opened. If the "New Viewport" option is selected, a new
viewport will be created and the model will be made visible within the viewport. If the
“Current Viewport” option is selected, the model will simply made visible within the
current viewport. Modelzilla allows any number of models to be displayed in a given
viewport, and allows any number a viewports to display a given model.
Opening a recently saved model
The "Recent Files" list has a list of models that you have been dealing with
recently. Double click on a file name in the list to open the model.
Creating a new model
Go to Basic Controls -> Model Files -> New. This creates a new empty repository
group. Newly created pieces of a model are deposited the repository group of the current
model.
Selecting the current model
The current model is chosen by selecting the title bar of the Viewport that is
displays this model. If the viewport displays multiple models, the first model that the
view displays is made current. It is also possible to select the current model from the list
in the "Open Files" list box under the "Model Files" control panel.
Close the current model
Go to Basic Controls -> Model Files -> Close. This removes the current model
from the repository, and removes any corresponding geometries from all viewports that
model is displayed in. You will be asked if you want to save the model before it is
cleared from memory.
Saveing all non-model settings
Go to Basic Controls -> Model Files -> Save Settings. This saves any global
settings, like user interface settings or settings specific to an application module. The
settings are automatically saved if Modelzilla is exited normally. These settings are saved
in Exiting Modelzilla (no!)
Go to Basic Controls -> Model Files -> Exit. You will be asked to save any un-
saved models.
Using the repository editor
Copying, Deleting, Editing, Showing, and Hiding Objects
Selecting Objects in General
Many operations require a selection of objects (to tell the operation what to
operate on). Objects can be selected two ways. One way is to pick it in the viewport. As
you move the mouse over an object in the viewport, it will become brighter. This is
telling you which object will be selected should you chose to select it. If you then click
the left mouse button on it, it is added to the selection set. It will then become even
brighter to show it is selected. The other way is to find it in the repository editor and pick
it.
Deleting Objects
Go to Basic Controls->Objects->Delete. This function allows you specify any
number of objects to delete. To use the function, you may first select the objects to delete
and then invoke the function, or you may first invoke the function and then select the
objects. Like most operations Modelzilla, the delete function is undoable.
Copying Objects
Go to Basic Controls->Objects->Copy. This function allows you specify any
number of objects to copy. The "Copy Type" option gives a few ways of doing the copy.
The "Regular Copy" will make an independent, exact duplicate of the input objects. The
"Link Copy" will make a copy of the input objects that stays linked to the original input
objects, so that it will try to reflect the values of the original object. The new objects are
actually up the same type as the original input objects, but are only shallow copies. This
function admittedly doesn't always work because of the complexities of maintaining a
link in more complex objects are actually use other objects as input. It does however
always work for simpler objects. The "Raw Geometry Copy" option is for objects that
have geometry associated with them. This copy method creates a special type of
repository node that simply holds a dumb copy of the geometry of the input objects. No
link is maintained to the original object in this copy and method. The raw geometry
object has no semantic behavior, in other words it has no model of this human
understanding of this object. The raw geometry object properly saves to an MVG file
despite its lack of semantics, because the actual geometry data is written in binary form as
part of the MVG file. A "Linked Geometry Copy" option is planned for the future and
maybe in Modelzilla by the time you read this.
Editing Object Properties
A lot of good work can be done by simply changing the properties of objects.
There are several ways to do this in Modelzilla.
Showing and Hiding Objects
All geometrical objects in Modelzilla are subject to the same conditions
controlling whether or not they appear in a given viewport. A geometrical object is
visible and in a viewport if the model to which belongs is set to be visible to the viewport.
Every object also has a true or false flag indicating whether not it should be shown. This
value must be set to true as well, for the object to appear in any viewport. The framework
actually offers a more sophisticated method for controlling visibility of objects on a per-
viewport basis, however this user interface currently does not make full use of this ability.
Maybe it will soon. The only thing you can do from the GUI is to control the true or false
property called "visibility" that is a member of every geometrical object. One way to
control this property is to go to the repository editor, find the property and set it. If you
click on what a value section of the visibility property, a little window will pop up for
controlling the value. If you then switch back to the geometry viewer, you can see the
object will become invisible if you set this value to false, and become visible again when
the value is set to true.
Controlling Object Transparency
Transparency enables you to control the visibility of an object on a continuous
basis. The transparency of all geometrical objects the Modelzilla are controlled by
property called "transparancy". This is a scalar value that ranges from 0 to 1. A value of
zero makes the object completely opaque. A value of one will make the object
completely see-through. To change the transparency value, follow the instructions for
editing any object property.
Debugging Object Geometry
The Basic Controls application comes with a handy tool for examining the
geometries of an object. To use it, select the objects of interest, and hit the “Debug
Geometry” button. This brings up a special dialog that lets you do things like show
vertex values, show the vertex index values, and the same trick for normals, colors and
texture values. You can also put up a graphical picture of normal vectors and other
various values that appear as text next to the corresponding vertices.
Controlling the Point of View
Rotating the viewpoint with the mouse
Rotating the viewpoint with the mouse is the most useful, and therefore the
easiest, viewpoint change that you can do. Just drag the right mouse button in the
viewport. All viewpoint changes are accessible all the time by dragging the right mouse
button. The meaning of the left mouse button will change according to the specific
function that is currently taking input, however the right mouse button will always make
changes to the viewpoint. This enables you to make changes to the viewpoint the middle
of doing any other operation.
Translating the viewpoint with the mouse
To translate the viewpoint, or in is words to move the viewpoint up, down, right
or left, hold down the shift key on your computer's keyboard and drag the right mouse
button in the viewport. The viewpoint will track the motion of the mouse cursor exactly.
Scaling the viewpoint with the mouse
To scale the viewpoint, drag the right mouse button while holding down the
control key on your computer's keyboard. The objects will appear to get bigger when
dragging the mouse up, and smaller when dragging the mouse down.
Translating the viewpoint with the abstract picture
Translating the viewpoint with the scroll bars
The translation factor can be controlled with scroll bars. You will first need to
enables scrollbars by going to viewport settings, finding the "scrollbars" property and
turning it on. You can then control the translation by dragging the scrollbars.
Interestingly, the scrollbars work backwards from conventional scrollbars.
Rotating the viewpoint with the knobs
The rotation factor can be a controlled with handy graphical knobs that are
attached to the side of the few port. You will first need to enables scrollbars by going to
viewport settings, finding the "scrollbars" property and turning it on. The rotation about
z-axis is controlled with the small circular knob in the upper left-hand corner. The x-axis
rotation is controlled with the dial type knob on the right. The y-axis rotation is
controlled with the dial type knob on the top.
To window on a region of the viewport
Use to Eye->Window. Drag the right mouse button in the viewport and a yellow
rectangle will trace out its motion. When you let go of the mouse the viewpoint
translation and scale factors are modified so that the portion model within the dragged-
out rectangle filled the viewport.
Jumping to the previous view
Use the Eye->Previous function to cause the viewpoint to jump back to what it
was before the previous drag event.
Setting the center point for rotation and scaling changes
The viewpoint rotation and scaling changers require a center point to rotate and
scale about. The default location of this point is the origin of the user coordinate system.
It is possible reset this point. Use the Eye->Ctr-Pnt. function to pick an arbitrary point.
Use the Eye->Ctr-Obj. function to pick an object, whose center point will become the
rotation and scale center point. Note that the center point will not stay bound to this
object.
Fitting all objects to the viewport
Use the Eye->FitAll function. This modifies the translation and scaling factors to
bring in all objects whose visibility is enabled for the viewport with in view.
Fitting selected objects to the viewport
Use the Eye->Fit-Object function to cause the viewpoint translation and scaling
factors to be modified to accommodate the selected objects.
Align viewpoint to user axis plane
Use Eye->Algn-Z.
Saving desirable viewpoints
The Eye control panel has some handy controls for saving and recalling the points
that are especially desirable. These viewpoints are saved to the MVG file that goes along
with the model so that you can conveniently change between saved viewpoints that are
especially good. To save the current viewpoint, hit the Eye->Save button. This will add
an entry to the saved viewpoints list. You may rename this entry by clicking on it in the
list. Typed in the new name and hit enter. To recall a saved viewpoint click on it the list
and hit the Eye->Recall button. To replace a viewpoint in the list with the current
viewpoint that to presumably better, selected the viewpoint entry in the list and hit the
Eye->Update button. To remove a viewpoint entry from the list hit the Eye->Remove
button.
Moving Objects Geometrically
The User Coordinate System
The User Coordinate System, or UCS, is given an arbitrary position and
orientation by the user. You, the user may then do work involving geometrical entities
such as three-dimensional points and vectors with respect to this coordinate system. For
example, to rotate an object about an axis, is may be easier if the axis is exactly the Z axis
thus enabling you to consider the rotation in the 2D plane. Or to draw out some points all
in the same plane, it is once again easier to work in the XY plane. Hence, you need to be
able to define the working coordinate system. This is described fully in the User
Coordinate System section. For a simple model it will be sufficient to leave the user
coordinate system at its default position, which is equal to the global coordinate system.
But a more complex model will have many pieces with different positions and
orientations that are more convenient to work with in the user coordinate system.
Translating Objects Precisely
To translate is to move from side to side, up and down, and forward and
backward, without rotating or resizing it. To accurately translate an object, use Basic
Controls->Transforms->Translate. This function is an example of a sequential input
function. To use it, first select a set of objects to translate. Then enter a translation
vector, with respect to the UCS. After you enter the object selection, the translation
vector input device will automatically start taking input. You may simply type in the
vector value at this point, or you can enter the vector using the mouse. The first piece of
input for this is the tail of the vector. Notice the vector entry task is divided into two sub-
tasks, viewable by expanding the drop down arrow in the vector entry widget. If you
move the mouse into the viewport, a two dimensional crosshair will appear in the UCS
xy-plane. You may simply pick a point in the plane this way. Once this point is entered,
you are asked for the head of the vector. Enter this point the same way. If you choose to
use the tail/head method of entering the vector, the translation will be done interactively
as you move the mouse to enter the head. This enables you to visually verify the objects
are in the right place before you finalize the translation.
Translating Objects Easily
Sometimes it is only necessary to move the objects so that they appear to be
visually in the right place. This often sufficient if you are dealing with objects in
biological systems or any system that is so complex that the shape of the objects appear to
be arbitrary in nature. Such objects do not have any obvious coordinate system that is
more amiable than any other. For this reason, we have the Transformations->Move-By-
Eye function that simply moves objects with respect to the viewport projection plane.
The UCS is not a factor here. To use this function, first select the objects you wish to
move. Then set the movement method to "Pan XY". The left mouse button will now
cause the selected objects to move parallel to the viewport plane. They should precisely
follow the motion of the mouse cursor. If the movement method is set to "Pan Z", the left
mouse button will cause the selected objects to move perpendicular to the viewport plane.
An upward motion will move objects and closer to the viewer, and downward motion will
move them away from the viewer.
Rotating objects precisely
Use Basic Controls->Transformations->Rotate2D. This function works in a
similar way to precise translator function. The difference is that this function does a
rotation about a base point. If this function is used in the usual sequential manner, the
base point is entered first, using the method of any point input. The base point is the
point about which the selected objects are rotated. The rotation is about an axis that
includes the base point, and is perpendicular to the UCS xy-plane. The function then asks
for is the angle to rotate by. This angle can be typed in. It is also possible to enter the
angle using the mouse. The angle input device’s usual mode of operation is to first ask
for a base point and then two legs of the triangle forming the angle. The base point has
already been entered, so the angle input device starts asking for first leg of the triangle. It
then asks for the second leg. As the mouse is moved, the angle is computed and the
rotation is done interactively on the selected objects. When the second leg of the triangle
is finalized the rotation is finished.
The Rotate2D function requires that you carefully set up the UCS before doing the
rotation. An easier way to do a rotation about an arbitrary axis is to use the Rotate3D
function. This function first asks you for the axis of rotation, which defines both of the
base point in normal vector of the rotation. It then automatically repositions and reorients
the UCS, and continues like the Rotate2D function. After the rotation is finished, the
UCS bounces back to where it was before you started the function.
Rotating objects easily
The "Move by Eye" function will do rotations and with respect to the viewport xy-
plane. To use this function, first select the objects to rotate. Then set the transformation
method to "Rotate". The objects are transformed according to mouse input using the
virtual trackball method. You can read about this method in the discussion of controlling
the viewpoint. The base point for this rotation is the UCS origin.
Scaling objects precisely
Use Basic Controls->Transformations->Scale. This function works in a similar
manner to the precise translator function. The difference is that this function does a
scaling about a base point. After the selection of objects to scale has been entered, you
are asked for a base point. The scaling is done about this base point so that fragments in
the object selection at exactly this point will not move at all, and points increasingly far
away from the base point will move proportionally more than points that are closer. The
next thing the function asks for is the scaling factor. The scaling factor can be typed in.
It is also possible to enter the scaling factor with the mouse. The mouse entry method for
the scaling factor uses the ratio in radii from two points measured from the base point.
You have already entered the base point. Therefore entering the scale factor with a
mouse requires picking an initial radius point, and then picking a second radius point.
During the picking of the second radius, the scale factor is computed and the scaling
transformation is done interactively (as the mouse is moved).
Scaling objects easily
The "Move by Eye" function can also scale objects. To use this function first
select the objects you wish to scale. Then set the transformation method to "Zoom".
Now grab a point on the viewport plane and drag the mouse. The scaling factor is
computed as the ratio between the distance between first point / scaling base point, and
the distance between current point / scaling base point. If you move the mouse along the
direction exactly radially from the base point, the scaling transformation will be done
such that any graphical fragments of objects under the mouse cursor will stay under the
mouse cursor as the mouse is moved.
Scaling objects non uniformly
Use Basic Controls->Transformations->ScaleNU. Much like the uniform scaling
function, this function has for a selection set of objects to scale and a base point. It also
asks you for an independent scaling factor in the X dimension, Y dimension and Z
dimension with respect to the UCS.
Mirroring objects
Use Basic Controls->Transformations->Mirror2D. This function does a mirroring
transformation within the xy-plane of the UCS. To use the function, first select the
objects to mirror, and then enter two points to defining the mirroring axis within the UCS
xy-plane. The objects are then mirrored about a plane that goes through this axis and is
perpendicular to the UCS xy-plane.
Making a rectangular array of objects
Use Basic Controls->Transformations->Translate Array. It is possible to make
many copies of the selection of objects in the pattern of a rectangular array. This saves
the trouble of making many independently translated copies. To use this function, first
select the objects to copy. Select the copy method. The choices are "Copy" and "Link",
which work in exactly the same way as the other transformation functions. The
parameters for this function are the number of rows and columns in the array, in the
overall size of the bounding rectangle.
Making a polar array of objects
Use Basic Controls->Transformations->Rotate Array. This function sweeps multiple
copies of the selected of objects about a given base point, total sweeping angle, and copy
count.
Viewport Attributes
Creating a new viewport
Use the "New Viewport" function to create a new viewport and that will display
the current model.
Closing a viewport
Use the "Remove Viewport" function to remove the viewport currently selected in
the viewport list. It is also possible to remove a viewport by using the standard window
closer in the viewport’s title bar.
Avatars
showLights
If this is true, objects representing the lights that go along with the models
displayed by the viewport are drawn in the upper right corner.
showClippingPlanes
If this is true, objects representing the clipping planes that go along with the
models displayed by the viewport are drawn.
ucsInCorner
If this is true, the UCS triple is drawn in the lower left-hand corner of the
viewport always, regardless of the actual origin of the UCS.
Features
haloLines, haloThickness, haloAlways, hiddenLines
These options are currently obsolete. They used to control rendering options that
were intended to increase the visual understandability of line drawings. The feature may
be added back as it was actually fairly useful, so the settings are left here to encourage the
feature to come back.
solidFilling
If this is true, the back sides of polygons representing the surfaces of solid objects
are drawn in a brown color. You can see the backsides of these polygons if the objects
are partially clipped by the front clipping plane. This feature makes it easier to
understand what is going on.
GUI
scrollBars
If this is true, scroll bars for effecting the viewpoint translation factor and small
tools for affecting the viewpoint rotation factor are placed beside the 3D graphics area.
The section on the viewpoint control describes how to use them.
bigPicture
If this is true, a small window that is an abstract picture of the viewport content,
with respect to the viewport projection plane, is placed in the lower right-hand corner of
the viewport. The section on viewpoint control describes how to use it.
depthPicture
If this is true, a small window that is an abstract picture the viewport content
along depth dimension is placed in the lower right-hand corner of the viewport. The
section on the viewpoint control describes how to use it.
progressPicture
If this is true, a small window for displaying progress messages displayed in the
lower right-hand corner of the viewport.
selectionPicture
If this is true, a small window for displaying the name of the object that the mouse
is currently over is drawn in the lower right-hand corner of the viewport.
Rendering
depthCue
If this is true, the depth cue effect is used in rendering the 3D graphics. Depth cue
makes it easier to understand what is in front of what. Objects towards the back are
blended in with the background color. Object in front standout more in their own in their
own color. This gives a strong visual cue as to what is in front and what is in back.
autoDepthCue
If this is true, the front and back depth cue planes are computed automatically
based on the content of the viewport. This is convenient for sophisticated graphics that
are heavily reliant on depth cue for understanding.
depthCueFront
This scalar value is the distance away from the viewport coordinate system origin
to the front depth cue plane. The front depth cue plane should always be farther away
from the viewport origin then the back depth cue plane. The front plane establishes the
start point at which objects begin to blend into the background color. The front plane
should generally be behind the front clipping plane.
depthCueBack
This scalar value is the distance away from the viewport coordinate system origin
to the back depth cue plane. The back depth cue plane establishes the end point at which
objects are fully blended into the background color. Objects behind the back depth cue
plane will not be visible.
frontClip
This scalar value is the distance of the front clipping plane away from the
viewport origin. Any 3D graphics fragments located in front of the front clipping plane
are not drawn.
backClip
This scalar value is the distance of the back clipping plane away from the
viewport origin. Any 3D graphics fragments located behind of the back clipping plane
are not drawn.
localViewer
If this is true, angle computations are made with the assumption that the user is
about 3 ft. away from the computer monitor. It is false, computations are made with the
idea that the user is infinitely far away.
jitterCount
This sets the number of jitter steps used in the scene anti-aliasing method. If you
hit the anti-alias button, the quality of the rendering is determined by this number. Anti-
aliasing draws the three-dimensional graphics several times in slightly different places,
and blends each drawing together into a final image that is shown to the user. This
mostly eliminates the jagged edges that vex raster graphics.
bgColor
This sets the background color of the viewport.
perspective
If this is true, a perspective transformation is made as the model contents are
projected to the viewport plane. This causes the model content farther away from the
viewer, or deeper in depth, to become compressed. This imitates the perspective effect
that people see in everyday life. The perspective effect is what makes far away objects
appear to be smaller than close objects. This long held fact of life is rendered beautifully
by the prospective transformation.
frustum
This controls the amount of perspective transformation that is used. A value of
zero results in no perspective transformation.
Stereo
stereoMode
This choice can be one of two options. The "None" option causes nothing special
to happen at all. The "Split Screen" option will cause the viewport to be rendered in a
split screen stereo mode. Split screen stereo is a method of increasing the feel of depth by
providing separate images for the left and right eye. In real life our two eyes see objects
from two different positions and therefore see objects at somewhat different angles. Of
course for very far away objects the effect is greatly reduced, which is why people
looking across Arizona's Grand Canyon say it looks like a painting.
stereoAngle
This controls the angle difference between the two sides of stereo pairs. An angle
of about three degrees should provide a realistic view.
stereoSeparation
This is the difference in pixels between the centers of the stereo pairs. Adjust this
value to get the stereo pairs at suitable distance. The proper distance will depend how far
away you are sitting from the computer screen.
stereoGap
A narrow gap is placed between the stereo pairs where nothing is rendered all.
This is the width of this gap in pixels.
Lighting
Lighting Color
All types lighting objects have a color attribute. The color of light affects the
graphical rendition by being multiplied with the pigment color of the surface being
drawn. For example, if the surface has an even grey color, the hue of the lights cast on
surface will come through exactly, as in (0.5, 0.5, 0.5)*(r, g, b) = (0.5*r, 0.5*g, 0.5*b).
Or if the lights are even grey color, the hue of the lit objects will come through exactly, as
in (r, g, b)*(0.5, 0.5, 0.5) = (0.5*r, 0.5*g, 0.5*b). Otherwise, the apparent color of the
surface will be a blend of the surface color and light color. However this blend is not an
average of colors, but a multiplication of colors. For example, if the object’s color is pure
black, no amount of light and will make the object anything but black, as in (0, 0, 0)*(r, g,
b) = (0, 0, 0). If the object is pure red, and it lit by pure blue light, once again the object
will appear completely black because the red blue and green terms are multiplied
independently, as in (r, 0, 0)*(0, 0, b)=(0, 0, 0). Lights should share a common color
component with the objects they are intended to cast light upon.
Lighting Direction
The directional lights and the spotlights have a direction attribute. Generally you
want to locate lights towards the top of the viewport, and have them point in a downward
direction. You are warned that it can be confusing to the viewer if the lights are on the
bottom, facing up. Consider the lighting effects on a sphere. The only geometrical
difference between the convex surface of the front side of a sphere, and the concave
surface on the inside of a spherical bowl, is the sign of the depth dimension of the
surface’s slope. If you apply lighting from the top of the viewport pointing down, the
convex sphere will appear brighter on the top and bottom. The concave bowl will appear
brighter on the bottom than the top, because the bottom side is pointing towards the light.
However, if you apply lighting from the bottom of the viewport pointing up, the convex
sphere will appear brighter on the bottom, and the concave bowl will appear brighter on
the top. In other words the sphere can be made to look like a bowl if the lighting comes
from the bottom, and the bowl made to look like sphere. The moral of the story is, light
your objects from the top, to avoid confusing the viewer’s perception of depth.
Lighting Position
The point light and the spotlight have a position attribute. This point is kept with
respect to the global coordinate system.
Ambient Lights
A new ambient light is created with Basic Controls->Lights->Ambient Lt..
Generally you will not need to create a new ambient light because a default new model
will always come with one, and one is always enough. Ambient lights cause lighting to
come from all directions at once. Some degree of ambient lighting is essential. It enables
you to see the darker, unlit areas of the model. Using ambient lighting is also more
physically realistic than using many directional lights. The lighting in a room or even in
the outdoors does not come only from the source of the light, but also objects that reflect
the light from the light source. This is evident even in the outdoors. Just ask yourself,
where does the light come from in the half hour after sun set? It must be reflected off the
atmosphere itself.
Directional Lights
A new directional light is created with Basic Controls->Lights->Directional Lt.
This creates a new directional light and adds it to the model. The default model comes
with two directional lights pointing in a downward direction, to the left and right.
Directional lights model the light coming from the Sun. This is parallel rays of light that
do not diminish in strength as they get further from the source, which has no certain
location. This is a very close model to light coming from the Sun within the general
proximity of the Earth because, the Sun is so very much more far away from the Earth
than any distance we can travel on Earth to notice any change in angle or strength in the
sunrays.
Point Lights
A new point light is created with Basic Controls->Lights->Point Lt. This creates a
new point light and adds to the model. Point lights have a position associated with them.
The strength of a point light diminishes with the distance away from it. It resembles a
light bulb, or candle, or even the Sun on a galactic scale.
Spot Lights
A new spot light is created with Basic Controls->Lights->Spot Lt. This creates a
new spotlight and adds to the model. Spotlights are more sophisticated versions of point
lights. In addition to a position and attenuation factors, spotlights are limited to affect the
graphics within a cone of influence.
color - This is the color of the light. It affects objects as described above.
position - This is the position of the light in global coordinates.
linearAttenuation - This controls how much the light diminishes in strength as
the subject moves further away. This value is multiplied by the inverse of the distance,
which then multiplies the total affect of the light.
quadAttenuation - This controls how much the light diminishes in strength as the
subject moves further away. This value is multiplied by the inverse of the distance
squared, which then multiplies the total affect of the light.
enable - Change this value to false to disable the light. The light will then have
no affect on the graphics.
angle - This controls the angle of the cone of influence.
direction - This controls the direction of the cone of influence in global
coordinates.
Undo/Redo
The User Coordinate System
Transforming the UCS
RotateX, RotateY, RotateZ Rotate the UCS about its x, y, and z axis by a specified
angle.
3 Points Lets you specify the new origin, a point on the x axis, and a point on the
xy-plane.
Origin Lets you set the origin of the UCS with out changing the orientation.
Global Sets the UCS to the global coordinate system.
View Rot Changes the orientation of the UCS to be in the viewport plane.
Object Changes the UCS to match the coordinate system of a given object.
Saving the UCS
Save Saves the UCS transform to a list.
Recall Recalls the selected transform to the UCS.
Delete Removes the selected transform.
Managing the Grid
The Grid Spacing sets the spacing of the grid lines. The snap and tick ratios set
the relative spacing of the grid snap and ticks.
Exporting VRML, STL, POV-Ray, and Image formats
Global Attributes
Files
undoLimit The number of undo nodes kept in history.
autoSave If true, model files are automatically saved to name.mvg.autosave on a
timer.
saveDirectory The directory recently looked at by the file opener function.
Rendering
pointerSwapHardware Effects how XOR updates are done.
fastObjectUpdate Geometric objects changing often will update in lines if true.
useXOR If true, XOR update is used in creating some geometric objects.
quickViewpoint If true, line drawings are used when doing gradual viewpoint
changes.
selectionPreview If true, objects will highlight some when the mouse is moved
over them.
textureFallback If true, texture maps are not applied during gradual viewpoint
changes.
visibilityChecking If true, a quick check is done before drawing objects to find
out if they are actually in the viewport bounding rectangle.
specularScale The relative proportion of specular highlights given to objects.
Sean W Hennessy