project - 3D bouncing ball program

Keith Tyler
COM1370
MArch 12, 1999

DESCRIPTION

The program displays a simple 3D animation of a sphere bouncing within the
confines of a cube.  The cube space takes up the displayed space.  The
sphere is represented by three ellipses which represent xy, yz, and xz
dimensions for the sphere.  The ball moves at a constant rate, and
reflects off of the "sides" of the cube.

LOCATION

The source, as well as a set of compiled class files, are in
/home/romulus/courses/com1370/project/.

INSTALLATION

The source code file is program.java (it cannot be renamed).  It should be
compiled with the standard Sun Java compiler:

javac project.java

USAGE

The program requires three command line arguments which define the x, y,
and z center of the starting position of the sphere in 3-space.
Java-compiled files must be run through the Java interpreter by their
class name, and command line arguments are appended:

java project ball-x ball-y ball-z

BACKGROUND

The 3D environment is transferred to the 2D display by use of perspective
projection.  Both the cube shape and the ball shape are processed through
the perspective projection transformation each time the ball moves, and
the screen is redrawn with the new information (although only the ball
data changes).

The main engine behind the ball movement is the run() method of the
BouncingBall class.  The method runs indefinitely, taking a short pause
for each redraw.  Each cycle, run() calls the function to apply the ball
movement function (a translation transform matrix) to the point data.

The display is carried out with multiple functions which take the 3D space
definitions of the shapes and get them to a point where they can be
displayed properly.  The projection transformation is applied using a
Z-axis perspective projection transform matrix.  The 3D display space is
defined from (-100,-100,-100) to (100,100,100).  To get the displayed
values to appear in the window coordinates of (0,0) - (200,200), a second
method, toViewCoords(), is used which simply adds 100 to both the X and Y
values of a given point.

The perspectiveTransform() method is called on a point or set of points to
return a set of points in projection coordinates.  The 
perspectiveTransform() method itself in turn calls the matrix-vector
multiply method, matVectMult(), on each of the set of points, and
the Z-axis projection transform matrix, persTransMat.

The method which "moves" the ball on each redraw, moveBall() calls the
translate() method on the set of points defining the ball, which in turn
calls matVectMult on each of the points and the translation matrix,
currTranslation.

The moveBall() method keeps track of the current center of the ball and
the current X, Y, and Z movements of the ball.  If the coordinates of the
ball center breach a certain subarea of the cube (i.e. the center comes
within R of the cube limits) the moveBall() negates the appropriate
movement parameter(s) for use in the next ball movement.

The function which draws the ball, drawBall, uses the Java drawOval()
graphics function to draw each ring of the sphere.  Each ring is defined
by four of the six defining points of the sphere, and each point of the
sphere is continually processed through the projection transform.
Therefore as the ball moves, these ovals should appear similar to how the
rings in such a real ball would appear as the ball moves through 3-space.
The "size" of the ball also therefore changes according to its distance
from the view plane.

A special object, HomPoint, was defined in this project to conveniently
contain the x,y,z,h values of each 3D homogeneous point.  The HomPoint
class contains multiple constructors to create HomPoints with values that
are 0-initialized, explicitly defined, or indirectly defined (by an
array).  The class also contains a conversion method allowing easy
transfer between the HomPoint structure and the array format required by
the matVectMult() and other functions.

OPERATING PARAMETERS

The only parameters definable at run-time are the X, Y, Z values of the
sphere starting point.  Other parameters are defined within the source
code which could be altered to give slightly different view of the
animation. 

The projection reference point is stored in HomPoint prp, though only the
Z coordinate, prp.z, is actually used in the Z-axis projection transform.
By default this is 200, placing it 100 pixels in 3-space away from the
view plane (which is at the front of the cube, on the XY plane at z=100).

The translation matrix for the ball movement is defined by an array
ballMovement. ballMovement[0] defines X movement, etc.  The array values
are plugged directly into the currTransform matrix which exists within the
moveBall() method.  By default, ballMovement is {1,1,1}.  These could be
changed to alter the velocity and direction of the ball movement.

The animation timing is defined by the argument to a sleep() call in the
run() method.  This could be changed to speed up or slow down the
animation progression.

FURTHER POSSIBILITIES

With all of the physical and display procedures in working order as they
are now, it should be trivial for example to add a second ball, with its
own movement and/or even size characteristics, and bounce it around the
cube simultaneously.  The proximity detection used for the cube sides 
could be easily replicated to ensure that the two balls properly interact
physically with each other.