Section 7.2.1
Include Files

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

at any point in the input file. The filename may be specified by any valid string expression but it usually is a literal string enclosed in double quotes. It 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.

It is legal to specify drive and directory information in the file specification however it is discouraged because it makes scene files less portable between various platforms.

It is typical to put standard include files in a special sub-directory. POV-Ray can only read files in the current directory or one referenced by the Library_Path option (See section "Library Paths").

Section 7.2.2
Declare

Identifiers may be declared and later referenced to make scene files more readable and to parametrize scenes so that changing a single declaration changes many values. There are several built-in identifiers which POV-Ray declares for you. See section "Built-in Identifiers" for details.

Section 7.2.2.1
Declaring identifiers

An identifier is declared as follows.

#declare IDENTIFIER = ITEM

Where IDENTIFIER is the name of the identifier up to 40 characters long and ITEM is any of the following

float, vector, color or string expressions objects (all kinds) texture, pigment, normal, finish or halo color_map, pigment_map, slope_map, normal_map camera, light_source atmosphere fog rainbow sky_sphere transform

Here are some examples.

#declare Rows = 5 #declare Count = Count+1 #declare Here = <1,2,3> #declare White = rgb <1,1,1> #declare Cyan = color blue 1.0 green 1.0 #declare Font_Name = "ariel.ttf" #declare Ring = torus e="ref 1009 pri 0">exp(A): Exponential of A. Returns the value of e raised to the power A where e is the base of the natural logarithm, i.e. the non-repeating value approximately equal to 2.71828182846.

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.

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 B. 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.

Section 7.1.8.3
String Functions

The following are the functions which take one or more string and float parameters and return string or float values. Assume that S1 and S2 are any valid strings and that A, L and P are any valid expressions that evaluate to floats.

asc(S1): ASCII value of S1. Returns an integer value in the range 0 to 255 that is the ASCII value of the first character of S1. For example asc("ABC") is 65 because that is the value of the character "A".

chr(A): Character whose ASCII value is A. Returns a single character string. The ASCII value of the character is specified by an integer A which must be in the range 0 to 255. For example chr(70) is the string "F". When rendering text objects you should be aware that the characters rendered for values of A > 127 are dependent on the (TTF) font being used. Many (TTF) fonts use the Latin-1 (ISO 8859-1) character set, but not all do.

concat(S1,S2,[S3...]): Concatenate strings S1 and S2. Returns a string that is the concatenation of all parameter strings. Must have at least 2 parameters but may have more. For example:

concat("Value is ", str(A,3,1), " inches")

If the float value A was 12.34 the result is "Value is 12.3 inches" which is a string.

file_exists(S1): Search for file specified by S1. Attempts to open the file whose name is specified by the string S1. The current directory and all directories specified in any Library_Path INI options or +L command line switches are searched. File is immediately closed. Returns a boolean value 1 on success and 0 on failure.

str(A,L,P): Convert float A to a formatted string. Returns a formatted string representation of float value A. The float parameter L specifies the minimum length of the string and the type of left padding used if the string's representation is shorter than the minimum. If L is positive then the padding is with blanks. If L is negative then the padding is with zeros. The overall minimum length of the formatted string is abs(L). If the string needs to be longer, it will be made as long as necessary to represent the value.

The float parameter P specifies the number of digits after the decimal point. If P is negative then a compiler-specific default precision is use. Here are some examples:

  str(123.456,0,3)   "123.456"
  str(123.456,4,3)   "123.456"
  str(123.456,9,3)   "  123.456"
  str(123.456,-9,3)  "00123.456"
  str(123.456,0,2)   "123.46"
  str(123.456,0,0)   "123"
  str(123.456,5,0)   "  123"
  str(123.000,7,2)   " 123.00"
  str(123.456,0,-1)  "123.456000" (platform specific)

strcmp(S1,S2): Compare string S1 to S2. Returns a float value zero if the strings are equal, a positive number if S1 comes after S2 in the ASCII collating sequence, else a negative number.

strlen(S1): Length of S1. Returns an integer value that is the number of characters in the string S1.

strlwr(S1): Lower case of S1. Returns a new string in which all upper case letters in the string S1 are converted to lower case. The original string is not affected. For example strlwr("Hello There!") results in "hello there!".

substr(S1,P,L): Sub-string from S1. Returns a string that is a subset of the characters in parameter S1 starting at the position specified by the integer value P for a length specified by the integer value L. For example substr("ABCDEFGHI",4,2) evaluates to the string "EF". If P+L>strlen(S1) an error occurs.

strupr(S1): Upper case of S1. Returns a new string in which all lower case letters in the string S1 are converted to upper case. The original string is not affected. For example strupr("Hello There!") results in "HELLO THERE!".

val(S1): Convert string S1 to float. Returns a float value that is represented by the text in S1. For example val("123.45") is 123.45 as a float.

Section 7.2
Language Directives

The POV Scene Language contains several statements called language directives which tell the file parser how to do its job. These directives can appear in almost any place in the scene file - even in the middle of some other statements. They are used to include other text files in the stream of commands, to declare identifiers, to define conditional or looped parsing and to control other important aspects of scene file processing.

Each directive begins with the hash character # (often called a number sign or pound sign). It is followed by a keyword and optionally other parameters.

In versions of POV-Ray prior to 3.0, the use of this # character was optional. Language directives could only be used between objects, camera or light_source statements and could not appear within those statements. The exception was the #include which could appear anywhere. Now that all language directives can be used almost anywhere, the # character is mandatory.

The following keywords introduce language directives.


#break              #default            #statistics
#case               #else               #switch
#debug              #end                #version
#declare            #render             #warning


Earlier versions of POV-Ray considered the keyword
#max_intersections and the keyword #max_trace_level to
be language directives but they have been moved to the
global_settings statement. Their use as a directive still works
but it generates a warning and may be discontinued in the future.