
             _________The Sky factory___________
                        version 1.1
                           7-4-08
                             for
                PERSISTENCE OF VISION RAY TRACER
                        POV-Ray VERSION 3.6         
                              by
                        Leroy Whetstone 
                     Email lrwii@joplin.com
                  _____________________________   
                     
================ CONTENTS ================= 
1: Installation
 1.1 Quick Start
 1.2 INI Files
2: Overview
 2.1 using this file
 2.2 variable names
 2.3 Preview
3: File input/output
  3.1 SaveSky
4: Sky_sphere
 4.1 Sky pigment maps
 4.2 Sky modifiers
5: Cloud Cloud Boxes 
  5.1 Cloud Pigment maps
   5.1.1 Cloud 0
   5.1.2 Cloud 1
   5.1.3 Cloud 2
   5.1.4 Cloud 3
   5.1.5 Cloud 4
   5.1.6 Cloud 5
  5.2 Cloud Pigment Adjustments
  5.3 Box Tips
6: Special Tricks
7: After Thoughts


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

1:================== Installation ==================

  the zip should contain:
   Sky_factory.pov - the sky maker
   Sky.ini         - an ini file for stills
   SkyAni.ini      - an ini file for animation
   AnimaSky.pov    -an example animation
   Default.inc     -has the settings that Sky_Factory's came with
   Desert.pov      -an example of Sky_Factory's pov output
   TestA.pov       -an example of Sky_Factory's pov append output
   Sea.inc         -an example of Sky_Factory's data output
   Sea.pov         -an example of calling Sky_Factory
   Intro.txt       -this file
   
  
  You should be able to unzip this into any directory ya want.
  I like to put it in its own directory so I can have all the skies
  that I make in one place.

1.1 ================ Quick Start===============

    All you have to do is run 'Sky_Factory.pov' from POV
         using 'Sky.ini' or your own INI.
    'Sky_Factory.pov' has its own preview built in
    
        All the examples are best veiwed with 
           Width =800 Height =400 in the INI
    
    There are a lot of variables to understand.
    So when after you've done the first run, try changing 'Boxn'
    and see the clouds disapear. 
    Now change 'BackPig' and see what the background does.

1.2 ============ INI Files ===============

    There are two INI files that come with Sky Factory

    'Sky.ini' has the bare minimum to produce a still image
                   It displays the image only 
        It does have antialise settings but these are turned OFF
             The default Width =800 and Height =400 
    
    'SkyAni.ini' has the bare minimum to produce a Animation
                   It displays the images only
        The antialise settings are OFF and should be keeped OFF
                or at least have the jitter OFF            
             The default Width =400 and Height =200
                  Initial_Frame=0  Final_Frame=23
                   with Cyclic_Animation off

   I keep the a few the 'Library_Path' in both. They are commented out.
            They're there to make adding your own eazier.

2:================ Overview  ===============

  I got tired of making a sky from scratch for each of my POV projects.
  So, the Sky factory was made to produce a supply of skies.
 
  The Sky factory can be use to make and save skies or be called from
  another POV file to make still or animated skies. 
 
  It uses a sky_sphere as background color and 3 boxes as clouds.
  The sky_sphere has 12 preset pigment maps that can be modified.
  The Cloud boxes have 6 preset pigment maps that also can be modified.
  Any or all the Cloud boxes can be turn off. The Cloud boxes have two 
  places the pigment maps can be placed near the view and far from the 
  viewer.
 
  There are three ways of saving a Sky one way is to save the just the
  variables that are used to make a sky. The next is to make an inc file
  that can be use with #include from any POV file to make a Sky.
  the last is to append to an existing POV file.

  
  The Sky Factory has it's own preview scene built in.
  Sky Factory's default camera is Pov default camera with the
  cameras 'right' set to 'x*image_width/image_height'.

  To call the Sky factory from another POV file, I used the 
  variable 'Get' to turn off the predefined variables and the 
  preview display. Define 'Get' and the variables needed 
  then include 'Sky_factory.pov'.
  You will get back an object 'LRClouds' and a pigment 'Sky_Pigment'
   that you can use in a sky sphere

   The sky factory was built for use without Radiosity.
      You may have to tweek some files if you use it.



2.1 ============= using this file ============

   Hopefully this file contains enough information to help you
   make truly wonderful skies.
   
   If your using a text editor with the find function you should 
    be able to use it on key words to find any thing ya need.

2.2 ============= variable names ============   

     There are 4 main variable name types
      boxes, clouds, sky sphere, files

      boxes-- deal with size and number of cloud boxes
              and uses the 'Box' prefix
      clouds-- deal with the pigment map and finish for each cloud box
               all cloud boxes use 'Cloud' as the prefix then the
               next letter will be a 'L' or 'M' or 'H' 
               for the size of  box   Low    Mid    High. 
               if there is another letter before the '_' 
               it has to be 'n' or 'f' they stand for 'near' or 'far'
      sky sphere-- deal with sky sphere pigment map
                   and uses the 'Back' prefix 
      Files------ have no organise naming system
      
     Here is a list of variables and their functions:

      // files i/o
       an empty string means don't do

      SaveData="" //save the variables (use 'LoadFile' later)
      SaveSky=""  // save a stand alone Sky 
      AddtoSky=no //append SaveSky to an POV file
      LoadFile="" //#include file
 
      //boxes
      BoxL =vector  //lowest corner middle box size
      BoxH =vector  //upper corner middle box size
      BoxD =float   //difference between Mid and Low,high boxes
      Boxn =interger//1=Low,2=Mid,4=High,7=all place boxes 0=no boxes
                      // binary 'or' these values togather
                      
      //background(sky_sphere)
      BackPig =interger  //0-11 background(sky_sphere) pigment
      BackRev =yes/no    //reverse background pigment colors
      BackRotate =vector //rotate background pigment 
      BackMap =float     //pigment background color_map point
      BackTurb =vector   // turbulence of background pigment map
      Back_Dc =ColorVec  // shade background sky

      //Clouds Type & pigment blend maps variables
     //Low box value 1
     CloudLn =interger     //0-5 Low clouds near viewer 
     CloudLf =interger     //0-5 Low clouds far from viewer 
      CloudLn_Dc =ColorVec // shade Ln Clouds 
      CloudLf_Dc =ColorVec // shade Lf Clouds 
       CloudLn_Ps =vector    // scale Ln Clouds pigment
       CloudLf_Ps =vector    // scale Lf Clouds pigment
     CloudL_Mv =vector     //translate Ln & Lf Clouds pigments
     CloudL_Rot =vector    //Rotate Ln & Lf Clouds pigments
     CloudL_Range =XYvector // Near/Far color_map transition values x= closest 
     CloudL_Turb =vector   //low box pigment_map turbulence value
     CloudL_Amb =vector    //low box ambient
     CloudL_Shadow =no;    //yes/no low box cast shadows
  
 //Mid box value 2
   the mid box variables are exactly the same as the low boxs
   Except the 'L' in the name is replaced with 'M'

 //High box value 4
   The High box variables are exactly the same as the low boxs
   Except the 'L' in the name is replaced with 'H'

2.3 ============= Preview ======================

   The Sky Factory has it's own preview scene built in.
  Sky Factory's default camera is Pov default camera with the
  cameras 'right' set to 'x*image_width/image_height'.
  
  It has 'global_settings {max_trace_level 20}'

  It has
   'object{LRClouds}'
   'sky_sphere{pigment{Sky_Pigment}}'
  to preview the sky.
  
  It has two test grounds a plane and a box both commented out
   Using the plane will always cut the screen in half.
   The box can give you a larger sky area.
                  
  and a test Sun also commented out
   I use this Sun with 'BackPig'>5 but you can use any time
   
   Feel free to change the preview to anything ya like

3:============ File input/output ==============
  
  The Sky Factory has many way to use the POV's file system 
  
  'SaveData','SaveSky','LoadFile' are all string variables
      If they are null then Sky Factory ignores them
  
  There are many ways of saving a Sky, 
  'SaveData' saves the just the variables that are used to make a sky.
             they are stored with the declare statement
             these can be loaded from Sky Factory or any Pov file
  'SaveSky'  saves a file that can be rendered directly from POV or 
             to append to an existing POV file setting 'AddtoSky' to yes
             I've added a preview camera to this file because
             the default camera in Pov3.6 'right' statement
             clashes with my default 'right' statement
                'x*image_width/image_height'
             
  There are only one way to Load, use 'LoadFile'
   'LoadFile' uses includes to load anything
  It don't have to be the variables that ya save with 'SaveData'
   use your imaginaion

   One more thing you can use all three at the same time.
    Sky_factory will load first with 'LoadFile' then it saves using
    'SaveData' then it will save with 'SaveSky'. If 'LoadFile' is any-
    thing other than a variable list it won't be saved.

3.1============= SaveSky ====================

  Saving a file with 'SaveSky' saves only the data needed to make your sky.

  It saves only the pigments for the needed Clouds,if there are clouds.
   The Cloud pigments saved have unique names. All start with the prefix
   'P_Cloud' then comes the box size name 'L','M','H' Low,mid,High
    and lastly the position on the box 'n','f' near or far
   If the far and near cloud pigments of the same cloud Box  use the 
    same varibales then only the near pigment will be saved and used 
     
   It creates only the boxes needed for the Clouds 
    an unioned(if needed) object named 'LRClouds' 

   It makes a sky sphere.
   
   It also saves the Sky_Factory preview default camera.
   
   Take a look at 'Test.pov' for an example
   
4:============ Sky_sphere======================

  The Sky_sphere uses a pigment map and modifiers for background color 
     This pigment is name 'Sky_Pigment'
    
    There are 12 basic Sky_Spheres to choose from, numbered 0 to 11.
    'BackPig' is the variable that lets you choose Sky_spheres
 
    All use a pigment map with a light color to a dark color

    'Sky_Pigment'(0-5) use a gradient y pigment map with repeat warp
                      (I found this better than using planar)
                            this map range is 0 to 1 
    the next 6 (6-11) uses a cylinder pigment map with the same
                      colors as 0-5 I've scale these pigment maps 
                      by half so as to make a tighter center
                           this map range is 1 to 0 

    use 'BackRev' to reverse the pigment map color to dark to light


4.1 ============== Sky pigment maps ================
 
     since Sky_spheres 6-11  use the same colors as Sky_spheres 0-5
     here is a quick list colors Sky_spheres 0-5 uses
      0 white, black
      1 off white, dark blue
      2 cyan, light blue
      3 light purple  darker purple
      4 light gay darker gray
      5 light yellow darker yellow 

4.2 ============== Sky modifiers ================     
     
     'BackRotate'rotates sky_sphere pigment map
     'BackMap'   is the color_map point where the second color starts
                 the first color starts at 0 or 1
                              (depending on pigment see 4:) 
     'BackTurb'  is the turbulence of the pigment map
     'Back_Dc'   change the  sky_sphere colors by multiplying 
                 them with this
    
  
5:============ Cloud Boxes  ====================

  There can be 3 cloud boxes or no Clouds at All!!
            Each can cast a shadow!!

  'Boxn' controls what boxes are made. Each box has a power of 2 number.
   1 is the low box, 2 is the mid box, 4 is the high box
   add the appropriate number to 'Boxn' to make its box
    examples: 'Boxn=0' makes no boxes, 'Boxn=7' makes all the boxes
              'Boxn=3' makes the low and mid boxes
             
  You decide the size of the Middle box with 'BoxL' & 'BoxH',
   'BoxL' is the lowest corner & 'BoxH' is the upper corner.
  The High box and Low box sizes are determined by 'BoxD' 
  For their corners
  the high box adds 'BoxD' to 'BoxH' and subtracts 'BoxD' from 'BoxL',
  the low box subtracts 'BoxD' from 'BoxH' and adds 'BoxD' to 'BoxL'.

  The boxes are the frame which the clouds pigment rest. With all the 
  other variables the same, changing the boxes size can make a Big 
  difference. With 'BoxD' set low the cloud layers can blend into a
  feild of single looking clouds. With higher values the layers separate
  out witch give a deeper shy.
  
   EACH BOX HAS A SET OF VARIABLES TO MAKE ITS CLOUD TEXTURE.
   I ONLY SHOW THE LOW BOX VARIABLES FOR THE REST OF THIS 

   The mid box variables are exactly the same as the low boxs
   Except the 'L' in the name is replaced with 'M'

   And the High box variables are exactly the same as the low boxs
   Except the 'L' in the name is replaced with 'H'


5.1 ======== Cloud Pigment maps============
    
    The pigment map of a box is split between 2 cloud pigments
    'CloudLn'&'CloudLf' using gradient z and 'CloudL_Range' and
    is scaled using 'BoxH.z'.
    'CloudLn' is the clouds nearest the viewer.
    'CloudLf' is the clouds farther away.
    'CloudL_Range'is a vector, the first 2 values (x,y) determain 
      how the pigment map is made x is lower number and is where
      'CloudLn' pigment start to blend with the 'CloudLf' pigment.
       y is where the 'CloudLf' pigment starts
       
    'CloudLn'&'CloudLf' can use 6 Cloud pigments they are numbered 0-5
     If you use a number out of this range then 0 cloud pigment is used 

5.1.1 ======== Cloud 0 ============  
      this pigment is clear using rgbt 1
      its macro in Sky Factory is P_Cloud0()

5.1.2 ======== Cloud 1 ============  
      this pigment use bozo
      its macro in Sky Factory is P_Cloud1(Dark,Trans,Rot) 

5.1.3 ======== Cloud 2 ============  
      this pigment use wrinkles
      its macro in Sky Factory is P_Cloud2(Dark,Trans,Rot) 

5.1.4 ======== Cloud 3 ============  
      this pigment use granite
      its macro in Sky Factory is P_Cloud3(Dark,Trans,Rot) 

5.1.5 ======== Cloud 4 ============  
      this pigment use wrinkles
      its macro in Sky Factory is P_Cloud4(Dark,Trans,Rot) 

5.1.6 ======== Cloud 5 ============  
      this pigment use ripples
      its macro in Sky Factory is P_Cloud5(Dark,Trans,Rot) 


5.2 ========== Cloud pigment adjustments============

     there are several pigment adjustment that can be done
     some only affect the near pigment 'CloudLn'
          or only the far pigment 'CloudLn'
     some affect both or the boxes texture
          
    Let us start with the near pigment 'CloudLn'
     'CloudLn_Dc' changes the 'CloudLn' cloud colors by mutiplication
     'CloudLn_Ps' changes the 'CloudLn' cloud pigments by scaling
    The far pigment 'CloudLf'
     'CloudLn_Dc' changes the 'CloudLf' cloud colors by mutiplication
     'CloudLn_Ps' changes the 'CloudLf' cloud pigments by scaling

   The variables that change both far and near clouds 'CloudLn'&'CloudLf'
      'CloudL_Mv' ___ moves or translates the Clouds pigments
      'CloudL_Rot' ___rotates the Clouds pigments after translate
      'CloudL_Range'_is a vector, the first 2 values (x,y) determain 
                      how the box pigment map is made x is lower number
                      and is where 'CloudLn' pigment start to blend 
                      with the 'CloudLf' pigment. y is where the 
                      'CloudLf' pigment starts
       'CloudL_Turb'_is the turbulence vector that deforms 
                      the box pigment map the z value should always be 0
                      as all box pigments maps use 'gradient z'
       'CloudL_Amb'__is the ambient value in a boxes texture
                      this was added because I did have the 3 boxes with
                      their ambient value set so that the high box was 
                      bright then lower ambient values on down. This made
                      a certain type of cloud. Now you have more choises.
                      You can also use the ambient value to shade both
                      the far and near clouds with the same color. 
                      
       'CloudL_Shadow' although not a texture or pigment function
                       this is the last cloud box variable and its here
                       it lets the cloud box have a shadow the
                       default is no shadow  

5.3 ============= Box tips ================
   
    The boxes should be keep very large so they don't interfere with
   any scene objects. 
   The boxes are combine in a union object named LRClouds. 
   If you need to you can rotate and translate that object.

6: ============= Special Tricks =============    

  Multiple Cloud Boxes:
   If you find that 3 Cloud boxes are not enough then
   you can Call Sky Factory from a POV file several times,
   each time with different box sizes and other changes.
   Or you can change the variables in Sky Factory and save
   with 'SaveSky' and 'AddtoSky=yes'
  
   With this trick the last sky sphere will be the only one used
    PoV 3.6 can have only one sky sphere.
    
   The horison looks bad:
   If you cann't get the horison the way ya want then
   try rotating the Clock boxes object 'LRClouds' so that the top of
   the boxes is under the horisonal plane.
    
   Lightening:
    you can have a bolt of lightening if you have 
    'BackPig'<6 , 'BackMap'<.2 , 'BackTurb'!=<0,0,0>
    and 'BackRotate'=<0,0,90>
     with 'BackRotate' you can rotate in the y direction and 
     the z direction to make an animation lightening
    
   The sun:
    with 'BackPig'>5 you get a center of brightness, in that area
    it can be nice to put a sun. To do so have a large textured sphere
    position a long ways in the +z direction then use 'BackRot' to
    rotate it into place. checkout 'Sea.pov' 

7: ============= After Thoughts =============
   
   This started as a small file to help make a simple Sky. The
  more I played with it the more things I added. 
   I've test the Sky factory extensively, but that doesn't mean
  that I've caught all the bugs. If you find some bugs PLEASE!
          E-mail me about them (lrwii@joplin.com).
   Be sure to put POV in the subject or it may never be read.
   
    You can use Sky factory any way ya want. I would like credit
   if you make a master piece with its help. But I won't hunt you 
   down if you don't.
    I do ask that if you modify it by adding or deleting some functions 
   that you at least rename that file if you destribute it,
   so that I won't be getting e-mails about your modifications. 
   
   
   Variables I could have added but didn't:
   
     for Clouds a diffuse componet and double_illuminate
     I tested both and they make some good effects but my variable
     list is long enough already. And if you want you can always
     experiment with them on Clouds that Sky Factory had made and saved
   
   And of course all the turbulences lambda, omega, octaves 
   uses the defaults.
   
     