Support is provided at the following locations:

Installation of VE-Suite is fairly straightforward. Visit the Downloads section and locate your operating system.

Windows: Two installers are provided for Windows. Each installer will guide you through the process of selecting various options. One installer, vesuite#.#.#_####.exe, contains the core VE-Suite binaries and .dll files. The dependencies installer, vesuite_deps#.#.#.exe, contains the binaries and .dll files of VE-Suite's dependencies, arranged to include bin, lib, and share subdirectories.

Unix: A tar.gz file of the current release of VE-Suite is provided. You can extract the VE-Suite.#.#.# directory from it. Instead of one central dependencies directory, we provide the dependencies' rpm files. Be sure to install the necessary dependencies before running VE-Suite.

Macintosh: One installer is provided for Macintosh OS: VE-Suite Installer 20xx-xx-xx.pkg. It contains the core VE-Sute binaries and .dll files as well as the binaries and .dll files of VE-Suite's dependencies.

Installing VE-Suite and its dependencies follows the same procedures as other installations. The user chooses which components to install, their locations, their Start Menu folder, and whether to add an icon to the desktop.

One important consideration is which components to install. In large setups, certain computers will run the NameServer while others will handle VE-Conductor and VE-Xplorer. To run VE-Suite on a single desktop, leave all of the checkboxes checked to install everything.

Go through the same process for VE-Suite's dependencies.

On Unix, the installers are compressed tar.gz files. Open them using these commands:

NOTE: These examples use vesuite_#.#.# as a general placeholder for any version of VE-Suite. Be sure to change the version number to the specific version you are installing.

One installer is provided for Macintosh OS. Just double-click the install file to run it and follow the directions.

In previous versions, VE-Suite's runtime environment was set through text scripts. Now it uses VE-Launcher to set up the environment. Most of it is automated, but you should be aware of two important variables it sets: VE-Suite's directory and VE-Suite's dependencies directory.

VE-Launcher automatically determines VE-Suite's directory from the current working directory. Moving VE-Launcher out of VE-Suite's directory or starting it from a different directory will pass the wrong value to VE-Suite, causing errors.

On Windows and UNIX/Linux, the dependencies directory needs to be set manually. The first time you start VE-Launcher, you will be asked to find the dependencies directory. On Windows, the dependencies directory is VE_Suite.#.#.#_Dependencies.

On UNIX/Linux, multiple dependencies can be chosen. The only one that needs to be specifically selected is VR Juggler's directory.

If you are upgrading from an earlier version of VE-Suite, the dependencies' directories can be changed by selecting the dependency and clicking the Delete button, or clicking the Add button and selecting a new directory.

On Macintosh OS, the dependencies directory does not need to be manually set. The first time you start VE-Launcher, it is already set.

VE-Suite comes with a vesuiteConfig.sh script to set up menus, icons, and filetypes for VE-Suite on Linux desktop systems. The script works for Gnome 2.8+ and KDE.

To run it, go to its directory and enter ./vesuiteConfig.sh, followed by the arguments. The script accepts these arguments:

VE-Launcher is the gateway to VE-Suite. To open VE-Launcher, Windows users can double-click on the VE-Suite desktop icon or on velauncher.exe in the VE-Suite/bin directory. UNIX/Linux users should navigate by terminal into VE-Suite’s /bin directory and enter python velauncher.py.

If this is the first time VE-Launcher has been run after installation, you will be asked for the dependencies directory (see Chapter 1.5, Setting the Runtime Environment) before you are shown the main window.

VE-Launcher's more advanced commands are discussed in Chapter 12, Launcher. For now, make sure Desktop Mode is selected and click the Launch button. VE-Launcher will launch the Name Service, VE-Conductor, and VE-Xplorer in Desktop Mode.

For more information about VE-Launcher, read Chapter 12.

VE-Suite loads objects through plugins. This section describes how to load a geometry file through a plugin. Other data files may be loaded in the same manner.

Plugins are set up through the Available Objects window. Click on the New Document button to make sure the design space is clear.

To create a new plugin, double-click on the DefaultPlugin directory, which is in the Available Plugins directory in the VE-Conductor Network window.

Right-click on the gray DefaultPlugin box that appears in the pane on the right side of the window to access the plugin's menu, and select the Geometry Config option.

A new window, the CADTree Manager, will open. This holds the objects that are inserted into the plugin. To select a geometry file, right-click on the Model_Geometry icon and select Add Node..., then Load CAD file...

In the dialog box that opens, choose the appropriate file type, then select the file (e.g., Surface0.75.stl) and click the Open button. Name the object you loaded, then click the OK button to insert it into the plugin. Click Close on the CADTree Manager.

To load the information for the plugin's node into the rest of VE-Suite, click on the Connection menu and select Submit Job. The starting logo in Xplorer should be replaced by the objects in the plugins you submitted.

If the object is not initially visible in the Xplorer window, it may be outside the viewing region. Hold down the right mouse button and drag up in the Xplorer window to pull back the camera. Continue doing so until the scene is visible in the Xplorer window.

In addition to allowing users to load multiple geometry objects, VE-Suite also allows objects to be transformed, shaded, and textured.

There are two ways to manipulate VE-Suite's view using just the mouse: dragging in the Xplorer window itself or using the Navigation Pane. A RemotePoint RF wand can also be used to navigate VE-Suite.

To store multiple viewpoints and switch between them, use the Viewpoints Pane under the VE-Xplorer menu.

When the Viewpoints Pane starts, no viewpoints are loaded. As the user adds them to the pane, they appear in the Move to a Viewpoint dropdown menu, which can be used to select the viewpoint the user wants to switch to.

To add a viewpoint, position the camera the way you want it in the viewpoint, then click the Add Location button. The viewpoint will be added to the dropdown menu.

Viewpoints can be deleted by clicking the Delete Location(s) button, selecting the appropriate viewpoint from the window that opens, and clicking OK.

Once a viewpoint is added, the stored_viewpts_flythroughs.vel file in the working directory is updated. It is automatically updated when a viewpoint is added or deleted. Saved viewpoints can be restored later by clicking the Load button.

To move to a viewpoint, select it from the dropdown menu in the Flythrough Control section of the Viewpoints Pane. The camera will fly to that viewpoint at the speed set in the speed scroller.

Viewpoints can also be cycled through a flythrough. Click on the Start button below Automate Flythrough to begin a flythrough between each viewpoint in successive order. The flythrough will start at the first viewpoint, then hit each successive viewpoint, going at the speed specified by the speed scroller. When it reaches the last viewpoint, it will go back to the first one and repeat the flythrough. To stop the flythrough at any time, click the Stop button.

A frames-per-second (FPS) counter and a coordinate compass can be displayed in the VE-Xplorer window.

To display the FPS counter, go to the VE-Xplorer menu and select Display, then Frame Rate. VE-Xplorer will display the FPS in the lower right corner of its window.

To display the coordinate compass, go to the VE-Xplorer menu and select Display, then Coord System. VE-Xplorer will display the coordinate compass in the upper left corner of its window.

Ending a VE-Suite session requires two steps:

VE-Suite's physics functionality makes representations of interactions in VE-Suite more realistic.

To use VE-Suite's physics functionality, start VE-Suite as described in Chapter 3, Creating Content in VE-Suite. In VE-Conductor, go to the File menu and click Open ...

Navigate to the directory where your file is located and, in Files of Type, select *.ves. Select the appropriate file (to demonstrate the physics functionality, we use simple_physics_boxes.ves, which is located in the share/vesuite/examples/simple directory) and click Open.

The visualization will open in the VE-Xplorer window. Use the Frame All and other keyboard and mouse commands to change the view (see Chapter 3.3 for navigation instructions).

For each new file that is loaded in VE-Suite, the physics must be enabled. To do this, right-click on the plugin and click on Enable Physics.

The physics functionality must also be turned on in VE-Conductor. To do this, click on the Physics On/Off button in the VE-Conductor toolbar.

In addition to the Physics On/Off button, there are five more buttons in the Conductor toolbar that can be used to manipulate a visualization. The Start Simulation button starts the simulation.

The toolbar also allows you to view the simulation step by step rather than all at once. To view one step of the simulation at a time, click the Step Simulation button.

To reset the simulation to its original position, click the Reset Simulation button.

When running longer simulations, you might want to pause the simulation while it is running. To do so, click the Pause Simulation button.

The physics capability in VE-Suite also includes a Character Controller. To demonstrate the Character Controller, we will use the character_demo.ves file (also located in the share/vesuite/examples/simple directory).

After loading the character_demo.ves file, click on the Character Controller button in Conductor.

Use the Frame All and other keyboard and mouse commands to change the view (see Chapter 3.3 for navigation instructions).

The tables below provide keyboard and mouse commands for interacting with the visualization in character mode.

This section will describe how to create physics data in VE-Suite using a simple example.

First, load simple.ves in the same way you loaded simple_physics_boxes.ves in the previous section of this chapter. Right-click on DefaultPlugin in the VE-Conductor Network window and click on Geometry Config. This will open the CADTree Manager.

Expand the Model_Geometry tree by clicking on the arrow. In this example, you should see three nodes: eightCorners, Surface0.75, and Surface0.75_cloned. Each node corresponds to a different part of the visualization: eightCorners corresponds to the bounding box, while Surface0.75 and Surface0.75_cloned each correponds to one of the white polygonal objects.

Initialize physics on a node by right-clicking on it and selecting Initialize Physics. The CADTree Manager will open. Click on the Physics tab to set the Physics Properties (Mass, Friction, Restitution), Motion Type, LOD Type, Mesh Type, and Mesh Decimation). Each node must be initialized before physics can be run.

Once you have initialized physics, the Initialize Physics option will no longer be available when you right-click on a node. To edit the physics properties of a node, right-click and select Properties... This will open the CADTree Manager with the Physics tab, where you can edit your previously set physics properties.

Note: You must reset the simulation before editing a node's physics properties.

Initializing physics on a node also enables you to pick up individual parts of a visualization and move them. Simply hold down the Shift key and left-click on the object to drag it within the plane of the screen.

To use VE-Suite's manipulation tools, load your ves file and click the Transform Manipulator On/Off button in the toolbar. The four manipulation mode buttons will be activated. To select a manipulator, point it. When it turns yellow, click on it. The manipulator modes are described below.

To use VE-Suite's GIS tools:

A visualization's latitude and longitude can also be changed in VE-Suite. In the CADTree Manager, right-click on the appropriate node and click Properties...

In the CAD Properties window, select the Geographic tab, enter the appropriate longitude and latitude, and click OK. You can also enter a location in the text box and click Geocode to have VE-Suite automatically find the longitude and latitude data.

To use VE-Suite's ephemeris tools:

Although visualizations only require a dataset file (which models the technical data), users may want to add a geometry file to the scene to view the physical object as well. Once the scene is set, visualization can be used to analyze the data. This chapter uses the PrISUm car example to demonstrate visualization.

Load the geometry file. To do this, open VE-Launcher and set the Working Directory to the project's PrISUm directory. Next, use VE-Launcher to open VE-Suite in Desktop Mode. Load the geometry file, PrISUmblend.obj.

Keep the CADTree Manager open. Right-click on the Model_Geometry directory and choose Properties. A CAD Properties window will open. This can be used to transform the file's dimensions. To fit PrISUm's geometry file with its dataset file, set the following values in the Transform tab:

Figure 8.1. Transform the geometry file's dimensions

Once the parameters are entered, close the CAD Properties and CADTree Manager window. Next, you will need to load the datasets, the primary files for visualization.

The dataset contains the technical data about the model, such as pressure and airflow. Visualization turns that data into a map for easier viewing. Datasets are loaded similar to the geometry configuration file.

This figure shows the dialog box for loading datasets:

Figure 8.2. Selecting a dataset

The following matrix outlines which filetypes are required for each type of dataset:

The required files in column A reference the required files in column B. All files in columns A and B are required for loading the filetype in that row.

To load a dataset in VE-Suite, right-click on the gray plugin box and click on Data Set Config.

Click Add Dataset to create a new dataset and name it, then click Open under DataSet Filename and choose your dataset file (in this case, prisum.vtk). If you are just loading the PrISUm dataset, nothing else needs to be loaded, so click OK to load the dataset.

If you need to load more information, you can do so through other fields. The Precomputed Data Directory and Surface Data Directory fields take data files created by the VE-Builder preprocessor to speed up calculations. The Volumetric Data Directories field takes texture-based data files.

NOTE: VE-Suite expects each type of precomputed data to be stored in a separate folder. Storing all of the precomputed data in one folder, or storing any of it in the Working Directory, will cause problems in the dataset.

Finally, the dataset may need to be transformed to match up with the geometry data. The Transform button brings up a Transformation window, like the one used to transform the geometry data.

The dataset does not need to be adjusted because the geometry objects were adjusted to fit it, so the Transform Input Window can be closed.

Once the dataset files have been selected, click OK in the DataSetLoader window, then choose Submit Job from the Connection menu to display the PrISUm car. Use the navigation pane, the mouse, or the VE-Xplorer-->View-->Frame All command to adjust the camera until the view is satisfactory.

To use visualizations, go to the File menu in VE-Conductor, click Open, and select the appropriate .ves file. You might need to clear the design space by clicking on the New button in VE-Conductor.

NOTE: Make sure to save your work before clearning the design space.

To bring up the visualization interface, right-click on the plugin to access the menu and select Visualization. The Visualization window will open.

NOTE: This tool can only be used in a CAVE.

The Design Review Tool is a collection of features that facilitate capturing design suggestions during the review process and enable users to interrogate the product under review.

The Design Review Tool allows a user to:

The virtual camera allows you to take a picture of a scene. To turn on the virutal camera:

To change the resolution of the image that is taken as well as the size of your view angle, select the appropriate resolution on the Aspect Ratio choice dialog on the Camera tab.

Ensure that the Auto Computer Near/Far Plane is selected to ensure that you are capturing the image you intend to.

Use Button 1 to take your picture. When you press Button 1, the view frustum is displayed. The picture is taken when you release Button 1.

Choose the the appropriate image directory to save the image.

The ability to turn components on and off is controlled through the Conductor preferences pane, The CAD Selection check box is located under the Xplorer Settings tab. You should no longer be required to check and uncheck this box whenever you launch VE-Suite. The preferences should now be sent on the fly when VE-Suite is launched.

Button 0 toggles the selected CAD off.

Button 4 toggles the previously selected CAD back on.

To use the Virtual Pointer, go to the Xplorer menu, choose Devices, and select Pointer. This will display an arrow that is tied to the configured device VESPointer.

The Dynamic Vehicle Simulator Tool is a plugin to VE-Xplorer and VE-Conductor that enables mapping global positioning data to user-selected CAD.

The Registration Tools enable users to position a vehicle buck in a tracked environment for the purpose of registering a digital CAD representation of the vehicle buck to the physical buck.

Information users should know before using the Registration Tools:

There is an inherent trade-off between robust, readable code and optimum performance. These coding conventions are designed to maximize code robustness and readability, possibly at the expense of optimal performance.

This section contains general rules that apply to class, variable, function, and namespace names.

Select names that are clear and easy to understand. Keep in mind that your code will likely be viewed and maintained by several developers after you leave the project.

Use standard or commonplace acronyms. For example, CreateOSGCamera() is an acceptable name for a function that creates an OpenSceneGraph Camera object. Using highly descriptive names can help tremendously. Names like CheckForErrors and DumpDataToFile are much more descriptive than ErrorCheck or DataFile. In the second case one may need to check the implementation of the function to be confident in knowing exactly what it means.

When the name includes a natural abbreviation such as OpenGL, keep the abbreviation and capitalize the abbreviated letters. Never create new acronyms or abbreviations. For example, name a function SetRasterFontRange() instead of SetRFR().

Use only alphanumeric characters in names (A-Z, a-z, 0-9). For example, name a variable exteriorSurface rather than exterior_Surface.

Use underscores only as follows:

Use capitalization to indicate words within a name (CamelCase). For example, you could call a class VectorTopologyFilter.

Use the keyword "this" inside of methods even though C++ does not require you to. This really seems to make the code more readable because it disambiguates between instance variables and local or global variables. It also disambiguates between member functions and other functions.

Only one public class is allowed per file. Every class name, macro, etc. starts with either cfd or CFD to avoid name clashes with other libraries. Classes should all start with cfd and macros. Constants can start with either. Class names and file names are the same (e.g., cfdContours class is declared in cfdContours.h and implemented in cfdContours.cpp). This makes it easier to find the correct file for a specific class. Similarly, .cxx and .h file pairs should declare and define only one public class.

Declare classes in header (.h) files. Define all member functions in source (.cxx) files. Never place source code in header files, which prevents other developers from easily finding the source code.

Do not nest classes within other classes. It is difficult to move a nested class out of the owning class at a future date because all code using the fully qualified nested class name must be fixed. Nesting classes also causes them to be more difficult to locate.

Each class must support a copy constructor and an operator=() member function.

When declaring a class intended for use as a base class, declare the destructor as virtual to ensure that derived class destructors execute. This helps guard against memory leaks in derived classes.

When the base class has a virtual destructor, derived classes should also declare their destructors as virtual.

Always declare a function return type. Never allow the computer to default to type int.

Use const on any member function that does not change any data. It enforces the purpose of a function and allows for better compiler optimizations.

When overriding a base class member function declared as virtual, declare the derived class member function virtual as well to avoid confusion.

If a class implementation needs a local function, include that function in the class declaration as protected or private. Avoid declaring the function locally in the implementation, which limits code reusability. If the local function could be generalized consider making or adding it to a small utility library.

Always initialize member variables in the constructor. All instance variables are declared as protected. The user and application developer should access instance variables through Set/Get methods.

Declare variables where they are first used. C++ lifted this restriction from C for a reason. It makes code more modular and easier to understand, modify, and debug.

Always declare member variables as protected or private. Add public accessor methods to allow external access to the member variable. Initialize all member variables in the class constructor. Make sure to include the unit the variable represents as a suffix.

Never place a using statement at global scope in a header file. This pollutes the namespace of any code that includes that header, and can cause runtime issues and invisible conflicts that are difficult to debug and hard to track. Restrict using statements to implementation files (if at all).

Always use the fully qualified name for methods outside of the class, so for standard namespace keywords (cout, cin, cerr, endl, vector, string), you must std::cout, etc. Alternately, use using for specific functions or variables rather than global namespace inclusion. For example, if you only require the string class from the std namespace and it will appear frequently, use using std::string; instead of using std;

Header files are for declarations only. It is difficult to read and find code if source is in the declarations.

The header file of the class should include only the superclass header file. If you need any other include statements, add comments at each one describing why it should be included.

Forward declare classes when possible to avoid including unnecessary header files in a class header file.

Never place a using statement in a header file. This pollutes the namespace of any code that includes that header, and can cause runtime issues that are difficult to debug. Restrict using statements to implementation files.

Header files should use guards to prevent multiple inclusion. These guards should be defined in the style FILENAME_H, which is the filename written in all upper case with punctuation such as dots (.) replaced by underscores.

#ifdef CFDHEADER_H

#define CFDHEADER_H

...

#endif // CFDHEADER_H

You can also use the C Preprocessor to protect against multiple inclusions. Create a unique C Preprocessor identifier using the namespace, module, subdirectory, and file name. For example, given a file named Contours.h in the VE-Suite namespace in the Framework subdirectory of the Conductor module

#ifdef VES_CONDUCTOR_FRAMEWORK_CONTOURS_H

#define VES_CONDUCTOR_FRAMEWORK_CONTOURS_H

...

#endif // VES_CONDUCTOR_FRAMEWORK_CONTOURS_H

Comment the end of every #endif, as shown above. Nested #ifdef can be difficult to follow.

A new line after the last #endif is required by some compilers.

The following sections provide guidelines for editing the VE-Suite documentation using DocBook.

VE-Suite, as well as its dependencies, is currently being bested on a broad range of UNIX/Linux platforms including IRIX 6.5, SuSE, and RedHat Enterprise.

Set the environment variables (see Chapter 15, Setting the Environment) and source the setup file included with the VE-Suite project: $(VE_SUITE_HOME)/VE_Installer/setup. {.sh,tsh}. Once this file has been properly edited, type gmake. The UNIX build system is based on Doozer, which is included with VR Juggler.

Supported base configurations available:

There are also cluster variants of each of the above configurations:

To change any of the configurations described above, open the setup file and set SCENE_GRAPH, CLUSTER_APP, VE_PATENTED accordingly.

VE-Suite, as well as its dependencies, is currently built and tested using Visual Studio 7.1(2003).

VE-Launcher is a quick and easy way to launch any configuration of VE-Suite. It helps users save configurations, choose which programs to run, and launch them without entering text commands. Because so many options and configurations are available, choosing the necessary one can take some work. This chapter explains how to use VE-Launcher and includes an example setup.

VE-Launcher is started differently on Windows and Unix installs. On Windows, double-click the VE-Launcher executable. On a Unix-based install, VE-Launcher is a Python program. Go to VE-Suite’s /bin directory and run velauncher.py. Specifically, from the command line, enter the /bin directory and type python velauncher.py to run VE-Launcher.

For both the Windows and Unix-based development versions, VE-Launcher is a Python program. Run it in the same way as the Unix-based install. In development mode, VE-Launcher does not require dependencies to be set and it looks for stereo desktop configuration files in their build location, not their install location.

Preset Environmental Variables: Certain values, such as the VPR_DEBUG_LEVEL, can be automatically entered into VE-Launcher from the environment when VE-Launcher starts. If they are set in the environment, they overwrite the values saved from previous VE-Launcher sessions. These variables include:

Before VE-Suite can be run, VE-Launcher must be pointed to its dependencies. The process for doing this depends on whether VE-Suite is being run on a Windows- or Unix-based system.

Pointing to the dependencies is bypassed completely in development mode because VE-Launcher assumes the enviromental variables have been set.

Windows: VE-Launcher needs to find the VE-Suite dependencies directory that was installed along with VE-Suite. The first time VE-Launcher is started, the user is prompted to choose the dependencies directory for it. This directory should be named VE_Suite.#.#_Dependencies.

If necessary, you can change the dependencies directory by selecting Choose Dependencies from the Options menu in VE-Launcher.

UNIX: VE-Launcher supports dependencies spread across multiple directories. The first time VE-Launcher is run, you will be asked to choose the directory for its dependencies. Each dependency's directory should be added to the list.

The only exception is VR Juggler's dependency directory. Since it sets multiple variables, it needs to be chosen separately from the other dependencies.

If necessary, you can change the the dependencies directory by selecting Choose Dependencies from the Options menu in VE-Launcher.

Once the dependencies have been selected, VE-Launcher's main window displays.

Development mode: VE-Launcher does not require dependencies in development mode. It assumes that the necessary environmental variables have already been set.

VE-Launcher's main window displays the basic choices that need to be made before running VE-Suite. Here is a breakdown of what can be done from the main window:

The settings for every mode can be viewed and changed by clicking the Mode Settings button. Once you have chosen the appropriate settings, click Launch VE Suite to close VE-Launcher and start VE-Suite.

VE-Launcher's main window has a menu bar with the following menus:

Click the Mode Settings button to view and change settings. The Desktop, Tablet, and Computation Modes display their settings in read-only mode. Visualization Mode allows Xplorer Configuration Mode and Cluster Settings (when Cluster Mode is selected) to be changed. Custom Mode allows every setting to be changed. Choices are displayed in read-only mode if they cannot be changed, or if changing them would not have any effect. For example, Xplorer Configuration Mode cannot be selected if VE-Xplorer is not being run.

Options that can be set include:

Edit Configuration List

Figure 14.1. Click the Edit Configuration List button [RUN VE-SUITE TO CHECK THIS]

Click the Edit Configuration List button. VE-Suite has multiple configuration files available. To help users keep track of them, VE-Launcher keeps a list of the configuration files used. Entries in this list can be added, renamed, or deleted. The path to the currently selected entry is listed in the field at the bottom of the window so you can tell which name stands for which file.

When a new configuration is added to the list, its initial name is the same as its file name. The configuration should be renamed to be more descriptive.

VE-Launcher can run VE-Suite from one computer across a cluster. To use VE-Launcher's cluster functions on Unix, the cluster must satisfy these requirements:

Once all the nodes have been authenticated, the cluster can be run from VE-Launcher:

NOTE: There is a slight delay between each node launched because simultaneous launching causes erratic behavior in clusters. The delay can be changed by selecting Cluster Wait Times from the Options menu. If sync or unconnected nodes cause problems using VE-Launcher, try lengthening the delays. If launching the cluster takes too long, try shortening them.

VE-Launcher can start VE-Suite across a Windows cluster through PsExec.

To use the cluster functions of VE-Launcher on Windows, the cluster must satisfy these requirements:

To launch the cluster:

NOTE: There is a slight delay between each node launched because simultaneous launching causes erratic behavior in clusters. The delay can be changed by selecting Cluster Wait Times from the Options menu. If sync or unconnected nodes cause problems using VE-Launcher, try lengthening the delays. If launching the cluster takes too long, try shortening them.

The cluster template: If your cluster needs extra code to launch (for example, a net use command to set up a remote drive), the code can be entered into the clusterTemplate.txt file. Any terminal code in the clusterTemplate.txt file will run on the cluster’s other computer before VE-Xplorer is launched. Please read the comments in clusterTemplate.txt for more details.

Once VE-Launcher is set up, VE-Suite can be quickly started by passing arguments from the command line. Some arguments pass values to VE-Launcher while others bypass VE-Launcher completely and auto-launch VE-Suite. Arguments that auto-launch VE-Suite use the previously saved settings for any fields they do not change.

John Doe wants to set up VE-Suite to look at a virtual power plant design. He needs to start it in Visualization Mode, using the VR Juggler configuration "standalone". He also needs VE-Suite to connect to computer kiwi on port 1239.

When John starts VE-Launcher, he sees this:

Figure 14.2. Example (a)

First, John types the path to the plant design data directory in the Working Directory field. He could also use the Choose Working Directory button to find it.

Figure 14.3. Example (b)

John needs to change the computational engine (CE) name, but he cannot because VE-Launcher is currently in Desktop Mode, which automatically sets the CE name to localhost. To unlock the CE name, he switches to Visualization Mode. Remember that any mode besides Desktop Mode will allow users to change the CE name.

Figure 14.4. Example (c)

Switching modes unlocks the CE name and sets it to the last user-input value. Now John can change the CE name and port.

Figure 14.5. Example (d)

To finish setting up VE-Launcher, John must change the mode's settings. He clicks the Mode Settings button to bring up the Settings window.

Figure 14.6. Example (e)

Visualization Mode sets most of the options, and the Non-Cluster Xplorer Configuration Mode is already selected. That leaves changing the Xplorer Configuration. However, the configuration that John needs is not on the list. He clicks the Edit Configuration List button.

Figure 14.7. Example (f)

John clicks the Add button, which opens the configFiles directory. He selects the appropriate file and clicks Open.

Figure 14.8. Example (g)

The configuration is added to the list with the same filename that it had in the configFiles directory. In this case, that name is standalone.jconf. John clicks the Rename button to rename it "Plant Design" so he can remember which project it is for.

Figure 14.9. Example (h)

Now that he has finished editing the list, John exits the Xplorer Configurations window. Because Plant Design was selected when he exited, it is automatically set as his current configuration file. With everything set up appropriately, John can now click the Launch VE-Suite button to look at the design.

VE-Builder is a set of tools for modifying three-dimensional data files for VE-Suite.

A VE-Suite shell environment is necessary to run VE-Builder. To run VE-Builder tools from VE-Launcher, select the Shell Mode.

The loaderToVtkd program transforms prepared three-dimensional data files from other programs into VE-Suite files. First, prepare the environment for it by launching a Builder shell from VE-Launcher, as described in the previous section. Then the loaderToVtkd can be used to import files into VE-Suite formats. The general syntax of the program is:

loaderToVtkd -singleFile <input filename> -loader <loader type>

-o <full path to the output directory> -w file COMMAND FOR THE NAME OF THE OUTPUT FILE

To see loaderToVtkd options, type in loaderToVtkd. loaderToVtkd supports the following loader types:

It also supports Plot3D, but with this syntax:

loaderToVtkd -geometryFileXYZ [input filename] -dataFileQ [input filename2]

-o [full path to the output directory] -multiGrid Flag [0:1] -iblankFlag [0:1] -numberofDimensions [0:1]

-outFileName [output file] -loader xyz -w file

The following sections include detailed instructions for preparing and importing data files from StarCD (Section 9.4) and Fluent (AVS) (Section 9.5).

First, write out an .avs file for the post-processed data from Fluent and place it into the working directory. Use VE-Launcher to open a Builder shell (see Section 9.2), making sure to set the working directory to the directory where the .avs file is located. Use this command to convert it.

loaderToVtkd –singleFile [AVS filename] –loader avs –o [working directory] –w file

VE-Suite has the capability to display FEA datasets in the virtual environment, much like CFD datasets. However, the FEA data is primarily displayed as a surface on the object(s) of interest.

To display FEA data from an FEA dataset, select the Polydata icon and select the desired scalar for the FEA data.

You will need a .vtu file to create preprocessed data. Start a Builder shell from VE-Launcher, being sure to set the working directory to the .vtu file's directory. Verify that there is a directory called POST_DATA in the same directory as the .vtu file. If there is not, create one. Once the POST_DATA directory is ready, type in preprocessor. The first prompt will ask for a filename. Type in the .vtu file's name. The second prompt will ask for a directory to dump the data into. Type in the full path to the directory where you want to put the preprocessed data. The program will then ask you what you want to process. Your choices include:

Once you have made your choices, the program will execute and produce your preprocessed data.

If you want to extract cutting planes, you can specify the planes in a .txt file instead of manually typing them in each time. First, create a .txt file in the same directory as the .vtu file and write your cutting planes in it using this format:

1 //Number of x cuts

0.0 //X cuts

1 //Number of y cuts

0.0 //Y cuts

4 //Number of z cuts

3.26 3.39 3.42 3.73 //Z cuts

When you run the preprocessor, enter (1)Yes to extract cutting planes. You will be asked how to set the number of cuts. Select (2)Specify text file, then enter the name of your .txt file. The preprocessor will pull the values for the cutting planes from it.

Launch a Builder shell from VE-Launcher. In the VE-Launcher Shell window, enter the following:

vtkTo3DTexture

This will launch the translator interface. Select the desired parameters from the GUI and click Translate. Input parameters include:

A progress dialog will appear as the input .vtk files are translated to three-dimensional texture data files that are usable in VE-Suite.

Batch Mode

The translator can also be run in a batch mode. To run in batch mode, enter this on the command line:

vtkTo3DTexture -i /home/users/mcdoe/LTN/3D_Jets_Test/vtk -o / home/users/mcdoe/LTN/3D_Jets_Test/jets_vti -x 32 -y 64 -z 32 / home/users/mcdoe/LTN/3D_Jets_Test/Jets_Data

where:

The batch mode also supports parallel processing (MPI), which is convenient for large transient datasets. To run in batch mode with MPI, you must first install the MPI library. We recommend LAM/MPI. This is available for most Linux platforms. To run with LAM/MPI, a script should be created similar to:

#/bin/tcsh

setenv VE_SUITE_HOME /home/users/mcdoe/svn_VE_Suite/VE_Suite && source $VE_SUITE_HOME/VE_Installer/setup.tsh

vtkTo3DTextureMPI -i /home/users/mcdoe/LTN/3D_Jets_Test/vtk -o / home/users/mcdoe/LTN/3D_Jets_Test/jets_vti -x 32 -y 64 -z 32 / home/users/mcdoe/LTN/3D_Jets_Test/Jets_Data

which should then be executed as follows:

mpirun -np 2 ./

If you need to write out star.cel, star.vrt, and star.usr files from StarCD, follow these instructions:

To avoid dependencies problems during development, we have provided guidelines for using dependencies with VE-Suite. These are the guidelines the main VE-Suite development group follows and are provided as suggestions for other users.

Windows:

Linux:

It is best to read the specific installation/build instructions for each dependency before attempting to build. The information provided includes specific details to allow VE-Suite to build/run correctly.

VE-Suite and its dependencies are currently built and tested using Visual Studio 8.0(2005).

You can find the development libraries at http://www.vesuite.org/external/deps/non-admin/.

Notes on installing dependencies:

If you are installing individual components of VE-Suite on different desktops, it is only necessary to install the dependencies for that specific component. Below is a table listing the individual components and their specific dependencies.

Computers running VE-Suite must be able to run all of the dependencies listed above. They must also have shader support. VE-Suite will not run properly without shader support.

To achieve the goals outlined for the project, a powerful and flexible user interface (UI) was implemented. Key features of the VE-Suite two-dimensional UI (VE-Conductor) are described in the following sections.

Unified Control

Another feature of the UI is unified control for all user interaction. This ensures that the user is not burdened with moving between different UIs to perform operations. There is a single UI with the ability to: 1) construct, specify, execute and monitor simulations; and 2) provide complete control of the three-dimensional virtual environment.

To provide this functionality, the UI is designed to communicate via CORBA to not only the computational engine, but also to the graphical engine. As was discussed for the UI-to-computational engine link, the use of CORBA with an appropriate IDL provides a flexible, detachable, and platform independent communication mechanism for this link as well.

The following figure shows the two-dimensional GUI. A list of available modules is maintained in a tree structure on the left side of the window, while the main canvas area shows the current simulation network.

Figure 18.1. Two-dimensional GUI

The computational engine (VE-CE) is the core of the framework. Its duties are to construct, coordinate, schedule, and monitor plant simulation runs. It is capable of running a simulation containing a multitude of different types of models, each accepting and generating a myriad of data types. The computational engine is able to analyze a plant configuration, determine execution order, marshal system resources to create model instances, and coordinate the flow of data through the simulation framework. Tasks that require specific knowledge about a data type or model are relegated to either a detachable UI or to a specific model, thus keeping the computational engine generalized at a high level.

Important functions that the computational engine controls can be broken down into several pieces for explanation: plant configuration, data handling, error handling, relationship to detachable UI, scheduling, and relationship to models. Each of these is described in detail in the following sections.

The graphical engine (VE-Xplorer) provides the core functionality for the virtual engineering aspect of the framework. VE-Xplorer enables the engineering analysis and design process to take place in a virtual environment. For maximum graphical performance on multiple operating systems, it is built upon VR Juggler, OpenGL Performer, and Kitware's Visualization ToolKit. This visual interface, controlled by the UI and the computational engine, is a graphical representation of the simulation under review.

The graphical engine is generalized to load data not only from comprehensive models, but also from other engineering sources, including results generated from the CMU Vision 21 planner software and other generalized datasets (e.g., experimental data from a test rig). The engine is also being modified to make use of the high level CORBA interface specifications used throughout the software framework. This interface allows the visualization engine to communicate directly with the component models, computational engine, and UI. To communicate with the graphical engine there is an external socket connection that is made between individual component models and the respective graphical objects. This connection allows large high fidelity datasets to be transferred to the graphical environment without interrupting the overall communication network.

The graphical engine is also designed to allow graphics objects to be added to the virtual environment just like the objects are added in the GUI. This allows the graphical environment to be a direct representation of the system being designed by the engineer. In much the same way that the GUI auto-discovers the plugins for use by the engineer, the graphical engine also dynamically discovers plugins. Unlike the GUI, the graphical engine is controlled by the network string that is created by the GUI. This represents a significant capability since the graphical engine has no a priori knowledge of the system under interrogation.

Please set environment var on Linux to limit coredump size to 10000000000

There are four programs that have to be built and installed to run VE-Suite. Consult Chapter 1, Installation and Setup, for the current version requirements. In order of install they are:

We recommend reading the README files before compiling these programs.

Raw code files for UNIX will generally be in the .tar format. A .tar file has to be unpacked after it is downloaded. For help with this process, refer to the instructions in the VR Juggler tutorial "Getting Started". There is a section on .tar files that lists several different possible commands for the command line invocation. The two most common commands are:

You might be asked to download into a source folder but actually install the program into a separate folder. There is a special command that is appended to the compile command that will do this:

--prefix=/directory/to/save/to

The basic compile command itself may be slightly different for various programs.

Once the TAR file has been downloaded and unpacked, you can find which dependencies are already on your system by using the command rpm -qa | grep -i [package] where package is the program name you are looking for.

When you encounter a dependency you do not have, you will have to download, unpack, and install it using the same process as for the earlier programs.

Many installs involve CMAKE, which has its own set of steps.

Some downloads may not be available as compressed files. Occasionally you will have to download code from an SVN server. There is a continuously updated online book that is useful for this.

The commenting style below is designed to allow for automatic generation of documentation using Doxygen, while also maintaining readability. There are different places in code that comments can appear and for each there is a different style. Every method in the header (.h) file must have at least a brief comment; detailed comments are optional. Both brief and detailed comments are described below. Comments will appear in the doxygen-generated HTML files. Documentation in the implementation (.cxx/.cpp) file is primarily for human comprehension.

The best information regarding downloading and installing Doxygen can be found here.

***For the time being, this applies only to Linux builds*** In your OS terminal, navigate within VE-Suite to the file named doxygen, which will contain all of its doxygen files. The initial part of the filepath will depend on your install, but the end of it will be: <VeSuite filename>/share/docs/doxygen. To make sure that the configuration file exists, type doxygen -g, then type doxygen Doxyfile. This will generate documentation using the default settings. If you wish to create a differently named file to contain documentation settings, this can be accomplished with doxygen -g <filename> and doxygen <filename>. The default in VE-Suite is Doxyfile.

Open the html folder inside doxygen. Find the index.html file. You can click on it to open it in a browser and if you have run doxygen Doxyfile. It will display a hierarchy of documentation for all your generated files.

To edit the settings for the type of documentation that will be created when doxygen is run, read through the Doxyfile. Each variable is commented, and you can edit the values given to those variables in the Doxyfile.

This website contains a more detailed explanation for creating the configuration file (Doxyfile) and running Doxygen: http://www.stack.nl/~dimitri/doxygen/starting.html

This documentation was created using DocBook and the XML editor XMLmind. To use XMLmind:

The VE-Suite documentation was created as a modular DocBook v5+ document separated by chapter. To create a new chapter, choose Chapter from the DocBook v5+ template list.

User guides and online help for XMLmind can be found here.

The following DocBook manuals are also available free of charge online:

http://www.oreilly.com/catalog/docbook/chapter/book/docbook.html

http://www.sagehill.net/docbookxsl/

See Chapter 10.10, DocBook Documentation, for more DocBook coding guidelines specific to this document.

The best way to import data from Bentley software is to use the u3d file format. This will preserve the hierarchy in the CAD assembly and preserve the BIM data potentially in the Bentley exported data.

The best file format for working with AutoCAD is the 3D AutoCAD format, or the DWF format. When importing data, uncheck the "import text" option under the Options dialog.

If you do need text imported from the AutoCAD file, choose to export it as text in the osgPTExporter rather than as 3D data.

Always import PMI (Production Manufacturing Information) and use the highest level LOD for most cases. If you need to preserve the CAD hierarchy, do not optimize the hierarchy during import.

Be sure to regenerate the normals for the model once it is imported. The lights, animations, and other non-polygonal data will not be exported to OSG, so there is no need to be concerned with importing it.

Users who want to customize how Xplorer starts can launch it from the command line. Here is how the command should be set up:

This method of launching Xplorer is only needed in rare cases.