HAPI Installation

From H3D.org

Jump to: navigation, search



Installation on Windows


To install HAPI on Windows follow these steps.

  1. Download the latest binary release from the download section of the H3D community. (Currently you need to use the installation file for H3D to install HAPI, if H3DAPI is not desired then just do deselect it before installing.)
  2. Install HAPI using that file.
  3. Run examples through start menu.
  4. You will need to install drivers for specific haptics devices when you want to use those with HAPI.

Building from source

To build HAPI on Windows follow these steps.

  1. Obtain the source code. Preferrably by installing HAPI as in the step above. If the development source is desired follow the instructions in the Source Repositories section.
  2. Install version 2.8.7 or later of CMake. Go to the cmake homepage to download and install that program.
  3. Start CMake GUI. Put the search path to CMakeLists.txt in the first text box in this GUI. On a standard installation the search path is C:\H3D\HAPI\build. Put the search path to where the generate projects will be build in the second text box, for example C:\H3D\HAPI\build\win32. Press the Configure button and choose the compiler for which CMake will generate build files. Then wait while CMake tries to detect what libraries are installed on your system. If everything went fine then the "OK" button should light up and when it is pressed the project files will be generated.

    Alternatively the CMake command line could be used to generate the project files. In that case navigate (in the command line) to the HAPI\build folder and on a standard installation of CMake 2.8.7 write:
    C:\Program Files\CMake 2.8\bin\cmake.exe
    The project files will then be generated in HAPI\build folder.
  4. Open the projects and start building. When generating for Microsoft Visual Studio the project file to open is the solution file generated.
  5. When the HAPI ( and H3DUtil) library(ies) finished building build the INSTALL project once. This will copy needed files to a location in which other CMakeLists.txt distributed with HAPI can find them.
  6. To generate examples use the CMAKE GUI again and enable HAPI_EXAMPLE_PROJECTS before configuring again. Then open solution and build as before.

Installation on GNU/Linux

Using debian package

It is quite easy to use debian packages to install HAPI and obtain its source code. These steps are tested for Ubuntu 18.04 We assume it will work on other systems as well.

  1. Open /etc/apt/sources.list as sudo. Use for example the terminal command
    sudo gedit /ets/apt/sources.list
  2. At the end of that file add the following
    deb ftp://www.h3dapi.org/pub/releases/linux/debian/ distro sensegraphics
    Where "distro" is your linux distribution. For Ubuntu 18.04 this is "bionic".
  3. If you would like to make it easy to download source the also add
    deb-src ftp://www.h3dapi.org/pub/releases/linux/debian/ distro sensegraphics
  4. Save file and exit.
  5. In terminal write
    sudo apt-get update
    followed by
    sudo apt-get install libhapi
  6. Select Yes for all questions about "not known debian package". Alternatively you might have to use the [ trusted=yes ] option for the urls you added to sources.list. Note that this is really not a recommended approach by debian but if you want our debian package you have to trust the package somehow.

Sadly we can not distribute HAPI with prebuilt OpenHaptics support for linux. Therefore it might be useful to get source of HAPI. Then do the following.

  1. In terminal cd to a directory in which you want to download the source.
  2. Write
    apt-get source libhapi libh3dutil
  3. After download is finished you will have tar.gz files in your directory which contains all the source code for h3d. Note that if you only want extra OpenHaptics support it should be enough to only custom build hapi and h3dapi. The rest can be installed using debian.

Installation from Source

If you want to build follow these steps.

  1. Install version 2.8.7 or later of CMake. To do this on Ubuntu open a terminal and write:
     sudo apt-get install cmake 
  2. Download the source for H3DAPI at http://www.h3d.org.
  3. HAPI depends on other libraries. If you installed hapi from debian and then want to build it from source you should not need to use apt-get to install any new libraries. The build system used by HAPI will detect which libraries are installed on the system and only enable the features that the system can support. If more features are desired the corresponding library has to be installed. Note that some libraries are required for HAPI to compile. See the list of external libraries.

    • If using Ubuntu, several of these libraries can be obtained by using the apt-get feature. The first two packages installed below are the C++ compilers needed to compile HAPI. In a terminal write:
      sudo apt-get update
      sudo apt-get install gcc g++ libglu1-mesa-dev

      Freeglut can be obtained using the following commands(not sure if the -fexceptions build is still needed. It is to handle H3D exceptions properly but perhaps the default freeglut installations are fine for later versions of Ubuntu. In that case install freeglut3-dev):
      wget http://ovh.dl.sourceforge.net/sourceforge/freeglut/freeglut-2.4.0.tar.gz
      tar -xzvf freeglut-2.4.0.tar.gz
      cd freeglut-2.4.0
      sudo ./configure CFLAGS="-fexceptions" CXXFLAGS="-fexceptions"
      sudo make
      sudo make install
  4. In the terminal change folder to the HAPI/build folder and generate a makefile by writing:
    mkdir linux
    The reason for creating a new directory called 'linux' is to easily remove all the cmake generated files in the future in case this is needed. Now change directory to the new 'linux' directory. Then write:
    cmake ../

    To build HAPI using the makefile write:

    When the make finished all that is left is to install HAPI. This can be done by writing:
    sudo make install

    HAPI libraries are now installed on your system. But there is no application installed that use HAPI libraries. The second last step could be skipped if one want to build and install right away.
  5. There are example applications in this distribution that use HAPI. One of the examples requires WxWidgets, to install WxWidgets on Ubuntu write this in the terminal:
    sudo apt-get install libwxgtk3.0-dev

    To build the examples simply change the folder to HAPI/examples and do the following:
    mkdir linux
    cd linux
    cmake ../

    To test one of the examples change folder to HAPI/examples/SurfaceExample/build and do the following:

    Note that a supported haptics device must be connected for this demo to work properly.

Installation on Mac OS

Using Macports

  1. Download and install MacPorts as instructed on http://www.macports.org.
  2. Open a Terminal window and run the command "sudo port install hapi"

Do everything manually

Currently you need to build HAPI on MacOS X yourself. To build HAPI on MacOS X follow these steps.

  1. Install version 2.8.7 or later of CMake.
  2. Install XCode. If gcc is an unrecognized command in the terminal after installing XCode there is a high probability that CMake will not be able to generate build files for gcc and/or XCode. Another version of XCode could be used or fix it in some other way.
  3. Download the source for HAPI at http://www.h3d.org.
  4. HAPI depends on other libraries. The build system used by HAPI will detect which libraries are installed on the system and only enable the features that the system can support. If more features are desired the corresponding library has to be installed. Note that some libraries are required for HAPI to compile. See the list of external libraries.
  5. Generate build files for your build system using CMake. Either use the console version as in the installation guide for linux above or use the GUI version in which the first textbox should contain the location of the CMakeLists.txt file. This file is located in HAPI/build. The second box is the location of where the build files will be created. Use for example HAPI/build/OSX. Press configure, choose which system to generate build files for wait and press configure again until the generate button can be used. Press generate and then the build files will be in the choosen folder. If "Unix Makefile" are choosen then proceed from step 3 in the installation guide for linux.
  6. There are example applications in this distribution that use HAPI. To build these use the CMakeLists.txt located in the folder HAPI/examples. Run any of the built examples to test your HAPI build.



Source Repositories

Latest development version

Sometimes it is convenient to get the latest source of HAPI that is not yet in an official release. To obtain the source an internet connection and a subversion client is needed. Subversion can be obtained from subversion.apache.org. The following instructions assume that a subversion client is used. When subversion is installed HAPI source can be checked out from a shell by these commands.

cd mydevdir
svn checkout https://www.h3dapi.org:8090/HAPI/trunk HAPI
svn checkout https://www.h3dapi.org:8090/H3DUtil/trunk/H3DUtil H3DUtil

This will make the directories HAPI and H3DUtil subdirectories to mydevdir.

On Windows it is important to put the directories in this type of hierarchy structure unless it is desired to set most of the paths to libraries by hand when using CMake. It also makes developing smoother if an official HAPI release is installed and the folders created by it are used to check out the source in. The reason for this is to not have to download and install all external libraries needed by HAPI and H3DUtil. For Windows TortoiseSVN could be used as a subversion client to integrate subversion closely to the Explorer interface.

Personal tools
go to