Section 7.1.4
Vector Expressions

POV-Ray often requires you to specify a vector. A vector is a set of related float values. Vectors may be specified using literals, identifiers or functions which return vector values. You may also create very complex vector expressions from combinations of any of these using various familiar operators.

POV-Ray vectors may have from two to five components but the vast majority of vectors have three components. Unless specified otherwise, you should assume that the word vector means a three component vector. POV-Ray operates in a 3D x, y, z coordinate system and you will use three component vectors to specify x, y and z values. In some places POV-Ray needs only two coordinates. These are often specified by a 2D vector called an UV vector. Fractal objects use 4D vectors. Color expressions use 5D vectors but allow you to specify 3, 4 or 5 components and use default values for the unspecified components. Unless otherwise noted, all 2, 4 or 5 component vectors work just like 3D vectors but they have a different number of components.

Section 7.1.4.1
Vector Literals

Vectors consist of two to five float expressions that are bracketed by angle brackets < and >. The terms are separated by commas. For example here is a typical three component vector:

< 1.0, 3.2, -5.4578 >

The commas between components are necessary to keep the program from thinking that the 2nd term is the single float expression 3.2-5.4578 and that there is no 3rd term. If you see an error message such as Float expected but '>' found instead you probably have missed a comma.

Sometimes POV-Ray requires you to specify floats and vectors side-by-side. The rules for vector expressions allow for mixing of vectors with vectors or vectors with floats so commas are required separators whenever an ambiguity might arise. For example < 1,2,3>-4 evaluates as a mixed float and vector expression where 4 is subtracted from each component resulting in < -3,-2,-1>. However the comma in <1,2,3>,-4 means this is a vector followed by a float.

Each component may be a full float expression. For example < This+3,That/3,5*Other_Thing> is a valid vector.

Section 7.1.4.2
Vector Identifiers

Vector identifiers may be declared to make scene files more readable and to parameterize scenes so that changing a single declaration changes many values. An identifier is declared as follows...

#declare IDENTIFIER = EXPRESSION

Where IDENTIFIER is the name of the identifier up to 40 characters long and EXPRESSION is any valid expression which evaluates to a vector value. Here are some examples...

#declare Here = <1,2,3> #declare There = <3,4,5> #declare Jump = <Foo*2,Bar-1,Bob/3> #declare Route = There-Here #declare Jump = Jump+<1,2,3>

Note that you invoke a vector identifier by using its name without any angle brackets. As the last example shows, you can re-declare a vector identifier and may use previously declared values in that re-declaration. There are several built-in identifiers which POV-Ray declares for you. See section "Built-in Identifiers" for details.

Section 7.1.4.3
Vector Operators

Vector literals, identifiers and functions may also be combined in expressions the same as float values. Operations are performed on a component-by-component basis. For example <1,2,3> + <4,5,6> evaluates the same as < 1+4,2+5,3+6> or <5,7,9>. Other operations are done on a similar component-by-component basis. For example (< 1,2,3> = <3,2,1>) evaluates to < 0,1,0> because the middle components are equal but the others are not. Admittedly this isn't very useful but its consistent with other vector operations.

Conditional expressions such as (C ? A : B) require that C is a float expression but A and B may be vector expressions. The result is that the entire conditional evaluates as a valid vector. For example if Foo and Bar are floats then

Foo < Bar ? <1,2,3> : <5,6,7> evaluates as the vector <1,2,3> if Foo is less than Bar and evaluates as <5,6,7> otherwise.

You may use the dot operator to extract a single component from a vector. Suppose the identifier Spot was previously defined as a vector. Then Spot.x is a float value that is the first component of this x, y, z vector. Similarly Spot.y and Spot.z reference the 2nd and 3rd components. If Spot was a two component UV vector you could use Spot.u and Spot.v to extract the first and second component. For a 4D vector use .x, .y, .z and .t to extract each float component. The dot operator is also used in color expressions which are covered later.

Section 7.1.4.4
Operator Promotion

You may use a lone float expression to define a vector whose components are all the same. POV-Ray knows when it needs a vector of a particular type and will promote a float into a vector if need be. For example the POV-Ray scale statement requires a three component vector. If you specify scale 5 then POV-Ray interprets this as scale <5,5,5> which means you want to scale by 5 in every direction.

Versions of POV-Ray prior to 3.0 only allowed such use of a float as a vector in various limited places such as scale and turbulence. However you may now use this trick anywhere. For example...

box{0,1} // Same as box{<0,0,0>,<1,1,1>} sphere{0,1} // Same as sphere{<0,0,0>,1}

When promoting a float into a vector of 2, 3, 4 or 5 components, all components are set to the float value, however when promoting a vector of a lower number of components into a higher order vector, all remaining components are set to zero. For example if POV-Ray expects a 4D vector and you specify 9 the result is <9,9,9,9> but if you specify <7,6> the result is < 7,6,0,0>.

Section 7.1.5
Specifying Colors

POV-Ray often requires you to specify a color. Colors consist of five values or color components. The first three are called red, green and blue. They specify the intensity of the primary colors red, green and blue using an additive color system like the one used by the red, green and blue color phosphors on a color monitor.

The 4th component, called filter, specifies the amount of filtered transparency of a substance. Some real-world examples of filtered transparency are stained glass windows or tinted cellophane. The light passing through such objects is tinted by the appropriate color as the material selectively absorbs some frequencies of light while allowing others to pass through. The color of the object is subtracted from the light passing through so this is called subtractive transparency.

The 5th component, called transmit, specifies the amount of non-filtered light that is transmitted through a surface. Some real-world examples of non-filtered transparency are thin see-through cloth, fine mesh netting and dust on a surface. In these examples, all frequencies of light are allowed to pass through tiny holes in the surface. Although the amount of light passing through is diminished, the color of the light passing through is unchanged. The color of the object is added to the light passing through so this is called additive transparency.

Note that early versions of POV-Ray used the keyword alpha to specify filtered transparency. However that word is often used to describe non-filtered transparency. For this reason alpha is no longer used.

Each of the five components of a color are float values which are normally in the range between 0.0 and 1.0. However any values, even negatives may be used.

Colors may be specified using vectors, keywords with floats or identifiers. You may also create very complex color expressions from combinations of any of these using various familiar operators. The syntax for specifying a color has evolved since POV-Ray was first released. We have maintained the original keyword-based syntax and added a short-cut vector notation. Either the old or new syntax is acceptable however the vector syntax is easier to use when creating color expressions.

Section 7.1.5.1
Color Vectors

The syntax for a color vector is any of the following...

color rgb VECTOR3 color rgbf VECTOR4 color rgbt VECTOR4 color rgbft VECTOR5

where VECTOR3, VECTOR4 or VECTOR5 are any valid vector expressions of 3, 4 or 5 components. For example

color rgb <1.0, 0.5, 0.2>

This specifies a color whose red component is 1.0 or 100% of full intensity. The green component is 0.5 or 50% of full intensity and the blue component is 0.2 or 20% of full intensity. Although the filter and transmit components are not explicitly specified, they exist and are set to their default values of 0 or no transparency.

The rgbf keyword requires a four component vector. The 4th component is the filter component and the transmit component defaults to zero. Similarly the rgbt keyword requires four components where the 4th value is moved to the 5th component which is transmit and then the filter component is set to zero.

The rgbft keyword allows you to specify all five components. Internally in expressions all five are always used.

Under most circumstances the keyword color is optional and may be omitted. We also support the British or Canadian spelling colour. Under some circumstances, if the vector expression is a 5 component expression or there is a color identifier in the expression then the rgbtf keyword is optional.

Section 7.1.5.2
Color Keywords

The older keyword method of specifying a color is still useful and many users prefer it. Like a color vector, you begin with the optional keyword color. This is followed by any of five additional keywords red, green, blue, filter or transmit. Each of these component keywords is followed by a float expression. For example

color red 1.0 green 0.5

This specifies a color whose red component is 1.0 or 100% of full intensity and the green component is 0.5 or 50% of full intensity. Although the blue, filter and transmit components are not explicitly specified, they exist and are set to their default values of 0. The component keywords may be given in any order and if any component is unspecified its value defaults to zero.

Section 7.1.5.3
Color Identifiers

Color identifiers may be declared to make scene files more readable and to parameterize scenes so that changing a single declaration changes many values. A color identifier is declared as either of the following...

#declare IDENTIFIER = COLOR_VECTOR #declare IDENTIFIER = COLOR_KEYWORDS...

Where IDENTIFIER is the name of the identifier up to 40 characters long and COLOR_VECTOR or COLOR_KEYWORDS are any valid color specifications as described in the two previous sections of this document. Here are some examples...

#declare White = rgb <1,1,1> #declare Cyan = color blue 1.0 green 1.0 #declare Weird = rgb <Foo*2,Bar-1,Bob/3> #declare LightGray = White*0.8 #declare LightCyan = Cyan red 0.6

As the LightGray example shows you do not need any color keywords when creating color expressions based on previously declared colors. The last example shows you may use a color identifier with the keyword style syntax. Make sure that the identifier comes first before any other component keywords.

Like floats and vectors, you may re-define colors throughout a scene but the need to do so is rare.

Section 7.1.5.4
Color Operators

Color vectors may be combined in expressions the same as float or vector values. Operations are performed on a component-by-component basis. For example rgb <1.0, 0.5 0.2> * 0.9 evaluates the same as rgb <1.0, 0.5 0.2> * <0.9, 0.9, 0.9> or rgb <0.9, 0.45, 0.18>. Other operations are done on a similar component-by-component basis.

You may use the dot operator to extract a single component from a color. Suppose the identifier Shade was previously defined as a color. Then Shade.red is the float value of the red component of Shade. Similarly Shade.green, Shade.blue, Shade.filter and Shade.transmit extract the float value of the other color components.

Section 7.1.5.5
Common Color Pitfalls

The variety and complexity of color specification methods can lead to some common mistakes. Here are some things to consider when specifying a color.

When using filter transparency, the colors which come through are multiplied by the primary color components. For example if gray light such as rgb <0.9,0.9,0.9> passes through a filter such as rgbf <1.0,0.5,0.0,1.0> the result is rgb <0.9,0.45,0.0> with the red let through 100%, the green cut in half from 0.9 to 0.45 and the blue totally blocked. Often users mistakenly specify a clear object by

color filter 1.0

but this has implied red, green and blue values of zero. You've just specified a totally black filter so no light passes through. The correct way is either

color red 1.0 green 1.0 blue 1.0 filter 1.0

or

color transmit 1.0

In the 2nd example it doesn't matter what the rgb values are. All of the light passes through untouched.

Another pitfall is the use of color identifiers and expressions with color keywords. For example...

color My_Color red 0.5

this substitutes whatever was the red component of My_Color with a red component of 0.5 however...

color My_Color + red 0.5

adds 0.5 to the red component of My_Color and even less obvious...

color My_Color * red 0.5

that cuts the red component in half as you would expect but it also multiplies the green, blue, filter and transmit components by zero! The part of the expression after the multiply operator evaluates to rgbft <0.5,0,0,0,0> as a full 5 component color.

The following example results in no change to My_Color.

color red 0.5 My_Color

This is because the identifier fully overwrites the previous value. When using identifiers with color keywords, the identifier should be first.

One final issue, some POV-Ray syntax allows full color specifications but only uses the rgb part. In these cases it is legal to use a float where a color is needed. For example:

finish { ambient 1 }

The ambient keyword expects a color so the value 1 is promoted to <1,1,1,1,1> which is no problem. However

pigment { color 0.4 }

is legal but it may or may not be what you intended. The 0.4 is promoted to <0.4,0.4,0.4,0.4,0.> with the filter and transmit set to 0.4 as well. It is more likely you wanted...

pigment { color rgb 0.4 }

in which case a 3 component vector is expected. Therefore the 0.4 is promoted to <0.4,0.4,0.4,0.0,0.0> with default zero for filter and transmit.

Section 7.1.6
Strings

The POV-Ray language requires you to specify a string of characters to be used as a file name, text for messages or text for a text object. Strings may be specified using literals, identifiers or functions which return string values. Although you cannot build string expressions from symbolic operators such as are used with floats, vectors or colors, you may perform various string operations using string functions. Some applications of strings in POV-Ray allow for non-printing formatting characters such as newline or form-feed.

Section 7.1.6.1
String Literals

String literals begin with a double quote mark '"' which is followed by up to 256 printable ASCII characters and are terminated by another double quote mark. The following are all valid string literals:

  "Here"   "There"    "myfile.gif"    "textures.inc"

Note if you need to specify a quote mark in a string literal you must preceed it with a backslash. For example

  "Joe said \"Hello\" as he walked in."

is converted to

  Joe said "Hello" as he walked in.

If you need to specify a backslash, most of the time you need do nothing special. However if the string ends in a backslash, you will have to specify two. For example:

  "This is a backslash  and so is this"

Is converted to:

  This is a backslash  and so is this\

The

regardless usage however other formating codes such as \n for new line are supported in user message streams. See "Text Formatting" for details.

Next Section
Table Of Contents