# Documentation:Tutorial Section 2.2

 This document is protected, so submissions, corrections and discussions should be held on this documents talk page.

### Simple Texture Options

The highlight we have added illustrates how much of our perception depends on the reflective properties of an object. Ray-tracing can exploit this by playing tricks on our perception to make us see complex details that are not really there.

Suppose we wanted a very bumpy surface on the object. It would be very difficult to mathematically model lots of bumps. We can however simulate the way bumps look by altering the way light reflects off of the surface. Reflection calculations depend on a vector called a surface normal. This is a vector which points away from the surface and is perpendicular to it. By artificially modifying (or perturbing) this normal vector we can simulate bumps. We change the scene to read as follows and render it:

```  sphere {
<0, 1, 2>, 2
texture {
pigment { color Yellow }
normal { bumps 0.4 scale 0.2 }
finish { phong 1 }
}
}
```

This tells POV-Ray to use the `bumps` pattern to modify the surface normal. The value 0.4 controls the apparent depth of the bumps. Usually the bumps are about 1 unit wide which does not work very well with a sphere of radius 2. The scale makes the bumps 1/5th as wide but does not affect their depth.

#### Creating Color Patterns

We can do more than assigning a solid color to an object. We can create complex patterns in the pigment block like in these examples:

```  sphere {
<0, 1, 2>, 2
texture {
pigment {
wood
color_map {
[0.0 color DarkTan]
[0.9 color DarkBrown]
[1.0 color VeryDarkBrown]
}
turbulence 0.05
scale <0.2, 0.3, 1>
}
finish { phong 1 }
}
}

sphere {
<0, 1, 2>, 2
texture {
pigment {
wood
color_map {
[0.0 color Red]
[0.5 color Red]
[0.5 color Blue]
[1.0 color Blue]
}
scale <0.2, 0.3, 1>
}
finish { phong 1 }
}
}
```

The keyword `wood` specifies a pigment pattern of concentric rings like rings in wood. For every position in POV-space, a pattern returns a float value in the range from zero to one. Values outside the zero to one range are ignored. The `color_map` specifies what color vector is assigned to that float value. In the first example the color of the wood blends from `DarkTan` to `DarkBrown` over the first 90% of the vein and from `DarkBrown` to `VeryDarkBrown` over the remaining 10%. In the second example the colors do not blend from one to an other, but change abrupt. The `turbulence` keyword slightly stirs up the pattern so the veins are not perfect circles and the `scale` keyword adjusts the size of the pattern.

Most patterns are set up by default to give us one feature across a sphere of radius 1.0. A feature is very roughly defined as a color transition. For example, a wood texture would have one band on a sphere of radius 1.0. In this example we scale the pattern using the `scale` keyword followed by a vector. In this case we scaled 0.2 in the x direction, 0.3 in the y direction and the z direction is scaled by 1, which leaves it unchanged. Scale values larger than one will stretch an element. Scale values smaller than one will squish an element. A scale value of one will leave an element unchanged.

#### Pre-defined Textures

POV-Ray has some very sophisticated textures pre-defined in the standard include files `glass.inc`, `metals.inc`, `stones.inc` and `woods.inc`. Some are entire textures with pigment, normal and/or finish parameters already defined. Some are just pigments or just finishes.

We change the definition of our sphere to the following and then re-render it:

```  sphere {
<0, 1, 2>, 2
texture {
pigment {
DMFWood4       // pre-defined in textures.inc
scale 4        // scale by the same amount in all
// directions
}
finish { Shiny } // pre-defined in finish.inc
}
}
```

The pigment identifier `DMFWood4` has already been scaled down quite small when it was defined. For this example we want to scale the pattern larger. Because we want to scale it uniformly we can put a single value after the scale keyword rather than a vector of x, y, z scale factors.

We look through the file `textures.inc` to see what pigments and finishes are defined and try them out. We just insert the name of the new pigment where `DMFWood4` is now or try a different finish in place of `Shiny` and re-render our file.

Here is an example of using a complete texture identifier rather than just the pieces.

```  sphere {
<0, 1, 2>, 2
texture { PinkAlabaster }
}
```

### Using the Camera

#### Using Focal Blur

Let's construct a simple scene to illustrate the use of focal blur. For this example we will use a pink sphere, a green box and a blue cylinder with the sphere placed in the foreground, the box in the center and the cylinder in the background. A checkered floor for perspective and a couple of light sources will complete the scene. We create a new file called ``` focaldem.pov``` and enter the following text

```  #include "colors.inc"
#include "shapes.inc"
#include "textures.inc"
sphere {
<1, 0, -6>, 0.5
finish {
ambient 0.1
diffuse 0.6
}
pigment { NeonPink }
}
box {
<-1, -1, -1>, < 1,  1,  1>
rotate <0, -20, 0>
finish {
ambient 0.1
diffuse 0.6
}
pigment { Green }
}
cylinder {
<-6, 6, 30>, <-6, -1, 30>, 3
finish {
ambient 0.1
diffuse 0.6
}
pigment {NeonBlue}
}
plane {
y, -1.0
pigment {
checker color Gray65 color Gray30
}
}
light_source { <5, 30, -30> color White }
light_source { <-5, 30, -30> color White }
```

Now we can proceed to place our focal blur camera to an appropriate viewing position. Straight back from our three objects will yield a nice view. Adjusting the focal point will move the point of focus anywhere in the scene. We just add the following lines to the file:

```  camera {
location <0.0, 1.0, -10.0>
look_at  <0.0, 1.0,  0.0>
//  focal_point <-6, 1, 30>    // blue cylinder in focus
//  focal_point < 0, 1,  0>    // green box in focus
focal_point < 1, 1, -6>    // pink sphere in focus
aperture 0.4     // a nice compromise
//  aperture 0.05    // almost everything is in focus
//  aperture 1.5     // much blurring
//  blur_samples 4       // fewer samples, faster to render
blur_samples 20      // more samples, higher quality image
}
```

The focal point is simply the point at which the focus of the camera is at its sharpest. We position this point in our scene and assign a value to the aperture to adjust how close or how far away we want the focal blur to occur from the focused area.

The aperture setting can be considered an area of focus. Opening up the aperture has the effect of making the area of focus smaller while giving the aperture a smaller value makes the area of focus larger. This is how we control where focal blur begins to occur around the focal point.

The blur samples setting determines how many rays are used to sample each pixel. Basically, the more rays that are used the higher the quality of the resultant image, but consequently the longer it takes to render. Each scene is different so we have to experiment. This tutorial has examples of 4 and 20 samples but we can use more for high resolution images. We should not use more samples than is necessary to achieve the desired quality - more samples take more time to render. The confidence and variance settings are covered in the section Focal Blur.

We experiment with the focal point, aperture, and blur sample settings. The scene has lines with other values that we can try by commenting out the default line with double slash marks and un-commenting the line we wish to try out. We make only one change at a time to see the effect on the scene.

Two final points when tracing a scene using a focal blur camera. We need not specify anti-aliasing because the focal blur code uses its own sampling method that automatically takes care of anti-aliasing. Focal blur can only be used with the perspective camera.

### POV-Ray Coordinate System

Objects, lights and the camera are positioned using a typical 3D coordinate system. The usual coordinate system for POV-Ray has the positive y-axis pointing up, the positive x-axis pointing to the right and the positive z-axis pointing into the screen. The negative values of the axes point the other direction as shown in the images in the section Understanding POV-Ray's Coordinate System.

Locations within that coordinate system are usually specified by a three component vector. The three values correspond to the x, y and z directions respectively. For example, the vector `<1,2,3>` means the point that is one unit to the right, two units up and three units in front of the center of the universe at `<0,0,0>`.

Vectors are not always points though. They can also refer to an amount to size, move or rotate a scene element or to modify the texture pattern applied to an object.

The size, location, orientation, and deformation of items within the coordinate system is controlled by modifiers called transformations. The follow sub-sections describe the transformations and their usage.

#### Transformations

The supported transformations are `rotate`, ``` scale```, and `translate`. They are used to turn, size and move an object or texture. A transformation matrix may also be used to specify complex transformations directly. Groups of transformations may be merged together and stored in a transformation identifier. The syntax for transformations is as follows.

```TRANSFORMATION:
rotate <Rotate_Amt> | scale <Scale_Amt> |
translate <Translate_Amt> | transform TRANSFORM_IDENTIFIER |
transform { TRANSFORMATION_BLOCK...} |
matrix <Val00, Val01, Val02,
Val10, Val11, Val12,
Val20, Val21, Val22,
Val30, Val31, Val32>
TRANSFORMATION_BLOCK:
TRANSFORM_IDENTIFIER | TRANSFORMATION | inverse
TRANSFORM_DECLARATION:
#declare IDENTIFIER = transform { TRANSFORMATION_BLOCK...} |
#local IDENTIFIER = transform { TRANSFORMATION_BLOCK...}
```
##### Translate

Items may be moved by adding a `translate` modifier. It consists of the keyword `translate` followed by a vector expression. The three terms of the vector specify the number of units to move in each of the x, y and z directions. Translate moves the element relative to its current position. For example

``` sphere { <10, 10, 10>, 1
pigment { Green }
translate <-5, 2, 1>
}
```

will move the sphere from the location `<10,10,10>` to `<5,12,11>`. It does not move it to the absolute location `<-5,2,1>`. Translations are always relative to the item's location before the move. Translating by zero will leave the element unchanged on that axis. For example:

``` sphere { <10, 10, 10>, 1
pigment { Green }
translate 3*x // evaluates to <3,0,0> so move 3 units
// in the x direction and none along y or z
}
```
##### Scale

You may change the size of an object or texture pattern by adding a ``` scale``` modifier. It consists of the keyword `scale` followed by a vector expression. The three terms of the vector specify the amount of scaling in each of the x, y and z directions.

Uneven scaling is used to stretch or squish an element. Values larger than one stretch the element on that axis while values smaller than one are used to squish it. Scale is relative to the current element size. If the element has been previously re-sized using scale then scale will size relative to the new size. Multiple scale values may used.

For example

``` sphere { <0,0,0>, 1
scale <2,1,0.5>
}
```

will stretch and smash the sphere into an ellipsoid shape that is twice the original size along the x-direction, remains the same size in the y-direction and is half the original size in the z-direction.

If a lone float expression is specified it is promoted to a three component vector whose terms are all the same. Thus the item is uniformly scaled by the same amount in all directions. For example:

``` object {
MyObject
scale 5 // Evaluates as <5,5,5> so uniformly scale
// by 5 in every direction.
}
```

When one of the scaling components is zero, POV-Ray changes this component to 1 since it assumes that 0 means no scaling in this direction. A warning "Illegal Value: Scale X, Y or Z by 0.0. Changed to 1.0." is printed then.

##### Rotate

You may change the orientation of an object or texture pattern by adding a `rotate` modifier. It consists of the keyword ` rotate` followed by a vector expression. The three terms of the vector specify the number of degrees to rotate about each of the x-, y- and z-axes.

Note: The order of the rotations does matter. Rotations occur about the x-axis first, then the y-axis, then the z-axis. If you are not sure if this is what you want then you should only rotate on one axis at a time using multiple rotation statements to get a correct rotation.

``` rotate <0, 30, 0>  // 30 degrees around Y axis then,
rotate <-20, 0, 0> // -20 degrees around X axis then,
rotate <0, 0, 10>  // 10 degrees around Z axis.
```

Rotation is always performed relative to the axis. Thus if an object is some distance from the axis of rotation it will not only rotate but it will orbit about the axis as though it was swinging around on an invisible string.

POV-Ray uses a left-handed rotation system. Using the famous Computer Graphics Aerobics exercise, you hold up your left hand and point your thumb in the positive direction of the axis of rotation. Your fingers will curl in the positive direction of rotation. Similarly if you point your thumb in the negative direction of the axis your fingers will curl in the negative direction of rotation. See Understanding POV-Ray's Coordinate System for an illustration.

##### Matrix

The `matrix` keyword can be used to explicitly specify the transformation matrix to be used for objects or textures. Its syntax is:

```MATRIX:
matrix <Val00, Val01, Val02,
Val10, Val11, Val12,
Val20, Val21, Val22,
Val30, Val31, Val32>
```

Where `Val00` through `Val32` are float expressions enclosed in angle brackets and separated by commas.

Note: This is not a vector. It is a set of 12 float expressions.

These floats specify the elements of a 4 by 4 matrix with the fourth column implicitly set to `<0,0,0,1>`. At any given point P, P=<px, py, pz>, is transformed into the point Q, Q=<qx, qy, qz> by

qx = Val00 * px + Val10 * py + Val20 * pz + Val30

qy = Val01 * px + Val11 * py + Val21 * pz + Val31

qz = Val02 * px + Val12 * py + Val22 * pz + Val32

Normally you will not use the matrix keyword because it is less descriptive than the transformation commands and harder to visualize. However the matrix command allows more general transformation effects like shearing. The following matrix causes an object to be sheared along the y-axis.

``` object {
MyObject
matrix < 1, 1, 0,
0, 1, 0,
0, 0, 1,
0, 0, 0 >
}
```

#### Transformation Order

Because rotations are always relative to the axis and scaling is relative to the origin, you will generally want to create an object at the origin and scale and rotate it first. Then you may translate it into its proper position. It is a common mistake to carefully position an object and then to decide to rotate it. However because a rotation of an object causes it to orbit about the axis, the position of the object may change so much that it orbits out of the field of view of the camera!

Similarly scaling after translation also moves an object unexpectedly. If you scale after you translate the scale will multiply the translate amount.
For example

```  translate <5, 6, 7>
scale 4
```

will translate to `<20,24,28>` instead of ``` <5,6,7>```. Be careful when transforming to get the order correct for your purposes.

#### Inverse Transform

```  transform { scale <20,24,28> translate y*3  inverse }
```

An inverse transform does the opposite of what the transform would normally do, and can be used to undo transforms without messing around with huge numbers of transformations. To do the same without this `inverse`, you would have to duplicate each transform, change them to do the opposite of what they would normally do (for example `translate -y*3` instead of `translate y*3`)and reverse their order.

#### Transform Identifiers

At times it is useful to combine together several transformations and apply them in multiple places. A transform identifier may be used for this purpose. Transform identifiers are declared as follows:

```TRANSFORM_DECLARATION:
#declare IDENTIFIER = transform{ TRANSFORMATION... } |
#local IDENTIFIER = transform{ TRANSFORMATION... }
```

Where IDENTIFIER is the name of the identifier up to 40 characters long and TRANSFORMATION is any valid transformation modifier. See #declare vs. #local for information on identifier scope. Here is an example...

```  #declare MyTrans =
transform {
rotate THISWAY
scale SOMUCH
rotate -THISWAY
scale BIGGER
translate OVERTHERE
rotate WAYAROUND
}
```

A transform identifier is invoked by the `transform` keyword with or without brackets as shown here:

```  object {
MyObject              // Get a copy of MyObject
transform MyTrans     // Apply the transformation
translate -x*5        // Then move it 5 units left
}
object {
MyObject              // Get another copy of MyObject
transform { MyTrans } // Apply the same transformation
translate x*5         // Then move this one 5 units right
}
```

On extremely complex CSG objects with lots of components it may speed up parsing if you apply a declared transformation rather than the individual `translate`, `rotate`, `scale`, or ``` matrix``` modifiers. The `transform` is attached just once to each component. Applying each individual `translate`, ``` rotate```, `scale`, or `matrix` modifiers takes longer. This only affects parsing - rendering works the same either way.

#### Transforming Textures and Objects

When an object is transformed all textures attached to the object at that time are transformed as well. This means that if you have a ``` translate```, `rotate`, `scale`, or ``` matrix``` modifier in an object before a texture, then the texture will not be transformed. If the transformation is after the texture then the texture will be transformed with the object. If the transformation is inside the `texture` statement then only the texture is affected. The shape remains the same. For example:

``` sphere { 0, 1
texture { Jade } // texture identifier from TEXTURES.INC
scale 3          // this scale affects both the
// shape and texture
}
sphere { 0, 1
scale 3          // this scale affects the shape only
}
sphere { 0, 1
texture {
scale 3        // this scale affects the texture only
}
}
```

Transformations may also be independently applied to pigment patterns and surface normal patterns.

Note: Scaling a normal pattern not only affects the width and spacing. It does also affect the apparent height or depth of the bumps, for how to avoid this see Scaling normals.

For example:

``` box { <0, 0, 0>, <1, 1, 1>
texture {
pigment {
checker Red, White
scale 0.25 // This affects only the color pattern
}
normal {
bumps 0.3 // This specifies apparent height of bumps
scale 0.2 // Scales diameter and space between bumps
// and also the height. Has no effect on
// color pattern.
}
rotate y*45 // This affects the entire texture but
}            // not the object.
}
```

### Setting POV-Ray Options

POV-Ray was originally created as a command-line program for operating systems without graphical interfaces, dialog boxes and pull-down menus. Most versions of POV-Ray still use command-line switches to tell it what to do. This documentation assumes you are using the command-line version. All graphical versions of POV-Ray provide a means of using command-line switches and INI files from within the user interface, so you can use the below options in any version of POV-Ray. There is system-specific documentation for each system describing which of these commands are also able to be set via menus or dialogs.

There are two distinct ways of setting POV-Ray options (other than through the GUI interface, if applicable) : command line switches and INI file keywords. Both are explained in detail in the following sections.

#### Command Line Switches

Command line switches consist of a `+` (plus) or ``` -``` (minus) sign, followed by one or more alphabetic characters and possibly a numeric value. Here is a typical command line with switches.

```  povray +Isimple.pov +V +W80 +H60
```

`povray` is the name of the program and it is followed by several switches. Each switch begins with a plus or minus sign. The ``` +I``` switch with the filename tells POV-Ray what scene file it should use as input and `+V` tells the program to output its status to the text screen as it is working. The `+W` and ` +H` switches set the width and height of the image in pixels. This image will be 80 pixels wide by 60 pixels high.

In switches which toggle a feature, the plus turns it on and minus turns it off. For example ` +P` turns on the pause for keypress when finished option while `-P` turns it off. Other switches are used to specify values and do not toggle a feature. Either plus or minus may be used in that instance. For example `+W320` sets the width to 320 pixels. You could also use ` -W320` and get the same results.

Switches may be specified in upper or lower case. They are read left to right but in general may be specified in any order. If you specify a switch more than once, the previous value is generally overwritten with the last specification. The only exception is the `+L` switch for setting library paths.

Almost all ` +` or `-` switches have an equivalent option which can be used in an INI file which is described in the next section. A detailed description of each switch is given in the option reference section.

#### Using INI Files

Note: Although the term 'INI file' is used by POV-Ray, this was implemented before the widespread acceptance of Microsoft Windows, and while POV-Ray's INI files are almost identical to those of Windows, there are some minor differences (the foremost being that it is legal to have multiple instances of the same item in a section). INI files are used on all platform versions of POV-Ray, not just on the Windows platform.

Because it is difficult to set more than a few options on a command line, you have the ability to put multiple options in one or more text files. These initialization files or INI files have .ini as their default extension.

The majority of options you use will be stored in INI files. The command line switches are recommended for options which you will turn off or on frequently as you perform test renderings of a scene you are developing. The file `povray.ini` is automatically read if present in the same directory as the scene; most platforms also have platform-specific INI files that are read prior to `povray.ini`. You may also specify additional INI files on the command-line by simply typing the file name on the command line. For example:

```  povray myopts.ini
```

If no extension is given, then `.ini` is assumed. POV-Ray knows this is not a switch because it is not preceded by a plus or minus.

You may have multiple INI files on the command line along with switches. For example:

```  povray myopts +V other
```

This reads options from `myopts.ini`, then sets the ``` +V``` switch, then reads options from `other.ini`.

An INI file is a plain ASCII text file with options of the form...

```  Option_keyword=VALUE ; Text after semicolon is a comment
```

For example the INI equivalent of the switch `+Isimple.pov` is...

```  Input_File_Name=simple.pov
```

Options are read top to bottom in the file but in general may be specified in any order. If you specify an option more than once, the previous values are generally overwritten with the last specification. The only exception is the `Library_Path=path` option.

Almost all INI-style options have equivalent `+` or ``` -``` switches. The option reference section gives a detailed description of all POV-Ray options. It includes both the INI-style settings and the `+`/`-` switches.

The INI keywords are not case sensitive. Only one INI option is permitted per line of text. You may also include switches in your INI file if they are easier for you. You may have multiple switches per line but you should not mix switches and INI options on the same line. You may nest INI files by simply putting the file name on a line by itself with no equals sign after it. Nesting may occur up to ten levels deep. For example:

```  ; This is a sample INI file. This entire line is a comment.
; Blank lines are permitted.
Input_File_Name=simple.pov ;This sets the input file name
+W80 +H60 ; Traditional +/- switches are permitted too
MOREOPT   ; Read MOREOPT.INI and continue with next line
+V        ; Another switch
; That's all folks!
```

INI files may have labeled sections so that more than one set of options may be stored in a single file. Each section begins with a label in [] brackets. For example:

```  ; RES.INI
; This sample INI file is used to set resolution.
+W120 +H100  ; This section has no label.
; Select it with "RES"
[Low]
+W80 +H60    ; This section has a label.
; Select it with "RES[Low]"
[Med]
+W320 +H200  ; This section has a label.
; Select it with "RES[Med]"
[High]
+W640 +H480  ; Labels are not case sensitive.
; "RES[high]" works
[Really High]
+W800 +H600  ; Labels may contain blanks
```

When you specify the INI file you should follow it with the section label in brackets. For example...

```  povray res[Med] +Imyfile.pov
```

POV-Ray reads `res.ini` and skips all options until it finds the label `Med`. It processes options after that label until it finds another label and then it skips. If no label is specified on the command line then only the unlabeled area at the top of the file is read. If a label is specified, the unlabeled area is ignored.

Note: If your shell treats '[' or ']' specially you may need to escape them.

If a file or path contains blanks the whole file and path specification has to be put in quotes. You may either use a double-quote or a single-quote, but you have to use the same at the beginning and end. For example:

``` +I"my file.pov"
+I'my file.pov'
Input_File="my file.pov"
Input_File='my file.pov'
```

By using either single or double quotes it is possible to specify files whose name or path contains either as part of the name. For example:

``` +I"file's.pov"
+I'my "big" file.pov'
Input_File="file's.pov"
Input_File='my "big" file.pov'
```

#### Using the POVINI Environment Variable

On some platforms the environment variable POVINI is used to specify the location and name of a default INI file that is read every time POV-Ray is executed. The Unix and Linux versions of POV-Ray, for example, support this whilst the Windows version does not.

If POVINI is not specified, or if your computer platform does not use environment variables, a default INI file may be read; see your platform-specific documentation for information.

On most operating systems the sequence of reading options is as follows:

1. Read options from default INI file specified by the POVINI environment variable or platform specific INI file.
2. Read switches from command line (this includes reading any specified INI files).

Note: The POVRAYOPT environment variable supported by some earlier POV-Ray versions is no longer available.

 This document is protected, so submissions, corrections and discussions should be held on this documents talk page.