**************************************************************************
**************************************************************************
        OBJECT EXPLODER INCLUDE FILE FOR PERSISTENCE OF VISION 3.x
**************************************************************************
**************************************************************************

Created by Chris Colefax, March 1997

1.0  INSTALLATION
2.0  QUICK START
3.0  OPTIONS
3.1  A NOTE ON UNITS
        3.2  OBJECT OPTIONS
                3.2.1  explode_object
                3.2.2  object_centre
                3.2.3  object_size
                3.2.4  object_corner1
                3.2.5  object_corner2
                3.2.6  object_hollow
        3.3  PARTICLE OPTIONS
                3.3.1  particle_res
                3.3.2  particle_object
                3.3.3  particle_texture
        3.4  EXPLOSION OPTIONS
                3.4.1  exp_location
                3.4.2  exp_strength
                3.4.3  exp_falloff
                3.4.4  exp_gravity
                3.4.5  exp_sky
                3.4.6  exp_spin
        3.5  GROUND PLANE OPTIONS
                3.5.1  ground_plane
                3.5.2  ground_dist
                3.5.3  ground_reflection
                3.5.4  max_bounces
        3.6  TURBULENCE OPTIONS
                3.6.1  exp_turb
                3.6.2  scale_turb
                3.6.3  rotate_turb
                3.6.4  vel_turb
                3.6.5  dir_turb
                3.6.6  spin_turb
                3.6.7  exp_seed
        4.0  GENERATING THE EXPLOSION
        5.0  CONTACTING THE AUTHOR

**************************************************************************


1.0  INSTALLATION
**************************************************************************
Copy the Object Exploder include file (Explode.inc) to one of the
directories (folders) in your POVRay library path.  Normally this is the
INCLUDE sub-directory of the directory where you installed POVRay, so if
you installed POVRay in C:\POVRAY you should copy the Explode.inc file to 
C:\POVRAY\INCLUDE.  On a Windows 95 system, this is probably something 
like:

   C:\Program Files\POV-Ray for Windows\Include

On UNIX and similar systems, where filenames are case-sensitive, you may
have to rename the include file so that it starts with a capital and the
rest of its letters are lowercase.  If you want to render the sample
files you should also check that the naming of Map.gif is as shown.  This
will enable you to render the sample files without modification.


2.0  QUICK START
**************************************************************************
The Object Exploder include file will take any existing POVRay object,
from a simple sphere to a complex CSG object, and explode it into a mass
of animated particles.  There are many options you can use to affect the
way the explosion occurs; to use any of these you simply add the following
line to your POVRay scene file:

   #declare [variable-name] = [value]

substituting the desired variable name and value where appropriate.  After
you have declared all the options you want to use, you add the following
line to your POVRay scene file:

   #include "Explode.inc"

The Object Exploder include file will then automatically create the
animated explosion for you.  Although only one option is required to
create an explosion (explode_object) you will want to use the options
listed below to ensure you get the sort of explosion that you want.


3.0  OPTIONS
**************************************************************************

3.1  A NOTE ON UNITS
********************
When using the Object Exploder options you will discover a number of
variables that must be specified as a certain number of units.  Just as in
POVRay the units you wish to use are entirely up to you, eg. you may
specify the object size in microns or miles, and the explosion clock in
milliseconds or days.

The important thing is that you keep the units that you use in a
particular scene file consistent for that entire file, eg. if you are
measuring distances in metres and time in seconds then speeds should be
expressed as metres per second.  This will ensure that you get the results
you expect, and will save you a lot of trouble.


3.2  OBJECT OPTIONS
*******************
The first step when using the Object Exploder include file is to specify
a number of parameters that identify the object you wish to explode, as
well as it's position in the POVRay universe.

3.2.1  explode_object
*********************
This parameter indicates the object you want to explode, and can be either
a predefined object or a completely new object definition, including
textures and transformations, eg:

   #declare explode_object = object {MyObject scale 3}
   #declare explode_object = sphere {<0, 5, 0>, 3 pigment {Red}}

Any POVRay object can be used, including CSG objects and triangle meshes.

After you have specified the explode_object you must declare a number of
variables that indicate the size and position of the object.  Four vectors
can be used for this, but only two are needed, and only the first two
found will be used.  For the best results you should try to make these
measurements as accurate as possible.

3.2.2  object_centre
********************
This specifies the exact centre of the explode_object, and is best used
when exploding spherical or cylindrical objects.

Note: object_center can also be used to specify this variable.

3.2.3  object_size
******************
This specifies the X, Y, and Z dimensions of the explode_object, eg. if
the explode_object was a sphere with a radius of 1 then the size would
be <2, 2, 2>.

3.2.4  object_corner1
*********************
This specifies the lower-left hand corner of the object, and is best used
when exploding box-like objects.

3.2.5  object_corner2
*********************
This vector specifies the upper-right hand corner of the object.

3.2.6  object_hollow
********************
This is a true / false value that indicates whether the explode_object is
to be considered as a surface model only, or as a solid object.
If object_hollow = true (default) then the object is considered to be
hollow inside, and particles are created from the surface of the object.

If object_hollow = false then the object is considered to be solid, and
when it is exploded particles will be created inside the object as well as
on the surface.  Note that this may not work with all objects (eg.
triangles, polygons) as they do not have clearly defined insides and
outsides.

3.3  PARTICLE OPTIONS
*********************
After you have specified all the desired object variables you can specify
a number of options which will adjust the shape, size, and number of
particles created when the object is exploded.

3.3.1  particle_res
*******************
This is the most important of the particle options, and specifies the
number of particles to create.  It should be specified as a vector, but
may be specified as a float (eg. 3 = <3, 3, 3>).  When the object is
exploded it is broken up into a grid of particles, with the number of
particles in each direction taken from the X, Y, and Z components of
this vector, eg. #declare particle_res = <7, 3, 5> will create 7
particles in the X direction, 3 in the Y direction, and 5 in the Z
direction, which gives 7 * 3 * 5 particles, or 105 particles in total.

Each component of the vector can be 1 or larger.  However, adjusting
this variable can drastically alter the speed it takes to generate the
explosion, so keep this in mind when trying larger numbers.

3.3.2  particle_object
**********************
This specifies the shape of the individual particles created by the
Object Exploder, and should generally be a unit sized object centred
around the origin (the default is box {<-.5, -.5, -.5>, <.5, .5, .5>}).

The particle_object can include texture information, but this will
only be used if object_hollow = false.  Note also that this will give
all particles the same texture; if you want the particles to be
textured based on their location inside the object you should use the
particle_texture option.

3.3.3  particle_texture
***********************
This specifies the texture of the inside of the object, and will only
be used if object_hollow = false.  Using this option allows you to
texture particles differently according to their position within the
object, eg. if you use a gradient that goes from white at the bottom
of the object to red at the top, any particles from the bottom of the
object will be white while any from the top will be red.
The default particle_texture = texture {pigment {rgb <.5, .5, .5>}}

3.4  EXPLOSION OPTIONS
**********************
The following parameters specify the actual characteristics of the
explosion itself (ie. the force that breaks apart the object).

3.4.1  exp_location
*******************
This specifies the vector location of the explosion, and determines the
direction in which the particles will move after the explosion, eg.
making this the same as the object_centre will explode the particles
outwards in all directions, while placing this below the object will
explode the particles upwards.  By default this is at the origin.

3.4.2  exp_strength
*******************
This specifies the force of the explosion.  It is actually the velocity
given to each particle at the start of the explosion.  Larger numbers
will make the objects explode more quickly, while smaller numbers will
make the explosion seem smaller.  Specifying 0 for this option will
not actually move the particles, and is useful for giving the impression
of an object that cracks without actually blowing up (it is best used
with the exp_gravity option).

Specifying negative numbers will cause the particles to move in the
opposite direction, and can be used to create an imploding object,
rather than an exploding object.

3.4.3  exp_falloff
******************
Normally all particles are given the same velocity (specified by
exp_strength) at the start of the explosion, regardless of their distance
from the explosion itself.  You can use the exp_falloff option to make
particles further from the explosion receive less of the explosion's
force than particles that are near the explosion.  The number specified
actually indicates the distance at which the exp_strength drops to 25% of
its original strength, eg. #declare exp_falloff = 10 means that a particle
10 units away from the exp_location will only receive 25% of the force
specified by exp_strength.

3.4.4  exp_gravity
******************
This specifies the strength of the force of gravity, declared as a float
(NOT a vector).  Normally this is 0 (ie. no gravity), but specifying
otherwise will cause particles to be pulled to the ground.

3.4.5  exp_sky
**************
This specifies the direction vector that points in the up direction
(normally this it y, ie. <0, 1, 0>).  It works in a similar way to the
sky keyword in the POVRay camera, and it useful when using a different
coordinate system (eg. #declare exp_sky = z if the z-axis points upwards).
This vector determines the direction of the gravity (opposite to the sky,
of course) and is also used as the normal of the ground plane if one
is specified (see section 3.5).

3.4.6  exp_spin
***************
This option can be used to cause the exploded particles to spin as they
move through space.  It can be specified as a vector or float, and
indicates the number of spins to make per each unit of time, eg.
#declare exp_spin = <.5, 1, 0> will spin each particle 180 degrees about
the x-axis and 360 degrees about the y-axis for every unit of time that
passes.  Usually it is easier to #declare this option as a float value
that indicates the amount of spin you wish to give each particle, eg.
#declare exp_spin = .3

3.5  GROUND PLANE OPTIONS
*************************
The Object Exploder include file has the ability to add a ground plane
to the scene.  If a particle hits this plane it can automatically rebound
off it or it can stop and come to rest on the plane.
Note that the Object Exploder include file will not actually create a
ground plane object for you, giving you the option to use any sort of
object you like to represent the ground.

3.5.1  ground_plane
*******************
This is a true / false value that indicates whether a ground plane is
present or not.  Normally this is false, but setting it to true will
cause the Object Exploder to check each particle's movement against
this plane to see if it rebounds or stops.  Also, any particles
underneath the plane will not be created.

3.5.2  ground_dist
******************
This specifies the distance of the ground from the origin, and is the
same as the distance value as specified in the plane object.  Note that
the normal direction of the plane is always the same as exp_sky (the
default if <0, 1, 0>; see section 3.4.5).  Normally the ground_dist = 0.

3.5.3  ground_reflection
************************
This specifies the amount of energy a particle retains after hitting the
ground plane.  ground_reflection = 1 means that the particles retains
all it's energy, and will bounce back to the same height each time
it hits the ground.  ground_reflection = 0 means that the particle retains
none of it's energy after hitting the plane, and therefore it comes to
a stop.  Values in between 0 and 1 will cause the particle to bounce
less high each time it hits the plane, eventually coming to a stop.
Values larger than 1 will cause the particle to bounce higher each time
it hits the plane.

3.5.4  max_bounces
******************
This option specifies the maximum number of times a particle will rebound
off a plane before coming to a stop (even if ground_reflection >= 1).
This is necessary because of the way the rebounds are calculated: each
time a particle is checked for rebounds all the particles rebounds prior
to the current rebound need to be recalculated (this is a limitation in
the way POVRay handles variables from frame to frame in an animation).
This means that on a particle's second rebound the first rebound has to
be calculated again, while on the third rebound the first and second
rebounds have to recalculated.

Because calculating each rebound requires solving a quadratic equation
as well as a number of other calculations, this can add a considerable
amount to the time needed to generate the explosion.  For this reason,
you can use the max_bounces option to limit the number of bounces a
particle will make.  By default this is set to 1 (ie. each particle
will bounce once, and then stop).  Setting it to 0 will stop particles
bouncing at all, while increasing the number will allow particles to
bounce more times before coming to a stop.

3.6  TURBULENCE OPTIONS
***********************
By default the Object Exploder include file creates the explosion
particles in a perfect grid (specified by the particle_res option), and
each particle is the same size, and travels at the same speed.  While this
is fine for some explosions it is less than realistic.  To remedy this you
can add turbulence to the explosion, adding a little randomness to each
particle's size and speed.

3.6.1  exp_turb
***************
This option controls the overall amount of turbulence added to the
explosion (normally this is 0).  Good values range from 0 (no
turbulence) to 1 (lots of turbulence), but any value can be used.
Changing this value will add equal turbulence to all aspects of
the explosion.  If you wish to adjust the turbulence of individual areas
of the explosion you can use the following parameters.   (Note that all
the individual turbulence options are multiplied by exp_turb to find the
final turbulence, so you will have to make sure that exp_turb is not 0
before using the other turbulence options).

3.6.2  scale_turb
*****************
This option controls the amount of turbulence added to the scaling of the
particles.  It is specified as a factor of the particle size,
eg. scale_turb = .5 will give particles scaled up to 50% larger or smaller
than normal.

3.6.3  rotate_turb
******************
This option controls the amount of turbulence added to the rotation of the
particles.  It is specified as a fraction of 360 degrees,
eg. rotate_turb = .1 will give particles rotated up to 36 degrees away from
normal.

3.6.4  vel_turb
***************
This option controls the amount of turbulence added to the velocity of the
particles.  It is specified as a factor of the particle velocity,
eg. #declare vel_turb = .3 will give particles with velocities up to 30%
more or less than normal.

3.6.5  dir_turb
***************
This option controls the amount of turbulence added to the direction of the
particles movement.  It is specified as a fraction of 360 degrees,
eg. #declare dir_turb = .2 will give particles that move up to 20 degrees
away from normal.

3.6.6  spin_turb
****************
This option controls the amount of turbulence added to the spin of each
particle, and only applies when you have specified a non-zero value for
exp_spin (see section 3.4.6).  It is measured as a factor of the total spin
amount, eg. #declare spin_turb = .7 will give particles that spin up to 70%
more or less than normal.

3.6.7  exp_seed
***************
This option specifies that random number seed used when adding turbulence to
the explosion.  Normally this is 0, but any integer value can be used.


4.0  GENERATING THE EXPLOSION
**************************************************************************
After you have declared all the desired variables you have to specify the
explode_clock variable (and then include the "Explode.inc" file, of course).
This variable indicates the current time value of the explosion, where 0 is
just before the explosion starts.

Normally the explode_clock is equal to POVRay's internal clock variable.
This may not, however, be what you require for a particular animation.
Because of this you are given the option to #declare explode_clock to be
any value you want.  

You can use this to create still scenes from a particular way through the
explosion, eg. #declare explode_clock = 1.47 will create a still scene of
the explosion 1.47 units of time after it started.  (Note that when
explode_clock is less than or equal to 0 the explode_object is placed in
the scene without being altered at all).

Usually you will declare explode_clock to be some function of POVRay's
internal clock variable.  Sometimes this will be as simple as:

   #declare explode_clock = clock * 5

which will create an explode_clock that goes 5 times as fast as the
internal clock.  You could use 0.5 to make the explode_clock half as fast as
the internal clock, or any number you wish.

Sometimes, however, you might want a more complicated explode_clock, such
as one that starts only at a particular time, or one that goes backwards,
or one that starts fast and slows down.  All of these can be easily
accomplished using POVRay's various float functions, and the #if and #switch
directives.

For some examples of using explode_clock in this way take
a look at the sample animations that came with the Object Exploder include
file.


5.0  CONTACTING THE AUTHOR
**************************************************************************
If you wish to contact me with bug reports, bug fixes, criticisms, 
comments, suggested improvements, questions, etc. you can reach me by 
email at:

   ccolefax@geocities.com

or by regular mail at:

   Chris Colefax
   PO Box 110
   Kuranda, Queensland
   Australia  4872

**************************************************************************

POV-Ray(tm) and Persistence of Vision(tm) are registered trademarks of the
POV-Ray Team(tm)
