========================================
Using the Qt HOOPS Parasolid Demo Viewer
========================================
        
Using the Reference Application
===============================
        
The QtHoops for Parasolid Reference Application is a multi-platform, Qt-based application built on top of the Parasolid Kernel, the Qt library, and the HOOPS/3dGS, HOOPS/Parasolid, HOOPS/MVO and HOOPS/Qt components of the HOOPS 3D Application Framework (HOOPS/3DAF). The HOOPS/Parasolid Bridge connects the Parasolid and HOOPS libraries, by providing a two-way communication system for the mapping of geometric data between HOOPS/3dGS and Parasolid.

The application source code is located in the *demo/Qt/Qtparahoopsrefapp* directory of your installation, while the executable is located in the *bin* directory.
	

Notes on Unix installations
---------------------------
	
1. There are two versions of the executable. *Qtparahoopsrefappogl* uses the HOOPS OpenGL driver and can be run using the RUNPARAOGL script. *Qtparahoopsrefappx11* uses the HOOPS X11 driver and can be run using the *RUNPARAX11* script. (These scripts are also found in the *bin* directory, and automatically set some necessary environment variables as well as the startup HOOPS display driver.)

2. The application is dependent on a version of HOOPS/3dGS that was built with the HOOPS OpenGL Driver included. If you wish to run the application on a system that does not have an OpenGL runtime environment, you will need to rearchive the HOOPS library using a supplied script. Go into *lib* and run the 'prep_library' script in order to rebuild the HOOPS/3dGS library without OGL dependencies. You will then need to use this new library, and will need to rebuild both HOOPS/MVO and the application itself. 


The Reference Application
-------------------------
        
The QtHoops Reference Application enables the user to invoke the HOOPS/MVO operators and "operate" the application in the following ways: 

* Read Parasolid XMT files 
* Create simple Parasolid Entities (cones, spheres, cylinders) 
* Create simple HOOPS geometry (cutting planes) 
* Create selection sets of Parasolid models 
* Perform Boolean operations between Parasolid bodies 
* Annotate entities 
* Switch between Render Modes 
* Switch between different camera manipulation operators 
* Show the curvature across a ``PK_Face`` 
* Query the Parasolid model

The application is intended to function as a demonstration of the integration of Parasolid and HOOPS (i.e., rendering performance, integration with Qt), and most importantly, to serve as a reference architecture from which developers can extend their own code. As such, the set of Operators that were implemented in the application were chosen for their usefulness in demonstrating how to implement many operations common to 3D modeling applications. Application developers may take the QtHoops for Parasolid Reference Application and easily customize and extend its functionality by creating new HOOPS/MVO-derived Operator classes.

For more information about the architecture refer to the section on Building Applications.

        
Using the QtHoops for Parasolid Reference Application
=====================================================
        
The QtHoops for Parasolid Reference Application uses a single-document interface supporting the standard file I/O services (New, Open, Save As). Parasolid XMT files may be read, created, modified and viewed. Though not currently implemented the application could have easily supported printing by using the HOOPS Postscript driver.

The Reference Application has the concept of an active render mode and an active model operator. The render modes can be toggled by using the "right click" menu, while the model operators can be selected to invoke a camera manipulation, a selection operator, an entity translate operator, or an entity creation/deletion operator. The operators can be made active by clicking on the appropriate icon or pull down menu.
  
The icons from left to right are: 

**Standard services**

* File New - Creates a new empty window. 
* File Open - Launches a file browser. Use this to find and open a Parasolid XMT file. 
* File Save - Launches a file browser. Use this to save the scene as either a XMT file or a tiff image file. 
* Print - Not currently implemented in this vesion of the Reference Application.
        
**HOOPS Reference Application Specific Services**

* Set XY View Plane - Sets the camera in the active view to look down the Z axis 
* Set XZ View Plane - Sets the camera in the active view to look down the Y axis 
* Set YZ View Plane - Sets the camera in the active view to look down the X axis 
* Zoom to Extents - Resets the camera so that it can view the entire scene 
* Zoom to Window - Use the mouse to define a new camera view field 
* Orbit - Use the mouse to interactively orbit the camera about its target 
* Zoom - Use the mouse to interactively change the camera field 
* Pan - Use the mouse to interactively pan the camera in the active view 
* Select By Single Click - Sets the operator on the active view to be Select by Single Click 
* Select by Window - Sets the operator on the active view to be Select by Window 
* Create Sphere - Sets the operator on the active view to be Create Sphere 
* Create Cylinder - Sets the operator on the active view to be Create Cylinder 
* Create Cone - Sets the operator on the active view to be Create Cone 
* Create Cutting Plane - Sets the operator on the active view to be Create Cutting Plane. 
* Annotate Model - Sets the operator on the current view to be Annotate Model. 
* Translate Selection - Interactively translate the current set of selected entities 
* Model Query - Interactively query of the geometry and topology in the scene. 
* Show Curvature - Set different color values onto the face reflecting the change in curvature across the face.
        
There are also a number of settings that can be toggled by clicking on the right mouse button. They are: 

* Selection Level - Allows user to toggle the topological selection level on the active view. 
* Visibility - Allows the users to toggle on/off the visibility of different Parasolid topological entities. 
* Render Mode - Allows the users to switch between all the major HOOPS render modes. 
* Text - Allows the user to control the settings on the text in the scene.
        
These features are explained in more detail below: 

**Opening and reading files**
        
The QtHoops for Parasolid Reference Application reads in .xmt files. For your convenience a set of demonstration files are contained on this media located in the parasolid/parts directory of your HOOPS distribution. The files are of varying degrees of complexity so certain files may take a couple of seconds to load (depending on the speed of your system).
        
**Saving files**

The Reference Application allows you to save scenes as either a XMT file (v11) or a tiff image. By using the tiff output you can create raster images of scenes which can then easily be imported into any standard image editing software.  

**Printing**
        
Use the print button to generate a Postscript file which you can either send to your printer directly or save to your hard disk. 
   
**Camera Manipulation**
        
Each window has a separate HOOPS camera that may be manipulated to change the current view of the model. The camera operations implemented are: 

* Orbit 
* Pan 
* Zoom
        
These are modal operators on the view, and are activated by toggling the appropriate menu button or by using the pull down menus on the frame. Once a camera manipulation operator has been selected, the camera may be manipulated interactively with the mouse. All operators respond to the following sequence: left mouse button down, left mouse button down and moved (motion), left mouse button up.
   
        
**Entity creation**
        
Operators are provided for the creation of new Parasolid bodies and HOOPS cutting planes. These are modal operators on the view and are activated by toggling the appropriate menu button or by using the pull down menus on the frame. Once a body creation operator has been selected, geometry may be created interactively with the mouse. All operators respond to the following sequence: left mouse button down, left mouse button down and moved (motion), left mouse button up. The following geometric entities may be created:

* Spheres 
* Cylinders 
* Cones 
* Cutting Planes
        
The sphere and cutting plane entities are defined by one full cycle of left mouse button (LMB) down, LMB down and motion, LMB up. To move the cutting plane orthogonal to the view plane hold the shift key down while in the LMB down and motion state. The cylinder and cone entities require two full cycles, the first defines the circle for their base and the next sequence defines the height vector. 
   
**Entity selection**
	
Entity selection operators are modal operators associated with the view. There are two selection operators provided: selection by circular aperture (a circle around the mouse position), and selection by rectangular aperture (defined interactively with the mouse). 

	**Circular aperture pick**
		  
	Circular aperture pick is the default pick mode. This type of selection 
	operator selects and highlights the Parasolid entity type that is nearest 
	to the coordinate of a mouse click. 
		  
	**Rectangular aperture pick**
		  
	Rectangular aperture pick selects and highlights all the specified Parasolid 
	entity types under a coordinate window that is created using the left mouse 
	button. The window is defined by a sequence of events using the left mouse 
	button: down, down and motion, up. 
		  
	**Creating selection lists**
			  
	Selection lists may be created by holding down either the Shift or Ctrl 
	key while using one of the Selection Operators. The Modeling Transform 
	Operator operates on the geometry in the current selection list.
        
The application makes use of the "right click" user interface to provide a mechanism for controlling the visibility and selectability of the entities in the scene. Positioning the mouse in the view window and pressing the right mouse button invokes a floating menu bar. The behavior of the selection operators can be configured via this interface. The interface may be used to determine which Parasolid Topological Entity type is selectable, whether it be the nearest Parasolid Edge, Parasolid Face or Parasolid Body. The color of the selected geometry is changed to white (or "highlighted"). 
  
**Entity translation**
        
The translate operator is a modal modeling transformation operator associated with the view, and is activated by toggling its menu button or via the pulldown menus on the frame. Once the translation operator has been selected, the ``PK_Bodies`` in the current selection list may be interactively translated in the current view plane, using the mouse. The translate operator responds to the sequence of: left mouse button (LMB) down, LMB down and motion, LMB up. On the LMB down and motion events, it translates the PK_Bodies by the vector defined by the first point given on the LMB down event and the current mouse position. 

**Model annotation**
	
The model annotation operator allows you to associate text strings with geometry in the scene. To annotate geometry simply click on the piece of geometry you want to annotate then click where you want the text string to appear, and begin entering the text string. The string can be terminated by either hitting carriage return, loading a new operator or clicking on a new object for annotation. Text font and transformation characteristics are controlled from the right click menu. 
   
**Performing Boolean operations**
        
Boolean operations can only occur between Parasolid bodies. A Parasolid Boolean operation requires a target and an array of tools that operate on the target. Both the tools and the target are Parasolid bodies. They are defined relatively via the selection list, as follows: target is defined as the first entity in the Selection list, tools are the subsequent list items. Use the selection operators to build the selection list prior to invoking the Boolean operators. The Boolean operators are invoked by toggling the appropriate menu buttons or via the pull down menus on the frame. The following Boolean operations are implemented: 

* Union 
* Intersect 
* Subtract
        
Boolean operations are only performed on ``PK_Bodies``. 
   
        
**Querying the model**
        
The query operator is a modal operator associated with the view and is selected by toggling the appropriate menu button or via the pulldown menus. Once the operator is selected, the mouse may be used to interactively query Parasolid models. The first time the left mouse button is pressed (over a Parasolid model) a dialog window is created and displays the following information: 

* Analytical intersection of the selection ray with the Parasolid geometry 
* Parasolid tag ID for the ``PK_Body`` entity queried 
* Number of ``PK_Edges`` and ``PK_Faces`` in the ``PK_Body`` queried
        
Moving the mouse around the scene with the mouse depressed will cause the information to be updated realtime. 
   
**Evaluate curvature across a face**
	
The show curvature operator determines the curvature at each vertex of a HOOPS shell that represents a currently-selected Parasolid face(s). These values are then used to index into a colormap and subsequently the appropriate values at each vertex in the underlying HOOPS shell are set. Color interpolation is then automatically turned on so that the analytic results can be visualized. To visualize the modes in various different ways, the user can toggle the color index interpolation and color interpolation flags via the right-click Render Mode dialog. 
   
**Setting visibility of lights and Parasolid topological entities**
	
The application makes use of the "right click" user interface to provide a mechanism for controlling the visibility and selectability of the entities in the scene. Positioning the mouse in the view window and pressing the right mouse button invokes a floating menu bar. The visibility settings for lights and Parasolid edges and faces may be toggled using this menubar 
   
**Changing the render mode**
	
You can also control the render mode for the scene via the "right click" mouse button. There are 6 different rendering modes provided for viewing models. 

* Wire frame 
* Flat shaded 
* Smooth shaded (Gouraud) 
* Smooth shaded (Phong) 
* True analytic hidden line 
* Color interpolation
	
Upon startup, the default rendering mode is "smooth shading". Please note that the True Analytic Hidden Line algorithm is computationally intensive and for large models may take several seconds. Visibility of the hidden lines is controlled by the right click Visibility menu. 

In order for color interpolation to have any visual effect, some of the geometry in the scene must have analysis information mapped to its vertices. For this to occur, effect you will have to have previously used the "Show Curvature" operator.

**Changing the viewing projection**
        
By default the scene is rendered with a perspective viewing projection, you can change this to an orthographic viewing projection via the View menu. 
   
**Deleting Objects from the view**
	
You can delete all the objects in the active view's selection list via the Selection menu. This only works on a body level and deletes the entities from both the HOOPS and the Parasolid databases. 
   
**Level of detail**
        
The HOOPS Reference Application contains an operator which enables users turn on the new Level of Detail module in HOOPS. When Level Of Detail (LOD) is activated, HOOPS iterates through each shell or mesh in the scene and generates several different simplified versions of each shell/mesh. Depending on the complexity and size of the shells in the scene, the LOD calculations may take several seconds. Once the simplified models (or "levels of detail") are generated, HOOPS will then use its dynamic loading logic to make decisions based on the LOD options set in the scene. These options, which are controlled by the LOD options portion of the HOOPS Rendering Options, allow the user to control which levels of detail are sent to the rendering pipeline as a function of the screen-space size of the shell. 

A slider bar is also available that allows the user to control the LOD switching values. The bar will appear when LOD is activated under the View/Level of Detail options menu. Moving the bar will increase or decrease the "threshold" of the LOD rendering process. This number maps directly to the maximum number of triangles desired per sq. cm for each shell. Consequently, a low number will cause the most coarse level of detail to be loaded into the view. To visualize the differences it is often best to turn off light interpolation in the scene (i.e. turn the render mode to flat shading).
        
**Performance testing**
	
An animate button is available under the View menu. This enables you to test the capability of HOOPS to render user supplied metafiles. When the animation executes, the frame rate and the number of triangles drawn per second are returned to the user. 

**Display Lists**
	
From the View menu, the "display list" driver option can be activated. This option only has an effect when using the OpenGL driver, and typically only causes a performance increase when the system has dedicated OpenGL hardware. A known limitation of display lists is that they do not support two-sided lighting. To compensate, we have provided two extra buttons in the View menu which allow the user to specify the handedness of the geometry in the scene.  
