Overview of the result of my lab course 2005
by Daniel Jungblut
Introduction and user manual of my project
A few words about the GLUI toolkit library
My project is based on the dissertation of Silvia Harmsen. For historical and theoretical information about the Muqarnas Project, please have a look at this page: http://www.iwr.uni-heidelberg.de/groups/ngg/Muqarnas/index.php?L=E
During her dissertation, Silvia Harmsen developed an algorithm which is able to create three dimensional Muqarnas vaults, from two dimensional plans using graph theory. This small example should visualize the important steps of the algorithm:
| First we have a two dimensional plan. The plan is saved in the *.fig file format which can be edited by using XFig for example. |  |
| If the plan follows some rules which are necessary to describe a Muqarnas plan, it could be converted to a graph by using the program "PlanToGraph". The graph is also saved in the *.fig file format. |  |
| After checking the correctness of the calculated graph, you can convert the graph to a Muqarnas vault by using the program "GraphToMuq". The Muqarnas is saved in *.wrl data, using the VRML 2.0 standard. |  |
My goal was to create a user interface with which you should be able to edit Muqarnas plans and graphs and start the calculation of the vaults by using your computer mouse. To create the user interface I used the GLUI - library. My experiences with this library are listed below.
Introduction and user manual of my project
We will first have a look on the planeditor program:
At the bottom of the program, you find the "Editor Panel", at the right you can find the "Viewer" and the "Muqarnas / File Management" options. First we will have a look on all of these options:
General Information:
The Muqarnas Planeditor is a tool to create and modify two dimensional plans to convert them to 3 dimensional Muqarnas data. It is based on the xfig file format *.fig but can only understand a small part of the xfig language. It generates regular xfig data, so the plans modified by the Muqarnas Planeditor can still be used with xfig. The Muqarnas Planeditor is a totally OpenGL rendered program. It is written with the help of the GLUT and GLUI libraries. The Muqarnas Planeditor comes together with the small program "viewer". This programm can be used to visualize *.wrl data which was generated by the Planeditor. It is also an entire OpenGL rendered program, written with the help of GLUT and GLUI.
IMPORTANT: viewer is not a "reference VRML-viewer". It is only a small tool to visualize very special *.wrl data. To show textures with the viewer you can use either *.ppm raw data or *.jpg data which can be created with GIMP for example.
How to start:
You can start the Muqarnas Planeditor by using the console. Just enter "./planedit" and press edit (it is recommended to start the program by using the command "./planedit &" to avoid some bugs coming up with the GLUI library). You can also start the Muqarnas Planeditor with the command "./planedit filename &". Then the Planeditor starts and automatically loads the file "filename" as plan.
IMPORTANT: You should not change the directory in the console window with which you started the plan editor, because this could lead to errors by hard disc operations.
The Viewer Options:
To translate the view on the plan you can either press the right mouse button in the viewer window and move the mouse, or you can use the "Translation X/Y" axis at the top right of the viewer window by pressing the left mouse button and moving the mouse. You can reset the view to default values by using the correspondent button. You can also zoom the view by using the zoom buttons or change the line width of the lines in the plan.
IMPORTANT: The line width of the Muqarnas Planeditor is only an option of the viewer - this information will not be saved in the *.fig output files.
The Muqarnas / File Management Options:
Textbox "Plan": Here you can set the name of the current plan. This parameter can be set while starting the program by using an additional parameter (see above).
Textbox "Comp. Plan": Here you can load an additional plan called "complete plan". If you start the program GraphToMuq the complete plan will be used - if this box is empty the "plan" will be used for this operation.
Textbox "Graph": The filename of the graph which is automatically set by the operation "PlanToGraph".
Textbox "Output": Here you can choose an output directory for the VRML output data.
Textbox "Texture": You can choose a texture which is laid on the VRML output. The Planeditor comes with a few example textures which you can try. The Textures should be twice as wide than high. In the left half of the texture the image for the regular elements should be stored, in the right half of the texture the image for the intermediate elements should be stored.
Textbox "Muqarnas": Here you can see the name of the calculated Muqarnas. You can start the viewer with this data by pressing the button "Load Muqarnas".
With the "+" buttons right to the textboxes you can start a small dialogue with which you can browse through your directories and choose files and directories.
The "Loadsave-Dialogue" with which you can browse through your directories:
The group "Select":
"Plan": If you set the hook to plan, the current file will be saved and the plan will be loaded.
"Comp. Plan": If you set the hook to complete plan, the current file will be saved and the complete plan will be loaded.
"Graph": If you set the hook to graph, the current file will be saved and the graph will be loaded.
The group "Plan Size": Determines which part of the Muqarnas is stored in your plan (important if you run the calculation of the Muqarnas).
The group "Vault Size": Determines the size of the Muqarnas output.
The button "PlanToGraph": This button only works if the selection hook is set to "Plan". The current plan will be saved and then converted to a Muqarnas graph. After this the calculated graph will be opened.
The button "GraphToMuq": This button only works if the selection hook is set to "Graph". It will save the current graph and calculate the VRML Muqarnas data. For input the "Graph" and the "Complete Plan" are used. If the textbox "Complete Plan" is emtpy the "Plan" will be used as input instead. After the calculation of the VRML data, the "viewer" is started to visualize this data.
The hook "Irregular Plan": If you set this hook only standard elements will be used while calculating the Muqarnas.
The button "Load Muqarnas": The viewer is started again with the calculated Muqarnas data.
The button "Save As": Opens a dialogue in which you can choose a new filename for the current plan, complete plan or graph:
The button "Save File": Saves the current plan, complete plan or graph.
The button "Load File": Loads the selected plan, complete plan or graph.
The button "Quit": Exits the program.
NOTICE: Whenever the file "filename" is saved, the program will create a backup of the former file called "filename~".
The Editor Options:
After loading some data in the editor window, you can edit this data:
The group "Edit":
The button "New Line": Creates a new line which will be fixed in the origin of the coordinate system. The line will be selected automatically.
The button "Delete Line": Deletes the selected line. You can use the button " Del " or "Backspace" instead.
The button "Undo": Undoes the last operation (new line, delete line or changing a line).
The button "Submit": Submits the changes which where made to the current line and deselects this line.
NOTICE: These four operations can also be reached by clicking in the editor window with the middle mouse button.
The hook "Edit Line": If this button is not set, selected lines cannot be changed.
The group "color":
You can set the color of the selected line, to one of the implemented possibilities:
Black, blue, green, cyan, red, magenta or yellow.
NOTICE: The color of a selected line will always be brown. So you won't see the change of the color until you deselect the line.
How to edit plans:
If you want to change a line of your plan, you have to select this line by clicking on it with the left mouse button. A selected line will appear brown and has three green rectangles on the edges and on the middle of the selected line. If you put the mouse button in one of those rectangles and press the left mouse button you can move the line if you let the mouse button pressed. With the rectangles on the edges of a line you can move the edge points of the line and with the rectangle on the middle of the line you can translate the whole line. You can deselect a line by clicking on white space in the editor window.
A selected line, an arrow and some lines of different colors:
You can also change the lines by using the options of the group "Line":
The spinner "X0": The x-coordinate of the first edge point of the selected line. It can be modified by typing a new value in the spinner or by using the up/down arrows right to value.
The spinner "Y0": The y-coordinate of the first edge point of the selected line.
The spinner "X1": The x-coordinate of the second edge point of the selected line.
The spinner "Y1": The y-coordinate of the second edge point of the selected line.
NOTICE: If no line is selected, all these coordinates will be set to 0.
The hook "Arrow": You can make a line to an arrow by setting this hook, to get a visualisation of a directed graph. The arrow always points from X0/Y0 to X1/Y1. If a whole orbit is selected, all the containing lines are changed by this operation.
The spinner "Depth": Shows the depth of the selected line. With the help of these depth levels you can blend out data which you don't want to modify at the moment.
The button "Depth options": Opens a window in which you can set which depth levels should be displayed. With the hook "Blank" you can determine whether the non selected depth levels should be white or bright grey.
The button "Flip Line / Orbit": This buttons flips the two edge points of the selected line. This operation also flips the direction of an arrow. If a whole orbit is selected all the containing lines are flipped.
The hook "Orbit Selection": The calculated graphs group certain lines to orbits. If this hook is set and you select a line, all the lines of the corresponding orbit are selected (they will appear brown with small beige rectangles). The options "Arrow" and "Flip Line / Orbit" will operate on all of these lines.
The spinner "Orbit": Displays the orbit number of the selected line. Because of the automatically calculation of these orbits, this information cannot be changed.
NOTICE: The orbit information is not an information which comes with the *.fig file format. So this information will be lost if you edit your graph with another *.fig editor.
The group "Grid":
You can show a grid for easier edit your plan. With the spinner "Gridwidth", you can change the width of the grid.
The button "SnapToGrid": The edge points of the selected line will be snapped to the next points of the grid. If the hook "Snap all" is set, this operation will work on all lines.
IMPORTANT: If you snap all the lines to grid, this operation cannot be undone!
The button "SnapToNext": The edge points of the selected line will be set to the nearest egde points of any other line.
The group "Length":
You can set a specified length to the selected line. You have the possibility to set three different lengths with which you can work. If you set such a length, the first edge point of the selected line will be fixed while the second edge point will be changed.
If you set the hook "Depending", following dependencies will occur between the three lengths:
Length_2 = Length_1 / sqrt(2)
Length_3 = Length_1 * sqrt(2)
Now we will have a look on the VRML visualization tool "Viewer":
The panel "View":
You can rotate, translate or zoom the view with the buttons at the left bottom of the program. You can either use your mouse buttons for these operations. Just press the corresponding button and move your mouse:
Left button: Rotation
Middle button: Translation Z - Axis (Zoom)
Right button: Translation X/Y - Axis
The panel "Options":
The hook "Textures": Switches texture support on / off.
The hook "Colors": Switches color on / off.
The hook "Orthographic View": Switches to the orthographic view:
This is the orthographic view of the vault from above. In this orthographic projection, you find the original plan:
The spinner "Background": Here you can change the background color. You can choose a greyscale between 0.0 (black) and 1.0 (white).
The panel "File Management": You can browse through the directories and choose VRML data to visualize with "Viewer".
The color of the program name indicates the author of the program.
The brown programs are written by Silvia Harmsen, the black program can be found in the web http://www.ijg.org/ and the green colored programs are the work of my lab course.
The Planeditor is the central program of the whole project. It can start the computing of graphs and Muqarnas vaults and finally the VRML viewer. The viewer uses the DJPG program to support *.jpg files as textures.
The interaction of the planeditor and the loadsave dialogue:
The GLUI library contains an annoying issue: If you create more then one window in one application, and click the x-button at the right top of one of these windows, the whole application will be terminated (I found no possibility to deactivate this function - I think you must get in deep in the GLUI library to solve this problem). So the loadsave dialogue is an independent program. When the loadsave dialogue is started, the planeditor passes parameters to the loadsave dialogue, which enable different options of the loadsave dialogue. Following parameters are supported:
| Parameter | Title of the loadsave dialogue | Enabled options |
| -sp | "Save plan as" | create new directories, enter a new filename, only *.fig and *.fig~ files can be selected |
| -sfp | "Save full plan as" | create new directories, enter a new filename, only *.fig and *.fig~ files can be selected |
| -sg | "Save graph as" | create new directories, enter a new filename, only *.fig and *.fig~ files can be selected |
| -lp | "Choose a plan to load" | only *.fig and *.fig~ files can be selected |
| -lfp | "Choose a full plan to load" | only *.fig and *.fig~ files can be selected |
| -lg | "Choose a graph to load" | only *.fig and *.fig~ files can be selected |
| -od | "Choose an outputdirectory" | only directories can be selected, create new directories |
| -tx | "Choose a texture" | only *.jpg, *.jpeg and *.ppm files can be selected |
When you press the "Ok" or the "Cancel" button, the loadsave dialogue has to pass the chosen filename to the planeditor. For this, the loadsave dialogue creates the file "Log/loadsave.log" in which the information for the planeditor is stored. After calling the loadsave dialogue, the planeditor looks every tenth second if the file "Log/loadsave.log" exists. If it exists, the planeditor gets the information from this file and deletes it after all (and stops looking after the file of course).
To prevent the program to crash down the system performance, the planeditor terminates a previous called loadsave dialogue by using the program "top" which comes with the linux shell.
Some details of the VRML viewer:
As I mentioned before, the VRML viewer is optimized for the special Muqarnas structure of the VRML files, so this program gets extremely high fps rates while displaying a Muqarnas vault. It is also very fast in opening Muqarnas VRML files. If you do not believe me, you are very welcome to try a Muqarnas VRML example with my viewer and maybe FREEWRL ;-P (you can get a fps output to the console by clicking "z" while the mouse cursor is inside the viewer window).
The Muqarnas VRML files consist of three levels. In the file "main.wrl" the information about the number of tiers and the height levels of these tiers is found. In the files "tierX.wrl" the transformation information of the elements which are included in tier number X can be found. Finally the geometry data can be found in the element files. Because one element is used many times in different position, it is intelligent to cache these elements while running the program. So I will describe this caching algorithm:
We will now have a look on the program internal element management system:
The element manager consits of a list of elements. Elements from this list have the following structure:
The important thing is the work of the function:
VRML_ElementClass *VRML_ElementManagerClass::Return(char *FileName, string Path);
The filename and the path of the element which should be loaded are given to the function when it is called. Then the function searches the element list to know if the demanded element is already loaded. If it is so, a pointer to this element is returned - if not the element is loaded and attached to the element list and a pointer on it will be returned. Because of the big redundance of elements within a Muqarnas vault you get a great speedup because of this technique.
The included texture manager works very similar to the element manager. When a new texture is loaded, it will be directly put on the graphics accelerator card, so the only thing to remember is the index which will be returned by the OpenGL engine while loading a texture to the graphics memory.
After loading the Muqarnas vault, it will be put in the graphics memory by using a displaylist. This displaylist is only generated again, if you change one of the option hooks or if you load another Muqarnas. The current viewer transformation is put to the modelview matrix stack before calling the displaylist.
A few words about the GLUI toolkit library
GLUI is a GLUT-based C++ user interface library which provides controls such as buttons, checkboxes, radio buttons, and spinners to OpenGL applications. You will find the referene page here: http://www.cs.unc.edu/~rademach/glui/
I will not discuss the function of GLUI (you can easily download the manual on the webpage linked above), but I will have a short look on the advantages and disadvantages I found out while using this library:
Advantages:
- Easy creation of user interface objects (with one single line of code)
- Can be used with every ascii editor
- Comes with a detailed reference manual
Disadvantages:
- Not really OS independent (I have not succeeded to port my programs to windows)
- Difficult to arrange the GLUI objects
- Does not have a load / save dialogue to browse the hard disc (so I had to write my own)
- Contains some bugs (I had problems with the radio button, and sometimes some of the life variables are erased while clicking a button)
- If you create more then one window within an application, the whole application will be exited when you press the x-button in the top right corner of the one of these windows (this is the reason why the loadsave dialogue is an independent program)
If you have concrete questions about my experiences with this library, please write an email to:
daniel.jungblut at web.de
Here you are able to download the sourcecode of my project:
I am sorry, that I cannot publish the PlanToGraph and GraphToMuq program here. They are part of the dissertation of Silvia Harmsen which is not completed at all.
After all I want to mention some facts about the results of my work:
Total lines of code: about 4200
Total number of files: 37
Development, testing and learning time: about 120 hours
Because the development of my project is not finished yet, it can happen that the downloaded source code from this page does not match to hundred per cent to the description of the project above. Already existing options will only change insignificantly, but new features may be added in later versions.
If you have questions to this project, please write an email to:
daniel.jungblut at web.de