The Scene Description Language allows the user to describe the world in a 
readable and convenient way.  Files are created in plain ASCII text using 
an editor of your choice.  POV-Ray reads the file, processes it by creating 
an internal model of the scene and the renders the scene.

The POV-Ray language consists of identifiers, reserved keywords, floating 
point literals, string literals, special symbols and comments.  The text of 
a POV-Ray scene file is free format.  You may put statements on separate 
lines or on the same line as you desire.  You may add blank lines, spaces 
or indentations as long as you do not split any keywords or identifiers.

POV-Ray allows you to define identifiers for later use in the file.  An 
identifier may be 1 to 40 characters long.  It may consist of upper or 
lower case letters, the digits 0 through 9 or an underscore character.  The 
first character must be an alphabetic character.  The declaration of 
identifiers is covered later.

POV-Ray has a number of reserved words which are used in the language.  All 
reserved words are fully lower case.  Therefore it is recommended that your 
identifiers contain at least 1 upper case character so it is sure to avoid 
conflict with reserved words.

The following keywords are reserved in POV-Ray:

adaptive               height_field           rgbf                  
agate                  hexagon                right                 
agate_turb             iff                    ripples               
all                    image_map              rotate                
alpha                  include                roughness             
ambient                interpolate            scale                 
area_light             intersection           sky                   
background             inverse                smooth                
bicubic_patch          ior                    smooth_triangle       
blob                   jitter                 specular              
blue                   lambda                 sphere                
bounded_by             leopard                spotlight             
box                    light_source           spotted               
bozo                   location               sturm                 
brilliance             looks_like             texture               
bumps                  look_at                tga                   
bump_map               mandel                 threshold             
bump_size              map_type               tightness             
camera                 marble                 tile2                 
checker                material_map           tiles                 
clipped_by             max_intersections      torus                 
clock                  max_trace_level        translate             
color                  merge                  triangle              
color_map              metallic               turbulence            
colour                 normal                 type                  
colour_map             no_shadow              union                 
component              object                 up                    
composite              octaves                use_color             
cone                   omega                  use_colour            
crand                  once                   use_index             
cubic                  onion                  u_steps               
cylinder               open                   version               
declare                phase                  v_steps               
default                phong                  water_level           
dents                  phong_size             waves                 
difference             pigment                wood                  
diffuse                plane                  wrinkles              
direction              point_at               x                     
disc                   poly                   y                     
distance               pot                    z                     
dump                   quadric               
falloff                quartic               
filter                 quick_color           
finish                 quick_colour          
flatness               radial                
fog                    radius                
frequency              raw                   
gif                    red                   
gradient               reflection            
granite                refraction            
green                  rgb                   
                       

Comments are text in the scene file included to make the scene file easier 
to read or understand. They are ignored by the ray tracer and are there for 
humans to read.  There are two types of comments in POV-Ray.

Two slashes are used for single line comments.  Anything on a line after a 
double slash // is ignored by the ray tracer.  For example:

  // This line is ignored

You can have scene file information on the line in front of the comment, as 
in:

  object { FooBar }  // this is an object

The other type of comment is used for multiple lines.  This type of comment 
starts with /* and ends with */ everything in-between is ignored.  For 
example:

/* These lines
    Are ignored 
    By the
    Raytracer */

This can be useful if you want to temporarily remove elements from a scene 
file.   /*...*/ comments can "comment out" lines containing the other // 
comments, and thus can be used to temporarily or permanently comment out 
parts of a scene.  /*..*/ comments can be nested, the following is legal:

/* This is a comment
    // This too
    /* This also */
 */

Use comments liberally and generously. Well used, they really improve the 
readability of scene files.

The language allows include files to be specified by placing the line:

    #include "filename.inc"

at any point in the input file. The filename must be enclosed in double 
quotes and may be up to 40 characters long (or your computer's limit), 
including the two double-quote (") characters. 

The include file is read in as if it were inserted at that point in the 
file. Using include is the same as actually cutting and pasting the entire 
contents of this file into your scene. 

Include files may be nested. You may have at most 10 nested include files.  
There is no limit on un-nested include files.

Generally, include files have data for scenes, but are not scenes in 
themselves. By convention scene files end in .pov and include files end 
with .inc.

Many parts of the POV-Ray language require you to specify one or more 
floating point numbers.  A floating point number is a number with a decimal 
point.  Float literals are represented by an optional sign (-), some 
digits, an optional decimal point, and more digits.  If the number is an 
integer you may omit the decimal point and trailing zero.  If it is all 
fractional you may omit the leading zero.  POV-Ray supports scientific 
notation for very large or very small numbers.  The following are all valid 
float literals:

      1.0   -2.0  -4    34    3.4e6       2e-5        .3    0.6

Float identifiers may be declared and used anywhere a float can be used.  
See section 5.1.7 on declaring identifiers.  

Complex float expressions can be created using + - * / ( ) with float 
literals or identifiers.  Assuming the identifiers have been previously 
declared as floats, the following are valid float expressions:

      1+2+3       2*5         1/3         Row*3       Col*5

      (Offset-5)/2            This/That+Other*Thing

Expressions are evaluated left to right with innermost parenthesis 
evaluated first, then unary + or -, then multiply or divide, then add or 
subtract.

There are two built-in float identifiers.  The identifier "version" is the 
current setting of the version compatibility switch (See +MV under command-
line switches).  This allows you to save and restore the previous version 
switch.  For example suppose MYSTUFF.INC is in version 1.0 format.  At the 
top of the file you could put:

  #declare Temp_Vers = version    // Save previous value
  #version 1.0                    // Change to 1.0 mode

  ...   // Version 1.0 stuff goes here...

  #version Temp_Vers              // Restore previous version

The other float identifier is "clock".  Its value is set by the +K command-
line switch. (See +K under command-line switches).  This allows you to do 
limited animation control.  For example you could move an object using:

   translate <0.1*clock,0,0>

and render successive frames with +K1, +K2, +K3 etc.  In each frame the 
object would move 1/10th of a unit.

POV-Ray operates in a 3D x,y,z coordinate system.  Often you will need to 
specify x, y and z values.  A "vector" is a set of three float values used 
for such specification.  Vectors consist of three float expressions that 
are bracketed by angle brackets < and >.  The three terms are separated by 
commas.  For example:

     < 1.0, 3.2, -5.4578 >

The commas are necessary to keep the program from thinking that the 2nd 
term is "3.2-5.4578" and that there is no 3rd term.  If you see an error 
message "Float expected but '>' found instead" it probably means two floats 
were combined because a comma was missing.

The three values correspond to the x, y and z directions respectively. For 
example, the vector <1,2,3> means the point that's 1 unit to the right, 2 
units up, and 3 units in front the center of the "universe" at <0,0,0>. 
Vectors are not always points, though. They can also refer to an amount to 
size, move, or rotate a scene element.

Vectors may also be combined in expressions the same as float values.  For 
example <1,2,3>+<4,5,6> evaluates as <5,7,9>.  Subtraction, multiplication 
and division are also performed on a term-by-term basis.  You may also 
combine floats with vectors.  For example 5*<1,2,3> evaluates as <5,10,15>.

Sometimes POV-Ray requires you to specify floats and vectors side-by-side.  
Thus commas are required separators whenever an ambiguity might arise.  For 
example <1,2,3>-4 evaluates as <-3,-2,-1> but <1,2,3>,-4 is a vector 
followed by a float.

Vector identifiers may be declared and used anywhere a vector can be used.  
See section 5.1.7 on declaring identifiers.

Because vectors almost always refer to the x, y and z coordinates, POV-Ray 
has three built-in vector identifiers "x "y" and "z".  Like all POV-Ray 
keywords they must be lower case.  The vector identifier x is equivalent to 
the vector <1,0,0>.  Similarly y is <0,1,0> and z is <0,0,1>.

Thus an expression like 5*x evaluates to 5*<1,0,0> or <5,0,0>.  The use of 
these identifiers can make the scene file easier to read.

Vectors are used not only as a notation for a point in space but are used 
in the transformations scale, rotate, and translate. Scale sizes a texture 
or object. Translate moves a texture or object. And rotate turns a texture 
or object.

An object or texture pattern may be moved by adding a "translate" 
parameter.  It consists of the keyword "translate" followed by a vector.  
The terms of the vector specify the number of units to move in each of the 
x, y, and z directions.  Translate moves the element relative to it's 
current position. For example,

  sphere { <10, 10, 10>, 1 
    pigment { Green }
    translate <-5, 2, 1>
  }

Will move the sphere from <10, 10, 10> to <5, 12, 11>.  It does not move it 
to absolute location <5, 2, 1>. Translating by zero will leave the element 
unchanged on that axis. For example,

  sphere { <10, 10, 10>, 1 
    pigment { Green }
    translate <0, 0, 0>
  }

Will not move the sphere at all.

You may change the size of an object or texture pattern by adding a "scale" 
parameter.  It consists of the keyword "scale" followed by a vector or a 
single float value.  If a vector is used, terms of the vector specify the 
amount of scaling in each of the x, y, and z directions.  If a float value 
is used, the item is uniformly scaled by the same amount in all directions.

Scale, is used to "stretch" or "squish" an element. Values larger than 1 
stretch the element on that axis. Values smaller than one are used to 
squish the element on that axis. Scale is relative to the current element 
size. If the element has been previously re-sized using scale, then scale 
will size relative to the new size. Multiple scale values may used.

You may change the orientation of an object or texture pattern by adding a 
"rotate" parameter.  It consists of the keyword "rotate" followed by a 
vector.  The three terms of the vector specify the number of degrees to 
rotate about each of the x, y, and z axes.  

Note that the order of the rotations does matter.  Rotations occur about 
the x axis first, then the y axis, then the z axis.  If you are not sure if 
this is what you want then you should use multiple rotation statements to 
get a correct rotation. You should only rotate on one axis at a time. As 
in,

   rotate <0, 30, 0>  // 30 degrees around Y axis then,
   rotate <-20, 0, 0> // -20 degrees around X axis then,
   rotate <0, 0, 10>  // 10 degrees around Z axis.

Rotation is always performed relative to the axis.  Thus if an object is 
some distance from the axis of rotation, its will not only rotate but it 
will "orbit" about the axis as though it was swinging around on an 
invisible string.  

To work out the rotation directions, you must perform the famous "Computer 
Graphics Aerobics" exercise. Hold up your left hand. Point your thumb in 
the positive direction of the axis of rotation. Your fingers will curl in 
the positive direction of rotation. Similarly if you point your thumb in 
the negative direction of the axis your fingers will curl in the negative 
direction of rotation.  This is the famous "left-hand coordinate system". 

               ^
             +Y|   +Z/ _
               |    /_| |_  _
               |   _| | | |/ \
               |  | | | | |  |
               | /| | | | |  V
     -X        |/ | | | | |    +X
    <----------+--|-|-|-|-|------>
              /|  |       \____
             / |  |         ___|
            /  |  \        /
           /   |   |      /
        -Z/  -Y|
         /     |

In this 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 you want to use a right hand system, as some CAD systems such as AutoCAD 
do, the "right" vector in the camera specification needs to be changed. See 
the detailed description of the camera.  In a right handed system you use 
your right hand for the "Aerobics". 

When an object is transformed, all textures attached to the object AT THAT 
TIME are transformed as well. This means that if you have a translate, 
rotate, or scale in an object BEFORE a texture, the texture will not be 
transformed. If the scale, translate, or rotate is AFTER the texture then 
the texture will be transformed with the object.  If the transformation is 
INSIDE the "texture { }" statement then ONLY THE TEXTURE is affected.  The 
shape remains the same.  For example:

   sphere { <0, 0, 0>, 1
     texture { White_Marble }  // texture identifier from TEXTURES.INC
     scale 3                   // This scale affects both the 
                               // shape and texture 
   }

   sphere { <0, 0, 0>, 1
     scale 3             // This scale affects the shape only
     texture { White_Marble }  
   }

   sphere { <0, 0, 0>, 1
     texture { 
       White_Marble      
       scale 3           // This scale affects the texture only
     }  
   }

Transformations may also be independently applied to pigment patterns and 
surface normal (bump) patterns.  Note scaling a normal pattern affects only 
the width and spacing.  It does not affect the height or depth.  For 
example:

   box { <0, 0, 0>, <1, 1, 1>
     texture { 
       pigment {
         checker color Red color White
         scale 0.25  // This affects only the color pattern
       }
       normal {
         bumps 0.3   // This specifies apparent height of bumps
         scale 0.2   // Scales diameter and space between bumps but not 
                     //  not the height. Has no effect on color pattern.
       }
       rotate y*45   // This affects the entire texture but not
     }               //  the object. 
   }

Because rotations are always relative to the axis and scaling is relative 
to the origin, you will generally want to create an object at the origin 
and scale and rotate it first.  Then you may translate it into its proper 
position.  It is a common mistake to carefully position an object and then 
to decide to rotate it.  Because a rotation of an object causes it to orbit 
the axis, the position of the object may change so much that it orbits out 
of the field of view of the camera!

Similarly scaling after translation also moves an object unexpectedly. If 
you scale after you translate, the scale will multiply the translate 
amount. For example:

  translate <5, 6, 7>
  scale 4 

Will translate to 20, 24, 28 instead of 5, 6, 7. Be careful when 
transforming to get the order correct for your purposes.

The parameters used to describe the scene elements can be tedious to use at 
times. Some parameters are often repeated and it seems wasteful to have to 
type them over and over again. To make this task easier, the program allows 
users to create identifiers as synonyms for a pre-defined set of parameters 
and use them anywhere the parameters would normally be used. For example, 
the color white is defined in the POV-Ray language as:

   color red 1 green 1 blue 1

This can be pre-defined in the scene as:

   #declare White = color red 1 green 1 blue 1

and then substituted for the full description in the scene file, for 
example:

   sphere { 
     <0, 0, 0>, 1
     pigment { color red 1 green 1 blue 1 }
   }

becomes:

   #declare White = color red 1 green 1 blue 1

   sphere { 
     <0, 0, 0>, 1
     pigment { color White }
   }

This is much easier to type and to read. The pre-defined element may be 
used many times in a scene.

You use the keyword "declare" to pre-define a scene element and give it a 
one-word identifier. This pre-defined scene element is not used in the 
scene until you invoke its identifier. Textures, objects, colors, numbers 
and more can be predefined.

In most cases when you invoke an identifier you simply use the form 
"keyword{identifier}" where the keyword used is the type of statement that 
was declared. For example:

  #declare Shiny = finish {phong 0.8 phong_size 50 reflection 0.2}

  sphere {
     <0, 0, 0>, 1
     pigment { color White }
     finish { Shiny }
   }

The identifier "Shiny" was declared as a "finish" and is invoked by placing 
it inside a "finish { }" statement.

One exception is object identifiers.  If you declare any object of any kind 
such as sphere, box, union, intersection etc. you should invoke it by 
placing it in an "object { }" statement.  Thus you might have:

  #declare Thing = intersection {...}

  object {Thing}  // not "intersection{Thing}"

Pre-defined elements may be modified when they are used, for example:

  #declare Mickey = // Pre-define a union object called Mickey
     union {
       sphere { < 0, 0, 0>, 2 }
       sphere { <-2, 2, 0>, 1 }
       sphere { < 2, 2, 0>, 1 }
     }

  // Use Mickey
     object{        // Note use of "object", not "union" keyword
       Mickey
       scale 3
       rotate y*20
       translate <0, 8, 10>
       pigment {color red 1}
       finish {phong .7}
     }

This scene will only have one "Mickey", the Mickey that is described 
doesn't appear in the scene. Notice that Mickey is scaled, rotated, 
translated, and a texture is added to it. The Mickey identifier could be 
used many times in a scene file, and each could have a different size, 
position, orientation, and texture.

Declare is especially powerful when used to create a complex object. Each 
part of the object is defined separately using declare. These parts can be 
tested, rotated, sized, positioned, and textured separately then combined 
in one shape or object for the final sizing, positioning, etc. For example, 
you could define all the parts of a car like this:

  #declare Wheel = object {...}
  #declare Seat = object {...}
  #declare Body = object {...}
  #declare Engine = object {...}
  #declare Steering_Wheel = object {...}

  #declare Car = 
    union {
       object { Wheel translate < 1, 1, 2>}
       object { Wheel translate <-1, 1, 2>}
       object { Wheel translate < 1, 1,-2>}
       object { Wheel translate <-1, 1,-2>}
       object { Seat translate < .5, 1.4, 1>}
       object { Seat translate <-.5, 1.4, 1>}
       object { Steering_Wheel translate <-.5, 1.6, 1.3>}
       object { Body texture { Brushed_Steel } }
       object { Engine translate <0, 1.5, 1.5> 
    }

and then it like this:
 
  // Here is a car
  object {
    Car 
    translate <4, 0, 23>
  }

Notice that the Wheel and Seat are used more than once. A declared element 
can be used as many times as you need. Declared elements may be placed in 
"include" files so they can be used with more than one scene.

There are several files included with POV-Ray that use declare to pre-
define many shapes, colors, and textures. See the archive INCLUDE for more 
info.

NOTE: Declare is not the same as the C language's define. Declare creates 
an internal object of the type specified that POV-Ray can copy for later 
use.  The "define" used in C creates a text substitution macro.

Here's a list of what can be declared, how to declare the element, and how 
to use the declaration. See the reference section for element syntax.

Objects: (Any type may be declared, sphere, box, height_field, blob, etc.)
  #declare Tree = union {...}
  #declare Ball = sphere {...}
  #declare Crate= box {...}
 
  object {
    Tree
    (OBJECT_MODIFIERS...) 
  }

  object {
    Ball
    (OBJECT_MODIFIERS...) 
  }

  object {
    Crate
    (OBJECT_MODIFIERS...) 
  }

Textures:
  #declare Fred = texture {...} 

  sphere { <0, 0, 0>, 1 
    texture {
      Fred 
      (texture_modifiers) 
    }
  }

Layered textures:
  #declare Fred = 
     texture {...} 
     texture {...} 
     texture {...} (etc.)

  sphere { <0, 0, 0>, 1 
    texture {
      Fred 
      (texture_modifiers) 
    }
  }

Pigment:
  #declare Fred = pigment {checker color Red color White} 

  sphere { <0, 0, 0>, 1 
    pigment {
      Fred 
      (pigment_modifiers) 
    }
  }

Normal:
  #declare Fred = normal {bumps 0.5} 

  sphere { <0, 0, 0>, 1 
    pigment {White}
    normal {
      Fred 
      (normal_modifiers) 
    }
  }

Finish:
  #declare Fred = finish {phong 0.7 reflection 0.2} 

  sphere { <0, 0, 0>, 1 
    pigment {White}
    finish {
      Fred 
      (finish_items) 
    }
  }

Colors:
  #declare Fred = color red 1 green 1 blue 1 

  sphere { <0, 0, 0>, 1 
    pigment { color Fred }
  }

Color_map:
  #declare Rainbow = 
    color_map {
      [0.0 color Cyan]
      [1/3 color Yellow]
      [2/3 color Magenta]
      [1.0 color Cyan]
    }

  sphere { <0, 0, 0>, 1 
    pigment { radial color_map{Rainbow} rotate -90*x}
  }

Float Values:
  #declare Fred  = 3.45
  #declare Fred2 = .02
  #declare Fred3 = .5

 // Use the numeric value identifier 
 // anywhere a number would go
  sphere { <-Fred, 2, Fred>, Fred 
    pigment { color red 1 }
    finish { phong Fred3 }
  }

Camera:
  #declare Fred = camera {..}

  camera { Fred }

Vectors:
   #declare Fred = <9, 3, 2>
   #declare Fred2 = <4, 1, 4>

   sphere { Fred, 1  // Note do not put < > brackets
     scale Fred2     // around vector identifiers
   }