|
 |
2.2.1.4 Vector Expressions
POV-Ray often requires you to specify a vector. A vector is a set of related float values. Vectors may be
specified using literals, identifiers or functions which return vector values. You may also create very complex vector
expressions from combinations of any of these using various familiar operators.
POV-Ray vectors may have from two to five components but the vast majority of vectors have three components. Unless
specified otherwise, you should assume that the word "vector" means a three component vector. POV-Ray
operates in a 3D x, y, z coordinate system and you will use three component vectors to specify x, y and z values. In
some places POV-Ray needs only two coordinates. These are often specified by a 2D vector called an UV vector.
Fractal objects use 4D vectors. Color expressions use 5D vectors but allow you to specify 3, 4 or 5 components and use
default values for the unspecified components. Unless otherwise noted, all 2, 4 or 5 component vectors work just like
3D vectors but they have a different number of components.
The syntax for combining vector literals into vector expressions is almost identical to the rules for float
expressions. In the syntax for vector expressions below, some of the syntax items are defined in the section for float
expressions. See "Float Expressions" for those definitions.
Detailed explanations of vector-specific issues are given in the following sub-sections.
VECTOR:
NUMERIC_TERM [SIGN NUMERIC_TERM]
NUMERIC_TERM:
NUMERIC_FACTOR [MULT NUMERIC_FACTOR]
NUMERIC_FACTOR:
VECTOR_LITERAL |
VECTOR_IDENTIFIER |
SIGN NUMERIC_FACTOR |
VECTOR_FUNCTION |
VECTOR_BUILT-IN_IDENT |
( FULL_EXPRESSION ) |
! NUMERIC_FACTOR |
FLOAT
VECTOR_LITERAL:
< FLOAT , FLOAT , FLOAT >
VECTOR_FUNCTION:
min_extent ( OBJECT_IDENTIFIER ) |
max_extent ( OBJECT_IDENTIFIER ) |
trace(OBJECT_IDENTIFIER, VECTOR, VECTOR, [VECTOR_IDENTIFIER] )|
vaxis_rotate( VECTOR , VECTOR , FLOAT ) |
vcross( VECTOR , VECTOR ) |
vrotate( VECTOR , VECTOR ) |
vnormalize( VECTOR ) |
vturbulence(FLOAT, FLOAT, FLOAT, VECTOR)
VECTOR_BUILT-IN_IDENT:
x | y | z | t | u | v
Note: VECTOR_IDENTIFIERS are identifiers previously declared to have vector values.
Vector literals consist of two to five float expressions that are bracketed by angle brackets < and >.
The terms are separated by commas. For example here is a typical three component vector:
< 1.0, 3.2, -5.4578 >
The commas between components are necessary to keep the program from thinking that the 2nd term is the single float
expression 3.2-5.4578 and that there is no 3rd term. If you see an error message such as "Float
expected but '>' found instead" then you probably have missed a comma.
Sometimes POV-Ray requires you to specify floats and vectors side-by-side. The rules for vector expressions allow
for mixing of vectors with vectors or vectors with floats so commas are required separators whenever an ambiguity
might arise. For example <1,2,3>-4 evaluates as a mixed float and vector expression where 4 is
subtracted from each component resulting in <-3,-2,-1>. However the comma in
<1,2,3>,-4 means this is a vector followed by a float.
Each component may be a full float expression. For example
<This+3,That/3,5*Other_Thing>
is a valid vector.
Vector 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.
VECTOR_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 vector value.
Note: there should be a semi-colon after the expression in a vector 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 Here = <1,2,3>;
#declare There = <3,4,5>;
#declare Jump = <Foo*2,Bar-1,Bob/3>;
#declare Route = There-Here;
#declare Jump = Jump+<1,2,3>;
Note: you invoke a vector identifier by using its name without any angle brackets. As
the last example shows, you can re-declare a vector identifier and may use previously declared values in that
re-declaration. There are several built-in identifiers which POV-Ray declares for you. See section "Built-in
Vector Identifiers" for details.
Vector literals, identifiers and functions may also be combined in expressions the same as float values. Operations
are performed on a component-by-component basis. For example <1,2,3> + <4,5,6> evaluates the
same as <1+4,2+5,3+6> or <5,7,9>. Other operations are done on a similar
component-by-component basis. For example (<1,2,3> = <3,2,1>) evaluates to <0,1,0>
because the middle components are equal but the others are not. Admittedly this is not very useful but it is
consistent with other vector operations.
Conditional expressions such as (C ? A : B) require that C is a float expression but A
and B may be vector expressions. The result is that the entire conditional evaluates as a valid vector.
For example if Foo and Bar are floats then (Foo < Bar ? <1,2,3> :
<5,6,7>) evaluates as the vector <1,2,3> if Foo is less than Bar
and evaluates as <5,6,7> otherwise.
You may use the dot operator to extract a single float component from a vector. Suppose the identifier Spot
was previously defined as a vector. Then Spot.x is a float value that is the first component of this x,
y, z vector. Similarly Spot.y and Spot.z reference the 2nd and 3rd components. If Spot
was a two component UV vector you could use Spot.u and Spot.v to extract the first and
second component. For a 4D vector use .x, .y, .z, and .t to
extract each float component. The dot operator is also used in color expressions which are covered later.
2.2.1.4.4 Operator Promotion
You may use a lone float expression to define a vector whose components are all the same. POV-Ray knows when it
needs a vector of a particular type and will promote a float into a vector if need be. For example the POV-Ray scale
statement requires a three component vector. If you specify scale 5 then POV-Ray interprets this as scale
<5,5,5> which means you want to scale by 5 in every direction.
Versions of POV-Ray prior to 3.0 only allowed such use of a float as a vector in various limited places such as scale
and turbulence. However you may now use this trick anywhere. For example...
box{0,1} // Same as box{<0,0,0>,<1,1,1>}
sphere{0,1} // Same as sphere{<0,0,0>,1}
When promoting a float into a vector of 2, 3, 4 or 5 components, all components are set to the float value, however
when promoting a vector of a lower number of components into a higher order vector, all remaining components are set
to zero. For example if POV-Ray expects a 4D vector and you specify 9 the result is <9,9,9,9>
but if you specify <7,6> the result is <7,6,0,0>.
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 vector 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 vector; and F
is any float expression.
min_extent(OBJECT_IDENTIFIER), max_extent(OBJECT_IDENTIFIER). The min_extent and max_extent
return the minimum and maximum coordinates of a #declared object's bounding box (Corner1 and Corner2), in effect
allowing you to find the dimensions and location of the object.
Note: this is not perfect, in some cases (such as CSG intersections and differences
or isosurfaces) the bounding box does not represent the actual dimensions of the object.
Example:
#declare Sphere =
sphere {
<0,0,0>, 1
pigment { rgb <1,0,0> }
}
#declare Min = min_extent ( Sphere );
#declare Max = max_extent ( Sphere );
object { Sphere }
box {
Min, Max
pigment { rgbf <1,1,1,0.5> }
}
trace(OBJECT_IDENTIFIER, A, B, [VECTOR_IDENTIFIER]). trace helps you finding the exact
location of a ray intersecting with an object's surface. It traces a ray beginning at the point A in the
direction specified by the vector B. If the ray hits the specified object, this function returns the
coordinate where the ray intersected the object. If not, it returns <0,0,0>. If a fourth parameter
in the form of a vector identifier is provided, the normal of the object at the intersection point (not including any
normal perturbations due to textures) is stored into that vector. If no intersection was found, the normal vector is
reset to <0,0,0>.
Note: Checking the normal vector for <0,0,0> is the only reliable
way to determine whether an intersection has actually occurred, intersections can and do occur anywhere, including at <0,0,0>.
Example:
#declare MySphere = sphere { <0, 0, 0>, 1 }
#declare Norm = <0, 0, 0>;
#declare Start = <1, 1, 1>;
#declare Inter=
trace ( MySphere, Start, <0, 0, 0>-Start, Norm );
object {
MySphere
texture {
pigment { rgb 1}
}
}
#if (vlength(Norm)!=0)
cylinder {
Inter, Inter+Norm, .1
texture {
pigment {color red 1}
}
}
#end
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
equal to the area of the parallelogram defined by them. Or to put in an other way, the cross product can also be
formulated as: AxB = |A| * |B| * sin(angle(A,B)) * perpendicular_unit_vector(A,B) So the length
of the resulting vector is proportional to the sine of the angle between A and B. See the
animated demo scene VECT2.POV for an illustration.
vnormalize(A) Normalize vector A. Returns a unit length vector that is the same
direction as A. Formula is vnormalize(A)=A/vlength(A).
Note:vnormalize(<0,0,0>) will result in an error.
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.
vturbulence(Lambda, Omega, Octaves, A) Turbulence vector at A. Given the x,y,z coordinates of a point
in space designated by the vector A, return the turbulence vector for that point based on the numbers given for
Lambda, Omega and Octaves. For the meaning of the parameters, check out the Lambda, Omega and Octaves sections.
The amount of turbulence can be controlled by multiplying the turbulence vector by a multiple. The frequency at which
the turbulence vector changes can be controlled by multiplying A with a multiple. The turbulence vector returned by
the function can be added to the original point A to obtain a turbulated version of the point A. Example :
#declare
MyVector = MyVector + Amount * vturbulence(2, 0.5, 6, MyVector * Frequency);
See section "Float Functions" for other functions which are
somewhat vector-related but which return floats. In addition to the above built-in functions, you may also define your
own functions using the #macro directive. See the section "User
Defined Macros" for more details.
2.2.1.4.6 Built-in Constants
There are several built-in vector identifiers. You can use them to specify values or to create expressions but you
cannot re-declare them to change their values. They are:
VECTOR_BUILT-IN_IDENT:
x | y | z | t | u | v
All built-in vector identifiers never change value. They are defined as though the following lines were at the
start of every scene.
#declare x = <1, 0, 0>;
#declare y = <0, 1, 0>;
#declare z = <0, 0, 1>;
#declare t = <0, 0, 0, 1>;
#declare u = <1, 0>;
#declare v = <0, 1>;
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>.
Similarly u and v may be used in 2D vectors. When using 4D vectors you should use x,
y, z, and t and POV-Ray will promote x, y, and
z to 4D when used where 4D is required.
|
|
