Short description of the Zblur plugin			8.99, onk@gmx.net
-------------------------------------


This plugin fakes a focal blur of a camera - also known as depth
blur, depth of field, etc. (I don't know which is really the correct one :-) )

Drawbacks: It doesn't give good results on objects which have sharp edges.
The problem is, that the Z-Buffer values are subject to aliasing, even
if the OSA button is set. So for the moment, a part of the Z-Buffer
is slightly blurred to get a compromise between aliasing and sharpness.
(Maybe someone wants to invent an antialiasing algorithm for the Zbuffer
by edge detection ?)

On some complex scenes it can also introduce unrealistic artefacts
in the background which you will have to live with for the moment
and wait for a better method. (Suggestions ?)

There is a more detailed description at 
http://honk.physik.uni-konstanz.de/onk/3d
- but this Readme might be more up to date.

----------
Usage:

As a rule of thumb, set the ClipSta value of your camera as high as
possible. The closer the object is to the camera, the more it is
blurred, considering you have your focus not set too close.
So if ClipSta is too narrow, you might not see a blurring effect in
the foreground.

Input parameters ('N' key after plugin was selected):

Blursize: sets the blur radius for the maximum blur. The larger the radius,
	the longer it takes. (This simulates like the aperture of your
	camera iris).
Zmin:	(0.0 < Zmin < 1.0): Use this value to shift the beginning of
	the maximum close-up blur - normally, the max. blur starts at
	ClipSta, with Zmin > 0 you can shift it rather into the background.
	(Useful when you can't change ClipSta). The value isn't really
	representative for a distance - how you can properly set it
	is explained below.
	Zmin must not be greater than the focus Value, otherwise this
	would cause an error.
Focus:	The normalized focus value in the whole Z-buffer range - 0.0 is closest
	(ClipSta) and 1.0 furthest.

To find the exact values for Zmin and Focus:
Set the "Autofocus" option", and have your camera track an Empty.
Then move the Empty around and do a test render - on the shell window
(where you started blender from) it will print the Z value of the center
spot. For the moment this is the only workaround to get the exact focus
point.

Ipofocus: when set, the values from the SeqIpo-Curve (see IPO editor,
sequence button) are used for the focus. Same range as above - you can
just enter the exact autofocus values with selecting a curve CV and pressing
'n'.

Show zfront: shows the foreground part of the Zbuffer (before the focus plane).

Show zback: shows the background part of the Zbuffer (behind the focus plane).

You may use these for control purposes to determine your optimal blur range 
(white means maximum blur radius in the rendered image).

If the output is a full red image, an error has occured. Change to the
shell window you started Blender from to see the error message.


BUGS:
Field rendering and Panorama does not work (there is no Z-Buffer information
provided). Blender may crash if you try anyway.
Also, someone reported crash on plugin load on a mixed libc5/libc6 
with blender version 1.68a, libc5 static. Solution: Use the libc6 version.


-----------------------

Additions: (experimental section)

Gamma and Sigma correction:
When blurring an image with strong contrast, you may notice that some
of the bright spots on the image become too dark and look unnatural.
This is especially the case when having halos or reflections. Therefore
the intensity values are gamma-corrected for the blurred background, and
warped with a sigmoid function for the blurred foreground - according to
the entered values. If you have lights in the foreground, a value of
Sigma around 8 makes sense. A Sigma of 0.0 and Gamma of 1.0 means no
correction at all.

Suggestion: when you use lamp halo effects (like lens flares), render
them separately and compose them into the rendered image or movie
later. 
