### Appendix F.2
Scene Debugging Tips

To see a quick version of your picture, render it very small. With fewer pixels to calculate the ray-tracer can finish more quickly. -W160 -H100 is a good size.

Use the +Q quality switch when appropriate.

If there is a particular area of your picture that you need to see in high resolution, perhaps with anti-aliasing on (perhaps a fine-grained wood texture), use the +SC, +EC, +SR and +ER switches to isolate a window.

If your image contains a lot of inter-reflections, set max_trace_level to a low value such as 1 or 2. Don't forget to put it back up when you're finished!

Turn off any unnecessary lights. Comment out extended light keywords when not needed for debugging. Again, don't forget to put them back in before you retire for the night with a final render running!

If you've run into an error that is eluding you by visual examination it's time to start bracketing your file. Use the block comment characters /* ... */ to disable most of your scene and try to render again. If you no longer get an error the problem naturally lies somewhere within the disabled area. Slow and methodical testing like this will eventually get you to a point where you will either be able to spot the bug, or go quietly insane. Maybe both.

If you seem to have lost yourself or an object (a common experience for beginners) there are a few tricks that can sometimes help:

1) | Move your camera way back to provide a long range view. This may not help with very small objects which tend to be less visible at a distance, but it's a nice trick to keep up your sleeve.
2) | Try setting the ambient value to 1.0 if you suspect that the object may simply be hidden from the lights. This will make it self-illuminated and you'll be able to see it even with no lights in the scene.
3) | Replace the object with a larger, more obvious "stand-in" object like a large sphere or box. Be sure that all the same transformations are applied to this new shape so that it ends up in the same spot.

### Appendix F.3
Animation Tips

When animating objects with solid textures, the textures must move with the object, i. e. apply the same rotate or translate functions to the texture as to the object itself. This is now done automatically if the transformations are placed after the texture block like the following example

      shape { ...
        pigment { ... }
        scale < ... >
      }

will scale the shape and pigment texture by the same amount.

      shape { ...
        scale < ... >
        pigment { ... }
      }

will scale the shape but not the pigment.

Constants can be declared for most of the data types in the program including floats and vectors. By writing these to include files you can easily separate the parameters for an animation into a separate file.

Some examples of declared constants would be:

       #declare Y_Rotation = 5.0 * clock
       #declare ObjectRotation = <0, Y_Rotation, 0>
       #declare MySphere = sphere { <0, 0, 0>, 1.1234 }

Other examples can be found scattered throughout the sample scene files.

A tip for MS-Dos users: Get ahold of dta.exe (Dave's Targa Animator) for creating .FLI/.FLC animations. aaplay.exe and play.exe are common viewers for this type of file.

When moving the camera in an animation (or placing one in a still image, for that matter) avoid placing the camera directly over the origin. This will cause very strange errors. Instead, move off center slightly and avoid hovering directly over the scene.

### Appendix F.4
Texture Tips

Wood is designed like a log with growth rings aligned along the z-axis. Generally these will look best when scaled down by about a tenth (to a unit-sized object). Start out with rather small value for the turbulence too (around 0.05 is good for starters).

The marble texture is designed around a pigment primitive that is much like an x-gradient. When turbulated, the effect is different when viewed from the side or from the end. Try rotating it by 90 degrees on the y-axis to see the difference.

You cannot get specular highlights on a totally black object. Try using a very dark gray, say Gray10 or Gray15 (from colors.in), instead.

### Appendix F.5
Height Field Tips

Try using POV-Ray itself to create images for height fields:

      camera { location <0, 0, -2> }
      plane { z, 0
         finish { ambient 1 }    // needs no light sources
         pigment { bozo }        // or whatever.  Experiment.
      }

That's all you'll need to create a .tga file that can then be used as a height field in another image!

### Appendix F.6
Converting "Handedness"

If you are importing images from other systems you may find that the shapes are backwards (left-to-right inverted) and no rotation can make them correct.

Often, all you have to do is negate the terms in the right vector of the camera to flip the camera left-to-right (use the right-hand coordinate system). Some programs seem to interpret the coordinate systems differently, however, so you may need to experiment with other camera transformations if you want the y- and z-vectors to work as POV-Ray does.

### Appendix G
Frequently Asked Questions

This is a collection of frequently asked questions and their answers taken directly from messages posted in the POVRAY Forum on Compuserve and the comp.graphics.raytracing newsgroup.

This version of the FAQ is heavily biased towards the CompuServe user of the IBM PC version of POV-Ray. Hopefully later revisions will remove some of this bias, but at present time, that is the largest audience.

### Appendix G.1
General Questions

### Appendix G.2
POV-Ray Options Questions

Q: How can I set mosaic preview to go from 8*straight to final render without going to 4*and then 2*first? A: Use the +SPn or Preview_Start_Size option to set the starting resolution and the +EPn or Preview_End_Size option to set the ending resolution. With +SP8 and +EP8 it will go from 8*8 down to 8*8 (just one pass) then immediately drop into the final pass at 1*1.

Q: Should the +MB switch be used in very small scenes, i. e. with a low number of objects. A: That depends on the number of objects and their type. Normally it doesn't hurt to always use the bounding box hierarchy (+MB0). If you have just one or two objects it may be better to not use automatic bounding.

Q: Does the +MB switch affect the quality of the image? A: No. It only affects the speed of the intersection tests.

Q: How do I avoid that the options screen scrolls off when error messages are generated? A: Use the +P switch. Everytime POV-Ray is interrupted or the tracing finishes you can use the cursor keys to scroll-back the options text.

### Appendix G.3
Include File Questions

Q: In the file textures.v2, the glass textures are commented out. Why? A: The old glass textures are duplicated in glass.inc. The old texture names didn't fit in with the new naming scheme. Glass is now T_Glass1, Glass2 is now T_Glass2 and Glass3 is now T_Glass3. While you can easily un-comment the old names you're strongly encouraged to use the newer naming scheme.

### Appendix G.4
Object Questions

### Appendix G.4.1
Height Field Questions

Q: I have a lowly 8 meg of RAM on my computer and I ran out of memory trying to use a 1024x768 pot file and a gif of the same resolution as height fields (two different scenes). Is it my memory thats low or is that resolution crazy? A: Smoothed heightfields will consume a lot more memory (about three times as much) as one that isn't smoothed. Since smoothing really isn't neccessary at those resolutions don't smooth (if you're smoothing).

Q: I want to use the same image for an image map and a height-field (which gives some meaningful relationship between the height and colors). Does that only work when using a gif or bmp format? I couldn't get the pot file to map (format not supported). A: pot files are not supported as image maps. Their purpose to POV-Ray is as heightfields. That doesn't prevent you from making a matching gif in fractint that uses the continuous potential coloring that you used for the 16 bit pot file, and using that as the image map. Remember that both image maps and height fields are initialized in a 1*1(*1) area, with the lower-left of the image situated at the origin. The image map is initiated in the x-y-plane while the height field is in the x-z plane. Thus you'll have to rotate the image map by 90 degrees around the x-axis (use rotate x*90) to get the image map to line up.

### Appendix G.4.2
Text Questions

Q: Is there any possibility to know the size of a font-object? A: Sadly no. We really need it but its not easy to do. Until just days before beta release the horizontal spacing didn't even work right. Now that we've got that fixed, perhaps we can figure a way to get the length.

### Appendix G.5
Atmospheric Questions

### Appendix G.5.1
Atmosphere Questions

Q: Why is the atmosphere I added not visible? A: The most common error made when adding an atmosphere to a scene is the missing hollow keyword in all objects the camera currently is in. If you are inside a box that is used to model a room you'll have to add the hollow keyword to the box statement. If a plane is used to model the ground you'll have to make it hollow (only if you are inside the plane, but to be sure you can always do it).

If this doesn't help there may be other problems you'll have to verify. The distance and scattering values of the atmosphere have to be larger than zero. Light sources that shall interact with the atmosphere mustn't contain an atmosphere off statement.

Q: Why can't I see any atmosphere through my translucent object? A: If you have a translucent object you (almost) always have to make it hollow by adding the hollow keyword. Whenever an intersection is found and the ray is inside a solid object no atmospheric effects will be calculated.

If you have a partially transparent plane for example the atmosphere on the other side of the plane will only be visible through the plane if this plane is hollow.

Q: Why do the lit parts of the atmosphere amplify the background? A: First, they don't.

Second, whenever parts of the background are visible through the atmosphere and those areas of the atmosphere are lit by any light source, the scattered light is added to the light coming from the background. This is the reason why the background seems to be amplified by the atmosphere. Just imagine the followoing example: you have a blue background that is attenuated be the atmosphere in a way that the color reaching the viewer is <0,0,0.2>. Now some light coming from a light source is attenuated and scattered by the atmosphere and finally reaches the viewer with a color of <0.5,0.5,0.5>. Since we already have light coming from the background, both colors are added to give <0.5,0.5,0.7>. Thus the light gets a blue hue. As a result you think that the background light is amplified but it isn't as the following scene clearly shows.

    #version 3.0
      camera {
        location <0, 6, -20>
        look_at <0, 6, 0>
        angle 48
      }

      atmosphere {
        type 1
        samples 10
        distance 20
        scattering 0.3
        aa_level 3
        aa_threshold 0.1
        jitter 0.2
      }

      light_source { <0, 15, 0> color rgb .7 shadowless }

      light_source {
        <-5, 15, 0> color rgb <1, 0, 0>
        spotlight
        point_at <-5, 0, 0>
        radius 10
        falloff 15
        tightness 1
        atmospheric_attenuation on
      }

      light_source {
        <0, 15, 0> color rgb <0, 1, 0>
        spotlight
        point_at <0, 0, 0>
        radius 10
        falloff 15
        tightness 1
        atmospheric_attenuation on
      }

      light_source {
        <5, 15, 0> color rgb <0, 0, 1>
        spotlight
        point_at <5, 0, 0>
        radius 10
        falloff 15
        tightness 1
        atmospheric_attenuation on
      }

      plane { z, 10
        pigment { checker color rgb<1, 0, 0> color rgb<0, 1, 0> }
        hollow
      }

The atmosphere seems to amplify what is seen in the background.

In the background you see a red/green checkered plane. The background color visible through the atmosphere is added to the light scattered from the spotlights. You'll notice that even though the red squares behind the red spotlight's cone are brighter than those outside the cone the green ones are not. For the green spotlight the situation is turned around: the green squares seem to be amplified while the red are not. The blue spotlight doesn't show this effect at all.

Q: The docs say the distance parameter for atmosphere works in the same way as fog distance. Is that right? A: Yes, that's right. Try to use a fog instead of the atmosphere. If everything looks good, i. e. you still can see the background or whatever you want to see, use the same distance and color for the atmosphere.

### Appendix G.5.2
Fog Questions

Q: I'm using moray to build a scene containing a ground fog. The problem is that the fog fades out along the y-axis. In moray the z-axis is up, so I have a wall of fog, rather than a layer. What to do? A: There is an up keyword that can be used to specify the up direction the ground fog is using. Adding the line up z to your fog will help.

### Appendix H
Suggested Reading

Beside the POV-Ray specific books mentioned in "POV-Ray Related Books and CD-ROMs" there are several good books or periodicals that you should be able to locate in your local computer book store or your local university library.

      "An Introduction to Ray tracing"
      Andrew S. Glassner (editor)
      ISBN 0-12-286160-4
      Academic Press
      1989

      "3D Artist" Newsletter
      "The Only Newsletter about Affordable
       PC 3D Tools and Techniques")
      Publisher: Bill Allen
      P.O. Box 4787
      Santa Fe, NM 87502-4787
      (505) 982-3532

      "Image Synthesis:  Theory and Practice"
      Nadia Magnenat-Thalman and Daniel Thalmann
      Springer-Verlag
      1987

      "The RenderMan Companion"
      Steve Upstill
      Addison Wesley
      1989

      "Graphics Gems"
      Andrew S. Glassner (editor)
      Academic Press
      1990

      "Fundamentals of Interactive Computer Graphics"
      J. D. Foley and A. Van Dam
      ISBN 0-201-14468-9
      Addison-Wesley
      1983

      "Computer Graphics:  Principles and Practice (2nd Ed.)"
      J. D. Foley, A. van Dam, J. F. Hughes
      ISBN 0-201-12110-7
      Addison-Wesley,
      1990

      "Computers, Pattern, Chaos, and Beauty"
      Clifford Pickover
      St. Martin's Press

      "SIGGRAPH Conference Proceedings"
      Association for Computing Machinery
      Special Interest Group on Computer Graphics

      "IEEE Computer Graphics and Applications"
      The Computer Society
      10662, Los Vaqueros Circle
      Los Alamitos, CA 90720

      "The CRC Handbook of Mathematical Curves and Surfaces"
      David von Seggern
      CRC Press
      1990

      "The CRC Handbook of Standard Mathematical Tables"
      CRC Press
      The Beginning of Time

### Appendix I
Help on Help

Using the Help Reader (POVHELP.EXE)

KNOWN INCOMPATIBILITIES

See after the Quick Intro.

Quick Intro

Use the +E option to make the help reader a pop-up program. Use Space to go to the next section. Use Ctrl-PgUp and Ctrl-PgDn to move between sections also. Use Tab to highlight hypertext links. Use Alt-Tab to highlight code fragments. Use Enter to jump to a highlighted hypertext link. Use +/- to jump to relevant sections once link jumping has started. Use BACKSPACE to return to the last place you were before a search/jump. Use 'S' to search on a keyword. Use 'J' to toggle text justification when reading a section. Use 'P' to paste code into your application via the keyboard buffer.

POV-Help will handle non-standard page widths provided the BIOS column count is correctly updated by whatever program is being used to alter it from 80 columns.

If you use POV-Help as a pop-up program, it will attempt to search on the word under your cursor when you pop it up. Note that if you exit pop-up mode by using the hot-key (the default is ALT-ESC), POV-Help takes this to mean that you want to return to the same place next time and will not perform a search. A search is only performed if you exited using ESCAPE (meaning you have finished with the current subject.)

The history stack activated by using Backspace holds 32 entries.

KNOWN INCOMPATIBILITIES

POV-Help does not work with MS-DOS's EDIT program. [In fact, EDIT.COM is really QBASIC.EXE with a few add ons ; EDIT needs QBASIC to run.]

If it won't work with your editor, try this (assuming you have macro facilities) -

o | write a macro to get the word under the cursor
o | have it call POVHELP.EXE with the word as a parameter
o | bind the macro to your key-sequence of choice.

Command Line (case insensitive)

+Iname | use alternate file name (default HELP.PHE)
+N123 | go to the 123rd section (NOT section 123!)
+S4.5.6 | go to section '4.5.6'
+Tsphere or "+Tsphere" | go straight to the first section found with 'sphere' in its title.
+W50 | window width 40 characters (max 127)
+H15 | window height 15 lines (max 21)
+J[-] | justify ON (default), -J- to turn off
+PH[n] | send 'n' HOME keys after each CR when pasting. default is -ph1.
+KALT-ESC | hot key sequence. can be CTRL|ALT|CTRL-ALT+[Any character]|[ESC]. e.g. +KCTRL-ALT-P, +KCTRL-1, +KALT-CTL-'. CTL is also acceptable.
+Eabc d e | run program 'abc' with parameters 'd' and 'e'. all parameters after the '+e' are passed to the program.
text | same as +T unless collecting +E parameters, where it is a parameter

Viewer Commands

Top Menu

Up, Down | move highlight bar
Enter | view selected item
Escape | exit help viewer

Authors, Copyright

Up, Down | scroll screen
PgUp, PgDn | scroll screen
Left, Right | scroll screen
Escape | return to top menu

Section

Up, Down | scroll screen
PgUp, PgDn | scroll screen
Left, Right | scroll screen
Escape | return to top menu
Space or CtrlPgDn | view next section
CtrlPgUp | view previous section
"+", Enter | jump to first/next hypertext link
"-" | jump to previous link/original section
"B" | jump back to original section (from before link jumping)
Tab | select next visible link, wraps from last to first
ShiftTab | select previous visible hypertext link
AltTab | select code fragment for pasting.
"P" | paste highlighted code fragment via keyboard buffer.

General

The help reader wraps most text. Excluded are specified portions, lists, and a few others. Use the left and right arrow keys to scroll these if need be.

The help reader is intended to be a 'shell' around an editor program. Some people may prefer the term 'shim'.

Using EMS for most memory requirements, it loads itself and then runs your editor for you, providing pop-up help facilities. It will also be able to paste code fragments into your source. If your editor was, for example, 'ME', you would place a batch file called 'ME.BAT' in your scene development directory. If you use 'VI', you'd create 'VI.BAT', and so on.

    (YOUR-EDITOR-NAME.BAT)

    desired key sequence ----
                            |
            ----------- -------------- ----------------
    povhelp |+W50 +H15³ |+KCTRL-ALT-H| |+Ed:\me\me.exe| %1 %2 %3 %4 %5
            ----------- -------------- ----------------
                    |                      |
    size of window --                      |
                                           |
    place path to your editor here ---------

For example -

    povhelp +W50 +H15 +KALT-H +Ed:\me\me.exe %1 %2 %3 %4 %5

This command line will yield a version of POV-Help with a 50x15 window, popped-up with the ALT-H key sequence, over the editor 'd:\me\me.exe'. If you don't specify a key sequence, POV-Help defaults to using ALT-ESC.

This would load the help reader. which would then load ME.EXE, and things would proceed as normal. When you exit your editor, the help reader automatically unloads. You can use the ALT-ESC key sequence to pop up POVHELP. This is the default ; there is a way to set it. Note that no other parameters may appear after the +E parameter as they will just be passed to the program being run.

If you use the hotkey to pop-up, POVHELP performs a simplistic search of sections and titles based on the word under the cursor. If found, you are taken to that. Otherwise, you are taken to the main menu, unless you hot-keyed out.

You can hot-key out of the actual section text, by using the same hot key that got you in. If you press escape, you are taken back up to the top menu. But if you hotkey out, you go back to your program. Next time you press the hot key, you will be taken back to the same place. No search is performed in this case.

POVHELP needs EMS if it is running as a shell program.

If you don't specify the +E parameter, POVHELP will come up as a stand-alone program, in which case it does not use EMS.

If you highlight a section of code using Alt-Tab, and you are using POV-Help in pop-up mode, then you may paste the code via the keyboard buffer using 'P'.

As many editors today use auto-indentation, this may cause some problems with column alignment. For that reason, POV-Help by default inserts a HOME key code into the keyboard buffer after each CR. Some editors require more than one HOME key operation to get to the left column. For this reason, the number of HOME's sent may be adjusted from 0 (none) to 9 using the +PH[n] command-line parameter. 'n' is any value from 0 to 9 and defaults to 1.

    POV-Help was written by  Christopher J. Cason.
    CIS      : 104706,3166
    Internet : povray@mail.oaks.com.au
               Chris.Cason@povray.org

Converters will be available which translate POV-Help databases to other formats such as Postscript, LaTeX, RTF, Windows Help, HTML, etc.

The format of the POV-Help database is documented and freely available.

POV-Help is free. It may not be sold. See POVLEGAL.DOC for details. The POV-Help suite of programs is copyright (c) 1994 C.J. Cason and the POV-Team.

POV-Help is free. It may not be sold. See POVLEGAL.DOC for details.