SimBalls - A Ball Simulator for Povray v3.5 by Alain Ducharme

Description:
  SimBalls is Povray SDL (Scene Description Language) code to simulate 	bouncing and rolling balls.

Bug(s):
  SimBalls has a bug: due to the simple method being used, if a ball rotation gets stuck (i.e.: against multiple objects or balls), its rotational energy will not be handled properly.  Therefore, if you throw a bunch of balls together into a closed container, when they eventually get stuck together they will release their angular momentum energy in strange ways.

The include files:
  simballs.inc
    Contains the SimBalls macros.
  quaternions.inc
    Contains the quaternion macros to help rotate the spheres.
  tdlowres.inc
  tdmedres.inc
  tdhighres.inc
    Trace direction arrays used for trace collisions.

NOTE:  These include files and the macros contained within them where created with the intention to collect together frequently used functions and alleviate the main SimBall .pov files.  However, Povray v3.5 doesn't handle macro calls between files efficiently as pointed out in the help, section 6.2.8.2.  Since SimBall macros may potentially be called hundreds to thousands of times per frame, this will have a significant impact on performance.  I've decided to leave the include files as is for simplicity and perhaps in anticipation of a near future version of Povray which may address this.  In the meantime, you may wish to collapse the required macros into your main SimBall .pov files.

Sample files:
  sbbasic.pov - Basic example, one ball with floor and wall boundaries
  sbstack.pov - Stack of balls in room, with bottom ball spinning like a top
  sbmix.pov   - Mix of types of collisions
  sbmb.pov    - Glass marbles and glass bowl

  I don't have any documentation at this time.  The sample files are the best way to learn how to use SimBalls.  Heres the basics:

Ball parameters:
  Unless otherwise specified, assume Povray units, coordinates and axis/rotation directions.
  Bg[I]: Gravity (units/second^2 in Y direction, < 0 = down, > 0 = up)
  Br[I]: Radius
  Bm[I]: Mass
  Bp[I]: Position  
  Bv[I]: Velocity (units/second)
  Bw[I]: Angular Velocity in circles ( 1 circle = 360 degrees = 2pi radians )
  Bo[I]: Orientation (quaternion that must be normalized!  Use tools in quaternions.inc to set)
  Bc[I]: Coefficient of restitution (bounciness, 0 = none to 1 = perfectly elastic)
  Bu[I]: Coefficient of friction (grip, 0 = no friction to 1 = extremely high friction)
    Note: nothing except perhaps vacuum space has a CF of 0.  Ice has a CF of approximately 0.02.  If a ball with a CF of 1 collides with another ball or object with a CF of 1, this collision will have infinite friction.

Collision detection:
  Ball to ball collision detection is handled by SimBalls.
  Ball to scene object collision detection can be handled by you or SimBalls.
  CR & CF = Coefficient of restitution and friction, as defined in the ball parameters but for the collision object.
  For speed, precision and exactness, it's best to handle simple ball to object collisions yourself.
    Call SimBalls' immovable object collision macro ImmovColl(CollNorm,CR,CF,Position) where CollNorm is the normal of the collision object's surface at the collision point and Position is the position the ball should be at the collision point without penetrating the collision object.  If you are not sure what the ball's position should be, simply pass Bp[I].
  For complex collisions you can simply use SimBalls's TraceColl() which uses Povray's trace() function.
    During initialization, you may optionally call SimBalls' SetTraceRes(R) where R = 0, 1 or 2 (low, medium and high) to set the trace() resolution.  Default is 1.  (0 = 23 traces, 1 = 57 traces and 2 = 255 traces)
    BTraceColl(Obj,CR,CF) will do a bounding box check before detecting a collision using trace().  You should only use this if the object's bounding box is well defined and if balls will not collide with more than one BTraceColl() object at a time.
    TraceColl(Obj,CR,CF) will always test collisions using trace.  If you are going to use this, Obj should be a union of all the possible objects balls can collide with.  You should not have more than one TraceColl in a simulation.

Troubleshooting:
  - Balls pass through objects for which collision detection is active
    : Decrease SimStep (i.e. 1/500, 1/1000, etc. if balls move at high speeds)
  - Balls get stuck inside objects surface using TraceColl()
    : Object may have it's normals reversed, use RNTraceColl(Obj,CR,CF) if so
    : Use TraceText(TObj,CR,CF,Z) for text objects
  - Unusual ball behavior
    : Check parameters, are normals normalized?
  - When a lot of balls are thrown into a closed container the balls get jumpy
    : This is a bug in SimBalls (see above), use fewer balls or don't throw them in ;-)
