File: t2_3.html

package info (click to toggle)
povray 1%3A3.7.0.10-3
links: PTS, VCS
area: main
in suites: forky, sid, trixie
size: 147,232 kB
sloc: cpp: 845,011; ansic: 122,118; sh: 34,204; pascal: 6,420; asm: 3,355; ada: 1,681; makefile: 1,389; cs: 879; awk: 590; perl: 245; xml: 95
file content (11182 lines) | stat: -rw-r--r-- 447,736 bytes
parent folder | download | duplicates (4)
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">

<!--  This file copyright Persistence of Vision Raytracer Pty. Ltd. 2009-2011  -->

<html lang="en">
<head>
<meta http-equiv=Content-Type content="text/html; charset=windows-1252">
<title>Tutorial Section 3</title>
<link rel="StyleSheet" href="povray37.css" type="text/css">
<link rel="shortcut icon" href="favicon.ico">

<!--  NOTE: In order to help users find information about POV-Ray using web      -->
<!--  search engines, we ask that you *not* let them index documentation         -->
<!--  mirrors because effectively, when searching, users will get hundreds of    -->
<!--  results containing the same information! For this reason, these meta tags  -->
<!--  below disable archiving of this page by search engines.                    -->

<meta name="robots" content="noarchive">
<meta http-equiv="Pragma" content="no-cache">
<meta http-equiv="expires" content="0">
</head>
<body>

<div class="Page">

<!-- NavPanel Begin -->
<div class="NavPanel">
<table class="NavTable">
<tr>
  <td class="FixedPanelHeading"><a title="2.3" href="#t2_3">Advanced Features</a></td>
</tr>
<tr>
  <td><div class="divh2"><strong><a title="2.3.1" href="#t2_3_1">Spline Based Shapes</a></strong></div></td>
</tr>
<tr>
  <td><div class="divh3"><a title="2.3.1.1" href="#t2_3_1_1">Lathe Object</a></div></td>
</tr>
<tr>
  <td><div class="divh4"><a title="2.3.1.1.1" href="#t2_3_1_1_1">Understanding The Concept of Splines</a></div></td>
</tr>
<tr>
  <td><div class="divh3"><a title="2.3.1.2" href="#t2_3_1_2">Surface of Revolution Object</a></div></td>
</tr>
<tr>
  <td><div class="divh3"><a title="2.3.1.3" href="#t2_3_1_3">Prism Object</a></div></td>
</tr>
<tr>
  <td><div class="divh4"><a title="2.3.1.3.1" href="#t2_3_1_3_1">Teaching An Old Spline New Tricks</a></div></td>
</tr>
<tr>
  <td><div class="divh4"><a title="2.3.1.3.2" href="#t2_3_1_3_2">Smooth Transitions</a></div></td>
</tr>
<tr>
  <td><div class="divh4"><a title="2.3.1.3.3" href="#t2_3_1_3_3">Multiple Sub-Shapes</a></div></td>
</tr>
<tr>
  <td><div class="divh4"><a title="2.3.1.3.4" href="#t2_3_1_3_4">Conic Sweeps And The Tapering Effect</a></div></td>
</tr>
<tr>
  <td><div class="divh3"><a title="2.3.1.4" href="#t2_3_1_4">Sphere Sweep Object</a></div></td>
</tr>
<tr>
  <td><div class="divh3"><a title="2.3.1.5" href="#t2_3_1_5">Bicubic Patch Object</a></div></td>
</tr>
<tr>
  <td><div class="divh3"><a title="2.3.1.6" href="#t2_3_1_6">Text Object</a></div></td>
</tr>
<tr>
  <td><div class="divh2"><strong><a title="2.3.2" href="#t2_3_2">Polygon Based Shapes</a></strong></div></td>
</tr>
<tr>
  <td><div class="divh3"><a title="2.3.2.1" href="#t2_3_2_1">Mesh Object</a></div></td>
</tr>
<tr>
  <td><div class="divh3"><a title="2.3.2.2" href="#t2_3_2_2">Mesh2 Object</a></div></td>
</tr>
<tr>
  <td><div class="divh4"><a title="2.3.2.2.1" href="#t2_3_2_2_1">Smooth triangles and mesh2</a></div></td>
</tr>
<tr>
  <td><div class="divh4"><a title="2.3.2.2.2" href="#t2_3_2_2_2">UV mapping and mesh2</a></div></td>
</tr>
<tr>
  <td><div class="divh4"><a title="2.3.2.2.3" href="#t2_3_2_2_3">A separate texture per triangle</a></div></td>
</tr>
<tr>
  <td><div class="divh3"><a title="2.3.2.3" href="#t2_3_2_3">Polygon Object</a></div></td>
</tr>
<tr>
  <td><div class="divh2"><strong><a title="2.3.3" href="#t2_3_3">Other Shapes</a></strong></div></td>
</tr>
<tr>
  <td><div class="divh3"><a title="2.3.3.1" href="#t2_3_3_1">Blob Object</a></div></td>
</tr>
<tr>
  <td><div class="divh4"><a title="2.3.3.1.1" href="#t2_3_3_1_1">Component Types and Other New Features</a></div></td>
</tr>
<tr>
  <td><div class="divh4"><a title="2.3.3.1.2" href="#t2_3_3_1_2">Complex Blob Constructs and Negative Strength</a></div></td>
</tr>
<tr>
  <td><div class="divh3"><a title="2.3.3.2" href="#t2_3_3_2">Height Field Object</a></div></td>
</tr>
<tr>
  <td><div class="divh3"><a title="2.3.3.3" href="#t2_3_3_3">Isosurface Object</a></div></td>
</tr>
<tr>
  <td><div class="divh4"><a title="2.3.3.3.1" href="#t2_3_3_3_1">Simple functions</a></div></td>
</tr>
<tr>
  <td><div class="divh4"><a title="2.3.3.3.2" href="#t2_3_3_3_2">Several surfaces</a></div></td>
</tr>
<tr>
  <td><div class="divh4"><a title="2.3.3.3.3" href="#t2_3_3_3_3">Non-linear functions</a></div></td>
</tr>
<tr>
  <td><div class="divh4"><a title="2.3.3.3.4" href="#t2_3_3_3_4">Specifying functions</a></div></td>
</tr>
<tr>
  <td><div class="divh4"><a title="2.3.3.3.5" href="#t2_3_3_3_5">Internal functions</a></div></td>
</tr>
<tr>
  <td><div class="divh4"><a title="2.3.3.3.6" href="#t2_3_3_3_6">Combining isosurface functions</a></div></td>
</tr>
<tr>
  <td><div class="divh4"><a title="2.3.3.3.7" href="#t2_3_3_3_7">Noise and pigment functions</a></div></td>
</tr>
<tr>
  <td><div class="divh4"><a title="2.3.3.3.8" href="#t2_3_3_3_8">Conditional directives and loops</a></div></td>
</tr>
<tr>
  <td><div class="divh4"><a title="2.3.3.3.9" href="#t2_3_3_3_9">Transformations on functions</a></div></td>
</tr>
<tr>
  <td><div class="divh4"><a title="2.3.3.3.10" href="#t2_3_3_3_10">Improving Isosurface Speed</a></div></td>
</tr>
<tr>
  <td><div class="divh3"><a title="2.3.3.4" href="#t2_3_3_4">Poly Object</a></div></td>
</tr>
<tr>
  <td><div class="divh4"><a title="2.3.3.4.1" href="#t2_3_3_4_1">Creating the polynomial function</a></div></td>
</tr>
<tr>
  <td><div class="divh4"><a title="2.3.3.4.2" href="#t2_3_3_4_2">Writing the polynomial vector</a></div></td>
</tr>
<tr>
  <td><div class="divh4"><a title="2.3.3.4.3" href="#t2_3_3_4_3">Polynomial made easy</a></div></td>
</tr>
<tr>
  <td><div class="divh3"><a title="2.3.3.5" href="#t2_3_3_5">Superquadric Ellipsoid Object</a></div></td>
</tr>
<tr>
  <td><div class="divh2"><strong><a title="2.3.4" href="#t2_3_4">Gamma Handling</a></strong></div></td>
</tr>
<tr>
  <td><div class="divh3"><a title="2.3.4.1" href="#t2_3_4_1">Setting Up Your Display</a></div></td>
</tr>
<tr>
  <td><div class="divh3"><a title="2.3.4.2" href="#t2_3_4_2">Setting Up POV-Ray</a></div></td>
</tr>
<tr>
  <td><div class="divh3"><a title="2.3.4.3" href="#t2_3_4_3">Gamma in Output Images</a></div></td>
</tr>
<tr>
  <td><div class="divh3"><a title="2.3.4.4" href="#t2_3_4_4">Setting Up Your Scene</a></div></td>
</tr>
<tr>
  <td><div class="divh3"><a title="2.3.4.5" href="#t2_3_4_5">Gamma in Literal Colors</a></div></td>
</tr>
<tr>
  <td><div class="divh3"><a title="2.3.4.6" href="#t2_3_4_6">Gamma in Input Images</a></div></td>
</tr>
<tr>
  <td><div class="divh3"><a title="2.3.4.7" href="#t2_3_4_7">Gamma in Legacy Scenes</a></div></td>
</tr>
<tr>
  <td><div class="divh2"><strong><a title="2.3.5" href="#t2_3_5">Advanced Texture Options</a></strong></div></td>
</tr>
<tr>
  <td><div class="divh3"><a title="2.3.5.1" href="#t2_3_5_1">Pigments</a></div></td>
</tr>
<tr>
  <td><div class="divh4"><a title="2.3.5.1.1" href="#t2_3_5_1_1">Using Color List Pigments</a></div></td>
</tr>
<tr>
  <td><div class="divh4"><a title="2.3.5.1.2" href="#t2_3_5_1_2">Using Pigment and Patterns</a></div></td>
</tr>
<tr>
  <td><div class="divh4"><a title="2.3.5.1.3" href="#t2_3_5_1_3">Using Pattern Modifiers</a></div></td>
</tr>
<tr>
  <td><div class="divh4"><a title="2.3.5.1.4" href="#t2_3_5_1_4">Using Transparent Pigments and Layered Textures</a></div></td>
</tr>
<tr>
  <td><div class="divh4"><a title="2.3.5.1.5" href="#t2_3_5_1_5">Using Pigment Maps</a></div></td>
</tr>
<tr>
  <td><div class="divh3"><a title="2.3.5.2" href="#t2_3_5_2">Normals</a></div></td>
</tr>
<tr>
  <td><div class="divh4"><a title="2.3.5.2.1" href="#t2_3_5_2_1">Using Basic Normal Modifiers</a></div></td>
</tr>
<tr>
  <td><div class="divh4"><a title="2.3.5.2.2" href="#t2_3_5_2_2">Blending Normals</a></div></td>
</tr>
<tr>
  <td><div class="divh4"><a title="2.3.5.2.3" href="#t2_3_5_2_3">Slope Map Tutorial</a></div></td>
</tr>
<tr>
  <td><div class="divh5"><a title="2.3.5.2.3.1" href="#t2_3_5_2_3_1">Slopes, what are they?</a></div></td>
</tr>
<tr>
  <td><div class="divh5"><a title="2.3.5.2.3.2" href="#t2_3_5_2_3_2">Syntax of a slope map</a></div></td>
</tr>
<tr>
  <td><div class="divh5"><a title="2.3.5.2.3.3" href="#t2_3_5_2_3_3">Examples of slope maps</a></div></td>
</tr>
<tr>
  <td><div class="divh3"><a title="2.3.5.3" href="#t2_3_5_3">Finishes</a></div></td>
</tr>
<tr>
  <td><div class="divh4"><a title="2.3.5.3.1" href="#t2_3_5_3_1">Using Ambient</a></div></td>
</tr>
<tr>
  <td><div class="divh4"><a title="2.3.5.3.2" href="#t2_3_5_3_2">Using Emission</a></div></td>
</tr>
<tr>
  <td><div class="divh4"><a title="2.3.5.3.3" href="#t2_3_5_3_3">Using Surface Highlights</a></div></td>
</tr>
<tr>
  <td><div class="divh4"><a title="2.3.5.3.4" href="#t2_3_5_3_4">Using Reflection, Metallic and Metallic</a></div></td>
</tr>
<tr>
  <td><div class="divh4"><a title="2.3.5.3.5" href="#t2_3_5_3_5">Using Iridescence</a></div></td>
</tr>
<tr>
  <td><div class="divh3"><a title="2.3.5.4" href="#t2_3_5_4">Working With Pigment Maps</a></div></td>
</tr>
<tr>
  <td><div class="divh3"><a title="2.3.5.5" href="#t2_3_5_5">Working With Normal Maps</a></div></td>
</tr>
<tr>
  <td><div class="divh3"><a title="2.3.5.6" href="#t2_3_5_6">Working With Texture Maps</a></div></td>
</tr>
<tr>
  <td><div class="divh3"><a title="2.3.5.7" href="#t2_3_5_7">Working With List Textures</a></div></td>
</tr>
<tr>
  <td><div class="divh3"><a title="2.3.5.8" href="#t2_3_5_8">What About Tiles?</a></div></td>
</tr>
<tr>
  <td><div class="divh3"><a title="2.3.5.9" href="#t2_3_5_9">Average Function</a></div></td>
</tr>
<tr>
  <td><div class="divh3"><a title="2.3.5.10" href="#t2_3_5_10">Working With Layered Textures</a></div></td>
</tr>
<tr>
  <td><div class="divh4"><a title="2.3.5.10.1" href="#t2_3_5_10_1">Declaring Layered Textures</a></div></td>
</tr>
<tr>
  <td><div class="divh4"><a title="2.3.5.10.2" href="#t2_3_5_10_2">Another Layered Textures Example</a></div></td>
</tr>
<tr>
  <td><div class="divh3"><a title="2.3.5.11" href="#t2_3_5_11">When All Else Fails: Material Maps</a></div></td>
</tr>
<tr>
  <td><div class="divh3"><a title="2.3.5.12" href="#t2_3_5_12">Limitations Of Special Textures</a></div></td>
</tr>
<tr>
  <td><div class="divh2"><strong><a title="2.3.6" href="#t2_3_6">Using Atmospheric Effects</a></strong></div></td>
</tr>
<tr>
  <td><div class="divh3"><a title="2.3.6.1" href="#t2_3_6_1">The Background</a></div></td>
</tr>
<tr>
  <td><div class="divh3"><a title="2.3.6.2" href="#t2_3_6_2">The Sky Sphere</a></div></td>
</tr>
<tr>
  <td><div class="divh4"><a title="2.3.6.2.1" href="#t2_3_6_2_1">Creating a Sky with a Color Gradient</a></div></td>
</tr>
<tr>
  <td><div class="divh4"><a title="2.3.6.2.2" href="#t2_3_6_2_2">Adding the Sun</a></div></td>
</tr>
<tr>
  <td><div class="divh4"><a title="2.3.6.2.3" href="#t2_3_6_2_3">Adding Some Clouds</a></div></td>
</tr>
<tr>
  <td><div class="divh3"><a title="2.3.6.3" href="#t2_3_6_3">The Fog</a></div></td>
</tr>
<tr>
  <td><div class="divh4"><a title="2.3.6.3.1" href="#t2_3_6_3_1">A Constant Fog</a></div></td>
</tr>
<tr>
  <td><div class="divh4"><a title="2.3.6.3.2" href="#t2_3_6_3_2">Setting a Minimum Translucency</a></div></td>
</tr>
<tr>
  <td><div class="divh4"><a title="2.3.6.3.3" href="#t2_3_6_3_3">Creating a Filtering Fog</a></div></td>
</tr>
<tr>
  <td><div class="divh4"><a title="2.3.6.3.4" href="#t2_3_6_3_4">Adding Some Turbulence to the Fog</a></div></td>
</tr>
<tr>
  <td><div class="divh4"><a title="2.3.6.3.5" href="#t2_3_6_3_5">Using Ground Fog</a></div></td>
</tr>
<tr>
  <td><div class="divh4"><a title="2.3.6.3.6" href="#t2_3_6_3_6">Using Multiple Layers of Fog</a></div></td>
</tr>
<tr>
  <td><div class="divh4"><a title="2.3.6.3.7" href="#t2_3_6_3_7">Fog and Hollow Objects</a></div></td>
</tr>
<tr>
  <td><div class="divh3"><a title="2.3.6.4" href="#t2_3_6_4">The Rainbow</a></div></td>
</tr>
<tr>
  <td><div class="divh4"><a title="2.3.6.4.1" href="#t2_3_6_4_1">Starting With a Simple Rainbow</a></div></td>
</tr>
<tr>
  <td><div class="divh4"><a title="2.3.6.4.2" href="#t2_3_6_4_2">Increasing the Rainbow's Translucency</a></div></td>
</tr>
<tr>
  <td><div class="divh4"><a title="2.3.6.4.3" href="#t2_3_6_4_3">Using a Rainbow Arc</a></div></td>
</tr>
<tr>
  <td><div class="divh2"><strong><a title="2.3.7" href="#t2_3_7">Simple Media Tutorial</a></strong></div></td>
</tr>
<tr>
  <td><div class="divh3"><a title="2.3.7.1" href="#t2_3_7_1">Types of media</a></div></td>
</tr>
<tr>
  <td><div class="divh3"><a title="2.3.7.2" href="#t2_3_7_2">Some media concepts</a></div></td>
</tr>
<tr>
  <td><div class="divh3"><a title="2.3.7.3" href="#t2_3_7_3">Simple media examples</a></div></td>
</tr>
<tr>
  <td><div class="divh4"><a title="2.3.7.3.1" href="#t2_3_7_3_1">Emitting media</a></div></td>
</tr>
<tr>
  <td><div class="divh4"><a title="2.3.7.3.2" href="#t2_3_7_3_2">Absorbing media</a></div></td>
</tr>
<tr>
  <td><div class="divh4"><a title="2.3.7.3.3" href="#t2_3_7_3_3">Scattering media</a></div></td>
</tr>
<tr>
  <td><div class="divh3"><a title="2.3.7.4" href="#t2_3_7_4">Multiple medias inside the same object</a></div></td>
</tr>
<tr>
  <td><div class="divh3"><a title="2.3.7.5" href="#t2_3_7_5">Media and transformations</a></div></td>
</tr>
<tr>
  <td><div class="divh3"><a title="2.3.7.6" href="#t2_3_7_6">A more advanced example of scattering media</a></div></td>
</tr>
<tr>
  <td><div class="divh3"><a title="2.3.7.7" href="#t2_3_7_7">Media and photons</a></div></td>
</tr>
<tr>
  <td><div class="divh2"><strong><a title="2.3.8" href="#t2_3_8">Radiosity</a></strong></div></td>
</tr>
<tr>
  <td><div class="divh3"><a title="2.3.8.1" href="#t2_3_8_1">Introduction</a></div></td>
</tr>
<tr>
  <td><div class="divh3"><a title="2.3.8.2" href="#t2_3_8_2">Radiosity with conventional lighting</a></div></td>
</tr>
<tr>
  <td><div class="divh3"><a title="2.3.8.3" href="#t2_3_8_3">Radiosity without conventional lighting</a></div></td>
</tr>
<tr>
  <td><div class="divh3"><a title="2.3.8.4" href="#t2_3_8_4">Normals and Radiosity</a></div></td>
</tr>
<tr>
  <td><div class="divh3"><a title="2.3.8.5" href="#t2_3_8_5">Performance considerations</a></div></td>
</tr>
<tr>
  <td><div class="divh2"><strong><a title="2.3.9" href="#t2_3_9">Making Animations</a></strong></div></td>
</tr>
<tr>
  <td><div class="divh3"><a title="2.3.9.1" href="#t2_3_9_1">The Clock Variable: Key To It All</a></div></td>
</tr>
<tr>
  <td><div class="divh3"><a title="2.3.9.2" href="#t2_3_9_2">Clock Dependant Variables And Multi-Stage Animations</a></div></td>
</tr>
<tr>
  <td><div class="divh3"><a title="2.3.9.3" href="#t2_3_9_3">The Phase Keyword</a></div></td>
</tr>
<tr>
  <td><div class="divh3"><a title="2.3.9.4" href="#t2_3_9_4">Do Not Use Jitter Or Crand</a></div></td>
</tr>
<tr>
  <td><div class="divh3"><a title="2.3.9.5" href="#t2_3_9_5">INI File Settings</a></div></td>
</tr>
<tr>
  <td><div class="divh2"><strong><a title="2.3.10" href="#t2_3_10">While-loop tutorial</a></strong></div></td>
</tr>
<tr>
  <td><div class="divh3"><a title="2.3.10.1" href="#t2_3_10_1">What a while-loop is and what it is not</a></div></td>
</tr>
<tr>
  <td><div class="divh3"><a title="2.3.10.2" href="#t2_3_10_2">How does a single while-loop work?</a></div></td>
</tr>
<tr>
  <td><div class="divh3"><a title="2.3.10.3" href="#t2_3_10_3">How do I make a while-loop?</a></div></td>
</tr>
<tr>
  <td><div class="divh3"><a title="2.3.10.4" href="#t2_3_10_4">What is a condition and how do I make one?</a></div></td>
</tr>
<tr>
  <td><div class="divh3"><a title="2.3.10.5" href="#t2_3_10_5">What about loop types other than simple for-loops?</a></div></td>
</tr>
<tr>
  <td><div class="divh3"><a title="2.3.10.6" href="#t2_3_10_6">What about nested loops?</a></div></td>
</tr>
<tr>
  <td><div class="divh3"><a title="2.3.10.7" href="#t2_3_10_7">Mixed-type nested loops</a></div></td>
</tr>
<tr>
  <td><div class="divh3"><a title="2.3.10.8" href="#t2_3_10_8">Other things to note</a></div></td>
</tr>
<tr>
  <td><div class="divh2"><strong><a title="2.3.11" href="#t2_3_11">SDL tutorial: A raytracer</a></strong></div></td>
</tr>
<tr>
  <td><div class="divh3"><a title="2.3.11.1" href="#t2_3_11_1">Introduction</a></div></td>
</tr>
<tr>
  <td><div class="divh3"><a title="2.3.11.2" href="#t2_3_11_2">The idea and the code</a></div></td>
</tr>
<tr>
  <td><div class="divh3"><a title="2.3.11.3" href="#t2_3_11_3">Short introduction to raytracing</a></div></td>
</tr>
<tr>
  <td><div class="divh3"><a title="2.3.11.4" href="#t2_3_11_4">Global settings</a></div></td>
</tr>
<tr>
  <td><div class="divh3"><a title="2.3.11.5" href="#t2_3_11_5">Scene definition</a></div></td>
</tr>
<tr>
  <td><div class="divh3"><a title="2.3.11.6" href="#t2_3_11_6">Initializing the raytracer</a></div></td>
</tr>
<tr>
  <td><div class="divh3"><a title="2.3.11.7" href="#t2_3_11_7">Ray-sphere intersection</a></div></td>
</tr>
<tr>
  <td><div class="divh4"><a title="2.3.11.7.1" href="#t2_3_11_7_1">Inner workings of a macro</a></div></td>
</tr>
<tr>
  <td><div class="divh4"><a title="2.3.11.7.2" href="#t2_3_11_7_2">The ray-sphere intersection macro</a></div></td>
</tr>
<tr>
  <td><div class="divh3"><a title="2.3.11.8" href="#t2_3_11_8">The Trace macro</a></div></td>
</tr>
<tr>
  <td><div class="divh4"><a title="2.3.11.8.1" href="#t2_3_11_8_1">Calculating the closest intersection</a></div></td>
</tr>
<tr>
  <td><div class="divh4"><a title="2.3.11.8.2" href="#t2_3_11_8_2">If the ray doesn't hit anything</a></div></td>
</tr>
<tr>
  <td><div class="divh4"><a title="2.3.11.8.3" href="#t2_3_11_8_3">Initializing color calculations</a></div></td>
</tr>
<tr>
  <td><div class="divh4"><a title="2.3.11.8.4" href="#t2_3_11_8_4">Going through the light sources</a></div></td>
</tr>
<tr>
  <td><div class="divh4"><a title="2.3.11.8.5" href="#t2_3_11_8_5">Shadow test</a></div></td>
</tr>
<tr>
  <td><div class="divh4"><a title="2.3.11.8.6" href="#t2_3_11_8_6">Diffuse lighting</a></div></td>
</tr>
<tr>
  <td><div class="divh4"><a title="2.3.11.8.7" href="#t2_3_11_8_7">Specular lighting</a></div></td>
</tr>
<tr>
  <td><div class="divh4"><a title="2.3.11.8.8" href="#t2_3_11_8_8">Reflection Calculation</a></div></td>
</tr>
<tr>
  <td><div class="divh3"><a title="2.3.11.9" href="#t2_3_11_9">Calculating the image</a></div></td>
</tr>
<tr>
  <td><div class="divh3"><a title="2.3.11.10" href="#t2_3_11_10">Creating the colored mesh</a></div></td>
</tr>
<tr>
  <td><div class="divh4"><a title="2.3.11.10.1" href="#t2_3_11_10_1">The structure of the mesh</a></div></td>
</tr>
<tr>
  <td><div class="divh4"><a title="2.3.11.10.2" href="#t2_3_11_10_2">Creating the mesh</a></div></td>
</tr>
<tr>
  <td><div class="divh4"><a title="2.3.11.10.3" href="#t2_3_11_10_3">Creating the vertex points</a></div></td>
</tr>
<tr>
  <td><div class="divh4"><a title="2.3.11.10.4" href="#t2_3_11_10_4">Creating the textures</a></div></td>
</tr>
<tr>
  <td><div class="divh4"><a title="2.3.11.10.5" href="#t2_3_11_10_5">Creating the triangles</a></div></td>
</tr>
<tr>
  <td><div class="divh3"><a title="2.3.11.11" href="#t2_3_11_11">The Camera-setup</a></div></td>
</tr>
<tr>
  <td><div class="divh1">&nbsp;</div></td>
</tr>
<tr>
  <td><div class="divh1">&nbsp;</div></td>
</tr>
</table>
</div>
<!-- NavPanel End -->

<div class="Content">
<table class="HeaderFooter" width="100%">
<tr>
  <td colspan=5 align="left" class="HeaderFooter">
    POV-Ray for Unix <strong class="HeaderFooter">version 3.7</strong>
  </td>
</tr>
<tr >
  <td colspan=5>
    <hr align="right" width="70%">
  </td>
</tr>
<tr>
  <td width="30%"></td>
  <td class="NavBar"><a href="index.html" title="The Front Door">Home</a></td>
  <td class="NavBar"><a href="u1_0.html" title="Unix Table of Contents">POV-Ray for Unix</a></td>
  <td class="NavBar"><a href="t2_0.html" title="Tutorial Table of Contents">POV-Ray Tutorial</a></td>
  <td class="NavBar"><a href="r3_0.html" title="Reference Table of Contents">POV-Ray Reference</a></td>
</tr>
</table>

<a name="t2_3"></a>
<div class="content-level-h2" contains="Advanced Features" id="t2_3">
<h2>2.3 Advanced Features</h2>
</div>
<a name="t2_3_1"></a>
<div class="content-level-h3" contains="Spline Based Shapes" id="t2_3_1">
<h3>2.3.1 Spline Based Shapes</h3>
<p>After we have gained some experience with the simpler shapes available in
POV-Ray it is time to go on to the more advanced, thrilling shapes.</p>
<p>
We should be aware that the shapes described in this and the following two chapters are not trivial to
understand. We need not be worried though if we do not know how to use
them or how they work. We just try the examples and play with the features
described in the reference chapter. There is nothing better than learning by
doing.</p>
<p>
You may wish to skip to the chapter <a href="t2_2.html#t2_2_5">Simple Texture Options</a>
before proceeding with these advanced shapes.</p>

</div>
<a name="t2_3_1_1"></a>
<div class="content-level-h4" contains="Lathe Object" id="t2_3_1_1">
<h4>2.3.1.1 Lathe Object</h4>
<p>In the real world, <code><a href="r3_4.html#r3_4_5_1_8">lathe</a></code> refers to a process of making patterned rounded shapes by spinning the source material in place and carving pieces out as it turns. The results can be elaborate, smoothly rounded, elegant looking artefacts such as table legs, pottery, etc. In POV-Ray, a lathe object is used for creating much the same kind of items, although we are referring to the object itself rather than the means of production.</p>
<p>
Here is some source for a really basic lathe.</p>
<pre>
  #include &quot;colors.inc&quot;
  background{White}
  camera {
    angle 10
    location &lt;1, 9, -50&gt;
    look_at &lt;0, 2, 0&gt;
  }
  light_source {
    &lt;20, 20, -20&gt; color White
  }
  lathe {
    linear_spline
    6,
    &lt;0,0&gt;, &lt;1,1&gt;, &lt;3,2&gt;, &lt;2,3&gt;, &lt;2,4&gt;, &lt;0,4&gt;
    pigment { Blue }
    finish {
      ambient .3
      phong .75
    }
  }
</pre>

<table class="centered" width="700px" cellpadding="0" cellspacing="10">
<tr>
  <td>
    <p>We render this, and what we see is a fairly simply type of lathe, which looks like a child's top. Let's take a look at how this code produced the effect.</p>
    <p>First, a set of six points is declared which the raytracer connects with lines. We note that there are only two components in the vectors which describe these points. The lines that are drawn are assumed to be in the x-y-plane, therefore it is as if all the z-components were assumed to be zero. The use of a two-dimensional vector is mandatory, attempting to use a 3D vector would trigger an error... with one exception, which we will explore later in the discussion of splines.</p>
    <p>Once the lines are determined, the ray-tracer rotates this line around the y-axis, and we can imagine a trail being left through space as it goes, with the surface of that trail being the surface of our object.</p>
    <p>The specified points are connected with straight lines because we used the <code>linear_spline</code> keyword. There are other types of splines available with the lathe, which will result in smooth curving lines, and even rounded curving points of transition, but we will get back to that in a moment.</p>
  </td>
  <td>
    <img class="center" width="320px" src="images/6/61/TutImgLatheobj.png">
  </td>
</tr>
<tr>
  <td>
  </td>
  <td>
    <p class="caption">A simple lathe object.</p>
</td>
</tr>
</table>


<p>
First, we would like to digress a moment to talk about the difference
between a lathe and a surface of revolution object (SOR). The SOR object,
described in a separate tutorial, may seem terribly similar to the lathe at
first glance. It too declares a series of points and connects them with
curving lines and then rotates them around the y-axis. The lathe has certain
advantages, such as different kinds of splines, linear, quadratic and cubic,
and one more thing:</p>
<p>
The simpler mathematics used by a SOR does not allow the curve to double
back over the same y-coordinates, thus, if using a SOR, any sudden twist
which cuts back down over the same heights that the curve previously covered
will trigger an error. For example, suppose we wanted a lathe to arc up from
&lt;0,0&gt; to &lt;2,2&gt;, then to dip back down to &lt;4,0&gt;. Rotated
around the y-axis, this would produce something like a gelatin mold - a
rounded semi torus, hollow in the middle. But with the SOR, as soon as the
curve doubled back on itself in the y-direction, it would become an illegal
declaration.</p>
<p>
Still, the SOR has one powerful strong point: because it uses simpler order
mathematics, it generally tends to render faster than an equivalent lathe. So
in the end, it is a matter of: we use a SOR if its limitations will allow, but
when we need a more flexible shape, we go with the lathe instead.</p>
</div>
<a name="t2_3_1_1_1"></a>
<div class="content-level-h5" contains="Understanding The Concept of Splines" id="t2_3_1_1_1">
<h5>2.3.1.1.1 Understanding The Concept of Splines</h5>
<p>It would be helpful, in order to understand splines, if we had a sort of <em>Spline Workshop</em> where we could practice manipulating types and points of splines and see what the effects were like. So let's make one! Now that we know how to create a basic lathe, it will be easy:</p>
<pre>
#include &quot;colors.inc&quot;
  camera {
    orthographic
    up &lt;0, 5, 0&gt;
    right &lt;5, 0, 0&gt;
    location &lt;2.5, 2.5, -100&gt;
    look_at &lt;2.5, 2.5, 0&gt;
  }
  /* set the control points to be used */
  #declare Red_Point    = &lt;1.00, 0.00&gt;;
  #declare Orange_Point = &lt;1.75, 1.00&gt;;
  #declare Yellow_Point = &lt;2.50, 2.00&gt;;
  #declare Green_Point  = &lt;2.00, 3.00&gt;;
  #declare Blue_Point   = &lt;1.50, 4.00&gt;;
  /* make the control points visible */
  cylinder { Red_Point, Red_Point - &lt;0,0,20&gt;, .1
    pigment { Red }
    finish { ambient 1 }
  }
  cylinder { Orange_Point, Orange_Point - &lt;0,0,20&gt;, .1
    pigment { Orange }
    finish { ambient 1 }
  }
  cylinder { Yellow_Point, Yellow_Point - &lt;0,0,20&gt;, .1
    pigment { Yellow }
    finish { ambient 1 }
  }
  cylinder { Green_Point, Green_Point - &lt;0,0,20&gt;, .1
    pigment { Green }
    finish { ambient 1 }
  }
  cylinder { Blue_Point, Blue_Point- &lt;0,0,20&gt;, .1
    pigment { Blue }
    finish { ambient 1 }
  }
  /* something to make the curve show up */
  lathe {
    linear_spline
    5,
    Red_Point,
    Orange_Point,
    Yellow_Point,
    Green_Point,
    Blue_Point
    pigment { White }
    finish { ambient 1 }
  }
</pre>

<table class="centered" width="700px" cellpadding="0" cellspacing="10">
<tr>
  <td>
    <img class="center" width="320px" src="images/b/b4/TutImgSpline.png">
  </td>
  <td>
    <p>Now, we take a deep breath. We know that all looks a bit weird, but with some simple explanations, we can easily see what all this does.</p>
    <p>First, we are using the orthographic camera. If we have not read up on that yet, a quick summary is: it renders the scene <em>flat</em>, eliminating perspective distortion so that in a side view. The objects look like they were drawn on a piece of graph paper, like in the side view of a modeler or CAD package. There are several uses for this practical type of camera, but here it is allowing us to see our lathe and cylinders <em>edge on</em>, so that what we see is almost like a cross section of the curve which makes the lathe, rather than the lathe itself. To further that effect, we eliminated shadowing with the <code>ambient 1</code> finish, which of course also eliminates the need for lighting. We have also positioned this particular side view so that &lt;0,0&gt; appears at the lower left of our scene.</p> 
  </td>
</tr>
<tr>
  <td>
    <p class="caption">A simple Spline Workshop</p>
  </td>
  <td>
  </td>
</tr>
</table>

<p>Next, we declared a set of points. We note that we used 3D vectors for these points rather than the 2D vectors we expect in a lathe. That is the exception we mentioned earlier. When we declare a 3D point, then use it in a lathe, the lathe only uses the first two components of the vector, and whatever is in the third component is simply ignored. This is handy here, since it makes this example possible.</p>

<p>Next we do two things with the declared points. First we use them to place small diameter cylinders at the locations of the points with the circular caps facing the camera. Then we re-use those same vectors to determine the lathe.</p>

<p>Since trying to declare a 2D vector can have some odd results, and is not really what our cylinder declarations need anyway, we can take advantage of the lathe's tendency to ignore the third component by just setting the z-coordinate in these 3D vectors to zero.</p>

<p>The end result is: when we render this code, we see a white lathe against a black background showing us how the curve we have declared looks, and the circular ends of the cylinders show us where along the x-y-plane our control points are. In this case, it is very simple. The linear spline has been used so our curve is just straight lines zig-zagging between the points.</p>

<table class="centered" width="700px" cellpadding="0" cellspacing="10">
<tr>
  <td>
    <img class="center" width="320px" src="images/6/61/TutImgMvspline.png">
  </td>
  <td>
    <p>We change the declarations of <code>Red_Point</code> and <code>Blue_Point</code> to read as follows:</p>

<pre>
  #declare Red_Point  = &lt;2.00, 0.00&gt;;
  #declare Blue_Point = &lt;0.00, 4.00&gt;;
</pre>

    <p>We re-render and, as we can see, all that happens is that the straight line segments just move to accommodate the new position of the red and blue points. Linear splines are so simple, we could manipulate them in our sleep, no?</p>
  </td>
</tr>
<tr>
  <td>
    <p class="caption">Moving some points of the spline.</p>
  </td>
  <td>
  </td>
</tr>
</table>
<p>Now let's examine the different types of splines that the lathe object supports: </p>
<table class="centered" width="700px" cellpadding="0" cellspacing="10">
<tr>
  <td>
    <img class="center" width="320px" src="images/6/66/TutImgQuspline.png">
  </td>
  <td>
    <p>First, we change the points to the following.</p>
<pre>
  #declare Red_Point    = &lt;1.00, 0.00&gt;;
  #declare Orange_Point = &lt;2.00, 1.00&gt;;
  #declare Yellow_Point = &lt;3.50, 2.00&gt;;
  #declare Green_Point  = &lt;2.00, 3.00&gt;;
  #declare Blue_Point   = &lt;1.50, 4.00&gt;;
</pre>
    <p>We then find the lathe declaration and change <code>linear_spline</code> to <code>quadratic_spline</code>. We re-render and what do we have? Well, there is a couple of things worthy of note this time. First, we will see that instead of straight lines we have smooth arcs connecting the points. These arcs are made from quadratic curves, so our lathe looks much more
interesting this time. Also, <code>Red_Point</code> is no longer connected to the curve. What happened?</p>
  </td>
<tr>
  <td>
    <p class="caption">A quadratic spline lathe.</p>
  </td>
  <td>
  </td>
</tr>
</table>

<p>Well, while any two points can determine a straight line, it takes three to determine a quadratic curve. POV-Ray looks not only to the two points to be connected, but to the point immediately preceding them to determine the formula of the quadratic curve that will be used to connect them. The problem comes in at the beginning of the curve. Beyond the first point in the curve there is no <em>previous</em> point. So we need to declare one. Therefore, when using a quadratic spline, we must remember that the first point we specify is only there so that POV-Ray can determine what curve to connect the first two points with. It will not show up as part of the actual curve.</p>

<p>There is just one more thing about this lathe example. Even though our curve is now put together with smooth curving lines, the transitions between those lines is... well, kind of choppy, no? This curve looks like the lines between each individual point have been terribly mismatched. Depending on what we are trying to make, this could be acceptable, or, we might need a more smoothly curving shape. Fortunately, if the latter is true, we have another option.</p>

<p>The quadratic spline takes longer to render than a linear spline. The math is more complex. Taking longer still is the cubic spline, yet for a really smoothed out shape this is the only way to go. We go back into our example, and simply replace <code>quadratic_spline</code> with <code>cubic_spline</code>.  We render one more time, and take a look at what we have.</p>

<table class="centered" width="700px" cellpadding="0" cellspacing="10">
<tr>
  <td>
    <img class="center" width="320px" src="images/0/09/TutImgCuspline.png">
  </td>
  <td>
    <p> While a quadratic spline takes three points to determine the curve, a cubic needs four. So, as we might expect, <code>Blue_Point</code> has now dropped out of the curve, just as <code>Red_Point</code> did, as the first and last points of our curve are now only control points for shaping the curves between the remaining points. But look at the transition from <code>
Orange_Point</code> to <code>Yellow_Point</code> and then back to <code>Green_Point</code>. Now, rather than looking mismatched, our curve segments look like one smoothly joined curve.</p>
  </td>
<tr>
  <td>
    <p class="caption">A cubic spline lathe.</p>
  </td>
  <td></td>
</tr>
</table>

<p>Finally there is another kind of quadratic spline, the <code>bezier_spline</code>. This one takes four points per section. The start point, the end points and in between, two control points. To use it, we will have to make a few changes to our work shop. Delete the Yellow point, delete the Yellow cylinder. Change the points to:</p>
<pre>
  #declare Red_Point    = &lt;2.00, 1.00&gt;;
  #declare Orange_Point = &lt;3.00, 1.50&gt;;
  #declare Green_Point  = &lt;3.00, 3.50&gt;;
  #declare Blue_Point   = &lt;2.00, 4.00&gt;;
</pre>
<p>And change the lathe to:</p>
<pre>
  lathe {
    bezier_spline
    4,
    Red_Point,
    Orange_Point,
    Green_Point,
    Blue_Point
    pigment { White }
    finish { ambient 1 }
  }
</pre>
<table class="centered" width="700px" cellpadding="0" cellspacing="10">
<tr>
  <td>
    <img class="center" width="320px" src="images/e/ed/TutImgBezspline1.png">
  </td>
  <td>
    <p> The green and orange control points are not connected to the curve. Move them around a bit, for example:</p>
<pre>
#declare Orange_Point = &lt;1.00, 1.50&gt;;
</pre>
<p>The line that can be drawn from the start point to its closest control point (red to orange) shows the tangent of the curve at the start point. Same for the end point, blue to green.</p>
  </td>
<tr>
  <td>
    <p class="caption">A bezier spline lathe.</p>
  </td>
  <td></td>
</tr>
</table>

<p> One spline segment is nice, two is nicer. So we will add another segment and connect it to the blue point. One segment has four points, so two segments have eight. The first point of the second segment is the same as the last point of the first segment. The blue point. So we only have to declare three more points. Also we have to move the camera a bit and add more cylinders. Here is the complete scene again:</p>
<pre>
#include &quot;colors.inc&quot;
  camera {
    orthographic
    up &lt;0, 7, 0&gt;
    right &lt;7, 0, 0&gt;
    location &lt;3.5, 4, -100&gt;
    look_at &lt;3.5, 4, 0&gt;
  }
  /* set the control points to be used */
  #declare Red_Point    = &lt;2.00, 1.00&gt;;
  #declare Orange_Point = &lt;1.00, 1.50&gt;;
  #declare Green_Point  = &lt;3.00, 3.50&gt;;
  #declare Blue_Point   = &lt;2.00, 4.00&gt;;
  #declare Green_Point2 = &lt;3.00, 4.50&gt;;
  #declare Orange_Point2= &lt;1.00, 6.50&gt;;
  #declare Red_Point2   = &lt;2.00, 7.00&gt;;
  /* make the control points visible */

  cylinder { Red_Point, Red_Point - &lt;0,0,20&gt;, .1
    pigment { Red } finish { ambient 1 }
  }
  cylinder { Orange_Point, Orange_Point - &lt;0,0,20&gt;, .1
    pigment { Orange } finish { ambient 1 }
  }
  cylinder { Green_Point, Green_Point - &lt;0,0,20&gt;, .1
    pigment { Green } finish { ambient 1 }
  }
  cylinder { Blue_Point, Blue_Point- &lt;0,0,20&gt;, .1
    pigment { Blue } finish { ambient 1 }
  }
  cylinder { Green_Point2, Green_Point2 - &lt;0,0,20&gt;, .1
    pigment { Green } finish { ambient 1 }
  }
  cylinder { Orange_Point2, Orange_Point2 - &lt;0,0,20&gt;, .1
    pigment { Orange } finish { ambient 1 }
  }
  cylinder { Red_Point2, Red_Point2 - &lt;0,0,20&gt;, .1
    pigment { Red } finish { ambient 1 }
  }  
  /* something to make the curve show up */
  lathe {
    bezier_spline
    8,
    Red_Point, Orange_Point, Green_Point, Blue_Point
    Blue_Point, Green_Point2, Orange_Point2, Red_Point2
    pigment { White }
    finish { ambient 1 }
  }
</pre>

<table class="centered" width="700px" cellpadding="0" cellspacing="10">
<tr>
  <td>
    <img class="center" width="320px" src="images/d/db/TutImgBezspline2.png">
  </td>
  <td>
    <p>A nice curve, but what if we want a smooth curve? Let us have a look at the tangents on the <code>Blue_Point</code>, draw the lines <code>Green_Point</code>, <code>Blue_Point</code> and <code>Green_Point2</code>, <code>Blue_Point</code>. Look at the angle they make, it is as sharp as the dent in the curve. What if we make the angle bigger? What if we make the angle 180°?</p>
  </td>
</tr>
<tr>
  <td>
    <p class="caption">Two bezier spline segments, not smooth.</p>
  </td>
  <td></td>
</tr>
</table>
<p> Try a few positions for <code>Green_Point2</code> and end with:</p>
<pre>
#declare Green_Point2 = &lt;1.00, 4.50&gt;;
</pre>
<table class="centered" width="700px" cellpadding="0" cellspacing="10">
<tr>
  <td>
    <img class="center" width="320px" src="images/6/61/TutImgBezspline3.png">
  </td>
  <td>
    <p>It's a smooth curve. If we make sure that the two control points and the connection point are on one line, the curve is perfectly smooth.</p>
  </td>
</tr>
<tr>
  <td>
    <p class="caption">A smooth bezier spline lathe.</p>
  </td>
  <td></td>
</tr>
</table>
<p>In general this can be achieved by:</p>
<pre>
#declare Green_Point2 = Blue_Point&nbsp;+&nbsp;(Blue_Point&nbsp;-&nbsp;Green_Point);
</pre>
<p>The concept of splines is a handy and necessary one, which will be seen again in the prism and polygon objects. It's easy to see, that with a little tinkering, how quickly we can get a feel for working with splines.</p>

</div>
<a name="t2_3_1_2"></a>
<div class="content-level-h4" contains="Surface of Revolution Object" id="t2_3_1_2">
<h4>2.3.1.2 Surface of Revolution Object</h4>
<p>Bottles, vases and glasses make nice objects in ray-traced scenes. We want
to create a golden cup using the <em>surface of revolution</em> object (SOR
object).</p>
<p>
We first start by thinking about the shape of the final object. It is quite
difficult to come up with a set of points that describe a given curve without
the help of a modeling program supporting POV-Ray's surface of revolution
object. If such a program is available we should take advantage of it.</p>

<table class="centered" width="660px" cellpadding="0" cellspacing="10">
  <tr>
    <td><img class="center" width="640px" src="images/e/e7/TutImgPtcubobj.gif"></td>
  </tr>
  <tr>
    <td>
      <p class="caption">The point configuration of our cup object.</p>
    </td>
  </tr>
</table>

<p>We will use the point configuration shown in the figure above. There are eight points describing the curve that will be rotated about the y-axis to get our cup. The curve was calculated using the method described in the
reference section (see <a href="r3_4.html#r3_4_5_1_15">Surface of Revolution</a>).</p>
<p>
Now it is time to come up with a scene that uses the above SOR object. We
create a file called <code>sordemo.pov</code> and enter the following text.</p>
<pre>
  #include &quot;colors.inc&quot;
  #include &quot;golds.inc&quot;
  camera {
    location &lt;10, 15, -20&gt;
    look_at &lt;0, 5, 0&gt;
    angle 45
  }
  background { color rgb&lt;0.2, 0.4, 0.8&gt;  }
  light_source { &lt;100, 100, -100&gt; color rgb 1 }
  plane {
    y, 0
    pigment { checker color Red, color Green scale 10 }
  }
  sor {
    8,
    &lt;0.0,  -0.5&gt;,
    &lt;3.0,   0.0&gt;,
    &lt;1.0,   0.2&gt;,
    &lt;0.5,   0.4&gt;,
    &lt;0.5,   4.0&gt;,
    &lt;1.0,   5.0&gt;,
    &lt;3.0,  10.0&gt;,
    &lt;4.0,  11.0&gt;
    open
    texture { T_Gold_1B }
  }
</pre>

<p>The scene contains our cup object resting on a checkered plane. Tracing
this scene results in the image below.</p>

<table class="centered" width="340px" cellpadding="0" cellspacing="10">
  <tr>
    <td><img class="center" width="320px" src="images/9/9f/TutImgSorobj.png"></td>
  </tr>
  <tr>
    <td>
      <p class="caption">A surface of revolution object.</p>
    </td>
  </tr>
</table>

<p>The surface of revolution is described by starting with the number of
points followed by the points. Points from second to last but one are listed
with ascending heights. Each of them determines the radius of the curve for
a given height. E. g. the first valid point (second listed) tells POV-Ray
that at height 0.0 the radius is 3. We should take care that each point has
a larger height than its predecessor. If this is not the case the program
will abort with an error message. First and last point from the list are
used to determine slope at beginning and end of curve and can be defined for
any height.</p>

</div>
<a name="t2_3_1_3"></a>
<div class="content-level-h4" contains="Prism Object" id="t2_3_1_3">
<h4>2.3.1.3 Prism Object</h4>
<p>The prism is essentially a polygon or closed curve which is swept along a
linear path. We can imagine the shape so swept leaving a trail in space, and
the surface of that trail is the surface of our prism. The curve or polygon
making up a prism's face can be a composite of any number of sub-shapes,
can use any kind of three different splines, and can either keep a constant
width as it is swept, or slowly tapering off to a fine point on one end. But
before this gets too confusing, let's start one step at a time with the
simplest form of prism. We enter and render the following POV code (see file
<code>prismdm1.pov</code>).</p>
<pre>
  #include &quot;colors.inc&quot;
  background{White}
  camera {
    angle 20
    location &lt;2, 10, -30&gt;
    look_at &lt;0, 1, 0&gt;
  }
  light_source { &lt;20, 20, -20&gt; color White }
  prism {
    linear_sweep
    linear_spline
    0, // sweep the following shape from here ...
    1, // ... up through here
    7, // the number of points making up the shape ...
    &lt;3,5&gt;, &lt;-3,5&gt;, &lt;-5,0&gt;, &lt;-3,-5&gt;, &lt;3, -5&gt;, &lt;5,0&gt;, &lt;3,5&gt;
    pigment { Green }
  }
</pre>

<table class="centered" width="340px" cellpadding="0" cellspacing="10">
  <tr>
    <td><img class="center" width="320px" src="images/4/45/TutImgHexprism.png"></td>
  </tr>
  <tr>
    <td>
      <p class="caption">A hexagonal prism shape.</p>
    </td>
  </tr>
</table>

<p>This produces a hexagonal polygon, which is then swept from y=0 through
y=1. In other words, we now have an extruded hexagon. One point to note is
that although this is a six sided figure, we have used a total of seven
points. That is because the polygon is supposed to be a closed shape, which
we do here by making the final point the same as the first. Technically, with
linear polygons, if we did not do this, POV-Ray would automatically join
the two ends with a line to force it to close, although a warning would be
issued. However, this only works with linear splines, so we must not get
too casual about those warning messages!</p>

</div>
<a name="t2_3_1_3_1"></a>
<div class="content-level-h5" contains="Teaching An Old Spline New Tricks" id="t2_3_1_3_1">
<h5>2.3.1.3.1 Teaching An Old Spline New Tricks</h5>
<p>If we followed the section on splines covered under the lathe tutorial
(see the section <a href="t2_3.html#t2_3_1_1_1">Understanding The Concept of Splines</a>), we know that
there are two additional kinds of splines besides linear: the quadratic and
the cubic spline. Sure enough, we can use these with prisms to make a more
free form, smoothly curving type of prism.</p>
<p>
There is just one catch, and we should read this section carefully to keep
from tearing our hair out over mysterious <em>too few points in prism</em>
messages which keep our prism from rendering. We can probably guess where
this is heading: how to close a non-linear spline. Unlike the linear spline,
which simply draws a line between the last and first points if we forget to
make the last point equal to the first, quadratic and cubic splines are a
little more fussy.</p>
<p>
First of all, we remember that quadratic splines determine the equation of
the curve which connects any two points based on those two points and the
previous point, so the first point in any quadratic spline is just <em>
control point</em> and will not actually be part of the curve. What this
means is: when we make our shape out of a quadratic spline, we must match the
second point to the last, since the first point is not on the curve -
it is just a control point needed for computational purposes.</p>
<p>
Likewise, cubic splines need both the first and last points to be control
points, therefore, to close a shape made with a cubic spline, we must match
the second point to the second from last point. If we do not match the
correct points on a quadratic or cubic shape, that is when we will get the
<em>too few points in prism</em> error. POV-Ray is still waiting for us to
close the shape, and when it runs out of points without seeing the closure,
an error is issued.</p>
<p>
Confused? Okay, how about an example? We replace the prism in our last bit
of code with this one (see file <code>prismdm2.pov</code>).</p>
<pre>
  prism {
    cubic_spline
    0, // sweep the following shape from here ...
    1, // ... up through here
    6, // the number of points making up the shape ...
    &lt; 3, -5&gt;, // point#1 (control point... not on curve)
    &lt; 3,  5&gt;, // point#2  ... THIS POINT ...
    &lt;-5,  0&gt;, // point#3
    &lt; 3, -5&gt;, // point#4
    &lt; 3,  5&gt;, // point#5 ... MUST MATCH THIS POINT
    &lt;-5,  0&gt;  // point#6 (control point... not on curve)
    pigment { Green }
  }
</pre>

<table class="centered" width="340px" cellpadding="0" cellspacing="10">
  <tr>
    <td><img class="center" width="320px" src="images/b/b9/TutImgCubprism.png"></td>
  </tr>
  <tr>
    <td>
      <p class="caption">A cubic, triangular prism shape.</p>
    </td>
  </tr>
</table>

<p>This simple prism produces what looks like an extruded triangle with its
corners sanded smoothly off. Points two, three and four are the corners of
the triangle and point five closes the shape by returning to the location of
point two. As for points one and six, they are our control points, and
are not part of the shape - they are just there to help compute what
curves to use between the other points.</p>
</div>
<a name="t2_3_1_3_2"></a>
<div class="content-level-h5" contains="Smooth Transitions" id="t2_3_1_3_2">
<h5>2.3.1.3.2 Smooth Transitions</h5>
<p>Now a handy thing to note is that we have made point one equal point four,
and also point six equals point three. Yes, this is important. Although this
prism would still be legally closed if the control points were not what
we have made them, the curve transitions between points would not be as
smooth. We change points one and six to &lt;4,6&gt; and &lt;0,7&gt;
respectively and re-render to see how the back edge of the shape is altered
(see file <code>prismdm3.pov</code>).</p>
<p>
To put this more generally, if we want a smooth closure on a cubic spline,
we make the first control point equal to the third from last point, and the
last control point equal to the third point. On a quadratic spline, the trick
is similar, but since only the first point is a control point, make that
equal to the second from last point.</p>

</div>
<a name="t2_3_1_3_3"></a>
<div class="content-level-h5" contains="Multiple Sub-Shapes" id="t2_3_1_3_3">
<h5>2.3.1.3.3 Multiple Sub-Shapes</h5>
<p>Just as with the polygon object (see section
<a href="t2_3.html#t2_3_2_3">Polygon Object</a>)
the prism is very flexible, and allows us to make one prism out of several
sub-prisms. To do this, all we need to do is keep listing points after we
have already closed the first shape. The second shape can be simply an add on
going off in another direction from the first, but one of the more
interesting features is that if any even number of sub-shapes overlap, that
region where they overlap behaves as though it has been cut away from both
sub-shapes. Let's look at another example. Once again, same basic code as
before for camera, light and so forth, but we substitute this complex prism
(see file <code>prismdm4.pov</code>).</p>
<pre>
  prism {
    linear_sweep
    cubic_spline
    0,  // sweep the following shape from here ...
    1,  // ... up through here
    18, // the number of points making up the shape ...
    &lt;3,-5&gt;, &lt;3,5&gt;, &lt;-5,0&gt;, &lt;3, -5&gt;, &lt;3,5&gt;, &lt;-5,0&gt;,//sub-shape #1
    &lt;2,-4&gt;, &lt;2,4&gt;, &lt;-4,0&gt;, &lt;2,-4&gt;, &lt;2,4&gt;, &lt;-4,0&gt;, //sub-shape #2
    &lt;1,-3&gt;, &lt;1,3&gt;, &lt;-3,0&gt;, &lt;1, -3&gt;, &lt;1,3&gt;, &lt;-3,0&gt; //sub-shape #3
    pigment { Green }
  }
</pre>

<table class="centered" width="340px" cellpadding="0" cellspacing="10">
  <tr>
    <td><img class="center" width="320px" src="images/d/dc/TutImgSubshape.png"></td>
  </tr>
  <tr>
    <td>
      <p class="caption">Using sub-shapes to create a more complex shape.</p>
    </td>
  </tr>
</table>

<p>For readability purposes, we have started a new line every time we moved
on to a new sub-shape, but the ray-tracer of course tells where each shape
ends based on whether the shape has been closed (as described earlier). We
render this new prism, and look what we have got. It is the same
familiar shape, but it now looks like a smaller version of the shape has been
carved out of the center, then the carved piece was sanded down even smaller
and set back in the hole.</p>
<p>
Simply, the outer rim is where only sub-shape one exists, then the carved
out part is where sub-shapes one and two overlap. In the extreme center, the
object reappears because sub-shapes one, two, and three overlap, returning us
to an odd number of overlapping pieces. Using this technique we could make
any number of extremely complex prism shapes!</p>

</div>
<a name="t2_3_1_3_4"></a>
<div class="content-level-h5" contains="Conic Sweeps And The Tapering Effect" id="t2_3_1_3_4">
<h5>2.3.1.3.4 Conic Sweeps And The Tapering Effect</h5>
<p>In our original prism, the keyword <code>linear_sweep</code> is actually
optional. This is the default sweep assumed for a prism if no type of sweep
is specified. But there is another, extremely useful kind of sweep: the conic
sweep. The basic idea is like the original prism, except that while we are
sweeping the shape from the first height through the second height, we are
constantly expanding it from a single point until, at the second height, the
shape has expanded to the original points we made it from. To give a small
idea of what such effects are good for, we replace our existing prism with
this (see file <code>prismdm4.pov</code>):</p>
<pre>
  prism {
    conic_sweep
    linear_spline
    0, // height 1
    1, // height 2
    5, // the number of points making up the shape...
    &lt;4,4&gt;,&lt;-4,4&gt;,&lt;-4,-4&gt;,&lt;4,-4&gt;,&lt;4,4&gt;
    rotate &lt;180, 0, 0&gt;
    translate &lt;0, 1, 0&gt;
    scale &lt;1, 4, 1&gt;
    pigment { gradient y scale .2 }
  }
</pre>

<table class="centered" width="340px" cellpadding="0" cellspacing="10">
  <tr>
    <td><img class="center" width="320px" src="images/9/92/TutImgPyrsweep.png"></td>
  </tr>
  <tr>
    <td>
      <p class="caption">Creating a pyramid using conic sweeping.</p>
    </td>
  </tr>
</table>

<p>The gradient pigment was selected to give some definition to our object
without having to fix the lights and the camera angle right at this moment,
but when we render it, what have we created? A horizontally striped
pyramid! By now we can recognize the linear spline connecting the four points
of a square, and the familiar final point which is there to close the
spline.</p>
<p>
Notice all the transformations in the object declaration. That is going
to take a little explanation. The rotate and translate are easy. Normally, a
conic sweep starts full sized at the top, and tapers to a point at y=0, but
of course that would be upside down if we are making a pyramid. So we flip
the shape around the x-axis to put it right side up, then since we actually
orbited around the point, we translate back up to put it in the same position
it was in when we started.</p>
<p>
The scale is to put the proportions right for this example. The base is
eight units by eight units, but the height (from y=1 to y=0) is only one
unit, so we have stretched it out a little. At this point, we are
probably thinking, why not just sweep up from y=0 to y=4 and avoid this
whole scaling thing?</p>
<p>
That is a very important gotcha! with conic sweeps. To see what is wrong
with that, let's try and put it into practice (see file <code>
prismdm5.pov</code>). We must make sure to remove the scale statement, and
then replace the line which reads</p>
<pre>
  1, // height 2
</pre>

<p>with</p>
<pre>
  4, // height 2
</pre>

<p>This sets the second height at y=4, so let's re-render and see if the
effect is the same.</p>

<table class="centered" width="340px" cellpadding="0" cellspacing="10">
  <tr>
    <td><img class="center" width="320px" src="images/6/6b/TutImgImprswep.png"></td>
  </tr>
  <tr>
    <td>
      <p class="caption">Choosing a second height larger than one for the conic sweep.</p>
    </td>
  </tr>
</table>

<p>Whoa! Our height is correct, but our pyramid's base is now huge! What
went wrong here? Simple. The base, as we described it with the points we used
actually occurs at y=1 no matter what we set the second height for. But if we
do set the second height higher than one, once the sweep passes y=1, it keeps
expanding outward along the same lines as it followed to our original base,
making the actual base bigger and bigger as it goes.</p>
<p>
To avoid losing control of a conic sweep prism, it is usually best to let
the second height stay at y=1, and use a scale statement to adjust the height
from its unit size. This way we can always be sure the base's corners
remain where we think they are.</p>
<p>
That leads to one more interesting thing about conic sweeps. What if we for
some reason do not want them to taper all the way to a point? What if
instead of a complete pyramid, we want more of a ziggurat step? Easily done.
After putting the second height back to one, and replacing our scale
statement, we change the line which reads</p>
<pre>
  0, // height 1
</pre>

<p>to</p>
<pre>
  0.251, // height 1
</pre>

<table class="centered" width="340px" cellpadding="0" cellspacing="10">
  <tr>
    <td><img class="center" width="320px" src="images/0/0d/TutImgSweepinc.png"></td>
  </tr>
  <tr>
    <td>
      <p class="caption">Increasing the first height for the conic sweep.</p>
    </td>
  </tr>
</table>

<p>When we re-render, we see that the sweep stops short of going all the way
to its point, giving us a pyramid without a cap. Exactly how much of the cap
is cut off depends on how close the first height is to the second height.</p>

</div>
<a name="t2_3_1_4"></a>
<div class="content-level-h4" contains="Sphere Sweep Object" id="t2_3_1_4">
<h4>2.3.1.4 Sphere Sweep Object</h4>
<p>A Sphere Sweep Object is the space a sphere occupies during its movement along a spline.
<br>So we need to specify the kind of spline we want and a list of control points to define
that spline. To help POV-Ray we tell how many control points will be used. In addition, we also
define the radius the moving sphere should have when passing through each of these control
points.</p>

<p>The syntax of the sphere_sweep object is:</p>
<pre>
  sphere_sweep {
    linear_spline | b_spline | cubic_spline
    NUM_OF_SPHERES,

    CENTER, RADIUS,
    CENTER, RADIUS,
    ...
    CENTER, RADIUS
    [tolerance DEPTH_TOLERANCE]
    [OBJECT_MODIFIERS]
  }
</pre>

<p>An example for a linear Sphere Sweep would be:</p>
<pre>
  sphere_sweep {
    linear_spline
    4,
    &lt;-5, -5, 0&gt;, 1
    &lt;-5,  5, 0&gt;, 1
    &lt; 5, -5, 0&gt;, 1
    &lt; 5,  5, 0&gt;, 1
  }
</pre>
<p>This object is described by four spheres. You can use as many spheres as you like to
describe the object, but you will need at least two spheres for a linear Sphere Sweep, and
four spheres for one approximated with a cubic_spline or b_spline.</p>

<p>The example above would result in an object shaped like the letter &quot;N&quot;. The
sphere sweep goes through <em>all</em> points which are connected with straight
cones.</p>
<p>Changing the kind of interpolation to a cubic_spline produces a quite different,
slightly bent, object. It then starts at the second sphere and ends at the last but one. Since
the first and last points are used to control the spline, you need two more points to get a
shape that can be compared to the linear sweep. Let's add them:</p>
<pre>
  sphere_sweep {
    cubic_spline
    6,
    &lt;-4, -5, 0&gt;, 1
    &lt;-5, -5, 0&gt;, 1
    &lt;-5,  5, 0&gt;, 0.5
    &lt; 5, -5, 0&gt;, 0.5
    &lt; 5,  5, 0&gt;, 1
    &lt; 4,  5, 0&gt;, 1
    tolerance 0.1
 }
</pre>
<p>So the cubic sweep creates a smooth sphere sweep actually going through
all points (except the first and last one). In this example the radius of the second and third
spheres have been changed. We also added the <code>tolerance</code> keyword, because
dark spots appeared on the surface with the default value (0.000001).</p>

<p>When using a b_spline, the resulting object is somewhat similar to the cubic
sweep, but does not actually go through the control points. It lies somewhere between them.</p>

</div>
<a name="t2_3_1_5"></a>
<div class="content-level-h4" contains="Bicubic Patch Object" id="t2_3_1_5">
<h4>2.3.1.5 Bicubic Patch Object</h4>
<p>
Bicubic patches are useful surface representations because they allow an easy definition
of surfaces using only a few control points. The control points serve to determine the shape
of the patch. Instead of defining the vertices of triangles, we simply give the coordinates
of the control points. A single patch has 16 control points, one at each corner, and the rest
positioned to divide the patch into smaller sections. POV-Ray does not ray trace the patches
directly, they are approximated using triangles as described in the <a href="r3_4.html#r3_4_5_2_1">Scene Description Language</a> section.
</p>
<p>
Bicubic patches are almost always created by using a third party modeler, but for this tutorial
we will manipulate them by hand. Modelers that support Bicubic patches and export to POV-Ray
can be found in the <a href="http://www.povray.org/resources/links/">links collection on our server</a><br>
Let's set up a basic scene and start exploring the Bicubic patch.
</p>
<pre>
#version 3.5;
global_settings {assumed_gamma 1.0}
background {rgb &lt;1,0.9,0.9&gt;}
camera {location &lt;1.6,5,-6&gt; look_at &lt;1.5,0,1.5&gt; angle 40}
light_source {&lt;500,500,-500&gt; rgb 1 }

#declare B11=&lt;0,0,3&gt;; #declare B12=&lt;1,0,3&gt;; //
#declare B13=&lt;2,0,3&gt;; #declare B14=&lt;3,0,3&gt;; // row 1

#declare B21=&lt;0,0,2&gt;; #declare B22=&lt;1,0,2&gt;; //
#declare B23=&lt;2,0,2&gt;; #declare B24=&lt;3,0,2&gt;; // row 2

#declare B31=&lt;0,0,1&gt;; #declare B32=&lt;1,0,1&gt;; //
#declare B33=&lt;2,0,1&gt;; #declare B34=&lt;3,0,1&gt;; // row 3

#declare B41=&lt;0,0,0&gt;; #declare B42=&lt;1,0,0&gt;; //
#declare B43=&lt;2,0,0&gt;; #declare B44=&lt;3,0,0&gt;; // row 4

bicubic_patch {
   type 1 flatness 0.001
   u_steps 4 v_steps 4
   uv_vectors
   &lt;0,0&gt; &lt;1,0&gt; &lt;1,1&gt; &lt;0,1&gt;
   B11, B12, B13, B14
   B21, B22, B23, B24
   B31, B32, B33, B34
   B41, B42, B43, B44
   uv_mapping
   texture {
      pigment {
         checker 
         color rgbf &lt;1,1,1,0.5&gt; 
         color rgbf &lt;0,0,1,0.7&gt; 
         scale 1/3
      }
      finish {phong 0.6 phong_size 20}
   }
   no_shadow
}
</pre>
<p>
The points B11, B14, B41, B44 are the corner points of the patch.
All other points are control points. The names of the declared points are as follows:
B for the colour of the patch, the first digit gives the row number, the second digit
the column number. If you render the above scene, you will get a blue &amp; white
checkered square, not very exciting. First we will add some spheres to make the control
points visible. As we do not want to type the code for 16 spheres, we will use
an array and a while loop to construct the spheres.
</p>
<pre>
#declare Points=array[16]{
   B11, B12, B13, B14
   B21, B22, B23, B24
   B31, B32, B33, B34
   B41, B42, B43, B44
}
#declare I=0;
#while (I&lt;16)
   sphere {
      Points[I],0.1 
      no_shadow 
      pigment{
         #if (I=0|I=3|I=12|I=15)
            color rgb &lt;1,0,0&gt;
         #else
            color rgb &lt;0,1,1&gt;
         #end
      }
   }
   #declare I=I+1;
#end
</pre>
<p>
Rendering this scene will show the patch with its corner points in red and its control
points in cyan. Now it is time to start exploring.
<br>
Change B41 to <code>&lt;-1,0,0&gt;</code> and render.<br>
Change B41 to <code>&lt;-1,1,0&gt;</code> and render.<br>
Change B41 to <code>&lt; 1,2,1&gt;</code> and render.<br>
</p>
<p>
Let's do some exercise with the control points. Start with a flat patch again.<br>
Change B42 to <code>&lt;1,2,0&gt;</code> and B43 to <code>&lt;2,-2,0&gt;</code> and render.<br>
Change B42 and B43 back to their original positions and try B34 to <code>&lt;4,2,1&gt;</code>  
and B24 to <code>&lt;2,-2,2&gt;</code> and render. Move the points around some more, also
try the control points in the middle.
</p>

<table class="centered" width="340px" cellpadding="0" cellspacing="10">
  <tr>
    <td><img class="center" width="320px" src="images/0/06/TutImgBpatch01.png"></td>
  </tr>
  <tr>
    <td>
      <p class="caption">Bicubic_patch with control points.</p>
    </td>
  </tr>
</table>

<p>
After all this we notice two things: </p>
<ul type="disc">
<li> The patch always goes through the corner points.</li>
<li> In most situations the patch does not go through the control points.</li>
</ul>
<p>
Now go back to our spline work shop and have a look at the bezier_spline again. Indeed,
the points B11, B12, B13, B14, make up a bezier_spline. So do the points B11, B21, B31, B41 
and B41, B42, B43, B44 and B14, B24, B34, B44.
</p>
<p>
So far we have only been looking at one single patch, but one of the strengths of the
Bicubic patch lays in the fact that they can be connected smoothly, to form bigger shapes.
The process of connecting is relatively simple as there are actually only two rules to
follow. It can be done by using a well set up set of macros or by using a modeler. To give
an idea what is needed we will do a simple example by hand.
</p>
<p>
First put the patch in our scene back to its flat position.</p>
<p>Next change:</p>
<pre>
#declare B14 = &lt;3,0,3&gt;;
#declare B24 = &lt;3,2,2&gt;;
#declare B34 = &lt;3.5,1,1&gt;;
#declare B44 = &lt;3,-1,0&gt;;
#declare B41 = &lt;0,-1,0&gt;;
</pre>
<p>Move the camera a bit back:</p>
<pre>camera { location &lt;3.1,7,-8&gt; look_at &lt;3,-2,1.5&gt; angle 40 }</pre>
<p>... and delete all the code for the spheres. We will now try and stitch a patch to the right side of the current one. Off course the points on the left side (column 1) of the new patch have to be in the same position as the points on the right side (column 4) of the blue one.</p>
<p>
Render the scene, including our new patch:
</p>
<pre>
#declare R11=B14; #declare R12=&lt;4,0,3&gt;;     //
#declare R13=&lt;5,0,3&gt;; #declare R14=&lt;6,0,3&gt;; // row 1

#declare R21=B24; #declare R22=&lt;4,0,2&gt;;     //
#declare R23=&lt;5,0,2&gt;; #declare R24=&lt;6,0,2&gt;; // row 2

#declare R31=B34; #declare R32=&lt;4,0,1&gt;;     //
#declare R33=&lt;5,0,1&gt;; #declare R34=&lt;6,0,1&gt;; // row 3

#declare R41=B44; #declare R42=&lt;4,0,0&gt;;     //
#declare R43=&lt;5,0,0&gt;; #declare R44=&lt;6,0,0&gt;; // row 4

bicubic_patch {
   type 1 flatness 0.001
   u_steps 4 v_steps 4
   uv_vectors
   &lt;0,0&gt; &lt;1,0&gt; &lt;1,1&gt; &lt;0,1&gt;
   R11, R12, R13, R14
   R21, R22, R23, R24
   R31, R32, R33, R34
   R41, R42, R43, R44
   uv_mapping
   texture {
      pigment {
         checker 
         color rgbf &lt;1,1,1,0.5&gt; 
         color rgbf &lt;1,0,0,0.7&gt; 
         scale 1/3
      }
      finish {phong 0.6 phong_size 20}
   }
   no_shadow
}
</pre>
<p>
This is a rather disappointing result. The patches are connected, but not exactly smooth.
In connecting patches the same principles apply as for connecting two 2D bezier splines
as we see in the <a href="t2_3.html#t2_3_1_1_1">spline workshop</a>.
Control point, connection point and the next control point should be on one line to give
a smooth result. Also it is preferred, not required, that the distances from both control
points to the connection point are the same. For the Bicubic patch we have to do the same,
for all connection points involved in the joint. So, in our case, the following points 
should be on one line:</p>
<ul type="disc">
<li> B13, B14=R11, R12</li>
<li> B23, B24=R21, R22</li>
<li> B33, B34=R31, R32</li>
<li> B43, B44=R41, R42</li>
</ul>
<p>
To achieve this we do:
</p>
<pre>
#declare R12=B14+(B14-B13); 
#declare R22=B24+(B24-B23); 
#declare R32=B34+(B34-B33); 
#declare R42=B44+(B44-B43); 
</pre>

<table class="centered" width="340px" cellpadding="0" cellspacing="10">
  <tr>
    <td><img class="center" width="320px" src="images/e/ea/TutImgBpatch02.png"></td>
  </tr>
  <tr>
    <td>
      <p class="caption">patches, (un)smoothly connected.</p>
    </td>
  </tr>
</table>

<p>
This renders a smooth surface. Adding a third patch in front is relative simple now:</p>
<pre>
#declare G11=B41;      #declare G12=B42;                //
#declare G13=B43;      #declare G14=B44;                // row 1

#declare G21=B41+(B41-B31); #declare G22=B42+(B42-B32); //
#declare G23=B43+(B43-B33); #declare G24=B44+(B44-B34); // row 2

#declare G31=&lt;0,0,-2&gt;; #declare G32=&lt;1,0,-2&gt;;           //
#declare G33=&lt;2,0,-2&gt;; #declare G34=&lt;3,2,-2&gt;;           // row 3

#declare G41=&lt;0,0,-3&gt;; #declare G42=&lt;1,0,-3&gt;;           // 
#declare G43=&lt;2,0,-3&gt;; #declare G44=&lt;3,0,-3&gt;            // row 4

bicubic_patch {
   type 1 flatness 0.001
   u_steps 4 v_steps 4
   uv_vectors
   &lt;0,0&gt; &lt;1,0&gt; &lt;1,1&gt; &lt;0,1&gt;
   G11, G12, G13, G14
   G21, G22, G23, G24
   G31, G32, G33, G34
   G41, G42, G43, G44
   uv_mapping
   texture {
      pigment {
         checker 
         color rgbf &lt;1,1,1,0.5&gt; 
         color rgbf &lt;0,1,0,0.7&gt; 
         scale 1/3
      }
      finish {phong 0.6 phong_size 20}
   }
   no_shadow
}
</pre>
<p>
Finally, let's put a few spheres back in the scene and add some cylinders to visualize what
is going on. See what happens if you move for example B44, B43, B33 or B34.
</p>
<pre>
#declare Points=array[8]{B33,B34,R32,B43,B44,R42,G23,G24}
#declare I=0;
#while (I&lt;8)
   sphere {
      Points[I],0.1 
      no_shadow 
      pigment{
         #if (I=4)
            color rgb &lt;1,0,0&gt;
         #else
            color rgb &lt;0,1,1&gt;
         #end
      }
   }
   #declare I=I+1;
#end
union {
   cylinder {B33,B34,0.04} cylinder {B34,R32,0.04}
   cylinder {B43,B44,0.04} cylinder {B44,R42,0.04}
   cylinder {G23,G24,0.04} 
   cylinder {B33,B43,0.04} cylinder {B43,G23,0.04}
   cylinder {B34,B44,0.04} cylinder {B44,G24,0.04}
   cylinder {R32,R42,0.04}
   no_shadow 
   pigment {color rgb &lt;1,1,0&gt;}
}
</pre>
<p>
The hard part in using the Bicubic patch is not in connecting several patches. The 
difficulty is keeping control over the shape you want to build. As patches are added, 
in order to keep the result smooth, control over the position of many points gets restrained.
</p>

<table class="centered" width="340px" cellpadding="0" cellspacing="10">
  <tr>
    <td><img class="center" width="320px" src="images/4/4a/TutImgBpatch03.png"></td>
  </tr>
  <tr>
    <td>
      <p class="caption">3 patches, some control points.</p>
    </td>
  </tr>
</table>

</div>
<a name="t2_3_1_6"></a>
<div class="content-level-h4" contains="Text Object" id="t2_3_1_6">
<h4>2.3.1.6 Text Object</h4>
<p>The <code>text</code> object is a primitive that can use TrueType fonts
and TrueType Collections to create text objects. These
objects can be used in CSG, transformed and textured just like any other POV
primitive.</p>
<p>
For this tutorial, we will make two uses of the text object. First,
let's just make some block letters sitting on a checkered plane. Any TTF
font should do, but for this tutorial, we will use the <code>
timrom.ttf</code> or <code>cyrvetic.ttf</code> which come bundled with
POV-Ray.</p>
<p>
We create a file called <code>textdemo.pov</code> and edit it as
follows:</p>
<pre>
  #include &quot;colors.inc&quot;
  camera {
    location &lt;0, 1, -10&gt;
    look_at 0
    angle 35
  }
  light_source { &lt;500,500,-1000&gt; White }
  plane {
    y,0
    pigment { checker Green White }
  }
</pre>

<p>Now let's add the text object. We will use the font <code>
timrom.ttf</code> and we will create the string &quot;POV-RAY 3.0&quot;. For
now, we will just make the letters red. The syntax is very simple. The first
string in quotes is the font name, the second one is the string to be
rendered. The two floats are the thickness and offset values. The thickness
float determines how thick the block letters will be. Values of .5 to 2 are
usually best for this. The offset value will add to the kerning distance of
the letters. We will leave this a 0 for now.</p>
<pre>
  text {
    ttf &quot;timrom.ttf&quot; &quot;POV-RAY 3.0&quot; 1, 0
    pigment { Red }
  }
</pre>

<p>Rendering this we notice that the letters are
off to the right of the screen. This is because they are placed so that the
lower left front corner of the first letter is at the origin. To center the
string we need to translate it -x some distance. But how far? In the docs we
see that the letters are all 0.5 to 0.75 units high. If we assume that each
one takes about 0.5 units of space on the x-axis, this means that the string
is about 6 units long (12 characters and spaces). Let's translate the
string 3 units along the negative x-axis.</p>
<pre>
  text {
    ttf &quot;timrom.ttf&quot; &quot;POV-RAY 3.0&quot; 1, 0
    pigment { Red }
    translate -3*x
  }
</pre>

<p>That is better. Now let's play around with some of the parameters
of the text object. First, let's raise the thickness float to something
outlandish... say 25!</p>
<pre>
  text {
    ttf &quot;timrom.ttf&quot; &quot;POV-RAY 3.0&quot; 25, 0
    pigment { Red }
    translate -2.25*x
  }
</pre>

<p>Actually, that is kind of cool. Now let's return the thickness
value to 1 and try a different offset value. Change the offset float from 0
to 0.1 and render it again.</p>
<p>
Wait a minute?! The letters go wandering off up at an angle! That is not
what the docs describe! It almost looks as if the offset value applies in
both the x- and y-axis instead of just the x axis like we intended. Could it
be that a vector is called for here instead of a float? Let's try it. We
replace <code>0.1</code> with <code> 0.1*x</code> and render it again.</p>
<p>
That works! The letters are still in a straight line along the x-axis, just
a little further apart. Let's verify this and try to offset just in the
y-axis. We replace <code> 0.1*x</code> with <code> 0.1*y</code>. Again, this
works as expected with the letters going up to the right at an angle with no
additional distance added along the x-axis. Now let's try the z-axis. We
replace <code> 0.1*y</code> with <code> 0.1*z</code>. Rendering this yields a
disappointment. No offset occurs! The offset value can only be applied in the
x- and y-directions.</p>
<p>
Let's finish our scene by giving a fancier texture to the block letters,
using that cool large thickness value, and adding a slight y-offset. For fun,
we will throw in a sky sphere, dandy up our plane a bit, and use a little
more interesting camera viewpoint (we render the following scene at 640x480
<code> +A0.2</code>):</p>
<pre>
  #include &quot;colors.inc&quot;
  camera {
    location &lt;-5,.15,-2&gt;
    look_at &lt;.3,.2,1&gt;
    angle 35
  }
  light_source { &lt;500,500,-1000&gt; White }
  plane {
    y,0
    texture {
      pigment { SeaGreen }
      finish { reflection .35 specular 1 }
      normal { ripples .35 turbulence .5 scale .25 }
    }
  }
  text {
    ttf &quot;timrom.ttf&quot; &quot;POV-RAY 3.0&quot; 25, 0.1*y
    pigment { BrightGold }
    finish { reflection .25 specular 1 }
    translate -3*x
  }
  #include &quot;skies.inc&quot;
  sky_sphere { S_Cloud5 }
</pre>

<p>Let's try using text in a CSG object. We will attempt to create an
inlay in a stone block using a text object. We create a new file called
<code>textcsg.pov</code> and edit it as follows:</p>
<pre>
  #include &quot;colors.inc&quot;
  #include &quot;stones.inc&quot;
  background { color rgb 1 }
  camera {
    location &lt;-3, 5, -15&gt;
    look_at 0
    angle 25
  }
  light_source { &lt;500,500,-1000&gt; White }
</pre>

<p>Now let's create the block. We want it to be about eight units across
because our text string &quot;POV-RAY 3.0&quot; is about six units long. We
also want it about four units high and about one unit deep. But we need to
avoid a potential coincident surface with the text object so we will make the
first z-coordinate 0.1 instead of 0. Finally, we will give this block a nice
stone texture.</p>
<pre>
  box {
    &lt;-3.5, -1, 0.1&gt;, &lt;3.5, 1, 1&gt;
    texture { T_Stone10 }
  }
</pre>

<p>Next, we want to make the text object. We can use the same object we used
in the first tutorial except we will use slightly different thickness and
offset values.</p>
<pre>
  text {
    ttf &quot;timrom.ttf&quot; &quot;POV-RAY 3.0&quot; 0.15, 0
    pigment { BrightGold }
    finish { reflection .25 specular 1 }
    translate -3*x
  }
</pre>

<p>We remember that the text object is placed by default so that its front
surface lies directly on the x-y-plane. If the front of the box begins at
z=0.1 and thickness is set at 0.15, the depth of the inlay will be 0.05
units. We place a difference block around the two objects.</p>
<pre>
  difference {
    box {
      &lt;-3.5, -1, 0.1&gt;, &lt;3.5, 1, 1&gt;
      texture { T_Stone10 }
    }
    text {
      ttf &quot;timrom.ttf&quot; &quot;POV-RAY 3.0&quot; 0.15, 0
      pigment { BrightGold }
      finish { reflection .25 specular 1 }
      translate -3*x
    }
  }
</pre>

<table class="centered" width="340px" cellpadding="0" cellspacing="10">
  <tr>
    <td><img class="center" width="320px" src="images/3/36/TutImgTxtstone.png"></td>
  </tr>
  <tr>
    <td>
      <p class="caption">Text carved from stone.</p>
    </td>
  </tr>
</table>

<p>When we render this at a low resolution we can see the inlay clearly and that it is indeed a bright gold color. We can render at a higher resolution and see the results more clearly but be forewarned... this trace
will take a little time.</p>

</div>

<a name="t2_3_2"></a>
<div class="content-level-h3" contains="Polygon Based Shapes" id="t2_3_2">
<h3>2.3.2 Polygon Based Shapes</h3>
</div>
<a name="t2_3_2_1"></a>
<div class="content-level-h4" contains="Mesh Object" id="t2_3_2_1">
<h4>2.3.2.1 Mesh Object</h4>
<p>Mesh objects are very useful because they allow us to create objects
containing hundreds or thousands of triangles. Compared to a simple union of
triangles the mesh object stores the triangles more efficiently. Copies of
mesh objects need only a little additional memory because the triangles are
stored only once.</p>
<p>
Almost every object can be approximated using triangles but we may need a
lot of triangles to create more complex shapes. Thus we will only create a
very simple mesh example. This example will show a very useful feature of the
triangles meshes though: a different texture can be assigned to each triangle
in the mesh.</p>
<p>
Now let's begin. We will create a simple box with differently colored
sides. We create an empty file called <code>meshdemo.pov</code> and add the
following lines. Note that a mesh is - not surprisingly - declared using the
keyword <code><a href="r3_4.html#r3_4_5_2_3">mesh</a></code>.</p>
<pre>
  camera {
    location &lt;20, 20, -50&gt;
    look_at &lt;0, 5, 0&gt;
  }
  light_source { &lt;50, 50, -50&gt; color rgb&lt;1, 1, 1&gt; }
  #declare Red = texture {
    pigment { color rgb&lt;0.8, 0.2, 0.2&gt; }
    finish { ambient 0.2 diffuse 0.5 }
  }
  #declare Green = texture {
    pigment { color rgb&lt;0.2, 0.8, 0.2&gt; }
    finish { ambient 0.2 diffuse 0.5 }
  }
  #declare Blue = texture {
    pigment { color rgb&lt;0.2, 0.2, 0.8&gt; }
    finish { ambient 0.2 diffuse 0.5 }
  }
</pre>

<p>We must declare all textures we want to use inside the mesh before the
mesh is created. Textures cannot be specified inside the mesh due to the poor
memory performance that would result.</p>
<p>
Now we add the mesh object. Three sides of the box will use individual
textures while the other will use the <em> global</em> mesh texture.</p>
<pre>
  mesh {
    /* top side */
    triangle {
      &lt;-10, 10, -10&gt;, &lt;10, 10, -10&gt;, &lt;10, 10, 10&gt;
      texture { Red }
    }
    triangle {
      &lt;-10, 10, -10&gt;, &lt;-10, 10, 10&gt;, &lt;10, 10, 10&gt;
      texture { Red }
    }
    /* bottom side */
    triangle { &lt;-10, -10, -10&gt;, &lt;10, -10, -10&gt;, &lt;10, -10, 10&gt; }
    triangle { &lt;-10, -10, -10&gt;, &lt;-10, -10, 10&gt;, &lt;10, -10, 10&gt; }
    /* left side */
    triangle { &lt;-10, -10, -10&gt;, &lt;-10, -10, 10&gt;, &lt;-10, 10, 10&gt; }
    triangle { &lt;-10, -10, -10&gt;, &lt;-10, 10, -10&gt;, &lt;-10, 10, 10&gt; }
    /* right side */
    triangle {
      &lt;10, -10, -10&gt;, &lt;10, -10, 10&gt;, &lt;10, 10, 10&gt;
      texture { Green }
    }
    triangle {
      &lt;10, -10, -10&gt;, &lt;10, 10, -10&gt;, &lt;10, 10, 10&gt;
      texture { Green }
    }
    /* front side */
    triangle {
      &lt;-10, -10, -10&gt;, &lt;10, -10, -10&gt;, &lt;-10, 10, -10&gt;
      texture { Blue }
    }
    triangle {
      &lt;-10, 10, -10&gt;, &lt;10, 10, -10&gt;, &lt;10, -10, -10&gt;
      texture { Blue }
    }
    /* back side */
    triangle { &lt;-10, -10, 10&gt;, &lt;10, -10, 10&gt;, &lt;-10, 10, 10&gt; }
    triangle { &lt;-10, 10, 10&gt;, &lt;10, 10, 10&gt;, &lt;10, -10, 10&gt; }
    texture {
      pigment { color rgb&lt;0.9, 0.9, 0.9&gt; }
      finish { ambient 0.2 diffuse 0.7 }
    }
  }
</pre>

<p>Tracing the scene at 320x240 we will see that the top, right and front
side of the box have different textures. Though this is not a very impressive
example it shows what we can do with mesh objects. More complex examples,
also using smooth triangles, can be found under the scene directory as <code>
chesmsh.pov</code>.</p>

</div>
<a name="t2_3_2_2"></a>
<div class="content-level-h4" contains="Mesh2 Object" id="t2_3_2_2">
<h4>2.3.2.2 Mesh2 Object</h4>
<p>The <code>mesh2</code> is a representation of a mesh, that is much more
like POV-Ray's internal mesh representation than the standard <code>mesh</code>.
As a result, it parses faster and it file size is smaller.</p>
<p>Due to its nature, <code>mesh2</code> is not really suitable for 
building meshes by hand, it is intended for use by modelers and file
format converters. An other option is building the meshes by macros.
Yet, to understand the format, we will do a small example by hand and go through
all options.</p>

<table class="centered" width="660px" cellpadding="0" cellspacing="10">
  <tr>
    <td><img class="center" width="640px" src="images/2/21/TutImgMesh2.gif"></td>
  </tr>
  <tr>
    <td>
      <p class="caption">To be written as mesh2.</p>
    </td>
  </tr>
</table>

<p>We will turn the mesh sketched above into a <code>mesh2</code> object.
The mesh is made of 8 triangles, each with 3 vertices, many of 
these vertices are shared among the triangles. This can later be
used to optimize the mesh. First we will set it up straight forward.</p>

<p>In <code>mesh2</code> all the vertices are listed in a list named
<code>vertex_vectors{}</code>. A second list, <code>face_indices{}</code>,
tells us how to put together three vertices to create one triangle,
by pointing to the index number of a vertex. All lists in <code>mesh2</code>
are zero based, the number of the first vertex is 0. The very first
item in a list is the amount of vertices, normals or uv_vectors it contains.
<code>mesh2</code> has to be specified in the order <em>VECTORS...</em>,
<em>LISTS...</em>, <em>INDICES...</em>.</p>

<p>Lets go through the mesh above, we do it counter clockwise. The total 
amount of vertices is 24 (8 triangle * 3 vertices).</p>

<pre>
mesh2 {
   vertex_vectors {
      24,
      ...
</pre>

<p>Now we can add the coordinates of the vertices of the first triangle:</p>

<pre>
mesh2 {
   vertex_vectors {
      24, 
      &lt;0,0,0&gt;, &lt;0.5,0,0&gt;, &lt;0.5,0.5,0&gt;
      ..
</pre>

<p>Next step, is to tell the mesh how the triangle should be created;
There will be a total of 8 face_indices (8 triangles). The first
point in the first face, points to the first vertex_vector (0: &lt;0,0,0&gt;), 
the second to the second (1: &lt;0.5,0,0&gt;), etc...</p>

<pre>
mesh2 {
   vertex_vectors {
      24, 
      &lt;0,0,0&gt;, &lt;0.5,0,0&gt;, &lt;0.5,0.5,0&gt;
      ...
   }
   face_indices {
      8, 
      &lt;0,1,2&gt; 
      ...
</pre>

<p>The complete mesh:</p>

<pre>
mesh2 {
   vertex_vectors {
      24, 
      &lt;0,0,0&gt;, &lt;0.5,0,0&gt;, &lt;0.5,0.5,0&gt;, //1
      &lt;0.5,0,0&gt;, &lt;1,0,0&gt;, &lt;0.5,0.5,0&gt;, //2
      &lt;1,0,0&gt;, &lt;1,0.5,0&gt;, &lt;0.5,0.5,0&gt;, //3
      &lt;1,0.5,0&gt;, &lt;1,1,0&gt;, &lt;0.5,0.5,0&gt;, //4
      &lt;1,1,0&gt;, &lt;0.5,1,0&gt;, &lt;0.5,0.5,0&gt;, //5
      &lt;0.5,1,0&gt;, &lt;0,1,0&gt;, &lt;0.5,0.5,0&gt;, //6
      &lt;0,1,0&gt;, &lt;0,0.5,0&gt;, &lt;0.5,0.5,0&gt;, //7
      &lt;0,0.5,0&gt;, &lt;0,0,0&gt;, &lt;0.5,0.5,0&gt;  //8
   }
   face_indices {
      8, 
      &lt;0,1,2&gt;,    &lt;3,4,5&gt;,       //1 2
      &lt;6,7,8&gt;,    &lt;9,10,11&gt;,     //3 4
      &lt;12,13,14&gt;, &lt;15,16,17&gt;,    //5 6
      &lt;18,19,20&gt;, &lt;21,22,23&gt;     //7 8
   }
   pigment {rgb 1}
}
</pre>

<p>As mentioned earlier, many vertices are shared by triangles. We can 
optimize the mesh by removing all duplicate vertices but one. In the 
example this reduces the amount from 24 to 9.</p>

<pre>
mesh2 {
   vertex_vectors {
      9, 
      &lt;0,0,0&gt;, &lt;0.5,0,0&gt;, &lt;0.5,0.5,0&gt;,
      /*as 1*/ &lt;1,0,0&gt;,   /*as 2*/
      /*as 3*/ &lt;1,0.5,0&gt;, /*as 2*/
      /*as 4*/ &lt;1,1,0&gt;,   /*as 2*/
      /*as 5*/ &lt;0.5,1,0&gt;, /*as 2*/
      /*as 6*/ &lt;0,1,0&gt;,   /*as 2*/
      /*as 7*/ &lt;0,0.5,0&gt;, /*as 2*/
      /*as 8*/ /*as 0*/   /*as 2*/
   }
   ...
   ...
</pre>

<p>Next step is to rebuild the list of face_indices, as they now point 
to indices in the <code>vertex_vector{}</code> list that do not exist anymore.</p>

<pre>
   ...
   ...
   face_indices {
      8, 
      &lt;0,1,2&gt;, &lt;1,3,2&gt;,
      &lt;3,4,2&gt;, &lt;4,5,2&gt;,
      &lt;5,6,2&gt;, &lt;6,7,2&gt;,
      &lt;7,8,2&gt;, &lt;8,0,2&gt;
   }
   pigment {rgb 1}
}
</pre>

</div>
<a name="t2_3_2_2_1"></a>
<div class="content-level-h5" contains="Smooth triangles and mesh2" id="t2_3_2_2_1">
<h5>2.3.2.2.1 Smooth triangles and mesh2</h5>
<p>In case we want a smooth mesh, the same steps we did also apply to the 
normals in a mesh. For each vertex there is one normal vector listed in 
<code>normal_vectors{}</code>, duplicates can be removed. If the number
of normals equals the number of vertices then the <code>normal_indices{}</code>
list is optional and the indexes from the <code>face_indices{}</code> list
are used instead.</p>

<pre>
mesh2 {
   vertex_vectors {
      9, 
      &lt;0,0,0&gt;, &lt;0.5,0,0&gt;, &lt;0.5,0.5,0&gt;,
      &lt;1,0,0&gt;, &lt;1,0.5,0&gt;, &lt;1,1,0&gt;,
      &lt;0.5,1,0&gt;, &lt;0,1,0&gt;, &lt;0,0.5,0&gt;   
   }
   normal_vectors {
      9,
     &lt;-1,-1,0&gt;,&lt;0,-1,0&gt;, &lt;0,0,1&gt;,
      /*as 1*/ &lt;1,-1,0&gt;, /*as 2*/
      /*as 3*/ &lt;1,0,0&gt;,  /*as 2*/
      /*as 4*/ &lt;1,1,0&gt;,  /*as 2*/
      /*as 5*/ &lt;0,1,0&gt;,  /*as 2*/
      /*as 6*/ &lt;-1,1,0&gt;, /*as 2*/
      /*as 7*/ &lt;-1,0,0&gt;, /*as 2*/
      /*as 8*/ /*as 0*/  /*as 2*/ 
   }
   face_indices {
      8, 
      &lt;0,1,2&gt;, &lt;1,3,2&gt;,
      &lt;3,4,2&gt;, &lt;4,5,2&gt;,
      &lt;5,6,2&gt;, &lt;6,7,2&gt;,
      &lt;7,8,2&gt;, &lt;8,0,2&gt;
   }
   pigment {rgb 1}
}
</pre>

<p>When a mesh has a mix of smooth and flat triangles a list of 
<code>normal_indices{}</code> has to be added, where each entry points to what 
vertices a normal should be applied. In the example below only the first four
normals are actually used.</p>

<pre>
mesh2 {
   vertex_vectors {
      9, 
      &lt;0,0,0&gt;, &lt;0.5,0,0&gt;, &lt;0.5,0.5,0&gt;,
      &lt;1,0,0&gt;, &lt;1,0.5,0&gt;, &lt;1,1,0&gt;,
      &lt;0.5,1,0&gt;, &lt;0,1,0&gt;,   &lt;0,0.5,0&gt;
   }
   normal_vectors {
      9,
      &lt;-1,-1,0&gt;, &lt;0,-1,0&gt;, &lt;0,0,1&gt;,
      &lt;1,-1,0&gt;, &lt;1,0,0&gt;, &lt;1,1,0&gt;,
      &lt;0,1,0&gt;, &lt;-1,1,0&gt;, &lt;-1,0,0&gt;
   }
   face_indices {
      8, 
      &lt;0,1,2&gt;, &lt;1,3,2&gt;,
      &lt;3,4,2&gt;, &lt;4,5,2&gt;,
      &lt;5,6,2&gt;, &lt;6,7,2&gt;,
      &lt;7,8,2&gt;, &lt;8,0,2&gt;
   }
   normal_indices {
      4, 
      &lt;0,1,2&gt;, &lt;1,3,2&gt;,
      &lt;3,4,2&gt;, &lt;4,5,2&gt;
   }
   pigment {rgb 1}
}
</pre>

</div>
<a name="t2_3_2_2_2"></a>
<div class="content-level-h5" contains="UV mapping and mesh2" id="t2_3_2_2_2">
<h5>2.3.2.2.2 UV mapping and mesh2</h5>
<p>uv_mapping is a method of 'sticking' 2D textures on an object in such a way that it
follows the form of the object. For uv_mapping on triangles imagine it as follows; 
First you cut out a triangular section of a texture form the xy-plane. Then stretch,
shrink and deform the piece of texture to fit to the triangle and stick it on.</p>

<p>Now, in <code>mesh2</code> we first build a list of 2D-vectors that are the coordinates of the
triangular sections in the xy-plane. This is the <code>uv_vectors{}</code> list. In the example we
map the texture from the rectangular area <code>&lt;-0.5,-0.5&gt;, &lt;0.5,0.5&gt;</code> to the triangles in the mesh. 
Again we can omit all duplicate coordinates</p>

<pre>
mesh2 {
   vertex_vectors {
      9, 
      &lt;0,0,0&gt;, &lt;0.5,0,0&gt;, &lt;0.5,0.5,0&gt;,
      &lt;1,0,0&gt;, &lt;1,0.5,0&gt;, &lt;1,1,0&gt;,
      &lt;0.5,1,0&gt;, &lt;0,1,0&gt;,   &lt;0,0.5,0&gt;
   }
   uv_vectors {
      9
     &lt;-0.5,-0.5&gt;,&lt;0,-0.5&gt;,  &lt;0,0&gt;,
      /*as 1*/   &lt;0.5,-0.5&gt;,/*as 2*/
      /*as 3*/   &lt;0.5,0&gt;,   /*as 2*/
      /*as 4*/   &lt;0.5,0.5&gt;, /*as 2*/
      /*as 5*/   &lt;0,0.5&gt;,   /*as 2*/
      /*as 6*/   &lt;-0.5,0.5&gt;,/*as 2*/
      /*as 7*/   &lt;-0.5,0&gt;,  /*as 2*/
      /*as 8*/   /*as 0*/   /*as 2*/       
   }
   face_indices {
      8, 
      &lt;0,1,2&gt;, &lt;1,3,2&gt;,
      &lt;3,4,2&gt;, &lt;4,5,2&gt;,
      &lt;5,6,2&gt;, &lt;6,7,2&gt;,
      &lt;7,8,2&gt;, &lt;8,0,2&gt;
   }
   uv_mapping
   pigment {wood scale 0.2}
}
</pre>

<p>Just as with the <code>normal_vectors</code>, if the number
of <code>uv_vectors</code> equals the number of vertices then the <code>uv_indices{}</code>
list is optional and the indices from the <code>face_indices{}</code> list
are used instead.</p>

<p>In contrary to the <code>normal_indices</code> list, if the <code>uv_indices</code>
list is used, the amount of indices should be equal to the amount of <code>face_indices</code>.
In the example below only 'one texture section' is specified and used on all triangles, using the
<code>uv_indices</code>.</p>
<pre>
mesh2 {
   vertex_vectors {
      9, 
      &lt;0,0,0&gt;, &lt;0.5,0,0&gt;, &lt;0.5,0.5,0&gt;,
      &lt;1,0,0&gt;, &lt;1,0.5,0&gt;, &lt;1,1,0&gt;,
      &lt;0.5,1,0&gt;, &lt;0,1,0&gt;,   &lt;0,0.5,0&gt;
   }
   uv_vectors {
      3
      &lt;0,0&gt;, &lt;0.5,0&gt;, &lt;0.5,0.5&gt;    
   }
   face_indices {
      8, 
      &lt;0,1,2&gt;, &lt;1,3,2&gt;,
      &lt;3,4,2&gt;, &lt;4,5,2&gt;,
      &lt;5,6,2&gt;, &lt;6,7,2&gt;,
      &lt;7,8,2&gt;, &lt;8,0,2&gt;
   }
   uv_indices {
      8, 
      &lt;0,1,2&gt;, &lt;0,1,2&gt;,
      &lt;0,1,2&gt;, &lt;0,1,2&gt;,
      &lt;0,1,2&gt;, &lt;0,1,2&gt;,
      &lt;0,1,2&gt;, &lt;0,1,2&gt;
   }
   uv_mapping
   pigment {gradient x scale 0.2}
}
</pre>

</div>
<a name="t2_3_2_2_3"></a>
<div class="content-level-h5" contains="A separate texture per triangle" id="t2_3_2_2_3">
<h5>2.3.2.2.3 A separate texture per triangle</h5>
<p>By using the <code>texture_list</code> it is possible to specify a texture per triangle
or even per vertex in the mesh. In the latter case the three textures per triangle will
be interpolated. To let POV-Ray know what texture to apply to a triangle, the index of a
texture is added to the <code>face_indices</code> list, after the face index it belongs to.</p>

<pre>
mesh2 {
   vertex_vectors {
      9, 
      &lt;0,0,0&gt;, &lt;0.5,0,0&gt;, &lt;0.5,0.5,0&gt;,
      &lt;1,0,0&gt;, &lt;1,0.5,0&gt;, &lt;1,1,0&gt;   
      &lt;0.5,1,0&gt;, &lt;0,1,0&gt;, &lt;0,0.5,0&gt; 
   }
   texture_list {
      2,
      texture{pigment{rgb&lt;0,0,1&gt;}}
      texture{pigment{rgb&lt;1,0,0&gt;}}
   }
   face_indices {
      8, 
      &lt;0,1,2&gt;,0,  &lt;1,3,2&gt;,1,
      &lt;3,4,2&gt;,0,  &lt;4,5,2&gt;,1,
      &lt;5,6,2&gt;,0,  &lt;6,7,2&gt;,1,
      &lt;7,8,2&gt;,0,  &lt;8,0,2&gt;,1
   }
}
</pre>

<p>To specify a texture per vertex, three <code>texture_list</code> indices are added after
the <code>face_indices</code></p>

<pre>
mesh2 {
   vertex_vectors {
      9, 
      &lt;0,0,0&gt;, &lt;0.5,0,0&gt;, &lt;0.5,0.5,0&gt;,
      &lt;1,0,0&gt;, &lt;1,0.5,0&gt;, &lt;1,1,0&gt;   
      &lt;0.5,1,0&gt;, &lt;0,1,0&gt;, &lt;0,0.5,0&gt; 
   }
   texture_list {
      3,
      texture{pigment{rgb &lt;0,0,1&gt;}}
      texture{pigment{rgb 1}}
      texture{pigment{rgb &lt;1,0,0&gt;}}
   }
   face_indices {
      8, 
      &lt;0,1,2&gt;,0,1,2,  &lt;1,3,2&gt;,1,0,2,
      &lt;3,4,2&gt;,0,1,2,  &lt;4,5,2&gt;,1,0,2,
      &lt;5,6,2&gt;,0,1,2,  &lt;6,7,2&gt;,1,0,2,
      &lt;7,8,2&gt;,0,1,2,  &lt;8,0,2&gt;,1,0,2
   }
}
</pre>

<p>Assigning a texture based on the <code>texture_list</code> and texture
interpolation is done on a per triangle base. So it is possible to mix
triangles with just one texture and triangles with three textures in a mesh.
It is even possible to mix in triangles without any texture indices, these
will get their texture from a general <code>texture</code> statement in the
<code>mesh2</code>. uv_mapping is supported for texturing using a <code>texture_list</code>.</p>

</div>
<a name="t2_3_2_3"></a>
<div class="content-level-h4" contains="Polygon Object" id="t2_3_2_3">
<h4>2.3.2.3 Polygon Object</h4>
<p>The <code><a href="r3_4.html#r3_4_5_2_5">polygon</a></code> object can be used to create any planar, n-sided shapes like squares, rectangles, pentagons, hexagons, octagons, etc.</p>
<p>
A polygon is defined by a number of points that describe its shape. Since
polygons have to be closed the first point has to be repeated at the end of
the point sequence.</p>
<p>
In the following example we will create the word &quot;POV&quot; using just
one polygon statement.</p>
<p>
We start with thinking about the points we need to describe the desired
shape. We want the letters to lie in the x-y-plane with the letter O being at
the center. The letters extend from y=0 to y=1. Thus we get the following
points for each letter (the z coordinate is automatically set to zero).</p>

<p>Letter P (outer polygon):</p>
<pre>
    &lt;-0.8, 0.0&gt;, &lt;-0.8, 1.0&gt;,
    &lt;-0.3, 1.0&gt;, &lt;-0.3, 0.5&gt;,
    &lt;-0.7, 0.5&gt;, &lt;-0.7, 0.0&gt;
</pre>

<p>Letter P (inner polygon):</p>
<pre>
    &lt;-0.7, 0.6&gt;, &lt;-0.7, 0.9&gt;,
    &lt;-0.4, 0.9&gt;, &lt;-0.4, 0.6&gt;
</pre>

<p>Letter O (outer polygon):</p>
<pre>
    &lt;-0.25, 0.0&gt;, &lt;-0.25, 1.0&gt;,
    &lt; 0.25, 1.0&gt;, &lt; 0.25, 0.0&gt;
</pre>

<p>Letter O (inner polygon):</p>
<pre>
    &lt;-0.15, 0.1&gt;, &lt;-0.15, 0.9&gt;,
    &lt; 0.15, 0.9&gt;, &lt; 0.15, 0.1&gt;
</pre>

<p>Letter V:</p>
<pre>
    &lt;0.45, 0.0&gt;, &lt;0.30, 1.0&gt;,
    &lt;0.40, 1.0&gt;, &lt;0.55, 0.1&gt;,
    &lt;0.70, 1.0&gt;, &lt;0.80, 1.0&gt;,
    &lt;0.65, 0.0&gt;
</pre>

<p>Both letters P and O have a hole while the letter V consists of only one
polygon. We will start with the letter V because it is easier to define
than the other two letters.</p>
<p>
We create a new file called <code> polygdem.pov</code> and add the following
text.</p>
<pre>
  camera {
    orthographic
    location &lt;0, 0, -10&gt;
    right 1.3 * 4/3 * x
    up 1.3 * y
    look_at &lt;0, 0.5, 0&gt;
  }
  light_source { &lt;25, 25, -100&gt; color rgb 1 }
  polygon {
    8,
    &lt;0.45, 0.0&gt;, &lt;0.30, 1.0&gt;, // Letter &quot;V&quot;
    &lt;0.40, 1.0&gt;, &lt;0.55, 0.1&gt;,
    &lt;0.70, 1.0&gt;, &lt;0.80, 1.0&gt;,
    &lt;0.65, 0.0&gt;,
    &lt;0.45, 0.0&gt;
    pigment { color rgb &lt;1, 0, 0&gt; }
  }
</pre>

<p>As noted above the polygon has to be closed by appending the first point
to the point sequence. A closed polygon is always defined by a sequence of
points that ends when a point is the same as the first point.</p>
<p>
After we have created the letter V we will continue with the letter P.
Since it has a hole we have to find a way of cutting this hole into the basic
shape. This is quite easy. We just define the outer shape of the letter P,
which is a closed polygon, and add the sequence of points that describes the
hole, which is also a closed polygon. That is all we have to do.
There will be a hole where both polygons overlap.</p>
<p>
In general we will get holes whenever an even number of sub-polygons inside
a single polygon statement overlap. A sub-polygon is defined by a closed
sequence of points.</p>
<p>
The letter P consists of two sub-polygons, one for the outer shape and one
for the hole. Since the hole polygon overlaps the outer shape polygon
we will get a hole.</p>
<p>
After we have understood how multiple sub-polygons in a single polygon
statement work, it is quite easy to add the missing O letter.</p>
<p>
Finally, we get the complete word POV.</p>
<pre>
  polygon {
    30,
    &lt;-0.8, 0.0&gt;, &lt;-0.8, 1.0&gt;,    // Letter &quot;P&quot;
    &lt;-0.3, 1.0&gt;, &lt;-0.3, 0.5&gt;,    // outer shape
    &lt;-0.7, 0.5&gt;, &lt;-0.7, 0.0&gt;,
    &lt;-0.8, 0.0&gt;,
    &lt;-0.7, 0.6&gt;, &lt;-0.7, 0.9&gt;,    // hole
    &lt;-0.4, 0.9&gt;, &lt;-0.4, 0.6&gt;,
    &lt;-0.7, 0.6&gt;
    &lt;-0.25, 0.0&gt;, &lt;-0.25, 1.0&gt;,  // Letter &quot;O&quot;
    &lt; 0.25, 1.0&gt;, &lt; 0.25, 0.0&gt;,  // outer shape
    &lt;-0.25, 0.0&gt;,
    &lt;-0.15, 0.1&gt;, &lt;-0.15, 0.9&gt;,  // hole
    &lt; 0.15, 0.9&gt;, &lt; 0.15, 0.1&gt;,
    &lt;-0.15, 0.1&gt;,
    &lt;0.45, 0.0&gt;, &lt;0.30, 1.0&gt;,    // Letter &quot;V&quot;
    &lt;0.40, 1.0&gt;, &lt;0.55, 0.1&gt;,
    &lt;0.70, 1.0&gt;, &lt;0.80, 1.0&gt;,
    &lt;0.65, 0.0&gt;,
    &lt;0.45, 0.0&gt;
    pigment { color rgb &lt;1, 0, 0&gt; }
  }
</pre>

<table class="centered" width="340px" cellpadding="0" cellspacing="10">
  <tr>
    <td><img class="center" width="320px" src="images/4/42/TutImgPolyword.png"></td>
  </tr>
  <tr>
    <td>
      <p class="caption">The word &quot;POV&quot; made with one polygon statement.</p>
    </td>
  </tr>
</table>

</div>
<a name="t2_3_3"></a>
<div class="content-level-h3" contains="Other Shapes" id="t2_3_3">
<h3>2.3.3 Other Shapes</h3>
</div>
<a name="t2_3_3_1"></a>
<div class="content-level-h4" contains="Blob Object" id="t2_3_3_1">
<h4>2.3.3.1 Blob Object</h4>
<p>Blobs are described as spheres and cylinders covered with <em>goo</em> which stretches to smoothly join them (see section <a href="r3_4.html#r3_4_5_1_1">Blob</a>).</p>
<p>
Ideal for modeling atoms and molecules, blobs are also powerful tools for
creating many smooth flowing <em>organic</em> shapes.</p>
<p>
A slightly more mathematical way of describing a blob would be to say that
it is one object made up of two or more component pieces. Each piece is
really an invisible field of force which starts out at a particular strength
and falls off smoothly to zero at a given radius. Where ever these components
overlap in space, their field strength gets added together (and yes, we can
have negative strength which gets subtracted out of the total as well). We
could have just one component in a blob, but except for seeing what it looks
like there is little point, since the real beauty of blobs is the way the
components interact with one another.</p>
<p>
Let us take a simple example blob to start. Now, in fact there are a couple
different types of components but we will look at them a little later. For
the sake of a simple first example, let us just talk about spherical
components. Here is a sample POV-Ray code showing a basic camera, light, and
a simple two component blob:</p>
<pre>
  #include &quot;colors.inc&quot;
  background{White}
  camera {
    angle 15
    location &lt;0,2,-10&gt;
    look_at &lt;0,0,0&gt;
  }
  light_source { &lt;10, 20, -10&gt; color White }
  blob {
    threshold .65
    sphere { &lt;.5,0,0&gt;, .8, 1 pigment {Blue} }
    sphere { &lt;-.5,0,0&gt;,.8, 1 pigment {Pink} }
    finish { phong 1 }
  }
</pre>

<table class="centered" width="340px" cellpadding="0" cellspacing="10">
  <tr>
    <td><img class="center" width="320px" src="images/6/68/TutImgSimpblob.png"></td>
  </tr>
  <tr>
    <td>
      <p class="caption">A simple, two-part blob.</p>
    </td>
  </tr>
</table>

<p>The threshold is simply the overall strength value at which the blob
becomes visible. Any points within the blob where the strength matches the
threshold exactly form the surface of the blob shape. Those less than the
threshold are <em>outside</em> and those greater than are <em>inside</em> the
blob.</p>
<p>
We note that the spherical component looks a lot like a simple sphere
object. We have the sphere keyword, the vector representing the location of
the center of the sphere and the float representing the radius of the sphere.
But what is that last float value? That is the individual strength of that
component. In a spherical component, that is how strong the component's
field is at the center of the sphere. It will fall off in a linear
progression until it reaches exactly zero at the radius of the sphere.</p>
<p>
Before we render this test image, we note that we have given each component
a different pigment. POV-Ray allows blob components to be given separate
textures. We have done this here to make it clearer which parts of the blob
are which. We can also texture the whole blob as one, like the finish
statement at the end, which applies to all components since it appears at the
end, outside of all the components. We render the scene and get a basic
kissing spheres type blob.</p>
<p>
The image we see shows the spheres on either side, but they are smoothly
joined by that bridge section in the center. This bridge represents where the
two fields overlap, and therefore stay above the threshold for longer than
elsewhere in the blob. If that is not totally clear, we add the following two
objects to our scene and re-render. We
note that these are meant to be entered as separate sphere objects, not more
components in the blob.</p>
<pre>
  sphere { &lt;.5,0,0&gt;, .8
    pigment { Yellow transmit .75 }
  }
  sphere { &lt;-.5,0,0&gt;, .8
    pigment { Green transmit .75 }
  }
</pre>

<table class="centered" width="340px" cellpadding="0" cellspacing="10">
  <tr>
    <td><img class="center" width="320px" src="images/3/35/TutImgSphblob.png"></td>
  </tr>
  <tr>
    <td>
      <p class="caption">The spherical components made visible.</p>
    </td>
  </tr>
</table>

<p>Now the secrets of the kissing spheres are laid bare. These
semi-transparent spheres show where the components of the blob actually are.
If we have not worked with blobs before, we might be surprised to see that
the spheres we just added extend way farther out than the spheres that
actually show up on the blobs. That of course is because our spheres have
been assigned a starting strength of one, which gradually fades to zero as we
move away from the sphere's center. When the strength drops below the
threshold (in this case 0.65) the rest of the sphere becomes part of the
outside of the blob and therefore is not visible.</p>
<p>
See the part where the two transparent spheres overlap? We note that it
exactly corresponds to the bridge between the two spheres. That is the region
where the two components are both contributing to the overall strength of the
blob at that point. That is why the bridge appears: that region has a high
enough strength to stay over the threshold, due to the fact that the combined
strength of two spherical components is overlapping there.</p>

</div>
<a name="t2_3_3_1_1"></a>
<div class="content-level-h5" contains="Component Types and Other New Features" id="t2_3_3_1_1">
<h5>2.3.3.1.1 Component Types and Other New Features</h5>
<p>The shape shown so far is interesting, but limited. POV-Ray has a few
extra tricks that extend its range of usefulness however. For example, as we
have seen, we can assign individual textures to blob components, we can also
apply individual transformations (translate, rotate and scale) to stretch,
twist, and squash pieces of the blob as we require. And perhaps most
interestingly, the blob code has been extended to allow cylindrical
components.</p>
<p>
Before we move on to cylinders, it should perhaps be mentioned that the old
style of components used in previous versions of POV-Ray still work. Back
then, all components were spheres, so it was not necessary to say sphere or
cylinder. An old style component had the form:</p>
<p>
component Strength, Radius, &lt;Center&gt;</p>

<p>This has the same effect as a spherical component, just as we already saw
above. This is only useful for backwards compatibility. If we already have
POV-Ray files with blobs from earlier versions, this is when we would need to
recognize these components. We note that the old style components did not put
braces around the strength, radius and center, and of course, we cannot
independently transform or texture them. Therefore if we are modifying an
older work into a new version, it may arguably be of benefit to convert old
style components into spherical components anyway.</p>
<p>
Now for something new and different: cylindrical components. It could be
argued that all we ever needed to do to make a roughly cylindrical portion of
a blob was string a line of spherical components together along a straight
line. Which is fine, if we like having extra to type, and also assuming that
the cylinder was oriented along an axis. If not, we would have to work out
the mathematical position of each component to keep it is a straight line.
But no more! Cylindrical components have arrived.</p>
<p>
We replace the blob in our last example with the following and re-render. We
can get rid of the transparent spheres too, by the way.</p>
<pre>
  blob {
    threshold .65
    cylinder { &lt;-.75,-.75,0&gt;, &lt;.75,.75,0&gt;, .5, 1 }
    pigment { Blue }
    finish { phong 1 }
  }
</pre>

<p>We only have one component so that we can see the basic shape of the
cylindrical component. It is not quite a true cylinder - more of a sausage
shape, being a cylinder capped by two hemispheres. We think of it as if it
were an array of spherical components all closely strung along a straight
line.</p>
<p>
As for the component declaration itself: simple, logical, exactly as we
would expect it to look (assuming we have been awake so far): it looks pretty
much like the declaration of a cylinder object, with vectors specifying the
two endpoints and a float giving the radius of the cylinder. The last float,
of course, is the strength of the component. Just as with spherical
components, the strength will determine the nature and degree of this
component's interaction with its fellow components. In fact, next let us
give this fellow something to interact with, shall we?</p>
</div>
<a name="t2_3_3_1_2"></a>
<div class="content-level-h5" contains="Complex Blob Constructs and Negative Strength" id="t2_3_3_1_2">
<h5>2.3.3.1.2 Complex Blob Constructs and Negative Strength</h5>
<p>Beginning a new POV-Ray file, we enter
this somewhat more complex example:</p>
<pre>
#include &quot;colors.inc&quot;
background{White}
camera {
  angle 20
  location&lt;0,2,-10&gt;
  look_at&lt;0,0,0&gt;
}
light_source { &lt;10, 20, -10&gt; color White }
blob {
  threshold .65
  sphere{&lt;-.23,-.32,0&gt;,.43, 1 scale &lt;1.95,1.05,.8&gt;}   //palm
  sphere{&lt;+.12,-.41,0&gt;,.43, 1 scale &lt;1.95,1.075,.8&gt;}  //palm
  sphere{&lt;-.23,-.63,0&gt;, .45, .75 scale &lt;1.78, 1.3,1&gt;} //midhand
  sphere{&lt;+.19,-.63,0&gt;, .45, .75 scale &lt;1.78, 1.3,1&gt;} //midhand
  sphere{&lt;-.22,-.73,0&gt;, .45, .85 scale &lt;1.4, 1.25,1&gt;} //heel
  sphere{&lt;+.19,-.73,0&gt;, .45, .85 scale &lt;1.4, 1.25,1&gt;} //heel
  cylinder{&lt;-.65,-.28,0&gt;, &lt;-.65,.28,-.05&gt;, .26, 1}    //lower pinky
  cylinder{&lt;-.65,.28,-.05&gt;, &lt;-.65, .68,-.2&gt;, .26, 1}  //upper pinky
  cylinder{&lt;-.3,-.28,0&gt;, &lt;-.3,.44,-.05&gt;, .26, 1}      //lower ring
  cylinder{&lt;-.3,.44,-.05&gt;, &lt;-.3, .9,-.2&gt;, .26, 1}     //upper ring
  cylinder{&lt;.05,-.28,0&gt;, &lt;.05, .49,-.05&gt;, .26, 1}     //lower middle
  cylinder{&lt;.05,.49,-.05&gt;, &lt;.05, .95,-.2&gt;, .26, 1}    //upper middle
  cylinder{&lt;.4,-.4,0&gt;, &lt;.4, .512, -.05&gt;, .26, 1}      //lower index
  cylinder{&lt;.4,.512,-.05&gt;, &lt;.4, .85, -.2&gt;, .26, 1}    //upper index
  cylinder{&lt;.41, -.95,0&gt;, &lt;.85, -.68, -.05&gt;, .25, 1}  //lower thumb
  cylinder{&lt;.85,-.68,-.05&gt;, &lt;1.2, -.4, -.2&gt;, .25, 1}  //upper thumb
  pigment{ Flesh }
}
</pre>

<table class="centered" width="340px" cellpadding="0" cellspacing="10">
  <tr>
    <td><img class="center" width="320px" src="images/3/30/TutImgBlobhand.png"></td>
  </tr>
  <tr>
    <td>
      <p class="caption">A hand made with blobs.</p>
    </td>
  </tr>
</table>

<p>As we can guess from the comments, we are building a hand here. After we
render this image, we can see there are a few problems with it. The palm and
heel of the hand would look more realistic if we used a couple dozen smaller
components rather than the half dozen larger ones we have used, and each
finger should have three segments instead of two, but for the sake of a
simplified demonstration, we can overlook these points. But there is one
thing we really need to address here: This poor fellow appears to have
horrible painful swelling of the joints!</p>
<p>
A review of what we know of blobs will quickly reveal what went wrong. The
joints are places where the blob components overlap, therefore the combined
strength of both components at that point causes the surface to extend
further out, since it stays over the threshold longer. To fix this, what we
need are components corresponding to the overlap region which have a negative
strength to counteract part of the combined field strength. We add the
following components to our blob.</p>
<pre>
sphere{&lt;-.65,.28,-.05&gt;, .26, -1} //counteract pinky knucklebulge
sphere{&lt;-.65,-.28,0&gt;, .26, -1}   //counteract pinky palm bulge
sphere{&lt;-.3,.44,-.05&gt;, .26, -1}  //counteract ring knuckle bulge
sphere{&lt;-.3,-.28,0&gt;, .26, -1}    //counteract ring palm bulge
sphere{&lt;.05,.49,-.05&gt;, .26, -1}  //counteract middle knuckle bulge
sphere{&lt;.05,-.28,0&gt;, .26, -1}    //counteract middle palm bulge
sphere{&lt;.4,.512,-.05&gt;, .26, -1}  //counteract index knuckle bulge
sphere{&lt;.4,-.4,0&gt;, .26, -1}      //counteract index palm bulge
sphere{&lt;.85,-.68,-.05&gt;, .25, -1} //counteract thumb knuckle bulge
sphere{&lt;.41,-.7,0&gt;, .25, -.89}   //counteract thumb heel bulge
</pre>

<table class="centered" width="340px" cellpadding="0" cellspacing="10">
  <tr>
    <td><img class="center" width="320px" src="images/e/ed/TutImgImprhand.png"></td>
  </tr>
  <tr>
    <td>
      <p class="caption">The hand without the swollen joints.</p>
    </td>
  </tr>
</table>

<p>Much better! The negative strength of the spherical components counteracts
approximately half of the field strength at the points where to components
overlap, so the ugly, unrealistic (and painful looking) bulging is cut out
making our hand considerably improved. While we could probably make a yet
more realistic hand with a couple dozen additional components, what we get
this time is a considerable improvement. Any by now, we have enough basic
knowledge of blob mechanics to make a wide array of smooth, flowing organic
shapes!</p>
</div>
<a name="t2_3_3_2"></a>
<div class="content-level-h4" contains="Height Field Object" id="t2_3_3_2">
<h4>2.3.3.2 Height Field Object</h4>
<p>A <code>height_field</code> is an object that has a surface that is
determined by the color value or palette index number of an image designed
for that purpose. With height fields, realistic mountains and other types of
terrain can easily be made. First, we need an image from which to create the
height field. It just so happens that POV-Ray is ideal for creating such an
image.</p>
<p>
We make a new file called <code>image.pov</code> and edit it to contain the
following:</p>
<pre>
  #include &quot;colors.inc&quot;
  global_settings {
    assumed_gamma 2.2
    hf_gray_16
  }
</pre>

<p>The <code><a href="r3_4.html#r3_4_1_4">hf_gray_16</a></code> keyword causes the output to be in a special 16 bit grayscale that is perfect for generating height fields. The normal 8 bit output will lead to less smooth surfaces.</p>
<p>
Now we create a camera positioned so that it points directly down the z-axis
at the origin.</p>
<pre>
  camera {
    location &lt;0, 0, -10&gt;
    look_at 0
  }
</pre>

<p>We then create a plane positioned like a wall at z=0. This plane will
completely fill the screen. It will be colored with white and gray
wrinkles.</p>
<pre>
  plane { z, 10
    pigment {
      wrinkles
      color_map {
       [0 0.3*White]
       [1 White]
      }
    }
  }
</pre>

<p>Finally, create a light source.</p>
<pre>
  light_source { &lt;0, 20, -100&gt; color White }
</pre>

<p>We render this scene at 640x480 <code>+A0.1</code> <code>+FT</code>.
We will get an image that will produce an excellent height field. We create a
new file called <code>hfdemo.pov</code> and edit it as follows:</p>
<p class="Note"><strong>Note:</strong> Unless you specify <code>+FT</code> as above, you will get a <em>PNG</em> file, the default cross-platform output file type. In this case you will need to use <code>png</code> instead of <code>tga</code> in the <code>height_field</code> statement below.</p>
<pre>
  #include &quot;colors.inc&quot;
</pre>

<p>We add a camera that is two units above the origin and ten units back ...</p>
<pre>
  camera{
    location &lt;0, 2, -10&gt;
    look_at 0
    angle 30
  }
</pre>

<p>... and a light source.</p>
<pre>
  light_source{ &lt;1000,1000,-1000&gt; White }
</pre>

<p>Now we add the height field. In the following syntax, a Targa image file
is specified, the height field is smoothed, it is given a simple white
pigment, it is translated to center it around the origin and it is scaled so
that it resembles mountains and fills the screen.</p>
<pre>
  height_field {
    tga &quot;image.tga&quot;
    smooth
    pigment { White }
    translate &lt;-.5, -.5, -.5&gt;
    scale &lt;17, 1.75, 17&gt;
  }
</pre>

<p>We save the file and render it at 320x240 <code>-A</code>. Later, when we
are satisfied that the height field is the way we want it, we render it at a
higher resolution with anti-aliasing.</p>

<table class="centered" width="340px" cellpadding="0" cellspacing="10">
  <tr>
    <td><img class="center" width="320px" src="images/9/9f/TutImgPvhfield.png"></td>
  </tr>
  <tr>
    <td>
      <p class="caption">A height field created completely with POV-Ray.</p>
    </td>
  </tr>
</table>

<p>Wow! The Himalayas have come to our computer screen!</p>

</div>
<a name="t2_3_3_3"></a>
<div class="content-level-h4" contains="Isosurface Object" id="t2_3_3_3">
<h4>2.3.3.3 Isosurface Object</h4>
<p>Isosurfaces are shapes described by mathematical functions.</p>

<p>In contrast to the other mathematically based shapes in POV-Ray, isosurfaces
are approximated during rendering and therefore they are sometimes more
difficult to handle. However, they offer many interesting possibilities, like real deformations and surface displacements</p>

<p>Some knowledge about mathematical functions and geometry is useful,
but not necessarily required to work with isosurfaces.</p>

</div>


<a name="t2_3_3_3_1"></a>
<div class="content-level-h5" contains="Simple functions" id="t2_3_3_3_1">
<h5>2.3.3.3.1 Simple functions</h5>
<p>Let's begin with something simple. In this first series of images, let's explore the <a href="r3_3.html#r3_3_1_8">user defined function</a> shown as <code>function&nbsp;{&nbsp;x&nbsp;}</code> that we see in the code example below. It produces the first image on the left, a simple box. The container, which is a requirement for the isosurface object, is represented by the box object and the <code>contained_by</code> keyword in the isosurface definition.</p>

<pre>
  isosurface {
    function { x }
    contained_by { box { -2, 2 } }
  }
</pre>

<p>You should have also noticed that in the image on the left, only half the box was produced, that's because the <code>threshold</code> keyword was omitted, so the <em>default value</em> 0 was used to evaluate the x-coordinate.</p>
<p>In this next code example <code>threshold 1</code> was added to produce the center image.</p>

<pre>
  isosurface {
    function { x }
    threshold 1
    contained_by { box { -2, 2 } }
  }
</pre>

<p>It is also possible to <em>remove</em> the visible surfaces of the container by adding the <code>open</code> keyword to the isosurface definition. </p>
<p>For the final image on the right, the following code example was used. Notice that the <em>omission</em> of the <code>threshold</code> keyword causes the x-coordinate to be again evaluated to zero.</p>

<pre>
  isosurface {
    function { x }
    open
    contained_by { box { -2, 2 } }
  }
</pre>

<table class="centered" width="770px" cellpadding="0" cellspacing="10">
<tr>
  <td>
    <img class="leftpanel" width="220px" src="images/7/71/TutImgIso_01.png">
  </td>
  <td>
    <img class="centerpanel" width="220px" src="images/e/ee/TutImgIso_02.png">
  </td>
  <td>
    <img class="rightpanel" width="220px" src="images/a/a6/TutImgIso_03.png">
  </td>
</tr>
<tr>
  <td>
    <p class="caption">function { x }</p>
  </td>
  <td>
    <p class="caption">function { x } with threshold 1</p>
  </td>
  <td>
    <p class="caption">function { x } with open</p>
  </td>
</tr>
</table>

<p class="Hint"><strong>Hint:</strong> The checkered ground plane is scaled to one unit squares.</p>

<p>For the last series of images in this section, let's try something different. These next two code examples were used to show the results of changing the user defined function to <code>function&nbsp;{&nbsp;x+y&nbsp;}</code> and <code>function&nbsp;{&nbsp;x+y+z&nbsp;}</code> respectively. They describe planes going through the origin, the function just describes the normal vector of the plane.</p>

<pre>
  isosurface {
    function { x+y }
    max_gradient 4
    contained_by { box { -2, 2 } }
  }
</pre>

<p class="Note"><strong>Note:</strong> To properly render these examples <code>max_gradient 4</code> was added to the isosurface definition, and will be explained later.</p>

<pre>
  isosurface {
    function { x+y+z }
    max_gradient 4
    contained_by { box { -2, 2 } }
  }
</pre>

<table class="centered" width="460px" cellpadding="0" cellspacing="10">
<tr>
  <td>
    <img class="leftpanel" width="220px" src="images/5/56/TutImgIso_04.png">
  </td>
  <td>
    <img class="rightpanel" width="220px" src="images/6/67/TutImgIso_05.png">
  </td>
</tr>
<tr>
  <td>
    <p class="caption">plane function { x+y }</p>
  </td>
  <td>
    <p class="caption">plane function { x+y+z }</p>
  </td>
</tr>
</table>

<p class="Note"><strong>Note:</strong> When appropriate, to better visualize the difference between the isosurface and the container object, the images in this tutorial have been color coded.</p>

</div>
<a name="t2_3_3_3_2"></a>
<div class="content-level-h5" contains="Several surfaces" id="t2_3_3_3_2">
<h5>2.3.3.3.2 Several surfaces</h5>
<p>Now that you're starting to become familiar with <code>isosurface</code> syntax, there really isn't any need to show a code example for each and every image. You can always look back at the earlier examples when needed. The image captions will most often contain additional keyword hints when appropriate.</p>
<p class="Note"><strong>Note:</strong> The user defined function portion will <em>always</em> use this color coded format: <code>function&nbsp;{&nbsp;x+y+z&nbsp;}</code></p>

<p>For the first image on the left, these two functions lead to identical results: <code>function&nbsp;{&nbsp;abs(x)-1&nbsp;}</code> and <code>function&nbsp;{&nbsp;sqrt(x*x)-1&nbsp;}</code> because both of these formulas have the same solution where the function value is 0, specifically <code>x=-1</code> and <code>x=1</code> in this example.</p>
<p>You can easily mix any of these elements in different combinations, but the results always produce planar surfaces. The last two images in this series used <code>function&nbsp;{&nbsp;abs(x)-1+y&nbsp;}</code> and <code>function&nbsp;{&nbsp;abs(x)+abs(y)+abs(z)-2&nbsp;}</code> respectively.</p>

<table class="centered" width="700px" cellpadding="0" cellspacing="10">
<tr>
  <td>
    <img class="leftpanel" width="220px" src="images/5/50/TutImgIso_06.png">
  </td>
  <td>
    <img class="centerpanel" width="220px" src="images/f/f5/TutImgIso_07.png">
  </td>
  <td>
    <img class="rightpanel" width="220px" src="images/9/95/TutImgIso_08.png">
  </td>
</tr>
<tr>
  <td>
    <p class="caption">identical results with open</p>
  </td>
  <td>
    <p class="caption">linear functions x &amp; y axis</p>
  </td>
  <td>
    <p class="caption">linear functions x, y &amp; z axis</p>
  </td>
</tr>
</table>

</div>
<a name="t2_3_3_3_3"></a>
<div class="content-level-h5" contains="Non-linear functions" id="t2_3_3_3_3">
<h5>2.3.3.3.3 Non-linear functions</h5>
<table class="centered" width="570px" cellpadding="0" cellspacing="10">
<tr>
  <td>
    <img class="leftpanel" width="220px" src="images/a/a0/TutImgIso_09.png">
  </td>
  <td>
    <p class="tabletext">Curved surfaces of many different kinds can be achieved with non-linear
functions. A square function creates the parabolic shape:<br><code>function&nbsp;{&nbsp;pow(x,2)+y&nbsp;}</code></p>
  </td>
</tr>
<tr>
  <td>
    <p class="caption">a parabolic shape</p>
  </td>
  <td></td>
</tr>
</table>

<table class="centered" width="570px" cellpadding="0" cellspacing="10">
<tr>
  <td>
    <p class="tabletext">If you describe a circle in 2 dimensions with a constant in the 3rd dimension you get a cylinder:<br><code> function&nbsp;{&nbsp;sqrt(pow(x,2)+pow(z,2))-1&nbsp;}</code></p>
  </td>
  <td>
    <img class="rightpanel" width="220px" src="images/c/c0/TutImgIso_10.png">
  </td>
</tr>
<tr>
  <td></td>
  <td>
    <p class="caption">the cylinder shape</p>
  </td>
</tr>
</table>

<table class="centered" width="570px" cellpadding="0" cellspacing="10">
<tr>
  <td>
    <img class="leftpanel" width="220px" src="images/f/fd/TutImgIso_11.png">
  </td>
  <td>
    <p class="tabletext">It's easy to change a cylinder into a cone, we just need
to add a linear component in y-direction:<br><code>function&nbsp;{&nbsp;sqrt(pow(x,2)+pow(z,2))+y&nbsp;}</code></p>
  </td>
</tr>
<tr>
  <td>
    <p class="caption">the cone shape</p>
  </td>
  <td></td>
  <td></td>
</tr>
</table>

<table class="centered" width="570px" cellpadding="0" cellspacing="10">
<tr>
  <td>
    <p class="tabletext">No worries, creating a sphere is easy too. In this example <code>2</code> specifies the radius:<br><code> function&nbsp;{&nbsp;sqrt(pow(x,2)+pow(y,2)+pow(z,2))-2&nbsp;}</code></p>
  </td>
  <td>
    <img class="rightpanel" width="220px" src="images/2/2d/TutImgIso_12.png">
  </td>
</tr>
<tr>
  <td></td>
  <td>
    <p class="caption">the sphere shape</p>
  </td>
</tr>
</table>

</div>
<a name="t2_3_3_3_4"></a>
<div class="content-level-h5" contains="Specifying functions" id="t2_3_3_3_4">
<h5>2.3.3.3.4 Specifying functions</h5>
<p>Until now, we have seen, the functions used to define the isosurface were literally written in the <code>function {...}</code> block:</p>
<pre>
#declare Threshold = 1;

isosurface {
function {pow(x,2) + pow(y,2) + pow(z,2)}
  threshold Threshold
  ...
}
</pre>

<p>Let's expand on that concept, and add some flexibility. Remember that user defined functions (like equations), all float expressions and operators which are legal in POV-Ray can be used, and that functions should be declared first, and then used in the isosurface. See the section <a href="r3_3.html#r3_3_1_8">user defined function</a> for more information.</p>

<p>This next example takes the above equation, and rewrites it as a user defined function. By default a function that takes three parameters (x,y,z) does not require you to explicitly specify the parameter names when declaring it,  however when <em>using</em> the identifier, the parameters <em>must</em> be specified.</p>

<pre>
#declare Threshold = 1;

#declare Sphere = function {pow(x,2) + pow(y,2) + pow(z,2)};

isosurface {
  function { Sphere(x,y,z) }
  threshold Threshold
  ...
}
</pre>

<p>However, if you need more or less than three parameters when declaring a function, you will also have to explicitly specify the parameter names.</p>
<pre>
#declare Sphere = function (x,y,z,Radius) {pow(x,2) + pow(y,2) + pow(z,2) - pow(Radius,2)};

isosurface {
  function { Sphere(x,y,z,1) }
  ...
}
</pre>

</div>
<a name="t2_3_3_3_5"></a>
<div class="content-level-h5" contains="Internal functions" id="t2_3_3_3_5">
<h5>2.3.3.3.5 Internal functions</h5>
<p>There are a lot of internal functions available in POV-Ray. For example a sphere could also be generated with <code>function&nbsp;{&nbsp;f_sphere(x,&nbsp;y,&nbsp;z,&nbsp;2)&nbsp;}</code>, for these and other functions, see the <code>functions.inc</code> include file. Most of them are more complicated and it is usually faster to use them instead of a hand coded equivalent.</p>
<p>See the <a href="r3_4.html#r3_4_9_1_7">complete list</a> for details.</p>

<p>The following makes a torus just like POV-Ray's torus object:</p>

<pre>
  #include &quot;functions.inc&quot;

  isosurface {
    function { f_torus(x, y, z, 1.6, 0.4) }
    contained_by { box { -2, 2 } }
  }
</pre>

<table class="centered" width="570px" cellpadding="0" cellspacing="10">
<tr>
  <td>
    <img class="leftpanel" width="220px" src="images/9/9f/TutImgIso_13.png">
  </td>
  <td>
    <p class="tabletext">The 4th and 5th parameters are the major and minor radius, just like the corresponding values in the <code>torus{}</code> object.</p>
    <p class="tabletext">The parameters x, y and z are required, because it is a declared function. You can also declare functions yourself like it is explained in the <a href="r3_3.html#r3_3_1_8_3">reference section</a>.</p>
  </td>
</tr>
<tr>
  <td>
    <p class="caption">the torus function</p>
  </td>
  <td></td>
</tr>
</table>

</div>
<a name="t2_3_3_3_6"></a>
<div class="content-level-h5" contains="Combining isosurface functions" id="t2_3_3_3_6">
<h5>2.3.3.3.6 Combining isosurface functions</h5>
<p>We can also simulate some Constructive Solid Geometry with isosurface functions.  If you do not know about CSG we suggest you have a look at <em><a href="t2_2.html#t2_2_3_1">What is CSG?</a></em> or the corresponding part of the <a href="r3_4.html#r3_4_5_4">reference section</a> first.</p>

<p>For this next group of images, consider the two functions for a cylinder and a rotated box:</p>

<pre>
  #declare fn_A = function { sqrt(pow(y,2) + pow(z,2)) - 0.8 }
  #declare fn_B = function { abs(x)+abs(y)-1 }
</pre>

<ol>
  <li>If we combine them the following way, we get a <em>merge</em>:<br>
<code>function { min(fn_A(x, y, z), fn_B(x, y, z)) }</code></li>
  <li>An <em>intersection</em> can be obtained by using <code>max()</code> instead of <code>min()</code>:<br>
<code>function { max(fn_A(x, y, z), fn_B(x, y, z)) }</code>
</li>
  <li>A <em>difference</em> is possible, by adding a minus (-) before the second function:<br>
<code>function { max(fn_A(x, y, z), -fn_B(x, y, z)) }</code>
</li>
</ol>

<table class="centered" width="700px" cellpadding="0" cellspacing="10">
<tr>
  <td>
    <img class="leftpanel" width="220px" src="images/7/77/TutImgIso_14.png">
  </td>
  <td>
    <img class="centerpanel" width="220px" src="images/6/69/TutImgIso_15.png">
  </td>
  <td>
    <img class="rightpanel" width="220px" src="images/8/80/TutImgIso_16.png">
  </td>
</tr>
<tr>
  <td>
    <p class="caption">merge example</p>
  </td>
  <td>
    <p class="caption">intersection example</p>
  </td>
  <td>
    <p class="caption">difference example</p>
  </td>
</tr>
</table>

<p>Apart from basic CSG you can also obtain smooth transits between the different surfaces, for instance the <a href="t2_3.html#t2_3_3_1">blob object</a>:</p>

<pre>
  #declare Blob_Threshold=0.01;

  isosurface {
    function {
      (1+Blob_Threshold)
      -pow(Blob_Threshold, fn_A(x,y,z))
      -pow(Blob_Threshold, fn_B(x,y,z))
    }
    max_gradient 4
    contained_by { box { -2, 2 } }
  }
</pre>

<table class="centered" width="570px" cellpadding="0" cellspacing="10">
<tr>
  <td>
    <img class="leftpanel" width="220px" src="images/c/c9/TutImgIso_17.png">
  </td>
  <td>
    <p class="tabletext">The <code>Blob_Threshold</code> value influences the smoothness of
the transit between the shapes.  A lower value leads to sharper edges, and it's function looks like:</p>
<pre>
function{fn_A(x,y,z) + pow(Blob_Threshold,(fn_B(x,y,z) + Strength))}
</pre>
  </td>
</tr>
<tr>
  <td>
    <p class="caption">smooth transitions using blob</p>
  </td>
</tr>
</table>

</div>
<a name="t2_3_3_3_7"></a>
<div class="content-level-h5" contains="Noise and pigment functions" id="t2_3_3_3_7">
<h5>2.3.3.3.7 Noise and pigment functions</h5>
<p>Some of the <a href="r3_3.html#r3_3_1_8_6">internal functions</a> have a random or noise-like structure</p>

<p>Together with the pigment functions they are one of the most powerful tools for designing isosurfaces. We can add real surface displacement to the objects rather than only normal perturbation known from the <a href="r3_4.html#r3_4_6_2">normal</a> statement.</p>

<p>The relevant internal functions are:</p>

<ul>
<li><code>f_noise3d(x,y,z)</code><br>
uses the <a href="r3_4.html#r3_4_7_5_4">noise generator</a> specified in <code>global_settings</code> and generates structures like the bozo pattern.</li>
<li><code>f_noise_generator(x, y, z, noise_generator)</code><br>
generates noise with a specified noise generator.</li>
<li><code>f_ridged_mf(x, y, z, H, Lacunarity, Octaves, Offset, Gain, noise_generator)</code><br>
generates a ridged multifractal pattern.</li>
<li><code>f_ridge(x, y, z, Lambda, Octaves, Omega, Offset, Ridge, noise_generator)</code><br>
generates another noise with ridges.</li>
<li><code>f_hetero_mf(x, y, z, H, Lacunarity, Octaves, Offset, T, noise_generator)</code><br>
generates heterogenic multifractal noise.</li>
</ul>

<table class="centered" width="570px" cellpadding="0" cellspacing="10">
<tr>
  <td>
    <p class="tabletext">Using this simple noise3d function results in the image on the right. The value <code>-0.5</code> matches the default <code>threshold</code> value of zero. The <code>f_noise3d</code> function returns values between 0 and 1:</p> 
    <p class="tabletext"><code>function&nbsp;{&nbsp;f_noise3d(x,y,z)-0.5&nbsp;}</code></p>
  </td>
  <td>
    <img class="rightpanel" width="220px" src="images/7/77/TutImgIso_18.png">
  </td>
</tr>
<tr>
  <td></td>
  <td>
    <p class="caption">simple noise3d function</p>
  </td>
</tr>
</table>

<table class="centered" width="570px" cellpadding="0" cellspacing="10">
<tr>
  <td>
    <p class="tabletext">In these next two images the noise function was added to a plane function. The x-parameter was set to 0 so the noise function is constant in x-direction. This way we achieve the typical heightfield structure.</p>
  </td>
</tr>
</table>

<table class="centered" width="570px" cellpadding="0" cellspacing="10">
<tr>
  <td>
    <img class="leftpanel" width="220px" src="images/4/49/TutImgIso_19.png">
  </td>
  <td>
    <p class="tabletext">With this and the other functions you can generate objects similar to heightfields, having the advantage that a high resolution can be achieved without high memory requirements:</p>
    <p class="tabletext"><code>function&nbsp;{&nbsp;x&nbsp;+&nbsp;f_noise3d(0,y,z)&nbsp;}</code></p> 
  </td>   
</tr>
<tr>
  <td>
    <p class="caption">a noise3d heightfield</p>
  </td>
  <td></td>
</tr>
</table>

<table class="centered" width="570px" cellpadding="0" cellspacing="10">
<tr>
  <td>
    <p class="tabletext">The noise function can of course also be subtracted which results in an <em>inverted</em> version:</p>
    <p class="tabletext"><code>function&nbsp;{&nbsp;x&nbsp;-&nbsp;f_noise3d(0,y,z)&nbsp;}</code></p>
  </td>
  <td>
    <img class="rightpanel" width="220px" src="images/9/9d/TutImgIso_20.png">
  </td>
</tr>
<tr>
  <td></td>
  <td>
    <p class="caption">a noise3d heightfield - inverted</p>
  </td>
</tr>
</table>

<table class="centered" width="570px" cellpadding="0" cellspacing="10">
<tr>
  <td>
    <img class="leftpanel" width="220px" src="images/0/0e/TutImgIso_21.png">
  </td>
  <td>
    <p class="tabletext">Of course we can also add noise to any other function. If the noise function is very strong this can result in several separated surfaces.</p>
    <p class="tabletext"><code>function&nbsp;{&nbsp;f_sphere(x,y,z,1.2)&nbsp;-&nbsp;f_noise3d(x,y,z)&nbsp;}</code></p>
  </td>
</tr>
<tr>
  <td>
    <p class="caption">noise3d on a sphere</p>
  </td>
  <td>
  </td>
</tr>
</table>

<table class="centered" width="570px" cellpadding="0" cellspacing="10">
<tr>
  <td>
    <p class="tabletext">This is a noise function applied to a sphere surface, we can influence the intensity of the noise by multiplying it with a factor and change the scale by multiplying the coordinate parameters:</p>
    <p class="tabletext"><code>function&nbsp;{</code><br><code>&nbsp;&nbsp;f_sphere(x,y,z,1.6)&nbsp;-</code><br><code>&nbsp;&nbsp;&nbsp;&nbsp;f_noise3d(x*5,y*5,z* )&nbsp;*&nbsp;0.5<br>&nbsp;&nbsp;&nbsp;&nbsp;}</code></p>
  </td>
  <td>
    <img class="rightpanel" width="220px" src="images/9/9c/TutImgIso_22.png">
  </td>
</tr>
<tr>
  <td></td>
  <td>
    <p class="caption">noise3d on a sphere - scaled</p>
  </td>
</tr>
</table>

<p>As alternative to noise functions we can also use any pigment in a function:</p>

<pre>
  #declare fn_Pigm=function {
    pigment {
      agate
      color_map {
        [0 color rgb 0]
        [1 color rgb 1]
      }
    }
  }
</pre>

<p>This is a vector function, it returns a color vector for use in isosurface functions. They <em>must</em> be pre-declared first. When using the identifier, you have to specify which component of the color vector should be used.</p>
<p>To do this, the dot notation is used. Refer to the above example: <code>fn_Pigm(x,y,z).red</code></p>

<p>A color vector has five components, their supported dot types to access these components are:</p>

<ol>
  <li><code>fn_Pigm( ).x</code> | <code>fn_Pigm( ).u</code> | <code>fn_Pigm( ).red</code><br>
to get the red value of the color vector </li>
  <li><code>fn_Pigm( ).y</code> | <code>fn_Pigm( ).v</code> | <code>fn_Pigm( ).green</code><br>
to get the green value of the color vector</li>
  <li><code>fn_Pigm( ).z</code> | <code>fn_Pigm( ).blue</code><br>
to get the blue value of the color vector</li>
  <li><code>fn_Pigm( ).filter</code> | <code>fn_Pigm( ).f</code><br>
to get the filter value of the color vector</li>
  <li><code>fn_Pigm( ).transmit</code> | <code>fn_Pigm( ).t</code><br>
to get the transmit value of the color vector</li>
</ol>

<p>And two special purpose operators, their supported dot types to access these operators are:</p>
<p class="Note"><strong>Note:</strong> The <code>.hf</code> operator is experimental and will generate a warning.</p> 

<ol>
  <li><code>fn_Pigm( ).gray</code> to get the gray value of the color vector<br>
<em>gray value</em> = Red*29.7% + Green*58.9% + Blue*11.4% </li>
  <li><code>fn_Pigm( ).hf</code> to get the height_field value of the color vector<br>
<em>hf value</em> = (Red + Green/255)*0.996093</li>
</ol>

<table class="centered" width="570px" cellpadding="0" cellspacing="10">
<tr>
  <td>
    <img class="leftpanel" width="220px" src="images/c/c2/TutImgIso_23.png">
  </td>
  <td>
    <p class="tabletext">There are quite a lot of things possible with pigment functions. However, it should be noted that, some functions can cause longer render times:</p>
    <p class="tabletext"><code>function {<br>&nbsp;&nbsp;f_sphere(x,&nbsp;y,&nbsp;z,&nbsp;1.6)&nbsp;-<br>&nbsp;&nbsp;&nbsp;&nbsp;fn_Pigm(x/2,&nbsp;y/2,&nbsp;z/2).gray*0.5<br>&nbsp;&nbsp;&nbsp;&nbsp;}</code></p>
  </td>
</tr>
<tr>
  <td>
    <p class="caption">noise using a pigment function</p>
  </td>
  <td></td>
</tr>
</table>

</div>
<a name="t2_3_3_3_8"></a>
<div class="content-level-h5" contains="Conditional directives and loops" id="t2_3_3_3_8">
<h5>2.3.3.3.8 Conditional directives and loops</h5>
<p>
Conditional directives are allowed in functions: 
</p>

<pre>
#declare Rough = yes;
#include &quot;functions.inc&quot;
isosurface {
  function { y #if(Rough=1)-f_noise3d(x/0.5,y/0.3,z/0.4)*0.8 #end }
  ...
}
</pre>

<p>
Loops can also be used in functions: 
</p>

<pre>
#include &quot;functions.inc&quot;
#declare Thr = 1/1000;
#declare Ang = radians(45);
#declare Offset = 1.5;
#declare Scale = 1.2;
#declare TrSph = function { f_sphere(x-Offset,y,z,0.7*Scale) }

function {
  (1-Thr)
  #declare A = 0;
  #while (A&lt;8)
  -pow(Thr, TrSph(x*cos(A*Ang) + y*sin(A*Ang),
                  y*cos(A*Ang) -x*sin(A*Ang), z) )
    #declare A=A+1;
  #end
}
</pre>

<p class="Note"><strong>Note:</strong> The loops and conditionals are evaluated at parse time, not at render time.</p>

</div>
<a name="t2_3_3_3_9"></a>
<div class="content-level-h5" contains="Transformations on functions" id="t2_3_3_3_9">
<h5>2.3.3.3.9 Transformations on functions</h5>
<p>Transforming an isosurface object is done like transforming any POV-Ray object. Simply use the object modifiers, scale, translate, and rotate. However, when you want to transform functions within the <code>contained_by</code> object, you have to substitute parameters in the functions.</p>

<p>The results <em>seem</em> inverted to what you would normally expect, here's why:</p>

<p>Remember the sphere function we created earlier in this tutorial: <code>Sphere(x,y,z)</code></p>
<p>We know it sits at the origin because <code>x=0</code>. If we want to translate it 2 units to the right to <code>x=2</code> we need to write the second equation in the same form: <code>x-2=0</code>. Now that both equations equal zero, we can replace the parameter <code>x</code> with <code>x-2</code>, call our function as: <code>Sphere(x-2,y,z)</code> and it's translated two units to the right.</p>

<p>Let's look at how to scale our test sphere by <code>0.5</code> in the <em>y direction</em>. Given the default value of <code>y=1</code> <em>one unit</em> we'd want <code>y=0.5</code>. To do this we need to have the equation in the same form as the first one, so we'll multiply both sides by two: <code>y*2 = 0.5*2</code> which gives <code>y*2=1</code>.</p>
<p>Now we can replace the <code>y</code> parameter in our sphere: <code>Sphere(x,y*2,z)</code>. This scales the <em>y-size</em> of the sphere by half.</p>

<p>Here is an overview of some useful substitutions, we'll be using a pseudo-object designated as <code>P(x,y,z)</code> in the following examples:</p>

<p><strong>Scale:</strong></p>
<p>&nbsp;&nbsp;To scale <code>x</code> replace <code>x</code> with <code>x/scale</code>:<br>&nbsp;&nbsp;<code>P(x/2,y,z)</code></p>

<p><strong>Scale Infinitely:</strong></p>
<p>&nbsp;&nbsp;To scale <code>y</code> infinitely replace <code>y</code> with <code>0</code>:<br>&nbsp;&nbsp;<code>P(x,0,z)</code></p>

<p><strong>Translate:</strong></p>
<p>&nbsp;&nbsp;To translate <code>z</code> replace <code>z</code> with <code>z&nbsp;-&nbsp;translation</code>:<br>&nbsp;&nbsp;<code>P(x,y,z-3)</code></p>

<p><strong>Shear:</strong></p>
<p>&nbsp;&nbsp;To shear in <em>xy-plane</em> replace <code>x</code> with <code>x + y*tan(radians(Angle))</code>:<br>&nbsp;&nbsp;<code>P(x+y*tan(radians(Angle)),y,z)</code></p>

<p><strong>Rotate:</strong></p>
<p class="Note"><strong>Note:</strong> These rotation substitutions work like normal POV-rotations, they already compensate for the inverse behavior.</p>

<p>To rotate around the X-axis:</p>
<p>&nbsp;&nbsp;replace <code>y</code> with <code>z*sin(radians(Angle)) + y*cos(radians(Angle))</code></p>
<p>&nbsp;&nbsp;replace <code>z</code> with <code>z*cos(radians(Angle)) - y*sin(radians(Angle))</code></p>

<p>To rotate around the Y-axis:</p>
<p>&nbsp;&nbsp;replace <code>x</code> with <code>x*cos(radians(Angle)) - z*sin(radians(Angle))</code></p>
<p>&nbsp;&nbsp;replace <code>z</code> with <code>x*sin(radians(Angle)) + z*cos(radians(Angle))</code></p>

<p>To rotate around the Z-axis:</p>
<p>&nbsp;&nbsp;replace <code>x</code> with <code>x*cos(radians(Angle)) + y*sin(radians(Angle))</code></p>
<p>&nbsp;&nbsp;replace <code>y</code> with <code>-x*sin(radians(Angle)) + y*cos(radians(Angle)) </code></p>

<p><strong>Flip:</strong></p>
<p>To flip X - Y:</p>
<p>&nbsp;&nbsp;replace <code>x</code> with <code>y</code> <em>AND</em> replace <code>y</code> with <code>-x</code></p>

<p>To flip Y - Z:</p>
<p>&nbsp;&nbsp;replace <code>y</code> with <code>z</code> <em>AND</em> replace <code>z</code> with <code>-y</code></p>

<p>To flip X - Z:</p>
<p>&nbsp;&nbsp;replace <code>x</code> with <code>-z</code> <em>AND</em> replace <code>z</code> with <code>x</code></p>

<p><strong>Twist:</strong></p>
<p>To twist N turns/unit around the <code>x</code> axis:</p>
<p>&nbsp;&nbsp;replace <code>y</code> with <code>z*sin(x*2*pi*N) + y*cos(x*2*pi*N)</code></p>
<p>&nbsp;&nbsp;replace <code>z</code> with <code>z*cos(x*2*pi*N) - y*sin(x*2*pi*N)</code></p>

</div>
<a name="t2_3_3_3_10"></a>
<div class="content-level-h5" contains="Improving Isosurface Speed" id="t2_3_3_3_10">
<h5>2.3.3.3.10 Improving Isosurface Speed</h5>
<p>To optimize the approximation of the isosurface and to get maximum rendering speed it is important to adapt certain values:</p>

<p><strong><code>accuracy</code>:</strong></p>

<p>The accuracy value influences how accurate the surface geometry is calculated. Lower values lead to a more precise, but slower result. The default value of <code>0.001</code> is fairly low. We used this value in all the previous samples, but often you can raise this quite a lot and thereby make things faster.</p>

<p><strong><code>max_gradient</code>:</strong></p>

<p>For finding the actual surface it is important for POV-Ray to know the maximum gradient of the function, meaning how fast the function value changes. We can specify a value with the <code>max_gradient</code> keyword.  Lower max_gradient values lead to faster rendering, but if the specified value is below the actual maximum gradient of the function, there can be holes or other artefact's in the surface.</p>

<p>For the same reason functions with an infinite gradient should not be used. This applies for pigment functions with brick or checker patterns for example. You should also be careful when using <code>select()</code> in isosurface functions because of this.</p>

<p>If the real maximum gradient differs too much from the specified value POV-Ray issues a warning together with the found maximum gradient. It is usually sufficient to use this number for the <code>max_gradient</code> parameter to get fast and correct results.</p>

<p>POV-Ray can also dynamically change the <code>max_gradient</code> when you specify <code>evaluate</code> with 3 parameters in the isosurface definition. Concerning the details on this and other things see the <a href="r3_4.html#r3_4_5_1_6">evaluate</a> keyword in the reference section.</p>

<p><strong><code>contained_by</code>:</strong></p>

<p>Make sure your <code>contained_by</code> object fits as tightly as possible. An oversized container can sky-rocket the render time. When the container has a lot of empty space around the actual isosurface, POV-Ray has to do a lot of superfluous sampling: especially with complex functions this can become very time consuming. On top of this, the <code>max_gradient</code> needed to get a proper surface will also increase rapidly, almost proportional to the oversize! You could use a transparent copy of the container (using exactly the same transformations) to check how it fits. Getting the <code>min_extent</code> and <code>max_extent</code> of the isosurface is not useful because it only gives the extent of the container and not of the actual isosurface.</p>

</div>
<a name="t2_3_3_4"></a>
<div class="content-level-h4" contains="Poly Object" id="t2_3_3_4">
<h4>2.3.3.4 Poly Object</h4>
<p>The polynomial object (and its <em>shortcut</em> versions: <code><a href="r3_4.html#r3_4_5_3_3">cubic</a></code>, <code><a href="r3_4.html#r3_4_5_3_4">quartic</a></code> and <code><a href="r3_4.html#r3_4_5_3_6">quadric</a></code>)
of POV-Ray is one of the most complex and mathematical primitives of the program. One could think that it is seldom
used and more or less obsolete, but we have to remember that for example the torus primitive is just a shortcut for the equivalent <code>quartic</code>, which is just a shortcut for the equivalent <code>poly</code> object. Polys are, however, seldom used in scenes due to the fact that they are so difficult to define and it is far from trivial to get the desired shape with just a polynomial equation. It is mostly used by the most mathematically oriented POV-Ray users.</p>

<p>This tutorial explains the process of making a polynomial object
in POV-Ray.</p>

<p class="Note"><strong>Note:</strong> Since version 3.5, POV-Ray includes the new <code>isosurface</code> object
which makes the polynomial object more or less obsolete. The isosurface is more versatile (you can specify any mathematical function, not
just polynomials) and easier to use. You can write the function as is, without needing to put values in a gigantic vector. Isosurfaces also often (although not always) render considerably faster than equivalent polys.</p>

<p>However, the most mathematically oriented still like polys because
isosurfaces are calculated just by approximating the right value, while
the poly is calculated in a mathematically exact way. Usually isosurfaces
are more than good enough for most applications, though.</p>

<p class="Note"><strong>Note:</strong> A maximum of 35th degree polynomial can be represented with the poly object. If a higher degree polynomial or other non-polynomial function has to be represented, then it is necessary to use the isosurface object.</p>

</div>
<a name="t2_3_3_4_1"></a>
<div class="content-level-h5" contains="Creating the polynomial function" id="t2_3_3_4_1">
<h5>2.3.3.4.1 Creating the polynomial function</h5>
<p>The first step is to create the polynomial function to be represented.
You will need some (high-school level) mathematical knowledge for this.</p>

<p><strong>1)</strong> Let's start with an easy example, a sphere:</p>

<p>The sphere function is:</p>

<table class="centered" width="190px" cellpadding="0" cellspacing="10">
<tr>
  <td>
    <img class="centered" width="170px" src="images/f/f0/TutImgPolyfunc1.png">
  </td>
</tr>
<tr>
  <td>
    <p class="caption">sphere function</p>
  </td>
</tr>
</table>

<p>Now we have to convert this to polynomial form, we will need a polynomial of the 2nd degree to represent this:</p>

<table class="centered" width="205px" cellpadding="0" cellspacing="10">
<tr>
  <td>
    <img class="centered" width="185px" src="images/5/5d/TutImgPolyfunc2.png">
  </td>
</tr>
<tr>
  <td>
    <p class="caption">sphere polynomial</p>
  </td>
</tr>
</table>

<p><strong>2)</strong> A more elaborated example:</p>

<p>Let's take the function:</p>

<table class="centered" width="130px" cellpadding="0" cellspacing="10">
<tr>
  <td>
    <img class="centered" width="110px" src="images/c/c2/TutImgPolyfunc3.png">
  </td>
</tr>
<tr>
  <td>
    <p class="caption">function</p>
  </td>
</tr>
</table>

<p>Converting this to polynomial form we get:</p>

<table class="centered" width="215px" cellpadding="0" cellspacing="10">
<tr>
  <td>
    <img class="centered" width="195px" src="images/3/30/TutImgPolyfunc4.png">
  </td>
</tr>
<tr>
  <td>
    <p class="caption">polynomial</p>
  </td>
</tr>
</table>

<p>Although the highest power is 4 we will need a 5th order polynomial to
represent this function (because we cannot represent y<sup>4</sup>z with a
4th order polynomial).</p>

<p><strong>3)</strong> And since we talked about the torus, let's also take it as an example.</p>
<p>A torus can be represented with the function:</p>

<table class="centered" width="295px" cellpadding="0" cellspacing="10">
<tr>
  <td>
    <img class="centered" width="275px" src="images/5/57/TutImgPolyfunc5.png">
  </td>
</tr>
<tr>
  <td>
    <p class="caption">torus function</p>
  </td>
</tr>
</table>

<p>where r<sub>1</sub> is the major radius and r<sub>2</sub> is the minor radius.</p>

<p>Now, this is tougher to convert to polynomial form, but finally we get:</p>

<table class="centered" width="700px" cellpadding="0" cellspacing="10">
<tr>
  <td>
    <img class="centered" width="680px" src="images/d/d5/TutImgPolyfunc6.png">
  </td>
</tr>
<tr>
  <td>
    <p class="caption">torus polynomial</p>
  </td>
</tr>
</table>

<p>A 4th order polynomial is enough to represent this.</p>

<p class="Note"><strong>Note:</strong> Not every function can be represented in polynomial form. Only functions that use addition (and substraction), multiplication (and division) and scalar powers (including rational powers, eg. the square root) can be represented. Also, the poly primitive supports only polynomials of the 35th degree at max.</p>

<p>Converting a function to polynomial form may be a very laborious task for
certain functions. Some mathematical programs are very helpful in this matter.</p>

</div>
<a name="t2_3_3_4_2"></a>
<div class="content-level-h5" contains="Writing the polynomial vector" id="t2_3_3_4_2">
<h5>2.3.3.4.2 Writing the polynomial vector</h5>
<p>Now that we have the function in polynomial form, we have to write it
in POV-Ray syntax. The syntax is specified in the sections on <a href="r3_4.html#r3_4_5_3_5">polynomial</a> and <a href="r3_4.html#r3_4_5_3_6">quadric</a> of the reference section. There is also a table in this chapter which we will be using to make the polynomial vector. It is easier to have this table printed on paper.</p>

<p class="Note"><strong>Note:</strong> It is also possible to make a little program with your favorite
programming language which will print the poly vector from the polynomial
function, but making a program like this is up to you.</p>

<p><strong>1)</strong> Let's start with the easy one, ie. the sphere.</p>

<p>Since the sphere can be represented with a polynomial of 2nd degree, we
look at the column titled <em>2nd</em> in the <a href="r3_4.html#r3_4_5_3_5">table</a>. We see that it has 10 items,
ie. we need a vector of size 10. Each item of the vector will be the factor of the term listed in the table.</p>

<p>The polynomial was:</p>

<table class="centered" width="205px" cellpadding="0" cellspacing="10">
<tr>
  <td>
    <img class="centered" width="185px" src="images/5/5d/TutImgPolyfunc2.png">
  </td>
</tr>
<tr>
  <td>
    <p class="caption">sphere polynomial function</p>
  </td>
</tr>
</table>

<p>Writing the poly in this way we get:</p>

<pre>
#declare Radius=1;
poly
{ 2,
  &lt;1,0,0,0,1,
   0,0,1,0,-Radius*Radius&gt;
}
</pre>

<p>Put each group of factors (separated with lines in the table) in their
own lines.</p>

<p>In the table we see that the first item is the factor for x<sup>2</sup>,
which is 1 in the function. The next item is xy. Since it is not in the
function, its factor is 0. Likewise the next item, which is xz. And so on.
The last item is the scalar term, which is in this case -r<sup>2</sup>.</p>

<p>If we make a proper scene and render it, we get:</p>

<pre>
camera { location y*4-z*5 look_at 0 angle 35 }
light_source { &lt;100,200,-50&gt; 1 }
background { rgb &lt;0,.25,.5&gt; }

#declare Radius=1;
poly
{ 2,
  &lt;1,0,0,0,1,
   0,0,1,0,-Radius*Radius&gt;
  pigment { rgb &lt;1,.7,.3&gt; } finish { specular .5 }
}
</pre>

<table class="centered" width="340px" cellpadding="0" cellspacing="10">
<tr>
  <td>
    <img class="centered" width="320px" src="images/1/1b/TutImgPolypic1.png">
  </td>
</tr>
<tr>
  <td>
    <p class="caption">sphere polynomial image</p>
  </td>
</tr>
</table>

<p></p>
<p class="Note"><strong>Note:</strong> There is a shortcut for 2nd degree polynomials: The <code><a href="r3_4.html#r3_4_5_3_6">quadric</a></code> primitive. Using a shortcut version, whenever possible, can lead to faster
renderings. We can write the sphere code described above in the following way:</p>

<pre>
quadric
{ &lt;1,1,1&gt;, &lt;0,0,0&gt;, &lt;0,0,0&gt;, -Radius*Radius
  pigment { rgb &lt;1,.7,.3&gt; } finish { specular .5 }
}
</pre>

<p><strong>2)</strong> Now lets try the second one. We do it similarly, but this time we need
to look at the column titled <em>5th</em> in the table.</p>

<p>The polynomial was:</p>

<table class="centered" width="215px" cellpadding="0" cellspacing="10">
<tr>
  <td>
    <img class="centered" width="195px" src="images/3/30/TutImgPolyfunc4.png">
  </td>
</tr>
<tr>
  <td>
    <p class="caption">5th order polynomial function</p>
  </td>
</tr>
</table>

<p>Writing the poly primitive we get:</p>
<pre>
poly
{ 5,
  &lt;0,0,0,0,0,
   0,0,0,0,0,
   0,0,0,0,0,
   0,0,0,1,0,
   0,0,0,0,0,
   -2,0,0,0,0,
   0,0,0,0,0,
   0,1,0,0,0,
   0,0,0,0,0,
   0,0,0,0,0,
   0,0,0,0,0,0&gt;
}
</pre>

<p>With the proper scene we get:</p>
<pre>
camera { location &lt;8,20,-10&gt;*.7 look_at x*.01 angle 35 }
light_source { &lt;100,200,20&gt; 1 }
background { rgb &lt;0,.25,.5&gt; }

poly
{ 5,
  &lt;0,0,0,0,0,
   0,0,0,0,0,
   0,0,0,0,0,
   0,0,0,1,0,
   0,0,0,0,0,
   -2,0,0,0,0,
   0,0,0,0,0,
   0,1,0,0,0,
   0,0,0,0,0,
   0,0,0,0,0,
   0,0,0,0,0,0&gt;
  clipped_by { box { &lt;-4,-4,-1&gt;&lt;4,4,1&gt; } }
  bounded_by { clipped_by }
  pigment { rgb &lt;1,.7,.3&gt; } finish { specular .5 }
  rotate &lt;0,90,-90&gt;
}
</pre>

<table class="centered" width="340px" cellpadding="0" cellspacing="10">
<tr>
  <td>
    <img class="centered" width="320px" src="images/9/9c/TutImgPolypic2.png">
  </td>
</tr>
<tr>
  <td>
    <p class="caption">5th order polynomial image</p>
  </td>
</tr>
</table>

<p><strong>3)</strong> And finally the torus:</p>

<p>The polynomial was:</p>

<table class="centered" width="700px" cellpadding="0" cellspacing="10">
<tr>
  <td>
    <img class="centered" width="680px" src="images/d/d5/TutImgPolyfunc6.png">
  </td>
</tr>
<tr>
  <td>
    <p class="caption">torus polynomial function</p>
  </td>
</tr>
</table>

<p>And we get the proper 4th degree poly primitive:</p>
<pre>
camera { location y*4-z*5 look_at 0 angle 35 }
light_source { &lt;100,200,-50&gt; 1 }
background { rgb &lt;0,.25,.5&gt; }

#declare r1=1;
#declare r2=.5;
poly
{ 4,
  &lt;1,0,0,0,2,
   0,0,2,0,-2*(r1*r1+r2*r2),
   0,0,0,0,0,
   0,0,0,0,0,
   1,0,0,2,0,
   2*(r1*r1-r2*r2),0,0,0,0,
   1,0,-2*(r1*r1+r2*r2),0,pow(r1,4)+pow(r2,4)-2*r1*r1*r2*r2&gt;
  pigment { rgb &lt;1,.7,.3&gt; } finish { specular .5 }
}
</pre>

<p>When rendered we get:</p>

<table class="centered" width="340px" cellpadding="0" cellspacing="10">
<tr>
  <td>
    <img class="centered" width="320px" src="images/0/04/TutImgPolypic3.png">
  </td>
</tr>
<tr>
  <td>
    <p class="caption">torus polynomial image</p>
  </td>
</tr>
</table>


<p>There is a shortcut for 4th order polynomials: The <code><a href="r3_4.html#r3_4_5_3_4">quartic</a></code> primitive. We can write the torus like this:</p>

<pre>
quartic
{ &lt;1,0,0,0,2,
   0,0,2,0,-2*(r1*r1+r2*r2),
   0,0,0,0,0,
   0,0,0,0,0,
   1,0,0,2,0,
   2*(r1*r1-r2*r2),0,0,0,0,
   1,0,-2*(r1*r1+r2*r2),0,pow(r1,4)+pow(r2,4)-2*r1*r1*r2*r2&gt;
  pigment { rgb &lt;1,.7,.3&gt; } finish { specular .5 }
}
</pre>

</div>
<a name="t2_3_3_4_3"></a>
<div class="content-level-h5" contains="Polynomial made easy" id="t2_3_3_4_3">
<h5>2.3.3.4.3 Polynomial made easy</h5>
<p>Since consulting the table in the section <a href="r3_4.html#r3_4_5_3_5">Polynomial</a> or writing a program to get the right poly vector can be a bit cumbersome, especially when the poly vector is not a write-once-only expression and that you want to get it back, so let's examine how those equations would be rewritten using the <em>simplified</em> syntax.</p>
<p>You should refer to the images in the previous section, as these examples produce <em>exactly</em> the same results.</p>

<p><strong>1)</strong> The sphere example can be rewritten as:</p>
<pre>
#declare Radius=1;
polynomial { 2, 
  xyz(2,0,0):1, 
  xyz(0,2,0):1,
  xyz(0,0,2):1,
  xyz(0,0,0):-Radius*Radius 
}
</pre>

<p><strong>2)</strong> Let's now see the second one:</p>
<pre>
polynomial { 5,
  xyz(2,0,1):1,
  xyz(0,4,1):1,
  xyz(1,2,0):-2
}
</pre>

<p><strong>3)</strong> And finally the torus example:</p>
<pre>
polynomial { 4,
  xyz(4,0,0):1,
  xyz(2,2,0):2,
  xyz(2,0,2):2,
  xyz(2,0,0):-2*(r1*r1+r2*r2),
  xyz(0,4,0):1,
  xyz(0,2,2):2,
  xyz(0,2,0):2*(r1*r1-r2*r2),
  xyz(0,0,4):1,
  xyz(0,0,2):-2*(r1*r1+r2*r2),
  xyz(0,0,0):pow((r1*r1-r2*r2),2)
}
</pre>

</div>


<a name="t2_3_3_5"></a>
<div class="content-level-h4" contains="Superquadric Ellipsoid Object" id="t2_3_3_5">
<h4>2.3.3.5 Superquadric Ellipsoid Object</h4>
<p>Sometimes we want to make an object that does not have perfectly sharp
edges like a box does. Then, the superquadric ellipsoid shape made by the
<code>superellipsoid</code> is a useful object. It is described by the simple
syntax:</p>
<pre>
  superellipsoid { &lt;Value_E, Value_N &gt;}
</pre>

<p>Where <em>Value_E</em> and <em>Value_N</em> are float values greater than
zero and less than or equal to one. Let's make a superellipsoid and
experiment with the values of <em>Value_E</em> and <em>Value_N</em> to see
what kind of shapes we can make. We create a file called <code>
supellps.pov</code> and edit it as follows:</p>
<pre>
  #include &quot;colors.inc&quot;
  camera {
    location &lt;10, 5, -20&gt;
    look_at 0
    angle 15
  }
  background { color rgb &lt;.5, .5, .5&gt; }
  light_source { &lt;10, 50, -100&gt; White }
</pre>

<p>The addition of a gray background makes it a little easier to see our
object. We now type:</p>
<pre>
  superellipsoid { &lt;.25, .25&gt;
    pigment { Red }
  }
</pre>

<p>We save the file and render it to see the shape. It will look like a box, but the edges will be rounded off. Now let's
experiment with different values of <em>Value_E</em> and <em> Value_N</em>.
For the next trace, try &lt;1, 0.2&gt;. The shape now looks like a cylinder,
but the top edges are rounded. Now try &lt;0.1, 1&gt;. This shape is an odd
one! We do not know exactly what to call it, but it is interesting.
Finally, let's try &lt;1, 1&gt;. Well, this is more familiar... a sphere!</p>
<p>
There are a couple of facts about superellipsoids we should know. First, we
should not use a value of 0 for either <em> Value_E</em> nor <em>
Value_N</em>. This will cause POV-Ray to incorrectly make a black box instead
of our desired shape. Second, very small values of <em>Value_E</em> and <em>
Value_N</em> may yield strange results so they should be avoided. Finally,
the Sturmian root solver will not work with superellipsoids.</p>
<p>
Superellipsoids are finite objects so they respond to auto-bounding and can
be used in CSG.</p>
<p>
Now let's use the superellipsoid to make something that would be useful
in a scene. We will make a tiled floor and place a couple of superellipsoid
objects hovering over it. We can start with the file we have already
made.</p>
<p>
We rename it to <code> tiles.pov</code> and edit it so that it reads as
follows:</p>
<pre>
  #include &quot;colors.inc&quot;
  #include &quot;textures.inc&quot;
  camera {
    location &lt;10, 5, -20&gt;
    look_at 0
    angle 15
  }
  background { color rgb &lt;.5, .5, .5&gt; }
  light_source{ &lt;10, 50, -100&gt; White }
</pre>

<p class="Note"><strong>Note:</strong> We have added <code>#include &quot;textures.inc&quot;</code> so
we can use pre-defined textures. Now we want to define the superellipsoid
which will be our tile.</p>
<pre>
  #declare Tile = superellipsoid { &lt;0.5, 0.1&gt;
    scale &lt;1, .05, 1&gt;
  }
</pre>

<p>Superellipsoids are roughly 2*2*2 units unless we scale them otherwise. If
we wish to lay a bunch of our tiles side by side, they will have to be offset
from each other so they do not overlap. We should select an offset value
that is slightly more than 2 so that we have some space between the tiles to
fill with grout. So we now add this:</p>
<pre>
  #declare Offset = 2.1;
</pre>

<p>We now want to lay down a row of tiles. Each tile will be offset from the
original by an ever-increasing amount in both the +z and -z directions. We
refer to our offset and multiply by the tile's rank to determine the
position of each tile in the row. We also union these tiles into a single
object called <code>Row</code> like this:</p>
<pre>
  #declare Row = union {
    object { Tile }
    object { Tile translate z*Offset }
    object { Tile translate z*Offset*2 }
    object { Tile translate z*Offset*3 }
    object { Tile translate z*Offset*4 }
    object { Tile translate z*Offset*5 }
    object { Tile translate z*Offset*6 }
    object { Tile translate z*Offset*7 }
    object { Tile translate z*Offset*8 }
    object { Tile translate z*Offset*9 }
    object { Tile translate z*Offset*10 }
    object { Tile translate -z*Offset }
    object { Tile translate -z*Offset*2 }
    object { Tile translate -z*Offset*3 }
    object { Tile translate -z*Offset*4 }
    object { Tile translate -z*Offset*5 }
    object { Tile translate -z*Offset*6 }
  }
</pre>

<p>This gives us a single row of 17 tiles, more than enough to fill the
screen. Now we must make copies of the <code>Row</code> and translate them,
again by the offset value, in both the +x and -x directions in ever
increasing amounts in the same manner.</p>
<pre>
  object { Row }
  object { Row translate x*Offset }
  object { Row translate x*Offset*2 }
  object { Row translate x*Offset*3 }
  object { Row translate x*Offset*4 }
  object { Row translate x*Offset*5 }
  object { Row translate x*Offset*6 }
  object { Row translate x*Offset*7 }
  object { Row translate -x*Offset }
  object { Row translate -x*Offset*2 }
  object { Row translate -x*Offset*3 }
  object { Row translate -x*Offset*4 }
  object { Row translate -x*Offset*5 }
  object { Row translate -x*Offset*6 }
  object { Row translate -x*Offset*7 }
</pre>

<p>Finally, our tiles are complete. But we need a texture for them. To do
this we union all of the <code>Rows</code> together and apply a <code>White
Marble</code> pigment and a somewhat shiny reflective surface to it:</p>
<pre>
  union{
    object { Row }
    object { Row translate x*Offset }
    object { Row translate x*Offset*2 }
    object { Row translate x*Offset*3 }
    object { Row translate x*Offset*4 }
    object { Row translate x*Offset*5 }
    object { Row translate x*Offset*6 }
    object { Row translate x*Offset*7 }
    object { Row translate -x*Offset }
    object { Row translate -x*Offset*2 }
    object { Row translate -x*Offset*3 }
    object { Row translate -x*Offset*4 }
    object { Row translate -x*Offset*5 }
    object { Row translate -x*Offset*6 }
    object { Row translate -x*Offset*7 }
    pigment { White_Marble }
    finish { phong 1 phong_size 50 reflection .35 }
  }
</pre>

<p>We now need to add the grout. This can simply be a white plane. We have
stepped up the ambient here a little so it looks whiter.</p>
<pre>
  plane {
    y, 0  //this is the grout
    pigment { color White }
    finish { ambient .4 diffuse .7 }
  }
</pre>

<p>To complete our scene, let's add five different superellipsoids, each
a different color, so that they hover over our tiles and are reflected in
them.</p>
<pre>
  superellipsoid {
    &lt;0.1, 1&gt;
    pigment { Red }
    translate &lt;5, 3, 0&gt;
    scale .45
  }
  superellipsoid {
    &lt;1, 0.25&gt;
    pigment { Blue }
    translate &lt;-5, 3, 0&gt;
    scale .45
  }
  superellipsoid {
    &lt;0.2, 0.6&gt;
    pigment { Green }
    translate &lt;0, 3, 5&gt;
    scale .45
  }
  superellipsoid {
    &lt;0.25, 0.25&gt;
    pigment { Yellow }
    translate &lt;0, 3, -5&gt;
    scale .45
  }
  superellipsoid {
    &lt;1, 1&gt;
    pigment { Pink }
    translate y*3
    scale .45
  }
</pre>

<table class="centered" width="340px" cellpadding="0" cellspacing="10">
<tr>
  <td>
    <img class="centered" width="320px" src="images/4/4f/TutImgSuperell.png">
  </td>
</tr>
<tr>
  <td>
    <p class="caption">Some superellipsoids hovering above a tiled floor.</p>
  </td>
</tr>
</table>

<p>We trace the scene at 320x200 <code>-A</code> to see the result. If we are
happy with that, we do a final trace at 640x480 <code>+A0.2</code>.</p>

</div>
<a name="t2_3_4"></a>
<div class="content-level-h3" contains="Gamma Handling" id="t2_3_4">
<h3>2.3.4 Gamma Handling</h3>
<p>In this section, we will explain how to use the <em>experimental</em> gamma handling framework introduced with POV-Ray version 3.7. However, first we may need to introduce the term <em>gamma</em>, and why it needs handling anyway:</p>

<p class="Note"><strong>Note:</strong> In a nutshell, <em>gamma handling</em> is the compensation for <em>non-linearities</em> in the <em>representation</em> of color values.</p>

<table class="centered" width="700px" cellpadding="0" cellspacing="10">
<tr>
  <td width="320px">
    <p class="tabletext">As a raytracing engine, POV-Ray internally needs to represent colors using <em>linear</em> brightness values to produce physically accurate results. However, the majority of contemporary digital image processing tools and file formats do <em>not</em>. This comes as a surprise to most people, probably because the human visual perception is non-linear as well, as can be demonstrated in the render to the right, generated with POV-Ray using physically realistic settings:</p>
  </td>
    <td width="320px">
    <img class="rightpanel" width="320px" src="images/3/3c/TutImgGammaShowcase_ref0.png">
  </td>
</tr>
<tr>
  <td></td>
  <td>
    <p class="caption">gamma handling reference image</p>
  </td>
</tr>
</table>

<p>Both front and second row show spheres with pigments increasing from <code>rgb 0.0</code> to <code>rgb 1.0</code>. When asked which of them increases linearly, with a <em>medium grey</em> at the center, most people will go for the front row without too much hesitation. And in fact the pigment of the front center sphere <em>does</em> correspond to what Photoshop or similar image processing software would normally call <em>50% grey</em>, but the pigment is a mere 21.8% as bright as the rightmost one. The true 50% brightness sphere sits right behind it.</p>

<p>A corresponding nonlinearity can be found in the traditional internal representation of colors in digital image processing, as implemented in file formats, graphics cards frame buffers, display APIs and so forth. Using one byte per colour component, and black and white represented by (0;0;0) and (255;255;255) respectively, a value of (128;128;128) will typically be used to encode a light intensity of just about 20%. To make matters a bit more complicated, the actual light intensity seen on the computer display may vary from one computer to the next, not only due to a historical lack of standardization in the PC display and graphics hardware market, but also due to factors such as electrical tolerances and even aging of the display. In professional environments, displays are therefore <em>calibrated</em> at regular intervals.</p>

<p>The non-linear relationship between <em>color values</em> and actual light intensity is usually approximated by (or calibrated to match) a power-law function (aka <em>gamma function</em>, hence the technical term <em>gamma</em>), i.e.:</p>

<!--- :<math>f(x)\!\,=x^{\gamma}</math> --->
<!--- cannot currently support in-line Latex when generating distribution doc sets --->
<!--- use this for now --->
<p><span class="formula">f(x) = x &#770; &#947;</span></p>

<p>where <span class="formula">x</span> is the internal representation normalized to the range [0...1], <span class="formula">f(x)</span> is the actual output light intensity, and <span class="formula">&#947;</span> is a value typically somewhere between 2.0 to 2.4, though in the professional image processing world a value of 1.8 is also common.</p>

<p>Another formula becoming more and more popular is the so-called <em>sRGB transfer function</em> as defined in the sRGB color space standard, which has been adopted as the official standard on the World Wide Web. This function roughly corresponds to a power-law gamma of 2.2.</p>

</div>
<a name="t2_3_4_1"></a>
<div class="content-level-h4" contains="Setting Up Your Display" id="t2_3_4_1">
<h4>2.3.4.1 Setting Up Your Display</h4>

<p>Using POV-Ray's gamma handling framework will not make much sense unless your display is set up properly; ideally, this would be done with a <em>colorimeter</em> and professional <em>display calibration</em> software. However, for hobbyists' purposes, less expensive solutions will suffice:</p>

<ul>
  <li>Your graphics card drivers may come with a wizard to help you adjust your display.</li>
  <li>Various versions of Photoshop shipped with a utility called &quot;Adobe Gamma&quot;.</li>
  <li>There are numerous sites on the internet dedicated to <a href="http://www.photoscientia.co.uk/Gamma.htm">getting your display settings straight</a>.</li>
</ul>
<p class="Note"><strong>Note:</strong> We disagree with the author of the site linked to above, about which display gamma to aim for, and <em>strongly recommend</em> a gamma of 2.2, unless you know exactly what you're doing.</p>

<p>As an additional sanity check of your system display settings (and also of your image viewing software) POV-Ray provides a sample scene custom-tailored to this purpose, to be found at <code>scenes/gamma/gamma_showcase.pov</code>. Render the scene twice as PNG, using the following options:</p>

<pre>
  +w640 +h480 +a0.3 +am1 +fN -d File_Gamma=sRGB Output_File_Name=gamma_showcase.png
  +w640 +h480 +a0.3 +am1 +fN -d File_Gamma=1.0  Output_File_Name=gamma_showcase_linear.png
</pre>

<p>At 100% zoom, both images should look identical in your viewing software (if they don't, then by all means get rid of that obsolete software). Moreover, all the spheres should look uniform, like in the introductory image above. It is ok if you notice stripes on the spheres, but the overall brightness and hue should not be perceived as varying between the left and right hemispheres of any single sphere.</p>

<p>If however the image appears like shown below, then your system display gamma is either higher (left) or lower (right) than what your image viewing software expects. Note that in the PC world, most contemporary software will expect the display to either have a gamma of 2.2 or comply with the sRGB transfer function, unless there's a way to tell the software otherwise.</p>

<p class="Note"><strong>Note:</strong> LCD owners should make sure their display resolution is set to match the maximum resolution of the LCD, as interpolation might mess up the intended effect. Furthermore, it is not uncommon for LCDs to exhibit variations of gamma depending on viewing angle and, as a result, also across the display area. In that case, we recommend to adjust your display so that you get the desired gamma at the center of the screen when sitting as you usually do.</p>

<table class="centered" width="660px" cellpadding="0" cellspacing="10">
<tr>
  <td>
    <img class="left" width="320px" src="images/d/d7/TutImgGammaShowcase_ref1.png">
  </td>
  <td>
    <img class="right" width="320px" src="images/3/39/TutImgGammaShowcase_ref2.png">
  </td>
</tr>
<tr>
  <td>
    <p class="caption">higher example</p>
  </td>
  <td>
    <p class="caption">lower example</p>
  </td>
</tr>
</table>

<p>Just for the sake of it, here's a render of that showcase scene (note however that due to conversion of the original documentation source to whatever format you are currently reading it in, whether it be PDF, HTML or whatever, the image may have undergone some conversion, and may therefore be unsuited to serve as a good reference):</p>

<table class="centered" width="660px" cellpadding="0" cellspacing="10">
<tr>
  <td>
    <img class="center" width="640px" src="images/3/3a/TutImgGammaShowcase.png">
  </td>
</tr>
<tr>
  <td>
    <p class="caption">refer to: scenes/gamma/gamma_showcase.pov</p>
  </td>
</tr>
</table>

</div>
<a name="t2_3_4_2"></a>
<div class="content-level-h4" contains="Setting Up POV-Ray" id="t2_3_4_2">
<h4>2.3.4.2 Setting Up POV-Ray</h4>

<p>Now that you can be sure that your operating system in general and your image viewing software in particular behave well regarding gamma, it is time to set up POV-Ray to do the same.</p>

<p>If you know that your system matches the sRGB standard, or have chosen to go for an approximate display gamma of 2.2, or used a tool that doesn't explicitly mention the gamma it has helped you to set up (in which case it will typically be 2.2 or sRGB as well), you're probably done already, as POV-Ray expects sRGB compliance by default, which is close enough to a display gamma of 2.2 for starters. Otherwise (or if you want an exact display gamma of 2.2) you should edit your master <code>povray.ini</code> to add the following line (e.g. for a display gamma of 1.8):</p>

<pre>
  Display_Gamma=1.8
</pre>

<p>Instead of a numerical value, you can also specify <code>Display_Gamma=sRGB</code> to explicitly tell POV-Ray that your system is calibrated to match the sRGB standard (which, as already mentioned, is actually the default setting).</p>

<p>Again, the gamma showcase scene can be used as a sanity check; use the following parameters:</p>

<pre>
  +w640 +h480 +a0.3 +am1 -f +d
</pre>

<p>Make sure you set the preview to windowed mode to get a 100% zoom. If everything works as expected, the preview window should look just like the PNG files already created, with each sphere again appearing to have a uniform color and brightness. If this is not the case for some mysterious reason, you may need to tweak the <code>Display_Gamma</code> setting accordingly; increase it if the left hemispheres appear too dark, or decrease it if they appear too bright. When you're done testing, update your <code>povray.ini</code> again.</p>

</div>
<a name="t2_3_4_3"></a>
<div class="content-level-h4" contains="Gamma in Output Images" id="t2_3_4_3">
<h4>2.3.4.3 Gamma in Output Images</h4>

<p>Besides being used internally in most contemporary digital image processing software, non-linear color representations are also used in most conventional image file formats. This is often called <em>gamma pre-correction</em>, in the sense that the original linear brightness information has already been transformed by a gamma function to compensate for display non-linearity. Unfortunately, due to the large variety of display gamma in the world of computing, the gamma value used for pre-correction traditionally followed no set standard either.</p>

<p>In recent years the situation has changed, partly due to the adoption of the sRGB standard as the official recommendation for the World Wide Web, with major file format specifications following suit, and partly due to the advent of new file formats like PNG designed right from the start for a standardized way of gamma handling. (For such file formats, it is customary to speak of non-linear color representation not as <em>gamma pre-correction</em>, but rather as <em>gamma encoding</em>.) By now, for virtually all contemporary file formats there exists either a clear specification of how to handle gamma, or an official recommendation to adhere to the sRGB standard.</p>

<p>POV-Ray's gamma handling defaults are set to comply with the official file format standards or recommendations, so normally you will not need to worry about gamma handling. However, should the need arise, you can tell POV-Ray to ignore gamma recommendations and pre-correct the output file for a different display gamma, using the <code>File_Gamma</code> INI file option, e.g.:</p>

<pre>
  File_Gamma=1.8
</pre>

<p>Again, <code>sRGB</code> is a valid value, specifying that POV-Ray should apply the sRGB transfer function.</p>

<p class="Note"><strong>Note:</strong> Some of the file formats supported by POV-Ray are explicitly specified to never use gamma pre-correction or gamma encoding. For such file types (currently OpenEXR and Radiance HDR), <code>File_Gamma</code> has no effect whatsoever. For certain other file types (currently PNG), <code>File_Gamma</code> does have an effect on the encoding of the image, but not on the general visual appearance.</p>

<p>For output files, POV-Ray handles gamma according to the following rules:</p>

<ul>
  <li>For OpenEXR and Radiance HDR, which are officially specified to store linear brightness values, POV-Ray <em>always</em> stores linear values, ignoring the <code>File_Gamma</code> setting.</li>
  <li>For PNG, which explicitly allows different encoding gamma values, POV-Ray will interpret the <code>File_Gamma</code> setting as the decoding gamma to encode for, and <em>always</em> write corresponding meta information into the header; as a result, the image will always look virtually identical irregardless of the <code>File_Gamma</code> setting; however, to minimize visible encoding artifacts like color banding, it is strongly recommended to use a setting of around 2.2, or <code>sRGB</code>.</li>
  <li>For all other file formats, POV-Ray will interpret the <code>File_Gamma</code> setting as the display gamma to pre-correct for; as a result, the image will look different depending on the value used. It will also look different than the preview if you use a value other than your system's display gamma.</li>
</ul>

</div>
<a name="t2_3_4_4"></a>
<div class="content-level-h4" contains="Setting Up Your Scene" id="t2_3_4_4">
<h4>2.3.4.4 Setting Up Your Scene</h4>

<p>As stated above, POV-Ray needs to work with linear colors to produce the most physically accurate output. However, if you prefer you <em>can</em> coax POV-Ray to work directly with non-linear color values. This is controlled via the <code>assumed_gamma</code> statement in the scene file's global settings, e.g.:</p>

<pre>
  global_settings { assumed_gamma 1.8 }
</pre>

<p>This enables the <em>experimental</em> gamma handling feature, and instructs POV-Ray to work with colors pre-corrected for a display gamma of whatever value you specify (in this example obviously a gamma of 1.8). You can also specify <code>srgb</code> instead of a numerical value, instructing POV-Ray to work with colors pre-corrected according to the sRGB standard.</p>

<p class="Note"><strong>Note:</strong> It is highly recommended to either set <code>assumed_gamma</code> to your system's display gamma for convenience, or set it to <code>1.0</code> for maximum realism. Using it for purely artistic purposes is strongly discouraged.</p>

POV-Ray will take this setting into account when pre-correcting the computed image according to the Display_Gamma and File_Gamma settings.

<p class="Note"><strong>Note:</strong> Sometimes you may want to use POV-Ray to generate other data than images in the strict sense, using the output image file as a mere data container, e.g. for height field data, bump maps, transparency maps or the like. In such cases, it is highly recommended to set both <code>assumed_gamma</code> and <code>File_Gamma</code> to 1.0 to avoid unexpected results.</p>

</div>
<a name="t2_3_4_5"></a>
<div class="content-level-h4" contains="Gamma in Literal Colors" id="t2_3_4_5">
<h4>2.3.4.5 Gamma in Literal Colors</h4>

<p>By default, POV-Ray will expect each and every color value you enter to match your <code>assumed_gamma</code>, normalized to a range from 0.0 to 1.0. When using <code>assumed_gamma 1.0</code> for realism, this can make it cumbersome to copy color values from other applications because those values will typically be non-linear representations of the respective colors; some people may also feel more at home with non-linear colors. To mitigate this issue, a special color literal syntax has been introduced to specify color values conforming to the sRGB standard; the syntax is as follows:</p>

<pre>
  color srgb &lt;Rp,Gp,Bp&gt;
  color srgbf &lt;Rp,Gp,Bp,F&gt;
  color srgbt &lt;Rp,Gp,Bp,T&gt;
  color srgbft &lt;Rp,Gp,Bp,F,T&gt;
</pre>

<p>where Rp, Gp and Bp are pre-corrected color component values in the range from 0.0 to 1.0, while F and T are linear color component values in the same range.</p>

<p class="Note"><strong>Note:</strong> The filter and transmit components are <em>always</em> interpreted as linear values, and the use of this alternative syntax will have no effect on them.</p>

The following is also valid and gives the expected results:

<pre>
  color srgb &lt;255,240,0&gt;/255
</pre>

<p class="Note"><strong>Note:</strong> This alternative syntax for colors does <em>not</em> constitute a new flavor of colors; instead, when encountering such a statement POV-Ray will immediately convert the specified non-linear color values into a linear ones. Any access to the individual components or computations done with the resulting color will therefore access the linear values.</p>

</div>
<a name="t2_3_4_6"></a>
<div class="content-level-h4" contains="Gamma in Input Images" id="t2_3_4_6">
<h4>2.3.4.6 Gamma in Input Images</h4>

<p>Normally, gamma handling of input image files will work fine without intervention, but in some cases it may fail. To resolve such problems, the default handling can be overridden using the <code>gamma</code> SDL keyword, e.g:</p>

<pre>
  image_map { jpeg "foo.jpg" gamma 1.8 }
</pre>

<p>Instead of a numerical value, you can also use the <code>srgb</code> keyword to inform POV-Ray that the file conforms to the sRGB standard.</p>

<p>For input files in general, the following rules apply:</p>

<ul>
  <li>When using an image file in an <code>image_map</code>, POV-Ray will always convert the image data to the scene's <code>assumed_gamma</code>, according to whatever gamma the file is presumably pre-corrected for; you can override any file-specific presumtions by explicitly specifying the <code>gamma</code> <em>you</em> presume it to be pre-corrected for.</li>
  <li>When using an image file in a <code>height_field</code>, <code>bump_map</code> or <code>image_pattern</code>, POV-Ray will convert the image data to <em>linear</em> values if you explicitly specify a <code>gamma</code> for that particular file; if you don't, no gamma adjustment will be performed (or, in other words, the file will be presued to carry linear data, regardless of file format).</li>
</ul>

<p>For <code>image_map</code> input files, the following file-specific rules apply:</p>

<ul>
  <li>For OpenEXR and Radiance HDR, POV-Ray will presume the data to be linear, as per official file format specification.</li>
  <li>For PNG, POV-Ray will presume the image data to be encoded according to file header information (currently sRGB or gAMA chunks); in the absence of such information, POV-Ray will presume sRGB-compliant encoding as per official recommendation.</li>
  <li>For PPM and PGM. POV-Ray will currently presume the image data to match the <code>assumed_gamma</code> (in other words, no gamma adjustment will be performed by default).</li>
  <li>For any other file formats, POV-Ray will presume sRGB-compliant encoding, to match either official recommendations or common practice.</li>
</ul>

<p class="Note"><strong>Note:</strong> If you explicitly specify <code>gamma</code> for a particular file, POV-Ray will ignore any file format specifications, recommendations or meta information, and <em>always</em> presume the file to be pre-corrected for the specified gamma, or encoded for the specified decoding gamma. This applies in <em>all</em> contexts and to <em>all</em> file formats without exception.</p>

</div>
<a name="t2_3_4_7"></a>
<div class="content-level-h4" contains="Gamma in Legacy Scenes" id="t2_3_4_7">
<h4>2.3.4.7 Gamma in Legacy Scenes</h4>

<p>POV-Ray version 3.6 used slightly different rules for its (optional) gamma handling, while yet earlier versions used no gamma correction at all. To provide backward compatibility with legacy scenes, POV-Ray does its best to mimic the behavior of these older versions in the following cases:</p>

<ul>
  <li>If the scene contains an <code>assumed_gamma</code> statement, and does not explicitly specify a version of 3.7 or later, gamma handling will follow the 3.6 rules.</li>
  <li>If the scene does neither specify an <code>assumed_gamma</code> statement, nor explicitly specify a version of 3.7 or later, gamma correction will be turned off.</li>
</ul>

<p>The 3.6 rules differ from standard behaviour with regards to <code>image_map</code> input files as follows:</p>

<ul>
  <li>For OpenEXR, Radiance HDR and PNG, the behaviour is the same as described above.</li>
  <li>For any other file formats, in "3.6 mode" POV-Ray will currently presume the image data to match the <code>assumed_gamma</code> (in other words, no gamma adjustment will be performed by default).</li>
</ul>

<p>As POV-Ray 3.6 did not have a File_Gamma setting, and used Display_Gamma for both purposes, you will have to set File_Gamma to whatever you used to set Display_Gamma to (or leave it undefined if you did not specify Display_Gamma either) in order to get the same output.</p>

<p>Furthermore, backward compatibility with 3.6 for PNG input files is subject to the following restrictions:</p>

<ul>
  <li>For palette-based PNG files (an uncommon flavor of PNG), backward compatibility is provided only if gamma correction is disabled (i.e. <code>assumed_gamma</code> is <em>not</em> specified). This is due to fixes in the handling of this PNG flavor.</li>
  <li>For non-palette-based PNG files, backward compatibility is provided only if gamma correction is enabled (i.e. <code>assumed_gamma</code> <em>is</em> specified). This is due to inconsistencies in POV-Ray 3.6's PNG file handling which would have been prohibitively difficult to reproduce with the architectural changes in POV-Ray 3.7.</li>
  <li>For PNG files carrying both an sRGB chunk and a fitting gAMA chunk, results will slightly differ, while for PNG files carrying an sRGB chunk but no gAMA chunk (or a wrong one), backward compatibility is not provided. This is due to POV-Ray 3.6 honoring only gAMA chunks, while POV-Ray 3.7 honors sRGB chunks as well, giving them precedence over gAMA chunks to comply with the official file format specification.</li>
</ul>

<p>If you experience problems with a PNG input file in a legacy scene, explicitly specify the decoding gamma to be applied for that particular image using the <code>gamma</code> statement may help. When using e.g. <code>assumed gamma 1.8</code>, some values worth trying would be <code>gamma 1</code>, <code>gamma 1/1.8</code>, <code>gamma 2.2/1.8</code> or <code>gamma 1.8</code>. (With POV-Ray 3.6's PNG file handling having been quite a mess, it is difficult to be more specific.)</p>

</div>
<a name="t2_3_5"></a>
<div class="content-level-h3" contains="Advanced Texture Options" id="t2_3_5">
<h3>2.3.5 Advanced Texture Options</h3>
<p>The extremely powerful texturing ability is one thing that really sets
POV-Ray apart from other raytracers. So far we have not really tried anything
too complex but by now we should be comfortable enough with the program's
syntax to try some of the more advanced texture options.</p>
<p>
Obviously, we cannot try them all. It would take a tutorial a lot more pages
to use every texturing option available in POV-Ray. For this limited
tutorial, we will content ourselves to just trying a few of them to give an
idea of how textures are created. With a little practice, we will soon be
creating beautiful textures of our own.</p>
<p class="Note"><strong>Note:</strong> Early versions of POV-Ray made a distinction between pigment and
normal patterns, i. e. patterns that could be used inside a <code>
normal</code> or <code>pigment</code> statement. Since POV-Ray 3.0 this
restriction was removed so that all patterns listed in section <a href="r3_4.html#r3_4_7">Pattern</a> can be used as a pigment or normal pattern.</p>

</div>
<a name="t2_3_5_1"></a>
<div class="content-level-h4" contains="Pigments" id="t2_3_5_1">
<h4>2.3.5.1 Pigments</h4>
<p>Every surface must have a color. In POV-Ray this color is called a <code><a href="r3_4.html#r3_4_6_1">pigment</a></code>.
It does not have to be a single color. It can be a color pattern, a color
list or even an image map. Pigments can also be layered one on top of the next
so long as the uppermost layers are at least partially transparent so the ones
beneath can show through. Let's play around with some of these kinds of
pigments.</p>
<p>
We create a file called <code>texdemo.pov</code> and edit it as
follows:</p>
<pre>
  #include &quot;colors.inc&quot;
  camera {
    location &lt;1, 1, -7&gt;
    look_at 0
    angle 36
  }
  light_source { &lt;1000, 1000, -1000&gt; White }
  plane {
    y, -1.5
    pigment { checker Green, White }
  }
  sphere {
    &lt;0,0,0&gt;, 1
    pigment { Red }
  }
</pre>

<p>Giving this file a quick test render we see
that it is a simple red sphere against a green and white checkered plane. We
will be using the sphere for our textures.</p>

</div>
<a name="t2_3_5_1_1"></a>
<div class="content-level-h5" contains="Using Color List Pigments" id="t2_3_5_1_1">
<h5>2.3.5.1.1 Using Color List Pigments</h5>
<p>Before we begin we should note that we have already made one kind of
pigment, the color list pigment. In the previous example we have used a
checkered pattern on our plane. There are three other kinds of color list
pigments, <code><a href="r3_4.html#r3_4_7_1_4">brick</a></code>, <code><a href="r3_4.html#r3_4_7_2_4">hexagon</a></code> and the
<code><a href="r3_4.html#r3_4_7_2_5">object</a></code> pattern.
Let's quickly try each of these. First, we change the plane's
pigment as follows:</p>
<pre>
  pigment { hexagon Green, White, Yellow }
</pre>

<p>Rendering this we see a three-color hexagonal pattern. Note that this
pattern requires three colors. Now we change the pigment to...</p>
<pre>
  pigment { brick Gray75, Red rotate -90*x scale .25 }
</pre>

<p>Looking at the resulting image we see that the plane now has a brick
pattern. We note that we had to rotate the pattern to make it appear
correctly on the flat plane. This pattern normally is meant to be used on
vertical surfaces. We also had to scale the pattern down a bit so we could
see it more easily. We can play around with these color list pigments, change
the colors, etc. until we get a floor that we like.</p>

</div>
<a name="t2_3_5_1_2"></a>
<div class="content-level-h5" contains="Using Pigment and Patterns" id="t2_3_5_1_2">
<h5>2.3.5.1.2 Using Pigment and Patterns</h5>
<p>Let's begin texturing our sphere by using a pattern and a color map
consisting of three colors. We replace the pigment block with the
following.</p>
<pre>
  pigment {
    gradient x
    color_map {
      [0.00 color Red]
      [0.33 color Blue]
      [0.66 color Yellow]
      [1.00 color Red]
    }
  }
</pre>
<p>Rendering this we see that the <code><a href="r3_4.html#r3_4_7_1_13">gradient</a></code> pattern gives us an
interesting pattern of vertical stripes. We change the gradient direction to
y. The stripes are horizontal now. We change the gradient direction to z. The
stripes are now more like concentric rings. This is because the gradient
direction is directly away from the camera. We change the direction back to x
and add the following to the pigment block.</p>
<pre>
  pigment {
    gradient x
    color_map {
      [0.00 color Red]
      [0.33 color Blue]
      [0.66 color Yellow]
      [1.00 color Red]
    }
    rotate -45*z          // &lt;- add this line
  }
</pre>
<p>The vertical bars are now slanted at a 45 degree angle. All patterns can
be rotated, scaled and translated in this manner. Let's now try some
different types of patterns. One at a time, we substitute the following
keywords for <code>gradient x</code> and render to see the result: <code><a href="r3_4.html#r3_4_7_1_3">bozo</a></code>,
<code><a href="r3_4.html#r3_4_7_1_16">marble</a></code>, <code><a href="r3_4.html#r3_4_7_1_1">agate</a></code>, <code><a href="r3_4.html#r3_4_7_1_14">granite</a></code>,
<code><a href="r3_4.html#r3_4_7_1_15">leopard</a></code>, <code><a href="r3_4.html#r3_4_7_1_27">spotted</a></code> and <code><a href="r3_4.html#r3_4_7_1_30">wood</a></code>
(if we like  we can test all patterns listed in section <a href="r3_4.html#r3_4_7">Pattern</a>).</p>
<p>
Rendering these we see that each results in a slightly different pattern.
But to get really good results each type of pattern requires the use of some
pattern modifiers.</p>

</div>
<a name="t2_3_5_1_3"></a>
<div class="content-level-h5" contains="Using Pattern Modifiers" id="t2_3_5_1_3">
<h5>2.3.5.1.3 Using Pattern Modifiers</h5>
<p>Let's take a look at some pattern modifiers. First, we change the
pattern type to bozo. Then we add the following change.</p>
<pre>
  pigment {
    bozo
    frequency 3            // &lt;- add this line
    color_map {
      [0.00 color Red]
      [0.33 color Blue]
      [0.66 color Yellow]
      [1.00 color Red]
    }
    rotate -45*z
  }
</pre>
<p>The <code>frequency</code> modifier determines the number of times the
color map repeats itself per unit of size. This change makes the <code>bozo</code>
pattern we saw earlier have many more bands in it. Now we change
the pattern type to <code>marble</code>. When we rendered this earlier, we
saw a banded pattern similar to <code>gradient y</code> that really did not
look much like marble at all. This is because marble really is a kind of
gradient and it needs another pattern modifier to look like marble. This
modifier is called <code><a href="r3_4.html#r3_4_7_5_5_9">turbulence</a></code>. We change the line <code>
frequency 3</code> to <code>turbulence 1</code> and render again. That's
better! Now let's put <code>frequency 3</code> back in right after the
turbulence and take another look. Even more interesting!</p>
<p>
But wait, it gets better! Turbulence itself has some modifiers of its own. We can adjust the turbulence several ways. First, the float that follows the <code>turbulence</code> keyword can be any value with higher values giving
us more turbulence. Second, we can use the keywords <code><a href="r3_4.html#r3_4_7_5_5_6">omega</a></code>, <code><a href="r3_4.html#r3_4_7_5_5_5">lambda</a></code> and <code><a href="r3_4.html#r3_4_7_5_5_4">octaves</a></code> to change the turbulence parameters.</p>
<p>
Let's try this now:</p>
<pre>
  pigment {
    marble
    turbulence 0.5
    lambda 1.5
    omega 0.8
    octaves 5
    frequency 3
    color_map {
      [0.00 color Red]
      [0.33 color Blue]
      [0.66 color Yellow]
      [1.00 color Red]
    }
    rotate 45*z
  }
</pre>

<p>Rendering this we see that the turbulence has changed and the pattern
looks different. We play around with the numerical values of turbulence,
lambda, omega and octaves to see what they do.</p>

</div>
<a name="t2_3_5_1_4"></a>
<div class="content-level-h5" contains="Using Transparent Pigments and Layered Textures" id="t2_3_5_1_4">
<h5>2.3.5.1.4 Using Transparent Pigments and Layered Textures</h5>
<p>Pigments are described by numerical values that give the <a href="r3_3.html#r3_3_1_7_1">rgb</a> value of the color to be used (like <code>color rgb&lt;1,0,0&gt;</code> giving us a red
color). But this syntax will give us more than just the rgb values. We can
specify filtering transparency by changing it as follows: <code>color
rgbf&lt;1,0,0,1&gt;</code>. The <em>f</em> stands for <code>filter</code>,
POV-Ray's word for <a href="r3_3.html#r3_3_1_7_1">filtered</a> transparency. A value of one means that the
color is completely transparent, but still filters the light according to
what the pigment is. In this case, the color will be a transparent red, like
red cellophane.</p>
<p>
There is another kind of transparency in POV-Ray. It is called <em>transmittance</em>
or non-filtering transparency (the keyword is <code><a href="r3_3.html#r3_3_1_7">transmit</a></code>;
see also <code><a href="r3_3.html#r3_3_1_7_1">rgbt</a></code>). It is different from <code>filter</code> in that it does not filter the light according to the pigment color. It instead allows all the light to pass through unchanged. It can be specified like this: <code>rgbt &lt;1,0,0,1&gt;</code>.</p>
<p>
Let's use some transparent pigments to create another kind of texture,
the layered texture. Returning to our previous example, declare the following
texture.</p>
<pre>
  #declare LandArea = texture {
      pigment {
        agate
        turbulence 1
        lambda 1.5
        omega .8
        octaves 8
        color_map {
          [0.00 color rgb &lt;.5, .25, .15&gt;]
          [0.33 color rgb &lt;.1, .5, .4&gt;]
          [0.86 color rgb &lt;.6, .3, .1&gt;]
          [1.00 color rgb &lt;.5, .25, .15&gt;]
        }
      }
    }
</pre>

<p>This texture will be the land area. Now let's make the oceans by
declaring the following.</p>
<pre>
  #declare OceanArea = texture {
      pigment {
        bozo
        turbulence .5
        lambda 2
        color_map {
          [0.00, 0.33 color rgb &lt;0, 0, 1&gt;
                      color rgb &lt;0, 0, 1&gt;]
          [0.33, 0.66 color rgbf &lt;1, 1, 1, 1&gt;
                      color rgbf &lt;1, 1, 1, 1&gt;]
          [0.66, 1.00 color rgb &lt;0, 0, 1&gt;
                      color rgb &lt;0, 0, 1&gt;]
        }
      }
    }
</pre>

<p class="Note"><strong>Note:</strong> Now the ocean is the opaque blue area and the land is the clear area
which will allow the underlying texture to show through.</p>
<p>
Now, let's declare one more texture to simulate an atmosphere with
swirling clouds.</p>
<pre>
  #declare CloudArea = texture {
    pigment {
      agate
      turbulence 1
      lambda 2
      frequency 2
      color_map {
        [0.0 color rgbf &lt;1, 1, 1, 1&gt;]
        [0.5 color rgbf &lt;1, 1, 1, .35&gt;]
        [1.0 color rgbf &lt;1, 1, 1, 1&gt;]
      }
    }
  }
</pre>

<p>Now apply all of these to our sphere.</p>
<pre>
  sphere {
    &lt;0,0,0&gt;, 1
    texture { LandArea }
    texture { OceanArea }
    texture { CloudArea }
  }
</pre>

<p>We render this and have a pretty good rendition of a little planetoid. But
it could be better. We do not particularly like the appearance of the
clouds. There is a way they could be done that would be much more
realistic.</p>

</div>
<a name="t2_3_5_1_5"></a>
<div class="content-level-h5" contains="Using Pigment Maps" id="t2_3_5_1_5">
<h5>2.3.5.1.5 Using Pigment Maps</h5>
<p>Pigments may be blended together in the same way as the colors in a color
map using the same pattern keywords and a <code>pigment_map</code>. Let's
just give it a try.</p>
<p>
We add the following declarations, making sure they appear before the other
declarations in the file.</p>
<pre>
  #declare Clouds1 = pigment {
      bozo
      turbulence 1
      color_map {
        [0.0 color White filter 1]
        [0.5 color White]
        [1.0 color White filter 1]
      }
    }
  #declare Clouds2 = pigment {
    agate
    turbulence 1
    color_map {
      [0.0 color White filter 1]
      [0.5 color White]
      [1.0 color White filter 1]
      }
    }
  #declare Clouds3 = pigment {
    marble
    turbulence 1
    color_map {
      [0.0 color White filter 1]
      [0.5 color White]
      [1.0 color White filter 1]
    }
  }
  #declare Clouds4 = pigment {
    granite
    turbulence 1
    color_map {
      [0.0 color White filter 1]
      [0.5 color White]
      [1.0 color White filter 1]
    }
  }
</pre>

<p>Now we use these declared pigments in our cloud layer on our planetoid. We
replace the declared cloud layer with.</p>
<pre>
  #declare CloudArea = texture {
    pigment {
      gradient y
      pigment_map {
        [0.00 Clouds1]
        [0.25 Clouds2]
        [0.50 Clouds3]
        [0.75 Clouds4]
        [1.00 Clouds1]
      }
    }
  }
</pre>

<p>We render this and see a remarkable pattern that looks very much like
weather patterns on the planet earth. They are separated into bands,
simulating the different weather types found at different latitudes.</p>

</div>
<a name="t2_3_5_2"></a>
<div class="content-level-h4" contains="Normals" id="t2_3_5_2">
<h4>2.3.5.2 Normals</h4>
<p>Objects in POV-Ray have very smooth surfaces. This is not very realistic
so there are several ways to disturb the smoothness of an object by
perturbing the surface normal. The surface normal is the vector that is
perpendicular to the angle of the surface. By changing this normal the
surface can be made to appear bumpy, wrinkled or any of the many patterns
available. Let's try a couple of them.</p>

</div>
<a name="t2_3_5_2_1"></a>
<div class="content-level-h5" contains="Using Basic Normal Modifiers" id="t2_3_5_2_1">
<h5>2.3.5.2.1 Using Basic Normal Modifiers</h5>
<p>We comment out the planetoid sphere for now and, at the bottom of the
file, create a new sphere with a simple, single color texture.</p>
<pre>
  sphere {
    &lt;0,0,0&gt;, 1
    pigment { Gray75 }
    normal { bumps 1 scale .2 }
  }
</pre>

<p>Here we have added a <code>normal</code> block in addition to the <code>
pigment</code> block (note that these do not have to be included in a <code>
texture</code> block unless they need to be transformed together or need to
be part of a layered texture). We render this to see what it looks like. Now,
one at a time, we substitute for the keyword <code><a href="r3_4.html#r3_4_7_1_5">bumps</a></code> the following
keywords: <code><a href="r3_4.html#r3_4_7_1_9">dents</a></code>, <code><a href="r3_4.html#r3_4_7_1_31">wrinkles</a></code>,
<code><a href="r3_4.html#r3_4_7_1_23">ripples</a></code> and <code><a href="r3_4.html#r3_4_7_1_29">waves</a></code>
(we can also use any of the patterns listed in <a href="r3_4.html#r3_4_7">Pattern</a>).
We render each to see what they look like. We play around with the float value that follows the
keyword. We also experiment with the scale value.</p>
<p>
For added interest, we change the plane texture to a single color with a
normal as follows.</p>
<pre>
  plane {
    y, -1.5
    pigment { color rgb &lt;.65, .45, .35&gt; }
    normal { dents .75 scale .25 }
  }
</pre>

</div>
<a name="t2_3_5_2_2"></a>
<div class="content-level-h5" contains="Blending Normals" id="t2_3_5_2_2">
<h5>2.3.5.2.2 Blending Normals</h5>
<p>Normals can be layered similar to pigments but the results can be
unexpected. Let's try that now by editing the sphere as follows.</p>
<pre>
  sphere {
    &lt;0,0,0&gt;, 1
    pigment { Gray75 }
      normal { radial frequency 10 }
      normal { gradient y scale .2 }
  }
</pre>

<p>As we can see, the resulting pattern is neither a radial nor a gradient.
It is instead the result of first calculating a radial pattern and then
calculating a gradient pattern. The results are simply additive. This can be
difficult to control so POV-Ray gives the user other ways to blend
normals.</p>
<p>
One way is to use normal maps. A normal map works the same way as the
pigment map we used earlier. Let's change our sphere texture as
follows.</p>
<pre>
  sphere {
    &lt;0,0,0&gt;, 1
    pigment { Gray75 }
    normal {
      gradient y
      frequency 3
      turbulence .5
      normal_map {
        [0.00 granite]
        [0.25 spotted turbulence .35]
        [0.50 marble turbulence .5]
        [0.75 bozo turbulence .25]
        [1.00 granite]
      }
    }
  }
</pre>

<p>Rendering this we see that the sphere now has a very irregular bumpy
surface. The gradient pattern type separates the normals into bands but they
are turbulated, giving the surface a chaotic appearance. But this gives us an
idea.</p>
<p>
Suppose we use the same pattern for a normal map that we used to create the
oceans on our planetoid and applied it to the land areas. Does it follow that
if we use the same pattern and modifiers on a sphere the same size that the
shape of the pattern would be the same? Would not that make the land areas
bumpy while leaving the oceans smooth? Let's try it. First, let's
render the two spheres side-by-side so we can see if the pattern is indeed
the same. We un-comment the planetoid sphere and make the following
changes.</p>
<pre>
  sphere {
    &lt;0,0,0&gt;, 1
    texture { LandArea }
    texture { OceanArea }
    //texture { CloudArea }  // &lt;-comment this out
    translate -x             // &lt;- add this transformation
  }
</pre>

<p>Now we change the gray sphere as follows.</p>
<pre>
  sphere {
    &lt;0,0,0&gt;, 1
    pigment { Gray75 }
    normal {
      bozo
      turbulence .5
      lambda 2
      normal_map {
        [0.4 dents .15 scale .01]
        [0.6 agate turbulence 1]
        [1.0 dents .15 scale .01]
      }
    }
    translate x // &lt;- add this transformation
  }
</pre>

<p>We render this to see if the pattern is the same. We see that indeed it
is. So let's comment out the gray sphere and add the <code>normal</code>
block it contains to the land area texture of our planetoid. We remove the
transformations so that the planetoid is centered in the scene again.</p>
<pre>
  #declare LandArea = texture {
    pigment {
      agate
      turbulence 1
      lambda 1.5
      omega .8
      octaves 8
      color_map {
        [0.00 color rgb &lt;.5, .25, .15&gt;]
        [0.33 color rgb &lt;.1, .5, .4&gt;]
        [0.86 color rgb &lt;.6, .3, .1&gt;]
        [1.00 color rgb &lt;.5, .25, .15&gt;]
      }
    }
    normal {
      bozo
      turbulence .5
      lambda 2
      normal_map {
        [0.4 dents .15 scale .01]
        [0.6 agate turbulence 1]
        [1.0 dents .15 scale .01]
      }
    }
  }
</pre>

<p>Looking at the resulting image we see that indeed our idea works! The land
areas are bumpy while the oceans are smooth. We add the cloud layer back in
and our planetoid is complete.</p>
<p>
There is much more that we did not cover here due to space constraints. On
our own, we should take the time to explore slope maps, average and bump
maps.</p>

</div>
<a name="t2_3_5_2_3"></a>
<div class="content-level-h5" contains="Slope Map Tutorial" id="t2_3_5_2_3">
<h5>2.3.5.2.3 Slope Map Tutorial</h5>
<p>One of the most powerful texturing features of POV-Ray is normal perturbation (which is specified using the <code>normal</code> block of an object texture). With this feature it's possible to emulate small surface displacement in a very efficient way, without actually having to modify the actual surface (which often would increase the complexity of the object considerably, resulting in much slower renders).</p>
<p>Slope maps are used to define more precisely how the normal perturbation is generated from a specified pattern. Slope maps are a very powerful feature often dismissed by many.</p>
<p>As an example, let's create a simple scene with an object using normal perturbation:</p>
<pre>
camera { location &lt;0, 10, -7&gt;*1.4 look_at 0 angle 35 }
light_source
{ &lt;100, 80, -30&gt;, 1 area_light z*20, y*20, 12, 12 adaptive 0 }
plane { y, 0 pigment { rgb 1 } }

cylinder
{ 0, y, 4
  pigment { rgb &lt;1, .9, .2&gt; }
  finish { specular 1 }
  normal
  { wood 1
    rotate x*90
  }
}
</pre>

<table class="centered" width="340px" cellpadding="0" cellspacing="10">
<tr>
  <td>
    <img class="center" width="320px" src="images/8/89/TutImgSlopemap1.jpg">
  </td>
</tr>
<tr>
  <td>
    <p class="caption">Normal modifier example</p>
  </td>
</tr>
</table>

<p>By default the <code>wood</code> pattern uses a ramp wave (going from 0 to 1 and then back to 0) arranged in concentric circles, as we can see from the image.</p>
<p>By default POV-Ray simply takes the values of the pattern as they are in order to calculate the normal perturbation of the surface. However, using a <code>slope_map</code> we can more precisely define how these values are interpreted. For example, if we add this <code>slope_map</code> (the meaning of the values are explained later in this tutorial) to the <code>normal</code> block in the example above:</p>
<pre>
    slope_map
    { [0 &lt;0, 0&gt;]
      [.2 &lt;1, 1&gt;]
      [.2 &lt;1, 0&gt;]
      [.8 &lt;1, 0&gt;]
      [.8 &lt;1, -1&gt;]
      [1 &lt;0, 0&gt;]
    }
</pre>
<p>we get a much more interesting result:</p>

<table class="centered" width="340px" cellpadding="0" cellspacing="10">
<tr>
  <td>
    <img class="center" width="320px" src="images/f/f3/TutImgSlopemap2.jpg">
  </td>
</tr>
<tr>
  <td>
    <p class="caption">Slope map example 1</p>
  </td>
</tr>
</table>

<p>We can also use a slope map to simply smooth out the original ramp wave pattern like this:</p>
<pre>
    slope_map
    { [0 &lt;0, 0&gt;]
      [.5 &lt;.5, 1&gt;]
      [1 &lt;1, 0&gt;]
    }
</pre>

<table class="centered" width="340px" cellpadding="0" cellspacing="10">
<tr>
  <td>
    <img class="center" width="320px" src="images/3/34/TutImgSlopemap3.jpg">
  </td>
</tr>
<tr>
  <td>
    <p class="caption">Slope map example 2</p>
  </td>
</tr>
</table>

</div>
<a name="t2_3_5_2_3_1"></a>
<div class="content-level-h6" contains="Slopes, what are they?" id="t2_3_5_2_3_1">
<h6>2.3.5.2.3.1 Slopes, what are they?</h6>
<p>Mathematically speaking the slope of a curve (also called gradient) at a certain point is the <code>tan()</code> of the angle of the tangent line of that curve at that point. In other words, it's the amount of change of the vertical coordinate with respect to the change of the horizontal coordinate.</p>
<p>In a more colloquial way, the slope of a completely horizontal part of the curve is 0. The slope of a 45-degree line is 1 (because for each unit in the horizontal direction the line goes up by the same amount). Lines between 0 and 45 degrees have corresponding slopes between 0 and 1 (the relation between them is not linear, though, but one usually doesn't have to worry about that). Lines with an angle of over 45 degrees have correspondently slopes increasingly larger than 1 (a line of 90 degrees has an infinite slope).</p>
<p>Usually when defining slope maps it's enough to keep between slopes of 0 and 1, even though higher slopes are sometimes useful too to get steeper changes. Usually it's enough to think that a slope of 0 means a horizontal part of the curve while a slope of 1 means a 45-degree steep part of the curve (and slopes between 0 and 1 correspond to degrees between 0 and 45 respectively).</p>
<p>A slope can be negative too. A negative slope simply means that the curve is going down instead of going up.</p>
<p>The following figure shows some basic slopes in a curve (note that the slope values are only approximate):</p>

<table class="centered" width="648px" cellpadding="0" cellspacing="10">
<tr>
  <td>
    <img class="center" width="628px" src="images/3/3e/TutImgSlopemap4.png">
  </td>
</tr>
<tr>
  <td>
    <p class="caption">Slopes in a curve</p>
  </td>
</tr>
</table>

</div>
<a name="t2_3_5_2_3_2"></a>
<div class="content-level-h6" contains="Syntax of a slope map" id="t2_3_5_2_3_2">
<h6>2.3.5.2.3.2 Syntax of a slope map</h6>
<p>In the exact same way as for example a <code>color_map</code> assigns colors to pattern values, a <code>slope_map</code> assign slopes to pattern values. If you are fluent in defining color maps for a pattern, defining a slope map shouldn't be any more difficult.</p>
<p>Each entry in a slope map takes two values: The <em>displacement</em> of the surface (although one should remember that this displacement is only simulated, not real) and the slope of the surface at that point.</p>
<p>You can think of the first parameter as an altitude value which tells how much the surface (in relative terms) is displaced from its original location. Usually values between 0 and 1 are used for this. You can think of 0 meaning that the surface is not displaced and 1 as the surface having maximum displacement (outwards).</p>
<p>Let's examine the slope map we used to smooth out the wood pattern at the beginning of this tutorial:</p>
<pre>
    slope_map
    { [0 &lt;0, 0&gt;]
      [.5 &lt;.5, 1&gt;]
      [1 &lt;1, 0&gt;]
    }
</pre>
<p>This means:</p>
<ul>
<li>When the pattern has a value of 0, the surface is not displaced and the slope of the surface is 0 (ie. it's horizontal).</li>
<li>When the pattern has a value of 0.5, the surface is displaced by 0.5 and the slope of the surface is 1.</li>
<li>When the pattern has a value of 1, the surface has maximum displacement and the slope is again 0, ie. horizontal.</li>
</ul>
<p>When the pattern is linear (as the wood pattern is), this kind of slope map corresponds approximately to a half sine wave. Since the wood pattern uses a ramp wave (ie. after going from 0 to 1 it then goes from 1 to 0), the result is basically a complete (approximate) sine wave.</p>
<p>As with a color map, all the values in between are interpolated and that's why we get a smooth transition between these values.</p>

</div>
<a name="t2_3_5_2_3_3"></a>
<div class="content-level-h6" contains="Examples of slope maps" id="t2_3_5_2_3_3">
<h6>2.3.5.2.3.3 Examples of slope maps</h6>
<p>As we saw in the first slope map example in this tutorial, it is possible to create sharp transitions, not just smooth ones. This is achieved in the same way as how sharp transitions are achieved with color maps: By repeating the same pattern value. Here is an example:</p>
<pre>
    slope_map
    { [0 &lt;0, 1&gt;]
      [.5 &lt;1, 1&gt;]
      [.5 &lt;1, -.3&gt;]
      [1 &lt;.7, -.3&gt;]
    }
</pre>

<table class="centered" width="340px" cellpadding="0" cellspacing="10">
<tr>
  <td>
    <img class="center" width="320px" src="images/9/9c/TutImgSlopemap5.jpg">
  </td>
</tr>
<tr>
  <td>
    <p class="caption">Slope map example 3</p>
  </td>
</tr>
</table>

<p>There's a sharp transition at the pattern value 0.5, where the surface goes from slope 1 to slope -0.3 (ie. from going strongly upwards to going slightly downwards). Due to how the wood pattern repeats itself, there are also sharp transitions at the pattern values 0 and 1.</p>
<p>We can combine sharp and smooth transitions for nice effects. For example, this simple slope map achieves a nice result:</p>
<pre>
    slope_map
    { [0 &lt;0, 1&gt;]
      [1 &lt;1, 0&gt;]
    }
</pre>

<table class="centered" width="340px" cellpadding="0" cellspacing="10">
<tr>
  <td>
    <img class="center" width="320px" src="images/4/4a/TutImgSlopemap6.jpg">
  </td>
</tr>
<tr>
  <td>
    <p class="caption">Slope map example 4</p>
  </td>
</tr>
</table>

<ul>
<li>At the pattern value 0 the <em>displacement</em> of the surface is 0 and the slope is 1 (ie. strongly upwards).</li>
<li>At the pattern value 1 the surface is fully displaced and horizontal.</li>
<li>Due to the ramp-wave-repetition quality of the wood pattern (which effectively reverses this pattern), the surface then continues smoothly from this point until it descends to 0, where the slope is now effectively -1. Now there's a sharp transition from -1 back to 1 as the pattern starts over.</li>
</ul>
<p>One application where slope maps are really useful is when creating tiled floors. When the tiles on a floor are not too close to the camera and there is a very large amount of tiles, instead of creating hundreds or thousands of individual tile objects, it may be more efficient to simply create a normal pattern which emulates the tiles.</p>
<p>This example shows how to create a floor made of wooden planks:</p>
<pre>
camera { location &lt;2, 10, -12&gt;*.5 look_at 0 angle 35 }
light_source
{ &lt;100, 150, 0&gt;, 1 area_light z*40, y*40, 12, 12 adaptive 0 }
sphere { y*.5, .5 pigment { rgb x } finish { specular .5 } }

plane
{ y, 0
  pigment
  { wood color_map { [0 rgb &lt;.9,.7,.3&gt;][1 rgb &lt;.8,.5,.2&gt;] }
    turbulence .5
    scale &lt;1, 1, 20&gt;*.2
  }
  finish { specular 1 }
  normal
  { gradient x 1
    slope_map
    { [0 &lt;0, 1&gt;] // 0 height, strong slope up
      [.05 &lt;1, 0&gt;] // maximum height, horizontal
      [.95 &lt;1, 0&gt;] // maximum height, horizontal
      [1 &lt;0, -1&gt;] // 0 height, strong slope down
    }
  }
}
</pre>

<table class="centered" width="340px" cellpadding="0" cellspacing="10">
<tr>
  <td>
    <img class="center" width="320px" src="images/c/cc/TutImgSlopemap7.jpg">
  </td>
</tr>
<tr>
  <td>
    <p class="caption">Slope map example 5</p>
  </td>
</tr>
</table>

<p>In this case a gradient pattern was used. Since the gradient pattern goes from 0 to 1 and then immediately back to 0, we have to mirror the slope map (around 0.5) in order to get a repetitive symmetric result.</p>
<p>In this example the slope map starts from 0 height and a strong slope up, and goes quickly to maximum height, where the surface is horizontal. Then there's a large horizontal area (from pattern value 0.5 to 0.95) after which the slope goes rapidly back down to 0 height and a strong slope down. (After this there's a sharp transition to the beginning due to the gradient pattern starting over.)</p>
<p>If we want square tiles instead of just planks, we can achieve that by eg. using an average normal map like this:</p>
<pre>
  #declare TileNormal =
    normal
    { gradient x 2 // Double the strength because of the averaging
      slope_map
      { [0 &lt;0, 1&gt;] // 0 height, strong slope up
        [.05 &lt;1, 0&gt;] // maximum height, horizontal
        [.95 &lt;1, 0&gt;] // maximum height, horizontal
        [1 &lt;0, -1&gt;] // 0 height, strong slope down
      }
    }
  normal
  { average normal_map
    { [1 TileNormal]
      [1 TileNormal rotate y*90]
    }
  }
</pre>

<table class="centered" width="340px" cellpadding="0" cellspacing="10">
<tr>
  <td>
    <img class="center" width="320px" src="images/8/89/TutImgSlopemap8.jpg">
  </td>
</tr>
<tr>
  <td>
    <p class="caption">Slope map example 6</p>
  </td>
</tr>
</table>

<p>If we change the pigment of the plane a bit, we get a nice tiled floor:</p>
<pre>
  pigment
  { checker
    pigment { granite color_map { [0 rgb 1][1 rgb .9] } }
    pigment { granite color_map { [0 rgb .9][1 rgb .7] } }
  }
</pre>

<table class="centered" width="340px" cellpadding="0" cellspacing="10">
<tr>
  <td>
    <img class="center" width="320px" src="images/1/14/TutImgSlopemap9.jpg">
  </td>
</tr>
<tr>
  <td>
    <p class="caption">Slope map example 7</p>
  </td>
</tr>
</table>

<p>As you can see in the image, close to the camera it's more evident that the tiles are not truely three-dimensional (and that only a normal perturbation trick has been used), but farther away from the camera the effect is pretty convincing.</p>

</div>
<a name="t2_3_5_3"></a>
<div class="content-level-h4" contains="Finishes" id="t2_3_5_3">
<h4>2.3.5.3 Finishes</h4>
<p>The final part of a POV-Ray texture is the <code><a href="r3_4.html#r3_4_6_3">finish</a></code>. It
controls the properties of the surface of an object. It can make it shiny and
reflective, or dull and flat. It can also specify what happens to light that
passes through transparent pigments, what happens to light that is scattered
by less-than-perfectly-smooth surfaces and what happens to light that is
reflected by surfaces with thin-film interference properties. There are
twelve different properties available in POV-Ray to specify the finish of a
given object. These are controlled by the following keywords: <code><a href="r3_4.html#r3_4_6_3_1">ambient</a></code>,
<code><a href="r3_4.html#r3_4_6_3_3_1">diffuse</a></code>, <code><a href="r3_4.html#r3_4_6_3_3_2">brilliance</a></code>,
<code><a href="r3_4.html#r3_4_6_3_4_1">phong</a></code>, <code><a href="r3_4.html#r3_4_6_3_4_2">specular</a></code>, <code><a href="r3_4.html#r3_4_6_3_4_3">metallic</a></code>, <code><a href="r3_4.html#r3_4_6_3_5">reflection</a></code>, <code><a href="r3_4.html#r3_4_6_3_3_3">crand</a></code> and <code><a href="r3_4.html#r3_4_6_3_7">iridescence</a></code>. Let's design a couple of textures that make use of these parameters.</p>

</div>
<a name="t2_3_5_3_1"></a>
<div class="content-level-h5" contains="Using Ambient" id="t2_3_5_3_1">
<h5>2.3.5.3.1 Using Ambient</h5>
<p>Since objects in POV-Ray are illuminated by light sources, the portions of
those objects that are in shadow would be completely black were it not for
the first two finish properties, <code><a href="r3_4.html#r3_4_6_3_1">ambient</a></code> and
<code>><a href="r3_4.html#r3_4_6_3_3_1">diffuse</a></code>. Ambient is used to simulate the light that is scattered
around the scene that does not come directly from a light source. Diffuse
determines how much of the light that is seen comes directly from a light
source. These two keywords work together to control the simulation of ambient
light. Let's use our gray sphere to demonstrate this. Let's also
change our plane back to its original green and white checkered pattern.</p>
<pre>
  plane {
    y, -1.5
    pigment {checker Green, White}
  }
  sphere {
    &lt;0,0,0&gt;, 1
    pigment { Gray75 }
    finish {
      ambient .2
      diffuse .6
    }
  }
</pre>

<p>In the above example, the default values for ambient and diffuse are used.
We render this to see what the effect is and then make the following change
to the finish.</p>
<pre>
  ambient 0
  diffuse 0
</pre>

<p>The sphere is black because we have specified that none of the light
coming from any light source will be reflected by the sphere. Let's
change <code>diffuse</code> back to the default of 0.6.</p>
<p>
Now we see the gray surface color where the light from the light source
falls directly on the sphere but the shaded side is still absolutely black.
Now let's change <code>diffuse</code> to 0.3 and <code>ambient</code> to
0.3.</p>
<p>
The sphere now looks almost flat. This is because we have specified a fairly
high degree of ambient light and only a low amount of the light coming from
the light source is diffusely reflected towards the camera. The default
values of <code> ambient</code> and <code>diffuse</code> are pretty good
averages and a good starting point. In most cases, an ambient value of 0.1
... 0.2 is sufficient and a diffuse value of 0.5 ... 0.7 will usually do the
job. There are a couple of exceptions. If we have a completely transparent
surface with high refractive and/or reflective values, low values of both
ambient and diffuse may be best. Here is an example:</p>
<pre>
sphere {
   &lt;0,0,0&gt;, 1
   pigment { White filter 1 }
   finish {
      ambient 0
      diffuse 0
      reflection .25
      specular 1
      roughness .001
   }
   interior { ior 1.33 }
}
</pre>

<p>This is glass, obviously. Glass is a material that takes nearly all of its
appearance from its surroundings. Very little of the surface is seen because
it transmits or reflects practically all of the light that shines on it. See
<code>glass.inc</code> for some other examples.</p>

<p class="Note"><strong>Note:</strong> As of POV-Ray 3.7, <code>ambient</code> is disabled when using radiosity, as both mechanisms are intended to simulate the same thing (albeit with different quality) and don't play well together.</p>

</div>
<a name="t2_3_5_3_2"></a>
<div class="content-level-h5" contains="Using Emission" id="t2_3_5_3_2">
<h5>2.3.5.3.2 Using Emission</h5>
<p>
If we ever need an object to be completely illuminated independently of the
lighting situation in a given scene we can do this artificially by specifying
an <code>emission</code> value of 1 and an <code>ambient</code> and <code>diffuse</code> value of 0.
This will eliminate all shading and simply give the object its fullest and
brightest color value at all points. This is good for simulating objects that
emit light like light bulbs and for skies in scenes where the sky may not be
adequately lit by any other means.</p>
<p>
Let's try this with our sphere now.</p>
<pre>
  sphere {
     &lt;0,0,0&gt;, 1
     pigment { White }
     finish {
        emission 1
        ambient 0
        diffuse 0
     }
  }
</pre>

<p>Rendering this we get a blinding white sphere with no visible highlights
or shaded parts. It would make a pretty good street light.</p>

<p class="Note"><strong>Note:</strong> Versions of POV-Ray prior to 3.7 did not provide the <code>emission</code> keyword for finish, and it was customary to resort to <code>ambient</code> instead for such purpose. This is now discouraged, as <code>ambient</code> is now disabled when using radiosity.</p>

</div>


<a name="t2_3_5_3_3"></a>
<div class="content-level-h5" contains="Using Surface Highlights" id="t2_3_5_3_3">
<h5>2.3.5.3.3 Using Surface Highlights</h5>
<p>In the glass example above, we noticed that there were bright little <em>
hotspots</em> on the surface. This gave the sphere a hard, shiny appearance.
POV-Ray gives us two ways to specify surface specular highlights. The first
is called <em>phong highlighting.</em> Usually, phong highlights are
described using two keywords: <code><a href="r3_4.html#r3_4_6_3_4_1">phong</a></code> and <code>
<a href="r3_4.html#r3_4_6_3_4_1">phong_size</a></code>. The float that follows <code>phong</code> determines the brightness of the highlight while the float following <code>phong_size</code> determines its size. Let's try this.</p>
<pre>
  sphere {
    &lt;0,0,0&gt;, 1
    pigment { Gray50 }
    finish {
      ambient .2
      diffuse .6
      phong .75
      phong_size 25
    }
  }
</pre>

<p>Rendering this we see a fairly broad, soft highlight that gives the sphere
a kind of plastic appearance. Now let's change <code>phong_size</code>
to 150. This makes a much smaller highlight which gives the sphere the
appearance of being much harder and shinier.</p>
<p>
There is another kind of highlight that is calculated by a different means
called <em>specular highlighting</em>. It is specified using the keyword
<code><a href="r3_4.html#r3_4_6_3_4_2">specular</a></code> and operates in conjunction with another keyword
called <code><a href="r3_4.html#r3_4_6_3_4_2">roughness</a></code>. These two keywords work together in much the
same way as <code>phong</code> and <code>phong_size</code> to create
highlights that alter the apparent shininess of the surface. Let's try
using specular in our sphere.</p>
<pre>
  sphere {
     &lt;0,0,0&gt;, 1
     pigment { Gray50 }
     finish {
        ambient .2
        diffuse .6
        specular .75
        roughness .1
    }
  }
</pre>

<p>Looking at the result we see a broad, soft highlight similar to what we
had when we used <code>phong_size</code> of 25. Change <code>roughness</code>
to .001 and render again. Now we see a small, tight highlight similar to what
we had when we used <code>phong_size</code> of 150. Generally speaking, specular
is slightly more accurate and therefore slightly more realistic than phong but
you should try both methods when designing a texture. There are even times when
both phong and specular may be used on a finish.</p>

</div>
<a name="t2_3_5_3_4"></a>
<div class="content-level-h5" contains="Using Reflection, Metallic and Metallic" id="t2_3_5_3_4">
<h5>2.3.5.3.4 Using Reflection, Metallic and Metallic</h5>
<p>There is another surface parameter that goes hand in hand with highlights,
<code><a href="r3_4.html#r3_4_6_3_5">reflection</a></code>. Surfaces that are very shiny usually have a degree
of reflection to them. Let's take a look at an example.</p>
<pre>
  sphere {
     &lt;0,0,0&gt;, 1
     pigment { Gray50 }
     finish {
        ambient .2
        diffuse .6
        specular .75
        roughness .001
        reflection {
           .5
        }
     }
  }
</pre>

<p>We see that our sphere now reflects the green and white checkered plane
and the black background but the gray color of the sphere seems out of place.
This is another time when a lower diffuse value is needed. Generally, the
higher <code>reflection</code> is the lower <code>diffuse</code> should be.
We lower the diffuse value to 0.3 and the ambient value to 0.1 and render
again. That is much better. Let's make our sphere as shiny as a polished
gold ball bearing.</p>
<pre>
  sphere {
     &lt;0,0,0&gt;, 1
     pigment { BrightGold }
     finish {
        ambient .1
        diffuse .1
        specular 1
        roughness .001
        reflection {
           .75
        }
     }
   }
</pre>

<p>That is close but there is something wrong, the colour of the reflection and the highlight. To
make the surface appear more like metal the keyword <code><a href="r3_4.html#r3_4_6_3_4_3">metallic</a></code>
is used. We add it now to see the difference.</p>
<pre>
  sphere {
     &lt;0,0,0&gt;, 1
     pigment { BrightGold }
     finish {
        ambient .1
        diffuse .1
        specular 1
        roughness .001
        reflection {
          .75
          metallic
        }
     }
  }
</pre>
<p>The reflection has now more of the gold color than the color of its environment. Last detail, 
the highlight. We add another metallic statement, now to the finish and not inside the reflection 
block.</p> 
<pre>
  sphere {
     &lt;0,0,0&gt;, 1
     pigment { BrightGold }
     finish {
        ambient .1
        diffuse .1
        specular 1
        roughness .001
        metallic
        reflection {
          .75
          metallic
        }
     }
  }
</pre>
<p>We see that the highlight has taken on the color of the surface rather
than the light source. This gives the surface a more metallic appearance.</p>

</div>
<a name="t2_3_5_3_5"></a>
<div class="content-level-h5" contains="Using Iridescence" id="t2_3_5_3_5">
<h5>2.3.5.3.5 Using Iridescence</h5>
<p><em>Iridescence</em> is what we see on the surface of an oil slick when
the sun shines on it. The rainbow effect is created by something called
<em>thin-film interference</em> (read section <a href="r3_4.html#r3_4_6_3_7">Iridescence</a> for
details). For now let's just try using it. Iridescence is specified by
the <code><a href="r3_4.html#r3_4_6_3_7">irid</a></code> statement and three values: amount,
<code>thickness</code> and <code>turbulence</code>. The amount is the contribution
to the overall surface color. Usually 0.1 to 0.5 is sufficient here.
The thickness affects the <em>busyness</em> of the effect. Keep this between
0.25 and 1 for best results. The turbulence is a little different from
pigment or normal turbulence. We cannot set <code>octaves</code>, <code>lambda</code>
or <code>omega</code> but we can specify an amount which will affect the thickness
in a slightly different way from the thickness value. Values between 0.25 and 1
work best here too. Finally, iridescence will respond to the surface normal since
it depends on the angle of incidence of the light rays striking the surface.
With all of this in mind, let's add some iridescence to our glass sphere.</p>
<pre>
sphere {
     &lt;0,0,0&gt;, 1
     pigment { White filter 1 }
     finish {
        ambient .1
        diffuse .1
        reflection .2
        specular 1
        roughness .001
        irid {
          0.35
          thickness .5
          turbulence .5
        }
     }
     interior{
        ior 1.5
        fade_distance 5
        fade_power 1
        caustics 1
     }
}
</pre>

<p>We try to vary the values for amount, thickness and turbulence to see what
changes they make. We also try to add a <code>normal</code> block to see what
happens.</p>

</div>
<a name="t2_3_5_4"></a>
<div class="content-level-h4" contains="Working With Pigment Maps" id="t2_3_5_4">
<h4>2.3.5.4 Working With Pigment Maps</h4>
<p>Let's look at the pigment map. We must not confuse this with a color
map, as color maps can only take individual colors as entries in the map,
while pigment maps can use entire other pigment patterns. To get a feel for
these, let's begin by setting up a basic plane with a simple pigment map.
Now, in the following example, we are going to declare each of the pigments
we are going to use before we actually use them. This is not strictly
necessary (we could put an entire pigment description in each entry of the
map) but it just makes the whole thing more readable.</p>
<pre>
  // simple Black on White checkerboard... it's a classic
  #declare Pigment1 = pigment {
    checker color Black color White
    scale .1
  }
  // kind of a &quot;psychedelic rings&quot; effect
  #declare Pigment2 = pigment {
    wood
    color_map {
      [ 0.0 Red ]
      [ 0.3 Yellow ]
      [ 0.6 Green ]
      [ 1.0 Blue ]
    }
  }
  plane {
    -z, 0
    pigment {
      gradient x
      pigment_map {
        [ 0.0 Pigment1 ]
        [ 0.5 Pigment2 ]
        [ 1.0 Pigment1 ]
      }
    }
  }
</pre>

<p>Okay, what we have done here is very simple, and probably quite
recognizable if we have been working with color maps all along anyway. All we
have done is substituted a pigment map where a color map would normally go,
and as the entries in our map, we have referenced our declared pigments. When
we render this example, we see a pattern which fades back and forth between
the classic checkerboard, and those colorful rings. Because we fade from
Pigment1 to Pigment2 and then back again, we see a clear blending of the two
patterns at the transition points. We could just as easily get a sudden
transition by amending the map to read.</p>
<pre>
  pigment_map {
    [ 0.0 Pigment1 ]
    [ 0.5 Pigment1 ]
    [ 0.5 Pigment2 ]
    [ 1.0 Pigment2 ]
  }
</pre>

<p>Blending individual pigment patterns is just the beginning.</p>

</div>
<a name="t2_3_5_5"></a>
<div class="content-level-h4" contains="Working With Normal Maps" id="t2_3_5_5">
<h4>2.3.5.5 Working With Normal Maps</h4>
<p> For our next example, we replace the plane in the scene with this
one.</p>
<pre>
  plane {
    -z, 0
    pigment { White }
    normal {
      gradient x
      normal_map {
        [ 0.0 bumps 1 scale .1]
        [ 1.0 ripples 1 scale .1]
      }
    }
  }
</pre>

<p>First of all, we have chosen a solid white color to show off all bumping
to best effect. Secondly, we notice that our map blends smoothly from all
bumps at 0.0 to all ripples at 1.0, but because this is a default gradient,
it falls off abruptly back to bumps at the beginning of the next cycle. We
Render this and see just enough sharp transitions to clearly see where one
normal gives over to another, yet also an example of how two normal patterns
look while they are smoothly blending into one another.</p>
<p>
The syntax is the same as we would expect. We just changed the type of map,
moved it into the normal block and supplied appropriate bump types. It is
important to remember that as of POV-Ray 3, all patterns that work with
pigments work as normals as well (and vice versa, except for facets) so we could just
as easily have blended from wood to granite, or any other pattern we like. We
experiment a bit and get a feel for what the different patterns look
like.</p>
<p>
After seeing how interesting the various normals look blended, we might like
to see them completely blended all the way through rather than this business
of fading from one to the next. Well, that is possible too, but we would be
getting ahead of ourselves. That is called the <code>average</code>
function, and we will return to it a little bit further down the page.</p>

</div>
<a name="t2_3_5_6"></a>
<div class="content-level-h4" contains="Working With Texture Maps" id="t2_3_5_6">
<h4>2.3.5.6 Working With Texture Maps</h4>
<p>We know how to blend colors, pigment patterns, and normals, and we are
probably thinking what about finishes? What about whole textures? Both of
these can be kind of covered under one topic. While there is no finish map
per se, there are texture maps, and we can easily adapt these to serve as
finish maps, simply by putting the same pigment and/or normal in each of the
texture entries of the map. Here is an example. We eliminate the declared
pigments we used before and the previous plane, and add the following.</p>
<pre>
  #declare Texture1 = texture {
    pigment { Grey }
    finish { reflection 1 }
  }
  #declare Texture2 = texture {
    pigment { Grey }
    finish { reflection 0 }
  }
  cylinder {
    &lt;-2, 5, -2&gt;, &lt;-2, -5, -2&gt;, 1
    pigment { Blue }
  }
  plane {
    -z, 0
    rotate y * 30
    texture {
      gradient y
      texture_map {
        [ 0.0 Texture1 ]
        [ 0.4 Texture1 ]
        [ 0.6 Texture2 ]
        [ 1.0 Texture2 ]
      }
      scale 2
    }
  }
</pre>

<p>Now, what have we done here? The background plane alternates vertically
between two textures, identical except for their finishes. When we render
this, the cylinder has a reflection part of the way down the plane, and then
stops reflecting, then begins and then stops again, in a gradient pattern
down the surface of the plane. With a little adaptation, this could be used
with any pattern, and in any number of creative ways, whether we just wanted
to give various parts of an object different finishes, as we are doing here,
or whole different textures altogether.</p>
<p>
One might ask: if there is a texture map, why do we need pigment and normal
maps? Fair question. The answer: speed of calculation. If we use a texture
map, for every in-between point, POV-Ray must make multiple calculations for
each texture element, and then run a weighted average to produce the correct
value for that point. Using just a pigment map (or just a normal map)
decreases the overall number of calculations, and our texture renders a bit
faster in the bargain. As a rule of thumb: we use pigment or normal maps
where we can and only fall back on texture maps if we need the extra
flexibility.</p>

</div>
<a name="t2_3_5_7"></a>
<div class="content-level-h4" contains="Working With List Textures" id="t2_3_5_7">
<h4>2.3.5.7 Working With List Textures</h4>
<p> If we have followed the corresponding tutorials on simple pigments, we
know that there are three patterns called <em>color list</em> patterns,
because rather than using a color map, these simple but useful patterns take
a list of colors immediately following the pattern keyword. We are talking
about checker, hexagon, the brick pattern and the object pattern.</p>
<p>
Naturally they also work with whole pigments, normals, and entire textures,
just as the other patterns do above. The only difference is that we list
entries in the pattern (as we would do with individual colors) rather than
using a map of entries. Here is an example. We strike the plane and any
declared pigments we had left over in our last example, and add the following
to our basic file.</p>
<pre>
  #declare Pigment1 = pigment {
    hexagon
    color Yellow color Green color Grey
    scale .1
  }
  #declare Pigment2 = pigment {
    checker
    color Red color Blue
    scale .1
  }
  #declare Pigment3 = pigment {
    brick
    color White color Black
    rotate -90*x
    scale .1
  }
  box {
    -5, 5
    pigment {
      hexagon
      pigment {Pigment1}
      pigment {Pigment2}
      pigment {Pigment3}
      rotate 90*x
    }
  }
</pre>

<p>We begin by declaring an example of each of the color list patterns as
individual pigments. Then we use the hexagon pattern as a <em>pigment
list</em> pattern, simply feeding it a list of pigments rather than colors as
we did above. There are two rotate statements throughout this example,
because bricks are aligned along the z-direction, while hexagons align along
the y-direction, and we wanted everything to face toward the camera we
originally declared out in the -z-direction so we can really see the patterns
within patterns effect here.</p>
<p>
Of course color list patterns used to be only for pigments, but as of
POV-Ray 3, everything that worked for pigments can now also be adapted for
normals or entire textures. A couple of quick examples might look like</p>
<pre>
  normal {
    brick
    normal { granite .1 }
    normal { bumps 1 scale .1 }
  }
</pre>

<p>or...</p>
<pre>
  texture {
    checker
    texture { Gold_Metal }
    texture { Silver_Metal }
  }
</pre>

</div>
<a name="t2_3_5_8"></a>
<div class="content-level-h4" contains="What About Tiles?" id="t2_3_5_8">
<h4>2.3.5.8 What About Tiles?</h4>
<p>In earlier versions of POV-Ray, there was a texture pattern called
<code>tiles</code>. By simply using a checker texture pattern (as we just saw
above), we can achieve the same thing as tiles used to do, so it is now
obsolete. It is still supported by POV-Ray 3 for backwards compatibility with
old scene files, but now is a good time to get in the habit of using a
checker pattern instead.</p>

</div>
<a name="t2_3_5_9"></a>
<div class="content-level-h4" contains="Average Function" id="t2_3_5_9">
<h4>2.3.5.9 Average Function</h4>
<p>Now things get interesting. Above, we began to see how pigments and
normals can fade from one to the other when we used them in maps. But how
about if we want a smooth blend of patterns all the way through? That is
where a new feature called <code><a href="r3_4.html#r3_4_7_4_1">average</a></code> can come in very handy.
Average works with pigment, normal, and texture maps, although the syntax is
a little bit different, and when we are not expecting it, the change can be
confusing. Here is a simple example. We use our standard includes, camera and
light source from above, and enter the following object.</p>
<pre>
  plane { -z, 0
    pigment { White }
    normal {
      average
      normal_map {
        [1, gradient x ]
        [1, gradient y ]
      }
    }
  }
</pre>

<p>What we have done here is pretty self explanatory as soon as we render it.
We have combined a vertical with a horizontal gradient bump pattern, creating
crisscrossing gradients. Actually, the crisscrossing effect is a smooth blend
of gradient x with gradient y all the way across our plane. Now, what about
that syntax difference?</p>
<p>
We see how our normal map has changed from earlier examples. The floating
point value to the left-hand side of each map entry has a different meaning now.
It gives the weight factor per entry in the map. Try some different values for the 'gradient x'
entry and see how the normal changes.</p>
<p>The weight factor can be omitted, the result
then will be the same as if each entry had a weight factor of 1.</p>

</div>
<a name="t2_3_5_10"></a>
<div class="content-level-h4" contains="Working With Layered Textures" id="t2_3_5_10">
<h4>2.3.5.10 Working With Layered Textures</h4>
<p>With the multitudinous colors, patterns, and options for creating complex
textures in POV-Ray, we can easily become deeply engrossed in mixing and
tweaking just the right textures to apply to our latest creations. But as we
go, sooner or later there is going to come that <em>special</em> texture.
That texture that is sort of like wood, only varnished, and with a kind of
spotty yellow streaking, and some vertical gray flecks, that looks like
someone started painting over it all, and then stopped, leaving part of the
wood visible through the paint.</p>
<p>
Only... now what? How do we get all that into one texture? No pattern can do
that many things. Before we panic and say image map there is at least one
more option: <em>layered textures</em>.</p>
<p>
With layered textures, we only need to specify a series of textures, one
after the other, all associated with the same object. Each texture we list
will be applied one on top of the other, from bottom to top in the order they
appear.</p>
<p>
It is very important to note that we must have some degree of transparency
(filter or transmit) in the pigments of our upper textures, or the ones below
will get lost underneath. We will not receive a warning or an error -
technically it is legal to do this: it just does not make sense. It is
like spending hours sketching an elaborate image on a bare wall, then
slapping a solid white coat of latex paint over it.</p>
<p>
Let's design a very simple object with a layered texture, and look at
how it works. We create a file called <code>LAYTEX.POV</code> and add the
following lines.</p>
<pre>
  #include &quot;colors.inc&quot;
  #include &quot;textures.inc&quot;
  camera {
    location &lt;0, 5, -30&gt;
    look_at &lt;0, 0, 0&gt;
  }
  light_source { &lt;-20, 30, -50&gt; color White }
  plane { y, 0 pigment { checker color Green color Yellow  } }
  background { rgb &lt;.7, .7, 1&gt; }
  box {
    &lt;-10, 0, -10&gt;, &lt;10, 10, 10&gt;
    texture {
      Silver_Metal // a metal object ...
      normal {     // ... which has suffered a beating
        dents 2
        scale 1.5
      }
    } // (end of base texture)
    texture { // ... has some flecks of rust ...
      pigment {
        granite
        color_map {
          [0.0 rgb &lt;.2, 0, 0&gt; ]
          [0.2 color Brown ]
          [0.2 rgbt &lt;1, 1, 1, 1&gt; ]
          [1.0 rgbt &lt;1, 1, 1, 1&gt; ]
        }
        frequency 16
      }
    } // (end rust fleck texture)
    texture { // ... and some sooty black marks
      pigment {
        bozo
        color_map {
          [0.0 color Black ]
          [0.2 color rgbt &lt;0, 0, 0, .5&gt; ]
          [0.4 color rgbt &lt;.5, .5, .5, .5&gt; ]
          [0.5 color rgbt &lt;1, 1, 1, 1&gt; ]
          [1.0 color rgbt &lt;1, 1, 1, 1&gt; ]
        }
        scale 3
      }
    } // (end of sooty mark texture)
  } // (end of box declaration)
</pre>

<p>Whew. This gets complicated, so to make it easier to read, we have
included comments showing what we are doing and where various parts of the
declaration end (so we do not get lost in all those closing brackets!). To
begin, we created a simple box over the classic checkerboard floor, and give
the background sky a pale blue color. Now for the fun part...</p>
<p>
To begin with we made the box use the <code>Silver_Metal</code> texture as
declared in textures.inc (for bonus points, look up <code>textures.inc</code>
and see how this standard texture was originally created sometime). To give
it the start of its abused state, we added the dents normal pattern, which
creates the illusion of some denting in the surface as if our mysterious
metal box had been knocked around quite a bit.</p>
<p>
The flecks of rust are nothing but a fine grain granite pattern fading from
dark red to brown which then abruptly drops to fully transparent for the
majority of the color map. True, we could probably come up with a more
realistic pattern of rust using pigment maps to cluster rusty spots, but
pigment maps are a subject for another tutorial section, so let's skip
that just now.</p>
<p>
Lastly, we have added a third texture to the pot. The randomly shifting
<code>bozo</code> texture gradually fades from blackened centers to
semi-transparent medium gray, and then ultimately to fully transparent for
the latter half of its color map. This gives us a look of sooty burn marks
further marring the surface of the metal box. The final result leaves our
mysterious metal box looking truly abused, using multiple texture patterns,
one on top of the other, to produce an effect that no single pattern could
generate!</p>

</div>
<a name="t2_3_5_10_1"></a>
<div class="content-level-h5" contains="Declaring Layered Textures" id="t2_3_5_10_1">
<h5>2.3.5.10.1 Declaring Layered Textures</h5>
<p>In the event we want to reuse a layered texture on several objects in our
scene, it is perfectly legal to declare a layered texture. We will not
repeat the whole texture from above, but the general format would be
something like this:</p>
<pre>
  #declare Abused_Metal =
    texture { /* insert your base texture here... */ }
    texture { /* and your rust flecks here... */ }
    texture { /* and of course, your sooty burn marks here */ }
</pre>

<p>POV-Ray has no problem spotting where the declaration ends, because the
textures follow one after the other with no objects or directives in between.
The layered texture to be declared will be assumed to continue until it finds
something other than another texture, so any number of layers can be added in
to a declaration in this fashion.</p>
<p>
One final word about layered textures: whatever layered texture we create,
whether declared or not, we must not leave off the texture wrapper. In
conventional single textures a common shorthand is to have just a pigment, or
just a pigment and finish, or just a normal, or whatever, and leave them
outside of a texture statement. This shorthand does not extend to layered
textures. As far as POV-Ray is concerned we can layer entire textures, but
not individual pieces of textures. For example</p>
<pre>
  #declare Bad_Texture =
    texture { /* insert your base texture here... */ }
    pigment { Red filter .5 }
    normal { bumps 1 }
</pre>

<p>will not work. The pigment and the normal are just floating there without
being part of any particular texture. Inside an object, with just a single
texture, we can do this sort of thing, but with layered textures, we would
just generate an error whether inside the object or in a declaration.</p>

</div>
<a name="t2_3_5_10_2"></a>
<div class="content-level-h5" contains="Another Layered Textures Example" id="t2_3_5_10_2">
<h5>2.3.5.10.2 Another Layered Textures Example</h5>
<p>To further explain how layered textures work another example is described
in detail. A tablecloth is created to be used in a picnic scene. Since a
simple red and white checkered cloth looks entirely too new, too flat, and
too much like a tiled floor, layered textures are used to stain the
cloth.</p>
<p>
We are going to create a scene containing four boxes. The first box has
that plain red and white texture we started with in our picnic scene, the
second adds a layer meant to realistically fade the cloth, the third adds
some wine stains, and the final box adds a few wrinkles (not another layer,
but we must note when and where adding changes to the surface normal have an
effect in layered textures).</p>
<p>
We start by placing a camera, some lights, and the first box. At this stage,
the texture is plain tiling, not layered. See file <code>layered1.pov</code>.</p>
<pre>
  #include &quot;colors.inc&quot;
  camera {
    location &lt;0, 0, -6&gt;
    look_at &lt;0, 0, 0&gt;
  }
  light_source { &lt;-20, 30, -100&gt; color White }
  light_source { &lt;10, 30, -10&gt; color White }
  light_source { &lt;0, 30, 10&gt; color White }
  #declare PLAIN_TEXTURE =
    // red/white check
    texture {
      pigment {
        checker
        color rgb&lt;1.000, 0.000, 0.000&gt;
        color rgb&lt;1.000, 1.000, 1.000&gt;
        scale &lt;0.2500, 0.2500, 0.2500&gt;
      }
    }
  // plain red/white check box
  box {
    &lt;-1, -1, -1&gt;, &lt;1, 1, 1&gt;
    texture {
      PLAIN_TEXTURE
    }
    translate  &lt;-1.5, 1.2, 0&gt;
  }
</pre>

<p>We render this scene. It is not particularly interesting, is it?
That is why we will use some layered textures to make it more
interesting.</p>
<p>
First, we add a layer of two different, partially transparent grays. We tile
them as we had tiled the red and white colors, but we add some turbulence to
make the fading more realistic. We add the following box to the previous scene
and re-render (see file <code>layered2.pov</code>).</p>
<pre>
  #declare FADED_TEXTURE =
    // red/white check texture
    texture {
      pigment {
        checker
        color rgb&lt;0.920, 0.000, 0.000&gt;
        color rgb&lt;1.000, 1.000, 1.000&gt;
        scale &lt;0.2500, 0.2500, 0.2500&gt;
      }
    }
    // greys to fade red/white
    texture {
      pigment {
        checker
        color rgbf&lt;0.632, 0.612, 0.688, 0.698&gt;
        color rgbf&lt;0.420, 0.459, 0.520, 0.953&gt;
        turbulence 0.500
        scale &lt;0.2500, 0.2500, 0.2500&gt;
      }
    }
  // faded red/white check box
  box {
    &lt;-1, -1, -1&gt;, &lt;1, 1, 1&gt;
    texture {
      FADED_TEXTURE
    }
    translate  &lt;1.5, 1.2, 0&gt;
  }
</pre>

<p>Even though it is a subtle difference, the red and white checks no longer
look quite so new.</p>
<p>
Since there is a bottle of wine in the picnic scene, we thought it might be
a nice touch to add a stain or two. While this effect can almost be achieved
by placing a flattened blob on the cloth, what we really end up with is a
spill effect, not a stain. Thus it is time to add another layer.</p>
<p>
Again, we add another box to the scene we already have scripted and
re-render (see file <code>layered3.pov</code>).</p>
<pre>
  #declare STAINED_TEXTURE =
    // red/white check
    texture {
      pigment {
        checker
        color rgb&lt;0.920, 0.000, 0.000&gt;
        color rgb&lt;1.000, 1.000, 1.000&gt;
        scale &lt;0.2500, 0.2500, 0.2500&gt;
      }
    }
    // greys to fade check
    texture {
      pigment {
        checker
        color rgbf&lt;0.634, 0.612, 0.688, 0.698&gt;
        color rgbf&lt;0.421, 0.463, 0.518, 0.953&gt;
        turbulence 0.500
        scale &lt;0.2500, 0.2500, 0.2500&gt;
      }
    }
    // wine stain
    texture {
      pigment {
        spotted
        color_map {
          [ 0.000  color rgb&lt;0.483, 0.165, 0.165&gt; ]
          [ 0.329  color rgbf&lt;1.000, 1.000, 1.000, 1.000&gt; ]
          [ 0.734  color rgbf&lt;1.000, 1.000, 1.000, 1.000&gt; ]
          [ 1.000  color rgb&lt;0.483, 0.165, 0.165&gt; ]
        }
        turbulence 0.500
        frequency 1.500
      }
    }
  // stained box
  box {
    &lt;-1, -1, -1&gt;, &lt;1, 1, 1&gt;
    texture {
      STAINED_TEXTURE
    }
    translate  &lt;-1.5, -1.2, 0&gt;
  }
</pre>

<p>Now there is a tablecloth texture with personality.</p>
<p>
Another touch we want to add to the cloth are some wrinkles as if the cloth
had been rumpled. This is not another texture layer, but when working with
layered textures, we must keep in mind that changes to the surface normal
must be included in the uppermost layer of the texture. Changes to lower
layers have no effect on the final product (no matter how transparent the
upper layers are).</p>
<p>
We add this final box to the script and re-render (see file <code>layered4.pov</code>)</p>
<pre>
  #declare WRINKLED_TEXTURE =
    // red and white check
    texture {
      pigment {
        checker
        color rgb&lt;0.920, 0.000, 0.000&gt;
        color rgb&lt;1.000, 1.000, 1.000&gt;
        scale &lt;0.2500, 0.2500, 0.2500&gt;
      }
    }
    // greys to &quot;fade&quot; checks
    texture {
      pigment {
        checker
        color rgbf&lt;0.632, 0.612, 0.688, 0.698&gt;
        color rgbf&lt;0.420, 0.459, 0.520, 0.953&gt;
        turbulence 0.500
        scale &lt;0.2500, 0.2500, 0.2500&gt;
      }
    }
    // the wine stains
    texture {
      pigment {
        spotted
        color_map {
          [ 0.000  color rgb&lt;0.483, 0.165, 0.165&gt; ]
          [ 0.329  color rgbf&lt;1.000, 1.000, 1.000, 1.000&gt; ]
          [ 0.734  color rgbf&lt;1.000, 1.000, 1.000, 1.000&gt; ]
          [ 1.000  color rgb&lt;0.483, 0.165, 0.165&gt; ]
        }
        turbulence 0.500
        frequency 1.500
      }
      normal {
        wrinkles 5.0000
      }
    }
  // wrinkled box
  box {
    &lt;-1, -1, -1&gt;, &lt;1, 1, 1&gt;
    texture {
      WRINKLED_TEXTURE
    }
    translate  &lt;1.5, -1.2, 0&gt;
  }
</pre>

<p>Well, this may not be the tablecloth we want at any picnic we are
attending, but if we compare the final box to the first, we see just how much
depth, dimension, and personality is possible just by the use of creative
texturing.</p>
<p>
One final note: the comments concerning the surface normal do not hold true
for finishes. If a <em>lower</em> layer contains a specular finish and an
<em>upper</em> layer does not, any place where the upper layer is
transparent, the specular will show through.</p>

</div>
<a name="t2_3_5_11"></a>
<div class="content-level-h4" contains="When All Else Fails: Material Maps" id="t2_3_5_11">
<h4>2.3.5.11 When All Else Fails: Material Maps</h4>
<p>We have some pretty powerful texturing tools at our disposal, but what if
we want a more free form arrangement of complex textures? Well, just as image
maps do for pigments, and bump maps do for normals, whole textures can be
mapped using a material map, should the need arise.</p>
<p>
Just as with image maps and bump maps, we need a source image in bitmapped
format which will be called by POV-Ray to serve as the map of where the
individual textures will go, but this time, we need to specify what texture
will be associated with which palette index. To make such an image, we can
use a paint program which allows us to select colors by their palette index
number (the actual color is irrelevant, since it is only a map to tell
POV-Ray what texture will go at that location). Now, if we have the complete
package that comes with POV-Ray, we have in our include files an image called
<code>povmap.gif</code> which is a bitmapped image that uses only the first
four palette indices to create a bordered square with the words
&quot;Persistence of Vision&quot; in it. This will do just fine as a sample
map for the following example. Using our same include files, the camera and
light source, we enter the following object.</p>
<pre>
  plane {
    -z, 0
    texture {
      material_map {
        gif &quot;povmap.gif&quot;
        interpolate 2
        once
        texture { PinkAlabaster }          // the inner border
        texture { pigment { DMFDarkOak } } // outer border
        texture { Gold_Metal }             // lettering
        texture { Chrome_Metal }           // the window panel
      }
      translate &lt;-0.5, -0.5, 0&gt;
      scale 5
    }
  }
</pre>

<p>The position of the light source and the lack of foreground objects to be
reflected do not show these textures off to their best advantage. But at
least we can see how the process works. The textures have simply been placed
according to the location of pixels of a particular palette index. By using
the <code><a href="r3_4.html#r3_4_7_7_1">once</a></code> keyword (to keep it from tiling), and translating and scaling our map to match the camera we have been using, we get to see the
whole thing laid out for us.</p>
<p>
Of course, that is just with palette mapped image formats, such as GIF and
certain flavors of PNG. Material maps can also use non-paletted formats, such
as the TGA files that POV-Ray itself outputs. That leads to an interesting
consequence: We can use POV-Ray to produce source maps for POV-Ray! Before we
wrap up with some of the limitations of special textures, let's do one
more thing with material maps, to show how POV-Ray can make its own source
maps.</p>
<p>
To begin with, if using a non-paletted image, POV-Ray looks at the 8 bit
red component of the pixel's color (which will be a value from 0 to 255)
to determine which texture from the list to use. So to create a source map,
we need to control very precisely what the red value of a given pixel will
be. We can do this by</p>
<ol>
<li>Using an rgb statement to choose our color such as rgb &lt;N/255,0,0&gt;,
where &quot;N&quot; is the red value we want to assign that pigment, and then...</li>
<li>Use no light sources and apply a finish of <code>finish { ambient 1 }</code>
to all objects, to ensure that highlighting and shadowing will not interfere.</li>
</ol>
<p>Confused? Alright, here is an example, which will generate a map very much
like <code>povmap.gif</code> which we used earlier, except in TGA file
format. We notice that we have given the pigments blue and green components
too. POV-Ray will ignore that in our final map, so this is really for us
humans, whose unaided eyes cannot tell the difference between red variances
of 0 to 4/255ths. Without those blue and green variances, our map would look
to our eyes like a solid black screen. That may be a great way to send secret
messages using POV-Ray (plug it into a material map to decode) but it is no
use if we want to see what our source map looks like to make sure we have
what we expected to.</p>
<p>
We create the following code, name it <code>povmap.pov</code>, then render
it. This will create an output file called <code>povmap.png</code></p>
<pre>
  camera {
    orthographic
    up &lt;0, 5, 0&gt;
    right &lt;5, 0, 0&gt;
    location &lt;0, 0, -25&gt;
    look_at &lt;0, 0, 0&gt;
  }
  plane {
    -z, 0
    pigment { rgb &lt;1/255, 0, 0.5&gt; }
    finish { ambient 1 }
  }
  box {
    &lt;-2.3, -1.8, -0.2&gt;, &lt;2.3, 1.8, -0.2&gt;
    pigment { rgb &lt;0/255, 0, 1&gt; }
    finish { ambient 1 }
  }
  box {
    &lt;-1.95, -1.3, -0.4&gt;, &lt;1.95, 1.3, -0.3&gt;
    pigment { rgb &lt;2/255, 0.5, 0.5&gt; }
    finish { ambient 1 }
  }
  text {
    ttf &quot;crystal.ttf&quot;, &quot;The vision&quot;, 0.1, 0
    scale &lt;0.7, 1, 1&gt;
    translate &lt;-1.8, 0.25, -0.5&gt;
    pigment { rgb &lt;3/255, 1, 1&gt; }
    finish { ambient 1 }
  }
  text {
    ttf &quot;crystal.ttf&quot;, &quot;Persists!&quot;, 0.1, 0
    scale &lt;0.7, 1, 1&gt;
    translate &lt;-1.5, -1, -0.5&gt;
    pigment { rgb &lt;3/255, 1, 1&gt; }
    finish { ambient 1 }
  }
</pre>

<p>All we have to do is modify our last material map example by changing the
material map from GIF to TGA and modifying the filename. When we render using
the new map, the result is extremely similar to the palette mapped GIF we
used before, except that we did not have to use an external paint program
to generate our source: POV-Ray did it all!</p>

</div>


<a name="t2_3_5_12"></a>
<div class="content-level-h4" contains="Limitations Of Special Textures" id="t2_3_5_12">
<h4>2.3.5.12 Limitations Of Special Textures</h4>
<p>There are a couple limitations to all of the special textures we have seen
(from textures, pigment and normal maps through material maps). First, if we
have used the default directive to set the default texture for all items in
our scene, it will not accept any of the special textures discussed here.
This is really quite minor, since we can always declare such a texture and
apply it individually to all objects. It does not actually prevent us from
doing anything we could not otherwise do.</p>
<p>
The other is more limiting, but as we will shortly see, can be worked around
quite easily. If we have worked with layered textures, we have already seen
how we can pile multiple texture patterns on top of one another (as long as
one texture has transparency in it). This very useful technique has a problem
incorporating the special textures we have just seen as a layer. But there is
an answer!</p>
<p>
For example, say we have a layered texture called <code>
Speckled_Metal</code>, which produces a silver metallic surface, and then
puts tiny specks of rust all over it. Then we decide, for a really rusty
look, we want to create patches of concentrated rust, randomly over the
surface. The obvious approach is to create a special texture pattern, with
transparency to use as the top layer. But of course, as we have seen, we
would not be able to use that texture pattern as a layer. We would just
generate an error message. The solution is to turn the problem inside out,
and make our layered texture part of the texture pattern instead, like
this</p>

<pre>
  // This part declares a pigment for use
  // in the rust patch texture pattern
  #declare Rusty = pigment {
    granite
    color_map {
      [ 0 rgb &lt;0.2, 0, 0&gt; ]
      [ 1 Brown ]
    }
    frequency 20
  }
  // And this part applies it
  // Notice that our original layered texture
  // &quot;Speckled_Metal&quot; is now part of the map
  #declare Rust_Patches = texture {
    bozo
    texture_map {
      [ 0.0  pigment {Rusty} ]
      [ 0.75 Speckled_Metal ]
      [ 1.0  Speckled_Metal ]
    }
  }
</pre>

<p>And the ultimate effect is the same as if we had layered the rust patches
on to the speckled metal anyway.</p>
<p>
With the full array of patterns, pigments, normals, finishes, layered and
special textures, there is now practically nothing we cannot create in the
way of amazing textures. An almost infinite number of new possibilities are
just waiting to be created!</p>

</div>
<a name="t2_3_6"></a>
<div class="content-level-h3" contains="Using Atmospheric Effects" id="t2_3_6">
<h3>2.3.6 Using Atmospheric Effects</h3>
<p>POV-Ray offers a variety of atmospheric effects, i. e. features that
affect the background of the scene or the air by which everything is
surrounded.</p>
<p>
It is easy to assign a simple color or a complex color pattern to a virtual
sky sphere. You can create anything from a cloud free, blue summer sky to a
stormy, heavy clouded sky. Even starfields can easily be created.</p>
<p>
You can use different kinds of fog to create foggy scenes. Multiple fog
layers of different colors can add an eerie touch to your scene.</p>
<p>
A much more realistic effect can be created by using an atmosphere, a
constant fog that interacts with the light coming from light sources. Beams
of light become visible and objects will cast shadows into the fog.</p>
<p>
Last but not least you can add a rainbow to your scene.</p>

</div>
<a name="t2_3_6_1"></a>
<div class="content-level-h4" contains="The Background" id="t2_3_6_1">
<h4>2.3.6.1 The Background</h4>
<p>The <code><a href="r3_4.html#r3_4_3_2">background</a></code> feature is used to assign a color to all rays
that do not hit any object. This is done in the following way.</p>
<pre>
  camera {
    location &lt;0, 0, -10&gt;
    look_at &lt;0, 0, 0&gt;
  }
  background { color rgb &lt;0.2, 0.2, 0.3&gt; }
  sphere {
    0, 1
    pigment { color rgb &lt;0.8, 0.5, 0.2&gt; }
  }
</pre>

<p>The background color will be visible if a sky sphere is used and if some
translucency remains after all sky sphere pigment layers are processed.</p>

</div>
<a name="t2_3_6_2"></a>
<div class="content-level-h4" contains="The Sky Sphere" id="t2_3_6_2">
<h4>2.3.6.2 The Sky Sphere</h4>
<p>The <code><a href="r3_4.html#r3_4_3_4">sky_sphere</a></code> can be used to easily create a cloud covered
sky, a nightly star sky or whatever sky you have in mind.</p>
<p>
In the following examples we will start with a very simple sky sphere that
will get more and more complex as we add new features to it.</p>

</div>
<a name="t2_3_6_2_1"></a>
<div class="content-level-h5" contains="Creating a Sky with a Color Gradient" id="t2_3_6_2_1">
<h5>2.3.6.2.1 Creating a Sky with a Color Gradient</h5>
<p>Beside the single color sky sphere that is covered with the background
feature the simplest sky sphere is a color gradient. You may have noticed
that the color of the sky varies with the angle to the earth's surface
normal. If you look straight up the sky normally has a much deeper blue than
it has at the horizon.</p>
<p>
We want to model this effect using the sky sphere as shown in the scene <code>skysph1.pov</code>
below.</p>
<pre>
  #include &quot;colors.inc&quot;
  camera {
    location &lt;0, 1, -4&gt;
    look_at &lt;0, 2, 0&gt;
    angle 80
  }
  light_source { &lt;10, 10, -10&gt; White }
  sphere {
    2*y, 1
    pigment { color rgb &lt;1, 1, 1&gt; }
    finish { ambient 0.2 diffuse 0 reflection 0.6 }
  }
  sky_sphere {
    pigment {
      gradient y
      color_map {
        [0 color Red]
        [1 color Blue]
      }
      scale 2
      translate -1
    }
  }
</pre>

<p>The interesting part is the sky sphere statement. It contains a pigment
that describes the look of the sky sphere. We want to create a color gradient
along the viewing angle measured against the earth's surface normal.
Since the ray direction vector is used to calculate the pigment colors we
have to use the y-gradient.</p>
<p>
The scale and translate transformation are used to map the points derived
from the direction vector to the right range. Without those transformations
the pattern would be repeated twice on the sky sphere. The <code><a href="r3_3.html#r3_3_1_12_2">scale</a></code>
statement is used to avoid the repetition and the <code><a href="r3_3.html#r3_3_1_12_1">translate</a> -1</code>
statement moves the color at index zero to the bottom of the sky sphere
(that is the point of the sky sphere you will see if you look straight
down).</p>
<p>
After this transformation the color entry at position 0 will be at the
bottom of the sky sphere, i. e. below us, and the color at position 1 will be
at the top, i. e. above us.</p>
<p>
The colors for all other positions are interpolated between those two colors
as you can see in the resulting image.</p>

<table class="centered" width="340px" cellpadding="0" cellspacing="10">
<tr>
  <td>
    <img class="center" width="320px" src="images/9/93/TutImgSkyspher.png">
  </td>
</tr>
<tr>
  <td>
    <p class="caption">A simple gradient sky sphere.</p>
  </td>
</tr>
</table>

<p>If you want to start one of the colors at a specific angle you will
first have to convert the angle to a color map index. This is done by using
the formula <code>color_map_index = (1 - cos(angle)) / 2</code> where the
angle is measured against the negated earth's surface normal. This is the
surface normal pointing towards the center of the earth. An angle of 0
degrees describes the point below us while an angle of 180 degrees represents
the zenith.</p>
<p>
In POV-Ray you first have to convert the degree value to <code><a href="r3_3.html#r3_3_1_5_4">radians</a></code>
as it is shown in the following example.</p>
<pre>
  sky_sphere {
    pigment {
      gradient y
      color_map {
        [(1-cos(radians( 30)))/2 color Red]
        [(1-cos(radians(120)))/2 color Blue]
      }
      scale 2
      translate -1
    }
  }
</pre>

<p>This scene uses a color gradient that starts with a red color at 30
degrees and blends into the blue color at 120 degrees. Below 30 degrees
everything is red while above 120 degrees all is blue.</p>

</div>
<a name="t2_3_6_2_2"></a>
<div class="content-level-h5" contains="Adding the Sun" id="t2_3_6_2_2">
<h5>2.3.6.2.2 Adding the Sun</h5>
<p>In the following example we will create a sky with a red sun surrounded by
a red color halo that blends into the dark blue night sky. We will do this
using only the sky sphere feature.</p>
<p>
The sky sphere we use is shown below. A ground plane is also added for
greater realism (<code>skysph2.pov</code>).</p>
<pre>
  sky_sphere {
    pigment {
      gradient y
      color_map {
        [0.000 0.002 color rgb &lt;1.0, 0.2, 0.0&gt;
                     color rgb &lt;1.0, 0.2, 0.0&gt;]
        [0.002 0.200 color rgb &lt;0.8, 0.1, 0.0&gt;
                     color rgb &lt;0.2, 0.2, 0.3&gt;]
      }
      scale 2
      translate -1
    }
    rotate -135*x
  }
  plane {
    y, 0
    pigment { color Green }
    finish { ambient .3 diffuse .7 }
  }
</pre>

<p>The gradient pattern and the transformation inside the pigment are the
same as in the example in the previous section.</p>
<p>
The color map consists of three colors. A bright, slightly yellowish red
that is used for the sun, a darker red for the halo and a dark blue for the
night sky. The sun's color covers only a very small portion of the sky
sphere because we do not want the sun to become too big. The color is used
at the color map values 0.000 and 0.002 to get a sharp contrast at value
0.002 (we do not want the sun to blend into the sky). The darker red color
used for the halo blends into the dark blue sky color from value 0.002 to
0.200. All values above 0.200 will reveal the dark blue sky.</p>
<p>
The <code>rotate -135*x</code> statement is used to rotate the sun and the
complete sky sphere to its final position. Without this rotation the sun
would be at 0 degrees, i.e. right below us.</p>

<table class="centered" width="340px" cellpadding="0" cellspacing="10">
<tr>
  <td>
    <img class="center" width="320px" src="images/0/0a/TutImgRedsun.png">
  </td>
</tr>
<tr>
  <td>
    <p class="caption">A red sun descends into the night.</p>
  </td>
</tr>
</table>

<p>Looking at the resulting image you will see what impressive effects you
can achieve with the sky sphere.</p>
</div>
<a name="t2_3_6_2_3"></a>
<div class="content-level-h5" contains="Adding Some Clouds" id="t2_3_6_2_3">
<h5>2.3.6.2.3 Adding Some Clouds</h5>
<p>To further improve our image we want to add some clouds by adding a second
pigment. This new pigment uses the bozo pattern to create some nice clouds.
Since it lays on top of the other pigment it needs some transparent colors in
the color map (look at entries 0.5 to 1.0).</p>
<pre>
  sky_sphere {
    pigment {
      gradient y
      color_map {
        [0.000 0.002 color rgb &lt;1.0, 0.2, 0.0&gt;
                     color rgb &lt;1.0, 0.2, 0.0&gt;]
        [0.002 0.200 color rgb &lt;0.8, 0.1, 0.0&gt;
                     color rgb &lt;0.2, 0.2, 0.3&gt;]
      }
      scale 2
      translate -1
    }
    pigment {
      bozo
      turbulence 0.65
      octaves 6
      omega 0.7
      lambda 2
      color_map {
          [0.0 0.1 color rgb &lt;0.85, 0.85, 0.85&gt;
                   color rgb &lt;0.75, 0.75, 0.75&gt;]
          [0.1 0.5 color rgb &lt;0.75, 0.75, 0.75&gt;
                   color rgbt &lt;1, 1, 1, 1&gt;]
          [0.5 1.0 color rgbt &lt;1, 1, 1, 1&gt;
                   color rgbt &lt;1, 1, 1, 1&gt;]
      }
      scale &lt;0.2, 0.5, 0.2&gt;
    }
    rotate -135*x
  }
</pre>

<table class="centered" width="340px" cellpadding="0" cellspacing="10">
<tr>
  <td>
    <img class="center" width="320px" src="images/e/ef/TutImgCloudsky.png">
  </td>
</tr>
<tr>
  <td>
    <p class="caption">A cloudy sky with a setting sun.</p>
  </td>
</tr>
</table>

<p>The sky sphere has one drawback as you might notice when looking at the
final image (<code>skysph3.pov</code>). The sun does not emit any light
and the clouds will not cast any shadows. If you want to have clouds that
cast shadows you will have to use a real, large sphere with an appropriate
texture and a light source somewhere outside the sphere.</p>
</div>
<a name="t2_3_6_3"></a>
<div class="content-level-h4" contains="The Fog" id="t2_3_6_3">
<h4>2.3.6.3 The Fog</h4>
<p>You can use the <code><a href="r3_4.html#r3_4_3_3">fog</a></code> feature to add fog of two different types
to your scene: constant fog and ground fog. The constant fog has a constant
density everywhere while the ground fog's density decreases as you move
upwards.</p>
<p>
The usage of both fog types will be described in the next sections in
detail.</p>

</div>
<a name="t2_3_6_3_1"></a>
<div class="content-level-h5" contains="A Constant Fog" id="t2_3_6_3_1">
<h5>2.3.6.3.1 A Constant Fog</h5>
<p>The simplest fog type is the constant fog that has a constant density in
all locations. It is specified by a <code>distance</code> keyword which
actually describes the fog's density and a fog <code><a href="r3_4.html#r3_4_3_3">color</a></code>.</p>
<p>
The distance value determines the distance at which 36.8% of the background
is still visible (for a more detailed explanation of how the fog is
calculated read the reference section <a href="r3_4.html#r3_4_3_3">Fog</a>).</p>
<p>
The fog color can be used to create anything from a pure white to a red,
blood-colored fog. You can also use a black fog to simulate the effect of a
limited range of vision.</p>
<p>
The following example will show you how to add fog to a simple scene
(<code>fog1.pov</code>).</p>
<pre>
  #include &quot;colors.inc&quot;
  camera {
    location  &lt;0, 20, -100&gt;
  }
  background { color SkyBlue }
  plane {
    y, -10
    pigment {
      checker color Yellow color Green
      scale 20
    }
  }
  sphere {
    &lt;0, 25, 0&gt;, 40
    pigment { Red }
    finish { phong 1.0 phong_size 20 }
  }
  sphere {
    &lt;-100, 150, 200&gt;,  20
    pigment { Green }
    finish { phong 1.0 phong_size 20 }
  }
  sphere {
    &lt;100, 25, 100&gt;, 30
    pigment { Blue }
    finish { phong 1.0 phong_size 20 }
  }
  light_source { &lt;100, 120, 40&gt; color White }
  fog {
    distance 150
    color rgb&lt;0.3, 0.5, 0.2&gt;
  }
</pre>

<table class="centered" width="340px" cellpadding="0" cellspacing="10">
<tr>
  <td>
    <img class="center" width="320px" src="images/6/61/TutImgSmplfog.png">
  </td>
</tr>
<tr>
  <td>
    <p class="caption">A foggy scene.</p>
  </td>
</tr>
</table>

<p>According to their distance the spheres in this scene more or less vanish
in the greenish fog we used, as does the checkerboard plane.</p>

</div>
<a name="t2_3_6_3_2"></a>
<div class="content-level-h5" contains="Setting a Minimum Translucency" id="t2_3_6_3_2">
<h5>2.3.6.3.2 Setting a Minimum Translucency</h5>
<p>If you want to make sure that the background does not completely vanish in
the fog you can set the transmittance channel of the fog's color to the
amount of background you always want to be visible.</p>
<p>
Using as transmittance value of 0.2 as in</p>
<pre>
  fog {
    distance 150
    color rgbt&lt;0.3, 0.5, 0.2, 0.2&gt;
  }
</pre>

<p>the fog's translucency never drops below 20% as you can see in the
resulting image (<code>fog2.pov</code>).</p>

<table class="centered" width="340px" cellpadding="0" cellspacing="10">
<tr>
  <td>
    <img class="center" width="320px" src="images/9/9a/TutImgBgvisfog.png">
  </td>
</tr>
<tr>
  <td>
    <p class="caption">Fog with translucency threshold added.</p>
  </td>
</tr>
</table>

</div>
<a name="t2_3_6_3_3"></a>
<div class="content-level-h5" contains="Creating a Filtering Fog" id="t2_3_6_3_3">
<h5>2.3.6.3.3 Creating a Filtering Fog</h5>
<p>The greenish fog we have used so far does not filter the light passing
through it. All it does is to diminish the light's intensity. We can
change this by using a non-zero filter channel in the fog's color
(<code>fog3.pov</code>).</p>
<pre>
  fog {
    distance 150
    color rgbf&lt;0.3, 0.5, 0.2, 1.0&gt;
  }
</pre>

<p>The filter value determines the amount of light that is filtered by the
fog. In our example 100% of the light passing through the fog will be
filtered by the fog. If we had used a value of 0.7 only 70% of the light
would have been filtered. The remaining 30% would have passed unfiltered.</p>

<table class="centered" width="340px" cellpadding="0" cellspacing="10">
<tr>
  <td>
    <img class="center" width="320px" src="images/8/85/TutImgFiltfog.png">
  </td>
</tr>
<tr>
  <td>
    <p class="caption">A filtering fog.</p>
  </td>
</tr>
</table>

<p>You will notice that the intensity of the objects in the fog is not only
diminished due to the fog's color but that the colors are actually
influenced by the fog. The red and especially the blue sphere got a green
hue.</p>
</div>
<a name="t2_3_6_3_4"></a>
<div class="content-level-h5" contains="Adding Some Turbulence to the Fog" id="t2_3_6_3_4">
<h5>2.3.6.3.4 Adding Some Turbulence to the Fog</h5>
<p>In order to make our somewhat boring fog a little bit more interesting we
can add some turbulence, making it look like it had a non-constant density
(<code>fog4.pov</code>).</p>
<pre>
  fog {
    distance 150
    color rgbf&lt;0.3, 0.5, 0.2, 1.0&gt;
    turbulence 0.2
    turb_depth 0.3
  }
</pre>

<table class="centered" width="340px" cellpadding="0" cellspacing="10">
<tr>
  <td>
    <img class="center" width="320px" src="images/4/43/TutImgTurbfog.png">
  </td>
</tr>
<tr>
  <td>
    <p class="caption">Fog made more interesting with turbulence.</p>
  </td>
</tr>
</table>

<p>The <code>turbulence</code> keyword is used to specify the amount of
turbulence used while the <code>turb_depth</code> value is used to move the
point at which the turbulence value is calculated along the viewing ray.
Values near zero move the point to the viewer while values near one move it
to the intersection point (the default value is 0.5). This parameter can be
used to avoid noise that may appear in the fog due to the turbulence (this
normally happens at very far away intersection points, especially if no
intersection occurs, i. e. the background is hit). If this happens just lower
the <code>turb_depth</code> value until the noise vanishes.</p>
<p>
You should keep in mind that the actual density of the fog does not change.
Only the distance-based attenuation value of the fog is modified by the
turbulence value at a point along the viewing ray.</p>

</div>
<a name="t2_3_6_3_5"></a>
<div class="content-level-h5" contains="Using Ground Fog" id="t2_3_6_3_5">
<h5>2.3.6.3.5 Using Ground Fog</h5>
<p>The much more interesting and flexible fog type is the ground fog, which
is selected with the <code><a href="r3_4.html#r3_4_3_3">fog_type</a></code> statement.
Its appearance is described with the <code><a href="r3_4.html#r3_4_3_3">fog_offset</a></code>
and <code><a href="r3_4.html#r3_4_3_3">fog_alt</a></code> keywords.
The <code>fog_offset</code> specifies the height, i. e. y value, below which
the fog has a constant density of one. The <code>fog_alt</code> keyword
determines how fast the density of the fog will approach zero as one moves
along the y axis. At a height of fog_offset+fog_alt the fog will have a
density of 25%.</p>
<p>
The following example (<code>fog5.pov</code>) uses a ground fog which has a
constant density below y=25 (the center of the red sphere) and quickly falls
off for increasing altitudes.</p>
<pre>
  fog {
    distance 150
    color rgbf&lt;0.3, 0.5, 0.2, 1.0&gt;
    fog_type 2
    fog_offset 25
    fog_alt 1
  }
</pre>

<table class="centered" width="340px" cellpadding="0" cellspacing="10">
<tr>
  <td>
    <img class="center" width="320px" src="images/d/de/TutImgLowfog.png">
  </td>
</tr>
<tr>
  <td>
    <p class="caption">An example of ground fog.</p>
  </td>
</tr>
</table>


</div>



<a name="t2_3_6_3_6"></a>
<div class="content-level-h5" contains="Using Multiple Layers of Fog" id="t2_3_6_3_6">
<h5>2.3.6.3.6 Using Multiple Layers of Fog</h5>
<p>It is possible to use several layers of fog by using more than one fog
statement in your scene file. This is quite useful if you want to get nice
effects using turbulent ground fogs. You could add up several, differently
colored fogs to create an eerie scene for example.</p>
<p>
Just try the following example (<code>fog6.pov</code>).</p>
<pre>
  fog {
    distance 150
    color rgb&lt;0.3, 0.5, 0.2&gt;
    fog_type 2
    fog_offset 25
    fog_alt 1
    turbulence 0.1
    turb_depth 0.2
  }
  fog {
    distance 150
    color rgb&lt;0.5, 0.1, 0.1&gt;
    fog_type 2
    fog_offset 15
    fog_alt 4
    turbulence 0.2
    turb_depth 0.2
  }
  fog {
    distance 150
    color rgb&lt;0.1, 0.1, 0.6&gt;
    fog_type 2
    fog_offset 10
    fog_alt 2
  }
</pre>

<table class="centered" width="340px" cellpadding="0" cellspacing="10">
<tr>
  <td>
    <img class="center" width="320px" src="images/d/d2/TutImgMultifog.png">
  </td>
</tr>
<tr>
  <td>
    <p class="caption">Using multiple layers of fog.</p>
  </td>
</tr>
</table>

<p>You can combine constant density fogs, ground fogs, filtering fogs,
non-filtering fogs, fogs with a translucency threshold, etc.</p>
</div>
<a name="t2_3_6_3_7"></a>
<div class="content-level-h5" contains="Fog and Hollow Objects" id="t2_3_6_3_7">
<h5>2.3.6.3.7 Fog and Hollow Objects</h5>
<p>Whenever you use the fog feature and the camera is inside a non-hollow
object you will not get any fog effects. For a detailed explanation why this
happens see <a href="r3_4.html#r3_4_8_1_2">Empty and Solid Objects</a>.</p>
<p>
In order to avoid this problem you have to make all those objects hollow by
either making sure the camera is outside these objects (using the <code><a href="r3_4.html#r3_4_5_5_5">inverse</a></code>
keyword) or by adding the <code><a href="r3_4.html#r3_4_5_5_4">hollow</a></code> to them (which is much easier).</p>

</div>
<a name="t2_3_6_4"></a>
<div class="content-level-h4" contains="The Rainbow" id="t2_3_6_4">
<h4>2.3.6.4 The Rainbow</h4>
<p>The <code><a href="r3_4.html#r3_4_3_5">rainbow</a></code> feature can be used
to create rainbows and maybe other more strange effects. The rainbow is a fog
like effect that is restricted to a cone-like volume.</p>

</div>
<a name="t2_3_6_4_1"></a>
<div class="content-level-h5" contains="Starting With a Simple Rainbow" id="t2_3_6_4_1">
<h5>2.3.6.4.1 Starting With a Simple Rainbow</h5>
<p>The rainbow is specified with a lot of parameters: the angle under which
it is visible, the width of the color band, the direction of the incoming
light, the fog-like distance based particle density and last but not least
the color map to be used.</p>
<p>
The size and shape of the rainbow are determined by the <code><a href="r3_4.html#r3_4_3_5">angle</a></code>
and <code><a href="r3_4.html#r3_4_3_5">width</a></code> keywords. The <code><a href="r3_4.html#r3_4_3_5">width</a></code>
keyword is used to set the direction of the incoming light, thus setting the
rainbow's position. The rainbow is visible when the angle between the direction
vector and the incident light direction is larger than angle-width/2 and smaller
than angle+width/2.</p>
<p>
The incoming light is the virtual light source that is responsible for the
rainbow. There need not be a real light source to create the rainbow
effect.</p>
<p>
The rainbow is a fog-like effect, i.e. the rainbow's color is mixed with
the background color based on the distance to the intersection point. If you
choose small distance values the rainbow will be visible on objects, not just
in the background. You can avoid this by using a very large distance
value.</p>
<p>
The color map is the crucial part of the rainbow since it contains all the
colors that normally can be seen in a rainbow. The color of the innermost
color band is taken from the color map entry 0 while the outermost band is
take from entry 1. You should note that due to the limited color range any
monitor can display it is impossible to create a real rainbow. There are just
some colors that you cannot display.</p>
<p>
The filter channel of the rainbow's color map is used in the same way as
with fogs. It determines how much of the light passing through the rainbow is
filtered by the color.</p>
<p>
The following example shows a simple scene with a ground plane, three
spheres and a somewhat exaggerated rainbow (<code>rainbow1.pov</code>).</p>
<pre>
  #include &quot;colors.inc&quot;
  camera {
    location &lt;0, 20, -100&gt;
    look_at &lt;0, 25, 0&gt;
    angle 80
  }
  background { color SkyBlue }
  plane { y, -10 pigment { color Green } }
  light_source { &lt;100, 120, 40&gt; color White }
  // declare rainbow's colors
  #declare r_violet1 = color rgbf&lt;1.0, 0.5, 1.0, 1.0&gt;;
  #declare r_violet2 = color rgbf&lt;1.0, 0.5, 1.0, 0.8&gt;;
  #declare r_indigo  = color rgbf&lt;0.5, 0.5, 1.0, 0.8&gt;;
  #declare r_blue    = color rgbf&lt;0.2, 0.2, 1.0, 0.8&gt;;
  #declare r_cyan    = color rgbf&lt;0.2, 1.0, 1.0, 0.8&gt;;
  #declare r_green   = color rgbf&lt;0.2, 1.0, 0.2, 0.8&gt;;
  #declare r_yellow  = color rgbf&lt;1.0, 1.0, 0.2, 0.8&gt;;
  #declare r_orange  = color rgbf&lt;1.0, 0.5, 0.2, 0.8&gt;;
  #declare r_red1    = color rgbf&lt;1.0, 0.2, 0.2, 0.8&gt;;
  #declare r_red2    = color rgbf&lt;1.0, 0.2, 0.2, 1.0&gt;;
  // create the rainbow
  rainbow {
    angle 42.5
    width 5
    distance 1.0e7
    direction &lt;-0.2, -0.2, 1&gt;
    jitter 0.01
    color_map {
      [0.000  color r_violet1]
      [0.100  color r_violet2]
      [0.214  color r_indigo]
      [0.328  color r_blue]
      [0.442  color r_cyan]
      [0.556  color r_green]
      [0.670  color r_yellow]
      [0.784  color r_orange]
      [0.900  color r_red1]
    }
  }
</pre>

<p>Some irregularity is added to the color bands using the <code><a href="t2_3.html#t2_3_9_4">jitter</a></code> keyword.</p>

<table class="centered" width="340px" cellpadding="0" cellspacing="10">
<tr>
  <td>
    <img class="center" width="320px" src="images/d/d4/TutImgCrainbow.png">
  </td>
</tr>
<tr>
  <td>
    <p class="caption">A colorful rainbow.</p>
  </td>
</tr>
</table>

<p>The rainbow in our sample is much too bright. You will never see a
rainbow like this in reality. You can decrease the rainbow's colors by
decreasing the RGB values in the color map.</p>

</div>
<a name="t2_3_6_4_2"></a>
<div class="content-level-h5" contains="Increasing the Rainbow's Translucency" id="t2_3_6_4_2">
<h5>2.3.6.4.2 Increasing the Rainbow's Translucency</h5>
<p>The result we have so far looks much too bright. Just reducing the
rainbow's color helps but it is much better to increase the
translucency of the rainbow because it is more realistic if the background is
visible through the rainbow.</p>
<p>
We can use the transmittance channel of the colors in the color map to
specify a minimum translucency, just like we did with the fog. To get
realistic results we have to use very large transmittance values as you can
see in the following example (<code>rainbow2.pov</code>).</p>
<pre>
  rainbow {
    angle 42.5
    width 5
    distance 1.0e7
    direction &lt;-0.2, -0.2, 1&gt;
    jitter 0.01
    color_map {
      [0.000  color r_violet1 transmit 0.98]
      [0.100  color r_violet2 transmit 0.96]
      [0.214  color r_indigo  transmit 0.94]
      [0.328  color r_blue    transmit 0.92]
      [0.442  color r_cyan    transmit 0.90]
      [0.556  color r_green   transmit 0.92]
      [0.670  color r_yellow  transmit 0.94]
      [0.784  color r_orange  transmit 0.96]
      [0.900  color r_red1    transmit 0.98]
    }
  }
</pre>

<p>The transmittance values increase at the outer bands of the rainbow to
make it softly blend into the background.</p>

<table class="centered" width="340px" cellpadding="0" cellspacing="10">
<tr>
  <td>
    <img class="center" width="320px" src="images/8/8f/TutImgRrainbow.png">
  </td>
</tr>
<tr>
  <td>
    <p class="caption">A much more realistic rainbow.</p>
  </td>
</tr>
</table>

<p>The resulting image looks much more realistic than our first rainbow.</p>
</div>
<a name="t2_3_6_4_3"></a>
<div class="content-level-h5" contains="Using a Rainbow Arc" id="t2_3_6_4_3">
<h5>2.3.6.4.3 Using a Rainbow Arc</h5>
<p>Currently our rainbow has a circular shape, even though most of it is
hidden below the ground plane. You can easily create a rainbow arc by using
the <code><a href="r3_4.html#r3_4_3_5">arc_angle</a></code> keyword with an angle below 360 degrees.</p>
<p>
If you use <code>arc_angle 120</code> for example you will get a rainbow
arc that abruptly vanishes at the arc's ends. This does not look good. To
avoid this the <code><a href="r3_4.html#r3_4_3_5">falloff_angle</a></code> keyword can be used to specify a
region where the arc smoothly blends into the background.</p>
<p>
As explained in the rainbow's reference section (see <a href="r3_4.html#r3_4_3_5">Rainbow</a>) the arc extends from -arc_angle/2 to arc_angle/2 while
the blending takes place from -arc_angle/2 to -falloff_angle/2 and
falloff_angle/2 to arc_angle/2. This is the reason why the <code>falloff_angle</code>
has to be smaller or equal to the <code>arc_angle</code>.</p>
<p>
In the following examples we use an 120 degrees arc with a 45 degree falloff
region on both sides of the arc (<code>rainbow3.pov</code>).</p>
<pre>
  rainbow {
    angle 42.5
    width 5
    arc_angle 120
    falloff_angle 30
    distance 1.0e7
    direction &lt;-0.2, -0.2, 1&gt;
    jitter 0.01
    color_map {
      [0.000  color r_violet1 transmit 0.98]
      [0.100  color r_violet2 transmit 0.96]
      [0.214  color r_indigo  transmit 0.94]
      [0.328  color r_blue    transmit 0.92]
      [0.442  color r_cyan    transmit 0.90]
      [0.556  color r_green   transmit 0.92]
      [0.670  color r_yellow  transmit 0.94]
      [0.784  color r_orange  transmit 0.96]
      [0.900  color r_red1    transmit 0.98]
    }
  }
</pre>

<p>The arc angles are measured against the rainbows up direction which can be
specified using the <code>up</code> keyword. By default the up direction is
the y-axis.</p>

<table class="centered" width="340px" cellpadding="0" cellspacing="10">
<tr>
  <td>
    <img class="center" width="320px" src="images/0/09/TutImgArainbow.png">
  </td>
</tr>
<tr>
  <td>
    <p class="caption">A rainbow arc.</p>
  </td>
</tr>
</table>

<p>We finally have a realistic looking rainbow arc.</p>

</div>
<a name="t2_3_7"></a>
<div class="content-level-h3" contains="Simple Media Tutorial" id="t2_3_7">
<h3>2.3.7 Simple Media Tutorial</h3>
<p>Media in POV-Ray is a very versatile feature and can be used for a very
diverse set of special effects such as glows, smoke, dust, fog, etc. However, due to its versatility, media is not one of the easiest and simplest features of 
POV-Ray and often requires experience for getting things to look good.</p>

</div>
<a name="t2_3_7_1"></a>
<div class="content-level-h4" contains="Types of media" id="t2_3_7_1">
<h4>2.3.7.1 Types of media</h4>
<p>There are three types of media in POV-Ray: Emitting, absorbing and
scattering. They have the following properties:</p>
<ul>
  <li>Emitting: This is an additive media, which is handled as if it only emits
light (note: it does not emit light to its surroundings like a 
<code>light_source</code> does; this just describes how it affects the rays 
going through it). That is, the color of the media is added to the color of 
the ray passing through it. Light sources do not have any effect at all in it 
(ie. it does not affect shadows in any way).</li> 
  <li>Absorbing: This is a substractive media. This media substracts (absorbs) 
its coloration from the ray passing through it. Light sources are taken into 
account only in the shadow of the media (that is, absorbing media casts a 
shadow).</li> 
  <li>Scattering: This is the most advanced media type as it fully takes into 
account light passing through it. That is, this media is lit by light sources 
(and thus, for example, nearby objects can cast shadows into the scattering 
media).</li>
</ul>

<p>Emitting and absorbing medias are the simplest and thus fastest ones. 
Emitting media can be used for things like glows, lasers, sparkles and similar 
light-emitting effects. Absorbing media can be used for things like smoke and 
fog (the difference between the <code>fog</code> feature of POV-Ray is that the 
density of an absorbing media can be modified by a pattern and the media can be 
contained inside an object). 
</p>
<p>Scattering media is the more advanced and slower type. It is somewhat similar
to absorbing media except that it is fully lit by light sources. This can be used 
for smoke or fog with visible lightbeams and shadows.</p>

</div>
<a name="t2_3_7_2"></a>
<div class="content-level-h4" contains="Some media concepts" id="t2_3_7_2">
<h4>2.3.7.2 Some media concepts</h4>
<p>Media can be global to the whole universe, or it can be contained by an 
object. In the latter case the media is defined in the <code>interior</code> 
block of the object definition.</p> 

<p>For an object to be able to contain media (or to allow media from other 
objects or the global media inside itself) it has to be defined as 
<code>hollow</code> (a common mistake is to forget adding this keyword). If an 
object with no media should not allow media inside itself (eg. a solid glass 
ball), then <code>hollow</code> should not be defined for that object.</p>

<p>If media is defined in the <code>interior</code> of an object or as a global 
media it will have a constant density throughout the object/universe. However, a 
density pattern can be specified for non-uniform media. Also all kinds of 
transformations can be applied to the media. This is specially useful for 
various effects (such as smoke with certain shape). </p>

</div>
<a name="t2_3_7_3"></a>
<div class="content-level-h4" contains="Simple media examples" id="t2_3_7_3">
<h4>2.3.7.3 Simple media examples</h4>

</div>
<a name="t2_3_7_3_1"></a>
<div class="content-level-h5" contains="Emitting media" id="t2_3_7_3_1">
<h5>2.3.7.3.1 Emitting media</h5>
<p>Let's start with a very simple scene showing an emitting media using a 
spherical density map. Emitting media is used with the <code>emission</code> 
keyword followed by a color value. This color value tells the overall color of 
the media:</p>

<pre>
 global_settings { assumed_gamma 1 }
 background { rgb 1 }
 camera { location &lt;3,4,-5&gt;*.8 look_at 0 angle 35 }
 light_source { &lt;20,40,10&gt;, 1 }

 box // floor
 { &lt;-1.5,-1.01,-1.5&gt;, &lt;1.5,-1.2,1.5&gt;
   pigment { checker rgb 0.75, rgb 0.25 scale 0.2 }
 }

 sphere // transparent sphere containing media
 { 0,1 pigment { rgbt 1 } hollow
   interior
   { media
     { emission 1
       density
       { spherical density_map
         { [0 rgb 0]
           [0.4 rgb &lt;1,0,0&gt;]
           [0.8 rgb &lt;1,1,0&gt;]
           [1 rgb 1]
         }
       }
     }
  }
 }
</pre>

<p class="Note"><strong>Note:</strong> The <code>spherical</code> pattern gets values from 0 in the outer 
surface of a unit sphere to 1 in the origin (that is, the density with the index 
value 1 will be the density at the center of the media).</p>

<p>The color values in the density map tell what color the media is emitting at 
a certain point in the pattern. That is, for example when the pattern gets the 
value 0.4, the media will be completely red at that place. If the color is 
<code>&lt;0,0,0&gt;</code>, it means that the media does not emit any light at 
all in that location. </p>

<p class="Note"><strong>Note: </strong>The density map colors are multiplied by the color given with the <code>emission</code> keyword; since 1 is used in this case, the density map colors are not affected.</p>

<p>Thus, this will give us a media with a bright white center which fades to 
yellow and red at the outer limits of the unit sphere: </p>

<table class="centered" width="340px" cellpadding="0" cellspacing="10">
<tr>
  <td>
    <img class="center" width="320px" src="images/3/32/TutImgMediatut1.png">
  </td>
</tr>
<tr>
  <td>
    <p class="caption">Simple emitting media example</p>
  </td>
</tr>
</table>

<p>As you can see from the image, the emitting media is invisible against white 
background. This is due to its additive nature (any color added to pure white 
gives pure white). In fact, emitting media gives usually best results for dark 
backgrounds. </p>

</div>
<a name="t2_3_7_3_2"></a>
<div class="content-level-h5" contains="Absorbing media" id="t2_3_7_3_2">
<h5>2.3.7.3.2 Absorbing media</h5>
<p>Modifying the previous example to use absorbing media is rather simple: 
Simply change the <code>emission</code> keyword for <code>absorption</code>. 
However, the colors we used above are not very illustrative for absorbing media, 
so let's change them a bit like this:</p>

<pre>
    media
    { absorption 1
      density
      { spherical density_map
        { [0 rgb 0]
          [0.4 rgb 0]
          [0.5 rgb &lt;0,0.5,1&gt;]
          [1 rgb &lt;0,1,1&gt;]
        }
      }
    }
</pre>

<table class="centered" width="340px" cellpadding="0" cellspacing="10">
<tr>
  <td>
    <img class="center" width="320px" src="images/9/91/TutImgMediatut2.png">
  </td>
</tr>
<tr>
  <td>
    <p class="caption">Simple absorbing media example</p>
  </td>
</tr>
</table>

<p>The feature which we immediately notice in the image is that the media seems 
to be inverted from the colors specified in the density map: Blueish colors were 
specified in the map, but the image shows a reddish media. This is perfectly 
normal and to be expected from the substractive nature of absorbing media: The 
media actually absorbs the colors we specified in the density map. This means 
that for example specifying a white color (<code>&lt;1,1,1&gt;</code>) in the 
density map will absorb all colors, thus resulting in a dark media. </p>

<p>See how this media has a shadow: light rays passing through the media are absorbed.</p>

<p>Because of its subtractive nature, absorbing media works well with light backgrounds and not very well with dark ones.</p>

</div>
<a name="t2_3_7_3_3"></a>
<div class="content-level-h5" contains="Scattering media" id="t2_3_7_3_3">
<h5>2.3.7.3.3 Scattering media</h5>
<p>Since scattering media fully takes light sources into account we need to make 
a slightly more complex scene to see this. Let's modify the above example by 
replacing the sphere with a box containing evenly distributed scattering media, 
and a cylinder which will cast a shadow onto the media:</p>

<pre>
 box
 { -1,1 pigment { rgbt 1 } hollow
   interior
   { media
     { scattering { 1, 0.5 }
     }
   }
 }
 cylinder
 { &lt;0.9, -1, 0.7&gt;, &lt;0.9, 0.9, 0.7&gt;, 0.5
   pigment { rgb &lt;1, 0.8, 0.5&gt; }
 }
</pre>

<table class="centered" width="340px" cellpadding="0" cellspacing="10">
<tr>
  <td>
    <img class="center" width="320px" src="images/1/14/TutImgMediatut3.png">
  </td>
</tr>
<tr>
  <td>
    <p class="caption">Simple scattering media example</p>
  </td>
</tr>
</table>

<p>(The effect may look a bit unnatural for a fog effect because the media is 
contained inside a box and the cylinder is partially out of this box, but this 
is done to better visualize what is happening.) </p>

<p>The <code>scattering</code> keyword takes more parameters than the other two. 
The first number inside the curly brackets is the scattering media type. In this 
example we used scattering media type 1. A full list of scattering media types 
is given in the section <a href="r3_4.html#r3_4_8_2_3">scattering</a> of the Media reference.</p> 

<p>The second parameter is the overall color of the media, similar to the 
parameter of the other two media types.</p> 

<p>An optional third parameter can be given with the <code>extinction</code> 
keyword inside the curly brackets. This keyword controls how fast the scattering 
media absorbs light and has to be used sometimes to get the desired effect, such 
as when the media absorbs too much light.</p> 

<p><strong>Tip:</strong> If you are getting a really dense or dark scattering media, try 
different values for the color and the extinction value (usually values between 
0 and 1). It is usually enough to play with these two values to get the desired 
effect.</p>

</div>


<a name="t2_3_7_4"></a>
<div class="content-level-h4" contains="Multiple medias inside the same object" id="t2_3_7_4">
<h4>2.3.7.4 Multiple medias inside the same object</h4>
<p>Emitting media works well with dark backgrounds. Absorbing media works well 
for light backgrounds. But what if we want a media which works with both type of 
backgrounds? </p>

<p>One solution for this is to use both types of medias inside the same object. 
This is possible in POV-Ray. </p>

<p>Let's take the very first example, which did not work well with the white 
background, and add a slightly absorbing media to the sphere:</p>

<pre>
 sphere
 { 0,1 pigment { rgbt 1 } hollow
   interior
   { media
     { emission 1
       density
       { spherical density_map
         { [0 rgb 0]
           [0.4 rgb &lt;1,0,0&gt;]
           [0.8 rgb &lt;1,1,0&gt;]
           [1 rgb 1]
         }
       }
     }
     media
     { absorption 0.2
     }
   }
 }
</pre>

<p>This will make the sphere not only add light to the rays passing through it, 
but also substract. </p>

<table class="centered" width="340px" cellpadding="0" cellspacing="10">
<tr>
  <td>
    <img class="center" width="320px" src="images/8/8d/TutImgMediatut4.png">
  </td>
</tr>
<tr>
  <td>
    <p class="caption">Emitting and absorbing media example.</p>
  </td>
</tr>
</table>

<p>Multiple medias in the same object can be used for several other effects as 
well. </p>

</div>
<a name="t2_3_7_5"></a>
<div class="content-level-h4" contains="Media and transformations" id="t2_3_7_5">
<h4>2.3.7.5 Media and transformations</h4>
<p>The density of a media can be modified with any pattern modifier, such as 
turbulence, scale, etc. This is a very powerful tool for making diverse effects.</p>

<p>As an example, let's make an absorbing media which looks like smoke. For this 
we take the absorbing media example and modify the sphere like this:</p>
<pre>
 sphere
 { 0,1.5 pigment { rgbt 1 } hollow
   interior
   { media
     { absorption 7
       density
       { spherical density_map
         { [0 rgb 0]
           [0.5 rgb 0]
           [0.7 rgb .5]
           [1 rgb 1]
         }
         scale 1/2
         warp { turbulence 0.5 }
         scale 2
       }
     }
   }
   scale &lt;1.5,6,1.5&gt; translate y
 }
</pre>

<table class="centered" width="340px" cellpadding="0" cellspacing="10">
<tr>
  <td>
    <img class="center" width="320px" src="images/d/dd/TutImgMediatut5.png">
  </td>
</tr>
<tr>
  <td>
    <p class="caption">Media transformation example.</p>
  </td>
</tr>
</table>

<p>A couple of notes: </p>
<p>The radius of the sphere is now a bit bigger than 1 because the turbulent 
pattern tends to take more space. </p>
<p>The absorption color can be larger than 1, making the absorption stronger and 
the smoke darker. </p>

<P class="Note"><strong>Note:</strong> When you scale an object containing media the media density is not 
scaled accordingly. This means that if you for example scale a container object 
larger the rays will pass through more media than before, giving a stronger 
result. If you want to keep the same media effect with the larger object, you 
will need to divide the color of the media by the scaling amount.</p> 

<p>The question of whether the program should scale the density of the media 
with the object is a question of interpretation: For example, if you have a 
glass of colored water, a larger glass of colored water will be more colored 
because the light travels a larger distance. This is how POV-Ray behaves. 
Sometimes, however, the object needs to be scaled so that the media does not 
change; in this case the media color needs to be scaled inversely.</p> 

</div>
<a name="t2_3_7_6"></a>
<div class="content-level-h4" contains="A more advanced example of scattering media" id="t2_3_7_6">
<h4>2.3.7.6 A more advanced example of scattering media</h4>
<p>For a bit more advanced example of scattering media, let's make a room with a 
window and a light source illuminating from outside the room. The room contains 
scattering media, thus making the light beam coming through the window visible.</p>

<pre>
 global_settings { assumed_gamma 1 }
 camera { location &lt;14.9, 1, -8&gt; look_at -z angle 70 }
 light_source { &lt;10,100,150&gt;, 1 }
 background { rgb &lt;0.3, 0.6, 0.9&gt; }

 // A dim light source inside the room which does not
 // interact with media so that we can see the room:
 light_source { &lt;14, -5, 2&gt;, 0.5 media_interaction off }

 // Room
 union
 { difference
   { box { &lt;-11, -7, -11&gt;, &lt;16, 7, 10.5&gt; }
     box { &lt;-10, -6, -10&gt;, &lt;15, 6, 10&gt; }
     box { &lt;-4, -2, 9.9&gt;, &lt;2, 3, 10.6&gt; }
   }
   box { &lt;-1.25, -2, 10&gt;, &lt;-0.75, 3, 10.5&gt; }
   box { &lt;-4, 0.25, 10&gt;, &lt;2, 0.75, 10.5&gt; }
   pigment { rgb 1 }
 }
 
 // Scattering media box:
 box
 { &lt;-5, -6.5, -10.5&gt;, &lt;3, 6.5, 10.25&gt;
   pigment { rgbt 1 } hollow
   interior
   { media
     { scattering { 1, 0.07 extinction 0.01 }
       samples 30
     }
   }
 }
</pre>

<table class="centered" width="700px" cellpadding="0" cellspacing="10">
<tr>
  <td>
    <img class="left" width="320px" src="images/9/9b/TutImgMediatut6.png">
  </td>
  <td>
    <p>As suggested previously, the scattering color and extinction values were adjusted until the image looked good. In this kind of scene usually very small values are needed.</p>
    <p>Note how the container box is quite smaller than the room itself. Container boxes should always be sized as minimally as possible. If the box were as big as the room much higher values for <code>samples</code> would be needed for a good result, thus resulting in a much slower rendering.</p>
  </td>
</tr>
<tr>
  <td>
    <p class="caption">more advanced scattering media example</p>
  </td>
  <td></td>
</tr>
</table>

</div>
<a name="t2_3_7_7"></a>
<div class="content-level-h4" contains="Media and photons" id="t2_3_7_7">
<h4>2.3.7.7 Media and photons</h4>
<p>The photon mapping technique can be used in POV-Ray for making stunningly 
beautiful images with light reflecting and refracting from objects. By default, 
however, reflected and refracted light does not affect media. Making photons 
interact with media can be turned on with the <code>media</code> keyword in the 
<code>photons</code> block inside <code>global_settings</code>.</p>

<p>To visualize this, let's make the floor of our room reflective so that it 
will reflect the beam of light coming from the window.</p>

<p>Firstly, due to how photons work, we need to specify <code>photons { 
pass_through }</code> in our scattering media container box so that photons will 
pass through its surfaces. </p>

<p>Secondly, we will want to turn photons off for our fill-light since it's 
there only for us to see the interior of the room and not for the actual 
lighting effect. This can be done by specifying <code>photons { reflection off 
}</code> in that light source. </p>

<p>Thirdly, we need to set up the photons and add a reflective floor to the 
room. Let's make the reflection colored for extra effect:</p>
<pre>
 global_settings
 { photons
   { count 20000
     media 100
   }
 }
 
 // Reflective floor:
 box
 { &lt;-10, -5.99, -10&gt;, &lt;15, -6, 10&gt;
   pigment { rgb 1 }
   finish { reflection &lt;0.5, 0.4, 0.2&gt; }
   photons { target reflection on }
 }
</pre>

<table class="centered" width="340px" cellpadding="0" cellspacing="10">
<tr>
  <td>
    <img class="center" width="320px" src="images/8/8a/TutImgMediatut7.png">
  </td>
</tr>
<tr>
  <td>
    <p class="caption">Scattering media with photons example.</p>
  </td>
</tr>
</table>

<p>With all these fancy effects the render times start becoming quite high, but unfortunately this is a price which has to be paid for such effects. </p>

</div>
<a name="t2_3_8"></a>
<div class="content-level-h3" contains="Radiosity" id="t2_3_8">
<h3>2.3.8 Radiosity</h3>
</div>
<a name="t2_3_8_1"></a>
<div class="content-level-h4" contains="Introduction" id="t2_3_8_1">
<h4>2.3.8.1 Introduction</h4>
<p>Radiosity is a lighting technique to simulate the diffuse exchange of
radiation between the objects of a scene.  With a raytracer like POV-Ray,
normally only the direct influence of light sources on the objects can be
calculated, all shadowed parts look totally flat.  Radiosity can help to
overcome this limitation.  More details on the technical aspects can be
found in the <a href="r3_4.html#r3_4_4_3">reference</a> section.</p>

<p>To enable radiosity, you have to add a radiosity block to the
global_settings in your POV-Ray scene file. Radiosity is more accurate than
simplistic ambient light but it takes much longer to compute, so it can be useful
to switch off radiosity during scene development. You can use a declared constant
or an <a href="r3_2.html#r3_2_5_1">INI-file constant</a> and an <code>#if</code> statement to do this:</p>
<pre>
  #declare RAD = off;

  global_settings {
     #if(RAD)
        radiosity {
           ...
        }
     #end
  }
</pre>

<p>Most important for radiosity are the emission and diffuse finish components of the objects. Their effect differs quite greatly from a conventionally lit scene.</p>

<ul>
<li><code>emission</code>: specifies the amount of light emitted by the object. This is the basis for <a href="t2_3.html#t2_3_8_3">radiosity without conventional lighting</a> but also in scenes with light sources this can be important. In a radiosity scene, <code>emission</code> not only makes the object itself brighter, but effectively makes it a light source, illuminating nearby objects.</li>
<li><code>diffuse</code>: influences the amount of diffuse reflection of incoming light.  In a radiosity scene this does not only mean the direct appearance of the surface but also how much other objects are illuminated by indirect light from this surface.</li>
</ul>

<p class="Note"><strong>Note:</strong> Previous versions of POV-Ray up to 3.6 inclusive did not provide the <code>emission</code> keyword, leading to the practice of using <code>ambient</code> instead. As of POV-Ray 3.7, this will no longer work, as <code>ambient_light</code> is effectively forced to zero when radiosity is enabled. For backward compatibility, an exception is made for scenes specifying a <code>#version</code> of 3.6 or earlier (or no version at all). In such scenes, it is strongly recommended to set the <code>ambient</code> of all materials to zero (unless you want them to emit light), or explicitly set <code><a href="r3_4.html#r3_4_1_2">ambient_light</a></code> to zero.</p>

</div>
<a name="t2_3_8_2"></a>
<div class="content-level-h4" contains="Radiosity with conventional lighting" id="t2_3_8_2">
<h4>2.3.8.2 Radiosity with conventional lighting</h4>
<p>This section will introduce you to the technique of combining conventional and radiosity lighting. In this part of the tutorial, we'll be using basically the same sample scene that's located at <code>~/scenes/radiosity/radiosity2.pov</code>, however by changing various radiosity parameters, we'll be able to explore the effects that those changes can have on the scenes appearance and in some cases the render time. Later on, in this tutorial, you can find examples of <a href="t2_3.html#t2_3_8_3">pure radiosity</a> illumination.</p>

<p class="Note"><strong>Note:</strong> Unless otherwise stated all the images in this section were rendered with the following radiosity settings:</p>

<pre>
  global_settings {
    radiosity {
      pretrace_start 0.08
      pretrace_end   0.01
      count 150
      nearest_count 10
      error_bound 0.5
      recursion_limit 3
      low_error_factor 0.5
      gray_threshold 0.0
      minimum_reuse 0.005
      maximum_reuse 0.2
      brightness 1
      adc_bailout 0.005
    }
  }
</pre>

<p>Finally, a few more things about the scene setup. All objects except the sky have <code>diffuse 0.65</code> and <code>emission 0</code> in their finish block. The sky sphere has a bright blue pigment (what a surprise) with <code>diffuse 0</code> and <code>emission 1.0</code> as finish attributes.</p>

<p class="Note"><strong>Note:</strong> If using the <code><a href="r3_4.html#r3_4_3_4">sky_sphere</a></code> object, which does not support the <code>finish</code> keyword, instead of a <code><a href="r3_4.html#r3_4_5_1_12">sphere</a></code> object that does, you will need define a <code><a href="r3_3.html#r3_3_2_4">#default</a></code> finish in order to affect it's finish properties.</p>

<p>For example:</p>

<pre>
#default {finish { diffuse 0 emission 1 }}
</pre>

<p class="Hint"><strong>Hint:</strong> You can easily turn radiosity on/off with the use of a conditional statement.</p>

<pre>
#declare UseRad = yes;

  global_settings {
  #if (UseRad)
    radiosity {
      rad settings ...
    }
  #end
  }
</pre>

<p>OK, let's get started! In this set of images we first have the scene as it should appear without radiosity, in other words the <code>radiosity</code> block has been removed, next with the settings noted above, and finally an image showing the difference between the two. Looking at the difference image, you can see that radiosity greatly affects the shadowed areas when applied in combination with conventional lighting.</p>

<p class="Note"><strong>Note:</strong> The use of <code>emission 1</code> in the finish block of the blue sky is what gives the bluish touch of the whole scene in the radiosity version, as it functions as kind of a diffuse light source.</p>

<table class="matte" width="700px" cellpadding="0" cellspacing="10px">
<tr>
  <td>
    <img class="leftpanel" width="220px" src="images/4/4e/TutImgRadA01.png">
  </td>
  <td>
    <img class="centerpanel" width="220px" src="images/9/94/TutImgRadA03.png">
  </td>
  <td>
    <img class="rightpanel" width="220px" src="images/9/9b/TutImgRadA0103.png">
  </td>
</tr>
<tr>
  <td>
    <p class="caption">no radiosity</p>
  </td>
  <td>
    <p class="caption">radiosity</p>
  </td>
  <td>
    <p class="caption">difference w/o radiosity</p>
  </td>
</tr>
</table>

<p>Radiosity is a highly <em>tunable</em> process, and it comes equipped with a variety of tunable parameters that make it easy to strike a balance between quality and rendering speed. However, as with most things, higher quality means more render time. Patience is a virtue.</p>
<p>For instance, let's examine our test object with default settings, with our reference settings, and finally with some maddeningly high-quality settings. For comparison, below each image you can see the difference to the high-quality version.</p>

<table class="matte" width="700px" cellpadding="0" cellspacing="10px">
<tr>
  <td>
    <img class="leftpanel" width="220px" src="images/4/45/TutImgRadA02.png">
  </td>
  <td>
    <img class="centerpanel" width="220px" src="images/d/dd/TutImgRadA99.png">
  </td>
  <td>
    <img class="rightpanel" width="220px" src="images/9/94/TutImgRadA03.png">
  </td>
</tr>
<tr>
  <td>
    <p class="caption">default settings</p>
  </td>
  <td>
    <p class="caption">high-quality render</p>
  </td>
  <td>
    <p class="caption">reference settings</p>
  </td>
</tr>
<tr>
  <td>
    <img class="leftpanel" width="220px" src="images/9/9d/TutImgRadA0299.png">
  </td>
  <td>
  </td>
  <td>
    <img class="rightpanel" width="220px" src="images/3/39/TutImgRadA0399.png">
  </td>
</tr>
<tr>
  <td>
    <p class="caption">default settings difference</p>
  </td>
  <td>
  </td>
  <td>
    <p class="caption">reference settings difference</p>
  </td>
</tr>
</table>

<p>Changing the <code>brightness</code> changes the intensity of radiosity effects. Theoretically specifying <code>brightness 0</code> would be the same as without radiosity, however in practice POV-Ray doesn't accept a zero value. As a rule <code>brightness 1</code> should work correctly in most cases. If the effects are too strong you <em>can</em> reduce this, though this is not recommended, as it's usually an indication that your textures are too bright and your illumination too dim. Larger values can lead to quite strange results in most cases.</p>

<table class="matte" width="700px" cellpadding="0" cellspacing="10px">
<tr>
  <td>
    <img class="leftpanel" width="220px" src="images/9/91/TutImgRadA04.png">
  </td>
  <td>
    <img class="centerpanel" width="220px" src="images/9/94/TutImgRadA03.png">
  </td>
  <td>
    <img class="rightpanel" width="220px" src="images/5/5c/TutImgRadA05.png">
  </td>
</tr>
<tr>
  <td>
    <p class="caption">brightness 0.5</p>
  </td>
  <td>
    <p class="caption">brightness 1.0</p>
  </td>
  <td>
    <p class="caption">brightness 2.0</p>
  </td>
</tr>
</table>

<p>The <code>recursion_limit</code> setting primarily affects the brightness of shadows, nooks and corners. The following group of images show the results of setting this parameter to 1, 2 and 5 respectively ...</p>

<table class="matte" width="700px" cellpadding="0" cellspacing="10px">
<tr>
  <td>
    <img class="leftpanel" width="220px" src="images/a/aa/TutImgRadA06.png">
  </td>
  <td>
    <img class="centerpanel" width="220px" src="images/9/9f/TutImgRadA07.png">
  </td>
  <td>
    <img class="rightpanel" width="220px" src="images/c/c3/TutImgRadA08.png">
  </td>
</tr>
<tr>
  <td>
    <p class="caption">recursion_limit 1</p>
  </td>
  <td>
    <p class="caption">recursion_limit 2</p>
  </td>
  <td>
    <p class="caption">recursion_limit 5</p>
  </td>
</tr>
</table>
<p>... while this next grouping shows the difference when compared to our reference setting of <code>recursion_limit 3</code>. As you can see, values higher than 3 do not lead to any better results in such a quite simple scene. In most cases values of 1 or 2 are sufficient, especially for outdoor scenes.</p>
<table class="matte" width="700px" cellpadding="0" cellspacing="10px">
<tr>
  <td>
    <img class="leftpanel" width="220px" src="images/b/b0/TutImgRadA0306.png">
  </td>
  <td>
    <img class="centerpanel" width="220px" src="images/c/cb/TutImgRadA0307.png">
  </td>
  <td>
    <img class="rightpanel" width="220px" src="images/5/52/TutImgRadA0308.png">
  </td>
</tr>
<tr>
  <td>
    <p class="caption">recursion_limit 1 difference</p>
  </td>
  <td>
    <p class="caption">recursion_limit 2 difference</p>
  </td>
  <td>
    <p class="caption">recursion_limit 5 difference</p>
  </td>
</tr>
</table>

<p>The <code>error_bound</code> setting mainly affects the structures of the shadows. Values larger than the default of 1.8 do not have much effect, they make the shadows even flatter.  Extremely low values can lead to very good results, but the rendering time can become very long, and you may need to modify other parameters to avoid a grainy appearance.</p>

<table class="matte" width="700px" cellpadding="0" cellspacing="10px">
<tr>
  <td>
    <img class="leftpanel" width="220px" src="images/d/d9/TutImgRadA09.png">
  </td>
  <td>
    <img class="centerpanel" width="220px" src="images/a/a6/TutImgRadA10.png">
  </td>
  <td>
    <img class="rightpanel" width="220px" src="images/c/c4/TutImgRadA11.png">
  </td>
</tr>
<tr>
  <td>
    <p class="caption">error_bound 0.01</p>
  </td>
  <td>
    <p class="caption">error_bound 1.0</p>
  </td>
  <td>
    <p class="caption">error_bound 1.8</p>
  </td>
</tr>
<tr>
  <td>
    <img class="leftpanel" width="220px" src="images/2/25/TutImgRadA0309.png">
  </td>
  <td>
    <img class="centerpanel" width="220px" src="images/e/ea/TutImgRadA0310.png">
  </td>
  <td>
    <img class="rightpanel" width="220px" src="images/6/6a/TutImgRadA0311.png">
  </td>
</tr>
<tr>
  <td>
    <p class="caption">error_bound 0.01 difference</p>
  </td>
  <td>
    <p class="caption">error_bound 1.0 difference</p>
  </td>
  <td>
    <p class="caption">error_bound 1.8 difference</p>
  </td>
</tr>
</table>

<p>Somewhat related to error_bound is <code>low_error_factor</code>. It reduces error_bound setting during the pretrace phase, changing this can be useful to eliminate artifacts. The difference images used the <code>low_error_factor 0.5</code> case for comparison.</p>

<table class="matte" width="700px" cellpadding="0" cellspacing="10px">
<tr>
  <td>
    <img class="leftpanel" width="220px" src="images/b/b5/TutImgRadA12.png">
  </td>
  <td>
    <img class="centerpanel" width="220px" src="images/9/94/TutImgRadA03.png">
  </td>
  <td>
    <img class="rightpanel" width="220px" src="images/a/a2/TutImgRadA13.png">
  </td>
</tr>
<tr>
  <td>
    <p class="caption">low_error_factor 0.01</p>
  </td>
  <td>
    <p class="caption">low_error_factor 0.5</p>
  </td>
  <td>
    <p class="caption">low_error_factor 1.0</p>
  </td>
</tr>
<tr>
  <td>
    <img class="leftpanel" width="220px" src="images/b/b7/TutImgRadA0312.png">
  </td>
  <td>
  </td>
  <td>
    <img class="rightpanel" width="220px" src="images/c/cb/TutImgRadA0313.png">
  </td>
</tr>
<tr>
  <td>
    <p class="caption">low_error_factor 0.01 difference</p>
  </td>
  <td>
  </td>
  <td>
    <p class="caption">low_error_factor 1.0 difference</p>
  </td>
</tr>
</table>

<p>This next sequence of images illustrate the effect of <code>count</code>. It is a general quality and accuracy parameter leading to higher quality and slower rendering at higher values. Keep in mind that higher <code>count</code> isn't necessarily a cure-for-all when it comes to quality. The difference images were compared to a <code>count 150</code> case.</p>

<p class="Note"><strong>Note:</strong> Until otherwise noted the following settings are being used to emphasize the effects of the next parameters we'll be examining.</p>
<ul>
  <li><code>recursion_limit 1</code></li>
  <li><code>error_bound 0.2</code></li>
  <li><code>low_error_factor 1.0</code></li>
</ul>
<p></p>
<table class="matte" width="700px" cellpadding="0" cellspacing="10px">
<tr>
  <td>
    <img class="leftpanel" width="220px" src="images/5/59/TutImgRadA15.png">
  </td>
  <td>
    <img class="centerpanel" width="220px" src="images/e/e5/TutImgRadA16.png">
  </td>
  <td>
    <img class="rightpanel" width="220px" src="images/e/ee/TutImgRadA17.png">
  </td>
</tr>
<tr>
  <td>
    <p class="caption">count 2</p>
  </td>
  <td>
    <p class="caption">count 35 (default)</p>
  </td>
  <td>
    <p class="caption">count 1000</p>
  </td>
</tr>
<tr>
  <td>
    <img class="leftpanel" width="220px" src="images/d/d3/TutImgRadA1415.png">
  </td>
  <td>
    <img class="centerpanel" width="220px" src="images/9/93/TutImgRadA1416.png">
  </td>
  <td>
    <img class="rightpanel" width="220px" src="images/f/f3/TutImgRadA1417.png">
  </td>
</tr>
<tr>
  <td>
    <p class="caption">count 2 difference</p>
  </td>
  <td>
    <p class="caption">count 35 difference</p>
  </td>
  <td>
    <p class="caption">count 1000 difference</p>
  </td>
</tr>
</table>

<p>Another parameter that affects quality is <code>nearest_count</code>. You can use values ranging from 1 to 20 the default is 5. Just like <code>count</code>, higher values can lead to less artifacts and smoother appearance but slower rendering. The <code>nearest_count</code> setting also accepts a second parameter, which activates <em>adaptive pretrace</em>, providing a good means of speeding up pretrace without significant loss of quality (not shown here) the value must be smaller than the first parameter (e.g. <code>nearest_count 20,10</code>). When set, POV-Ray will stop pretracing individual areas of the image where the average sample density already satisfies this second value, thereby avoiding tracing low-detail areas over and over again for little gain, while still being able to drill down deep into high-detail areas. A setting of <code>nearest_count 10</code> was used for the comparison.</p>

<table class="matte" width="700px" cellpadding="0" cellspacing="10px">
<tr>
  <td>
    <img class="leftpanel" width="220px" src="images/5/5c/TutImgRadA18.png">
  </td>
  <td>
    <img class="centerpanel" width="220px" src="images/1/17/TutImgRadA19.png">
  </td>
  <td>
    <img class="rightpanel" width="220px" src="images/7/72/TutImgRadA20.png">
  </td>
</tr>
<tr>
  <td>
    <p class="caption">nearest_count 1</p>
  </td>
  <td>
    <p class="caption">nearest_count 5 (default)</p>
  </td>
  <td>
    <p class="caption">nearest_count 20</p>
  </td>
</tr>
<tr>
  <td>
    <img class="leftpanel" width="220px" src="images/5/53/TutImgRadA1418.png">
  </td>
  <td>
    <img class="centerpanel" width="220px" src="images/d/d5/TutImgRadA1419.png">
  </td>
  <td>
    <img class="rightpanel" width="220px" src="images/5/54/TutImgRadA1420.png">
  </td>
</tr>
<tr>
  <td>
    <p class="caption">nearest_count 1 difference</p>
  </td>
  <td>
    <p class="caption">nearest_count 5 difference</p>
  </td>
  <td>
    <p class="caption">nearest_count 20 difference</p>
  </td>
</tr>
</table>

<p><code>minimum_reuse</code> influences at which minimum distance previous radiosity samples are always reused during calculation, affecting quality and smoothness in nooks and corners. Higher values generally give a smoother appearance, at the cost of corner detail, while lower values may cause corners to look splotchy unless the other parameters (most notably <code>count</code> and <code>nearest_count</code>) are set for higher quality as well.</p>

<p>As <code>minimum_reuse</code> must be lower than <code>maximum_reuse</code>, to avoid a parse error with the highest setting we're using <code>maximum_reuse 0.4</code> and the <code>minimum_reuse 0.005</code> case, was used for the comparison with these next three images.</p>

<table class="matte" width="700px" cellpadding="0" cellspacing="10px">
<tr>
  <td>
    <img class="leftpanel" width="220px" src="images/3/39/TutImgRadA22.png">
  </td>
  <td>
    <img class="centerpanel" width="220px" src="images/d/dc/TutImgRadA21.png">
  </td>
  <td>
    <img class="rightpanel" width="220px" src="images/7/76/TutImgRadA23.png">
  </td>
</tr>
<tr>
  <td>
    <p class="caption">minimum_reuse 0.2</p>
  </td>
  <td>
    <p class="caption">minimum_reuse 0.005</p>
  </td>
  <td>
    <p class="caption">minimum_reuse 0.015</p>
  </td>
</tr>
<tr>
  <td>
    <img class="leftpanel" width="220px" src="images/f/fb/TutImgRadA2122.png">
  </td>
  <td>
  </td>
  <td>
    <img class="rightpanel" width="220px" src="images/c/c8/TutImgRadA2123.png">
  </td>
</tr>
<tr>
  <td>
    <p class="caption">minimum_reuse 0.2 difference</p>
  </td>
  <td>
  </td>
  <td>
    <p class="caption">minimum_reuse 0.015 difference</p>
  </td>
</tr>
</table>

<p>Another important setting is <code>pretrace_end</code>.  It specifies how many pretrace steps are calculated and thereby strongly influences the speed.  Usually lower values lead to better quality, but it is important to keep this in good relation to <code>error_bound</code>.</p>

<table class="matte" width="700px" cellpadding="0" cellspacing="10px">
<tr>
  <td>
    <img class="leftpanel" width="220px" src="images/f/f0/TutImgRadA24.png">
  </td>
  <td>
    <img class="centerpanel" width="220px" src="images/d/db/TutImgRadA14.png">
  </td>
  <td>
    <img class="rightpanel" width="220px" src="images/f/f3/TutImgRadA25.png">
  </td>
</tr>
<tr>
  <td>
    <p class="caption">pretrace_end 0.2</p>
  </td>
  <td>
    <p class="caption">pretrace_end 0.01</p>
  </td>
  <td>
    <p class="caption">pretrace_end 0.001</p>
  </td>
</tr>
<tr>
  <td>
    <img class="leftpanel" width="220px" src="images/d/de/TutImgRadA1424.png">
  </td>
  <td>
  </td>
  <td>
    <img class="rightpanel" width="220px" src="images/d/d4/TutImgRadA1425.png">
  </td>
</tr>
<tr>
  <td>
    <p class="caption">pretrace_end 0.2</p>
  </td>
  <td>
  </td>
  <td>
    <p class="caption">pretrace_end 0.001</p>
  </td>
</tr>
</table>

<p>Normally in the final trace no additional radiosity samples are taken unless absolutely needed. You can change this by adding <code>always_sample on</code> allowing you to increase <code>pretrace_end</code> to speed up rendering. Note however that this is very prone to artifacts such as visible render block boundaries and horizontal &quot;smearing&quot;, so it is usually only useful for test renders. You should also use a low setting for <code>nearest_count</code>, or you may actually <em>increase</em> the rendering time, <em>and</em> the probability of getting the mentioned artifacts!.</p>

<table class="matte" width="700px" cellpadding="0" cellspacing="10px">
<tr>
  <td>
    <img class="leftpanel" width="220px" src="images/d/db/TutImgRadA14.png">
  </td>
  <td>
    <img class="centerpanel" width="220px" src="images/a/a5/TutImgRadA1426.png">
  </td>
  <td>
    <img class="rightpanel" width="220px" src="images/8/8d/TutImgRadA26.png">
  </td>
</tr>
<tr>
  <td>
    <p class="caption">always_sample off</p>
  </td>
   <td>
    <p class="caption">always_sample on difference</p>
  </td>
  <td>
    <p class="caption">always_sample on</p>
  </td>
</tr>
</table>

<p>The effect of <code>max_sample</code> is similar to <code>brightness</code>. It does not reduce the radiosity effect in general but weakens samples with brightness above the specified value.</p>

<table class="matte" width="700px" cellpadding="0" cellspacing="10px">
<tr>
  <td>
    <img class="leftpanel" width="220px" src="images/4/4d/TutImgRadA27.png">
  </td>
  <td>
    <img class="centerpanel" width="220px" src="images/e/ee/TutImgRadA28.png">
  </td>
  <td>
    <img class="rightpanel" width="220px" src="images/d/db/TutImgRadA14.png">
  </td>
</tr>
<tr>
  <td>
    <p class="caption">max_sample 0.5</p>
  </td>
  <td>
    <p class="caption">max_sample 0.8</p>
  </td>
  <td>
    <p class="caption">max_sample not set (default)</p>
  </td>
</tr>
</table>

<p>You can strongly affect things with an object's <a href="r3_4.html#r3_4_6_3">finish</a> attributes. In fact that is the most important thing about radiosity. Normal objects should have an <code>emission 0</code> (the default) finish. Objects with an emission setting greater than zero actually act as light sources in radiosity scenes. Remember that the default finish values used until now were <code>diffuse 0.65</code> and <code>emission 0</code>.</p>

<table class="matte" width="700px" cellpadding="0" cellspacing="10px">
<tr>
  <td>
    <img class="leftpanel" width="220px" src="images/a/ab/TutImgRadA29.png">
  </td>
  <td>
    <img class="centerpanel" width="220px" src="images/d/d1/TutImgRadA30.png">
  </td>
  <td>
    <img class="rightpanel" width="220px" src="images/7/77/TutImgRadA31.png">
  </td>
</tr>
<tr>
  <td>
    <p class="caption">diffuse 0.65 emission 0.2</p>
  </td>
  <td>
    <p class="caption">diffuse 0.4 emission 0</p>
  </td>
  <td>
    <p class="caption">diffuse 1.0 emission 0</p>
  </td>
</tr>
</table>

<p>Finally you can vary the sky in outdoor radiosity scenes. In all these examples it is implemented with a sphere object.
<code>finish { emission 1 diffuse 0 }</code> and the pigment of the original sample scene were used until now. The following images show some variations.</p>

<table class="matte" width="700px" cellpadding="0" cellspacing="10px">
<tr>
  <td>
    <img class="leftpanel" width="220px" src="images/a/ab/TutImgRadA32.png">
  </td>
  <td>
    <img class="centerpanel" width="220px" src="images/e/e3/TutImgRadA33.png">
  </td>
  <td>
    <img class="rightpanel" width="220px" src="images/6/69/TutImgRadA34.png">
  </td>
</tr>
<tr>
  <td>
    <p class="caption">emission 0 diffuse 1</p>
  </td>
  <td>
    <p class="caption">emission 0 diffuse 0 (no sky)</p>
  </td>
  <td>
    <p class="caption">rgb &lt;1,0.8,0&gt; to blue 1 gradient</p>
  </td>
</tr>
</table>

</div>
<a name="t2_3_8_3"></a>
<div class="content-level-h4" contains="Radiosity without conventional lighting" id="t2_3_8_3">
<h4>2.3.8.3 Radiosity without conventional lighting</h4>
<p>Radiosity also allows us to have scenes <em>without</em> conventional light sources. What's left is a situation that's similar to what you'd expect on a cloudy day where the light comes from no specific direction but from the whole sky.</p>
<p>Reminder: The following settings are <em>still</em> in effect.</p>
<ul>
<li> <code>recursion_limit 1</code></li>
<li> <code>error_bound 0.2</code></li>
<li> <code>low_error_factor 1.0</code></li>
</ul>
<p>You can see that when the light source is removed the whole image takes on a noticeable blue tint. That's because the scene is now illuminated by our sky object, which in this case happens to be blue. Later on you'll see how varying the color of the sky influences the appearance of  the scene.</p>

<table class="matte" width="470px" cellpadding="0" cellspacing="10px">
<tr>
  <td>
    <img class="leftpanel" width="220px" src="images/d/db/TutImgRadA14.png">
  </td>
  <td>
    <img class="rightpanel" width="220px" src="images/f/f1/TutImgRadB_35.png">
  </td>
</tr>
<tr>
  <td>
    <p class="caption">with light source</p>
  </td>
  <td>
    <p class="caption">without light source</p>
  </td>
</tr>
</table>

<p class="Note"><strong>Note:</strong> We'll be using the sample scene <code>~/scenes/radiosity/radiosity3.pov</code> for the rest of this tutorial.</p>

<p>This next series of images show our new test object with the default settings, then our reference settings, and lastly those maddeningly high-quality settings we used earlier. Notice that with the default settings, the image looks much worse than in the first part of this tutorial. The reason being, those settings were mainly selected for use with a conventionally lit scene. Keep in mind, radiosity-only scenes are less forgiving of low-quality settings.</p>

<p class="Note"><strong>Note:</strong> As a reminder you might want to refer back to the reference <a href="t2_3.html#t2_3_8_2">settings</a> used at the beginning of this tutorial.</p>

<table class="matte" width="700px" cellpadding="0" cellspacing="10px">
<tr>
  <td>
    <img class="leftpanel" width="220px" src="images/6/63/TutImgRadB01.png">
  </td>
  <td>
    <img class="centerpanel" width="220px" src="images/5/59/TutImgRadB_22.png">
  </td>
  <td>
    <img class="rightpanel" width="220px" src="images/e/e1/TutImgRadB99.png">
  </td>
</tr>
<tr>
  <td>
    <p class="caption">default settings</p>
  </td>
  <td>
    <p class="caption">tutorial reference settings</p>
  </td>
  <td>
    <p class="caption">high-quality settings</p>
  </td>
</tr>
</table>

<p>The following images demonstrate the effect of different settings for <code>recursion_limit</code>.</p>

<table class="matte" width="700px" cellpadding="0" cellspacing="10px">
<tr>
  <td>
    <img class="leftpanel" width="220px" src="images/8/88/TutImgRadB03.png">
  </td>
  <td>
    <img class="centerpanel" width="220px" src="images/5/59/TutImgRadB_22.png">
  </td>
  <td>
    <img class="rightpanel" width="220px" src="images/e/e3/TutImgRadB04.png">
  </td>
</tr>
<tr>
  <td>
    <p class="caption">recursion_limit 1</p>
  </td>
  <td>
    <p class="caption">recursion_limit 3</p>
  </td>
  <td>
    <p class="caption">recursion_limit 2</p>
  </td>
</tr>
<tr>
  <td>
    <img class="leftpanel" width="220px" src="images/c/c0/TutImgRadB0203.png">
  </td>
  <td>
  </td>
  <td>
    <img class="rightpanel" width="220px" src="images/9/9a/TutImgRadB0204.png">
  </td>
</tr>
<tr>
  <td>
    <p class="caption">recursion_limit 1 difference</p>
  </td>
  <td>
  </td>
  <td>
    <p class="caption">recursion_limit 2 difference</p>
  </td>
</tr>
</table>

<p>The next three images show the effect of <code>error_bound</code>. In scenes without light sources, this is even more important than than scenes that do. Good values mostly depend on the scenery and the other settings, lower values do not necessarily lead to better results. Note that we're using our <code>error_bound 0.5</code> image as reference.</p>

<table class="matte" width="700px" cellpadding="0" cellspacing="10px">
<tr>
  <td>
    <img class="leftpanel" width="220px" src="images/4/46/TutImgRadB05.png">
  </td>
  <td>
    <img class="centerpanel" width="220px" src="images/c/c2/TutImgRadB06.png">
  </td>
  <td>
    <img class="rightpanel" width="220px" src="images/9/96/TutImgRadB07.png">
  </td>
</tr>
<tr>
  <td>
    <p class="caption">error_bound 0.01</p>
  </td>
  <td>
    <p class="caption">error_bound 1.0</p>
  </td>
  <td>
    <p class="caption">error_bound 1.8</p>
  </td>
</tr>
<tr>
  <td>
    <img class="leftpanel" width="220px" src="images/2/23/TutImgRadB0205.png">
  </td>
  <td>
    <img class="centerpanel" width="220px" src="images/4/40/TutImgRadB0206.png">
  </td>
  <td>
    <img class="rightpanel" width="220px" src="images/6/64/TutImgRadB0207.png">
  </td>
</tr>
<tr>
  <td>
    <p class="caption">error_bound 0.01 difference</p>
  </td>
  <td>
    <p class="caption">error_bound 1.0 difference</p>
  </td>
  <td>
    <p class="caption">error_bound 1.8 difference</p>
  </td>
</tr>
</table>

<p>If there are artifacts it often helps to increase <code>count</code>, it does affect quality in general and often helps removing them, the following three images use <code>error_bound 0.2</code>.</p>

<table class="matte" width="700px" cellpadding="0" cellspacing="10px">
<tr>
  <td>
    <img class="leftpanel" width="220px" src="images/2/2c/TutImgRadB09.png">
  </td>
  <td>
    <img class="centerpanel" width="220px" src="images/2/2a/TutImgRadB08.png">
  </td>
  <td>
    <img class="rightpanel" width="220px" src="images/5/55/TutImgRadB10.png">
  </td>
</tr>
<tr>
  <td>
    <p class="caption">count 2</p>
  </td>
  <td>
    <p class="caption">count 50</p>
  </td>
  <td>
    <p class="caption">count 200</p>
  </td>
</tr>
<tr>
  <td>
    <img class="leftpanel" width="220px" src="images/6/6e/TutImgRadB0809.png">
  </td>
  <td>
  </td>
  <td>
    <img class="rightpanel" width="220px" src="images/1/1a/TutImgRadB0810.png">
  </td>
</tr>
<tr>
  <td>
    <p class="caption">count 35 difference</p>
  </td>
  <td>
  </td>
  <td>
    <p class="caption">count 150 difference</p>
  </td>
</tr>
</table>

<p>As can be seen upon closer inspection however, this is no magic cure-all, some bright speckles remain even with extremely high <code>count</code> values.</p>

<p>In this case, the reason is that the pretrace is simply too short to provide the number of samples we aim for. This is a job for <code>pretrace_end</code>: Together with <code>pretrace_start</code> it specifies how many pretrace steps are done, and how high their resolution is. Lower values of <code>pretrace_end</code> lead to more pretrace steps and more accurate results but also to significantly slower rendering.</p>

<p>We're still using <code>error_bound 0.1</code> for these images.</p>

<table class="matte" width="700px" cellpadding="0" cellspacing="10px">
<tr>
  <td>
    <img class="leftpanel" width="220px" src="images/e/e9/TutImgRadB11.png">
  </td>
  <td>
    <img class="centerpanel" width="220px" src="images/2/2a/TutImgRadB08.png">
  </td>
  <td>
    <img class="rightpanel" width="220px" src="images/a/ab/TutImgRadB12.png">
  </td>
</tr>
<tr>
  <td>
    <p class="caption">pretrace_end 0.4</p>
  </td>
  <td>
    <p class="caption">pretrace_end 0.01</p>
  </td>
  <td>
    <p class="caption">pretrace_end 0.001</p>
  </td>
</tr>
<tr>
  <td>
    <img class="leftpanel" width="220px" src="images/c/c4/TutImgRadB0811.png">
  </td>
  <td>
  </td>
  <td>
    <img class="rightpanel" width="220px" src="images/4/43/TutImgRadB0812.png">
  </td>
</tr>
<tr>
  <td>
    <p class="caption">pretrace_end 0.4 difference</p>
  </td>
  <td>
  </td>
  <td>
    <p class="caption">pretrace_end 0.001 difference</p>
  </td>
</tr>
</table>

<p>This next sequence shows the effect of <code>nearest_count</code>, the difference is not very strong, but larger values always lead to better results, the maximum is 20. We'll be using <code>error_bound 0.5</code> again, but also the following modifications to emphasize the effect.</p>

<ul>
<li> <code>recursion_limit 1</code></li>
<li> <code>low_error_factor 1.0</code></li>
<li> <code>pretrace_end 0.001</code></li>
</ul>
<p class="Note"><strong>Note:</strong> From now on we'll stick to these values.</p>

<table class="matte" width="700px" cellpadding="0" cellspacing="10px">
<tr>
  <td>
    <img class="leftpanel" width="220px" src="images/a/ad/TutImgRadB14.png">
  </td>
  <td>
    <img class="centerpanel" width="220px" src="images/3/3a/TutImgRadB15.png">
  </td>
  <td>
    <img class="rightpanel" width="220px" src="images/4/49/TutImgRadB16.png">
  </td>
</tr>
<tr>
  <td>
    <p class="caption">nearest_count 2</p>
  </td>
  <td>
    <p class="caption">nearest_count 5 (default)</p>
  </td>
  <td>
    <p class="caption">nearest_count 20</p>
  </td>
</tr>
<tr>
  <td>
    <img class="leftpanel" width="220px" src="images/f/f3/TutImgRadB1314.png">
  </td>
  <td>
    <img class="centerpanel" width="220px" src="images/8/82/TutImgRadB1315.png">
  </td>
  <td>
    <img class="rightpanel" width="220px" src="images/4/44/TutImgRadB1316.png">
  </td>
</tr>
<tr>
  <td>
    <p class="caption">nearest_count 2 difference</p>
  </td>
  <td>
    <p class="caption">nearest_count 5 difference</p>
  </td>
  <td>
    <p class="caption">nearest_count 20 difference</p>
  </td>
</tr>
</table>

<p>The <code>minimum_reuse</code> is a geometric value related to the size of the render in pixels and affects whether previous radiosity calculations are reused at a new point. Lower values lead to more often and therefore more accurate calculations, but care must be taken to balance this setting with the others. The <code>minimum_reuse 0.05</code> was used for the comparison.</p>

<table class="matte" width="700px" cellpadding="0" cellspacing="10px">
<tr>
  <td>
    <img class="leftpanel" width="220px" src="images/1/18/TutImgRadB17.png">
  </td>
  <td>
    <img class="centerpanel" width="220px" src="images/1/12/TutImgRadB13.png">
  </td>
  <td>
    <img class="rightpanel" width="220px" src="images/5/5e/TutImgRadB18.png">
  </td>
</tr>
<tr>
  <td>
    <p class="caption">minimum_reuse 0.1</p>
  </td>
  <td>
    <p class="caption">minimum_reuse 0.05 (default)</p>
  </td>
  <td>
    <p class="caption">minimum_reuse 0.015</p>
  </td>
</tr>
<tr>
  <td>
    <img class="leftpanel" width="220px" src="images/6/6c/TutImgRadB1317.png">
  </td>
  <td>
  </td>
  <td>
    <img class="rightpanel" width="220px" src="images/d/d1/TutImgRadB1318.png">
  </td>
</tr>
<tr>
  <td>
    <p class="caption">minimum_reuse 0.1 difference</p>
  </td>
  <td>
  </td>
  <td>
    <p class="caption">minimum_reuse 0.015 difference</p>
  </td>
</tr>
</table>

<p>In most cases it is not necessary to change the <code>low_error_factor</code>. This setting reduces the <code>error_bound</code> value during the final pretrace step. Changing this value can sometimes help to remove persistent artifacts.</p>

<table class="matte" width="700px" cellpadding="0" cellspacing="10px">
<tr>
  <td>
    <img class="leftpanel" width="220px" src="images/a/a1/TutImgRadB19.png">
  </td>
  <td>
    <img class="centerpanel" width="220px" src="images/1/12/TutImgRadB13.png">
  </td>
  <td>
    <img class="rightpanel" width="220px" src="images/6/65/TutImgRadB20.png">
  </td>
</tr>
<tr>
  <td>
    <p class="caption">low_error_factor 0.01</p>
  </td>
  <td>
    <p class="caption">low_error_factor 0.5 (default)</p>
  </td>
  <td>
    <p class="caption">low_error_factor 1.0</p>
  </td>
</tr>
<tr>
  <td>
    <img class="leftpanel" width="220px" src="images/1/14/TutImgRadB1319.png">
  </td>
  <td>
  </td>
  <td>
    <img class="rightpanel" width="220px" src="images/7/75/TutImgRadB1320.png">
  </td>
</tr>
<tr>
  <td>
    <p class="caption">low_error_factor 0.01 difference</p>
  </td>
  <td>
  </td>
  <td>
    <p class="caption">low_error_factor 1.0 difference</p>
  </td>
</tr>
</table>

<p>The <code>gray_threshold</code> setting reduces the color in the radiosity calculations. As mentioned above the blue sky affects the color of the whole scene when radiosity is calculated.  To reduce this coloring effect without affecting radiosity in general you can increase <code>gray_threshold</code>.  A value of 1.0 means no color in radiosity at all.</p>

<table class="matte" width="700px" cellpadding="0" cellspacing="10px">
<tr>
  <td>
    <img class="leftpanel" width="220px" src="images/1/12/TutImgRadB13.png">
  </td>
  <td>
    <img class="centerpanel" width="220px" src="images/b/be/TutImgRadB21.png">
  </td>
  <td>
    <img class="rightpanel" width="220px" src="images/3/34/TutImgRadB22.png">
  </td>
</tr>
<tr>
  <td>
    <p class="caption">gray_threshold 0.0 (default)</p>
  </td>
  <td>
    <p class="caption">gray_threshold 0.5</p>
  </td>
  <td>
    <p class="caption">gray_threshold 1.0</p>
  </td>
</tr>
</table>

<p>It is worth experimenting with the things affecting radiosity to get some feeling for how things work. The next 3 images show some more experiments. We're back with the original reference settings from now on.</p>

<table class="matte" width="700px" cellpadding="0" cellspacing="10px">
<tr>
  <td>
    <img class="leftpanel" width="220px" src="images/f/ff/TutImgRadB23.png">
  </td>
  <td>
    <img class="centerpanel" width="220px" src="images/f/fb/TutImgRadB24.png">
  </td>
  <td>
    <img class="rightpanel" width="220px" src="images/c/ce/TutImgRadB25.png">
  </td>
</tr>
<tr>
  <td>
    <p class="caption">emission 3 for two objects</p>
  </td>
  <td>
    <p class="caption">all objects emission 0.3 sky is 0</p>
  </td>
  <td>
    <p class="caption">emission -3 for one object</p>
  </td>
</tr>
</table>

<p>Finally you can strongly change the appearance of the whole scene with the sky's texture.  The following images give some examples.</p>

<table class="matte" width="700px" cellpadding="0" cellspacing="10px">
<tr>
  <td>
    <img class="leftpanel" width="220px" src="images/c/c7/TutImgRadB26.png">
  </td>
  <td>
    <img class="centerpanel" width="220px" src="images/e/e6/TutImgRadB27.png">
  </td>
  <td>
    <img class="rightpanel" width="220px" src="images/8/8f/TutImgRadB28.png">
  </td>
</tr>
<tr>
  <td>
    <p class="caption">rgb &lt;1,0.8,0&gt; to blue gradient</p>
  </td>
  <td>
    <p class="caption">light-dark gradient left-right</p>
  </td>
  <td>
    <p class="caption">light-dark gradient bottom-top</p>
  </td>
</tr>
</table>
<p></p>
<table class="matte" width="700px" cellpadding="0" cellspacing="10">
<tr>
  <td>
    <p class="tabletext">Really good results mostly depend on the single situation and how the scene is meant to look. We used these settings listed below, to get this example of a <em>higher quality</em> render of our test object. It's important to remember that requirements can be much different from scene to scene.</p>
  <td>
    <img class="right" width="320px" src="images/a/a5/TutImgRadB29.png">
  </td>
</tr>
<tr>
  <td>
  </td>
  <td>
    <p class="caption">higher quality radiosity scene</p>
  </td>
</tr>
</table>

<pre>
  global_settings {
    radiosity {
      pretrace_start 0.128
      pretrace_end   0.002
      count 500
      nearest_count 20
      error_bound 0.5
      recursion_limit 2
      low_error_factor 1.0
      gray_threshold 0.0
      minimum_reuse 0.005
      maximum_reuse 0.1
      brightness 1
      adc_bailout 0.005
    }
  }
</pre>

</div>
<a name="t2_3_8_4"></a>
<div class="content-level-h4" contains="Normals and Radiosity" id="t2_3_8_4">
<h4>2.3.8.4 Normals and Radiosity</h4>
<p>When using a <a href="r3_4.html#r3_4_4_3_4_4">normal</a>  statement in combination with radiosity lighting, you will see that the shadowed parts of the objects are totally smooth, no matter how strong the normals are made. The reason is that POV-Ray by default does not take the normal into account when calculating radiosity. You can easily change this by adding <code>normal on</code> to the radiosity block. Be aware that this can slow things down quite a bit and will require more memory, however it usually leads to more realistic results.</p>

<p>When using normals you should also remember that they are only faked irregularities and do not generate real geometric disturbances of the surface. A more realistic approach is using an <a href="r3_4.html#r3_4_5_1_6">isosurface</a> with a pigment function, but this can quickly lead to increased render times.</p>
<p>As you can see with this next series of images, the isosurface version does not have the same smooth-like appearance to it's circumference, as compared to the first two images. Notice that it also has a more realistic shadow-line.</p>

<table class="matte" width="700px" cellpadding="0" cellspacing="10px">
<tr>
  <td>
    <img class="leftpanel" width="220px" src="images/8/85/TutImgRadC_01.jpg">
  </td>
  <td>
    <img class="centerpanel" width="220px" src="images/c/cc/TutImgRadC_02.jpg">
  </td>
  <td>
    <img class="rightpanel" width="220px" src="images/c/c4/TutImgRadC_03.jpg">
  </td>
</tr>
<tr>
  <td>
    <p class="caption">normal off (default)</p>
  </td>
  <td>
    <p class="caption">normal on</p>
  </td>
  <td>
    <p class="caption">isosurface</p>
  </td>
</tr>
</table>

</div>
<a name="t2_3_8_5"></a>
<div class="content-level-h4" contains="Performance considerations" id="t2_3_8_5">
<h4>2.3.8.5 Performance considerations</h4>
<p>High quality radiosity can be very slow. To some extent this is the price to pay for realistic lighting, but there are a lot of things that can be done to improve speed.</p>

<p>If average to good quality radiosity will work for your scene, then it's probably a good idea to spend the time to find the <em>sweet spot</em> that strikes the best balance between quality and speed.  Especially <code>recursion_limit</code> should be kept as low as possible. Sometimes <code>1</code> is sufficient, if not <code>2</code> or <code>3</code> should often be enough.</p>

<p>With high quality settings, radiosity data can take quite a lot of memory. Apart from that the other scene data is also used much more intensively than in a conventional scene. Therefore insufficient memory and swapping can slow down things even more. Here's a few <a href="r3_2.html#r3_2_8_8">radiosity options</a> that might help.</p>

<p>Finally the scene geometry and textures are important too. Objects not visible in the camera usually only increase parsing time and memory use, but in a radiosity scene, also objects behind the camera can slow down the rendering process. See the section <a href="r3_4.html#r3_4_4_3_4">Configuring Radiosity</a> for some helpful hints.</p>

</div>
<a name="t2_3_9"></a>
<div class="content-level-h3" contains="Making Animations" id="t2_3_9">
<h3>2.3.9 Making Animations</h3>
<p>There are a number of programs available that will take a series of still
image files (such as POV-Ray outputs) and assemble them into animations. Such
programs can produce AVI, MPEG, FLI/FLC, QuickTime, or even animated GIF
files (for use on the World Wide Web). The trick, therefore, is how to
produce the frames. That, of course, is where POV-Ray comes in. In earlier
versions producing an animation series was no joy, as everything had to be
done manually. We had to set the clock variable, and handle producing unique
file names for each individual frame by hand. We could achieve some degree of
automation by using batch files or similar scripting devices, but still, We
had to set it all up by hand, and that was a lot of work (not to mention
frustration... imagine forgetting to set the individual file names and coming
back 24 hours later to find each frame had overwritten the last).</p>
<p>
Now, at last, with POV-Ray 3, there is a better way. We no longer need a
separate batch script or external sequencing programs, because a few simple
settings in our INI file (or on the command line) will activate an internal
animation sequence which will cause POV-Ray to automatically handle the
animation loop details for us.</p>
<p>
Actually, there are two halves to animation support: those settings we put
in the INI file (or on the command line), and those code modifications we
work into our scene description file. If we have already worked with
animation in previous versions of POV-Ray, we can probably skip ahead to the
section <a href="t2_3.html#t2_3_9_5">INI File Settings</a> below. Otherwise, let's start with
basics. Before we get to how to activate the internal animation loop,
let's look at a couple examples of how a couple of keywords can set up
our code to describe the motions of objects over time.</p>

</div>
<a name="t2_3_9_1"></a>
<div class="content-level-h4" contains="The Clock Variable: Key To It All" id="t2_3_9_1">
<h4>2.3.9.1 The Clock Variable: Key To It All</h4>
<p>POV-Ray supports an automatically declared floating point variable
identified as <code><a href="r3_3.html#r3_3_1_5_6">clock</a></code> (all lower case). This is the key to making
image files that can be automated. In command line operations, the clock
variable is set using the <code>+k</code> switch. For example, <code>
+k3.4</code> from the command line would set the value of clock to 3.4. The
same could be accomplished from the INI file using <code>Clock=3.4</code> in
an INI file.</p>
<p>
If we do not set clock for anything, and the animation loop is not used
(as will be described a little later) the clock variable is still there -
it is just set for the default value of 0.0, so it is possible to set up
some POV code for the purpose of animation, and still render it as a still
picture during the object/world creation stage of our project.</p>
<p>
The simplest example of using this to our advantage would be having an
object which is travelling at a constant rate, say, along the x-axis. We
would have the statement</p>
<pre>
  translate &lt;clock, 0, 0&gt;
</pre>

<p>in our object's declaration, and then have the animation loop assign
progressively higher values to clock. And that is fine, as long as only
one element or aspect of our scene is changing, but what happens when we want
to control multiple changes in the same scene simultaneously?</p>
<p>
The secret here is to use normalized clock values, and then make other
variables in your scene proportional to clock. That is, when we set up our
clock, (we are getting to that, patience!) have it run from 0.0 to 1.0,
and then use that as a multiplier to some other values. That way, the other
values can be whatever we need them to be, and clock can be the same 0 to 1
value for every application. Let's look at a (relatively) simple
example</p>
<pre>
  #include &quot;colors.inc&quot;
  camera {
    location &lt;0, 3, -6&gt;
    look_at &lt;0, 0, 0&gt;
  }
  light_source { &lt;20, 20, -20&gt; color White }
  plane {
    y, 0
    pigment { checker color White color Black }
  }
  sphere {
    &lt;0, 0, 0&gt; , 1
    pigment {
      gradient x
      color_map {
        [0.0 Blue  ]
        [0.5 Blue  ]
        [0.5 White ]
        [1.0 White ]
      }
      scale .25
    }
    rotate &lt;0, 0, -clock*360&gt;
    translate &lt;-pi, 1, 0&gt;
    translate &lt;2*pi*clock, 0, 0&gt;
  }
</pre>

<p>Assuming that a series of frames is run with the clock progressively going
from 0.0 to 1.0, the above code will produce a striped ball which rolls from
left to right across the screen. We have two goals here:</p>
<ol>
<li>Translate the ball from point A to point B, and,</li>
<li>Rotate the ball in exactly the right proportion to its linear movement to
imply that it is rolling -- not gliding -- to its final position.</li>
</ol>
<p>Taking the second goal first, we start with the sphere at the origin,
because anywhere else and rotation will cause it to orbit the origin instead
of rotating. Throughout the course of the animation, the ball will turn one
complete 360 degree turn. Therefore, we used the formula, <code>360*clock</code>
to determine the rotation in each frame. Since clock runs 0 to 1, the rotation
of the sphere runs from 0 degrees through 360.</p>
<p>
Then we used the first translation to put the sphere at its initial starting
point. Remember, we could not have just declared it there, or it would
have orbited the origin, so before we can meet our other goal (translation),
we have to compensate by putting the sphere back where it would have been at
the start. After that, we re-translate the sphere by a clock relative
distance, causing it to move relative to the starting point. We have chosen
the formula of 2*pi* r*clock (the widest circumference of the sphere times
current clock value) so that it will appear to move a distance equal to the
circumference of the sphere in the same time that it rotates a complete 360
degrees. In this way, we have synchronized the rotation of the sphere to
its translation, making it appear to be smoothly rolling along the plane.</p>
<p>
Besides allowing us to coordinate multiple aspects of change over time more
cleanly, mathematically speaking, the other good reason for using normalized
clock values is that it will not matter whether we are doing a ten frame
animated GIF, or a three hundred frame AVI. Values of the clock are
proportioned to the number of frames, so that same POV code will work without
regard to how long the frame sequence is. Our rolling ball will still travel
the exact same amount no matter how many frames our animation ends up
with.</p>

</div>
<a name="t2_3_9_2"></a>
<div class="content-level-h4" contains="Clock Dependant Variables And Multi-Stage Animations" id="t2_3_9_2">
<h4>2.3.9.2 Clock Dependant Variables And Multi-Stage Animations</h4>
<p>Okay, what if we wanted the ball to roll left to right for the first half
of the animation, then change direction 135 degrees and roll right to left,
and toward the back of the scene. We would need to make use of POV-Ray's
new conditional rendering directives, and test the clock value to determine
when we reach the halfway point, then start rendering a different clock
dependant sequence. But our goal, as above, it to be working in each stage
with a variable in the range of 0 to 1 (normalized) because this makes the
math so much cleaner to work with when we have to control multiple aspects
during animation. So let's assume we keep the same camera, light, and
plane, and let the clock run from 0 to 2! Now, replace the single sphere
declaration with the following...</p>
<pre>
  #if ( clock &lt;= 1 )
    sphere { &lt;0, 0, 0&gt; , 1
      pigment {
        gradient x
        color_map {
          [0.0 Blue  ]
          [0.5 Blue  ]
          [0.5 White ]
          [1.0 White ]
        }
        scale .25
      }
      rotate &lt;0, 0, -clock*360&gt;
      translate &lt;-pi, 1, 0&gt;
      translate &lt;2*pi*clock, 0, 0&gt;
    }
  #else
    // (if clock is &gt; 1, we're on the second phase)
    // we still want to work with  a value from 0 - 1
    #declare ElseClock = clock - 1;
    sphere { &lt;0, 0, 0&gt; , 1
      pigment {
        gradient x
        color_map {
          [0.0 Blue  ]
          [0.5 Blue  ]
          [0.5 White ]
          [1.0 White ]
        }
        scale .25
      }
      rotate &lt;0, 0, ElseClock*360&gt;
      translate &lt;-2*pi*ElseClock, 0, 0&gt;
      rotate &lt;0, 45, 0&gt;
      translate &lt;pi, 1, 0&gt;
    }
  #end
</pre>

<p>If we spotted the fact that this will cause the ball to do an unrealistic
<em>snap turn</em> when changing direction, bonus points for us - we are a
born animator. However, for the simplicity of the example, let's ignore
that for now. It will be easy enough to fix in the real world, once we
examine how the existing code works.</p>
<p>
All we did differently was assume that the clock would run 0 to 2, and that
we wanted to be working with a normalized value instead. So when the clock
goes over 1.0, POV assumes the second phase of the journey has begun, and we
declare a new variable <code>Elseclock</code> which we make relative to the
original built in clock, in such a way that while clock is going 1 to 2,
Elseclock is going 0 to 1. So, even though there is only one <code>
clock</code>, there can be as many additional variables as we care to declare
(and have memory for), so even in fairly complex scenes, the single clock
variable can be made the common coordinating factor which orchestrates all
other motions.</p>

</div>
<a name="t2_3_9_3"></a>
<div class="content-level-h4" contains="The Phase Keyword" id="t2_3_9_3">
<h4>2.3.9.3 The Phase Keyword</h4>
<p>There is another keyword we should know for purposes of animations: the
<code><a href="r3_4.html#r3_4_7_5_2">phase</a></code> keyword. The phase keyword can be used on many texture
elements, especially those that can take a color, pigment, normal or texture
map. Remember the form that these maps take. For example:</p>
<pre>
  color_map {
    [0.00 White ]
    [0.25 Blue ]
    [0.76 Green ]
    [1.00 Red ]
  }
</pre>

<p>The floating point value to the left inside each set of brackets helps
POV-Ray to map the color values to various areas of the object being
textured. Notice that the map runs cleanly from 0.0 to 1.0?</p>
<p>
Phase causes the color values to become shifted along the map by a floating
point value which follows the keyword <code>phase</code>. Now, if we are
using a normalized clock value already anyhow, we can make the variable clock
the floating point value associated with phase, and the pattern will smoothly
shift over the course of the animation. Let's look at a common example
using a gradient normal pattern</p>
<pre>
  #include &quot;colors.inc&quot;
  #include &quot;textures.inc&quot;
  background { rgb&lt;0.8, 0.8, 0.8&gt; }
  camera {
    location &lt;1.5, 1, -30&gt;
    look_at &lt;0, 1, 0&gt;
    angle 10
  }
  light_source { &lt;-100, 20, -100&gt; color White }
  // flag
  polygon {
    5, &lt;0, 0&gt;, &lt;0, 1&gt;, &lt;1, 1&gt;, &lt;1, 0&gt;, &lt;0, 0&gt;
    pigment { Blue }
    normal {
      gradient x
      phase clock
      scale &lt;0.2, 1, 1&gt;
      sine_wave
    }
    scale &lt;3, 2, 1&gt;
    translate &lt;-1.5, 0, 0&gt;
  }
  // flagpole
  cylinder {
    &lt;-1.5, -4, 0&gt;, &lt;-1.5, 2.25, 0&gt;, 0.05
    texture { Silver_Metal }
  }
  // polecap
  sphere {
    &lt;-1.5, 2.25, 0&gt;, 0.1
    texture { Silver_Metal }
  }
</pre>

<p>Now, here we have created a simple blue flag with a gradient normal
pattern on it. We have forced the gradient to use a sine-wave type wave so
that it looks like the flag is rolling back and forth as though flapping in a
breeze. But the real magic here is that phase keyword. It has been set to
take the clock variable as a floating point value which, as the clock
increments slowly toward 1.0, will cause the crests and troughs of the
flag's wave to shift along the x-axis. Effectively, when we animate the
frames created by this code, it will look like the flag is actually rippling
in the wind.</p>
<p>
This is only one, simple example of how a clock dependant phase shift can
create interesting animation effects. Trying phase will all sorts of texture
patterns, and it is amazing the range of animation effects we can create
simply by phase alone, without ever actually moving the object.</p>

</div>


<a name="t2_3_9_4"></a>
<div class="content-level-h4" contains="Do Not Use Jitter Or Crand" id="t2_3_9_4">
<h4>2.3.9.4 Do Not Use Jitter Or Crand</h4>
<p> One last piece of basic information to save frustration. Because jitter
is an element of anti-aliasing, we could just as easily have mentioned this
under the INI file settings section, but there are also forms of
anti-aliasing used in area lights, and the new atmospheric effects of
POV-Ray, so now is as good a time as any.</p>
<p>
<a href="r3_4.html#r3_4_4_1_5">Jitter</a> is a very small amount of random ray perturbation designed to diffuse
tiny aliasing errors that might not otherwise totally disappear, even with
intense anti-aliasing. By randomizing the placement of erroneous pixels, the
error becomes less noticeable to the human eye, because the eye and mind are
naturally inclined to look for regular patterns rather than random
distortions.</p>
<p>
This concept, which works fantastically for still pictures, can become a
nightmare in animations. Because it is random in nature, it will be different
for each frame we render, and this becomes even more severe if we dither the
final results down to, say 256 color animations (such as FLC's). The
result is jumping pixels all over the scene, but especially concentrated any
place where aliasing would normally be a problem (e.g., where an infinite
plane disappears into the distance).</p>
<p>
For this reason, we should always set jitter to <code>off</code> in area
lights and anti-aliasing options when preparing a scene for an animation. The
(relatively) small extra measure quality due to the use of jitter will be
offset by the ocean of jumpies that results. This general rule also applies
to any truly random texture elements, such as <code><a href="r3_4.html#r3_4_6_3_3_3">crand</a></code>.</p>

</div>
<a name="t2_3_9_5"></a>
<div class="content-level-h4" contains="INI File Settings" id="t2_3_9_5">
<h4>2.3.9.5 INI File Settings</h4>
<p>Okay, so we have a grasp of how to code our file for animation. We know
about the clock variable, user declared clock-relative variables, and the
phase keyword. We know not to jitter or crand when we render a scene, and
we are all set build some animations. Alright, let's have at it.</p>
<p>
The first concept we will need to know is the INI file settings,
<code><a href="r3_2.html#r3_2_1_2">Initial_Frame</a></code> and
<code><a href="r3_2.html#r3_2_1_2">Final_Frame</a></code>. These are very handy
settings that will allow us to render a particular number of frames and each
with its own unique frame number, in a completely hands free way. It is of
course, so blindingly simple that it barely needs explanation, but here is
an example anyway. We just add the following lines to our favorite INI file
settings</p>
<pre>
  Initial_Frame = 1
  Final_Frame = 20
</pre>

<p>and we will initiate an automated loop that will generate 20 unique
frames. The settings themselves will automatically append a frame number onto
the end of whatever we have set the output file name for, thus giving each
frame an unique file number without having to think about it. Secondly, by
default, it will cycle the clock variable up from 0 to 1 in increments
proportional to the number of frames. This is very convenient, since, no
matter whether we are making a five frame animated GIF or a 300 frame MPEG
sequence, we will have a clock value which smoothly cycles from exactly the
same start to exactly the same finish.</p>
<p>
Next, about that clock. In our example with the rolling ball code, we saw
that sometimes we want the clock to cycle through values other than the
default of 0.0 to 1.0. Well, when that is the case, there are setting for
that too. The format is also quite simple. To make the clock run, as in our
example, from 0.0 to 2.0, we would just add to your INI file the lines</p>
<code>
<a href="r3_2.html#r3_2_1_2">Initial_Clock</a> = 0.0<br>
<a href="r3_2.html#r3_2_1_2">Final_Clock</a> = 2.0<br>
</code>

<p>Now, suppose we were developing a sequence of 100 frames, and we detected
a visual glitch somewhere in frames, say 51 to 75. We go back over our code
and we think we have fixed it. We would like to render just those 25 frames
instead of redoing the whole sequence from the beginning. What do we
change?</p>
<p>
If we said make <code>Initial_Frame = 51</code>, and <code>Final_Frame =
75</code>, we are wrong. Even though this would re-render files named with
numbers 51 through 75, they will not properly fit into our sequence, because
the clock will begin at its initial value starting with frame 51, and cycle
to final value ending with frame 75. The only time <code>Initial_Frame</code>
and <code>Final_Frame</code> should change is if we are doing an essentially
new sequence that will be appended onto existing material.</p>
<p>
If we wanted to look at just 51 through 75 of the original animation, we
need two new INI settings</p>
<code>
<a href="r3_2.html#r3_2_1_3">Subset_Start_Frame</a> = 51<br>
<a href="r3_2.html#r3_2_1_3">Subset_End_Frame</a> = 75<br>
</code>

<p>Added to settings from before, the clock will still cycle through its
values proportioned from frames 1 to 100, but we will only be rendering that
part of the sequence from the 51st to the 75th frames.</p>
<p>
This should give us a basic idea of how to use animation. Although, this
introductory tutorial does not cover all the angles. For example, the last
two settings we just saw, subset animation, can take fractional values, like
0.5 to 0.75, so that the number of actual frames will not change what portion
of the animation is being rendered. There is also support for efficient
odd-even field rendering as would be useful for animations prepared for
display in interlaced playback such as television (see the reference section
for full details).</p>
<p>
With POV-Ray 3 now fully supporting a complete host of animation options, a
whole fourth dimension is added to the raytracing experience. Whether we are
making a FLIC, AVI, MPEG, or simply an animated GIF for our web site,
animation support takes a lot of the tedium out of the process. And do not
forget that phase and clock can be used to explore the range of numerous
texture elements, as well as some of the more difficult to master objects
(hint: the julia fractal for example). So even if we are completely content
with making still scenes, adding animation to our repertoire can greatly
enhance our understanding of what POV-Ray is capable of. Adventure
awaits!</p>

</div>
<a name="t2_3_10"></a>
<div class="content-level-h3" contains="While-loop tutorial" id="t2_3_10">
<h3>2.3.10 While-loop tutorial</h3>
<p>Usually people who have never programmed have great difficulties understanding how simple while-loops work and how they should be used. When you get into nested loops, the problem is even worse.</p>
<p>Sometimes even people who have programmed a bit with some language get confused with POV-Ray's while-loops. This usually happens when they have only used a for-loop which in itself has an index variable which is often incremented automatically.</p>

</div>
<a name="t2_3_10_1"></a>
<div class="content-level-h4" contains="What a while-loop is and what it is not" id="t2_3_10_1">
<h4>2.3.10.1 What a while-loop is and what it is not</h4>
<p>A while-loop in POV-Ray is just a control structure which tells POV-Ray to repeat a command block while the specified condition is true.</p>
<p>The while-loop syntax is as follows:</p>
<pre>
#while(condition)
  ...
#end
</pre>
<p>The commands between <code>#while</code> and <code>#end</code> are run over and over as long as the condition evaluates to true.</p>
<p>A while-loop <strong>is not</strong> a for-loop nor any kind of loop which has an index variable that may be incremented automatically with each iteration.</p>
<p>The while loop <strong>does not</strong> care what the conditions are between the parentheses as long as they evaluate to some value, nor what the block between <code>#while</code> and <code>#end</code> contains. It will just execute that block until the condition becomes false.</p>
<p>The while-loop does not do anything else. You can think of it as a &quot;simple&quot; loop, which does not do anything automatically. This is not necessarily a bad thing.</p>

</div>
<a name="t2_3_10_2"></a>
<div class="content-level-h4" contains="How does a single while-loop work?" id="t2_3_10_2">
<h4>2.3.10.2 How does a single while-loop work?</h4>
<p>The while loop works like this:</p>
<ol>
<li>If the condition between the parentheses evaluates to false, jump to the command after the <code>#end</code> statement. If the condition evaluates to true, just continue normally.</li>
<li>At the <code>#end</code> statement jump to the <code>#while</code> statement and start again.</li>
</ol>
<p>That is:</p>
<ul>
<li>When POV-Ray gets to the <code>#while</code> statement it evaluates the condition between parentheses.</li>
<li>If the statement evaluated as true then it will just continue normally with the next command.</li>
<li>If the statement evaluated as false, POV-Ray will skip the entire body of the loop and continue with the command after the <code>#end</code> statement.</li>
<li>At an <code>#end</code> statement POV-Ray will just jump back to the corresponding <code>#while</code> statement, and will conditionally execute the commands, if the condition evaluates true.</li>
</ul>
<p>Note that nowhere there is any mention about any index variable or anything else that could be used to automatically end the loop. As said, it is just a &quot;simple&quot; loop that continues forever if necessary, only testing the statement between the parentheses, and it is not interested in what it is, only in its evaluated value.</p>
<p>Although one could easily think that this kind of simple loop is bad, and it should be more intelligent, the fact is that this kind of simple loop is actually a lot more flexible and versatile. It allows you to make things not possible or very difficult to do with an intelligent for-loop with automatic index variables.</p>

</div>
<a name="t2_3_10_3"></a>
<div class="content-level-h4" contains="How do I make a while-loop?" id="t2_3_10_3">
<h4>2.3.10.3 How do I make a while-loop?</h4>
<p>It depends on what you are trying to accomplish.</p>
<p>The most common usage is to use it as a simple for-loop, that is, a loop which loops a certain number of times, with an index value getting successive values (for example 1, 2, 3, ..., 10).</p>
<p>For this you need to first declare your index identifier with the first value.</p>
<pre>
#declare Index = 1;
</pre>
<p>If you want to loop 10 times, remember how the condition worked: The while-loop repeats as long as the condition is true. So it should loop as long as our 'Index' identifier is less or equal to 10</p>
<pre>
#while(Index &lt;= 10)
</pre>
<p>When the value of 'Index' is 11 the loop ends, as it should.</p>
<p>We only have to add 1 to 'Index' at the end of each loop</p>
<pre>
#declare Index = 1;
#while(Index &lt;= 10)

  (some commands here)

  #declare Index = Index + 1;
#end
</pre>
<p>The incrementation before the <code>#end</code> is important. If we do not do it, 'Index' would always have the value 1 and the loop would go forever since 1 is always less or equal to 10.</p>
<p>What happens here?</p>
<ol>
<li>First POV-Ray sets the value 1 to 'Index'.</li>
<li>Then it sees the <code>#while</code> statement and evaluates what is between the parentheses: Index &lt;= 10</li>
<li>As 'Index' has the value of 1 and 1 &lt;= 10, the condition evaluates to true.</li>
<li>So, it just continues normally, and executes the commands following the <code>#while</code> statement, as noted in the above example as (some commands here).</li>
<li>Then it arrives normally to the last #declare command in the block. This causes the value 2 to be assigned to 'Index'.</li>
<li>Now it arrives the the <code>#end</code> command and so it just jumps to the <code>#while</code>.</li>
<li>After that it executes the steps 2-6 again because 2 is also less or equal to 10.</li>
<li>After this has been done 10 times, the value 11 is assigned to 'Index' in the last command of the block.</li>
<li>Now, when POV-Ray evaluates the condition it sees that it is false, because 11 is not less or equal to 10. This causes POV-Ray to jump to the command after the <code>#end</code> statement.</li>
<li>The net effect of all this is that POV-Ray looped 10 times and the 'Index' variable was assigned successive values from 1 to 10 along the way.</li>
</ol>
<p>If you read carefully the above description you will notice that the looping is done in a quite simple way, that is, there is no higher logic hidden inside the loop structure. In fact, POV-Ray does not have the slightest idea how many times the loop is executed and what variable is used to count the loops. It just follows orders.</p>
<p>The higher logic in this type of loop is in the combination of commands we wrote. The effect of this combination is that the loop works like a simple for-loop in most programming languages (like BASIC, etc).</p>

</div>
<a name="t2_3_10_4"></a>
<div class="content-level-h4" contains="What is a condition and how do I make one?" id="t2_3_10_4">
<h4>2.3.10.4 What is a condition and how do I make one?</h4>
<p>A condition is an expression that evaluates to a boolean value (ie. true or false) and is used in POV-Ray in <code>#while</code> loops and <code>#if</code> statements.</p>
<p>A condition is mainly a comparison between two values, although there are also some other ways of making a condition, that is not important now.</p>
<p>For example:</p>
<pre>
1 &lt; 2  is true
1 &gt; 2  is false
1 = 1  is true
1 = 2  is false
</pre>
<p>Usually it makes no sense to make comparisons like those. However, when comparing identifiers with some value or two identifiers together it starts to be very useful. Consider this:</p>
<pre>
#if(version &lt; 3.1)
  #error &quot;Wrong version!&quot;
#end
</pre>
<p>If the identifier called 'version' has a value which is less than 3.1 the <code>#error</code> line will be executed. If 'version' has a value which is 3.1 or greater, the <code>#error</code> line is just skipped.</p>
<p>You can combine conditions together with the boolean operators &amp; (and) and | (or). You can also invert the value of a condition with ! (not).</p>
<p>For example, if you want something to be done when 'a' is less than 10 <strong>and</strong> 'b' is greater or equal to 20, the condition would be:</p>
<pre>
a&lt;10 &amp; b&gt;=20
</pre>
<p>For more information about these comparison operators, see the <a href="r3_3.html#r3_3_1_5_3">Operators</a> section of the POV-Ray documentation.</p>

</div>
<a name="t2_3_10_5"></a>
<div class="content-level-h4" contains="What about loop types other than simple for-loops?" id="t2_3_10_5">
<h4>2.3.10.5 What about loop types other than simple for-loops?</h4>
<p>As POV-Ray does not care what the condition is and what we are using to make that condition, we can use the while-loop in many other ways.</p>
<p>For example, this is a typical use of the while-loop that is not just a simple for-loop:</p>
<pre>
#declare S = seed(0);
#declare Point = &lt;2*rand(S)-1, 2*rand(S)-1, 2*rand(S)-1&gt;;
#while(vlength(Point) &gt; 1)
  #declare Point = &lt;2*rand(S)-1, 2*rand(S)-1, 2*rand(S)-1&gt;;
#end
</pre>
<p>We take a random point between &lt;-1, -1, -1&gt; and &lt;1, 1, 1&gt; and if it is not inside the unit sphere take another random point in that range until we get a point inside the unit sphere.</p>
<p>This is not an unrealistic example since it is very handy, and we can plainly see, this looks nothing like an ordinary for-loop.</p>
<ul>
<li>It does not have any 'index' value which gets consecutive values during the loop.</li>
<li>We do not know how many times it will loop. In this case it loops a random number of times.</li>
<li>Usually for-loops are used to place or create a series of objects. For each iteration another instance of that object is created. Here, however, we are only interested in the value that results <strong>after</strong> the loop, not the values inside it.</li>
</ul>
<p>As we can see, a while-loop can also be used for a variety of tasks, for instance, to calculate a value or some values until the result is inside a specified range.</p>
<p>By the way, there is a variant of this kind of loop where the task would be to calculate a value until the result is inside a specified range, but make only a certain number of tries. If the value does not get inside that range after that number of tries, stop trying. This is used when there is a possibility for the loop for going on forever.</p>
<p>In the above example about the point inside the unit sphere we do not need this because the random point will surely hit the inside of the sphere at some time. In some other situations, however, we cannot be so sure.</p>
<p>In this case we need a regular index variable to count the number of loops. If we reach a predetermined number of iterations, then we stop.</p>
<p>Suppose that we wanted to modify our point searching program to be completely safe and to try only up to 10 times. If the point does not hit the inside of the sphere after 10 tries, we just give up and use the point &lt;0,0,0&gt;.</p>
<pre>
#declare S = seed(0);
#declare Point = &lt;2*rand(S)-1, 2*rand(S)-1, 2*rand(S)-1&gt;;
#declare Index = 1;
#while(Index &lt;= 10 &amp; vlength(Point) &gt; 1)
  #declare Point = &lt;2*rand(S)-1, 2*rand(S)-1, 2*rand(S)-1&gt;;
  #declare Index = Index + 1;
#end

#if(vlength(Point) &gt; 1)
  #declare Point = &lt;0,0,0&gt;
#end
</pre>
<p>What did we do?</p>
<ul>
<li>We added an 'Index' value which counts the amount of loops gone so far. It is quite similar to the index loop of a simple for-loop.</li>
<li>We added an extra condition to the while-loop: Besides testing that the point is outside the unit sphere it also tests that our index
variable has not bailed out. So now there are two conditions for the loop to continue: The 'Index' value must be less or equal to 10
<strong>and</strong> the 'Point' has to be outside the unit sphere. If either one of them fails, the loop is ended.</li>
<li>Then we check if the point is still outside the unit sphere. If it is, we just take &lt;0,0,0&gt;.</li>
</ul>
<p>Sometimes it is not convenient to make the test again in the <code>#if</code> statement. There is another way of determining whether the loop bailed out without successful termination. Since the loop ends when the 'Index' gets the value 11, we can use this to test the successfulness of the loop</p>
<pre>
#if(Index = 11)
  (loop was not successful)
#end
</pre>

</div>
<a name="t2_3_10_6"></a>
<div class="content-level-h4" contains="What about nested loops?" id="t2_3_10_6">
<h4>2.3.10.6 What about nested loops?</h4>
<p>Even when one masters simple loops, nested loops can be a frightening thing, or at least hard to understand.</p>
<p>Nested loops are used for example in creating a 2D array of objects, that is rows and columns of objects. For example if you want to create a 10x20 array of spheres in your scene, a nested loop is up to the task.</p>
<p>There is nothing special about nested loops. You only have to pay attention to where you initialize and update your index variables.</p>
<p>Let's recall the form of a simple for-loop:</p>
<pre>
#declare Index = initial_value;
#while(Index &lt;= final_value)

  [Something here]

  #declare Index = Index + index_step;
#end
</pre>
<p>The [Something here] part can be anything. If it is another while-loop, then we have nested loops. The inner loop should have the same structure as the outer one.</p>
<p>Note that proper indentation helps us distinguishing between the loops. It is always a good idea to use a good indentation scheme:</p>
<pre>
#declare Index1 = initial_value1;
#while(Index1 &lt;= final_value1)

   #declare Index2 = initial_value2;
   #while(Index2 &lt;= final_value2)

      [Something here]

      #declare Index2 = Index2 + index2_step;
   #end

   #declare Index1 = Index1 + index1_step;
#end
</pre>
<p>It is a common mistake for beginners to break this structure. For example it is common to declare the 'Index2' before the first <code>#while</code>. This breaks the for-loop structure and thus does not work. If you follow step by step what POV-Ray does, as explained earlier, you will see why it does not work. Do not mix the structures of the inner and the outer loops together or your code will simply not work as expected.</p>
<p>So, if we want to make our 10x20 array of spheres, it will look like this:</p>
<pre>
#declare Index1 = 0;
#while(Index1 &lt;= 9)

   #declare Index2 = 0;
   #while(Index2 &lt;= 19)

      sphere { &lt;Index1, Index2, 0&gt;, .5 }

      #declare Index2 = Index2 + 1;
   #end

   #declare Index1 = Index1 + 1;
#end
</pre>
<p>Notice how we now start from 0 and continue to 9 in the outer loop and from 0 to 19 in the inner loop. This has been done to get the sphere array start from the origin, instead of starting from &lt;1, 1, 0&gt;, of course we could have made the 'Index1' and 'Index2' go from 1 to 10 and from 1 to 20 respectively and then created the sphere in this way:</p>
<pre>
  sphere { &lt;Index1-1, Index2-1, 0&gt;, .5 }
</pre>
<p>Although you should not mix the loop structures together, you can perfectly use the values of the outer loop in the inner loop (eg. in its condition). For example, if we wanted to create a triangular array of spheres instead of a rectangular one, that is, we create only half of the spheres, we could have made the inner <code>#while</code> like this:</p>
<pre>
  #while(Index2 &lt; Index1*2)
</pre>
<p>'Index2' will go from 0 to the value of 'Index1' multiplied by 2.</p>
<p>There is no reason why we should limit ourselves to just two nested loops. There is virtually no limit how many loops you can nest. For example, if we wanted to create a box-shape filled by spheres rows, columns and depth, we just make three nested loops, one for the x-axis, another for the y-axis and the third for the z-axis.</p>

</div>
<a name="t2_3_10_7"></a>
<div class="content-level-h4" contains="Mixed-type nested loops" id="t2_3_10_7">
<h4>2.3.10.7 Mixed-type nested loops</h4>
<p>It is perfectly possible to put a for-loop inside a non-for-loop or vice-versa. Again, you just have to be careful, with experience it gets easier.</p>
<p>For example, suppose that we want to create 50 spheres which are randomly placed inside the unit sphere.</p>
<p>So the distinction is clear: First we need a loop to create 50 spheres, a for-loop type suffices, and then we need another loop inside it to calculate the location of the sphere. It will look like this:</p>
<pre>
#declare S = seed(0);
#declare Index = 1;
#while(Index &lt;= 50)

   #declare Point = &lt;2*rand(S)-1, 2*rand(S)-1, 2*rand(S)-1&gt;;
   #while(vlength(Point) &gt; 1)
      #declare Point = &lt;2*rand(S)-1, 2*rand(S)-1, 2*rand(S)-1&gt;;
   #end

   sphere { Point, .1 }

   #declare Index = Index + 1;
#end
</pre>
<p>There are some important things to note in this specific example:</p>
<ul>
<li>Although this is a nested loop, the sphere is not created in the inner loop but in the outer one. The reason is clear: We want to create 50 spheres, so the sphere creation has to be inside the loop that counts to 50. The inner loop just calculates an appropriate location.</li>
<li>The seed value 'S' is declared outside all the loops although it is used only in the inner loop. Can you guess why? Putting it inside the outer loop would have caused an undesired result: Which one?</li>
</ul>

</div>
<a name="t2_3_10_8"></a>
<div class="content-level-h4" contains="Other things to note" id="t2_3_10_8">
<h4>2.3.10.8 Other things to note</h4>
<p>There is no reason why the index value in your simple for-loop should step one unit at a time. Since the while-loop does not care how the index changes, you can change it in whichever way you want. For example:</p>
<pre>
#declare Index = Index - 1;   // Decrements the index (be careful with the while loop condition)
#declare Index = Index + 0.2; // Increases by steps of 0.2
#declare Index = Index * 2;   // Doubles the value of the index at each step.
</pre>
<p class="Note"><strong>Note:</strong> Be careful <em>where</em> you put your while-loop.</p>
<p>The example below illustrates a very common mistake:</p>
<pre>
#declare Index = 1;
#while(Index &lt;= 10)
   blob
   {  threshold 0.6
      sphere { &lt;Index, 0, 0&gt;, 2, 1 }
   }
   #declare Index = Index + 1;
#end
</pre>
<p>You will probably immediately see the problem.</p>
<p>This code creates 10 blobs with one component each. It does not seem to make much sense. Most probably the user wanted to make one blob with 10 components.</p>
<p>Why did this mistake happen? It may be that the user thought that the while-loop must be the outermost control structure and did not realize that while-loops can be anywhere. For example, inside objects to create subcomponents.</p>
<p>The correct code is, of course:</p>
<pre>
blob
{  threshold 0.6

   #declare Index = 1;
   #while(Index &lt;= 10)

      sphere { &lt;Index, 0, 0&gt;, 2, 1 }

      #declare Index = Index + 1;
   #end
}
</pre>
<p>The essential difference here is that it is only the sphere code which is run 10 times instead of the whole blob code. The net result is the same as if we had written the sphere code 10 times with proper values of 'Index'.</p>
<p>Be also careful with the placement of the braces. If you put them in the wrong place you can end up accidentally repeating an opening or a closing brace 10 times. Again, a proper indentation usually helps a lot with this, as seen in the above example.</p>
<p class="Note"><strong>Tip:</strong> You can use while-loops in conjunction with arrays to automate the creation of long lists of elements with differing data.</p>
<p>Imagine that you are making something like this:</p>
<pre>
color_map {
  [0.00 rgb &lt;.1,1,.6&gt;]
  [0.05 rgb &lt;.8,.3,.6&gt;]
  [0.10 rgb &lt;.3,.7,.9&gt;]
  [0.15 rgb &lt;1,.7,.3&gt;]
  ...
  [1.0 rgb &lt;.8,.2,.5&gt;]
  }
</pre>
<p>It is tedious to have to write the same things over and over just changing the index value and the values in the vector, even if you use copy-paste to copy the lines.</p>
<p>There is also one very big problem here: If you ever want to add a new color to the color map or remove a color, you would have to renumber all the indices again, which can be extremely tedious and frustrating.</p>
<p>Wouldn't it be nice to automate the creation of the color map so that you only have to write the vectors and that's it?</p>
<p>Well, you can. Using a while-loop which reads an array of vectors:</p>
<pre>
#declare MyColors = array[20]
   {  &lt;.1,1,.6&gt;, &lt;.8,.3,.6&gt;, &lt;.3,.7,.9&gt;,
      &lt;1,.7,.3&gt;, ... , &lt;.8,.2,.5&gt;
   }

...

color_map {
  #declare LastIndex = dimension_size(MyColors, 1)-1;
  #declare Index = 0;
  #while(Index &lt;= LastIndex)

     [Index/LastIndex rgb MyColors[Index]]

     #declare Index = Index + 1;
   #end
   }
</pre>
<p>Now it is easy to add, remove or modify colors in your color map. Just edit the vector array, remembering to change its size number accordingly, and the while-loop will automatically calculate the right values and create the color map for you.</p>

</div>
<a name="t2_3_11"></a>
<div class="content-level-h3" contains="SDL tutorial: A raytracer" id="t2_3_11">
<h3>2.3.11 SDL tutorial: A raytracer</h3>

</div>
<a name="t2_3_11_1"></a>
<div class="content-level-h4" contains="Introduction" id="t2_3_11_1">
<h4>2.3.11.1 Introduction</h4>
<p>A raytracer made with POV-Ray sounds really weird, doesn't it? What is it
anyways? POV-Ray is already a raytracer in itself, how can we use it
to make a raytracer? What the...?</p>

<p>The idea is to make a simple sphere raytracer which supports colored spheres
(with diffuse and specular lighting), colored light sources, reflections
and shadows with the POV-Ray SDL (Scene Description Language), then just
render the image created this way. That is, we do not use POV-Ray itself
to raytrace the spheres, but we make our own raytracer with its SDL and use
POV-Ray's raytracing part to just get the image on screen.</p>

<p>What obscure idea could be behind this weirdness? Why do not just use POV-Ray itself to raytrace the spheres a lot faster and that is it?</p>

<p>The idea is not speed nor quality, but to show the power of the POV-Ray SDL.
If you know how to make such a thing as a raytracer with it, we can really
grasp the expressive power of the SDL.</p>

<p>The idea of this document is to make a different approach to POV-Ray SDL
teaching. It is intended to be a different type of tutorial: Instead of
starting from the basics and give simple and dumb examples, we jump right
into a high-end SDL code and see how it is done. However, this is done
in a way that even beginners can learn something from it.</p>

<p>Another advantage is that you will learn how a simple sphere raytracer is
done by reading this tutorial. There are lots of misconceptions about
raytracing out there, and knowing how to make one helps clear most of them.</p>

<p>Although this tutorial tries to start from basics, it will go quite
fast to very &quot;high-end&quot; scripting, so it might not be the best tutorial
to read for a completely new user, but it should be enough to have some basic
knowledge. Also more advanced users may get some new info from it.</p>

<p class="Note"><strong>Note:</strong> In some places some mathematics is needed, so you would better not
be afraid of math.</p>

<p>If some specific POV-Ray SDL syntax is unclear you should consult the
POV-Ray documentation for more help. This tutorial explains how they can
be used, not so much what is their syntax.</p>

</div>


<a name="t2_3_11_2"></a>
<div class="content-level-h4" contains="The idea and the code" id="t2_3_11_2">
<h4>2.3.11.2 The idea and the code</h4>
<p>The idea is to raytrace a simple scene consisting of spheres and light
sources into a 2-dimensional array containing color vectors which represents
our screen.</p>

<p>After this we just have to put those colors on the actual scene for POV-Ray
to show them. This is made by creating a flat colored triangle mesh.
The mesh is just flat like a plane with a color map on it. We could as well
have written the result to a format like PPM and then read it and apply it as
an image map to a plane, but this way we avoid a temporary file.</p>

<p>The following image is done with the raytracer SDL. It calculated the image
at a resolution of 160x120 pixels and then raytraced an 512x384 image from
it. This causes the image to be blurred and jagged (because it is
practically zoomed in by a factor of 3.2). Calculating the image at 320x240
gives a much nicer result, but it is also much slower:</p>

<table class="centered" width="340px" cellpadding="0" cellspacing="10">
<tr>
  <td>
    <img class="center" width="320px" src="images/6/62/TutImgRaytracer.png">
  </td>
</tr>
<tr>
  <td>
    <p class="caption">Some spheres raytraced by the SDL at 160x120</p>
  </td>
</tr>
</table>

<p class="Note"><strong>Note:</strong> There are no real spheres nor light sources here
(real from the point of view of POV-Ray), just a flat colored triangle mesh
(like a plane with a pigment on it) and a camera, nothing else.</p>

<p>Here is the source code of the raytracer; we will look it part by part through this 
tutorial.</p>

<pre>
#declare ImageWidth = 160;
#declare ImageHeight = 120;
#declare MaxRecLev = 5;
#declare AmbientLight = &lt;.2,.2,.2&gt;;
#declare BGColor = &lt;0,0,0&gt;;

// Sphere information.
// Values are:
// Center, &lt;Radius, Reflection, 0&gt;, Color, &lt;phong_size, amount, 0&gt;
#declare Coord = array[5][4]
{ {&lt;-1.05,0,4&gt;, &lt;1,.5,0&gt;, &lt;1,.5,.25&gt;, &lt;40, .8, 0&gt;}
  {&lt;1.05,0,4&gt;, &lt;1,.5,0&gt;, &lt;.5,1,.5&gt;, &lt;40, .8, 0&gt;}
  {&lt;0,-3,5&gt;, &lt;2,.5,0&gt;, &lt;.25,.5,1&gt;, &lt;30, .4, 0&gt;}
  {&lt;-1,2.3,9&gt;, &lt;2,.5,0&gt;, &lt;.5,.3,.1&gt;, &lt;30, .4, 0&gt;}
  {&lt;1.3,2.6,9&gt;, &lt;1.8,.5,0&gt;, &lt;.1,.3,.5&gt;, &lt;30, .4, 0&gt;}
}

// Light source directions and colors:
#declare LVect = array[3][2]
{ {&lt;-1, 0, -.5&gt;, &lt;.8,.4,.1&gt;}
  {&lt;1, 1, -.5&gt;, &lt;1,1,1&gt;}
  {&lt;0,1,0&gt;, &lt;.1,.2,.5&gt;}
}



//==================================================================
// Raytracing calculations:
//==================================================================
#declare MaxDist = 1e5;
#declare ObjAmnt = dimension_size(Coord, 1);
#declare LightAmnt = dimension_size(LVect, 1);

#declare Ind = 0;
#while(Ind &lt; LightAmnt)
  #declare LVect[Ind][0] = vnormalize(LVect[Ind][0]);
  #declare Ind = Ind+1;
#end

#macro calcRaySphereIntersection(P, D, sphereInd)
  #local V = P-Coord[sphereInd][0];
  #local R = Coord[sphereInd][1].x;

  #local DV = vdot(D, V);
  #local D2 = vdot(D, D);
  #local SQ = DV*DV-D2*(vdot(V, V)-R*R);
  #if(SQ &lt; 0) #local Result = -1;
  #else
    #local SQ = sqrt(SQ);
    #local T1 = (-DV+SQ)/D2;
    #local T2 = (-DV-SQ)/D2;
    #local Result = (T1&lt;T2 ? T1 : T2);
  #end
  Result
#end

#macro Trace(P, D, recLev)
  #local minT = MaxDist;
  #local closest = ObjAmnt;

  // Find closest intersection:
  #local Ind = 0;
  #while(Ind &lt; ObjAmnt)
    #local T = calcRaySphereIntersection(P, D, Ind);
    #if(T&gt;0 &amp; T&lt;minT) 
      #local minT = T;
      #local closest = Ind;
    #end
    #local Ind = Ind+1;
  #end

  // If not found, return background color:
  #if(closest = ObjAmnt)
    #local Pixel = BGColor;
  #else
    // Else calculate the color of the intersection point:
    #local IP = P+minT*D;
    #local R = Coord[closest][1].x;
    #local Normal = (IP-Coord[closest][0])/R;

    #local V = P-IP;
    #local Refl = 2*Normal*(vdot(Normal, V)) - V;

    // Lighting:
    #local Pixel = AmbientLight;
    #local Ind = 0;
    #while(Ind &lt; LightAmnt)
      #local L = LVect[Ind][0];

      // Shadowtest:
      #local Shadowed = false;
      #local Ind2 = 0;
      #while(Ind2 &lt; ObjAmnt)
        #if(Ind2!=closest &amp; calcRaySphereIntersection(IP,L,Ind2)&gt;0)
          #local Shadowed = true;
          #local Ind2 = ObjAmnt;
        #end
        #local Ind2 = Ind2+1;
      #end
      
      #if(!Shadowed)
        // Diffuse:
        #local Factor = vdot(Normal, L);
        #if(Factor &gt; 0)
          #local Pixel=Pixel+LVect[Ind][1]*Coord[closest][2]*Factor;
        #end

        // Specular:
        #local Factor = vdot(vnormalize(Refl), L);
        #if(Factor &gt; 0)
          #local Pixel = 
             Pixel +
             LVect[Ind][1]*pow(Factor, Coord[closest][3].x)*
             Coord[closest][3].y;
        #end
      #end
      #local Ind = Ind+1;
    #end

    // Reflection:
    #if(recLev &lt; MaxRecLev &amp; Coord[closest][1].y &gt; 0)
      #local Pixel = 
    Pixel + Trace(IP, Refl, recLev+1)*Coord[closest][1].y;
    #end
  #end

  Pixel
#end


#debug &quot;Rendering...\n\n&quot;
#declare Image = array[ImageWidth][ImageHeight]
#declare IndY = 0;
#while(IndY &lt; ImageHeight)
  #declare CoordY = IndY/(ImageHeight-1)*2-1;
  #declare IndX = 0;
  #while(IndX &lt; ImageWidth)
    #declare CoordX = 
      (IndX/(ImageWidth-1)-.5)*2*ImageWidth/ImageHeight;
    #declare Image[IndX][IndY] =
      Trace(-z*3, &lt;CoordX, CoordY, 3&gt;, 1);
    #declare IndX = IndX+1;
  #end
  #declare IndY = IndY+1;
  #debug concat(&quot;\rDone &quot;, str(100*IndY/ImageHeight, 0, 1),
    &quot;%  (line &quot;,str(IndY,0,0),&quot; out of &quot;,str(ImageHeight,0,0),&quot;)&quot;)
#end
#debug &quot;\n&quot;


//==================================================================
// Image creation (colored mesh):
//==================================================================
#default { finish { ambient 1 } }

#debug &quot;Creating colored mesh to show image...\n&quot;
mesh2
{ vertex_vectors
  { ImageWidth*ImageHeight*2,
    #declare IndY = 0;
    #while(IndY &lt; ImageHeight)
      #declare IndX = 0;
      #while(IndX &lt; ImageWidth)
        &lt;(IndX/(ImageWidth-1)-.5)*ImageWidth/ImageHeight*2,
         IndY/(ImageHeight-1)*2-1, 0&gt;,
        &lt;((IndX+.5)/(ImageWidth-1)-.5)*ImageWidth/ImageHeight*2,
         (IndY+.5)/(ImageHeight-1)*2-1, 0&gt;
        #declare IndX = IndX+1;
      #end
      #declare IndY = IndY+1;
    #end
  }
  texture_list
  { ImageWidth*ImageHeight*2,
    #declare IndY = 0;
    #while(IndY &lt; ImageHeight)
      #declare IndX = 0;
      #while(IndX &lt; ImageWidth)
        texture { pigment { rgb Image[IndX][IndY] } }
        #if(IndX &lt; ImageWidth-1 &amp; IndY &lt; ImageHeight-1)
          texture { pigment { rgb
            (Image[IndX][IndY]+Image[IndX+1][IndY]+
             Image[IndX][IndY+1]+Image[IndX+1][IndY+1])/4 } }
        #else
          texture { pigment { rgb 0 } }
        #end
        #declare IndX = IndX+1;
      #end
      #declare IndY = IndY+1;
    #end
  }
  face_indices
  { (ImageWidth-1)*(ImageHeight-1)*4,
    #declare IndY = 0;
    #while(IndY &lt; ImageHeight-1)
      #declare IndX = 0;
      #while(IndX &lt; ImageWidth-1)
        &lt;IndX*2+  IndY    *(ImageWidth*2),
         IndX*2+2+IndY    *(ImageWidth*2),
         IndX*2+1+IndY    *(ImageWidth*2)&gt;,
         IndX*2+  IndY    *(ImageWidth*2),
         IndX*2+2+IndY    *(ImageWidth*2),
         IndX*2+1+IndY    *(ImageWidth*2),

        &lt;IndX*2+  IndY    *(ImageWidth*2),
         IndX*2+  (IndY+1)*(ImageWidth*2),
         IndX*2+1+IndY    *(ImageWidth*2)&gt;,
         IndX*2+  IndY    *(ImageWidth*2),
         IndX*2+  (IndY+1)*(ImageWidth*2),
         IndX*2+1+IndY    *(ImageWidth*2),

        &lt;IndX*2+  (IndY+1)*(ImageWidth*2),
         IndX*2+2+(IndY+1)*(ImageWidth*2),
         IndX*2+1+IndY    *(ImageWidth*2)&gt;,
         IndX*2+  (IndY+1)*(ImageWidth*2),
         IndX*2+2+(IndY+1)*(ImageWidth*2),
         IndX*2+1+IndY    *(ImageWidth*2),

        &lt;IndX*2+2+IndY    *(ImageWidth*2),
         IndX*2+2+(IndY+1)*(ImageWidth*2),
         IndX*2+1+IndY    *(ImageWidth*2)&gt;,
         IndX*2+2+IndY    *(ImageWidth*2),
         IndX*2+2+(IndY+1)*(ImageWidth*2),
         IndX*2+1+IndY    *(ImageWidth*2)
        #declare IndX = IndX+1;
      #end
      #declare IndY = IndY+1;
    #end
  }
}

camera { orthographic location -z*2 look_at 0 }
</pre>

</div>
<a name="t2_3_11_3"></a>
<div class="content-level-h4" contains="Short introduction to raytracing" id="t2_3_11_3">
<h4>2.3.11.3 Short introduction to raytracing</h4>
<p>Before we start looking at the code, let's look briefly how raytracing
works. This will help you understand what the script is doing.</p>

<p>The basic idea of raytracing is to shoot rays from the camera towards the
scene and see what does the ray hit. If the ray hits the surface of an object
then lighting calculations are performed in order to get the color of the
surface at that place.</p>

<p>The following image shows this graphically:</p>

<table class="centered" width="660px" cellpadding="0" cellspacing="10">
<tr>
  <td>
    <img class="center" width="640px" src="images/c/c8/TutImgRaytracing.gif">
  </td>
</tr>
<tr>
  <td>
    <p class="caption">The basic raytracing algorithm</p>
  </td>
</tr>
</table>

<p>First a ray is shot in a specified direction to see if there is something
there. As this is solved mathematically, we need to know the mathematical
representation of the ray and the objects in the scene so that we can
calculate where does the ray intersect the objects. Once we get all the
intersection points, we choose the closest one.</p>

<p>After this we have to calculate the lighting (ie. the illumination) of
the object at the intersection point. In the most basic lighting model
(as the one used in the script) there are three main things that affect
the lighting of the surface:</p>

<ul>
<li>The shadow test ray, which determines whether a light source illuminates
the intersection point or not.</li>
<li>The normal vector, which is a vector perpendicular (ie. at 90 degrees) to
the object surface at the intersection point. It determines the diffuse
component of the lighting as well as the direction of the reflected
ray (in conjunction with the incoming ray; that is, the angle alpha
determines the direction of the reflected ray).</li>
<li>The reflected ray, which determines the specular component of the
lighting and of course the color of the reflection (if the object is
reflective).</li>
</ul>

<p>Do not worry if these things sound a bit confusing. Full details of all
these things will be given through this tutorial, as we look what does
the raytracing script do. The most important thing at this stage is to
understand how the basic raytracing algorithm works at theoretical level
(the image above should say most of it).</p>

<p>Let's just look at the raytracer source code line by line and look what
does it do</p>

</div>
<a name="t2_3_11_4"></a>
<div class="content-level-h4" contains="Global settings" id="t2_3_11_4">
<h4>2.3.11.4 Global settings</h4>
<pre>
#declare ImageWidth = 160;
#declare ImageHeight = 120;
#declare MaxRecLev = 5;
#declare AmbientLight = &lt;.2,.2,.2&gt;;
#declare BGColor = &lt;0,0,0&gt;;
</pre>

<p>These lines just declare some identifiers defining some general values
which will be used later in the code. The keyword we use here is
<code>#declare</code> and it means that we are declaring a global identifier,
which will be seen in the whole code.</p>

<p>As you can see, we declare some identifiers to be of float type and others
to be of vector type. The vector type identifiers are, in fact, used later
for color definition (as their name implies).</p>

<p>The <code>ImageWidth</code> and <code>ImageHeight</code> define the
resolution of the image we are going to render. </p>
<p class="Note"><strong>Note:</strong> This only defines
the resolution of the image we are going to render in our SDL (ie. into the
array we will define later); it does not set the resolution of the image
which POV-Ray will render.</p>

<p>The <code>MaxRecLev</code> limits the maximum number of recursive
reflections the code will calculate. It is equivalent to the
<code>max_trace_level</code> value in <code>global_settings</code> which
POV-Ray uses to raytrace.</p>

<p>The <code>AmbientLight</code> defines a color which is added to all
surfaces. This is used to lighten up shadowed parts so that they are not
completely dark. It is equivalent to the <code>ambient_light</code> value in
<code>global_settings</code>.</p>

<p>Finally, <code>BGColor</code> defines the color of the rays which do not
hit anything. It is equivalent to the <code>background</code> block of POV-Ray.</p>

</div>
<a name="t2_3_11_5"></a>
<div class="content-level-h4" contains="Scene definition" id="t2_3_11_5">
<h4>2.3.11.5 Scene definition</h4>
<pre>
// Sphere information.
// Values are:
// Center, &lt;Radius, Reflection, 0&gt;, Color, &lt;phong_size, amount, 0&gt;
#declare Coord = array[5][4]
{ {&lt;-1.05,0,4&gt;, &lt;1,.5,0&gt;, &lt;1,.5,.25&gt;, &lt;40, .8, 0&gt;}
  {&lt;1.05,0,4&gt;, &lt;1,.5,0&gt;, &lt;.5,1,.5&gt;, &lt;40, .8, 0&gt;}
  {&lt;0,-3,5&gt;, &lt;2,.5,0&gt;, &lt;.25,.5,1&gt;, &lt;30, .4, 0&gt;}
  {&lt;-1,2.3,9&gt;, &lt;2,.5,0&gt;, &lt;.5,.3,.1&gt;, &lt;30, .4, 0&gt;}
  {&lt;1.3,2.6,9&gt;, &lt;1.8,.5,0&gt;, &lt;.1,.3,.5&gt;, &lt;30, .4, 0&gt;}
}

// Light source directions and colors:
#declare LVect = array[3][2]
{ {&lt;-1, 0, -.5&gt;, &lt;.8,.4,.1&gt;}
  {&lt;1, 1, -.5&gt;, &lt;1,1,1&gt;}
  {&lt;0,1,0&gt;, &lt;.1,.2,.5&gt;}
}
</pre>

<p>Here we use a bit more complex declarations: Array declarations.</p>

<p>In fact, they are even more complex than simple arrays, as we are declaring
two-dimensional arrays.</p>

<p>A simple one-dimensional array can be declared like:</p>

<pre>
#declare MyArray = array[4] { 1, 2, 3, 4 }
</pre>

<p>and then values can be read from inside it with for example:
<code>MyArray[2]</code> (which will return <code>3</code> in this case as
the indexing starts from 0, ie. the index 0 gets the first value in the
array).</p>

<p>A two-dimensional array can be thought as an array containing arrays.
That is, if you say <code>array[3][2]</code>, that means an array which
has 3 elements; each one of those elements is an array with 2 elements.
When you want to read a value from it, for example <code>MyArray[1][3]</code>,
you can think about it as get the fourth value from the second array (as
indexing starts from 0, then the index value 3 actually means fourth value).</p>

<p class="Note"><strong>Note:</strong> Although you can put almost anything inside an array (floats,
vectors, objects and so on) you can only put one type of things inside an
array. That is, you cannot mix float values and objects inside the same array.
(One nice feature is that all POV-Ray objects are considered equivalent,
which means that an object array can contain any objects inside it.)</p>

<p>What we are doing here is to define the information for our spheres and
light sources. The first array (called <code>Coord</code>) defines the
information for the spheres and the second (<code>LVect</code>) defines
the light sources.</p>

<p>For spheres we define their center as the first vector. The second
vector has both the radius of the sphere and its reflection amount
(which is equivalent to the <code>reflection</code> value in the
<code>finish</code> block of an object). This is a trick we use to
not to waste so much space, so we use two values of the same vector
for defining two different things.</p>

<p>The third vector defines the color of the sphere and the fourth the
specular component of the lighting (equivalent to <code>phong_size</code>
and <code>phong</code> values in the <code>finish</code> block of an
object).</p>

<p>The light source definition array contains direction vectors and colors.
This means that the light sources are directional, that is, they just say
which direction the light is coming from. It could have been equally easy
to make point lights, though.</p>

<p>We will use the information inside these arrays later in order to raytrace
the scene they define.</p>

</div>
<a name="t2_3_11_6"></a>
<div class="content-level-h4" contains="Initializing the raytracer" id="t2_3_11_6">
<h4>2.3.11.6 Initializing the raytracer</h4>
<pre>
#declare MaxDist = 1e5;
#declare ObjAmnt = dimension_size(Coord, 1);
#declare LightAmnt = dimension_size(LVect, 1);

#declare Ind = 0;
#while(Ind &lt; LightAmnt)
  #declare LVect[Ind][0] = vnormalize(LVect[Ind][0]);
  #declare Ind = Ind+1;
#end
</pre>

<p>Before being able to start the raytracing, we have to intialize a couple
of things.</p>

<p>The <code>MaxDist</code> defines the maximum distance a surface can
be from the starting point of a ray. This means that if a surface is farther
away from the starting point of the ray than this value, it will not be
seen. Strictly speaking this value is unnecessary and we can make the
raytracer so that there is no such a limitation, but we save one extra
step when we do it this way, and for scenes sized like ours it does not
really matter. (If you really, really want to get rid of the limitation,
I am sure you will figure out yourself how to do it after this tutorial.)</p>

<p>The <code>ObjAmnt</code> and <code>LightAmnt</code> identifiers are
declared just to make it easier for us to see how many objects and lights
are there (we need this info to loop through all the objects and lights).
Calling the <code>dimension_size()</code> function is a really nice way
of getting the number of items in an array.</p>

<p>All right, now we are getting to a bit more advanced stuff: What does the
while-loop do there?</p>

<p>The <code>#while</code>-loop uses the <code>Ind</code> identifier as
an index value going from <code>0</code> to <code>LightAmnt-1</code>
(yes, <code>-1</code>; when <code>Ind</code> gets the value
<code>LightAmnt</code> the loop is ended right away). We also see that
we are indexing the <code>LVect</code> array; thus, it is clear we are
going through all the light sources (specifically through their direction
vectors, as we only use the <code>[0]</code> part) and we assign something
to them.</p>

<p>What we are doing is to assign a normalized version of each light
source direction onto themselves, that is, just normalizing them.</p>

<p>Normalize is a synonym for convert to unit vector, that is, convert
to a vector with the same direction as the original but with length 1.</p>

<p>Why? We will later see that for illumination calculations we will be
needing unit vectors. It is more efficient to convert the light source
directions to unit vectors once at the beginning than every time for
each pixel later.</p>

</div>
<a name="t2_3_11_7"></a>
<div class="content-level-h4" contains="Ray-sphere intersection" id="t2_3_11_7">
<h4>2.3.11.7 Ray-sphere intersection</h4>
<pre>
#macro calcRaySphereIntersection(P, D, sphereInd)
  #local V = P-Coord[sphereInd][0];
  #local R = Coord[sphereInd][1].x;

  #local DV = vdot(D, V);
  #local D2 = vdot(D, D);
  #local SQ = DV*DV-D2*(vdot(V, V)-R*R);
  #if(SQ &lt; 0) #local Result = -1;
  #else
    #local SQ = sqrt(SQ);
    #local T1 = (-DV+SQ)/D2;
    #local T2 = (-DV-SQ)/D2;
    #local Result = (T1&lt;T2 ? T1 : T2);
  #end
  Result
#end
</pre>

<p>This is the core of the whole raytracing process.</p>

<p>First let's see how a macro works (if you know it, just skip the
following section):</p>

</div>
<a name="t2_3_11_7_1"></a>
<div class="content-level-h5" contains="Inner workings of a macro" id="t2_3_11_7_1">
<h5>2.3.11.7.1 Inner workings of a macro</h5>
<p>A macro works like a substitution command (similar to the #define macros
in the C programming language). The body of the macro is in practice inserted in the place where
the macro is called. For example you can use a macro like this:</p>

<pre>
#macro UnitSphere()
  sphere { 0,1 }
#end

object { UnitSphere() pigment { rgb 1 } }
</pre>

<p>The result of this code is, in effect, as if you had written:</p>

<pre>
object { sphere { 0,1 } pigment { rgb 1 } }
</pre>

<p>Of course there is no reason in making this, as you could have just #declared
the <code>UnitSphere</code> as a sphere of radius 1. However, the power of
macros kick in when you start using macro parameters. For example:</p>

<pre>
#macro Sphere(Radius)
  sphere { 0, Radius }
#end

object { Sphere(3) pigment { rgb 1 } }
</pre>


<p>Now you can use the macro <code>Sphere</code> to create a sphere with
the specified radius. Of course this does not make much sense either, as
you could just write the sphere primitive directly because it is so short,
but this example is intentionally short to show how it works; the macros
become very handy when they create something much more complicated than
just a sphere.</p>

<p>There is one important difference between macros in POV-Ray and real
substitution macros: Any <code>#local</code> statement inside the macro
definition will be parsed at the visibility level of the macro only, that
is, it will have no effect on the environment where the macro was called
from. The following example shows what I am talking about:</p>

<pre>
#macro Sphere(Radius)
  #local Color = &lt;1,1,1&gt;;
  sphere { 0, Radius pigment { rgb Color } }
#end

#declare Color = &lt;1,0,0&gt;;
object { Sphere(3) }
   // 'Color' is still &lt;1,0,0&gt; here, 
   // thus the following box will be red:
box { -1,1 pigment { rgb Color } }
</pre>

<p>In the example above, although the macro creates a local identifier
called <code>Color</code> and there is an identifier with the same name
at global level, the local definition does not affect the global one.
Also even if there was not any global definition of <code>Color</code>,
the one inside the macro is not seen outside it.</p>

<p>There is one important exception to this, and this is one of the most
powerful features of macros (thanks to this they can be used as if they
were functions): If an identifier (be it local or global) appears alone
in the body of a macro (usually at the end), its value will be passed
outside the macro (as if it was a return value). The following example
shows how this works:</p>

<pre>
#macro Factorial(N)
  #local Result = 1;
  #local Ind = 2;
  #while(Ind &lt;= N)
    #local Result = Result*Ind;
    #local Ind = Ind+1;
  #end
  Result
#end

#declare Value = Factorial(5);
</pre>

<p>Although the identifier <code>Result</code> is local to the macro, its
value is passed as if it was a return value because of the last line of
the macro (where <code>Result</code> appears alone) and thus the identifier
<code>Value</code> will be set to the factorial of 5.</p>

</div>
<a name="t2_3_11_7_2"></a>
<div class="content-level-h5" contains="The ray-sphere intersection macro" id="t2_3_11_7_2">
<h5>2.3.11.7.2 The ray-sphere intersection macro</h5>
<p>Here is again the macro at the beginning of the page so that you do not
have to scroll so much in order to see it:</p>

<pre>
#macro calcRaySphereIntersection(P, D, sphereInd)
  #local V = P-Coord[sphereInd][0];
  #local R = Coord[sphereInd][1].x;

  #local DV = vdot(D, V);
  #local D2 = vdot(D, D);
  #local SQ = DV*DV-D2*(vdot(V, V)-R*R);
  #if(SQ &lt; 0) #local Result = -1;
  #else
    #local SQ = sqrt(SQ);
    #local T1 = (-DV+SQ)/D2;
    #local T2 = (-DV-SQ)/D2;
    #local Result = (T1&lt;T2 ? T1 : T2);
  #end
  Result
#end
</pre>

<p>The idea behind this macro is that it takes a starting point (ie. the
starting point of the ray) a direction vector (the direction where the
ray is shot) and an index to the sphere definition array defined previously.
The macro returns a factor value; this value expresses how much we have to
multiply the direction vector in order to hit the sphere.</p>

<p>This means that if the ray hits the specified sphere, the intersection
point will be located at:<br>
<code>StartingPoint + Result*Direction</code></p>

<p>The return value can be negative, which means that the intersection
point was actually behind the starting point. A negative value will be
just ignored, as if the ray did not hit anything. We can use this to make
a little trick (which may seem obvious when said, but not so obvious when
you have to figure it out for yourself): If the ray actually does not hit
the sphere, we return just a negative value (does not really matter which).</p>

<p>And how does the macro do it? What is the theory behind those
complicated-looking mathematical expressions?</p>

<p>I will use a syntax similar to POV-Ray syntax to express mathematical
formulas here since that is probably the easiest way of doing it.</p>

<p>Let's use the following letters:</p>

<p>
<code>P</code> = Starting point of the ray<br>
<code>D</code> = Direction of the ray<br>
<code>C</code> = Center of the sphere<br>
<code>R</code> = Radius of the sphere
</p>

<p>The theory behind the macro is that we have to see what is the value
<code>T</code> for which holds that:</p>

<p><code>vlength(P+T*D-C) = R</code></p>

<p>This means: The length of the vector between the center of the sphere
(<code>C</code>) and the intersection point (<code>P+T*D</code>) is equal
to the radius (<code>R</code>).</p>

<p>If we use an additional letter so that:</p>

<p><code>V = P-C</code></p>

<p>then the formula is reduced to:</p>

<p><code>vlength(T*D+V) = R</code></p>

<p>which makes our life easier. This formula can be opened as:</p>

<p><code>(T*D<sub>x</sub>+V<sub>x</sub>)<sup>2</sup> + 
(T*D<sub>y</sub>+V<sub>y</sub>)<sup>2</sup> + 
(T*D<sub>z</sub>+V<sub>z</sub>)<sup>2</sup> - R<sup>2</sup> = 0</code></p>

<p>Solving <code>T</code> from that is rather trivial math. We get a
2nd order polynomial which has two solutions (I will use the &quot;&#183;&quot; symbol
to represent the dot-product of two vectors):</p>

<p><code>T = (-D&#183;V &#177; sqrt((D&#183;V)<sup>2</sup> - D<sup>2</sup>(V<sup>2</sup>-R<sup>2</sup>))) / D<sup>2</sup></code></p>

<p class="Note"><strong>Note:</strong> <code>D<sup>2</sup></code> means actually
<code>D&#183;D</code>)</p>

<p>When the discriminant (ie. the expression inside the square root) is
negative, the ray does not hit the sphere and thus we can return a negative
value (the macro returns -1). We must check this in order to avoid the
<em>square root of a negative number</em> error; as it has a very logical
meaning in this case, the checking is natural.</p>

<p>If the value is positive, there are two
solutions (or just one if the value is zero, but that does not really
matter here), which corresponds to the two intersection points of the
ray with the sphere.</p>

<p>As we get two values, we have to return the one which is smaller (the
closest intersection). This is what this portion of the code does:</p>

<pre>
    #local Result = (T1&lt;T2 ? T1 : T2);
</pre>

<p class="Note"><strong>Note:</strong> This is an incomplete algorithm: If one value is negative
and the other positive (this happens when the starting point is inside
the sphere), we would have to return the positive one. The way it is now
results in that we will not see the inner surface of the sphere if we
put the camera inside one.</p>

<p>For our simple scene this is enough as we do not put our camera inside
a sphere nor we have transparent spheres. We could add a check there
which looks if one of the values is positive and the other negative and
returns the positive one. However, this has an odd and very annoying
result (you can try it if you want). This is most probably caused by
the inaccuracy of floating point numbers and happens when calculating
reflections (the starting point is exactly on the surface of the sphere).
We could correct these
problems by using epsilon values to get rid of accuracy problems, but
in our simple scene this will not be necessary. </p>

</div>
<a name="t2_3_11_8"></a>
<div class="content-level-h4" contains="The Trace macro" id="t2_3_11_8">
<h4>2.3.11.8 The Trace macro</h4>
<pre>
#macro Trace(P, D, recLev)
</pre>

<p>If the ray-sphere intersection macro was the core of the raytracer, then
the Trace-macro is practically everything else, the body of the raytracer.</p>

<p>The Trace-macro is a macro which takes the starting point of a ray, the
direction of the ray and a recursion count (which should always be 1 when
calling the macro from outside; 1 could be its default value if POV-Ray
supported default values for macro parameters). It calculates and returns a
color for that ray.</p>

<p>This is the macro we call for each pixel we want to calculate. That is,
the starting point of the ray is our camera location and the direction is
the direction of the ray starting from there and going through the pixel
we are calculating. The macro returns the color of that pixel.</p>

<p>What the macro does is to see which sphere (if any) does the ray hit
and then calculates the lighting for that intersection point (which includes
calculating reflection), and returns the color.</p>

<p>The Trace-macro is <em>recursive</em>, meaning that it calls itself. More
specifically, it calls itself when it wants to calculate the ray reflected
from the surface of a sphere. The <code>recLev</code> value is used to stop
this recursion when the maximum recursion level is reached (ie. it calculates
the reflection only if <code>recLev &lt; MaxRecLev</code>).</p>

<p>Let's examine this relatively long macro part by part:</p>

</div>
<a name="t2_3_11_8_1"></a>
<div class="content-level-h5" contains="Calculating the closest intersection" id="t2_3_11_8_1">
<h5>2.3.11.8.1 Calculating the closest intersection</h5>
<pre>
  #local minT = MaxDist;
  #local closest = ObjAmnt;

  // Find closest intersection:
  #local Ind = 0;
  #while(Ind &lt; ObjAmnt)
    #local T = calcRaySphereIntersection(P, D, Ind);
    #if(T&gt;0 &amp; T&lt;minT) 
      #local minT = T;
      #local closest = Ind;
    #end
    #local Ind = Ind+1;
  #end
</pre>

<p>A ray can hit several spheres and we need the closest intersection point
(and to know which sphere does it belong to). One could think that calculating
the closest intersection is rather complicated, needing things like sorting
all the intersection points and such. However, it is quite simple, as seen
in the code above.</p>

<p>If we remember from the previous part, the ray-sphere intersection macro
returns a factor value which tells us how much do we have to multiply the
direction vector in order to get the intersection point. What we do is just
to call the ray-sphere intersection macro for each sphere and take the
smallest returned value (which is greater than zero).</p>

<p>First we initialize the <code>minT</code> identifier, which will hold
this smallest value to something big (this is where we need the
<code>MaxDist</code> value, although modifying this code to work around this
limitation is trivial and left to the user). Then we go through all the
spheres and call the ray-sphere intersection macro for each one. Then we
look if the returned value was greater than 0 and smaller than
<code>minT</code>, and if so, we assign the value to <code>minT</code>. When
the loop ends, we have the smallest intersection point in it.</p>

<p class="Note"><strong>Note:</strong> We also assign the index to the sphere which the closest
intersection belongs to in the <code>closest</code> identifier.</p>

<p>Here we use a small trick, and it is related to its initial value:
<code>ObjAmnt</code>. Why did we initialize it to that? The purpose of it
was to initialize it to some value which is not a legal index to a sphere
(<code>ObjAmnt</code> is not a legal index as the indices go from 0 to
<code>ObjAmnt-1</code>); a negative value would have worked as well, it
really does not matter. If the ray does not hit any sphere, then this identifier
is not changed and so we can see it afterwards.</p>

</div>
<a name="t2_3_11_8_2"></a>
<div class="content-level-h5" contains="If the ray doesn't hit anything" id="t2_3_11_8_2">
<h5>2.3.11.8.2 If the ray doesn't hit anything</h5>
<pre>
  // If not found, return background color:
  #if(closest = ObjAmnt)
    #local Pixel = BGColor;
</pre>

<p>If the ray did not hit any sphere, what we do is just to return the
bacground color (defined by the <code>BGColor</code> identifier).</p>

</div>
<a name="t2_3_11_8_3"></a>
<div class="content-level-h5" contains="Initializing color calculations" id="t2_3_11_8_3">
<h5>2.3.11.8.3 Initializing color calculations</h5>
<p>Now comes one of the most interesting parts of the raytracing process:
How do we calculate the color of the intersection point?</p>

<p>First we have to pre-calculate a couple of things:</p>

<pre>
  #else
    // Else calculate the color of the intersection point:
    #local IP = P+minT*D;
    #local R = Coord[closest][1].x;
    #local Normal = (IP-Coord[closest][0])/R;

    #local V = P-IP;
    #local Refl = 2*Normal*(vdot(Normal, V)) - V;
</pre>

<p>Naturally we need the intersection point itself (needed to calculate the
normal vector and as the starting point of the reflected ray). This is
calculated into the <code>IP</code> identifier with the formula which I
have been repeating a few times during this tutorial.</p>

<p>Then we need the normal vector of the surface at the intersection point.
A normal vector is a vector perpendicular (ie. at 90 degrees) to the surface.
For a sphere this is very easy to calculate: It is just the vector from the
center of the sphere to the intersection point.</p>
<p class="Note"><strong>Note:</strong> We normalize it
(ie. convert it into a unit vector, ie. a vector of length 1) by dividing
it by the radius of the sphere. The normal vector needs to be normalized for
lighting calculation.</p>

<p>Now a tricky one: We need the direction of the reflected ray. This
vector is of course needed to calculate the reflected ray, but it is also
needed for specular lighting.</p>

<p>This is calculated into the <code>Refl</code> identifier in the code
above. What we do is to take the vector from the intersection point to
the starting point (<code>P-IP</code>) and mirror it with respect to
the normal vector. The formula for mirroring a vector <code>V</code> with
respect to a unit vector (let's call it <code>Axis</code>) is:</p>

<p><code>MirroredV = 2*Axis*(Axis&#183;V) - V</code></p>

<p>(We could look at the theory behind this formula in more detail, but let's
not go too deep into math in this tutorial, shall we?)</p>
</div>
<a name="t2_3_11_8_4"></a>
<div class="content-level-h5" contains="Going through the light sources" id="t2_3_11_8_4">
<h5>2.3.11.8.4 Going through the light sources</h5>
<pre>
    // Lighting:
    #local Pixel = AmbientLight;
    #local Ind = 0;
    #while(Ind &lt; LightAmnt)
      #local L = LVect[Ind][0];
</pre>

<p>Now we can calculate the lighting of the intersection point. For this
we need to go through all the light sources.</p>
<p class="Note"><strong>Note:</strong> <code>L</code> contains the direction vector which
points towards the light source, not its location.</p>

<p>We also initialize the color to be returned (<code>Pixel</code>) with
the ambient light value (given in the global settings part). The goal is to
add colors to this (the colors come from diffuse and specular lighting, and
reflection).</p>

</div>



<a name="t2_3_11_8_5"></a>
<div class="content-level-h5" contains="Shadow test" id="t2_3_11_8_5">
<h5>2.3.11.8.5 Shadow test</h5>
<p>The very first thing to do for calculating the lighting for a light source
is to see if the light source is illuminating the intersection point in the
first place (this is one of the nicest features of raytracing: shadow
calculations are laughably easy to do):</p>

<pre>
      // Shadowtest:
      #local Shadowed = false;
      #local Ind2 = 0;
      #while(Ind2 &lt; ObjAmnt)
        #if(Ind2!=closest &amp; calcRaySphereIntersection(IP,L,nd2)&gt;0)
          #local Shadowed = true;
          #local Ind2 = ObjAmnt;
        #end
        #local Ind2 = Ind2+1;
      #end
</pre>

<p>What we do is to go through all the spheres (we skip the current sphere
although it is not necessary, but a little optimization is still a little
optimization), take the intersection point as starting point and the
light direction as the direction vector and see if the ray-sphere intersection
test returns a positive value for any of them (and quit the loop immediately
when one is found, as we do not need to check the rest anymore).</p>

<p>The result of the shadow test is put into the <code>Shadowed</code>
identifier as a boolean value (<code>true</code> if the point is shadowed).</p>

</div>
<a name="t2_3_11_8_6"></a>
<div class="content-level-h5" contains="Diffuse lighting" id="t2_3_11_8_6">
<h5>2.3.11.8.6 Diffuse lighting</h5>
<p>The diffuse component of lighting is generated when a light ray hits
a surface and it is reflected equally to all directions. The brightest part
of the surface is where the normal vector points directly in the direction
of the light. The lighting diminishes in relation to the cosine of the
angle between the normal vector and the light vector.</p>

<pre>
      #if(!Shadowed)
        // Diffuse:
        #local Factor = vdot(Normal, L);
        #if(Factor &gt; 0)
          #local Pixel = 
             Pixel + LVect[Ind][1]*Coord[closest][2]*Factor;
        #end
</pre>

<p>The code for diffuse lighting is surprisingly short.</p>

<p>There is an extremely nice trick in mathematics to get the cosine of the
angle between two unit vectors: It is their dot-product.</p>

<p>What we do is to calculate the dot-product of the normal vector and the
light vector (both have been normalized previously). If the dot-product
is negative it means that the normal vector points in the opposite direction
than the light vector. Thus we are only interested in positive values.</p>

<p>Thus, we add to the pixel color the color of the light source multiplied
by the color of the surface of the sphere multiplied by the dot-product.
This gives us the diffuse component of the lighting.</p>

</div>
<a name="t2_3_11_8_7"></a>
<div class="content-level-h5" contains="Specular lighting" id="t2_3_11_8_7">
<h5>2.3.11.8.7 Specular lighting</h5>
<p>The specular component of lighting comes from the fact that most surfaces
do not reflect light equally to all directions, but they reflect more light
to the reflected ray direction, that is, the surface has some mirror
properties. The brightest part of the surface is where the reflected ray
points in the direction of the light.</p>

<p>Photorealistic lighting is a very complicated issue and there are lots
of different lighting models out there, which try to simulate real-world
lighting more or less accurately. For our simple raytracer we just use
a simple Phong lighting model, which suffices more than enough.</p>

<pre>
        // Specular:
        #local Factor = vdot(vnormalize(Refl), L);
        #if(Factor &gt; 0)
          #local Pixel = Pixel + LVect[Ind][1]*
                         pow(Factor, Coord[closest][3].x)*
                         Coord[closest][3].y;
        #end
</pre>

<p>The calculation is similar to the diffuse lighting with the following
differences:</p>

<ul>
<li>We do not use the normal vector, but the reflected vector.</li>
<li>The color of the surface is not taken into account (a very simple
Phong lighting model).</li>
<li>We do not take the dot-product as is, but we raise it to a power given
in the scene definition (phong size).</li>
<li>We use a brightness factor given in the scene definition to multiply
the color (phong amount).</li>
</ul>

<p>Thus, the color we add to the pixel color is the color of the light
source multiplied by the dot-product (which is raised to the given power)
and by the given brightness amount.</p>

<p>Then we close the code blocks:</p>

<pre>
      #end // if(!Shadowed)
      #local Ind = Ind+1;
    #end // while(Ind &lt; LightAmnt)
</pre>

</div>
<a name="t2_3_11_8_8"></a>
<div class="content-level-h5" contains="Reflection Calculation" id="t2_3_11_8_8">
<h5>2.3.11.8.8 Reflection Calculation</h5>
<pre>
    // Reflection:
    #if(recLev &lt; MaxRecLev &amp; Coord[closest][1].y &gt; 0)
      #local Pixel = 
        Pixel + Trace(IP, Refl, recLev+1)*Coord[closest][1].y;
    #end
</pre>

<p>Another nice aspect of raytracing is that reflection is very easy to 
calculate.</p>

<p>Here we check that the recursion level has not reached the limit and 
that the sphere has a reflection component defined. If both are so, we 
add the reflected component (the color of the reflected ray multiplied 
by the reflection factor) to the pixel color.</p>

<p>This is where the recursive call happens (the macro calls itself). The 
recursion level (recLev) is increased by one for the next call so that 
somewhere down the line, the series of Trace() calls will know to stop 
(preventing a ray from bouncing back and forth forever between two 
mirrors). This is basically how the max_trace_level global setting works 
in POV-Ray.</p>

<p>Finally, we close the code blocks and return the pixel color from the 
macro:</p>

<pre>
  #end // else

  Pixel
#end
</pre>

</div>
<a name="t2_3_11_9"></a>
<div class="content-level-h4" contains="Calculating the image" id="t2_3_11_9">
<h4>2.3.11.9 Calculating the image</h4>
<pre>
#debug &quot;Rendering...\n\n&quot;
#declare Image = array[ImageWidth][ImageHeight]

#declare IndY = 0;
#while(IndY &lt; ImageHeight)
  #declare CoordY = IndY/(ImageHeight-1)*2-1;
  #declare IndX = 0;
  #while(IndX &lt; ImageWidth)
    #declare CoordX =
       (IndX/(ImageWidth-1)-.5)*2*ImageWidth/ImageHeight;
    #declare Image[IndX][IndY] =
      Trace(-z*3, &lt;CoordX, CoordY, 3&gt;, 1);
    #declare IndX = IndX+1;
  #end
  #declare IndY = IndY+1;
  #debug concat(&quot;\rDone &quot;, str(100*IndY/ImageHeight,0,1),
    &quot;%  (line &quot;, str(IndY,0,0),&quot; out of &quot;,str(ImageHeight,0,0),&quot;)&quot;)
#end
#debug &quot;\n&quot;
</pre>

<p>Now we just have to calculate the image into an array of colors. This
array is defined at the beginning of the code above; it is a two-dimensional
array representing the final image we are calculating.</p>

<p>Notice how we use the <code>#debug</code> stream to output useful information
about the rendering process while we are calculating. This is nice because
the rendering process is quite slow and it is good to give the user some
feedback about what is happening and how long it will take. (Also note that
the &quot;<code>%</code>&quot; character in the string of the second
<code>#debug</code> command will work ok only in the Windows version of
POV-Ray; for other versions it may be necessary to convert it to
&quot;<code>%%</code>&quot;.)</p>

<p>What we do here is to go through each pixel of the image (ie. the
array) and for each one calculate the camera location (fixed to
<code>-z*3</code> here) and the direction of the ray that goes through the
pixel (in this code the viewing plane is fixed and located in the
x-y-plane and its height is fixed to 1).</p>

<p>What the following line:</p>

<pre>
  #declare CoordY = IndY/(ImageHeight-1)*2-1;
</pre>

<p>does is to scale the <code>IndY</code> so that it goes from -1 to 1.
It is first divided by the maximum value it gets (which is
<code>ImageHeight-1</code>) and then it is multiplied by 2 and substracted
by 1. This results in a value which goes from -1 to 1.</p>

<p>The <code>CoordX</code> is calculated similarly, but it is also multiplied
by the aspect ratio of the image we are calculating (so that we do not get
a squeezed image).</p>

</div>
<a name="t2_3_11_10"></a>
<div class="content-level-h4" contains="Creating the colored mesh" id="t2_3_11_10">
<h4>2.3.11.10 Creating the colored mesh</h4>
<p>If you think that these things we have been examining are advanced, then
you have not seen anything. Now comes real hard-core advanced POV-Ray code,
so be prepared. This could be called <em>The really advanced section</em>.</p>

<p>We have now calculated the image into the array of colors. However, we
still have to show these color pixels on screen, that is, we have to make
POV-Ray to render our pixels so that it creates a real image.</p>

<p>There are several ways of doing this, all of them being more or less
kludges (as there is currently no way of directly creating an image map
from a group of colors). One could create colored boxes representing each
pixel, or one could output to an ascii-formatted image file (mainly PPM)
and then read it as an image map. The first one has the disadvantage of
requiring huge amounts of memory and missing bilinear interpolation of the
image; the second one has the disadvantage of requiring a temporary file.</p>

<p>What we are going to do is to calculate a colored mesh2 which represents
the screen.
As colors are interpolated between the vertices of a triangle, the
bilinear interpolation comes for free (almost).</p>

</div>
<a name="t2_3_11_10_1"></a>
<div class="content-level-h5" contains="The structure of the mesh" id="t2_3_11_10_1">
<h5>2.3.11.10.1 The structure of the mesh</h5>
<p>Although all the triangles are located in the x-y plane and they are all
the same size, the structure of the mesh is quite complicated (so complicated
it deserves its own section here).</p>

<p>The following image shows how the triangles are arranged for a 4x3 pixels
image:</p>

<table class="centered" width="660px" cellpadding="0" cellspacing="10">
<tr>
  <td>
    <img class="center" width="640px" src="images/9/9a/TutImgTriangles.gif">
  </td>
</tr>
<tr>
  <td>
    <p class="caption">Triangle arrangement for a 4x3 image</p>
  </td>
</tr>
</table>

<p>The number pairs in parentheses represent image pixel coordinates
(eg. <code>(0,0)</code> refers to the pixel at the lower left corner of
the image and <code>(3,2)</code> to the pixel at the upper right corner).
That is, the triangles will be colored as the image pixels at these
points. The colors will then be interpolated between them along the surface
of the triangles.</p>

<p>The filled and non-filled circles in the image represent the vertex points
of the triangles and the lines connecting them show how the triangles are
arranged. The smaller numbers near these circles indicate their index value
(the one which will be created inside the <code>mesh2</code>).</p>

<p>We notice two things which may seem odd: Firstly there are extra vertex
points outside the mesh, and secondly, there are extra vertex points in the
middle of each square.</p>

<p>Let's start with the vertices in the middle of the squares: We could
have just made each square with two triangles instead of four, as we have
done here. However, the color interpolation is not nice this way, as there
appears a clear diagonal line where the triangle edges go. If we make
each square with four triangles instead, then the diagonal lines are
less apparent, and the interpolation resembles a lot better a true
bilinear interpolation. And what is the color of the middle points? Of
course it is the average of the color of the four points in the corners.</p>

<p>Secondly: Yes, the extra vertex points outside the mesh are completely
obsolete and take no part in the creation of the mesh. We could perfectly
create the exact same mesh without them. However, getting rid of these
extra vertex points makes our lives more difficult when creating the
triangles, as it would make the indexing of the points more difficult.
It may not be too much work to get rid of them, but they do not take
any considerable amount of resources and they make our lives easier, so
let's just let them be (if you want to remove them, go ahead).</p>

</div>
<a name="t2_3_11_10_2"></a>
<div class="content-level-h5" contains="Creating the mesh" id="t2_3_11_10_2">
<h5>2.3.11.10.2 Creating the mesh</h5>
<p>What this means is that for each pixel we create two vertex points,
one at the pixel location and one shifted by 0.5 in the x and y directions.
Then we specify the color for each vertex points: For the even vertex points
it is directly the color of the correspondent pixel; for the odd vertex points
it is the average of the four surrounding pixels.</p>

<p>Let's examine the creation of the mesh step by step:</p>

</div>
<a name="t2_3_11_10_3"></a>
<div class="content-level-h5" contains="Creating the vertex points" id="t2_3_11_10_3">
<h5>2.3.11.10.3 Creating the vertex points</h5>
<pre>
#default { finish { ambient 1 } }

#debug &quot;Creating colored mesh to show image...\n&quot;
mesh2
{ vertex_vectors
  { ImageWidth*ImageHeight*2,
    #declare IndY = 0;
    #while(IndY &lt; ImageHeight)
      #declare IndX = 0;
      #while(IndX &lt; ImageWidth)
        &lt;(IndX/(ImageWidth-1)-.5)*ImageWidth/ImageHeight*2,
         IndY/(ImageHeight-1)*2-1, 0&gt;,
        &lt;((IndX+.5)/(ImageWidth-1)-.5)*ImageWidth/ImageHeight*2,
         (IndY+.5)/(ImageHeight-1)*2-1, 0&gt;
        #declare IndX = IndX+1;
      #end
      #declare IndY = IndY+1;
    #end
  }
</pre>

<p>First of all we use a nice trick in POV-Ray: Since we are not using
light sources and there is nothing illuminating our mesh, what we do
is to set the ambient value of the mesh to 1. We do this by just making
it the default with the <code>#default</code> command, so we do not have
to bother later.</p>

<p>As we saw above, what we are going to do is to create two vertex points
for each pixel. Thus we know without further thinking how many vertex
vectors there will be: <code>ImageWidth*ImageHeight*2</code></p>

<p>That was the easy part; now we have to figure out how to create the
vertex points themselves. Each vertex location should correspond to the
pixel location it is representing, thus we go through each pixel index
(practically the number pairs in parentheses in the image above) and
create vertex points using these index values. The location of these
pixels and vertices are the same as we assumed when we calculated the
image itself (in the previous part). Thus the y coordinate of each vertex
point should go from -1 to 1 and similarly the x coordinate, but scaled
with the aspect ratio.</p>

<p>If you look at the creation of the first vector in the code above, you will
see that it is almost identical to the direction vector we calculated when
creating the image.</p>

<p>The second vector should be shifted by 0.5 in both directions, and that is
exactly what is done there. The second vector definition is identical to
the first one except that the index values are shifted by 0.5. This creates
the points in the middle of the squares.</p>

<p>The index values of these points will be arranged as shown in the image
above.</p>

</div>
<a name="t2_3_11_10_4"></a>
<div class="content-level-h5" contains="Creating the textures" id="t2_3_11_10_4">
<h5>2.3.11.10.4 Creating the textures</h5>
<pre>
  texture_list
  { ImageWidth*ImageHeight*2,
    #declare IndY = 0;
    #while(IndY &lt; ImageHeight)
      #declare IndX = 0;
      #while(IndX &lt; ImageWidth)
        texture { pigment { rgb Image[IndX][IndY] } }
        #if(IndX &lt; ImageWidth-1 &amp; IndY &lt; ImageHeight-1)
          texture { pigment { rgb
            (Image[IndX][IndY]+Image[IndX+1][IndY]+
             Image[IndX][IndY+1]+Image[IndX+1][IndY+1])/4 } }
        #else
          texture { pigment { rgb 0 } }
        #end
        #declare IndX = IndX+1;
      #end
      #declare IndY = IndY+1;
    #end
  }
</pre>

<p>Creating the textures is very similar to creating the vertex points
(we could have done both inside the same loop, but due to the syntax
of the <code>mesh2</code> we have to do it separately).</p>

<p>So what we do is to go through all the pixels in the image and create
textures for each one. The first texture is just the pixel color itself.
The second texture is the average of the four surrounding pixels. </p>
<p class="Note"><strong>Note:</strong> We can calculate it only for the vertex points in the middle of
the squares; for the extra vertex points outside the image we just define
a dummy black texture.</p>

<p>The textures have the same index values as the vertex points.</p>

</div>
<a name="t2_3_11_10_5"></a>
<div class="content-level-h5" contains="Creating the triangles" id="t2_3_11_10_5">
<h5>2.3.11.10.5 Creating the triangles</h5>
<p>This one is a bit trickier. Basically we have to create four triangles
for each square between pixels. How many triangles will there be?</p>

<p>Let's examine the creation loop first:</p>

<pre>
  face_indices
  { (ImageWidth-1)*(ImageHeight-1)*4,
    #declare IndY = 0;
    #while(IndY &lt; ImageHeight-1)
      #declare IndX = 0;
      #while(IndX &lt; ImageWidth-1)

        ...

        #declare IndX = IndX+1;
      #end
      #declare IndY = IndY+1;
    #end
  }
</pre>

<p>The number of squares is one less than the number of pixels in each
direction. That is, the number of squares in the x direction will be one
less than the number of pixels in the x direction. The same for the y
direction. As we want four triangles for each square, the total number of
triangles will then be <code>(ImageWidth-1)*(ImageHeight-1)*4</code>.</p>

<p>Then to create each square we loop the amount of pixels minus one for
each direction.</p>

<p>Now in the inside of the loop we have to create the four triangles.
Let's examine the first one:</p>

<pre>
        &lt;IndX*2+  IndY    *(ImageWidth*2),
         IndX*2+2+IndY    *(ImageWidth*2),
         IndX*2+1+IndY    *(ImageWidth*2)&gt;,
         IndX*2+  IndY    *(ImageWidth*2),
         IndX*2+2+IndY    *(ImageWidth*2),
         IndX*2+1+IndY    *(ImageWidth*2),
</pre>

<p>This creates a triangle with a texture in each vertex. The first three
values (the indices to vertex points) are identical to the next three values
(the indices to the textures) because the index values were exactly the same
for both.</p>

<p>The <code>IndX</code> is always multiplied by 2 because we had two vertex
points for each pixel and <code>IndX</code> is basically going through the
pixels. Likewise <code>IndY</code> is always multiplied by
<code>ImageWidth*2</code> because that is how long a row of index points
is (ie. to get from one row to the next at the same x coordinate we have
to advance <code>ImageWidth*2</code> in the index values).</p>

<p>These two things are identical in all the triangles. What decides which
vertex point is chosen is the &quot;+1&quot; or &quot;+2&quot; (or &quot;+0&quot; when there is nothing).
For <code>IndX</code> &quot;+0&quot; is the current pixel, &quot;+1&quot; chooses the point in
the middle of the square and &quot;+2&quot; chooses the next pixel. For
<code>IndY</code> &quot;+1&quot; chooses the next row of pixels.</p>

<p>Thus this triangle definition creates a triangle using the vertex point
for the current pixel, the one for the next pixel and the vertex point in
the middle of the square.</p>

<p>The next triangle definition is likewise:</p>

<pre>
        &lt;IndX*2+  IndY    *(ImageWidth*2),
         IndX*2+  (IndY+1)*(ImageWidth*2),
         IndX*2+1+IndY    *(ImageWidth*2)&gt;,
         IndX*2+  IndY    *(ImageWidth*2),
         IndX*2+  (IndY+1)*(ImageWidth*2),
         IndX*2+1+IndY    *(ImageWidth*2),
</pre>

<p>This one defines the triangle using the current point, the point in the
next row and the point in the middle of the square.</p>

<p>The next two definitions define the other two triangles:</p>

<pre>
        &lt;IndX*2+  (IndY+1)*(ImageWidth*2),
         IndX*2+2+(IndY+1)*(ImageWidth*2),
         IndX*2+1+IndY    *(ImageWidth*2)&gt;,
         IndX*2+  (IndY+1)*(ImageWidth*2),
         IndX*2+2+(IndY+1)*(ImageWidth*2),
         IndX*2+1+IndY    *(ImageWidth*2),

        &lt;IndX*2+2+IndY    *(ImageWidth*2),
         IndX*2+2+(IndY+1)*(ImageWidth*2),
         IndX*2+1+IndY    *(ImageWidth*2)&gt;,
         IndX*2+2+IndY    *(ImageWidth*2),
         IndX*2+2+(IndY+1)*(ImageWidth*2),
         IndX*2+1+IndY    *(ImageWidth*2)
</pre>

</div>
<a name="t2_3_11_11"></a>
<div class="content-level-h4" contains="The Camera-setup" id="t2_3_11_11">
<h4>2.3.11.11 The Camera-setup</h4>
<p>The only thing left is the camera definition, so that POV-Ray can
calculate the image correctly:</p>

<pre>
  camera { orthographic location -z*2 look_at 0 }
</pre>

<p>Why 2? As the default <code>direction</code> vector is
<code>&lt;0,0,1&gt;</code> and the default <code>up</code> vector is
<code>&lt;0,1,0&gt;</code> and we want the up direction to cover 2 units,
we have to move the camera two units away.</p>

</div>

</div>

</div>
</body>
</html>