:orphan:

===========================
Cross-Platform Applications
===========================

Overview
========

The Reference Application enables the user to read in HOOPS Stream Files and invoke the supplied HOOPS/MVO Operators to "operate" the application. The operations provided are:

* Read HOOPS Stream Files (HSF) and Metafiles (HMF)
* Create simple geometry (cones, spheres, cylinders and cutting planes)
* Create selection sets of entities
* Annotate objects
* Switch between Render Modes
* Switch between different camera manipulation operators
* Query the geometry in the scene
* Playback animation recorded in HSF files or Behavior (.bhv) files.

The application is intended as a demonstration of the integration of HOOPS with Qt, a showcase of all the functionality available in the HOOPS/MVO class library, and most importantly, as a reference architecture that developers may extend. As such, the set of Operator objects implemented were chosen to demonstrate the ways in which many operations common to 3D modeling applications can be implemented. Application developers may take the QtHoops Reference Application and easily customize and extend its functionality by creating new HOOPS/MVO derived operator classes.

For more information about the architecture of the QtHoops Reference Application, refer to the section on Building Applications.


Using the QtHoops Reference Application
=======================================

The QtHoops Reference Application has been designed to work and act like any standard Windows application. It uses a single-document interface (SDI) supporting the standard application services (New, Open, Save As, etc). HOOPS Stream Files (HSF) and Metafiles (HMFs) may be read, created, modified, and viewed.

The viewer 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 following icons are on the toolbar:

.. image:: images/qtpv_toolbar_std.gif

From left to right they are for:

**Standard Toolbar:**

* File New - Creates a new empty window.
* File Open - Launches a file browser. Use this to find and open a HOOPS metafile.
* Print - Not currently implemented in this version of the Reference Application.
* 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
* Walk - Use the mouse to interactively walk through the camera view field
* 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 NURBS Curve - Sets the operator on the active view to be Create NURBS Curve
* Create Sphere - Sets the operator on the active view to be Create Sphere
* Create Cone - Sets the operator on the active view to be Create Cone
* Create Cylinder - Sets the operator on the active view to be Create Cylinder
* Create NURBS Surface - Sets the operator on the active view to be Create NURBS Surface
* Create Cutting Plane - Sets the operator on the active view to be Create Cutting Plane.
* Translate Selection - Interactively translate the current set of selected geometry
* Rotate Selection - Interactively rotate the currently selected geometry. The operator only works on the first element in the selection list.

.. image:: images/qtpv_toolbar_stdviews.gif

**Standard Views Toolbar:**

* Front - Sets the camera in the active view to the front of the object.
* Back - Sets the camera in the active view to the back of the object.
* Top - Sets the camera in the active view to the top of the object.
* Bottom - Sets the camera in the active view to the bottom of the object.
* Right - Sets the camera in the active view to the right of the object.
* Left - Sets the camera in the active view to the left of the object.
* Isometric - Sets the camera in the active view to show the object in isometric position.

.. image:: images/qtpv_toolbar_markuptxt.gif

**Markup-Text Toolbar:**

* Freehand Markup - Use this tool to draw free-hand markups in the scene. Click the left mouse button and drag. 
* Rectangle Markup - Use this tool to draw rectangular markups in the scene. Click the left mouse button and drag.  
* Circle Markup - Use this tool to draw circular markups in the scene. Click the left mouse button and drag.  
* Text Markup - Use this tool to insert text markups in the scene. 
* Save/Restore Markup 1,2 - By holding down the [SHIFT] key and pressing any of these buttons the application will store the markup data and current camera position. Clicking on the button at any later time in your session will cause the application to re-position your view at the saved camera position with the markup data restored 

.. image:: images/qtpv_toolbar_tools.gif

**Tools Toolbar:**

* Annotation - Create a text annotation. After clicking on this button, click on an object in the scene to which annotation is to be attached. Move the mouse and click again and begin typing your text annotation. Press 'Enter' to complete. You can also click on the annotation and drag it to relocate it.
* Measure Distance - Interactively query the distance between two points on the Model.Create
* Cutting Plane - Creates a cutting plane and inserts it in the scene. Use the mouse to interactively rotate/pan the cutting plane to see the sections of models in various planes.
* Query Model- Interactively query the geometry and topology in the scene.
* Test Performance - Animates the model in the scene to test the performance. Displays the information about the performance (in frames/second) achieved.
* Rewind - Rewinds Animation
* Play/Pause - Plays or Pauses Animation
* Stop - Stops Animation

There are also a number of HOOPS settings that can be toggled by clicking on the right mouse button. They are:

* Selection Level - Allows user to toggle the selection level on the active view.
* Visibility - Allows the users to toggle on/off the visibility of HOOPS geometry.
* 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 HOOPS Reference Application reads in *.hsf* and *.hmf* files. For your convenience a set of demonstration files are contained on this media. They are separated into industry-specific folders located in the datasets/hsf and datasets/hmf_master directories of the datasets package (available from the Tech Soft 3D Developer Zone).


Saving Files
============

The Reference Application allows you to save models as:

* **HSF**: Saving Files as HOOPS Stream Files will create a compressed file of the graphical data within the scene. To ensure that Levels of Details (LODs) of objects in the scene are included in the HSF you must tell HOOPS to generate LODs for the scene. This is automatically done by turning on Level of Details when you set a constant framerate via the Frame Rate Options dialog in the view menu. 
* **HTML**: This creates both a HTML page and a HSF which you can then post to your website as live 3D data. The HTML page has an embedded HOOPS 3D Control which will stream the HSF from either a local disk or a website. The embedded object will, behind the scenes, download and install the HOOPS 3D Control if it is not already installed on the machine reading the webpage. This means that developers simply need to put the HTML and HSF file on their Website and then any user of MSIE can view the model over the web by simply pointing their browser to the page's URL. 
* **PostScript**: This creates a postscript file that can be used with a variety of applications across many platforms
* **JPEG, BMP, PNG, TIFF**: These image files can be used to bring any of the data into any of the standard image editing software. If the Image Magick libraries are not installed, some of these image formats may not be available.
    

Printing
========

Use the print button to generate a postscript file which you can either send to your printer directly or save to your local storage.


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 chosen by toggling the appropriate menu button or using the pull down menus on the frame. Once a camera manipulation operator has been selected, the camera may be interactively manipulated 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.


Geometry Creation
=================

Operators are provided for the creation of new geometry. These are modal operators on the View and are chosen by toggling the appropriate menu button or using the pull down menus on the frame. Once a geometry creation operator has been selected, geometry may be interactively created 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.


Geometry Selection
==================

Geometry 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 picking mode and selects and highlights the entity type that is nearest to a Windows mouse click. 

**Rectangular Aperture Pick**
Rectangular aperture pick selects and highlights all the entity types under a window that is defined using the left mouse button. The window is defined by a sequence of events using the left mouse button: down, down and motion, up. On the mouse up event, the selection calculation is performed.

**Creating Selection Lists**
Selection lists may be created by holding down either the Shift or Ctrl key while using either of the selection operators. The modeling transform operator operates on the geometry in the current selection list.

The QtHoops 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 HOOPS object is selectable, whether it be the nearest piece of geometry or the nearest piece of geometry's owning segment. By default, the color of the selected geometry is changed to white (or "highlighted").


Moving Geometry
===============

Two operators are provided for moving objects around the scene: 

* Object Translate
* Object Rotate 

You can either move an object around in the view plane or rotate an object about its centroid. If the shift key is held down while geometry is translated, the selected geometry will be moved in the plane orthogonal to the viewport. Both operators operate on objects in the selection list and work only when the selected objects are segments (you control the selection level with the right click menu). The translate operator is designed to work independent of the size of the selection set. However, the rotate operator is designed to work specifically when there is only one object in the active view's selection set.


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 text string can be terminated by either hitting carriage return, loading a new operator or clicking on a new object for annotation. Choice of the text font and its transformation characteristics are controlled by the right click menu.


Querying the Model
==================

The query operator is a modal operator associated with the view, and is selected via the pulldown menus or by toggling the appropriate menu button. Once selected, the mouse may be used to interactively query the HOOPS model. The first time the left mouse button is pressed while in the view (and over a HOOPS model) a dialog window is created and displays the following information:

* Unique long integer identifying the HOOPS geometry
* The type and number of vertices in the piece of HOOPS geometry
* Analytical intersection of the selection ray with the HOOPS geometry

Moving the mouse around the scene with the mouse depressed will cause the information to be updated in realtime.


Setting Visibility of Geometry in the Scene
===========================================

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. Via this menu you can toggle on/off the visibility settings for edges, lines, faces, lights, grids, text, cutting planes, capping lines and hidden lines (if appropriate).


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

On 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 Visibility right click 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. Some example metafiles which contain such information, such as *urn.hmf*, are shipped with the HOOPS distribution. Some additional logic, written for the QtHoops application, maps sample data to the vertices of all the shells in the scene. This logic is invoked via the View/Compute Sample Data menu.


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.


Level of Detail
===============

The HOOPS Reference Application contains an operator which enables end-users to turn on the new Level Of Detail (LOD) module in HOOPS. When LOD is turned on, HOOPS iteratively searches through each shell/mesh in the scene and generates several different simplified models for each shell/mesh. Depending on the complexity and size of the shells in the scene this may take several seconds. Once the 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 are controlled by the "LOD options" portion of the HOOPS Rendering Options. They allow the developer to control which level of detail is sent to the rendering pipeline, depending on the screen space size of the shell.

A slider bar is also available that allows the user to control the rendering of simplified LOD-generated shells. 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 directly maps to the maximum number of triangles 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 executed, 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 it does not support two-sided lighting. Consequently there are two extra buttons in the View menu which allow you to specify the handedness of the geometry in the scene.


Segment Browser
===============

The segment browser is activated by selecting the Segment Browser item from the Tools menu. It will split the main window into two frames, with the HOOPS view frame in the right window pane, and the segment browser occupying the left window pane. This tool allows the user to explore the segments and attributes of the HOOPS scene graph they are viewing.
