Previous:Boolean Keywords   Main Index   Next:Vector Expressions

#### Float Functions

POV-Ray defines a variety of built-in functions for manipulating floats, vectors and strings. 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)`

The following are the functions which return float values. They take one or more float, integer, vector, or string parameters. Assume that `A` and `B` are any valid expression that evaluates to a float; `I` is a float which is truncated to integer internally, `S`, `S1`, `S2` etc. are strings, and `V`, `V1`, `V2` etc. are any vector expressions.

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

`asc(S) `Returns an integer value in the range 0 to 255 that is the ASCII value of the first character of the string `S`. For example `asc("ABC")` is 65 because that is the value of the character "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.

`defined(`IDENTIFIER `) `Returns `true` if the identifier is currently defined, `false` otherwise. This is especially useful for detecting end-of-file after a `#read` directive because the file identifer is automatically undefined when end-of-file is reached. See "The #read Directive" for details.

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

`dimensions(` ARRAY_IDENTIFIER `) `Returns the number of dimensions of a previously declared array identifier. For example if you do `#declare MyArray=array[6][10]` then `dimensions(MyArray)` returns the value `2`.

`dimension_size(` ARRAY_IDENTIFIER, FLOAT `) `Returns the size of a given dimension of a previously declared array identifier. Dimensions are numbered left-to-right starting with 1. For example if you do `#declare MyArray=array[6][10]` then `dimension_size(MyArray,2)` returns the value `10`.

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

`file_exists(S) `Attempts to open the file specified by the string `S`. The current directory and all library directories specified by the `Library_Path` or `+L` options are also searched. See "Library Paths" for details. Returns `1` if successful and `0` if unsuccessful.

`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(I) `Returns the next pseudo-random number from the stream specified by the positive integer `I`. 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.

`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(S) `Length of `S`. Returns an integer value that is the number of characters in the string `S`.

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

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

`vdot(V1,V2) `Dot product of `V1` and `V2`. Returns a float value that is the dot product (sometimes called scalar product of `V1` with `V2`. Formula is vdot=V1.x*V2.x + V1.y*V2.y + V1.z*V2.z. See the animated demo scene `VECT2.POV` for an illustration.

`vlength(V) `Length of `V`. Returns a float value that is the length of vector `V`. Formula is vlength=sqrt(vdot(A,A)). Can be used to compute the distance between two points. `Dist=vlength(V2-V1)`.

See section "Vector Functions" and section "String Functions" for other functions which are somewhat float-related but which return vectors and strings. In addition to the above built-in functions, you may also define your own functions using the new `#macro` directive. See the section "User Defined Macros" for more details.

Previous:Boolean Keywords   Main Index   Next:Vector Expressions