Povray Help

This page is intended to help with the SDG Povray Framework.

There is a separate page for help with the Image Repository search engine.

Povray (or Persistence of Vision Raytracer) is a tool for generating 3D images. This is typically done by creating a text file that contains code written in a specialized programming language that describes the scene. The Povray utility then parses and draws the scene. Povray and its full documentation can be found at http://povray.org. This page is designed to help you understand the very narrow subset of Povray necessary to create Icehouse Zendo koans.

The Povray documentation is lengthy and can be very daunting. The parts salient to this discussion can be found at:

• Coordinate System
• Moving Objects Around

There is lots more that you can accomplish with Povray, but these two pages are sufficient for our needs.

SDG provides everything you need to generate koan images. You do not need to download anything. In fact, SDG also provides a host of predefined constants and scene elements to make things as simple as possible. All you have to worry about are the Pyramid objects themselves. The SDG parser uses the following include files, faithfully created and maintained by Ryan McGuire and Kerry Breitenbach.

• Pyramids.inc - This file describes the pyramids themselves and provides all sorts of useful constants and macros. This is the heart of it all!
• koan.pov - This file contains the default scene information such as background, lighting, and camera location. (The actual file used by SDG is slightly altered from this master copy.)

The best way to get started is to have a look at the Koan Image Repository and examine the code used to generate the various koans. Let's go through some simple examples though.

#include "koan.pov"
object { 
  LargeOrangePyramid
}

• The #include line is added automatically for you. Koan.pov imports all the Pyramids.inc constants and default lighting and camera settings. If you're feeling really adventurous, you can override these settings by adding the appropriate camera and other commands after this line.

• object {…} is what defines each individual object in the scene. You will need one object command for each pyramid in the koan.
  • In this case, all that is included in the object command is the constant LargeOrangePyramid, which places the pyramid in the very centre of the scene.

#include "koan.pov"
object { 
  LargeOrangeFlatPyramid
}

• The only difference here is the name of the constant to include the word Flat. This properly moves and rotates the pyramid so it is lying flat against the playing surface with its point at the origin. A small change will center the pyramid in the scene.

#include "koan.pov"
object { 
  LargeOrangeFlatPyramid
  translate <-(LargeHeight/2), 0, 0>
}

include "koan.pov"
object {
  MediumCyanPyramid
}
object {
  SmallCyanPyramid
  translate <0, SmallOnMedium, 0>
}

• The translate command takes a matrix of x, y, z distances and moves the object accordingly. In this case, the Small pyramid (which would normally be drawn at the origin) is moved up a set distance, defined by the SmallOnMedium constant. Constants are defined for all possiblities, including SmallOnLarge, MediumOnLarge, and LargeOnLarge.

• There is also a macro for making stacks weird. In the following code, note the parenthesis ()!! They are required!

#include "koan.pov"
object {
  MediumCyanPyramid
}
object {
  SmallCyanPyramid
  SmallWeirdHatOnMedium()
}

The last thing to demonstrate is the union {…} command. This keyword surrounds a group of objects and then allows you to treat them as a single unit. I will demonstrate its use by generating a Fallen Tower.

#include "koan.pov"
#declare TowerHeight = LargeHeight+(PyrStackDelta*2);
 
union {
  object {
    LargeClearPyramid
  }
  object {
    MediumRedPyramid
    translate (MediumOnLarge)*y
  }
  object {
    SmallBlackPyramid
    translate (MediumOnLarge+SmallOnMedium)*y
  }
  translate <0,-TowerHeight,0>
  rotate <0,0,90+LargeAngle>
  translate <-TowerHeight/2,0,0>
}

• To make things simpler, I started by #declare-ing a variable called TowerHeight which of course represents the height of all three stacked pyramids. (Don't forget the trailing semicolon!)
• After I declared all my objects as normal, but before the closing } of the union command, I insert a number of commands that will now affect the entire tower.
  • The first translate command drops the entire tower straight down, just below the playing surface.
  • The rotate command brings the tower back in view, flat against the playing surface.
  • The final translate centers the tower in the image.
• You can also animate koans by simply checking the Animate? checkbox! Animation takes significantly longer than normal image generation, so please do not animate koans that don't need it.

If the default view angle isn't right, you can aim the camera manually. The camera responds to translate, rotate, and location just as the pyramids do, but it has an additional look_at parameter as well. The default camera settings are in koan.pov, but you can override them in your own code. (Of course, you can't move the camera if you want to animate the koan, too.)

If you turn the camera so that it's looking out past your koan into “empty space”, you won't even have a background there to look at, just blackness. You can add a background with a plane object. Here's an example of an alternate camera arrangement that hides the infinite blackness behind some extra background planes.

camera {
        location <3.6, 3, 3>
        look_at <-2, 1, 0>
}
 
plane {-z, 10 texture {pigment {checker White squarecolor}}}
plane {-x, 10 texture {pigment {checker squarecolor White}}}
plane {x, 10 texture {pigment {checker White squarecolor}}}

If you wish to hide the infinite blackness in your koan image, add those three planes.

The forums are the best place to ask for help with the Povray system. Simply visit the Koan Requests forum. As always, you can also email me directly if you have any questions or concerns. Enjoy!