Licensing
Package hierarchy
Sandboxes
Library descriptions
This page provides an overview of how to get started with Visualize.
You must specify a valid Visualize license in your application code in order to use the Visualize product. The license key is a character sequence either provided by Tech Soft 3D or generated using the "Generate Key" button located on the Visualize downloads page in the Developer Zone.
If an invalid or expired license is set, your Visualize-based application will exit when Visualize attempts to start. If you are using a time-bound evaluation license, the Visualize viewport will display a small piece of text indicating that it's an evaluation license, and also display the number of days remaining until expiration.
The license should be compiled into your application via the HPS::World object, which initializes HOOPS Visualize. The license is delivered in a file called visualize_license.h. Paste your license string into the HPS::World constructor.
Alternatively, C++ users have the option of replacing the existing visualize_license.h in the include directory with the one from the Developer Zone, and passing the defined variable VISUALIZE_LICENSE to the HPS::World constructor. C# developers must explicity specify the license as a string.
For C++ developers or mobile users, the various samples and sandbox projects already reference visualize_license.h for convenience, and you can simply copy your license file to your Visualize installation's include directory.
IMPORTANT: Your application must instantiate the HPS::World object before interacting with Visualize, and the object must stay in scope as long as the application continues to use Visualize. For C# users, a static HPS::World object at the module level is recommended, due to the unpredictable nature of the .NET garbage collector.
Note that the hierarchy above includes <gui>_sandbox. Each platform includes a Sandbox, which is a sample application intended to be used as a starting point for prototyping, testing, and learning the API. Each sandbox contains a viewport and a set of manipulations operators, such as rotation, pan, and zoom.
Project name | Description |
---|---|
mfc_sandbox | Windows: MFC GUI framework for C++ |
wpf_sandbox | Windows: WPF GUI framework for C# |
cocoa_sandbox | OSX: Cocoa GUI framework for C++ |
qt_sandbox | Windows/OSX/Linux: QT GUI framework for C++ |
wx_sandbox | Windows/OSX/Linux: WxWidgets GUI framework for C++ |
ios_sandbox | iOS: Cocoa-Touch framework for Objective-C/C++ |
android_sandbox | Android: Android SDK framework for Java/C++ |
The segment browser is a Microsoft tree control that is included in both the WPF and MFC sandboxes.
The segment browser is a GUI control that allows you to inspect the segment structure of the loaded model. SceneTree and SceneTreeItem facilitate populating the tree-view, and they have derived classes located in CHPSSegmentBrowserPane.cpp (for MFC), or SegmentBrowser.cs (for WPF).
The model browser is a Microsoft tree control that is included in both the WPF and MFC sandboxes. It is provided in source code form as a reference, to facilitate adding a custom model browser to your application.
The model browser is a GUI control that allows you to inspect the Component hierarchy of models loaded with either the Exchange or Parasolid interface. Right-clicking on an item in the tree-view brings up a context menu which allows you to show, hide, or isolate an item in the viewport. Selecting an item in the viewport will highlight its corresponding item in the tree-view, and vice versa.
ComponentTree and ComponentTreeItem facilitate populating the tree control, and they have derived classes located in CHPSModelBrowserPane.cpp (for MFC), or ModelBrowser.cs (for WPF). Note that the model browser is only applicable when a Component hierarchy is present, such as when a model is loaded using one of the Component integrations.
Exchange: If you have a HOOPS Exchange license, Exchange support can be added to the MFC, WPF, Cocoa, Qt, and Wx sandboxes. To enable Exchange support, the project must be compiled with the USING_EXCHANGE preprocessor flag, and must be linked to hps_sprk_exchange.lib. The WPF sandbox requires that you add USING_EXCHANGE to the list of "Conditional Compilation Symbols" in its project file, and you must add a reference to cs_sprk_exchange. When using the sandboxes with Exchange, you need to locate the Exchange libraries for the application by calling HPS::World::SetExchangeLibraryDirectory.
If you load an Exchange file which has configurations, the "Configurations" tab of the model browser will display a list of the configurations in the file. If you double-click on a configuration, that configuration will be loaded from the file, replacing the currently loaded model.
Publish: If you have a HOOPS Publish license, Publish support can be added to the MFC, WPF, Qt, and Wx sandboxes. In order to be able to save 3D PDFs you will need to rebuild the sandbox with the USING_PUBLISH preprocessor definition. You will also need to link against sprk_publish.
When USING_PUBLISH is defined, the sandboxes look for the HPUBLISH_INSTALL_DIR environment variable, which needs to be set by the user to point to the Publish installation directory.
Note that the 3D PDF export is only enabled when those sandboxes are run in Windows, since Publish is currently not supported anywhere else when integrated into HPS.
Parasolid: To enable Parasolid support, the MFC sandbox must be compiled with the USING_PARASOLID preprocessor flag, and must be linked to hps_sprk_parasolid.lib. The WPF sandbox requires that you add USING_PARASOLID to the list of "Conditional Compilation Symbols" in its project file, and you must add a reference to cs_sprk_parasolid. Additionally, some Parasolid files require schema files for import. For those files, it is necessary to either set the schema directory using either HPS::World::SetParasolidSchemaDirectory or the P_SCHEMA environment variable. Alternatively, you may or have a the schema subdirectory in the same folder as the executable.
The WPF Sandbox supports both WinForms and D3DImage canvases with either DX9 or DX11. For an example on how they are used, see SprocketsWPFControl.cs in the wpf_sandbox project. WinForms is the default. If you want to use D3DImage, you'll have to define the USE_D3D_IMAGE_CANVAS variable as shown in the code. Other relevant lines are:
Lastly, you must add a reference to the sprk_d3dimage library in order to use D3DImage.
The following libraries are provided with HOOPS Visualize. You only need to include those libraries that your application uses:
Library name | Description | Required? |
---|---|---|
hps_core | Core Graphics | always |
hps_sprk | Supporting classes | when using view hierarchy, or any module listed below |
hps_sprk_ops | Standard operators | when using operators |
hps_sprk_exchange | Visualize-Exchange interface module | when using HOOPS Exchange |
hps_sprk_publish | Visualize-Publish interface module | when using HOOPS Publish |
The officially supported platform and development environment for Windows is noted here. You can choose to develop in either C++ or C#. The solution file is called visualize_vc<version>.sln; it contains all the projects you might need to compile during the course of your development cycle, including the MFC Sandbox, a WPF Sandbox, and the sample code. The default installation directory is of the form hoops_visualize_hps<version>_vc<version>.
Tech Soft provides Visualize libraries as pre-compiled binaries, thus, there is nothing extra that needs to be built. Your application links to the Visualize libraries during the build process and subsequently to the DLLs at runtime.
A few modifications must be made to a clean project file in order to compile a HOOPS Visualize application:
There is a macro conflict that occurs frequently with certain Windows headers. The problem is that these headers #define a number of common names. Since #define can't be scoped by a namespace or class, they cause conflicts with other code. The most commonly encountered conflicts are min, max, and Window.
The solution is to simply include the HPS header file after any Windows headers. This will enable Visualize to determine if _WINDOWS_ is defined, and if so, it will undefine the conflicting macros.
Similar to C++, your C# application must reference the Visualize C# assemblies that it requires. They are located in in %install_dir%\bin\<platform_name> The assembly names correspond to the C++ DLLs noted in the previous subsection, with one minor difference. The names include cs - for example, hps_core.dll becomes hps_cs_core.dll
The C# assemblies depend on the corresponding C++ DLLs. Thus, when using the hps_cs_core.dll assembly, the supporting C++ binary called hps_core.dll must also be in the environment PATH or the application's directory. The C++ DLLs are also located in in %install_dir%\bin<platform_name>.
Additionally, when compiling, the platform target must be either 32 or 64-bit. The "Any CPU" target will not work.
If you are using one of the DirectX drivers (DX9 or DX11) and wish to support Windows Vista, you must ensure that the Microsoft DirectX End-User Runtime is installed on the target machine. Microsoft provides both a redistributable standalone installer and a web installer.
The officially supported platform and development environment for Linux is noted here. There is a makefile for the sample applications (hps_samples), and a subdirectory for the QT sandbox (qt_sandbox).
For the samples, users can navigate to samples/code/cpp and run
...where <platform> is one of [linux32, linux32-debug, linux64, linux64-debug].
For the QT sandbox, there is a qt_sandbox.pro file which can be used to build the application using QtCreator.
The officially supported platform and development environment for OSX is noted here. There is a workspace for the sample applications (hps_samples_osx), and subdirectories for the Cocoa sandbox (cocoa_sandbox) and QT sandbox (qt_sandbox).
The Visualize Mobile development framework allows you to code once for both systems to maintain platform-independent Visualize code.
This applies especially to events and event handling, where the interface related to user input is abstracted from platform-specific GUI or language. The sandboxes are set up so that the platform-specific events will trigger Visualize function calls:
If you choose not to use the framework provided by the sandboxes, you will have to coordinate this event handoff yourself.
The officially supported platform and development environment for iOS is noted here. There is no top-level workspace. The iOS package provides three library files, libhps_core.a, libhps_sprk.a, and libhps_sprk_ops.a.
In addition to the Visualize libraries mentioned above, your application should also link to these third-party libraries:
NOTE: You must be registered in the iOS developer program. This step is required in order to run on a physical iOS device (as opposed to just running on the simulator).
The iOS Sandbox is a sample application which shows how to integrate Visualize into an iOS app. It can be found at <HPS install dir>/samples/ios_sandbox/iOS-Sandbox.xcodeproj. iOS developers are encouraged to review it or use it as a template when writing their own Visualize application.
Of particular interest is the MobileSurfaceView class, which provides the infrastructure. MobileSurfaceView is a subclass of the Cocoa UIView class. Here, we are specifying that we want a CAEGLLayer as the view's layer type. Your application will need to do something similar:
Additionally, the MobileSurfaceView init function includes the following initialization. If you create a custom view class you will need to do this as well:
Any model that is to be loaded by the iOS Sandbox must be added to the Xcode project.
The iOS Sandbox will listen for events generated by the operating system, use them to build Visualize events, then inject the event objects into the Visualize event queue. If you do not use the iOS Sandbox as a template, you will have to make these connections yourself in order for Visualize to receive user input. You can see how input events are passed to Visualize by inspecting the sandbox code. For example, the sandbox injects a touch-down event in this way:
self.surfacePointer->touchMove refers to the following platform-independent function:
As mentioned above, you are encouraged to use the iOS Sandbox as a template for your own application, as it will maintain platform independence related to events and event handling. All the platform-independent code related to the iOS Sandbox can found in <HPS install dir>/samples/shared.
The officially supported platform and development environment for Android is noted here. When starting a new project using Eclipse ADT, be sure to set the NDK directory before importing the Android Sandbox source. The following line needs to be added to your Application.mk file:
You must also have Python in your environment's PATH.
The Android package provides three library files, libhps_core.so, libhps_sprk.so, and libhps_sprk_ops.so.
The libraries mentioned above are C++ native binaries. As such, all of your Visualize function calls must be made in C++. Your GUI environment, however, will still be Java. An example of how to combine the C++ and Java code into an application can be found in the Android Sandbox project. That project is located in samples/android_sandbox.
The Sandbox
The Android Sandbox is a sample application which shows how to integrate Visualize into an Android app. It can be found at <HPS install dir>/samples/android_sandbox. Developers are encouraged to review it or use it as a template when writing their own Visualize application. If you do not start with the Sandbox, you will have to create much of the "glue" code yourself (see "Android Sandbox Specific notes", below).
In addition to the requirements listed on the Supported Platforms page, the sandbox project also requires:
Any model that is to be loaded by the Android Sandbox must be present in the hps/samples/android_sandbox/assets/datasets.
Since Visualize is written in C++ and Android uses Java, the JVM must use JNI to call Visualize methods from Java. For event handling, Visualize handles this process for you during the build using a Python script. The script examines your C++ event handler declarations, creates corresponding Java functions, and sets up the JNI calls. The benefit of this system is that you can do all of your programming in C++ and you don't have to worry about JNI. Additionally, platform-independence is maintained.
As mentioned above, you are encouraged to use the Android Sandbox as a template for your own application, as it will maintain platform independence related to events and event handling. All the platform-independent code related to the Android Sandbox can found in <HPS install dir>/samples/android_sandbox/jni/shared.
You may notice that after opening the sandbox project in the supported IDE, the project structure looks familiar. The jni folder contains the Java-C++ interface. The jni/shared directory contains files common to all mobile platforms. Of particular interest is UserMobileSurface.h. In that file, you'll see the GUI event handler function declarations are all preceded by the SURFACE_ACTION identifier. During the build process, the Python script sip.py (requires Python 2.7+) uses these tags to automatically generate the Java-C++ interface wrappers. In UserMobileSurface.cpp, you'll see the implementation function of each SURFACE_ACTION. Any new GUI component you add to your application should follow this paradigm when calling Visualize.
You should not modify any of the files that are auto-generated. Auto-generated files all have a comment near the top that looks like this:
Any parameters present in your C++ event function declarations will be marshalled by sip.py into a form that is usable by C++:
Instructions on using Visualize operators for handling user input events can be found in the Programming Guide, section 6.
Any SURFACE_ACTION function declaration must be written on a single line. sip.py cannot process multiline function declarations.