
@C4@M@bBeginning Tutorial


The beginning tutorial explains step by step how to use POV-Ray's scene
description language to create own scenes. The use of almost every feature of
POV-Ray's language is explained in detail. We will learn basic things like
placing cameras and light sources. We will also learn how to create a large
variety of objects and how to assign different textures to them. The more
sophisticated features like radiosity, halos and atmospheric effects will be
explained in detail.

The following sections explain the features in roughly the same order as they
are described in the reference guide.

4.1              Our First Image

We will create the scene file for a simple picture. Since ray-tracers thrive
on spheres, that is what we will render first.

4.1.1            Understanding POV-Ray's Coordinate System

First, we have to tell POV-Ray where our camera is and where it is looking.
To do this, we use 3D coordinates. The usual coordinate system for POV-Ray
has the positive y-axis pointing up, the positive x-axis pointing to the
right, and the positive z-axis pointing into the screen as follows:

          ^+Y
          |   /+Z
          |  /
          | /
  -X      |/        +X
  <-------|-------->
         /|
        / |
       /  |
    -Z/   |
          v-Y
The left-handed coordinate system (the z-axis is pointing away).

This kind of coordinate system is called a left-handed coordinate system. If
we use our left hand's fingers we can easily see why it is called
left-handed. We just point our thumb in the direction of the positive x-axis,
the index finger in the direction of the positive y-axis and the middle
finger in the positive z-axis direction. We can only do this with our left
hand. If we had used our right hand we would not have been able to point the
middle finger in the correct direction.

The left hand can also be used to determine rotation directions. To do this
we must perform the famous Computer Graphics Aerobics exercise. We hold up
our left hand and point our thumb in the positive direction of the axis of
rotation. Our fingers will curl in the positive direction of rotation.
Similarly if we point our thumb in the negative direction of the axis our
fingers will curl in the negative direction of rotation.

           ^
         +Y|   +Z/ _
           |    /_| |_  _
           |   _| | | |/ \
           |  | | | | |  |
           | /| | | | |  V
 -X        |/ | | | | |    +X
<----------+--|-|-|-|-|------>
          /|  |       ____
         / |  |         ___|
        /  |          /
       /   |   |      /
    -Z/  -Y|
     /     |
"Computer Graphics Aerobics" to determine the rotation direction.

In the above illustration, the left hand is curling around the x-axis. The
thumb points in the positive x direction and the fingers curl over in the
positive rotation direction.

If we want to use a right-handed system, as some CAD systems and modellers
do, the right vector in the camera specification needs to be changed. See the
detailed description in "Handedness". In a right-handed system we use our
right hand for the Aerobics.

There is some controversy over whether POV-Ray's method of doing a
right-handed system is really proper. To avoid problems we stick with the
left-handed system which is not in dispute.

4.1.2            Adding Standard Include Files

Using our personal favorite text editor, we create a file called demo.pov. We
then type in the following text. The input is case sensitive, so we have to
be sure to get capital and lowercase letters correct.

  #include "colors.inc"    // The include files contain
  #include "shapes.inc"    // pre-defined scene elements
  #include "finish.inc"
  #include "glass.inc"
  #include "metals.inc"
  #include "stones.inc"
  #include "woods.inc"


The first include statement reads in definitions for various useful colors.
The second include statement reads in some useful shapes. The next read
pre-defined finishes, glass, metal, stone and wood textures. It is a good
idea to have a look through them to see but a few of the many possible shapes
and textures available.

We should only include files we really need in our scene. Some of the include
files coming with POV-Ray are quite large and we should better save the
parsing time and memory if we don't need them. In the following examples we
will only use the colors.inc, finish.inc and stones.inc include files so we
will better remove the appropriate lines from our scene file.

We may have as many include files as needed in a scene file. Include files
may themselves contain include files, but we are limited to declaring
includes nested only ten levels deep.

Filenames specified in the include statements will be searched for in the
current directory first and, if not found, will then be searched for in
directories specified by any +L or Library_Path options active. This would
facilitate keeping all our "include" (.inc) files such as shapes.inc,
colors.inc and textures.inc in an "include" subdirectory, and giving an +L
switch on the command line to where our library of include files are.

4.1.3            Adding a Camera

The camera declaration describes where and how the camera sees the scene. It
gives x-, y- and z-coordinates to indicate the position of the camera and
what part of the scene it is pointing at. We describe the coordinates using a
three-part vector. A vector is specified by putting three numeric values
between a pair of angle brackets and separating the values with commas.

We add the following camera statement to the scene.

  camera {
    location <0, 2, -3>
    look_at  <0, 1,  2>
  }


Briefly, location <0,2,-3> places the camera up two units and back three
units from the center of the ray-tracing universe which is at <0,0,0>. By
default +z is into the screen and -z is back out of the screen.

Also look_at <0,1,2> rotates the camera to point at the coordinates <0,1,2>.
A point 5 units in front of and 1 unit lower than the camera. The look_at
point should be the center of attention of our image.

4.1.4            Describing an Object

Now that the camera is set up to record the scene, let's place a yellow
sphere into the scene. We add the following to our scene file:

  sphere {
    <0, 1, 2>, 2
    texture {
      pigment { color Yellow }
    }
  }


The first vector specifies the center of the sphere. In this example the x
coordinate is zero so it is centered left and right. It is also at y=1 or one
unit up from the origin. The z coordinate is 2 which is five units in front
of the camera, which is at z=-3. After the center vector is a comma followed
by the radius which in this case is two units. Since the radius is half the
width of a sphere, the sphere is four units wide.

4.1.5            Adding Texture to an Object

After we have defined the location and size of the sphere, we need to
describe the appearance of the surface. The texture block specifies these
parameters. Texture blocks describe the color, bumpiness and finish
properties of an object. In this example we will specify the color only. This
is the minimum we must do. All other texture options except color will use
default values.

The color we define is the way we want an object to look if fully
illuminated. If we were painting a picture of a sphere we would use dark
shades of a color to indicate the shadowed side and bright shades on the
illuminated side. However ray-tracing takes care of that. We pick the basic
color inherent in the object and POV-Ray brightens or darkens it depending on
the lighting in the scene. Because we are defining the basic color the object
actually has rather than how it looks the parameter is called pigment.

Many types of color patterns are available for use in a pigment statement.
The keyword color specifies that the whole object is to be one solid color
rather than some pattern of colors. We can use one of the color identifiers
previously defined in the standard include file colors.inc.

If no standard color is available for our needs, we may define our own color
by using the color keyword followed by red, green and blue keywords
specifying the amount of red, green and blue to be mixed. For example a nice
shade of pink can be specified by:

  color red 1.0 green 0.8 blue 0.8


The values after each keyword should be in the range from 0.0 to 1.0. Any of
the three components not specified will default to 0. A shortcut notation may
also be used. The following produces the same shade of pink:

  color rgb <1.0, 0.8, 0.8>


4.1.6            Defining a Light Source

One more detail is needed for our scene. We need a light source. Until we
create one, there is no light in this virtual world. Thus we add the line

  light_source { <2, 4, -3> color White}


to the scene file to get our first complete POV-Ray scene file as shown
below.

  #include "colors.inc"

  background { color Cyan }

  camera {
    location <0, 2, -3>
    look_at  <0, 1,  2>
  }

  sphere {
    <0, 1, 2>, 2
    texture {
      pigment { color Yellow }
    }
  }

  light_source { <2, 4, -3> color White}


The vector in the light_source statement specifies the location of the light
as two units to our right, four units above the origin and three units back
from the origin. The light source is invisible, it only casts light, so no
texture is needed.

That's it! We close the file and render a small picture of it using the
command

  povray +w160 +h120 +p +x +d0 -v -idemo.pov


If our computer does not use the command line, we have to read the platform
specific docs for the correct command to render the scene.

We may also set any other command line options we like. The scene is written
to the image file demo.tga (or some suffix other than .tga if our computer
uses a different default file format).

The scene we just traced isn't quite state of the art but we will have to
start with the basics before we soon get to much more fascinating features
and scenes.

4.2              Using the Camera


4.2.1            Using Focal Blur

Let's construct a simple scene to illustrate the use of focal blur. For this
example we will use a pink sphere, a green box and a blue cylinder with the
sphere placed in the foreground, the box in the center and the cylinder in
the background. A checkered floor for perspective and a couple of light
sources will complete the scene.

We create a new file called focaldem.pov and enter the following text

  #include "colors.inc"
  #include "shapes.inc"
  #include "textures.inc"

  #version 3.0

  global_settings {
    assumed_gamma 2.2 // for most PC monitors
    max_trace_level 5
  }

  sphere { <1, 0, -6>, 0.5
    finish {
      ambient 0.1
      diffuse 0.6
    }
    pigment { NeonPink }
  }

  box { <-1, -1, -1>, < 1,  1,  1>
    rotate <0, -20, 0>
    finish {
      ambient 0.1
      diffuse 0.6
    }
    pigment { Green }
  }

  cylinder { <-6, 6, 30>, <-6, -1, 30>, 3
    finish {
      ambient 0.1
      diffuse 0.6
    }
    pigment {NeonBlue}
  }

  plane { y, -1.0
    pigment {
      checker color Gray65 color Gray30
    }
  }

  light_source { <5, 30, -30> color White }

  light_source { <-5, 30, -30> color White }


Now we can proceed to place our focal blur camera to an appropriate viewing
position. Straight back from our three objects will yield a nice view.
Adjusting the focal point will move the point of focus anywhere in the scene.
We just add the following lines to the file:

  camera {
    location <0.0, 1.0, -10.0>
    look_at  <0.0, 1.0,  0.0>

  //  focal_point <-6, 1, 30>    // blue cylinder in focus
  //  focal_point < 0, 1,  0>    // green box in focus
    focal_point < 1, 1, -6>    // pink sphere in focus

    aperture 0.4     // a nice compromise
  //  aperture 0.05    // almost everything is in focus
  //  aperture 1.5     // much blurring

  //  blur_samples 4       // fewer samples, faster to render
    blur_samples 20      // more samples, higher quality image
  }


The focal point is simply the point at which the focus of the camera is at
its sharpest. We position this point in our scene and assign a value to the
aperture to adjust how close or how far away we want the focal blur to occur
from the focused area.

The aperture setting can be considered an area of focus. Opening up the
aperture has the effect of making the area of focus smaller while giving the
aperture a smaller value makes the area of focus larger. This is how we
control where focal blur begins to occur around the focal point.

The blur samples setting determines how many rays are used to sample each
pixel. Basically, the more rays that are used the higher the quality of the
resultant image, but consequently the longer it takes to render. Each scene
is different so we have to experiment. This tutorial has examples of 4 and 20
samples but we can use more for high resolution images. We should not use
more samples than is necessary to achieve the desired quality - more samples
take more time to render. The confidence and variance settings are covered in
section "Focal Blur".

We experiment with the focal point, aperture, and blur sample settings. The
scene has lines with other values that we can try by commenting out the
default line with double slash marks and un-commenting the line we wish to
try out. We make only one change at a time to see the effect on the scene.

Two final points when tracing a scene using a focal blur camera. We needn't
specify anti-aliasing (the \Clo{+A} switch) because the focal blur code uses
its one sampling method that automatically takes care of anti-aliasing. Focal
blur can only be used with the perspective camera.

4.3              Simple Shapes

So far we have just used the sphere shape. There are many other types of
shapes that can be rendered by POV-Ray. The following sections will describe
how to use some of the more simple objects as a replacement for the sphere
used above.

4.3.1            Box Object

The box is one of the most common objects used. We try this example in place
of the sphere:

  box {
    <-1, 0,   -1>,  // Near lower left corner
    < 1, 0.5,  3>   // Far upper right corner

    texture {
      T_Stone25     // Pre-defined from stones.inc
      scale 4       // Scale by the same amount in all
                    // directions
    }

    rotate y*20     // Equivalent to "rotate <0,20,0>"
  }


In the example we can see that a box is defined by specifying the 3D
coordinates of its opposite corners. The first vector must be the minimum x-,
y- and z-coordinates and the 2nd vector must be the maximum x-, y- and
z-values. Box objects can only be defined parallel to the axes of the world
coordinate system. We can later rotate them to any angle. Note that we can
perform simple math on values and vectors. In the rotate parameter we
multiplied the vector identifier y by 20. This is the same as <0,1,0>*20 or
<0,20,0>.

4.3.2            Cone Object

Here's another example showing how to use a cone:

  cone {
    <0, 1, 0>, 0.3    // Center and radius of one end
    <1, 2, 3>, 1.0    // Center and radius of other end

    texture { T_Stone25 scale 4 }
  }


The cone shape is defined by the center and radius of each end. In this
example one end is at location <0,1,0> and has a radius of 0.3 while the
other end is centered at <1,2,3> with radius=1. If we want the cone to come
to a sharp point we must use radius=0. The solid end caps are parallel to
each other and perpendicular to the cone axis. If we want an open cone with
no end caps we have to add the keyword open after the 2nd radius like this:

  cone {
    <0, 1, 0>, 0.3    // Center and radius of one end
    <1, 2, 3>, 1.0    // Center and radius of other end
    open              // Removes end caps

    texture { T_Stone25 scale 4 }
  }


4.3.3            Cylinder Object

We may also define a cylinder like this:

  cylinder {
    <0, 1, 0>,     // Center of one end
    <1, 2, 3>,     // Center of other end
    0.5            // Radius
    open           // Remove end caps

    texture { T_Stone25 scale 4 }
  }


4.3.4            Plane Object

Let's try out a computer graphics standard - The Checkered Floor. We add the
following object to the first version of the demo.pov file, the one including
the sphere.

  plane { <0, 1, 0>, -1
    pigment {
      checker color Red, color Blue
    }
  }


The object defined here is an infinite plane. The vector <0,1,0> is the
surface normal of the plane (i.e. if we were standing on the surface, the
normal points straight up). The number afterward is the distance that the
plane is displaced along the normal from the origin - in this case, the floor
is placed at y=-1 so that the sphere at y=1, radius=2, is resting on it.

We note that even though there is no texture statement there is an implied
texture here. We might find that continually typing statements that are
nested like texture {pigment} can get to be tiresome so POV-Ray let's us
leave out the texture statement under many circumstances. In general we only
need the texture block surrounding a texture identifier (like the T_Stone25
example above), or when creating layered textures (which are covered later).

This pigment uses the checker color pattern and specifies that the two colors
red and blue should be used.

Because the vectors <1,0,0>, <0,1,0> and <0,0,1> are used frequently, POV-Ray
has three built-in vector identifiers x, y and z respectively that can be
used as a shorthand. Thus the plane could be defined as:

  plane { y, -1
    pigment { ... }
  }


Note that we do not use angle brackets around vector identifiers.

Looking at the floor, we notice that the ball casts a shadow on the floor.
Shadows are calculated very accurately by the ray-tracer, which creates
precise, sharp shadows. In the real world, penumbral or "soft" shadows are
often seen. Later we will learn how to use extended light sources to soften
the shadows.

4.3.5            Standard Include Objects

The standard include file shapes.inc contains some pre-defined shapes that
are about the size of a sphere with a radius of one unit. We can invoke them
like this:

  #include "shapes.inc"

  object {
    UnitBox
    texture { T_Stone25 scale 4 }
    scale 0.75
    rotate <-20,25,0>
    translate y
  }


4.4              Advanced Shapes

After we have gained some experience with the simpler shapes available in
POV-Ray it is time to go on to the more advanced, thrilling shapes.

We should be aware that the shapes described below are not trivial to
understand. We needn't be worried though if we do not know how to use them or
how they work. We just try the examples and play with the features described
in the reference chapter. There is nothing better than learning by doing.

4.4.1            Bicubic Patch Object

Bicubic or Bezier patches are useful surface representations because they
allow an easy definition of surfaces using only a few control points. The
control points serve to determine the shape of the patch. Instead of defining
the vertices of triangles, we simply give the coordinates of the control
points. A single patch has 16 control points, four at each corner, and the
rest positioned to divide the patch into smaller sections. For ray-tracing
(or rendering) the patches are approximated using triangles. Bezier patches
are almost always created using a third party modeller so for this tutorial,
we will use moray (any other modeller that supports Bezier patches and
POV-Ray can also be used). We will use moray only to create the patch itself,
not the other elements of the scene.

Bezier patches are actually very useful and, with a little practice, some
pretty amazing things can be created with them. For our first tutorial, let's
make a sort of a teepee/tent shape using a single sheet patch.

First, we start moray and, from the main edit screen, we click on "CREATE".
We Name our object Teepee. The "CREATE BEZIER PATCH" dialogue box will
appear. We have to make sure that "SHEET" is depressed. We click on "OK,
CREATE". At the bottom of the main edit screen, we click on "EXTENDED EDIT".

We hold the cursor over the "TOP" view and right click to make the pop-up
menu appear. We click on "MAXIMIZE". We [ALT]-drag to zoom in a little. We
click on "MARK ALL", and under the transformation mode box, "UFRM SCL". We
drag the mouse to scale the patch until it is approximately four units wide.
We click on "TRANSLATE", and move the patch so that its center is over the
origin. We right click "MINIMIZE" and "UNMARK ALL".

We [SHIFT]-drag a box around the lower right control point to mark it. We
[ALT]-zoom into the "FRONT" view so that we can see the patch better. In the
"FRONT" view, we "TRANSLATE" that point 10 units along the negative z-axis
(we note that in MORAY z is up). We "UNMARK ALL". We repeat this procedure
for each of the other three corner points. We make sure we remember to
"UNMARK ALL" once each point has been translated. We should have a shape that
looks as though it is standing on four pointed legs. We "UNMARK ALL".

Working once again in the "TOP" view, we [SHIFT]-drag a box around the four
center control points to mark them. We right-click over the "TOP" view and
"MAXIMIZE". We click on "UFRM SCL" and drag the mouse to scale the four
points close together. We [ALT]-drag to zoom closer and get them as close
together as we can. We [ALT]-drag to zoom out, right click and "MINIMIZE".

In the "FRONT" view, we "TRANSLATE" the marked points 10 units along the
positive z-axis. We "UNMARK ALL". The resulting shape is quite interesting,
was simple to model, and could not be produced using CSG primitives. Now
let's use it in a scene.

We click on "DONE" to return to the main edit screen. We note that U_STEPS
and V_STEPS are both set to 3 and flatness is set to 0.01. We leave them
alone for now. We click on "FILES" and then "SAVE SEL" (save selection). We
name our new file teepee1.mdl. We press [F3] and open teepee1.mdl. There is
no need to save the original file. When teepee1 is open, we create a quick
"dummy" texture (moray will not allow us to export data without a texture).
We use white with default finish and name it TeePeeTex. We apply it to the
object, save the file and press [CTRL-F9]. moray will create two files:
teepee1.inc and teepee1.pov.

We exit moray and copy teepee1.inc and teepee1.pov into our working directory
where we are doing these tutorials. We create a new file called bezdemo.pov
and edit it as follows:

  #include "colors.inc"

  camera {
    location <0, .1, -60>
    look_at 0
    angle 40
  }

  background { color Gray25 }  //to make the patch easier to see

  light_source { <300, 300, -700> White }

  plane { y, -12
    texture {
      pigment {
        checker
        color Green
        color Yellow
      }
    }
  }


Using a text editor, we create and declare a simple texture for our teepee
object:

  #declare TeePeeTex = texture {
    pigment {
      color rgb <1, 1, 1,>
    }
    finish {
      ambient .2
      diffuse .6
    }
  }


We paste in the bezier patch data from teepee1.pov (the additional object
keywords added by moray were removed):

  bicubic_patch {
    type 1 flatness 0.0100 u_steps 3 v_steps 3,
    <-5.174134, 5.528420, -13.211995>,
    <-1.769023, 5.528420, 0.000000>,
    <1.636088, 5.528420, 0.000000>,
    <5.041199, 5.528420, -13.003932>,
    <-5.174134, 1.862827, 0.000000>,
    <0.038471, 0.031270, 18.101474>,
    <0.036657, 0.031270, 18.101474>,
    <5.041199, 1.862827, 0.000000>,
    <-5.174134, -1.802766, 0.000000>,
    <0.038471, 0.028792, 18.101474>,
    <0.036657, 0.028792, 18.101474>,
    <5.041199, -1.802766, 0.000000>,
    <-5.174134, -5.468359, -13.070366>,
    <-1.769023, -5.468359, 0.000000>,
    <1.636088, -5.468359, 0.000000>,
    <4.974128, -5.468359, -12.801446>
    texture {
      TeePeeTex
    }
    rotate -90*x  // to orient the object to LHC
    rotate 25*y   // to see the four "legs" better
  }



We add the above rotations so that the patch is oriented to POV-Ray's
left-handed coordinate system (remember the patch was made in moray in a
right handed coordinate system), so we can see all four legs. Rendering this
at 200x150 -a we see pretty much what we expect, a white teepee over a green
and yellow checkered plane. Let's take a little closer look. We render it
again, this time at 320x200.

Now we see that something is amiss. There appears to be sharp angling, almost
like faceting, especially near the top. This is indeed a kind of faceting and
is due to the U_STEPS and V_STEPS parameters. Let's change these from 3 to 4
and see what happens.

That's much better, but it took a little longer to render. This is an
unavoidable tradeoff. If we want even finer detail, we must use a U_STEPS and
V_STEPS value of 5 and set flatness to 0. But we must expect to use lots of
memory and an even longer tracing time.

Well, we can't just leave this scene without adding a few items just for
interest. We declare the patch object and scatter a few of them around the
scene:

  #declare TeePee = bicubic_patch {
    type 1 flatness 0.0100 u_steps 3 v_steps 3,
    <-5.174134, 5.528420, -13.211995>,
    <-1.769023, 5.528420, 0.000000>,
    <1.636088, 5.528420, 0.000000>,
    <5.041199, 5.528420, -13.003932>,
    <-5.174134, 1.862827, 0.000000>,
    <0.038471, 0.031270, 18.101474>,
    <0.036657, 0.031270, 18.101474>,
    <5.041199, 1.862827, 0.000000>,
    <-5.174134, -1.802766, 0.000000>,
    <0.038471, 0.028792, 18.101474>,
    <0.036657, 0.028792, 18.101474>,
    <5.041199, -1.802766, 0.000000>,
    <-5.174134, -5.468359, -13.070366>,
    <-1.769023, -5.468359, 0.000000>,
    <1.636088, -5.468359, 0.000000>,
    <4.974128, -5.468359, -12.801446>
    texture {
      TeePeeTex
     }
     rotate -90*x // to orient the object to LHC
     rotate 25*y  // to see the four "legs" better
  }

  object { TeePee }

  object { TeePee translate <8, 0, 8> }

  object { TeePee translate <-9, 0, 9> }

  object { TeePee translate <18, 0, 24> }

  object { TeePee translate <-18, 0, 24> }


That looks good. Let's do something about that boring gray background. We
delete the background declaration and replace it with:

  plane { y, 500
    texture {
      pigment { SkyBlue }
      finish { ambient 1 diffuse 0}
     }
     texture {
       pigment {
         bozo
         turbulence .5
         color_map {
           [0 White]
           [1 White filter 1]
         }
       }
       finish { ambient 1 diffuse 0 }
       scale <1000, 250, 250>
       rotate <5, 45, 0>
    }
  }


This adds a pleasing cirrus-cloud filled sky. Now, let's change the checkered
plane to rippled sand dunes:

  plane {y,-12
    texture {
      pigment {
        color <.85, .5, .15>
      }
      finish {
        ambient .25
        diffuse .6
        crand .5
      }
      normal {
        ripples .35
        turbulence .25
        frequency 5
      }
      scale 10
      translate 50*x
    }
  }


We render this at 320x240 -a. Not bad! Let's just add one more element. Let's
place a golden egg under each of the teepees. And since this is a bezier
patch tutorial, let's make the eggs out of bezier patches.

We return to moray and create another bezier patch. We name it Egg1 and
select "CYLINDRICAL 2 - PATCH" from the "CREATE BEZIER PATCH" dialogue box.
We click on "EXTENDED EDIT". We "MARK ALL" and rotate the patch so that the
cylinder lays on its side. We "UNMARK ALL". In the "FRONT" view, we
[SHIFT]-drag a box around the four points on the right end to mark them. In
the "SIDE" view, we right click and "MAXIMIZE". We [ALT]-drag to zoom in a
little closer. We "UFRM SCL" the points together as close as possible. We
zoom in closer to get them nice and tight. We zoom out, right click and
"MINIMIZE".

We click on "TRANSLATE" and drag the points to the left so that they are
aligned on the z-axis with the next group of four points. This should create
a blunt end to the patch. We repeat this procedure for the other end. We
"UNMARK ALL".

In the "FRONT" view, the control grid should be a rectangle now and the patch
should
be an ellipsoid. We [SHIFT]-drag a box around the upper right corner of the
control grid to mark those points. We then [SHIFT]-drag a box around the
lower right corner to mark those points as well. In the "SIDE" view, we "UFRM
SCL" the points apart a little to make that end of the egg a little wider
than the other. We "UNMARK ALL".

The egg may need a little proportional adjustment. We should be able to "MARK
ALL" and "LOCAL SCL" in the three views until we get it to look like an egg.
When we are satisfied that it does, we "UNMARK ALL" and click on done.
Learning from our teepee object, we now go ahead and change U_STEPS and
V_STEPS to 4.

We create a dummy texture, white with default finish, name it EggTex and
apply it to the egg. From the FILES menu, we "SAVE SEL" to filename egg1.mdl.
We load this file and export ([CTRL F9]). We exit moray and copy the files
egg1.inc and egg1.pov into our working directory.

Back in bezdemo.pov, we create a nice, shiny gold texture:

  #declare EggTex = texture {
    pigment { BrightGold }
    finish {
      ambient .1
      diffuse .4
      specular 1
      roughness 0.001
      reflection .5
      metallic
    }
  }


And while we're at it, let's dandy up our TeePeeTex texture:

  #declare TeePeeTex = texture {
    pigment { Silver }
    finish {
      ambient .1
      diffuse .4
      specular 1
      roughness 0.001
      reflection .5
      metallic
    }
  }


Now we paste in our egg patch data and declare our egg:

  #declare Egg = union { // Egg1
    bicubic_patch {
      type 1 flatness 0.0100 u_steps 4 v_steps 4,
      <2.023314, 0.000000, 4.355987>,
      <2.023314, -0.000726, 4.355987>,
      <2.023312, -0.000726, 4.356867>,
      <2.023312, 0.000000, 4.356867>,
      <2.032037, 0.000000, 2.734598>,
      <2.032037, -1.758562, 2.734598>,
      <2.027431, -1.758562, 6.141971>,
      <2.027431, 0.000000, 6.141971>,
      <-1.045672, 0.000000, 3.281572>,
      <-1.045672, -1.758562, 3.281572>,
      <-1.050279, -1.758562, 5.414183>,
      <-1.050279, 0.000000, 5.414183>,
      <-1.044333, 0.000000, 4.341816>,
      <-1.044333, -0.002947, 4.341816>,
      <-1.044341, -0.002947, 4.345389>,
      <-1.044341, 0.000000, 4.345389>
    }
    bicubic_patch {
      type 1 flatness 0.0100 u_steps 4 v_steps 4,
      <2.023312, 0.000000, 4.356867>,
      <2.023312, 0.000726, 4.356867>,
      <2.023314, 0.000726, 4.355987>,
      <2.023314, 0.000000, 4.355987>,
      <2.027431, 0.000000, 6.141971>,
      <2.027431, 1.758562, 6.141971>,
      <2.032037, 1.758562, 2.734598>,
      <2.032037, 0.000000, 2.734598>,
      <-1.050279, 0.000000, 5.414183>,
      <-1.050279, 1.758562, 5.414183>,
      <-1.045672, 1.758562, 3.281572>,
      <-1.045672, 0.000000, 3.281572>,
      <-1.044341, 0.000000, 4.345389>,
      <-1.044341, 0.002947, 4.345389>,
      <-1.044333, 0.002947, 4.341816>,
      <-1.044333, 0.000000, 4.341816>
    }
    texture { EggTex }
    translate <0.5, 0, -5>  // centers the egg around the origin
    translate -9.8*y        // places the egg on the ground
  }


We now place a copy of the egg under each teepee. This should require only
the x- and z-coordinates of each teepee to be changed:

  object { Egg }

  object { Egg translate <8, 0, 8> }

  object { Egg translate <-9, 0, 9> }

  object { Egg translate <18, 0, 24> }

  object { Egg translate <-18, 0, 24> }


Scene build with different Bezier patches.

We render this at 320x240 -A. Everything looks good so we run it again at
640x480 +A. Now we see that there is still some faceting near the top of the
teepees and on the eggs as well. The only solution is to raise U_STEPS and
V_STEPS from 4 to 5 and set flatness to 0 for all our bezier objects. We make
the changes and render it again at 640x480 +A.

4.4.2            Blob Object

Blobs are described as spheres and cylinders covered with "goo" which
stretches to smoothly join them (see section "Blob"). Ideal for modelling
atoms and molecules, blobs are also powerful tools for creating many smooth
flowing "organic" shapes.

A slightly more mathematical way of describing a blob would be to say that it
is one object made up of two or more component pieces. Each piece is really
an invisible field of force which starts out at a particular strength and
falls off smoothly to zero at a given radius. Where ever these components
overlap in space, their field strength gets added together (and yes, we can
have negative strength which gets subtracted out of the total as well). We
could have just one component in a blob, but except for seeing what it looks
like there is little point, since the real beauty of blobs is the way the
components interact with one another.

Let us take a simple example blob to start. Now, in fact there are a couple
different types of components but we will look at them a little later. For
the sake of a simple first example, let us just talk about spherical
components. Here is a sample POV-Ray code showing a basic camera, light, and
a simple two component blob (this scene is called blobdem1.pov):

  #include "colors.inc"

  camera {
    angle 15
    location <0,2,-10>
    look_at <0,0,0>
  }

  light_source { <10, 20, -10> color White }

  blob {
    threshold .65
    sphere { <.5,0,0>, .8, 1 pigment {Blue} }
    sphere { <-.5,0,0>,.8, 1 pigment {Pink} }

    finish { phong 1 }
  }


A simple, two-part blob.

The threshold is simply the overall strength value at which the blob becomes
visible. Any points within the blob where the strength matches the threshold
exactly form the surface of the blob shape. Those less than the threshold are
outside and those greater than are inside the blob.

We note that the spherical component looks a lot like a simple sphere object.
We have the sphere keyword, the vector representing the location of the
center of the sphere and the float representing the radius of the sphere. But
what is that last float value? That is the individual strength of that
component. In a spherical component, that is how strong the component's field
is at the center of the sphere. It will fall off in a linear progression
until it reaches exactly zero at the radius of the sphere.

Before we render this test image, we note that we have given each component a
different pigment. POV-Ray allows blob components to be given separate
textures. We have done this here to make it clearer which parts of the blob
are which. We can also texture the whole blob as one, like the finish
statement at the end, which applies to all components since it appears at the
end, outside of all the components. We render the scene and get a basic
kissing spheres type blob.

The image we see shows the spheres on either side, but they are smoothly
joined by that bridge section in the center. This bridge represents where the
two fields overlap, and therefore stay above the threshold for longer than
elsewhere in the blob. If that is not totally clear, we add the following two
objects to our scene and re-render (see file blobdem2.pov). We note that
these are meant to be entered as separate sphere objects, not more components
in the blob.

  sphere { <.5,0,0>, .8
    pigment { Yellow transmit .75 }
  }

  sphere { <-.5,0,0>, .8
    pigment { Green transmit .75 }
  }


The spherical components made visible.

Now the secrets of the kissing spheres are laid bare. These semi-transparent
spheres show where the components of the blob actually are. If we have not
worked with blobs before, we might be surprised to see that the spheres we
just added extend way farther out than the spheres that actually show up on
the blobs. That of course is because our spheres have been assigned a
starting strength of one, which gradually fades to zero as we move away from
the sphere's center. When the strength drops below the threshold (in this
case 0.65) the rest of the sphere becomes part of the outside of the blob and
therefore is not visible.

See the part where the two transparent spheres overlap? We note that it
exactly corresponds to the bridge between the two spheres. That is the region
where the two components are both contributing to the overall strength of the
blob at that point. That is why the bridge appears: that region has a high
enough strength to stay over the threshold, due to the fact that the combined
strength of two spherical components is overlapping there.

4.4.2.1          Component Types and Other New Features

The shape shown so far is interesting, but limited. POV-Ray has a few extra
tricks that extend its range of usefulness however. For example, as we have
seen, we can assign individual textures to blob components, we can also apply
individual transformations (translate, rotate and scale) to stretch, twist,
and squash pieces of the blob as we require. And perhaps most interestingly,
the blob code has been extended to allow cylindrical components.

Before we move on to cylinders, it should perhaps be mentioned that the old
style of components used in previous versions of POV-Ray still work. Back
then, all components were spheres, so it was not necessary to say sphere or
cylinder. An old style component had the form:

  component STRENGTH, RADIUS, <CENTER>


This has the same effect as a spherical component, just as we already saw
above. This is only useful for backwards compatibility. If we already have
POV-Ray files with blobs from earlier versions, this is when we would need to
recognize these components. We note that the old style components did not put
braces around the strength, radius and center, and of course, we cannot
independantly transform or texture them, so if we are modifying an older work
into a new version, it may arguably be of benefit to convert old style
components into spherical components anyway.

Now for something new and different: cylindrical components. It could be
argued that all we ever needed to do to make a roughly cylindrical portion of
a blob was string a line of spherical components together along a straight
line. Which is fine, if we like having extra to type, and also assuming that
the cylinder was oriented along an axis. If not, we would have to work out
the mathematical position of each component to keep it is a straight line.
But no more! Cylindrical components have arrived.

We replace the blob in our last example with the following and re-render. We
can get rid of the transparent spheres too, by the way.

  blob {
    threshold .65

    cylinder { <-.75,-.75,0>, <.75,.75,0>, .5, 1 }

    pigment { Blue }
    finish { phong 1 }
  }


We only have one component so that we can see the basic shape of the
cylindrical component. It is not quite a true cylinder - more of a sausage
shape, being a cylinder capped by two hemi-spheres. We think of it as if it
were an array of spherical components all closely strung along a straight
line.

As for the component declaration itself: simple, logical, exactly as we would
expect it to look (assuming we have been awake so far): it looks pretty much
like the declaration of a cylinder object, with vectors specifying the two
endpoints and a float giving the radius of the cylinder. The last float, of
course, is the strength of the component. Just as with spherical components,
the strength will determine the nature and degree of this component's
interaction with its fellow components. In fact, next let us give this fellow
something to interact with, shall we?

4.4.2.2          Complex Blob Constructs and Negative Strength

Beginning a new POV-Ray file called blobdem3.pov, we enter this somewhat more
complex example:

  #include "colors.inc"

  camera {
    angle 20
    location<0,2,-10>
    look_at<0,0,0>
  }

  light_source { <10, 20, -10> color White }

  blob {
    threshold .65

    sphere { <-.23,-.32,0>,.43, 1 scale <1.95,1.05,.8> }   //palm
    sphere { <+.12,-.41,0>,.43, 1 scale <1.95,1.075,.8> }  //palm
    sphere { <-.23,-.63,0>, .45, .75 scale <1.78, 1.3,1> } //midhand
    sphere { <+.19,-.63,0>, .45, .75 scale <1.78, 1.3,1> } //midhand
    sphere { <-.22,-.73,0>, .45, .85 scale <1.4, 1.25,1> } //heel
    sphere { <+.19,-.73,0>, .45, .85 scale <1.4, 1.25,1> } //heel

    cylinder { <-.65,-.28,0>, <-.65,.28,-.05>, .26, 1 }    //lower pinky
    cylinder { <-.65,.28,-.05>, <-.65, .68,-.2>, .26, 1 }  //upper pinky

    cylinder { <-.3,-.28,0>, <-.3,.44,-.05>, .26, 1 }      //lower ring
    cylinder { <-.3,.44,-.05>, <-.3, .9,-.2>, .26, 1 }     //upper ring

    cylinder { <.05,-.28,0>, <.05, .49,-.05>, .26, 1 }     //lower middle
    cylinder { <.05,.49,-.05>, <.05, .95,-.2>, .26, 1 }    //upper middle

    cylinder { <.4,-.4,0>, <.4, .512, -.05>, .26, 1 }      //lower index
    cylinder { <.4,.512,-.05>, <.4, .85, -.2>, .26, 1 }    //upper index

    cylinder { <.41, -.95,0>, <.85, -.68, -.05>, .25, 1 }  //lower thumb
    cylinder { <.85,-.68,-.05>, <1.2, -.4, -.2>, .25, 1 }  //upper thumb

    pigment { Flesh }
  }


A hand made with blobs.

As we can guess from the comments, we are building a hand here. After we
render this image, we can see there are a few problems with it. The palm and
heel of the hand would look more realistic if we used a couple dozen smaller
components rather than the half dozen larger ones we have used, and each
finger should have three segments instead of two, but for the sake of a
simplified demonstration, we can overlook these points. But there is one
thing we really need to address here: This poor fellow appears to have
horrible painful swelling of the joints!

A review of what we know of blobs will quickly reveal what went wrong. The
joints are places where the blob components overlap, therefore the combined
strength of both components at that point causes the surface to extend
further out, since it stays over the threshold longer. To fix this, what we
need are components corresponding to the overlap region which have a negative
strength to counteract part of the combined field strength. We add the
following components to our blob (see file blobdem4.pov).

  sphere { <-.65,.28,-.05>, .26, -1 } //counteract pinky knuckle bulge
  sphere { <-.65,-.28,0>, .26, -1 }   //counteract pinky palm bulge

  sphere { <-.3,.44,-.05>, .26, -1 }  //counteract ring knuckle bulge
  sphere { <-.3,-.28,0>, .26, -1 }    //counteract ring palm bulge

  sphere { <.05,.49,-.05>, .26, -1 }  //counteract middle knuckle bulge
  sphere { <.05,-.28,0>, .26, -1 }    //counteract middle palm bulge

  sphere { <.4,.512,-.05>, .26, -1 }  //counteract index knuckle bulge
  sphere { <.4,-.4,0>, .26, -1 }      //counteract index palm bulge

  sphere { <.85,-.68,-.05>, .25, -1 } //counteract thumb knuckle bulge
  sphere { <.41,-.7,0>, .25, -.89 }   //counteract thumb heel bulge


The hand without the swolen joints.

Much better! The negative strength of the spherical components counteracts
approximately half of the field strength at the points where to components
overlap, so the ugly, unrealistic (and painful looking) bulging is cut out
making our hand considerably improved. While we could probably make a yet
more realistic hand with a couple dozen additional components, what we get
this time is a considerable improvement. Any by now, we have enough basic
knowledge of blob mechanics to make a wide array of smooth, flowing organic
shapes!

4.4.3            Height Field Object

A height field is an object that has a surface that is determined by the
color value or palette index number of an image designed for that purpose.
With height fields, realistic mountains and other types of terrain can easily
be made. First, we need an image from which to create the height field. It
just so happens that POV-Ray is ideal for creating such an image.

We make a new file called image.pov and edit it to contain the following:

  #include "colors.inc"

  global_settings {
    assumed_gamma 2.2
    hf_gray_16
  }


The hf_gray_16 keyword causes the output to be in a special 16 bit grayscale
that is perfect for generating height fields. The normal 8 bit output will
lead to less smooth surfaces.

Now we create a camera positioned so that it points directly down the z-axis
at the origin.

  camera {
    location <0, 0, -10>
    look_at 0
  }


We then create a plane positioned like a wall at z=0. This plane will
completely fill the screen. It will be colored with white and gray wrinkles.

  plane { z, 10
    pigment {
      wrinkles
      color_map {
       [0 0.3*White]
       [1 White]
      }
    }
  }


Finally, create a light source.

  light_source { <0, 20, -100> color White }


We render this scene at 640x480 +A0.1 +FT. We will get an image that will
produce an excellent height field. We create a new file called hfdemo.pov and
edit it as follows:

  #include "colors.inc"


We add a camera that is two units above the origin and ten units back ...

  camera{
    location <0, 2, -10>
    look_at 0
    angle 30
  }


... and a light source.

  light_source{ <1000,1000,-1000> White }


Now we add the height field. In the following syntax, a Targa image file is
specified, the height field is smoothed, it is given a simple white pigment,
it is translated to center it around the origin and it is scaled so that it
resembles mountains and fills the screen.

  height_field {
    tga "image.tga"
    smooth
    pigment { White }
    translate <-.5, -.5, -.5>
    scale <17, 1.75, 17>
  }


We save the file and render it at 320x240 -A. Later, when we are satisfied
that the height field is the way we want it, we render it at a higher
resolution with anti-aliasing.

A height field created completely with POV-Ray.


4.4.4            Lathe Object

In the real world, lathe refers to a process of making patterned rounded
shapes by spinning the source material in place and carving pieces out as it
turns. The results can be elaborate, smoothly rounded, elegant looking
artifacts such as table legs, pottery, etc. In POV-Ray, a lathe object is
used for creating much the same kind of items, although we are refering to
the object itself rather than the means of production.

Here is some source for a really basic lathe (called lathdem1.pov).

  #include "colors.inc"

  camera {
    angle 10
    location <1, 9, -50>
    look_at <0, 2, 0>
  }

  light_source {
    <20, 20, -20> color White
  }

  lathe {
    linear_spline
    6,
    <0,0>, <1,1>, <3,2>, <2,3>, <2,4>, <0,4>
    pigment { Blue }
    finish {
      ambient .3
      phong .75
    }
  }


A simple lathe object.

We render this, and what we see is a fairly simply type of lathe, which looks
like a child's top. Let's take a look at how this code produced the effect.

First, a set of six points are declared which the raytracer connects with
lines. We note that there are only two components in the vectors which
describe these points. The lines that are drawn are assumed to be in the
x-y-plane, therefore it is as if all the z-components were assumed to be
zero. The use of a two-dimensional vector is mandatory (Attempting to use a
3D vector would trigger an error... with one exception, which we will explore
later in the discussion of splines).

Once the lines are determined, the ray-tracer rotates this line around the
y-axis, and we can imagine a trail being left through space as it goes, with
the surface of that trail being the surface of our object.

The specified points are connected with straight lines because we used the
linear_spline keyword. There are other types of splines available with the
lathe, which will result in smooth curving lines, and even rounded curving
points of transition, but we will get back to that in a moment.

First, we would like to digress a moment to talk about the difference between
a lathe and a surface of revolution object (SOR). The SOR object, described
in a separate tutorial, may seem terribly similar to the lathe at first
glance. It too declares a series of points and connects them with curving
lines and then rotates them around the y-axis. The lathe has certain
advantages, such as different kinds of splines, linear, quadratic and cubic,
and one more thing:

The simpler mathematics used by a SOR doesn't allow the curve to double back
over the same y-coordinates, thus, if using a SOR, any sudden twist which
cuts back down over the same heights that the curve previously covered will
trigger an error. For example, suppose we wanted a lathe to arc up from <0,0>
to <2,2>, then to dip back down to <4,0>. Rotated around the y-axis, this
would produce something like a gelatin mold - a rounded semi torus, hollow in
the middle. But with the SOR, as soon as the curve doubled back on itself in
the y-direction, it would become an illegal declaration.

Still, the SOR has one powerful strong point: because it uses simpler order
mathematics, it generally tends to render faster than an equivalent lathe. So
in the end, its a matter of: we use a SOR if its limitations will allow, but
when we need a more flexible shape, we go with the lathe instead.

4.4.4.1          Understanding The Concept of Splines

It would be helpful, in order to understand splines, if we had a sort of
Spline Workshop where we could practice manipulating types and points of
splines and see what the effects were like. So let's make one! Now that we
know how to create a basic lathe, it will be easy (see file lathdem2.pov):

  #include "colors.inc"

  camera {
    orthographic
    up <0, 5, 0>
    right <5, 0, 0>
    location <2.5, 2.5, -100>
    look_at <2.5, 2.5, 0>
  }

  /* set the control points to be used */

  #declare Red_Point    = <1.00, 0.00, 0>
  #declare Orange_Point = <1.75, 1.00, 0>
  #declare Yellow_Point = <2.50, 2.00, 0>
  #declare Green_Point  = <2.00, 3.00, 0>
  #declare Blue_Point   = <1.50, 4.00, 0>

  /* make the control points visible */

  cylinder { Red_Point, Red_Point - 20*z, .1
    pigment { Red }
    finish { ambient 1 }
  }

  cylinder { Orange_Point, Orange_Point - 20*z, .1
    pigment { Orange }
    finish { ambient 1 }
  }

  cylinder { Yellow_Point, Yellow_Point - 20*z, .1
    pigment { Yellow }
    finish { ambient 1 }
  }

  cylinder { Green_Point, Green_Point - 20*z, .1
    pigment { Green }
    finish { ambient 1 }
  }

  cylinder { Blue_Point, Blue_Point- 20*z, .1
    pigment { Blue }
    finish { ambient 1 }
  }

  /* something to make the curve show up */

  lathe {
    linear_spline
    5,
    Red_Point,
    Orange_Point,
    Yellow_Point,
    Green_Point,
    Blue_Point

    pigment { White }
    finish { ambient 1 }
  }


A simple "Spline Workshop".

Now, we take a deep breath. We know that all looks a bit weird, but with some
simple explanations, we can easily see what all this does.

First, we are using the orthographic camera. If we haven't read up on that
yet, a quick summary is: it renders the scene flat, eliminating perspective
distortion so that in a side view, the objects look like they were drawn on a
piece of graph paper (like in the side view of a modeller or CAD package).
There are several uses for this practical new type of camera, but here it is
allowing us to see our lathe and cylinders edge on, so that what we see is
almost like a cross section of the curve which makes the lathe, rather than
the lathe itself. To further that effect, we eliminated shadowing with the
ambient 1 finish, which of course also eliminates the need for lighting. We
have also positioned this particular side view so that <0,0> appears at the
lower left of our scene.

Next, we declared a set of points. We note that we used 3D vectors for these
points rather than the 2D vectors we expect in a lathe. That's the exception
we mentioned earlier. When we declare a 3D point, then use it in a lathe, the
lathe only uses the first two components of the vector, and whatever is in
the third component is simply ignored. This is handy here, since it makes
this example possible.

Next we do two things with the declared points. First we use them to place
small diameter cylinders at the locations of the points with the circular
caps facing the camera. Then we re-use those same vectors to determine the
lathe. Since trying to declare a 2D vector can have some odd results, and
isn't really what our cylinder declarations need anyway, we can take
advantage of the lathe's tendancy to ignore the third component by just
setting the z-coordinate in these 3D vectors to zero.

The end result is: when we render this code, we see a white lathe against a
black background showing us how the curve we've declared looks, and the
circular ends of the cylinders show us where along the x-y-plane our control
points are. In this case, it's very simple. The linear spline has been used
so our curve is just straight lines zig-zagging between the points. We change
the declarations of Red_Point and Blue_Point to read as follows (see file
lathdem3.pov).

  #declare Red_Point  = <2.00, 0.00, 0>
  #declare Blue_Point = <0.00, 4.00, 0>


Moving some points of the spline.

We re-render and, as we can see, all that happens is that the straight line
segments just move to accomodate the new position of the red and blue points.
Linear splines are so simple, we could manipulate them in our sleep, no?

Let's try something different. First, we change the points to the following
(see file lathdem4.pov).

  #declare Red_Point    = <1.00, 0.00, 0>
  #declare Orange_Point = <2.00, 1.00, 0>
  #declare Yellow_Point = <3.50, 2.00, 0>
  #declare Green_Point  = <2.00, 3.00, 0>
  #declare Blue_Point   = <1.50, 4.00, 0>



A quadratic spline lathe.

We then go down to the lathe declaration and change linear_spline to
quadratic_spline. We re-render and what do we have? Well, there's a couple of
things worthy of note this time. First, we will see that instead of straight
lines we have smooth arcs connecting the points. These arcs are made from
quadratic curves, so our lathe looks much more interesting this time. Also,
Red_Point is no longer connected to the curve. What happened?

Well, while any two points can determine a straight line, it takes three to
determine a quadratic curve. POV-Ray looks not only to the two points to be
connected, but to the point immediately preceeding them to determine the
formula of the quadratic curve that will be used to connect them. The problem
comes in at the beginning of the curve. Beyond the first point in the curve
there is no previous point. So we need to declare one. Therefore, when using
a quadratic spline, we must remember that the first point we specify is only
there so that POV-Ray can determine what curve to connect the first two
points with. It will not show up as part of the actual curve.

There's just one more thing about this lathe example. Even though our curve
is now put together with smooth curving lines, the transitions between those
lines is... well, kind of choppy, no? This curve looks like the lines between
each individual point have been terribly mismatched. Depending on what we are
trying to make, this could be acceptable, or, we might long for a more
smoothly curving shape. Fortunately, if the latter is true, we have another
option.

The quadratic spline takes longer to render than a linear spline. The math is
more complex. Still longer needs the cubic spline, yet, for a really smoothed
out shape, this is the only way to go. We go back into our example, and
simply replace quadratic_spline with cubic_spline (see file lathdem5.pov). We
render one more time, and take a look at what we have.

A cubic spline lathe.

While a quadratic spline takes three points to determine the curve, a cubic
needs four. So, as we might expect, Blue_Point has now dropped out of the
curve, just as Red_Point did, as the first and last points of our curve are
now only control points for shaping the curves between the remaining points.
But look at the transition from Orange_Point to Yellow_Point and then back to
Green_Point. Now, rather than looking mismatched, our curve segements look
like one smoothly joined curve.

The concept of splines is a handy and necessary one, which will be seen again
in the prism and polygon objects. But with a little tinkering we can quickly
get a feel for working with them.

4.4.5            Mesh Object

Mesh objects are very useful because they allow us to create objects
containing hundreds or thousands of triangles. Compared to a simple union of
triangles the mesh object stores the triangles more efficiently. Copies of
mesh objects need only a little additional memory because the triangles are
stored only once.

Almost every object can be approximated using triangles but we may need a lot
of triangles to create more complex shapes. Thus we will only create a very
simple mesh example. This example will show a very useful feature of the
triangles meshes though: a different texture can be assigned to each triangle
in the mesh.

Now let's begin. We will create a simple box with differently colored sides.
We create an empty file called meshdemo.pov and add the following lines.

  camera {
    location <20, 20, -50>
    look_at <0, 5, 0>
  }

  light_source { <50, 50, -50> color rgb<1, 1, 1> }

  #declare Red = texture {
    pigment { color rgb<0.8, 0.2, 0.2> }
    finish { ambient 0.2 diffuse 0.5 }
  }

  #declare Green = texture {
    pigment { color rgb<0.2, 0.8, 0.2> }
    finish { ambient 0.2 diffuse 0.5 }
  }

  #declare Blue = texture {
    pigment { color rgb<0.2, 0.2, 0.8> }
    finish { ambient 0.2 diffuse 0.5 }
  }


We must declare all textures we want to use inside the mesh before the mesh
is created. Textures cannot be specified inside the mesh due to the poor
memory performance that would result.

Now we add the mesh object. Three sides of the box will use individual
textures while the other will use the global mesh texture.

  mesh {
    /* top side */
    triangle { <-10, 10, -10>, <10, 10, -10>, <10, 10, 10>
      texture { Red }
    }
    triangle { <-10, 10, -10>, <-10, 10, 10>, <10, 10, 10>
      texture { Red }
    }
    /* bottom side */
    triangle { <-10, -10, -10>, <10, -10, -10>, <10, -10, 10> }
    triangle { <-10, -10, -10>, <-10, -10, 10>, <10, -10, 10> }
    /* left side */
    triangle { <-10, -10, -10>, <-10, -10, 10>, <-10, 10, 10> }
    triangle { <-10, -10, -10>, <-10, 10, -10>, <-10, 10, 10> }
    /* right side */
    triangle { <10, -10, -10>, <10, -10, 10>, <10, 10, 10>
      texture { Green }
    }
    triangle { <10, -10, -10>, <10, 10, -10>, <10, 10, 10>
      texture { Green }
    }
    /* front side */
    triangle { <-10, -10, -10>, <10, -10, -10>, <-10, 10, -10>
      texture { Blue }
    }
    triangle { <-10, 10, -10>, <10, 10, -10>, <10, -10, -10>
      texture { Blue }
    }
    /* back side */
    triangle { <-10, -10, 10>, <10, -10, 10>, <-10, 10, 10> }
    triangle { <-10, 10, 10>, <10, 10, 10>, <10, -10, 10> }
    texture {
      pigment { color rgb<0.9, 0.9, 0.9> }
      finish { ambient 0.2 diffuse 0.7 }
    }
  }


Tracing the scene at 320x240 we will see that the top, right and front side
of the box have different textures. Though this is not a very impressive
example it shows what we can do with mesh objects. More complex examples,
also using smooth triangles, can be found under the scene directory as
chesmsh.pov and robotmsh.pov.

4.4.6            Polygon Object

The polygon object can be used to create any planar, n-sided shapes like
squares, rectangles, pentagons, hexagons, octagons, etc.

A polygon is defined by a number of points that describe its shape. Since
polygons have to be closed the first point has to be repeated at the end of
the point sequence.

In the following example we will create the word POV using just one polygon
statement.

We start with thinking about the points we need to describe the desired
shape. We want the letters to lie in the x-y-plane with the letter O being at
the center. The letters extend from y=0 to y=1. Thus we get the following
points for each letter (the z coordinate is automatically set to zero).

Letter P (outer polygon):
    <-0.8, 0.0>, <-0.8, 1.0>,
    <-0.3, 1.0>, <-0.3, 0.5>,
    <-0.7, 0.5>, <-0.7, 0.0>

Letter P (inner polygon):
    <-0.7, 0.6>, <-0.7, 0.9>,
    <-0.4, 0.9>, <-0.4, 0.6>

Letter O (outer polygon):
    <-0.25, 0.0>, <-0.25, 1.0>,
    < 0.25, 1.0>, < 0.25, 0.0>

Letter O (inner polygon):
    <-0.15, 0.1>, <-0.15, 0.9>,
    < 0.15, 0.9>, < 0.15, 0.1>

Letter V:
    <0.45, 0.0>, <0.30, 1.0>,
    <0.40, 1.0>, <0.55, 0.1>,
    <0.70, 1.0>, <0.80, 1.0>,
    <0.65, 0.0>


Both letters P and O have a hole while the letter V consists of only one
polygon. We'll start with the letter V because it is easier to define than
the other two letters.

We create a new file called polygdem.pov and add the following text.

  camera {
    orthographic
    location <0, 0, -10>
    right 1.3 * 4/3 * x
    up 1.3 * y
    look_at <0, 0.5, 0>
  }

  light_source { <25, 25, -100> color rgb 1 }

  polygon {
    8,

    <0.45, 0.0>, <0.30, 1.0>, // Letter "V"
    <0.40, 1.0>, <0.55, 0.1>,
    <0.70, 1.0>, <0.80, 1.0>,
    <0.65, 0.0>,
    <0.45, 0.0>

    pigment { color rgb <1, 0, 0> }
  }


As noted above the polygon has to be closed by appending the first point to
the point sequence. A closed polygon is always defined by a sequence of
points that ends when a point is the same as the first point.

After we have created the letter V we'll continue with the letter P. Since it
has a hole we have to find a way of cutting this hole into the basic shape.
This is quite easy. We just define the outer shape of the letter P, which is
a closed polygon, and add the sequence of points that describes the hole,
which is also a closed polygon. That's all we have to do. There'll be a hole
where both polygons overlap.

In general we will get holes whenever an even number of sub-polygons inside a
single polygon statement overlap. A sub-polygon is defined by a closed
sequence of points.

The letter P consists of two sub-polygons, one for the outer shape and one
for the hole. Since the hole polygon overlaps the outer shape polygon we'll
get a hole.

After we have understood how multiple sub-polygons in a single polygon
statement work, it is quite easy to add the missing O letter.

Finally, we get the complete word POV.

  polygon {
    30,

    <-0.8, 0.0>, <-0.8, 1.0>,    // Letter "P"
    <-0.3, 1.0>, <-0.3, 0.5>,    // outer shape
    <-0.7, 0.5>, <-0.7, 0.0>,
    <-0.8, 0.0>,

    <-0.7, 0.6>, <-0.7, 0.9>,    // whole
    <-0.4, 0.9>, <-0.4, 0.6>,
    <-0.7, 0.6>

    <-0.25, 0.0>, <-0.25, 1.0>,  // Letter "O"
    < 0.25, 1.0>, < 0.25, 0.0>,  // outer shape
    <-0.25, 0.0>,

    <-0.15, 0.1>, <-0.15, 0.9>,  // whole
    < 0.15, 0.9>, < 0.15, 0.1>,
    <-0.15, 0.1>,

    <0.45, 0.0>, <0.30, 1.0>,    // Letter "V"
    <0.40, 1.0>, <0.55, 0.1>,
    <0.70, 1.0>, <0.80, 1.0>,
    <0.65, 0.0>,
    <0.45, 0.0>

    pigment { color rgb <1, 0, 0> }
  }


4.4.7            Prism Object

The prism is essentially a polygon or closed curve which is swept along a
linear path. We can imagine the shape so swept leaving a trail in space, and
the surface of that trail is the surface of our prism. The curve or polygon
making up a prism's face can be a composite of any number of sub-shapes, can
use any kind of three different splines, and can either keep a constant width
as it is swept, or slowly tapering off to a fine point on one end. But before
this gets too confusing, let's start one step at a time with the simplest
form of prism. We enter and render the following POV code (see file
prismdm1.pov).

  #include "colors.inc"

  camera {
    angle 20
    location <2, 10, -30>
    look_at <0, 1, 0>
  }

  light_source { <20, 20, -20> color White }

  prism {
    linear_sweep
    linear_spline
    0, // sweep the following shape from here ...
    1, // ... up through here
    7, // the number of points making up the shape ...

    <3,5>, <-3,5>, <-5,0>, <-3,-5>, <3, -5>, <5,0>, <3,5>

    pigment { Green }
  }


A hexagonal prism shape.

This produces a hexagonal polygon, which is then swept from y=0 through y=1.
In other words, we now have an extruded hexagon. One point to note is that
although this is a six sided figure, we have used a total of seven points.
That is because the polygon is supposed to be a closed shape, which we do
here by making the final point the same as the first. Technically, with
linear polygons, if we didn't do this, POV-Ray would automatically join the
two ends with a line to force it to close, although a warning would be
issued. However, this only works with linear splines, so we mustn't get too
casual about those warning messages!

4.4.7.1          Teaching An Old Spline New Tricks

If we followed the section on splines covered under the lathe tutorial (see
section "Understanding The Concept of Splines"), we know that there are two
additional kinds of splines besides linear: the quadratic and the cubic
spline. Sure enough, we can use these with prisms to make a more free form,
smoothly curving type of prism.

There is just one catch, and we should read this section carefully to keep
from tearing our hair out over mysterious too few points in  prism messages
which keep our prism from rendering. We can probably guess where this is
heading: how to close a non-linear spline. Unlike the linear spline, which
simply draws a line between the last and first points if we forget to make
the last point equal to the first, quadratic and cubic splines are a little
more fussy.

First of all, we remember that quadratic splines determine the equation of
the curve which connects any two points based on those two points and the
previous point, so the first point in any quadratic spline is just a control
point and won't actually be part of the curve. What this means is: when we
make our shape out of a quadratic spline, we must match the second point to
the last, since the first point is not on the curve - it's just a control
point needed for computational purposes.

Likewise, cubic splines need both the first and last points to be control
points, therefore, to close a shape made with a cubic spline, we must match
the second point to the second from last point. If we don't match the correct
points on a quadratic or cubic shape, that's when we will get the too few
points in prism error. POV-Ray is still waiting for us to close the shape,
and when it runs out of points without seeing the closure, an error is
issued.

Confused? Okay, how about an example? We replace the prism in our last bit of
code with this one (see file prismdm2.pov).

  prism {
    cubic_spline
    0, // sweep the following shape from here ...
    1, // ... up through here
    6, // the number of points making up the shape ...

    < 3, -5>, // point#1 (control point... not on curve)
    < 3,  5>, // point#2  ... THIS POINT ...
    <-5,  0>, // point#3
    < 3, -5>, // point#4
    < 3,  5>, // point#5 ... MUST MATCH THIS POINT
    <-5,  0>  // point#6 (control point... not on curve)

    pigment { Green }
  }


A cubic, triangular prism shape.

This simple prism produces what looks like an extruded triangle with its
corners sanded smoothly off. Points two, three and four are the corners of
the triangle and point five closes the shape by returning to the location of
point two. As for points one and six, they are our control points, and aren't
part of the shape - they're just there to help compute what curves to use
between the other points.

4.4.7.2          Smooth Transitions

Now a handy thing to note is that we have made point one equal point four,
and also point six equals point three. Yes, this is important. Although this
prism would still be legally closed if the control points were not what we've
made them, the curve transitions between points would not be as smooth. We
change points one and six to <4,6> and <0,7> respectively and re-render to
see how the back edge of the shape is altered (see file prismdm3.pov).

To put this more generally, if we want a smooth closure on a cubic spline, we
make the first control point equal to the third from last point, and the last
control point equal to the third point. On a quadratic spline, the trick is
similar, but since only the first point is a control point, make that equal
to the second from last point.

4.4.7.3          Multiple Sub-Shapes

Just as with the polygon object (see section "Polygon Object") the prism is
very flexible, and allows us to make one prism out of several sub-prisms. To
do this, all we need to do is keep listing points after we have already
closed the first shape. The second shape can be simply an add on going off in
another direction from the first, but one of the more interesting features is
that if any even number of sub-shapes overlap, that region where they overlap
behaves as though it has been cut away from both sub-shapes. Let's look at
another example. Once again, same basic code as before for camera, light and
so forth, but we substitute this complex prism (see file prismdm4.pov).

  prism {
    linear_sweep
    cubic_spline
    0,  // sweep the following shape from here ...
    1,  // ... up through here
    18, // the number of points making up the shape ...

    <3,-5>, <3,5>, <-5,0>, <3, -5>, <3,5>, <-5,0>, // sub-shape #1
    <2,-4>, <2,4>, <-4,0>, <2,-4>, <2,4>, <-4,0>,  // sub-shape #2
    <1,-3>, <1,3>, <-3,0>, <1, -3>, <1,3>, <-3,0>  // sub-shape #3

    pigment { Green }
  }


Using sub-shapes to create a more complex shape.

For readability purposes, we have started a new line every time we moved on
to a new sub-shape, but the ray-tracer of course tells where each shape ends
based on whether the shape has been closed (as described earlier). We render
this new prism, and look what we've got. It's the same familiar shape, but it
now looks like a smaller version of the shape has been carved out of the
center, then the carved piece was sanded down even smaller and set back in
the hole.

Simply, the outer rim is where only sub-shape one exists, then the carved out
part is where sub-shapes one and two overlap. In the extreme center, the
object reappears because sub-shapes one, two, and three overlap, returning us
to an odd number of overlapping pieces. Using this technique we could make
any number of extremely complex prism shapes!

4.4.7.4          Conic Sweeps And The Tapering Effect

In our original prism, the keyword linear_sweep is actually optional. This is
the default sweep assumed for a prism if no type of sweep is specified. But
there is another, extremely useful kind of sweep: the conic sweep. The basic
idea is like the original prism, except that while we are sweeping the shape
from the first height through the second height, we are constantly expanding
it from a single point until, at the second height, the shape has expanded to
the original points we made it from. To give a small idea of what such
effects are good for, we replace our existing prism with this (see file
prismdm5.pov):

  prism {
    conic_sweep
    linear_spline
    0, // height 1
    1, // height 2
    5, // the number of points making up the shape...

    <4,4>,<-4,4>,<-4,-4>,<4,-4>,<4,4>

    rotate <180, 0, 0>
    translate <0, 1, 0>
    scale <1, 4, 1>
    pigment { gradient y scale .2 }
  }


Creating a pyramid using conic sweeping.

The gradient pigment was selected to give some definition to our object
without having to fix the lights and the camera angle right at this moment,
but when we render it, we what we've created? A horizontally striped pyramid!
By now we can recognize the linear spline connecting the four points of a
square, and the familiar final point which is there to close the spline.

Notice all the transformations in the object declaration. That's going to
take a little explanation. The rotate and translate are easy. Normally, a
conic sweep starts full sized at the top, and tapers to a point at y=0, but
of course that would be upside down if we're making a pyramid. So we flip the
shape around the x-axis to put it rightside up, then since we actually
orbitted around the point, we translate back up to put it in the same
position it was in when we started.

The scale is to put the proportions right for this example. The base is eight
units by eight units, but the height (from y=1 to y=0) is only one unit, so
we've stretched it out a little. At this point, we're probably thinking, "why
not just sweep up from y=0 to y=4 and avoid this whole scaling thing?"

That is a very important gotcha! with conic sweeps. To see what's wrong with
that, let's try and put it into practice (see file prismdm6.pov). We must
make sure to remove the scale statement, and then replace the line which
reads

  1, // height 2
with

  1, // height 2


This sets the second height at y=4, so let's re-render and see if the effect
is the same.

Choosing a second height larger than one for the conic sweep.

Whoa! Our height is correct, but our pyramid's base is now huge! What went
wrong here? Simple. The base, as we described it with the points we used
actually occurs at y=1 no matter what we set the second height for. But if we
do set the second height higher than one, once the sweep passes y=1, it keeps
expanding outward along the same lines as it followed to our original base,
making the actual base bigger and bigger as it goes.

To avoid losing control of a conic sweep prism, it is usually best to let the
second height stay at y=1, and use a scale statement to adjust the height
from its unit size. This way we can always be sure the base's corners remain
where we think they are.

That leads to one more interesting thing about conic sweeps. What if we for
some reason don't want them to taper all the way to a point? What if instead
of a complete pyramid, we want more of a ziggurat step? Easily done. After
putting the second height back to one, and replacing our scale statment, we
change the line which reads

  0, // height 1
to

  0, // height 1


Increasing the first height for the conic sweep.

When we re-render, we see that the sweep stops short of going all the way to
its point, giving us a pyramid without a cap. Exactly how much of the cap is
cut off depends on how close the first height is to the second height.

4.4.8            Superquadric Ellipsoid Object

Sometimes we want to make an object that does not have perfectly sharp edges
like a box does. Then, the superquadric ellipsoid is a useful object. It is
described by the simple syntax:

  superellipsoid { <r, n> }


Where r and n are float values greater than zero and less than or equal to
one. Let's make a superellipsoid and experiment with the values of r and n to
see what kind of shapes we can make.

We create a file called supellps.pov and edit it as follows:

  #include "colors.inc"

  camera {
    location <10, 5, -20>
    look_at 0
    angle 15
  }

  background { color rgb <.5, .5, .5> }

  light_source { <10, 50, -100> White }


The addition of a gray background makes it a little easier to see our object.
We now type:

  superellipsoid { <.25, .25>
    pigment { Red }
  }


We save the file and trace it at 200x150 -A to see the shape. It will look
like a box, but the edges will be rounded off. Now let's experiment with
different values of r and n. For the next trace, try <1, 0.2>. The shape now
looks like a cylinder, but the top edges are rounded. Now try <0.1, 1>. This
shape is an odd one! We don't know exactly what to call it, but it is
interesting. Finally, lets try <1, 1>. Well, this is more familiar... a
sphere!

There are a couple of facts about superellipsoids we should know. First, we
should not use a value of 0 for either r nor n. This will cause POV-Ray to
incorrectly make a black box instead of our desired shape. Second, very small
values of r and n may yield strange results so they should be avoided.
Finally, the Sturmian root solver will not work with superellipsoids.

Superellipsoids are finite objects so they respond to auto-bounding and can
be used in CSG.

Now let's use the superellipsoid to make something that would be useful in a
scene. We will make a tiled floor and place a couple of superellipsoid
objects hovering over it. We can start with the file we have already made.

We rename it to tiles.pov and edit it so that it reads as follows:

  #include "colors.inc"
  #include "textures.inc"

  camera {
    location <10, 5, -20>
    look_at 0
    angle 15
  }
  background { color rgb <.5, .5, .5> }

  light_source{ <10, 50, -100> White }


Note that we have added #include "textures.inc" so we can use pre-defined
textures. Now we want to define the superellipsoid which will be our tile.

  #declare Tile = superellipsoid { <0.5, 0.1>
    scale <1, .05, 1>
  }


Superellipsoids are roughly 2*2*2 units unless we scale them otherwise. If we
wish to lay a bunch of our tiles side by side, they will have to be offset
from each other so they don't overlap. We should select an offset value that
is slightly more than 2 so that we have some space between the tiles to fill
with grout. So we now add this:

  #declare Offset = 2.1


We now want to lay down a row of tiles. Each tile will be offset from the
original by an ever-increasing amount in both the +z and -z directions. We
refer to our offset and multiply by the tile's rank to determine the position
of each tile in the row. We also union these tiles into a single object
called Row like this:

  #declare Row = union {
    object { Tile }
    object { Tile translate z*Offset }
    object { Tile translate z*Offset*2 }
    object { Tile translate z*Offset*3 }
    object { Tile translate z*Offset*4 }
    object { Tile translate z*Offset*5 }
    object { Tile translate z*Offset*6 }
    object { Tile translate z*Offset*7 }
    object { Tile translate z*Offset*8 }
    object { Tile translate z*Offset*9 }
    object { Tile translate z*Offset*10 }
    object { Tile translate -z*Offset }
    object { Tile translate -z*Offset*2 }
    object { Tile translate -z*Offset*3 }
    object { Tile translate -z*Offset*4 }
    object { Tile translate -z*Offset*5 }
    object { Tile translate -z*Offset*6 }
  }


This gives us a single row of 17 tiles, more than enough to fill the screen.
Now we must make copies of the Row and translate them, again by the offset
value, in both the +x and -x directions in ever increasing amounts in the
same manner.

  object { Row }
  object { Row translate x*Offset }
  object { Row translate x*Offset*2 }
  object { Row translate x*Offset*3 }
  object { Row translate x*Offset*4 }
  object { Row translate x*Offset*5 }

  object { Row translate x*Offset*6 }
  object { Row translate x*Offset*7 }
  object { Row translate -x*Offset }
  object { Row translate -x*Offset*2 }
  object { Row translate -x*Offset*3 }
  object { Row translate -x*Offset*4 }
  object { Row translate -x*Offset*5 }
  object { Row translate -x*Offset*6 }
  object { Row translate -x*Offset*7 }


Finally, our tiles are complete. But we need a texture for them. To do this
we union all of the Rows together and apply a White Marble pigment and a
somewhat shiny reflective surface to it:

  union{
    object { Row }
    object { Row translate x*Offset }
    object { Row translate x*Offset*2 }
    object { Row translate x*Offset*3 }
    object { Row translate x*Offset*4 }
    object { Row translate x*Offset*5 }
    object { Row translate x*Offset*6 }
    object { Row translate x*Offset*7 }
    object { Row translate -x*Offset }
    object { Row translate -x*Offset*2 }
    object { Row translate -x*Offset*3 }
    object { Row translate -x*Offset*4 }
    object { Row translate -x*Offset*5 }
    object { Row translate -x*Offset*6 }
    object { Row translate -x*Offset*7 }
    pigment { White_Marble }
    finish { phong 1 phong_size 50 reflection .35 }
  }


We now need to add the grout. This can simply be a white plane. We have
stepped up the ambient here a little so it looks whiter.

  plane { y, 0  //this is the grout
    pigment { color White }
    finish { ambient .4 diffuse .7 }
  }


To complete our scene, let's add five different superellipsoids, each a
different color, so that they hover over our tiles and are reflected in them.


  superellipsoid {
    <0.1, 1>
    pigment { Red }
    translate <5, 3, 0>
    scale .45
  }

  superellipsoid {
    <1, 0.25>
    pigment { Blue }
    translate <-5, 3, 0>
    scale .45
  }

  superellipsoid {
    <0.2, 0.6>
    pigment { Green }
    translate <0, 3, 5>
    scale .45
  }

  superellipsoid {
    <0.25, 0.25>
    pigment { Yellow }
    translate <0, 3, -5>
    scale .45
  }

  superellipsoid {
    <1, 1>
    pigment { Pink }
    translate y*3
    scale .45
  }


Some superellipsoids hovering above a tiled floor.

We trace the scene at 320x200 -A to see the result. If we are happy with
that, we do a final trace at 640x480 +A0.2.

4.4.9            Surface of Revolution Object

Bottles, vases and glasses make nice objects in ray-traced scenes. We want to
create a golden cup using the surface of revolution object (SOR object).

We first start by thinking about the shape of the final object. It is quite
difficult to come up with a set of points that describe a given curve without
the help of a modelling program supporting POV-Eay's surface of revolution
object. If such a program is available we should take advantage of it.

The point configuration of our cup object.

We will use the point configuration shown in the figure above. There are
eight points describing the curve that will be rotated about the y-axis to
get our cup. The curve was calculated using the method described in the
reference section (see "Surface of Revolution").

Now it is time to come up with a scene that uses the above SOR object. We
edit a file called sordemo.pov and enter the following text.

  #include "colors.inc"
  #include "golds.inc"

  global_settings { assumed_gamma 2.2 }

  camera {
    location <10, 15, -20>
    look_at <0, 5, 0>
    angle 45
  }

  background { color rgb<0.2, 0.4, 0.8>  }

  light_source { <100, 100, -100> color rgb 1 }

  plane { y, 0
    pigment { checker color Red, color Green scale 10 }
  }

  sor {
    8,
    <0.0,  -0.5>,
    <3.0,   0.0>,
    <1.0,   0.2>,
    <0.5,   0.4>,
    <0.5,   4.0>,
    <1.0,   5.0>,
    <3.0,  10.0>,
    <4.0,  11.0>
    texture { T_Gold_1B }
  }


The scene contains our cup object resting on a checkered plane. Tracing this
scene at a resolution of 320x200 results in the image below.

A surface of revolution object.

The surface of revolution is described by starting with the number of points
followed by the points with ascending heights. Each point determines the
radius the curve for a given height. E. g. the first point tells POV-Ray that
at height -0.5 the radius is 0. We should take care that each point has a
larger height than its predecessor. If this is not the case the program will
abort with an error message.

4.4.10           Text Object

Creating text objects using POV-Ray always used to mean that the letters had
to be built either from CSG, a painstaking process or by using a black and
white image of the letters as a height field, a method that was only somewhat
satisfactory. Now, for POV-Ray 3.0, a new primitive has been introduced that
can use any TrueType font to create text objects. These objects can be used
in CSG, transformed and textured just like any other POV primitive.

For this tutorial, we will make two uses of the text object. First, let's
just make some block letters sitting on a checkered plane. Any TTF font
should do, but for this tutorial, we will use the ones bundled with POV-Ray
3.0.

We create a file called textdemo.pov and edit it as follows:

  #include "colors.inc"

  camera {
    location <0, 1, -10>
    look_at 0
    angle 35
  }

  light_source { <500,500,-1000> White }

  plane { y,0
    pigment { checker Green White }
  }


Now let's add the text object. We will use the font timrom.ttf and we will
create the string POV-RAY 3.0. For now, we will just make the letters red.
The syntax is very simple. The first string in quotes is the font name, the
second one is the string to be rendered. The two floats are the thickness and
offset values. The thickness float determines how thick the block letters
will be. Values of .5 to 2 are usually best for this. The offset value will
add to the kerning distance of the letters. We will leave this a 0 for now.

  text { ttf "timrom.ttf" "POV-RAY 3.0" 1, 0
    pigment { Red }
  }


Rendering this at 200x150 -A, we notice that the letters are off to the right
of the screen. This is because they are placed so that the lower left front
corner of the first letter is at the origin. To center the string we need to
translate it -x some distance. But how far? In the docs we see that the
letters are all 0.5 to 0.75 units high. If we assume that each one takes
about 0.5 units of space on the x-axis, this means that the string is about 6
units long (12 characters and spaces). Let's translate the string 3 units
along the negative x-axis.

  text { ttf "timrom.ttf" "POV-RAY 3.0" 1, 0
    pigment { Red }
    translate -3*x
  }


That's better. Now let's play around with some of the parameters of the text
object. First, let's raise the thickness float to something outlandish... say
25!

  text { ttf "timrom.ttf" "POV-RAY 3.0" 25, 0
    pigment { Red }
    translate -2.25*x
  }


Actually, that's kind of cool. Now let's return the thickness value to 1 and
try a different offset value. Change the offset float from 0 to 0.1 and
render it again.

Wait a minute?! The letters go wandering off up at an angle! That is not what
the docs describe! It almost looks as if the offset value applies in both the
x- and y-axis instead of just the x axis like we intended. Could it be that a
vector is called for here instead of a float? Let's try it. We replace 0.1
with 0.1*x and render it again.

That works! The letters are still in a straight line along the x-axis, just a
little further apart. Let's verify this and try to offset just in the y-axis.
We replace 0.1*x with 0.1*y. Again, this works as expected with the letters
going up to the right at an angle with no additional distance added along the
x-axis. Now let's try the z-axis. We replace 0.1*y with 0.1*z. Rendering this
yields a disappointment. No offset occurs! The offset value can only be
applied in the x- and y-directions.

Let's finish our scene by giving a fancier texture to the block letters,
using that cool large thickness value, and adding a slight y-offset. For fun,
we will throw in a sky sphere, dandy up our plane a bit, and use a little
more interesting camera viewpoint (we render the following scene at 640x480
+A0.2):

  #include "colors.inc"

  camera {
    location <-5,.15,-2>
    look_at <.3,.2,1>
    angle 35
  }

  light_source { <500,500,-1000> White }

  plane { y,0
    texture {
      pigment { SeaGreen }
      finish { reflection .35 specular 1 }
      normal { ripples .35 turbulence .5 scale .25 }
    }
  }

  text { ttf "timrom.ttf" "POV-RAY 3.0" 25, 0.1*y
    pigment { BrightGold }
    finish { reflection .25 specular 1 }
    translate -3*x
  }

  #include "skies.inc"

  sky_sphere { S_Cloud5 }


Let's try using text in a CSG object. We will attempt to create an inlay in a
stone block using a text object. We create a new file called textcsg.pov and
edit it as follows:

  #include "colors.inc"

  #include "stones.inc"

  background { color rgb 1 }

  camera {
    location <-3, 5, -15>
    look_at 0
    angle 25
  }

  light_source { <500,500,-1000> White }


Now let's create the block. We want it to be about eight units across because
our text string (POV-RAY 3.0) is about six units long. We also want it about
four units high and about one unit deep. But we need to avoid a potential
coincident surface with the text object so we will make the first
z-coordinate 0.1 instead of 0. Finally, we will give this block a nice stone
texture.

  box { <-3.5, -1, 0.1>, <3.5, 1, 1>
    texture { T_Stone10 }
  }


Next, we want to make the text object. We can use the same object we used in
the first tutorial except we will use slightly different thickness and offset
values.

  text { ttf "timrom.ttf" "POV-RAY 3.0" 0.15, 0
    pigment { BrightGold }
    finish { reflection .25 specular 1 }
    translate -3*x
  }


We remember that the text object is placed by default so that its front
surface lies directly on the x-y-plane. If the front of the box begins at
z=0.1 and thickness is set at 0.15, the depth of the inlay will be 0.05
units. We place a difference block around the two objects.

  difference {
    box { <-3.5, -1, 0.1>, <3.5, 1, 1>
      texture { T_Stone10 }
    }
    text { ttf "timrom.ttf" "POV-RAY 3.0" 0.15, 0
      pigment { BrightGold }
      finish { reflection .25 specular 1 }
      translate -3*x
    }
  }


Text carved from stone.

We render this at 200x150 -A. We can see the inlay clearly and that it is
indeed a bright gold color. We re-render at 640x480 +A0.2 to see the results
more clearly, but be forewarned... this trace will take a little time.

4.4.11           Torus Object

A torus can be thought of as a donut or an inner-tube. It is a shape that is
vastly useful in many kinds of CSG so POV-Ray has adopted this 4th order
quartic polynomial as a primitive shape. The syntax for a torus is so simple
that it makes it a very easy shape to work with once we learn what the two
float values mean. Instead of a lecture on the subject, let's create one and
do some experiments with it.

We create a file called tordemo.pov and edit it as follows:

  #include "colors.inc"

  camera {
    location <0, .1, -25>
    look_at 0
    angle 30
  }

  background { color Gray50 } // to make the torus easy to see

  light_source{ <300, 300, -1000> White }

  torus { 4, 1        // major and minor radius
    rotate -90*x      // so we can see it from the top
    pigment { Green }
  }


We trace the scene. Well, it's a donut alright. Let's try changing the major
and minor radius values and see what happens. We change them as follows:

  torus { 5, .25      // major and minor radius


That looks more like a hula-hoop! Let's try this:

  torus { 3.5, 2.5    // major and minor radius


Whoa! A donut with a serious weight problem!

With such a simple syntax, there isn't much else we can do to a torus besides
change its texture... or is there? Let's see...

Torii are very useful objects in CSG. Let's try a little experiment. We make
a difference of a torus and a box:

  difference {
    torus { 4, 1
      rotate x*-90  // so we can see it from the top
    }
    box { <-5, -5, -1>, <5, 0, 1> }
    pigment { Green }
  }


Interesting... a half-torus. Now we add another one flipped the other way.
Only, let's declare the original half-torus and the necessary transformations
so we can use them again:

  #declare Half_Torus = difference {
    torus { 4, 1
      rotate -90*x  // so we can see it from the top
    }
    box { <-5, -5, -1>, <5, 0, 1> }
    pigment { Green }
  }

  #declare Flip_It_Over = 180*x

  #declare Torus_Translate = 8  // twice the major radius


Now we create a union of two Half_Torus objects:

  union {
    object { Half_Torus }
    object { Half_Torus
      rotate Flip_It_Over
      translate Torus_Translate*x
    }
  }


This makes an S-shaped object, but we can't see the whole thing from our
present camera. Let's add a few more links, three in each direction, move the
object along the +z-direction and rotate it about the +y-axis so we can see
more of it. We also notice that there appears to be a small gap where the
half torii meet. This is due to the fact that we are viewing this scene from
directly on the x-z-plane. We will change the camera's y-coordinate from 0 to
0.1 to eliminate this.

  union {
    object { Half_Torus }
    object { Half_Torus
      rotate Flip_It_Over
      translate x*Torus_Translate
    }
    object { Half_Torus
      translate x*Torus_Translate*2
    }
    object { Half_Torus
      rotate Flip_It_Over
      translate x*Torus_Translate*3
    }
    object { Half_Torus
      rotate Flip_It_Over
      translate -x*Torus_Translate
    }
    object { Half_Torus
      translate -x*Torus_Translate*2
    }
    object { Half_Torus
      rotate Flip_It_Over
      translate -x*Torus_Translate*3
    }
    object { Half_Torus
      translate -x*Torus_Translate*4
    }
    rotate y*45
    translate z*20
  }


Rendering this we see a cool, undulating, snake-like something-or-other.
Neato. But we want to model something useful, something that we might see in
real
life. How about a chain?

Thinking about it for a moment, we realize that a single link of a chain can
be easily modeled using two half toruses and two cylinders. We create a new
file. We can use the same camera, background, light source and declared
objects and transformations as we used in tordemo.pov:

  #include "colors.inc"

  camera {
    location <0, .1, -25>
    look_at 0
    angle 30
  }

  background { color Gray50 }

  light_source{ <300, 300, -1000> White }

  #declare Half_Torus = difference {
    torus { 4,1
      sturm
      rotate x*-90  // so we can see it from the top
    }
    box { <-5, -5, -1>, <5, 0, 1> }
    pigment { Green }
  }

  #declare Flip_It_Over = x*180

  #declare Torus_Translate = 8


Now, we make a complete torus of two half toruses:

  union {
    object { Half_Torus }
    object { Half_Torus rotate Flip_It_Over }
  }


This may seem like a wasteful way to make a complete torus, but we are really
going to move each half apart to make room for the cylinders. First, we add
the declared cylinder before the union:

  #declare Chain_Segment = cylinder { <0, 4, 0>, <0, -4, 0>, 1
    pigment { Green }
  }


We then add two chain segments to the union and translate them so that they
line up with the minor radius of the torus on each side:

  union {
    object { Half_Torus }
    object { Half_Torus rotate Flip_It_Over }
    object { Chain_Segment translate  x*Torus_Translate/2 }
    object { Chain_Segment translate -x*Torus_Translate/2 }
  }


Now we translate the two half toruses +y and -y so that the clipped ends meet
the ends of the cylinders. This distance is equal to half of the previously
declared Torus_Translate:

  union {
    object { Half_Torus
      translate y*Torus_Translate/2
    }
    object { Half_Torus
      rotate Flip_It_Over
      translate -y*Torus_Translate/2
    }
    object { Chain_Segment
      translate x*Torus_Translate/2
    }
    object { Chain_Segment
      translate -x*Torus_Translate/2
    }
  }


We render this and viola! A single link of a chain. But we aren't done yet!
Whoever heard of a green chain? We would rather use a nice metallic color
instead. First, we remove any pigment blocks in the declared toruses and
cylinders. Then we add the following before the union:

  #declare Chain_Gold = texture {
    pigment { BrightGold }
    finish {
      ambient .1
      diffuse .4
      reflection .25
      specular 1
      metallic
    }
  }


We then add the texture to the union and declare the union as a single link:

  #declare Link = union {
    object { Half_Torus
      translate y*Torus_Translate/2
    }
    object { Half_Torus
      rotate Flip_It_Over
      translate -y*Torus_Translate/2
    }
    object { Chain_Segment
      translate x*Torus_Translate/2
    }
    object { Chain_Segment
      translate -x*Torus_Translate/2
    }
    texture { Chain_Gold }
  }


Now we make a union of two links. The second one will have to be translated
+y so that its inner wall just meets the inner wall of the other link, just
like the links of a chain. This distance turns out to be double the
previously declared Torus_Translate minus 2 (twice the minor radius). This
can be described by the expression:

  Torus_Translate*2-2*y



We declare this expression as follows:

  #declare Link_Translate = Torus_Translate*2-2*y


In the object block, we will use this declared value so that we can multiply
it to create other links. Now, we rotate the second link 90*y so that it is
perpendicular to the first, just like links of a chain. Finally, we scale the
union by 1/4 so that we can see the whole thing:

  union {
    object { Link }
    object { Link translate y*Link_Translate rotate y*90 }
    scale .25
  }


We render this and we will see a very realistic pair of links. If we want to
make an entire chain, we must declare the above union and then create another
union of this declared object. We must be sure to remove the scaling from the
declared object:

  #declare Link_Pair =
  union {
    object { Link }
    object { Link translate y*Link_Translate rotate y*90 }
  }


Now we declare our chain:

  #declare Chain = union {
    object { Link_Pair}
    object { Link_Pair translate  y*Link_Translate*2 }
    object { Link_Pair translate  y*Link_Translate*4 }
    object { Link_Pair translate  y*Link_Translate*6 }
    object { Link_Pair translate -y*Link_Translate*2 }
    object { Link_Pair translate -y*Link_Translate*4 }
    object { Link_Pair translate -y*Link_Translate*6 }
  }


And finally we create our chain with a couple of transformations to make it
easier to see. These include scaling it down by a factor of 1/10, and
rotating it so that we can clearly see each link:

  object { Chain scale .1 rotate <0, 45, -45> }


The torus object can be used to create chains.

We render this and we should see a very realistic gold chain stretched
diagonally across the screen.

4.5              CSG Objects

Constructive Solid Geometry, CSG, is a powerful tool to combine primitive
objects to create more complex objects as shown in the following sections.

4.5.1            What is CSG?

CSG stands for Constructive Solid Geometry. POV-Ray allows us to construct
complex solids by combining primitive shapes in four different ways. These
are union, where two or more shapes are added together. Intersection, where
two or more shapes are combined to make a new shape that consists of the area
common to both shapes. Difference, where subsequent shapes are subtracted
from the first shape. And last not least merge, which is like a union where
the surfaces inside the union are removed (useful in transparent CSG
objects). We will deal with each of these in detail in the next few sections.


CSG objects can be extremely complex. They can be deeply nested. In other
words there can be unions of differences or intersections of merges or
differences of intersections or even unions of intersections of differences
of merges... ad infinitum. CSG objects are (almost always) finite objects and
thus respond to auto-bounding and can be transformed like any other POV
primitive shape.

4.5.2            CSG Union

Let's try making a simple union. Create a file called csgdemo.pov and edit it
as follows:

  #include "colors.inc"

  camera {
    location <0, 1, -10>
    look_at 0
    angle 36
  }

  light_source { <500, 500, -1000> White }

  plane { y, -1.5
    pigment { checker Green White }
  }


Let's add two spheres each translated 0.5 units along the x-axis in each
direction. We color one blue and the other red.

  sphere { <0, 0, 0>, 1
    pigment { Blue }
    translate -0.5*x
  }
  sphere { <0, 0, 0>, 1
    pigment { Red }
    translate 0.5*x
  }


We trace this file at 200x150 -A. Now we place a union block around the two
spheres. This will create a single CSG union out of the two objects.

  union{
    sphere { <0, 0, 0>, 1
      pigment { Blue }
      translate -0.5*x
    }
    sphere { <0, 0, 0>, 1
      pigment { Red }
      translate 0.5*x
    }
  }


We trace the file again. The union will appear no different from what each
sphere looked like on its own, but now we can give the entire union a single
texture and transform it as a whole. Let's do that now.

  union{
    sphere { <0, 0, 0>, 1
      translate -0.5*x*
    }
    sphere { <0, 0, 0>, 1
      translate 0.5*x
    }
    pigment { Red }
    scale <1, .25, 1>
    rotate <30, 0, 45>
  }


We trace the file again. As we can see, the object has changed dramatically.
We experiment with different values of scale and rotate and try some
different textures.

There are many advantages of assigning only one texture to a CSG object
instead of assigning the texture to each individual component. First, it is
much easier to use one texture if our CSG object has a lot of components
because changing the objects appearance involves changing only one single
texture. Second, the file parses faster because the texture has to be parsed
only once. This may be a great factor when doing large scenes or animations.
Third, using only one texture saves memory because the texture is only stored
once and referenced by all components of the CSG object. Assigning the
texture to all n components means that it is stored n times.

4.5.3            CSG Intersection

Now let's use these same spheres to illustrate the next kind of CSG object,
the intersection. We change the word union to intersection and delete the
scale and rotate statements:

  intersection {
    sphere { <0, 0, 0>, 1
      translate -0.5*x
    }
    sphere { <0, 0, 0>, 1
      translate 0.5*x
    }
    pigment { Red }
  }


We trace the file and will see a lens-shaped object instead of the two
spheres. This is because an intersection consists of the area shared by both
shapes, in this case the lens-shaped area where the two spheres overlap. We
like this lens-shaped object so we will use it to demonstrate differences.

4.5.4            CSG Difference

We rotate the lens-shaped intersection about the y-axis so that the broad
side is facing the camera.

  intersection{
    sphere { <0, 0, 0>, 1
      translate -0.5*x
    }
    sphere { <0, 0, 0>, 1
      translate 0.5*x
    }
    pigment { Red }
    rotate 90*y
  }


Let's create a cylinder and stick it right in the middle of the lens.

  cylinder { <0, 0, -1> <0, 0, 1>, .35
    pigment { Blue }
  }


We render the scene to see the position of the cylinder. We will place a
difference block around both the lens-shaped intersection and the cylinder
like this:

  difference {
    intersection {
      sphere { <0, 0, 0>, 1
        translate -0.5*x
      }
      sphere { <0, 0, 0>, 1
        translate 0.5*x
      }
      pigment { Red }
      rotate 90*y
    }
    cylinder { <0, 0, -1> <0, 0, 1>, .35
      pigment { Blue }
    }
  }


We render the file again and see the lens-shaped intersection with a neat
hole in the middle of it where the cylinder was. The cylinder has been
subtracted from the intersection. Note that the pigment of the cylinder
causes the surface of the hole to be colored blue. If we eliminate this
pigment the surface of the hole will be red.

OK, let's get a little wilder now. Let's declare our perforated lens object
to give it a name. Let's also eliminate all textures in the declared object
because we will want them to be in the final union instead.

  #declare Lens_With_Hole = difference {
    intersection {
      sphere { <0, 0, 0>, 1
        translate -0.5*x
      }
      sphere { <0, 0, 0>, 1
        translate 0.5*x
      }
      rotate 90*y
    }
    cylinder { <0, 0, -1> <0, 0, 1>, .35 }
  }


Let's use a union to build a complex shape composed of copies of this object.


  union {
    object { Lens_With_Hole translate <-.65, .65, 0> }
    object { Lens_With_Hole translate <.65, .65, 0> }
    object { Lens_With_Hole translate <-.65, -.65, 0> }
    object { Lens_With_Hole translate <.65, -.65, 0> }
    pigment { Red }
  }


We render the scene. An interesting object to be sure. But let's try
something more. Let's make it a partially-transparent object by adding some
filter to the pigment block.

  union {
    object { Lens_With_Hole translate <-.65, .65, 0> }
    object { Lens_With_Hole translate <.65, .65, 0> }
    object { Lens_With_Hole translate <-.65, -.65, 0> }
    object { Lens_With_Hole translate <.65, -.65, 0> }
    pigment { Red filter .5 }
  }


We render the file again. This looks pretty good... only... we can see parts
of each of the lens objects inside the union! This is not good.

4.5.5            CSG Merge

This brings us to the fourth kind of CSG object, the merge. Merges are the
same as unions, but the geometry of the objects in the CSG that is inside the
merge is not traced. This should eliminate the problem with our object. Let's
try it.

  merge {
    object { Lens_With_Hole translate <-.65, .65, 0> }
    object { Lens_With_Hole translate <.65, .65, 0> }
    object { Lens_With_Hole translate <-.65, -.65, 0> }
    object { Lens_With_Hole translate <.65, -.65, 0> }
    pigment { Red filter .5 }
  }


4.5.6            CSG Pitfalls


4.5.6.1          Coincidence Surfaces

POV-Ray uses inside/outside tests to determine the points at which a ray
intersects a CSG object. A problem arises when the surfaces of two different
shapes coincide because there is no way (due to numerical problems) to tell
whether a point on the coincident surface belongs to one shape or the other.

Look at the following example where a cylinder is used to cut a hole in a
larger box.

  difference {
    box { -1, 1 pigment { Red } }
    cylinder { -z, z, 0.5 pigment { Green } }
  }


If we trace this object we see red speckles where the hole is supposed to be.
This is caused by the coincident surfaces of the cylinder and the box. One
time the cylinder's surface is hit first by a viewing ray, resulting in the
correct rendering of the hole, and another time the box is hit first, leading
to a wrong result where the hole vanishes and red speckles appear.

This problem can be avoided by increasing the size of the cylinder to get rid
of the coincidence surfaces. This is done by:

  difference {
    box { -1, 1 pigment { Red } }
    cylinder { -1.001*z, 1.001*z, 0.5 pigment { Green } }
  }


In general we have to make the subtracted object a little bit larger in a CSG
difference. We just have to look for coincident surfaces and increase the
subtracted object appropriately to get rid of those surfaces.

The same problem occurs in CSG intersections and is also avoided by scaling
some of the involved objects.

4.6              The Light Source

In any ray-traced scene, the light needed to illuminate our objects and their
surfaces must come from a light source. There are many kinds of light sources
available in POV-Ray and careful use of the correct kind can yield very
impressive results. Let's take a moment to explore some of the different
kinds of light sources and their various parameters.

4.6.1            The Ambient Light Source

The ambient light source is used to simulate the effect of inter-diffuse
reflection. If there wasn't inter-diffuse reflection all areas not directly
lit by a light source would be completely dark. POV-Ray uses the ambient
keyword to determine how much light coming from the ambient light source is
reflected by a surface.

By default the ambient light source, which emits its light everywhere and in
all directions, is pure white (rgb <1,1,1>). Changing its color can be used
to create interesting effects. First of all the overall light level of the
scene can be adjusted easily. Instead of changing all ambient values in every
finish only the ambient light source is modified. By assigning different
colors we can create nice effects like a moody reddish ambient lighting. For
more details about the ambient light source see "Ambient Light".

Below is an example of a red ambient light source.

  global_settings { ambient_light rgb<1, 0, 0> }


4.6.2            The Pointlight Source

Pointlights are exactly what the name indicates. A pointlight has no size, is
invisible and illuminates everything in the scene equally no matter how far
away from the light source it may be (this behavior can be changed). This is
the simplest and most basic light source. There are only two important
parameters, location and color. Let's design a simple scene and place a
pointlight source in it.

We create a new file and name it litedemo.pov. We edit it as follows:

  #include "colors.inc"
  #include "textures.inc"

  camera {
    location  <-4, 3, -9>
    look_at   <0, 0, 0>
    angle 48
  }


We add the following simple objects:

  plane { y, -1
    texture {
      pigment {
        checker
        color rgb<0.5, 0, 0>
        color rgb<0, 0.5, 0.5>
      }
      finish {
        diffuse 0.4
        ambient 0.2
        phong 1
        phong_size 100
        reflection 0.25
      }
    }
  }

  torus { 1.5, 0.5
    texture { Brown_Agate }
    rotate <90, 160, 0>
    translate  <-1, 1, 3>
  }

  box { <-1, -1, -1>, <1, 1, 1>
    texture { DMFLightOak }
    translate  <2, 0, 2.3>
  }

  cone { <0,1,0>, 0, <0,0,0>, 1
    texture { PinkAlabaster }
    scale <1, 3, 1>
    translate  <-2, -1, -1>
  }

  sphere { <0,0,0>,1
    texture { Sapphire_Agate }
    translate  <1.5, 0, -2>
  }


Now we add a pointlight:

  light_source {
    <2, 10, -3>
    color White
  }


We render this at 200x150 -A and see that the objects are clearly visible
with sharp shadows. The sides of curved objects nearest the light source are
brightest in color with the areas that are facing away from the light source
being darkest. We also note that the checkered plane is illuminated evenly
all the way to the horizon. This allows us to see the plane, but it is not
very realistic.

4.6.3            The Spotlight Source

Spotlights are a very useful type of light source. They can be used to add
highlights and illuminate features much as a photographer uses spots to do
the same thing. There are a few more parameters with spotlights than with
pointlights. These are radius, falloff, tightness and point_at. The radius
parameter is the angle of the fully illuminated cone. The falloff parameter
is the angle of the umbra cone where the light falls off to darkness. The
tightness is a parameter that determines the rate of the light falloff. The
point_at parameter is just what it says, the location where the spotlight is
pointing to. Let's change the light in our scene as follows:

  light_source {
    <0, 10, -3>
    color White
    spotlight
    radius 15
    falloff 20
    tightness 10
    point_at <0, 0, 0>
  }


We render this at 200x150 -A and see that only the objects are illuminated.
The rest of the plane and the outer portions of the objects are now unlit.
There is a broad falloff area but the shadows are still razor sharp. Let's
try fiddling with some of these parameters to see what they do. We change the
falloff value to 16 (it must always be larger than the radius value) and
render again. Now the falloff is very narrow and the objects are either
brightly lit or in total darkness. Now we change falloff back to 20 and
change the tightness value to 100 (higher is tighter) and render again. The
spotlight appears to have gotten much smaller but what has really happened is
that the falloff has become so steep that the radius actually appears
smaller.

We decide that a tightness value of 10 (the default) and a falloff value of
18 are best for this spotlight and we now want to put a few spots around the
scene for effect. Let's place a slightly narrower blue and a red one in
addition to the white one we already have:

  light_source {
    <10, 10, -1>
    color Red
    spotlight
    radius 12
    falloff 14
    tightness 10
    point_at <2, 0, 0>
  }

  light_source {
    <-12, 10, -1>
    color Blue
    spotlight
    radius 12
    falloff 14
    tightness 10
    point_at <-2, 0, 0>
  }


Rendering this we see that the scene now has a wonderfully mysterious air to
it. The three spotlights all converge on the objects making them blue on one
side and red on the other with enough white in the middle to provide a
balance.

4.6.4            The Cylindrical Light Source

Spotlights are cone shaped, meaning that their effect will change with
distance. The farther away from the spotlight an object is, the larger the
apparent radius will be. But we may want the radius and falloff to be a
particular size no matter how far away the spotlight is. For this reason,
cylindrical light sources are needed. A cylindrical light source is just like
a spotlight, except that the radius and falloff regions are the same no
matter how far from the light source our object is. The shape is therefore a
cylinder rather than a cone. We can specify a cylindrical light source by
replacing the spotlight keyword with the cylinder keyword. We try this now
with our scene by replacing all three spotlights with cylinder lights and
rendering again. We see that the scene is much dimmer. This is because the
cylindrical constraints do not let the light spread out like in a spotlight.
Larger radius and falloff values are needed to do the job. We try a radius of
20 and a falloff of 30 for all three lights. That's the ticket!

4.6.5            The Area Light Source

So far all of our light sources have one thing in common. They produce sharp
shadows. This is because the actual light source is a point that is
infinitely small. Objects are either in direct sight of the light, in which
case they are fully illuminated, or they are not, in which case they are
fully shaded. In real life, this kind of stark light and shadow situation
exists only in outer space where the direct light of the sun pierces the
total blackness of space. But here on Earth, light bends around objects,
bounces off objects, and usually the source has some dimension, meaning that
it can be partially hidden from sight (shadows are not sharp anymore). They
have what is known as an umbra, or an area of fuzziness where there is
neither total light or shade. In order to simulate these soft shadows, a
ray-tracer must give its light sources dimension. POV-Ray accomplishes this
with a feature known as an area light.

Area lights have dimension in two axis'. These are specified by the first two
vectors in the area light syntax. We must also specify how many lights are to
be in the array. More will give us cleaner soft shadows but will take longer
to render. Usually a 3*3 or a 5*5 array will suffice. We also have the option
of specifying an adaptive value. The adaptive keyword tells the ray-tracer
that it can adapt to the situation and send only the needed rays to determine
the value of the pixel. If adaptive is not used, a separate ray will be sent
for every light in the area light. This can really slow things down. The
higher the adaptive value the cleaner the umbra will be but the longer the
trace will take. Usually an adaptive value of 1 is sufficient. Finally, we
probably should use the jitter keyword. This tells the ray-tracer to slightly
move the position of each light in the area light so that the shadows appear
truly soft instead of giving us an umbra consisting of closely banded
shadows.

OK, let's try one. We comment out the cylinder lights and add the following:

  light_source {
    <2, 10, -3>
    color White
    area_light <5, 0, 0>, <0, 0, 5>, 5, 5
    adaptive 1
    jitter
  }


This is a white area light centered at <2,10,-3>. It is 5 units (along the
x-axis) by 5 units (along the z-axis) in size and has 25 (5*5) lights in it.
We have specified adaptive 1 and jitter. We render this at 200x150 -A.

Right away we notice two things. The trace takes quite a bit longer than it
did with a point or a spotlight and the shadows are no longer sharp! They all
have nice soft umbrae around them. Wait, it gets better.

Spotlights and cylinder lights can be area lights too! Remember those sharp
shadows from the spotlights in our scene? It would not make much sense to use
a 5*5 array for a spotlight, but a smaller array might do a good job of
giving us just the right amount of umbra for a spotlight. Let's try it. We
comment out the area light and change the cylinder lights so that they read
as follows:

  light_source {
    <2, 10, -3>
    color White
    spotlight
    radius 15
    falloff 18
    tightness 10
    area_light <1, 0, 0>, <0, 0, 1>, 2, 2
    adaptive 1
    jitter
    point_at <0, 0, 0>
  }

  light_source {
    <10, 10, -1>
    color Red
    spotlight
    radius 12
    falloff 14
    tightness 10
    area_light <1, 0, 0>, <0, 0, 1>, 2, 2
    adaptive 1
    jitter
    point_at <2, 0, 0>
  }

  light_source {
    <-12, 10, -1>
    color Blue
    spotlight
    radius 12
    falloff 14
    tightness 10
    area_light <1, 0, 0>, <0, 0, 1>, 2, 2
    adaptive 1
    jitter
    point_at <-2, 0, 0>
  }


We now have three area-spotlights, one unit square consisting of an array of
four (2*2) lights, three different colors, all shining on our scene. We
render this at 200x150 -A. It appears to work perfectly. All our shadows have
small, tight umbrae, just the sort we would expect to find on an object under
a real spotlight.

4.6.6            Assigning an Object to a Light Source

Light sources are invisible. They are just a location where the light appears
to be coming from. They have no true size or shape. If we want our light
source to be a visible shape, we can use the looks_like keyword. We can
specify that our light source can look like any object we choose. When we use
looks_like, no_shadow is applied to the object automatically. This is done so
that the object will not block any illumination from the light source. If we
want some blocking to occur (as in a lampshade), it is better to simply use a
union to do the same thing. Let's add such an object to our scene. Here is a
light bulb we have made just for this purpose:

  #declare Lightbulb = union {
    merge {
      sphere { <0,0,0>,1 }
      cylinder { <0,0,1>, <0,0,0>, 1
        scale <0.35, 0.35, 1.0>
        translate  0.5*z
      }
      texture {
        pigment {color rgb <1, 1, 1>}
        finish {ambient .8 diffuse .6}
      }
    }
    cylinder { <0,0,1>, <0,0,0>, 1
      scale <0.4, 0.4, 0.5>
      texture { Brass_Texture }
      translate  1.5*z
    }
    rotate -90*x
    scale .5
  }


Now we add the light source:

  light_source {
    <0, 2, 0>
    color White
    looks_like { Lightbulb }
  }


Rendering this we see that a fairly believable light bulb now illuminates the
scene. However, if we do not specify a high ambient value, the light bulb is
not lit by the light source. On the plus side, all of the shadows fall away
from the light bulb, just as they would in a real situation. The shadows are
sharp, so let's make our bulb an area light:

  light_source {
    <0, 2, 0>
    color White
    area_light <1, 0, 0>, <0, 1, 0>, 2, 2
    adaptive 1
    jitter
    looks_like { Lightbulb }
  }


We note that we have placed this area light in the x-y-plane instead of the
x-z-plane. We also note that the actual appearance of the light bulb is not
affected in any way by the light source. The bulb must be illuminated by some
other light source or by, as in this case, a high ambient value. More
interesting results might therefore be obtained in this case by using halos
(see section "Halos").

4.6.7            Light Source Specials


4.6.7.1          Using Shadowless Lights

Light sources can be assigned the shadowless keyword and no shadows will be
cast due to its presence in a scene. Sometimes, scenes are difficult to
illuminate properly using the lights we have chosen to illuminate our
objects. It is impractical and unrealistic to apply a higher ambient value to
the texture of every object in the scene. So instead, we would place a couple
of fill lights around the scene. Fill lights are simply dimmer lights with
the shadowless keyword that act to boost the illumination of other areas of
the scene that may not be lit well. Let's try using one in our scene.

Remember the three colored area spotlights? We go back and un-comment them
and comment out any other lights we have made. Now we add the following:   li
    <0, 20, 0>
    color Gray50
    shadowless
  }


This is a fairly dim light 20 units over the center of the scene. It will
give a dim illumination to all objects including the plane in the background.
We render it and see.

4.6.7.2          Using Light Fading

If it is realism we want, it is not realistic for the plane to be evenly
illuminated off into the distance. In real life, light gets scattered as it
travels so it diminishes its ability to illuminate objects the farther it
gets from its source. To simulate this, POV-Ray allows us to use two
keywords: fade_distance, which specifies the distance at which full
illumination is achieved, and fade_power, an exponential value which
determines the actual rate of attenuation. Let's apply these keywords to our
fill light.

First, we make the fill light a little brighter by changing Gray50 to Gray75.
Now we change that fill light as follows:

  light_source {
    <0, 20, 0>
    color Gray75
    fade_distance 5
    fade_power 1
    shadowless
  }


This means that the full value of the fill light will be achieved at a
distance of 5 units away from the light source. The fade power of 1 means
that the falloff will be linear (the light falls of at a constant rate). We
render this to see the result.

That definitely worked! Now let's try a fade power of 2 and a fade distance
of 10. Again, this works well. The falloff is much faster with a fade power
of 2 so we had to raise the fade distance to 10.

4.6.7.3          Light Sources and Atmosphere

By definition more than default, light sources are affected by atmosphere,
i.e. their light is scattered by the atmosphere. This can be turned off by
adding atmosphere off to the light source block. The light emitted by a light
source can also be attenuated by the atmosphere (and also fog), that is it
will be diminished as it travels through it, by adding
atmospheric_attenuation on. The falloff is exponential and depends on the
distance parameter of the atmosphere (or fog). We note that this feature only
affects light coming directly from the light source. Reflected and refracted
light is ignored.

Let's experiment with these keywords. First we must add an atmosphere to our
scene:

  #include "atmos.inc"

  atmosphere { Atmosphere2 }


We comment out the three lines that turn each of the three spotlights into
area lights. Otherwise the trace will take to long.

  //area_light <1, 0, 0>, <0, 0, 1>, 2, 2
  //adaptive 1
  //jitter


Tracing the scene at 200x150 -A we see that indeed the spotlights are
visible. We can see where the blue and red spots cross each other and where
the white overhead light shines down through the center of the scene. We also
notice that the spotlights appear to diminish in their intensity as the light
descends from the light source to the objects. The red light is all but gone
in the lower left part of the scene and the blue light all but gone in the
lower right. This is due to the atmospheric attenuation and lends a further
realism to the scene. The atmosphere-light source interaction gives our scene
a smoky, mysterious appearance, but the trace took a long time. Making those
spotlights area lights and it will take even longer. This is an inevitable
trade-off - tracing speed for image quality.

4.7              Simple Texture Options

The pictures rendered so far where somewhat boring regarding the appearance
of the objects. Let's add some fancy features to the texture.

4.7.1            Surface Finishes

One of the main features of a ray-tracer is its ability to do interesting
things with surface finishes such as highlights and reflection. Let's add a
nice little Phong highlight (shiny spot) to the sphere. To do this we need to
add a finish keyword followed by a parameter. We change the definition of the
sphere to this:

  sphere { <0, 1, 2>, 2
    texture {
      pigment { color Yellow } // Yellow is pre-defined in COLORS.INC
      finish { phong 1 }
    }
  }


We render the scene. The phong keyword adds a highlight the same color of the
light shining on the object. It adds a lot of credibility to the picture and
makes the object look smooth and shiny. Lower values of phong will make the
highlight less bright (values should be between 0 and 1).

4.7.2            Adding Bumpiness

The highlight we have added illustrates how much of our perception depends on
the reflective properties of an object. Ray-tracing can exploit this by
playing tricks on our perception to make us see complex details that aren't
really there.

Suppose we wanted a very bumpy surface on the object. It would be very
difficult to mathematically model lots of bumps. We can however simulate the
way bumps look by altering the way light reflects off of the surface.
Reflection calculations depend on a vector called surface normal. This is a
vector which points away from the surface and is perpendicular to it. By
artificially modifying (or perturbing) this normal vector we can simulate
bumps. We change the scene to read as follows and render it:

  sphere { <0, 1, 2>, 2
    texture {
      pigment { color Yellow }
      normal { bumps 0.4 scale 0.2 }
      finish { phong 1}
    }
  }


This tells POV-Ray to use a bump pattern to modify the surface normal. The
value 0.4 controls the apparent depth of the bumps. Usually the bumps are
about 1 unit wide which doesn't work very well with a sphere of radius 2. The
scale makes the bumps 1/5th as wide but does not affect their depth.

4.7.3            Creating Color Patterns

We can do more than assigning a solid color to an object. We can create
complex patterns in the pigment block like in this example:

  sphere { <0, 1, 2>, 2
    texture {
      pigment {
        wood
        color_map {
          [0.0 color DarkTan]
          [0.9 color DarkBrown]
          [1.0 color VeryDarkBrown]
        }
        turbulence 0.05
        scale <0.2, 0.3, 1>
      }
      finish { phong 1 }
    }
  }


The keyword wood specifies a pigment pattern of concentric rings like rings
in wood. The color_map keyword specifies that the color of the wood should
blend from DarkTan to DarkBrown over the first 90% of the vein and from
DarkBrown to VeryDarkBrown over the remaining 10%. The turbulence keyword
slightly stirs up the pattern so the veins aren't perfect circles and the
scale keyword adjusts the size of the pattern.

Most patterns are set up by default to give us one feature across a sphere of
radius 1.0. A feature is very roughly defined as a color transition. For
example, a wood texture would have one band on a sphere of radius 1.0. In
this example we scale the pattern using the scale keyword followed by a
vector. In this case we scaled 0.2 in the x direction, 0.3 in the y direction
and the z direction is scaled by 1, which leaves it unchanged. Scale values
larger than one will stretch an element. Scale values smaller than one will
squish an element. A scale value of one will leave an element unchanged.

4.7.4            Pre-defined Textures

POV-Ray has some very sophisticated textures pre-defined in the standard
include files glass.inc, metals.inc, stones.inc and woods.inc. Some are
entire textures with pigment, normal and/or finish parameters already
defined. Some are just pigments or just finishes. We change the definition of
our sphere to the following and then re-render it:

  sphere { <0, 1, 2>, 2
    texture {
      pigment {
        DMFWood4       // pre-defined in textures.inc
        scale 4        // scale by the same amount in all
                       // directions
      }
      finish { Shiny } // pre-defined in finish.inc
    }
  }


The pigment identifier DMFWood4 has already been scaled down quite small when
it was defined. For this example we want to scale the pattern larger. Because
we want to scale it uniformly we can put a single value after the scale
keyword rather than a vector of x, y, z scale factors.

We look through the file textures.inc to see what pigments and finishes are
defined and try them out. We just insert the name of the new pigment where
DMFWood4 is now or try a different finish in place of Shiny and re-render our
file.

Here is an example of using a complete texture identifier rather than just
the pieces.

  sphere { <0, 1, 2>, 2
    texture { PinkAlabaster }
  }


4.8              Advanced Texture Options

The extremely powerful texturing ability is one thing that really sets
POV-Ray apart from other raytracers. So far we have not really tried anything
too complex but by now we should be comfortable enough with the program's
syntax to try some of the more advanced texture options.

Obviously, we cannot try them all. It would take a tutorial a lot more pages
to use every texturing option available in POV-Ray. For this limited
tutorial, we will content ourselves to just trying a few of them to give an
idea of how textures are created. With a little practice, we will soon be
creating beautiful textures of our own.

4.8.1            Pigment and Normal Patterns

Previous versions of POV-Ray made a distinction between pigment and normal
patterns, i. e. patterns that could be used inside a normal or pigment
statement. With POV-Ray 3.0 this restriction was removed so that all patterns
listed in section "Patterns" can be used as a pigment or normal pattern.

4.8.2            Pigments

Every surface must have a color. In POV-Ray this color is called a pigment.
It does not have to be a single color. It can be a color pattern, a color
list or even an image map. Pigments can also be layered one on top of the
next so long as the uppermost layers are at least partially transparent so
the ones beneath can show through. Let's play around with some of these kinds
of pigments.

We create a file called texdemo.pov and edit it as follows:

  #include "colors.inc"

  camera {
    location <1, 1, -7>
    look_at 0
    angle 36
  }

  light_source { <1000, 1000, -1000> White }

  plane { y, -1.5
    pigment { checker Green, White }
  }

  sphere { <0,0,0>, 1
    pigment { Red }
  }


Giving this file a quick test render at 200x150 -A we see that it is a simple
red sphere against a green and white checkered plane. We will be using the
sphere for our textures.

4.8.2.1          Using Color List Pigments

Before we begin we should note that we have already made one kind of pigment,
the color list pigment. In the previous example we have used a checkered
pattern on our plane. There are two other kinds of color list pigments, brick
and hexagon. Let's quickly try each of these. First, we change the plane's
pigment as follows:

  pigment { hexagon Green, White, Yellow }


Rendering this we see a three-color hexagonal pattern. Note that this pattern
requires three colors. Now we change the pigment to...

  pigment { brick Gray75, Red rotate -90*x scale .25 }


Looking at the resulting image we see that the plane now has a brick pattern.
We note that we had to rotate the pattern to make it appear correctly on the
flat plane. This pattern normally is meant to be used on vertical surfaces.
We also had to scale the pattern down a bit so we could see it more easily.
We can play around with these color list pigments, change the colors, etc.
until we get a floor that we like.

4.8.2.2          Using Pigment and Patterns

Let's begin texturing our sphere by using a pattern and a color map
consisting of three colors. wE replace the pigment block with the following.

  pigment {
    gradient x
    color_map {
      [0.00 color Red]
      [0.33 color Blue]
      [0.66 color Yellow]
      [1.00 color Red]
    }
  }


Rendering this we see that it gives us an interesting pattern of vertical
stripes. We change the gradient direction to y. The stripes are horizontal
now. We change the gradient direction to z. The stripes are now more like
concentric rings. This is because the gradient direction is directly away
from the camera. We change the direction back to x and add the following to
the pigment block.

  pigment {
    gradient x
    color_map {
      [0.00 color Red]
      [0.33 color Blue]
      [0.66 color Yellow]
      [1.00 color Red]
    }
    rotate -45*z          // <- add this line
  }


The vertical bars are now slanted at a 45 degree angle. All patterns can be
rotated, scaled and translated in this manner. Let's now try some different
types of patterns. One at a time, we substitute the following keywords for
gradient x and render to see the result: bozo, marble, agate, granite,
leopard, spotted and wood (if we like we can test all patterns listed in
section "Patterns").

Rendering these we see that each results in a slightly different pattern. But
to get really good results each type of pattern requires the use of some
pattern modifiers.

4.8.2.3          Using Pattern Modifiers

Let's take a look at some pattern modifiers. First, we change the pattern
type to bozo. Then we add the following change.

  pigment {
    bozo
    frequency 3            // <- add this line
    color_map {
      [0.00 color Red]
      [0.33 color Blue]
      [0.66 color Yellow]
      [1.00 color Red]
    }
    rotate -45*z
  }


The frequency modifier determines the number of times the color map repeats
itself per unit of size. This change makes the bozo pattern we saw earlier
have many more bands in it. Now we change the pattern type to marble. When we
rendered this earlier, we saw a banded pattern similar to gradient y that
really did not look much like marble at all. This is because marble really is
a kind of gradient and it needs another pattern modifier to look like marble.
This modifier is called turbulence. We change the line frequency 3 to
turbulence 1 and render again. That's better! Now let's put frequency 3 back
in right after the turbulence and take another look. Even more interesting!

But wait, it get's better! Turbulence itself has some modifiers of its own.
We can adjust the turbulence several ways. First, the float that follows the
turbulence keyword can be any value with higher values giving us more
turbulence. Second, we can use the keywords omega, lambda and octaves to
change the turbulence parameters. Let's try this now:

  pigment {
    marble
    turbulence 0.5
    lambda 1.5
    omega 0.8
    octaves 5
    frequency 3
    color_map {
      [0.00 color Red]
      [0.33 color Blue]
      [0.66 color Yellow]
      [1.00 color Red]
    }
    rotate 45*z
  }


Rendering this we see that the turbulence has changed and the pattern looks
different. We play around with the numerical values of turbulence, lambda,
omega and octaves to see what they do.

4.8.2.4          Using Transparent Pigments and Layered Textures

Pigments are described by numerical values that give the rgb value of the
color to be used (like color rgb <1, 0, 0> giving us a red color). But this
syntax will give us more than just the rgb values. We can specify filtering
transparency by changing it as follows: color rgbf<1, 0, 0, 1>. The f stands
for filter, POV-Ray's word for filtered transparency. A value of one means
that the color is completely transparent, but still filters the light
according to what the pigment is. In this case, the color will be a
transparent red, like red cellophane.

There is another kind of transparency in POV-Ray. It is called transmittance
or non-filtering transparency (the keyword is transmit). It is different from
filter in that it does not filter the light according to the pigment color.
It instead allows all the light to pass through unchanged. It can be
specified like this: rgbt <1, 0, 0, 1>.

Let's use some transparent pigments to create another kind of texture, the
layered texture. Returning to our previous example, declare the following
texture.

  #declare LandArea = texture {
      pigment {
        agate
        turbulence 1
        lambda 1.5
        omega .8
        octaves 8
        color_map {
          [0.00 color rgb <.5, .25, .15>]
          [0.33 color rgb <.1, .5, .4>]
          [0.86 color rgb <.6, .3, .1>]
          [1.00 color rgb <.5, .25, .15>]
        }
      }
    }
  }


This texture will be the land area. Now let's make the oceans by declaring
the following.

  #declare OceanArea = texture {
    pigment {
      bozo
        turbulence .5
        lambda 2
        color_map {
          [0.00, 0.33 color rgb <0, 0, 1>
                      color rgb <0, 0, 1>]
          [0.33, 0.66 color rgbf <1, 1, 1, 1>
                      color rgbf <1, 1, 1, 1>]
          [0.66, 1.00 color rgb <0, 0, 1>
                      color rgb <0, 0, 1>]
        }
      }
    }
  }


Note how the ocean is the opaque blue area and the land is the clear area
which will allow the underlying texture to show through.

Now, let's declare one more texture to simulate an atmosphere with swirling
clouds.

  #declare CloudArea = texture {
    pigment {
      agate
      turbulence 1
      lambda 2
      frequency 2
      color_map {
        [0.0 color rgbf <1, 1, 1, 1>]
        [0.5 color rgbf <1, 1, 1, .35>]
        [1.0 color rgbf <1, 1, 1, 1>]
      }
    }
  }


Now apply all of these to our sphere.

  sphere { <0,0,0>, 1
    texture { LandArea }
    texture { OceanArea }
    texture { CloudArea }
  }


We render this and have a pretty good rendition of a little planetoid. But it
could be better. We don't particularly like the appearance of the clouds.
There is a way they could be done that would be much more realistic.

4.8.2.5          Using Pigment Maps

Pigments may be blended together in the same way as the colors in a color map
using the same pattern keywords that we can use for pigments. Let's just give
it a try.

We add the following declarations, making sure they appear before the other
declarations in the file.

  #declare Clouds1 = pigment {
      bozo
      turbulence 1
      color_map {
        [0.0 color White filter 1]
        [0.5 color White]
        [1.0 color White filter 1]
      }
    }
  #declare Clouds2 = pigment {
    agate
    turbulence 1
    color_map {
      [0.0 color White filter 1]
      [0.5 color White]
      [1.0 color White filter 1]
      }
    }
  #declare Clouds3 = pigment {
    marble
    turbulence 1
    color_map {
      [0.0 color White filter 1]
      [0.5 color White]
      [1.0 color White filter 1]
    }
  }
  #declare Clouds4 = pigment {
    granite
    turbulence 1
    color_map {
      [0.0 color White filter 1]
      [0.5 color White]
      [1.0 color White filter 1]
    }
  }


Now we use these declared pigments in our cloud layer on our planetoid. We
replace the declared cloud layer with.

  #declare CloudArea = texture {
    pigment {
      gradient y
      pigment_map {
        [0.00 Clouds1]
        [0.25 Clouds2]
        [0.50 Clouds3]
        [0.75 Clouds4]
        [1.00 Clouds1]
      }
    }
  }


We render this and see a remarkable pattern that looks very much like weather
patterns on the planet earth. They are separated into bands, simulating the
different weather types found at different latitudes.

4.8.3            Normals

Objects in POV-Ray have very smooth surfaces. This is not very realistic so
there are several ways to disturb the smoothness of an object by perturbing
the surface normal. The surface normal is the vector that is perpendicular to
the angle of the surface. By changing this normal the surface can be made to
appear bumpy, wrinkled or any of the many patterns available. Let's try a
couple of them.

4.8.3.1          Using Basic Normal Modifiers

We comment out the planetoid sphere for now and, at the bottom of the file,
create a new sphere with a simple, single color texture.

  sphere { <0,0,0>, 1
    pigment { Gray75 }
    normal { bumps 1 scale .2 }
  }


Here we have added a normal block in addition to the pigment block (note that
these do not have to be included in a texture block unless they need to be
transformed together or need to be part of a layered texture). We render this
to see what it looks like. Now, one at a time, we substitute for the keyword
bumps the following keywords: dents, wrinkles, ripples and waves (we can also
use any of the patterns listed in "Patterns"). We render each to see what
they look like. We play around with the float value that follows the keyword.
We also experiment with the scale value.

For added interest, we change the plane texture to a single color with a
normal as follows.

  plane { y, -1.5
    pigment { color rgb <.65, .45, .35> }
    normal { dents .75 scale .25 }
  }


4.8.3.2          Blending Normals

Normals can be layered similar to pigments but the results can be unexpected.
Let's try that now by editing the sphere as follows.

  sphere { <0,0,0>, 1
    pigment { Gray75 }
      normal { radial frequency 10 }
      normal { gradient y scale .2 }
  }


As we can see, the resulting pattern is neither a radial nor a gradient. It
is instead the result of first calculating a radial pattern and then
calculating a gradient pattern. The results are simply additive. This can be
difficult to control so POV-Ray gives the user other ways to blend normals.

One way is to use normal maps. A normal map works the same way as the pigment
map we used earlier. Let's change our sphere texture as follows.

  sphere { <0,0,0>, 1
    pigment { Gray75 }
    normal {
      gradient y
      frequency 3
      turbulence .5
      normal_map {
        [0.00 granite]
        [0.25 spotted turbulence .35]
        [0.50 marble turbulence .5]
        [0.75 bozo turbulence .25]
        [1.00 granite]
      }
    }
  }


Rendering this we see that the sphere now has a very irregular bumpy surface.
The gradient pattern type separates the normals into bands but they are
turbulated, giving the surface a chaotic appearance. But this give us an
idea.

Suppose we use the same pattern for a normal map that we used to create the
oceans on our planetoid and applied it to the land areas. Does it follow that
if we use the same pattern and modifiers on a sphere the same size that the
shape of the pattern would be the same? Wouldn't that make the land areas
bumpy while leaving the oceans smooth? Let's try it. First, let's render the
two spheres side-by-side so we can see if the pattern is indeed the same. We
un-comment the planetoid sphere and make the following changes.

  sphere { <0,0,0>, 1
    texture { LandArea }
    texture { OceanArea }
    //texture { CloudArea }  // <-comment this out
    translate -x             // <- add this transformation
  }


Now we change the gray sphere as follows.

  sphere { <0,0,0>, 1
    pigment { Gray75 }
    normal {
      bozo
      turbulence .5
      lambda 2
      normal_map {
        [0.4 dents .15 scale .01]
        [0.6 agate turbulence 1]
        [1.0 dents .15 scale .01]
      }
    }
    translate x // <- add this transformation
  }


We render this to see if the pattern is the same. We see that indeed it is.
So let's comment out the gray sphere and add the normal block it contains to
the land area texture of our planetoid. We remove the transformations so that
the planetoid is centered in the scene again.

  #declare LandArea = texture {
    pigment {
      agate
      turbulence 1
      lambda 1.5
      omega .8
      octaves 8
      color_map {
        [0.00 color rgb <.5, .25, .15>]
        [0.33 color rgb <.1, .5, .4>]
        [0.86 color rgb <.6, .3, .1>]
        [1.00 color rgb <.5, .25, .15>]
      }
    }
    normal {
      bozo
      turbulence .5
      lambda 2
      normal_map {
        [0.4 dents .15 scale .01]
        [0.6 agate turbulence 1]
        [1.0 dents .15 scale .01]
      }
    }
  }


Looking at the resulting image we see that indeed our idea works! The land
areas are bumpy while the oceans are smooth. We add the cloud layer back in
and our planetoid is complete.

There is much more that we did not cover here due to space constraints. On
our own, we should take the time to explore slope maps, average and bump
maps.

4.8.4            Finishes

The final part of a POV-Ray texture is the finish. It controls the properties
of the surface of an object. It can make it shiny and reflective, or dull and
flat. It can also specify what happens to light that passes through
transparent pigments, what happens to light that is scattered by
less-than-perfectly-smooth surfaces and what happens to light that is
reflected by surfaces with thin-film interference properties. There are
twelve different properties available in POV-Ray to specify the finish of a
given object. These are controlled by the following keywords: ambient,
diffuse, brilliance, phong, specular, metallic, reflection, refraction,
caustics, attenuation, crand and iridescence. Let's design a couple of
textures that make use of these parameters.

4.8.4.1          Using Ambient

Since objects in POV-Ray are illuminated by light sources, the portions of
those objects that are in shadow would be completely black were it not for
the first two finish properties, ambient and diffuse. Ambient is used to
simulate the light that is scattered around the scene that does not come
directly from a light source. Diffuse determines how much of the light that
is seen comes directly from a light source. These two keywords work together
to control the simulation of ambient light. Let's use our gray sphere to
demonstrate this. Let's also change our plane back to its original green and
white checkered pattern.

  plane {y,-1.5
    pigment {checker Green, White}
  }

  sphere { <0,0,0>, 1
    pigment {Gray75}
    finish {
      ambient .2
      diffuse .6
  }


In the above example, the default values for ambient and diffuse are used. We
render this to see what the effect is and then make the following change to
the finish.

  ambient 0
  diffuse 0


The sphere is black because we have specified that none of the light coming
from any light source will be reflected by the sphere. Let's change diffuse
back to the default of 0.6.

Now we see the gray surface color where the light from the light source falls
directly on the sphere but the shaded side is still absolutely black. Now
let's change diffuse to 0.3 and ambient to 0.3.

The sphere now looks almost flat. This is because we have specified a fairly
high degree of ambient light and only a low amount of the light coming from
the light source is diffusely reflected towards the camera. The default
values of ambient and diffuse are pretty good averages and a good starting
point. In most cases, an ambient value of 0.1 ... 0.2 is sufficient and a
diffuse value of 0.5 ... 0.7 will usually do the job. There are a couple of
exceptions. If we have a completely transparent surface with high refractive
and/or reflective values, low values of both ambient and diffuse may be best.
Here is an example.

  sphere { <0,0,0>, 1
     pigment { White filter 1 }
       finish {
         ambient 0
         diffuse 0
         reflection .25
         refraction 1
         ior 1.33
         specular 1
         roughness .001
      }
    }
  }


This is glass, obviously. Glass is a material that takes nearly all of its
appearance from its surroundings. Very little of the surface is seen because
it transmits or reflects practically all of the light that shines on it. See
glass.inc for some other examples.

If we ever need an object to be completely illuminated independently of the
lighting situation in a given scene we can do this artificially by specifying
an ambient value of 1 and a diffuse value of 0. This will eliminate all
shading and simply give the object its fullest and brightest color value at
all points. This is good for simulating objects that emit light like
lightbulbs and for skies in scenes where the sky may not be adequately lit by
any other means.

Let's try this with our sphere now.

  sphere { <0,0,0>, 1
    pigment { White }
      finish {
        ambient 1
        diffuse 0
      }
    }
  }


Rendering this we get a blinding white sphere with no visible highlights or
shaded parts. It would make a pretty good streetlight.

4.8.4.2          Using Surface Highlights

In the glass example above, we noticed that there were bright little hotspots
on the surface. This gave the sphere a hard, shiny appearance. POV-Ray gives
us two ways to specify surface specular highlights. The first is called Phong
highlighting. Usually, Phong highlights are described using two keywords:
phong and phong_size. The float that follows phong determines the brightness
of the highlight while the float following phong_size determines its size.
Let's try this.

  sphere { <0,0,0>, 1
    pigment { Gray50 }
    finish {
      ambient .2
      diffuse .6
      phong .75
      phong_size 25
    }
  }


Rendering this we see a fairly broad, soft highlight that gives the sphere a
kind of plastic appearance. Now let's change phong_size to 150. This makes a
much smaller highlight which gives the sphere the appearance of being much
harder and shinier.

There is another kind of highlight that is calculated by a different means
called specular highlighting. It is specified using the keyword specular and
operates in conjunction with another keyword called roughness. These two
keywords work together in much the same way as phong and phong_size to create
highlights that alter the apparent shininess of the surface. Let's try using
specular in our sphere.

  sphere { <0,0,0>, 1
    pigment { Gray50 }
      finish {
        ambient .2
        diffuse .6
        specular .75
        roughness .1
      }
    }
  }


Looking at the result we see a broad, soft highlight similar to what we had
when we used phong_size of 25. Change roughness to .001 and render again. Now
we see a small, tight highlight similar to what we had when we used
phong_size of 150. Generally speaking, specular is slightly more accurate and
therefore slightly more realistic than phong but you should try both methods
when designing a texture. There are even times when both phong and specular
may be used on a finish.

4.8.4.3          Using Reflection and Metallic

There is another surface parameter that goes hand in hand with highlights,
reflection. Surfaces that are very shiny usually have a degree of reflection
to them. Let's take a look at an example.

  sphere { <0,0,0>, 1
    pigment { Gray50 }
      finish {
        ambient .2
        diffuse .6
        specular .75
        roughness .001
        reflection .5
      }
    }
  }


We see that our sphere now reflects the green and white checkered plane and
the black background but the gray color of the sphere seems out of place.
This is another time when a lower diffuse value is needed. Generally, the
higher reflection is the lower diffuse should be. We lower the diffuse value
to 0.3 and the ambient value to 0.1 and render again. That is much better.
Let's make our sphere as shiny as a polished gold ball bearing.

  sphere { <0,0,0>, 1
    pigment { BrightGold }
      finish {
        ambient .1
        diffuse .1
        specular 1
        roughness .001
        reflection .75
      }
    }
  }


That is very close but there is something wrong with the highlight. To make
the surface appear more like metal the keyword metallic is used. We add it
now to see the difference.

  sphere { <0,0,0>, 1
    pigment { BrightGold }
      finish {
        ambient .1
        diffuse .1
        specular 1
        roughness .001
        reflection .75
        metallic
      }
    }
  }


We see that the highlight has taken on the color of the surface rather than
the light source. This gives the surface a more metallic appearance.

4.8.4.4          Using Refraction

Objects that are transparent allow light to pass through them. With some
substances, the light is bent as it travels from one substance into the other
because of the differing optical densities of the objects. This is called
refraction. Water and glass both bend light in this manner. To create water
or glass, POV-Ray gives us a way to specify refraction. This is done with the
keywords refraction and ior. The amount of light that passes through an
object is determined by the value of the filtering and/or transmittance
channel in the pigment. We should use the refraction value only to switch
refraction on or off using values of 1 or 0 respectively (or the boolean
values on and off). See section "Refraction" for a detailed explanation of
the reasons.

The degree of refraction, i. e. the amount of bending that occurs, is given
by the keyword ior, short for index of refraction. If we know the index of
refraction of the substance we are trying to create, we may just use that.
For instance, water is 1.33, glass is around 1.45 and diamond is 1.75. Let's
return to the example of a glass sphere we used earlier.

  sphere { <0,0,0>, 1
    pigment { White filter 1 }
      finish {
        ambient 0
        diffuse 0
        reflection .25
        refraction 1
        ior 1.45
        specular 1
        roughness .001
      }
    }
  }


We render this again and notice how the plane that is visible through the
sphere is distorted and turned upside-down. This is because the light passing
through the sphere is being bent or refracted to the degree specified. We
reduce ior to 1.25 and re-render. We increase it to 1.75 and re-render. We
notice how the distortion changes.

4.8.4.5          Adding Light Attenuation

Transparent objects can be made to cause the intensity of light passing
through them to be reduced. In reality, this is due to impurities in
scattering the light. Two float values determine the effect: fade_distance is
the distance the light has to travel to reach one-half its original intensity
and fade_power is the degree of falloff. Let's try an example of this.

  sphere { <0,0,0>, 1
    pigment { White filter 1 }
      finish {
        ambient .1
        diffuse .1
        reflection .15
        refraction 1
        ior 1.45
        specular 1
        roughness .001
        fade_distance 5
        fade_power 1
    }
  }


The caustics of a translucent sphere.

This gives the sphere a slightly clouded look as if not all of the light was
able to pass through it. For interesting variations of this texture, try
lowering ior to 1.15 and raising reflection to 0.5.

4.8.4.6          Using Faked Caustics


4.8.4.6.1        What are Caustics?

First, let us raid our kitchen cupboard. We are looking for transparent glass
or crystal drinking glasses. If they have a pattern etched in their surface,
so much the better. One by one, we place them under a bright lamp and observe
the shadow they cast on the desk or table beneath. If we look closely we will
make out bright regions within the shadow. These will be places where the
refractive properties of the drinking glass are concentrating light
sufficiently to make the bright spots. If there is a pattern in the surface
of the glass we will see the pattern formed out of the bright areas. Those
bright regions are the caustics caused by refraction, the refractice
caustics. There will also be bright patterns of light on the table that are
caused by light reflected off the glass. These are called reflective
caustics.

Once we know what we are looking for we will be able to spot caustics in many
everyday situations: the shadow cast by a magnifying glass has one, light
streaming through an aquarium might makes them, the light passing through a
piece of crumpled cellophane might cast them on the table top, etc. We will
even see them in the bottom of a swimming pool on a bright sunny day.
Caustics are a subtle lighting effect that can really lend realism to
raytraced images of such items.

POV-Ray uses algorithms that fake refractive caustics (reflective caustices
are not possible).There are inherant limitations on the process of (standard)
ray-tracing in general which make it unsuitable for certain light simulation
applications, such as optical testing and a few very particular architectural
lighting projects. Methods which do the considerably more extensive
calculations needed to do full light simulation including caustics (like
path-tracing, photon-tracing or bi-directional ray-tracing) are very slow and
impractical on average platforms.

This means that we have to tinker with the caustics to get the best possible
look, but with a little experimentation, we will see we can very closely
emulate the real thing. The best way to go is, where ever possible, to study
an example of the thing we are trying to trace. We need to get to know its
pattern of caustics and then adjust our final picture until we are satisfied.

4.8.4.6.2        Applying Caustics to a Scene

Caustics is a new texture property under the area of finishes. We apply it to
the shadows of a transparent, refractive object by adding in the caustics
keyword to the finish. We try the following simple example for a start (see
file caustic1.pov).

  #include "colors.inc"
  #include "textures.inc"

  camera {
    location <0, 15, -40>
    look_at <-2, 0, 1>
    angle 10
  }

  light_source { <10, 20, 10> color White }

  // lay down a boring floor to view the shadow against

  plane { y, 0
    pigment { Grey }
  }

  // here's something to have caustics property applied

  sphere { <0, 3, 0>, 2
    texture {
      Glass3
      finish { caustics .6 }
    }
  }


The caustics in a swimming-pool.

When we render this we will see our sphere in the upper right corner of the
image, floating a little over the plane, and the shadow it casts is sprawled
across the central part of our view. And there in the center is a basic
caustic. That bright area in the center represents the light which normally
refractivity would concentrate in the middle of the shadow.

The only question this leaves is: what is with the floating point value which
follows the caustics keyword? Well, that's where our discussion above on
adjusting the caustic comes in. Remember the drinking glasses? If we had one
that had fairly thin walls and then a thick glass base we will see what we
mean in the shadows it casts. Above, with the thinner walls (with less
refraction) the caustics are less pronounced and more evenly diffused through
the shadow, but when we get to the part of the shadow cast by the thicker,
more refractive base, suddenly the caustic becomes more pronounced and more
tightly focused near the center.

Of course, since this is a simulated caustic, there is no correspondence
between the degree to which the caustic is focused or diffused and the shape,
size and refractivity of the object. But we can manually control it with the
floating point value following the caustic keyword. The closer this value
gets to zero, the more diffused and dimmer the caustic gets, while the nearer
it becomes to 1, the more tightly focused and pronounced the caustic gets. At
1, we have the caustic of a thick, highly refractive piece of lead crystal,
while at 0.1 it is more like a hollow glass sphere. We try this by
re-rendering the above scene, with a range of values from 0.1 to 1.0 and
watching the different caustics we get.

Out of range values work also. Numbers higher than 1 just lead to more and
more tightly focused caustics. Negative numbers are just plain weird, but
interesting. Essentially, the object becomes illuminated in all sorts of
bizzare ways and the shadow becomes like a photographic negative of itself.
Kind of like a 1950's sci-fi raygun effect. It looks strange, and not at all
photo-realistic, but if we like the surreal we may want to try it at least
once and file away the effect in our mind in case we ever want it.

4.8.4.6.3        Caustics And Normals

POV-Ray makes use of surface normal perturbation in a way that is more unique
than people generally stop to think. When we apply a surface normal in a
texture we are actually not altering the surface at all, but rather telling
POV-Ray to treat the surface as if it were altered, for purposes of computing
the illumination falling on each individual spot. In short, it is a trick of
the light and shadow which, supposing only that we don't see it at too sharp
a viewing angle, effectively creates the illusion of distortions in the
surface of an object.

Caustics are also a synthetic trick, as we saw above, and sure enough, they
have been designed to react to texture normal patterns as if those patterns
were genuinely there. Remember the drinking glass experiment? If we found a
glass with patterns etched into the surface we probably noted that the
pattern showed up in the caustics cast by the glass too. When we have a
transparent surface with a normal applied to it, it causes the caustics cast
by that surface to mimick the normal pattern, so that it shows up in the
shadows.

Following is an example of what we mean: it is a simply meant to represent
water in a swimming pool. We have distilled this down to a plane above to
represent the water, one below to represent the floor of the pool, a camera
just below the waterline, looking at the floor, and a light source high above
(see caustic2.pov).

  #include "colors.inc"

  // Our camera is underwater, looking at the bottom of
  // the pool for the best view of the caustics produced

  camera {
    location <0, -5, 0>
    look_at  <0, -10, -5>
  }

  light_source { <0, 100, 49.5> color White }

  // the bottom of the pool...

  plane { y, -10
    texture {
      pigment { color rgb <0.6, 0.7, 0.7> }
      finish { ambient 0.1 diffuse 0.7 }
      scale 0.01
    }
  }

  // and the surface of the water

  plane { y, 0
    texture {
      pigment { rgbf <0.6, 0.67, 0.72, 0.9> }
      normal {
        bumps .6
        scale <.75, .25, .25>
        rotate <0, 45, 0>
      }
      finish { caustics .9 }
    }
  }


The bumps we have given the water plane are meant to represent the small,
random crests and troughs that form on a pool when a light breeze blows over
it. We could have used ripples or waves as well, like something had recently
splashed into it at some point, but the bumps will work well enough for an
example.

We notice that our view of the pool floor shows dozens of tiny caustic light
spots, corresponding approximately to a random bump pattern. If we like we
can try putting in ripples or waves and watch the pattern of the caustics
change. Even though a flat plane itself would cast no caustics (we could try
without the normal), POV-Ray's faked caustic generation knows that if the
surface was really bumped like this normal is indicating, the refraction of
the bumped surface would be just enough to concentrate light in caustics
throughout the bottom of the pool.

We see that just as with a curved surface, such as the sphere previously,
normal patterns also trigger the appearance of caustics cast by an object.
Interestingly enough, this alone would be proof that the caustics really are
faked: our water hasn't even been given any refraction properties in its
finish, yet the caustics are still there just the same!

4.8.4.7          Using Iridescence

Iridescence is what we see on the surface of an oil slick when the sun shines
on it. The rainbow effect is created by something called thin-film
interference (read section "Iridescence" for details). For now let's just try
using it. Iridescence is specified by the irid keyword and three values:
amount, thickness and turbulence. The amount is the contribution to the
overall surface color. Usually 0.1 to 0.5 is sufficient here. The thickness
affects the busyness of the effect. Keep this between 0.25 and 1 for best
results. The turbulence is a little different from pigment or normal
turbulence. We cannot set octaves, lambda or omega but we can specify an
amount which will affect the thickness in a slightly different way from the
thickness value. Values between 0.25 and 1 work best here too. Finally,
iridescence will respond to the surface normal since it depends on the angle
of incidence of the light rays striking the surface. With all of this in
mind, let's add some iridescence to our glass sphere.

  sphere { <0,0,0>, 1
    pigment { White filter 1 }
      finish {
        ambient .1
        diffuse .1
        reflection .2
        refraction 1
        ior 1.5
        specular 1
        roughness .001
        fade_distance 5
        fade_power 1
        caustics 1
        irid {
          0.35
          thickness .5
          turbulence .5
        }
     }
  }


We try to vary the values for amount, thickness and turbulence to see what
changes they make. We also try to add a normal block to see what happens.

4.8.5            Halos

Important notice: The halo feature in POV-Ray 3.0 is somewhat experimental.
There is a high probability that the design and implementation of these
features will be changed in future versions. We cannot guarantee that scenes
using these features in 3.0 will render identically in future releases or
that full backwards compatibility of language syntax can be maintained.

Halos are a powerful feature that can be used to create a lot of different
effects like clouds, fogs, fire, lasers, etc. The name actually comes from
the ability to render halos with it, like the ones seen around the moon or
the sun.

Due to the complexity of the halo feature and the large amount of parameters
provided it is very difficult to get satisfying results. The following
sections will help to create a halo step by step, starting with the basic
things and going to the more subtle stuff.

It is also helpful to read the halo reference sections to get a better
understanding of the halo feature. One should especially read the sections
"Empty and Solid Objects" and "Halo Mapping"  because they are essential for
understanding halos.

4.8.5.1          What are Halos?

Halos are a texture feature allowing us to fill the interior of an object
with particles. The distribution of these particles can be modified using
several density mappings and density functions. The particles can emit light
to give fire- or laser-like effects or they can absorb light to create clouds
or fog.

A halo is attached to an object, the so called container object, just like a
pigment, normal or finish. The container object is completely filled by the
halo but we will not see anything if we do not make sure that the object is
hollow and the surface is translucent. How this is accomplished will be shown
in the next section.

When working with halos we always have to keep in mind that the container
object has to be hollow and translucent.

4.8.5.2          The Emitting Halo

We start with one of the simpler types, the emitting halo. It uses particles
that only emit light. There are no particles that absorb the light coming
from other particles or light sources.

4.8.5.2.1        Starting with a Basic Halo

A clever approach in designing a nice halo effect is to start with a simple,
unit-sized shape that sits on the coordinate system's origin.

In the first example (halo01.pov) we try to create a fiery explosion, which
the sphere is best suited for. We start with a simple scene consisting of a
camera, a light source (we don't care about shadows so we add the shadowless
keyword), a checkered plane and a unit-sized sphere containing the halo.

  camera {
    location <0, 0, -2.5>
    look_at <0, 0, 0>
  }

  light_source { <10, 10, -10> color rgb 1 shadowless }

  plane { z, 2
    pigment { checker color rgb 0, color rgb 1 }
    finish { ambient 1 diffuse 0 }
    scale 0.5
    hollow
  }

  sphere { 0, 1
    pigment { color rgbt <1, 1, 1, 1> }
    halo {
      emitting
      spherical_mapping
      linear
      color_map {
        [ 0 color rgbt <1, 0, 0, 1> ]
        [ 1 color rgbt <1, 1, 0, 0> ]
      }
      samples 10
    }
    hollow
  }


We note that the sphere is set to be hollow and has a translucent surface
(the transmittance channel in the pigment's color is 1), just like it is
required for halos. We also note that the plane has a hollow keyword even
though it has no halo. Why is this necessary?

The reason is quite simple. As described in section "Empty and Solid Objects"
there can be no halo inside any other non-hollow object. Since the camera is
inside the plane object, i. e. it is on the side of the plane that is
considered to be inside, the halo will never be visible unless the plane is
made hollow (or the negative keyword is added to bring the camera on the
outside side of the plane).

What do all those halo keywords and values mean? At the beginning of the halo
the emitting keyword is used to specify what type of halo we want to use. The
emitting halo emits light. That is what is best suited for our fiery
explosion.

The spherical_mapping and linear keywords need a more detailed explanation of
how a halo works (this is also done in chapter "Halo" in more detail).

As noted above the halo is made up of lots of small particles. The
distribution of these particles is described by a density function. In
general, a density function tells us how much particles we'll find at a given
location.

Instead of using an explicitly, mathematical density function, halos rely on
a given set of density mappings and density functions to model a variety of
particle distributions.

The first step in this model is the density mapping function that is used to
map three-dimensional points onto a one-dimensional range of values. In our
example we use a spherical mapping, i.e. we take the distance of a point from
the center of the coordinate system. This is the reason why it is clever to
start with a container object sitting on the coordinate system's center.
Since all density mappings are made relative to this center we won't see
anything if we start with an object sitting somewhere else. Moving the whole
object (including textures and halos) to another location is the correct way
of placing a container object.

Now we have a single value in the range from 0 to 1. This value will be
transformed using a density function to get density values instead of
distance values. Just using this single value won't work because we want to
have particle distributions were the density decreases as we move from the
center of the container object to the outside.

This is done by the density function. There are several alternatives
available as described in the halo reference (see section "Density Function"
). We use the simple linear function that just maps values between 0 and 1
onto a 1 to 0 range. Thus we get a density value of 1 at the center of our
sphere and a value of 0 at its surface.

Now that we have a density function what do we do to see something? This is
where the colour_map keyword comes into play. It is used to describe a color
map that actually tells the program what colors are to be used for what
density. The relation is quite simple: colors at the beginning of the color
map (with small values) will be used for low density values and colors at the
end of the map (high values) will be used for high densities. In our example
the halo will be yellow at the center of the sphere where the density is
greatest and it will blend to red at the surface of the sphere where the
density approaches zero.

The transmittance channel of the colors in the color map is used to model the
translucency of the density field. A value of 0 represents no translucency,
i. e. that areas with the corresponding density will be (almost) opaque,
while a value of 1 means (almost) total translucency.

In our example we use

  color_map {
    [ 0 color rgbt <1, 0, 0, 1> ]
    [ 1 color rgbt <1, 1, 0, 0> ]
  }


which results in a halo with a very translucent, reddish outer area and a
nearly opaque, yellowish inner areas as we can see after tracing the example
image.

The basic halo used in modelling a fiery explosion.

There is one parameter that still needs to be explained: the samples keyword.
This keyword tells POV-Ray how many samples have to be taken along any ray
traveling through the halo to calculate its effect. Using a low value will
result in a high tracing speed while a high value will lead to a low speed.
The sample value has to be increased if the halo looks somewhat noisy, i. e.
if some artifacts of the low sampling rate appear. For more details see
section "Halo Sampling".



4.8.5.2.2        Increasing the Brightness

The colors of the halo in the above image are somewhat dim. There is too much
of the background visible through the halo. That does not look much like
fire, does it? An easy way to fix this is to decrease the transparency of the
particles in the areas of high density. We do this by using use the following
color map instead of the old one (the negative transmittance is correct).

  color_map {
    [ 0 color rgbt <1, 0, 0,  1> ]
    [ 1 color rgbt <1, 1, 0, -1> ]
  }


Looking at the result of halo02.pov we see that the halo is indeed much
brighter.


4.8.5.2.3        Adding Some Turbulence

What we now have does not look like a fiery explosion. It's more a glowing
ball than anything else. Somehow we have to make it look more chaotic, we
have to add some turbulence to it.

This is done by using the turbulence keyword together with the amount of
turbulence we want to add. Just like in the following example.

  sphere { 0, 1
    pigment { color rgbt <1, 1, 1, 1> }
    halo {
      emitting
      spherical_mapping
      linear
      turbulence 1.5
      color_map {
        [ 0 color rgbt <1, 0, 0,  1> ]
        [ 1 color rgbt <1, 1, 0, -1> ]
      }
      samples 10
    }
    hollow
  }


Adding turbulence to the halo moves all points inside the halo container in a
pseudo-random manner. This results in a particle distribution that looks like
there was some kind of flow in the halo (depending on the amount of
turbulence we'll get a laminar or turbulent flow). The high turbulence value
is used because an explosion is highly turbulent.

Looking at the example image (halo03.pov) we'll see that this looks more like
a fiery explosion than the glowing ball we got until now.

Adding some turbulence makes the fiery explosion more realistic.

We notice that the time it took to render the image increased after we added
the turbulence. This is due to the fact that for every sample taken from the
halo the slow turbulence function has to be evaluated.

4.8.5.2.4        Resizing the Halo

There is one strange thing about our fiery explosion though. It still looks
like a sphere. Why does this happen and what can we do to avoid it?

As noted above adding turbulence moves the particles inside the halo
container around. The problem is that some of the particles are actually
moved out of the container object. This leads to high densities at the
surface of the container object revealing the shape of the object (all
particles outside the container are lost and will not visible resulting in a
large, highly visible density change at the surface).

An easy way of avoiding this is to make sure that the particles stay inside
the container object even if we add some turbulence. This is done by scaling
the halo to reduce its size. We do not scale the container object, just the
halo.

This is done by adding the scale keyword inside the halo statement.

  sphere { 0, 1
    pigment { color rgbt <1, 1, 1, 1> }
    halo {
      emitting
      spherical_mapping
      linear
      turbulence 1.5
      color_map {
        [ 0 color rgbt <1, 0, 0,  1> ]
        [ 1 color rgbt <1, 1, 0, -1> ]
      }
      samples 10
      scale 0.5
    }
    hollow
    scale 1.5
  }


The scale 0.5 command tells POV-Ray to scale all points inside the halo by
this amount. This effectively scales the radius we get after the density
mapping to a range of 0 to 0.5 instead of 0 to 1 (without turbulence). If we
now add the turbulence the points are allowed to move half a unit in every
direction without leaving the container object. That is exactly what we want.


To compensate for the smaller halo we would get we scale the sphere (and the
halo inside) by 1.5.

Looking at the new example image (halo04.pov) we will no longer see any signs
of the container sphere. We finally have a nice fiery explosion.

Resizing the halo makes it look much better.

The amount by which to scale the halo depends on the amount of turbulence we
use. The higher the turbulence value the smaller the halo has to be scaled.
That is something to experiment with.

Another way to avoid that points move out of the sphere is to use a larger
sphere, i. e. a sphere with a radius larger than one. It is important to
re-size the sphere before the halo is added because otherwise the halo will
also be scaled.

We note that this only works for spherical and box mapping (and a
non-constant density function). All other mapping types are (partially)
infinite, i. e. the resulting particle distribution covers an infinite space
(see also "Halo Mapping").

4.8.5.2.5        Using Frequency to Improve Realism

Another very good way of improving the realism of our explosion is to use a
frequency value other than one. The way frequency works is explained in
section "Frequency Modifier" in the reference part.

The rather mathematical explanation used there doesn't help much in
understanding how this feature is used. It is quite simple though. The
frequency value just tells the program how many times the color map will be
repeated in the density range from 0 to 1. If a frequency of one (the
default) is specified the color map will be visible once in the density
field, e. g. the color at 0 will be used for density 0, color at 0.5 will be
used for density 0.5 and the color at 1 will be used for density 1. Simple,
isn't it?

If we choose a frequency of two, the color at 0 will be used for density 0,
the color at 0.5 will be used for density 0.25 and the color at 1 will be
used for density 0.5. What about the densities above 0.5? Since there are no
entries in the color map for values above 1 we just start at 0 again. Thus
the color at 0.1 will be used for density 0.55 ((2*0.55) mod 1 = 1.1 mod 1 =
0.1), the color at 0.5 will be used for density 0.75 and the color at 1 will
be used for density 1.

If we are good at mathematics we'll note that the above example is not quite
right because (1 * 2) mod 1 = 0 and not 1. We just think that we used a value
slightly smaller than one and everything will be fine.

We may have noticed that in order to avoid sudden changes in the halo color
for frequencies larger than one we'll have to used a periodic color map, i.e.
a color map whose entries at 0 and 1 are the same.

We'll change our example by using a periodic color map and changing the
frequency value to two.

  sphere { 0, 1
    pigment { color rgbt <1, 1, 1, 1> }
    halo {
      emitting
      spherical_mapping
      linear
      turbulence 1.5
      color_map {
        [ 0.0 color rgbt <1, 0, 0,  1> ]
        [ 0.5 color rgbt <1, 1, 0, -1> ]
        [ 1.0 color rgbt <1, 0, 0,  1> ]
      }
      frequency 2
      samples 20
      scale 0.5
    }
    hollow
    scale 1.5
  }


Using a periodic color map and a frequency of two gives a much nicer
explosion.

Looking at the result of (halo05.pov) we can be quite satisfied with the
explosion we just have created, can't we?

There's one thing left we should be aware of when increasing the frequency
value. It is often necessary to increase the sample rate in (nearly) the same
way as we change the frequency. If we don't do this we'll probably get some
severe aliasing artifacts (like color jumps or strange bands of colors). If
this happens just change the samples value according to the frequency value
(twice sampling rate for a doubled frequency).

4.8.5.2.6        Changing the Halo Color

We have a nice fiery explosion but we want to try to add some science fiction
touch to it by using different colors. How about a nice green, less turbulent
explosion that gets red at its borders?

Nothing easier than that!

  sphere { 0, 1.5
    pigment { color rgbt <1, 1, 1, 1> }
    halo {
      emitting
      spherical_mapping
      linear
      turbulence 0.5
      color_map {
        [ 0 color rgbt <0, 1, 0,  1> ]
        [ 1 color rgbt <1, 0, 0, -1> ]
      }
      samples 10
      scale 0.75
    }
    hollow
    scale 1.5
  }


Using red and green colors gives an unexpected result.

This should do the trick. Looking at the result of halo06.pov we may be
disappointed. Where is the red center of the explosion? The borders are green
as expected but there is a lot of yellow in the center and only a little bit
red. What is happening?

We use an emitting halo in our example. According to the corresponding
section in the halo reference chapter (see "Emitting") this type of halo uses
very small particles that do not attenuate light passing through the halo.
Especially particles near the viewer do not attenuate the light coming from
particles far away from the viewer.

During the calculation of the halo's color near the center of the container
sphere, the ray steps through nearly all possible densities of the particle
distribution. Thus we get red and green colors as we march on, depending on
the current position in the halo. The sum of these colors is used which will
gives as a yellow color (the sum of red and green is yellow). This is what is
happening here.

How can we still get what we want? The answer is to use a glowing halo
instead of the emitting halo. The glowing halo is very similar to the
emitting one except that it attenuates the light passing through. Thus the
light of particles lying behind other particles will be attenuated by the
particles in front.


4.8.5.3          The Glowing Halo

We have mentioned the glowing halo in the section about the emitting halo as
one way to avoid the color mixing that is happening with emitting halos.

The glowing halo is very similar to the emitting halo except that it also
absorbs light. We can view it as a combination of the emitting and the
attenuating halo described in section "The Attenuating Halo".

By just replacing the emitting keyword in the example in section "Changing
the Halo Color" with the glowing keyword we get the desired effect as shown
in the example image (halo11.pov).

Using a glowing halo gives the expected result.

Even though the red color of the high density areas is not very visible
because the green colored, lower density areas lying in front absorb most of
the red light, we don't get yellow color where we would have expected a red
one.

Due to its similarity with the emitting halo we have to make some experiments
with this halo type. We just have to keep all those things we learned in the
previous sections in mind to get some satisfying results.

4.8.5.4          The Attenuating Halo

Another simple halo type is the attenuating halo that only absorbs light. It
doesn't radiate on its own.

A great difference between the attenuating halo and the other halo types is
that the color of the attenuating halo is calculated from the halo's color
map using the total particle density along a given ray. The other types
calculated a (weighted) average of the colors calculated from the density at
each sample.

4.8.5.4.1        Making a Cloud

Attenuating halos are ideal to create clouds and smoke. In the following
examples we will try to make a neat little cloud. We start again by using a
unit-sized sphere that is filled with a basic attenuating halo (halo21.pov).

  camera {
    location <0, 0, -2.5>
    look_at <0, 0, 0>
  }

  light_source { <10, 10, -10> color rgb 1 shadowless }

  plane { z, 2
    pigment { checker color rgb 0, color rgb 1 }
    finish { ambient 1 diffuse 0 }
    scale 0.5
    hollow
  }

  sphere { 0, 1
    pigment { color rgbt <1, 1, 1, 1> }
    halo {
      attenuating
      spherical_mapping
      linear
      color_map {
        [ 0 color rgbt <1, 0, 0, 1> ]
        [ 1 color rgbt <1, 0, 0, 0> ]
      }
      samples 10
    }
    hollow
  }


Even though clouds normally are not red but white or gray, we use the red
color to make it more visible against the black/white checkerboard
background.

The color of an attenuating halo is calculated from the total accumulated
density after a ray has marched through the complete particle field. This has
to be kept in mind when creating the color map. We want the areas of the
cloud with a low density to have a high translucency so we use a color of
rgbt<1,0,0,1> and we want the high density areas to be opaque so we choose a
color of rgbt<1,0,0,0>.


4.8.5.4.2        Scaling the Halo Container

The cloud we have created so far doesn't look very realistic. It's just a
red, partially translucent ball. In order to get a better result we use some
of the methods we have already learned in the sections about emitting halos
above. We add some turbulence to get a more realistic shape, we scale the
halo to avoid the container object's surface to become visible and we
decrease the translucency of the areas with a high particle density.

Another idea is to scale the container object to get an ellipsoid shape that
can be used to model a cloud pretty good. This is done by the scale <1.5,
0.75, 1> command at the end of the sphere. It scales both, the sphere and the
halo inside.

  sphere { 0, 1
    pigment { color rgbt <1, 1, 1, 1> }
    halo {
      attenuating
      spherical_mapping
      linear
      turbulence 1
      color_map {
        [ 0 color rgbt <1, 0, 0,  1> ]
        [ 1 color rgbt <1, 0, 0, -1> ]
      }
      samples 10
      scale 0.75
    }
    hollow
    scale <1.5, 0.75, 1>
  }


Looking at the results of halo22.pov we see that this looks more like a real
cloud (besides the color).


4.8.5.4.3        Adding Additional Halos

Another trick to get some more realism is to use multiple halos. If we look
at cumulus clouds e. g. we notice that they often extend at the top while
they are quite flat at the bottom.

We want to model this appearance by adding two additional halos to our
current container object (see section "Multiple Halos" for more details).
This is done in the following way:

  sphere { 0, 1.5
    pigment { color rgbt <1, 1, 1, 1> }
    halo {
      attenuating
      spherical_mapping
      linear
      turbulence 1
      color_map {
        [ 0 color rgbt <1, 0, 0,  1> ]
        [ 1 color rgbt <1, 0, 0, -1> ]
      }
      samples 10
      scale <0.75, 0.5, 1>
      translate <-0.4, 0, 0>
    }
    halo {
      attenuating
      spherical_mapping
      linear
      turbulence 1
      color_map {
        [ 0 color rgbt <1, 0, 0,  1> ]
        [ 1 color rgbt <1, 0, 0, -1> ]
      }
      samples 10
      scale <0.75, 0.5, 1>
      translate <0.4, 0, 0>
    }
    halo {
      attenuating
      spherical_mapping
      linear
      turbulence 1
      color_map {
        [ 0 color rgbt <1, 0, 0,  1> ]
        [ 1 color rgbt <1, 0, 0, -1> ]
      }
      samples 10
      scale 0.5
      translate <0, 0.2, 0>
    }
    hollow
  }


The three halos used differ only in their location, i. e. in the translation
vector we have used. The first two halos are used to form the base of the
cloud while the last sits on top of the others. The sphere has a different
radius than the previous ones because more space is needed for all three
halos.

The result of halo23.pov somewhat looks like a cloud, even though it may need
some work.


4.8.5.5          The Dust Halo

The dust halo is a very complex halo type. It allows us to see the
interaction of light coming from a light source with the particles in the
halo. These particles absorb light in the same way as the attenuating halo.
In addition they scatter the incoming light. This makes beams of light and
shadows cast by objects onto the halo become visible.

4.8.5.5.1        Starting With an Object Lit by a Spotlight

We start with a box shaped object that is lit by a spotlight. We don't use
any halo at this moment because we want to see if the object is completely
lit by the light (halo31.pov).

  camera {
    location <0, 0, -2.5>
    look_at <0, 0, 0>
  }

  background { color rgb <0.2, 0.4, 0.8> }

  light_source {
    <2.5, 2.5, -2.5>
    colour rgb <1, 1, 1>
    spotlight
    point_at <0, 0, 0>
    radius 12
    falloff 15
    tightness 1
  }

  difference {
    box { -1, 1 }
    box { <-1.1, -0.8, -0.8>, <1.1, 0.8, 0.8> }
    box { <-0.8, -1.1, -0.8>, <0.8, 1.1, 0.8> }
    box { <-0.8, -0.8, -1.1>, <0.8, 0.8, 1.1> }
    pigment { color rgb <1, 0.2, 0.2> }
    scale 0.5
    rotate 45*y
    rotate 45*x
  }


The object we want to use.

As we see the whole object is lit by the light source. Now we can start to
add some dust.

4.8.5.5.2        Adding Some Dust

We use a box to contain the dust halo. Since we use a constant density
function it doesn't matter what kind of density mapping we use. The density
has the value specified by the max_value keyword everywhere inside the halo
(the default value is one). The isotropic scattering is selected with
dust_type .

  box { -1, 1
    pigment { colour rgbt <1, 1, 1, 1> }
    halo {
      dust
      dust_type 1
      box_mapping
      constant
      colour_map {
        [ 0 color rgbt <1, 1, 1, 1> ]
        [ 1 color rgbt <1, 1, 1, 0> ]
      }
      samples 10
    }
    hollow
    scale 5
  }


This dust is too thick.

The result of halo32.pov is too bright. The dust is too thick and we can only
see some parts of the object and no background.

4.8.5.5.3        Decreasing the Dust Density

The density inside the halo has the constant value one. This means that only
the color map entry at position one is used to determine the density and
color of the dust.

We use a transmittance value of 0.7 to get a much thinner dust.

  box { -1, 1
    pigment { colour rgbt <1, 1, 1, 1> }
    halo {
      dust
      dust_type 1
      box_mapping
      constant
      colour_map {
        [ 0 color rgbt <1, 1, 1, 1.0> ]
        [ 1 color rgbt <1, 1, 1, 0.7> ]
      }
      samples 10
    }
    hollow
    scale 5
  }


A thinner dust looks much better.

Beside the ugly aliasing artifacts the image looks much better. We can see
the whole object and even the background is slightly visible (halo33.pov).

4.8.5.5.4        Making the Shadows Look Good

In order to reduce the aliasing artifacts we use three different techniques:
jittering, super-sampling and an increased overall sampling rate.

The jittering is used to add some randomness to the sampling points making
the image look more noisy. This helps because regular aliasing artifacts are
more annoying than noise. A low jitter value is a good choice.

The super-sampling tries to detect fine features by taking additional samples
in areas of high intensity changes. The threshold at which super-sampling is
used and the maximum recursion level can be specified using the aa_threshold
and aa_level keywords.

The approach that always works is to increase the overall sampling rate.
Since this is also the slowest method we should always try to use the other
methods first. If they don't suffice we have to increase the sampling rate.

We use the following halo to reduce the aliasing artifacts (halo34.pov).

  box { -1, 1
    pigment { colour rgbt <1, 1, 1, 1> }
    halo {
      dust
      dust_type 1
      box_mapping
      constant
      colour_map {
        [ 0 color rgbt <1, 1, 1, 1.0> ]
        [ 1 color rgbt <1, 1, 1, 0.7> ]
      }
      samples 50
      aa_level 3
      aa_threshold 0.2
      jitter 0.1
    }
    hollow
    scale 5
  }


Different anti-aliasing methods help to get a satisfying result.

The image looks much better now. There are hardly any aliasing artifacts
left.

The same parameters we have used are discussed in the section about the
atmosphere feature (see "The Atmosphere" for further explanations).

4.8.5.5.5        Adding Turbulence

The major difference between the halo's dust and the atmosphere described in
"The Atmosphere" is the ability to choose a non-uniform particle distribution
for the dust. This includes the fact that the halo is limited to a container
object as well as the different density mappings and functions.

Another interesting way of getting an irregular distribution is to add some
turbulence to the dust. This is done with the turbulence keyword followed by
the amount of turbulence to use, like the following example shows
(halo35.pov).

  box { -1, 1
    pigment { colour rgbt <1, 1, 1, 1> }
    halo {
      dust
      dust_type 1
      box_mapping
      linear
      turbulence 1
      colour_map {
        [ 0 color rgbt <1, 1, 1, 1.0> ]
        [ 1 color rgbt <1, 1, 1, 0.5> ]
      }
      samples 50
      aa_level 3
      aa_threshold 0.2
      jitter 0.1
    }
    hollow
    scale 5
  }


Adding turbulence to the dust makes it much more interesting.

The image we now get looks much more interesting due to the shifts in the
particle density.

We should note that we use a linear density function instead of the previous
constant one. This is necessary because with a constant density function the
density has the same value everywhere. Adding turbulence would have no effect
because wherever the points are moved the density will have this same value.
Only a non-constant density distribution makes sense when turbulence is
added.

The fact that the turbulence value is actually a vector can be used to create
effects like waterfalls by using a large turbulence value in one direction
only (e.g. turbulence <0.2, 1, 0.2> ).

4.8.5.5.6        Using a Coloured Dust

If we want to create a colored dust we can easily do this by using a
non-white color in the halo's color map. In this case we'll also have to set
the filter channels in the color map to non-zero values to specify the amount
of light that will be filtered by the dust's color.

We use the following color map to get a partially filtering, red dust for
example:

  colour_map {
    [ 0 color rgbft <1, 0, 0, 0.5, 1.0> ]
    [ 1 color rgbft <1, 0, 0, 0.5, 0.7> ]
  }


4.8.5.6          Halo Pitfalls

Due to the complexity of the halo feature and the few experiences people have
made so far there are a lot of things still to discover.

Some of the most common problems and pitfalls are described below to help us
avoid the most common problems.

4.8.5.6.1        Where Halos are Allowed

As mentioned above a halo completly fills the interior of an object. Keeping
this in mind it is reasonable that the following example does not make sense.


  sphere { 0, 1
    pigment {
      checker
      texture {
        pigment { color Clear }
        halo { ... }
      }
      texture {
        pigment { color Red }
      }
    }
    hollow
  }


What's wrong with this example? It's simply that a halo is used to describe
the interior of an object and that one cannot describe this interior by
describing how the surface of the object looks like. But that's what was done
in the example above. We cannot imagine what the interior of the sphere will
look like. Will it be filled completey with the halo? Will there be areas
filled by the halo and some filled by air? How will those areas look like?

We won't be able to tell the interior's properties from looking at the
surface. It's just not possible. This should always be kept in mind.

If the above example was meant to create a sphere filled with a halo and
covered with a checker board pattern that partially hid the halo we would
have used the following syntax:

  sphere { 0, 1
    pigment {
      checker
      texture {
        pigment { color Clear }
      }
      texture {
        pigment { color Red }
      }
    }
    halo { ... }
    hollow
  }


A halo is always applied to an object in the following way:

  OBJECT {
    texture {
      pigment { ... }
      normal { ... }
      finish { ... }
      halo { ... }
    }
    hollow
  }


There's no halo allowed inside any pigment statement, color map, pigment map,
texture map, material map, or whatever. We are not hindered to do this but we
will not get what we want.

We can use halos with a layered textures as long as we make sure that the
halos are only attached to the lowest layer (this layer has to be partially
transparent to see the halo of course).

4.8.5.6.2        Overlapping Container Objects

POV-Ray is not able to handle overlapping container objects correctly. If we
create two overlapping spheres that contain a halo we won't get correct
results where the spheres overlap. The halo effect is calculated
independently for each sphere and the results are added.

If we want to add different halos we have to put all halos inside a single
container object to make sure the halo is calculated correctly (see also
"Multiple Halos").

We should also note that non-overlapping, stacked halo containers are handled
correctly. If we put a container object in front of another container object
the halos are rendered correctly.

4.8.5.6.3        Multiple Attenuating Halos

It is currently not possible to use multiple attenuating halos with different
color maps. The color map of the last halo will be used for all halos in the
container object.

4.8.5.6.4        Halos and Hollow Objects

In order to correctly render halo effects we have to make sure that all
objects the camera is inside are hollow. This is done by adding the hollow
keyword.


4.8.5.6.5        Scaling a Halo Container

If we scale a halo container object we should keep in mind that it makes a
great difference where we place the scale keyword.

Scaling the object before the halo statement will only scale the container
object not the halo. This is useful if we want to avoid that the surface of
the container object becomes visible due to the use of turbulence. As we have
learned in the sections above particles may move out of the container object
- where they are invisible - if turbulence is added. This only works for
spherical and box mapping because the density fields described by the other
mapping types don't have finite dimensions.

If the scale keyword is used after the halo statement both, the halo and the
container object, are scaled. This is useful to scale the halo to our needs.

The halo keeps its appearance regardless of the transformations applied to
the container object (after the halo), i.e. the halo's translucency, color
and turbulence characteristics will not change.

4.8.5.6.6        Choosing a Sampling Rate

Normally we will start with a low sampling rate and we willl only increase it
if any aliasing artifacts show up (and don't vanish by using super-sampling
and jittering).

The halo's appearance is independent from the sampling rate as long as there
are enough samples to get a good estimate of what the halo really looks like.
This means that one or two samples are hardly ever enough to determine the
halo's appearance. As we increase the number of samples the halo will quickly
approach its real appearance.

To put it in a nutshell, the halo will not change its appearance with the
sample rate as long as we have a sufficient number of samples and no aliasing
artifacts occur.

4.8.5.6.7        Using Turbulence

As noted in one of the above sections turbulence will have no effect if the
constant density function is used (keyword constant). It doesn't matter how
much or where we move a point if the density is constant and thus does not
depend on the location of the point. We'll get the same density value for all
location.

Whenever we add turbulence to a halo we must not use the constant density
function.

4.9              Working With Special Textures

Many of the pigment patterns we have seen elsewhere in POV-Ray make use of a
color_map statement to blend different colors together. Depending on how we
list the entries of the color map, we can fade gradually from one color to
the next, or have it abruptly make the transition from one to the next. In
fact, the color map is a powerful tool for customizing the various pigment
patterns, which requires a bit of practice to learn to use it correctly. And
all that's fine, when it's just individual colors we want to use. But what if
we could blend entire pigment patterns, normal patterns, or whole other
textures? Starting with POV-Ray 3, we can!

In order to experiment with some of the exciting new texturing options, let
us set up a basic scene file, into which we will be plugging the example
textures to experiment with later. So to begin, we set up the following basic
include files, a camera and a light source.

  #include "colors.inc"
  #include "textures.inc"

  camera {
    orthographic
    up <0, 5, 0>
    right <5, 0, 0>
    location <0, 0, -25>
    look_at <0, 0, 0>
  }

  light_source { <100, 100, -100> color White }


4.9.1            Working With Pigment Maps

Starting with something simple, let's look at the pigment map. We must not
confuse this with a color map, as color maps can only take individual colors
as entries in the map, while pigment maps can use entire other pigment
patterns. To get a feel for these, let's begin by setting up a basic plane
with a simple pigment map. Now, in the following example, we are going to
declare each of the pigments we are going to use before we actually use them.
This isn't strictly necessary (we could put an entire pigment description in
each entry of the map) but it just makes the whole thing more readable.

  // simple Black on White checkboard... it's a classic
  #declare Pigment1 = pigment {
    checker color Black color White
    scale .1
  }

  // kind of a "psychedelic rings" effect
  #declare Pigment2 = pigment {
    wood
    color_map {
      [ 0.0 Red ]
      [ 0.3 Yellow ]
      [ 0.6 Green ]
      [ 1.0 Blue ]
    }
  }

  plane { -z, 0
    pigment {
      gradient x
      pigment_map {
        [ 0.0 Pigment1 ]
        [ 0.5 Pigment2 ]
        [ 1.0 Pigment1 ]
      }
    }
  }


Okay, what we have done here is very simple, and probably quite recognizable
if we have been working with color maps all along anyway. All we have done is
substituted a pigment map where a color map would normally go, and as the
entries in our map, we have referenced our declared pigments. When we render
this example, we see a pattern which fades back and forth between the classic
checkerboard, and those colorful rings. Because we fade from Pigment1 to
Pigment2 and then back again, we see a clear blending of the two patterns at
the transition points. We could just as easily get a sudden transition by
amending the map to read.

  pigment_map {
    [ 0.0 Pigment1 ]
    [ 0.5 Pigment1 ]
    [ 0.5 Pigment2 ]
    [ 1.0 Pigment2 ]
  }


4.9.2            Working With Normal Maps

For our next example, we replace the plane in the scene with this one.

  plane { -z, 0
    pigment { White }
    normal {
      gradient x
      normal_map {
        [ 0.0 bumps 1 scale .1]
        [ 1.0 ripples 1 scale .1]
      }
    }
  }


First of all, we have chosen a solid white color to show off all bumping to
best effect. Secondly, we notice that our map blends smoothly from all bumps
at 0.0 to all ripples at 1.0, but because this is a default gradient, it
falls off abruptly back to bumps at the beginning of the next cycle. We
Render this and see just enough sharp transitions to clearly see where one
normal gives over to another, yet also an example of how two normal patterns
look while they are smoothly blending into one another.

The syntax is the same as we would expect. We just changed the type of map,
moved it into the normal block and supplied appropriate bump types. It is
important to remember that as of POV-Ray 3, all patterns that work with
pigments work as normals as well (and vice versa, of course) so we could just
as easily have blended from wood to granite, or any other pattern we like. We
experiment a bit and get a feel for what the different patterns look like.

After seeing how interesting the various normals look blended, we might like
to see them completely blended all the way through rather than this business
of fading from one to the next. Well, that is possible too, but we would be
getting ahead of ourselves. That is called the average function, and we will
return to it a little bit further down the page.

4.9.3            Working With Texture Maps

We know how to blend colors, pigment patterns, and normals, and we are
probably thinking what about finishes? What about whole textures? Both of
these can be kind of covered under one topic. While there is no finish map
per se, there are texture maps, and we can easily adapt these to serve as
finish maps, simply by putting the same pigment and/or normal in each of the
texture entries of the map. Here is an example. We eliminate the declared
pigments we used before and the previous plane, and add the following.

  #declare Texture1 = texture {
    pigment { Grey }
    finish { reflection 1 }
  }

  #declare Texture2 = texture {
    pigment { Grey }
    finish { reflection 0 }
  }

  cylinder { <-2, 5, -2>, <-2, -5, -2>, 1
    pigment { Blue }
  }

  plane { -z, 0
    rotate y * 30
    texture {
      gradient y
      texture_map {
        [ 0.0 Texture1 ]
        [ 0.4 Texture1 ]
        [ 0.6 Texture2 ]
        [ 1.0 Texture2 ]
      }
      scale 2
    }
  }


Now, what have we done here? The background plane alternates vertically
between two textures, identical except for their finishes. When we render
this, the cylinder has a reflection part of the way down the plane, and then
stops reflecting, then begins and then stops again, in a gradient pattern
down the surface of the plane. With a little adaptation, this could be used
with any pattern, and in any number of creative ways, whether we just wanted
to give various parts of an object different finishes, as we are doing here,
or whole different textures altogether.

One might ask: if there is a texture map, why do we need pigment and normal
maps? Fair question. The answer: speed of calculation. If we use a texture
map, for every in-between point, POV-Ray must make multiple calculations for
each texture element, and then run a weighted average to produce the correct
value for that point. Using just a pigment map (or just a normal map)
decreases the overall number of calculations, and our texture renders a bit
faster in the bargain. As a rule of thumb: we use pigment or normal maps
where we can and only fall back on texture maps if we need the extra
flexibility.

4.9.4            Working With List Textures

If we have followed the corresponding tutorials on simple pigments, we know
that there are three patterns called color list patterns, because rather than
using a color map, these simple but useful patterns take a list of colors
immediately following the pattern keyword. We're talking about checker,
hexagon, and, new to POV-Ray 3, the brick pattern.

Naturally they also work with whole pigments, normals, and entire textures,
just as the other patterns do above. The only difference is that we list
entries in the pattern (as we would do with individual colors) rather than
using a map of entries. Here is an example. We strike the plane and any
declared pigments we had left over in our last example, and add the following
to our basic file.

  #declare Pigment1 = pigment {
    hexagon
    color Yellow color Green color Grey
    scale .1
  }

  #declare Pigment2 = pigment {
    checker
    color Red color Blue
    scale .1
  }

  #declare Pigment3 = pigment {
    brick
    color White color Black
    rotate -90*x
    scale .1
  }

  box { -5, 5
    pigment {
      hexagon
      pigment {Pigment1}
      pigment {Pigment2}
      pigment {Pigment3}
      rotate 90*x
    }
  }


We begin by declaring an example of each of the color list patterns as
individual pigments. Then we use the hexagon pattern as a pigment list
pattern, simply feeding it a list of pigments rather than colors as we did
above. There are two rotate statements throughout this example, because
bricks are aligned along the z-direction, while hexagons align along the
y-direction, and we wanted everything to face toward the camera we originally
declared out in the -z-direction so we can really see the patterns within
patterns effect here.

Of course color list patterns used to be only for pigments, but as of POV-Ray
3, everything that worked for pigments can now also be adapted for normals or
entire textures. A couple of quick examples might look like

  normal {
    brick
    normal { granite .1 }
    normal { bumps 1 scale .1 }
  }


or...

  texture {
    checker
    texture { Gold_Metal }
    texture { Silver_Metal }
  }


4.9.5            What About Tiles?

In earlier versions of POV-Ray, there was a texture pattern called tiles. By
simply using a checker texture pattern (as we just saw above), we can achieve
the same thing as tiles used to do, so it is now obsolete. It is still
supported by POV-Ray 3 for backwards compatibility with old scene files, but
now is a good time to get in the habit of using a checker pattern instead.

4.9.6            Average Function

Now things get interesting. Above, we began to see how pigments and normals
can fade from one to the other when we used them in maps. But how about if we
want a smooth blend of patterns all the way through? That is where a new
feature called average can come in very handy. Average works with pigment,
normal, and texture maps, although the syntax is a little bit different, and
when we are not expecting it, the change can be confusing. Here is a simple
example. We use our standard includes, camera and light source from above,
and enter the following object.

  plane { -z, 0
    pigment { White }
    normal {
      average
      normal_map {
        [ gradient x ]
        [ gradient y ]
      }
    }
  }


What we have done here is pretty self explanatory as soon as we render it. We
have combined a vertical with a horizontal gradient bump pattern, creating
crisscrossing gradients. Actually, the crisscrossing effect is a smooth blend
of gradient x with gradient y all the way across our plane. Now, what about
that syntax difference?

We see how our normal map has changed from earlier examples. The floating
point value to the lefthand side of each map entry has been removed. That
value usually helps in procedurally mapping each entry to the pattern we have
selected, but average is a smooth blend all the way through, not a pattern,
so it cannot use those values. In fact, including them may sometimes lead to
unexpected results, such as entries being lost or misrepresented in some way.
To ensure that we'll get the pattern blend we anticipate, we leave off the
floating point value.

4.9.7            Working With Layered Textures

With the multitudinous colors, patterns, and options for creating complex
textures in POV-Ray, we can easily become deeply engrossed in mixing and
tweaking just the right textures to apply to our latest creations. But as we
go, sooner or later there is going to come that special texture. That texture
that is sort of like wood, only varnished, and with a kind of spotty yellow
streaking, and some vertical gray flecks, that looks like someone started
painting over it all, and then stopped, leaving part of the wood visible
through the paint.

Only... now what? How do we get all that into one texture? No pattern can do
that many things. Before we panic and say image map there is at least one
more option: layered textures.

With layered textures, we only need to specify a series of textures, one
after the other, all associated with the same object. Each texture we list
will be applied one on top of the other, from bottom to top in the order they
appear.

It is very important to note that we must have some degree of transparency
(filter or transmit) in the pigments of our upper textures, or the ones below
will get lost underneath. We won't receive a warning or an error -
technically it is legal to do this: it just doesn't make sense. It is like
spending hours sketching an elaborate image on a bare wall, then slapping a
solid white coat of latex paint over it.

Let's design a very simple object with a layered texture, and look at how it
works. We create a file called LAYTEX.POV and add the following lines.

  #include "colors.inc"
  #include "textures.inc"

  camera {
    location <0, 5, -30>
    look_at <0, 0, 0>
  }

  light_source { <-20, 30, -50> color White }

  plane { y, 0 pigment { checker color Green color Yellow  } }

  background { rgb <.7, .7, 1> }

  box { <-10, 0, -10>, <10, 10, 10>
    texture {
      Silver_Metal // a metal object ...
      normal {     // ... which has suffered a beating
        dents 2
        scale 1.5
      }
    } // (end of base texture)

    texture { // ... has some flecks of rust ...
      pigment {
        granite
        color_map {
          [0.0 rgb <.2, 0, 0> ]
          [0.2 color Brown ]
          [0.2 rgbt <1, 1, 1, 1> ]
          [1.0 rgbt <1, 1, 1, 1> ]
        }
        frequency 16
      }
    } // (end rust fleck texture)

    texture { // ... and some sooty black marks
      pigment {
        bozo
        color_map {
          [0.0 color Black ]
          [0.2 color rgbt <0, 0, 0, .5> ]
          [0.4 color rgbt <.5, .5, .5, .5> ]
          [0.5 color rgbt <1, 1, 1, 1> ]
          [1.0 color rgbt <1, 1, 1, 1> ]
        }
        scale 3
      }
    } // (end of sooty mark texture)

  } // (end of box declaration)


Whew. This gets complicated, so to make it easier to read, we have included
comments showing what we are doing and where various parts of the declaration
end (so we don't get lost in all those closing brackets!). To begin, we
created a simple box over the classic checkerboard floor, and give the
background sky a pale blue color. Now for the fun part...

To begin with we made the box use the Silver_Metal texture as declared in
textures.inc (for bonus points, look up textures.inc and see how this
standard texture was originally created sometime). To give it the start of
its abused state, we added the dents normal pattern, which creates the
illusion of some denting in the surface as if our mysterious metal box had
been knocked around quite a bit.

The flecks of rust are nothing but a fine grain granite pattern fading from
dark red to brown which then abruptly drops to fully transparent for the
majority of the color map. True, we could probably come up with a more
realistic pattern of rust using pigment maps to cluster rusty spots, but
pigment maps are a subject for another tutorial section, so let's skip that
just now.

Lastly, we have added a third texture to the pot. The randomly shifting bozo
texture gradually fades from blackened centers to semi-transparent medium
gray, and then ultimately to fully transparent for the latter half of its
color map. This gives us a look of sooty burn marks further marring the
surface of the metal box. The final result leaves our mysterious metal box
looking truly abused, using multiple texture patterns, one on top of the
other, to produce an effect that no single pattern could generate!

4.9.7.1          Declaring Layered Textures

In the event we want to reuse a layered texture on several objects in our
scene, it is perfectly legal to declare a layered texture. We won't repeat
the whole texture from above, but the general format would be something like
this:

  #declare Abused_Metal =
    texture { /* insert your base texture here... */ }
    texture { /* and your rust flecks here... */ }
    texture { /* and of course, your sooty burn marks here */ }


POV-Ray has no problem spotting where the declaration ends, because the
textures follow one after the other with no objects or directives in between.
The layered texture to be declared will be assumed to continue until it finds
something other than another texture, so any number of layers can be added in
to a declaration in this fashion.

One final word about layered textures: whatever layered texture we create,
whether declared or not, we must not leave off the texture wrapper. In
conventional single textures a common shorthand is to have just a pigment, or
just a pigment and finish, or just a normal, or whatever, and leave them
outside of a texture statement. This shorthand does not extend to layered
textures. As far as POV-Ray is concerned we can layer entire textures, but
not individual pieces of textures. For example

  #declare Bad_Texture =
    texture { /* insert your base texture here... */ }
    pigment { Red filter .5 }
    normal { bumps 1 }


will not work. The pigment and the normal are just floating there without
being part of any particular texture. Inside an object, with just a single
texture, we can do this sort of thing, but with layered textures, we would
just generate an error whether inside the object or in a declaration.

4.9.7.2          Another Layered Textures Example

To further explain how layered textures work another example is described in
detail. A tablecloth is created to be used in a picnic scene. Since a simple
red and white checked cloth looks entirely too new, too flat, and too much
like a tiled floor, layered textures are used to stain the cloth.

We're going to create a scene containing four boxes. The first box has that
plain red and white texture we started with in our picnic scene, the second
adds a layer meant to realistically fade the cloth, the third adds some wine
stains, and the final box adds a few wrinkles (not another layer, but we must
note when and where adding changes to the surface normal have an effect in
layered textures).

We start by placing a camera, some lights, and the first box. At this stage,
the texture is plain tiling, not layered. See file layered1.pov.

  #include "colors.inc"

  camera {
    location <0, 0, -6>
    look_at <0, 0, 0>
  }

  light_source { <-20, 30, -100> color White }
  light_source { <10, 30, -10> color White }
  light_source { <0, 30, 10> color White }

  #declare PLAIN_TEXTURE =
    // red/white check
    texture {
      pigment {
        checker
        color rgb<1.000, 0.000, 0.000>
        color rgb<1.000, 1.000, 1.000>
        scale <0.2500, 0.2500, 0.2500>
      }
    }

  // plain red/white check box

  box { <-1, -1, -1>, <1, 1, 1>
    texture {
      PLAIN_TEXTURE
    }
    translate  <-1.5, 1.2, 0>
  }


We render this scene. It is not particularly interesting, isn't it? That is
why we will use some layered textures to make it more interesting.

First, we add a layer of two different, partially transparent greys. We tile
them as we had tiled the red and white colors, but we add some turbulence to
make the fading more realistic. We add following box to the previous scene
and re-render (see file layered2.pov).

  #declare FADED_TEXTURE =
    // red/white check texture
    texture {
      pigment {
        checker
        color rgb<0.920, 0.000, 0.000>
        color rgb<1.000, 1.000, 1.000>
        scale <0.2500, 0.2500, 0.2500>
      }
    }
    // greys to fade red/white
    texture {
      pigment {
        checker
        color rgbf<0.632, 0.612, 0.688, 0.698>
        color rgbf<0.420, 0.459, 0.520, 0.953>
        turbulence 0.500
        scale <0.2500, 0.2500, 0.2500>
      }
    }

  // faded red/white check box

  box { <-1, -1, -1>, <1, 1, 1>
    texture {
      FADED_TEXTURE
    }
    translate  <1.5, 1.2, 0>
  }


Even though it is a subtle difference, the red and white checks no longer
look quite so new.

Since there is a bottle of wine in the picnic scene, we thought it might be a
nice touch to add a stain or two. While this effect can almost be achieved by
placing a flattened blob on the cloth, what we really end up with is a spill
effect, not a stain. Thus it is time to add another layer.

Again, we add another box to the scene we already have scripted and re-render
(see file layered3.pov).

  #declare STAINED_TEXTURE =
    // red/white check
    texture {
      pigment {
        checker
        color rgb<0.920, 0.000, 0.000>
        color rgb<1.000, 1.000, 1.000>
        scale <0.2500, 0.2500, 0.2500>
      }
    }
    // greys to fade check
    texture {
      pigment {
        checker
        color rgbf<0.634, 0.612, 0.688, 0.698>
        color rgbf<0.421, 0.463, 0.518, 0.953>
        turbulence 0.500
        scale <0.2500, 0.2500, 0.2500>
      }
    }
    // wine stain
    texture {
      pigment {
        spotted
        color_map {
          [ 0.000  color rgb<0.483, 0.165, 0.165> ]
          [ 0.329  color rgbf<1.000, 1.000, 1.000, 1.000> ]
          [ 0.734  color rgbf<1.000, 1.000, 1.000, 1.000> ]

          [ 1.000  color rgb<0.483, 0.165, 0.165> ]
        }
        turbulence 0.500
        frequency 1.500
      }
    }

  // stained box

  box { <-1, -1, -1>, <1, 1, 1>
    texture {
      STAINED_TEXTURE
    }
    translate  <-1.5, -1.2, 0>
  }


Now there's a tablecloth texture with personality.

Another touch we want to add to the cloth are some wrinkles as if the cloth
had been rumpled. This is not another texture layer, but when working with
layered textures, we must keep in mind that changes to the surface normal
must be included in the uppermost layer of the texture. Changes to lower
layers have no effect on the final product (no matter how transparent the
upper layers are).

We add this final box to the script and re-render (see file layered4.pov)

  #declare WRINKLED_TEXTURE =
    // red and white check
    texture {
      pigment {
        checker
        color rgb<0.920, 0.000, 0.000>
        color rgb<1.000, 1.000, 1.000>
        scale <0.2500, 0.2500, 0.2500>
      }
    }
    // greys to "fade" checks
    texture {
      pigment {
        checker
        color rgbf<0.632, 0.612, 0.688, 0.698>
        color rgbf<0.420, 0.459, 0.520, 0.953>
        turbulence 0.500
        scale <0.2500, 0.2500, 0.2500>
      }
    }
    // the wine stains
    texture {
      pigment {
        spotted
        color_map {
          [ 0.000  color rgb<0.483, 0.165, 0.165> ]
          [ 0.329  color rgbf<1.000, 1.000, 1.000, 1.000> ]
          [ 0.734  color rgbf<1.000, 1.000, 1.000, 1.000> ]
          [ 1.000  color rgb<0.483, 0.165, 0.165> ]
        }
        turbulence 0.500
        frequency 1.500
      }
      normal {
        wrinkles 5.0000
      }
    }

  // wrinkled box

  box { <-1, -1, -1>, <1, 1, 1>
    texture {
      WRINKLED_TEXTURE
    }
    translate  <1.5, -1.2, 0>
  }


Well, this may not be the tablecloth we want at any picnic we're attending,
but if we compare the final box to the first, we see just how much depth,
dimension, and personality is possible just by the use of creative texturing.


One final note: the comments concerning the surface normal do not hold true
for finishes. If a lower layer contains a specular finish and an upper layer
does not, any place where the upper layer is transparent, the specular will
show through.

4.9.8            When All Else Fails: Material Maps

We have some pretty powerful texturing tools at our disposal, but what if we
want a more free form arrangement of complex textures? Well, just as image
maps do for pigments, and bump maps do for normals, whole textures can be
mapped using a material map, should the need arise.

Just as with image maps and bump maps, we need a source image in bitmapped
format which will be called by POV-Ray to serve as the map of where the
individual textures will go, but this time, we need to specify what texture
will be associated with which palette index. To make such an image, we can
use a paint program which allows us to select colors by their palette index
number (the actual color is irrelevant, since it is only a map to tell
POV-Ray what texture will go at that location). Now, if we have the complete
package that comes with POV-Ray, we have in our include files an image called
povmap.gif which is a bitmapped image that uses only the first four palette
indices to create a bordered square with the words Persistance of Vision in
it. This will do just fine as a sample map for the following example. Using
our same include files, the camera and light source, we enter the follow
object.

  plane { -z, 0
    texture {
      material_map {
        gif "povmap.gif"
        interpolate 2
        once
        texture { PinkAlabaster }          // the inner border
        texture { pigment { DMFDarkOak } } // outer border
        texture { Gold_Metal }             // lettering
        texture { Chrome_Metal }           // the window panel
      }
      translate <-0.5, -0.5, 0>
      scale 5
    }
  }


The position of the light source and the lack of foreground objects to be
reflected do not show these textures off to their best advantage. But at
least we can see how the process works. The textures have simply been placed
according to the location of pixels of a particular palette index. By using
the once keyword (to keep it from tiling), and translating and scaling our
map to match the camera we have been using, we get to see the whole thing
laid out for us.

Of course, that is just with palette mapped image formats, such as GIF and
certain flavors of PNG. Material maps can also use non-paletted formats, such
as the TGA files that POV-Ray itself outputs. That leads to an interesting
consquence: We can use POV-Ray to produce source maps for POV-Ray! Before we
wrap up with some of the limitations of special textures, let's do one more
thing with material maps, to show how POV-Ray can make its own source maps.

To begin with, if using an non-paletted image, POV-Ray looks at the 8 bit red
component of the pixel's color (which will be a value from 0 to 255) to
determine which texture from the list to use. So to create a source map, we
need to control very precisely what the red value of a given pixel will be.
We can do this by

  1.)Using an rgb statement to choose our color such as rgb <x/255, 0, 0>,
  2.)Use no light sources and apply a finish of finish { ambient 1 } to all
     objects, to ensure that highlighting and shadowing will not interfere.


Confused? Alright, here is an example, which will generate a map very much
like povmap.gif which we used earlier, except in TGA file format. We notice
that we have given the pigments blue and green components too. POV-Ray will
ignore that in our final map, so this is really for us humans, whose unaided
eyes cannot tell the difference between red variances of 0 to 4/255ths.
Without those blue and green variances, our map would look to our eyes like a
solid black screen. That may be a great way to send secret messages using
POV-Ray (plug it into a material map to decode) but it is no use if we want
to see what our source map looks like to make sure we have what we expected
to.

We render the following code, and name the resulting file povmap.tga.

  camera {
    orthographic
    up <0, 5, 0>
    right <5, 0, 0>
    location <0, 0, -25>
    look_at <0, 0, 0>
  }

  plane { -z, 0
    pigment { rgb <1/255, 0, 0.5> }
    finish { ambient 1 }
  }

  box { <-2.3, -1.8, -0.2>, <2.3, 1.8, -0.2>
    pigment { rgb <0/255, 0, 1> }
    finish { ambient 1 }
  }

  box { <-1.95, -1.3, -0.4>, <1.95, 1.3, -0.3>
    pigment { rgb <2/255, 0.5, 0.5> }
    finish { ambient 1 }
  }

  text { ttf "crystal.ttf", "The vision", 0.1, 0
    scale <0.7, 1, 1>
    translate <-1.8, 0.25, -0.5>
    pigment { rgb <3/255, 1, 1> }
    finish { ambient 1 }
  }

  text { ttf "crystal.ttf", "Persists!", 0.1, 0
    scale <0.7, 1, 1>
    translate <-1.5, -1, -0.5>
    pigment { rgb <3/255, 1, 1> }
    finish { ambient 1 }
  }


All we have to do is modify our last material map example by changing the
material map from GIF to TGA and modifying the filename. When we render using
the new map, the result is extremely similar to the pallette mapped GIF we
used before, except that we didn't have to use an external paint program to
generate our source: POV-Ray did it all!

4.9.9            Limitations Of Special Textures

There are a couple limitations to all of the special textures we have seen
(from textures, pigment and normal maps through material maps). First, if we
have used the default directive to set the default texture for all items in
our scene, it will not accept any of the special textures discussed here.
This is really quite minor, since we can always declare such a texture and
apply it individually to all objects. It doesn't actually prevent us from
doing anything we couldn't otherwise do.

The other is more limiting, but as we will shortly see, can be worked around
quite easily. If we have worked with layered textures, we have already seen
how we can pile multiple texture patterns on top of one another (as long as
one texture has transparency in it). This very useful technique has a problem
incorporating the special textures we have just seen as a layer. But there is
an answer!

For example, say we have a layered texture called Speckled_Metal, which
produces a silver metallic surface, and then puts tiny specks of rust all
over it. Then we decide, for a really rusty look, we want to create patches
of concentrated rust, randomly over the surface. The obvious approach is to
create a special texture pattern, with transparency to use as the top layer.
But of course, as we have seen, we wouldn't be able to use that texture
pattern as a layer. We would just generate an error message. The solution is
to turn the problem inside out, and make our layered texture part of the
texture pattern instead, like this

  // This part declares a pigment for use
  // in the rust patch texture pattern
  #declare Rusty = pigment {
    granite
    color_map {
      [ 0 rgb <0.2, 0, 0> ]
      [ 1 Brown ]
    }
    frequency 20
  }

  // And this part applies it
  // Notice that our original layered texture
  // "Speckled_Metal" is now part of the map
  #declare Rust_Patches = texture {
    bozo
    texture_map {
      [ 0.0  pigment {Rusty} ]
      [ 0.75 Speckled_Metal ]
      [ 1.0  Speckled_Metal ]
    }
  }


And the ultimate effect is the same as if we had layered the rust patches on
to the speckled metal anyway.

With the full array of patterns, pigments, normals, finishes, layered and
special textures, there is now practically nothing we cannot create in the
way of amazing textures. An almost infinite number of new possibilities are
just waiting to be created!

4.10             Using Atmospheric Effects

POV-Ray offers a variety of atmospheric effects, i. e. features that affect
the background of the scene or the air by which everything is surrounded.

It is easy to assign a simple color or a complex color pattern to a virtual
sky sphere. You can create anything from a cloud free, blue summer sky to a
stormy, heavy clouded sky. Even starfields can easily be created.

You can use different kinds of fog to create foggy scenes. Multiple fog
layers of different colors can add an eerie touch to your scene.

A much more realistic effect can be created by using an atmosphere, a
constant fog that interacts with the light coming from light sources. Beams
of light become visible and objects will cast shadows into the fog.


4.10.1           The Background

The background feature is used to assign a color to all rays that don't hit
any object. This is done in the following way.

  camera {
    location <0, 0, -10>
    look_at <0, 0, 0>
  }

  background { color rgb <0.2, 0.2, 0.3> }

  sphere { 0, 1
    pigment { color rgb <0.8, 0.5, 0.2> }
  }


The background color will be visible if a sky sphere is used and if some
translucency remains after all sky sphere pigment layers are processed.

4.10.2           The Sky Sphere

The sky sphere can be used to easily create a cloud covered sky, a nightly
star sky or whatever sky you have in mind.

In the following examples we'll start with a very simple sky sphere that will
get more and more complex as we add new features to it.

4.10.2.1         Creating a Sky with a Color Gradient

Beside the single color sky sphere that is covered with the background
feature the simplest sky sphere is a color gradient.

You may have noticed that the color of the sky varies with the angle to the
earth's surface normal. If you look straight up the sky normally has a much
deeper blue than it has at the horizon.

We want to model this effect using the sky sphere as shown in the scene below
(skysph1.pov).

  #include "colors.inc"

  camera {
    location <0, 1, -4>
    look_at <0, 2, 0>
    angle 80
  }

  light_source { <10, 10, -10> White }

  sphere { 2*y, 1
    pigment { color rgb <1, 1, 1> }
    finish { ambient 0.2 diffuse 0 reflection 0.6 }
  }

  sky_sphere {
    pigment {
      gradient y
      color_map {
        [0 color Red]
        [1 color Blue]
      }
      scale 2
      translate -1
    }
  }


The interesting part is the sky sphere statement. It contains a pigment that
describe the look of the sky sphere. We want to create a color gradient along
the viewing angle measured against the earth's surface normal. Since the ray
direction vector is used to calculate the pigment colors we have to use the
y-gradient.

The scale and translate transformation are used to map the points derived
from the direction vector to the right range. Without those transformations
the pattern would be repeated twice on the sky sphere. The scale statement is
used to avoid the repetition and the translate -1 statement moves the color
at index zero to the bottom of the sky sphere (that's the point of the sky
sphere you'll see if you look straight down).

After this transformation the color entry at position 0 will be at the bottom
of the sky sphere, i. e. below us, and the color at position 1 will be at the
top, i. e. above us.

The colors for all other positions are interpolated between those two colors
as you can see in the resulting image.

A simple gradient sky sphere.

If you want to start one of the colors at a specific angle you'll first have
to convert the angle to a color map index. This is done by using the formula

  color_map_index = (1 - cos(angle)) / 2


where the angle is measured against the negated earth's surface normal. This
is the surface normal pointing towards the center of the earth. An angle of 0
degrees describes the point below us while an angle of 180 degrees represents
the zenith.

In POV-Ray you first have to convert the degree value to radian values as it
is shown in the following example.

  sky_sphere {
    pigment {
      gradient y
      color_map {
        [(1-cos(radians( 30)))/2 color Red]
        [(1-cos(radians(120)))/2 color Blue]
      }
      scale 2
      translate -1
    }
  }


This scene uses a color gradient that starts with a red color at 30 degrees
and blends into the blue color at 120 degrees. Below 30 degrees everything is
red while above 120 degrees all is blue.

4.10.2.2         Adding the Sun

In the following example we will create a sky with a red sun surrounded by a
red color halo that blends into the dark blue night sky. We'll do this using
only the sky sphere feature.

The sky sphere we use is shown below. A ground plane is also added for
greater realism (skysph2.pov).

  sky_sphere {
    pigment {
      gradient y
      color_map {
        [0.000 0.002 color rgb <1.0, 0.2, 0.0>
                     color rgb <1.0, 0.2, 0.0>]
        [0.002 0.200 color rgb <0.8, 0.1, 0.0>
                     color rgb <0.2, 0.2, 0.3>]
      }
      scale 2
      translate -1
    }
    rotate -135*x
  }

  plane { y, 0
    pigment { color Green }
    finish { ambient .3 diffuse .7 }
  }


The gradient pattern and the transformation inside the pigment are the same
as in the example in the previous section.

The color map consists of three colors. A bright, slightly yellowish red that
is used for the sun, a darker red for the halo and a dark blue for the night
sky. The sun's color covers only a very small portion of the sky sphere
because we don't want the sun to become too big. The color is used at the
color map values 0.000 and 0.002 to get a sharp contrast at value 0.002 (we
don't want the sun to blend into the sky). The darker red color used for the
halo blends into the dark blue sky color from value 0.002 to 0.200. All
values above 0.200 will reveal the dark blue sky.

The rotate -135*x statement is used to rotate the sun and the complete sky
sphere to its final position. Without this rotation the sun would be at 0
degrees, i.e. right below us.

A red sun descends into the night.

Looking at the resulting image you'll see what impressive effects you can
achieve with the sky sphere.

4.10.2.3         Adding Some Clouds

To further improve our image we want to add some clouds by adding a second
pigment. This new pigment uses the bozo pattern to create some nice clouds.
Since it lays on top of the other pigment it needs some translucent colors in
the color map (look at entries 0.5 to 1.0).

  sky_sphere {
    pigment {
      gradient y
      color_map {
        [0.000 0.002 color rgb <1.0, 0.2, 0.0>
                     color rgb <1.0, 0.2, 0.0>]
        [0.002 0.200 color rgb <0.8, 0.1, 0.0>
                     color rgb <0.2, 0.2, 0.3>]
      }
      scale 2
      translate -1
    }
    pigment {
      bozo
      turbulence 0.65
      octaves 6
      omega 0.7
      lambda 2
      color_map {
          [0.0 0.1 color rgb <0.85, 0.85, 0.85>
                   color rgb <0.75, 0.75, 0.75>]
          [0.1 0.5 color rgb <0.75, 0.75, 0.75>
                   color rgbt <1, 1, 1, 1>]
          [0.5 1.0 color rgbt <1, 1, 1, 1>
                   color rgbt <1, 1, 1, 1>]
      }
      scale <0.2, 0.5, 0.2>
    }
    rotate -135*x
  }


A cloudy sky with a setting sun.

The sky sphere has one drawback as you might notice when looking at the final
image (skysph3.pov). The sun doesn't emit any light and the clouds will not
cast any shadows. If you want to have clouds that cast shadows you'll have to
use a real, large sphere with an appropriate texture and a light source
somewhere outside the sphere.

4.10.3           The Fog

You can use the fog feature to add fog of two different types to your scene:
constant fog and ground fog. The constant fog has a constant density
everywhere while the ground fog's density decreases as you move upwards.


4.10.3.1         A Constant Fog

The simplest fog type is the constant fog that has a constant density in all
locations. It is specified by a distance keyword which actually describes the
fog's density and a fog color.

The distance value determines the distance at which 36.8% of the background
are still visible (for a more detailed explanation of how the fog is
calculated read the reference section "Fog").

The fog color can be used to create anything from a pure white to a red,
blood-colored fog. You can also use a black fog to simulate the effect of a
limited range of vision.

The following example will show you how to add fog to a simple scene
(fog1.pov).

  #include "colors.inc"

  camera {
    location  <0, 20, -100>
  }

  background { colour SkyBlue }

  plane { y, -10
    pigment {
      checker colour Yellow colour Green
      scale 20
    }
  }

  sphere { <0, 25, 0>, 40
    pigment { Red }
    finish { phong 1.0 phong_size 20 }
  }

  sphere { <-100, 150, 200>,  20
    pigment { Green }
    finish { phong 1.0 phong_size 20 }
  }

  sphere { <100, 25, 100>, 30
    pigment { Blue }
    finish { phong 1.0 phong_size 20 }
  }

  light_source { <100, 120, 40> colour White}

  fog {
    distance 150
    colour rgb<0.3, 0.5, 0.2>
  }


A foggy scene.

According to their distance the spheres in this scene more or less vanish in
the greenish fog we used, as does the checkerboard plane.

4.10.3.2         Setting a Minimum Translucency

If you want to make sure that the background does not completely vanish in
the fog you can set the transmittance channel of the fog's color to the
amount of background you always want to be visible.

Using as transmittance value of 0.2 as in

  fog {
    distance 150
    colour rgbt<0.3, 0.5, 0.2, 0.2>
  }


the fog's translucency never drops below 20% as you can see in the resulting
image (fog2.pov).

Adding a translucency threshold you make sure that the background does not
vanish.

4.10.3.3         Creating a Filtering Fog

The greenish fog we have used so far doesn't filter the light passing through
it. All it does is to diminish the light's intensity. We can change this by
using a non-zero filter channel in the fog's color (fog3.pov).

  fog {
    distance 150
    colour rgbf<0.3, 0.5, 0.2, 1.0>
  }


The filter value determines the amount of light that is filtered by the fog.
In our example 100% of the light passing through the fog will be filtered by
the fog. If we had used a value of 0.7 only 70% of the light would have been
filtered. The remaining 30% would have passed unfiltered.

A filtering fog.

You'll notice that the intensity of the objects in the fog is not only
diminished due to the fog's color but that the colors are actually influenced
by the fog. The red and especially the blue sphere got a green hue.

4.10.3.4         Adding Some Turbulence to the Fog

In order to make our somewhat boring fog a little bit more interesting we can
add some turbulence, making it look like it had a non-constant density
(fog4.pov).

  fog {
    distance 150
    colour rgbf<0.3, 0.5, 0.2, 1.0>
    turbulence 0.2
    turb_depth 0.3
  }


Adding some turbulence makes the fog more interesting.

The turbulence keyword is used to specify the amount of turbulence used while
the turb_depth value is used to move the point at which the turbulence value
is calculated along the viewing ray. Values near zero move the point to the
viewer while values near one move it to the intersection point (the default
value is 0.5). This parameter can be used to avoid noise that may appear in
the fog due to the turbulence (this normally happens at very far away
intersection points, especially if no intersection occurs, i. e. the
background is hit). If this happens just lower the turb_depth value until the
noise vanishes.

You should keep in mind that the actual density of the fog does not change.
Only the distance-based attenuation value of the fog is modified by the
turbulence value at a point along the viewing ray.

4.10.3.5         Using Ground Fog

The much more interesting and flexible fog type is the ground fog, which is
selected with the fog_type statement. It's appearance is described with the
fog_offset and fog_alt keywords. The fog_offset specifies the height, i. e. y
value, below which the fog has a constant density of one. The fog_alt keyword
determines how fast the density of the fog will approach zero as one moves
along the y axis. At a height of fog_offset+fog_alt the fog will have a
density of 25%.

The following example (fog5.pov) uses a ground fog which has a constant
density below y=25 (the center of the red sphere) and quickly falls off for
increasing altitudes.

  fog {
    distance 150
    colour rgbf<0.3, 0.5, 0.2, 1.0>
    fog_type 2
    fog_offset 25
    fog_alt 1
  }


4.10.3.6         Using Multiple Layers of Fog

It is possible to use several layers of fog by using more than one fog
statement in your scene file. This is quite useful if you want to get nice
effects using turbulent ground fogs. You could add up several, differently
colored fogs to create an eerie scene for example.

Just try the following example (fog6.pov).

  fog {
    distance 150
    colour rgb<0.3, 0.5, 0.2>
    fog_type 2
    fog_offset 25
    fog_alt 1
    turbulence 0.1
    turb_depth 0.2
  }

  fog {
    distance 150
    colour rgb<0.5, 0.1, 0.1>
    fog_type 2
    fog_offset 15
    fog_alt 4
    turbulence 0.2
    turb_depth 0.2
  }

  fog {
    distance 150
    colour rgb<0.1, 0.1, 0.6>
    fog_type 2
    fog_offset 10
    fog_alt 2
  }


Quite nice results can be achieved using multiple layers of fog.

You can combine constant density fogs, ground fogs, filtering fogs,
non-filtering fogs, fogs with a translucency threshold, etc.

4.10.3.7         Fog and Hollow Objects

Whenever you use the fog feature and the camera is inside a non-hollow object
you won't get any fog effects. For a detailed explanation why this happens
see "Empty and Solid Objects".

In order to avoid this problem you have to make all those objects hollow by
either making sure the camera is outside these objects (using the inverse
keyword) or by adding the hollow to them (which is much easier).

4.10.4           The Atmosphere

Important notice: The atmosphere feature in POV-Ray 3.0 are somewhat
experimental. There is a high probability that the design and implementation
of these features will be changed in future versions. We cannot guarantee
that scenes using these features in 3.0 will render identically in future
releases or that full backwards compatibility of language syntax can be
maintained.

The atmosphere feature can be used to model the interaction of light with
particles in the air. Beams of light will become visible and objects will
cast shadows into the fog or dust that's filling the air.

The atmosphere model used in POV-Ray assumes a constant particle density
everywhere except solid objects. If you want to create cloud like fogs or
smoke you'll have to use the halo texturing feature described in section
"Halos".

4.10.4.1         Starting With an Empty Room

We want to create a simple scene to explain how the atmosphere feature works
and how you'll get good results.

Imagine a simple room with a window. Light falls through the window and is
scattered by the dust particles in the air. You'll see beams of light coming
from the window and shining on the floor.

We want to model this scene step by step. The following examples start with
the room, the window and a spotlight somewhere outside the room. Currently
there's no atmosphere to be able to verify if the lighting is correct
(atmos1.pov).

  camera {
    location <-10, 8, -19>
    look_at <0, 5, 0>
    angle 75
  }

  background { color rgb <0.2, 0.4, 0.8> }

  light_source { <0, 19, 0> color rgb 0.5 atmosphere off }

  light_source {
    <40, 25, 0> color rgb <1, 1, 1>
    spotlight
    point_at <0, 5, 0>
    radius 20
    falloff 20
    atmospheric_attenuation on
  }

  union {
    difference {
      box { <-21, -1, -21>, <21, 21, 21> }
      box { <-20, 0, -20>, <20, 20, 20> }
      box { <19.9, 5, -3>, <21.1, 15, 3> }
    }
    box { <20, 5, -0.25>, <21, 15, 0.25> }
    box { <20, 9.775, -3>, <21, 10.25, 3> }
    pigment { color red 1 green 1 blue 1 }
    finish { ambient 0.2 diffuse 0.5 }
  }


The empty room we want to start with.

The point light source is used to illuminate the room from inside without any
interaction with the atmosphere. This is done by adding atmosphere off . We
don't have to care about this light when we add the atmosphere later.

The spotlight is used with the atmospheric_attenuation keyword. This means
that light coming from the spotlight will be diminished by the atmosphere.

The union object is used to model the room and the window. Since we use the
difference between two boxes to model the room (the first two boxes in the
difference statement) there is no need for setting the union hollow. If we
are inside this room we actually will be outside the object (see also "Using
Hollow Objects and Atmosphere").

4.10.4.2         Adding Dust to the Room

The next step is to add an atmosphere to the room. This is done by the
following few lines (atmos2.pov).

  atmosphere {
    type 1
    samples 10
    distance 40
    scattering 0.2
  }


The type keyword selects the type of atmospheric scattering we want to use.
In this case we use the isotropic scattering that equally scatters light in
all directions (see "Atmosphere" for more details about the different
scattering types).

The samples keyword determines the number of samples used in accumulating the
atmospheric effect. For every ray samples are taken along the ray to
determine whether a sample is lit by a light source or not. If the sample is
lit the amount of light scattered into the direction of the viewer is
determined and added to the total intensity.

You can always start with an arbitrary number of samples. If the results do
not fit your ideas you can increase the sampling rate to get better results.
The problem of choosing a good sampling rate is the trade-off between a
satisfying image and a fast rendering. A high sampling rate will almost
always work but the rendering will also take a very long time. That's
something to experiment with.

The distance keyword specifies the density of the atmosphere. It works in the
same way as the distance parameter of the fog feature.

Last but not least will the scattering value determine the amount of light
that is scattered by the particles (the remaining light is absorbed). As
you'll later see this parameter is very useful in adjusting the overall
brightness of the atmosphere.

After adding some dust beams of light become visible.

Looking at the image created from the above scene you'll notice some very
ugly anti-aliasing artifacts known as mach-bands. They are the result of a
low sampling rate.


4.10.4.3         Choosing a Good Sampling Rate

As you've seen a too low sampling rate can cause some ugly results. There are
some ways of reducing or even avoiding those problems.

The brute force approach is to increase the sampling rate until the artifacts
vanish and you get a satisfying image. Though this will always work it is a
bad idea because it is very time consuming. A better approach is to use
jittering and anti-aliasing first. If both features don't help you'll have to
increase the sampling rate.

Jittering moves each sample point by a small, random amount along the
sampling direction. This helps to reduce regular features resulting from
aliasing. There is (hardly) nothing more annoying to the human visual system
than the regular features resulting from a low sampling rate. It's much
better to add some extra noise to the image by jittering the sample
positions. The human eye is much more forgiving to that.

Use the jitter keyword followed by the amount of jittering you want to use.
Good jittering values are up to 0.5, higher values result in too much noise.

You should be aware that jittering can not fix the artifacts introduced by a
too low sampling rate. It can only make them less visible.

An additional and better way of reducing aliasing artifacts is to use
(adaptive) super-sampling. This method casts additional samples where it is
likely that they are needed. If the intensity between two adjacent samples
differs too much additional samples are taken in-between. This step is done
recursively until a specified recursion level is reached or the sample get
close to each other.

The aa_level and aa_threshold keywords give full control over the
super-sampling process. The aa_level keyword determines the maximum recursion
level while aa_threshold specifies the maximum allowed difference between two
sample before the super-sampling is done.

After all this theory we get back to our sample scene and add the appropriate
keywords to use both jittering and super-sampling (atmos3.pov).

  atmosphere {
    type 1
    samples 50
    distance 40
    scattering 0.2
    aa_level 4
    aa_threshold 0.1
    jitter 0.2
  }


A very low threshold value was chosen to super-sample even between adjacent
points with a very similar intensity. The maximum recursion level of 4 will
lead to a maximum of fifteen super-samples.

If you are looking at the results that you get after adding jittering and
super-sampling you won't be satisfied. The only way of reducing the still
visible artifacts is to increase the sampling rate by choosing a higher
number of samples.

A high sampling rate leads to a satisfying image.

Doing this you'll get a good result showing (almost) no artifacts. BTW, the
amount of dust floating around in this room may be a little bit exaggerated
but it's just an example. And examples tend to be exaggerated.

4.10.4.4         Using a Coloured Atmosphere

You can assign a color to the atmosphere that gives you more control over the
atmosphere's appearance. First of all the color is used to filter all light
passing through it, whether it comes from light sources, reflected and
refracted rays, or the background. The amount by which the passing light is
filtered by the atmosphere's color is determined by the color's filter value.
A value of 0 means that the light is not influenced by the atmosphere's color
while a value of 1 means that all light will be filtered by the color.

If you want to create a reddish atmosphere for example, you can add the
following line to the atmosphere statement used in the above example.

  color rgbf <1, 0, 0, 0.25>


Just using rgb <1,0,0> does not work because the color's filter value will be
zero and thus no light will be filtered by the color, i. e. no light will be
multiplied with the color's RGB components.

The filter value of 0.25 means that 25% of the light passing through the
atmosphere will be filtered by the red color and 75% will pass unfiltered.

The transmittance channel of the atmosphere's color is used to specify a
minimum translucency. By default the transmittance channel is zero and thus
there is no such minimum translucency. Using a positive value lets you
determine the amount of background light that will always pass through the
atmosphere, regardless of its thickness set by the distance keyword.

If you use e.g. a color of rgbt <0,0,0,0.3> with our room example you can
make the blue background become visible. Until now it was hidden by the
atmosphere.

4.10.4.5         Atmosphere Tips

It is very difficult to get satisfying results when using the atmosphere
feature. Some of the more common problems will be discussed in the next
sections to help you to solve them (see also the FAQ section about the
atmosphere in "Atmosphere Questions").

4.10.4.5.1       Choosing the Distance and Scattering Parameters

The first difficult step is to choose a good distance and scattering value.
You need to be able to control the visibility of the objects in the scene and
the atmospheric effects.

The best approach is to choose the distance value first. This value
determines the visibility of the objects in the scene regardless of
atmospheric light scattering. It works in the same way as the distance value
of the fog feature.

Since fog is very similar to the unlit atmosphere you can use a fog instead
of an atmosphere to quickly choose a working distance value. If you do this
with room scene we used earlier you would use the following fog statement
instead of the atmosphere (atmos4.pov).

  fog {
    distance 40
    color rgb <0, 0, 0>
  }


A black fog can be used to get a working distance value for the atmosphere.

The black color is used to simulate the attenuation you'll get in those parts
of the atmosphere scene lying in shadow.

If you want to use a colored atmosphere you'll have to use the same color for
the fog as you want to use for the atmosphere, including the filter and
transmittance channel values (see "Using a Coloured Atmosphere" and
"Atmosphere" for an explanation of the atmosphere's color).

If you (roughly) want to simulate the appearance of those parts lit by a
light source you can use the color of the atmosphere inside the fog statement
instead.

After you are satisfied with the distance value you'll have to choose a
scattering value. This value lets you fit the atmosphere's intensity to your
needs. Starting with a value of one you have to increase the value if the
atmosphere effects are hardly visible. If you don't see anything in the lit
parts of the atmosphere you'll have to decrease the value.

You should be aware that you may have to use very small or very large values
to get the desired results.

4.10.4.5.2       Atmosphere and Light Sources

The best results are generated with spotlights and cylindrical light sources.
They create nice beams of light and are fast to render because the
atmospheric sampling takes only place inside the light cone of the spotlight
or light cylinder of the cylindrical light.

If you want to add a light source that does not interact with the atmosphere
you can use the atmosphere keyword inside the light source statement (see
"Atmosphere Interaction"). Just add atmosphere off.

By default the light coming from any light source will not be diminished by
the atmosphere. Thus the highlights in your scene will normally be too
bright. This can be changed with atmospheric_attenuation on.

4.10.4.5.3       Atmosphere Scattering Types

The different scattering types listed in "Atmosphere" can be used to model
different types of particles. This is something for you to experiment with.

The Rayleigh scattering is used for small particles like dust and smoke while
the Mie scattering is used for fog.

If you ever saw the lighthouse scene in the movie Casper you'll know what
effect the scattering type has. In this scene the beam of light coming from
the lighthouse becomes visible while it points nearly towards the viewer. As
it starts to point away from the viewer it vanishes. This behaviour is
typical for minuscule water droplets as modeled by the Mie scattering.

4.10.4.5.4       Increasing the Image Resolution

You have to be aware that you may have to increase the atmosphere sampling
rate if you increase the resolution of the image. Otherwise some aliasing
artifacts that were no visible at the lower resolution may become visible.

4.10.4.5.5       Using Hollow Objects and Atmosphere

Whenever you use the atmosphere feature you have to make sure that all
objects that ought to be filled with atmosphere are set to hollow using the
hollow keyword.

Even though this is not obvious this holds for infinite and patch objects
like quadrics, quartics, triangles, polygons, etc. Whenever you add one of
those objects you should add the hollow keyword as long as you are not
absolutely sure you don't need it. You also have to make sure that all
objects the camera is inside are set to be hollow.

Whenever you get unexpected results you should check for solid objects and
set them to be hollow.

4.10.5           The Rainbow

The rainbow feature can be used to create rainbows and maybe other more
strange effects. The rainbow is a fog like effect that is restricted to a
cone-like volume.

4.10.5.1         Starting With a Simple Rainbow

The rainbow is specified with a lot of parameters: the angle under which it
is visible, the width of the color band, the direction of the incoming light,
the fog-like distance based particle density and last not least the color map
to be used.

The size and shape of the rainbow are determined by the angle and width
keywords. The direction keyword is used to set the direction of the incoming
light, thus setting the rainbow's position. The rainbow is visible when the
angle between the direction vector and the incident light direction is larger
than angle-width/2 and smaller than angle+width/2.

The incoming light is the virtual light source that is responsible for the
rainbow. There needn't be a real light source to create the rainbow effect.

The rainbow is a fog-like effect, i.e. the rainbow's color is mixed with the
background color based on the distance to the intersection point. If you
choose small distance values the rainbow will be visible on objects, not just
in the background. You can avoid this by using a very large distance value.

The color map is the crucial part of the rainbow since it contains all the
colors that normally can be seen in a rainbow. The color of the innermost
color band is taken from the color map entry 0 while the outermost band is
take from entry 1. You should note that due to the limited color range any
monitor can display it is impossible to create a real rainbow. There are just
some colors that you cannot display.

The filter channel of the rainbow's color map is used in the same way as with
fogs. It determines how much of the light passing through the rainbow is
filtered by the color.

The following example shows a simple scene with a ground plane, three spheres
and a somewhat exaggerated rainbow (rainbow1.pov).

  #include "colors.inc"

  camera {
    location <0, 20, -100>
    look_at <0, 25, 0>
    angle 80
  }

  background { color SkyBlue }

  plane { y, -10 pigment { colour Green } }

  light_source {<100, 120, 40> colour White}

  // declare rainbow's colours

  #declare r_violet1 = colour rgbf<1.0, 0.5, 1.0, 1.0>
  #declare r_violet2 = colour rgbf<1.0, 0.5, 1.0, 0.8>
  #declare r_indigo  = colour rgbf<0.5, 0.5, 1.0, 0.8>
  #declare r_blue    = colour rgbf<0.2, 0.2, 1.0, 0.8>
  #declare r_cyan    = colour rgbf<0.2, 1.0, 1.0, 0.8>
  #declare r_green   = colour rgbf<0.2, 1.0, 0.2, 0.8>
  #declare r_yellow  = colour rgbf<1.0, 1.0, 0.2, 0.8>
  #declare r_orange  = colour rgbf<1.0, 0.5, 0.2, 0.8>
  #declare r_red1    = colour rgbf<1.0, 0.2, 0.2, 0.8>
  #declare r_red2    = colour rgbf<1.0, 0.2, 0.2, 1.0>

  // create the rainbow

  rainbow {
    angle 42.5
    width 5
    distance 1.0e7
    direction <-0.2, -0.2, 1>
    jitter 0.01
    colour_map {
      [0.000  colour r_violet1]
      [0.100  colour r_violet2]
      [0.214  colour r_indigo]
      [0.328  colour r_blue]
      [0.442  colour r_cyan]
      [0.556  colour r_green]
      [0.670  colour r_yellow]
      [0.784  colour r_orange]
      [0.900  colour r_red1]
    }
  }


Some irregularity is added to the color bands using the jitter keyword.

A colorful rainbow.

The rainbow in our sample is much too bright. You'll never see a rainbow like
this in reality. You can decrease the rainbow's colors by decreasing the RGB
values in the color map.

4.10.5.2         Increasing the Rainbow's Translucency

The result we have so far looks much too bright. Just reducing the rainbow's
color helps but it's much better to increase the translucency of the rainbow
because it is more realistic if the background is visible through the
rainbow.

We can use the transmittance channel of the colors in the color map to
specify a minimum translucency, just like we did with the fog. To get
realistic results we have to use very large transmittance values as you can
see in the following example (rainbow2.pov).

  rainbow {
    angle 42.5
    width 5
    distance 1.0e7
    direction <-0.2, -0.2, 1>
    jitter 0.01
    colour_map {
      [0.000  colour r_violet1 transmit 0.98]
      [0.100  colour r_violet2 transmit 0.96]
      [0.214  colour r_indigo  transmit 0.94]
      [0.328  colour r_blue    transmit 0.92]
      [0.442  colour r_cyan    transmit 0.90]
      [0.556  colour r_green   transmit 0.92]
      [0.670  colour r_yellow  transmit 0.94]
      [0.784  colour r_orange  transmit 0.96]
      [0.900  colour r_red1    transmit 0.98]
    }
  }


The transmittance values increase at the outer bands of the rainbow to make
it softly blend into the background.

A much more realistic rainbow.


4.10.5.3         Using a Rainbow Arc

Currently our rainbow has a circular shape, even though most of it is hidden
below the ground plane. You can easily create a rainbow arc by using the
arc_angle keyword with an angle below 360 degrees.

If you use arc_angle 120 for example you'll get a rainbow arc that abruptly
vanishes at the arc's ends. This does not look good. To avoid this the
falloff_angle keyword can be used to specify a region where the arc smoothly
blends into the background.

As explained in the rainbow's reference section (see "Rainbow") the arc
extends from -arc_angle/2 to arc_angle/2 while the blending takes place from
-arc_angle/2 to -falloff_angle/2 and falloff_angle/2 to arc_angle/2. This is
the reason why the falloff_angle has to be smaller or equal to the arc_angle.


In the following examples we use an 120 degrees arc with a 45 degree falloff
region on both sides of the arc (rainbow3.pov).

  rainbow {
    angle 42.5
    width 5
    arc_angle 120
    falloff_angle 30
    distance 1.0e7
    direction <-0.2, -0.2, 1>
    jitter 0.01
    colour_map {
      [0.000  colour r_violet1 transmit 0.98]
      [0.100  colour r_violet2 transmit 0.96]
      [0.214  colour r_indigo  transmit 0.94]
      [0.328  colour r_blue    transmit 0.92]
      [0.442  colour r_cyan    transmit 0.90]
      [0.556  colour r_green   transmit 0.92]
      [0.670  colour r_yellow  transmit 0.94]
      [0.784  colour r_orange  transmit 0.96]
      [0.900  colour r_red1    transmit 0.98]
    }
  }


The arc angles are measured against the rainbows up direction which can be
specified using the up keyword. By default the up direction is the y-axis.

A rainbow arc.


4.10.6           Animation

There are a number of programs available that will take a series of still TGA
files (such as POV-Ray outputs) and assemble them into animations. Such
programs can produce AVI, MPEG, FLI/FLC, or even animated GIF files (for use
on the World Wide Web). The trick, therefore, is how to produce the frames.
That, of course, is where POV-Ray comes in. In earlier versions producing an
animation series was no joy, as everything had to be done manually. We had to
set the clock variable, and handle producing unique file names for each
individual frame by hand. We could achieve some degree of automation by using
batch files or similar scripting devices, but still, We had to set it all up
by hand, and that was a lot of work (not to mention frustration... imagine
forgetting to set the individual file names and coming back 24 hours later to
find each frame had overwritten the last).

Now, at last, with POV-Ray 3, there is a better way. We no longer need a
separate batch script or external sequencing programs, because a few simple
settings in our INI file (or on the command line) will activate an internal
animation sequence which will cause POV-Ray to automatically handle the
animation loop details for us.

Actually, there are two halves to animation support: those settings we put in
the INI file (or on the command line), and those code modifications we work
into our scene description file. If we've already worked with animation in
previous versions of POV-Ray, we can probably skip ahead to the section "INI
File Settings" below. Otherwise, let's start with basics. Before we get to
how to activate the internal animation loop, let's look at a couple examples
of how a couple of keywords can set up our code to describe the motions of
objects over time.

4.10.6.1         The Clock Variable: Key To It All

POV-Ray supports an automatically declared floating point variable identified
as clock (all lower case). This is the key to making image files that can be
automated. In command line operations, the clock variable is set using the +k
switch. For example, \Clo{+k3.4} from the command line would set the value of
clock to 3.4. The same could be accomplished from the INI file
using\IFKINDEX{Clock}

  Clock = 3.4


If we don't set clock for anything, and the animation loop is not used (as
will be described a little later) the clock variable is still there - it's
just set for the default value of 0.0, so it is possible to set up some POV
code for the purpose of animation, and still render it as a still picture
during the object/world creation stage of our project.

The simplest example of using this to our advantage would be having an object
which is travelling at a constant rate, say, along the x-axis. We would have
the statement

  translate <clock, 0, 0>


in our object's declaration, and then have the animation loop assign
progressively higher values to clock. And that's fine, as long as only one
element or aspect of our scene is changing, but what happens when we want to
control multiple changes in the same scene simulatneously?

The secret here is to use normalized clock values, and then make other
variables in your scene proportional to clock. That is, when we set up our
clock, (we're getting to that, patience!) have it run from 0.0 to 1.0, and
then use that as a multiplier to some other values. That way, the other
values can be whatever we need them to be, and clock can be the same 0 to 1
value for every application. Let's look at a (relatively) simple example

  #include "colors.inc"

  camera {
    location <0, 3, -6>
    look_at <0, 0, 0>
  }

  light_source { <20, 20, -20> color White }

  plane { y, 0
    pigment { checker color White color Black }
  }

  sphere { <0, 0, 0> , 1
    pigment {
      gradient x
      color_map {
        [0.0 Blue  ]
        [0.5 Blue  ]
        [0.5 White ]
        [1.0 White ]
      }
      scale .25
    }
    rotate <0, 0, -clock*360>
    translate <-pi, 1, 0>
    translate <2*pi*clock, 0, 0>
  }


Assuming that a series of frames is run with the clock progressively going
from 0.0 to 1.0, the above code will produce a striped ball which rolls from
left to right across the screen. We have two goals here:

  2.Rotate the ball in exactly the right proportion to its linear movement to
    imply that it is rolling -- not gliding -- to its final position.


Taking the second goal first, we start with the sphere at the origin, because
anywhere else and rotation will cause it to orbit the origin instead of
rotating. Throughout the course of the animation, the ball will turn one
complete 360 degree turn. Therefore, we used the formula, 360*clock to
determine the rotation in each frame. Since clock runs 0 to 1, the rotation
of the sphere runs from 0 degrees through 360.

Then we used the first translation to put the sphere at its initial starting
point. Remember, we couldn't have just declared it there, or it would have
orbited the origin, so before we can meet our other goal (translation), we
have to compensate by putting the sphere back where it would have been at the
start. After that, we re-translate the sphere by a clock relative distance,
causing it to move relative to the starting point. We've chosen the formula
of 2*pi* r*clock (the widest circumference of the sphere times current clock
value) so that it will appear to move a distance equal to the circumference
of the sphere in the same time that it rotates a complete 360 degrees. In
this way, we've synchronized the rotation of the sphere to its translation,
making it appear to be smoothly rolling along the plane.

Besides allowing us to coordinate multiple aspects of change over time more
cleanly, mathematically speaking, the other good reason for using normalized
clock values is that it will not matter whether we are doing a ten frame
animated GIF, or a three hundred frame AVI. Values of the clock are
proportioned to the number of frames, so that same POV code will work without
regard to how long the frame sequence is. Our rolling ball will still travel
the exact same amount no matter how many frames our animation ends up with.

4.10.6.2         Clock Dependant Variables And Multi-Stage Animations

Okay, what if we wanted the ball to roll left to right for the first half of
the animation, then change direction 135 degrees and roll right to left, and
toward the back of the scene. We would need to make use of POV's new
conditional rendering directives, and test the clock value to determine when
we reach the halfway point, then start rendering a different clock dependant
sequence. But our goal, as above, it to be working in each stage with a
variable in the range of 0 to 1 (normalized) because this makes the math so
much cleaner to work with when we have to control multiple aspects during
animation. So let's assume we keep the same camera, light, and plane, and let
the clock run from 0 to 2! Now, replace the single sphere declaration with
the following...

  #if ( clock <= 1 )
    sphere { <0, 0, 0> , 1
      pigment {
        gradient x
        color_map {
          [0.0 Blue  ]
          [0.5 Blue  ]
          [0.5 White ]
          [1.0 White ]
        }
        scale .25
      }
      rotate <0, 0, -clock*360>
      translate <-pi, 1, 0>
      translate <2*pi*clock, 0, 0>
    }
  #else
    // (if clock is > 1, we're on the second phase)

    // we still want to work with  a value from 0 - 1

    #declare ElseClock = clock - 1

    sphere { <0, 0, 0> , 1
      pigment {
        gradient x
        color_map {
          [0.0 Blue  ]
          [0.5 Blue  ]
          [0.5 White ]
          [1.0 White ]
        }
        scale .25
      }
      rotate <0, 0, ElseClock*360>
      translate <-2*pi*ElseClock, 0, 0>
      rotate <0, 45, 0>
      translate <pi, 1, 0>
    }
  #end


If we spotted the fact that this will cause the ball to do an unrealistic
snap turn when changing direction, bonus points for us - we're a born
animator. However, for the simplicity of the example, let's ignore that for
now. It will be easy enough to fix in the real world, once we examine how the
existing code works.

All we did differently was assume that the clock would run 0 to 2, and that
we wanted to be working with a normalized value instead. So when the clock
goes over 1.0, POV assumes the second phase of the journey has begun, and we
declare a new variable Elseclock which we make relative to the original built
in clock, in such a way that while clock is going 1 to 2, Elseclock is going
0 to 1. So, even though there is only one clock, there can be as many
additional variables as we care to declare (and have memory for), so even in
fairly complex scenes, the single clock variable can be made the common
coordinating factor which orchestrates all other motions.

4.10.6.3         The Phase Keyword

There is another keyword we should know for purposes of animations: the phase
keyword. The phase keyword can be used on many texture elements, especially
those that can take a color, pigment, normal or texture map. Remember the
form that these maps take. For example:

  color_map {
    [0.00 White ]
    [0.25 Blue ]
    [0.76 Green ]
    [1.00 Red ]
  }


The floating point value to the left inside each set of brackets helps
POV-Ray to map the color values to various areas of the object being
textured. Notice that the map runs cleanly from 0.0 to 1.0?

Phase causes the color values to become shifted along the map by a floating
point value which follows the keyword phase. Now, if we are using a
normalized clock value already anyhow, we can make the variable clock the
floating point value associated with phase, and the pattern will smoothly
shift over the course of the animation. Let's look at a common example using
a gradient normal pattern

  #include "colors.inc"
  #include "textures.inc"

  #background { rgb<0.8, 0.8, 0.8> }

  camera {
    location <1.5, 1, -30>
    look_at <0, 1, 0>
    angle 10
  }

  light_source { <-100, 20, -100> color White }

  // flag

  polygon { 5, <0, 0>, <0, 1>, <1, 1>, <1, 0>, <0, 0>
    pigment { Blue }
    normal {
      gradient x
      phase clock
      scale <0.2, 1, 1>
      sine_wave
    }
    scale <3, 2, 1>
    translate <-1.5, 0, 0>
  }

  // flagpole

  cylinder { <-1.5, -4, 0>, <-1.5, 2.25, 0>, 0.05
    texture { Silver_Metal }
  }

  // polecap

  sphere { <-1.5, 2.25, 0>, 0.1
    texture { Silver_Metal }
  }


Now, here we've created a simple blue flag with a gradient normal pattern on
it. We've forced the gradient to use a sine-wave type wave so that it looks
like the flag is rolling back and forth as though flapping in a breeze. But
the real magic here is that phase keyword. It's been set to take the clock
variable as a floating point value which, as the clock increments slowly
toward 1.0, will cause the crests and troughs of the flag's wave to shift
along the x-axis. Effectively, when we animate the frames created by this
code, it will look like the flag is actually rippling in the wind.

This is only one, simple example of how a clock dependant phase shift can
create interesting animation effects. Trying phase will all sorts of texture
patterns, and it is amazing the range of animation effects we can create
simply by phase alone, without ever actually moving the object.

4.10.6.4         Do Not Use Jitter Or Crand

One last piece of basic information to save frustration. Because jitter is an
element of anti-aliasing, we could just as easily have mentioned this under
the INI file settings section, but there are also forms of anti-aliasing used
in area lights, and the new atmospheric effects of POV-Ray, so now is as good
a time as any.

Jitter is a very small amount of random ray perturbation designed to diffuse
tiny aliasing errors that might not otherwise totally disappear, even with
intense anti-aliasing. By randomizing the placement of erroneous pixels, the
error becomes less noticable to the human eye, because the eye and mind are
naturally inclined to look for regular patterns rather than random
distortions.

This concept, which works fantasticly for still pictures, can become a
nightmare in animations. Because it is random in nature, it will be different
for each frame we render, and this becomes even more severe if we dither the
final results down to, say 256 color animations (such as FLC's). The result
is jumping pixels all over the scene, but especially concentrated any place
where aliasing would normally be a problem (e.g., where an infinite plane
disappears into the distance).

For this reason, we should always set jitter to off in area lights and
anti-aliasing options when preparing a scene for an animation. The
(relatively) small extra measure quality due to the use of jitter will be
offset by the ocean of jumpies that results. This general rule also applies
to any truly random texture elements, such as crand.

4.10.6.5         INI File Settings

Okay, so we have a grasp of how to code our file for animation. We know about
the clock variable, user declared clock-relative variables, and the phase
keyword. We know not to jitter or crand when we render a scene, and we're all
set build some animations. Alright, let's have at it.

The first concept we'll need to know is the INI file settings, Initial_Frame
and Final_Frame. These are very handy settings that will allow us to render a
particular number of frames and each with its own unique frame number, in a
completely hands free way. It is of course, so blindingly simple that it
barely needs explanation, but here's an example anyway. We just add the
following lines to our favorite INI file settings

  Initial_Frame = 1
  Final_Frame = 20


and we'll initiate an automated loop that will generate 20 unique frames. The
settings themselves will automatically append a frame number onto the end of
whatever we have set the output file name for, thus giving each frame an
unique file number without having to think about it. Secondly, by default, it
will cycle the clock variable up from 0 to 1 in increments proportional to
the number of frames. This is very convenient, since, no matter whether we
are making a five frame animated GIF or a 300 frame MPEG sequence, we will
have a clock value which smoothly cylces from exactly the same start to
exactly the same finish.

Next, about that clock. In our example with the rolling ball code, we saw
that sometimes we want the clock to cycle through values other than the
default of 0.0 to 1.0. Well, when that's the case, there are setting for that
too. The format is also quite simple. To make the clock run, as in our
example, from 0.0 to 2.0, we would just add to your INI file the lines

  Initial_Clock = 0.0
  Final_Clock = 2.0


Now, suppose we were developing a sequence of 100 frames, and we detected a
visual glitch somewhere in frames, say 51 to 75. We go back over our code and
we think we've fixed it. We'd like to render just those 25 frames instead of
redoing the whole sequence from the beginning. What do we change?

If we said make Initial_Frame = 51, and Final_Frame = 75, we're wrong. Even
though this would re-render files named with numbers 51 through 75, they will
not properly fit into our sequence, because the clock will begin at its
initial value starting with frame 51, and cycle to final value ending with
frame 75. The only time Initial_Frame and Final_Frame should change is if we
are doing an essentially new sequence that will be appended onto existing
material.

If we wanted to look at just 51 through 75 of the original animation, we need
two new INI settings

  Subset_Start_Frame = 51
  Subset_End_Frame = 75


Added to settings from before, the clock will still cycle through its values
proportioned from frames 1 to 100, but we will only be rendering that part of
the sequence from the 51st to the 75th frames.

This should give us a basic idea of how to use animation. Although, this
introductory tutorial doesn't cover all the angles. For example, the last two
settings we just saw, subset animation, can take fractional values, like 0.5
to 0.75, so that the number of actual frames will not change what portion of
the animation is being rendered. There is also support for efficient odd-even
field rendering as would be useful for animations prepared for display in
interlaced playback such as television (see the reference section for full
details).

With POV-Ray 3 now fully supporting a complete host of animation options, a
whole fourth dimension is added to the raytracing experience. Whether we are
making a FLIC, AVI, MPEG, or simply an animated GIF for our web site,
animation support takes a lot of the tedium out of the process. And don't
forget that phase and clock can be used to explore the range of numerous
texture elements, as well as some of the more difficult to master objects
(hint: the julia fractal for example). So even if we are completely content
with making still scenes, adding animation to our repetoire can greatly
enhance our understanding of what POV-Ray is capable of. Adventure awaits!
