                         Fill Cylinder With Spheres
                               Version 1.1.0

Syntax:

FCWS (container_height, cantainer_radius, number_of_spheres,
      sphere_max_radius, sphere_min_radius, intersect, contain_all)

Description:

This macro fills a cylinder 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 FBWS usage.

Options:

cantainer_width:
cantainer_height:
cantainer_depth: respectively the X, Y and Z dimensions of the cylinder.
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 cylinder with too much of
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 cylinder
(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 cylinder 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 cylinder boundaries.
Set it to "no" if you want that only the center of the spheres is contained
between cylinder 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 FBWS is not able
to find a sphere that fit the box without intersect any other sphere. Read the
NOTE of "number_of_spheres" option to avoid the problem.

Version history:

1.0.0 (9/November/1998)
Initial release.


Legal note:

FCWS 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
