Assignment 2 - Adding User Interface

Due Date: October 29, 2003
 

General description

In the second part of the assignment, you are going to add a graphical user interface (GUI) to your software. This user interface will provide user with the functions like adding and removing objects, applying transformations on the object according to the user input (mouse/keyboard) and saving the scene files. You are recommended to use GLUI for developing the GUI, but if you want to use other user interface design toolkits like Qt or GTK+ you should make sure that you code can be compiled in csil machines.
There are also some new additions to the Simple Scene Description Language.

Testing and output

In this part of the assignment, the input filename may be specified in the command line or through the user interface (see the section for GUI):

./mrender sample-2-1.pov
./mrender

Sample files (note that thehours.pov includes thehour-declare.pov):
thehours.pov (output)
thehours-declare.pov

For this assignment you are also required to design and submit a scene using your software. The scene should be interesting enough to get the full mark (and obviously your program should be able to open your own scene file). Top 3 scenes will receive bonus mark and will be put in the course webpage with their creator's name!!!
 

New additions to  Simple Scene Description Language

#declare ObjectName = [Object]

general purpose enclosing wrapper for an object.
ObjectName: A variable name that follows the standard C syntax for naming variables. (e.g. MyShape, Light_1,  ...)
[Object]: which is one of the basic objects (including basic shapes, union, light)

// --- examples:
#declare MyLight = light_source {
  <2 ,2, 5>
  color rgb <1,0,0>
}
// ---
#declare union_1 = union {
  cone {
    <0, 1, 0>, 0.05,
    <0, 0, 0>, 0.3
  }

  cylinder {
    <0, 2, 0>,
    <0, -1, 0>, 0.1
  }
}
// ---
 

Note that the #declare statement only defines the object and the object will not be included in the scene to be actually displayed. To include a pre-declared object in the scene we use the object statement:

object {
    ObjectName
    pigment {color rgb <R, G, B>}    // optional (similar to other shapes)
    [Transformations]                // optional (similar to other shapes)
}

Creates an actual instance of a pre-declared object.
ObjectName has already been defined in a #declare statement.

// --- examples:
object {MyLight}
// ---
union {
  object{
    union_1
    pigment {color rgb <1, 0, 1>}
  }
  object{
    union_1    // we can reuse a pre-delared object more that one time
    translate <10, 0, 0>
  }
}
// ---
 

#include "Filename.pov"

Includes another povray file. All objects and declare statements inside the Filename.pov file will be included in the scene except the camera commands (simply because we only have one camera). These is specially useful if we want to put the declare statements in separate files to keep our main scene files small and simple.
It is possible to have many #include statements in a scene file and also other #include s in the included file;
when a file is included in a scene file:
 - all declares in included files, would be also valid to be used in the scene file.
 - camera commands in included files will be ignored.
 

For compatibility with Pov-Ray^TM you only should consider inclue filenames that has ".pov" extension. Filenames with other extensions (".inc") would be ignored.

// --- examples:
#include "sample-1-1.pov"  // will include sample-1-1.pov
#include "shapes.inc"      // will be ignored

Graphical User Interface (GUI)

Your program should provide the following functionalities for the user through its graphical user interface:

File Functions

<New File>: Creates a new empty scene file which only contains a camera.

<Open File>: Opens an existing scene file. When program is opening a scene file, it will also search for included file(s) (except the files with .inc extension).

<Save File>: Saves changes to the scene file (in povray format).
Only those objects and #declares that were in the current scene file should be saved and other objects and #declares that are in the included files, will remain unchanged in those included files.
 

<Save As>: Asks for a filename and saves changes to the new filename.

<Include>: Includes an existing scene file (like an #include statement).

<Extract declares>: This function has been added for reusability purposes.
It will ask for a filename and extracts all the #declare statements in the current scene file (not in the other included files) to that file.
For example, suppose you open a scene file myfile.pov which includes myinclude1.pov and myinclude2.pov;  if you <Extract declares> to a myfile_declars.pov, a file myfile_declare.pov will be created that contains all the declares inside myfile.pov, and myinclude1.pov and myinclude2.pov will still remain unchanged. 

A user interface should be provided to enable user to enter filename (e.g. a text box) if a filename needs to be specified for the function.
(optional: selecting the file using a file dialog)

Objects Functions

Listing:
Your program should display a list of all actual objects in the scene. Each element in the list should be a name in form of "TypeIndex", in which Type specifies the type of the object (e.g. Light, Box, Union, MyShape, ...) and Index is a unique number assigned to the object of each type.
(e.g. Camera1, Light1, Light2, Box1, Box2, Box4).
Objects inside unions will not appear in the list.

Selecting:
When user selects an item (objects) from the list, coordinate axis (xyz) for the selected object should be shown centered in the origin of the object (<0, 0, 0> in the object coordinate system) on the output window, specifying the selected object and its orientation (i.e. if the object is rotated or scaled, the coordinate axis should be too). If the selected object is the camera, coordinate axis should be displayed in some corner of the screen so that it can be visible (obviously because camera cannot see itself).

Modifying:
Objects can be modified in two general ways:
They can be either transformed by applying basic transformations (translate, rotate, ...) and specifying color or they can have object specific parameter modifications (e.g. changing radius of end points of a cone, changing aspect ratio of the camera).
Your program should provide a user interface for both functions.

Add:
User should be able to add a new object to the scene by selecting the object type from a group of available objects. The available objects are the basic shapes, light and pre-declared objects (which has been declared in the current scene and in included files). Then the program can either ask the user to enter the object parameters or it can use default values (so that user can modify them later)
/* Removed feature: There is no need to have an option to add an object to another object to create a union. So, all objects will be added directly to the main scene files.*/

Group:
User should be able to select a group of objects (shapes, unions and lights) and group them to create a union.
 

Ungroup:
User should be able to select a union and ungroup it. If the object is an instance of a #declare, the #declare will not be changed Ungrouping is done only in one level, not recursively. So, if you ungroup a union that contains other unions, those inside unions will not be ungrouped.

For example:

#declare union_1 =
union {
  sphere ...
  box ...
  union ...
  union ...
  transformations
}
object {union_1}
 

if you ungroup the object, it will be broken apart to:

sphere {...
  transformations
}
box ... {
  transformations
}
union ...{
  transformations
}
union ... {
  transformations
}
and union_1 will still remain unchanged

Make Symbol:
User can select an object and define it as a declare. User will be asked for a name and then the object would be considered as an instance of the new declare.
For example if you select this object:

union {
  asdfasdf
  transformations
}

and make it as a symbol named "mysymbol":

#declare mysymbol =
union {
  asdfasdf
  transformations
}
object {mysymbol}
 

Remove:
User should be able to select and remove a group of objects (except the camera).

Design, Coding & Documentation

Again, the first thing to do (after reading the whole assignment) is to design the objects. This would be an easy or difficult task depending on how you have already done in your assignment 1.

Again, do not delay this task, do not fudge it, do not proceed to code without most of this design finished. For each object you design, write down a brief description of its duties and members (data and functions). If unsure, discuss your design with me or the T.A.

You may find the following tips useful. Do not limit yourself to the ideas presented here; these are just to get you thinking:

• You should probably think about adding copy constructors to your objects

• You should probably add a new member function for you objects to save the object to the file

• You may find GLUI samples helpful for developing user interface for your program.

• You can treat #declares as regular objects that only are invisible in the scene. Then creating an instance of a declare would be as easy as calling the copy constructor.

The marks given for design on this assignment (and all assignments) are for embodied design---that is, design that has made its way into code. A supplementary document or comments explaining what you would do in code will not receive design marks.

Marking

Last updated in Oct 24, 2003