# Sprays

RenderWorld provides the capability to generate and render a time evolving, 3D spray field. Depending on the density and scattering parameters this can be used to simulate a range of effects such as water spray, evolving clouds, or smoke. In this section, we concentrate on the creation of a water-like spray.

The spray is created by building sources of the spray and its interaction with the air around it. The spray evolution can contain the effects of buoyancy, vorticity, turbulence, windshear and vortical motion.

As with clouds, the lighting of the spray is affected by the incident sun and air light. The user can specify the strength with which light is scattered and absorbed. Advanced users can also modify the angular dependence of the scattering.

### Adding a Spray Volume to a Scene

A spray is added to a scene by specifying the object `type` :`spray` in the scene file. The object coordinates correspond to the location and orientation of the center of the spray box. An example of a spray object entry using a spray object file spray.dat in a scene file is:

  `number_of_times` `1`
  `time x y z theta phi chi`
  `0 10 0 0 0 0 0`
  `name:` `spraything`
  `type:` `spray`
  `input:` `spray.dat`
  `priority:` `2`

``

### The Spray File

The contents of an example spray file are shown below. Many of the lines in it are familiar from other object files.

  `RenderWorld_data_file volume 1 1`
  nx `216`
  ny `216`
  nz `64`
  dx `12`
  dy `12`
  dz `15`
  `number_of_bands 3`
  `band_id 1 2 3`
  absorption `0.025 0.025 0.025`
  scattering_coefficient `0.1 0.1 0.1`
  extinction_coefficient `0.025 0.025 0.025`
  phase_function_file `phase_functions.dat`
  threshold_density `0.01`
  scattering_flag `multiple`
  integration_step `0.125`
  transmission_cut `0.01`
  sub_res_threshold `0.004`
  `end`
  ``
  `RenderWorld_data_file spray 5 5`
  initial_time `0`
  final_time `100`
  output_density_at_end `yes`
  density_file `density.dat`
  ``
  slice_the_spray `yes`
  slicex `0`
  slicey `0`
  slicez `15`
  ``
  taper `yes`
  taperx `250`
  tapery `250`
  taperz `150`
  taper_power `0.5`
  ``
  number_of_sources `1`
  ``
  spray_shape `gaussian`
  spray_velocity `50`
  spray_angle `0 0`
  base_orientation `z`
  spray_width `100.0`
  spray_start_time `0`
  spray_duration `100`
  spray_ramp_time `0.1`
  spray_center `64 64 64`
  source_density `1.0`
  ``
  ambient_type `wind`
  ambient_velocity `0`
  ambient_angle `15 90`
  ambient_height `1000.0`
  delta_time `0.1`
  ``
  reference_density `4.0`
  air_density`0.001`
  gravity_flag `full`
  ``
  random_fluctuations_flag `no`
  ``
  small_scale_fluctuatuion_flag `no`
  `end`

The lines prior to the line `RenderWorld_data_file spray 5 5` are identical in structure and meaning to those used in clouds. The section on Clouds describes them in detail. The lines from `RenderWorld_data_file spray 5 5` on are specific to sprays, and blobs have a similar structure, as described in the section on Blobs.

The parameters `initial_time` and `final_time` determine when to turn on the spray volume evolution, and turn it off. After `final_time`, the distribution is written to a file if desired, and the spray is frozen in time in subsequent frames.

Following this, you specify whether you want to output the density of the spray at the end of the simulation by putting `yes` or `no` after output_density_at_end. If you choose `yes`, then you put the name of the output file after `density_file` on the next line. If you choose `no`, then eliminate then line `density_file` from the input file. The density file is a binary file that gives the particle density at each point in the box. The density that has been written to a file can be used in the cloud or blob objects.

During the evolution of a spray (or blob), cloud material may be transported out of the boundaries of the box. When this happens, there is an obvious visual cue to the bounding box. To eliminate this, the operations of slicing and tapering the edges are provided. Keep in mind that the operations affect the appearance of the cloud material distribution during rendering time, but only apply as an optical effect. The 3D distribution of material in the box is not affected by slicing and tapering.

Slicing is a process of apparently moving the three sides of the bounding box which intersect the box origin inward from the box edges. Thus `slicex, slicey, and slicez` are the distance inward in meters each of the three sides are moved in. One useful result of slicing is that spray source nozzles lying between the bounding box edge and the slice walls are not visible in a rendered image, giving the spray a chance to evolve somewhat before being visible.

The second method of dealing with material passing close to or through the bounding box edges is tapering the density from its full strength within the volume, to zero at the edges. When tapering is chosen, the `taperx, tapery, taperz` parameters are the distance inward from the box edges affected by tapering. If slicing has also been chosen, the slice edges are used for measuring the taper distance. The cloud material density is tapered with a taper coefficient in each of the three directions. The taper coefficient is zero at the edges, one at the inside distance, and varies between these extremes according to a power-law specified by `taper_power` .

### Spray Source

The next part of the spray file provides the spray source characteristics. The source is a nozzle that emits particles for a period of time. The distribution of the material emitted over time and space can be partially controled. The first parameter specified is the spatial shape of the nozzle. The gaussian shape emits material with a gaussian-shaped cross section across it. The option `spray_shape` `flat` has uniform density across the nozzle. As material moves out of the nozzle, its speed is given by the `spray_velocity` line, and its absolute angle is `spray_angle` `0 0` , with the angles corresponding to elevation and azimuth.

Even though the spray can be emitted at any angle, the nozzle cross-section must be oriented along one of the major axes of the bounding box. This the parameter choices `base_orientation` `z,` `y`, or `x` control the nozzle orientation. The width of the circular cross section of the spray nozzle is given by `spray_width` . Emission of material begins at physical time `spray_start_time` , and stops `spray_duration` seconds later. After stopping, the spray material in the bounding box will continue to evolve with whatever wind is present. During the initial `pray_ramp_time` seconds, the magnitude of emitted material is ramped up from zero to `source_density` . The center of the spray nozzle is located at `spray_center`. which is given in cell units, not physical units.

### An Array of Sprays Sources

As the line number_of_sources `1` might suggest, any number of spray sources can be placed in the spray bounding box. To accomplish this, replace `1` by the appropriate number of sources, and repeat lines `spray_shape` through `source_density` with new parameters for each source.

### Windshear Evolution

The `ambient_wind` part of the spray file specifies the types of advective wind carrying spray material throughout the volume. There are two types: an ambient windshear and a vortex. This wind is not to be confused with turbulence, which is included separately, as discussed in the section below on turbulent evolution.

The choice of the ambient windshear is specified by setting `ambient_type` `wind` . The wind velocity starts at zero at the bottom of the bounding box, and increases linearly to the `ambient_velocity` at the `ambient_height` (in meters), with direction `ambient_angl`e. Above this height the wind velocity remains at the `ambient_velocity`. The spray shape is updated periodically in time at intervals separated by `delta_time` seconds.

### Vortex Evolution

The alternative motion to windshear is vortex motion. RenderWorld is capable of generating very complex motion patterns in a cylindrical geometry. To generate this type of motion, the `ambient_type` is changed to `ambient_type` `vortex`, and a sequence of lines defines a procedural form for the wind. An example of the vortex type is:

  `ambient_type` `vortex`
  `core` `1`
  `n_radial` `2`
  `v_radial` `-0.00005`
  `p_radial` `2`
  `v_radial` `500`
  `p_radial` `-2`
  `n_theta` `1`
  `v_theta` `200.0`
  `p_theta` `0`
  `n_z` `1`
  `v_theta` `-0.001`
  `p_theta` `2`

In the cylindrical geometry, a central core region is defined with a radius given in the `core` `1` line, e.g. 1 meter. Within this region, the vortex wind velocity on the outside boundary of the core is smoothly tapered to zero at the center. Throughout the rest of the spray bounding box, the cylindrical components of the velocity field are created as power series in either the radius or height. In the example above, the radial velocity has two terms in its power series expansion, as given by the `n_radial` line. Each term is characterized by a pair of numers, one for the power of the radius used `p_radial`, and one for the coefficient `v_radial`.. When applied, the radius is scaled by the core radius. In equation form, the radial velocity in the above example is:

Similarly, the angular velocity in the direction perpendicular to the radial direction is defined as a power series in radius, following the same format: give the number of terms in the power series, followed by pairs of numbers for the coefficient and power of each term. The vertical velocity component follows exactly the same procedure, but here the power series is in the height from the center of the bounding box.

### Buoyant Force

Next, the parameters for the buoyant evolution are specified. The `air_density` is the density that neither rises or falls in the presence of gravity. Densities greater than the `air_density` fall, and those less rise. To control the degree of rising and falling, set the `reference_density` parameter. Specifically, the acceleration experienced by a given density is calculated by

`acceleration = earths_gravity * (density - air_density)/reference_density`

so that a high reference density diminishes the effect of gravity and a low reference density enhances it.

Finally, the specific way that spray couples to gravity is determined by setting `gravity_flag`. A value of `full` gives full buoyant evolution, a value of `yes` turns off buoyancy and simply gives each density an acceleration equal to earths_gravity, and a value of `no` turns off all gravitational effects.

### Turbulent Evolution

Turbulence is creted by changing `random_fluctuations_flag` to `yes` from `no`. When set to `yes`, turbulence is present and a group of parameters that specify the turbulence must be included. The result looks like:

  `random_fluctuations_flag` `yes`
  `seed` `10`
  `time_scale` `1`
  `velocity_scale` `50`
  `length_scale` `300`
  `end`

The turbulence is generated from a set of random numbers, for which `seed`, is the seed from which the random numbers are generated. It must be a positive integer. The `time_scale` is the time over which the turbulent field evolves. The evolution of the turbulent field is itself random, so this time is effectively the time over which the turbulence becomes uncorrelated with its previous state. The `velocity_scale` is the average velocity of the turbulence, which determines how strongly the turbulence deviates from the ambient wind motion. The value of this relative to the spray source velocity determines how much distortion the turbulence generates in the spray jet. Finally, the turbulence is on scales as small as the cell size up to the scale `length_scale`.

### Small Scale Structure

Running a large spray with a cell size spacing can eat up a lot of memory. In order to get around this problem, RenderWorld allows you to introduce small scale structure into the spray without having to use a fine lattice spacing in the bounding box. This is accomplished by adding a second grid, called the small-scale grid. The small-scale grid is a small periodic grid of fluctuation parameters that evolve in time, and plays a role like that for clouds. The density at any point in space is determined by combining the density of the spray field with the small-scale field.

The last part of the spray input file gives you the ability to add a small scale fluctuation field to the spray. If you want to add small scale fluctuations, then set`small_scale_fluctuations_flag` to either `yes` or `dynamic`. If you set the flag to `yes`, then the parameters of the small scale fluctuation are as follows:

  `small_scale_fluctuatuion_flag` `yes`
  `nx` `64`
  `ny` `64`
  `nz` `64`
  `scale` `0.33333`
  `fluctuation` `0.33`
  `power_law` `2`
  `length` `150`
  `seed` `11011`
  `end`

The first three parameters (`nx`, `ny`, and `nz`) specify the number of cells in the small scale fluctuation box. The cell size is some fraction of the cell size of the spray box, specified by a number less than one after `scale`. The value of scale should be determined by the ultimate resolution you want in the spray. The number of lattice points should then be picked so that the total volume of the fluctuation field overlaps a reasonable number ( typically > 5 in each dimension) of spray field cells. This is necessary so that the periodicity of the small scale field is not apparent in the final images.

The magnitude of the fluctuations is determined by setting `fluctuations`. The parameter `fluctuations` can be any number greater or equal to zero. A value of zero corresponds to no fluctuations and a value of one can provide large fluctuations.

Although the fluctuations are random (the random number series is based on the `seed` parameter), they are correlated in space and time. The `power_law` controls the rate of fall-off of the correlation with distance (similar to a fractal dimension), and the `length` is the largest spatial length scale of fluctuations.

These small scale fluctuations do not evolve in time. For evolving fluctuations, the `small_scale_fluctuatuion_flag` should be set to `dynamic` and this portion of the input file becomes:

  `small_scale_fluctuatuion_flag` `dynamic`
  `nx` `64`
  `ny` `64`
  `nz` `64`
  `scale` `0.33333`
  `small_scale_fluctuation_file` `fluct.dat`
  `generate_file` `yes`
  `fluctuation` `0.33`
  `power_law` `2`
  `length` `150`
  `seed` `11011`
  `reference_time` `0`
  `update_time` `0.1`
  `sigma` `16.0`
  `end`

This choice for the small scale fluctuations is identical to the `dynamic` choice for cloud small scale fluctuations described in that section.

Contents