First of all, povscript does not create an entire input file for POVRay.
 Rather it makes a model that can be used in a POVRay scene.  The part of
 the model centered on your postscript page in molscript is created
 centered at the origin of the POVRay world.  All models get created at a
 scale where one angstrom in your molecule corresponds to one unit in
 POVRay.

 You can use whatever naming convention you like, but I like the
 following for all my files.  I use a ".inp" suffix with my molscript
 input files, a ".povinc" suffix with the output of povscript, and ".pov"
 with my POVRay scenes (which include the ".povinc" model) which are
 ready for rendering.  I've set up all the sample input files that we
 distribute with povray in this way.

 So, a typical session might have you do the following:

         molscript -in test.inp -povray -out test.povinc
         povray +D +Itest.pov

 I'll talk about running povray later, but first I'll tell you more
 about POVRay scenes.
        
 Almost every picture you would ever want to make in POVRay has to have a
 few items in it.  These include:

 1) A description of a camera in your 3D world.  This includes where it
 is located, where it is looking, how wide of a field of view should it
 have.  and so on.

 2) At least one light source.  (Otherwise your picture comes out very
 dark.)

 3) You may want the background set to some other color than the default,
 black.

 4) Finally, you need to place all the items in your 3D world that make
 up the picture.

 Here is a sample input file (like the test.pov file called above) that
 you might make.

 =========================================================================
 #include "colors.inc"
 #include "glass.inc"
 #include "metals.inc"
 #include "textures.inc"

 // orthographic image
 #declare orth = 1;
 // distance to focal plane (i.e. camera location/look_at setting)
 #declare dist = 20;
 // set to 1 for stereo (then run with: +KFF2 +KI-1.0 +KF1.0)
 #declare stereo = 0;
 // eye sep. of 1/20 the focal length (30 may be "easier" on the eyes)
 #declare eyesep = 20;

 camera {
        #if (orth)
	  orthographic
	#end

	#if (stereo)
          location < (clock*dist)/(eyesep*2.0), 0, dist>
	  #debug concat("offset:",str((clock*dist)/(eyesep*2.0), 4, 1),"\n")
	#else
	  location < 0, 0, dist >
	  #debug "offset: 0 (no stereo)\n"
	#end

	direction < 0, 0, -1 >

	#if (orth)
          up < 0, dist, 0 >
          right < dist, 0, 0 >
	#else
          up < 0, 1, 0 >
          right < 1, 0, 0 >
	#end

        translate < 0, 0, 0 >
        rotate < 0, 0, 0 >

	#if (stereo)
          look_at < (clock*dist)/(eyesep*2.0), 0, 0 >
	#else
	  look_at <0, 0, 0>
	#end
 }

 light_source { <10, 10, 50>, color rgb .6 }
 light_source { <10, 10, 50>, color rgb .6 shadowless }

 background { color rgb < 1.00, 1.00, 1.00> }

 #default { texture { finish { specular 0.5 roughness 0.02 } } }

 #declare NoHeaders = 1;

 #ifndef (RFont)
 #declare RFont="cyrvetic.ttf"
 #declare FontWidth=0.2;
 #end

 #ifndef (TEST_10)
 #declare TEST_10 = material { texture { NBglass } }
 #end

 #declare mol=union {
	 #include "test.povinc"
 }

 object { mol }

 =========================================================================

 I think a lot of this is pretty straightforward.  But I'll give you some
 hints as to what you might need to change.

 First of, comment your input files well!  Any text to the right of a

         //

 is a comment ignored by POVRay.

 First off in the input file, the following includes:

	 #include "glass.inc"
	 #include "metals.inc"
	 #include "textures.inc"

 are pretty neat - they allow you to just call any one of the
 predefined textures that come with povray.  There is an example of
 this below.

 Next are some settings that help make rendering various types of
 images easier.  These are:

 #declare orth = 1;

 The first setting has to do with orthographic projections.  Leave
 this to 1 for most stuff.  This will result in an orthographic
 projection (which can sometimes be useful to avoid perspective
 "warping") - but in this case, the up and right vectors are used to
 determine the image size. (the if/else nonsense in the camera setting
 takes care of this for you, however.)

 #declare dist = 20;

 This second setting is the distance to the image, which you'll
 probably have to play around with a bit to get right.  (A good
 starting value is the "window" setting from POVScript+).  It
 basically changes the "zoom" of the image.

 If you want to generate stereopairs, use the following two settings:

 #declare stereo = 0;
 #declare eyesep = 20;

 change the stereo value to 1 (i.e. true) so that the camera settings
 will be changed appropriately.  You may also want to set "orth = 0;",
 so a perspective is imposed on the image (so the depth is easier to
 see) As this also requires two images to be generated, I hacked up a
 macro that does both for you - you just need to run povray with the
 following switches:

   +KFF2 +KI-1.0 +KF1.0

 so 2 images (KFF) will be made, the first with the clock setting at
 -1.0 (KI) and the second with a clock of +1.0 (KF).  Therefore, the
 first image output is the left eye image, and the second is the right
 eye.  (for more information about *correct* stereo pair image
 generation, see
 http://astronomy.swin.edu.au/~pbourke/povray/raystereo).


 Going on, the

         direction < 0, 0, -1 >

 set of statements is actually one of the harder concepts in POVRay.
 POVRay by default works in a left handed coordinate system.  This is
 done so by making right a positive vector along x, up a positive
 vector along y, and the z direction, therefore, points *into* the
 screen.  To switch this, you could make the right vector negative in
 x and set the camera location positive - thats just too tricky and
 confusing.  Instead, I just set the camera direction vector to -1 in
 z - therefore, *any and all* rotations, translations, etc. we make to
 the camera position are multiplied by -1 in z.  Consequently, z now
 points *out* of the screen, towards the viewer.  Simple and easy to
 keep track of.

 The following statements:

         translate < 0, 0, 0 >
         rotate < 0, 0, 0 >

 Further modify the camera position.  You'll probably want to change
 them if you're trying to animate object(s).

 One other thing - the right vector can be a ratio (e.g. 3/2*x), which
 then describes the aspect ratio for the entire scene, independent of
 the number of pixels you use.  if you want your circles to be
 perfectly round, then set this ratio to be the ratio of the
 dimensions of your image.  For example, to make a 600x400 pixel
 image, set this to 3/2*x.  For a 200x800 pixel image, set it to
 1/4*x.  Take any of the sample images and play with the "right"
 parameter to see what happens.

 You may have noticed that I create two light sources at the same
 location in the POVRay scene.  If you used only the first light source,
 areas in shadow would come out completely dark, which is a bit
 unrealistic.  So I always put a second light source which casts no
 shadows to light up these darkened areas a bit.

 Models made by povscript have a default font and fontdepth used for any
 labels.  If it isn't defined, the following statement will set them:

	 #ifndef (RFont)
	 #declare RFont="cyrvetic.ttf"
	 #declare FontWidth=0.2
	 #end

 POVRay comes with a few installed fonts:

         timrom.ttf for Times Roman
         cyrvetic.ttf for Helvetica
         crystal.ttf for Courier

 In theory, you can use any True-Type Font (.ttf) in POVRay's library
 search path.  There are a bunch that come with the macintosh and windows
 95 operating system.  For example, "symbol.ttf" is needed if you want
 greek characters in your labels.  Unfortunately, this is a trademarked
 font so we can't distribute it.  Go find a mac or PC and put symbol.ttf
 in the include directory of your povray source tree if you need Greek
 labels.

 Note: PC .ttf fonts are all set for the UNIX version of x-povray.  Mac
 .ttf files come with macinstosh resource forks which causes POVRay to
 break.  If you want to use a mac .ttf font in POVRay, you need to strip
 out the resources with a program called "TTConverter."  It's available
 from the Info-Mac Archive.  You can get it from:

         http://hyperarchive.lcs.mit.edu/cgi-bin/NewSearch?key=TTConverter

 Every object in your scene has to define characteristics of it's
 surface.  POVRay breaks this up into three sections:

         pigment - the color or pattern of the surface.
         finish - how bright is the surface, how shiny, how reflective?
         normal - do you want the surface to look bumpy?  dented?  rippled?

 By setting a

         #default { texture { finish { specular 0.5 roughness 0.02 } } }

 this makes every object that follows in the scene WHICH DON'T HAVE THEIR
 OWN DEFINED FINISH (models made by povscript do not, for example) to
 have a specular shine.  This is, for example, the bright white shine
 which appears on the face of a watch on a sunny day.  The variable
 "specular" changes how bright the shine will be.  "roughness" changes
 how spread-out the shine comes out.  The lower the roughness, the
 smaller and more glass-like the shine.  The higher the roughness, the
 more plastic a highlight.  Sometimes you may want to get rid of this
 shine.  That's why we mention it here so you know how to do this.

 The line

 #ifndef (TEST_10)
 #declare TEST_10 = material { texture { NBglass } }
 #end

 demonstrate a redefinition of material TEST_10 (which can be found in the
 .povinc file).  The reason for doing so can be one of many: molscript
 doesn't allow the definition of anything besides colors.  Therefore, upon
 defining the color of say, a metal as rgb 0.1 0.2 0.3, we can now make it
 appear as a shiny glass object, just so long as we've matched the color
 definition (TEST_10 - which should be 0.1 0.2 0.3 in this case) from the
 .povinc file.  See the glass.inc (or glass_old.inc in the case of POVRay
 3.5) for a full definition of the texture, or any of the .inc files from
 the first few input file lines for a slew of additional possibilities.
 This sort of thing is also useful if you'd like to redefine the texture
 of a single object - as mentioned, we defined a default texture, but what
 if we only want to change the texture for a single object in the scene?
 Just redefine that texture, as shown above.  Note that povscript+ version
 2.03 allows the redefinition of *materials* as well as textures - this is
 important if you'd like to define an additional interior declaration,
 like:

 #ifndef (TEST_10)
 #declare TEST_10 = material { texture { Aluminum } interior { Water_Int } }
 #end

 which would produce a shiny aluminum finish with an interior index of
 refraction similar to that of water (1.33).

 Finally, in the sample input we declare an object called "molecule"
 which is made up of a model that povscript made.

         #declare mol=union {
           #include "test.povinc"
         }

 This does not actually place a "molecule" into our scene.  This gets
 done later with the command:

         object { mol }

 One last thing - several people have asked how to animate a scene
 using povray.  This too is relatively easy - simply define the motion
 you'd like as a function of the clock variable (see the povray
 documention) in the camera setting - for example:

	     rotate <0, 360*clock, 0>

 will rotate the scene by some amount (multiplied by 360) in y.  The
 possible settings for the clock variable are described below.

 Once you are ready to render a scene, there are a few command-line
 options to x-povray that you should know about.  For example, the
 command to make a test render might be:

         povray +D +Itest +W300 +H300 +SP4

 or, if you want an animation, you might want:

	 povray +KFI0 +KFF10 +KI0.0 +KF1.0 +Itest +W300 +H300

 The options I've used are:

         +D - Display while rendering.
         +I - The name of the input file.  By default, povray looks
                 for a file with a ".pov" suffix, and writes out a
                 png format image with a ".png" suffix.  (test.pov
                 renders test.png)
         +W300 - Render 300 pixels wide
         +H300 - Render 300 pixels high
         +SP4 - "Starting preview"
                 This is pretty cool, actually.  For the first pass,
                 calculate every fourth pixel.  For a second pass,
                 calculate every second pixel.  In a final pass,
                 calculate every pixel.  Yes, it takes twice as long
                 for the entire job, but it allows you to quickly see
                 the entire scene.
	 +KFIn - initial frame of animation - default is 1.
	 +KFFn - final frame of animation - if you want a 360 degree
	         rotation about an axis, I've found 25 images is
		 usually plenty.
	 +KIn.n - initial clock setting for animation
	 +KFn.n - final clock setting - I usually use 1.0, then I can
	          define a multiplicative factor to reach the desired result
		  (e.g. for a 360 degree rotation, use 360*clock).

 Once I get everything looking good, I might type

         povray +Itest +W800 +H800 +A +V &

 with the animation options included, if thats what I'm shooting for.

 The only added options are

         +A - Antialias mode.  (Takes longer, but gets rid of jagged edges)
         +V - Verbose mode.  (Gives more info during render)

 Oh, one more useful option is:

         +C - which tells povray to attempt to continue an unfinished render.
                 (in case a long job died before it was finished)

 If you're stuck trying to figure out what to do with the 30 images
 you just made from an animation, check out ImageMagick.  Its easy to
 do something like:

	 convert -loop 0 -delay 20 test*.png final.gif

 in order to make a final, animated gif.  Watch out - the image can be
 huge (it can be further compressed by something like GIMP), so be
 sure not to go too overboard.

 This just scratches the surface of what POVRay can do, check out

	 http://www.povray.org

 for the real documentation.  Its easy to take the fundamentals here
 and generate texture maps, patterns, reflective surfaces, planes
 (imagine your molecule sitting on a wooden table), bitmapped
 backgrounds, etc...

 Ok.  That's it!  Go play, and good luck!  If you make any images that
 you are proud of and would like to share with the rest of the world,
 send me a copy and I'll put it on the povscript web page.

 -originally written by Dan Peisach
 -modified by Tim Fenn (7/23/02 - POVRay 3.5 updates)
 -modified by Tim Fenn (6/16/03 - New script to automate stereographics)
 fenn@stanford.edu