Peanuts NeXT Software Archives/Peanuts-3.iso/Graphics/3d/Rotation.1.0.README

Text File | 1992-08-16 | 9.1 KB | 189 lines

                 3-d_Rotation
        Douglas M. Bates ([e-mail])
          Murray K. Clayton ([e-mail])
0. Summary

3-d_Rotation is an application for displaying and rotating
3-dimensional data.  It allows the user to plot lines, points, both,
or neither (see below).  This readme file explains: How to Work It,
How It Works, How We Wish It Would Work (things to add), and What
Doesn't Work (Bugs).

This package is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 1, or (at your option)
any later version.

This package is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program (in file COPYING); if not, write to the Free
Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.  A
copy of the GNU General Public License is also available when running
the application by clicking on ``Info...'' in the main menu.

(Thanks for Jacob Gore ([e-mail]) for providing the GNU License
Panel.)

1.  How To Work It

Data must be arranged in an ascii file with extension .dat , .data ,
or .3d .  The data must be in 3 columns, each line of data
corresponding to a point in 3-space.  The first column corresponds to
the ``x'' coordinate, the second column corresponds to the ``y''
coordinate, and the third column corresponds to the ``z'' coordinate.

Data may be plotted as points, lines, both, or neither.  To plot data
as points, the word ``points'' (or, in fact, any word beginning with P
or p) must be on a separate line before the data to be plotted as
points.  (To be precise, the plotted points will appear as small
circles.) Using the word ``lines'' instead will result in a series of
connected line segments with endpoints given by the coordinates in the
data file.  Using ``both'' will put a small circle at the endpoints of
each line segment.

When ``neither'' is used, the data will not be plotted but will be
used to determine the scaling of the plot.  Each axis is scaled to
accomodate the range of all the data in that column from the file.
You can force an unusual scaling by adding points under ``neither''.

The data file can be opened in the usual way by selecting ``File'' from
the main menu and then ``Open'' from the submenu (or Command-o).

Clicking the ``Axes'' button will cause axes to be displayed.  Note
that when originally opened, the x axis lies horizontally, the z
axis lies vertically, and the y axis runs ``into'' the picture (a
right-hand system).  Clicking the ``Cube'' button causes a cube to
be displayed.  This is the default when the application starts up.
Both axes and the cube can be displayed, or neither.

The sliders allow rotating the data:  the phi slider changes the
elevation angle; the theta slider changes the azimuth.  The delta
slider changes the ``viewing distance.''  To show the current values
of phi, theta, and delta, click the ``Show Angles'' button.  The
``Reset Button'' will reset these values.  Specific values of phi,
theta, or delta may also be typed into the forms at the top of the
3-d Rotation window.

Opening a new data file will automatically release the current data
and reset the values of phi, theta, and delta.

The Print menu item prints the current contents of the view.  It can
also be used to save an encapsulated PostScript version of the view.
You can save the PostScript to the pasteboard instead using the Copy
item in the Edit submenu.

2.  How It Works

3-d_Rotation relies on a PerspMat class of objects, an AzimuthMat
class of objects, and a custom view called CubeView.

PerspMat inherits from Object, and provides perspective projections of
3-d coordinates onto a 2-dimensional plane.  It includes methods for
translating, scaling, rotation around each of the coordinate axes (x,
y, and z) and providing perspective based on the viewer's distance
from the item being viewed.  The approach involves transforming
homogeneous coordinates through matrix manipulations as described, for
example, in chapters 7 and 8 of Foley and Van Dam (1982) Fundamentals
of Interactive Computer Graphics, Addison-Wesley, Reading, Mass.  For
the purposes of viewing the projected data, there are 2 methods:
render: and as_DPSpath:.  render fills a 3-dimensional array of arrays
of floats with the projected coordinates while as_DPSpath projects the
(x,y,z) values and stores the two projected coordinates in the order
(u1,v1,u2,v2,...).  This is the type of structure used in the system
function DPSDoUserPath.  as_DPSpath comes in two forms, the second
taking an additional argument to offset:.  We added that method so we
could plot points more conveniently.

AzimuthMat inherits from PerspMat, and is a class of pespective
matrices where the viewpoint is determined by the azimuth angle
(theta), the elevation angle (phi), and a distance to the viewpoint.
It sets limits to correspond to the range of the three coordinates,
and rescales them to lie in the interval [-1, 1].

Of course, PerspMat and AzimuthMat could be useful beyond the current
purposes.  Since we need to change the transformation and recalculate
the projected positions of the data very quickly to get the appearance
of smooth rotations, the code in these classes favors efficiency over
readability.

Finally, CubeView inherits from View, and imports AzimuthMat.
CubeView contains the methods for actually getting the projected image
onto the screen.  The factory methods and the methods for
communicating with the sliders and buttons of the interface are fairly
straightforward.  The setlimits: method uses the setlimits: method of
AzimuthMat to rescale the data, and also constructs the axes and cube
displays.  The drawSelf method puts the image onto the screen.  Two
approaches are used.  For displaying the cube, the axes, or sets of
connected line segments, the DPSDoUserPath function is used.  The
as_DPSpath method of AzimuthMat is used to create the array needed by
DPSDoUserPath as described above.  This seems to work very quickly.
We had more problems in finding a way to put up a set of unconnected
points quickly.  The approach we finally settled on is this: first, a
tiff image was created using Icon (which, incidentally, seems to have
a lot of bugs in it).  The image consists of a ``circle'' in a 5
pixels by 5 pixels rectangle.  Some shading was used to produce an
image that looks ``rounder'' than simply using the arc command of
PostScript.  The tiff image is stored as a bitmap object ``dot'' in
CubeView.  Next, the second version of as_DPSpath: in AzimuthMat is
used to create an array consisting of the centers of the circles as
they are to appear on the screen, again in the form u1, v1, u2, v2,
etc.  However, the centers are offset by the offset method by the
amount 2.5*2/384.  The 384 is the width, in pixels, of the customview
in the 3-d_Rotation window, 2 is the width in the local coordinate
system, and 2.5 is half the width of the rectangle containing the
bitmap.  Finally, the pswrap dotAt pushes this array onto the
PostScript stack and composits the bitmap.  (Thanks to Carl Sutter at
USC for information on using Bitmap objects.)

We experimented with some other methods for getting the points up
quickly, but none seems to be as fast as the above.  Even still,
things start to slow down appreciably if the number of points to
be plotted is large.  (To seem this, change all occurrences of
``lines'' to ``points'' in sample.3d and try dragging the theta or
phi slider quickly.)

To add Print and Edit/Copy menu items, as suggested by Dan McCreary
from NeXT, we had to create a PostScript-only version of dotAt that
drew the points as PostScript circles.


3.  How We Wish It Would Work

Things to do:

a.  Allow automatic rocking or rolling of the image using a
    DPSTimedEntry.  (Similar to the Motor button of the Molecule demo
    application.)

b.  Add an edit window for viewing and editing the raw data.

c.  Allow the use of many different plotting symbols (and
    thus highlighting of points).

d.  Allow data files to have k>3 columns, and allow interactive
    assignment of x, y, and z axes to any three given columns.

e.  Use the DSP for rendering the data points.  That is, scale the data
    values so they are in the range -1 to 1 and convert them to the 24
    bit DSP format.  When a new transformation matrix is determined,
    use the DSP to do the linear algebra in a DSPrender: method.  We
    imagine this will be faster than using floating point operations
    as we do now.  For lines this may produce smoother rotations.  It
    seems that for points, though, actually drawing the points in the
    window is slower than calculating where to draw them.

f.  Allow the window to be resized.


4.  Things That Don't Work

a.  A data file with line 1 containing 'points' line 2 blank, and
    line 3 with some data produces the error message ``First line of ...
    does not contain numeric data,'' which is misleading, since, although it
    does identify an error in the data file, it's the wrong error.