
			*******************
			*	RAD	  *
			*   Version 1.0   *
			*		  *
			*	by	  *
			*   G.Moreillon	  *
			*		  *
			*    July 1992	  *
			*******************



RAD USER'S MANUAL
=================


1. Introduction
   ------------

   Rad is a program that reads a text file describing a scene, and allows the
   user to walk through the scene while a radiosity solution for the scene is
   being computed.
   The user can also modify the caracteristics of the objects and see the
   effects of the modification propagate through the scene.
   The whole application is highly interactive, as everything is done with the
   mouse or the spaceball (the spaceball is not mandatory, but highly
   recommended).

2. Running Rad
   -----------

   Before running Rad you have to set up some environment variables. To do
   this, type "source .radrc", or put that line in your .login file. This
   short script will setup the environment variables so that Rad can find the
   location of the scenes, OFF files and textures.

   To run Rad, simply type "rad".

3. Loading a scene
   ---------------

   When Rad starts, no scene is loaded. To load a scene, push on the 'Load'
   button in the control panel. A file browser will appear, from which you can
   choose the scene you want to visualize/compute.
   There are two kind of files you can read a scene from:
     - the .rd files. Those are ASCII files describing scenes in their
       original state, that is, at the beginning of the computation.
     - the .rc files. Those are binary files describing the state of a
       computation for a scene. They are generated by Rad itself when you
       push the 'Save' button (see below).
   Once a scene is loaded (it can take some time, if the scene is big), it
   appears in the visualization window.

4. Starting the computation of a scene
   -----------------------------------

   The computation is done in parallel with the real time display, but to
   insure a smooth animation, the display has a higher priority than the
   computation. Thus, Rad only computes new radiosity solutions when it is not
   displaying. However, the algorithm is such that the display might be slowed
   down by the computation. Therefore a 'Hold' button has been provided that
   stops the computation when it is pushed, and let it run free again when
   pushed once more.
   When a scene is loaded from a .rd file (ASCII), the computation state is at
   the very beginning: only the light sources are visible in the scene.
   To start the computation, push on the 'Hold' button. If the button is blue,
   the computation is running, when it is red, the computation is stopped.
   When the computation is free to run, the dial on the right side of the
   control panel shows the activity of the CPU concerning the computation.
   If it doesn't move, either the computation is stopped ('Hold' button is
   red), or it is finished (the best solution Rad can compute has been
   reached) or the display is taking too much time to allow the computation to
   run.
   
5. Saving a scene
   --------------

   It is possible to save the current state of a computation by pushing the
   'Save' button. This will display a popup window asking you to type in the
   name of the file you want the scene to be saved in. The default name for
   that file is already displayed in the input field, and you usualy only have
   to hit Return to confirm the choice.
   If you want to change the name, you can do so by typing it in yourself, but
   be careful to specify a .rc extension.

6. Quitting Rad
   ------------

   To quit Rad, all you have to do is push on the 'Quit' button.

7. Modifying the global parameters
   -------------------------------

   A few global parameters can be modified directly through the control panel.

   7.1 Update Rate

       The number of frame per seconds you wish to have during the walkthrough
       of the scene can be modified with the slider named 'Update Rate' in the
       control panel.
       Setting a high update rate gives smoother movements, but usualy stops
       the computation.

   7.2 Aperture

       The aperture of the camera can be set using the 'Aperture' slider.
       The bigger the aperture, the greater the deformations of the picture
       due to the fish-eye effect.

   7.3 Translation step

       The translation step is the size of the step used when flying with the
       mouse. It has no effect on the spaceball.

   7.4 Rotation step

       The rotation step is the size of the step angle used when flying with
       the mouse. It has no effect on the spaceball.

8. Walking through a scene
   -----------------------

   There are two ways of doing this:

   8.1 With the spaceball

       That's the easiest way. Simply use the spaceball to move and turn the
       camera.

   8.2 With the mouse

       Less fun for sure...
       Be sure to be in Walkthrough mode before attempting to move.
       Press the left button of the mouse and move it in the direction you
       want to look. This will turn the camera the way you want, but you
       won't move.
       Press the middle button of the mouse and move it in the direction you
       want to go. This will turn the camera the way you want and move it in
       the direction you are looking.
       Note: when you move the mouse downward, the camera will go up, just like
       in a plane when you pull on the stick.

9. Modifying a scene
   -----------------

   Due to the nature of the algorithm, it is not possible to modify the
   geometry of a scene during the computation. Only the caracteristics of the
   objects composing the scene can be changed. They include:
     - Color or Texture
     - Reflectivity
     - Emissivity

   9.1 Selecting

       To modify an object, you first have to select it. To put the mouse in
       selection mode, hold down the RIGHT mouse button while in the
       visualization window, and choose 'Selection' in the popup menu.
       It is no more possible to move in the scene with the mouse, while in
       selection mode.
       To select an object, put the mouse cursor on it, and push the LEFT mouse
       button.
       When the object is selected, it becomes partly transparent. The
       triangle in the object that has been selected is hilighted, with all
       its subdivisions (if any). The selected triangle or subdivision is
       displayed in Gouraud shading with a different colors at each corner.
       Two more windows are displayed on the right side of the screen: the
       Radiosity window, and the Edit window.
       The Radiosity window displays the exact value (in RGB) of the computed
       Radiosity for each point of the selected triangle. The color of the
       corners in the 3D window and the color of the field in the Radiosity
       window correspond.

   9.2 Modifying
       The second window displayed is the Edit window. There are two different
       Edit windows, but only one of them is diplayed at a time. It depends if
       the selected objects has a texture or not. If it is not textured, then
       the regular Edit window is displayed, otherwise the Texture Edit window
       is drawn instead.

       9.2.1 Edit

	     The Edit window allows you to change the caracteristics of the
	     selected object, that is:
	       - The color: use the three color sliders
	       - The reflectivity: use the input field. The value should be
	         greater than 0.0 and less than 1.0
	       - The emissivity: use the input field. The values should be
		 greater than 0.0
	     Once everything is set up the way you like, push the 'Ok to
	     modify' button. The modification will be taken into account as
	     soon as the state of the computation allows it. Note that no
	     modification will be made while the computation is stopped.

	     If you want to map a texture on the selected object instead of
	     using a plain color, push on the 'Add Texture' button. This will
	     make you switch from the Edit panel to the Texture Edit panel.

       9.2.2 Texture Edit

	     The Texture Edit window allows you to change the caracteritics of
	     a textured object, that is:
	       - The texture: use the texture browser
	       - The scale of the texture: use the input field. The value
	         should be greater than 0.0
	       - The reflectivity: use the input field. The value should be
	         greater than 0.0 and less than 1.0
	       - The emissivity: use the input field. The values should be
		 greater than 0.0
	     The selected texture is mapped on the object along the Z axis of
	     the current camera coordinate system.

	     Once everything is set up the way you like, push the 'Bind &
	     Modify' button. The modification will be taken into account as
	     soon as the state of the computation allows it. Note that no
	     modification will be made while the computation is stopped.

	     If you want to use a plain color for the object instead of a
	     texture, push the 'No Texture' button.

10.Input File Format
   -----------------

   The format of the input file is rather simple and very readable. Its grammar
   is the following one:

   scene		: string UPAXIS axis composition
   axis			: XAXIS | YAXIS | ZAXIS
   composition		: complex | composition complex
   complex		: OBJECT string assembly
			| OBJECT string composite
			| simple
   assembly		: ASSEMBLY { composition }
   composite		: COMPOSITE { objects }
   objects		: simple | objects simple
   simple		: OBJECT string pure
   pure 		: PURE { caracteristic geometry }
   caracteristic	: base | texture base
   base			: REFLECTIVITY real COLOR vector
			  EMISS real SHADOWS state
   texture		: TEXTURE TFILE filename DIRECTION vector
			  VIEWUP vector SCALE real
   state		: ON | OFF
   geometry		: file | datas
   file			: TFILE filename
   datas		: DATA LEFTB pol_array RIGHTB
   pol_array		: poly | pol_array poly
   poly 		: vector vector vector
   vector		: < real real real >

   When you specify a geometry with a filename, the contents of that file has
   to be an object in OFF format (a simple universal text format. Check the
   many examples in the ./off directory). You need not specify the complete
   path to the OFF file, only the filename. The path used is the one held in
   the RADOFF environment variable.

   Several test scenes are provided in the ./scenes directory, check them out.

11.Scene hierarchy
   ---------------

   There are 3 kinds of objects in Rad scene, forming a hierarchy: Pure,
   Composite and Assembly.
   A Pure is an object composed of triangles exclusively. It has its own
   color/texture, reflectivity and emissivity. A voxel grid is associated to a
   Pure so that the ray/object intersection test for shadows computation is
   made a lot faster.
   A Composite is an object composed of Pures exclusively. A voxel grid is
   associated to a Composite. In that case, the Pures belonging to the
   Composite do not have a voxel grid for themselves, there is only one voxel
   grid for the whole group of Pures.
   An Assembly is an object composed of Assemblies, Composites and Pures. Only
   a bounding box is associated to an Assembly.

   The way to use that hierarchy is to tink of it as a way to organize a scene
   geometricaly. For example, suppose you want to create a simple scene of a
   room with four walls, a floor, a ceiling, a neon light, a table and a chair
   sitting next to the table.
   Suppose the table is made entirely out of wood. It will be a Pure.
   The chair is in metal except for the seat. The seat will be a Pure, the
   rest of the chair another, and the whole a Composite.
   Now, since the table and the chair are close together in an empty room, we
   can join them into an Assembly.
   The rest of the objects will be Pures.

   In short: Pures are groups of polygons of the same material, Composites are
   compact objects, and Assemblies are groups of various objects forming
   'regions' of space (a room in a building for instance).

12.Polygon meshes and boundaries
   -----------------------------

   When using Rad, there is a compromise to be made between the quality of the
   solution and the time you are willing to wait for it. The greater the number
   of polygons in a scene, the longer you will have to wait (and that rule goes
   in O(n2)).
   Thus, when building a scene, make sure small surfaces are NOT divided in
   hundreds of small triangles. It will take A LOT of time to compute their
   illumination, and even though the result will be good, a much smaller
   number of polygons will do the job just as well.

   There is one thing you have to know when using Rad: the radiosity values are
   computed at the triangles' vertices, and NEVER inside the triangle.
   Consequently, make sure that great surfaces are cut into smaller polygons,
   otherwise the illumination computed for those surfaces could be terribly
   wrong.

   Also, be careful with the polygon boundaries at the edges of the surfaces:
   polygons should not hide one another. For example, at the point where a
   floor and a wall meet, the polygons of the floor and the ones of the wall
   should use the same vertices (that is the same coordinates), and the floor
   should never continue a little way behind the wall. If that is the case, the
   edge of the floor will be hidden from the light by the edge of the wall,
   and it will be dark instead of being illuminated.

		|				|
		|   Wall			|   Wall
		|				|
		|				|
	       ------------ Floor		----------- Floor

		    Wrong			    Right

   One more thing: each triangle in the scene can be subdivided automatically
   by Rad in order to follow more accurately the gradient of illumination on
   that triangle. The number of polygon can easily double during the
   computation, slowing down the display and the computation.

13.Hints
   -----

   If you want the computation to go faster, cut on the Update Rate, and vice
   versa. The display has the priority, but the computation slows it down
   anyway.
