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:
**vaxis_rotate(***VECTOR*`,`

*VECTOR*`,`

*FLOAT*|`)`

**vcross(***VECTOR*`,`

*VECTOR*|`)`

**vrotate(***VECTOR*`,`

*VECTOR*|`)`

**vnormalize(***VECTOR*`)`

- VECTOR_BUILT-IN_IDENT:

|**x**|`y`

|`z`

|`t`

|`u`

`v`

```
```

```
```

```
```

```
```

Note: *VECTOR_IDENTIFIERS* are identifiers previously declared to have vector values.

Vectors literals consist of two to five float expressions that are bracketed by angle brackets ** <** and

`>`

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

`<1,2,3>,-4`

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 that there should be a semi-colon after the expression in a vector declaration. This semi-colon is new with POV-Ray version 3.1. 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 that 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>`

`<5,7,9>`

`(<1,2,3> = <3,2,1>)`

`<0,1,0>`

Conditional expressions such as ** (C ? A : B)** require that

`C`

`A`

`B`

`Foo`

`Bar`

`(Foo < Bar ? <1,2,3> : <5,6,7>)`

`<1,2,3>`

`Foo`

`Bar`

`<5,6,7>`

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`

`Spot.y`

`Spot.z`

`Spot`

`Spot.u`

`Spot.v`

`.x`

`.y`

`.z`

`.t`

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`

`scale <5,5,5>`

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`

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

`<7,6>`

`<7,6,0,0>`

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`

`z`

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

`<5,0,0>`

Similarly ** u** and

`v`

`x`

`y`

`z`

`t`

`x`

`y`

`z`

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`

`F`

Rotate **vaxis_rotate(A,B,F)**** A** about

`B`

`F`

`A`

`B`

`F`

Cross product of **vcross(A,B) **** A** and

`B`

`VECT2.POV`

for an illustration.

Normalize vector **vnormalize(A) **** A**. Returns a unit length vector that is the same direction as

`A`

Rotate **vrotate(A,B) **** A** about origin by

`B`

`A`

`B`

`B.x`

`B.y`

`B.z`

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 new ** #macro** directive. See the section "User Defined Macros" for more details.