The Online POV-Ray Tutorial

POV-Ray Basics

(Show Jump Points) (Hide Jump Points)

Before you can start creating scenes in POV-Ray, you need to know a few things: how to describe objects in three dimensions, some of POV-Ray's basic notation, and other stuff. This section will give you the background knowledge you'll need to get started.

Quick reference:

  1. POV-Ray's Coordinate System
  2. Vectors in POV-Ray
  3. How to describe color: RGB and RGBF Vectors
  4. Normal Vectors
  5. POV-Ray Source Code
  6. Comments in POV-Ray Source Code
  7. Including files

POV-Ray's Coordinate System

The source code file, the file POV-Ray takes as input, is really one big list of descriptions of objects. The very first thing we need in order to describe objects is a way of telling POV-Ray where things go. Such a method is called a coordinate system. If you have taken elementary algebra, you will already have experience with a simple coordinate system: a two-dimensional (or 2D) Cartesian coordinate system. A quick graph of a 2D Cartesian plane looks something like this:

Any position on this graph can be specified by a set of coordinates, usually written in the form (x,y). The x coordinate corresponds to its position along the horizontal, or x, axis, and the y coordinate corresponds to its position along the vertical, or y axis. For example, (0,0) corresponds to the point in the middle of the graph, or the origin. The point (1,3) corresponds to the point on the graph one unit right from the origin, and three units up from the origin. Negative numbers can also be used: (-6,4) corresponds to the point 6 units left from the origin, and four units up. You get the idea.

Now this is all well and good, but when we look at things other than our computer screen, we notice we can observe three dimensions, not two: in other words, we describe objects not just by how far to the right (or left) and how high (or low) they are, but also how close they are in front (or in back) of you. In other words, to be able to describe a real scene to POV-Ray, we need, in addition to the x and y coordinates, a third coordinate. This coordinate is called (surprisingly enough) the z coordinate.

The coordinate system that POV-Ray uses, then, is called a three-dimensional (or 3D) Cartesian coordinate system. A quick graph looks like this:

(You have to use your imagination somewhat: that third axis is not a diagonal but is perpendicular to your computer screen -- imagine it shooting out at your face). As you can see, it looks similar to the 2D graph, except that one additional axis has been added: the z axis. Because of the additional possible direction, points in this coordinate system must be described in the form (x,y,z). The point (0,0,0) corresponds to the origin, or center of the graph, and (1,-2,7) corresponds to the point one unit to the right of, two units below, and seven units behind the origin.

If you have experience with mathematical 3D coordinate systems, you will notice that the axes are labelled slightly differently than the system most commonly used in mathematical terms. The axis we have drawn above is not fixed in POV-Ray -- the way the axis looks (in terms of which axes are which) really depends on where you place your camera in POV-Ray. We'll get to explaining the camera soon. For now, just understand that the labels on the axes may change, depending on how you position your camera.

The 3D graph above represents a coordinate system that POV-Ray can use. Visualizing objects and scenes in three dimensions can be tricky. Often, a pad of paper and a pencil can be extremely valuable tools, especially in more complex scenes. Alternatively, you can take a look at the Resource Library for some graphical tools that may help.

Vectors in POV-Ray

POV-Ray calls the number triples that define positions position vectors. The term vector refers to any group of numbers describing a certain thing -- there are color vectors and normal vectors, for example, in addition to position vectors.

In POV-Ray, vectors are surrounded by angle brackets (that's < and >). For example, to specify the origin in terms that POV-Ray understands, we would say <0,0,0>.

The magnitude of a vector can be thought of as the "length" of the vector. Imagine a line from the origin to the point in the coordinate system represented by your vector. The magnitude is the length of this line. (If you really care about the math, the magnitute can be computed as the square root of the sum of the squares of the elements of the vector -- but don't worry, you probably won't have to know that).

An important thing to know about is a POV-Ray feature called vector promotion. Vector promotion is when a single number is substituted in place of a vector. The single number is then promoted to a vector, one with all elements equal to that number. For example, promoting the number 2 to a three-dimensional vector would result in the vector <2,2,2>. Vector promotion is done automatically for you by POV-Ray in most cases -- just put in a single number instead of a vector. This feature allows you to quickly specify similar vectors.

How to describe color: RGB and RGBF Vectors

Much as any position within the scene can be specified by a three-element vector, so can any color. In describing a position, each coordinate in the vector corresponds to the position along a particular axis. In describing a color, each element of the vector corresponds to the amount of a primary color -- red, green and blue. Such a vector is called a RGB vector (for red green blue vector).

In a position vector, the individual elements can be any real number at all (actually, this isn't quite true -- there are upper and lower limits set by the hardware constraints of your computer). In a RGB vector, the numbers should be between 0.0 and 1.0. You can have values higher that 1.0, but they don't correspond to any physical property (what's greener than green?). A value of 1.0 means 100% of that color. For example, the color black, which is actually the absence of all color, is described by the color vector <0,0,0>. The color white, a complete combination of all three primary colors, is specified by the color vector <1,1,1>. Try experimenting with the Color Tool to find the color vectors for particular colors -- it will help you get a good "feel" for describing colors in terms of POV-Ray color vectors.

In addition to RGB vectors, you can specify a color in POV-Ray with an RGBF vector. As you might guess, a RGBF vector is like a RGB vector, but with one extra element - the F, for filter. The filter value specifies how transparent the pigment is, ranging from 0.0 (not transparent at all) to 1.0 (100% transparent). RGB vectors have an implied filter value of 0.0 -- in other words, a color specified by a RGB vector will be perfectly opaque. A filter value of 1.0 means that all light will be let through, but the light will still be filtered. For example, the RGBF vector <1,0,0,1> acts like red cellophane -- 100% of light is passed through, but it is filtered by the red pigment. RGBF vectors can be a little confusing at first, but they aren't too difficult once you get the hang of it.

These are the most commonly-used ways of specifying color. There are a few more ways to do it; if you want to read about them, look at the color section of the Language Reference.

Normal Vectors

Occasionally you will be called upon to specify a normal vector in POV-Ray. Simply put, a normal vector is a vector parallel to a given plane in three dimensions. Imagine a flat sheet of paper. If you were to poke a pencil all the way through it so that the end of the pencil was touching the paper and the pencil was standing straight up (with respect to the paper), the pencil would represent the normal vector to the paper. In the picture below, the normal vector is in red and the plane is in blue.

Note that the magnitude of normal vectors is not important (as long as it is non-zero). This is because normal vectors are used to specify an orientation, not a distance.

POV-Ray is kind enough to automatically define three normal vectors for you: x (corresponding to <1,0,0>), the normal vector for a plane lying along the y and z axes, y (corresponding to <0, 1, 0>), the normal vector for a plane lying along the x and z axes, and z (corresponding to <0, 0, 1>), the normal vector for a plane lying along the x and y axes. Any time you are asked for a normal vector (or any vector, really) you can substitute those letters.

POV-Ray Source Code

Source code is the name for the text you give to POV-Ray. POV-Ray reads the source code file and outputs an image. There are two things you need to know about POV-Ray source code:

  1. POV-Ray source code is case sensitive
  2. POV-Ray ignores whitespace
  3. Ordering is unimportant
Case sensitive means that upper and lower-case letters are not treated as the same by POV-Ray. For example, to POV-Ray, sphere is not the same as Sphere and is not the same as SpHeRe. Whitespace is the common name for any characters you can't directly see on screen -- spaces, tab characters (the invisible characters put there when you press the Tab key), carriage returns and line feeds (the invisible characters put there when you hit the Enter key). Between any two words or symbols in your source code, POV-Ray doesn't care whether you put one space, two spaces, one hundred spaces, a new line, or any other whitespace.

For example, the phrase:

one two
the phrase 
one             two
and the phrase 
one
two
are all treated the same by POV-Ray.

Ordering means the order in which you declare objects. POV-Ray does not care where in the file the objects are -- it makes no difference to the final scene. (VRML programmers will note that this is a very different approach than VRML's "virtual pen" concept). This does not hold entirely true for some attributes and CSG operations (both of which we will describe in detail later), but in the outer-most level in POV-Ray (the one in which you list the objects in your scene) it doesn't matter.

Comments in POV-Ray Source Code

Comments are another useful part of POV-Ray source code. A comment is a portion of text that POV-Ray will ignore. It is used to add information to the source code, usually to make things clearer to the human reader. Comments can be enclosed in /* and */, or, for single-line comments, can be prefixed with a //. For example: 
// this is a single-line comment
/* this is
   another comment.  it can be as long as you want it to be */
C and C++ programmers will recognized this comment style. For a detailed description of comments, see the comments section of the Language Reference.

Including files

Including files is a feature of many languages that makes re-using code easier. If you have, for example, many red objects in your scene, you will find it cumbersome (and not very readable) to type the correct RGB vector for red every time. POV-Ray comes to the rescue with a file full of pre-defined colors, which you can use and re-use in your source code. (POV-Ray also comes with files of textures and even objects; we'll get to those later). You can take advantage of these files by adding the string #include "filename" to the beginning of your file. For example, to use the pre-defined colors, you would add the string

#include "colors.inc"

to the beginning of your file. Technically, the statement does not have to occur at the beginning of the file, but the convention is such, and it makes for readability.

The example statement above tells POV-Ray to look for the file called colors.inc and to read it before continuing to the rest of your file. colors.inc defines many colors, such as Red, that you can use in your file any time you need a color, in place of a RGB (or RGBF) vector. This makes your source file much easier to read. Later in the tutorial, you will learn how to define your own colors (and objects, and textures, and so on) and how to put them in your own text files. For now, know how to use the provided ones and be happy.

Now that you've got that out of the way, you're ready to start creating your first scene... almost.

Top of Document Main Page Step 1: Introduction to POV-Ray and Ray-tracing Step 3: Creating Simple Scenes

The Online POV-Ray Tutorial © 1996 The Online POV-Ray Tutorial ThinkQuest Team