River tutorial: Part 4.

Foam on the river

In this chapter we shall deal with foam simulation on the river surface. Foam in World
Builder is a specific material, which is designed to simulate the foamy stuff spreading
downstream in a turbulent water flow, in the crests of surf waves, etc. The foam
pattern once created will not remain the same but will change with animation time
(frame by frame) in agreement with river flow speed and speed profile (see below).
Important note. Foam belongs to the so-called object-dependent type of shaders, it is
specially designed for the river surface. It imposes some restrictions on its usage. See
Appendix at the end of this document.
We shall begin with an AWB project containing a simple landscape with a stream
flowing in the forest. Open projects /RiverPart1.awb file and render the scene in
Camera01 window using the Production Rendering mode (
toolbar). In a minute the camera view will look like:

button at the main

Our goal is to speed up this quiet flow making it turbulent. To achieve this we have to
add some obstacles to the river channel. Suppose that our river has just come to the
forest from a mountain country so that its bottom may be stony and some stones may
be seen from under the water.
First of all let us outline an area on the river where we want to see stones.

Area
Select River_0 in the Objects Tree. When the river is selected the Area Creation
button appears in the object-specific part of the toolbar:

Click this button to enter the Area Creation / Editing tool. Now you can create area

points by left clicks at any viewport. However, you have always remember that area's
points must belong to the river surface. That is why the mouse cursor may change its
icon when you move it over some viewport.
This icon shows that an immediate left click at the cursor location in the
viewport will add a new vertex to the area being created. The vertex will appear just
at the point of intersection of a ray outgoing from the current mouse location in the
direction of the current view with the river.
This icon shows that a new vertex cannot be created because a ray outgoing
from the current mouse location in the direction of the current view does not intersect
the landscape. Thus, a new area on the landscape may be created in a viewport if the
mouse cursor lies within the landscape projection onto this viewport.
Tip: The best view for area creation on the river surface is the top view. However, we
want to see how the new area is seen through the camera viewport. To make the
camera view re-draw immediately every area point being created in the top view,
button at the main
render the scene in the camera view using Skeleton mode (
toolbar)
In the top view locate the mouse cursor somewhere inside River_0 in the vicinity of
the camera, press the left mouse button and draw a closed shape without releasing the
button. The area (shown by the red line in the picture below) should look
approximately like:

To finish with the river area release the left mouse button and press the right button.
The area on the river surface is ready. Its default name in the scene is Area 2. Now we
have to add some stones to the area.

Stones from Library

In the main menu choose Library / Stones as shown in the left panel below. The
Stone20.odb is loaded to the library window. In the left sub-window select Stones /
misc. Stones. Images of stones appear in the right sub-window of the library
window. Select stone1. Make sure that River_0 is selected (highlighted) in the Object
Tree. Then catch stone1 from the library by left mouse click on its icon and drag the
item to the top view. When the mouse cursor is over rivers Area 2 release the left
button.

As you have dropped stone1 to Area 2, the program will ask you about the type of
object distribution:

We shall choose Scattered Shaded Objects type (this is a uniform objects

distribution). Select Scattered Shaded Objects and click OK. Stone1 is uniformly
scattered in Area 2 on the river.
However, to see the stones distributed in the rivers area we still have to adjust
scattering parameters.

Scattering Parameters.
Size and Density.
In the Property Tree of Area 2 select Area 2 :ON / Scattered Object / Size & Density.
The Size and Density dialog appears in the bottom window of the Property Editor:

This property sets the overall size and spacing of the objects. The size of individual
objects varies randomly between minimum and maximum settings.
The default value 50 units for the average distance between scattered objects is too
large for our river area. To make our stones more dense, decrease the default value of
the average distance from 50 to 8. Also, we have to make the stones smaller. Set the
height range to maximal height 4, minimal height 3 and render the camera view.

A pair of important notes before we finish with this dialog.

1. Note that varying the Random Seed you generate a unique random pattern of sizes
and locations. Different numbers produce different patterns. There is no way to
predict the pattern that a particular seed number will produce, but the same number
will always generate the same pattern.
2. Proportional scale means that changing the instance's height we change the rest
dimensions, proportionally. If you want to increase the the only height, length or
width, uncheck proportional scale and set all three values manually.
3. Absolute size means that the world size of the scattered objects is exactly as it is set
here. I recommend you always keep this button checked.

Distribution
In the Property Tree of Area 2 select Area 2 :ON / stone1 / Distribution. The
Distribution dialog appears in the bottom window of the Property Editor:

We will set negative values to both maximal and minimal heights to sink a little the
scattered stones in the water. We need this to create an impression of stones lying on
the ground. Set the max height to 2, while the min height to 2.5 (remember that the
average height of the stones varies from 4 to 3 units) so that the stones will not be
fully sunk.

Changing the stones material.

One more step to finish with stones. Let us change the default stone material making
stones look wet (remember that they are immersed into water). First of all we shall
convert the 3DS-material lying on the stones to the World Builder material. In the
Property Tree for rivers Area 2 select Stone1 / Contents Viewer / Area 1 (full) /
Shader / 3DS Material / KAM01 / Photometry. Make a right click at Photometry

and choose Convert in the pop-up menu appeared. The 3DS-material will just be

converted into the inner WB material. In the updated Property Tree expand KAM01
as shown on the left panel in the figure below and select Phong Photometry. The
Phong Photometry dialog appears in the bottom window of the Property Editor (the
right panel):

Set the coefficients of the Phong photometry model to what shown on the right panel
above. Notice that we have just increased the diffuse and specular components of the
material increasing its reflection ability.
If we render the camera view in the AA buffer mode (
toolbar) we will see the following image:

button at the main

Incremental Design
In what follows we will adjust river flow parameters and thus we will need to draw
our river many times. In order not to waste time for the landscape drawing let us use
the so-called incremental design approach. In the Objects Tree select River_0. In the

Property Tree for River_0 select Settings. The following dialog appears in the bottom
window of the Property Editor:

Click at Invisible. Now River_0 surface will not be drawn, while the stones scattered
on it will be seen. Render the camera view. When the image in the camera view is
ready, click Incremental Design Step Forward (
button in the main toolbar). All
the renderable objects in the scene are hidden. The camera image with depths (ZBuffer) has been stored in the computers memory. In the River Settings dialog
(above) uncheck Invisible to make the river visible again. Now all is ready for
multiple river drawing.

External Perturbations.
Up to now the only animation of our river was the procedural flow. WB allows also to
add some extra animation to the water surface by means of the so-called External
Perturbations. The main idea of this kind of animation is that we place an external
object to the river channel and tell the river to create some kind of surface
perturbations from the object. The perturbations are created automatically. All the
External Perturbations are subdivided into two big groups perturbations created by
the scene objects (objects, seen in the Objects Tree) and perturbations created by the
objects scattered in areas. Perturbations also differ by their types. There are four types
of perturbations: Circular Waves for Dropped, For Oblong Dropped, Waves for Static
Object and Cavity.
To add any kind of external perturbation to the river surface select River_0 in the
Objects Tree and then click at External Perturbations in the Properties Tree. The
External Perturbations dialog appears in the bottom window of the Properties Editor.

External Perturbations dialog

External Perturbations list

Click at the small green cross at the dialogs toolbar. A list of possible External
Perturbations appears. Select Cavity and click OK. The selected External Perturbation
is added to the river.

Cavity.
Cavity is an external perturbation of special type simulating the decrease of the water
level in an confined region just after the obstacle immersed into the river.
If Cavity is attached to the river and this property is selected in the Property Tree (the
left panel in the picture below) the following dialog appears in the bottom window of
the Property Editor (the right panel):

The brief description of the dialog parameters are given below.

Length is the length of the region with decreased water level. It is measured from
the object downstream.
Central Angle shows how wide the region with decreased water level will be.

Depth defines the maximal decrease of the water level behind the obstacle.
Set Length to 15 units, Central Angle to 60 degrees and Depth to 0.25 units. These
values are resonable for the size of our river and stones immersed into it.

Amplitude of the Permanent Perturbations

To emphasize the turbulent character of our flow let us increase the amplitude of the
permanent perturbations, e.g. those perturbations, which always present on the river
surface making the flow visible. In the Properties Tree for River_0 select Flow
Parameters. The Flow Parameters dialog appears in the bottom window of the
Properties Editor.

Flow Parameters dialog

Increase the Amplitude of the permanent perturbations on the river surface. (These
random waves make the river flow visible). Set Amplitude to 0.2 and render the
scene:

It is well seen that the flow in the river channel became remarkably more turbulent.
Compare the latest picture to the previous one. Obviously, the stones produce a
chaotic flow pattern and the only thing we still have to do is to add some foam to the
turbulent stream.

Foam
Up to now the rivers Area 2 contained only the distributed stones in it. It seems to be
reasonable to add the foamy material just to the same area in which perturbations are
created.
Foam Material.
In the Property Tree for Area 2 select Area 2: ON. The main area dialog appears in
the bottom window of the Property Tree:

Click at the little green plus at the top of the dialog. The list of possible area contents
appears (left panel below). Select Material in Area and click OK. A new material is
added to Area 2. In the Property Tree select the new string Material in Area and right
click on it. The following pop-up menu appears:

Select Add. The list of all possible materials appears (right panel below):

Select Foam and click OK. Foam is added to Area 2. Now we have to fit parameters
of this shader. First of all, adjust the fractalization of the foam.
Color Gradient.

In the Properties Tree for Area 2 select Material / Foam / Color Gradient. The
Gradient Editor appears in the bottom window of the Properties Editor. Its default
view is shown in the left panel below. Using the short command reference below, set
the gradient to what is shown on the right panel. This will result in more chaotic color
distribution in the foam material.

Default Gradient

Final Gradient

Apply Color - When selected, provides a pencil mouse pointer that enables you to
apply the current color anywhere along the color gradient. Click the button and move
the mouse anywhere along the color gradient, clicking where you want the current
color added.
Select Color - When selected, provides an eye dropper pointer that enables you to
select a color anywhere along the color gradient. The selected color becomes the
current color as displayed in the Current Color button.
Delete Color - Enables you to click and thus delete any color in the color gradient.
Reset Gradient - Resets the color gradient using the left-most and right-most
colors.
Current Color - Enables you to select a color from the Color Picker. Click the
button, select the color you desire and click OK.
Noise 2D.

In the Properties Tree for Area 2 select Material / Foam / Noise 2D. The noise dialog
appears in the bottom window of the Properties Editor (see above).

The noise parameters should be adjusted empirically (that is why we asked you to use
the Incremental Design approach, see above). The values shown in the figure above
lead to the following camera view:

It is well seen that the foamy stuff occupies all Area 2. Now we have to confine the
application of the foam material by the cavities created by the stones. To do so we
shall use the Placing Conditions.
In the Property Tree for Area 2 select Area 2: ON / Material in Area / Foam / Placing
Conditions. The following dialog appears in the bottom window of the Property
Editor:

First of all unselect Ignore All check box. In our case we shall deal with the altitude
range only. Note that above and below the edit lines controlling the altitude range
there are a pair of informational controls showing you the actual heights range in the
river mesh. Obviously, the negative minimal value results from the Cavity action. If
you set the range as shown in the figure above (from 3 to 0.5) the foam will be
applied only within the cavities.
Render the scene to get the camera view:

If you will now render the animation you will see that some flow parameters should
be re-set. First, the flow is still too slow. Second, it is shifted to the right shore so that
the foam drift is almost suppressed in the vicinity of the left shore.
Let us correct these faults. We shall do two things. First, increase the river flow speed.
Second, change the rivers speed profile to make the flow occupy nearly all the
channel.

River Flow Speed

In the Properties Tree for River_0 select Flow Parameters and make sure that Flow
Parameters dialog is loaded to the bottom window of the Properties Editor.
Set Max Flow Speed to 0.2 and Wave Period to 45 (frames). These digits mean that
the randomly scattered perturbations will oscillate having the maximal absolute height
0.2 units decreasing to the minimum and increasing again for 45 frames.

Flow Parameters dialog

Speed Profile Editor

In the Property Tree select Flow Parameters / Sped Profile.
The Speed Profile dialog contains the spline editor. The default profile of the flow
speed (in our case perturbations height profile is the same as the speed profile) has 3
basic points and has its maximum at the center of the channel. The speed profile
coming with foam_00.awb is shown on the left panel below.
Profile editing is easy. The profile is implemented as a spline drawn through some
base points (little squares in the figures below). You can either move existing points
or create a new point on the spline. It is also possible to delete points from the spline.
To move a point locate the mouse pointer near it and press the left button of the
mouse. Move the point to desirable position on the plot and release the button.
To create a new point locate the mouse pointer near the spline curve and make a
double click by the left button.
To delete a point locate the mouse pointer near it and press the right button of the
mouse.
Tension - allows you to control spline shape between base points. To make spline
curve nearly a straight line connecting the points, set this parameter to some big
number, say, 10. Lower values result in more smooth line.
To make the peak in the speed profile wider and locate the maximum at the center it is
convenient to add one more point to the curve and manipulate with three central
points. Make the speed profile look as on the right panel in the figure below. If you
render the scene now, you will see that the flow pattern has been changed (see below).
Note that the foam pattern will also move obeying the same speed profile.

Camera view with more wide speed profile.

The results of this (last for this tutorial) step you can find in Projects /
RiverPart4.awb. Look also for the ready movie file Movies/part4.avi. to enjoy the
flow you have just created.
In the end a pair words of advice on how make your own movie in World Builder.

How to Make a Movie

In general, all the projects coming with this tutorial allow to make a primitive movie
with a static background and a flowing water. The parameters of the flow we have just
set along with default value of flow speed (see Flow Parameters dialog above)
provide an automatic procedural animation of the water surface. The camera view is
fixed, which makes it possible to use the background.

Background
The first step is to create the background image. It is very similar to what was
described in Incremental Design part with the only additional detail. You have to save
the camera image before clicking Incremental Design Step Forward (
button in
the main toolbar). To save the image click Window / Save picture at the main
toolbar. The standard Save File dialog appears. Important: you have first to set the file
type filter to *.zbf files. Than type the file name and click Save. The background
image is saved.

Camera part.
In the Objects Tree select Camera01. In the Properties Tree for Camera01 select
Output. The Camera Output dialog appears in the bottom window of the Properties
Editor. Select Window Bitmap among the list of possible file formats. The Path
control at the bottom of the dialog is no longer gray. Type the full path of the output
file or use the Browse button to specify the file name and the path. Finally, check
Replace if exists box to overwrite the existing files.

Camera Output dialog.

Image Composer dialog

The next step is to assign the background image. In the Properties Tree for Camera01
select Image Composer. The Image Composer dialog appears appears in the bottom
window of the Properties Editor. Click at Static to ensure the static background. Use
the Browse button to specify the path to the *.zbf camera image file you have just
saved. When you have chosen the file and clicked OK in the standard Open File
dialog, World Builder asks you about the Units System you use in the current project:

Click OK to accept metric system or choose your system using the pull-down box and
then click OK. The background image is assigned.
Final Rendering.
Click the Final Rendering button (
) at the main toolbar to begin render series of
images for the movie. The Render Options dialog appears. Set Frames to All to
render all the frames allowed (the default number of frames is 100). Set Rendering to
Production to ensure anti-aliasing of the final images. All other values in this dialog
are taken from Camera object and may be changed here. Make sure that the rest
parameters are that you want and click Render. The series of frames has started.

Appendix.
The river foam shader imposes some important restrictions on the usage of the shader.
Before rendering an image with foam on the river in A- and AA- buffer mode make
sure that rivers shores are assigned correctly. Under correctly I mean that the left
river shore is really left with respect to the flow direction; the same to the right shore.
The figures below demonstrate correct and incorrect shores assignement.

Correct shores assignement. Note that the flow direction is shown by little arrows.
The right part of the figure shows Select Shores dialog. The gray informational lines
read the names of skeletons chosen as shores.

Incorrect shores assignement. For example, SkeletonLine0 is in fact the left shore.
Meanwhile, it is assigned as the right shore. This situation may lead to rendering
artifacts when A- or AA-buffer rendering modes are chosen.
How to correct the shores assignement. Click at Select Shores in the Properties Tree.
The Channel Definition dialog is loaded to the bottom window of the Properties
Editor:

Click at Left Shore. The Select Object from Scene dialog (right panel above) appears.
Select a skeleton you want to be the left shore and click OK. The left shore is
assigned.
Repeat the same actions for the right shore. The right shore is assigned.