**************************************************************************
**************************************************************************
    DEPTH OF FIELD CONTROL INCLUDE FILE FOR PERSISTENCE OF VISION 3.1
**************************************************************************
**************************************************************************

Created by Francois Dispot, 15 July 1998

1  INSTALLATION
2  USAGE
3  ERRORS
4  COPYRIGHT AND LEGAL INFORMATION
5  CONTACTING THE AUTHOR

**************************************************************************


1  INSTALLATION
**************************************************************************
The DoF Include File package consists of a macro file and associated
examples and documentation.  This macro file should be copied to
one of the directories (folders) in your POVRay library path.  Normally
this is the INCLUDE sub-directory of the directory where you installed
POVRay, so if you installed POVRay in C:\POVRAY you should copy the files
to C:\POVRAY\INCLUDE.  On an Amiga system, this is probably something
as simple as:

   POV:Include

On UNIX and similar systems, where filenames are case-sensitive, you may
have to rename the four include files so the filenames are all uppercase.
This will enable you to render the sample files without modification.


2  USAGE
**************************************************************************

The DoF Include File allows you to use the Depth of Field features of the
Persistence of Vision v. 3.1 raytracer in a very simple fashion. Normally
one should specify two scale parameters and three statistical values to
POVRay to get proper results. This file will still let you tune the
statistical values, which cannot be guessed, but should give you a bit of
help for the two others.

In fact, it replaces the focal_point (not that easy) and aperture (quite
hairy) values with the correct ones, provided two points in the scene,
being the first and last points for which sharpness is needed.

To use this macro, first include the DoF file in the beginning of your
scene description:
   #include "DOF.INC"

Then, when declaring the camera, replace the focal_point <...> and
aperture ... statements with:
   DoF(location, width, angle, look_at, 1st point, 2nd point)
where:

   Location is the location (!) of the camera, identical to the location
statement
   look_at is identical to the look_at statement
   angle is identical to the angle statement
   1st point and 2nd point are two points in the scene which will be
situated at the limit between sharpness and blur. Since blurring is
progressive, the "amount" of blur at these points will be given by the next
parameter.
   width is the width in pixels of the rendering. This will calculate the
aperture so that, for the two control points, the blur "radius" will be
1/2 pixel. Note that this will usually lead to soft blurring, since it
demands a very limited blur for the two control points. Do not hesitate to
decrease this value to get a more blurred scene!

Have a look at the example files to see that it is easier to use than to
explain!

3  ERRORS
**************************************************************************
DoF.inc is likely to give an error message if one of the following
conditions is met:

-The two control points are at the same distance from the camera. This
would result to a physical nonsense, with a null sharpness zone. If you
want to get something very narrow, give a width of 1 and be patient.

-One of the control points is below the camera. This is impossible with
CURRENT camera implementations.

A note about the above statement, before the photographers start to
complain. POV provides with an interesting set of lenses. It is even
possible to use "perspective control" (or "shift") lenses, looking at a
point different from the center of the picture, and then rendering only a
part of it to have it back to its normal place. Typically this will
suppress the "bending" of vertical lines while looking at a building.
Unfortunately, it does not seem possible to use "tilt" lenses, which enable
the photographer to have a focal plane which is not perpendicular to the
axis of the lens (thus leading to sharp but invisible points behind the
camera). I might be wrong on this point and will humbly correct myself if a
guru of both POVRay internal code and Scheimpflug's relation shows me how
to get an optical axis which is not perpendicular to the "film".

4  COPYRIGHT AND LEGAL INFORMATION
**************************************************************************
The DoF Include File package, including DoF.inc, all documentation, and
associated sample files are Copyright 1998 by Francois Dispot.  Full
permission is granted to theuser to modify any or all of the files for
his/her own use.  If modifiedversions are to be distributed the user
should make clear the modificationsthat have been made by him/herself.
The DoF Include File package maybe bundled with or without other software
on CD-ROM collections, BulletinBoard systems and other file archives,
providing that all associated files,including documentation and samples,
are included.  I would also requestthat persons intending to distribute
the DoF Include File package inthis manner or otherwise would first
contact me (see below for contactinformation) to ensure that they are in
possession of the latest version.


5  CONTACTING THE AUTHOR
**************************************************************************
If you wish to contact me with bug reports, bug fixes, criticisms, 
comments, suggested improvements, questions, etc. you can reach me by 
email at:

   wozzeck@club-internet.fr


**************************************************************************

POV-Ray(tm) and Persistence of Vision(tm) are registered trademarks of the
POV-Ray Team(tm)
