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

Adding Bumpiness

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 a valid identifier name and TRANSFORMATION is any valid transformation modifier.

Here is an example...

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

See also: Identifiers and #declare vs. #local for additional information on identifier naming and scope.

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
  texture { Jade }
 }
 sphere { 0, 1
  texture {
   Jade
   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.

Surface Finishes

Advanced Features

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