2.2.1.3 Float Expressions
Many parts of the POVRay language require you to specify one or more floating point numbers. A floating point
number is a number with a decimal point. Floats may be specified using literals, identifiers or functions which return
float values. You may also create very complex float expressions from combinations of any of these using various
familiar operators.
Where POVRay needs an integer value it allows you to specify a float value and it truncates it to an integer. When
POVRay needs a logical or boolean value it interprets any nonzero float as true and zero as false. Because float
comparisons are subject to rounding errors POVRay accepts values extremely close to zero as being false when doing
boolean functions. Typically values whose absolute values are less than a preset value epsilon are
considered false for logical expressions. The value of epsilon is system dependent but is generally about
1.0e10. Two floats a and b are considered to be equal if abs(ab) < epsilon.
The full syntax for float expressions is given below. Detailed explanations are given in the following
subsections.
FLOAT:
NUMERIC_TERM [SIGN NUMERIC_TERM]...
SIGN:
+  
NUMERIC_TERM:
NUMERIC_FACTOR [MULT NUMERIC_FACTOR]...
MULT:
*  /
NUMERIC_FACTOR:
FLOAT_LITERAL 
FLOAT_IDENTIFIER 
SIGN NUMERIC_FACTOR 
FLOAT_FUNCTION 
FLOAT_BUILTIN_IDENT 
( FULL_EXPRESSION ) 
! NUMERIC_FACTOR
VECTOR DECIMAL_POINT DOT_ITEM FLOAT_LITERAL:
[DIGIT...] [DECIMAL_POINT] DIGIT... [EXP [SIGN] DIGIT...]
DIGIT:
0  1  2  3  4  5  6  7  8  9
DECIMAL_POINT:
.
EXP:
e  E
DOT_ITEM:
x  y  z  t  u  v  red  blue  green  filter 
transmit  gray
FLOAT_FUNCTION:
abs( FLOAT )  acos( FLOAT )  acosh( FLOAT )  asc( STRING ) 
asin( FLOAT )  asinh( FLOAT )  atan( FLOAT)  atanh( FLOAT) 
atan2( FLOAT , FLOAT )  ceil( FLOAT )  cos( FLOAT ) 
cosh( FLOAT )  defined(IDENTIFIER )  degrees( FLOAT ) 
dimensions( ARRAY_IDENTIFIER ) 
dimension_size( ARRAY_IDENTIFIER , FLOAT ) 
div( FLOAT , FLOAT )  exp( FLOAT )  file_exists( STRING ) 
floor( FLOAT )  int( FLOAT )  ln(Float  log( FLOAT ) 
max( FLOAT , FLOAT, ... )  min( FLOAT , FLOAT, ... ) 
mod( FLOAT , FLOAT )  pow( FLOAT , FLOAT ) 
radians( FLOAT )  rand( FLOAT )  seed( FLOAT ) 
select( FLOAT, FLOAT, FLOAT [,FLOAT])  sin( FLOAT ) 
sinh( FLOAT )  sqrt( FLOAT )  strcmp( STRING , STRING ) 
strlen( STRING )  tan( FLOAT )  tanh( FLOAT ) 
val( STRING )  vdot( VECTOR , VECTOR )  vlength( VECTOR ) 
FLOAT_BUILTIN_IDENT:
clock  clock_delta  clock_on  false  final_clock 
final_frame  frame_number  initial_clock  initial_frame 
image_width  image_height  no  off  on  pi  true 
version  yes 
FULL_EXPRESSION:
LOGICAL_EXPRESSION [? FULL_EXPRESSION : FULL_EXPRESSION]
LOGICAL_EXPRESSION:
REL_TERM [LOGICAL_OPERATOR REL_TERM]...
LOGICAL_OPERATOR:
&   (note: this means an ampersand or a
vertical bar is a logical operator)
REL_TERM:
FLOAT [REL_OPERATOR FLOAT]...
REL_OPERATOR:
<  <=  =  >=  >  !=
INT:
FLOAT (note: any syntax which requires a
integer INT will accept a FLOAT
and it will be truncated to an
integer internally by POVRay).
Note: FLOAT_IDENTIFIERS are identifiers previously declared to have float
values. The DOT_ITEM syntax is actually a vector or color operator but it returns a float value. See "Vector
Operators" or "Color Operators" for details. An ARRAY_IDENTIFIER is just the identifier
name of a previously declared array, it does not include the [] braces nor the index. The syntax for STRING
is in the section "Strings".
Float literals are represented by an optional sign ("+" or "") digits, an optional decimal
point and more digits. If the number is an integer you may omit the decimal point and trailing zero. If it is all
fractional you may omit the leading zero. POVRay supports scientific notation for very large or very small numbers.
The following are all valid float literals:
2.0 4 34 3.4e6 2e5 .3 0.6
Float 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.
FLOAT_DECLARATION:
#declare IDENTIFIER = EXPRESSION; 
#local 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 float value.
Note: there should be a semicolon after the expression in a float declaration. If
omitted, it generates a warning and some macros may not work properly. See " #declare
vs. #local" for information on identifier scope.
Here are some examples.
#declare Count = 0;
#declare Rows = 5.3;
#declare Cols = 6.15;
#declare Number = Rows*Cols;
#declare Count = Count+1;
As the last example shows, you can redeclare a float identifier and may use previously declared values in that
redeclaration. There are several builtin identifiers which POVRay declares for you. See "Float Expressions: Builtin
Variables" for details.
Arithmetic expressions: Basic math expressions can be created from float literals, identifiers or
functions using the following operators in this order of precedence...
Arithmetic expressions
( )

expressions in parentheses first

+A A !A

unary minus, unary plus and logical "not"

A*B A/B

multiplication and division

A+B AB

addition and subtraction

Relational, logical and conditional expressions may also be created. However there is a restriction that these
types of expressions must be enclosed in parentheses first. This restriction, which is not imposed by most computer
languages, is necessary because POVRay allows mixing of float and vector expressions. Without the parentheses there
is an ambiguity problem. Parentheses are not required for the unary logical not operator "!" as shown above.
The operators and their precedence are shown here.
Relational expressions: The operands are arithmetic expressions and the result is always boolean
with 1 for true and 0 for false. All relational operators have the same precedence.
Relational expressions
(A < B)

A is less than B

(A <= B)

A is less than or equal to B

(A = B)

A is equal to B (actually abs(AB)<EPSILON)

(A != B)

A is not equal to B (actually abs(AB)>=EPSILON)

(A >= B)

A is greater than or equal to B

(A > B)

A is greater than B

Logical expressions: The operands are converted to boolean values of 0 for false and 1 for true.
The result is always boolean. All logical operators have the same precedence.
Note: these are not bitwise operations, they are logical.
Logical expressions
(A & B)

true only if both A and B are true, false otherwise

(A  B)

true if either A or B or both are true

Conditional expressions: The operand C is boolean while operands A and B are any expressions. The
result is of the same type as A and B.
Conditional expressions
(C ? A : B)

if C then A else B

Assuming the various identifiers have been declared, the following are examples of valid expressions...
1+2+3 2*5 1/3 Row*3 Col*5
(Offset5)/2 This/That+Other*Thing
((This<That) & (Other>=Thing)?Foo:Bar)
Expressions are evaluated left to right with innermost parentheses evaluated first, then unary +,  or !, then
multiply or divide, then add or subtract, then relational, then logical, then conditional.
POVRay defines a variety of builtin 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.O is an
object identifier to a predeclared object.
abs(A) Absolute value of A . If A
is negative, returns A otherwise returns A .
acos(A) Arccosine of A . Returns the
angle, measured in radians, whose cosine is A .
acosh(A) inverse hyperbolic cosine of 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) Arcsine of A . Returns the
angle, measured in radians, whose sine is A .
asinh(A) invers hyperbolic sine of A
atan2(A,B) Arctangent 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.
atanh(A) invers hyperbolic tangent of A
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.
cosh(A) The hyperbolic cosine of A .
defined( IDENTIFIER)
Returns true if the identifier is currently defined, false otherwise. This is especially
useful for detecting endoffile after a #read directive because the file identifier is automatically
undefined when endoffile 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 lefttoright 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 nonrepeating 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.
inside(O,V) It returns either 0.0, when the vector V
is outside the object, specified by the objectidentifier O , or 1.0 if it is inside.
Note: inside does not accept objectidentifiers to nonsolid objects.
int(A) Integer part of A . Returns the
truncated integer part of A . Rounds towards zero.
log(A) Logarithm of A . Returns the
logarithm base 10 of the value A .
ln(A) Natural logarithm of A . Returns
the natural logarithm base e of the value A .
max(A,B,...) Maximum of two or more float values.
Returns A if A larger than B . Otherwise returns B .
min(A,B,...) Minimum of two or more float values.
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 .
Note:For a negative A and a noninteger B the function has no defined return
value. The result then may depend on the platform POVRay is compiled on.
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 pseudorandom 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(I) Initializes a new pseudorandom stream with
the initial seed value A . The number corresponding to this random stream is returned. Any number of
pseudorandom 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.
select(A, B, C [,D]) . It can be used with three or
four parameters. Select compares the first argument with zero, depending on the outcome it will return B ,
C or D . A,B,C,D can be floats or funtions. When used with three parameters,
if A < 0 it will return B , else C (A >= 0 ). When used
with four parameters, if A < 0 it will return B. If A = 0 it will return C .
Else it will return D (A > 0 ).
Example: If A has the consecutive values 2, 1, 0, 1, and 2 :
// A = 2 1 0 1 2
select (A, 1, 0, 1) //returns 1 1 0 1 1
select (A, 1, 1) //returns 1 1 1 1 1
sin(A) Sine of A . Returns the sine of
the angle A , where A is measured in radians.
sinh(A) The hyperbolic sine of A .
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.
tanh(A) The hyperbolic tangent of A .
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 .
It is directly proportional to the length of the two vectors and the cosine of the angle between them. 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(V2V1) .
See section "Vector Functions" and section "String
Functions" for other functions which are somewhat floatrelated but which return vectors and strings. In
addition to the above builtin functions, you may also define your own functions using the #macro
directive. See the section "User Defined Macros" for more
details.
2.2.1.3.5 Builtin Constants
Constants are:
FLOAT_BUILTIN_IDENT:
false  no  off  on  pi  true  yes
The builtin constants 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;
The builtin float identifier pi is obviously useful in math expressions involving circles. The
builtin float identifiers on , off , yes , no , true ,
and false are designed for use as boolean constants.
The builtin float constats on , off , yes , no , true ,
and false are most often used as boolean values with object modifiers or parameters such as sturm ,
hollow , hierarchy ,
smooth , media_attenuation ,
and media_interaction . Whenever you see syntax of the form keyword
[Bool] , if you simply specify the keyword without the optional boolean then it assumes keyword
on . You need not use the boolean but for readability it is a good idea. You must use one of the false booleans
or an expression which evaluates to zero to turn it off.
Note: some of these keywords are on by default, if no keyword is
specified.
For example:
object { MyBlob } // sturm defaults off, but
// hierarchy defaults on
object { MyBlob sturm } // turn sturm on
object { MyBlob sturm on } // turn sturm on
object { MyBlob sturm off } // turn sturm off
object { MyBlob hierarchy } // does nothing, hierarchy was
// already on
object { MyBlob hierarchy off } // turn hierarchy off
2.2.1.3.6 Builtin Variables
There are several builtin float variables. You can use them to specify values or to create expressions but you
cannot redeclare them to change their values.
Clockrelated are:
FLOAT_BUILTIN_IDENT:
clock  clock_delta  clock_on  final_clock  final_frame
frame_number  initial_clock  initial_frame
These keywords allow to use the values of the clock which have been set in the command line switch options (or
INIfile). They represent float or integer values, read from the animation options. You cannot redeclare these
identifiers.
clock The builtin float identifier clock is used to control
animations in POVRay. Unlike some animation packages, the action in POVRay animated scenes does not depend upon the
integer frame numbers. Rather you should design your scenes based upon the float identifier clock . For
nonanimated 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 commandline switch +K n.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 yaxis from 0 to 360 degrees.
Although the value of clock will change from frametoframe, it will never change throughout the
parsing of a scene.
clock_delta The builtin float identifier clock_delta returns the
amount of time between clock values in animations in POVRay. While most animations only need the clock value itself,
some animation calculations are easier if you know how long since the last frame. Caution must be used when designing
such scenes. If you render a scene with too few frames, the results may be different than if you render with more
frames in a given time period. On nonanimated scenes, clock_delta defaults to 1.0. See section "Animation
Options" for more details.
clock_on With this identifier the status of the clock can be checked: 1 is on, 0
is off.
#if(clock_on=0)
//stuff for still image
#else
//some animation
#end
frame_number If you rather want to define the action in POVRay animated scenes
depending upon the integer frame numbers, this identifier can be used. It reads the number of the frame currently
being rendered.
#if(frame_number=1)
//stuff for first image or frame
#end
#if(frame_number=2)
//stuff for second image or frame
#end
#if(frame_number=n)
//stuff for n th image or frame
#end
initial_clock This identifier reads the value set through the INI file option Initial_Clock= n.n
or the commandline switch +KI n.n.
final_clock This identifier reads the value set through the INI file option Final_Clock= n.n
or the commandline switch +KF n.n.
initial_frame This identifier reads the value set through the INI file option Initial_Frame= n
or the commandline switch +KFI n.
final_frame This identifier reads the value set through the INI file option Final_Frame= n
or the commandline switch +KFF n.
Note: that these values are the ones actually used. When the option 'cyclic
animation' is set, they could be different from the ones originally set in the options.
Imagesize are:
FLOAT_BUILTIN_IDENT:
image_width  image_height
image_width This identifier reads the value set through the INI file option Width= n
or the commandline switch +W n.
image_height This identifier reads the value set through the INI file option Height= n
or the commandline switch +H n.
You could use these keywords to set the camera ratio (up and right vectors) correctly. The viewing angle of the
camera covers the full width of the rendered image. The camera ratio will always follow the ratio of the image width
to height, regardless of the set image size. Use it like this:
up y*image_height
right x*image_width
You could also make some items of the scene dependent on the image size:
#if (image_width < 300) crand 0.1 #else crand 0.5 #end
or:
image_map {
pattern image_width, image_width { //make pattern resolution
gradient x //dependent of render width
color_map { [ 0.0 ... ] [ 1.0 ... ] }
}
}
Version is:
FLOAT_BUILTIN_IDENT:
version
The builtin float variable version contains the current setting of the version compatibility option.
Although this value defaults to the current POVRay version number, the initial value of version may be
set by the INI file option Version= n.n or by the +MV n.n commandline
switch. This tells POVRay to parse the scene file using syntax from an earlier version of POVRay.
The INI option or switch only affects the initial setting. Unlike other builtin 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 builtin version identifier the #version directive allows you to save
and restore the previous values of this compatibility setting. The new #local identifier option is
especially useful here. For example suppose mystuff.inc is in version 1 format. At the top of the file
you could put:
#local 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
Note: there should be a semicolon after the float expression in a #version
directive. If omitted, it generates a warning and some macros may not work properly.
More about "Strings"
