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 grey 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

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"

Section 7.1.6.2
String Identifiers

String 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 = STRING

Where IDENTIFIER is the name of the identifier up to 40 characters long and STRING is a string literal, string identifier or function which returns a string value. Here are some examples...

#declare Font_Name = "ariel.ttf" #declare Inc_File = "myfile.inc" #declare Name = "John" #declare Name = concat(Name," Doe")

As the last example shows, you can re-declare a string identifier and may use previously declared values in that re-declaration.

Section 7.1.7
Built-in Identifiers

There are several built-in float and vector identifiers. You can use them to specify values or to create expressions but you cannot re-declare them to change their values.

Section 7.1.7.1
Constant Built-in Identifiers

Most built-in identifiers never change value. They are defined as though the following lines were at the start of every scene.

#declare pi = 3.1415926535897932384626 #declare true = 1 #declare yes = 1 #declare on = 1 #declare false = 0 #declare no = 0 #declare off = 0 #declare u = <1,0> #declare v = <0,1> #declare x = <1,0,0> #declare y = <0,1,0> #declare z = <0,0,1> #declare t = <0,0,0,1>

The built-in float identifier pi is obviously useful in math expressions involving circles.

The built-in float identifiers on , off , yes , no , true and false are designed for use as boolean constants.

The built-in vector identifiers x , y and z provide much greater readability for your scene files when used in vector expressions. For example....

plane { y, 1} // The normal vector is obviously "y". plane { <0,1,0>, 1} // This is harder to read. translate 5*x // Move 5 units in the "x" direction. translate <5,0,0> // This is less obvious.

An expression like 5*x evaluates to 5 <1,0,0> or <5,0,0>.

Section 7.1.7.2
Built-in Identifier 'clock'

The built-in float identifier clock is used to control animations in POV-Ray. Unlike some animation packages, the action in POV-Ray animated scenes does not depend upon the integer frame numbers. Rather you should design your scenes based upon the float identifier clock . For non-animated scenes its default value is 0 but you can set it to any float value using the INI file option Clock=n.n or the command-line switch +Kn.n to pass a single float value your scene file.

Other INI options and switches may be used to animate scenes by automatically looping through the rendering of frames using various values for clock . By default, the clock value is 0 for the initial frame and 1 for the final frame. All other frames are interpolated between these values. For example if your object is supposed to rotate one full turn over the course of the animation you could specify rotate 360*clock*y . Then as clock runs from 0 to 1, the object rotates about the y-axis from 0 to 360 degrees.

Although the value of clock will change from frame-to-frame, it will never change throughout the parsing of a scene.

See "Animation Options" for more details.

Section 7.1.7.3
Built-in Identifier 'version'

The built-in float identifier version contains the current setting of the version compatibility option. Although this value defaults to 3 which is the current POV-Ray version number, the initial value of version may be set by the INI file option Version=n.n or by the +MVn.n command-line switch. This tells POV-Ray to parse the scene file using syntax from an earlier version of POV-Ray.

The INI option or switch only affects the initial setting. Unlike other built-in identifiers, you may change the value of version throughout a scene file. You do not use #declare to change it though. The #version language directive is used to change modes. Such changes may occur several times within scene files.

Together with the built-in version identifier the #version directive allows you to save and restore the previous values of this compatibility setting. For example suppose mystuff.inc is in version 1 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

Section 7.1.8
Functions

POV-Ray defines a variety of built-in functions for manipulating floats, vectors and strings. The functions are listed grouped according to their usage and not by the type of value they return. For example vdot computes the dot product of two vectors and is listed as a vector function even though it returns a single float value.

Function calls consist of a keyword which specifies the name of the function followed by a parameter list enclosed in parentheses. Parameters are separated by commas. For example:

keyword(param1,param2)

Functions evaluate to values that are floats, vectors or strings and may be used in expressions or statements anywhere that literals or identifiers of that type may be used.

Section 7.1.8.1
Float Functions

The following are the functions which take one or more float parameters and return float values. Assume that A and B are any valid expression that evaluates to a float. See "Vector Functions" and "String Functions" for other functions which return float values but whose primary purpose is more closely related to vectors and strings.

abs(A): Absolute value of A. If A is negative, returns -A otherwise returns A.
acos(A): Arc-cosine of A. Returns the angle, measured in radians, whose cosine is A.
asin(A): Arc-sine of A. Returns the angle, measured in radians, whose sine is A.
atan2(A,B): Arc-tangent of (A/B). Returns the angle, measured in radians, whose tangent is (A/B). Returns appropriate value even if Bis zero. Use atan2(A,1) to compute usual atan(A) function.
ceil(A): Ceiling of A. Returns the smallest integer greater than A. Rounds up to the next higher integer.
cos(A): Cosine of A. Returns the cosine of the angle A, where A is measured in radians.
degrees(A): Convert radians to degrees. Returns the angle measured in degrees whose value in radians is A. Formula is degrees=A/pi*180.0.
div(A,B): Integer division. The integer part of (A/B).
exp(A): Exponential of A. Returns the value of e raised to the A power where e is the non-repeating value approximately equal to 2.71828182846 the base of natural logarithms.
floor(A): Floor of A. Returns the largest integer less than A. Rounds down to the next lower integer.
int(A): Integer part of A. Returns the truncated integer part of A. Rounds towards zero.
log(A): Natural logarithm of A. Returns the natural logarithm base e of the value A where e is the non-repeating value approximately equal to 2.71828182846.
max(A,B): Maximum of A and B. Returns A if A larger than B. Otherwise returns B.
min(A,B): Minimum of A and B. Returns A if A smaller than B. Otherwise returns B.
mod(A,B): Value of A modulo A. Returns the remainder after the integer division of A/B. Formula is mod=((A/B)-int(A/B))*B.
pow(A,B): Exponentiation. Returns the value of A raised to the power B.
radians(A): Convert degrees to radians. Returns the angle measured in radians whose value in degrees is A. Formula is radians=A*pi/180.0.
rand(A): Returns the next pseudo-random number from the stream specified by the positive integer A. You must call seed() to initialize a random stream before calling rand(). The numbers are uniformly distributed, and have values between 0.0 and 1.0, inclusively. The numbers generated by separate streams are independent random variables.
seed(A): Initializes a new pseudo-random stream with the initial seed value A. The number corresponding to this random stream is returned. Any number of pseudo-random streams may be used as shown in the example below:

#declare R1 = seed(0) #declare R2 = seed(12345) #sphere { <rand(R1), rand(R1), rand(R1)>, rand(R2) } Multiple random generators are very useful in situations where you use rand() to place a group of objects, and then decide to use rand() in another location earlier in the file to set some colors or place another group of objects. Without separate rand() streams, all of your objects would move when you added more calls to rand(). This is very annoying. sin(A): Sine of A. Returns the sine of the angle A, where A is measured in radians. sqrt(A): Square root of A. Returns the value whose square is A. tan(A): Tangent of A. Returns the tangent of the angle A, where A is measured in radians.

Section 7.1.8.2
Vector Functions

The following are the functions which take one or more vector and float parameters and return vector or float values. All of these functions support only three component vectors. Assume that A and B are any valid expression that evaluates to a three component vector and that F is any valid expression that evaluates to a float.

vaxis_rotate(A,B,F): Rotate A about B by F. Given the x,y,z coordinates of a point in space designated by the vector A, rotate that point about an arbitrary axis defined by the vector B. Rotate it through an angle specified in degrees by the float value F. The result is a vector containing the new x,y,z coordinates of the point.
vcross(A,B): Cross product of A and B. Returns a vector that is the vector cross product of the two vectors. The resulting vector is perpendicular to the two original vectors and its length is proportional to the angle between them. See the animated demo scene VECT2.POV for an illustration.
vdot(A,B): Dot product of A and B. Returns a float value that is the dot product (sometimes called scaler product of A with B. Formula is vdot=A.x*B.x + A.y*B.y + A.z*B.z. See the animated demo scene VECT2.POV for an illustration.
vlength(A): Length of A. Returns a float value that is the length of vector A. Can be used to compute the distance between two points. Dist=vlength(B-A). Formula is vlength=sqrt(vdot(A,A)).
vnormalize(A): Normalize vector A. Returns a unit length vector that is the same direction as A. Formula is vnormalize=A/vlength(A).
vrotate(A,B): Rotate A about origin by B. Given the x,y,z coordinates of a point in space designated by the vector A, rotate that point about the origin by an amount specified by the vector B. Rotate it about the x-axis by an angle specified in degrees by the float value B.x. Similarly B.y and B.z specify the amount to rotate in degrees about the y-axis and z-axis. The result is a vector containing the new x,y,z coordinates of the point.

Next Section
Table Of Contents