home *** CD-ROM | disk | FTP | other *** search
/ Collection of Hack-Phreak Scene Programs / cleanhpvac.zip / cleanhpvac / FAQSYS18.ZIP / FAQS.DAT / POV~1.SPE < prev    next >
Text File  |  1996-08-18  |  178KB  |  4,357 lines

  1.                 Persistence of Vision Ray Tracer (POV-Ray)
  2.  
  3.                                 Version 2.0
  4.  
  5.                            User's Documentation
  6.                             
  7.  
  8.                         Copyright 1993 POV-Ray Team   
  9.  
  10.  
  11. 5.0   SCENE DESCRIPTION LANGUAGE REFERENCE
  12. ==========================================
  13.  
  14. The Scene Description Language allows the user to describe the world in a 
  15. readable and convenient way.  Files are created in plain ASCII text using 
  16. an editor of your choice.  POV-Ray reads the file, processes it by creating 
  17. an internal model of the scene and the renders the scene.
  18.  
  19.  
  20. 5.1   LANGUAGE BASICS
  21. ---------------------
  22.  
  23. The POV-Ray language consists of identifiers, reserved keywords, floating 
  24. point literals, string literals, special symbols and comments.  The text of 
  25. a POV-Ray scene file is free format.  You may put statements on separate 
  26. lines or on the same line as you desire.  You may add blank lines, spaces 
  27. or indentations as long as you do not split any keywords or identifiers.
  28.  
  29.  
  30. 5.1.1 IDENTIFIERS AND KEYWORDS
  31.  
  32. POV-Ray allows you to define identifiers for later use in the file.  An 
  33. identifier may be 1 to 40 characters long.  It may consist of upper or 
  34. lower case letters, the digits 0 through 9 or an underscore character.  The 
  35. first character must be an alphabetic character.  The declaration of 
  36. identifiers is covered later.
  37.  
  38. POV-Ray has a number of reserved words which are used in the language.  All 
  39. reserved words are fully lower case.  Therefore it is recommended that your 
  40. identifiers contain at least 1 upper case character so it is sure to avoid 
  41. conflict with reserved words.
  42.  
  43. The following keywords are reserved in POV-Ray:
  44.  
  45. adaptive               height_field           rgbf                  
  46. agate                  hexagon                right                 
  47. agate_turb             iff                    ripples               
  48. all                    image_map              rotate                
  49. alpha                  include                roughness             
  50. ambient                interpolate            scale                 
  51. area_light             intersection           sky                   
  52. background             inverse                smooth                
  53. bicubic_patch          ior                    smooth_triangle       
  54. blob                   jitter                 specular              
  55. blue                   lambda                 sphere                
  56. bounded_by             leopard                spotlight             
  57. box                    light_source           spotted               
  58. bozo                   location               sturm                 
  59. brilliance             looks_like             texture               
  60. bumps                  look_at                tga                   
  61. bump_map               mandel                 threshold             
  62. bump_size              map_type               tightness             
  63. camera                 marble                 tile2                 
  64. checker                material_map           tiles                 
  65. clipped_by             max_intersections      torus                 
  66. clock                  max_trace_level        translate             
  67. color                  merge                  triangle              
  68. color_map              metallic               turbulence            
  69. colour                 normal                 type                  
  70. colour_map             no_shadow              union                 
  71. component              object                 up                    
  72. composite              octaves                use_color             
  73. cone                   omega                  use_colour            
  74. crand                  once                   use_index             
  75. cubic                  onion                  u_steps               
  76. cylinder               open                   version               
  77. declare                phase                  v_steps               
  78. default                phong                  water_level           
  79. dents                  phong_size             waves                 
  80. difference             pigment                wood                  
  81. diffuse                plane                  wrinkles              
  82. direction              point_at               x                     
  83. disc                   poly                   y                     
  84. distance               pot                    z                     
  85. dump                   quadric               
  86. falloff                quartic               
  87. filter                 quick_color           
  88. finish                 quick_colour          
  89. flatness               radial                
  90. fog                    radius                
  91. frequency              raw                   
  92. gif                    red                   
  93. gradient               reflection            
  94. granite                refraction            
  95. green                  rgb                   
  96.                        
  97.                        
  98. 5.1.2 COMMENTS
  99.  
  100. Comments are text in the scene file included to make the scene file easier 
  101. to read or understand. They are ignored by the ray tracer and are there for 
  102. humans to read.  There are two types of comments in POV-Ray.
  103.  
  104. Two slashes are used for single line comments.  Anything on a line after a 
  105. double slash // is ignored by the ray tracer.  For example:
  106.  
  107.   // This line is ignored
  108.  
  109. You can have scene file information on the line in front of the comment, as 
  110. in:
  111.  
  112.   object { FooBar }  // this is an object
  113.  
  114. The other type of comment is used for multiple lines.  This type of comment 
  115. starts with /* and ends with */ everything in-between is ignored.  For 
  116. example:
  117.  
  118. /* These lines
  119.     Are ignored 
  120.     By the
  121.     Raytracer */
  122.  
  123. This can be useful if you want to temporarily remove elements from a scene 
  124. file.   /*...*/ comments can "comment out" lines containing the other // 
  125. comments, and thus can be used to temporarily or permanently comment out 
  126. parts of a scene.  /*..*/ comments can be nested, the following is legal:
  127.  
  128. /* This is a comment
  129.     // This too
  130.     /* This also */
  131.  */
  132.  
  133. Use comments liberally and generously. Well used, they really improve the 
  134. readability of scene files.
  135.  
  136.  
  137. 5.1.3 INCLUDE FILES
  138.  
  139. The language allows include files to be specified by placing the line:
  140.  
  141.     #include "filename.inc"
  142.  
  143. at any point in the input file. The filename must be enclosed in double 
  144. quotes and may be up to 40 characters long (or your computer's limit), 
  145. including the two double-quote (") characters. 
  146.  
  147. The include file is read in as if it were inserted at that point in the 
  148. file. Using include is the same as actually cutting and pasting the entire 
  149. contents of this file into your scene. 
  150.  
  151. Include files may be nested. You may have at most 10 nested include files.  
  152. There is no limit on un-nested include files.
  153.  
  154. Generally, include files have data for scenes, but are not scenes in 
  155. themselves. By convention scene files end in .pov and include files end 
  156. with .inc.
  157.  
  158.  
  159. 5.1.4 FLOAT EXPRESSIONS
  160.  
  161. Many parts of the POV-Ray language require you to specify one or more 
  162. floating point numbers.  A floating point number is a number with a decimal 
  163. point.  Float literals are represented by an optional sign (-), some 
  164. digits, an optional decimal point, and more digits.  If the number is an 
  165. integer you may omit the decimal point and trailing zero.  If it is all 
  166. fractional you may omit the leading zero.  POV-Ray supports scientific 
  167. notation for very large or very small numbers.  The following are all valid 
  168. float literals:
  169.  
  170.       1.0   -2.0  -4    34    3.4e6       2e-5        .3    0.6
  171.  
  172. Float identifiers may be declared and used anywhere a float can be used.  
  173. See section 5.1.7 on declaring identifiers.  
  174.  
  175. Complex float expressions can be created using + - * / ( ) with float 
  176. literals or identifiers.  Assuming the identifiers have been previously 
  177. declared as floats, the following are valid float expressions:
  178.  
  179.       1+2+3       2*5         1/3         Row*3       Col*5
  180.  
  181.       (Offset-5)/2            This/That+Other*Thing
  182.  
  183. Expressions are evaluated left to right with innermost parenthesis 
  184. evaluated first, then unary + or -, then multiply or divide, then add or 
  185. subtract.
  186.  
  187. There are two built-in float identifiers.  The identifier "version" is the 
  188. current setting of the version compatibility switch (See +MV under command-
  189. line switches).  This allows you to save and restore the previous version 
  190. switch.  For example suppose MYSTUFF.INC is in version 1.0 format.  At the 
  191. top of the file you could put:
  192.  
  193.   #declare Temp_Vers = version    // Save previous value
  194.   #version 1.0                    // Change to 1.0 mode
  195.  
  196.   ...   // Version 1.0 stuff goes here...
  197.  
  198.   #version Temp_Vers              // Restore previous version
  199.  
  200. The other float identifier is "clock".  Its value is set by the +K command-
  201. line switch. (See +K under command-line switches).  This allows you to do 
  202. limited animation control.  For example you could move an object using:
  203.  
  204.    translate <0.1*clock,0,0>
  205.  
  206. and render successive frames with +K1, +K2, +K3 etc.  In each frame the 
  207. object would move 1/10th of a unit.
  208.  
  209.  
  210. 5.1.5 VECTOR EXPRESSIONS
  211.  
  212. POV-Ray operates in a 3D x,y,z coordinate system.  Often you will need to 
  213. specify x, y and z values.  A "vector" is a set of three float values used 
  214. for such specification.  Vectors consist of three float expressions that 
  215. are bracketed by angle brackets < and >.  The three terms are separated by 
  216. commas.  For example:
  217.  
  218.      < 1.0, 3.2, -5.4578 >
  219.  
  220. The commas are necessary to keep the program from thinking that the 2nd 
  221. term is "3.2-5.4578" and that there is no 3rd term.  If you see an error 
  222. message "Float expected but '>' found instead" it probably means two floats 
  223. were combined because a comma was missing.
  224.  
  225. The three values correspond to the x, y and z directions respectively. For 
  226. example, the vector <1,2,3> means the point that's 1 unit to the right, 2 
  227. units up, and 3 units in front the center of the "universe" at <0,0,0>. 
  228. Vectors are not always points, though. They can also refer to an amount to 
  229. size, move, or rotate a scene element.
  230.  
  231. Vectors may also be combined in expressions the same as float values.  For 
  232. example <1,2,3>+<4,5,6> evaluates as <5,7,9>.  Subtraction, multiplication 
  233. and division are also performed on a term-by-term basis.  You may also 
  234. combine floats with vectors.  For example 5*<1,2,3> evaluates as <5,10,15>.
  235.  
  236. Sometimes POV-Ray requires you to specify floats and vectors side-by-side.  
  237. Thus commas are required separators whenever an ambiguity might arise.  For 
  238. example <1,2,3>-4 evaluates as <-3,-2,-1> but <1,2,3>,-4 is a vector 
  239. followed by a float.
  240.  
  241. Vector identifiers may be declared and used anywhere a vector can be used.  
  242. See section 5.1.7 on declaring identifiers.
  243.  
  244. Because vectors almost always refer to the x, y and z coordinates, POV-Ray 
  245. has three built-in vector identifiers "x "y" and "z".  Like all POV-Ray 
  246. keywords they must be lower case.  The vector identifier x is equivalent to 
  247. the vector <1,0,0>.  Similarly y is <0,1,0> and z is <0,0,1>.
  248.  
  249. Thus an expression like 5*x evaluates to 5*<1,0,0> or <5,0,0>.  The use of 
  250. these identifiers can make the scene file easier to read.
  251.  
  252.  
  253. 5.1.6 TRANSFORMATIONS
  254.  
  255. Vectors are used not only as a notation for a point in space but are used 
  256. in the transformations scale, rotate, and translate. Scale sizes a texture 
  257. or object. Translate moves a texture or object. And rotate turns a texture 
  258. or object.
  259.  
  260.  
  261. 5.1.6.1     Translate
  262.  
  263. An object or texture pattern may be moved by adding a "translate" 
  264. parameter.  It consists of the keyword "translate" followed by a vector.  
  265. The terms of the vector specify the number of units to move in each of the 
  266. x, y, and z directions.  Translate moves the element relative to it's 
  267. current position. For example,
  268.  
  269.   sphere { <10, 10, 10>, 1 
  270.     pigment { Green }
  271.     translate <-5, 2, 1>
  272.   }
  273.  
  274. Will move the sphere from <10, 10, 10> to <5, 12, 11>.  It does not move it 
  275. to absolute location <5, 2, 1>. Translating by zero will leave the element 
  276. unchanged on that axis. For example,
  277.  
  278.   sphere { <10, 10, 10>, 1 
  279.     pigment { Green }
  280.     translate <0, 0, 0>
  281.   }
  282.  
  283. Will not move the sphere at all.
  284.  
  285.  
  286. 5.1.6.2     Scale
  287.  
  288. You may change the size of an object or texture pattern by adding a "scale" 
  289. parameter.  It consists of the keyword "scale" followed by a vector or a 
  290. single float value.  If a vector is used, terms of the vector specify the 
  291. amount of scaling in each of the x, y, and z directions.  If a float value 
  292. is used, the item is uniformly scaled by the same amount in all directions.
  293.  
  294. Scale, is used to "stretch" or "squish" an element. Values larger than 1 
  295. stretch the element on that axis. Values smaller than one are used to 
  296. squish the element on that axis. Scale is relative to the current element 
  297. size. If the element has been previously re-sized using scale, then scale 
  298. will size relative to the new size. Multiple scale values may used.
  299.  
  300.  
  301. 5.1.6.3     Rotate
  302.  
  303. You may change the orientation of an object or texture pattern by adding a 
  304. "rotate" parameter.  It consists of the keyword "rotate" followed by a 
  305. vector.  The three terms of the vector specify the number of degrees to 
  306. rotate about each of the x, y, and z axes.  
  307.  
  308. Note that the order of the rotations does matter.  Rotations occur about 
  309. the x axis first, then the y axis, then the z axis.  If you are not sure if 
  310. this is what you want then you should use multiple rotation statements to 
  311. get a correct rotation. You should only rotate on one axis at a time. As 
  312. in,
  313.  
  314.    rotate <0, 30, 0>  // 30 degrees around Y axis then,
  315.    rotate <-20, 0, 0> // -20 degrees around X axis then,
  316.    rotate <0, 0, 10>  // 10 degrees around Z axis.
  317.  
  318. Rotation is always performed relative to the axis.  Thus if an object is 
  319. some distance from the axis of rotation, its will not only rotate but it 
  320. will "orbit" about the axis as though it was swinging around on an 
  321. invisible string.  
  322.  
  323. To work out the rotation directions, you must perform the famous "Computer 
  324. Graphics Aerobics" exercise. Hold up your left hand. Point your thumb in 
  325. the positive direction of the axis of rotation. Your fingers will curl in 
  326. the positive direction of rotation. Similarly if you point your thumb in 
  327. the negative direction of the axis your fingers will curl in the negative 
  328. direction of rotation.  This is the famous "left-hand coordinate system". 
  329.  
  330.                ^
  331.              +Y|   +Z/ _
  332.                |    /_| |_  _
  333.                |   _| | | |/ \
  334.                |  | | | | |  |
  335.                | /| | | | |  V
  336.      -X        |/ | | | | |    +X
  337.     <----------+--|-|-|-|-|------>
  338.               /|  |       \____
  339.              / |  |         ___|
  340.             /  |  \        /
  341.            /   |   |      /
  342.         -Z/  -Y|
  343.          /     |
  344.  
  345. In this illustration, the left hand is curling around the X axis. The thumb 
  346. points in the positive X direction and the fingers curl over in the 
  347. positive rotation direction.
  348.  
  349. If you want to use a right hand system, as some CAD systems such as AutoCAD 
  350. do, the "right" vector in the camera specification needs to be changed. See 
  351. the detailed description of the camera.  In a right handed system you use 
  352. your right hand for the "Aerobics". 
  353.  
  354.  
  355. 5.1.6.4     Transforming Textures and Objects
  356.  
  357. When an object is transformed, all textures attached to the object AT THAT 
  358. TIME are transformed as well. This means that if you have a translate, 
  359. rotate, or scale in an object BEFORE a texture, the texture will not be 
  360. transformed. If the scale, translate, or rotate is AFTER the texture then 
  361. the texture will be transformed with the object.  If the transformation is 
  362. INSIDE the "texture { }" statement then ONLY THE TEXTURE is affected.  The 
  363. shape remains the same.  For example:
  364.  
  365.    sphere { <0, 0, 0>, 1
  366.      texture { White_Marble }  // texture identifier from TEXTURES.INC
  367.      scale 3                   // This scale affects both the 
  368.                                // shape and texture 
  369.    }
  370.  
  371.    sphere { <0, 0, 0>, 1
  372.      scale 3             // This scale affects the shape only
  373.      texture { White_Marble }  
  374.    }
  375.  
  376.    sphere { <0, 0, 0>, 1
  377.      texture { 
  378.        White_Marble      
  379.        scale 3           // This scale affects the texture only
  380.      }  
  381.    }
  382.  
  383. Transformations may also be independently applied to pigment patterns and 
  384. surface normal (bump) patterns.  Note scaling a normal pattern affects only 
  385. the width and spacing.  It does not affect the height or depth.  For 
  386. example:
  387.  
  388.    box { <0, 0, 0>, <1, 1, 1>
  389.      texture { 
  390.        pigment {
  391.          checker color Red color White
  392.          scale 0.25  // This affects only the color pattern
  393.        }
  394.        normal {
  395.          bumps 0.3   // This specifies apparent height of bumps
  396.          scale 0.2   // Scales diameter and space between bumps but not 
  397.                      //  not the height. Has no effect on color pattern.
  398.        }
  399.        rotate y*45   // This affects the entire texture but not
  400.      }               //  the object. 
  401.    }
  402.  
  403.  
  404. 5.1.6.5     Transformation Order
  405.  
  406. Because rotations are always relative to the axis and scaling is relative 
  407. to the origin, you will generally want to create an object at the origin 
  408. and scale and rotate it first.  Then you may translate it into its proper 
  409. position.  It is a common mistake to carefully position an object and then 
  410. to decide to rotate it.  Because a rotation of an object causes it to orbit 
  411. the axis, the position of the object may change so much that it orbits out 
  412. of the field of view of the camera!
  413.  
  414. Similarly scaling after translation also moves an object unexpectedly. If 
  415. you scale after you translate, the scale will multiply the translate 
  416. amount. For example:
  417.  
  418.   translate <5, 6, 7>
  419.   scale 4 
  420.  
  421. Will translate to 20, 24, 28 instead of 5, 6, 7. Be careful when 
  422. transforming to get the order correct for your purposes.
  423.  
  424.  
  425. 5.1.7 DECLARE
  426.  
  427. The parameters used to describe the scene elements can be tedious to use at 
  428. times. Some parameters are often repeated and it seems wasteful to have to 
  429. type them over and over again. To make this task easier, the program allows 
  430. users to create identifiers as synonyms for a pre-defined set of parameters 
  431. and use them anywhere the parameters would normally be used. For example, 
  432. the color white is defined in the POV-Ray language as:
  433.  
  434.    color red 1 green 1 blue 1
  435.  
  436. This can be pre-defined in the scene as:
  437.  
  438.    #declare White = color red 1 green 1 blue 1
  439.  
  440. and then substituted for the full description in the scene file, for 
  441. example:
  442.  
  443.    sphere { 
  444.      <0, 0, 0>, 1
  445.      pigment { color red 1 green 1 blue 1 }
  446.    }
  447.  
  448. becomes:
  449.  
  450.    #declare White = color red 1 green 1 blue 1
  451.  
  452.    sphere { 
  453.      <0, 0, 0>, 1
  454.      pigment { color White }
  455.    }
  456.  
  457. This is much easier to type and to read. The pre-defined element may be 
  458. used many times in a scene.
  459.  
  460. You use the keyword "declare" to pre-define a scene element and give it a 
  461. one-word identifier. This pre-defined scene element is not used in the 
  462. scene until you invoke its identifier. Textures, objects, colors, numbers 
  463. and more can be predefined.
  464.  
  465. In most cases when you invoke an identifier you simply use the form 
  466. "keyword{identifier}" where the keyword used is the type of statement that 
  467. was declared. For example:
  468.  
  469.   #declare Shiny = finish {phong 0.8 phong_size 50 reflection 0.2}
  470.  
  471.   sphere {
  472.      <0, 0, 0>, 1
  473.      pigment { color White }
  474.      finish { Shiny }
  475.    }
  476.  
  477. The identifier "Shiny" was declared as a "finish" and is invoked by placing 
  478. it inside a "finish { }" statement.
  479.  
  480. One exception is object identifiers.  If you declare any object of any kind 
  481. such as sphere, box, union, intersection etc. you should invoke it by 
  482. placing it in an "object { }" statement.  Thus you might have:
  483.  
  484.   #declare Thing = intersection {...}
  485.  
  486.   object {Thing}  // not "intersection{Thing}"
  487.  
  488. Pre-defined elements may be modified when they are used, for example:
  489.  
  490.   #declare Mickey = // Pre-define a union object called Mickey
  491.      union {
  492.        sphere { < 0, 0, 0>, 2 }
  493.        sphere { <-2, 2, 0>, 1 }
  494.        sphere { < 2, 2, 0>, 1 }
  495.      }
  496.  
  497.   // Use Mickey
  498.      object{        // Note use of "object", not "union" keyword
  499.        Mickey
  500.        scale 3
  501.        rotate y*20
  502.        translate <0, 8, 10>
  503.        pigment {color red 1}
  504.        finish {phong .7}
  505.      }
  506.  
  507. This scene will only have one "Mickey", the Mickey that is described 
  508. doesn't appear in the scene. Notice that Mickey is scaled, rotated, 
  509. translated, and a texture is added to it. The Mickey identifier could be 
  510. used many times in a scene file, and each could have a different size, 
  511. position, orientation, and texture.
  512.  
  513. Declare is especially powerful when used to create a complex object. Each 
  514. part of the object is defined separately using declare. These parts can be 
  515. tested, rotated, sized, positioned, and textured separately then combined 
  516. in one shape or object for the final sizing, positioning, etc. For example, 
  517. you could define all the parts of a car like this:
  518.  
  519.   #declare Wheel = object {...}
  520.   #declare Seat = object {...}
  521.   #declare Body = object {...}
  522.   #declare Engine = object {...}
  523.   #declare Steering_Wheel = object {...}
  524.  
  525.   #declare Car = 
  526.     union {
  527.        object { Wheel translate < 1, 1, 2>}
  528.        object { Wheel translate <-1, 1, 2>}
  529.        object { Wheel translate < 1, 1,-2>}
  530.        object { Wheel translate <-1, 1,-2>}
  531.        object { Seat translate < .5, 1.4, 1>}
  532.        object { Seat translate <-.5, 1.4, 1>}
  533.        object { Steering_Wheel translate <-.5, 1.6, 1.3>}
  534.        object { Body texture { Brushed_Steel } }
  535.        object { Engine translate <0, 1.5, 1.5> 
  536.     }
  537.  
  538. and then it like this:
  539.  
  540.   // Here is a car
  541.   object {
  542.     Car 
  543.     translate <4, 0, 23>
  544.   }
  545.  
  546. Notice that the Wheel and Seat are used more than once. A declared element 
  547. can be used as many times as you need. Declared elements may be placed in 
  548. "include" files so they can be used with more than one scene.
  549.  
  550. There are several files included with POV-Ray that use declare to pre-
  551. define many shapes, colors, and textures. See the archive INCLUDE for more 
  552. info.
  553.  
  554. NOTE: Declare is not the same as the C language's define. Declare creates 
  555. an internal object of the type specified that POV-Ray can copy for later 
  556. use.  The "define" used in C creates a text substitution macro.
  557.  
  558. Here's a list of what can be declared, how to declare the element, and how 
  559. to use the declaration. See the reference section for element syntax.
  560.  
  561. Objects: (Any type may be declared, sphere, box, height_field, blob, etc.)
  562.   #declare Tree = union {...}
  563.   #declare Ball = sphere {...}
  564.   #declare Crate= box {...}
  565.  
  566.   object {
  567.     Tree
  568.     (OBJECT_MODIFIERS...) 
  569.   }
  570.  
  571.   object {
  572.     Ball
  573.     (OBJECT_MODIFIERS...) 
  574.   }
  575.  
  576.   object {
  577.     Crate
  578.     (OBJECT_MODIFIERS...) 
  579.   }
  580.  
  581. Textures:
  582.   #declare Fred = texture {...} 
  583.  
  584.   sphere { <0, 0, 0>, 1 
  585.     texture {
  586.       Fred 
  587.       (texture_modifiers) 
  588.     }
  589.   }
  590.  
  591. Layered textures:
  592.   #declare Fred = 
  593.      texture {...} 
  594.      texture {...} 
  595.      texture {...} (etc.)
  596.  
  597.   sphere { <0, 0, 0>, 1 
  598.     texture {
  599.       Fred 
  600.       (texture_modifiers) 
  601.     }
  602.   }
  603.  
  604. Pigment:
  605.   #declare Fred = pigment {checker color Red color White} 
  606.  
  607.   sphere { <0, 0, 0>, 1 
  608.     pigment {
  609.       Fred 
  610.       (pigment_modifiers) 
  611.     }
  612.   }
  613.  
  614. Normal:
  615.   #declare Fred = normal {bumps 0.5} 
  616.  
  617.   sphere { <0, 0, 0>, 1 
  618.     pigment {White}
  619.     normal {
  620.       Fred 
  621.       (normal_modifiers) 
  622.     }
  623.   }
  624.  
  625. Finish:
  626.   #declare Fred = finish {phong 0.7 reflection 0.2} 
  627.  
  628.   sphere { <0, 0, 0>, 1 
  629.     pigment {White}
  630.     finish {
  631.       Fred 
  632.       (finish_items) 
  633.     }
  634.   }
  635.  
  636. Colors:
  637.   #declare Fred = color red 1 green 1 blue 1 
  638.  
  639.   sphere { <0, 0, 0>, 1 
  640.     pigment { color Fred }
  641.   }
  642.  
  643. Color_map:
  644.   #declare Rainbow = 
  645.     color_map {
  646.       [0.0 color Cyan]
  647.       [1/3 color Yellow]
  648.       [2/3 color Magenta]
  649.       [1.0 color Cyan]
  650.     }
  651.  
  652.   sphere { <0, 0, 0>, 1 
  653.     pigment { radial color_map{Rainbow} rotate -90*x}
  654.   }
  655.  
  656. Float Values:
  657.   #declare Fred  = 3.45
  658.   #declare Fred2 = .02
  659.   #declare Fred3 = .5
  660.  
  661.  // Use the numeric value identifier 
  662.  // anywhere a number would go
  663.   sphere { <-Fred, 2, Fred>, Fred 
  664.     pigment { color red 1 }
  665.     finish { phong Fred3 }
  666.   }
  667.  
  668. Camera:
  669.   #declare Fred = camera {..}
  670.  
  671.   camera { Fred }
  672.  
  673. Vectors:
  674.    #declare Fred = <9, 3, 2>
  675.    #declare Fred2 = <4, 1, 4>
  676.  
  677.    sphere { Fred, 1  // Note do not put < > brackets
  678.      scale Fred2     // around vector identifiers
  679.    }
  680.  
  681.  
  682. 5.2   OBJECTS
  683. -------------
  684.  
  685. Objects are the building blocks of your scene.  There are 20 different 
  686. types of objects supported by POV-Ray.  Seven of them are finite solid 
  687. primitives, 4 are finite patch primitives, 5 are infinite solid polynomial 
  688. primitives, 3 are types of Constructive Solid Geometry types and one is a 
  689. specialized object that is a light source.
  690.  
  691. The basic syntax of an object is a keyword describing its type, some 
  692. floats, vectors or other parameters which further define its location 
  693. and/or shape and some optional object modifiers such as texture, pigment, 
  694. normal, finish, bounding, clipping or transformations.
  695.  
  696. The texture describes what the object looks like, ie. its material.  
  697. Textures are combinations of pigments, normals and finishes.  Pigment is 
  698. the color or pattern of colors inherent in the material.  Normal is a 
  699. method of simulating various patterns of bumps, dents, ripples or waves by 
  700. modifying the surface normal vector.  Finish describes the reflective and 
  701. refractive properties of a material.
  702.  
  703. Bounding shapes are finite, invisible shapes which wrap around complex, 
  704. slow rendering shapes in order to speed up rendering time.  Clipping shapes 
  705. are used to cut away parts of shapes to expose a hollow interior.  
  706. Transformations tell the ray tracer how to move, size or rotate the shape 
  707. and/or the texture in the scene.
  708.  
  709.  
  710. 5.2.1 SOLID FINITE PRIMITIVES
  711.  
  712. There are 7 different solid finite primitive shapes: blob, box, cone, 
  713. cylinder, height_field, sphere, and torus. These have a well-defined 
  714. "inside" and can be used in Constructive Solid Geometry. Because these 
  715. types are finite, POV-Ray can use automatic bounding on them to speed up 
  716. rendering time.  
  717.  
  718.  
  719. 5.2.1.1     Spheres
  720.  
  721. Since spheres are so common in ray traced graphics, POV-Ray has a highly 
  722. optimized sphere primitive which renders much more quickly than the 
  723. corresponding polynomial quadric shape. The syntax is:
  724.  
  725.      sphere { <CENTER>, RADIUS }
  726.  
  727. Where <CENTER> is a vector specifying the x,y,z coordinates of the center 
  728. of the sphere and RADIUS is a float value specifying the radius.  You can 
  729. also add translations, rotations, and scaling to the sphere. For example, 
  730. the following two objects are identical:
  731.  
  732.   sphere { <0, 25, 0>, 10
  733.     pigment {Blue}
  734.   }
  735.  
  736.   sphere { <0, 0, 0>, 1.0
  737.     pigment {Blue}
  738.     scale 10
  739.     translate y*25
  740.   }
  741.  
  742. Note that Spheres may be scaled unevenly giving an ellipsoid shape. 
  743.  
  744. Because spheres are highly optimized they make good bounding shapes. 
  745. Because they are finite they respond to automatic bounding. As with all 
  746. shapes, they can be translated, rotated and scaled.
  747.  
  748.  
  749. 5.2.1.2     Boxes
  750.  
  751. A simple box can be defined by listing two corners of the box like this:
  752.  
  753.   box { <CORNER1>, <CORNER2> }
  754.  
  755. Where <CORNER1> and <CORNER2> are vectors defining the x,y,z coordinates of 
  756. opposite corners of the box.  For example:
  757.  
  758.   box { <0, 0, 0>, <1, 1, 1> }
  759.  
  760. Note that all boxes are defined with their faces parallel to the coordinate 
  761. axes.  They may later be rotated to any orientation using a rotate 
  762. parameter.
  763.  
  764. Each element of CORNER1 should always be less than the corresponding 
  765. element in CORNER2. If any elements of CORNER1 are larger than CORNER2, the 
  766. box will not appear in the scene.
  767.  
  768. Boxes are calculated efficiently and make good bounding shapes. Because 
  769. they are finite they respond to automatic bounding. As with all 
  770. shapes, they can be translated, rotated and scaled.
  771.  
  772.  
  773. 5.2.1.3     Cylinders
  774.  
  775. A finite length cylinder with parallel end caps may be defined by.
  776.  
  777.    cylinder { <END1>, <END2>, RADIUS }
  778.  
  779. Where <END1> and <END2> are vectors defining the x,y,z coordinates of the 
  780. center of each end of the cylinder and RADIUS is a float value for the 
  781. radius.  For example:
  782.  
  783.    cylinder { <0,0,0>, <3,0,0>, 2}
  784.  
  785. is a cylinder 3 units long lying along the x axis from the origin to x=3 
  786. with a radius of 2.
  787.  
  788. Normally the ends of a cylinder are closed by flat planes which are 
  789. parallel to each other and perpendicular to the length of the cylinder.  
  790. Adding the optional keyword "open" after the radius will remove the end 
  791. caps and results in a hollow tube.
  792.  
  793. Because they are finite they respond to automatic bounding. As with all 
  794. shapes, they can be translated, rotated and scaled.
  795.  
  796.  
  797. 5.2.1.4     Cones
  798.  
  799. A finite length cone or a frustum (a cone with the point cut off) may be 
  800. defined by.
  801.  
  802.    cone { <END1>, RADIUS1, <END2>, RADIUS2 }
  803.  
  804. Where <END1> and <END2> are vectors defining the x,y,z coordinates of the 
  805. center of each end of the cone and RADIUS1 and RADIUS2 are float values for 
  806. the radius of those ends.  For example:
  807.  
  808.    cone { <0,0,0>,2 <0,3,0>, 0}
  809.  
  810. is a cone 3 units tall pointing up the y axis from the origin to y=3.  The 
  811. base has a radius of 2.  The other end has a radius of 0 which means it 
  812. comes to a sharp point.  If neither radius is zero then the results look 
  813. like a tapered cylinder or a cone with the point cut off.
  814.  
  815. Like a cylinder, normally the ends of a cone are closed by flat planes 
  816. which are parallel to each other and perpendicular to the length of the 
  817. cone.  Adding the optional keyword "open" after RADIUS2 will remove the end 
  818. caps and results in a tapered hollow tube like a megaphone or funnel.
  819.  
  820. Because they are finite they respond to automatic bounding. As with all 
  821. shapes, they can be translated, rotated and scaled.
  822.  
  823.  
  824. 5.2.1.5     Torus
  825.  
  826. A torus is a 4th order quartic polynomial shape that looks like a donut or 
  827. inner tube.  Because this shape is so useful and quartics are difficult to 
  828. define, POV-Ray lets you take a short-cut and define a torus by:
  829.  
  830.    torus { MAJOR, MINOR }
  831.  
  832. where MAJOR is a float value giving the major radius and MINOR is a float 
  833. specifying the minor radius.  The major radius extends from the center of 
  834. the hole to the mid-line of the rim while the minor radius is the radius of 
  835. the cross-section of the rim.  The torus is centered at the origin and lies 
  836. in the X-Z plane with the Y-axis sticking through the hole.
  837.  
  838.         ----------- - - - - - - - ----------              +Y       
  839.        /          \              /          \              |       
  840.       /            \            /            \             |       
  841.      |              |          |       |<-B-->|       -X---|---+X  
  842.       \            /            \            /             |       
  843.        \__________/_ _ _ _ _ _ _ \__________/              |       
  844.                          |<-----A----->|                  -Y       
  845.  
  846.       A = Major Radius
  847.       B = Minor Radius
  848.  
  849. Internally the torus is computed the same as any other quartic or 4th order 
  850. polynomial however a torus defined this way will respond to automatic 
  851. bounding while a quartic must be manually bound if at all.  As with all 
  852. shapes, a torus can be translated, rotated and scaled.  Calculations for 
  853. all higher order polynomials must be very accurate.  If this shape renders 
  854. improperly you may add the keyword "sturm" after the MINOR value to use 
  855. POV-Ray's slower-yet-more-accurate Sturmian root solver.
  856.  
  857.  
  858. 5.2.1.6     Blob
  859.  
  860. Blobs are an interesting shape type. Their components are "flexible" 
  861. spheres that attract or repel each other creating a "blobby" organic 
  862. looking shape. The spheres' surfaces actually stretch out smoothly and 
  863. connect, as if coated in silly putty (honey? glop?) and pulled apart.
  864.  
  865. Picture each blob component as a point floating in space.  Each point has a 
  866. field around it that starts very strong at the center point and drops off 
  867. to zero at some radius. POV-Ray adds together the field strength of each 
  868. component and looks for the places that the strength of the field is 
  869. exactly the same as the "threshold" value that was specified.  Points with 
  870. a total field strength greater than the threshold are considered inside the 
  871. blob.  Those less than the threshold are outside.  Points equal to the 
  872. threshold are on the surface of the blob.
  873.  
  874. A blob is defined as follows:
  875.  
  876.   blob {
  877.      threshold THRESHOLD_VALUE
  878.      component STRENGTH, RADIUS, <CENTER>
  879.      component STRENGTH, RADIUS, <CENTER>  // Repeat for any number  
  880.      component STRENGTH, RADIUS, <CENTER>  //  of components         
  881.   }
  882.  
  883. The keyword "threshold" is followed by a float THRESHOLD_VALUE.  Each 
  884. component begins with the keyword "component".  STRENGTH is a float value 
  885. specifying the field strength at its center.  The strength may be positive 
  886. or negative. A positive value will make that component attract other 
  887. components. Negative strength will make that component repel other 
  888. components. Components in different, separate blob shapes do not affect 
  889. each other.  The strength tapers off to zero at the value specified by the 
  890. float RADIUS.  The vector <CENTER> specifies the x,y,z coordinates of the 
  891. component. For example:
  892.  
  893.   blob {
  894.     threshold 0.6
  895.     component 1.0, 1.0, <.75, 0, 0>
  896.     component 1.0, 1.0, <-.375, .64952, 0>
  897.     component 1.0, 1.0, <-.375, -.64952, 0>
  898.     scale 2 
  899.   }
  900.  
  901. If you have a single blob component then the surface you see will look just 
  902. like a sphere, with the radius of the surface being somewhere inside the 
  903. "radius" value you specified for the component. The exact radius of this 
  904. sphere-like surface can be determined from the blob equation listed below 
  905. (you will probably never need to know this, blobs are more for visual 
  906. appeal than for exact modeling).
  907.  
  908. If you have a number of blob components, then their fields add together at 
  909. every point in space - this means that if the blob components are close 
  910. together the resulting surface will smoothly flow around the components.
  911.  
  912. The various numbers that you specify in the blob declaration interact in 
  913. several ways.  The meaning of each can be roughly stated as:
  914.  
  915. THRESHOLD:
  916.      This is the total density value that POV-Ray is looking for. By 
  917. following the ray out into space and looking at how each blob component 
  918. affects the ray, POV-Ray will find the points in space where the density is 
  919. equal to the "threshold" value.
  920.  
  921.      1) "threshold" must be greater than 0. POV-Ray only looks for positive 
  922. densities.
  923.      2) If "threshold" is greater than the strength of a component, then 
  924. the component will disappear.
  925.      3) As "threshold" gets larger the surface you see gets closer to the 
  926. centers of the components.
  927.      4) As "threshold" gets smaller, the surface you see gets closer to the 
  928. spheres at a distance of "radius" from the centers of the components.
  929.  
  930. STRENGTH:
  931.      Each component has a strength value - this defines the density of the 
  932. component at the center of the component. Changing this value will usually 
  933. have only a subtle effect.
  934.  
  935.      1) "strength" may be positive or negative. Zero is a bad value, as the 
  936. net result is that no density was added - you might just as well have not 
  937. used this component.
  938.      2) If "strength" is positive, then POV-Ray will add its density to the 
  939. space around the center of the component. If this adds enough density to be 
  940. greater than "threshold you will see a surface.
  941.      3) If "strength" is negative, then POV-Ray will subtract its density 
  942. from the space around the center of the component. This will only do 
  943. something if there happen to be positive components nearby. What happens is 
  944. that the surface around any nearby positive components will be dented away 
  945. from the center of the negative component.
  946.  
  947. RADIUS: 
  948.      Each component has a radius of influence. The component can only 
  949. affect space within "radius" of its center. This means that if all of the 
  950. components are farther than "radius" from each other, you will only see a 
  951. bunch of spheres.  If a component is within the radius of another 
  952. component, then the two components start to affect each other. At first 
  953. there is only a small bulge outwards on each of the two components, as they 
  954. get closer they bulge more and more until they attach along a smooth neck.  
  955. If the components are very close (i.e. their centers are on top of each 
  956. other), then you will only see a sphere (this is just like having a 
  957. component of more strength. bigger than the size of each of the component 
  958. radii)
  959.      1) "radius" must be bigger than 0.
  960.      2) As "radius" increases the apparent size of the component will 
  961. increase.
  962.  
  963. CENTER:
  964.      This is simply a point in space.  It defines the center of a blob 
  965. component.  By changing the x/y/z values of the center you move the 
  966. component around.
  967.  
  968. THE FORMULA
  969.      For the more mathematically minded, here's the formula used internally 
  970. by POV-Ray to create blobs. You don't need to understand this to use blobs. 
  971.  
  972. The formula used for a single blob component is:
  973.  
  974.       density = strength * (1 - radius^2)^2
  975.  
  976. This formula has the nice property that it is exactly equal to strength" at 
  977. the center of the component and drops off to exactly 0 at a distance of 
  978. "radius" from the center of the component. The density formula for more 
  979. than one blob component is just the sum of the individual component 
  980. densities:
  981.  
  982.       density = density1 + density2 + ...
  983.  
  984. Blobs can be used in CSG shapes and they can be scaled, rotated and 
  985. translated. Because they are finite they respond to automatic bounding.  
  986. The calculations for blobs must be very accurate.  If this shape renders 
  987. improperly you may add the keyword "sturm" after the last component to use 
  988. POV-Ray's slower-yet-more-accurate Sturmian root solver.
  989.  
  990.  
  991. 5.2.1.7     Height Fields
  992.  
  993. Height fields are fast, efficient objects that are generally used to create 
  994. mountains or other raised surfaces out of hundreds of triangles in a mesh.  
  995.  
  996. A height field is essentially a 1 unit wide by 1 unit long box with a 
  997. mountainous surface on top.  The height of the mountain at each point is 
  998. taken from the color number (palette index) of the pixels in a graphic 
  999. image file. 
  1000.  
  1001.  
  1002.                     ________  <---- image index 255
  1003.                   /        /|
  1004.             +1y  ---------- |
  1005.                  |        | |
  1006.                  |        | |+1z <- Image upper-right
  1007.                  |        | /
  1008.             0,0,0---------- +1x
  1009.                  ^
  1010.                  |____ Image lower-left
  1011.  
  1012.  
  1013.     NOTE: Image resolution is irrelevant to the scale of the heightfield.
  1014.  
  1015. The mesh of triangles corresponds directly to the pixels in the image file. 
  1016. In fact, there are two small triangles for every pixel in the image file. 
  1017. The Y (height) component of the triangles is determined by the palette 
  1018. index number stored at each location in the image file. The higher the 
  1019. number, the higher the triangle. The maximum height of an un-scaled height 
  1020. field is 1 unit.
  1021.  
  1022. The higher the resolution of the image file used to create the height 
  1023. field, the smoother the height field will look. A 640 X 480 GIF will create 
  1024. a smoother height field than a 320 x 200 GIF.  The size/resolution of the 
  1025. image does not affect the size of the height field. The un-scaled height 
  1026. field size will always be 1x1. Higher resolution image files will create 
  1027. smaller triangles, not larger height fields.
  1028.  
  1029. There are three types files which can define a height field as follows:
  1030.  
  1031.    height_field { gif "filename.gif" }
  1032.    height_field { tga "filename.tga" }
  1033.    height_field { pot "filename.pot" }
  1034.  
  1035. The image file used to create a height field can be a GIF, TGA or POT 
  1036. format file. The GIF format is the only one that can be created using a 
  1037. standard paint program.
  1038.  
  1039. In a GIF file, the color number is the palette index at a given point. Use 
  1040. a paint program to look at the palette of a GIF image. The first color is 
  1041. palette index zero, the second is index 1, the third is index 2, and so on. 
  1042. The last palette entry is index 255. Portions of the image that use low 
  1043. palette entries will be lower on the height field.  Portions of the image 
  1044. that use higher palette entries will be higher on the height field. For 
  1045. example, an image that was completely made up of entry 0 would be a flat 
  1046. 1x1 square. An image that was completely made up of entry 255 would be a 
  1047. 1x1x1 cube.
  1048.  
  1049. The maximum number of colors in a GIF are 256, so a GIF height field can 
  1050. have any number of triangles, but they will only 256 different height 
  1051. values. 
  1052.  
  1053. The color of the palette entry does not affect the height of the pixel. 
  1054. Color entry 0 could be red, blue, black, or orange, but the height of any 
  1055. pixel that uses color entry 0 will always be 0. Color entry 255 could be 
  1056. indigo, hot pink, white, or sky blue, but the height of any pixel that uses 
  1057. color entry 255 will always be 1.
  1058.  
  1059. You can create height field GIF images with a paint program or a fractal 
  1060. program like "Fractint".  If you have access to an IBM-PC, you can get 
  1061. Fractint from most of the same sources as POV-Ray.
  1062.  
  1063. A POT file is essentially a GIF file with a 16 bit palette. The maximum 
  1064. number of colors in a POT file is greater than 32,000. This means a POT 
  1065. height field can have over 32,000 possible height values. This makes it 
  1066. possible to have much smoother height fields. Note that the maximum height 
  1067. of the field is still 1 even though more intermediate values are possible.
  1068.  
  1069. At the time of this writing, the only program that created POT files was a 
  1070. freeware IBM-PC program called Fractint. POT files generated with this 
  1071. fractal program create fantastic landscapes. If you have access to an IBM-
  1072. PC, you can get Fractint from most of the same sources as POV-Ray.
  1073.  
  1074. The TGA file format may be used as a storage device for 16 bit numbers 
  1075. rather than an image file. The TGA format uses the red and green bytes of 
  1076. each pixel to store the high and low bytes of a height value. TGA files are 
  1077. as smooth as POT files, but they must be generated with special custom-made 
  1078. programs. Currently, this format is of most use to programmers, though you 
  1079. may see TGA height field generator programs arriving soon.  There is 
  1080. example C source code included with the POV-Ray source archive to create a 
  1081. TGA file for use with a height field.  
  1082.  
  1083. It is nearly impossible to take advantage of the 16 bits of resolution 
  1084. offered by the use of tga files in height fields when the tga file is 
  1085. created in a paint program.  A gif file is a better choice for paint 
  1086. created height fields in 8 bits.  Also see Appendix B.5 for a tip on 
  1087. creating tga files for height fields.
  1088.  
  1089. An optional "water_level" parameter may be added after the file name.  It 
  1090. consists of the keyword "water_level" followed by a float value tells the 
  1091. program not to look for the height field below that value. Default value is 
  1092. 0, and legal values are between 0 and 1. For example, "water_level .5" 
  1093. tells POV-Ray to only render the top half of the height field. The other 
  1094. half is "below the water" and couldn't be seen anyway. This term comes from 
  1095. the popular use of height fields to render landscapes. A height field would 
  1096. be used to create islands and another shape would be used to simulate water 
  1097. around the islands. A large portion of the height field would be obscured 
  1098. by the "water" so the "water_level" parameter was introduced to allow the 
  1099. ray-tracer to ignore the unseen parts of the height field. Water_level is 
  1100. also used to "cut away" unwanted lower values in a height field. For 
  1101. example, if you have an image of a fractal on a solid colored background, 
  1102. where the background color is palette entry 0, you can remove the 
  1103. background in the height field by specifying, "water_level .001" 
  1104.  
  1105. Normally height fields have a rough, jagged look because they are made of 
  1106. lots of flat triangles.  Adding the keyword "smooth" causes POV-Ray to 
  1107. modify the surface normal vectors of the triangles in such a way that the 
  1108. lighting and shading of the triangles will give a smooth look.  This may 
  1109. allow you to use a lower resolution file for your height field than would 
  1110. otherwise be needed.
  1111.  
  1112. Height fields can be used in CSG shapes and they can be scaled, rotated and 
  1113. translated. Because they are finite they respond to automatic bounding.  
  1114.  
  1115. Here are a notes and helpful hints on height fields from their creator, 
  1116. Doug Muir:
  1117.  
  1118. The height field is mapped to the x-z plane, with its lower left corner 
  1119. sitting at the origin. It extends to 1 in the positive x direction and to 1 
  1120. in the positive z direction. It is maximum 1 unit high in the y direction. 
  1121. You can translate it, scale it, and rotate it to your heart's content. 
  1122.  
  1123. When deciding on what water_level to use, remember, this applies to the un-
  1124. transformed height field. If you are a Fractint user, the water_level 
  1125. should be used just like the water_level parameter for 3d projections in 
  1126. Fractint.
  1127.  
  1128. Here's a detailed explanation of how the ray-tracer creates the height 
  1129. field. You can skip this if you aren't interested in the technical side of 
  1130. ray-tracing. This information is not needed to create or use height fields.
  1131.  
  1132. To find an intersection with the height field, the ray tracer first checks 
  1133. to see if the ray intersects the box which surrounds the height field. 
  1134. Before any transformations, this box's two opposite vertexes are at (0, 
  1135. water_level, 0) and (1, 1, 1). If the box is intersected, the ray tracer 
  1136. figures out where, and then follows the line from where the ray enters the 
  1137. box to where it leaves the box, checking each pixel it crosses for an 
  1138. intersection. 
  1139.  
  1140. It checks the pixel by dividing it up into two triangles. The height vertex 
  1141. of the triangle is determined by the color index at the corresponding 
  1142. position in the GIF, POT, or TGA file.
  1143.  
  1144. If your file has a uses the color map randomly, your height field is going 
  1145. to look pretty chaotic, with tall, thin spikes shooting up all over the 
  1146. place. Not every GIF will make a good height field.
  1147.  
  1148. If you want to get an idea of what your height field will look like, I 
  1149. recommend using the IBM-PC program Fractint's 3d projection features to do 
  1150. a sort of preview. If it doesn't look good there, the ray tracer isn't 
  1151. going to fix it. For those of you who can't use Fractint, convert the image 
  1152. palette to a gray scale from black at entry 0 to white at entry 255 with 
  1153. smooth steps of gray in-between. The dark parts will lower than the 
  1154. brighter parts, so you can get a feel for how the image will look as a 
  1155. height field.
  1156.  
  1157.  
  1158. 5.2.2 FINITE PATCH PRIMITIVES
  1159.  
  1160. There are 4 totally thin, finite objects which have NO well-defined inside.  
  1161. They may be combined in CSG union but cannot be use in other types of CSG.  
  1162. They are bicubic_patch, disc, smooth_triangle and triangle.  Because these 
  1163. types are finite, POV-Ray can use automatic bounding on them to speed up 
  1164. rendering time.  
  1165.  
  1166.  
  1167. 5.2.2.1     Triangle and Smooth_triangle 
  1168.  
  1169. The triangle primitive is available in order to make more complex objects 
  1170. than the built-in shapes will permit.  Triangles are usually not created by 
  1171. hand, but are converted from other files or generated by utilities. 
  1172.  
  1173. A triangle is defined by:
  1174.  
  1175.    triangle { <CORNER1>, <CORNER2>, <CORNER3> }
  1176.  
  1177. where <CORNERn> is a vector defining the x,y,z coordinates of each corner 
  1178. of the triangle.
  1179.  
  1180. Because triangles are perfectly flat surfaces it would require extremely 
  1181. large numbers of very small triangles to approximate a smooth, curved 
  1182. surface.  However much of our perception of smooth surfaces is dependent 
  1183. upon the way light and shading is done.  By artificially modifying the 
  1184. surface normals we can simulate as smooth surface and hide the sharp-edged 
  1185. seams between individual triangles. 
  1186.  
  1187. The smooth_triangle primitive is used for just such purposes.  The 
  1188. smooth_triangles use a formula called Phong normal interpolation to 
  1189. calculate the surface normal for any point on the triangle based on normal 
  1190. vectors which you define for the three corners.  This makes the triangle 
  1191. appear to be a smooth curved surface. A smooth_triangle is defined by:
  1192.  
  1193.   smooth_triangle {
  1194.     <CORNER1>, <NORMAL1>,
  1195.     <CORNER2>, <NORMAL2>,
  1196.     <CORNER3>, <NORMAL3>
  1197.   }
  1198.  
  1199. where the corners are defined as in regular triangles and <NORMALn> is a 
  1200. vector describing the direction of the surface normal at each corner.
  1201.  
  1202. These normal vectors are prohibitively difficult to compute by hand.  
  1203. Therefore smooth_triangles are almost always generated by utility programs.  
  1204. To achieve smooth results, any triangles which share a common vertex should 
  1205. have the same normal vector at that vertex.  Generally the smoothed normal 
  1206. should be the average of all the actual normals of the triangles which 
  1207. share that point.
  1208.  
  1209.  
  1210. 5.2.2.2     Bicubic_patch
  1211.  
  1212. A bicubic patch is a 3D curved surface created from a mesh of triangles. 
  1213. POV-Ray supports a type of bicubic patch called a Bezier patch.  A bicubic 
  1214. patch is defined as follows:
  1215.  
  1216.   bicubic_patch { 
  1217.      type PATCH_TYPE
  1218.      flatness FLATNESS_VALUE
  1219.      u_steps NUM_U_STEPS
  1220.      v_steps NUM_V_STEPS
  1221.      <CP1>,  <CP2>,   <CP3>,   <CP4>,
  1222.      <CP5>,  <CP6>,   <CP7>,   <CP8>,
  1223.      <CP9>,  <CP10>,  <CP11>,  <CP12>,
  1224.      <CP13>, <CP14>,  <CP15>,  <CP16>
  1225.   }
  1226.  
  1227. The keyword "type" is followed by a float PATCH_TYPE which currently must 
  1228. be either 0 or 1.  For type 0 only the control points are retained within 
  1229. POV-Ray. This means that a minimal amount of memory is needed, but POV-Ray 
  1230. will need to perform many extra calculations when trying to render the 
  1231. patch.  Type 1 preprocesses the patch into many subpatches.  This results 
  1232. in a significant speedup in rendering, at the cost of memory.
  1233.  
  1234. These 4 parameters: type, flatness, u_steps & v_steps, may appear in any 
  1235. order.  They are followed by 16 vectors that define the x,y,z coordinates 
  1236. of the 16 control points which define the patch.  The patch touches the 4 
  1237. corner points <CP1>, <CP4>, <CP13> and <CP16> while the other 12 points 
  1238. pull and stretch the patch into shape.
  1239.  
  1240. The keywords "u_steps" and "v_steps" are each followed by float values 
  1241. which tell how many rows and columns of triangles are the minimum to use to 
  1242. create the surface.  The maximum number of individual pieces of the patch 
  1243. that are tested by POV-Ray can be calculated from the following:
  1244.  
  1245.    sub-pieces = 2^u_steps * 2^v_steps
  1246.  
  1247. This means that you really should keep "u_steps" and "v_steps" under 4 or 
  1248. 5.  Most patches look just fine with "u_steps 3" and "v_steps 3", which 
  1249. translates to 64 subpatches (128 smooth triangles).
  1250.  
  1251. As POV-Ray processes the Bezier patch, it makes a test of the current piece 
  1252. of the patch to see if it is flat enough to just pretend it is a rectangle.  
  1253. The statement that controls this test is: "flatness xxx".  Typical flatness 
  1254. values range from 0 to 1 (the lower the slower).
  1255.  
  1256. If the value for flatness is 0, then POV-Ray will always subdivide the 
  1257. patch to the extend specified by u_steps and v_steps.  If flatness is 
  1258. greater than 0, then every time the patch is split, POV-Ray will check to 
  1259. see if there is any need to split further.
  1260.  
  1261. There are both advantages and disadvantages to using a non-zero flatness.  
  1262. The advantages include:
  1263.  
  1264.    If the patch isn't very curved, then this will be detected and POV-Ray
  1265.    won't waste a lot of time looking at the wrong pieces.
  1266.  
  1267.    If the patch is only highly curved in a couple of places, POV-Ray will
  1268.    keep subdividing there and concentrate it's efforts on the hard part.
  1269.  
  1270. The biggest disadvantage is that if POV-Ray stops subdividing at a 
  1271. particular level on one part of the patch and at a different level on an 
  1272. adjacent part of the patch, there is the potential for "cracking".  This is 
  1273. typically visible as spots within the patch where you can see through.  How 
  1274. bad this appears depends very highly on the angle at which you are viewing 
  1275. the patch.
  1276.  
  1277. Like triangles, the bicubic patch is not meant to be generated by hand.  
  1278. These shapes should be created by a special utility. You may be able to 
  1279. acquire utilities to generate these shapes from the same source from which 
  1280. you obtained POV-Ray. 
  1281.  
  1282. Example:
  1283.   bicubic_patch { 
  1284.      type 1 
  1285.      flatness 0.01
  1286.      u_steps 4
  1287.      v_steps 4
  1288.      <0, 0, 2>, <1, 0, 0>, <2, 0, 0>, <3, 0,-2>,
  1289.      <0, 1  0>, <1, 1, 0>, <2, 1, 0>, <3, 1, 0>,
  1290.      <0, 2, 0>, <1, 2, 0>, <2, 2, 0>, <3, 2, 0>,
  1291.      <0, 3, 2>, <1, 3, 0>, <2, 3, 0>, <3, 3, -2>
  1292.   }
  1293.  
  1294. The triangles in a POV-Ray bicubic_patch are automatically smoothed using 
  1295. normal interpolation but it is up to the user (or the user's utility 
  1296. program) to create control points which smoothly stitch together groups of 
  1297. patches.  
  1298.  
  1299. As with the other shapes, bicubic_patch objects can be translated, rotated, 
  1300. and scaled.  Because they are finite they respond to automatic bounding.  
  1301. Since it's made from triangles, a bicubic_patch cannot be used in CSG 
  1302. intersection or difference types or inside a clipped_by modifier because 
  1303. triangles have no clear "inside". The CSG union type works acceptably.
  1304.  
  1305.  
  1306. 5.2.2.3     Disc
  1307.  
  1308. One other flat, finite object type is available with POV-Ray.  Note that a 
  1309. disc is infinitely thin.  It has no thickness.  If you want a disc with 
  1310. true thickness you should use a very short cylinder.  A disc shape may be 
  1311. defined by:
  1312.  
  1313.   disc { <CENTER>, <NORMAL>, RADIUS }
  1314.  
  1315. or 
  1316.  
  1317.   disc { <CENTER>, <NORMAL>, RADIUS, HOLE_RADIUS }
  1318.  
  1319. The vector <CENTER> defines the x,y,z coordinates of the center of the 
  1320. disc.  The <NORMAL> vector describes its orientation by describing its 
  1321. surface normal vector.  This is followed by a float specifying the RADIUS.  
  1322. This may be optionally followed by another float specifying the radius of a 
  1323. hole to be cut from the center of the disc.
  1324.  
  1325. Example:
  1326.   disc {
  1327.     <-2,-0.5, 0>,    //center location
  1328.     <0,  1,   0>,    //normal vector
  1329.     2                //radius         
  1330.     pigment { color Cyan }
  1331.   }
  1332.  
  1333.   disc {
  1334.     <0, 1, 0>,       //center location
  1335.     <-1, 3, -2>,     //normal vector  
  1336.     1.5,             //radius         
  1337.     0.5              //hole radius (optional)
  1338.     pigment { color Yellow }
  1339.   }
  1340.  
  1341. As with the other shapes, discs can be translated, rotated, and scaled.  
  1342. Because they are finite they respond to automatic bounding.  Disc cannot be 
  1343. used in CSG intersection or difference types or inside a clipped_by 
  1344. modifier because it has no clear "inside". The CSG union type works 
  1345. acceptably.
  1346.  
  1347.  
  1348. 5.2.3 INFINITE SOLID PRIMITIVES
  1349.  
  1350. There are 5 polynomial primitive shapes that are possibly infinite and do 
  1351. not respond to automatic bounding.  They do have a well defined inside and 
  1352. may be used in CSG.  They are plane, cubic, poly, quadric, and quartic.  
  1353.  
  1354.  
  1355. 5.2.3.1     Plane 
  1356.  
  1357. The plane primitive is a fast, efficient way to define an infinite flat 
  1358. surface.  The plane is specified as follows:
  1359.  
  1360.   plane { <NORMAL>, DISTANCE }
  1361.  
  1362. The <NORMAL> vector defines the surface normal of the plane.  A surface 
  1363. normal is a vector which points up from the surface at a 90 degree angle.  
  1364. This is followed by a float value that gives the distance along the normal 
  1365. that the plane is from the origin.  For example:
  1366.  
  1367.   plane { <0,1,0>,4 }
  1368.  
  1369. This is a plane where "straight up" is defined in the positive y direction.  
  1370. The plane is 4 units in that direction away from the origin.  Because most 
  1371. planes are defined with surface normals in the direction of an axis, you 
  1372. will often see planes defined using the "x", "y", or "z" built-in vector 
  1373. identifiers.  The example above could be specified as:
  1374.  
  1375.   plane { y,4 }
  1376.  
  1377. The plane extends infinitely in the x and z directions.  It effectively 
  1378. divides the world into two pieces.  By definition the normal vector points 
  1379. to the outside of the plane while any points away from the vector are 
  1380. defined as inside.  This inside/outside distinction is only important when 
  1381. using planes in CSG.
  1382.  
  1383. As with the other shapes, planes can be translated, rotated, and scaled.  
  1384. Because they are infinite they do not respond to automatic bounding.  Plane 
  1385. can be used freely in CSG because it has a clear defined "inside". 
  1386.  
  1387. A plane is called a "polynomial" shape because it is defined by a first 
  1388. order polynomial equation.  Given a plane:
  1389.  
  1390.   plane { <A, B, C>, D }
  1391.  
  1392. it can be represented by the formula:
  1393.  
  1394.    A*x + B*y + C*z = D
  1395.  
  1396. Therefore our example "plane {y,4}" is actually the polynomial equation 
  1397. "y=4".  You can think of this as a set of all x,y,z points where all have y 
  1398. values equal to 4, regardless of the x or z values.
  1399.  
  1400. This equation is a "first order" polynomial because each term contains only 
  1401. single powers of x, y or z.  A second order equation has terms like x^2, 
  1402. y^2, z^2, xy, xz and yz.  Another name for a 2nd order equation is a 
  1403. quadric equation.  Third order polys are called cubics.  A 4th order 
  1404. equation is a quartic.  Such shapes are described in the sections below.
  1405.  
  1406.  
  1407. 5.2.3.2     Quadric 
  1408.  
  1409. Quadric surfaces can produce shapes like ellipsoids, spheres, cones, 
  1410. cylinders, paraboloids (dish shapes), and hyperboloids (saddle or hourglass 
  1411. shapes).  NOTE: Do not confuse "quaDRic" with "quaRTic".  A quadric is a 
  1412. 2nd order polynomial while a quartic is 4th order.
  1413.  
  1414. A quadric is defined in POV-Ray by:
  1415.  
  1416.   quadric { <A,B,C>, <D,E,F>, <G,H,I>, J }
  1417.  
  1418. where A through J are float expressions.  
  1419.  
  1420. This defines a surface of x,y,z points which satisfy the equation:
  1421.  
  1422.        A x^2   + B y^2   + C z^2
  1423.      + D xy    + E xz    + F yz
  1424.      + G x     + H y     + I z    + J = 0
  1425.  
  1426. Different values of A,B,C,...J will give different shapes. So, if you take 
  1427. any three dimensional point and use its x, y, and z coordinates in the 
  1428. above equation, the answer will be 0 if the point is on the surface of the 
  1429. object. The answer will be negative if the point is inside the object and 
  1430. positive if the point is outside the object. Here are some examples: 
  1431.  
  1432.      X^2 + Y^2 + Z^2 - 1 = 0  Sphere
  1433.      X^2 + Y^2 - 1 = 0        Infinitely long cylinder along the Z axis 
  1434.      X^2 + Y^2 - Z^2 = 0      Infinitely long cone along the Z axis
  1435.  
  1436. The easiest way to use these shapes is to include the standard file 
  1437. "SHAPES.INC" into your program. It contains several pre-defined quadrics 
  1438. and you can transform these pre-defined shapes (using translate, rotate, 
  1439. and scale) into the ones you want.
  1440.  
  1441. You can invoke them by using the syntax,
  1442.  
  1443.   object { Quadric_Name }
  1444.  
  1445. The pre-defined quadrics are centered about the origin <0, 0, 0> and have a 
  1446. radius of 1. Don't confuse radius with width. The radius is half the 
  1447. diameter or width making the standard quadrics 2 units wide.
  1448.  
  1449. Some of the pre-defined quadrics are,
  1450.  
  1451.  Ellipsoid
  1452.  Cylinder_X, Cylinder_Y, Cylinder_Z
  1453.  QCone_X, QCone_Y, QCone_Z
  1454.  Paraboloid_X, Paraboloid_Y, Paraboloid_Z
  1455.  
  1456. For a complete list, see the file SHAPES.INC.
  1457.  
  1458.  
  1459. 5.2.3.3     Poly, Cubic and Quartic.  
  1460.  
  1461. Higher order polynomial surfaces may be defined by the use of a poly shape.  
  1462. The syntax is:
  1463.  
  1464.   poly { ORDER, <T1, T2, T3, .... Tm> }
  1465.  
  1466. Where ORDER is a whole number from 2 to 7 inclusively that specifies the 
  1467. order of the equation.  T1, T2... Tm are float values for the coefficients 
  1468. of the equation.  There are "m" such terms where 
  1469.  
  1470.     m=((ORDER+1)*(ORDER+2)*(ORDER+3))/6
  1471.  
  1472. An alternate way to specify 3rd order polys is:
  1473.  
  1474.   cubic { <T1, T2,... T20> }
  1475.  
  1476. Also 4th order equations may be specified with:
  1477.  
  1478.   quartic { <T1, T2,... T35> }
  1479.  
  1480. Here's a more mathematical description of quartics for those who are 
  1481. interested.  Quartic surfaces are 4th order surfaces, and can be used to 
  1482. describe a large class of shapes including the torus, the lemniscate, etc. 
  1483. The general equation for a quartic equation in three variables is (hold 
  1484. onto your hat):
  1485.  
  1486.   a00 x^4 + a01 x^3 y + a02 x^3 z+ a03 x^3 + a04 x^2 y^2+ 
  1487.   a05 x^2 y z+ a06 x^2 y + a07 x^2 z^2+a08 x^2 z+a09 x^2+
  1488.   a10 x y^3+a11 x y^2 z+ a12 x y^2+a13 x y z^2+a14 x y z+ 
  1489.   a15 x y + a16 x z^3 + a17 x z^2 + a18 x z + a19 x+
  1490.   a20 y^4 + a21 y^3 z + a22 y^3+ a23 y^2 z^2 +a24 y^2 z+ 
  1491.   a25 y^2 + a26 y z^3 + a27 y z^2 + a28 y z + a29 y+ 
  1492.   a30 z^4 + a31 z^3 + a32 z^2 + a33 z + a34
  1493.  
  1494. To declare a quartic surface requires that each of the coefficients (a0 -> 
  1495. a34) be placed in order into a single long vector of 35 terms. 
  1496.  
  1497. As an example let's define a torus the hard way.  A Torus can be 
  1498. represented by the equation:
  1499.  
  1500.  x^4 + y^4 + z^4 + 2 x^2 y^2 + 2 x^2 z^2 + 2 y^2 z^2
  1501.  -2 (r0^2 + r1^2) x^2 + 2 (r0^2 - r1^2) y^2 
  1502.  -2 (r0^2 + r1^2) z^2 + (r0^2 - r1^2)^2 = 0
  1503.  
  1504. Where r0 is the "major" radius of the torus - the distance from the hole of 
  1505. the donut to the middle of the ring of the donut, and r1 is the "minor" 
  1506. radius of the torus - the distance from the middle of the ring of the donut 
  1507. to the outer surface. The following object declaration is for a torus 
  1508. having major radius 6.3 minor radius 3.5 (Making the maximum width just 
  1509. under 10). 
  1510.  
  1511. //Torus having major radius sqrt(40), minor radius sqrt(12)
  1512.  
  1513.    quartic {
  1514.       < 1,   0,   0,   0,   2,   0,   0,   2,   0, 
  1515.      -104,   0,   0,   0,   0,   0,   0,   0,   0, 
  1516.         0,   0,   1,   0,   0,   2,   0,  56,   0, 
  1517.         0,   0,   0,   1,   0, -104,  0, 784 >
  1518.       sturm
  1519.       bounded_by { // bounded_by speeds up the render,
  1520.                    // see bounded_by
  1521.                    // explanation later 
  1522.                    // in docs for more info.
  1523.        sphere { <0, 0, 0>, 10 }
  1524.       }
  1525.    }
  1526.  
  1527. Poly, cubic and quartics are just like quadrics in that you don't have to 
  1528. understand what one is to use one. The file SHAPESQ.INC has plenty of pre-
  1529. defined quartics for you to play with. The most common one is the torus or 
  1530. donut. The syntax for using a pre-defined quartic is:
  1531.  
  1532.     object { Quartic_Name }
  1533.  
  1534. As with the other shapes, these shapes can be translated, rotated, and 
  1535. scaled.  Because they are infinite they do not respond to automatic 
  1536. bounding.  They can be used freely in CSG because they have a clear defined 
  1537. "inside". 
  1538.  
  1539. Polys use highly complex computations and will not always render perfectly. 
  1540. If the surface is not smooth, has dropouts, or extra random pixels, try 
  1541. using the optional keyword "sturm" in the definition. This will cause a 
  1542. slower, but more accurate calculation method to be used. Usually, but not 
  1543. always, this will solve the problem. If sturm doesn't work, try rotating, 
  1544. or translating the shape by some small amount. See the sub-directory MATH 
  1545. for examples of polys in scenes.
  1546.  
  1547. There are really so many different quartic shapes, we can't even begin to 
  1548. list or describe them all. If you are interested and mathematically 
  1549. inclined, an excellent reference book for curves and surfaces where you'll 
  1550. find more quartic shape formulas is:
  1551.  
  1552.    "The CRC Handbook of Mathematical Curves and Surfaces"
  1553.    David von Seggern
  1554.    CRC Press
  1555.    1990
  1556.  
  1557.  
  1558. 5.2.4 CONSTRUCTIVE SOLID GEOMETRY (CSG)
  1559.  
  1560. POV-Ray supports Constructive Solid Geometry (also called Boolean 
  1561. operations) in order to make the shape definition abilities more powerful.
  1562.  
  1563.  
  1564. 5.2.4.1     About CSG
  1565.        
  1566. The simple shapes used so far are nice, but not terribly useful on their 
  1567. own for making realistic scenes. It's hard to make interesting objects when 
  1568. you're limited to spheres, boxes, cylinders, planes, and so forth. 
  1569.        
  1570. Constructive Solid Geometry (CSG) is a technique for taking these simple 
  1571. building blocks and combining them together. You can use a cylinder to bore 
  1572. a hole through a sphere. You can start with solid blocks and carve away 
  1573. pieces.  Objects may be combined in groups and treated as though they were 
  1574. single objects.
  1575.        
  1576. Constructive Solid Geometry allows you to define shapes which are the 
  1577. union, intersection, or difference of other shapes.  Additionally you may 
  1578. clip sections of objects revealing their hollow interiors.
  1579.        
  1580. Unions superimpose two or more shapes. This has the same effect as defining 
  1581. two or more separate objects, but is simpler to create and/or manipulate. 
  1582. In POV-Ray 2.0 the union keyword may be used anyplace composite was used in 
  1583. previous versions of POV-Ray.  Also a new type of union called "merge" can 
  1584. eliminate internal surfaces on transparent or clipped objects.
  1585.        
  1586. Intersections define the space where the two or more surfaces overlap.
  1587.        
  1588. Differences allow you to cut one object out of another.
  1589.        
  1590. CSG intersections, unions, and differences can consist of two or more 
  1591. shapes. For example:
  1592.        
  1593.           union {
  1594.             object{O1}
  1595.             object{O2}
  1596.             object{O3}  // any number of objects 
  1597.             texture{T1}
  1598.           }
  1599.        
  1600. CSG shapes may be used in CSG shapes. In fact, CSG shapes may be used 
  1601. anyplace that a standard shape is used.
  1602.        
  1603. The order of the component shapes with the CSG doesn't matter except in a 
  1604. difference shape. For CSG differences, the first shape is visible and the 
  1605. remaining shapes are cut out of the first.
  1606.        
  1607. Constructive solid geometry shapes may be translated, rotated, or scaled in 
  1608. the same way as any shape. The shapes making up the CSG shape may be 
  1609. individually translated, rotated, and scaled as well.
  1610.        
  1611. When using CSG, it is often useful to invert a shape so that it's inside-
  1612. out. The appearance of the shape is not changed, just the way that POV-Ray 
  1613. perceives it. The inverse keyword can be used to do this for any shape. 
  1614. When inverse is used, the "inside" of the shape is flipped to become the 
  1615. "outside". For planes, "inside" is defined to be "in the opposite direction 
  1616. to the "normal" or "up" direction. 
  1617.        
  1618. Note that performing an intersection between a shape and some other inverse 
  1619. shapes is the same as performing a difference. In fact, the difference is 
  1620. actually implemented in this way in the code.
  1621.        
  1622.  
  1623. 5.2.4.2     Inside and outside
  1624.  
  1625. Most shape primitives, like spheres, boxes, and blobs, divide the world 
  1626. into two regions. One region is inside the surface and one is outside.  
  1627. (The exceptions to this rule are triangles, disc and bezier patches - we'll 
  1628. talk about this later.)
  1629.        
  1630. Given any point in space, you can say it's either inside or outside any 
  1631. particular primitive object (well, it could be exactly on the surface, but 
  1632. numerical inaccuracies will put it to one side or the other). 
  1633.        
  1634. Even planes have an inside and an outside. By definition, the surface 
  1635. normal of the plane points towards the outside of the plane. (For a simple 
  1636. floor, for example, the space above the floor is "outside" and the space 
  1637. below the floor is "inside". For simple floors this in un-important, but 
  1638. for planes as parts of CSG's it becomes much more important). CSG uses the 
  1639. concepts of inside and outside to combine shapes together. Take the 
  1640. following situation:
  1641.        
  1642. Note: The diagrams shown here demonstrate the concepts in 2D and are 
  1643. intended only as an analogy to the 3D case. 
  1644.        
  1645. Note that the triangles and triangle-based shapes cannot be used as solid 
  1646. objects in CSG since they have no clear inside and outside.
  1647.  
  1648. In this diagram, point 1 is inside object A only.  Point 2 is inside B 
  1649. only.  Point 3 is inside both A and B while point 0 is outside everything.
  1650.        
  1651.          * = Object A
  1652.          % = Object B
  1653.        
  1654.                             *  0
  1655.                            * *    %
  1656.                           *   *  % %
  1657.                          *     *%   %
  1658.                         *  1   %*    %
  1659.                        *      %  * 2  %
  1660.                       *      % 3  *    %
  1661.                      *******%*******    %
  1662.                            %             %
  1663.                           %%%%%%%%%%%%%%%%%
  1664.        
  1665.        
  1666. Complex shapes may be created by combining other shapes using a technique 
  1667. called "Constructive Solid Geometry" (or CSG for short).  The CSG shapes 
  1668. are difference, intersection, and union. The following gives a simple 2D 
  1669. overview of how these functions work. 
  1670.  
  1671. 5.2.4.3     Union  
  1672.  
  1673. Unions are simply "glue", used bind two or more shapes into a single entity 
  1674. that can be manipulated as a single object.  The diagram above shows the 
  1675. union of A and B.  The new object created by the union operation can then 
  1676. be scaled, translated, and rotated as a single shape.  The entire union can 
  1677. share a single texture, but each object contained in the union may also 
  1678. have its own texture, which will override any matching texture statements 
  1679. in the parent object:
  1680.  
  1681.       union {
  1682.         sphere { <0, 0.5, 0> 1 pigment { Red } }
  1683.         sphere { <0, 0.0, 0> 1 }
  1684.         sphere { <0,-0.5, 0> 1 }
  1685.         pigment { Blue }
  1686.         finish { Shiny }
  1687.       }
  1688.  
  1689. This union will contain three spheres.  The first sphere is explicitly 
  1690. colored Red while the other two will be shiny blue.  Note that the shiny 
  1691. finish does NOT apply to the first sphere.  This is because the 
  1692. "pigment{Red}" is actually shorthand for "texture{pigment{Red}}".  It 
  1693. attaches an entire texture with default normals and finish.  The textures 
  1694. or pieces of textures attached to the union apply ONLY to components with 
  1695. no textures.  These texturing rules also apply to intersection, difference 
  1696. and merge as well.
  1697.  
  1698. Earlier versions of POV-Ray placed restrictions on unions so you often had 
  1699. to combine objects with composite statements.  Those earlier restrictions 
  1700. have been lifted so composite is no longer needed.  Composite is still 
  1701. supported for backwards compatibility but it is recommended that union now 
  1702. be used in it's place since future support for the composite keyword is not 
  1703. guarantied.
  1704.  
  1705.  
  1706. 5.2.4.4     Intersection
  1707.  
  1708. A point is inside the intersection if it's inside both A AND B. This 
  1709. "logical AND's" the shapes and gets the common part, most useful for 
  1710. "cutting" infinite shapes off.  The diagram below consists of only those 
  1711. parts common to A and B.
  1712.        
  1713.        
  1714.                                %*
  1715.                               %  *
  1716.                              % 3  *
  1717.                             %*******
  1718.        
  1719. For example:
  1720.  
  1721.      intersection {
  1722.        sphere {<-0.75,0,0>,1}
  1723.        sphere {< 0.75,0,0>,1}
  1724.        pigment {Yellow}
  1725.      }
  1726.  
  1727.  
  1728. 5.2.4.5     Difference
  1729.  
  1730. A point is inside the difference if it's inside A but not inside B. The 
  1731. results is a "subtraction" of the 2nd shape from the first shape:
  1732.        
  1733.                             *
  1734.                            * *
  1735.                           *   *
  1736.                          *     *
  1737.                         *  1   %
  1738.                        *      %
  1739.                       *      %
  1740.                      *******%
  1741.        
  1742. For example:
  1743.  
  1744.      difference {
  1745.        sphere {<-0.75,0,0>,1}
  1746.        sphere {< 0.75,0,-0.25>,1}
  1747.        pigment {Yellow}
  1748.      }
  1749.  
  1750.  
  1751. 5.2.4.6     Merge
  1752.  
  1753. As can be seen in the diagram for union, the inner surfaces where the 
  1754. objects overlap is still present.  On transparent or clipped objects these 
  1755. inner surfaces cause problems.  A merge object works just like union but it 
  1756. eliminates the inner surfaces like this:
  1757.  
  1758.                             *  
  1759.                            * *    %
  1760.                           *   *  % %
  1761.                          *     *%   %
  1762.                         *            %
  1763.                        *              %
  1764.                       *                %
  1765.                      *******%           %
  1766.                            %             %
  1767.                           %%%%%%%%%%%%%%%%%
  1768.        
  1769.        
  1770.  
  1771. 5.2.5 LIGHT SOURCES
  1772.  
  1773. The last object we'll cover is the light source.  Light sources have no 
  1774. visible shape of their own.  They are just points or areas which emit 
  1775. light.
  1776.  
  1777.  
  1778. 5.2.5.1     Point Lights
  1779.  
  1780. Most light sources are infinitely small points which emit light.  Point 
  1781. light sources are treated like shapes, but they are invisible points from 
  1782. which light rays stream out. They light objects and create shadows and 
  1783. highlights. Because of the way ray tracing works, lights do not reflect 
  1784. from a surface.  You can use many light sources in a scene, but each light 
  1785. source used will increase rendering time. The brightness of a light is 
  1786. determined by its color. A bright color is a bright light, a dark color, a 
  1787. dark one. White is the brightest possible light, Black is completely dark 
  1788. and Gray is somewhere in the middle.
  1789.  
  1790. The syntax for a light source is:
  1791.  
  1792.     light_source { <X, Y, Z> color red #, green #, blue #}
  1793.  
  1794. Where X, Y and Z are the coordinates of the location and "color" is any 
  1795. color or color identifier. For example,
  1796.  
  1797.     light_source { <3, 5, -6> color Gray50}
  1798.  
  1799. is a 50% Gray light at X=3, Y=5, Z=-6.
  1800.  
  1801. Point light sources in POV-Ray do not attenuate, or get dimmer, with 
  1802. distance.
  1803.  
  1804.  
  1805. 5.2.5.2     Spotlights
  1806.  
  1807. A spotlight is a point light source where the rays of light are constrained 
  1808. by a cone. The light is bright in the center of the spotlight and falls 
  1809. off/darkens to soft shadows at the edges of the circle.
  1810.  
  1811. The syntax is:
  1812.  
  1813. Syntax:   light_source { <CENTER>
  1814.               color red #, green #, blue #
  1815.               spotlight
  1816.               point_at <POINT>
  1817.               radius #
  1818.               falloff #
  1819.               tightness #
  1820.           }
  1821.  
  1822. A spotlight is positioned using two vectors.  The first vector is the usual 
  1823. <CENTER> vector that you would use to position a point light source.
  1824.  
  1825. The second vector is the point_at <POINT>, the vector position of
  1826. the point the light is pointing at, similar to the look_at in a camera 
  1827. description.
  1828.  
  1829. The following illustrations will be helpful in understanding how these 
  1830. values relate to each other:
  1831.  
  1832.  
  1833.            (+) Spotlight <center>
  1834.            / \
  1835.           /   \
  1836.          /     \
  1837.         /       \
  1838.        /         \
  1839.       /           \
  1840.       +-----*-----+
  1841.             ^ point_at <point>
  1842.  
  1843. The center is specified the same way as a normal point light_source.
  1844.  
  1845. Point_at <POINT> is the location that the cone of light is
  1846. aiming at.
  1847.  
  1848. Spotlights also have three other parameters: radius, falloff, and 
  1849. tightness.
  1850.  
  1851. If you think of a spotlight as two nested cones,  the inner cone would be 
  1852. specified by the radius parameter, and would be fully lit.  The outer cone 
  1853. would be the falloff cone and beyond it would be totally unlit.  The values 
  1854. for these two parameters are specified in degrees of the half angle at the 
  1855. peak of each cone:
  1856.  
  1857.  
  1858.            (+) Spotlight <center>
  1859.             |\ <-----  angle measured here
  1860.             | \
  1861.             || \
  1862.             ||  \      shaded area = radius cone
  1863.             |||  \     outer line = falloff cone
  1864.             ||||  \
  1865.             |||||  \
  1866.             +-------+
  1867.  
  1868. The radius# is the radius, in degrees, of the bright circular hotspot at 
  1869. the center of the spotlight's area of affect.
  1870.  
  1871. The falloff# is the falloff angle of the radius of the total spotlight 
  1872. area, in degrees. This is the value where the light "falls off" to zero 
  1873. brightness.  Falloff should be larger than the radius. Both values should 
  1874. be between 1 and 180.
  1875.  
  1876. The tightness value specifies how quickly the light dims, or falls off, in 
  1877. the region between the radius (full brightness) cone and the falloff (full 
  1878. darkness) cone.  The default value for tightness is 10.  Lower tightness 
  1879. values will make the spot have very soft edges. High values will make the 
  1880. edges sharper, the spot "tighter".  Values from 1 to 100 are acceptable.
  1881.  
  1882. Spotlights may used anyplace that a normal light source is used. Like 
  1883. normal light sources, they are invisible points. They are treated as shapes 
  1884. and may be included in CSG shapes.  They may also be used in conjunction 
  1885. with area_lights.
  1886.  
  1887. Example:
  1888.    // This is the spotlight.
  1889.    light_source {
  1890.       <10, 10, 0>
  1891.       color red 1, green 1, blue 0.5
  1892.       spotlight
  1893.       point_at <0, 1, 0>
  1894.       tightness 50
  1895.       radius 11
  1896.       falloff 25
  1897.      }
  1898.  
  1899.  
  1900.  
  1901. 5.2.3.3     Area Lights
  1902.  
  1903. Regular light sources in POV-Ray are modeled as point light sources, that 
  1904. is they emit light from a single point in space. Because of this the 
  1905. shadows created by these lights have the characteristic sharp edges that 
  1906. most of us are use to seeing in ray traced images. The reason for the 
  1907. distinct edges is that a point light source is either fully in view or it 
  1908. is fully blocked by an object. A point source can never be partially 
  1909. blocked.
  1910.  
  1911. Area lights on the other hand occupy a finite area of space. Since it is 
  1912. possible for an area light to be partially blocked by an object the shadows 
  1913. created will have soft or "fuzzy" edges. The softness of the edge is 
  1914. dependent on the dimensions of the light source and it's distance from the 
  1915. object casting the shadow.
  1916.  
  1917. The area lights used in POV-Ray are rectangular in shape, sort of like a 
  1918. flat panel light. Rather than performing the complex calculations that 
  1919. would be required to model a true area light, POV-Ray approximates an area 
  1920. light as an array of "point" light sources spread out over the area 
  1921. occupied by the light. The intensity of each individual point light in the 
  1922. array is dimmed so that the total amount of light emitted by the light is 
  1923. equal to the light color specified in the declaration.
  1924.  
  1925.  
  1926. Syntax:
  1927.  
  1928. light_source {
  1929.    <X, Y, Z> color red # green # blue #
  1930.  
  1931.    area_light <X1, Y1, Z1>, <X2, Y2, Z2>, N1, N2
  1932.    adaptive #
  1933.    jitter
  1934.  
  1935.    [optional spotlight parameters]
  1936. }
  1937.  
  1938. The light's location and color are specified in the same way as a
  1939. regular light source.
  1940.  
  1941. The area_light command defines the size and orientation of the area light 
  1942. as well as the number of lights in the light source array.  The vectors 
  1943. <X1,Y1,Z1> and <X2,Y2,Z2> specify the lengths and directions of the edges 
  1944. of the light. Since the area lights are rectangular in shape these vectors 
  1945. should be perpendicular to each other. The larger the size of the light the 
  1946. thicker that the soft part of the shadow will be. The numbers N1 and N2 
  1947. specify the dimensions of the array of point lights. The larger the number 
  1948. of lights you use the smoother your shadows will be but the longer they 
  1949. will take to render.
  1950.  
  1951. The adaptive command is used to enable adaptive sampling of the light 
  1952. source. By default POV-Ray calculates the amount of light that reaches a 
  1953. surface from an area light by shooting a test ray at every point light 
  1954. within the array. As you can imagine this is VERY slow. Adaptive sampling 
  1955. on the other hand attempts to approximate the same calculation by using a 
  1956. minimum number of test rays. The number specified after the keyword 
  1957. controls how much adaptive sampling is used. The higher the number the more 
  1958. accurate your shadows will be but the longer they will take to render. If 
  1959. you're not sure what value to use a good starting point is 'adaptive 1'.  
  1960. The adaptive command only accepts integer values and cannot be set lower 
  1961. than 0. Adaptive sampling is explained in more detail later.
  1962.  
  1963. The jitter command is optional. When used it causes the positions of the 
  1964. point lights in the array to be randomly jittered to eliminate any shadow 
  1965. banding that may occur. The jittering is completely random from render to 
  1966. render and should not be used when generating animations.
  1967.  
  1968. Note: It's possible to specify spotlight parameters along with area_light 
  1969. parameters to create "area spotlights." Using area spotlights is a good way 
  1970. to speed up scenes that use area lights since you can confine the lengthy 
  1971. soft shadow calculations to only the parts of your scene that need them.
  1972.  
  1973.  
  1974. Example:
  1975.  
  1976. light_source {
  1977.    <0, 50, 0> color White
  1978.  
  1979.    area_light <5, 0, 0>, <0, 0, 10>, 5, 5
  1980.    adaptive 1
  1981.    jitter
  1982. }
  1983.  
  1984. This defines an area light that extends 5 units along the x axis and 10 
  1985. units along the z axis and is centered at the location <0,50,0>. The light 
  1986. consists of a 5 by 5 jittered array of point sources for a total of 25 
  1987. point lights. A minimum of 9 shadow rays will be used each time this light 
  1988. is tested.
  1989.  
  1990.                      / * * * * *
  1991.                    / * * * * *           Y
  1992.         <0,0,10> / * * * * *             |     Z
  1993.                / * * * * *               |   /
  1994.              / * * * * *                 | /
  1995.            +----------->                 +------X
  1996.               <5,0,0>
  1997.  
  1998.  
  1999. An interesting effect that can be created using area lights is a linear 
  2000. light. Rather than having a rectangular shape, a linear light stretches 
  2001. along a line sort of like a thin fluorescent tube. To create a linear light 
  2002. just create an area light with one of the array dimensions set to 1.
  2003.  
  2004. Example:
  2005.  
  2006. light_source {
  2007.    <0, 50, 0> color White
  2008.  
  2009.    area_light <40, 0, 0>, <0, 0, 1>, 100, 1
  2010.    adaptive 4
  2011.    jitter
  2012. }
  2013.  
  2014. This defines a linear light that extends from <-40/2,50,0> to <+40/2,50,0> 
  2015. and consists of 100 point sources along it's length. The vector <0,0,1> is 
  2016. ignored in this case since a linear light has no width. Note: If the linear 
  2017. light is fairly long you'll usually need to set the adaptive parameter 
  2018. fairly high as in the above example.
  2019.  
  2020. When performing adaptive sampling POV-Ray starts by shooting a test ray at 
  2021. each of the four corners of the area light. If the amount of light received 
  2022. from all four corners is approximately the same then the area light is 
  2023. assumed to be either fully in view or fully blocked. The light intensity is 
  2024. then calculated as the average intensity of the light received from the 
  2025. four corners.  However, if the light intensity from the four corners 
  2026. differs significantly then the area light is partially blocked. The light 
  2027. is the split into four quarters and each section is sampled as described 
  2028. above. This allows POV-Ray to rapidly approximate how much of the area 
  2029. light is in view without having to shoot a test ray at every light in the 
  2030. array.
  2031.  
  2032. While the adaptive sampling method is fast (relatively speaking) it can 
  2033. sometimes produces inaccurate shadows. The solution is to reduce the amount 
  2034. of adaptive sampling without completely turning it off. The number after 
  2035. the adaptive keyword adjusts the number of times that the area light will 
  2036. be split before the adaptive phase begins. For example if you use "adaptive 
  2037. 0" a minimum of 4 rays will be shot at the light. If you use "adaptive 1" a 
  2038. minimum of 9 rays will be shot (adaptive 2 = 25 rays, adaptive 3 = 81 rays, 
  2039. etc). Obviously the more shadow rays you shoot the slower the rendering 
  2040. will be so you should use the lowest value that gives acceptable results.
  2041.  
  2042. The number of rays never exceeds the values you specify for rows and 
  2043. columns of points.  For example: area_light x,y,4,4 specifies a 4 by 4 
  2044. array of lights.  If you specify adaptive 3 it would mean that you should 
  2045. start with a 5 by 5 array.  In this case no adaptive sampling is done.  The 
  2046. 4 by 4 array is used.
  2047.  
  2048.  
  2049. 5.2.3.4     Looks_like
  2050.  
  2051. Normally the light source itself has no visible shape.  The light simply 
  2052. radiates from an invisible point or area.  You may give a light source a 
  2053. any shape by adding a "looks_like{OBJECT}" statement.  For example:
  2054.  
  2055.         light_source {
  2056.            <100,200,-300> color White
  2057.            looks_like {sphere{<0,0,0>,1 texture{T1}}
  2058.         }
  2059.  
  2060. This creates a visible sphere which is automatically translated to the 
  2061. light's location <100,200,-300> even though the sphere has <0,0,0> as its 
  2062. center.  There is an implied "no_shadow" also attached to the sphere so 
  2063. that light is not blocked by the sphere.  Without the automatic no_shadow, 
  2064. the light inside the sphere would not escape. The sphere would, in effect, 
  2065. cast a shadow over everything.
  2066.        
  2067. If you want the attached object to block light then you should attach it 
  2068. with a union and not a looks_like as follows:
  2069.  
  2070.         union {
  2071.           light_source {<100,200,-300> color White}
  2072.           object {My_Lamp_Shade}
  2073.         }
  2074.  
  2075. Presumably parts of the lamp shade are open to let SOME light out.
  2076.  
  2077.  
  2078. 5.3   OBJECT MODIFIERS
  2079. ----------------------
  2080.  
  2081. A variety of modifiers may be attached to objects.  Transformations such as 
  2082. translate, rotate and scale have already been discussed.  Textures are in a 
  2083. section of their own below.  Here are three other important modifiers: 
  2084. clipped_by, bounded_by and no_shadow.  Although the examples below use 
  2085. object statements and object identifiers, these modifiers may be used on 
  2086. any type of object such as sphere, box etc.
  2087.  
  2088.  
  2089. 5.3.1 CLIPPED_BY
  2090.    
  2091. The "clipped_by" statement is technically an object modifier but it 
  2092. provides a type of CSG similar to CSG intersection.  You attach a clipping 
  2093. object like this:
  2094.  
  2095.         object {
  2096.            My_Thing
  2097.            clipped_by{plane{y,0}}
  2098.         }
  2099.  
  2100. Every part of the object "My_Thing" that is inside the plane is retained 
  2101. while the remaining part is clipped off and discarded.  In an intersection 
  2102. object, the hole is closed off.  With clipped_by it leaves an opening.  For 
  2103. example this diagram shows our object "A" being clipped_by a plane{y,0}.
  2104.  
  2105.  
  2106.  
  2107.                        *       *
  2108.                       *         *
  2109.                      *           *
  2110.                     ***************
  2111.     
  2112. Clipped_by may be used to slice off portions of any shape. In many cases it 
  2113. will also result in faster rendering times than other methods of altering a 
  2114. shape.
  2115.  
  2116. Often you will want to use the clipped_by and bounded_by options with the 
  2117. same object.  The following shortcut saves typing and uses less memory.
  2118.  
  2119.         object {
  2120.            My_Thing
  2121.            bounded_by{box{<0,0,0>,<1,1,1>}}
  2122.            clipped_by{bounded_by}
  2123.         }
  2124.  
  2125. This tells POV-Ray to use the same box as a clip that was used as a bounds.
  2126.  
  2127.  
  2128. 5.3.1 BOUNDED_BY
  2129.  
  2130. The calculations necessary to test if a ray hits an object can be quite 
  2131. time consuming.  Each ray has to be tested against every object in the 
  2132. scene.  POV-Ray attempts so speed up the process by building a set of 
  2133. invisible boxes, called bounding slabs, which cluster the objects together.  
  2134. This way a ray that travels in one part of the scene doesn't have to be 
  2135. tested against objects in another far away part of the scene.  When large 
  2136. number objects are present the slabs are nested inside each other.  POV-Ray 
  2137. can use slabs on any finite object.  However infinite objects such as 
  2138. plane, quadric, quartic, cubic & poly cannot be automatically bound.  Also 
  2139. CSG objects cannot be efficiently bound by automatic methods.  By attaching 
  2140. a bounded_by statement to such shapes you can speed up the testing of the 
  2141. shape and make it capable of using bounding slabs.
  2142.  
  2143. If you use bounding shapes around any complex objects you can speed up the 
  2144. rendering. Bounding shapes tell the ray tracer that the object is totally 
  2145. enclosed by a simple shape. When tracing rays, the ray is first tested 
  2146. against the simple bounding shape. If it strikes the bounding shape, then 
  2147. the ray is further tested against the more complicated object inside. 
  2148. Otherwise the entire complex shape is skipped, which greatly speeds 
  2149. rendering.  
  2150.  
  2151. To use bounding shapes, simply include the following lines in the 
  2152. declaration of your object:
  2153.        
  2154.             bounded_by {
  2155.                  object { ... }
  2156.             }
  2157.        
  2158.        An example of a Bounding Shape:
  2159.        
  2160.             intersection {
  2161.                 sphere {<0,0,0>, 2}
  2162.                 plane  {<0,1,0>, 0}
  2163.                 plane  {<1,0,0>, 0}
  2164.                 bounded_by {sphere {<0,0,0>, 2}}
  2165.             }
  2166.        
  2167. The best bounding shape is a sphere or a box since these shapes are highly 
  2168. optimized, although, any shape may be used.  If the bounding shape is 
  2169. itself a finite shape which responds to bounding slabs then the object 
  2170. which it encloses will also be used in the slab system.
  2171.  
  2172. CSG shapes can benefit from bounding slabs without a bounded_by statement 
  2173. however they may do so inefficiently in intersection, difference and merge.  
  2174. In these three CSG types the automatic bound used covers all of the 
  2175. component objects in their entirety.  However the result of these 
  2176. intersections may result in a smaller object.  Compare the sizes of the 
  2177. illustrations for union and intersection in the CSG section above.  It is 
  2178. possible to draw a much smaller box around the intersection of A and B than 
  2179. the union of A and B yet the automatic bounds are the size of union{A B} 
  2180. regardless of the kind of CSG specified.
  2181.  
  2182. While it is almost always a good idea to manually add a bounded_by to 
  2183. intersection, difference and merge, it is often best to NOT bound a union.  
  2184. If a union has no bounded_by and no clipped_by then POV-Ray can internally 
  2185. split apart the components of a union and apply automatic bounding slabs to 
  2186. any of its finite parts.  Note that some utilities such as RAW2POV may be 
  2187. able to generate bounds more efficiently than POV-Ray's current system.  
  2188. However most unions you create yourself can be easily bounded by the 
  2189. automatic system.  For technical reasons POV-Ray cannot split a merge 
  2190. object.  It is probably best to hand bound a merge, especially if it is 
  2191. very complex.
  2192.  
  2193. Note that if bounding shape is too small or positioned incorrectly, it may 
  2194. clip the object in undefined ways or the object may not appear at all.  To 
  2195. do true clipping, use clipped_by as explained above. Often you will want to 
  2196. use the clipped_by and bounded_by options with the same object.  The 
  2197. following shortcut saves typing and uses less memory.
  2198.  
  2199.         object {
  2200.            My_Thing
  2201.            clipped_by{box{<0,0,0>,<1,1,1>}}
  2202.            bounded_by{clipped_by}
  2203.         }
  2204.  
  2205. This tells POV-Ray to use the same box as a bounds that was used as a clip.
  2206.  
  2207. 5.3.2 NO_SHADOW
  2208.  
  2209. You may specify the no_shadow keyword in object and that object will not 
  2210. cast a shadow.  This is useful for special effects and for creating the 
  2211. illusion that a light source actually is visible.  This keyword was 
  2212. necessary in earlier versions of POV-Ray which did not have the 
  2213. "looks_like" statement.  Now it is useful for creating things like laser 
  2214. beams or other unreal effects.
  2215.  
  2216. Simply attach the keyword as follows:
  2217.  
  2218.         object {
  2219.           My_Thing
  2220.           no_shadow
  2221.         }
  2222.  
  2223.  
  2224. 5.4   TEXTURES
  2225. --------------
  2226.  
  2227. Textures are the materials from which the objects in POV-Ray are made. They 
  2228. specifically describe the surface coloring, shading, and properties like 
  2229. transparency and reflection.
  2230.  
  2231. You can create your own textures using the parameters described below, or 
  2232. you can use the many pre-defined high quality textures that have been 
  2233. provided in the files TEXTURES.INC and STONES.INC. The tutorial in section 
  2234. 4 above introduces the basics of defining textures and attaching them to 
  2235. objects.  It explains how textures are made up of three portions, a color 
  2236. pattern called "pigment", a bump pattern called "normal", and surface 
  2237. properties called "finish". 
  2238.  
  2239. The most complete form for defining a texture is as follows:
  2240.  
  2241.   texture {
  2242.     TEXTURE_IDENTIFIER
  2243.     pigment {...}
  2244.     normal {...}
  2245.     finish {...}
  2246.     TRANSFORMATIONS...
  2247.   }
  2248.  
  2249. Each of the items in a texture are optional but if they are present, the 
  2250. identifier must be first and the transformations bust be last.  The 
  2251. pigment, normal and finish parameters modify any pigment, normal and finish 
  2252. already specified in the TEXTURE_IDENTIFIER.  If no texture identifier is 
  2253. specified then the pigment, normal and finish statements modify the current 
  2254. default values.  TRANSFORMATIONs are translate, rotate and scale 
  2255. statements.  They should be specified last.
  2256.  
  2257. The sections below describe all of the options available in pigments, 
  2258. normals and finishes.
  2259.  
  2260.  
  2261. 5.4.1 PIGMENT
  2262.  
  2263. The color or pattern of colors for an object is defined by a pigment 
  2264. statement.  A pigment statement is part of a texture specification.  
  2265. However it can be tedious to type "texture{pigment{...}}" just to add a 
  2266. color to an object.  Therefore you may attach a pigment directly to an 
  2267. object without explicitly specifying that it as part of a texture.  For 
  2268. example...
  2269.  
  2270.  this...                        can be shortened to this...
  2271.  
  2272.   object {                           object {                   
  2273.     My_Object                          My_Object                
  2274.     texture {                          pigment {color Purple} 
  2275.       pigment {color Purple}         }                        
  2276.     }                                  
  2277.   }                                                           
  2278.  
  2279. The color you define is the way you want it to look if fully illuminated.  
  2280. You pick the basic color inherent in the object and POV-Ray brightens or 
  2281. darkens it depending on the lighting in the scene.  The parameter is called 
  2282. "pigment" because we are defining the basic color the object actually IS 
  2283. rather than how it LOOKS.
  2284.  
  2285. The most complete form for defining a pigment is as follows:
  2286.  
  2287.   pigment {
  2288.     PIGMENT_IDENTIFIER
  2289.     PATTERN_TYPE
  2290.     PIGMENT_MODIFIERS
  2291.     TRANSFORMATIONS...
  2292.   }
  2293.  
  2294. Each of the items in a pigment are optional but if they are present, they 
  2295. should be in the order shown above to insure that the results are as 
  2296. expected.  Any items after the PIGMENT_IDENTIFIER modify or override 
  2297. settings given in the IDENTIFIER.  If no identifier is specified then the 
  2298. items modify the pigment values in the current default texture.  
  2299. TRANSFORMATIONs are translate, rotate and scale statements.  They apply 
  2300. only to the pigment and not to other parts of the texture.  They should be 
  2301. specified last.
  2302.  
  2303. The various PATTERN_TYPEs fall into roughly 4 categories.  Each category is 
  2304. discussed below.  They are solid color, color list patterns, color mapped 
  2305. patterns and image maps.
  2306.  
  2307.  
  2308. 5.4.1.1     Color
  2309.  
  2310. The simplest type of pigment is a solid color.  To specify a solid color 
  2311. you simply put a color specification inside a pigment.  For example...
  2312.  
  2313.   pigment {color Orange}
  2314.  
  2315. A color specification consists of the keyword "color" followed a color 
  2316. identifier or by a specification of the amount or red, green, blue and 
  2317. transparency in the surface.  For example:
  2318.  
  2319.   color red 0.5   green 0.2   blue 1.0
  2320.  
  2321. The float values between 0.0 and 1.0 are used to specify the intensity of 
  2322. each primary color of light.  Note that we use additive color primaries 
  2323. like the color phosphors on a color computer monitor or TV.  Thus...
  2324.  
  2325.   color red 1.0   green 1.0   blue 1.0 
  2326.  
  2327.  ...specifies full intensity of all primary colors which is white light.  
  2328. The primaries may be given in any order and if any primary is unspecified 
  2329. its value defaults to zero.
  2330.  
  2331. In addition to the primary colors a 4th value called "filter" specifies the 
  2332. amount of transparency.  For example a piece of red tinted cellophane might 
  2333. have...
  2334.  
  2335.   color red 1.0  filter 1.0
  2336.  
  2337. Lowering the filter value would let less light through.  The default value 
  2338. if no filter is specified is 0.0 or no transparency.  Note that the example 
  2339. has an implied "green 0.0  blue 0.0" which means that no green or blue 
  2340. light can pass through.  Often users mistakenly specify a clear object 
  2341. by...
  2342.  
  2343.   color filter 1.0
  2344.  
  2345. but this has implied red, green and blue values of zero.  You've just 
  2346. specified a totally black filter so no light passes through.  The correct 
  2347. way is...
  2348.  
  2349.   color red 1.0   green 1.0   blue 1.0   filter 1.0
  2350.  
  2351. Note in earlier versions of POV-Ray the keyword "alpha" was used for 
  2352. transparency.  However common usage of "alpha" in this context usually 
  2353. means that light passes through unaffected.  In POV-Ray however, light is 
  2354. filtered when it passes through a colored surface.  The program works the 
  2355. same as it always did but the keyword has been changed to make its meaning 
  2356. clearer.
  2357.  
  2358. A short-cut way to specify a color is...
  2359.  
  2360.   color rgb<0.2, 0.5, 0.9>
  2361.  
  2362.       or
  2363.  
  2364.   color rgbf<0.2, 0.8, 1.0, 0.7>
  2365.  
  2366. Color specifications are used elsewhere in POV-Ray.  Unless stated 
  2367. otherwise, all of the above information on color specs given above applies 
  2368. to any color spec.
  2369.  
  2370. Color identifiers may be declared.  For examples see COLORS.INC.  A color 
  2371. identifier contains red, blue, green and filter values even if they are not 
  2372. explicitly specified.  For example:
  2373.  
  2374.   color filter 1.0 My_Color // here My_Color overwrites the filter
  2375.  
  2376.   color My_Color filter 1.0 // this changes My_Color's filter value to 1.0
  2377.  
  2378. When using a color specification to give an object a solid color pigment, 
  2379. the keyword "color" may be omitted.  For example...
  2380.  
  2381.   pigment {red 1  blue 0.5}
  2382.         or
  2383.   pigment {My_Color}
  2384.  
  2385. are legal.
  2386.  
  2387.  
  2388. 5.4.1.2     Color List Patterns -- checker and hexagon
  2389.  
  2390. Two of the simplest color patterns available are the checker and hexagon 
  2391. patterns.  These patterns take a simple list of colors one after the other.  
  2392. For example a checker pattern is specified by...
  2393.  
  2394.   pigment {checker color C1  color C2}
  2395.  
  2396. This produces a checkered pattern consisting of alternating squares of 
  2397. color C1 and C2.  If no colors are specified then default blue and green 
  2398. colors are used.
  2399.  
  2400. All color patterns in POV-Ray are 3 dimensional.  For every x,y,z point in 
  2401. space, the pattern has a unique color.  In the case of a checker pattern it 
  2402. is actually a series of cubes that are one unit in size.  Imagine a bunch 
  2403. of 1 inch cubes made from two different colors of modeling clay.  Now 
  2404. imagine arranging the cubes in an alternating check pattern and stacking 
  2405. them in layer after layer so that the colors still alternated in every 
  2406. direction.  Eventually you would have a larger cube.  The pattern of checks 
  2407. on each side is what the POV-Ray checker pattern produces when applied to a 
  2408. box object.  Finally imagine cutting away at the cube until it is carved 
  2409. into a smooth sphere or any other shape.  This is what the checker pattern 
  2410. would look like on an object of any kind.
  2411.  
  2412. Color patterns do not wrap around the surfaces like putting wallpaper on an 
  2413. object.  The patterns exist in 3-d and the objects are carved from them 
  2414. like carving stacked colored cubes.  In a later section we describe wood 
  2415. and marble patterns for example.  The wood grain or stone swirls exist 
  2416. through the whole object but they appear only at the surface.
  2417.  
  2418. Another pattern that uses a list of colors is the hexagon pattern.  A 
  2419. hexagon pattern is specified by...
  2420.  
  2421.   pigment {hexagon color C1  color C2  color C3}
  2422.  
  2423. Hex pattern generates a repeating pattern of hexagons in the XZ plane.  In 
  2424. this instance imagine tall rods that are hexagonal in shape and are 
  2425. parallel to the Y axis and grouped in bundles like this...
  2426.  
  2427.            _____              
  2428.           /     \              
  2429.          /   C2  \_____             
  2430.         |\       /     \        
  2431.         | \_____/   C3  \
  2432.         | /     \       /|      
  2433.          /   C1  \_____/ |
  2434.         |\       /|    | |
  2435.         | \_____/ |    | |
  2436.         | |     | |    | |
  2437.         | |     | |    | |
  2438.         | |     | |    | |
  2439.         | |     | |    | |
  2440.         | |     | |    |
  2441.         | |     | |    |
  2442.           |     |
  2443.           |     |
  2444.  
  2445.  
  2446. The three colors will repeat the pattern shown above with hexagon C1 
  2447. centered at the origin.  Each side of the hexagon is one unit long.  The 
  2448. hexagonal "rods" of color extend infinitely in the +Y and -Y directions.  
  2449. If no colors are specified then default blue, green, and red colors are 
  2450. used.
  2451.  
  2452.  
  2453. 5.4.1.3     Color Mapped Patterns
  2454.  
  2455. Most of the color patterns do not use abrupt color changes of just two or 
  2456. three colors like those in the checker or hexagon patterns.  They instead 
  2457. use smooth transitions of many colors that gradually change from one point 
  2458. to the next.  The colors are defined in a color map that describes how the 
  2459. pattern blends from one color to the next.  
  2460.  
  2461.  
  2462. 5.4.1.3.1   Gradient 
  2463.  
  2464. This simplest such pattern is the "gradient" pattern.  It is specified as 
  2465. follows...
  2466.  
  2467.   pigment {gradient VECTOR}
  2468.  
  2469. where VECTOR is a vector pointing in the direction that the colors blend.  
  2470. For example:
  2471.  
  2472.       sphere {
  2473.         <0, 1, 2>, 2
  2474.         pigment { gradient x } // bands of color vary as you move
  2475.                                // along the "x" direction.
  2476.       }
  2477.  
  2478. This produces a series of smooth bands of color that look like layers of 
  2479. color next to each other.  Points at x=0 are black.  As the X location 
  2480. increases it smoothly turns to white at x=1.  Then it starts over with 
  2481. black and gradually turns white at x=2.  The pattern reverses for negative 
  2482. values of X.  Using "gradient y" or "gradient z" makes the colors blend 
  2483. along the y or z axis.  Any vector may be used but x, y and z are most 
  2484. common.
  2485.  
  2486.  
  2487. 5.4.1.3.2   Color Maps
  2488.  
  2489. The gray scale default colors of the gradient pattern isn't a very 
  2490. interesting sight.  The real power comes from specifying a color map to 
  2491. define how the colors should blend.
  2492.  
  2493. Each of the various pattern types available is in fact a mathematical 
  2494. function that takes any x,y,z location and turns it into a number between 
  2495. 0.0 and 1.0.  That number is used to specify what mix of colors to use from 
  2496. the color map.
  2497.  
  2498. A color map is specified by...
  2499.  
  2500.       color_map {
  2501.         [ NUM_1 color C1]
  2502.         [ NUM_2 color C2]
  2503.         [ NUM_3 color C3]
  2504.          ... 
  2505.         }
  2506.  
  2507. Where NUM_1, NUM_2... are float values between 0.0 and 1.0 inclusive.  C1, 
  2508. C2 ... are color specifications.  NOTE: the [] brackets are part of the 
  2509. actual statement.  They are not notational symbols denoting optional parts.  
  2510. The brackets surround each entry in the color map.  There may be from 2 to 
  2511. 20 entries in the map. 
  2512.  
  2513. For example,
  2514.  
  2515.       sphere {
  2516.         <0,1,2>, 2
  2517.         pigment { 
  2518.           gradient x 
  2519.           color_map {
  2520.             [0.1  color Red]
  2521.             [0.3  color Yellow]
  2522.             [0.6  color Blue]
  2523.             [0.6  color Green]
  2524.             [0.8  color Cyan]
  2525.           }
  2526.         }
  2527.       }
  2528.  
  2529. The pattern function is evaluated and the result is a value from 0.0 to 
  2530. 1.0.  If the value is less than the first entry (in this case 0.1) then the 
  2531. first color (Red) is used.  Values from 0.1 to 0.3 use a blend of red and 
  2532. yellow using linear interpolation of the two colors.  Similarly values from 
  2533. 0.3 to 0.6 blend from yellow to blue.  Note that the 3rd and 4th entries 
  2534. both have values of 0.6.  This causes an immediate abrupt shift of color 
  2535. from blue to green.  Specifically a value that is less than 0.6 will be 
  2536. blue but exactly equal to 0.6 will be green.  Moving along, values from 0.6 
  2537. to 0.8 will be a blend of green and cyan.  Finally any value greater than 
  2538. or equal to 0.8 will be cyan.
  2539.  
  2540. If you want areas of unchanging color you simply specify the same color for 
  2541. two adjacent entries.  For example:
  2542.  
  2543.       color_map {
  2544.         [0.1  color Red]
  2545.         [0.3  color Yellow]
  2546.         [0.6  color Yellow]
  2547.         [0.8  color Green]
  2548.       }
  2549.  
  2550. In this case any value from 0.3 to 0.6 will be pure yellow.
  2551.  
  2552.  
  2553. 5.4.1.3.3   Marble
  2554.  
  2555. A "gradient x" pattern uses colors from the color map from 0.0 up to 1.0 at 
  2556. location x=1 but then jumps back to the first color for x=1.00000001 (or 
  2557. some tiny fraction above 1.0) and repeats the pattern again and again.  The 
  2558. marble pattern is similar except that it uses the color map from 0 to 1 but 
  2559. then it reverses the map and blends from 1 back to zero.  For example:
  2560.  
  2561.       pigment { 
  2562.         gradient x 
  2563.         color_map {
  2564.           [0.0  color Yellow]
  2565.           [1.0  color Cyan]
  2566.         }
  2567.       }
  2568.  
  2569. This blends from yellow to cyan and then it abruptly changes back to yellow 
  2570. and repeats.  However replacing "gradient x" with "marble" smoothly blends 
  2571. from yellow to cyan as the x coordinate goes from 0.0 to 0.5 and then 
  2572. smoothly blends back from cyan to yellow by x=1.0.
  2573.  
  2574. When used with a "turbulence" modifier and an appropriate color map, this 
  2575. pattern looks like veins of color of real marble, jade or other types of 
  2576. stone. By default, marble has no turbulence.
  2577.  
  2578.  
  2579. 5.4.1.3.4   Wood
  2580.  
  2581. Wood uses the color map to create concentric cylindrical bands of color 
  2582. centered on the Z axis.  These bands look like the growth rings and veins 
  2583. in real wood.  Small amounts of turbulence should be added to make it look 
  2584. more realistic. By default, wood has no turbulence.
  2585.  
  2586. Like marble, wood uses color map values 0 to 1 then repeats the colors in 
  2587. reverse order from 1 to 0.
  2588.  
  2589.  
  2590. 5.4.1.3.5   Onion
  2591.  
  2592. Onion is a pattern of concentric spheres like the layers of an onion.  It 
  2593. uses colors from a color map from 0 to 1, 0 to 1 etc without reversing.
  2594.  
  2595.  
  2596. 5.4.1.3.6   Leopard 
  2597.  
  2598. Leopard creates regular geometric pattern of circular spots.  It uses 
  2599. colors from a color map from 0 to 1, 0 to 1 etc without reversing.
  2600.  
  2601.  
  2602. 5.4.1.3.7   Granite 
  2603.  
  2604. This pattern uses a simple 1/f fractal noise function to give a pretty darn 
  2605. good granite pattern. Typically used with small scaling values (2.0 to 
  2606. 5.0).  This pattern is used with creative color maps in STONES.INC to 
  2607. create some gorgeous layered stone textures. By default, granite has no 
  2608. turbulence.  It uses colors from a color map from 0 to 1, 0 to 1 etc 
  2609. without reversing.
  2610.  
  2611.  
  2612. 5.4.1.3.8   Bozo 
  2613.  
  2614. The bozo color pattern takes a noise function and maps it onto the surface 
  2615. of an object. It uses colors from a color map from 0 to 1, 0 to 1 etc 
  2616. without reversing.
  2617.  
  2618. Noise in ray tracing is sort of like a random number generator, but it has 
  2619. the following properties:
  2620.  
  2621.   1) It's defined over 3D space i.e., it takes x, y, and z and returns the 
  2622. noise value there.
  2623.   2) If two points are far apart, the noise values at those points are 
  2624. relatively random.
  2625.   3) If two points are close together, the noise values at those points are 
  2626. close to each other.
  2627.  
  2628. You can visualize this as having a large room and a thermometer that ranges 
  2629. from 0.0 to 1.0. Each point in the room has a temperature. Points that are 
  2630. far apart have relatively random temperatures. Points that are close 
  2631. together have close temperatures. The temperature changes smoothly, but 
  2632. randomly as we move through the room. 
  2633.  
  2634. Now, let's place an object into this room along with an artist. The artist 
  2635. measures the temperature at each point on the object and paints that point 
  2636. a different color depending on the temperature. What do we get? A POV-Ray 
  2637. bozo texture!
  2638.  
  2639.  
  2640. 5.4.1.3.9   Spotted 
  2641.  
  2642. This uses the same noise pattern as bozo but it is unaffected by 
  2643. turbulence.  It uses colors from a color map from 0 to 1, 0 to 1 etc 
  2644. without reversing.
  2645.  
  2646.  
  2647. 5.4.1.3.10  Agate 
  2648.  
  2649. This pattern is very beautiful and similar to marble, but uses a different 
  2650. turbulence function. The turbulence keyword has no effect, and as such it 
  2651. is always very turbulent. You may control the amount of the built-in 
  2652. turbulence by adding the "agate_turb" keyword followed by a float value.  
  2653. For example:
  2654.  
  2655.       pigment { 
  2656.         agate
  2657.         agate_turb 0.5
  2658.         color_map {
  2659.           ...
  2660.         }
  2661.       }
  2662.  
  2663.  
  2664. 5.4.1.3.11  Mandel
  2665.  
  2666. The mandel pattern computes the standard Mandelbrot fractal pattern and 
  2667. projects it onto the X-Y plane.  It uses the X and Y coordinates to compute 
  2668. the Mandelbrot set.  The pattern is specified with the keyword mandel 
  2669. followed by an integer number.  This number is the maximum number of 
  2670. iterations to be used to compute the set.  Typical values range from 10 up 
  2671. to 256 but any positive integer may be used.  For example:
  2672.  
  2673.       sphere { 
  2674.        <0, 0, 0>, 1 
  2675.        pigment {
  2676.          mandel 25
  2677.          color_map {
  2678.            [0.0  color Cyan]
  2679.            [0.3  color Yellow]
  2680.            [0.6  color Magenta]
  2681.            [1.0  color Cyan]
  2682.          }
  2683.          scale .5
  2684.        }
  2685.       }
  2686.  
  2687. The value passed to the color map is computed by the formula:
  2688.  
  2689.     value = number_of_iterations / max_iterations
  2690.  
  2691. The color extends infinitely in the Z direction similar to a planar image 
  2692. map.  
  2693.  
  2694.  
  2695. 5.4.1.3.12  Radial
  2696.  
  2697. The radial pattern is a radial blend that wraps around the +Y axis.  The 
  2698. color for value 0.0 starts at the +X direction and wraps the color map 
  2699. around from east to west with 0.25 in the -Z direction, 0.5 in -X, 0.75 at 
  2700. +Z and back to 1.0 at +X.  See the "frequency" and "phase" pigment 
  2701. modifiers below for examples.
  2702.  
  2703.  
  2704. 5.4.1.4     Image Maps
  2705.  
  2706. When all else fails and none of the above pigment pattern types meets your 
  2707. needs, you can use an image map to wrap a 2-D bit-mapped image around your 
  2708. 3-D objects.
  2709.  
  2710.  
  2711. 5.4.1.4.1   Specifying an image map.
  2712.  
  2713. The syntax for image_map is...
  2714.  
  2715.   pigment {
  2716.     image_map {
  2717.       FILE_TYPE "filename"
  2718.       MODIFIERS...
  2719.     }
  2720.   }
  2721.  
  2722. Where FILE_TYPE is one of the following keywords "gif", "tga", "iff" or 
  2723. "dump".  This is followed by the name of the file in quotes.  Several 
  2724. optional modifiers may follow the file specification.  The modifiers are 
  2725. described below.  Note: Earlier versions of POV-Ray allowed some modifiers 
  2726. before the FILE_TYPE but that syntax is being phased out in favor of the 
  2727. syntax described here.
  2728.  
  2729. Filenames specified in the image_map statements will be searched for in the 
  2730. home (current) directory first, and if not found, will then be searched for 
  2731. in directories specified by any "-L" (library path) options active. This 
  2732. would facilitate keeping all your image maps files in a separate 
  2733. subdirectory, and giving an "-L" option on the command line to where your 
  2734. library of image maps are. 
  2735.  
  2736. By default, the image is mapped onto the X-Y plane.  The image is 
  2737. "projected" onto the object as though there were a slide projector 
  2738. somewhere in the -Z direction.  The image exactly fills the square area 
  2739. from x,y coordinates (0,0) to (1,1) regardless of the image's original size 
  2740. in pixels.  If you would like to change this default, you may translate, 
  2741. rotate or scale the pigment or texture to map it onto the object's surface 
  2742. as desired. 
  2743.  
  2744. In the section 5.4.1.2 above when we explained checker pigment patterns, we 
  2745. described the checks as solid cubes of colored clay from which objects are 
  2746. carved.  With image maps you should imagine that each pixel is a long, 
  2747. thin, square, colored rod that extends parallel to the Z axis.  The image 
  2748. is made from rows and columns of these rods bundled together and the object 
  2749. is then carved from the bundle.
  2750.  
  2751. If you would like to change this default orientation, you may translate, 
  2752. rotate or scale the pigment or texture to map it onto the object's surface 
  2753. as desired. 
  2754.  
  2755.  
  2756. 5.4.1.4.2   The "once" option.
  2757.  
  2758. Normally there are an infinite number of repeating images created over 
  2759. every unit square of the X-Y plane like tiles.  By adding the keyword 
  2760. "once" after a file name, you can eliminate all other copies of the image 
  2761. except the one at (0,0) to (1,1).  Areas outside this unit square are 
  2762. treated as fully transparent.
  2763.  
  2764. Note: The "once" keyword may also be used with bump_map and material_map 
  2765. statements.
  2766.  
  2767.  
  2768. 5.4.1.4.3   The "map_type" option.
  2769.  
  2770. The default projection of the image onto the X-Y plane is called a "planar 
  2771. map type".  This option may be changed by adding the "map_type" keyword 
  2772. followed by a number specifying the way to wrap the image around the 
  2773. object.
  2774.  
  2775. A "map_type 0" gives the default planar mapping already described.
  2776.  
  2777. A "map_type 1" is a spherical mapping.  It assumes that the object is a 
  2778. sphere of any size sitting at the origin.  The Y axis is the north/south 
  2779. pole of the spherical mapping.  The top and bottom edges of the image just 
  2780. touch the pole regardless of any scaling.  The left edge of the image 
  2781. begins at the positive X axis and wraps the image around the sphere from 
  2782. "west" to "east" in a -Y rotation.  The image covers the sphere exactly 
  2783. once.  The "once" keyword has no meaning for this type.
  2784.  
  2785. With "map_type 2" you get a cylindrical mapping.  It assumes that a 
  2786. cylinder of any diameter lies along the Y axis.  The image wraps around the 
  2787. cylinder just like the spherical map but the image remains 1 unit tall from 
  2788. y=0 to y=1.  This band of color is repeated at all heights unless the 
  2789. "once" keyword is applied.
  2790.  
  2791. Finally "map_type 5" is a torus or donut shaped mapping.  It assumes that a 
  2792. torus of major radius 1 sits at the origin in the X-Z plane.  The image is 
  2793. wrapped around similar to spherical or cylindrical maps.  However the top 
  2794. and bottom edges of the map wrap over and under the torus where they meet 
  2795. each other on the inner rim.
  2796.  
  2797. Types 3 and 4 are still under development.
  2798.  
  2799. Note: The "map_type" option may also be applied to bump_map and 
  2800. material_map statements.
  2801.  
  2802.  
  2803. 5.4.1.4.4   The "filter" options.
  2804.  
  2805. To make all or part of an image map transparent, you can specify filter 
  2806. values for the color palette/registers of GIF or IFF pictures (at least for 
  2807. the modes that use palettes/color maps). You can do this by adding the 
  2808. keyword "filter" following the filename.  The keyword is followed by two 
  2809. numbers.  The first number is the palette/register number value and 2nd is 
  2810. the amount of transparency. The values should be separated by a comma.  For 
  2811. example:
  2812.  
  2813.    image_map { 
  2814.      gif "mypic.gif"
  2815.      map_type 0 
  2816.      filter 0, 0.5 // Make color 0 50% transparent
  2817.      filter 5, 1.0 // Make color 5 100% transparent
  2818.      filter 8, 0.3 // Make color 8 30% transparent
  2819.     }
  2820.  
  2821. You can give the entire image a filter value using "filter all VALUE".  For 
  2822. example:
  2823.  
  2824.    image_map { 
  2825.      gif "stnglass.gif"
  2826.      map_type 0 
  2827.      filter all 0.9
  2828.     }
  2829.  
  2830. NOTE: Transparency works by filtering light by its original color.  Adding 
  2831. "filter" to the color black still leaves you with black no matter how high 
  2832. the filter value is. If you want a color to be clear, add filter 1 to the 
  2833. color white.
  2834.  
  2835.  
  2836. 5.4.1.4.5   The "interpolate" option.
  2837.  
  2838. Adding the "interpolate" keyword can smooths the jagged look of an image or 
  2839. bump map.  When POV-Ray asks a color or bump amount for an image or bump 
  2840. map, it often asks for a point that is not directly on top of one pixel, 
  2841. but sort of between several different colored pixels.  Interpolations 
  2842. returns an "in-between" value so that the steps between the pixels in the 
  2843. image or bump map will look smoother.
  2844.  
  2845. There are currently two types of interpolation:
  2846.  
  2847.    Normalized Distance -- interpolate 4
  2848.    Bilinear            -- interpolate 2
  2849.  
  2850. Default is no interpolation. Normalized distance is the slightly faster of 
  2851. the two, bilinear does a better job of picking the between color. Normally, 
  2852. bilinear is used.
  2853.  
  2854. If your bump or image map looks jaggy, try using interpolation instead of 
  2855. going to a higher resolution image.  The results can be very good.  For 
  2856. example:
  2857.  
  2858.    image_map { 
  2859.      gif "mypic.gif"
  2860.      map_type 0 
  2861.      interpolate 2
  2862.     }
  2863.  
  2864.  
  2865. 5.4.1.5     Pigment Modifiers
  2866.  
  2867. After specifying the pigment type such as marble, wood etc and adding an 
  2868. optional color map, you may add any of several modifiers.
  2869.  
  2870.  
  2871. 5.4.1.5.1   Turbulence
  2872.  
  2873. The keyword "turbulence" followed by a float or vector may be used to stir 
  2874. up the color pattern.  Typical values range from the default 0.0 which is 
  2875. no turbulence to 1.0 which is very turbulent.  If a vector is specified 
  2876. then different amounts of turbulence are applied in the x, y and z 
  2877. directions.  For example "turbulence <1.0, 0.6, 0.1>" has much turbulence 
  2878. in the x direction, a moderate amount in the y direction and a small amount 
  2879. in the z direction.
  2880.  
  2881. Turbulence uses a noise function called DNoise.  This is sort of like noise 
  2882. used in the bozo pattern except that instead of giving a single value it 
  2883. gives a direction. You can think of it as the direction that the wind is 
  2884. blowing at that spot.
  2885.  
  2886. Turbulence which uses DNoise to push a point around a few times.  We locate 
  2887. the point we want to color (P), then push it around a bit using turbulence 
  2888. to get to a final point (Q) then look up the color of point Q in our 
  2889. ordinary boring textures. That's the color that's used for the point P.
  2890.  
  2891. It in effect says "Don't give me the color at this spot... take a few 
  2892. random steps in a different direction and give me that color.  Each step is 
  2893. typically half as long as the one before.  For example:
  2894.  
  2895.          P ------------------------->
  2896.                   First Move        /
  2897.                                    /
  2898.                                   /
  2899.                                  /Second
  2900.                                 /  Move
  2901.                                /
  2902.                         ______/
  2903.                         \
  2904.                          \
  2905.                           Q - Final point.
  2906.  
  2907.  
  2908. The magnitude of these steps is controlled by the turbulence value.
  2909.  
  2910.  
  2911. 5.4.1.5.2   Octaves
  2912.  
  2913. The number of steps used by turbulence is controlled by the "octaves" 
  2914. value.  The values may range from 1 up to 10.  The default value of 
  2915. "octaves 6" is fairly close to the upper limit; you won't see much change 
  2916. by setting it to a higher value because the extra steps are too small.  You 
  2917. can achieve some very interesting wavy effects by specifying lower values. 
  2918. Setting octaves higher can slow down rendering because more steps are 
  2919. computed.
  2920.  
  2921.  
  2922. 5.4.1.5.3   Omega
  2923.  
  2924. The keyword "omega" followed by a float value may be added to change the 
  2925. turbulence calculations.  Each successive octave of turbulence is 
  2926. multiplied by the omega value. The default "omega 0.5" means that each 
  2927. octave is 1/2 the size of the previous one.  Higher omega values mean that 
  2928. 2nd, 3rd, 4th and up octaves contribute more turbulence giving a sharper, 
  2929. "krinkly" look while smaller omegas give a fuzzy kind of turbulence that 
  2930. gets blury in places.
  2931.  
  2932.  
  2933. 5.4.1.5.4   Lambda
  2934.  
  2935. The lambda parameter controls how statistically different the random move 
  2936. of an octave is compared to its previous octave.  The default value for 
  2937. this is "lambda 2".  Values close to lambda 1.0 will straighten out the 
  2938. randomness of the path in the diagram above.  Higher values can look more 
  2939. "swirly" under some circumstances.  More tinkering by POV-Ray users may 
  2940. lead us to discover ways to make good use of this parameter.  For now just 
  2941. tinker and enjoy.
  2942.  
  2943.  
  2944. 5.4.1.5.5   Quick_color
  2945.  
  2946. When developing POV-Ray scenes its often useful to do low quality test runs 
  2947. that render faster.  The +Q command line switch can be used to turn off 
  2948. some time consuming color pattern and lighting calculations to speed things 
  2949. up.  However all settings of +Q5 or lower turns off pigment calculations 
  2950. and creates gray objects.
  2951.  
  2952. By adding a "quick_color" to a pigment you tell POV-Ray what solid color to 
  2953. use for quick renders instead of a patterned pigment.  For example:
  2954.  
  2955.    pigment {
  2956.      gradient x
  2957.      color_map{
  2958.        [0 color Yellow][0.3 color Cyan][0.6 color Magenta][1 color Cyan]
  2959.      }
  2960.      turbulence 0.5  lambda 1.5  omega 0.75  octaves 8
  2961.      quick_color Neon_Pink
  2962.    }
  2963.  
  2964. This tells POV-Ray to use solid Neon_Pink for test runs at quality +Q5 or 
  2965. lower but to use the turbulent gradient pattern for rendering at +Q6 and 
  2966. higher.
  2967.  
  2968. Note that solid color pigments such as:
  2969.  
  2970.    pigment {color Magenta}
  2971.  
  2972. automatically set the quick_color to that value.  You may override this if 
  2973. you want.  Suppose you have 10 spheres on the screen and all are Yellow.  
  2974. If you want to identify them individually you could give each a different 
  2975. quick_color like this:
  2976.  
  2977.    sphere {<1,2,3>,4 pigment {color Yellow  quick_color Red}}
  2978.  
  2979.    sphere {<-1,-2,-3>,4 pigment {color Yellow  quick_color Blue}}
  2980.  
  2981.  ...and so on.  At +Q6 or higher they will all be Yellow but at +Q5 or 
  2982. lower each would be different colors so you could identify them.
  2983.  
  2984.  
  2985. 5.4.1.5.6   Frequency and Phase
  2986.  
  2987. The frequency and phase keywords were originally intended for the normal 
  2988. patterns ripples and waves discussed in the next section.  With version 2.0 
  2989. they were extended to pigments to make the radial and mandel pigment 
  2990. pattern easier to use.  As it turned out it was simple to make them apply 
  2991. to any color map pattern.
  2992.  
  2993. The frequency keyword adjusts the number of times that a color map repeats 
  2994. over one cycle of a pattern.  For example gradient x covers color map 
  2995. values 0 to 1 over the range x=0 to x=1.  By adding "frequency 2" the color 
  2996. map repeats twice over that same range.  The same effect can be achieved 
  2997. using "scale x*0.5" so the frequency keyword isn't that useful for patterns 
  2998. like gradient. 
  2999.  
  3000. However the radial pattern wraps the color map around the +Y axis once.  If 
  3001. you wanted two copies of the map (or 3 or 10 or 100) you'd have to build a 
  3002. bigger map.  Adding "frequency 2" causes the color map to be used twice per 
  3003. revolution.  Try this:
  3004.  
  3005.       sphere {<0,0,0>,3
  3006.         pigment { 
  3007.           radial
  3008.           color_map{[0.5 color Red][0.5 color White]}
  3009.           frequency 6
  3010.         }
  3011.         rotate -x*90
  3012.       }
  3013.  
  3014. The result is 6 sets of red and white radial stripes evenly spaced around 
  3015. the sphere.
  3016.  
  3017. Note "frequency -1" reverses the entries in a color_map.
  3018.  
  3019. The phase keyword takes values from 0.0 to 1.0 and rotates the color map 
  3020. entries.  In the example above if you render successive frames at phase 0 
  3021. then phase 0.1, phase 0.2 etc you could create an animation that rotates 
  3022. the stripes.  The same effect can be easily achieved by rotating the radial 
  3023. pigment using "rotate y*Angle" but there are other uses where phase can be 
  3024. handy.  
  3025.  
  3026. Sometimes you create a great looking gradient or wood color map but you 
  3027. want the grain slightly adjusted in or out.  You could re-order the color 
  3028. map entries but that's a pain.  A phase adjustment will shift everything 
  3029. but keep the same scale.  Try animating a mandel pigment for a color 
  3030. palette rotation effect.
  3031.  
  3032.  
  3033. 5.4.1.5.7   Transforming pigments
  3034.  
  3035. You may modify pigment patterns with "translate", "rotate" and "scale" 
  3036. commands.  Note that placing these transforms inside the texture but 
  3037. outside the pigment will transform the entire texture.  However placing 
  3038. them inside the pigment transforms just the pigment.  For example:
  3039.  
  3040.       sphere {<0,0,0>,3
  3041.         texture {
  3042.           pigment { 
  3043.             checker color Red color White
  3044.             scale <2,1,3>  // affects pigment only... not normal
  3045.           }
  3046.           normal {
  3047.             bumps 0.3
  3048.             scale 0.4      // affects bump normal only... not pigment
  3049.           }
  3050.           finish {Shiny}
  3051.           translate 5*x    // affects entire texture
  3052.         }
  3053.         translate y*2      // affects object and texture
  3054.       }
  3055.  
  3056. Note that transforms affect the entire pigment regardless of the ordering 
  3057. of other parameters.  For example:
  3058.  
  3059.   This...                         ...is the same as this...
  3060.  
  3061.      pigment {                          pigment {                    
  3062.        bozo                               bozo                       
  3063.        turbulence 0.3                     scale 2                              
  3064.        scale 2                            turbulence 0.3   
  3065.      }                                  }                            
  3066.  
  3067. The scaling before or after turbulence makes no difference.  In general it 
  3068. is best to put all transformations last for the sake of clarity.
  3069.  
  3070.  
  3071. 5.4.2 NORMAL
  3072.  
  3073. Ray tracing is known for the dramatic way it depicts reflection, refraction 
  3074. and lighting effects.  Much of our perception depends on the reflective 
  3075. properties of an object.  Ray tracing can exploit this by playing tricks on 
  3076. our perception to make us see complex details that aren't really there.
  3077.  
  3078. Suppose you wanted a very bumpy surface on the object.  It would be very 
  3079. difficult to mathematically model lots of bumps.  We can however simulate 
  3080. the way bumps look by altering the way light reflects off of the surface.  
  3081. Reflection calculations depend on a vector called a "surface normal" 
  3082. vector.  This is a vector which points away from the surface and is 
  3083. perpendicular to it.  By artificially modifying (or perturbing) this normal 
  3084. vector you can simulate bumps.  
  3085.  
  3086. The "normal {...}" statement is the part of a texture which defines the 
  3087. pattern of normal perturbations to be applied to an object.  Like the 
  3088. pigment statement, you can omit the surrounding texture block to save 
  3089. typing.  Do not forget however that there is a texture implied. For 
  3090. example...
  3091.  
  3092.  this...                        can be shortened to this...
  3093.  
  3094.   object {                           object {                   
  3095.     My_Object                          My_Object                
  3096.     texture {                          pigment {color Purple} 
  3097.       pigment {color Purple}           normal {bumps 0.3}                        
  3098.       normal {bumps 0.3}             }
  3099.     }                                  
  3100.   }                                                           
  3101.  
  3102. Note that attaching a normal pattern does not really modify the surface.  
  3103. It only affects the way light reflects or refracts at the surface so that 
  3104. it looks bumpy.
  3105.  
  3106. The most complete form for defining a normal is as follows:
  3107.  
  3108.   normal {
  3109.     NORMAL_IDENTIFIER
  3110.     NORMAL_PATTERN_TYPE
  3111.     NORMAL_MODIFIERS
  3112.     TRANSFORMATIONS...
  3113.   }
  3114.  
  3115. Each of the items in a normal are optional but if they are present, they 
  3116. should be in the order shown above to insure that the results are as 
  3117. expected.  Any items after the NORMAL_IDENTIFIER modify or override 
  3118. settings given in the IDENTIFIER.  If no identifier is specified then the 
  3119. items modify the normal values in the current default texture.  
  3120. TRANSFORMATIONs are translate, rotate and scale statements.  They apply 
  3121. only to the normal and not to other parts of the texture.  They should be 
  3122. specified last.
  3123.  
  3124. There are 6 different NORMAL_PATTERN_TYPEs discussed below.  They are 
  3125. bumps, dents, ripples, waves, wrinkles and bump_map.  
  3126.  
  3127.  
  3128. 5.4.2.1     Bumps
  3129.  
  3130. A smoothly rolling random pattern of bumps can be created with the "bumps" 
  3131. normal pattern.  Bumps uses the same random noise function as the bozo and 
  3132. spotted pigment patterns, but uses the derived value to perturb the surface 
  3133. normal or, in other words, make the surface look bumpy. This gives the 
  3134. impression of a "bumpy" surface, random and irregular, sort of like an 
  3135. orange. 
  3136.  
  3137. After the bumps keyword, you supply a single floating point value for the 
  3138. amount of surface perturbation.  Values typically range from 0.0 (No Bumps) 
  3139. to 1.0 or greater (Extremely Bumpy). For example:
  3140.  
  3141.       sphere {
  3142.         <0, 1, 2>, 2
  3143.         texture {
  3144.           pigment {color Yellow}  
  3145.           normal {bumps 0.4   scale 0.2}
  3146.           finish {phong 1}
  3147.         }
  3148.       }
  3149.  
  3150. This tells POV-Ray to use a bump pattern to modify the surface normal.  The 
  3151. value 0.4 controls the apparent depth of the bumps.  Usually the bumps are 
  3152. about 1 unit wide which doesn't work very well with a sphere of radius 2.  
  3153. The scale makes the bumps 1/5th as wide but does not affect their depth. 
  3154.  
  3155.  
  3156. 5.4.2.2     Dents
  3157.  
  3158. The "dents" pattern is especially interesting when used with metallic 
  3159. textures, it gives impressions into the metal surface that look like dents 
  3160. have been beaten into the surface with a hammer. A single value is supplied 
  3161. after the dents keyword to indicate the amount of denting required. Values 
  3162. range from 0.0 (Showroom New) to 1.0 (Insurance Wreck). Scale the pattern 
  3163. to make the pitting more or less frequent.
  3164.  
  3165.  
  3166. 5.4.2.3     Ripples
  3167.  
  3168. The ripples bump pattern make a surface look like ripples of water. The 
  3169. ripples option requires a value to determine how deep the ripples are.  
  3170. Values range from 0.0 to 1.0 or more.  The ripples radiate from 10 random 
  3171. locations inside the unit cube area <0,0,0> to <1,1,1>.  Scale the pattern 
  3172. to make the centers closer or farther apart.  
  3173.  
  3174. The frequency keyword changes the spacing between ripples.  The phase 
  3175. keyword can be used to move the ripples outwards for realistic animation.
  3176.  
  3177.  
  3178. 5.4.2.4     Waves
  3179.  
  3180. This works in a similar way to ripples except that it makes waves with 
  3181. different frequencies. The effect is to make waves that look more like deep 
  3182. ocean waves.  The waves option requires a value to determine how deep the 
  3183. waves are.  Values range from 0.0 to 1.0 or more.  The waves radiate from 
  3184. 10 random locations inside the unit cube area <0,0,0> to <1,1,1>.  Scale 
  3185. the pattern to make the centers closer or farther apart.  
  3186.  
  3187. The frequency keyword changes the spacing between waves.  The phase keyword 
  3188. can be used to move the waves outwards for realistic animation.
  3189.  
  3190.  
  3191. 5.4.2.5     Wrinkles
  3192.  
  3193. This is sort of a 3-D bumpy granite. It uses a similar 1/f fractal noise 
  3194. function to perturb the surface normal in 3-D space. With a transparent 
  3195. color pattern, could look like wrinkled cellophane. Requires a single value 
  3196. after the wrinkles keyword to indicate the amount of wrinkling desired. 
  3197. Values from 0.0 (No Wrinkles) to 1.0 (Very Wrinkled) are typical. 
  3198.  
  3199.  
  3200. 5.4.2.6     Bump_map
  3201.  
  3202. When all else fails and none of the above normal pattern types meets your 
  3203. needs, you can use a bump map to wrap a 2-D bit-mapped bump pattern around 
  3204. your 3-D objects.
  3205.  
  3206. Instead of placing the color of the image on the shape like an image_map, 
  3207. bump_map perturbs the surface normal based on the color of the image at 
  3208. that point. The result looks like the image has been embossed into the 
  3209. surface.  By default, bump_map uses the brightness of the actual color of 
  3210. the pixel. Colors are converted to gray scale internally before calculating 
  3211. height.  Black is a low spot, white is a high spot. The image's index 
  3212. values may be used instead (see use_index) below.  
  3213.  
  3214.  
  3215. 5.4.2.6.1   Specifying a bump map.
  3216.  
  3217. The syntax for bump_map is...
  3218.  
  3219.   normal {
  3220.     bump_map {
  3221.       FILE_TYPE "filename"
  3222.       MODIFIERS...
  3223.     }
  3224.   }
  3225.  
  3226. Where FILE_TYPE is one of the following keywords "gif", "tga", "iff" or 
  3227. "dump".  This is followed by the name of the file in quotes.  Several 
  3228. optional modifiers may follow the file specification.  The modifiers are 
  3229. described below.  Note: Earlier versions of POV-Ray allowed some modifiers 
  3230. before the FILE_TYPE but that syntax is being phased out in favor of the 
  3231. syntax described here.
  3232.  
  3233. Filenames specified in the bump_map statements will be searched for in the 
  3234. home (current) directory first, and if not found, will then be searched for 
  3235. in directories specified by any "-L" (library path) options active. This 
  3236. would facilitate keeping all your bump maps files in a separate 
  3237. subdirectory, and giving an "-L" option on the command line to where your 
  3238. library of bump maps are. 
  3239.  
  3240. By default, the bump is mapped onto the X-Y plane.  The bump is "projected" 
  3241. onto the object as though there were a slide projector somewhere in the -Z 
  3242. direction.  The bump exactly fills the square area from x,y coordinates 
  3243. (0,0) to (1,1) regardless of the bump's original size in pixels.  If you 
  3244. would like to change this default, you may translate, rotate or scale the 
  3245. normal or texture to map it onto the object's surface as desired. 
  3246.  
  3247. If you would like to change this default orientation, you may translate, 
  3248. rotate or scale the normal or texture to map it onto the object's surface 
  3249. as desired. 
  3250.  
  3251.  
  3252. 5.4.2.6.2   Bump_size
  3253.  
  3254. The relative bump_size can be scaled using bump_size modifier. The 
  3255. bump_size number can be any number other than 0. Valid numbers are 2, .5, 
  3256. -33, 1000, etc. For example:
  3257.  
  3258.   normal {
  3259.     bump_map { 
  3260.       gif "stuff.gif" 
  3261.       bump_size 5
  3262.     }
  3263.   }
  3264.  
  3265.  
  3266. 5.4.2.6.3   Use_index & use_color
  3267.  
  3268. Usually the bump_map converts the color of the pixel in the map to a 
  3269. grayscale intensity value in the range 0.0 to 1.0 and calculates the bumps 
  3270. based on that value.  If you specify use_index, bump_map uses the color's 
  3271. palette number to compute as the height of the bump at that point. So, 
  3272. color #0 would be low and color #255 would be high. The actual color of the 
  3273. pixels doesn't matter when using the index.  The "use_color" keyword may be 
  3274. specified to explicitly note that the color methods should be used instead.
  3275.  
  3276.  
  3277. 5.4.2.6.4   The "once" option.
  3278.  
  3279. Normally there are an infinite number of repeating bump_maps created over 
  3280. every unit square of the X-Y plane like tiles.  By adding the keyword 
  3281. "once" after a file name, you can eliminate all other copies of the 
  3282. bump_map except the one at (0,0) to (1,1).  Areas outside this unit square 
  3283. are treated as fully transparent.
  3284.  
  3285. Note: The "once" keyword may also be used with image_map and material_map 
  3286. statements.
  3287.  
  3288.  
  3289. 5.4.2.6.5   The "map_type" option.
  3290.  
  3291. The default projection of the bump onto the X-Y plane is called a "planar 
  3292. map type".  This option may be changed by adding the "map_type" keyword 
  3293. followed by a number specifying the way to wrap the bump around the object.
  3294.  
  3295. A "map_type 0" gives the default planar mapping already described.
  3296.  
  3297. A "map_type 1" is a spherical mapping.  It assumes that the object is a 
  3298. sphere of any size sitting at the origin.  The Y axis is the north/south 
  3299. pole of the spherical mapping.  The top and bottom edges of the bump_map 
  3300. just touch the pole regardless of any scaling.  The left edge of the 
  3301. bump_map begins at the positive X axis and wraps the pattern around the 
  3302. sphere from "west" to "east" in a -Y rotation.  The pattern covers the 
  3303. sphere exactly once.  The "once" keyword has no meaning for this type.
  3304.  
  3305. With "map_type 2" you get a cylindrical mapping.  It assumes that a 
  3306. cylinder of any diameter lies along the Y axis.  The bump pattern wraps 
  3307. around the cylinder just like the spherical map but remains 1 unit tall 
  3308. from y=0 to y=1.  This band of bumps is repeated at all heights unless the 
  3309. "once" keyword is applied.
  3310.  
  3311. Finally "map_type 5" is a torus or donut shaped mapping.  It assumes that a 
  3312. torus of major radius 1 sits at the origin in the X-Z plane.  The bump 
  3313. pattern is wrapped around similar to spherical or cylindrical maps.  
  3314. However the top and bottom edges of the map wrap over and under the torus 
  3315. where they meet each other on the inner rim.
  3316.  
  3317. Types 3 and 4 are still under development.
  3318.  
  3319. Note: The "map_type" option may also be applied to image_map and 
  3320. material_map statements.
  3321.  
  3322.  
  3323. 5.4.2.6.6   The "interpolate" option.
  3324.  
  3325. Adding the "interpolate" keyword can smooths the jagged look of a bump map.  
  3326. When POV-Ray asks bump amount for a bump map, it often asks for a point 
  3327. that is not directly on top of one pixel, but sort of between several 
  3328. different colored pixels.  Interpolations returns an "in-between" value so 
  3329. that the steps between the pixels in the bump map will look smoother.
  3330.  
  3331. There are currently two types of interpolation:
  3332.  
  3333.    Normalized Distance -- interpolate 4
  3334.    Bilinear            -- interpolate 2
  3335.  
  3336. Default is no interpolation. Normalized distance is the slightly faster of 
  3337. the two, bilinear does a better job of picking the between color. Normally, 
  3338. bilinear is used.
  3339.  
  3340. If your bump map looks jaggy, try using interpolation instead of going to a 
  3341. higher resolution image.  The results can be very good.
  3342.  
  3343.  
  3344. 5.4.2.7     Normal Modifiers
  3345.  
  3346. After specifying the normal type such as bumps, dents etc you may add any 
  3347. of several modifiers.
  3348.  
  3349.  
  3350. 5.4.2.7.1   Turbulence
  3351.  
  3352. The keyword "turbulence" followed by a float or vector may be used to stir 
  3353. up the color pattern.  Typical values range from the default 0.0 which is 
  3354. no turbulence to 1.0 which is very turbulent.  If a vector is specified 
  3355. then different amounts of turbulence is applied in the x, y and z 
  3356. directions.  For example "turbulence <1.0, 0.6, 0.1>" has much turbulence 
  3357. in the x direction, a moderate amount in the y direction and a small amount 
  3358. in the z direction.
  3359.  
  3360. A complete discussion of turbulence is given under Pigment Modifiers in 
  3361. section 5.4.1.5 above.  The "octaves", "omega", and "lambda" options are 
  3362. also available as normal modifiers.  They discussed under that section as 
  3363. well.
  3364.  
  3365.  
  3366. 5.4.2.7.2   Frequency and Phase
  3367.  
  3368. Both waves and ripples respond to a parameter called phase. The phase 
  3369. option allows you to create animations in which the water seems to move. 
  3370. This is done by making the phase increment slowly between frames. The range 
  3371. from 0.0 to 1.0 gives one complete cycle of a wave.
  3372.  
  3373. The waves and ripples textures also respond to a parameter called 
  3374. frequency. If you increase the frequency of the waves, they get closer 
  3375. together. If you decrease it, they get farther apart. 
  3376.  
  3377. Bumps, dents, wrinkles and bump_map do not respond to frequency or phase.
  3378.  
  3379.  
  3380. 5.4.2.7.3   Transforming normals
  3381.  
  3382. You may modify normal patterns with "translate", "rotate" and "scale" 
  3383. commands.  Note that placing these transforms inside the texture but 
  3384. outside the normal will transform the entire texture.  However placing them 
  3385. inside the normal transforms just the normal.  See section 5.4.1.5.7 
  3386. Transforming Pigments for examples:
  3387.  
  3388.  
  3389. 5.4.3 FINISH
  3390.  
  3391. The finish properties of a surface can greatly affect its appearance.  How 
  3392. does light reflect?  What happens when light passes through?  What kind of 
  3393. highlights are visible.  To answer these questions you need a finish 
  3394. statement.
  3395.  
  3396. The "finish {...}" statement is the part of a texture which defines the 
  3397. various finish properties to be applied to an object.  Like the pigment or 
  3398. normal statement, you can omit the surrounding texture block to save 
  3399. typing.  Do not forget however that there is a texture implied. For 
  3400. example...
  3401.  
  3402.  this...                        can be shortened to this...
  3403.  
  3404.   object {                           object {                   
  3405.     My_Object                          My_Object                
  3406.     texture {                          pigment {color Purple} 
  3407.       pigment {color Purple}           finish {phong 0.3}                        
  3408.       finish {phong 0.3}             }
  3409.     }                                  
  3410.   }                                                           
  3411.  
  3412. The most complete form for defining a finish is as follows:
  3413.  
  3414.   finish {
  3415.     FINISH_IDENTIFIER
  3416.     FINISH_ITEMS...
  3417.   }
  3418.  
  3419. The FINISH_IDENTIFIER is optional but should proceed all other items.  Any 
  3420. items after the FINISH_IDENTIFIER modify or override settings given in the 
  3421. IDENTIFIER.  If no identifier is specified then the items modify the finish 
  3422. values in the current default texture.  Note that transformations are not 
  3423. allowed inside a finish because finish items cover the entire surface 
  3424. uniformly.  
  3425.  
  3426.  
  3427. 5.4.3.1     Diffuse Reflection Items
  3428.  
  3429. When light reflects off of a surface, the laws of physics say that it 
  3430. should leave the surface at the exact same angle it came in.  This is 
  3431. similar to the way a billiard ball bounces off a bumper of a pool table.  
  3432. This perfect reflection is called "specular" reflection.  However only very 
  3433. smooth polished surfaces reflect light in this way.  Most of the time, 
  3434. light reflects and is scattered in all directions by the roughness of the 
  3435. surface.  This scattering is called "diffuse reflection" because the light 
  3436. diffuses or spreads in a variety of directions.  It accounts for the 
  3437. majority of the reflected light we see.
  3438.  
  3439. In the real world, light may come from any of three possible sources.  1)It 
  3440. can come directly from actual light sources which are illuminating an 
  3441. object.  2)It can bounce from other objects such as mirrors via specular 
  3442. reflection.  For example shine a flashlight onto a mirror.  3)It can bounce 
  3443. from other objects via diffuse reflections. Look at some dark area under a 
  3444. desk or in a corner.  Even though a lamp may not directly illuminate that 
  3445. spot you can still see a little bit because light comes from diffuse 
  3446. reflection off of nearby objects.
  3447.  
  3448.  
  3449. 5.4.3.1.1   Diffuse
  3450.  
  3451. POV-Ray and most other ray tracers can only simulate directly, one of these 
  3452. three types of illumination.  That is the light which comes directly from 
  3453. the light source which diffuses in all directions.  The keyword "diffuse" 
  3454. is used in a finish statement to control how much light of this direct 
  3455. light is reflected via diffuse reflection.  For example:
  3456.  
  3457.       finish {diffuse 0.7}
  3458.  
  3459. means that 70% of the light seen comes from direct illumination from light 
  3460. sources.  The default value is diffuse 0.6.
  3461.  
  3462.  
  3463. 5.4.3.1.2   Brilliance
  3464.  
  3465. The amount of direct light that diffuses from an object depends upon the 
  3466. angle at which it hits the surface.  When light hits at a shallow angle it 
  3467. illuminates less.  When it is directly above a surface it illuminates more.  
  3468. The "brilliance" keyword can be used in a finish statement to vary the way 
  3469. light falls off depending upon the angle of incidence.  This controls the 
  3470. tightness of the basic diffuse illumination on objects and slightly adjusts 
  3471. the appearance of surface shininess.  Objects may appear more metallic by 
  3472. increasing their brilliance. The default value is 1.0. Higher values from 
  3473. 3.0 to about 10.0 cause the light to fall off less at medium to low angles.  
  3474. There are no limits to the brilliance value. Experiment to see what works 
  3475. best for a particular situation. This is best used in concert with 
  3476. highlighting.
  3477.  
  3478.  
  3479. 5.4.3.1.3   Crand Graininess
  3480.  
  3481. Very rough surfaces, such as concrete or sand, exhibit a dark graininess in 
  3482. their apparent color.  This is caused by the shadows of the pits or holes 
  3483. in the surface.  The "crand" keyword can be added to cause a minor random 
  3484. darkening the diffuse reflection of direct illumination.  Typical values 
  3485. range from "crand 0.01" to "crand 0.5" or higher.  The default value is 0.  
  3486. For example:
  3487.  
  3488.       finish {crand 0.05}
  3489.  
  3490. The grain or noise introduced by this feature is applied on a pixel-by-
  3491. pixel basis.  This means that it will look the same on far away objects as 
  3492. on close objects.  The effect also looks different depending upon the 
  3493. resolution you are using for the rendering.  For these reasons it is not a 
  3494. very accurate way to model the rough surface effect, but some objects still 
  3495. look better with a little crand thrown in.
  3496.  
  3497. In previous versions of POV-Ray there was no "crand" keyword.  Any lone 
  3498. float value found inside a texture{...} which was not preceded by a keyword 
  3499. was interpreted as a randomness value.
  3500.  
  3501. NOTE: This should not be used when rendering animations.  This is the one 
  3502. of a few truly random features in POV-Ray, and will produce an annoying 
  3503. flicker of flying pixels on any textures animated with a "crand" value.
  3504.        
  3505.  
  3506. 5.4.3.1.4   Ambient
  3507.  
  3508. The light you see in dark shadowed areas comes from diffuse reflection off 
  3509. of other objects.  This light cannot be directly modeled using ray tracing.  
  3510. However we can use a trick called "ambient lighting" to simulate the light 
  3511. inside a shadowed area.  
  3512.  
  3513. Ambient light is light that is scattered everywhere in the room. It bounces 
  3514. all over the place and manages to light objects up a bit even where no 
  3515. light is directly shining.  Computing real ambient light would take far too 
  3516. much time, so we simulate ambient light by adding a small amount of white 
  3517. light to each texture whether or not a light is actually shining on that 
  3518. texture.
  3519.  
  3520. This means that the portions of a shape that are completely in shadow will 
  3521. still have a little bit of their surface color. It's almost as if the 
  3522. texture glows, though the ambient light in a texture only affects the shape 
  3523. it is used on. 
  3524.  
  3525. The default value is very little ambient light (0.1). The value can range 
  3526. from 0.0 to 1.0.  Ambient light affects both shadowed and non-shadowed 
  3527. areas so if you turn up the ambient value you may want to turn down the 
  3528. diffuse value.
  3529.  
  3530. Note that this method doesn't account for the color of surrounding objects.  
  3531. If you walk into a room that has red walls, floor and ceiling then your 
  3532. white clothing will look pink from the reflected light.  POV-Ray's ambient 
  3533. shortcut doesn't account for this.  There is also no way to model specular 
  3534. reflected indirect illumination such as the flashlight shining in a mirror.
  3535.  
  3536.  
  3537. 5.4.3.2     Specular Reflection Items
  3538.  
  3539. When light does not diffuse and it DOES reflect at the same angle as it 
  3540. hits an object, it is called "specular reflection".  Such mirror-like 
  3541. reflection is controlled by the "reflection" keyword in a finish statement.  
  3542. For example:
  3543.  
  3544.       finish {reflection 1.0  ambient 0  diffuse 0}
  3545.  
  3546. This gives the object a mirrored finish. It will reflect all other 
  3547. elements in the scene.  The value can range from 0.0 to 1.0. By default 
  3548. there is no reflection.
  3549.  
  3550. Adding reflection to a texture makes it take longer to render because an 
  3551. additional ray must be traced.  
  3552.  
  3553. NOTE: Although such reflection is called "specular" it is not controlled by 
  3554. the POV-Ray "specular" keyword.  That keyword controls a "specular" 
  3555. highlight.
  3556.  
  3557.  
  3558. 5.4.3.3     Highlights
  3559.  
  3560. A highlights are the bright spots that appear when a light source reflects 
  3561. off of a smooth object.  They are a blend of specular reflection and 
  3562. diffuse reflection.  They are specular-like because they depend upon 
  3563. viewing angle and illumination angle.  However they are diffuse-like 
  3564. because some scattering occurs.  In order to exactly model a highlight you 
  3565. would have to calculate specular reflection off of thousands of microscopic 
  3566. bumps called micro facets.  The more that micro facets are facing the 
  3567. viewer, the shinier the object appears, and the tighter the highlights 
  3568. become. POV-Ray uses two different models to simulate highlights without 
  3569. calculating micro facets.  They are the specular and phong models.
  3570.  
  3571. Note that specular and phong highlights are NOT mutually exclusive. It is 
  3572. possible to specify both and they will both take effect. Normally, however, 
  3573. you will only specify one or the other.
  3574.  
  3575.  
  3576. 5.4.3.3.1   Phong Highlights
  3577.  
  3578. The "phong" keyword controls the amount of Phong highlighting on the 
  3579. object.  It causes bright shiny spots on the object that are the color of 
  3580. the light source being reflected.
  3581.  
  3582. The Phong method measures the average of the facets facing in the mirror 
  3583. direction from the light sources to the viewer. 
  3584.  
  3585. Phong's value is typically from 0.0 to 1.0, where 1.0 causes complete 
  3586. saturation to the light source's color at the brightest area (center) of 
  3587. the highlight. The default phong 0.0 gives no highlight.
  3588.  
  3589. The size of the highlight spot is defined by the phong_size value.  The 
  3590. larger the phong_size, the tighter, or smaller, the highlight and the 
  3591. shinier the appearance. The smaller the phong_size, the looser, or larger, 
  3592. the highlight and the less glossy the appearance.
  3593.  
  3594. Typical values range from 1.0 (Very Dull) to 250 (Highly Polished) though 
  3595. any values may be used. Default phong_size is 40 (plastic) if phong_size is 
  3596. not specified.  For example:
  3597.  
  3598.       finish {phong 0.9  phong_size 60}
  3599.  
  3600. If "phong" is not specified then "phong_size" has no effect.
  3601.  
  3602.  
  3603. 5.4.3.3.2   Specular Highlight
  3604.  
  3605. A specular highlight is very similar to Phong highlighting, but uses 
  3606. slightly different model.  The specular model more closely resembles real 
  3607. specular reflection and provides a more credible spreading of the 
  3608. highlights occur near the object horizons. 
  3609.  
  3610. Specular's value is typically from 0.0 to 1.0, where 1.0 causes complete 
  3611. saturation to the light source's color at the brightest area (center) of 
  3612. the highlight. The default specular 0.0 gives no highlight.
  3613.  
  3614. The size of the spot is defined by the value given for roughness.  Typical 
  3615. values range from 1.0 (Very Rough -- large highlight) to 0.0005 (Very 
  3616. Smooth -- small highlight). The default value, if roughness is not 
  3617. specified, is 0.05 (Plastic).
  3618.  
  3619. It is possible to specify "wrong" values for roughness that will generate 
  3620. an error when you try to render the file. Don't use 0 and if you get 
  3621. errors, check to see if you are using a very, very small roughness value 
  3622. that may be causing the error.  For example:
  3623.  
  3624.       finish {specular 0.9  roughness 0.02}
  3625.  
  3626. If "specular" is not specified then "roughness" has no effect.
  3627.  
  3628.  
  3629. 5.4.3.3.3   Metallic Highlight Modifier
  3630.  
  3631. The keyword "metallic" may be used with phong or specular highlights.  This 
  3632. keyword indicates that the color of the highlights will be filtered by the 
  3633. surface color instead of directly using the light_source color. Note that 
  3634. the keyword has no numeric value after it.  You either have it or you 
  3635. don't.  For example:
  3636.  
  3637.       finish {phong 0.9  phong_size 60  metallic}
  3638.  
  3639. If "phong" or "specular" is not specified then "metallic" has no effect.
  3640.  
  3641.  
  3642. 5.4.3.4     Refraction
  3643.  
  3644. When light passes through a surface either into or out of a dense medium, 
  3645. the path of the ray of light is bent.  Such bending is called refraction.  
  3646. Normally transparent or semi-transparent surfaces in POV-Ray do not refract 
  3647. light.  Adding "refraction 1.0" to the finish statement turns on 
  3648. refraction.  
  3649.  
  3650. Note: It is recommended that you only use "refraction 0" or "refraction 1".  
  3651. Values in between will darken the refracted light in ways that do not 
  3652. correspond to any physical property.  Many POV-Ray scenes were created with 
  3653. intermediate refraction values before this "bug" was discovered so the 
  3654. "feature" has been maintained.  A more appropriate way to reduce the 
  3655. brightness of refracted light is to change the "filter" value in the colors 
  3656. specified in the pigment statement.  Note also that "refraction" does not 
  3657. cause the object to be transparent.  Transparency is only occurs if there 
  3658. is a non-zero "filter" value in the color.
  3659.  
  3660. The amount of bending or refracting of light depends upon the density of 
  3661. the material.  Air, water, crystal, diamonds all have different density and 
  3662. thus refract differently.  The "index of refraction" or "ior" value is used 
  3663. by scientists to describe the relative density of substances.  The "ior" 
  3664. keyword is used in POV-Ray to specify the value.  For example:
  3665.  
  3666.       texture {
  3667.         pigment { White filter 0.9 }
  3668.         finish {
  3669.           refraction 1
  3670.           ior 1.5
  3671.         }
  3672.       }
  3673.  
  3674. The default ior value of 1.0 will give no refraction.  The index of 
  3675. refraction for air is 1.0, water is 1.33, glass is 1.5, and diamond is 2.4. 
  3676. The file IOR.INC pre-defines several useful values for ior.
  3677.  
  3678. NOTE: If a texture has a filter component and no value for refraction and 
  3679. ior are supplied, the renderer will simply transmit the ray through the 
  3680. surface with no bending.  In layered textures, the refraction and ior 
  3681. keywords MUST be in the last texture, otherwise they will not take effect.
  3682.  
  3683.  
  3684. 5.4.4 SPECIAL TEXTURES
  3685.  
  3686. Most textures consist of a single pigment, normal and finish specification 
  3687. which applies to the entire surface.  However two special textures have 
  3688. been implemented that extend the "checker" and "image_map" concepts to 
  3689. cover not just pigment but the entire texture.
  3690.  
  3691.  
  3692. 5.4.4.1     Tiles
  3693.  
  3694. This first special texture is the "tiles" texture.  It works just like the 
  3695. "checker" pigment pattern except it colors the blocks with entire textures 
  3696. rather than solid colors.
  3697.  
  3698. The syntax is:
  3699.  
  3700.       texture{
  3701.         tiles {
  3702.           texture {... put in a texture here ... } 
  3703.         tile2
  3704.           texture {... this is the second tile texture } 
  3705.         } 
  3706.        // Optionally put translate, rotate or scale here
  3707.       }
  3708.  
  3709. For example:
  3710.  
  3711.     texture{
  3712.        tiles {
  3713.           texture { Jade }
  3714.        tile2
  3715.           texture { Red_Marble }
  3716.        } 
  3717.     }
  3718.  
  3719. The textures used in each tile may be any type of texture including more 
  3720. tiles or regular textures made from pigment, normal and finish statements.  
  3721. Note that no other pigment, normal or finish statements may be added to the 
  3722. texture.  This is illegal:
  3723.  
  3724.       texture {
  3725.         tiles {
  3726.           texture {T1}
  3727.         tile2
  3728.           texture {T2}
  3729.         }
  3730.         finish {phong 1.0}
  3731.       }
  3732.  
  3733. The finish must be individually added to each texture.
  3734.  
  3735. Note that earlier versions of POV-Ray used only the pigment parts of the 
  3736. textures in the tiles.  Normals and finish were ignored.  Also layered 
  3737. textures were not supported.  In order to correct these problems the above 
  3738. restrictions on syntax were necessary.  This means some POV-Ray 1.0 scenes 
  3739. using tiles many need minor modifications that cannot be done automatically 
  3740. with the version compatibility mode.
  3741.  
  3742. The textures within a tiles texture may be layered but tiles textures do 
  3743. don't work as part of a layered texture.
  3744.  
  3745.  
  3746. 5.4.4.2     Material_Map
  3747.  
  3748. The "material_map" special texture extends the concept of "image_map" to 
  3749. apply to entire textures rather than solid colors.  A material_map allows 
  3750. you to wrap a 2-D bit-mapped texture pattern around your 3-D objects.
  3751.  
  3752. Instead of placing a solid color of the image on the shape like an 
  3753. image_map, an entire texture is specified based on the index or color of 
  3754. the image at that point.  You must specify a list of textures to be used 
  3755. like a "texture palette" rather than the usual color palette.  
  3756.  
  3757. When used with mapped file types such as GIF, the index of the pixel is 
  3758. used as an index into the list of textures you supply.  For unmapped file 
  3759. types such as TGA, the 8 bit value of the red component in the range 0-255 
  3760. is used as an index.  
  3761.  
  3762. If the index of a pixel is greater than the number of textures in your list 
  3763. then the index is taken modulo N where N is the length of your list of 
  3764. textures.  
  3765.  
  3766.  
  3767. 5.4.4.2.1   Specifying a material map.
  3768.  
  3769. The syntax for material_map is...
  3770.  
  3771.       texture {
  3772.         material_map {
  3773.           FILE_TYPE "filename"
  3774.           MODIFIERS...
  3775.           texture {...} // First used for index 0
  3776.           texture {...} // Second texture used for index 1
  3777.           texture {...} // Third texture used for index 2
  3778.           texture {...} // Fourth texture used for index 3
  3779.                         // and so on for however many used.
  3780.         }
  3781.         TRANSFORMATION...
  3782.       }
  3783.  
  3784. If particular index values are not used in an image then it may be 
  3785. necessary to supply dummy textures.  It may be necessary to use a paint 
  3786. program or other utility to examine the map file's palette to determine how 
  3787. to arrange the texture list.
  3788.  
  3789. In the syntax above, FILE_TYPE is one of the following keywords "gif", 
  3790. "tga", "iff" or "dump".  This is followed by the name of the file in 
  3791. quotes.  Several optional modifiers may follow the file specification.  The 
  3792. modifiers are described below.  Note: Earlier versions of POV-Ray allowed 
  3793. some modifiers before the FILE_TYPE but that syntax is being phased out in 
  3794. favor of the syntax described here.
  3795.  
  3796. Filenames specified in the material_map statements will be searched for in 
  3797. the home (current) directory first, and if not found, will then be searched 
  3798. for in directories specified by any "-L" (library path) options active. 
  3799. This would facilitate keeping all your material maps files in a separate 
  3800. subdirectory, and giving an "-L" option on the command line to where your 
  3801. library of material maps are. 
  3802.  
  3803. By default, the material is mapped onto the X-Y plane.  The material is 
  3804. "projected" onto the object as though there were a slide projector 
  3805. somewhere in the -Z direction.  The material exactly fills the square area 
  3806. from x,y coordinates (0,0) to (1,1) regardless of the material's original 
  3807. size in pixels.  If you would like to change this default, you may 
  3808. translate, rotate or scale the normal or texture to map it onto the 
  3809. object's surface as desired. 
  3810.  
  3811. If you would like to change this default orientation, you may translate, 
  3812. rotate or scale the texture to map it onto the object's surface as desired. 
  3813.  
  3814. Note that no other pigment, normal or finish statements may be added to the 
  3815. texture outside the material_map.  This is illegal:
  3816.  
  3817.       texture {
  3818.         material_map {
  3819.           gif "matmap.gif"
  3820.           texture {T1}
  3821.           texture {T2}
  3822.           texture {T3}
  3823.         }
  3824.         finish {phong 1.0}
  3825.       }
  3826.  
  3827. The finish must be individually added to each texture.
  3828.  
  3829. Note that earlier versions of POV-Ray allowed such specifications but they 
  3830. were ignored.  The above restrictions on syntax were necessary for various 
  3831. bug fixes.  This means some POV-Ray 1.0 scenes using material_maps many 
  3832. need minor modifications that cannot be done automatically with the version 
  3833. compatibility mode.
  3834.  
  3835. The textures within a material_map texture may be layered but material_map 
  3836. textures do don't work as part of a layered texture.  To use a layered 
  3837. texture inside a material_map you must declare it as a texture identifier 
  3838. and invoke it in the texture list.
  3839.  
  3840.  
  3841. 5.4.4.2.2   Material_map options.
  3842.  
  3843. The "once" and "map_type" options may be used with material_maps exactly 
  3844. like image_map or bump_map.  The "interpolate" keyword also is allowed but 
  3845. it interpolates the map indices rather than the colors.  In most cases this 
  3846. results in a worse image instead of a better image.  Future versions will 
  3847. fix this problem.
  3848.  
  3849.  
  3850. 5.4.5 LAYERED TEXTURES
  3851.  
  3852. It is possible to create a variety of special effects using layered 
  3853. textures.  A layered texture is one where several textures that are 
  3854. partially transparent are laid one on top of the other to create a more 
  3855. complex texture. The different texture layers show through the transparent 
  3856. portions to create the appearance of one texture that is a combination of 
  3857. several textures.
  3858.  
  3859. You create layered textures by listing two or more textures one right after 
  3860. the other. The last texture listed will be the top layer, the first one 
  3861. listed will be the bottom layer. All textures in a layered texture other 
  3862. than the bottom layer should have some transparency.  For example:
  3863.  
  3864.       object {
  3865.         My_Object
  3866.         texture {T1}  // the bottom layer
  3867.         texture {T2}  // a semi-transparent layer
  3868.         texture {T3}  // the top semi-transparent layer
  3869.       }
  3870.  
  3871. In this example T2 shows only where T3 is transparent and T1 shows only 
  3872. where T2 and T3 are transparent.
  3873.  
  3874. The color of underlying layers is filtered by upper layers but the results 
  3875. do not look exactly like a series of transparent surfaces.  If you had a 
  3876. stack of surfaces with the textures applied to each, the light would be 
  3877. filtered twice: once on the way in as the lower layers are illuminated by 
  3878. filtered light and once on the way out.  Layered textures do not filter the 
  3879. illumination on the way in.  Other parts of the lighting calculations work 
  3880. differently as well.  The result look great and allow for fantastic looking 
  3881. textures but they are simply different from multiple surfaces.  See 
  3882. STONES.INC in the standard include files for some magnificent layered 
  3883. textures.
  3884.  
  3885. Note layered textures must use the "texture{...}" wrapped around any 
  3886. pigment, normal or finish statements.  Do not use multiple pigment, normal 
  3887. or finish statements without putting them inside the texture statement.
  3888.  
  3889. Layered textures may be declared.  For example:
  3890.  
  3891.       #declare Layered_Examp=
  3892.             texture {T1}
  3893.             texture {T2}
  3894.             texture {T3}
  3895.  
  3896. Then invoke it as follows:
  3897.  
  3898.       object {
  3899.         My_Object
  3900.         texture {
  3901.           Layer_Examp
  3902.           // Any pigment, normal or finish here
  3903.           // modifies the bottom layer only.
  3904.         }
  3905.       }
  3906.  
  3907.  
  3908. 5.4.6 DEFAULT TEXTURE
  3909.  
  3910. POV-Ray creates a default texture when it begins processing.  You may 
  3911. change those defaults as described below.  Every time you specify a 
  3912. "texture{...}" statement, POV-Ray creates a copy of the default texture.  
  3913. Anything items you put in the texture statement override the default 
  3914. settings.  If you attach a pigment, normal or finish to an object without 
  3915. any texture statement then POV-Ray checks to see if a texture has already 
  3916. been attached.  If it has a texture then the pigment, normal or finish will 
  3917. modify that existing texture.  If no texture has yet been attached to the 
  3918. object then the default texture is copied and the pigment, normal or finish 
  3919. will modify that texture.
  3920.  
  3921. You may change the default texture, pigment, normal or finish using the 
  3922. language directive "#default {...}" as follows:
  3923.  
  3924.       #default {
  3925.         texture {
  3926.           pigment {...}
  3927.           normal  {...}
  3928.           finish  {...}
  3929.         }
  3930.       }
  3931.  
  3932. Or you may change just part of it like this:
  3933.  
  3934.       #default {
  3935.          pigment {...}
  3936.       }
  3937.  
  3938. This still changes the pigment of the default texture.  At any time there 
  3939. is only one default texture made from the default pigment, normal and 
  3940. finish.  The example above does not make a separate default for pigments 
  3941. alone.  Note: Special textures tiles and material_map may not be used as 
  3942. defaults.
  3943.  
  3944. You may change the defaults several times throughout a scene as you wish.  
  3945. Subsequent #default statements begin with the defaults that were in effect 
  3946. at the time.  If you wish to reset to the original POV-Ray defaults then 
  3947. you should first save them as follows:
  3948.  
  3949.       //At top of file
  3950.       #declare Original_Default = texture {}
  3951.  
  3952. later after changing defaults you may restore it with...
  3953.  
  3954.       #default {texture {Original_Default}}
  3955.  
  3956. If you do not specify a texture for an object then the default texture is 
  3957. attached when the object appears in the scene.  It is not attached when an 
  3958. object is declared.  For example:
  3959.  
  3960.       #declare My_Object=
  3961.         sphere{<0,0,0>,1}  // Default texture not applied
  3962.  
  3963.       object{My_Object}    // Default texture added here
  3964.  
  3965. You may force a default texture to be added by using an empty texture 
  3966. statement as follows:
  3967.  
  3968.       #declare My_Thing=
  3969.         sphere{<0,0,0>,1 texture{}}  // Default texture applied
  3970.  
  3971. The original POV-Ray defaults for all items are given throughout the 
  3972. documentation under each appropriate section.
  3973.  
  3974.  
  3975. 5.5   CAMERA
  3976. ------------
  3977.  
  3978. Every scene in POV-Ray has a camera defined.  If you do not specify a 
  3979. camera then a default camera is used.  The camera definition describes the 
  3980. position, angle and properties of the camera viewing the scene. POV-Ray 
  3981. uses this definition to do a simulation of the camera in the ray tracing 
  3982. universe and "take a picture" of your scene.
  3983.  
  3984. The camera simulated in POV-Ray is a pinhole camera. Pinhole cameras have a 
  3985. fixed focus so all elements of the scene will always be perfectly in focus. 
  3986. The pinhole camera is not able to do soft focus or depth of field effects.
  3987.  
  3988. A total of 6 vectors may be specified to define the camera but only a few 
  3989. of those are needed to in most cases.  Here is an introduction to simple 
  3990. camera placement.
  3991.  
  3992.  
  3993. 5.5.1 LOCATION AND LOOK_AT
  3994.  
  3995. Under many circumstances just two vectors in the camera statement are all 
  3996. you need: location and look_at.  For example:
  3997.  
  3998.       camera {
  3999.         location <3,5,-10>
  4000.         look_at  <0,2,1>
  4001.       }
  4002.  
  4003. The location is simply the X, Y, Z coordinates of the camera. The camera 
  4004. can be located anywhere in the ray tracing universe.  The default location 
  4005. is <0,0,0>.  The look_at vector tells POV-Ray to pan and tilt the camera 
  4006. until it is looking at the specified X, Y, Z coordinate.  By default the 
  4007. camera looks at a point one unit in the +Z direction from the location. 
  4008.  
  4009. The look_at specification should almost always be the LAST item in the 
  4010. camera statement.  If other camera items are placed after the look_at 
  4011. vector then the camera may not continue to look at the specified point.
  4012.  
  4013.  
  4014. 5.5.2 THE SKY VECTOR
  4015.  
  4016. Normally POV-Ray pans left or right by rotating about the Y axis until it 
  4017. lines up with the look_at point and then tilts straight up or down until 
  4018. the point is met exactly.  However you may want to slant the camera 
  4019. sideways like an airplane making a banked turn.  You may change the tilt of 
  4020. the camera using the "sky" vector.  For example:
  4021.  
  4022.       camera {
  4023.         location <3,5,-10>
  4024.         sky      <1,1,0>
  4025.         look_at  <0,2,1>
  4026.       }
  4027.  
  4028. This tells POV-Ray to roll the camera until the top of the camera is in 
  4029. line with the sky vector.  Imagine that the sky vector is an antenna 
  4030. pointing out of the top of the camera.  Then it uses the "sky" vector as 
  4031. the axis of rotation left or right and then to tilt up or down in line with 
  4032. the "sky" vector.  In effect you're telling POV-Ray to assume that the sky 
  4033. isn't straight up.  Note that the sky vector must appear before the look_at 
  4034. vector.  The sky vector does nothing on its own.  It only modifies the way 
  4035. the look_at vector turns the camera.  The default value for sky is <0,1,0>.
  4036.  
  4037.  
  4038. 5.5.3 THE DIRECTION VECTOR
  4039.  
  4040. The "direction" vector serves two purposes.  It tells POV-Ray the initial 
  4041. direction to point the camera before moving it with look_at or rotate 
  4042. vectors.  It also controls the field of view.  
  4043.  
  4044. Note that this is only the initial direction.  Normally, you will use the 
  4045. look_at keyword, not the direction vector to point the camera in its actual 
  4046. direction. 
  4047.  
  4048. The length of the direction vector tells POV-Ray to use a telephoto or 
  4049. wide-angle view.  It is the distance from the camera location to the 
  4050. imaginary "view window" that you are looking through.  A short direction 
  4051. vector gives a wide angle view while a long direction gives a narrow, 
  4052. telephoto view.  
  4053.  
  4054. This figure illustrates the effect:
  4055.  
  4056.                  |\                                            |\   
  4057.                  | \                                           | \  
  4058.                  |  \                                          |  \ 
  4059.                  |   \                                         |   \
  4060.   Location       |   |            Location                     |   |
  4061.       *------------> |                *--------------------------> |
  4062.         Direction|   |                                         |   |
  4063.                  |   |                                         |   |
  4064.                  |   |                                         |   |
  4065.                   \  |                                          \  |
  4066.                    \ |                                           \ |
  4067.                     \|                                            \|
  4068.  
  4069.  
  4070. Short direction gives wide view...        long direction narrows view.
  4071.  
  4072. The default value is "direction <0,0,1>".
  4073.  
  4074. Be careful with short direction vector lengths like 1.0 and less. You may 
  4075. experience distortion on the edges of your images. Objects will appear to 
  4076. be shaped strangely. If this happens, move the location back and make the 
  4077. direction vector longer.
  4078.  
  4079. Wide angle example:
  4080.       camera {
  4081.         location  <3,5,-10>
  4082.         direction <0,0,1>
  4083.         look_at   <0,2,1>
  4084.       }
  4085.  
  4086. Zoomed in telephoto example:
  4087.       camera {
  4088.         location <3,5,-10>
  4089.         direction <0,0,8>
  4090.         look_at  <0,2,1>
  4091.       }
  4092.  
  4093.  
  4094. 5.5.4 UP AND RIGHT VECTORS
  4095.  
  4096. The "up" vector defines the height of the view window.  The "right" vector 
  4097. defines the width of the view window.  This figure illustrates the 
  4098. relationship of these vectors:
  4099.  
  4100.       --------------------------
  4101.      |             ^            |
  4102.      |   up <0,1,0>|            |
  4103.      |             |            |
  4104.      |             |            |
  4105.      |             |            |
  4106.      |             |            |
  4107.      |             |            |
  4108.      |------------------------->|
  4109.      |   right<1.33,0,0>        |
  4110.      |             |            |
  4111.      |             |            |
  4112.      |             |            |
  4113.      |             |            |
  4114.      |             |            |
  4115.      |             |            |
  4116.       --------------------------
  4117.  
  4118.  
  4119. 5.5.4.1     Aspect Ratio
  4120.  
  4121. Together these vectors define the "aspect ratio" (height to width ratio) of 
  4122. the resulting image.  The default values "up <0,1,0>" and "right 
  4123. <1.33,0,0>" results in an aspect ratio of about 4 to 3.  This is the aspect 
  4124. ratio of a typical computer monitor.  If you wanted a tall skinny image or 
  4125. a short wide panoramic image or a perfectly square image then you should 
  4126. adjust the up and right vectors to the appropriate proportions.
  4127.  
  4128. Most computer video modes and graphics printers use perfectly square 
  4129. pixels.  For example Macintosh displays and IBM S-VGA modes 640x480, 
  4130. 800x600 and 1024x768 all use square pixels.  When your intended viewing 
  4131. method uses square pixels then the width and height you set with the +W and 
  4132. +H switches should also have the same ratio as the right and up vectors.  
  4133. Note that 640/480=4/3 so the ratio is proper for this square pixel mode.
  4134.  
  4135. Not all display modes use square pixels however.  For example IBM VGA mode 
  4136. 320x200 and Amiga 320x400 modes do not use square pixels.  These two modes 
  4137. still produce a 4/3 aspect ratio image.  Therefore images intended to be 
  4138. viewed on such hardware should still use 4/3 ratio on their up & right 
  4139. vectors but the +W and +H settings will not be 4/3.
  4140.  
  4141. For example:
  4142.       camera {
  4143.         location <3,5,-10>
  4144.         up       <0,1,0>
  4145.         right    <1,0,0>
  4146.         look_at  <0,2,1>
  4147.       }
  4148.  
  4149. This specifies a perfectly square image.  On a square pixel display like 
  4150. SVGA you would use +W and +H settings such as +W480 +H480 or +W600 +H600.  
  4151. However on the non-square pixel Amiga 320x400 mode you would want to use 
  4152. values of +W240 +H400 to render a square image.
  4153.  
  4154.  
  4155. 5.5.4.2     Handedness
  4156.  
  4157. The "right" vector also describes the direction to the right of the camera. 
  4158. It tells POV-Ray where the right side of your screen is.  The sign of the 
  4159. right vector also determines the "handedness" of the coordinate system in 
  4160. use. The default right statement is:
  4161.  
  4162.       right <1.33, 0, 0>
  4163.  
  4164. This means that the +X direction is to the right.  It is called a "left-
  4165. handed" system because you can use your left hand to keep track of the 
  4166. axes.  Hold out your left hand with your palm facing to your right.  Stick 
  4167. your thumb up.  Point straight ahead with your index finger. Point your 
  4168. other fingers to the right.  Your bent fingers are pointing to the +X 
  4169. direction.  Your thumb now points +Y.  Your index finger points +Z.
  4170.  
  4171. To use a right-handed coordinate system, as is popular in some CAD programs 
  4172. and other ray tracers, make the same shape using your right hand.  Your 
  4173. thumb still points up in the +Y direction and your index finger still 
  4174. points forward in the +Z direction but your other fingers now say the +X is 
  4175. to the left.  That means that the "right" side of your screen is now in the 
  4176. -X direction. To tell POV-Ray to compensate for this you should use a 
  4177. negative X value in the "right" vector like this:
  4178.  
  4179.       right <-1.33, 0, 0>
  4180.  
  4181. Some CAD systems, like AutoCAD, also have the assumption that the Z axis is 
  4182. the "elevation" and is the "up" direction instead of the Y axis. If this is 
  4183. the case you will want to change your "up" and "direction" as well.  Note 
  4184. that the up, right, and direction vectors must always remain perpendicular 
  4185. to each other or the image will be distorted.
  4186.  
  4187.  
  4188. 5.5.5 TRANSFORMING THE CAMERA
  4189.  
  4190. The "translate" and "rotate" commands can re-position the camera once 
  4191. you've defined it.
  4192.  
  4193. For example:
  4194.       camera {
  4195.         location  < 0,  0,  0>
  4196.         direction < 0,  0,  1>
  4197.         up        < 0,  1,  0>
  4198.         right     < 1,  0,  0>
  4199.         rotate    <30, 60, 30>
  4200.         translate < 5,  3,  4>
  4201.       }                   
  4202.                       
  4203. In this example, the camera is created, then rotated by 30 degrees about 
  4204. the X axis, 60 degrees about the Y axis, and 30 degrees about the Z axis, 
  4205. then translated to another point in space.
  4206.  
  4207.  
  4208. 5.5.6 CAMERA IDENTIFIERS
  4209.  
  4210. You may declare several camera identifiers if you wish.  This makes it easy 
  4211. to quickly change cameras.  For example:
  4212.  
  4213.       #declare Long_Lens=
  4214.             camera {
  4215.               location -z*100
  4216.               direction z*50
  4217.             }
  4218.       #declare Short_Lens=
  4219.             camera {
  4220.               location -z*50
  4221.               direction z*10
  4222.             }
  4223.  
  4224.       camera {
  4225.         Long_Lens    //edit this line to change lenses
  4226.         look_at Here
  4227.       }
  4228.  
  4229.  
  4230. 5.6   MISC FEATURES
  4231. -------------------
  4232.  
  4233. Here are a variety of other topics about POV-Ray features.
  4234.  
  4235.  
  4236. 5.6.1 FOG
  4237.  
  4238. POV-Ray includes the ability to render fog. To add fog to a scene, place 
  4239. the following declaration outside of any object definitions:
  4240.  
  4241.        fog {
  4242.          color Gray70      // the fog color
  4243.          distance 200.0    // distance for 100% fog color
  4244.        }
  4245.  
  4246. The fog color is then blended into the current pixel color at a rate 
  4247. calculated as:
  4248.  
  4249.           1-exp(-depth/distance) =
  4250.           1-exp(-200/200) =
  4251.           1-exp(-1) =
  4252.           1-.37... =
  4253.           0.63...
  4254.  
  4255. So at depth 0, the color is pure (1.0) with no fog (0.0). At the fog 
  4256. distance, you'll get 63% of the color from the object's color and 37% from 
  4257. the fog color. 
  4258.  
  4259. Subtle use of fog can add considerable realism and depth cuing to a scene 
  4260. without adding appreciably to the overall rendering times.  Using a black 
  4261. or very dark gray fog can be used to simulate attenuated lighting by 
  4262. darkening distant objects.
  4263.  
  4264.  
  4265. 5.6.2 MAX_TRACE_LEVEL
  4266.  
  4267. The "#max_trace_level" directive sets a variable that defines how many 
  4268. levels that POV-Ray will trace a ray. This is used when a ray is reflected 
  4269. or is passing through a transparent object. When a ray hits a reflective 
  4270. surface, it spawns another ray to see what that point reflects, that's 
  4271. trace level 1. If it hits another reflective surface, then another ray is 
  4272. spawned and it goes to trace level 2. The maximum level by default is 5. 
  4273.  
  4274. If max trace level is reached before a non-reflecting surface is found, 
  4275. then the color is returned as black. Raise max_trace_level if you see black 
  4276. in a reflective surface where there should be a color.
  4277.  
  4278. The other symptom you could see is with transparent objects. For instance, 
  4279. try making a union of concentric spheres with the Cloud_Sky texture on 
  4280. them. Make ten of them in the union with radius's from 1-10 then render the 
  4281. Scene. The image will show the first few spheres correctly, then black. 
  4282. This is because a new level is used every time you pass through a 
  4283. transparent surface.  Raise max_trace_level to fix this problem.  For 
  4284. example:
  4285.  
  4286.       #max_trace_level 20
  4287.  
  4288. Note: Raising max_trace_level will use more memory and time and it could 
  4289. cause the program to crash with a stack overflow error. Values for 
  4290. max_trace_level are not restricted, so it can be set to any number as long 
  4291. as you have the time and memory. 
  4292.  
  4293.  
  4294. 5.6.3 MAX_INTERSECTIONS
  4295.  
  4296. POV-Ray uses a set of internal stacks to collect ray/object intersection 
  4297. points.  The usual maximum number of entries in these "I-Stacks" is 64.  
  4298. Complex scenes may cause these stacks to overflow.  POV-Ray doesn't stop 
  4299. but it may incorrectly render your scene.  When POV-Ray finishes rendering, 
  4300. a number of statistics are displayed.  If you see "I-Stack Overflows" 
  4301. reported in the statistics, you should increase the stack size.  Add a 
  4302. directive to your scene as follows:
  4303.  
  4304.       #max_intersections 200
  4305.  
  4306. If the "I-Stack Overflows" remain, increase this value until they stop.
  4307.  
  4308.  
  4309. 5.6.4 BACKGROUND
  4310.  
  4311. A background color can be specified if desired.  Any ray that doesn't hit 
  4312. an object will be colored with this color.  The default background is 
  4313. black.  The syntax for background is:
  4314.  
  4315.       background { color SkyBlue }
  4316.  
  4317. Using a colored background takes up no extra time for the ray tracer, 
  4318. making it a very economical, although limited, feature. Only solid colors 
  4319. can be specified for a background. Textures cannot be used.  No shadows 
  4320. will be cast on it, which makes it very useful, but at the same time, it 
  4321. has no "roundness", or shading, and can sometimes cause a scene to look 
  4322. "flat".  Use background with restraint.  It's often better, although a bit 
  4323. slower, to use a "sky sphere", but there are times when a solid background 
  4324. is just what you need.
  4325.  
  4326.  
  4327. 5.6.5 THE #VERSION DIRECTIVE
  4328.  
  4329. Although POV-Ray 2.0 has had significant changes to the language over POV-
  4330. Ray 1.0, almost all 1.0 scenes will still work if the compatibility mode is 
  4331. set to 1.0.  The +MV switch described earlier, sets the initial mode.  The 
  4332. default is +MV2.0.  
  4333.  
  4334. Inside a scene file you may turn compatibility off or on using the 
  4335. "#version" directive.  For example:
  4336.  
  4337.       #version 1.0
  4338.       // Put some version 1.0 statements here
  4339.  
  4340.       #version 2.0
  4341.       // Put some version 2.0 statements here
  4342.  
  4343. Note you may not change versions inside an object or declaration.
  4344.  
  4345. The primary purpose of the switch is to turn off float and expression 
  4346. parsing so that commas are not needed.  It also turns off some warning 
  4347. messages.
  4348.  
  4349. Note some changes in tiles and material_maps cannot be fixed by turning the 
  4350. version compatibility on.  It may require hand editing of those statements.  
  4351. See the special texture section for details.
  4352.  
  4353. Future versions of POV-Ray may not continue to maintain full backward 
  4354. compatibility.  We strongly encourage you to phase in 2.0 syntax as much as 
  4355. possible.
  4356.  
  4357.