# Building the Samples and Sandboxes

Below are instructions for building and using the samples and sandboxes available in Visualize downloadable packages. Each section includes a general description along with instructions for building and running the sample application.

The table on the right includes a full list of the available samples, along with the supported OS for each one.

Note: Throughout this document hoops_dir refers to the directory where the HOOPS 3DF package is located on your system.

## 3D Part Viewer

Description: The Part Viewer is an example of a fully featured application which showcases many of the features available in HOOPS. For a full description of the functionality available in this application, please visit the Reference Applications section.

Availability: Windows only

How to Run:

Launch hoops3dpartviewer.exe from hoops_dir/bin/<platform>

How to Build:

> 1. Open the samples solution from the main hoops directory
> 2. Place your license in hoops_license.h, if you haven’t done so already
> 3. Right-click on the hoopspartviewer project and choose ‘Build’

Command Line Arguments:

The 3D Part Viewer supports limited command line arguments to make it faster to load and export files. They follow this pattern:

hoops3dpartviewer.exe [input_file] [options]

Valid values for options are:

Command line argument | Description
--- | ---
–help, -h | Shows usage message
–output, -o <output_file_name> | Name of file to export

When an input file is specified, it is loaded at startup. If an input file is specified, an output file can optionally be passed as well. This will cause the application to export the file as soon as it is loaded. The export format will be implied based on the extension of the output file name.

## C# Simple

Description: Sample application built with the intent to show how to use the C# 3DF API together with Windows Forms GUI toolkit. It allows users to load HSF and HMF files, create spheres, cones, cylinders and annotations. When the orbit operator is active, the camera can be orbited using the left mouse button, panned using the right mouse button, and zoomed using the mouse wheel. The scene can be sent to a printer, and the code shows how hardcopy support can be added to a C# application. It is meant as a starting point for customers to prototype their applications. It uses the DirectX 11 driver by default.

Availability: Windows only

How to Run: Launch csharp_simple.exe from hoops_dir/bin/<platform>

How to Build:

> 1. Open the samples solution from the main hoops directory
> 2. Place your license in hoops_license.cs, if you haven’t done so already
> 3. Right-click on the csharp_simple_cs project and choose ‘Build’

## Cocoa Simple

Description: Cocoa Simple shows customers how to add HOOPS Visualize to a MacOS application built using the Cocoa GUI toolkit. It allows users to load HSF and HMF files, manipulate the camera and add annotations to the scene.

Availability: MacOS

How to Run: Launch cocoa_simple.app from hoops_dir/bin/<platform>

How to Build:

> 1. Open the samples XCode workspace from the main hoops directory
> 2. Place your license in hoops_license.h, if you haven’t done so already
> 3. Select the cocoa_simple scheme and choose ‘Build’

## Java Simple

Description: Sample application built with the intent to show how to use the Java 3DF API with the Java AWT GUI toolkit. This application provides basic functionalities, like loading files, manipulating the camera, creating simple geometries and selecting parts in the scene. It is meant as a starting point for customers to prototype their applications. It uses the OpenGL driver by default.

Availability: Available on Windows, Linux and MacOS

How to Run:

Windows:

> 1. Make sure that the JDK binary folder is somewhere in your system’s `PATH`, so that Java can be used from any directory.

> 2. From the command prompt, navigate to hoops_dir/bin/<platform> and execute this command:

>        java -jar java_simple.jar

Linux:

> 1. From the terminal, navigate to hoops_dir/bin/<platform>

> 2. Make sure that Java is somewhere in your path. To verify, try executing the `java -version` command from the terminal and verify that the version of Java you have installed is returned to you as a string

> 3. Add the current directory to `LD_LIBRARY_PATH` by executing this command:

>        export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:.

> 4. Launch `java_simple` using the following command:

>        java -jar java_simple.jar

How to Build:

There are a few important notes about building java_simple, which apply to all the platforms:

> - The Java JDK needs to be installed on your system before building samples which use Java.
> - Debug Java 3DF wrappers are not being distributed at this time. This means that even when building java_simple in debug mode, it should target the release version of 3DF libraries.
> - If you have not already done so, open hoops_license.java, found in hoops_dir/Dev_Tools/hoops_java/source and set the KEY variable with your HOOPS license.

Windows:

METHOD 1: Using Visual Studio in Release Mode

> 1. Open the samples solution from the main hoops directory
> 2. Add the java_simple_v<version>.vcxproj project, found at hoops_dir/demo/java/java_simple to the samples solution
> 3. Make sure the solution is in Release configuration
> 4. You will need an environment variable named `JAVA_HOME` which points to the directory containing the Java Development Kit.
> 5. Right-click on the java_simple project and choose ‘Build’.

Once the project is built using Visual Studio, it can be launched using the command line instruction detailed in the How to Run section.

METHOD 2: Using Visual Studio in Debug Mode

> 1. Open the samples solution from the main hoops directory

> 2. Add the java_simple_v<version>.vcxproj project, found at hoops_dir/demo/java/java_simple to the samples solution

> 3. Make sure the solution is in Debug configuration

> 4. You will need an environment variable named `JAVA_HOME` which points to the directory containing the Java Development Kit.

> 5. Because Debug 3DF Java wrappers are not distributed, the debug version of the project needs to be changed to link against the release 3DF Java wrappers as follows:

>    - Right-click on the java_simple project and choose ‘Properties’

>    - Click on ‘Configuration Properties’ and then ‘Build Events’

>    - Under ‘Post-Build Event’, expand the ‘Command Line’ setting

>    - Change the name of the directorie mentioned so that it doesn’t end with ‘d’. Example:

>      >     ..\..\bin\nt_x64_v141d\*

>    to:

>    >     ..\..\bin\nt_x64_v141\*

>    - Click OK to confirm the property changes
>    - Right-click on the java_simple project and choose ‘Build’

Once the project is built using Visual Studio, it can be launched using the command line instruction detailed in the “How to Run” section.

METHOD 3: Using Eclipse

> 1. Start Eclipse and click on File > New > Java Project
> 2. Give the project a name, and click Next
> 3. Click on the Libraries tab and then on the Add External JARs… button
> 4. Navigate to hoops_dir/bin/<platform> and choose the following libraries: HCanvas<version>.jar, HIJ<version>.jar, HJ<version>.jar, HJCanvas<version>.jar, HJMVO<version>.jar, HJSTREAM<version>.jar
> 5. Click Finish
> 6. Using Windows Explorer, navigate to the source folder which was created as part of the project. Unless the default location was changed, it should be located in C:/Users/<user>/eclipse-workspace/<project_name>/src
> 7. Create a directory called ‘com’, within it create a directory called ‘techsoft’, and within this last directory, create another one called ‘hoops’, so that a directory structure like this one can be found: C:/Users/<user>/eclipse-workspace/<project_name>/src/com/techsoft/hoops
> 8. Copy java_simple.java, found in hoops_dir/demo/java/java_simple to the directory created in the previous step
> 9. Back in Eclipse, click on File > Refresh to update the project to include the new directories which were created in the previous steps. The java_simple.java file should now be visible within the Package Explorer pane.
> 10. Click on Run / Run Configurations and double click on Java Application on the left pane.
> 11. From the Main tab, click the Search… button and choose java_simple from the dialog which pops up.
> 12. From the Arguments tab, in the Working Directory section, choose Other, then click on the File System… button. Choose the 3DF folder where the 3DF libraries are located (hoops_dir/bin/<platform>)
> 13. Click Apply and then Run.

When using Eclipse with Java support as your IDE, java_simple can be run directly from it, rather than using the command line.

### Linux: Building Java Simple in Release Mode

1. Before starting, make sure that both the Java JDK and JRE are installed on your system. The bin folder of the JDK should be in your system’s PATH. To check that this is the case, verify that ./javac can be called from any directory.

2. Navigate to the /usr/lib/jvm directory and create a symlink to the directory where your Java JDK is located as follows:

       sudo ln -s <path to the JDK directory> java-6-sun

It is important that the name of the symlink be exactly `java-6-sun`

3. Navigate to the main hoops directory, and use the following command to compile java_simple:

       make java_simple CONFIG=release

### Building Java Simple in Debug Mode

Linux packages of HOOPS Visualize 3DF do not ship with debug libraries, but our makefiles are nevertheless setup to try to link against the debug version of our libraries when building a project in debug mode. Because of this, our makefiles need to be modified before building the Java Simple application in debug mode.

1. Before starting, make sure that both the Java JDK and JRE are installed on your system. The bin folder of the JDK should be in your system’s PATH. To check that this is the case, verify that ./javac can be called from any directory.

2. Navigate to the following directory /usr/lib/jvm, and create a symlink to the directory where your Java JDK is located as follows:

       sudo ln -s <path to the JDK directory> java-6-sun

It is important that the name of the symlink be exactly java-6-sun

3. Navigate to hoops_dir/demo/java and open the java.mk file with a text editor and perform the following edits:

   > 1. Comment out the project dependencies as follows:

   >        JS_DEPS = \
   >        #       libhoops_utils.a \
   >        #       libhoops.so \
   >        #       libhoops_stream.a \
   >        #       libhoops_mvo_mgk.so

   > Since we want to link against the release version of the HOOPS libraries, which are distributed with the package, there is no need to rebuild them.

   > 2. Comment out the make commands for directories other than java_simple as done above, by prepending ‘#’ to the line containing those instructions

   > 3. Change this line:

   >        cd ./demo/java/java_simple && $(MAKE) $(PLATFORM) BIN_PATH=../../../$(TARGET_DIR)

   >    to this:

   >        cd ./demo/java/java_simple && $(MAKE) $(PLATFORM) BIN_PATH=../../../bin/linux_x86_64

4. Navigate to the main hoops</span> directory, and use the following command to compile *java_simple:

       make java_simple CONFIG=debug

The resulting debug application will be created in the release bin directory (i.e., hoops_dir/bin/linux_x86_64)

## Java Simple SWT

Description: Sample application built with the intent to show how to use the Java 3DF API with the Java SWT GUI toolkit. This application provides basic functionalities, like loading files, manipulating the camera, creating simple geometries and selecting parts in the scene. It is meant as a starting point for customers to prototype their applications. It uses the OpenGL driver by default.

Availability: Windows only

How to Run:

> 1. Make sure that the JDK binary folder is somewhere in your system’s PATH, so that Java can be used from any directory.

> 2. From the command prompt, navigate to hoops_dir/bin/<platform> and execute this command:”

>    java -jar java_simple_swt.jar

How to Build: There are a few important notes about building java_simple, which apply to all the platforms:

> - The Java JDK needs to be installed on your system before building samples which use Java.
> - Debug Java 3DF wrappers are not being distributed at this time. This means that even when building java_simple_swt in debug mode, it should target the release version of 3DF libraries.
> - If you have not already done so, open java_simple_swt.java, found in hoops_dir/demo/java/java_simple_swt and add your HOOPS license in the constructor of the `SWTApplication` class
> - Building java_simple_swt in 32-bit mode on a 64-bit system using a 64-bit JDK installation is not allowed.

METHOD 1: Using Visual Studio in Release Mode

> 1. Open the samples solution from the main hoops directory
> 2. Add the java_simple_swt_v<version>.vcxproj project, found at hoops_dir/demo/java/java_simple_swt to the samples solution
> 3. Make sure the solution is in Release configuration
> 4. You will need an environment variable named `JDK_INSTALL_DIR` which points to the directory containing the Java Development Kit.
> 5. Right-click on the java_simple_swt project and choose ‘Build’. Once the project is built using Visual Studio, it can be launched using the command line instruction detailed in the How to Run section.

METHOD 2: Using Visual Studio in Debug Mode

> 1. Open the samples solution from the main hoops directory

> 2. Add the java_simple_swt_v<version>.vcxproj project, found at hoops_dir/demo/java/java_simple to the samples solution

> 3. Make sure the solution is in Debug configuration

> 4. You will need an environment variable named `JDK_INSTALL_DIR` which points to the directory containing the Java Development Kit.

> 5. Because Debug 3DF Java wrappers are not distributed, the debug version of the project needs to be changed to link against the release 3DF Java wrappers as follows:

>    > 1. Right-click on the java_simple_swt project and choose Properties

>    > 2. Click on Configuration Properties and then NMake

>    > 3. Under General expand the Build Command Line setting

>    > 4. Change the name of all the directories mentioned to not end with ‘d’. Example:

>    >        ..\..\bin\nt_x64_v141d\HJ.jar

>    > to:

>    >     ..\..\bin\nt_x64_v141\HJ.jar

>    > 1. Click OK to confirm the property changes

> 6. Right-click on the java_simple_swt project and choose ‘Build’. The resulting debug application will be created in the release bin directory. Once the project is built using Visual Studio, it can be launched using the command line instruction detailed in the How to Run section.

METHOD 3: Using Eclipse

> 1. Start Eclipse and click on File / New / Java Project
> 2. Give the project a name, and click Next
> 3. Click on the Libraries tab and then on the Add External JARs… button
> 4. Navigate to hoops_dir/bin/<platform></span> and choose the following libraries: *HCanvas<version>.jar, HIJ<version>.jar, HJ<version>.jar, HJCanvas<version>.jar, HJMVO<version>.jar, HJSTREAM<version>.jar, HoopsSwtCanvas<version>.jar, swt.jar
> 5. Click Finish
> 6. Using Windows Explorer, navigate to the source folder which was created as part of the project. Unless the default location was changed, it should be located in C:/Users/<user>/eclipse-workspace/<project_name>/src
> 7. Create a directory called ‘com’, within it create a directory called ‘techsoft’, and within this last directory, create another one called ‘hoops’, so that a directory structure like this one can be found: C:/Users/<user>/eclipse-workspace/<project_name>/src/com/techsoft/hoops
> 8. Copy java_simple_swt.java, found in hoops_dir/demo/java/java_simple_swt to the directory created in the previous step
> 9. Back in Eclipse, click on File > Refresh to update the project to include the new directories which were created in the previous steps. The java_simple_swt.java file should now be visible within the Package Explorer pane.
> 10. Click on Run > Run Configurations and double click on Java Application on the left pane.
> 11. From the Main tab, click the Search… button and choose java_simple_swt from the dialog which pops up.
> 12. From the Arguments tab, in the Working Directory section, choose Other, then click on the File System… button. Choose the 3DF folder where the 3DF libraries are located (hoops_dir/bin/<platform>)
> 13. Click Apply and then Run

When using Eclipse with Java support as your IDE, java_simple_swt can be run directly from it, rather than using the command line.

## MFC Simple

Description: Sample application built with the intent to show how to create an MFC application using the MVO API. Users can load HSF and HMF files.

Interaction with the scene consists of standard camera manipulation (pan, zoom, orbit, zooming to extents and zooming to a particular area), as well as the ability to create cylinders, cones, spheres.

Users can also select and highlight geometry using the Select by Window operator.

Three different render modes are exposed through the View menu (Gouraud, Hidden Line and Wireframe).

Finally, the scene can be copied to the system clipboard or sent to a printer.

An extra, unused button is added at the end of the toolbar so that customers can quickly add and try some code in the application. It is meant as a starting point for customers to prototype their applications.

Availability: Windows only

How to Run: Launch mfc_simple.exe from hoops_dir/bin/<platform>

How to Build:

> 1. Open the samples solution from the main hoops directory
> 2. Place your license in hoops_license.h, if you haven’t done so already
> 3. Right-click on the mfc_simple project and choose ‘Build’

## MFC Simple – 3DGS Only

Description: MFC Simple – 3DGS Only is a stripped-down version of the MFC Simple application. It only links against the main HOOPS Visualize library, showing customers how to write an MFC application when they do not wish to use the MVO component of Visualize.

This sample is relevant for customers who wish to handle input from the user from an MFC application, but without using MVO. It supports loading HMF files, changing render modes and orbiting the camera.

Availability: Windows

How to Run:

The application needs to be built before it can be run. Please see the next section for instructions on how to build it. Once it is built, it can be run as follows:

Launch simple.exe from hoops_dir/bin/<platform>

How to Build:

> 1. Open the samples solution from the main hoops directory
> 2. Place your license in hoops_license.h, if you haven’t done so already
> 3. Right-click on the simple_v<version> project and choose ‘Build’

## NVIDIA Profile Creator

Description: This sample and associated project can be found in the demo/win32/nvapi_profile_creator directory.

This sample helps address the limitations of GPU selection using `Set_Driver_Options("gpu preference = [xxx]")`. nvidia_profile_creator demonstrates how to programmatically create an application profile that will make the NVIDIA GPU the preferred GPU for a particular application. As such, this method for GPU selection will only work on laptops with NVIDIA GPUs, and it will only work on Windows.

This is the programmatic equivalent to launching the NVIDIA Control Panel, adding a new application, and setting this preference via its GUI. This allows the discrete GPU to get used for any driver, and will work for `D3DImageCanvas` as well.

This sample demonstrates:

> - Initializing the NVAPI.
> - Create a new profile with given name.
> - Delete an existing profile of a given name.
> - Add an application to the new profile.
> - Add the settings which will make the NVIDIA GPU the preferred GPU for that application.
> - Save the profile so it will be used when the application is next launched.

Note that for the profile to have an effect, it must exist prior to launching an application. If an application is already launched prior to the creation of the profile, it will need to be closed and launched again after the profile is created.

We would recommend running this profile creation code as a step in your installer, or as a utility to run on demand.

Availability: Windows. C++ only.

How to Build:

> 1. This new sample requires the NVAPI SDK which can be found here: https://developer.nvidia.com/nvapi. It is free, but will require acceptance of a license agreement and a free NVIDIA Developer Account.
> 2. You will need to define an environment variable named <span class=’filename’>NVAPI_DIR</span> which points to the extracted location.

## Out of core pre-processor (OOC)

Description: The Out of Core Pre-Processor is used to turn ASCII point cloud files into a specially processed HSF file with the .ooc extension. Pre-processing a large point cloud is the first step towards visualizing very large point clouds with 3DF. A full description of the OOC functionality can be found in the OOC Technical Overview.

Availability: Windows only

How to Run:

Launch ooc.exe from hoops_dir/bin/<platform>, providing appropriate command line arguments. ooc.exe can be launched with the –help command line to see a description of all the available options.

How to Build: ooc.exe cannot be built by the user.

## OpenVR Simple

Description:

OpenVR Simple shows how to create a simple VR viewing application. The user can use this application to see how to use the VR API, how to collect data from VR controllers and how to create VR operators to interact with the scene. If two controllers are connected, the user will be able to move, rotate and scale the model, and to highlight parts of it. It is meant as a starting point for customers to prototype their applications.

Availability: Windows only

How to Run:

Launch openvr_simple_<version>.exe from hoops_dir/bin/<platform>, providing appropriate command line arguments.

There are two command line options which can be passed to openvr_simple:

Command line argument | Description
--- | ---
-filename <file_to_load> | The file to load in VR
-driver <driver_name> | The driver to use. Valid options are dx11 and opengl2. Defaults to dx11.

A VR headset that supports OpenVR needs to be connected before launching OpenVR Simple.

How to Build:

> 1. Open the samples solution from the main hoops directory
> 2. Place your license in hoops_license.h, if you haven’t done so already
> 3. You will need an environment variable named OPENVR_SDK which points to the directory containing the OpenVR SDK. The OpenVR SDK can be downloaded from https://github.com/ValveSoftware/openvr
> 4. Right-click on the openvr_simple project and choose ‘Build’

## Qt Simple

Description: The Qt Simple sample shows how to create a platform independent GUI application which uses the HOOPS API together with Qt. This sample provides basic functionalities, like loading files, manipulating the camera, and creating simple geometries. It is meant as a starting point for customers to prototype their applications.

Availability: Available on Windows, Linux and MacOS

How to Run:

Before attempting to run Qt Simple make sure that Qt is installed on your machine, and that it is somewhere in your `PATH`.

- Windows: Launch qt_simple.exe from hoops_dir/bin/<platform>
- Linux: Launch qt_simple from hoops_dir/bin/<platform>
- MacOS: On MacOS platforms qt_simple needs to be built before it can be launched. Please follow the instruction in the MacOS section of ‘How to Build’ to learn how to build this sample.

How to Build:

Qt Simple can be built on any supported architecture via Qt Creator.

> 1. Place your license in hoops_license.h if you haven’t done so already.
> 2. Open the qt_simple.pro pro file in Qt Creator and select the architecture you intend to build for.
> 3. Click the Build & Run button to build and launch the application.

The resulting application will be created alongside the binaries in the bin directory for the selected architecture.

## Win32 Simple

Description: Win32 Simple is a sample demonstrating how customers can get started using Visualize with a Windows application, without using the MFC toolkit. This sample is relevant for customers who wish to handle input from the user using only Win32 calls. It supports loading HMF files, changing render modes, camera manipulation, simple geometry creation and selection.

Availability: Windows

How to Run: Win32 Simple needs to be built before it can be run. Please see the next section for instructions on how to build it. Once it is built, it can be run by launching win32_simple.exe from hoops_dir/bin/<platform>.

How to Build:

> 1. Open the samples solution from the main hoops directory
> 2. Place your license in hoops_license.h, if you haven’t done so already
> 3. Right-click on the win32_simple_v<version> project and choose ‘Build’

## WPF Image

Description: WPF Image is a simple sample which showcases how to use HOOPS Visualize’s C# API in a WPF application which makes use of `D3DImage`. While there is a performance penalty for using `D3DImage`, this workflow allows the superimposition of other WPF controls on top of the canvas. This approach is demonstrated in the sample, where all the buttons are WPF button elements floating over the canvas. This application allows the user to load files and to manipulate the camera, as well as toggling shadow visibility for the model. It is meant as a starting point for customers to prototype their applications. It uses the DirectX 11 driver by default.

Availability: Windows

How to Run: WPF Image needs to be built before it can be run. Please see the next section for instructions on how to build it. Once it is built, it can be run by launching wpf_image.exe from hoops_dir/bin/<platform>.

How to Build:

> 1. Open the samples solution from the main hoops directory
> 2. Add the wpf_image_cs_v<version>.vcxproj project, found at hoops_dir/demo/dotnet/wpf_image to the samples solution
> 3. Place your license in hoops_license.cs, if you haven’t done so already
> 4. Right-click on the wpf_image project and choose ‘Build’

## WPF Simple

Description: Simple sample application built with the intent to show how to use the C# 3DF API together with WPF GUI toolkit. It allows users to load HSF and HMF files, create spheres, cones, cylinders and annotations. When the orbit operator is active, the camera can be orbited using the left mouse button, panned using the right mouse button, and zoomed using the mouse wheel. The scene can be sent to a printer, and the code shows how hardcopy support can be added to a C# application. It is meant as a starting point for customers to prototype their applications.

Availability: Windows only

How to Run: Launch wpf_simple.exe from hoops_dir/bin/<platform>

How to Build:

> 1. Open the samples solution from the main hoops directory
> 2. Place your license in hoops_license.cs, if you haven’t done so already
> 3. Right-click on the wpf_simple project and choose ‘Build’

Conversation saved
HOOPSY BETA

### Hello! I'm HOOPSY

Your multilingual generative AI assistant for documentation. Ask me anything about HOOPS Visualize 3DF in your own language, or choose a sample question below to start a conversation:

What is HOOPS Visualize 3DF?
What are the latest release notes for HOOPS Visualize 3DF?
How do I start evaluating HOOPS Visualize 3DF?
How do I write my first sample application?
How can I get assistance?

HOOPSY may store conversations according to OpenAI's policy. Responses may not always be accurate.

HOOPSY is thinking...