<h1>Blobby Modeler On-Line Help</h1>

<h2>Table of Contents:</h2>

1.  Getting started
2.  Drawing atoms
3.  Editing atoms
4.  Loading from and saving to disk
5.  Exporting to <em>IBM DataExplorer</em>
6.  Changing the options
7.  Accelerator keys

<h2>Getting Started</h2>

<h3>Introduction:  What is Blobby Modeler?</h3>

Blobby Modeler is an add-on tool designed to work with the <em>IBM DataExplorer</em>
package software to facilitate the creation of soft objects.  Established geometric 
techniques exist to handle most engineering components, including "free form" shapes
such as car bodies and telephones.  Stochastic or Fractal modeling are frequently used
in the modeling of natural phenomena such as clouds, shorelines, or smoke.  However,
none of the abovementioned techniques lend themselves neatly to the creation of a soft
object.  Blobby Modeler collaborates with <em>IBM DataExplorer</em> in this endeavor
using a surface of constant value in a scalar field over three dimensions.  This
software provides an intuitive and interactive front end to the design of the objects,
and <em>DataExplorer</em> handles the generation and rendering of the surface of
interest.

Blobby Modeler was written in C and Tcl/Tk in the spring semester of 1995 as partial
fulfillment of requirements toward CS 790 (Master of Engineering Project) under the
supervision of Dr. Bruce Land, Cornell University Department of Computer Science.

<h3>Using Blobby Modeler</h3>

The main editing window of Blobby Modeler is subdivided into four smaller two-
dimensional windows.  The upper left window is the "xy" window, in which all atoms
of the same x- and y-coordinates but different z-coordinate will be displayed as
overlapping.  The upper right window is the "yz" window, and the lower left being
the "xz" window.  A small label is placed in the positive direction of each axis.
At the lower right is a special window called the "free" window.  It allows a user
to view the object being edited from any angle or orientation.  The "free" window
cannot be edited.

At the bottom of each window, you will find a row of buttons with corresponding icons
inside them.  For the "xy", "yz", and "xz" windows, clicking mouse button 1 (usually
the leftmost) on the the buttons have the following meanings:

<b>Pencil</b>
    Enters the "drawing" mode (and leaves the "select" mode).
<b>Black Arrow</b>
    Enters the "select" mode (and leaves the "drawing" mode).
<b>Hollow Arrows</b>
    Moves the viewport in the direction shown, if possible.
<b>Magnifying Glass with a '-'</b>
    Zooms out the viewport to see a larger portion of the field.
<b>Magnifying Glass with a '+'</b>
    Zooms in the viewport to see more of a smaller portion of the field.

The "drawing" or "select" mode buttons apply to all three editing windows, so clicking
on any of them will have the same effect.  Different magnification levels and viewport
positions are possible for each of the three editing windows, and clicking on one of
them will not affect settings on another window.

Clicking on the icons underneath the free window have the following meanings:

<b>Arrows</b>
    Rotates the object in the window in the direction shown
<b>Magnifying Glass with a '-'</b>
    Zooms out the viewport to see a larger portion of the field.
<b>Magnifying Glass with a '+'</b>
    Zooms in the viewport to see more of a smaller portion of the field.

On top of the editing windows, you will find a row of menu items with the words
"File", "Edit", and "Options".  Clicking on these will each present sub-menus with
various choices.

<h2>Drawing Atoms</h2>

To start drawing, click on any of the pencil icons.  If you move your mouse over any
of the editing windows, you will find that your mouse cursor has changed to cross-hairs
(like "+").  This indicates that you are now in the "drawing" mode.

Position the mouse cursor over a spot which you intend to be the <em>center</em> of the
atom, and click mouse button 1.  A small dialog box should pop-up which prompts you to
enter the strength of the atom.  Keep in mind that the drawing volume is from -1 to 1
inclusive in all three axes, so a strength more than 1.0 would probably not make much
sense.  Strengths can also be negative, in which case will contribute negatively to the
surface generated.  Negative strengths are never visible, but will be seen as dents if
they are close to an atom of positive strength.

By now, an atom should have appeared.  Do not worry if it is not in the correct position.
Since a mouse is only a two-dimensional input device, Blobby Modeler supplies the missing
coordinate as 0.0.  For instance, if you draw in the "xy" window, the z-coordinate of
anything you draw will be zero.  You must move the atom into its correct place using
possibly one of the other windows.

<h2>Editing Atoms</h2>

Click on the black solid arrow icon now.  Wiggle your mouse cursor over one of the editing
windows to make sure that the cursor is now an arrow.  It means that you are now in the
"select" mode.

In any of the editing windows, click on an atom.  Be careful to click on the <em>edge</em> of
the atom, instead of the center.  The atom you clicked on should turn blue to indicate
that it is currently selected.  All the items in the "Edit" menu are now applicable on
the selected atom.  You could now:

<b>Cut</b>
    This action deletes the atom from the edit windows and places it in the clipboard.
<b>Copy</b>
    This action creates a copy of the atom in the clipboard, but does not delete it.
<b>Paste</b>
    This action copies the contents of the clipboard, if any, onto the drawing windows.
<b>Select All</b>
    Instead of clicking on each atom, this command allows you to mark all atoms in the
    editing areas as currently selected.
<b>Strength</b>
    This action allows you to adjust the strength of the currently selected atom.

By simple holding down mouse button one over any atom and releasing it over a new
location, you can move the atom in any editing window.  This is referred to as "dragging"
the atom.  You may only drag one atom at a time.

<h2>File Operations</h2>

When you have completed your drawing, you will want to preserve a permanent copy.  This
and others can be done by invoking the items under the "File" menu:

<b>New</b>
    This action clears the editing windows and leaves you with a clean sheet to work
    on.  Because of its consequences, this action will seek confirmation.
<b>Open</b>
    This action loads a previously saved Blobby Modeler file.
<b>Save</b>
    This action saves a copy of the current drawings to a file.
<b>Save As</b>
    This action is the same as "Save" but allows you to select another file name.
<b>Quit</b>
    This action exits Blobby Modeler and returns to the operating system shell, after
    seeking confirmation.

To prevent costly errors, the software pops up windows confirming your action.  The "Open",
"Save", and "Save As" items will present a dialog box requesting for a file name, listing
all appropriate files (*.bm) in the current directory.  You may double-click mouse button
one on any of the choices presented to select them.

In the case of permission problems (trying to write to a read-only file, etc), the software
will warn appropriately, and abort the action selected.  It will not make an attempt to
override the settings in the directory entry.

<h2>Exporting to IBM DataExplorer</h2>

When you are satisfied with your design, it will be time to transfer the data over to <em>IBM</em>
<em>DataExplorer</em> for final rendering.  For this action, select "Export" under the "File"
menu, and you will see a new dialog box.

The topmost item in the dialog box is the file name you wish to save the file to.  By default,
<em>IBM DataExplorer</em> expects a file with the extension ".dx".  Some other important options
are available as well.  In order to prevent the additional overhead of scaling or translating
in <em>IBM DataExplorer</em>, Blobby Modeler provides options to change the origin of the field,
as well as the scale of the field.  Likewise, six possible resolutions are presented for your
choice, from 21 x 21 x 21 up to 71 x 71 x 71.  The higher the resolution, the longer it will
take both Blobby Modeler and <em>IBM DataExplorer</em> to generate the results.

When you are satisfied with the options, click on "Proceed".  The software will idle for a while,
depending largely on the complexity of the scene, the chosen resolution, and of course the
processing speed of the computer.  When it is done, you will simply be returned to the editing
screen.  The file is now ready to import into <em>IBM DataExplorer</em>.

In the simplest case, <em>IBM DataExplorer</em> will require only three modules to display the
result of Blobby Modeler's work.  You start with an <b>Import</b> module, specifying the file
name.

The read input should enter an <b>Isosurface</b> module, which is responsible for the actual
generation of the surface.  It requires a threshold value parameter, which should generally be
0.5, but any other value is just as valid.  Increasing the threshold will "shrink" the object
and decreasing it will "enlarge" the object.

The rest is simple.  Just run the object through an <b>Image</b> module, and the blobby model is
complete.

The user must be careful, however, about selecting very high sampling resolutions.  A
71 x 71 x 71 field will generate over 350,900 data points!  A good idea would be to start with a
relatively low resolution (the default 31 x 31 x 31 is a good choice) and increase resolution
only when necessary.

<h2>Changing Options</h2>

Blobby Modeler provides three options that a user may select from under the "Options" menu.
The first option, "Free Window", turns the updating of the three dimensional view on or off.
Turning off the display may be advantageous at times especially if the computer is not very
fast.  The second option, "Grid", turns the screen ruler grids on or off.  The grids are
usually useful as they provide a cue to where in the field a node is.  The last item is "Grid
size", which can be used to select a custom graduation for the grids.  This is useful if you
wish to place a node rather accurately at a position, or if you work in a high-zoom window
where the default grids will be too far apart.

<h2>Accelerator Keys</h2>

Blobby Modeler provides full functionality through its menus and buttons, but also provides
keyboard shortcuts for the more experienced user.  The keys are listed below:  (<em>Ctrl-a</em>,
for instance, denotes that the `Ctrl' modifier key be held down while the `a' key be pressed)

<b>Ctrl-a</b>  Select all
<b>Ctrl-c</b>  Copy
<b>Ctrl-e</b>  Export
<b>Ctrl-n</b>  New file
<b>Ctrl-o</b>  Open file
<b>Ctrl-q</b>  Quit program
<b>Ctrl-s</b>  Save file
<b>Ctrl-t</b>  Set strength
<b>Ctrl-v</b>  Paste
<b>Ctrl-x</b>  Cut
