home *** CD-ROM | disk | FTP | other *** search
/ Graphics Plus / Graphics Plus.iso / general / raytrace / radiance / simplerd.lha / simplerad / FinalFTP / README < prev   
Encoding:
Text File  |  1992-07-20  |  11.7 KB  |  359 lines
  1.  
  2.  
  3.  
  4.             A "LIGHT" RADIOSITY PACKAGE            
  5.  
  6.  
  7.     This is the complete code to the radiosity implementation
  8.     written as part of my Masters Thesis work at York University,
  9.     Canada. It implements some of the more recent techniques
  10.     by Wallace89, Baum91, and others. Included is a radiosity
  11.     program, some utilities, and a scene walk-through program.
  12.  
  13.     A complete explanation of the algorithms in this package
  14.     are given in my thesis paper (also available via ftp).
  15.     I will only give a brief summary of some user points in this
  16.     file.
  17.  
  18.  
  19.  
  20.     1. INSTALLATION
  21.     ---------------
  22.  
  23.     All the files in this package have been archived using tar.
  24.     All files are in uncompressed format to avoid any transfer
  25.     problems. 
  26.  
  27.  
  28.     a) MAIN RADIOSITY PROGRAM and UTILITIES
  29.  
  30.     For machines running Sun/OS: to install the radiosity program,
  31.     some data files for geometric primitives, and some conversion 
  32.     programs to convert from Quickmodel(tm) or OFF format to the format
  33.     used in this package, just type make from the FinalFTP 
  34.     directory. 
  35.  
  36.     For Silicon Graphics machines: Modify the Makefile in
  37.     subdirectory Light first, as some of code differs for the
  38.     main radiosity program. Again just type make from the FinalFTP
  39.     directory.
  40.  
  41.     Following the make, the following executables, and data files 
  42.     will be created:
  43.  
  44.     /Light/(4d)lightR     : The main radiosity program. (4d)
  45.                   if you compile the IRIS version.
  46.     /Prims/data/        : Directory containing input files
  47.                   with meshed primitives for the main
  48.                   program.
  49.     /Prims/mprims        : Utility to create the above files.
  50.     /Conv/Qmodel/qm2patch    : QuickModel to radiosity program format
  51.     /Conv/Off/off2pat    : OFF (geometry only) to radiosity program 
  52.                   format
  53.  
  54.  
  55.     b) WALK-THROUGH PROGRAM
  56.  
  57.     The walk-through program is written using GL for a Silicon
  58.     Graphics workstation, so naturally won't compile on any
  59.     other machine.
  60.  
  61.     From the WalkT directory type "make" to make the walk-through
  62.     program. A file called walkR is created in this directory.
  63.  
  64.  
  65.  
  66.  
  67.     2. USAGE
  68.     --------
  69.  
  70.     The subdirectory Data contains some sample input 
  71.     data files. 
  72.  
  73.  
  74.     a) MODEL INPUT FILES (.pat files)
  75.  
  76.     The basic format of the input files is as follows, where the stuff
  77.     between brackets <> is defined by you:
  78.     
  79.     ----------------------------------------------------------------------
  80.  
  81.     Number objects <number-of-objects-in-this-file>
  82.     Object <name-of-object> <object-type> {
  83.       OWMatrix <object-to-world-matrix-name> { <ow-matrix> }
  84.       Prop <property-name> { E{ <energyRGB> p{ <reflectanceRGB> } Kd{ <kd } Ks{ <ks> }
  85.       NumMeshes <number-of-meshes>
  86.       <addition-mesh-info-if-required>
  87.     }
  88.  
  89.     ----------------------------------------------------------------------
  90.     
  91.     where:
  92.  
  93.     <number-of-objects-in-this-file> : gives the number of "objects" defined
  94.         in this data file, and is given as a integer.
  95.         An "Object" definition is required for this many objects.
  96.     <object-type> is one of: cube, mesh, cone, cylinder, or sphere.
  97.         Note that each of the above may be prepended by the word "pre"
  98.         [to indicate to premesh the object into elements], and a
  99.         number may be appended to define the number of subdivision levels.
  100.         All subdivision is bilinear.
  101.         
  102.         For example: 
  103.  
  104.             premesh2 
  105.  
  106.         would mean subdivide each patch in the mesh into elements 16 elements.
  107.         A maximum of 5 levels is currently allowed.
  108.  
  109.     <ow-matrix> is the transformation from object-space to world-space for
  110.         the current object being defined. The matrix is defined as follows
  111.         for an example matrix:
  112.  
  113.         a d g j  
  114.         b e h k
  115.         c f i l
  116.         x x x x
  117.  
  118.         is given as: a b c d e f g h i j k l
  119.         The last row "x x x x" is assumed to be 0 0 0 1, and is not specified.
  120.  
  121.     <energyRGB>, and <reflectanceRGB>: give the RGB triple for defining
  122.         the energy and reflectance of the object, respectively. A triple is 
  123.         given as three floating-point numbers seperated by spaces.
  124.     <kd> and <ks> give the diffuse and specular components such that kd + ks should
  125.         equal 1.0
  126.     NumMeshes <number-of-meshes> defines the number of meshes used to define
  127.         the object. NOTE: <number-of-meshes> should equal to -1 when
  128.         if the <object-type> is NOT a mesh. This basically signifies that
  129.         the mesh information is stored in external data files (the ones
  130.         mentioned above). 
  131.  
  132.         Otherwise the <addition-mesh-info-if-required> part is required. 
  133.         This part has the following syntax, for <number-of-meshes> 
  134.         number of meshes:
  135.  
  136.         ----------------------------------------------------------------------
  137.  
  138.         Mesh <mesh-name> <number-of-patches> {
  139.           Patch <normal-name> <number-of-vertices> { <point-xyz>... }
  140.           Patch <vertex-name> <number-of-vertices> { <point-xyz>... }        
  141.           <rest-of-patch-info>
  142.         }
  143.  
  144.         ----------------------------------------------------------------------
  145.  
  146.         where:
  147.  
  148.         <number-of-patches> is the number of patches for the current mesh.
  149.         <number-of-vertices> is the number of vertices for the current patch
  150.         <point-xyz> is a 3-D xyz coordinate defined as: { <x> <y> <z> }.
  151.         <rest-of-patch-info> means that the two lines defining normals and 
  152.             vertices is repeated for each patch. NOTE that vertices are 
  153.             assumed to be defined in counter-clockwise order, with the 
  154.             normal facing "upward" from the face of the patch, with 
  155.             vertices read is this order.    
  156.  
  157.     ** Examples are given in the Data directory
  158.  
  159.         cubein2.pat: is a simple meshed box scene
  160.         cubein2p.pat: is a simple meshed box scene with premeshing into elements.
  161.         l.pat: is a simple scene with a cube, cone, cylinder and sphere.
  162.  
  163.  
  164.     b) CAMERA INPUT MODELS (.vw files)
  165.  
  166.     For the IRIS version a camera position may be given to view the solution
  167.     as it progresses. The format of the file is:
  168.  
  169.     Camera {
  170.             lookfrom <point-xyz>
  171.             lookat <point-xyz>
  172.             lookup <point-xyz>
  173.             fovx <fovx> fovy <fovy> near <near> far <far>
  174.             xRes <xres> yRes <yres>
  175.         bank <bank>
  176.     }
  177.  
  178.     where <point-xyz> is a point in 3D, fovx, fovy defines the field of view
  179.     in x and y, near and far the positions of the near and far plane, and
  180.     xres and yres the resolution of the display window. bank is the bank angle
  181.     for the camera.
  182.  
  183.  
  184.     c) OUTPUT FILES
  185.  
  186.     The following files may be output depending on the options set for running:
  187.  
  188.     <input-file-name>.scene : Scene description after radiosity simulation;
  189.         used for walk-through program.
  190.         If the -I option is used files with suffix scene<n> will result,
  191.         where <n> is the iteration number stored. (See below under EXECUTION)
  192.     <input-file-name>.scene.opt : if the -O option is specified. Gives
  193.         output suitable for Optik instead of walk-through program.
  194.     <input-file-name>.conv : Convergence given as iteration number, percent
  195.             energy left ordered pairs.
  196.     <input-file-name>.stat : Some exectution statistics.
  197.     
  198.  
  199.     d) EXECUTION OF MAIN PROGRAM
  200.  
  201.     - SYNTAX 
  202.  
  203.     The syntax for executing the main program is as follows:
  204.  
  205.     lightR [-dhsVNO] (-f 0/1 0/1/2) (-R 0/1 s) (-p scene) (-v eye) (-I n i1 ... in)
  206.  
  207.     where:
  208.             d : Set debug mode
  209.             f : 0/1 = use hemicube or ray casting form-factor algorithm.
  210.               (Hemicube only available on IRIS)
  211.                 0/1/2 = use either circle, ellipse, or analytic form-factor
  212.             approximations.
  213.             p : Set patch input filename
  214.             s : Statistics: 0 = to stdout or 1 = to file
  215.             I : Storage of intermedieate results
  216.                 n = number of iterations to output, i_n = iteration number
  217.             N : Set to NTSC window mode           # Only or IRIS
  218.         O : Output scene in Optik format.
  219.             V : Record to VCR in NTSC mode        # Not currently available.
  220.                             # Naturally a NTSC video tape
  221.                             # recorder is required, as
  222.                             # well as code segments for
  223.                             # using on your given vcr. See
  224.                             # the Makefile as well as the 
  225.                             # vcr.c.example vcr.h and vcrS.c 
  226.                             # code for more details...
  227.             R : 0 = don't, 1 = ray cast with s samples per visibility test per
  228.                 patch vertex.
  229.             h : Short help message
  230.  
  231.     As an example:
  232.     
  233.         lightR -f 1 0 -R 1 4 -p test.patch -v test.view -s 1 -O 1
  234.  
  235.     would using file test.patch as the input scene, and test.view as the camera
  236.     position to view intermediate results from; use ray casting to compute
  237.     form-factors using a circle approximation, and send statistics to file 
  238.     such that data is stored in Optik format.
  239.  
  240.     ** NOTE: ENVIRONMENT VARIABLES **
  241.  
  242.     A number of environment variables may be set to define additional options
  243.     for execution. Refer to the file "radopts" for more details. THESE VARIABLES
  244.     SHOULD BE SET AT THE BEGINNING OF AN EXECUTION -- Especially so
  245.     if you intend to use the data files for premeshed primitives !!
  246.  
  247.     Just use source to read in the source commands to set the variables.
  248.  
  249.  
  250.     e) EXECUTION OF WALK-THROUGH PROGRAM
  251.  
  252.     As mentioned the walk-through program will only run on an IRIS 4D series machine.
  253.  
  254.     - SYNTAX
  255.  
  256.     The syntax for executing the walk-through program is a follows:
  257.  
  258.         walkR [-dghBW] [-s #] [[-w x y x y] -p patch-file
  259.  
  260.     where:
  261.             d : Run in debug mode
  262.         g : Use gamma correction
  263.             h : This help message
  264.             n : Set to NTSC mode
  265.             p : Set patch file to use
  266.         s : RGB scale factor (for display)
  267.             v : Record to VCR in NTSC mode        # See vcr notice above.
  268.         w x y x y : window origin(x,y) and size(x,y)
  269.             B : Black and white mesh rendering
  270.             W : Display on full screen
  271.  
  272.     As an example:
  273.  
  274.         walkR -w 10 10 512 480 -B -p test.patch.scene
  275.  
  276.     will display the scene stored in the file test.patch.scene at position 10,10
  277.     with size 512 by 480, and when the option to show the scene as a mesh is chosen,
  278.     the mesh will be displayed in black and white.
  279.  
  280.     For more details as to the operation of program see the HELP file in the
  281.     WalkT directory. The same help is also available while the program is
  282.     running via the program menus.
  283.  
  284.     - ANIMATION FILES
  285.  
  286.     Animating walk-throughs the scene may be accomplished (in a primitive way)
  287.     by either interactively keying a set of moves into a "animation file", or via
  288.     the walk-through program itself.
  289.  
  290.     To store movements through the scene vie the application you need
  291.     to go to the Log menu. To record the actions desired use the Start
  292.     menu option to start recording and the Stop option to stop. Once a
  293.     sequence of moves has been performed, they may be saved vie the Save option
  294.     The Automate option naturally automates any saved sequence of moves.
  295.  
  296.     As moves are saved to file, they can naturally be hand-edited, or created.
  297.     The syntax of moves is as follows: The first line must always be:
  298.  
  299.         nmoves <number-of-moves-in=file>
  300.  
  301.     where <number-of-moves-in=file> is the number of movements stored in the file.
  302.     For this many movements a "move" is of the form:
  303.  
  304.     Move <movement-type> {
  305.         <movement-parms>
  306.     }
  307.  
  308.     where
  309.         movement-type : is 
  310.             A = move to absolute position in the scene
  311.             T = translate in the x and y directions (left/right, up/down)
  312.             Z = zoom (translate) in the z direction (forward with respect to 
  313.                 the viewing direction)
  314.             R = rotate up/down or left/right about the current viewing 
  315.                 direction defined by a x or y axis rotation.
  316.             P = spin about the "up" direction relative to the current viewing 
  317.                 direction defined by a z axis rotation
  318.  
  319.     For an ABSOLUTE move the following syntax is required:
  320.  
  321.             lookFrom <point-xyz>
  322.             lookAt <point-xyz>
  323.             lookUp <point-xyz>
  324.             fovx <fovx> fovy <fovy> near <near> far <far>
  325.             xRes <xres> yRes <yres>
  326.         bank <bank>
  327.  
  328.     analagous to the camera position information description given above.
  329.  
  330.     For a RELATIVE move, the following synatx is required:
  331.  
  332.         x y z
  333.  
  334.     where x,y,z provide the axis about which the movement-type is being performed.
  335.     
  336.  
  337.     3. SUPPORT
  338.     ----------
  339.  
  340.     This package is presented as is. There should hopefully be
  341.     no problems, but just in case, I will try to actively support
  342.     this package considering the availability of time.
  343.  
  344.     Please let me know of any comments, bugs, upgrades, etc. 
  345.     at the following address:
  346.  
  347.     g-kwok@cs.yorku.ca
  348.  
  349.     Hope this package is of some use !
  350.     Have fun,
  351.  
  352.             Bernard Kwok (former grad student)
  353.             York University, Toronto
  354.             Ontario, Canada
  355.             M.. ...
  356.             
  357.  
  358.     
  359.