1.0 Overview
The Reference Application:
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.
2.0 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, ). 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:
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.
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.
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
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/Paus - 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:
2.1 Opening/Reading in 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 your HOOPS distribution.
2.2 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.
2.3 Creating a HNet Client
Before you can begin creating sessions on a server you must first launch the
HOOPS/Net Server. To do this simply run the "hnet_server" executable located
in the bin (or bin/$PLATFORM on UNIX) directory of your HOOPS installation.
Once you launch the server you can connect to the server via the Network button
under the File menu. To connect to the server you must provide the IP
address of the machine the Server is running on and the port the Server is listening
on for initial client connections. By default, the IP address is the address
of the local machine 127.0.0.1 and the port is 11111. If the Server you
want to connect to is on a separate machine to which you have access to simply
provide its IP address in the appropriate dialog box. If you wish to use
a different port on the Server then you will need to modify the hnet_server.conf
file located in the directory the Server resides. Please refer to the
HOOPS/Net Server Programming Guide for complete details on how to modify the
settings of your HOOPS/Net Server.
Once you have launched the server you simply press the connect button to connect
to the sever. A list of active sessions will be listed in the Session
dialog. You can then join a session by typing the name of the session
in the Session Name text box and your name in the Client name text box.
If the session is already created then simply press the Join button and you
will be connected to the active session. If you wan to create a
new session choose a name not already listed in the Session list and a Client
name and press the Connect button. Both Creating and Joining a Session
will create a new window. Use the Client button in the File Menu to send
text messages between other members of the session and also to request control
of the session. Once you have control you can loads HSFs into the scene,
create and delete geometry as well as annotate and select objects within the
scene.
TSA will host a number of demonstration sessions on our company website to
demonstrate the HTTP capabilities of the HOOPS/Net Server. Please connect
to www.hoops3d.com for further details.
2.4 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.
2.5 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:
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 & moved (motion), left mouse button up.
2.6 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 & 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 & 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.
2.7 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").
2.8 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.
2.9 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.
2.10 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.
2.11 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).
2.12 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.
2.13 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.
2.14 Deleting Objects from the View
You can delete all the objects in the active view's selection list via the
Selection menu.
2.15 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)
2.16 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.
2.17 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.
2.18 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.