|
LIQUID SPRAY INCLUDE FILE for Persistence of Vision 3.x
|
Created by Chris Colefax, 23 May 1997
Updated 13 August 1998: updated for POV-Ray 3.1
INSTALLATION
QUICK START
OPTIONS
TROUBLESHOOTING
COPYRIGHT AND LEGAL INFORMATION
CONTACTING THE AUTHOR
Copy both include files (Spray.inc and SprayG.inc) to one of the
directories (folders) in your POV-Ray library path. Normally this is the
INCLUDE sub-directory of the directory where you installed POV-Ray, so if
you installed POV-Ray in C:\POVRAY you should copy the files 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 files so that the case of the letters of both files is as shown above.
This will enable you to render the sample files without modification.
The Liquid Spray include file allows you to generate a whole range of
spray-type particle objects, such as fountains, hoses, waterfalls, fireworks, etc.
There are many options you can use to affect the way the spray is generated; to use any of these you simply add
the following line to your POV-Ray 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 POV-Ray scene file:
#include "Spray.inc"
The Liquid Spray include file will then automatically create the spray
object for you. Although you don't have to use any of the options (the
include file will use defaults if you don't specify a variable), you
will want to use the options listed below to ensure you get the sort of
spray object that you want.
Note that the Liquid Spray Include File should never be included at the start of a scene, like colors.inc or textures.inc. It should only be included after declaring all the options you want to use.
BASIC OPTIONS
The variables in this section control the basic features of the liquid spray, and should generally be the first variables you declare.
spray_location
This vector specifies the point from where the spray object originates,
ie. the point where the spray particles first appear.
The default value for spray_location is < 0, 0, 0>
spray_direction
This vector specifies the direction of the spray object, ie. the initial
direction of the spray particles.
The default value for spray_direction is < 0, 1, 0>
spray_strength
This number specifies the strength of the spray object, ie. the initial
speed of the spray particles.
The default value for spray_strength is the length of the spray_direction.
TIME OPTIONS
The following variables control how the spray object is animated (in relation to POV-Ray's clock variable).
spray_loop
This true / false variable specifies whether or not to generate a
perpetually looping spray object (for cyclic animations). If spray_loop
is true, then the spray object will be visible throughout the animation,
and it will have a constant spray_strength. If spray_loop is false, you
can use the following options to control how the spray object is turned
on or off:
spray_start
This number specifies the time to turn on the spray object, eg. if you
use spray_start = 0.5; then the spray will turn on halfway through the
animation (presuming the animation clock goes from 0 to 1).
The default value for spray_start is 0
spray_stop
This number specifies the time to turn off the spray object, eg. if you
use spray_stop = 0.5; then the spray will turn off halfway through the
animation.
The default value for spray_stop is 1
spray_start_time
This numbers specifies the time it takes for the spray to reach full
strength, eg. if you use spray_start = 0.1; and spray_start_time = 0.3; then
the spray object will reach full strength at clock = 0.4
The default value for spray_start_time is 0
spray_stop_time
This number specifies the time it takes for the spray to turn off, eg.
if you use spray_stop = 0.7; and spray_stop_time = 0.2; then the spray object
will start to run down at clock = 0.5, and be fully stopped by clock = 0.7
The default value for spray_stop_time is 0
PARTICLE OPTIONS
Each spray object contains a number of particles. You can use the options
in this section to specify the characteristics of these particles.
particle_count
This number specifies the number of particles used to create the spray
object. If spray_loop is true, then the spray object will always contain
the same number of particles. If spray_loop is false, then the number of
particles will change as the spray is turned on and off.
The default value for particle_count is 100
particle_life
This number specifies how long each particle is alive, eg. if you use
particle_life = 1.5, then each particle will disappear after 1.5 units
of time. If spray_loop is true, then the spray object will be automatically
adjusted so it always loops correctly.
The default value for particle_life is 1
particle_size
This number specifies the size (in POV units) of each spray particle. It
is actually the radius of the spheres or blob components that make up the
spray object.
The default value for particle_size is 1
particle_stretch
This number specifies how much to stretch the spray particles by. Numbers
larger than one make the particle thinner and torpedo shaped, giving the
effect of movement. Numbers smaller than one make the particles look like
discs (not usually recommended!).
The default value for particle_stretch is 1 (ie. no stretch).
particle_dist
This option can be used to generate a mixture of larger and smaller
particles, rather than all the particles being the same size. The number
used specifies the size distribution of the particles, ie. the ratio of
small particles to large particles:
1 - equal numbers of small and large particles
0 - all large particles
between 0 and 1 - more large particles than small particles
larger than 1 - more small particles than large particles
The default value for particle_dist is 1
particle_sep
This option can be used to separate the smaller particles from the larger
particles, giving the effect of a fine spray surrounding the main spray
object. It has no effect if particle_dist is 0. Setting particle_sep
to 0 specifies no separation between the differently sized particles,
while numbers larger than 0 increase the separation.
The default value for particle_sep is 0
evaporate
This number specifies the rate of evaporation of the particles. Setting
this option to 0 specifies no evaporation, while numbers larger than 0
will cause the particles to grow smaller until they disappear at the end
of their lives (see particle_life). The larger the number, the
faster the particles disappear.
The default value for evaporate is false (zero).
NOZZLE OPTIONS
The following options control the characteristics of the spray nozzle:
nozzle_spin
This option specifies the number of spins the nozzle makes per unit of
time. Setting nozzle_spin to 0 will stop the nozzle from spinning.
Negative numbers can be used to spin the nozzle in the opposite direction.
The default value for nozzle_spin is 1
nozzle_angle
This option specifies the angle (in degrees) of the spray nozzle. If you
think of the spray object as a cone, with its apex at spray_location, this
number is the angle at the apex of the cone (similar to the radius option
in POV-Ray's spotlight).
The default value for nozzle_angle is 20
nozzle_width
This option can be used to widen the nozzle, for waterfalls and other
similar spray objects.
The default value for nozzle_width is 0
BLOB OPTIONS
Normally the spray object is generated as a union of spheres. You can use
the following options to generate the spray object as a blob object
instead:
use_blob
Setting this option to true will cause the spray object to be generated
as a blob. The default value for use_blob is false.
blob_threshold
This number specifies the threshold of the blob used to create the spray
object (see the POV-Ray docs for more information on blob thresholds).
The default value for blob_threshold is .5
components_only
This option can be used to generate blob components only, rather than a
complete blob object. This is useful when you want to combine the liquid
spray blob with another blob (so the components interact). You will have
to place the include statement inside the blob {} object, and apply
textures manually. For an example of this, see the sample scenes that
came with the Liquid Spray include file.
The default value for components_only is false
ENVIRONMENT OPTIONS
The following options can be used to alter the environment in which the
spray object is created:
spray_gravity
This number specifies the strength of the gravity force applied to the
spray particles. Only positive numbers are accepted; the gravity force
is always in an opposite direction to the spray_sky vector.
The default value for spray_gravity is 9.8
spray_sky
This specifies the direction vector that points in the up direction.
It works in a similar way to the sky keyword in the POV-Ray camera, and
it useful when using a different coordinate system (eg. use spray_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.
The default value for spray_sky is < 0, 1, 0>
wind
You can use the wind option to blow the spray particles in a particular
direction. The direction of the wind vector is the direction in which
the wind blows, and the size of the wind vector determines the strength
of the wind force (multiplying by smaller values will create light breezes, while larger values will create strong gales).
The default value for wind is < 0, 0, 0> (ie. no wind).
GROUND PLANE OPTIONS
The Liquid Spray include file has the ability to add a ground plane
to the scene. If a spray particle hits this ground plane it can
automatically splash off it, or it can form puddles on the plane.
Note that the Liquid Spray 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.
ground_plane
This is a true / false value that indicates whether a ground plane is
present or not. The default value for ground_plane is false.
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 spray_sky.
The default value for ground_dist is 0
ground_reflection
This specifies the amount of energy a spray particle retains after splashing
off the ground plane. Setting ground_reflection to 1 means that the particle
retains all its energy, and will bounce back to the same height each time
it splashes. Setting ground_reflection to 0 means that the particle
retains none of its energy after hitting the plane, and therefore it
forms a puddle. Values in between 0 and 1 will cause the particle to
splash less high each time it hits the plane, eventually coming to a stop.
The default value for ground_reflection is 0.8
max_bounces
This option specifies the maximum number of times a spray particle will
splash off the ground plane before forming a puddle.
The default value for max_bounces is 1
ground_friction
After a spray particle stops splashing it will form a puddle which slides
along the ground. The ground_friction options specifies how quickly the
spray particle stops moving after it forms a puddle. Setting this option
to 0 causes the particle to stop as soon as it hits the ground. Setting
this option to 1 causes the particle to slide along without stopping.
Numbers in between 0 and 1 bring the particle to a gradual stop.
The default value for ground_friction is 0.5
puddle_thickness
This number specifies how thick the puddles formed by the spray particle
will be. Setting this option to 1 means that the puddles are as thick as
original particles, while smaller numbers make the puddles thinner (and
wider).
The default value for puddle_thickness is 0.3
puddle_scale
You can use this option to artificially alter the size of the puddles, eg.
puddle_scale = 2 will make the puddles twice as large as normal. This
is most useful when using blobs, as thin blobs can
sometimes cause rendering problems or become invisible.
The default value for puddle_scale is 1 (ie. no change in puddle size).
TEXTURE OPTIONS
The following options can be used to change the texture and colour of the
spray object and its particles:
spray_texture
This specifies the texture used for the spray object. You can use the
name of a predefined texture, eg: #declare spray_texture = MyTexture, or
you can specify a complete texture within a texture {} statement.
By default a plain blue texture is used.
spray_color_map
You can use this option to change the color of the spray object over time.
This option should be declared as a standard color_map, eg:
#declare spray_color_map =
color_map {[0 rgb < 1, 1, 1> ] [1 rgb < 0, 0, 0> ]}
This will cause the spray to gradually change from white at the beginning
of the animation, to black at the end of the animation.
use_color_map
You can set this option to false to turn OFF the color_map if you are
creating multiple spray objects and have already declared spray_color_map,
which you no longer want to use.
color_map_triangle
Setting this option to true will cause the color_map to go from 0 to 1,
and back to 0 (just like using the triangle_map pigment option). This
is the default if spray_loop is true; otherwise, the default value for
color_map_triangle is false.
color_map_frequency
Normally the first color of the spray_color_map is used at the beginning
of the spray, and the last color is used at the end of the spray. You can
change this option to have the color_map repeat itself more than once
through the life of the spray object, eg. using color_map_frequency = 5 will
make the color_map loop through 5 times.
TURBULENCE OPTIONS
The options in this section can be used to add randomness to certain
aspects of the spray object. You can use these options to make the
spray object more (or less) realistic.
spray_turb
This option controls the overall amount of turbulence added to the
spray object. 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 spray object. If you wish to
adjust the turbulence of individual areas of the spray object you can use
the following parameters.
Note that all the individual turbulence options are multiplied by spray_turb to find the final turbulence, so you
will have to make sure that spray_turb is not 0 before using the other
turbulence options).
The default value for spray_turb is 0
scale_turb
This option controls the amount of turbulence added to the scaling of the
spray particles. It is specified as a factor of the particle size,
eg. scale_turb = 0.5 will give particles scaled up to 50% larger or smaller
than normal.
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. vel_turb = 0.3 will give particles with velocities up to 30% more or
less than normal.
angle_turb
This option controls the amount of turbulence added to the nozzle angle.
It is specified as a fraction of the nozzle_angle option, eg.
angle_turb = 0.4 will give particles with nozzle angles up to 40% more
or less than normal.
spin_turb
This option controls the amount of turbulence added to the nozzle spin.
It is specified as a fraction of 360 degrees, eg. spin_turb = 0.1 will
give particles that spin up to 36 degrees away from normal.
color_turb
This option controls the amount of turbulence added to the color_map.
color_turb = 1 means that colors will be picked randomly from the
spray_color_map to color each particle.
wind_turb
This option controls the amount of turbulence added to the wind direction.
It is specified as a fraction of 360 degrees, eg. wind_turb = 0.2 will
give particles that are blown up to 72 degrees away from normal.
spray_seed
This option specifies that random number seed used when adding turbulence to
the spray object. Normally this is 0, but any integer value can be used.
OTHER OPTIONS
spray_clock
This option specifies the clock value you want to use to generate the
spray object. By default this is equal to POV-Ray's internal clock, so
you shouldn't normally have to use this option. However, there are a
number of interesting effects you can achieve by using the spray_clock.
If you use spray_clock = 0.6, you will get a still scene of the spray
object, as it would look at 0.6 units of time. You can also use functions
of the internal clock, eg:
#declare spray_clock = 1 - clock;
will give you a spray object that animates backwards.
time_scale
This option behaves differently, depending on the spray_loop option. If
spray_loop is true, then time_scale changes the time taken for the spray
object to complete one loop, eg. time_scale = 3 will make the spray object
loop three times per unit of time, rather than once.
If spray_loop is false, then time_scale gives the effect of increasing (if
you use a number larger than 1) or decreasing (if you use a number smaller
than 1) the speed of the spray particles. However, it has no effect
on the spray_start, spray_stop, spray_start_time, or spray_stop_time
options.
The default value for time_scale is 1
flow_rate
This option can be used to change the flow rate of the spray object, where
0 is off and 1 is full strength. Numbers between 0 and 1 give less than
full strength, while numbers larger than 1 give more than full strength.
Normally if you want to turn the spray object on or off you will use the
time options. However, you can use the flow_rate option
to create different effects, eg:
#declare flow_rate = sin(clock * 4 * pi) * .5 + 1;
will give an oscillating spray object.
Q: I have created an animation with the Liquid Spray include file but it seems to render very slowly?
A: This is probably related to POV-Ray's bounding threshold setting.
The default is 25 objects, and if your animation starts with less than this (eg. before the time set by the spray_start option), bounding will be turned off.
When the (many) particle objects are created bounding will not be enabled and rendering will be much slower than normal.
To enable bounding regardless of the number of objects in the animation's first frame, use the Bounding=0 setting in an INI file, or the +MB0 setting on the POV-Ray command line.
Q: I have set the use_blob option to true, but the spray doesn't render properly?
A: Rendering problems with blobs are usually the result of inaccurate calculations by the raytracer.
To fix the problems you can use the sturm keyword within the blob object; to enable sturmian calculations with the liquid spray, use the components_only option, eg:
#declare use_blob = true;
#declare components_only = true;
blob {threshold 0.5 #include "Spray.inc" texture {spray_texture}
sturm}
Q: I want to use the spray object with media and/or interior?
A: If you want to place media inside the spray object, or use POV-Ray 3.1's new interior to create refraction or caustics using the spray, you should follow the same directions as for other objects with interiors, ie. the textures should be partly (or wholly) transparent, and the object should be set to hollow.
To do this, simply surround the #include "Spray.inc" line in an object {} statement, and add the interior as normal, eg:
#declare spray_texture = texture {pigment {rgbt 1}}
object {#include "Spray.inc" hollow
interior {ior 1.33 media {MyMedia}}}
|
COPYRIGHT AND LEGAL INFORMATION
|
The Liquid Spray Include File, including Spray.inc, SprayG.inc, all documentation, and
associated sample *.POV files are Copyright 1997, 1998 by Chris Colefax. Full
permission is granted to the user to modify any or all of the files for
his/her own use. If modified versions are to be distributed the user
should make clear the modifications that have been made by him/herself.
The Liquid Spray Include File may be bundled with or without other
software on CD-ROM collections, Bulletin Board systems and other file
archives, providing that all associated files, including documentation and
samples, are included. I would also request that persons intending to
distribute the Liquid Spray Include File in this manner or otherwise
would first contact me to ensure that
they are in possession of the latest available version.
Further, no restrictions of any sort are placed on the usage of the include
files themselves (Spray.inc and SprayG.inc), and scene files or images created using the include
files remain entirely the property of the user or users who have created
them. I claim no liability or responsibility for damages or loss resulting
from usage of the include files, or any part of the include file package.
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-RayTM and Persistence of VisionTM are registered trademarks of the POV-Ray TeamTM