                        Fill Sphere With Spheres
                             Version 1.0.0

Syntax:

FBWS (cantainer_radius, number_of_spheres, sphere_max_radius, sphere_min_radius,
	  intersect, contain_all)

Description:

This macro fills a sphere with a certain number of randomly placed spheres.
The spheres can be of random size, between a min and a max values.
The spheres can intersect each other or can be placed carefully to avoid
intersections.
See the file "example.pov" for an example of FSWS usage.

Options:

cantainer_radius: the radius of the sphere to fill.
Note that it is centered in the origin.
You can then translate and rotate wherever you want.

number_of_spheres: the number of spheres to fill with. As you can guess the
larger this number the longer parsing and rendering times.
Minimum value is "1".
NOTE: if "intersect" option is set to "no" you should keep this number low and
than increase it gradually. If you fill a small sphere with too much spheres
(or of pretty big radius), POV-Ray will never end the parsing fase since FBSW
will search in eternity for a sphere that fit in the sphere (and this can be
impossible).
After some trial and error you will discover an optimal value.

sphere_max_radius: this is the maximum radius that the randomly generated
sphere size can have.
It cannot be lower than "sphere_min_radius".
NOTE: to fill a sphere with spheres of the same radius simply set
"sphere_max_radius" and "sphere_min_radius" to the same value.

sphere_min_radius: this is the maximum radius that the randomly generated
sphere size can have.
It must be a positive value.

intersect: set this option to "yes" if you want to allow the spheres to
intersecate.
Set it to "no" if you want the sphere to be place in a way to avoid
intersections (the surfaces of the spheres can "touch", however).
NOTE: use the "no" option carefully since it may dramatically increase parsing
time (the parsing time may became infinite, see the NOTE of "number_of_spheres").

contain_all: set this option to "yes" if you want the sphere to be completly
contained between sphere boundaries.
Set it to "no" if you want that only the center of the spheres is contained
between sphere boundaries.

Known Problems:

- There is no way (known to me) to avoid POV-Ray to engage a infinite loop during
parsing if the "intersect" option is set to "no" and FSWS is not able to find
a sphere that fit the container shpere without intersect any other sphere.
Read the NOTE of "number_of_spheres" option to avoid the problem.

Version history:

1.0.0 (8/November/1998)
Initial release.


Legal note:

FSWS is freeware and you can use it freely. It can be distribuited in any
way but only if this readme is provided.
However is not public domain and remains propierty of the author.
Modified versions of the macro can be distribuited but a note regarding
the author of the original one is greatly appreciated.


I would thank all the POV Team for their efforts and to bring us the macros
wich are just a marvelous dream (and I won't wake up!)  :)
Comments, suggestions, and ideas for future macros are encouraged.

Diego Krota

e-mail:    dkrota@geocities.com (if this address may be no longer valid in future
go to my Home Page and you will find the new address)

Home Page: http://www.geocities.com/SiliconValley/Way/2419

POV-Ray Macros: http://www.geocities.com/SiliconValley/Way/2419/POVMacros.html
