


			A "LIGHT" RADIOSITY PACKAGE			


	This is the complete code to the radiosity implementation
	written as part of my Masters Thesis work at York University,
	Canada. It implements some of the more recent techniques
	by Wallace89, Baum91, and others. Included is a radiosity
	program, some utilities, and a scene walk-through program.

	A complete explanation of the algorithms in this package
	are given in my thesis paper (also available via ftp).
	I will only give a brief summary of some user points in this
	file.



	1. INSTALLATION
	---------------

	All the files in this package have been archived using tar.
	All files are in uncompressed format to avoid any transfer
	problems. 


	a) MAIN RADIOSITY PROGRAM and UTILITIES

	For machines running Sun/OS: to install the radiosity program,
	some data files for geometric primitives, and some conversion 
	programs to convert from Quickmodel(tm) or OFF format to the format
	used in this package, just type make from the FinalFTP 
	directory. 

	For Silicon Graphics machines: Modify the Makefile in
	subdirectory Light first, as some of code differs for the
	main radiosity program. Again just type make from the FinalFTP
	directory.

	Following the make, the following executables, and data files 
	will be created:

	/Light/(4d)lightR 	: The main radiosity program. (4d)
				  if you compile the IRIS version.
	/Prims/data/		: Directory containing input files
				  with meshed primitives for the main
				  program.
	/Prims/mprims		: Utility to create the above files.
	/Conv/Qmodel/qm2patch	: QuickModel to radiosity program format
	/Conv/Off/off2pat	: OFF (geometry only) to radiosity program 
				  format


	b) WALK-THROUGH PROGRAM

	The walk-through program is written using GL for a Silicon
	Graphics workstation, so naturally won't compile on any
	other machine.

	From the WalkT directory type "make" to make the walk-through
	program. A file called walkR is created in this directory.




	2. USAGE
	--------

	The subdirectory Data contains some sample input 
	data files. 


	a) MODEL INPUT FILES (.pat files)

	The basic format of the input files is as follows, where the stuff
	between brackets <> is defined by you:
	
	----------------------------------------------------------------------

	Number objects <number-of-objects-in-this-file>
	Object <name-of-object> <object-type> {
	  OWMatrix <object-to-world-matrix-name> { <ow-matrix> }
	  Prop <property-name> { E{ <energyRGB> p{ <reflectanceRGB> } Kd{ <kd } Ks{ <ks> }
	  NumMeshes <number-of-meshes>
	  <addition-mesh-info-if-required>
	}

	----------------------------------------------------------------------
	
	where:

	<number-of-objects-in-this-file> : gives the number of "objects" defined
		in this data file, and is given as a integer.
		An "Object" definition is required for this many objects.
	<object-type> is one of: cube, mesh, cone, cylinder, or sphere.
		Note that each of the above may be prepended by the word "pre"
		[to indicate to premesh the object into elements], and a
		number may be appended to define the number of subdivision levels.
		All subdivision is bilinear.
		
		For example: 

			premesh2 

		would mean subdivide each patch in the mesh into elements 16 elements.
		A maximum of 5 levels is currently allowed.

	<ow-matrix> is the transformation from object-space to world-space for
		the current object being defined. The matrix is defined as follows
		for an example matrix:

		a d g j  
		b e h k
		c f i l
		x x x x

		is given as: a b c d e f g h i j k l
		The last row "x x x x" is assumed to be 0 0 0 1, and is not specified.

	<energyRGB>, and <reflectanceRGB>: give the RGB triple for defining
		the energy and reflectance of the object, respectively. A triple is 
		given as three floating-point numbers seperated by spaces.
	<kd> and <ks> give the diffuse and specular components such that kd + ks should
		equal 1.0
	NumMeshes <number-of-meshes> defines the number of meshes used to define
		the object. NOTE: <number-of-meshes> should equal to -1 when
		if the <object-type> is NOT a mesh. This basically signifies that
		the mesh information is stored in external data files (the ones
		mentioned above). 

		Otherwise the <addition-mesh-info-if-required> part is required. 
		This part has the following syntax, for <number-of-meshes> 
		number of meshes:

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

		Mesh <mesh-name> <number-of-patches> {
		  Patch <normal-name> <number-of-vertices> { <point-xyz>... }
		  Patch <vertex-name> <number-of-vertices> { <point-xyz>... }		
		  <rest-of-patch-info>
		}

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

		where:

		<number-of-patches> is the number of patches for the current mesh.
		<number-of-vertices> is the number of vertices for the current patch
		<point-xyz> is a 3-D xyz coordinate defined as: { <x> <y> <z> }.
		<rest-of-patch-info> means that the two lines defining normals and 
			vertices is repeated for each patch. NOTE that vertices are 
			assumed to be defined in counter-clockwise order, with the 
			normal facing "upward" from the face of the patch, with 
			vertices read is this order.	

	** Examples are given in the Data directory

		cubein2.pat: is a simple meshed box scene
		cubein2p.pat: is a simple meshed box scene with premeshing into elements.
		l.pat: is a simple scene with a cube, cone, cylinder and sphere.


	b) CAMERA INPUT MODELS (.vw files)

	For the IRIS version a camera position may be given to view the solution
	as it progresses. The format of the file is:

	Camera {
	        lookfrom <point-xyz>
        	lookat <point-xyz>
        	lookup <point-xyz>
        	fovx <fovx> fovy <fovy> near <near> far <far>
        	xRes <xres> yRes <yres>
		bank <bank>
	}

	where <point-xyz> is a point in 3D, fovx, fovy defines the field of view
	in x and y, near and far the positions of the near and far plane, and
	xres and yres the resolution of the display window. bank is the bank angle
	for the camera.


	c) OUTPUT FILES

	The following files may be output depending on the options set for running:

	<input-file-name>.scene : Scene description after radiosity simulation;
		used for walk-through program.
		If the -I option is used files with suffix scene<n> will result,
		where <n> is the iteration number stored. (See below under EXECUTION)
	<input-file-name>.scene.opt : if the -O option is specified. Gives
		output suitable for Optik instead of walk-through program.
	<input-file-name>.conv : Convergence given as iteration number, percent
			energy left ordered pairs.
	<input-file-name>.stat : Some exectution statistics.
	

	d) EXECUTION OF MAIN PROGRAM

	- SYNTAX 

	The syntax for executing the main program is as follows:

	lightR [-dhsVNO] (-f 0/1 0/1/2) (-R 0/1 s) (-p scene) (-v eye) (-I n i1 ... in)

	where:
	        d : Set debug mode
	        f : 0/1 = use hemicube or ray casting form-factor algorithm.
			  (Hemicube only available on IRIS)
	            0/1/2 = use either circle, ellipse, or analytic form-factor
			approximations.
        	p : Set patch input filename
	        s : Statistics: 0 = to stdout or 1 = to file
	        I : Storage of intermedieate results
	            n = number of iterations to output, i_n = iteration number
	        N : Set to NTSC window mode   		# Only or IRIS
		O : Output scene in Optik format.
	        V : Record to VCR in NTSC mode		# Not currently available.
							# Naturally a NTSC video tape
							# recorder is required, as
							# well as code segments for
							# using on your given vcr. See
							# the Makefile as well as the 
							# vcr.c.example vcr.h and vcrS.c 
							# code for more details...
	        R : 0 = don't, 1 = ray cast with s samples per visibility test per
				patch vertex.
	        h : Short help message

	As an example:
	
		lightR -f 1 0 -R 1 4 -p test.patch -v test.view -s 1 -O 1

	would using file test.patch as the input scene, and test.view as the camera
	position to view intermediate results from; use ray casting to compute
	form-factors using a circle approximation, and send statistics to file 
	such that data is stored in Optik format.

	** NOTE: ENVIRONMENT VARIABLES **

	A number of environment variables may be set to define additional options
	for execution. Refer to the file "radopts" for more details. THESE VARIABLES
	SHOULD BE SET AT THE BEGINNING OF AN EXECUTION -- Especially so
	if you intend to use the data files for premeshed primitives !!

	Just use source to read in the source commands to set the variables.


	e) EXECUTION OF WALK-THROUGH PROGRAM

	As mentioned the walk-through program will only run on an IRIS 4D series machine.

	- SYNTAX

	The syntax for executing the walk-through program is a follows:

		walkR [-dghBW] [-s #] [[-w x y x y] -p patch-file

	where:
	        d : Run in debug mode
		g : Use gamma correction
	        h : This help message
	        n : Set to NTSC mode
	        p : Set patch file to use
		s : RGB scale factor (for display)
	        v : Record to VCR in NTSC mode		# See vcr notice above.
		w x y x y : window origin(x,y) and size(x,y)
	        B : Black and white mesh rendering
	        W : Display on full screen

	As an example:

		walkR -w 10 10 512 480 -B -p test.patch.scene

	will display the scene stored in the file test.patch.scene at position 10,10
	with size 512 by 480, and when the option to show the scene as a mesh is chosen,
	the mesh will be displayed in black and white.

	For more details as to the operation of program see the HELP file in the
	WalkT directory. The same help is also available while the program is
	running via the program menus.

	- ANIMATION FILES

	Animating walk-throughs the scene may be accomplished (in a primitive way)
	by either interactively keying a set of moves into a "animation file", or via
	the walk-through program itself.

	To store movements through the scene vie the application you need
	to go to the Log menu. To record the actions desired use the Start
	menu option to start recording and the Stop option to stop. Once a
	sequence of moves has been performed, they may be saved vie the Save option
	The Automate option naturally automates any saved sequence of moves.

	As moves are saved to file, they can naturally be hand-edited, or created.
	The syntax of moves is as follows: The first line must always be:

		nmoves <number-of-moves-in=file>

	where <number-of-moves-in=file> is the number of movements stored in the file.
	For this many movements a "move" is of the form:

	Move <movement-type> {
		<movement-parms>
	}

	where
		movement-type : is 
			A = move to absolute position in the scene
			T = translate in the x and y directions (left/right, up/down)
			Z = zoom (translate) in the z direction (forward with respect to 
			    the viewing direction)
			R = rotate up/down or left/right about the current viewing 
			    direction defined by a x or y axis rotation.
			P = spin about the "up" direction relative to the current viewing 
			    direction defined by a z axis rotation

	For an ABSOLUTE move the following syntax is required:

	        lookFrom <point-xyz>
        	lookAt <point-xyz>
        	lookUp <point-xyz>
        	fovx <fovx> fovy <fovy> near <near> far <far>
        	xRes <xres> yRes <yres>
		bank <bank>

	analagous to the camera position information description given above.

	For a RELATIVE move, the following synatx is required:

		x y z

	where x,y,z provide the axis about which the movement-type is being performed.
	

	3. SUPPORT
	----------

	This package is presented as is. There should hopefully be
	no problems, but just in case, I will try to actively support
	this package considering the availability of time.

	Please let me know of any comments, bugs, upgrades, etc. 
	at the following address:

	g-kwok@cs.yorku.ca

	Hope this package is of some use !
	Have fun,

			Bernard Kwok (former grad student)
			York University, Toronto
			Ontario, Canada
			M.. ...
			

	
	