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 section "Vector Functions" and section "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 B is 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 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.

Next Section
Table Of Contents