Persistence of Vision Raytracer Version 1.0 Quick Reference ------------------------------- By Larry Tweed & Drew Wells This document is designed as a quick reference for those already familiar with the program POV-Ray. You should use POVRAY.DOC to learn about POV-Ray and then use this document as a memory jogger or for quick syntax checks. It is not meant to replace the main documents that accompany POV-Ray. NOTE: This document is not complete or perfectly accurate in all cases. We judged it to be useful even with a few innacuracies and its state of completion. Hopefully, it will be useful to you. If you can't find something here or can't understand what is here, refer to POVRAY.DOC. Some entries have been left blank due to time constraints. A later version of this document will contain text for these entries. For now, refer to POVRAY.DOC. The list is alphabetical, with texture modifiers at the end of the list. --------------------------------------------------------------------------- bezier/bicubic patches ---------------------- Syntax: Description: blob ---- Syntax: blob { threshold # component (strength_val) (radius_val) component (strength_val) (radius_val) [ any number of components ] [sturm] } Description: A blobby shape. Components radii should overlap. bounded_by ---------- Syntax: object { ... bounded_by { shape {...} } } Description: A bounding shape helps speed rendering time in many cases. The bounding shape is first tested by the raytracer. If the ray does not strike the bounding shape, the raytracer does not need to test or calculate any of the bounded objects. box --- Syntax: box { } Description: A box shape is defined by specifying 2 corners. The first corner ( in the example above) must be smaller than the second corner. camera ------ Syntax: camera { location <0 0 0> direction <0 0 1> up <0 1 0> right <1.33 0 0> look_at<0 0 0> sky <0 1 0> } Description: The camera defines the orientation and location in space of the viewer. The values shown above are the default values. If these items are not specified, the defaults will be used. clipped_by ---------- Syntax: object { ... clipped_by { object {...} } } Description: clipped_by will "cut off" any part of the object that is outside the clipping shape. This should not be confused with bounded_by. composite --------- Syntax: composite { object1 {...} object2 {...} } Description: composite will "glue together" 2 or more objects. Essentially, the objects can then be considered as single unit. difference ---------- Syntax: object { difference { shape1 {...} shape2 {...} // This will be "cut out" of shape1 shape3 {...} // This will be "cut out" of shape1 shape4 {...} // This will be "cut out" of shape1 (...) } } Description: A difference is a CSG shape. All points in shape1 that are not in shape2 will be included in the final shape. A difference essentially subtracts the shapes following shape1 from shape1. Any number of shapes may be used. direction --------- Syntax: direction <# # #> Description: The direction vector is used in the camera block and specifies the direction the camera is pointing with a vector. Normally, this vector points straight ahead (<0 0 1>) and look_at is used to point the camera. The direction vector should be used to set the "length" of the camera lens. Small values are similar to a wide-angle lens, large values are like a tele-photo lens. height_field ------------ Syntax: height_field { gif "file.gif" water_level # } Description: A height field is a rectangular mesh of triangles where the height of a triangle at a certain X,Z point is controlled by the number in a file at that same index. GIF, TGA and POT files may be used as height fields. The water_level is the height below which the untransformed height field is cut off. The untransformed height field is similar in size to: box { <0 0 0> <1 1 1> } intersection ------------ Syntax: object { intersection { shape1 {...} shape2 {...} } } Description: An intersection is a CSG shape composed of 2 or more shapes. All points that are contained in all the included shapes are included in the final shape. In essence, an intersection is the space where all the shapes meet. inverse ------- Syntax: object { csg_shape_type { shape1 {...} shape2 {... inverse } } } Description: Inverse only has effect when using CSG. When inverse is put into the definition of a shape, it turns the shape "inside-out". Essentially, every point that was "inside" the shape is now "outside" and vice versa. light_source ------------ Syntax: light_source { color red # green # blue #} Description: To shed a little light on a scene, you must provide a light_source. The center of the light is at the vector x, y and z. The red, green, and blue color values define the color of the light which is cast. The light_source itself is invisible. A light source is treated as a shape even though it cannot be seen. It may be used in CSG. look_at ------- Syntax: camera { ... look_at } Description: look_at defines the point in space at which the camera is pointing, or focused on as defined by the x, y and z parameters. no_shadow --------- Syntax: object { ... no_shadow } Description: no_shadow causes an object to be transparent to all light sources. The object will not cast a shadow. This feature is especially useful for enclosing a light source to give the illusion that the light source is actually visible with a shape. object ------ Syntax: object { shape_type { ... } texture { ... } } Description: objects are the basic building blocks. An object defines a shape and associated textures. Objects may not be used in CSG, but they may be used in composite objects. plane ----- Syntax: plane { d } Description: A plane is a flat surface which is infinite in all directions. The surface normal (or orientation) of the plane is determined by the x, y and z arguments. The d parameter specifies the distance of the plane from the origin in the direction of the surface normal. plane { <0 1 0> 0 } // XZ plane, a floor plane { <0 0 1> 10 }// XY plane, a wall Quadric ------- Syntax: Description: Quartic ------- Syntax: Description: right ----- Syntax: right Description: Used in the camera description, it specifies which direction in the ray tracing universe is the right hand side of the image being generated. Usually, right <1.33 0 0>. rotate ------ Syntax: object { ... rotate } shape { ... rotate } texture{ ... rotate } Description: rotate will move any element about the origin in x, y and z degrees. It is important to note that if the object is not centered at the origin, it will "orbit" the origin rather than its current center. scale ----- Syntax: object { ... scale } shape { ... scale } texture{ ... scale } Description: scale will enlarge or reduce the size of any element. If the values for x, y or z are greater than 1.0, the object is enlarged. If the values are between 0.0 and 1.0, the object is shrunk. Scale may also be use on textures. NOTE: Scaling by zero will cause an error. sky --- Syntax: camera { ... sky } Description: sky describes the orientation of the sky, which is not necessarily the same as the UP direction. If sky is defined, it must be defined before the look_at parameter. sphere ------ Syntax: sphere { r } Description: A sphere is a perfectly round shape. Its location in space is defined by the x, y, and z arguments. The radius is determined by the r argument. The width of a sphere will be 2 x r. It cannot be scaled unevenly. spotlight --------- Syntax: light_source { // center of light source color red # green # blue # spotlight point_at radius # falloff # tightness # } Description: A spotlight light_source emulates the behavior of a real spotlight, projecting a cone of light. point_at specifies the point in space that the light is aimed at. radius is the radius in degrees of the circular "hotspot" at the center of the spotlight's area of effect. falloff is the radius in degrees that defines the area where the brightness falls off to zero. Both values may range between 1 and 180. Tightness controls how fast the brightness falls off at the edges. Low values cause softer edges, high values create sharper edges. texture ------- Syntax: object { ... texture { (texture modifiers) } } shape { ... texture {...} } Description: The texture keyword begins a block which describes the appearance of an object, but not the size. See the section on texture modifiers for a list of available modifiers and their defaults. A texture may be used inside a shape or object, but not in a composite object. translate --------- Syntax: object { ... translate } shape { ... translate } texture{ ... translate } Description: translate moves the element in space by the number of units specified by the x, y and z parameters. Translate is relative to the element's current location. If the element is at <3 4 5> and is translated by <1 -1 1>, the element is moved to <4 3 6>. Normally, translate is used after scale because the scale will "scale" the translate. triangle -------- Syntax: triangle { } Description: A triangle is specified by the coordinates of the 3 vertices. Triangles have no inside or outside, so cannot be used correctly in CSG shapes. union ----- Syntax: object { union { shape1 {...} shape2 {...} } } Description: Union is a CSG shape. A union essentially superimposes two or more shapes to create a single object. All points in the shapes included in a union are included in the final object. up -- Syntax: camera { ... up } Description: The up parameter describes the surface normal of the "up" direction. up <0 1 0>, for example would have a "up" direction in the positive y direction. -------------------------------------------------------------------------- Texture Modifiers -------------------------------------------------------------------------- agate ----- Syntax: agate color_map {...} Description: agate is a pattern similar to marble. It is always turbulent and ignores the turbulence keyword. agate is used within a texture block. alpha ----- Syntax: color red # green # blue # alpha # Description: The alpha property of a color determines how transparent the color is. Values range from 0.0 (opaque) to 1.0 (totally transparent). Transparency is a filter. Black is always opaque. The color red with alpha 1 will only allow red light through, and so on. ambient ------- Syntax: texture { ... ambient # } Description: ambient determines the amount of light an object receives even if it is in complete shadow. This emulates the light that is just "bouncing around" the room. The default value for ambient is 0.1. Values range from 0.0 to 1.0. bozo ---- Syntax: bozo color_map {...} Description: A splotchy color pattern. Turbulence works on it. It's often used to create clouds. brilliance ---------- Syntax: texture { ... brilliance # } Description: brilliance controls the tightness of diffuse illumination on an object and adjusts the appearance of surface shininess. Values from 3.0 to 10.0 can give a shiny or metallic appearance. The default value is 1.0. There is no limit on the brilliance value. bump_map -------- Syntax: bump_map { file_type "filename" map_type # interpolate # bump_size # (use_color) (use_index) } Ex: bump_map { gif "rough.gif" map_type 1 interpolate 2 bump_size 3 } Description: Use a graphic image to simulate bumps on a shape. bumps ----- Syntax: texture { bumps # } Description: bumps gives the surface of an object a bumpy appearance. Values for bumps range from 0.0 (no bumps) to 1.0 (very bumpy). checker ------- Syntax: checker color red # green # blue # color red # green # blue # Description: the checker pattern gives an object a checkerboad appearance. Two colors must be specified after the checker keyword. These are the colors that will alternate in the checker pattern. The checker option is used within the texture block and works best on planes. color ----- Syntax: color red # green # blue # alpha # Description: colors are specified using the red, green, blue and (optionally) alpha components. The values for each component range form 0.0 to 1.0. If a component is not specified, it is assumed to be 0 (none of that component color). Alpha specifies the transparency of the color. color_map --------- Syntax: color_map { [start_value end_value color1 color2] [start_value end_value color1 color2] ... } Description: A color_map provides a palette for color patterns. A point on the surface is located and it is determined which start_value end_value pair the points falls within. The color is then determined by smoothly blending the colors associated with the start_value end_value pair. Values for start_value and end_value range from 0.0 to 1.0. Example: color_map { [0 .25 color red 1 color red 1] [.25 .5 color red 1 color green 1] [.5 .75 color green 1 color blue 1] [.75 .76 color Yellow color Orange] [.76 1 color Black color blue 1] } default texture --------------- Description: When a texture is first created, POV-Ray initializes it with default values for all options. The default values are: color red 0 green 0 blue 0 alpha 0 ambient .1 diffuse .6 phong 0 phong_size 40 specular 0 roughness .05 brilliance 1 metallic FALSE reflection 0 refraction 0 ior 1 turbulence 0 octaves 6 texture randomness (dither) 0 phase 0 frequency 1 color map NONE #default --------- Syntax: #default { texture { (modifications to default texture) } Description: The default textures can be modified by using the #default option. Any textures created after this option has been used will use the new defaults as specified in #default. All other defaults not specified will remain the unchanged. dents ----- Syntax: texture { ... dents # } Description: dents will give the object the appearance of being dented. Values for dents range between 0.0 (no dents) and 1.0 (the dentiest) that determines how dented the surface should be. diffuse ------- Syntax: texture { ... diffuse # } Description: The diffuse value specifies how the colors in a texture react to light directly shining on it. Higher values make the colors very bright, lower values make the colors more subdued. Values for diffuse range from 0.0 to 1.0. The default value is 0.6. fog --- Syntax: fog { color red # green # blue # distance_val } Description: Simulate a uniform haze over the entire scene. Fog should be described outside of all other descriptions. Ie. don't put it inside a texture, object, camera, or shape block. Example: fog { color red 1 green 1 blue 1 200.0 } gradient -------- Syntax: gradient color_map {...} Description: granite ------- Syntax: granite color_map {...} Description: This will create a granite pattern based on the supplied color_map. granite will respond to the turbulence keyword, but the default is no turbulence. granite is typically used with small scaling values (2.0 to 5.0). image_map --------- Syntax: image_map { file_type "filename" alpha (index # or all) # map_type # interpolate # (once) } Description: Place a graphic image on a shape as surface coloring. interpolate ------------- Syntax: image_map { gif "file.gif" interpolate # } interpolate 1 // Norm dist interpolation interpolate 2 // Bilinear interpolation (best) Description: Smooths the jaggies on image_maps and bump_maps. ior --- Syntax: texture { ... refraction 1 ior # } Description: The ior is the Index of Refraction. This value determines how far light will bend as it passes through a texture. To be effective, refraction should be set to 1 and the texture must have some transparent colors that use alpha. A value of 1.0 will not bend the light. Some typical ior values are 1.0 for air, 1.33 for water, 1.5 for glass and 2.4 for diamond. leopard ------- Syntax: leopard color_map {...} Description: Uniform spotted color pattern. Turbulence works. map_type -------- Syntax: map_type # Description: Changes the mapping type used with image_map, bump_map, and material map. 0 = Planar 1 = Spherical 2 = Cylindrical 3 = Toroidal (donut) marble ------ Syntax: marble color_map {...} Description: marble creates parallel bands of colors based on the color_map. Adding turbulence will give the appearance of true marble or other types of stones. The default is no turbulence. material_map ------------ Syntax: material_map { file_type "filename" map_type # [once] texture {...} texture {...} (...) } Description: Changes the texture on a surface based on the colors in the mapped image. max_trace_level --------------- Syntax: max_trace_level # Description: This option will set the number of levels that a ray will be traced. If a ray is reflected or refracted, it creates another ray. This is 1 level. The default value is 5. metallic -------- Syntax: texture { ... metallic } Description: This keyword specifies that the color of specular and phong highlights will be the surface color rather than the color of the light source. This creates a metallic appearance. octaves ------- Syntax: octaves # Description: Affects turbulence. Default value is 6. Values range from 1 to 16. onion ----- Syntax: onion color_map {...} Description: onion creates a pattern of concentric circles based on the supplied color_map. By default, onion has no turbulence. phong ----- Syntax: texture { ... phong # } Description: The phong keyword causes a bright shiny spot on the object that is the same color as the light source. Values for phong range from 0.0 (none) to 1.0 (very bright at the center of the highlight). There is no phong highlighting by default. phong_size ---------- Syntax: texture { ... phong_size # phong # } Description: The value for phong_size determines the size of the phong highlight of the object. The larger the value, the smaller (tighter) the highlight. The smaller the value, the larger (looser) the highlight. Values range from 1.0 (very dull) to 250 (highly polished). The default phong_size is 40. reflection ---------- Syntax: texture { ... reflection # } Description: The value of reflection determines how much of the light coming from an object is reflected from other objects in the scene. Values range from 0.0 (no reflection) to 1.0 (a perfect mirror). refraction ---------- Syntax: texture { ... refraction # } Description: The value for refraction will affect how light passing through transparent textures is treated. Values range from 0 to 1. Lower values will make the transparent portions less transparent. This value will usually be set to 1 with the transparancy amounts controlled by alpha. By default, there is no refraction. ripples ------- Syntax: texture { ... ripples # } Description: Simulates ripples on a shape's surface. roughness --------- Syntax: texture { ... roughness # } Description: The roughness value for a surface determines the size of the specular highlight of that object. Typical values range from 1.0 (Very Rough, large highlight) to 0.0005 (Very Smooth, small highlight). The default, if no roughness is specified, is 0.05. specular -------- Syntax: texture { ... specular # } Description: A specular highlight is similar to a phong highlight, but provides a more credible spreading of the highlights near the object horizons. Values for specular range from 0.0 (no highlighting) to 1.0 (bright highlighting). The size of the highlight is determined by the roughness value. spotted ------- Syntax: Description: tiles ----- Syntax: texture { tiles { texture {...} tile2 texture {...} } } Description: tiles gives an effect similar to checker, but with textures rather than just colors. The textures for tile1 and tile2 may also be layered, but only the first layer will be seen. turbulence ---------- Syntax: texture { ... turbulence # } Description: turbulence will distort a pattern so that it is not so "perfect". Typcical values for turbulence range between 0.0 and 1.0, but any value can be used. waves ----- Syntax: waves # Description: Simulates bumpy waves on a shape's surface. wood ---- Syntax: wood color_map {...} Description: wood used the supplied color map to create concentric cylindrical bands of color centered on the Z axis. Small amounts of turbulence will make the texture look more like real wood. There is no turbulence by default. wrinkles -------- Syntax: texture { ... wrinkles # } Description: wrinkles is a bump pattern that will give the appearance of a wrinkled surface. Values for wrinkles range from 0.0 (no wrinkles to 1.0 (very wrinkled)