# Difference between revisions of "Reference:Vector Expressions"

Jholsenback (talk | contribs) m (added note) |
m (→Operator Promotion: canonicalized a version number) |
||

Line 158: | Line 158: | ||

direction.</p> | direction.</p> | ||

<p> | <p> | ||

− | Versions of POV-Ray prior to | + | Versions of POV-Ray prior to v3.0 only allowed such use of a float as a |

vector in various limited places such as <code>scale</code> and <code> | vector in various limited places such as <code>scale</code> and <code> | ||

turbulence</code>. However you may now use this trick anywhere. For | turbulence</code>. However you may now use this trick anywhere. For |

## Latest revision as of 14:20, 9 June 2021

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.

## Literals

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.

## Identifiers

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 a valid identifier name 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 also: Identifiers and #declare vs. #local for additional information on identifier naming and 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.

## Operators

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.

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

.

## 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 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> } }

As of version 3.7 experimental support for reading the pixel resolution of an image map was added. This is done by giving an image map pigment identifier to `max_extent()`

, which will then return the resolution of the image map as the x and y values of the returned vector.

One usage of this feature would be when using an image as a background matte.

Example:

#declare MatteImage = pigment { image_map { jpeg "YourImage.jpg" } } #declare Resolution = max_extent ( MatteImage ); #declare MatteNormalizationScale = <min(1,Resolution.x/Resolution.y), min(1,Resolution.y/Resolution.x),1>; box { 0, <1,1,0.001> pigment { MatteImage } scale MatteNormalizationScale // Fit matte to unit square scale MatteSceneScale // Size matte for scene }

New in version 3.8 this functionality has been extended to support ** both** normal maps and density files.

To fit a df3 with unequal x,y,z ranges inside unit cube without distortion, the set up for the scaling variable is as follows:

#declare Density0 = density { density_file df3 "A20x30x40.df3" interpolate 0 } #declare Df3MapRange = max_extent(Density0); #declare Df3NormalizationScale = <min(1,Df3MapRange.x/max(Df3MapRange.y,Df3MapRange.z)), min(1,Df3MapRange.y/max(Df3MapRange.x,Df3MapRange.z)), min(1,Df3MapRange.z/max(Df3MapRange.x,Df3MapRange.y))>;

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

**Warning:** Using `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.

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

## Dot Item Access for Vectors

POV-Ray provides an easy method to access the individual components of different types of *vector* expressions, as illustrated in the following code examples:

#declare Vector = <1, 2>; #declare First_Component = Vector.u; #declare Second_Component = Vector.v; #declare Vector = <1, 2, 3>; #declare First_Component = Vector.x; #declare Second_Component = Vector.y; #declare Third_Component = Vector.z; #declare Vector = <1, 2, 3, 4>; #declare First_Component = Vector.x; #declare Second_Component = Vector.y; #declare Third_Component = Vector.z; #declare Fourth_Component = Vector.t;

**Note:** When dealing with non-color 4-D vectors, the `.t`

or *dot item* is NOT the same as the `.transmit`

*keyword*.

See also: Dot Item Access for Colors.