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



PREPRAD USER'S MANUAL
=====================


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

    Preprad is a program that reads a text file describing a scene in Rad
    format, and allows the user to modify the hierarchy of the scene as well
    as the caracteristics of the objects composing the scene. Preprad creates
    several file as output: a scene description file in Rad format as well as
    an OFF file for each object in the scene.
    The user can walk through the scene in real time and select the objects and
    polygons forming them by pointing them with the mouse.
    A spaceball is required to run this program.

2.  Running Preprad
    ---------------

    Before running Preprad 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 Prepad can find
    the location of the scenes, OFF files and textures.

    To run Preprad, simply type "preprad".

3.  Display description
    -------------------

    At least three windows are displayed at any one time during Preprad's
    execution.

    3.1	The Control panel

	It enables you to control Preprad in general (load/save file, global
	parameters,...)

    3.2	The Visualization window

	That's where the scene is displayed, and where you can act upon it.

    3.3	The Hierarchy window

	The hierarchy of the scene is graphicaly represented in that window.
	Each object, Pure, Composite or Assembly is pictured as a blue square.
	If it is a Composite or an Assembly, its sons are attached to it by
	yellow lines.
	It is possible to interact directly with the hierarchy (see below).
	
4.  Loading a scene
    ---------------

    When Preprad 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 work on.

    Once a scene is loaded (it can take some time, if the scene is big), it
    appears in the visualization window.

5.  Writing a scene
    ---------------

    Once a scene is set up the way you want, or if you need to save the
    current state of your work, you can write the description of the scene in
    a file in Rad format. To do that, push on the 'Write' button. A popup
    window will appear letting you enter the name of the output file.
    The scene can then be reloaded at a later time either by Preprad or by Rad.

6.  Quitting Preprad
    ----------------

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


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

    A few options are offered to modify the display.

    7.1	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.2	Normals display

	When this button is activated (light on), the normal of the selected
	triangles (if any) are displayed.

    7.3	Bounding-boxes display

	When this button is activated (light on), the bounding boxe of each
	object is displayed. The bounding-boxes of the selected objects (if
	any) are red while the others are yellow.

8.  Modifying the scene
    -------------------

    The scope of modification offered by Preprad is limited. It is possible to
    modify the hierarchy of the scene and the caracteristics of the objects,
    but not their shape or position.

    8.1 Polygons

	8.1.1 Selecting Polygons

	    To select polygons in a scene, click on it with the LEFT mouse
	    button. It will become red, and its normal will be displayed if
	    normals display is enabled.

	8.1.2 Inverting a polygon's normal

	    It can happen that some polygon's normal is facing the wrong way
	    (pointing towards the inside of the object). It is necessary to
	    invert those normals, otherwise the radiosity computation can't be
	    made correctly. Polygons that have inverted normals appear dark
	    when you face them with the camera (that is because the light
	    source is always attached to the camera in Preprad).
	    To invert a polygon's normal, first select it (see above), then
	    choose in the window's menu (hold down the RIGHT mouse button to
	    display it) the 'Flip Normals' option. It will invert the normal
	    of each selected polygon in the scene.

	8.1.3 Subdiving a polygon

	    Sometimes, you may wish to break a polygon in several smaller ones
	    so that the computation of the radiosity for the scene gives better
	    results. It is possible to do that to a certain extent with
	    Preprad.
	    First select the polygon(s) you want to subdivide, then choose the
	    'Split Polygons' option. Each selected triangle will be subdivided
	    in four smaller triangles of equal surfaces.
	    Once a triangle is subdivided, it can not be glued back together.

    8.2 Objects

	8.2.1 Selecting objects

	    There are two ways of selecting objets in a scene:
	    Either select an object directly in the Visualization window by
	    clicking on it with the MIDDLE mouse button, or click with the LEFT
	    mouse button on the corresponding square in the hierarchy window.
	    The selected object will become blue in the Visualization window,
	    and red in the hierarchy window.

	8.2.2 Hiding objects

	    To make polygon selection easier, it is possible to 'hide' an
	    object in the scene. A hidden object becomes partly transparent
	    and inexistant for polygon selection. It is, however, still
	    selectable, as an object.
	    To hide an object, click on it in while holding the keyboard's 
	    Control key down (either in the Visualization window or the
	    hierarchy window).

	8.2.3 Modifying an object

	    To modify and object's caracteristics, first select the object you
	    want to modify, then push on the 'Modify Object' button in the
	    control panel. This will display one of the two Object Edit
	    windows. If the selected object is not textured, the regular Edit
	    window is displayed, otherwise the Texture window is appears
	    instead. Both windows let you see the caracteristics of the
	    selected object:
	     - Color/Texture
	     - Reflectivity
	     - Emissivity
	     - Name
	     - Shadows flag
	    If you want to modify one or more of those caracteristics, simply
	    enter a new value for it (Reflectivity, Emissivity, Name), push on
	    the corresponding button (Shadows flag), or use the appropriate
	    device (Color, Texture). To change a color, use the three color
	    sliders, to change a texture, choose it in the browser and enter a
	    new scale factor if need be.
	    If you wish to add a texture if there is none, or remove it if
	    there is one, push on the corresponding button in the current
	    panel ('Add Texture' or 'No Texture' button).
	    Once a all the modifications are made, confirm the new
	    caracteristics by clicking on the 'Ok' button. If you wish to
	    cancel the whole modification, click on 'Cancel'.
	    While one of the Object Edit window is displayed, no interaction
	    with the other panels or with the scene is possible.

	8.2.4 Creating an object

	    It is possible to create a new object by selecting polygons in the
	    scene and pushing on the 'Create Object' button. The selected 
	    polygons can belong to several different objects. When the 'Create
	    Object' button is pushed, the Edit window is displayed (see above)
	    and you can define the object's caracteristics using it. The new
	    object is put in the scene at the lowest level.

    8.3	Hierarchy

	8.3.1 Joining objects

	    To join several objects into a new group (Composite or Assembly),
	    you first have to select the objects you want to join, then click
	    on the 'Join Objects' button. The selected objects must all have
	    the same father.

	8.3.2 Splitting an object

	    If you want to 'ungroup' some objects, select their father, and
	    click on the 'Split Object' button. It will destroy the selected
	    object and lower down its sons to the its own level.

	8.3.3 Moving an object

	    Sometimes, you might want to take an object from a group and move
	    it to another one. To do that in Preprad, simply drag the object's
	    box in the hierarchy display to the father of the group you want
	    to put it in, and release the mouse button. A yellow square will
	    follow the mouse while you drag it along in the window.

	8.3.4 Merging objects

	    If you want to merge an object into another one (it is one way to
	    destroy an object), that is, add an object's polygons to another
	    object, simply drag the object's box to the object you want to
	    merge it in. A popup window will appear asking you to confirm the
	    merge, since there is no easy way to undo the operation. Once the
	    merge is confirmed, the Object Edit window will appear with the
	    caracteristics of the receiving object. You then have the
	    opportunity to change those caracteristics before confirming again
	    the operation by clicking on the 'Ok' button.

	8.3.5 Destroying objects

	    Although Preprad is not meant to actually modify a scene's
	    geometry, it is possible to destroy an object, of any kind, by
	    selecting it and clicking on the 'Destroy Object' button. A popup
	    window will ask for confirmation. Once an object is destroyed
	    there is NO WAY to recover it, so be careful.

9.  Hints
    -----

    When extracting an object out of another one by selecting polygons,
    remember to hide the objects you don't want to select polygons from, it
    makes life a lot easier.

    If you want to add some polygons to an already existing object, select
    those polygons, make an object out of it (no need to give it a name or any
    kind of special caracteristics), then merge the new object into the one
    you want to extend.

    Remember when making groups, take into account only the geometry of the
    groups, not the logic of them. That is, don't group togheter all the
    chairs of a house for example. It might be logical, but it is probably not
    interesting from the geometrical point of view. Groups (especially 
    composites) should be compact gatherings of objects so that when building
    a voxel grid through it, all voxels are filled by a similar amount of
    polygons.

10. About the output
    ----------------

    Preprad generates several files when you 'write' a scene.
    The most important is the scene description file (.rd). It is written in
    the default scene directory (defined by RADSCENE). It references an OFF
    file for each object. Those OFF files are placed in a subdirectory in the
    default OFF directory (defined by RADOFF). The name of the subdirectory is
    the name of the file that holds the scene description, without the .rd
    extension.
    The OFF files are not as small as they could be, since each point can be
    repeated several times (actually, as many times as the number of triangles
    using it). This could be optimized, I haven't had time to do it though.

    The advantage of this method is that you can easily modify an object with
    another program without having to change anything in the scene description,
    whereas if the object is defined in the .rd file, it is not accessible at
    all.
