**************************************************************************
**************************************************************************
          LENS FLARE INCLUDE FILE FOR PERSISTENCE OF VISION 3.x
**************************************************************************
**************************************************************************

Created by Chris Colefax, November 1996
Last Updated March 1997

1.0  INSTALLATION
2.0  QUICK START
3.0  OPTIONS
        3.1  POSITION VECTORS
        3.2  camera_direction and camera_angle
        3.3  flare_type
        3.4  flare_size
        3.5  flare_brightness
        3.6  flare_rotate
        3.7  flare_spots
        3.8  flare_spot_spacing
        3.9  flare_rays
        3.10 flare_glow
        3.11 flare_colour
        3.12 flare_seed
4.0  MULTIPLE LENS FLARES
5.0  ALTERING THE CAMERA
6.0  ADDING LENS FLARE TO EXISTING IMAGES
        6.1  METHOD 1
        6.2  METHOD 2
7.0  ANIMATING LENS FLARES
8.0  LENS FLARE TYPES
9.0  TROUBLESHOOTING
10.0  CONTACTING THE AUTHOR

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


1.0  INSTALLATION
**************************************************************************
Copy the lens flare include file (LensFlar.inc) 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 LensFlar.inc file to 
C:\POVRAY\INCLUDE.  On a Windows 95 system, this is probably something 
like:

   C:\Program Files\POV-Ray for Windows\Include

On UNIX and similar systems, where filenames are case-sensitive, you may
have to rename the include file to LensFlar.inc rather than lensflar.inc
or LENSFLAR.INC.  This will enable you to render the sample files without
modification.

2.0  QUICK START
**************************************************************************
To add a lens flare effect to an existing POVRay scene file, just add the 
following four lines somewhere in the file:

   #declare camera_location = <0, 0, -5>
   #declare camera_look_at = <0, 0, 0>
   #declare flare_position = <4, 3, 10>
   #include "LensFlar.inc"

where the camera_location and camera_look_at are the same vectors used in 
your camera statement.  The flare_position is the position of the light 
source to which you want to add the lens flare effect.

EXAMPLE: Say you have the following two lines in your scene file:

   camera {location <100, 46, 420> look_at <-300, 67, 100>}
   light_source {<0, 50, 300> red 1 green 1 blue 1}

To add a lens flare to this scene, just add these lines to the end of the 
scene file:

   #declare camera_location = <100, 46, 420>
   #declare camera_look_at = <-300, 67, 100>
   #declare flare_position = <0, 50, 300>
   #include "LensFlar.inc"


3.0  OPTIONS
**************************************************************************
Although only the four lines shown above are required to create a lens 
flare effect, there are a number of options you can use to alter the lens 
flare, including changing its size, brightness, colour, and shape.


3.1  POSITION VECTORS
*********************
To make your scene file easier to manage, you might like to declare the 
lens flare position vectors first, and then use them in your camera and 
light_source statements, eg:

   #declare camera_location = <0, 0, -5>
   #declare camera_look_at = <0, 0, 0>
   #declare flare_position = <4, 3, 10>

   camera {location camera_location look_at camera_look_at}
   light_source {flare_position <1, 1, 1>}

That way, you only have to change one set of values to move your camera or 
light source.  However, what happens if you want to transform your camera 
(or light source) using rotations, translations, or scaling?  Fortunately, 
POVRay 3.x provides all the necessary functions to do this quite easily.  
For translations, just use vector addition; for scaling, just use vector 
multiplication; and for rotations, use the vrotate function.  For example, 
say you added these commands to the above camera:

   translate <-6, 4, 1.5>
   rotate <20, 15, 10>
   translate <3, 6, -5>
   scale 2

To make sure that the lens flare moves with the camera, remove the 
commands from the camera, and add these commands before the camera:

   #declare camera_location = camera_location + <-6, 4, 1.5>
   #declare camera_location = vrotate (camera_location, <20, 15, 10>)
   #declare camera_location = camera_location + <3, 6, -5>
   #declare camera_location = camera_location * 2

   #declare camera_look_at = camera_look_at + <-6, 4, 1.5>
   #declare camera_look_at = vrotate (camera_look_at, <20, 15, 10>)
   #declare camera_look_at = camera_look_at + <3, 6, -5>
   #declare camera_look_at = camera_look_at * 2

Note that if the transformations come after both the location and look_at 
commands, you have to transform both as above.  If the look_at command 
came *after* the transformations, you would only have to add the first 
four commands.


3.2  camera_direction and camera_angle
**************************************
Changing the direction and angle parameters of the POVRay camera causes
the camera to zoom in or out.  This will also change the apparent size
of any lens flare effects in a scene.  If you use either of these
parameters to alter the camera you can use the camera_direction and/or
camera_angle options.  If these are equal to the amounts specified in the
camera statements then the lens flare effects will always be the same size
even when the camera zooms in or out.


3.3  flare_type
***************
In photography, different lenses produce different lens flare effects.  
LensFlar.inc can also produce a number of different effects, specified by 
the flare_type option.  Just add the following line before you include 
LensFlar.inc:

   #declare flare_type = [ a number from 1 to 9 ]

See section 8.0 for a listing of the different effects available.


3.4  flare_size
***************
This option is used to adjust the overall scaling of the lens flare 
effect; numbers larger than one increase the size of the effect, and 
numbers smaller than one decrease the size of the effect, eg:

   #declare flare_size = 1.4

Generally, this number should be in the range of 0.5 to 2.0, but any 
number except 0 can be used.  Increasing the size dramatically is useful 
if you want to give the effect of blinding a scene with light.

NOTE: Specifying numbers smaller than 0.3 or 0.4 can result in ugly ring 
artifacts, and should not be used.


3.5  flare_brightness
*********************
This option is used to adjust the transparency or intensity of the lens 
flare effect; number larger than one increase the intensity of the effect, 
while numbers smaller than one increase the transparency of the effect, 
eg:

   #declare flare_brightness = .8

Setting this number to 0 makes the effect completely disappear, which if 
useful if you want the light source to vanish behind an object.

3.6  flare_rotate
*****************
All the different flare types contain rays that move outwards from the
centre of the light source.  The angle of these rays with respect to the
camera is fixed for each flare, and does not change when the flares are
moved (unlike the flare arms of flare types 1 to 3, which are always rotated
such that they pass through the centre of the screen).  You can change this
angle by using the flare_rotate option.  This specifies the angle (in
degrees) to rotate the flare rays, where positive numbers are counter-
clockwise and negative numbers are clockwise.

NOTE: Flare type 4 is not affected by this option, as the rays always pass
through the centre of the screen.


3.7  flare_spots
****************
A number of the different lens flare effects include flare arms, composed 
of spots of varying size, colour, and transparency.  These flare spots are 
not always desirable, especially when creating multiple lens flare effects 
in one scene.  To turn off these spots, just add this line before you 
include LensFlare.inc:

   #declare flare_spots = false

You can also set the value to true to turn the spots back on if they were
previously turned off.


3.8  flare_spot_spacing
***********************
You can use this option to alter the spacing between the individual spots
of the flare arms.  By default this is 1; numbers larger than 1 will
increase the spacing between the spots, while numbers less than 1 will
bring the spots closer together.  Any number is allowed except 0.


3.9  flare_rays
***************
Each different flare type includes rays, which extend outwards from the
light source.  You can turn these rays on or off for a particular flare
by setting this option to true or false.


3.10  flare_glow
****************
Each different flare type includes a glow which surrounds the light source.
In addition some of the flare types include a halo ring further out from
the flare glow.  You can turn the glow and halo on or off for a particular
flare by setting this option to true or false.

NOTE: You can use this option in conjuction with the flare_rays and
flare_spots options to mix and match various parts of different flare types
to create new flares, eg. the following will create a composite flare which
joins the glow and rays of flare type 1 with the spots of flare type 4:

   #declare flare_count = 2
   #declare flare_type = 1
   #declare flare_spots = false
   #include "LensFlar.inc"

   #declare flare_type = 3
   #declare flare_spots = true
   #declare flare_glow = false #declare flare_rays = false
   #include "LensFlar.inc"


3.11  flare_colour
*****************
Each lens flare effect tends to have a dominating colour, which may or may 
not be what you want in a particular scene.  To change the colour of an 
effect, just add this line to your scene file before you include 
LensFlar.inc:

   #declare flare_colour = <2, .5, 0>

where the three part vector specifies the scaling factor of the red, 
green, and blue components of the lens flare effect's colour.  The above 
example doubles the red, halves the green, and removes the blue from the 
lens flare effect.  This would generally result in a red or orange effect, 
while <.1, .3, 1.5> would give a blue effect.  Each type of effect is 
altered differently by the flare_colour option, and you should experiment 
to find the right value for a particular scene.

NOTE: You can also use flare_color to specify this option.


3.12  flare_seed
***************
A number of the different lens flare effect types use a random number 
generator to create various components of the effect.  You can specify the 
seed value to be used by adding this line before you include LensFlar.inc:

   #declare flare_seed = 98732

The default random number seed is 0.


4.0  MULTIPLE LENS FLARES
**************************************************************************
To specify multiple lens flare effects, you need to do three things:

a) Specify the camera_location and camera_look_at vectors.
b) Specify the number of lens flares using the flare_count option.
c) For each lens flare, specify the flare_position, and any other
   options, and include LensFlar.inc

For example, say you want three type 7 flares, at different positions:

   #declare camera_location = <0, 0, -5>
   #declare camera_look_at = <0, 0, 0>
   camera {location camera_location look_at camera_look_at}   

   #declare flare_type = 7
   #declare flare_count = 3

   #declare flare_position = <4, 3, 10>
   #include "LensFlar.inc"

   #declare flare_position = <-5,1,20>
   #include "LensFlar.inc"

   #declare flare_position = <-1,-6,15>
   #include "LensFlar.inc"

Notice that you only have to declare the flare_type once, as it is
remembered for subsequent lens flares.  The same goes for the other
lens flare options, but you can declare them separately for each
lens flare if you wish.

NOTE: Do not include any other commands in between the first and last
lens flare, except for declaring the desired lens flare effect options.
If you do, or do not include the LensFlar.inc file the correct number
of times, an error will result.


5.0  ALTERING THE CAMERA
**************************************************************************
The effects produced by LensFlar.inc are designed to look best when used 
with the POVRay default camera (with different camera locations and 
look_at's, of course).  However, POVRay 3.x includes a number of 
parameters to change various aspects of the camera, and altering the
camera in this way may or may not affect the lens flares.

The lens flare effect works well with all camera projections, except for 
orthographic, and some cylindrical projections.  Some projections may 
alter the size of the lens flare effect, but this can be counteracted by 
using the flare_size option.

Using the up, right, and sky vectors to change aspect ratios or to roll 
the camera should usually work fine.  Once again, however, the size of the 
effect might have to be adjusted using the flare_size option.

Using the direction and angle statements is also fine, but you must make 
sure that the camera_look_at vector is equal to the final look_at vector 
specified by the camera command.

Focal blurring will generally not work at all, or produce a very blurred 
lens flare effect.  If you wish to include focal blurring in an image with 
a lens flare effect, you can render the image without the lens flare and 
then use the techniques specified in section 6.0 to add the desired lens 
flare to the rendered image.

Similarly, using a normal statement within the camera command will also 
alter the appearance of the lens flare effect.  If you do not want the 
lens flare to be altered in this way, you can render the scene without the 
lens flare and use the techniques below to add the desired lens flare 
effect to the rendered image.


6.0  ADDING LENS FLARE TO EXISTING IMAGES
**************************************************************************
Although LensFlar.inc is primarily designed for adding lens flare effects 
to POVRay rendered scenes, there are a number of cases in which you may 
wish to add a lens flare to an existing image.  There are two ways of 
doing this; the first requires that you have suitable image manipulation 
software, while the second is slower but only requires POVRay.

6.1  METHOD 1
*************
Take your existing image that you wish to add a lens flare effect to, and 
create a POVRay scene file that contains a camera and a lens flare (or 
flares, if you want more than one).  You will have to set the 
flare_position of each flare so that when you render the scene at the same 
resolution as the existing image, the flares are in the desired locations.  
You may also have to use the up and right vectors to change the aspect 
ratio of the scene file if the existing image is not in the standard 4/3 
ratio.

Then, render the scene file at the same resolution as the existing image 
(the background of the rendered image should be black).  To add the lens 
flare effect to the existing image open both images in a suitable image 
manipulation program and "add" the two images together (Paint Shop Pro can 
be used for this in Windows, and most good image manipulation programs 
should be able to accomplish this).

6.2  METHOD 2
*************
If you do not have access to a suitable image manipulation program it is 
possible to use POVRay to perform the same function.  To do this you will 
need an existing image in a format compatible with POVRay's image_map 
function (eg. TGA or GIF).  Then, create a scene file like this:

   #declare camera_location = <0, 0, -1>
   #declare camera_look_at = <0, 0, 0>

   camera {location camera_location look_at camera_look_at}

   box {<0, 0, 0>, <1, 1, 1>
      texture {
         pigment {image_map {
            tga "image.tga" interpolate 2 map_type 0}}
         finish {ambient 1 diffuse 0}}
      translate <-.5, -.5, 0>
      scale <4/3, 1, 1>}

changing the image_map commands to reflect the image you are using.  If 
the existing image has a different aspect ratio, you should add up and 
right vectors to the camera command specifying the ratio.  Also, the 
scaling of the box (last line) should be the same as the up and right 
vectors of the camera, eg. for a 300 x 500 image:

   camera {location camera_location look_at camera_look_at
           up y * 5/3 right x}

   box { [above information, without last line]
      scale <1, 5/3, 1>}

To the end of this file add the desired lens flare commands, eg:

   #declare flare_position = <-4, 3, 10>
   #declare flare_brightness = 1.4
   #include "LensFlar.inc"

Now you can render this file at the desired resolution to produce the lens 
flare enhanced image.

NOTE: If you experience odd pixelation around the edges of the image try 
increasing the box scaling by a very small amount, eg:

   scale <4/3, 1, 1> * 1.01


7.0  ANIMATING LENS FLARES
**************************************************************************
Provided that the correct camera_location, camera_look_at, and 
flare_position are specified the lens flare effect will automatically be 
rotated into the correct position.  Note also that the lens flare 
automatically begins to fade away as it disappears from view, and becomes 
completely transparent when the angle between the flare_position and the 
camera_look_at vectors is bigger than 60 degrees.

If your animation includes shifting the camera or light_sources using 
translations, rotations, or scaling, see section 3.1 for instructions on 
how to automatically determine the correct position vectors.

Note that the lens flare effect does not automatically dissappear when the 
specified flare_position point moves behind another object.  To simulate 
this effect, you can set flare_brightness to 0 when the flared light 
source moves behind another object.


8.0  LENS FLARE TYPES
**************************************************************************

#declare flare_type = 1
   This produces the default lens flare.  It contains 6 primary rays,
   numerous secondary rays, and a bluish-white central glow.  This is
   surrounded by a rainbow halo, and the effect is enhanced by flare
   arms composed of randomly sized and coloured circular spots.

#declare flare_type = 2
   This produces a "warmer" lens flare than type 1.  It contains 9
   primary rays, and the same number of secondary rays.  The central
   glow is yellow to orange, and this is surrounded by a reddish
   halo.  The flare arms are composed of regular circular spots.

#declare flare_type = 3
   This flare has 8 primary rays, and numerous secondary rays.  The
   strong central flare ranges from blue to purple.  The flare arms
   are composed of purple triangular spots.  This colour can be altered
   using the flare_colour option for a whole variety of different
   effects.

#declare flare_type = 4
   This flare has a distinctive cross pattern of 8 primary rays, and
   numerous secondary rays.  By default the strong central glow is
   green in colour (perhaps suggesting underwater scenes), but this
   can be changed with the flare_colour option for a whole variety of
   different effects.

#declare flare_type = 5
   This flare has 6 primary rays and 12 secondary rays.  The slight
   central glow and halo are normally white in colour, but by changing
   the flare_colour option a whole range of different flares can be
   produced.

#declare flare_type = 6
   This small flare has numerous rays, and a warm yellowish central
   glow surrounded by a red halo.  The effect is similar to that of
   type 2, but this flare doesn't include any flare arms or spots.

#declare flare_type = 7
   This is a small golden coloured sparkle, with 8 primary rays and
   8 secondary rays.

#declare flare_type = 8
   This is a small bluish white sparkle, with 6 rays.

#declare flare_type = 9
   This is a small sparkle with four rays.  It is coloured white by
   default, and so is suitable when a small lens effect is desired.
   Many different coloured sparkles can be created by using the
   flare_colour option.


9.0  TROUBLESHOOTING
**************************************************************************
If you are having a problem using the lens flare include file please read 
these questions to see if it can help with your particular problem.  If 
you are still not able to solve the problem, please contact the author 
(see section 10.0).

Q: My scene halts with an error when I try to include lens flare effects?
A: An error could occur if you are trying to use multiple lens flare
   effects and you have not specified the correct commands (see
   section 4.0 for more details).  Also, make sure that each variable you
   declare is of the correct type (see section 3.0 for options).

Q: I have all the right commands, but I can't see any lens flare?
A: There are various situations in which the lens flare becomes invisible:
     1)  You have not specified the required information.
     2)  The lens flare may be out of the camera's view.
     3)  The flare_brightness may be set to 0.
     4)  You have specified an unknown flare_type number.
     5)  You have specified an incorrect camera_location,
         camera_look_at, or flare_position.

   If any of these occur, POVRay should give you a warning explaining
   the reason the error occurred.

Q: I have specified multiple lens flares, but I can only see one?
A: Make sure you have used the right commands to create the multiple
   lens flares, including the flare_count variable (see section 4.0
   for more details).

Q: Funny circular lines show up when I render my image?
A: These lines usually occur because you have specified a too small
   value for the flare_size variable.  Try increasing this value to
   see if the problem goes away.

Q: I rotated my camera, and now I can't see the lens flare?
A: If you wish to use rotation, translation, or scaling to position
   your camera or light source, see section 3.1 on how to make sure
   that the lens flare position vectors remain correct.

Q: After adding a lens flare effect some areas of my image are black
   where they shouldn't be?
A: If you notice areas of plain black on transparent or reflective
   objects, you may have to increase the max_trace_level for the scene.
   This is because the lens flare effects are created on a very small
   transparent sphere.  To fix the problem, add this command to your
   scene file:

      global_settings { max_trace_level 7 }

   If such a line already exists, or this does not solve the problem,
   just increase the number until the problem disappears.


10.0  CONTACTING THE AUTHOR
**************************************************************************
I first conceived the idea of generating lens flare effects using POVRay 
3.x's inbuilt texturing commands while creating an image for the 
September/October 1996 Internet RayTracing Competition.  After studying 
numerous computer generated and real world examples of various lens 
flares, I finally developed this include file.

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

   ccolefax@geocities.com

or by regular mail at:

   Chris Colefax
   P.O. Box 110
   Kuranda, Queensland
   Australia  4872

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

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