\documentclass{scrartcl}

%We want our table of contents, ... to be links
\usepackage{hyperref}
\hypersetup{colorlinks, citecolor=black, filecolor=black, linkcolor=black,   urlcolor=black}

\usepackage[pdftex]{graphicx}
\usepackage{float}

\usepackage{framed}

\let\subsectionautorefname\sectionautorefname
\let\subsubsectionautorefname\sectionautorefname

\begin{document}

%Title page data
\title{\vspace{150pt} SGE \\ SceneGraphEditor}
\subtitle{User's Guide\vspace{150pt}}
\author{Thomas Odaker}
\date{}
\maketitle

%do not show page number on title page
\thispagestyle{empty}

\newpage

\tableofcontents

\newpage


\section{Introduction}

The SceneGraphEditor ("SGE") is a tool developed for Ludwig-Maximilians University Munich and is part of the inVRs repository. It provides functionality to load, edit and store a scenegraph and compose a static scene.\\
\\
The current feature set of the tool includes:\\
\paragraph{3D models}
\begin{itemize}
\item loading and adding models into the scenegraph
\item removing nodes from the graph
\item transforming of nodes and subtrees
\item loading and saving of scenes/scenegraphs
\end{itemize}

\paragraph{Lighting, shading and shadows}
\begin{itemize}
\item creation and transformation of light sources
\item real-time shadows using shadow maps
\item rendering using phong shading
\end{itemize}

\paragraph{Materials}
\begin{itemize}
\item creating, editing and applying materials
\item loading and applying textures
\item multi-texturing, texture blending
\item normal/bump mapping
\end{itemize}

\paragraph{VR}
\begin{itemize}
\item output to multidisplays (e. g. CAVE)
\item output to Oculus Rift
\item support for articulated avatars on Oculus Rift
\end{itemize}
\vspace{30pt}
SGE is developed using OpenSG (\url{http://www.opensg.org}) to maintain the scenegraph as well as to handle loading, saving and rendering of 3D objects. It additionally relies on the use of inVRs (\url{www.inVRs.org}).\\
The user interface is created using Qt (\url{http://www.qt-project.org}).


	

\newpage

\section{User interface}
The user interface is created using Qt. This makes the UI flexible and therefore allows it to run on multiple platforms. The toolbars can be  rearranged freely and the individual elements resized.\\

\begin{figure}[H]
	\centering
	\includegraphics[scale=0.4]{images/main_interface.png} 
  \caption{Main interface}
  \label{fig:main_interface}
\end{figure}

\autoref{fig:main_interface} shows a screenshot of the main interface with an empty scene. This is the default view after launching SGE. \\
The toolbars at the top allow for quick access to some of the functionality of the editor. Below are the 3 main components of the interface: the scenegraph interface, the output area and the edit controls. The following sections of this guide will give a more in depth description of the individual elements of the interface.

\subsection{Scenegraph interface}
\begin{figure}[H]
	\centering
	\includegraphics[scale=0.4]{images/interface_scenegraph.png} 
  \caption{Scenegraph interface}
  \label{fig:interface_scenegraph}
\end{figure}
\autoref{fig:interface_scenegraph} highlights the scenegraph interface. \\
It contains several tabs used to access different information and lists (objects imported from files, list of materials, etc.).\\
\\
The first and default tab is the scenegraph tab. This shows a tree representation of the current scenegraph. When opening a new instance of SGE, the scenegraph consists of a root node only. The scenegraph in SGE can never be empty, a root node is always automatically generated. When objects or subtrees are added, this view is updated to show the tree view of the scenegraph for the current scene. \\

\begin{figure}[H]
	\centering
	\includegraphics[scale=0.5]{images/scenegraph_detail.png} 
  \caption{Scenegraph interface example}
  \label{fig:scenegraph_detail}
\end{figure}

\autoref{fig:scenegraph_detail} shows an example for a simple scenegraph with a small number of nodes (all of them children of the root node). \\
The interface shows two columns for each node. The first one contains the name of the node. Each node can be assigned a name. This is helpful to identify the node. It is however a user assigned string, not a unique identifier (see \autoref{subsectionedit} for instructions on how to edit node names).\\
The second column contains the type of core assigned to the node. OpenSG defines nodes to be the basic elements that define the hierarchy of the scenegraph. Node cores are assigned to nodes and store all important data (geometry, transformations, etc.). The node core name is provided by OpenSG and is displayed to indicate the function of the node.\\
\\
To improve the readability of the scenegraph, the representation of the tree adds icons and colours. \\
The column "Core" is assigned a background colour based on the type of the core assigned to the node. Each colour uniquely represents a certain type of core. The same is true for the displayed icons. Core name, colour and icon will always match and are equivalent.\\
\begin{framed}
\emph{Please note that while the core names are taken from the OpenSG core name, the colours and icons are assigned by SGE based on the core name. Non default cores are therefore not supported and will be displayed without a colour or icon.}
\end{framed}

The display of the names, colours and icons can individually be toggled on or off. This is done via the "View" menu:

\begin{figure}[H]
	\centering
	\includegraphics[scale=0.5]{images/scenegraph_menu_view.png} 
  \caption{Menu "View": Toggling names, icons and colours}
  \label{fig:scenegraph_menu_view}
\end{figure}

\autoref{fig:scenegraph_menu_view} shows the associated options. These can be individually toggled to customize the scenegraph representation to the user's preference. \\

\subsection{Output area}

The output area shows the rendered scene.

\begin{figure}[H]
	\centering
	\includegraphics[scale=0.4]{images/interface_output.png} 
  \caption{Output}
  \label{fig:interface_output}
\end{figure}

\autoref{fig:interface_output} highlights the output area.\\
This part of the interface does not only render a static representation of the scene, it also allows the user to navigate within the scene.\\

\subsubsection{Camera controls}
The current view direction can be changed using the mouse. Right-clicking any point within the output area and holding the right mouse button enables navigation mode. Releasing the right mouse button disables it.\\
When in navigation mode, mouse movements change the current view direction. \\
Pressing the arrow up or 'w' key moves the camera forward along the current view direction. The back arrow or 's' moves the camera backwards. Left/right arrow or 'a'/'d' moves the camera to the left and to the right. \\
\\
The output area can also be used to select and move objects. Left clicking selects a visible object and holding the left mouse button moves it. For a more in depth description on the selection/picking and editing functionality please refer to the corresponding section of this guide.

\subsection{Edit controls}

The last remaining part of the main user interface are the edit controls.

\begin{figure}[H]
	\centering
	\includegraphics[scale=0.4]{images/interface_controls.png} 
  \caption{Edit controls}
  \label{fig:interface_controls}
\end{figure}

\autoref{fig:interface_controls} shows the area for the edit controls highlighted. This part of the interface may be empty and changes depending on the type of selected node. \\
Whenever a node of the scenegraph, that can be edited by the user, is selected, a set of corresponding controls is displayed in this area. \\
When none is selected or editing of the node is not possible/allowed, this area is left blank to keep the size of the output area constant and prevent frequent resize operations.\\
\\
For information on how to use the edit controls please refer to \autoref{subsectionedit}.


\subsection{Options}

Using the "Options" button (shown in \autoref{fig:options_button}) toggles the options menu.
\begin{figure}[H]
	\centering
	\includegraphics[scale=1.0]{images/options_button.png} 
  \caption{Button "Options"}
  \label{fig:options_button}
\end{figure}

The options menu (\autoref{fig:options}) allows the user to control the headlight, the movement speed multipliers and the near/far plane. 

\begin{figure}[H]
	\centering
	\includegraphics[scale=0.8]{images/options.png} 
  \caption{Options}
  \label{fig:options}
\end{figure}

The headlight can be exclusively turned on for either the local rendering or a connected multidisplay. The multidisplay option becomes available only when a connection to a multidisplay has successfully been established. This option can also be controlled using the view menu. \\
\\
The second option is the movement speed multiplier. It is controlled individually for local rendering and a multidisplay. It allows to adapt the camera speed to the scale of a scene.\\
\\
The last option is the distance of the near and the far plane from the camera. Only objects that are farther than the near plane and closer than the far plane will be rendered. Everything else will be omitted. \\
\\
The movement speed multipliers and the near/far plane values will be stored automatically when SGE is closed and will be reapplied when SGE is launched again.

\newpage

\section{Scene editing}

This section covers the functionality of creating, loading, editing and saving scenes. \\

\begin{framed}
\emph{Please note that this guide is designed to document the functionality of SGE. SGE is based on OpenSG. For a documentation of OpenSG please visit \url{http://www.opensg.org}.}
\end{framed}

A scene consists of a number of nodes. Nodes are organized in a tree. A node can only have one parent, but an infinite number of children. \\
A node is a container and does not have an effect on the scene by itself. Therefore a node can be assigned a core. The node core defines the functionality of a node (e. g. geometry, transformation, ...). \\
\\
A scene consists of at least one node - the root node. There always must be a single root. SGE does not allow multiple roots and does not offer functionality to change the root node directly. \\
\\
SGE provides functionality to add, manipulate and delete nodes. It is also possible to save the entire scene as well as parts of the scene. \\
\\
\subsection{New, Load, Save}
Opening a new instance or creating a new scene with the "New" function results in an empty scene that only consists of the root node only but does not contain any other data.\\

\begin{figure}[H]
	\centering
	\includegraphics[scale=0.6]{images/menu_file.png} 
	\includegraphics[scale=0.9]{images/toolbar_main.png} 
  \caption{"New", "Load", "Save" and "Save As"}
  \label{fig:ctrl_load_save_new}
\end{figure}

\autoref{fig:ctrl_load_save_new} shows the controls to create ("New"), load ("Load") or save ("Save" or "Save As") a scene. These can either be found in the File menu or the file toolbar. \\
\\
"New" deletes the current scene and creates a new, empty scene. Any unsaved progress is lost when creating a new scene. \\
\\
"Load" deletes the current scene and loads a scene from a file. Any unsaved changes on the current scene are lost. \\
The supported file formats depend on the version of OpenSG used when compiling SGE. \\
\\
"Save" and "Save As" store the scene. Using "Save" or the "Save" button in the toolbar to store a previously unsaved scene will open the "Save As" dialog. \\
The File menu offers an additional option "Export Selected Subtree". When a node is selected in the scenegraph this option saves the selected node including all its children to a file using the selected node as the root node. \\
\\
Once a scene is created or loaded, nodes may be added, deleted and manipulated.

\subsection{Scene manipulation}

Scene manipulation includes adding, deleting and editing of nodes(functionality depends on type of node core).

\subsubsection{Adding nodes}
\label{addingnodes}

The first option offered by SGE is adding nodes to a scene. Two options are available: 
\begin{itemize}
\item Importing a scenegraph from a file and adding the imported graph or parts of it 
\item Adding individual nodes
\end{itemize}

Both cases require the definition of a node which serves as parent of the newly added nodes. It is not possible to add nodes as a new root. To achieve this, please use the load function, which deletes the current scene, as multiple roots are not allowed.\\
If no node is chosen as the parent, SGE automatically selects the root node for this purpose. The user can select any node of the current scenegraph as parent just by selecting it in the displayed scenegraph tree. Any nodes inserted into the graph are added as child of the currently selected node, or the root, if none is selected. \\

The first option is to import a scenegraph from a file and add it to the scene. SGE does not add file contents directly into the scenegraph but rather maintains a list of objects loaded from files so that they can be repeatedly added without the need to import them multiple times. \\
\\
The first step is to import a scenegraph (subsequently referred to as "object" to avoid confusion with the scenegraph of the main scene) into the list of loaded objects. This is done by using the "Import" button in the "Add" toolbar.\\

\begin{figure}[H]
	\centering
	\includegraphics[scale=0.6]{images/button_import.png} 
  \caption{Import button}
  \label{fig:button_import}
\end{figure}

\autoref{fig:button_import} highlights the aforementioned button. When it is pressed, an open file dialog appears that allows the user to select a file to be imported.

\begin{framed}
	\emph{Please note that importing of files is done via OpenSG. Supported file formats depend on the version of the OpenSG library and can vary depending on features enabled during OpenSG compilation.}
\end{framed}

After a successful load the imported object is shown in the "Loaded Objects" tab.

\begin{figure}[H]
	\centering
	\includegraphics[scale=0.6]{images/tab_loadedobjects.png} 
  \caption{List of loaded objects}
  \label{fig:tab_loadedobjects}
\end{figure}

Each object is shown as an individual tree that can be viewed in this tab. Even though this tab is similar to the "SceneGraph" tab, there is no manipulation of the nodes allowed here. \\
\\
The "Loaded Objects" tab features a preview mode that allows the user to preview a loaded object. Simply selecting an object while this tab is active will show a rendering of the current object in the output area. The current position and view direction of the camera is backed up and automatically restored when the preview is disabled again. \\
The preview mode is disabled when the user selects the "SceneGraph" tab or disables the preview mode with the option in the "View" menu. \\

\begin{figure}[H]
	\centering
	\includegraphics[scale=0.6]{images/menu_view_previewmode.png} 
  \caption{Toggle to enable/disable preview mode}
  \label{fig:menu_view_previewmode.png}
\end{figure}

While in preview mode, the camera controls are changed. Right clicking the output area and holding the button still enables navigation mode, but here moving the mouse rotates the rendered object while the w/s or arrow up/down keys will change the distance between the camera and the object. The a/d and left/right arrow keys are not used in this mode. \\
\\
To add a loaded object to the scene a parent node has to be selected. This can be done in the "SceneGraph" tab. If no node is selected, the object will be added as a child of the root node. \\
\\
While the "SceneGraph" tab is active, the "Insert loaded object" buttons are available. This function is available in the menu "Insert" as well as in the "Insert" toolbar (\autoref{insert_loadedobject}).

\begin{figure}[H]
	\centering
	\includegraphics[scale=0.6]{images/menu_insert_loadedobject.png} 
	\includegraphics[scale=0.9]{images/toolbar_insert_loadedobject.png} 
  \caption{Insert loaded object}
  \label{insert_loadedobject}
\end{figure}

When this function is chosen, the "Loaded Objects" tab is automatically selected and all other tabs are temporarily disabled. In addition a new set of buttons is shown at the bottom of the "Loaded Objects" tab. \\
\\
At this point the user can select an object to be added to the scene. It is also possible to "browse" the imported objects and select any node. SGE will always add the selected node including all its children to the scene. This functionality allows to import only parts of a complex scenegraph imported from a file. \\
\\
The buttons at the bottom of the "Loaded Objects" tab are used to add the selected node or abort and return to the "SceneGraph" tab. \\

\begin{figure}[H]
	\centering
	\includegraphics[scale=0.6]{images/tab_loadedobjects_importmode.png} 
  \caption{Buttons "Add Copy", "Add Deep Copy" and "Abort"}
  \label{fig:tab_loadedobjects_importmode.png}
\end{figure}

\autoref{fig:tab_loadedobjects_importmode.png} highlights the three aforementioned buttons (red, blue and yellow). The buttons on the left side are used to add the selected object/node. The button on the right aborts the add operation. \\

\begin{framed}
	\emph{As previously discussed the scenegraph consists of nodes and node cores. Nodes are containers and node cores define the function. A node can only have one parent but multiple children and is usually assigned a node core. A node core however can be assigned to multiple nodes. This allows for a better organization of the scenegraph and reduces redundancy. Manipulating a node core that is assigned to multiple nodes means that the changes are in effect whereever this specific node core is used.}
\end{framed}
The two buttons on the left add either a copy or a deep copy of the node to the scenegraph. Using the left button (red in \autoref{fig:tab_loadedobjects_importmode.png}) does a simple copy of the object and adds it into the scenegraph. This means that node cores are NOT duplicated. All objects that are added to the scene using this function share node cores and any changes done to a node core of this object will not only affect all other instances of this object in the scene, but also the imported object!\\
The second button (blue in \autoref{fig:tab_loadedobjects_importmode.png}) does a deep copy. This means that nodes AND node cores are duplicated and changes to the node cores have no effect on any other instances of the object in the scene or the loaded object itself.\\
\\
Using any of the "Add" buttons (copy or deep copy) will perform the selected operation and activate the "SceneGraph" tab. All other temporarily deactivated tabs will be enabled again at this point. \\
\\
A node added to the scenegraph using this method will be highlighted in the "SceneGraph" tab by a coloured background of the "Name" column. \\
\\
\\
The second way of adding nodes is to add them individually. SGE features a set of nodes assigned with common node cores to be easily added into the scenegraph. The supported node core types are:
\begin{description}
	\item[Geometry] OpenSG features a set of predefined geometry that can be created using various parameters.
	\item[Light] A light source
	\item[Transform] A transformation applied to all children of the node
	\item[Materialgroup] A material applied to all children of the node (if applicable)
	\item[Group] A group has no direct effect but can have multiple children
\end{description}

The first option to insert a node containing a geometry is called "Insert predefined object". It can be accessed using the "Insert" toolbar or the menu "Insert".

\begin{figure}[H]
	\centering
	\includegraphics[scale=0.6]{images/menu_insert_predefined.png} 
	\includegraphics[scale=0.9]{images/toolbar_insert_geometry.png} 
  \caption{Insert a geometry}
  \label{fig:insert_geometry}
\end{figure}

When this function is clicked, a dialog is shown that consists of two parts: a list of all predefined objects and a set of parameters. 

\begin{figure}[H]
	\centering
	\includegraphics[scale=0.6]{images/dialog_predefined.png} 
  \caption{Dialog: "Predefined Objects"}
  \label{fig:dialog_predefined}
\end{figure}

The user selects a type of object from the drop down list. This adapts the parameters below which are used to customize the object to be inserted into the scenegraph. The "OK" button confirms the action.\\
\\
\\
The next option is to insert a light source. This is done via the "Insert light" button available in the menu "Insert" or the toolbar "Insert"(\autoref{fig:insert_light}). \\
\begin{figure}[H]
	\centering
	\includegraphics[scale=0.6]{images/menu_insert_light.png} 
	\includegraphics[scale=0.9]{images/toolbar_insert_light.png} 
  \caption{Insert a light}
  \label{fig:insert_light}
\end{figure}

Similar to the option to insert a geometry, this also opens a dialog that consists of a drop down list of available types of light sources and parameters to customize them.
\begin{figure}[H]
	\centering
	\includegraphics[scale=0.6]{images/dialog_light.png} 
  \caption{Dialog: light source}
  \label{fig:dialog_light}
\end{figure}

There are 3 types of light sources available:

\begin{description}
	\item[Point light] A point light is a light source located at a point in space emitting light in all directions.
	\item[Directional light] A directional light is a light that has no origin and just a direction. 
	\item[Spot light] A spot light has a light source and a frustum defined via the exponent and cutoff parameters.
\end{description}

The "OK" button adds the light source, the "Cancel" button cancels the operation.\\

\begin{framed}
	\emph{Please note that in a scenegraph light sources only affect nodes that are children of the light source. Additionally the transformation of a light source is done by setting the beacon of the light source and not by adding a node with a transform core as the parent of the light.}
\end{framed}

The next option is to add a transformation to the scene graph (\autoref{fig:insert_transform}). As initial transformation the identity matrix is set, so the node is directly added and can be edited later(see corresponding part of this guide). Similar to light sources a transformation only affects children of the node with the transform core.
\begin{figure}[H]
	\centering
	\includegraphics[scale=0.6]{images/menu_insert_transform.png} 
	\includegraphics[scale=0.9]{images/toolbar_insert_transform.png} 
  \caption{Insert a transformation}
  \label{fig:insert_transform}
\end{figure}

The next option is to insert a material group (\autoref{fig:insert_materialgroup}). Similar to the transform core this node is directly inserted. The purpose of the material group core is to apply a material to this core which is subsequently used for all children of the node with the material group core.

\begin{figure}[H]
	\centering
	\includegraphics[scale=0.6]{images/menu_insert_material.png} 
	\includegraphics[scale=0.9]{images/toolbar_insert_material.png} 
  \caption{Insert a material group}
  \label{fig:insert_materialgroup}
\end{figure}

The last option is to insert a group (\autoref{fig:insert_group}). A node with a group core has no direct effect on its children but rather serves to organize nodes. A node with a group core is used as a container for one or more nodes. 

\begin{figure}[H]
	\centering
	\includegraphics[scale=0.6]{images/menu_insert_group.png} 
	\includegraphics[scale=0.9]{images/toolbar_insert_group.png} 
  \caption{Insert a group}
  \label{fig:insert_group}
\end{figure}

Apart from adding nodes, SGE offers a set of options to edit nodes and node cores of a scenegraph.

\subsubsection{Node selection}

Editing the scenegraph involves selecting nodes, changing their positions within the graph, adding or removing children, changing the parents and deleting nodes. It is also possible to manipulate the data of the node core assigned to a node.\\
It is however not possible to change the core of a node. If this is desired by the user, it can be achieved by deleting the node and creating a new one with the required core assigned. \\
\\
The first step to edit the scenegraph is selecting a node to be manipulated. This can be achieved by either clicking a node in the "SceneGraph" tab or by picking in the output area. \\
The simplest way to select a node is using the "SceneGraph" tab. This tab shows all nodes in a tree and any node may be clicked to be selected. The bounding box of the selected node will be shown in the output area, if applicable. \\
\\
The second way to select a node is clicking an object in the output area. This method of node selection has a serious disadvantage: only visible nodes can be selected. Nodes with cores such as group, transformation or material group are not visible and therefore can not be selected freely this way.\\
Another feature is traversing the graph of a loaded object inserted into the scene. \\
If the geometry of a loaded object is clicked in the output area, the node selected may not be the actual geometry node but rather the root of the subtree that was selected during the insertion of the loaded object. Subsequent clicks onto the same object will traverse the graph step by step until a leaf node is reached. \\

\begin{framed}
	\emph{Please note that traversing the graph by picking requires custom data to be attached to the scenegraph that is usually omitted when the scene is saved. After saving and loading the scene, this traversal will not be available and the clicked node is directly selected. }
\end{framed}

\subsubsection{Rearranging nodes}
The next important operation is to change the relationship between nodes in the graph. SGE supports a very simple way to rearrange the nodes in the graph: drag \& drop. \\
In the "SceneGraph" tab the user can simply select a node and drag it to a new position within the graph. This will change the parent of the selected node and move it and all its children to a new position and assign a new parent. \\
It is however not possible to drop a node where it would not be a child of the root node, as creating a new root is not allowed by SGE.\\

\subsubsection{Deleting nodes}
SGE offers the possibility to delete nodes from the scenegraph. This is done via the tab "SceneGraph".\\
The first way is the use of the 'del' key. A dialog will be shown asking for confirmation to delete the node. \\
This operation will not only delete the node, but also all its children and may therefore cause the removal of a subtree of the scenegraph. If the user wants to remove a single node only but not the child nodes, they have to be moved via drag \& drop first.\\
\\
It is also possible to remove nodes without using the keyboard. When the mouse cursor is hovered over a node in the "SceneGraph" tab, an "X" icon is displayed in front of the name of the node (\autoref{fig:delete}). Clicking this item has the same effect as using the delete key. 

\begin{figure}[H]
	\centering
	\includegraphics[scale=0.7]{images/delete.png} 
  \caption{Delete icon}
  \label{fig:delete}
\end{figure}

\subsubsection{Editing nodes and node cores}
\label{subsectionedit}

When a node is selected either in the "SceneGraph" tab or by clicking an object in the output area, a set of parameters that can be manipulated is displayed in the edit controls. The parameters may vary depending on the type of the node core of the selected node.\\
Not all displayed parameters may apply directly to the node or node core of the selected node. In some cases the controls for a transformation may be displayed even though the selected node does not contain a transform core or is not applicable for a transformation. This is a feature of SGE to make transformations easier to apply. \\
If the position/rotation/scale is changed, SGE will check the parents of the currently selected core  in order to find a node with a transform core, the transformation change is then applied to. If no suitable transform core is found, SGE will automatically change the scenegraph by inserting an additional node with a transform core. Any subsequent changes to the transformation will be applied to this newly created node. \\
\\
\begin{figure}[H]
	\centering
	\includegraphics[scale=0.7]{images/edit_node_name.png} 
  \caption{Changing the name of a node}
  \label{fig:edit_node_name}
\end{figure}

As \autoref{fig:edit_node_name} shows every node can be assigned a name. This name does not have to be unique and only serves for easier identification of nodes and purposes of nodes by the user, but has no effect on the scenegraph. 

\begin{figure}[H]
	\centering
	\includegraphics[scale=0.7]{images/edit_node_name_material.png} 
  \caption{Changing the material}
  \label{fig:edit_node_name_material}
\end{figure}

\autoref{fig:edit_node_name_material} shows the edit control when the node core supports the assignment of a material. Here a list of available materials is shown and a single material can be selected and applied by the user. 

\begin{framed}
\emph{For information on how to create and edit materials please see the corresponding section of this guide.}
\end{framed}

The transformation tab (\autoref{fig:edit_transformation}) of the default edit controls allows the user to see and to change the current values of the transformation applied to the currently selected node. 

\begin{figure}[H]
	\centering
	\includegraphics[scale=0.7]{images/edit_transformation.png} 
  \caption{Transform data}
  \label{fig:edit_transformation}
\end{figure}

By default the edit controls show the absolute position of the selected node. SGE allows to switch to relative transformations. \\
If there is a node with a transform core that is a child node of another one with a transform core, the transformation applied is not overwritten but rather combined. 
The default view showing the absolute transformation means that the data shown is the result of all transformations applied to the node.\\
\\
The option to switch to relative transformations is available from the view menu (as shown in \autoref{fig:menu_view_transformation}). 

\begin{figure}[H]
	\centering
	\includegraphics[scale=0.7]{images/menu_view_transformations.png} 
  \caption{Absolute/relative transformation}
  \label{fig:menu_view_transformation}
\end{figure}

With this option set to relative transformations, SGE will scan the tree for the first node with a transform core applicable to the selected node and show its transformation relatively to any transformation set higher up in the scenegraph. \\
\\
Another way to edit the transformation of a node is using the mouse. In the first step a node has to be selected. Then the output area has to be clicked with the left mouse button and the button held down. Now it is possible to move the selected node in the scene. \\
This way of transforming a node is restricted to a change of the position in the X/Z plane to avoid confusion when moving the node. The transformation applied is done in relation to the current view vector (so moving the mouse away from the user, will also move the selected node away from the current camera position).
\\
\\
The previously discussed edit controls apply for most node types with the exception of light nodes. 

\begin{framed}
\emph{While a transform core applies a transformation to all children of the node the core is assigned to, lights are an exception to this rule. The position of a light source is NOT influenced by the transformation of the node. This restriction is necessary since lights are applied to nodes only that are children of the light source. To allow a correct placement of the light, light cores are assigned a beacon. This beacon is a node of the scenegraph, the transformation of which is used to control the position of the light source.}
\end{framed}

\begin{figure}[H]
	\centering
	\includegraphics[scale=0.7]{images/edit_light_beacon.png} 
  \caption{Light edit controls}
  \label{fig:edit_light_basic}
\end{figure}

The basic tab of the light edit controls features (\autoref{fig:edit_light_basic}) three sets of parameters: The name of the light node, the colours of the light source that can be changed and lastly the beacon. It displays the beacon's name and allows to directly jump to the beacon (selects the node currently acting as beacon. This is the root node by default). It also allows to select a new beacon. \\

\begin{figure}[H]
	\centering
	\includegraphics[scale=0.7]{images/edit_light_beaconselect.png} 
  \caption{Changing the beacon}
  \label{fig:edit_light_beaconselect}
\end{figure}

By clicking the "Change beacon" button, SGE enters beacon select mode. This shows two buttons at the bottom of the "SceneGraph" tab. At this point the user can select any node in the "SceneGraph" tab for the new beacon and then either click the "Select" (green in \autoref{fig:edit_light_beaconselect}) or "Abort" (red) button. \\
\\
The second tab "Advanced" shows paramenters depending on the type of light source selected (point light, directional light or spot light).\\
\\
The third tab allows the user to control shadows cast by the light. The technique implemented here is relying on shadow maps. \\
\begin{framed}
\emph{Shadow maps are a simple technique to calculate shadows cast by a light source. It calculates hard edged shadows in real time. The shadow map resolution influences the quality of the resulting shadows. Too low a resolution may result in "blocky" artifacts being visible, increasing with the distance between the object and the light source.}
\end{framed}

\begin{figure}[H]
	\centering
	\includegraphics[scale=0.7]{images/edit_light_shadow.png} 
  \caption{Shadow controls}
  \label{fig:edit_light_shadow}
\end{figure}

Here the user can enable/disable the shadows altogether and select the colour of the shadows cast by this light source. It is also possible to adapt the resolution used for the shadow map.\\
\\


\subsection{Materials}

SGE allows to apply materials to material group or geometry node cores. In order to apply materials, they first have to be created. \\
A list of all currently available materials can be accessed via the "Materials" tab (\autoref{fig:tab_materials}). \\

\begin{figure}[H]
	\centering
	\includegraphics[scale=0.7]{images/tab_materials.png} 
  \caption{"Materials" tab}
  \label{fig:tab_materials}
\end{figure}

Whenever a scene is loaded or an object imported, all nodes are parsed for materials in the loaded data and the materials found are added to this list. \\
Alternatively the user can create new materials using the "Add Material" button (\autoref{fig:tab_add_materials}) in the "Add" toolbar.

\begin{figure}[H]
	\centering
	\includegraphics[scale=0.9]{images/toolbar_add_material.png} 
  \caption{"Add Material" button}
  \label{fig:tab_add_materials}
\end{figure}

Selecting any material in the list enables the preview mode for this material. A cube with the selected material assigned is drawn in the output area (as shown in \autoref{fig:material preview}). Any changes to the material are instantly applied to the preview. \\

\begin{figure}[H]
	\centering
	\includegraphics[scale=0.6]{images/material_preview.png} 
  \caption{Material preview mode}
  \label{fig:material preview}
\end{figure}

The preview can be manipulated in the same way as the preview for "loaded objects" can (see \autoref{addingnodes}).\\
\\
The edit controls for a selected material consist of two tabs: \\
\\
The "Simple" tab allows the user to name the material (names do not have to be unique) and adapt the colour and emission as well as the shininess of the material. \\
\\
The "Advanced" tab controls textures set for the material (\autoref{fig:material_tex_adv}). 

\begin{figure}[H]
	\centering
	\includegraphics[scale=0.7]{images/edit_texture_advanced.png} 
  \caption{"Advanced" tab}
  \label{fig:material_tex_adv}
\end{figure}

In this tab the user can add and remove textures. If a texture is selected, the "Weight" option is enabled and a weight can be set for the texture to control, how multiple textures are blended together. \\
On the right hand side of this tab there are the controls for normal and bump mapping. Here the user can either load a normal or a bump map. Please note that applying a normal or bump map replaces a currently set normal or bump map. The third button disables normal/bump mapping.


\subsection{Skybox}

SGE has support for a simple skybox. This consists of two controls: a toggle to enable/disable the skybox and a set of parameters to customize it (\autoref{fig:toolbar_skybox}).\\

\begin{figure}[H]
	\centering
	\includegraphics[scale=0.9]{images/toolbar_skybox.png} 
  \caption{Toolbar "Skybox"}
  \label{fig:toolbar_skybox}
\end{figure}

The left button of the toolbar "Skybox" enables or disables the skybox.

\begin{framed}
\emph{Please note that while the skybox is part of the scenegraph, it requires special handling during rendering. To guarantee a working skybox, it is therefore not displayed in the "SceneGraph" tab as a set of nodes and is discarded when saving the scene.}
\end{framed}

The second button shows/hides the edit controls for the skybox.\\
The controls consist of two tabs. The first tab "Size" lets the user control the size of the used skybox.

\begin{figure}[H]
	\centering
	\includegraphics[scale=0.7]{images/edit_skybox_size.png} 
  \caption{Skybox size controls}
  \label{fig:edit_skybox_size}
\end{figure}

The second tab "Textures" allows the user to set individual textures for each side of the skybox.

\begin{figure}[H]
	\centering
	\includegraphics[scale=0.7]{images/edit_skybox_texture.png} 
  \caption{Skybox texture controls}
  \label{fig:edit_skybox_texture}
\end{figure}

A new texture can be loaded for a side by clicking the button next to the current texture. Loading a new texture replaces the one in use. 

\newpage

\section{Viewpoints}

SGE contains a feature called "Viewpoints". A viewpoint is a defined camera position and view vector . A list of viewpoints can be created and maintained to allow the user to switch between a number of defined views onto the scene. \\
\\
In order to add the current camera position and view vector as viewpoint, the "Add Viewpoint" button from the "Add" toolbar is used (highlighted in \autoref{fig:toolbar_add_viewpoint}).

\begin{figure}[H]
	\centering
	\includegraphics[scale=0.9]{images/toolbar_add_viewpoint.png} 
  \caption{Add viewpoint button}
  \label{fig:toolbar_add_viewpoint}
\end{figure}

After clicking the button a dialog is shown asking the user to name the newly created viewpoint as shown in \autoref{fig:dialog_viewpoint}. 

\begin{figure}[H]
	\centering
	\includegraphics[scale=0.7]{images/dialog_viewpoint.png} 
  \caption{Creating a viewpoint}
  \label{fig:dialog_viewpoint}
\end{figure}

The user defined name does not have to be unique, it is however recommended, as to easily identify the viewpoints.\\
\\
After creating one or more viewpoints, the tab "Viewpoints" allows to view and edit the created viewpoints.\\

\begin{figure}[H]
	\centering
	\includegraphics[scale=0.7]{images/tab_viewpoint.png} 
  \caption{Viewpoints}
  \label{fig:tab_viewpoint}
\end{figure}

Similar to the "Loaded Objects" and "Materials" tab the viewpoints feature a preview mode. When a viewpoint is selected in the list and the preview mode option is enabled, the output area displays the scene using the viewpoint data. When returning to the "SceneGraph" tab the camera data used before entering preview mode is restored.\\
\\
The button at the bottom left of the "Viewpoints" tab can be used to apply the current viewpoint to the scene, placing the main camera for the scene at the position stored in the viewpoint.\\
\\
The button at the bottom right is used to delete the selected viewpoint. \\
\\
When selecting a viewpoint the edit controls for viewpoints are displayed. \\
Here a new name can be assigned to a viewpoint. At the same time it is possible to change the camera position and the look-at point for the viewpoint.\\

\begin{framed}
\emph{Please note that viewpoints are a feature provided by SGE and not by OpenSG. Since all the saving and loading of scenes is done using OpenSG, viewpoints are not supported in saved files. Therefore viewpoints only exist in a current session and are lost when SGE is closed.}
\end{framed}

\newpage

\section{Multidisplay support}

SGE allows for the current scene to be displayed on a multidisplay. SGE also allows the use of an Oculus Rift when it is attached as a secondary monitor. \\
The current scene will continue to be displayed in the output area and the user can edit it while the multidisplay output is active. It is however not possible, to use multiple multidisplays simultaneously.\\
\\
The multidisplay dialog (shown in \autoref{fig:dialog_md}) can be toggled via the multidisplay toolbar (\autoref{fig:toolbar_md}).

\begin{figure}[H]
	\centering
	\includegraphics[scale=0.9]{images/toolbar_md.png} 
  \caption{Toolbar Multidisplay}
  \label{fig:toolbar_md}
\end{figure}

SGE uses the "CaveSceneManager" library to handle multidisplay output which requires a config file to be loaded that specifies the necessary data for the display. The file can be selected using the "Select config" button.\\

\begin{figure}[H]
	\centering
	\includegraphics[scale=0.7]{images/dialog_md.png} 
  \caption{Dialog multidisplay}
  \label{fig:dialog_md}
\end{figure}

After selecting a config file the "Start" button is enabled. It can be used to activate the output to the multidisplay. \\
An active multidisplay output can be stopped by using the "Abort" button to the right of the start button.\\
A successful connection to a multidisplay enables the "Tracker" option. Here the user can enter the address of a tracking device used for navigation on the multidisplay. Besides headtracking, the user can navigate in the scene by using an analog stick. Movement direction is controlled by pointing the wand in the desired direction. \\
\\
Successfully establishing a connection to a multidisplay or a tracker(using an Oculus Rift counts as successful connection) stores the current config file as well as the tracker address and automatically fills in the appropriate fields the next time SGE is launched. \\
\\
SGE automatically determines if an active multidisplay is an Oculus Rift or not and adapts the output accordingly. Oculus Rift output is rendered to a separate window.\\
If an Oculus Rift config is detected, the "Screens" section is activated. This displays a list of all currently available displays and provides functionality to send the Oculus window to a selected display and toggle fullscreen for the window.\\
\\
When the Oculus Rift output is active, SGE allows the use of an avatar. SGE includes a default model and a set of animations/textures for the avatar. 

\begin{figure}[H]
	\centering
	\includegraphics[scale=0.6]{images/dialog_md_avatar.png} 
  \caption{Tab Avatar}
  \label{fig:toolbar_md_avatar}
\end{figure}

The "Avatar" tab (\autoref{fig:toolbar_md_avatar}) allows the user to choose custom data for an avatar and toggle the avatar on or off by pressing the "Activate" button.\\
\\
Lastly SGE also supports occlusion culling when the Oculus Rift output is active. This can be controlled using the "Occlusion Culling" tab (\autoref{fig:toolbar_md_oc}).

\begin{figure}[H]
	\centering
	\includegraphics[scale=0.6]{images/dialog_md_oc.png} 
  \caption{Tab occlusion culling}
  \label{fig:toolbar_md_oc}
\end{figure}

Besides the basic toggle to enable or disable occlusion culling in general, various parameters are displayed here to configure the occlusion culling algorithm used. \\
\\
The last tab is active only when a tracker is connected. It allows to define the default and up vectors for the wand of a tracker that is used for navigation as shown in \autoref{fig:toolbar_md_tv}.

\begin{figure}[H]
	\centering
	\includegraphics[scale=0.7]{images/dialog_md_tv.png} 
  \caption{Tab tracker orientation}
  \label{fig:toolbar_md_tv}
\end{figure}

When a multidisplay is active and a wand is available, navigation can be done using the wand and an analog stick. The wand can be used to choose the direction of the movement while the analog stick controls the movement itself.

\newpage

\section{Compilation}

SGE is designed as a cross platform utility and is part of the inVRs repository. It was tested on Windows and Linux.\\
For easy compilation SGE relies on cmake (\url{http://www.cmake.org}, Version 3.0 or greater). \\
\\
For compilation with Microsoft Visual Studio a minimum version of Microsoft Visual Studio 2012 is required.\\
\\
SGE relies on a number of libraries:\\
\begin{description}
\item[Qt] \url{http://www.qt-project.org}, tested with Qt 5.3
\item[OpenSG] \url{http://www.opensg.org}, requires OpenSG 2.0
\item[Boost] \url{http://www.boost.org}, tested with boost 1.53
\item[VRPN] \url{http://www.cs.unc.edu/Research/vrpn/}
\item[CaveSceneManager] part of inVRs: \url{http://www.invrs.org}
\item[Avatara] part of inVRs: \url{http://www.invrs.org}
\end{description}

Besides the compilation, SGE also supports installation via cmake. This will copy all essential files including the icon set, default models and textures to a user defined location (see \verb|CMAKE_INSTALL_PREFIX|).\\
\\
The icons used in SGE are part of the gnome icon scheme (\url{http://www.gnome.org}).


\end{document}        