This section describes how to create a scene using POV-Ray's scene 
description language and how to render this scene.

Let's create the scene file for a simple picture. Since ray tracers thrive 
on spheres, that's what we'll render first.

First, we have to tell POV-Ray where our camera is and where it's 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
    |-------->


The negative values of the axes point the other direction, as follows:


          ^+Y
          |   /+Z
          |  /
          | /
  -X      |/        +X
  <-------|-------->
         /|
        / |
       /  |
    -Z/   |
          v-Y

Using your personal favorite text editor, create a file called 
"picture1.pov". Now, type in the following (note: The input is case 
sensitive, so be sure to get capital and lowercase letters correct):

      #include "colors.inc"    // The include files contain
      #include "shapes.inc"    // pre-defined scene elements
      #include "textures.inc"

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

The first include statement reads in definitions for various useful colors. 
The second and third include statements read in some useful shapes and 
textures respectively. When you get a chance, have a look through them to 
see but a few of the many possible shapes and textures available.

You may have as many include files as needed in a scene file. Include files 
may themselves contain include files, but you are limited to declaring 
includes nested only 10 "deep".

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

The camera declaration describes where and how the camera sees the scene. 
It gives X, Y, Z coordinates to indicate the position of the camera and 
what part of the scene it is pointing at. You describe X, Y, Z coordinates 
using a 3-part "vector".  A vector is specified by putting 3 numeric values 
between a pair of angle brackets and separating the values with commas.

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>. Remember that 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 X, Y, Z 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 your image.

Now that the camera is set up to record the scene, let's place a red sphere 
into the scene.  Type the following into your scene file:

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

The first vector specifies 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 
1 unit up from the origin. The Z coordinate is 2 which is 5 units in front 
of the camera at Z=-3. After the center vector is a comma followed by the 
radius which in this case is 2 units. Since the radius is 1/2 the width of 
a sphere, the sphere is 4 units wide. 

Now that we've 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 the default values.

The color you define is the way you want it to look if fully illuminated.  
If you were painting a picture of a sphere you 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 for you.  You 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 IS 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.  The word "Yellow" is a 
color identifier which was previously defined in the standard include file 
"colors.inc".

If no standard color is available for your needs, you may define your 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 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>

Colors are explained in more detail later.

One more detail is needed for our scene.  We need a light source. Until you 
create one, there is no light in this virtual world.  Add the following 
text to your scene file:

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

The vector specifies the location of the light as 2 units to our right, 4 
units above the origin and 3 units back from the origin. The light_source 
is invisible, it only casts light, so no texture is needed.

That's it!  Close the file and render a small picture of it using this 
command:

      POVRAY +W160 +H120 +P +X +D0 -V -Ipicture1.pov

If your computer does not use the command line, see the executable docs for 
the correct command to render a scene.

You may set any other command line options you like, also. The scene is 
output to the image file DATA.TGA (or some suffix other than TGA if your 
computer uses a different file format). You can convert DATA.TGA to a GIF 
image using the commands listed in the docs included with your executable. 

You've now rendered your first picture but it is somewhat boring.  Let's 
add some fancy features to the texture.

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 you 
need a "finish" parameter. 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}
        }
      }

Now render this the same way you did before. 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. Phong can be 
between 0 and 1.

The highlight you've 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 you 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 a "surface normal" 
vector.  This is a vector which points away from the surface and is 
perpendicular to it.  By artificially modifying (or perturbing) this normal 
vector you can simulate bumps.  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. 

You can do more than assign a solid color to an object.  You can create 
complex patterns in the pigment block.  Consider 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 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 slightly 
stirs up the pattern so the veins aren't perfect circles and the scale 
factor adjusts the size of the pattern.

The most of the patterns are set up by default to give you 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 an the z direction is scaled by 1, which 
leaves it unchanged. Scale values larger than 1 will stretch an element. 
Scale values smaller than one will squish an element. And scale value 1 
will leave an element unchanged.

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

      sphere {
        <0, 1, 2>, 2
        texture {
          pigment {
            DMFWood4    // Pre-defined from textures.inc 
            scale 4     // Scale by the same amount in all
                        // directions
          }
          finish {Shiny}      // This finish defined in textures.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.

Look through the file TEXTURES.INC to see what pigments and finishes are 
defined and try them out. Just insert the name of the new pigment where 
DMFWood1 is now or try a different finish in place of Shiny and re-render 
your file. 

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

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

So far, we've just used the sphere shape. There are many other types of 
shapes that can be rendered by POV-Ray.  First let's make some room in the 
image by changing the sphere from a radius of 2 to a radius of 1 like this:

      sphere {
        <0, 1, 2>, 1 
        texture { ... and so on.

Let's try out a computer graphics standard - "The Checkered Floor."  Add 
the following object to your .pov file:

      plane {
        <0, 1, 0>, 0 
        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 you 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=0 so that the sphere at Y=1, radius= 1, is resting on 
it. 

Notice that there is no "texture{...}" statement.  There really is an 
implied texture there.  You might find that continually typing statements 
that are nested like "texture {pigment {...}}" can get to be a tiresome so 
POV-Ray lets you leave out the "texture{...}" under many circumstances.  In 
general you only need the texture block surrounding a texture identifier 
(like the PinkAlabaster 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 3 built-in vector identifiers "x", "y", and "z" respectively that 
can be used as shorthand.  Thus the plane could be defined as:

      plane { 
        y,0 
        pigment {... etc.

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

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

There are several other simple shapes available in POV-Ray.  The most 
common are the box, cylinder and cone.  Try these examples in place of the 
sphere:

      box {
        <-1,0  ,-1>,     // Near lower left corner
        < 1,0.5, 3>      // Far upper right corner
        pigment {
          DMFWood4      // Pre-defined from textures.inc 
          scale 4       // Scale by the same amount in all
                        // directions
        }
        rotate y*20     // Equivalent to "rotate <0,20,0>"
      }

In this example you can see that a box is defined by specifying the 3D 
coordinates of opposite corners.  The first vector must be the minimum 
x,y,z coordinates and the 2nd vector must be the maximum x,y,z values.  Box 
objects can only be defined parallel to the axes.  You can later rotate 
them to any angle.  Note that you 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>".  

Here's another example:

      cone {
        <0,1,0>,0.3    // Center and radius of one end
        <1,2,3>,1.0    // Center and radius of other end
        pigment {DMFWood4  scale 4 }
        finish {Shiny}  
      }

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 radius of 0.3 while the 
other end is centered at <1,2,3> with radius 1.  If you want the cone to 
come to a sharp point then use a 0 radius.  The solid end caps are parallel 
to each other and perpendicular to the cone axis.  If you want a hollow 
cone with no end caps then 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
        pigment {DMFWood4  scale 4 }
        finish {Shiny}  
      }

You 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
        pigment {DMFWood4  scale 4 }
        finish {Shiny}  
      }

Finally 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.  You 
can invoke them like this:

      object {
        UnitBox
        pigment {DMFWood4  scale 4 }
        finish {Shiny}  
        scale 0.75
        rotate <-20,25,0>
        translate y
      }

That's the end of our brief tutorial.  We've only scratched the surface.  
The rest of this document provides a reference to all of POV-Ray's 
features.